Guia de Desenvolvimento de Servidores MCP
Visão Geral
Para criar servidores MCP (Model Context Protocol) de alta qualidade que permitam 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 externos. 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
🚀 Fluxo de Trabalho de Alto Nível
Criar um servidor MCP de alta qualidade envolve quatro fases principais:
Fase 1: Pesquisa e Planejamento Aprofundados
1.1 Entenda os Princípios de Design Centrados em Agentes
Antes de mergulhar na implementação, entenda como projetar ferramentas para agentes de IA revisando estes princípios:
Construa para Fluxos de Trabalho, Não Apenas para Endpoints de API:
- Não simplesmente envolva endpoints de API existentes - construa ferramentas de fluxo de trabalho ponderadas e de alto impacto
- Consolide operações relacionadas (ex.:
schedule_eventque verifica disponibilidade e cria evento) - Foco em ferramentas que permitem tarefas completas, não apenas chamadas de API individuais
- Considere quais fluxos de trabalho os agentes realmente precisam realizar
Otimize para Contexto Limitado:
- Agentes têm janelas de contexto limitadas - faça cada token valer a pena
- Retorne informações de alto sinal, não despejos de dados exaustivos
- Forneça opções de formato de resposta "conciso" vs. "detalhado"
- Prefira identificadores legíveis por humanos a 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:
- As 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 por meio de feedback claro
Siga Subdivisões Naturais de Tarefas:
- Os nomes das ferramentas devem refletir como os humanos pensam sobre tarefas
- Agrupe ferramentas relacionadas com prefixos consistentes para facilitar a descoberta
- Projete ferramentas em torno de fluxos de trabalho naturais, não apenas da estrutura da API
Use Desenvolvimento Orientado por Avaliação:
- Crie cenários de avaliação realistas desde o início
- Deixe o feedback do agente impulsionar melhorias nas ferramentas
- Faça protótipos 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 completa do MCP e diretrizes.
1.4 Estude a Documentação do Framework
Carregue e leia os seguintes arquivos de referência:
- Práticas Recomendadas MCP: 📋 Ver Práticas Recomendadas - Diretrizes principais para todos os servidores MCP
Para implementações em 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 - Práticas recomendadas e exemplos específicos para Python
Para implementações em 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 - Práticas recomendadas 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 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 para implementar
- Priorize ferramentas que permitam os casos de uso mais comuns e importantes
- Considere quais ferramentas trabalham juntas para permitir fluxos de trabalho complexos
Utilitários e Auxiliares Compartilhados:
- Identifique padrões comuns de requisição de API
- Planeje auxiliares 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 larga 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 e em linguagem natural que incentivem ações adicionais
- Considere cenários de limitação de taxa e tempo limite
- Lide com erros de autenticação e autorização
Fase 2: Implementação
Agora que você tem um plano abrangente, comece a implementação seguindo as práticas recomendadas específicas da linguagem.
2.1 Configure a Estrutura do Projeto
Para Python:
- Crie um único arquivo
.pyou 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 uma estrutura de projeto adequada (veja ⚡ Guia TypeScript)
- Configure
package.jsonetsconfig.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 ferramentas:
- Funções auxiliares de requisição de API
- Utilitários de tratamento de erros
- Funções de formatação de resposta (JSON e Markdown)
- Auxiliares de paginação
- Gerenciamento de autenticação/token
2.3 Implemente Ferramentas Sistematicamente
Para cada ferramenta no plano:
Defina o Esquema de Entrada:
- Use Pydantic (Python) ou Zod (TypeScript) para validação
- Inclua restrições adequadas (min/max length, padrões regex, min/max values, ranges)
- 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 sobre o 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 diante de 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 E/S
- Implemente tratamento adequado de erros
- Suporte múltiplos formatos de resposta (JSON e Markdown)
- Respeite os parâmetros de paginação
- Verifique limites de caracteres e trunque adequadamente
Adicione Anotações à Ferramenta:
readOnlyHint: true (para operações somente leitura)destructiveHint: false (para operações não destrutivas)idempotentHint: true (se chamadas repetidas têm o mesmo efeito)openWorldHint: true (se estiver interagindo com sistemas externos)
2.4 Siga as Práticas Recomendadas 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 adequado de ferramentas
- Modelos Pydantic v2 com
model_config - Type hints em todo lugar
- Async/await para todas as operações de E/S
- Organização adequada de imports
- Constantes em nível de módulo (CHARACTER_LIMIT, API_BASE_URL)
Para Node/TypeScript: Carregue ⚡ Guia de Implementação TypeScript e garanta o seguinte:
- Usando
server.registerTooladequadamente - Esquemas Zod com
.strict() - TypeScript strict mode habilitado
- Sem tipos
any- use tipos adequados - Tipos de retorno explícitos Promise
- 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 do Código
Para garantir qualidade, revise o código quanto a:
- Princípio DRY: Sem código duplicado entre ferramentas
- Composabilidade: Lógica compartilhada extraída para funções
- Consistência: Operações semelhantes retornam formatos semelhantes
- Tratamento de Erros: Todas as chamadas externas têm tratamento de erros
- Type Safety: Cobertura total de tipos (type hints Python, tipos TypeScript)
- Documentação: Cada ferramenta tem docstrings/descrições abrangentes
3.2 Teste e Compile
Importante: Servidores MCP são processos de longa duração que aguardam requisiçõ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 pare indefinidamente.
Formas seguras de testar o servidor:
- Use o harness de avaliação (veja Fase 4) - abordagem recomendada
- Execute o servidor no 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 os imports funcionam corretamente revisando o arquivo
- Para testar manualmente: Execute o servidor no 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 builde garanta que termine sem erros - Verifique se dist/index.js foi criado
- Para testar manualmente: Execute o servidor no 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 o Checklist de Qualidade
Para verificar a qualidade da implementação, carregue o checklist apropriado do guia específico da linguagem:
- Python: veja "Quality Checklist" em 🐍 Guia Python
- Node/TypeScript: veja "Quality Checklist" 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 os 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:
- Inspeção de Ferramentas: Liste as ferramentas disponíveis e entenda suas capacidades
- Exploração de Conteúdo: Use operações SOMENTE LEITURA para explorar dados disponíveis
- Geração de Perguntas: Crie 10 perguntas complexas e realistas
- 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 ferramenta e exploração profunda
- Realista: Baseada em casos de uso reais que humanos se importariam
- Verificável: Resposta única e clara que pode ser verificada por comparação de strings
- Estável: Resposta que 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 nomeado após um gato selvagem manchado?</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 Central do MCP (Carregue Primeiro)
- Protocolo MCP: Obtenha de
https://modelcontextprotocol.io/llms-full.txt- Especificação completa do MCP - 📋 Práticas Recomendadas MCP - Diretrizes universais do MCP incluindo:
- Convenções de nomenclatura de servidores e ferramentas
- Diretrizes de formato de resposta (JSON vs Markdown)
- Práticas recomendadas 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 do 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 de 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
- Checklist de qualidade
-
⚡ Guia de Implementação TypeScript - Guia completo TypeScript com:
- Estrutura de projeto
- Padrões de esquema Zod
- Registro de ferramentas com
server.registerTool - Exemplos funcionais completos
- Checklist de qualidade
Guia de Avaliação (Carregue Durante a Fase 4)
- ✅ Guia de Avaliação - Guia completo de criação de avaliação com:
- Diretrizes de criação de perguntas
- Estratégias de verificação de respostas
- Especificações de formato XML
- Exemplos de perguntas e respostas
- Executando uma avaliação com os scripts fornecidos