O que Guia de Desenvolvimento de Servidor MCP faz?
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
A criação de um servidor MCP de alta qualidade envolve quatro fases principais:
Fase 1: Pesquisa e Planejamento Profundos
1.1 Entenda o Design Moderno de MCP
Cobertura de API vs. Ferramentas de Workflow: Equilibre a cobertura abrangente de endpoints de API com ferramentas de workflow especializadas. Ferramentas de workflow 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 workflows de nível superior. Quando estiver em dúvida, priorize a cobertura abrangente de API.
Nomeação e Descoberta de Ferramentas:
Nomes de ferramentas claros e descritivos ajudam os agentes a encontrar as ferramentas certas rapidamente. Use prefixos consistentes (por exemplo, github_create_issue, github_list_repos) e nomes orientados à ação.
Gerenciamento de Contexto: Os agentes se beneficiam de descrições concisas de ferramentas e da capacidade de filtrar/paginar resultados. Crie 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 guiar os agentes em direção a soluções com sugestões específicas e próximos passos.
1.2 Estude a Documentação do Protocolo MCP
Navegue pela especificação MCP:
Comece com o sitemap para encontrar páginas relevantes: https://modelcontextprotocol.io/sitemap.xml
Em seguida, busque páginas específicas com o sufixo .md para formato markdown (por exemplo, https://modelcontextprotocol.io/specification/draft.md).
Páginas principais a revisar:
- Visão geral da especificação e arquitetura
- Mecanismos de transporte (streamable HTTP, stdio)
- Definições de ferramenta, recurso e prompt
1.3 Estude a Documentação do Framework
Stack recomendada:
- Linguagem: TypeScript (suporte SDK de alta qualidade e boa compatibilidade em muitos ambientes de execução, como MCPB. Além disso, os 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: Streamable HTTP para servidores remotos, usando JSON sem estado (mais simples de escalar e manter, ao contrário de sessões stateful e respostas em streaming). stdio para servidores locais.
Carregue a documentação do framework:
- Melhores Práticas MCP: 📋 Ver Melhores Práticas - 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 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 Python
1.4 Planeje Sua Implementação
Entenda a API: Revise a documentação da API do serviço para identificar endpoints principais, requisitos de autenticação e modelos de dados. Use pesquisa 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 do 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 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 da ferramenta
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 quando aplicável
- Retorne tanto conteúdo de texto quanto 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 Compile e Teste
TypeScript:
- Execute
npm run buildpara verificar a compilação - Teste com o MCP Inspector:
npx @modelcontextprotocol/inspector
Python:
- Verifique a sintaxe:
python -m py_compile your_server.py - Teste com o 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 o ✅ 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 os LLMs podem usar efetivamente seu servidor MCP para responder a perguntas complexas e realistas.
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 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: A resposta não mudará 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 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 Principal do MCP (Carregue Primeiro)
- Protocolo MCP: Comece com o sitemap em
https://modelcontextprotocol.io/sitemap.xml, em seguida, busque páginas específicas com o sufixo.md - 📋 Melhores Práticas MCP - Diretrizes universais de MCP, incluindo:
- Convenções de nomenclatura de servidor e ferramenta
- Diretrizes de formato de resposta (JSON vs Markdown)
- Melhores práticas de paginação
- Seleção de transporte (streamable HTTP vs stdio)
- Padrões de segurança e tratamento de erros
Documentação do SDK (Carregue Durante a Fase 1/2)
- SDK Python: Buscar de
https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md - SDK TypeScript: Buscar de
https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
Guias de Implementação Específicos por 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 completos funcionais
- 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 completos funcionais
- 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çã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
- Execução de uma avaliação com os scripts fornecidos