MCP Builder

Guia de Desenvolvimento de Servidor MCP

Visão Geral

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.

Processo

🚀 Fluxo de Trabalho de Alto Nível

Criar um servidor MCP de alta qualidade envolve quatro fases principais:

Fase 1: Pesquisa Profunda e Planejamento

1.1 Entender 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 oferece 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 em dúvida, priorize a cobertura abrangente de API.

Nomenclatura e Descoberta de Ferramentas: Nomes de ferramentas claros e descritivos ajudam agentes a encontrar a ferramenta certa rapidamente. Use prefixos consistentes (ex: github_create_issue, github_list_repos) e nomenclatura orientada por ação.

Gerenciamento de Contexto: 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 agentes a filtrar e processar dados eficientemente.

Mensagens de Erro Acionáveis: Mensagens de erro devem orientar 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 do MCP:

Comece com o mapa do site para encontrar páginas relevantes: https://modelcontextprotocol.io/sitemap.xml

Em seguida, busque páginas específicas com sufixo .md para formato markdown (ex: https://modelcontextprotocol.io/specification/draft.md).

Páginas-chave a revisar:

• Visão geral da especificação e arquitetura
• Mecanismos de transporte (HTTP streaming, stdio)
• Definições de tool, resource e prompt

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, se beneficiando de seu uso amplo, tipagem estática e boas ferramentas de linting)
• Transporte: HTTP streaming para servidores remotos, usando JSON sem estado (mais simples de escalar e manter, em oposição a sessões com estado e respostas em streaming). stdio para servidores locais.

Carregue a documentação do framework:

• Melhores Práticas de MCP: 📋 Ver Melhores Práticas - Diretrizes principais

Para TypeScript (recomendado):

• TypeScript SDK: Use WebFetch para carregar https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
• ⚡ Guia TypeScript - Padrões e exemplos de TypeScript

Para Python:

• Python SDK: Use WebFetch para carregar https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
• 🐍 Guia Python - Padrões e exemplos de Python

1.4 Planejar Sua Implementação

Entender a API: Revise a documentação da API do serviço para identificar endpoints-chave, requisitos de autenticação e modelos de dados. Use busca na web e WebFetch conforme necessário.

Seleção de Ferramentas: Priorize cobertura abrangente de API. Liste endpoints a implementar, começando pelas operações mais comuns.

Fase 2: Implementação

2.1 Configurar Estrutura do Projeto

Veja guias específicos da 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 Implementar Infraestrutura Principal

Crie utilitários compartilhados:

• Cliente de API com autenticação
• Helpers de tratamento de erros
• Formatação de resposta (JSON/Markdown)
• Suporte a paginação

2.3 Implementar Ferramentas

Para cada ferramenta:

Input Schema:

• Use Zod (TypeScript) ou Pydantic (Python)
• Inclua restrições e descrições claras
• Adicione exemplos nas descrições de campos

Output Schema:

• Defina outputSchema quando possível para dados estruturados
• Use structuredContent em respostas de ferramentas (feature do TypeScript SDK)
• Ajuda clientes a entender e processar saídas de ferramentas

Descrição da Ferramenta:

• Resumo conciso da funcionalidade
• Descrições de parâmetros
• Schema de tipo de retorno

Implementação:

• Async/await para operações de I/O
• Tratamento adequado de erros com mensagens acionáveis
• Suporte a paginação quando aplicável
• Retorne conteúdo em texto e dados estruturados quando 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 para:

• Sem código duplicado (princípio DRY)
• Tratamento de erro consistente
• Cobertura de tipo completa
• Descrições de ferramentas claras

3.2 Build e Teste

TypeScript:

• Execute npm run build para verificar compilação
• Teste com MCP Inspector: npx @modelcontextprotocol/inspector

Python:

• Verifique sintaxe: python -m py_compile your_server.py
• Teste com MCP Inspector

Veja guias específicos da linguagem para abordagens de teste detalhadas e checklists de qualidade.

Fase 4: Criar Avaliações

Após implementar seu servidor MCP, crie avaliações abrangentes para testar sua efetividade.

Carregue ✅ Guia de Avaliação para diretrizes completas de avaliação.

4.1 Entender 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 Criar 10 Questões de Avaliação

Para criar avaliações efetivas, siga o processo descrito no guia de avaliação:

1. Inspeção de Ferramentas: Liste ferramentas disponíveis e entenda suas capacidades
2. Exploração de Conteúdo: Use operações SOMENTE LEITURA para explorar dados disponíveis
3. Geração de Questões: Crie 10 questões complexas e realistas
4. Verificação de Respostas: Resolva cada questão você mesmo para verificar respostas

4.3 Requisitos de Avaliação

Garanta que cada questão seja:

• Independente: Não dependente de outras questões
• Somente leitura: Apenas operações não-destrutivas necessárias
• Complexa: Requerendo múltiplas chamadas de ferramentas e exploração profunda
• Realista: Baseada em casos de uso reais que pessoas se importariam
• Verificável: Resposta única e clara que pode ser verificada por comparação de string
• Estável: A resposta não mudará ao longo do tempo

4.4 Formato de Saída

Crie um arquivo XML com esta estrutura:

<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 Principal de MCP (Carregue Primeiro)

• Protocolo MCP: Comece com mapa do site em https://modelcontextprotocol.io/sitemap.xml, depois busque páginas específicas com sufixo .md
• 📋 Melhores Práticas de MCP - Diretrizes MCP universais incluindo:
  • Convenções de nomenclatura para servidor e ferramenta
  • Diretrizes de formato de resposta (JSON vs Markdown)
  • Melhores práticas de paginação
  • Seleção de transporte (HTTP streaming vs stdio)
  • Padrões de segurança e tratamento de erros

Documentação SDK (Carregue Durante Fase 1/2)

• Python SDK: Busque de https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
• TypeScript SDK: Busque de https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md

Guias de Implementação Específicos da Linguagem (Carregue Durante 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 ferramenta com @mcp.tool
  • Exemplos funcionais completos
  • Checklist de qualidade

• ⚡ Guia de Implementação TypeScript - Guia TypeScript completo com:

  • Estrutura de projeto
  • Padrões de schema Zod
  • Registro de ferramenta com server.registerTool
  • Exemplos funcionais completos
  • Checklist de qualidade

Guia de Avaliação (Carregue Durante Fase 4)

• ✅ Guia de Avaliação - Guia completo de criação de avaliação com:
  • Diretrizes de criação de questões
  • Estratégias de verificação de respostas
  • Especificações de formato XML
  • Exemplos de questões e respostas
  • Executando uma avaliação com scripts fornecidos