Skill
MCP Builder
Crédito: anthropics no GitHub (anthropics/skills) · 0 cópias
Indicada na UseIA por Cristiano Rochenbach Abreu em 5 de out. de 2026
179,8 mil estrelas no GitHubVer no GitHub
Tradução feita por IA. Em caso de dúvida, vale o texto original (aba “Original”).
---
name: mcp-builder
description: Guia para criar servidores MCP (Model Context Protocol) de alta qualidade, que permitem que LLMs interajam com serviços externos por meio de ferramentas bem projetadas. Use ao construir servidores MCP para integrar APIs ou serviços externos, seja em Python (FastMCP) ou em Node/TypeScript (MCP SDK).
license: Complete terms in LICENSE.txt
---
# Guia de desenvolvimento de servidores MCP
## Visão geral
Crie servidores MCP (Model Context Protocol) que permitam que LLMs interajam com serviços externos por meio de ferramentas bem projetadas. A qualidade de um servidor MCP é medida pela capacidade de ele permitir 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 aprofundada e planejamento
#### 1.1 Entenda o design moderno de MCP
**Cobertura da API vs. ferramentas de fluxo de trabalho:**
Equilibre a cobertura abrangente dos endpoints da API com ferramentas de fluxo de trabalho especializadas. As 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 conforme o cliente — alguns clientes se beneficiam de execução de código que combina ferramentas básicas, enquanto outros funcionam melhor com fluxos de trabalho de nível mais alto. Na dúvida, priorize a cobertura abrangente da API.
**Nomes de ferramentas e descobribilidade:**
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 nomes orientados à ação.
**Gerenciamento de contexto:**
Os agentes se beneficiam de descrições de ferramentas concisas e da capacidade de filtrar/paginar resultados. Projete ferramentas que retornem dados focados e relevantes. Alguns clientes oferecem suporte a execução de código, o que pode ajudar os agentes a filtrar e processar dados com eficiência.
**Mensagens de erro acionáveis:**
As mensagens de erro devem orientar os agentes rumo 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 do MCP:**
Comece pelo sitemap para encontrar as páginas relevantes: `https://modelcontextprotocol.io/sitemap.xml`
Depois busque páginas específicas com o sufixo `.md` para obter o formato markdown (por exemplo, `https://modelcontextprotocol.io/specification/draft.md`).
Páginas principais para revisar:
- Visão geral e arquitetura da especificação
- Mecanismos de transporte (streamable HTTP, stdio)
- Definições de ferramentas, recursos e prompts
#### 1.3 Estude a documentação do framework
**Stack recomendada:**
- **Linguagem**: TypeScript (suporte de SDK de alta qualidade e boa compatibilidade em muitos ambientes de execução, por exemplo o MCPB. Além disso, os modelos de IA são bons em gerar código TypeScript, beneficiando-se do uso amplo, da tipagem estática e das boas ferramentas de lint)
- **Transporte**: Streamable HTTP para servidores remotos, usando JSON sem estado (mais simples de escalar e manter, em contraste com sessões com estado e respostas em streaming). stdio para servidores locais.
**Carregue a documentação do framework:**
- **Boas práticas de MCP**: [📋 Ver boas práticas](./reference/mcp_best_practices.md) - Diretrizes centrais
**Para TypeScript (recomendado):**
- **SDK de TypeScript**: Use o WebFetch para carregar `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md`
- [⚡ Guia de TypeScript](./reference/node_mcp_server.md) - Padrões e exemplos em TypeScript
**Para Python:**
- **SDK de Python**: Use o WebFetch para carregar `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md`
- [🐍 Guia de Python](./reference/python_mcp_server.md) - 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 os endpoints principais, os requisitos de autenticação e os modelos de dados. Use busca na web e o WebFetch conforme necessário.
**Seleção de ferramentas:**
Priorize a cobertura abrangente da API. Liste os endpoints a implementar, começando pelas operações mais comuns.
---
### Fase 2: Implementação
#### 2.1 Configure a estrutura do projeto
Veja os guias específicos de cada linguagem para a configuração do projeto:
- [⚡ Guia de TypeScript](./reference/node_mcp_server.md) - Estrutura do projeto, package.json, tsconfig.json
- [🐍 Guia de Python](./reference/python_mcp_server.md) - Organização de módulos, dependências
#### 2.2 Implemente a infraestrutura central
Crie utilitários compartilhados:
- Cliente de API com autenticação
- Auxiliares de tratamento de erros
- Formatação de respostas (JSON/Markdown)
- Suporte a paginação
#### 2.3 Implemente as 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 `outputSchema` sempre que possível para dados estruturados
- Use `structuredContent` nas respostas das ferramentas (recurso do SDK de 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 quando aplicável
- Retorne conteúdo em texto e dados estruturados ao usar SDKs modernos
**Anotações:**
- `readOnlyHint`: true/false
- `destructiveHint`: true/false
- `idempotentHint`: true/false
- `openWorldHint`: true/false
---
### Fase 3: Revisão e teste
#### 3.1 Qualidade do código
Revise quanto a:
- Nenhum código duplicado (princípio DRY)
- Tratamento de erros consistente
- Cobertura completa de tipos
- Descrições de ferramentas claras
#### 3.2 Compile e teste
**TypeScript:**
- Execute `npm run build` para 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
Veja os guias específicos de cada linguagem para abordagens de teste detalhadas e checklists de qualidade.
---
### Fase 4: Crie avaliações
Depois de implementar seu servidor MCP, crie avaliações abrangentes para testar a sua eficácia.
**Carregue o [✅ Guia de avaliação](./reference/evaluation.md) para as diretrizes completas de avaliação.**
#### 4.1 Entenda a finalidade da avaliação
Use as avaliações para testar se os LLMs conseguem usar de forma eficaz o 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 das ferramentas**: Liste as ferramentas disponíveis e entenda suas capacidades
2. **Exploração do 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 das respostas**: Resolva cada pergunta você mesmo para verificar as respostas
#### 4.3 Requisitos da avaliação
Garanta que cada pergunta seja:
- **Independente**: Sem depender de outras perguntas
- **Somente leitura**: Exigindo apenas operações não destrutivas
- **Complexa**: Exigindo várias chamadas de ferramentas e exploração profunda
- **Realista**: Baseada em casos de uso reais com os quais as pessoas se importariam
- **Verificável**: Uma única resposta clara, que possa 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:
```xml
<evaluation>
<qa_pair>
<question>Find discussions about AI model launches with animal codenames. One model needed a specific safety designation that uses the format ASL-X. What number X was being determined for the model named after a spotted wild cat?</question>
<answer>3</answer>
</qa_pair>
<!-- More 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**: Comece pelo sitemap em `https://modelcontextprotocol.io/sitemap.xml` e depois busque páginas específicas com o sufixo `.md`
- [📋 Boas práticas de MCP](./reference/mcp_best_practices.md) - Diretrizes universais de MCP, incluindo:
- Convenções de nomes de servidores e ferramentas
- Diretrizes de formato de resposta (JSON vs Markdown)
- Boas práticas de paginação
- Seleção de transporte (streamable HTTP vs stdio)
- Padrões de segurança e de tratamento de erros
### Documentação dos SDKs (carregue durante as Fases 1/2)
- **SDK de Python**: Busque em `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md`
- **SDK de TypeScript**: Busque em `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md`
### Guias de implementação específicos de cada linguagem (carregue durante a Fase 2)
- [🐍 Guia de implementação em Python](./reference/python_mcp_server.md) - Guia completo de Python/FastMCP, com:
- Padrões de inicialização do servidor
- Exemplos de modelos Pydantic
- Registro de ferramentas com `@mcp.tool`
- Exemplos completos e funcionais
- Checklist de qualidade
- [⚡ Guia de implementação em TypeScript](./reference/node_mcp_server.md) - Guia completo de TypeScript, com:
- Estrutura do projeto
- Padrões de esquemas Zod
- Registro de ferramentas com `server.registerTool`
- Exemplos completos e funcionais
- Checklist de qualidade
### Guia de avaliação (carregue durante a Fase 4)
- [✅ Guia de avaliação](./reference/evaluation.md) - Guia completo de criação de avaliações, com:
- Diretrizes de criação de perguntas
- Estratégias de verificação de respostas
- Especificações do formato XML
- Exemplos de perguntas e respostas
- Como rodar uma avaliação com os scripts fornecidosFunciona com:Claude

