Guia para criar servidores MCP (Model Context Protocol) de alta qualidade que permitem que LLMs interajam com serviços externos através de ferramentas bem projetadas. Use ao construir servidores MCP para integrar APIs ou serviços externos, seja em Python (FastMCP) ou Node/TypeScript (MCP SDK).
Crie servidores MCP (Model Context Protocol) que permitam que LLMs interajam com serviços externos através de ferramentas bem projetadas. A qualidade de um servidor MCP é medida por quão bem ele permite que LLMs realizem tarefas do mundo real.
Criar um servidor MCP de alta qualidade envolve quatro fases principais:
Cobertura de API vs. Ferramentas de Fluxo de Trabalho: Equilibre a cobertura abrangente de endpoint de API com ferramentas de fluxo de trabalho especializadas. 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 de acordo com o 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 incerto, priorize a cobertura abrangente da API.
Nomeação de Ferramentas e Descoberta:
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 nomenclatura orientada para 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 guiar os agentes em direção a soluções com sugestões e próximos passos específicos.
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 sufixo .md para formato markdown (por exemplo, https://modelcontextprotocol.io/specification/draft.md).
Páginas principais para revisar:
Stack recomendada:
Carregar documentação do framework:
Para TypeScript (recomendado):
https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.mdPara Python:
https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.mdEntenda a API: Revise a documentação da API do serviço para identificar pontos de extremidade 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 pontos de extremidade a serem implementados, começando com as operações mais comuns.
Veja os guias específicos da linguagem para configuração do projeto:
Crie utilitários compartilhados:
Para cada ferramenta:
Esquema de Entrada:
Esquema de Saída:
outputSchema sempre que possível para dados estruturadosstructuredContent nas respostas da ferramenta (recurso TypeScript SDK)Descrição da Ferramenta:
Implementação:
Anotações:
readOnlyHint: true/falsedestructiveHint: true/falseidempotentHint: true/falseopenWorldHint: true/falseRevise para:
TypeScript:
npm run build para verificar a compilaçãonpx @modelcontextprotocol/inspectorPython:
python -m py_compile your_server.pyVeja os guias específicos da linguagem para abordagens de teste detalhadas e listas de verificação de qualidade.
Após implementar seu servidor MCP, crie avaliações abrangentes para testar sua eficácia.
Carregue ✅ Guia de Avaliação para diretrizes de avaliação completas.
Use avaliações para testar se os LLMs podem usar efetivamente seu servidor MCP para responder a perguntas realistas e complexas.
Para criar avaliações eficazes, siga o processo descrito no guia de avaliação:
Certifique-se de que cada pergunta seja:
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 malhado?</question>
<answer>3</answer>
</qa_pair>
<!-- Mais qa_pairs... -->
</evaluation>
Carregue esses recursos conforme necessário durante o desenvolvimento:
https://modelcontextprotocol.io/sitemap.xml, depois busque páginas específicas com sufixo .mdhttps://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.mdhttps://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md🐍 Guia de Implementação Python - Guia completo Python/FastMCP com:
@mcp.tool⚡ Guia de Implementação TypeScript - Guia completo TypeScript com:
server.registerTool