Guia de Desenvolvimento de Servidor MCP
Visão Geral
Crie servidores MCP (Model Context Protocol) que permitem que LLMs interajam com serviços externos por meio de ferramentas bem projetadas. A qualidade de um servidor MCP é medida por quão bem ele permite que LLMs realizem tarefas do mundo real.
Processo
🚀 Fluxo de Trabalho de Alto Nível
Criar um servidor MCP de alta qualidade envolve quatro fases principais:
Fase 1: Pesquisa e Planejamento Profundos
1.1 Entender o Design Moderno de MCP
Cobertura de API vs. Ferramentas de Fluxo de Trabalho: Equilibre a cobertura abrangente de endpoints de API com ferramentas especializadas de fluxo de trabalho. Ferramentas de fluxo de trabalho podem ser mais convenientes para tarefas específicas, enquanto a cobertura abrangente dá aos agentes flexibilidade para compor operações. O desempenho varia por cliente — alguns clientes se beneficiam da execução de código que combina ferramentas básicas, enquanto outros funcionam melhor com fluxos de trabalho de nível superior. Quando estiver em dúvida, priorize a cobertura abrangente da API.
Nomenclatura e Descoberta de Ferramentas:
Nomes de ferramentas claros e descritivos ajudam os agentes a encontrar rapidamente as ferramentas certas. Use prefixos consistentes (por exemplo, github_create_issue, github_list_repos) e nomenclatura orientada por ação.
Gerenciamento de Contexto: Os agentes se beneficiam de descrições concisas de ferramentas e da capacidade de filtrar/paginar resultados. Projete ferramentas que retornem dados focados e relevantes. Alguns clientes suportam execução de código, o que pode ajudar os agentes a filtrar e processar dados de forma eficiente.
Mensagens de Erro Acionáveis: As mensagens de erro devem orientar os agentes em direção a soluções com sugestões específicas e próximos passos.
1.2 Estudar a Documentação do Protocolo MCP
Navegue pela especificação MCP:
Comece pelo sitemap para encontrar páginas relevantes: https://modelcontextprotocol.io/sitemap.xml
Em seguida, busque páginas específicas com o sufixo .md para o formato markdown (por exemplo, https://modelcontextprotocol.io/specification/draft.md).
Páginas principais a serem revisadas:
- Visão geral e arquitetura da especificação
- Mecanismos de transporte (HTTP streamable, stdio)
- Definições de ferramentas, recursos e prompts
1.3 Estudar a Documentação do Framework
Stack recomendado:
- Linguagem: TypeScript (suporte SDK de alta qualidade e boa compatibilidade em muitos ambientes de execução, ex. MCPB. Além disso, modelos de IA são bons em gerar código TypeScript, beneficiando-se de seu amplo uso, tipagem estática e boas ferramentas de linting)
- Transporte: HTTP Streamable para servidores remotos, usando JSON sem estado (mais simples de escalar e manter, em oposição a sessões com estado e respostas em stream). stdio para servidores locais.
Carregue a documentação do framework:
- Práticas Recomendadas MCP: 📋 Ver Práticas Recomendadas - Diretrizes principais
Para TypeScript (recomendado):
- SDK TypeScript: Use WebFetch para carregar
https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md - ⚡ Guia TypeScript - Padrões e exemplos em TypeScript
Para Python:
- SDK Python: Use WebFetch para carregar
https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md - 🐍 Guia Python - Padrões e exemplos em Python
1.4 Planeje Sua Implementação
Entenda a API: Revise a documentação da API do serviço para identificar endpoints-chave, requisitos de autenticação e modelos de dados. Use pesquisa na web e WebFetch conforme necessário.
Seleção de Ferramentas: Priorize a cobertura abrangente da API. Liste os endpoints a serem implementados, começando pelas operações mais comuns.
Fase 2: Implementação
2.1 Configure a Estrutura do Projeto
Consulte os guias específicos de linguagem para configuração do projeto:
- ⚡ Guia TypeScript - Estrutura de projeto, package.json, tsconfig.json
- 🐍 Guia Python - Organização de módulos, dependências
2.2 Implemente a Infraestrutura Principal
Crie utilitários compartilhados:
- Cliente de API com autenticação
- Auxiliares de tratamento de erros
- Formatação de resposta (JSON/Markdown)
- Suporte a paginação
2.3 Implemente Ferramentas
Para cada ferramenta:
Esquema de Entrada:
- Use Zod (TypeScript) ou Pydantic (Python)
- Inclua restrições e descrições claras
- Adicione exemplos nas descrições dos campos
Esquema de Saída:
- Defina
outputSchemaquando possível para dados estruturados - Use
structuredContentnas respostas da ferramenta (recurso do SDK TypeScript) - Ajuda os clientes a entender e processar as saídas das ferramentas
Descrição da Ferramenta:
- Resumo conciso da funcionalidade
- Descrições dos parâmetros
- Esquema do tipo de retorno
Implementação:
- Async/await para operações de I/O
- Tratamento de erros adequado com mensagens acionáveis
- Suporte a paginação onde aplicável
- Retorne conteúdo de texto e dados estruturados ao usar SDKs modernos
Anotações:
readOnlyHint: verdadeiro/falsodestructiveHint: verdadeiro/falsoidempotentHint: verdadeiro/falsoopenWorldHint: verdadeiro/falso
Fase 3: Revisão e Teste
3.1 Qualidade do Código
Revise para:
- Nenhum código duplicado (princípio DRY)
- Tratamento de erros consistente
- Cobertura total de tipos
- Descrições claras das ferramentas
3.2 Build e Teste
TypeScript:
- Execute
npm run buildpara verificar a compilação - Teste com MCP Inspector:
npx @modelcontextprotocol/inspector
Python:
- Verifique a sintaxe:
python -m py_compile seu_servidor.py - Teste com MCP Inspector
Consulte os guias específicos de linguagem para abordagens de teste detalhadas e listas de verificação de qualidade.
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
Use avaliações para testar se LLMs podem usar efetivamente seu servidor MCP para responder 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 os 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 da Avaliação
Garanta que cada pergunta seja:
- Independente: Não dependente de outras perguntas
- Somente Leitura: Apenas operações não destrutivas são 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 esses recursos conforme necessário durante o desenvolvimento:
Documentação Principal do MCP (Carregue Primeiro)
- Protocolo MCP: Comece pelo sitemap em
https://modelcontextprotocol.io/sitemap.xml, depois busque páginas específicas com o sufixo.md - 📋 Práticas Recomendadas MCP - Diretrizes universais de MCP incluindo:
- Convenções de nomenclatura de servidores e ferramentas
- Diretrizes de formato de resposta (JSON vs Markdown)
- Melhores práticas de paginação
- Seleção de transporte (HTTP streamable vs stdio)
- Padrões de segurança e tratamento de erros
Documentação do SDK (Carregue Durante a Fase 1/2)
- SDK Python: Busque em
https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md - SDK TypeScript: Busque em
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 do servidor
- Exemplos de modelo 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 de 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 - Guia completo de criação de avaliações 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