construtor-mcp

Guia de Desenvolvimento de Servidor MCP

Visão Geral

Para criar servidores MCP (Model Context Protocol) de alta qualidade que permitem que LLMs interajam efetivamente com serviços externos, use esta skill. Um servidor MCP fornece ferramentas que permitem que LLMs acessem serviços e APIs externas. A qualidade de um servidor MCP é medida por quão bem ele permite que LLMs realizem tarefas do mundo real usando as ferramentas fornecidas.

---

Processo

🚀 Workflow de Alto Nível

Criar um servidor MCP de alta qualidade envolve quatro fases principais:

Fase 1: Pesquisa e Planejamento Profundos

1.1 Entenda os Princípios de Design Centrado no Agente

Antes de mergulhar na implementação, entenda como projetar ferramentas para agentes de IA revisando estes princípios:

Construa para Workflows, Não Apenas para Endpoints de API:

• Não simplesmente envolva endpoints de API existentes - construa ferramentas de workflow criteriosas e de alto impacto
• Consolide operações relacionadas (ex.: agendar_evento que verifica disponibilidade e cria evento)
• Foco em ferramentas que permitem tarefas completas, não apenas chamadas de API individuais
• Considere quais workflows os agentes realmente precisam realizar

Otimize para Contexto Limitado:

• Agentes têm janelas de contexto restritas - faça cada token contar
• Retorne informações de alto sinal, não despejos de dados exaustivos
• Forneça opções de formato de resposta "conciso" vs "detalhado"
• Padrão para identificadores legíveis por humanos em vez de códigos técnicos (nomes em vez de IDs)
• Considere o orçamento de contexto do agente como um recurso escasso

Projete Mensagens de Erro Acionáveis:

• Mensagens de erro devem guiar os agentes para padrões de uso corretos
• Sugira próximos passos específicos: "Tente usar filter='active_only' para reduzir resultados"
• Torne os erros educativos, não apenas diagnósticos
• Ajude os agentes a aprender o uso adequado da ferramenta através de feedback claro

Siga Subdivisões Naturais de Tarefas:

• Os nomes das ferramentas devem refletir como os humanos pensam sobre as tarefas
• Agrupe ferramentas relacionadas com prefixos consistentes para facilitar a descoberta
• Projete ferramentas em torno de workflows naturais, não apenas da estrutura da API

Use Desenvolvimento Orientado por Avaliação:

• Crie cenários de avaliação realistas no início
• Deixe o feedback do agente impulsionar melhorias nas ferramentas
• Prototipe rapidamente e itere com base no desempenho real do agente

1.3 Estude a Documentação do Protocolo MCP

Obtenha a documentação mais recente do protocolo MCP:

Use WebFetch para carregar: https://modelcontextprotocol.io/llms-full.txt

Este documento abrangente contém a especificação MCP completa e diretrizes.

1.4 Estude a Documentação do Framework

Carregue e leia os seguintes arquivos de referência:

• Melhores Práticas MCP: 📋 Ver Melhores Práticas - Diretrizes principais para todos os servidores MCP

Para implementações Python, carregue também:

• Documentação do SDK Python: use WebFetch para carregar https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
• 🐍 Guia de Implementação Python - Melhores práticas e exemplos específicos para Python

Para implementações Node/TypeScript, carregue também:

• Documentação do SDK TypeScript: use WebFetch para carregar https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
• ⚡ Guia de Implementação TypeScript - Melhores práticas e exemplos específicos para Node/TypeScript

1.5 Estude Exaustivamente a Documentação da API

Para integrar um serviço, leia TODA a documentação da API disponível:

• Documentação de referência oficial da API
• Requisitos de autenticação e autorização
• Padrões de limitação de taxa e paginação
• Respostas de erro e códigos de status
• Endpoints disponíveis e seus parâmetros
• Modelos de dados e esquemas

Para reunir informações abrangentes, use a pesquisa na web e a ferramenta WebFetch conforme necessário.

1.6 Crie um Plano de Implementação Abrangente

Com base em sua pesquisa, crie um plano detalhado que inclua:

Seleção de Ferramentas:

• Liste os endpoints/operações mais valiosos a implementar
• Priorize ferramentas que permitem os casos de uso mais comuns e importantes
• Considere quais ferramentas trabalham juntas para habilitar workflows complexos

Utilitários e Ajudantes Compartilhados:

• Identifique padrões comuns de solicitação de API
• Planeje ajudantes de paginação
• Projete utilitários de filtragem e formatação
• Planeje estratégias de tratamento de erros

Design de Entrada/Saída:

• Defina modelos de validação de entrada (Pydantic para Python, Zod para TypeScript)
• Projete formatos de resposta consistentes (ex.: JSON ou Markdown) e níveis de detalhe configuráveis (ex.: Detalhado ou Conciso)
• Planeje para uso em grande escala (milhares de usuários/recursos)
• Implemente limites de caracteres e estratégias de truncamento (ex.: 25.000 tokens)

Estratégia de Tratamento de Erros:

• Planeje modos de falha elegantes
• Projete mensagens de erro claras, acionáveis, amigáveis para LLM, em linguagem natural que incentivem ações adicionais
• Considere cenários de limitação de taxa e tempo limite
• Trate erros de autenticação e autorização

---

Fase 2: Implementação

Agora que você tem um plano abrangente, comece a implementação seguindo as melhores práticas específicas da linguagem.

2.1 Configure a Estrutura do Projeto

Para Python:

• Crie um único arquivo .py ou organize em módulos se for complexo (veja 🐍 Guia Python)
• Use o MCP Python SDK para registro de ferramentas
• Defina modelos Pydantic para validação de entrada

Para Node/TypeScript:

• Crie a estrutura de projeto adequada (veja ⚡ Guia TypeScript)
• Configure package.json e tsconfig.json
• Use MCP TypeScript SDK
• Defina esquemas Zod para validação de entrada

2.2 Implemente a Infraestrutura Principal Primeiro

Para começar a implementação, crie utilitários compartilhados antes de implementar as ferramentas:

• Funções auxiliares de solicitação de API
• Utilitários de tratamento de erros
• Funções de formatação de resposta (JSON e Markdown)
• Ajudantes de paginação
• Gerenciamento de autenticação/token

2.3 Implemente Ferramentas Sistematicamente

Para cada ferramenta no plano:

Defina Esquema de Entrada:

• Use Pydantic (Python) ou Zod (TypeScript) para validação
• Inclua restrições adequadas (comprimento mínimo/máximo, padrões regex, valores mínimos/máximos, intervalos)
• Forneça descrições de campo claras e descritivas
• Inclua exemplos diversos nas descrições dos campos

Escreva Docstrings/Descrições Abrangentes:

• Resumo de uma linha do que a ferramenta faz
• Explicação detalhada do propósito e funcionalidade
• Tipos de parâmetros explícitos com exemplos
• Esquema completo do tipo de retorno
• Exemplos de uso (quando usar, quando não usar)
• Documentação de tratamento de erros, que descreve como proceder dados erros específicos

Implemente a Lógica da Ferramenta:

• Use utilitários compartilhados para evitar duplicação de código
• Siga padrões async/await para todas as operações de I/O
• Implemente tratamento de erros adequado
• Suporte a múltiplos formatos de resposta (JSON e Markdown)
• Respeite parâmetros de paginação
• Verifique limites de caracteres e trunque adequadamente

Adicione Anotações de Ferramenta:

• readOnlyHint: verdadeiro (para operações somente leitura)
• destructiveHint: falso (para operações não destrutivas)
• idempotentHint: verdadeiro (se chamadas repetidas têm o mesmo efeito)
• openWorldHint: verdadeiro (se estiver interagindo com sistemas externos)

2.4 Siga as Melhores Práticas Específicas da Linguagem

Neste ponto, carregue o guia de linguagem apropriado:

Para Python: Carregue 🐍 Guia de Implementação Python e garanta o seguinte:

• Usando MCP Python SDK com registro de ferramentas adequado
• Modelos Pydantic v2 com model_config
• Dicas de tipo em todo o código
• Async/await para todas as operações de I/O
• Organização adequada das importações
• Constantes no nível do módulo (CHARACTER_LIMIT, API_BASE_URL)

Para Node/TypeScript: Carregue ⚡ Guia de Implementação TypeScript e garanta o seguinte:

• Usando server.registerTool adequadamente
• Esquemas Zod com .strict()
• Modo TypeScript strict ativado
• Sem tipos any - use tipos adequados
• Tipos de retorno Promise<T> explícitos
• Processo de build configurado (npm run build)

---

Fase 3: Revisão e Refinamento

Após a implementação inicial:

3.1 Revisão de Qualidade de Código

Para garantir a qualidade, revise o código quanto a:

• Princípio DRY: Sem código duplicado entre ferramentas
• Composabilidade: Lógica compartilhada extraída em funções
• Consistência: Operações semelhantes retornam formatos semelhantes
• Tratamento de Erros: Todas as chamadas externas têm tratamento de erros
• Segurança de Tipos: Cobertura total de tipos (dicas de tipo Python, tipos TypeScript)
• Documentação: Cada ferramenta tem docstrings/descrições abrangentes

3.2 Teste e Construa

Importante: Servidores MCP são processos de longa duração que aguardam solicitações via stdio/stdin ou sse/http. Executá-los diretamente em seu processo principal (ex.: python server.py ou node dist/index.js) fará com que seu processo trave indefinidamente.

Maneiras seguras de testar o servidor:

• Use o harness de avaliação (veja Fase 4) - abordagem recomendada
• Execute o servidor em tmux para mantê-lo fora do seu processo principal
• Use um timeout ao testar: timeout 5s python server.py

Para Python:

• Verifique a sintaxe Python: python -m py_compile seu_servidor.py
• Verifique se as importações funcionam corretamente revisando o arquivo
• Para testar manualmente: Execute o servidor em tmux, depois teste com o harness de avaliação no processo principal
• Ou use o harness de avaliação diretamente (ele gerencia o servidor para transporte stdio)

Para Node/TypeScript:

• Execute npm run build e certifique-se de que termina sem erros
• Verifique se dist/index.js foi criado
• Para testar manualmente: Execute o servidor em tmux, depois teste com o harness de avaliação no processo principal
• Ou use o harness de avaliação diretamente (ele gerencia o servidor para transporte stdio)

3.3 Use a Lista de Verificação de Qualidade

Para verificar a qualidade da implementação, carregue a lista de verificação adequada do guia específico da linguagem:

• Python: veja "Lista de Verificação de Qualidade" em 🐍 Guia Python
• Node/TypeScript: veja "Lista de Verificação de Qualidade" em ⚡ Guia TypeScript

---

Fase 4: Crie Avaliações

Após implementar seu servidor MCP, crie avaliações abrangentes para testar sua eficácia.

Carregue ✅ Guia de Avaliação para diretrizes completas de avaliação.

4.1 Entenda o Propósito da Avaliação

As avaliações testam se LLMs podem usar efetivamente seu servidor MCP para responder a perguntas realistas e complexas.

4.2 Crie 10 Perguntas de Avaliação

Para criar avaliações eficazes, siga o processo descrito no guia de avaliação:

1. Inspeção de Ferramentas: Liste as ferramentas disponíveis e entenda suas capacidades
2. Exploração de Conteúdo: Use operações SOMENTE LEITURA para explorar os dados disponíveis
3. Geração de Perguntas: Crie 10 perguntas complexas e realistas
4. Verificação de Respostas: Resolva cada pergunta você mesmo para verificar as respostas

4.3 Requisitos de Avaliação

Cada pergunta deve ser:

• Independente: Não dependente de outras perguntas
• Somente Leitura: Apenas operações não destrutivas necessárias
• Complexa: Exigindo múltiplas chamadas de ferramentas e exploração profunda
• Realista: Baseada em casos de uso reais que humanos considerariam importantes
• Verificável: Resposta única e clara que pode ser verificada por comparação de strings
• Estável: A resposta não muda com o tempo

4.4 Formato de Saída

Crie um arquivo XML com esta estrutura:

<evaluation>
  <qa_pair>
    <question>Encontre discussões sobre lançamentos de modelos de IA com codinomes de animais. Um modelo precisava de uma designação de segurança específica que usa o formato ASL-X. Qual número X estava sendo determinado para o modelo com o nome de um gato selvagem malhado?</question>
    <answer>3</answer>
  </qa_pair>
<!-- Mais qa_pairs... -->
</evaluation>

---

Arquivos de Referência

📚 Biblioteca de Documentação

Carregue estes recursos conforme necessário durante o desenvolvimento:

Documentação Principal do MCP (Carregue Primeiro)

• Protocolo MCP: Obtenha de https://modelcontextprotocol.io/llms-full.txt - Especificação MCP completa
• 📋 Melhores Práticas MCP - Diretrizes MCP universais incluindo:
  • Convenções de nomenclatura de servidores e ferramentas
  • Diretrizes de formato de resposta (JSON vs Markdown)
  • Melhores práticas de paginação
  • Limites de caracteres e estratégias de truncamento
  • Diretrizes de desenvolvimento de ferramentas
  • Padrões de segurança e tratamento de erros

Documentação SDK (Carregue Durante a Fase 1/2)

• SDK Python: Obtenha de https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
• SDK TypeScript: Obtenha de https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md

Guias de Implementação Específicos da Linguagem (Carregue Durante a Fase 2)

• 🐍 Guia de Implementação Python - Guia completo Python/FastMCP com:

  • Padrões de inicialização de servidor
  • Exemplos de modelos Pydantic
  • Registro de ferramentas com @mcp.tool
  • Exemplos funcionais completos
  • Lista de verificação de qualidade

• ⚡ Guia de Implementação TypeScript - Guia completo TypeScript com:

  • Estrutura do projeto
  • Padrões de esquema Zod
  • Registro de ferramentas com server.registerTool
  • Exemplos funcionais completos
  • Lista de verificação de qualidade

Guia de Avaliação (Carregue Durante a Fase 4)

• [✅ Guia de Avaliação](https://raw.githubusercontent.com/ComposioHQ/awesome-claude-skills/master/./reference/evaluation.

…

[truncado para tradução]