Servidor MCP em TypeScript

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

O que é o MCP?

O Model Context Protocol (MCP) é um padrão aberto que permite 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:

VSCode

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
6. Clique em Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#mcp-server

yarn

yarn nx g @aws/nx-plugin:ts#mcp-server

npm

npx nx g @aws/nx-plugin:ts#mcp-server

bun

bunx nx g @aws/nx-plugin:ts#mcp-server

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

pnpm

pnpm nx g @aws/nx-plugin:ts#mcp-server --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#mcp-server --dry-run

npm

npx nx g @aws/nx-plugin:ts#mcp-server --dry-run

bun

bunx nx g @aws/nx-plugin:ts#mcp-server --dry-run

Dica

Primeiro use o gerador ts#project para criar um projeto onde adicionar seu servidor MCP.

Opções

Parâmetro	Tipo	Padrão	Descrição
project Obrigatório	string	-	The project to add an MCP server to
name	string	-	The name of your MCP server (default: mcp-server)

Saída do Gerador

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

• Directoryyour-project/

  • Directorysrc/

    • Directorymcp-server/ (ou nome personalizado se especificado)

      • index.ts Ponto de entrada do servidor MCP
      • server.ts Definição principal do servidor
      • Directorytools/

        • add.ts Ferramenta de exemplo
      • Directoryresources/

        • sample-guidance.ts Recurso de exemplo
  • package.json Atualizado com entrada bin e dependências MCP
  • project.json Atualizado com alvo de serviço do servidor MCP

Trabalhando com seu servidor MCP

Adicionando Ferramentas

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

Adicionando Recursos

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

const exampleContext = 'some context to return';

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

Configuração com Assistentes de IA

Arquivos de Configuração

A maioria dos assistentes de IA que suportam MCP utiliza 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": "npx",
      "args": ["tsx", "/path/to/your-mcp-server/index.ts"]
    }
  }
}

Cuidado

Se você receber um erro como ENOENT npx ao conectar ao servidor, talvez precise especificar o caminho completo para o npx, que pode ser obtido executando which npx no terminal.

Recarregamento Automático

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

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

Nota

Ao adicionar novas ferramentas ou recursos, talvez seja necessário atualizar o servidor MCP no assistente de IA.

Configuração Específica do Assistente

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

• Amazon Q Developer
• Cline
• Cursor
• Claude Code
• Roo Code

Dica

Alguns assistentes de IA, como o Amazon Q Developer, permitem especificar configurações de servidor MCP no nível do workspace, o que é especialmente útil para definir os servidores MCP relevantes para um projeto específico.

Executando seu servidor MCP

A maneira mais fácil de testar e usar um servidor MCP é configurando-o com um assistente de IA (como acima). Você também pode executar o servidor usando o alvo <your-server-name>-serve, útil se alternar do transporte STDIO para transporte HTTP Streamable.

pnpm

pnpm nx run your-project:your-server-name-serve

yarn

yarn nx run your-project:your-server-name-serve

npm

npx nx run your-project:your-server-name-serve

bun

bunx nx run your-project:your-server-name-serve

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