Gerar Servidor MCP TypeScript

Crie um servidor completo de Model Context Protocol (MCP) em TypeScript usando o MCP TypeScript SDK v2 com as seguintes especificações:

Requisitos

1. Estrutura do Projeto: Crie um novo projeto TypeScript/Node.js com estrutura de diretórios adequada.
2. Pacotes NPM: O pacote monolítico v1 @modelcontextprotocol/sdk está aposentado. Use os pacotes focados v2:
   • @modelcontextprotocol/server — implementação do servidor (transporte stdio via subcaminho @modelcontextprotocol/server/stdio)
   • @modelcontextprotocol/node — transporte HTTP Node (NodeStreamableHTTPServerTransport), ou um adaptador de framework: @modelcontextprotocol/express, @modelcontextprotocol/hono, @modelcontextprotocol/fastify — cada adaptador requer a instalação do seu framework correspondente junto com ele (por exemplo, @modelcontextprotocol/express + express)
   • @modelcontextprotocol/core — esquemas de protocolo compartilhados (importe as constantes *Schema daqui, não de sdk/types.js)
   • zod@^4.2 — v2 requer Zod 4.2+; não use zod@3
3. Runtime: Node.js 20+ (mínimo v2); ESM-first com "type": "module" (uma build CommonJS também é fornecida, então require() funciona se necessário)
4. Tipo de Servidor: Escolha entre servidor baseado em HTTP (transporte HTTP Streamable) ou stdio. Transportes SSE e WebSocket foram removidos na v2 — não os gere.
5. Ferramentas: Crie pelo menos uma ferramenta útil com validação de esquema adequada.
6. Tratamento de Erros: Inclua tratamento de erros e validação abrangentes.

Detalhes de Implementação

Configuração do Projeto

• Inicialize com npm init e crie package.json.
• Instale as dependências: @modelcontextprotocol/server, zod@^4.2 e o pacote de transporte — @modelcontextprotocol/node para HTTP Node puro, ou um adaptador de framework junto com seu framework correspondente (por exemplo, npm install @modelcontextprotocol/express express).
• Configure TypeScript com módulos ES: "type": "module" em package.json.
• Adicione dependências de desenvolvimento: tsx ou ts-node para desenvolvimento.
• Crie um arquivo .gitignore adequado.

Configuração do Servidor

• Use a classe McpServer de @modelcontextprotocol/server para implementação de alto nível.
• Defina o nome e a versão do servidor.
• Escolha o transporte apropriado:
  • HTTP (Node): NodeStreamableHTTPServerTransport de @modelcontextprotocol/node.
  • HTTP (Runtimes Web Standard): WebStandardStreamableHTTPServerTransport de @modelcontextprotocol/server.
  • stdio: StdioServerTransport de @modelcontextprotocol/server/stdio.
• Para HTTP: prefira um adaptador de framework (@modelcontextprotocol/express, etc.) com middleware e tratamento de erros adequados.
• Observe que a v2 usa os tipos Web Standard Headers/Request; leia cabeçalhos com ctx.http?.req?.headers.get('x-custom').

Implementação de Ferramentas

• Use registerTool() com um objeto de configuração — as assinaturas variádicas .tool() da v1 foram removidas:

  server.registerTool('greet', {
    description: 'Greet user',
    inputSchema: z.object({ name: z.string() })
  }, async ({ name }, ctx) => {
    return { content: [{ type: 'text', text: `Hello, ${name}!` }] };
  });
  

• Os esquemas devem ser objetos Zod completos (z.object({...})) — objetos de forma bruta ({ name: z.string() }) estão obsoletos.
• Forneça campos claros de title e description.
• Retorne tanto content quanto structuredContent nos resultados.
• O segundo parâmetro do handler é um objeto ctx estruturado (substitui extra da v1): ctx.mcpReq.signal, ctx.mcpReq.id, ctx.mcpReq.send(...), ctx.mcpReq.notify(...).
• Implemente tratamento de erros adequado com blocos try-catch; use a hierarquia de erros v2 (ProtocolError, SdkError, SdkHttpError com .status) em vez de McpError/StreamableHTTPError da v1.
• Suporte operações assíncronas onde apropriado.

Configuração de Recurso/Prompt (Opcional)

• Adicione recursos usando registerResource() com ResourceTemplate para URIs dinâmicos.
• Adicione prompts usando registerPrompt() com esquemas de argumento (mesmo estilo de objeto de configuração como registerTool()).
• Considere adicionar suporte de completude para melhor UX; observe a ordem do wrapper completable() da v2: completable(z.string(), callback).optional() (aplicado opcionalmente externamente).

Qualidade do Código

• Use TypeScript para segurança de tipos.
• Siga padrões async/await consistentemente.
• Implemente limpeza adequada em eventos de fechamento do transporte.
• Use variáveis de ambiente para configuração.
• Adicione comentários inline para lógica complexa.
• Estruture o código com clara separação de responsabilidades.

Tipos de Ferramentas de Exemplo a Considerar

• Processamento e transformação de dados

…