Pular para o conteúdo

Servidor MCP em TypeScript

Gere um servidor TypeScript do Model Context Protocol (MCP) para fornecer contexto a Large Language Models (LLMs), e opcionalmente implante-o no Amazon Bedrock AgentCore.

O Model Context Protocol (MCP) é um padrão aberto que permite a assistentes de IA interagirem com ferramentas e recursos externos. Ele fornece uma maneira consistente para LLMs:

  • Executar ferramentas (funções) que realizam ações ou recuperam informações
  • Acessar recursos que fornecem contexto ou dados

Você pode gerar um servidor MCP em TypeScript de duas formas:

  1. Instale o Nx Console VSCode Plugin se ainda não o fez
  2. Abra o console Nx no VSCode
  3. Clique em Generate (UI) na seção "Common Nx Commands"
  4. Procure por @aws/nx-plugin - ts#mcp-server
  5. Preencha os parâmetros obrigatórios
    • Clique em Generate
    Parâmetro Tipo Padrão Descrição
    project Obrigatório 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.

    O gerador adicionará os seguintes arquivos ao seu projeto TypeScript existente:

    • Directoryyour-project/
      • Directorysrc/
        • Directorymcp-server/ (ou nome personalizado se especificado)
          • index.ts Exporta seu servidor
          • server.ts Definição principal do servidor
          • stdio.ts Ponto de entrada para transporte STDIO, útil para servidores MCP locais simples
          • http.ts Ponto de entrada para transporte HTTP Streamable, útil para hospedar seu servidor MCP
          • Directorytools/
            • add.ts Exemplo de ferramenta
          • Directoryresources/
            • sample-guidance.ts Exemplo de recurso
          • Dockerfile Ponto de entrada para hospedar seu servidor MCP (excluído quando computeType é definido como None)
      • package.json Atualizado com entrada bin e dependências MCP
      • project.json Atualizado com alvo de serviço do servidor MCP

    Como este gerador fornece infraestrutura como código com base no iacProvider escolhido, ele criará um projeto em packages/common que inclui os constructs CDK ou módulos Terraform relevantes.

    O projeto comum de infraestrutura como código está estruturado da seguinte forma:

    • Directorypackages/common/constructs
      • Directorysrc
        • Directoryapp/ Constructs para infraestrutura específica de um projeto/gerador
        • Directorycore/ Constructs genéricos reutilizados pelos constructs em app
        • index.ts Ponto de entrada exportando os constructs de app
      • project.json Metas de build e configuração do projeto

    Para implantar seu MCP Server, os seguintes arquivos são gerados:

    • Directorypackages/common/constructs/src
      • Directoryapp
        • Directorymcp-servers
          • Directory<project-name>
            • <project-name>.ts Construto CDK para implantar seu MCP Server
            • Dockerfile Arquivo Docker passthrough usado pelo construto CDK
      • Directorycore
        • Directoryagent-core
          • runtime.ts Construto CDK genérico para implantação no Bedrock AgentCore Runtime

    Ferramentas são funções que o assistente de IA pode chamar para realizar ações. Você pode adicionar novas ferramentas no arquivo server.ts:

    server.tool("toolName", "tool description",
    { param1: z.string(), param2: z.number() }, // Esquema de entrada usando Zod
    async ({ param1, param2 }) => {
    // Implementação da ferramenta
    return {
    content: [{ type: "text", text: "Result" }]
    };
    }
    );

    Recursos fornecem contexto ao assistente de IA. Você pode adicionar recursos estáticos de arquivos ou recursos dinâmicos:

    const exampleContext = 'algum contexto para retornar';
    server.resource('resource-name', 'example://resource', async (uri) => ({
    contents: [{ uri: uri.href, text: exampleContext }],
    }));
    // Recurso dinâmico
    server.resource('dynamic-resource', 'dynamic://resource', async (uri) => {
    const data = await fetchSomeData();
    return {
    contents: [{ uri: uri.href, text: data }],
    };
    });

    A maioria dos assistentes de IA que suportam MCP usam uma abordagem de configuração semelhante. Você precisará criar ou atualizar um arquivo de configuração com os detalhes do seu servidor MCP:

    {
    "mcpServers": {
    "your-mcp-server": {
    "command": "npx",
    "args": ["tsx", "/path/to/your-mcp-server/stdio.ts"]
    }
    }
    }

    Durante o desenvolvimento do seu servidor MCP, você pode querer configurar a flag --watch para que o assistente de IA sempre veja as versões mais recentes de ferramentas/recursos:

    {
    "mcpServers": {
    "your-mcp-server": {
    "command": "npx",
    "args": ["tsx", "--watch", "/path/to/your-mcp-server/stdio.ts"]
    }
    }
    }

    Consulte a documentação a seguir para configurar o MCP com assistentes de IA específicos:

    O gerador configura um alvo chamado <your-server-name>-inspect, que inicia o MCP Inspector com a configuração para conectar ao seu servidor MCP usando transporte STDIO.

    Terminal window
    pnpm nx run your-project:your-server-name-inspect

    Isso iniciará o inspector em http://localhost:6274. Comece clicando no botão “Connect”.

    A maneira mais fácil de testar e usar um servidor MCP é usando o inspector ou configurando-o com um assistente de IA (como acima).

    Você também pode executar seu servidor com transporte STDIO diretamente usando o alvo <your-server-name>-serve-stdio.

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

    Este comando usa tsx --watch para reiniciar automaticamente o servidor quando arquivos mudarem.

    Se você deseja executar seu servidor MCP localmente usando transporte HTTP Streamable, pode usar o alvo <your-server-name>-serve-http.

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

    Este comando usa tsx --watch para reiniciar automaticamente o servidor quando arquivos mudarem.

    Implantando Seu Servidor MCP no Bedrock AgentCore Runtime

    Seção intitulada “Implantando Seu Servidor MCP no Bedrock AgentCore Runtime”

    Se você selecionou BedrockAgentCoreRuntime para computeType, a infraestrutura relevante do CDK ou Terraform será gerada para que você possa implantar seu servidor MCP no Amazon Bedrock AgentCore Runtime.

    Um construto CDK é gerado para você, nomeado com base no name escolhido ao executar o gerador, ou <ProjectName>McpServer por padrão.

    Você pode usar este construto CDK em uma aplicação CDK:

    import { MyProjectMcpServer } from ':my-scope/common-constructs';
    export class ExampleStack extends Stack {
    constructor(scope: Construct, id: string) {
    // Adicione o servidor MCP à sua stack
    new MyProjectMcpServer(this, 'MyProjectMcpServer');
    }
    }

    Por padrão, seu servidor MCP será protegido usando autenticação IAM. Basta implantá-lo sem argumentos adicionais:

    import { MyProjectMcpServer } from ':my-scope/common-constructs';
    export class ExampleStack extends Stack {
    constructor(scope: Construct, id: string) {
    new MyProjectMcpServer(this, 'MyProjectMcpServer');
    }
    }

    Você pode conceder acesso para invocar seu MCP no Bedrock AgentCore Runtime usando o método grantInvoke. Por exemplo, você pode permitir que um agent gerado com o gerador py#strands-agent chame seu servidor 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);
    }
    }

    O exemplo abaixo demonstra como configurar autenticação Cognito para seu servidor.

    Para configurar autenticação JWT, você pode passar a propriedade authorizerConfiguration para seu construto de servidor MCP. Este exemplo configura um user pool e client Cognito para proteger o servidor:

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

    O gerador configura automaticamente um destino bundle que utiliza o Rolldown para criar um pacote de implantação:

    Terminal window
    pnpm nx run <project-name>:bundle

    A configuração do Rolldown pode ser encontrada em rolldown.config.ts, com uma entrada para cada pacote a ser gerado. O Rolldown gerencia a criação de múltiplos pacotes em paralelo, se definidos.

    O alvo de bundle usa http.ts como ponto de entrada para o servidor MCP HTTP Streamable hospedado no Bedrock AgentCore Runtime.

    O gerador configura um alvo <your-server-name>-docker que executa o servidor MCP HTTP Streamable empacotado na porta 8000 conforme o contrato do protocolo MCP.

    Um alvo docker também é gerado para executar o build docker para todos servidores MCP se você tiver múltiplos definidos.

    Seu servidor MCP é configurado automaticamente com observabilidade usando a AWS Distro for Open Telemetry (ADOT), através da configuração de instrumentação automática em seu Dockerfile.

    Você pode encontrar traces no Console AWS do CloudWatch, selecionando “GenAI Observability” no menu. Observe que para que os traces sejam populados, você precisará habilitar o Transaction Search.

    Para mais detalhes, consulte a documentação do AgentCore sobre observabilidade.