Salta ai contenuti

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.

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

Puoi generare un server MCP TypeScript in due modi:

  1. Installa il Nx Console VSCode Plugin se non l'hai già fatto
  2. Apri la console Nx in VSCode
  3. Clicca su Generate (UI) nella sezione "Common Nx Commands"
  4. Cerca @aws/nx-plugin - ts#mcp-server
  5. Compila i parametri richiesti
    • Clicca su Generate
    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.

    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 a None)
      • package.json Aggiornato con entry bin e dipendenze MCP
      • project.json Aggiornato con target serve del server MCP

    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

    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

    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" }]
    };
    }
    );

    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 dinamica
    server.resource('dynamic-resource', 'dynamic://resource', async (uri) => {
    const data = await fetchSomeData();
    return {
    contents: [{ uri: uri.href, text: data }],
    };
    });

    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.

    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.

    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.

    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.

    Terminal window
    pnpm 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.

    Terminal window
    pnpm nx run your-project:your-server-name-serve-stdio

    Questo comando usa tsx --watch per riavviare automaticamente il server quando i file cambiano.

    Se vuoi eseguire il server MCP localmente usando il trasporto HTTP Streamable, puoi usare il target <your-server-name>-serve-http.

    Terminal window
    pnpm 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”

    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');
    }
    }

    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.

    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);
    }
    }

    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],
    },
    },
    });
    }
    }

    Il generatore configura automaticamente un target bundle che utilizza Rolldown per creare un pacchetto di distribuzione:

    Terminal window
    pnpm 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.

    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.

    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à.