Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # Server MCP DSQL Aurora di AWS Labs Un server MCP (Model Context Protocol) di AWS Labs per Aurora DSQL ## Funzionalità + Conversione di domande e comandi leggibili dall'uomo in query SQL strutturate compatibili con Postgres ed esecuzione sul database Aurora DSQL configurato. + Sola lettura per impostazione predefinita, transazioni abilitate con `--allow-writes` + Riutilizzo della connessione tra le richieste per migliorare le prestazioni + Accesso integrato alla documentazione, alla ricerca e ai consigli sulle best practice di Aurora DSQL ## Strumenti disponibili ### Operazioni del database + **readonly\$1query - Esegui query** SQL di sola lettura sul tuo cluster DSQL + **transact** - Esegue operazioni di scrittura in una transazione (richiede) `--allow-writes` + **get\$1schema - Recupera le informazioni sullo schema** della tabella ### Documentazione e raccomandazioni + **dsql\$1search\$1documentation - Cerca nella documentazione** DSQL di Aurora + Parametri: (obbligatorio), (opzionale) `search_phrase` `limit` + **dsql\$1read\$1documentation - Leggi pagine specifiche della documentazione** DSQL + Parametri: `url` (richiesto), (opzionale), `start_index` (opzionale) `max_length` + **dsql\$1recommend**: ottieni consigli sulle migliori pratiche DSQL + Parametri: (obbligatorio) `url` ## Prerequisiti 1. Un account AWS con un cluster [DSQL Aurora](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html) 1. Questo server MCP può essere eseguito solo localmente sullo stesso host del client LLM. 1. Configura le credenziali AWS con accesso ai servizi AWS + È necessario un account AWS con un ruolo che includa queste autorizzazioni: + `dsql:DbConnectAdmin`- Connect ai cluster DSQL come utente amministratore + `dsql:DbConnect`- Connect ai cluster DSQL con ruoli di database personalizzati (necessari solo se si utilizzano utenti non amministratori) + Configura le credenziali AWS con le nostre `aws configure` variabili di ambiente ## Installazione Per la maggior parte degli strumenti, dovrebbe essere sufficiente aggiornare la configurazione seguendo le istruzioni di [installazione predefinite](#default-installation). [Sono riportate istruzioni separate per [Claude Code e Codex.](#claude-code)](#codex) ### Installazione predefinita: aggiornamento del file di configurazione MCP pertinente #### Uso di `uv` 1. [Installa `uv` da [Astral](https://docs.astral.sh/uv/getting-started/installation/) o dal README GitHub](https://github.com/astral-sh/uv#installation) 1. Installa Python usando `uv python install 3.10` Configurare il server MCP nella configurazione del client MCP ([Finding the MCP Config File](#finding-mcp-config-file)) ``` { "mcpServers": { "awslabs.aurora-dsql-mcp-server": { "command": "uvx", "args": [ "awslabs.aurora-dsql-mcp-server@latest", "--cluster_endpoint", "[your dsql cluster endpoint, e.g. abcdefghijklmnopqrst234567.dsql.us-east-1.on.aws]", "--region", "[your dsql cluster region, e.g. us-east-1]", "--database_user", "[your dsql username, e.g. admin]", "--profile", "[your aws profile, e.g. default]" ], "env": { "FASTMCP_LOG_LEVEL": "ERROR" }, "disabled": false, "autoApprove": [] } } } ``` #### Installazione di Windows Per gli utenti Windows, il formato di configurazione del server MCP è leggermente diverso: ``` { "mcpServers": { "awslabs.aurora-dsql-mcp-server": { "disabled": false, "timeout": 60, "type": "stdio", "command": "uv", "args": [ "tool", "run", "--from", "awslabs.aurora-dsql-mcp-server@latest", "awslabs.aurora-dsql-mcp-server.exe" ], "env": { "FASTMCP_LOG_LEVEL": "ERROR", "AWS_PROFILE": "your-aws-profile", "AWS_REGION": "us-east-1" } } } } ``` #### Individuazione del file di configurazione del client MCP Per alcuni degli strumenti di sviluppo Agentic più comuni, è possibile trovare le configurazioni dei client MCP nei seguenti percorsi di file: + Kiro: + Config utente: `~/.kiro/settings/mcp.json` + Config dell'area di lavoro: `/path/to/workspace/.kiro/settings/mcp.json` + Claude Code: fai riferimento a [Claude Code Installation](#claude-code) per una guida dettagliata alla configurazione + Config utente: in `~/.claude.json` `"mcpServers"` + Config del progetto: `/path/to/project/.mcp.json` + Config locale: in `~/.claude.json` `"projects" -> "path/to/project" -> "mcpServers"` + Cursore: + Globale: `~/.cursor/mcp.json` + Progetto: `/path/to/project/.cursor/mcp.json` + Codice: `~/.codex/config.toml` + Ogni server MCP è configurato con una `[mcp_servers.]` tabella nel file di configurazione. Consultate le istruzioni di installazione del [Custom Codex](#codex) + Warp: + Modifica dei file: `~/.warp/mcp_settings.json` + Application Editor: `Settings > AI > Manage MCP Servers` e incolla json + CLI per sviluppatori di Amazon Q: `~/.aws/amazonq/mcp.json` + Cline: di solito un percorso VS Code annidato - `~/.vscode-server/path/to/cline_mcp_settings.json` ### Codice Claude #### Prerequisiti **Importante:** la gestione del server MCP è disponibile solo tramite l'esperienza del terminale CLI di Claude Code, non la modalità pannello nativa di VS Code. Installa prima la CLI di Claude Code seguendo la procedura di installazione [nativa](https://code.claude.com/docs/en/setup#native-install-recommended) consigliata da Claude. #### Scelta dell'ambito giusto Claude Code offre 3 diversi ambiti: locale (predefinito), di progetto e utente e specifica quale ambito scegliere in base alla sensibilità delle credenziali e alla necessità di condividere. Per maggiori dettagli, consulta la documentazione di Claude Code sugli ambiti di [installazione MCP](https://code.claude.com/docs/en/mcp#mcp-installation-scopes). 1. I server **con ambito locale** rappresentano il livello di configurazione predefinito e sono memorizzati nel `~/.claude.json` percorso del progetto. Sono **entrambi** privati per te e accessibili solo all'interno della directory corrente del progetto. Questa è l'impostazione predefinita per la `scope` creazione di server MCP. 1. I server **con ambito di progetto** **consentono la collaborazione in team** pur rimanendo accessibili solo in una directory di progetto. I server con ambito di progetto aggiungono un `.mcp.json` file nella directory principale del progetto. Questo file è progettato per essere archiviato nel controllo delle versioni, garantendo che tutti i membri del team abbiano accesso agli stessi strumenti e servizi MCP. Quando aggiungi un server con ambito di progetto, Claude Code crea o aggiorna automaticamente questo file con la struttura di configurazione appropriata. 1. **I server **con ambito utente** vengono archiviati `~/.claude.json` e **forniscono accessibilità tra progetti**, rendendoli disponibili in tutti i progetti sul computer pur rimanendo privati per l'account utente.** #### Utilizzo della CLI di Claude (consigliato) L'utilizzo di una sessione `claude` CLI interattiva consente una migliore esperienza di risoluzione dei problemi, quindi questo è il percorso consigliato. ``` claude mcp add amazon-aurora-dsql \ --scope [one of local, project, or user] \ --env FASTMCP_LOG_LEVEL="ERROR" \ -- uvx "awslabs.aurora-dsql-mcp-server@latest" \ --cluster_endpoint "[dsql-cluster-id].dsql.[region].on.aws" \ --region "[dsql cluster region, eg. us-east-1]" \ --database_user "[your-username]" ``` ##### Risoluzione dei problemi: utilizzo di Claude Code con Bedrock su un altro account AWS Se hai configurato Claude Code con un account o un profilo Bedrock AWS diverso dal profilo necessario per connetterti al tuo cluster dsql, dovrai fornire argomenti di ambiente aggiuntivi: ``` --env AWS_PROFILE="[dsql profile, eg. default]" \ --env AWS_REGION="[dsql cluster region, eg. us-east-1]" \ ``` #### Modifica diretta nel file di configurazione Claude Code Richiede una denominazione alfanumerica, quindi ti consigliamo di assegnare un nome al tuo server:. `aurora-dsql-mcp-server` ##### Ambito locale Aggiornamento `~/.claude.json` all'interno del campo specifico del progetto`mcpServers`: ``` { "projects": { "/path/to/project": { "mcpServers": {} } } } ``` ##### Ambito del progetto Aggiornamento sul `/path/to/project/root/.mcp.json` campo: `mcpServers` ``` { "mcpServers": {} } ``` ##### Ambito dell'utente Aggiornamento `~/.claude.json` all'interno del campo specifico del progetto: `mcpServers` ``` { "mcpServers": {} } ``` ### Codex #### Opzione 1: Codex CLI Se hai installato la CLI Codex, puoi usare il comando codex mcp per configurare i tuoi server MCP. ``` codex mcp add amazon-aurora-dsql \ --env FASTMCP_LOG_LEVEL="ERROR" \ -- uvx "awslabs.aurora-dsql-mcp-server@latest" \ --cluster_endpoint "[dsql-cluster-id].dsql.[region].on.aws" \ --region "[dsql cluster region, eg. us-east-1]" \ --database_user "[your-username]" ``` #### Opzione 2: config.toml Per un controllo più preciso sulle opzioni del server MCP, puoi modificare manualmente il file di configurazione. `~/.codex/config.toml` Ogni server MCP è configurato con una `[mcp_servers.]` tabella nel file di configurazione. ``` [mcp_servers.amazon-aurora-dsql] command = "uvx" args = [ "awslabs.aurora-dsql-mcp-server@latest", "--cluster_endpoint", ".dsql..on.aws", "--region", "", "--database_user", "" ] [mcp_servers.amazon-aurora-dsql.env] FASTMCP_LOG_LEVEL = "ERROR" ``` ### Verifica dell'installazione Per Amazon Q Developer CLI, Kiro CLI, CLI/TUI, or Codex CLI/TUI Claude, `/mcp` esegui per vedere lo stato del server MCP. Per l'IDE Kiro, puoi anche accedere alla `MCP SERVERS` scheda del pannello Kiro che mostra tutti i server MCP configurati e i relativi indicatori di stato della connessione. ## Opzioni di configurazione del server ### `--allow-writes` Per impostazione predefinita, il server dsql mcp non consente operazioni di scrittura («modalità di sola lettura»). Qualsiasi richiamo dello strumento transact avrà esito negativo in questa modalità. Per utilizzare lo strumento di transazione, consenti le scritture passando il parametro. `--allow-writes` Si consiglia di utilizzare l'accesso con privilegi minimi per la connessione a DSQL. Ad esempio, gli utenti devono utilizzare un ruolo di sola lettura quando possibile. La modalità di sola lettura prevede l'applicazione sul lato client del massimo impegno per rifiutare le mutazioni. ### `--cluster_endpoint` Questo è un parametro obbligatorio per specificare il cluster a cui connettersi. Questo dovrebbe essere l'endpoint completo del cluster, ad esempio `01abc2ldefg3hijklmnopqurstu.dsql.us-east-1.on.aws` ### `--database_user` Questo è un parametro obbligatorio per specificare l'utente con cui connettersi. Ad esempio `admin` o `my_user`. Tieni presente che le credenziali AWS che stai utilizzando devono avere l'autorizzazione per accedere come tale utente. Per ulteriori informazioni sulla configurazione e l'utilizzo dei ruoli del database in DSQL, consulta [Using database roles with IAM roles](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/using-database-and-iam-roles.html). ### `--profile` Puoi specificare il profilo aws da utilizzare per le tue credenziali. Nota che questo non è supportato per l'installazione dei docker. È supportato anche l'utilizzo della variabile di `AWS_PROFILE` ambiente nella configurazione MCP: ``` "env": { "AWS_PROFILE": "your-aws-profile" } ``` Se non viene fornito nessuno dei due, il server MCP utilizza per impostazione predefinita il profilo «predefinito» nel file di configurazione AWS. ### `--region` Questo è un parametro obbligatorio per specificare la regione del database DSQL. ### `--knowledge-server` Parametro opzionale per specificare l'endpoint del server MCP remoto per gli strumenti di conoscenza DSQL (ricerca della documentazione, lettura e consigli). Per impostazione predefinita, è preconfigurato. Esempio: ``` --knowledge-server https://custom-knowledge-server.example.com ``` **Nota:** per motivi di sicurezza, utilizza solo endpoint Knowledge Server affidabili. Il server deve essere un endpoint HTTPS. ### `--knowledge-timeout` Parametro opzionale per specificare il timeout in secondi per le richieste al knowledge server. Impostazione predefinita: `30.0` Esempio: ``` --knowledge-timeout 60.0 ``` Aumentate questo valore se si verificano dei timeout durante l'accesso alla documentazione su reti lente.