Pular para o conteúdo
@aws/nx-plugin
Blog

ts#mcp-server

Gerador de Servidor MCP em TypeScript

Gere um servidor Model Context Protocol (MCP) em TypeScript para fornecer contexto a Large Language Models (LLMs).

O que é o MCP?

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

Uso

Gerar um Servidor MCP

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

    Opções

    Parâmetro Tipo Padrão Descrição
    name Obrigatório string - MCP server project name.
    directory string packages Parent directory where the MCP server is placed.
    subDirectory string - The sub directory the MCP server is placed in. By default this is the MCP server project name.

    Saída do Gerador

    O gerador criará os seguintes arquivos do projeto:

    • Directorypackages/<nome>/
      • README.md Documentação do servidor MCP com instruções de uso
      • project.json Configuração do projeto Nx com targets de build, bundle e dev
      • Directorysrc/
        • index.ts Ponto de entrada do servidor MCP
        • server.ts Definição principal do servidor, definindo ferramentas e recursos
        • global.d.ts Declarações de tipos TypeScript para importar arquivos markdown
        • Directoryresources/
          • example-context.md Arquivo markdown de exemplo usado como recurso pelo servidor MCP

    Trabalhando com Seu Servidor MCP

    Adicionando Ferramentas

    Ferramentas são funções que o assistente de IA pode chamar para executar 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" }]
        };
      }
    );

    Adicionando Recursos

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

    // Recurso estático de um arquivo
    import exampleContext from './resources/example-context.md';
    

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

    Configurando com Assistentes de IA

    Para usar seu servidor MCP com assistentes de IA, você precisa compilá-lo primeiro:

    Terminal window
    pnpm nx run your-mcp-server:bundle

    Isso cria uma versão compilada em dist/packages/your-mcp-server/bundle/index.js (o caminho pode variar conforme suas configurações de diretório).

    Arquivos de Configuração

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

    {
      "mcpServers": {
        "your-mcp-server": {
          "command": "node",
          "args": [
            "/path/to/workspace/dist/packages/your-mcp-server/bundle/index.js"
          ],
          "transportType": "stdio"
        }
      }
    }

    Substitua /path/to/workspace/dist/packages/your-mcp-server/bundle/index.js pelo caminho real para seu servidor MCP compilado.

    Configuração Específica por Assistente

    Consulte a documentação abaixo para configurar o MCP com assistentes específicos:

    Nota de implementação:
    Como solicitado, todos os nomes de produtos, URLs e elementos técnicos foram mantidos em seu formato original. A estrutura MDX e a formatação permanecem idênticas ao conteúdo original em inglês.

    Fluxo de Desenvolvimento

    Targets de Build

    O gerador é baseado no gerador de projetos TypeScript e herda seus targets, além de adicionar os seguintes targets adicionais:

    Bundle

    O target bundle usa esbuild para criar um único arquivo JavaScript que pode ser usado com assistentes de IA:

    Terminal window
    pnpm nx run your-mcp-server:bundle

    Isso cria uma versão compilada em dist/packages/your-mcp-server/bundle/index.js (o caminho pode variar conforme suas configurações de diretório).

    Dev

    O target dev monitora mudanças em seu projeto e recompila automaticamente o bundle:

    Terminal window
    pnpm nx run your-mcp-server:dev

    Isso é particularmente útil durante o desenvolvimento, garantindo que seu assistente de IA utilize a versão mais recente do servidor MCP.