A maioria dos servidores MCP que vejo por aí começa como um script rápido e permanece assim — sem validação, sem registro estruturado, sem testes e uma história de implantação que significa enviar node_modules por aí.

Eu fiquei cansado de reconstruir a mesma estrutura toda vez que um projeto de cliente precisava de um servidor do Protocolo de Contexto de Modelo, então eu open-sourci o template que agora começo todos: 🚀 mcp-server-template

É uma base pronta para produção em TypeScript/Node.js para construir servidores MCP que conectam agentes de IA como Claude Desktop e Cursor às suas ferramentas, dados e fluxos de trabalho.

𝗚𝗲𝘁𝘁𝗶𝗻𝗴 𝘀𝘁𝗮𝗿𝘁𝗲𝗱 𝘁𝗮𝗸𝗲𝘀 𝗳𝗼𝘂𝗿 𝗰𝗼𝗺𝗺𝗮𝗻𝗱𝘀:

git clone https://github.com/qmmughal/mcp-server-template.git
cd mcp-server-template && npm install
cp .env.example .env
npm run dev

Isso inicia um servidor em modo de observação. npm test executa a suíte Vitest, npm run build empacota tudo em um único dist/index.js com esbuild — sem node_modules para implantar.

𝗪𝗵𝗮𝘁 𝗮 𝘁𝗼𝗼𝗹 𝗮𝗰𝘁𝘂𝗮𝗹𝗹𝘆 𝗹𝗼𝗼𝗸𝘀 𝗹𝗶𝗸𝗲:

Cada ferramenta recebe um esquema Zod, uma definição e um manipulador — assim, uma carga útil de IA malformada é rejeitada com um erro limpo em vez de travar seu processo:

const schema = z.object({
  text: z.string().describe("O texto a ser processado"),
  repeat: z.number().int().min(1).max(10).optional()
});

export async function handleExampleTool(args: unknown, service: ExampleService) {
  return withErrorHandling("process_text", async () => {
    const { text, repeat } = validateArgs(schema, args);
    const result = await service.processText(text, repeat);
    return { content: [{ type: "text", text: result }] };
  });
}

𝗘𝘅𝘁𝗲𝗻𝗱𝗶𝗻𝗴 𝗶𝘁 𝗳𝗼𝗿 𝘆𝗼𝘂𝗿 𝗼𝘄𝗻 𝘁𝗼𝗼𝗹𝘀:

1. Coloque um novo arquivo em src/tools/ seguindo a mesma estrutura de esquema → definição → manipulador
2. Registre-o em src/tools/index.ts — adicione sua definição à lista de ferramentas e um caso à declaração switch que roteia CallToolRequest para seu manipulador
3. Coloque sua lógica real em src/services/ para que a camada de protocolo permaneça fina e sua lógica de negócios permaneça testável em isolamento
4. Recursos (dados que a IA pode ler) e Prompts (modelos reutilizáveis) seguem o mesmo padrão exato em suas próprias pastas — copie o exemplo, renomeie, ajuste o esquema

A gravação estruturada com pino é roteada com segurança para stderr ao longo do caminho, para que nunca corrompa o transporte stdio do MCP, independentemente do que você adicionar.

Quando você estiver pronto para enviar, marque uma versão e um fluxo de trabalho do GitHub Actions publica automaticamente tanto no npm quanto no Registro MCP:

git tag v1.0.0 && git push origin v1.0.0

O objetivo é simples — gaste seu tempo na lógica que torna seu servidor MCP útil, não em resolver novamente a gravação, validação e empacotamento pela quinta vez.

Está licenciado sob MIT e disponível no GitHub agora. Se você está construindo integrações de IA agentivas, eu adoraria feedback ou uma estrela:

🔗 github.com/qmmughal/mcp-server-template

MCP #ModelContextProtocol #AgenticAI #TypeScript #OpenSource #AIEngineering #ClaudeAI