Server MCP TypeScript
Genera un server TypeScript Model Context Protocol (MCP) per fornire contesto ai Large Language Model (LLM), con opzione di deploy su Amazon Bedrock AgentCore.
Cos’è l’MCP?
Sezione intitolata “Cos’è l’MCP?”Il Model Context Protocol (MCP) è uno standard aperto che permette agli assistenti AI di interagire con strumenti e risorse esterne. Fornisce un modo consistente per i LLM di:
- Eseguire strumenti (funzioni) che compiono azioni o recuperano informazioni
- Accedere a risorse che forniscono contesto o dati
Utilizzo
Sezione intitolata “Utilizzo”Generare un server MCP
Sezione intitolata “Generare un server MCP”Puoi generare un server MCP TypeScript in due modi:
- Installa il Nx Console VSCode Plugin se non l'hai già fatto
- Apri la console Nx in VSCode
- Clicca su
Generate (UI)
nella sezione "Common Nx Commands" - Cerca
@aws/nx-plugin - ts#mcp-server
- Compila i parametri richiesti
- Clicca su
Generate
pnpm nx g @aws/nx-plugin:ts#mcp-server
yarn nx g @aws/nx-plugin:ts#mcp-server
npx nx g @aws/nx-plugin:ts#mcp-server
bunx nx g @aws/nx-plugin:ts#mcp-server
Puoi anche eseguire una prova per vedere quali file verrebbero modificati
pnpm nx g @aws/nx-plugin:ts#mcp-server --dry-run
yarn nx g @aws/nx-plugin:ts#mcp-server --dry-run
npx nx g @aws/nx-plugin:ts#mcp-server --dry-run
bunx nx g @aws/nx-plugin:ts#mcp-server --dry-run
Opzioni
Sezione intitolata “Opzioni”Parametro | Tipo | Predefinito | Descrizione |
---|---|---|---|
project Obbligatorio | string | - | The project to add an MCP server to |
computeType | string | BedrockAgentCoreRuntime | The type of compute to host your MCP server. Select None for no hosting. |
name | string | - | The name of your MCP server (default: mcp-server) |
iacProvider | string | Inherit | The preferred IaC provider. By default this is inherited from your initial selection. |
Output del generatore
Sezione intitolata “Output del generatore”Il generatore aggiungerà questi file al tuo progetto TypeScript esistente:
Directoryyour-project/
Directorysrc/
Directorymcp-server/ (o nome personalizzato se specificato)
- index.ts Esporta il tuo server
- server.ts Definizione principale del server
- stdio.ts Punto di ingresso per trasporto STDIO, utile per server MCP locali semplici
- http.ts Punto di ingresso per trasporto HTTP Streamable, utile per hosting del server MCP
Directorytools/
- add.ts Strumento di esempio
Directoryresources/
- sample-guidance.ts Risorsa di esempio
- Dockerfile Punto di ingresso per hosting del server MCP (escluso se
computeType
è impostato aNone
)
- package.json Aggiornato con entry bin e dipendenze MCP
- project.json Aggiornato con target serve del server MCP
Infrastruttura
Sezione intitolata “Infrastruttura”Poiché questo generatore fornisce infrastruttura come codice basata sul tuo iacProvider
selezionato, creerà un progetto in packages/common
che include i relativi costrutti CDK o moduli Terraform.
Il progetto comune di infrastruttura come codice è strutturato come segue:
Directorypackages/common/constructs
Directorysrc
Directoryapp/ Construct per l’infrastruttura specifica di un progetto/generatore
- …
Directorycore/ Construct generici riutilizzati dai construct in
app
- …
- index.ts Punto di ingresso che esporta i construct da
app
- project.json Target di build e configurazione del progetto
Directorypackages/common/terraform
Directorysrc
Directoryapp/ Moduli Terraform per l’infrastruttura specifica di un progetto/generatore
- …
Directorycore/ Moduli generici riutilizzati dai moduli in
app
- …
- project.json Target di build e configurazione del progetto
Per il deployment del tuo MCP Server, vengono generati i seguenti file:
Directorypackages/common/constructs/src
Directoryapp
Directorymcp-servers
Directory<project-name>
- <project-name>.ts Costrutto CDK per il deployment del tuo MCP Server
- Dockerfile File Docker passthrough utilizzato dal costrutto CDK
Directorycore
Directoryagent-core
- runtime.ts Costrutto CDK generico per il deployment su Bedrock AgentCore Runtime
Directorypackages/common/terraform/src
Directoryapp
Directorymcp-servers
Directory<project-name>
- <project-name>.tf Modulo per il deployment del tuo MCP Server
Directorycore
Directoryagent-core
- runtime.tf Modulo generico per il deployment su Bedrock AgentCore Runtime
Lavorare con il server MCP
Sezione intitolata “Lavorare con il server MCP”Aggiungere strumenti
Sezione intitolata “Aggiungere strumenti”Gli strumenti sono funzioni che l’assistente AI può chiamare per eseguire azioni. Puoi aggiungere nuovi strumenti nel file server.ts
:
server.tool("toolName", "tool description", { param1: z.string(), param2: z.number() }, // Schema di input usando Zod async ({ param1, param2 }) => { // Implementazione dello strumento return { content: [{ type: "text", text: "Result" }] }; });
Aggiungere risorse
Sezione intitolata “Aggiungere risorse”Le risorse forniscono contesto all’assistente AI. Puoi aggiungere risorse statiche da file o risorse dinamiche:
const exampleContext = 'alcuni contesti da restituire';
server.resource('resource-name', 'example://resource', async (uri) => ({ contents: [{ uri: uri.href, text: exampleContext }],}));
// Risorsa dinamicaserver.resource('dynamic-resource', 'dynamic://resource', async (uri) => { const data = await fetchSomeData(); return { contents: [{ uri: uri.href, text: data }], };});
Configurazione con assistenti AI
Sezione intitolata “Configurazione con assistenti AI”File di configurazione
Sezione intitolata “File di configurazione”La maggior parte degli assistenti AI che supportano MCP utilizza un approccio simile per la configurazione. È necessario creare o aggiornare un file di configurazione con i dettagli del server MCP:
{ "mcpServers": { "your-mcp-server": { "command": "npx", "args": ["tsx", "/path/to/your-mcp-server/stdio.ts"] } }}
Se ricevi un errore come ENOENT npx
durante la connessione al server, potrebbe essere necessario specificare il percorso completo di npx
, ottenibile eseguendo which npx
nel terminale.
Ricaricamento a caldo (Hot Reload)
Sezione intitolata “Ricaricamento a caldo (Hot Reload)”Durante lo sviluppo del server MCP, puoi configurare il flag --watch
per far sì che l’assistente AI rilevi sempre le versioni più recenti di strumenti/risorse:
{ "mcpServers": { "your-mcp-server": { "command": "npx", "args": ["tsx", "--watch", "/path/to/your-mcp-server/stdio.ts"] } }}
Se aggiungi nuovi strumenti o risorse, potrebbe essere necessario aggiornare il server MCP nell’assistente AI.
Configurazione specifica per l’assistente
Sezione intitolata “Configurazione specifica per l’assistente”Consulta la seguente documentazione per configurare MCP con assistenti AI specifici:
Alcuni assistenti AI, come Amazon Q Developer, permettono di specificare configurazioni MCP a livello di workspace, particolarmente utili per definire i server MCP rilevanti per un progetto specifico.
Esecuzione del server MCP
Sezione intitolata “Esecuzione del server MCP”Inspector
Sezione intitolata “Inspector”Il generatore configura un target chiamato <your-server-name>-inspect
, che avvia l’MCP Inspector con la configurazione per connettersi al tuo server MCP usando il trasporto STDIO.
pnpm nx run your-project:your-server-name-inspect
yarn nx run your-project:your-server-name-inspect
npx nx run your-project:your-server-name-inspect
bunx nx run your-project:your-server-name-inspect
Questo avvierà l’inspector su http://localhost:6274
. Inizia cliccando sul pulsante “Connect”.
Il modo più semplice per testare e usare un server MCP è utilizzare l’inspector o configurarlo con un assistente AI (come sopra).
Puoi comunque eseguire il server con trasporto STDIO direttamente usando il target <your-server-name>-serve-stdio
.
pnpm nx run your-project:your-server-name-serve-stdio
yarn nx run your-project:your-server-name-serve-stdio
npx nx run your-project:your-server-name-serve-stdio
bunx nx run your-project:your-server-name-serve-stdio
Questo comando usa tsx --watch
per riavviare automaticamente il server quando i file cambiano.
Streamable HTTP
Sezione intitolata “Streamable HTTP”Se vuoi eseguire il server MCP localmente usando il trasporto HTTP Streamable, puoi usare il target <your-server-name>-serve-http
.
pnpm nx run your-project:your-server-name-serve-http
yarn nx run your-project:your-server-name-serve-http
npx nx run your-project:your-server-name-serve-http
bunx nx run your-project:your-server-name-serve-http
Questo comando usa tsx --watch
per riavviare automaticamente il server quando i file cambiano.
Deploy del server MCP su Bedrock AgentCore Runtime
Sezione intitolata “Deploy del server MCP su Bedrock AgentCore Runtime”Infrastruttura come Codice
Sezione intitolata “Infrastruttura come Codice”Se hai selezionato BedrockAgentCoreRuntime
per computeType
, verrà generata l’infrastruttura CDK o Terraform rilevante che puoi utilizzare per distribuire il tuo server MCP su Amazon Bedrock AgentCore Runtime.
Viene generato un costrutto CDK per il tuo progetto, denominato in base al name
scelto durante l’esecuzione del generatore, o <ProjectName>McpServer
per impostazione predefinita.
Puoi utilizzare questo costrutto CDK in un’applicazione CDK:
import { MyProjectMcpServer } from ':my-scope/common-constructs';
export class ExampleStack extends Stack { constructor(scope: Construct, id: string) { // Aggiungi il server MCP al tuo stack new MyProjectMcpServer(this, 'MyProjectMcpServer'); }}
Viene generato un modulo Terraform per il tuo progetto, denominato in base al name
scelto durante l’esecuzione del generatore, o <ProjectName>-mcp-server
per impostazione predefinita.
Puoi utilizzare questo modulo Terraform in un progetto Terraform:
# Server MCPmodule "my_project_mcp_server" { # Percorso relativo al modulo generato nel progetto common/terraform source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"}
Docker è necessario per costruire e distribuire il tuo server MCP. Assicurati di aver installato e avviato Docker per evitare errori come:
ERROR: Cannot connect to the Docker daemon at unix://path/to/docker.sock.
Autenticazione
Sezione intitolata “Autenticazione”Per impostazione predefinita, il tuo server MCP sarà protetto utilizzando l’autenticazione IAM. Basta distribuirlo senza alcun argomento:
import { MyProjectMcpServer } from ':my-scope/common-constructs';
export class ExampleStack extends Stack { constructor(scope: Construct, id: string) { new MyProjectMcpServer(this, 'MyProjectMcpServer'); }}
Puoi concedere l’accesso per invocare il tuo MCP su Bedrock AgentCore Runtime utilizzando il metodo grantInvoke
. Ad esempio, potresti voler consentire a un agent generato con il generatore py#strands-agent
di chiamare il tuo server MCP:
import { MyProjectAgent, MyProjectMcpServer } from ':my-scope/common-constructs';
export class ExampleStack extends Stack { constructor(scope: Construct, id: string) { const agent = new MyProjectAgent(this, 'MyProjectAgent'); const mcpServer = new MyProjectMcpServer(this, 'MyProjectMcpServer');
mcpServer.agentCoreRuntime.grantInvoke(agent.agentCoreRuntime); }}
# Server MCPmodule "my_project_mcp_server" { # Percorso relativo al modulo generato nel progetto common/terraform source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"}
Per concedere l’accesso a invocare l’agent, dovrai aggiungere una policy come la seguente, riferendoti all’output module.my_project_mcp_server.agent_core_runtime_arn
:
{ Effect = "Allow" Action = [ "bedrock-agentcore:InvokeAgentRuntime" ] Resource = [ module.my_project_mcp_server.agent_core_runtime_arn, "${module.my_project_mcp_server.agent_core_runtime_arn}/*" ]}
Autenticazione con JWT di Cognito
Sezione intitolata “Autenticazione con JWT di Cognito”Di seguito viene dimostrato come configurare l’autenticazione Cognito per il tuo agent.
Per configurare l’autenticazione JWT, puoi passare la proprietà authorizerConfiguration
al costrutto del server MCP. Ecco un esempio che configura un user pool e client Cognito per proteggere il server MCP:
import { MyProjectMcpServer } from ':my-scope/common-constructs';
export class ExampleStack extends Stack { constructor(scope: Construct, id: string) { const userPool = new UserPool(this, 'UserPool'); const client = userPool.addClient('Client', { authFlows: { userPassword: true, }, });
new MyProjectMcpServer(this, 'MyProjectMcpServer', { authorizerConfiguration: { customJwtAuthorizer: { discoveryUrl: `https://cognito-idp.${Stack.of(userPool).region}.amazonaws.com/${userPool.userPoolId}/.well-known/openid-configuration`, allowedClients: [client.userPoolClientId], }, }, }); }}
Per configurare l’autenticazione JWT, puoi modificare il modulo del server MCP per configurare la variabile customJWTAuthorizer
come segue:
data "aws_region" "current" {}
locals { aws_region = data.aws_region.current.name
# Sostituisci con i tuoi ID user pool e client o esponili come variabili user_pool_id = "xxx" user_pool_client_ids = ["yyy"]}
module "agent_core_runtime" { source = "../../../core/agent-core" agent_runtime_name = "MyProjectMcpServer" docker_image_tag = "my-scope-my-project-agent:latest" server_protocol = "MCP" customJWTAuthorizer = { discoveryUrl = "https://cognito-idp.${local.aws_region}.amazonaws.com/${local.user_pool_id}/.well-known/openid-configuration", allowedClients = local.user_pool_client_ids } env = var.env additional_iam_policy_statements = var.additional_iam_policy_statements tags = var.tags}
Target bundle
Sezione intitolata “Target bundle”Il generatore configura automaticamente un target bundle
che utilizza Rolldown per creare un pacchetto di distribuzione:
pnpm nx run <project-name>:bundle
yarn nx run <project-name>:bundle
npx nx run <project-name>:bundle
bunx nx run <project-name>:bundle
La configurazione di Rolldown si trova in rolldown.config.ts
, con un’entry per bundle da generare. Rolldown gestisce la creazione di più bundle in parallelo se definiti.
Il target bundle usa http.ts
come entrypoint per il server MCP HTTP Streamable da hostare su Bedrock AgentCore Runtime.
Target Docker
Sezione intitolata “Target Docker”Il generatore configura un target <your-server-name>-docker
che esegue il server MCP HTTP Streamable bundled sulla porta 8000
secondo il contratto di servizio MCP.
Viene generato anche un target docker
che esegue il build Docker per tutti i server MCP se ne sono definiti multipli.
Osservabilità
Sezione intitolata “Osservabilità”Il tuo server MCP viene configurato automaticamente con l’osservabilità utilizzando AWS Distro for Open Telemetry (ADOT), tramite la configurazione dell’auto-strumentazione nel tuo Dockerfile
.
Puoi trovare le tracce nella Console AWS CloudWatch selezionando “GenAI Observability” nel menu. Nota che affinché le tracce vengano popolate, dovrai abilitare Transaction Search.
Per ulteriori dettagli, consulta la documentazione di AgentCore sull’osservabilità.