CommunityProgramação e Desenvolvimentogithub.com

mcp-builder

Guia para criar servidores MCP (Model Context Protocol) de alta qualidade, permitindo 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 Node/TypeScript (MCP SDK).

O que é mcp-builder?

Este guia fornece uma abordagem estruturada em quatro fases para criar servidores MCP (Model Context Protocol) de alta qualidade, essenciais para conectar modelos de linguagem a serviços externos. A primeira fase foca em pesquisa e planejamento, incluindo o entendimento de design moderno de MCP (cobertura de API vs. ferramentas de workflow, nomenclatura, gerenciamento de contexto e mensagens de erro acionáveis), estudo da especificação do protocolo MCP e da documentação dos SDKs recomendados (TypeScript SDK v2 ou Python/FastMCP). A segunda fase abrange a implementação prática: configuração do projeto, criação de infraestrutura central (cliente de API, tratamento de erros, formatação) e implementação de ferramentas com esquemas de entrada (Zod/Pydantic), saída estruturada e anotações. O guia também recomenda TypeScript (SDK v2) para novos servidores, mas oferece suporte completo para Python. As fases finais incluem revisão de qualidade e testes com MCP Inspector, além da criação de avaliações abrangentes com 10 perguntas realistas e complexas para validar a eficácia do servidor. O guia se aplica a plataformas como Claude Code, Cursor e Codex, enfatizando boas práticas como nomenclatura consistente, mensagens de erro acionáveis e design focado na capacidade do LLM de realizar tarefas do mundo real.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/anthropics/skills/tree/main/skills/mcp-builder

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Ver original→Navegar por todas as habilidades

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

Documentação

Guia de Desenvolvimento de Servidores 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 pela sua capacidade de 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 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 nomeação orientada a 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 oferecem suporte à 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 pelo 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-chave para revisar:

  • Visão geral da especificação e arquitetura
  • Mecanismos de transporte (HTTP streamable, stdio)
  • Definições de ferramentas, recursos e prompts

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, modelos de IA são bons em gerar código TypeScript, beneficiando-se de seu uso amplo, tipagem estática e boas ferramentas de linting)
  • Transporte: HTTP streamable para servidores remotos, usando JSON sem estado (mais simples de escalar e manter, ao contrário de sessões com estado e respostas de streaming). stdio para servidores locais.

Carregue a documentação do framework:

Para TypeScript (recomendado):

O SDK TypeScript tem duas versões principais. Escolha uma antes de escrever código:

  • v2 (@modelcontextprotocol/server): a versão estável atual. Use para novos servidores.
  • v1 (@modelcontextprotocol/sdk): recebe apenas correções de bugs e segurança. Use apenas quando o package.json do projeto já depender de @modelcontextprotocol/sdk, ou migre esse projeto com npx @modelcontextprotocol/codemod@latest v1-to-v2 .

Se o projeto já usar v1, informe o usuário uma vez, em uma ou duas frases, que v2 (@modelcontextprotocol/server) é a versão estável atual, que v1 recebe apenas correções de bugs e segurança, e que npx @modelcontextprotocol/codemod@latest v1-to-v2 . migra o projeto. Em seguida, continue com v1, a menos que o usuário peça para migrar.

Não misture as duas versões em um único projeto: exemplos de código v1 (importações de @modelcontextprotocol/sdk/...) não se aplicam ao v2.

  • TypeScript SDK (v2): Use WebFetch para carregar https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md; o índice completo da documentação é https://ts.sdk.modelcontextprotocol.io/v2/llms.txt
  • ⚡ Guia TypeScript (v2) - Padrões e exemplos TypeScript
  • Para projetos v1 apenas: https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/v1.x/README.md e o Guia TypeScript (v1)

Para Python:

  • Python SDK: 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-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 de API. Liste endpoints a serem implementados, começando pelas operações mais comuns.

Fase 2: Implementação

2.1 Configure a Estrutura do Projeto

Consulte guias específicos de linguagem para configuração do projeto:

2.2 Implemente a Infraestrutura Central

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 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 quando possível para dados estruturados
  • Use structuredContent nas respostas das ferramentas (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 quando aplicável
  • Retorne conteúdo de 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 Testes

3.1 Qualidade do Código

Revise para:

  • Sem código duplicado (princípio DRY)
  • Tratamento de erros consistente
  • Cobertura total de tipos
  • Descrições claras de ferramentas

3.2 Compile e Teste

TypeScript:

  • Execute npm run build para verificar a compilação
  • Projetos v2: execute o script de auto-verificação do guia v2 no servidor compilado
  • Teste com MCP Inspector: npx @modelcontextprotocol/inspector

Python:

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

Consulte 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:

  1. Inspeção de Ferramentas: Liste as 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 Perguntas: Crie 10 perguntas complexas e realistas
  4. Verificação de Respostas: Resolva cada pergunta você mesmo para verificar as respostas

4.3 Requisitos de Avaliação

Garanta que cada pergunta seja:

  • Independente: Não dependente de outras perguntas
  • Somente leitura: Requer apenas operações não destrutivas
  • Complexa: Exija múltiplas chamadas de ferramenta e exploração aprofundada
  • 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 nomeado após um gato selvagem pintado?</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 Central 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
  • 📋 Melhores Práticas de 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)

  • Python SDK: Busque de https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
  • TypeScript SDK (v2): Busque de https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md; índice completo da documentação em https://ts.sdk.modelcontextprotocol.io/v2/llms.txt
  • TypeScript SDK (v1, apenas projetos v1 existentes): Busque de https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/v1.x/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 de servidor
    • Exemplos de modelos Pydantic
    • Registro de ferramentas com @mcp.tool
    • Exemplos completos funcionais
    • Lista de verificação de qualidade

  • ⚡ Guia de Implementação TypeScript (SDK v2) - Guia completo TypeScript para @modelcontextprotocol/server com:

    • Configuração do projeto e a fábrica de servidores
    • Design de ferramentas: esquemas Zod 4, formatos de saída, paginação, erros
    • Um exemplo completo servindo stdio e HTTP streamable, mais autenticação bearer
    • Recursos, prompts e notificações
    • Um script de auto-verificação para testar o servidor compilado
    • Links para exemplos do SDK para funcionalidades avançadas
    • Uma tabela de tradução v1 → v2, passos de migração e uma lista de verificação de qualidade

  • ⚡ Guia de Implementação TypeScript (SDK v1) - O guia equivalente para projetos existentes com @modelcontextprotocol/sdk

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
    • Execução de uma avaliação com os scripts fornecidos

Individual skills in this repo

This repo contains 19 individual skills — each has its own dedicated page.

academy-guide

Stop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.

algorithmic-art

Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists

anthropics/template-skill

Replace with description of the skill and when Claude should use it.

brand-guidelines

Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.

canvas-design

Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists

claude-api

|-

discernment-nudge

After you give a substantive answer or draft that the user may act on — advice or recommendations, drafted artifacts such as goals, plans, pitches, proposals, or emails, estimates or projections, analysis or interpretation of data, factual claims they may rely on, or a multi-step argument — invoke this skill BEFORE finalizing your reply and then, if it applies, append 2-3 short follow-up questions, each tied to something specific in what you just produced, that help the user check key facts, probe the reasoning or assumptions, and notice missing context. Do this at most once per conversation. Skip it when the user asked a trivial how-to or simple lookup, wants a purely educational explanation, asked you only to format, convert, or assemble a file from content they provided, is writing code they will run, is doing creative writing or casual chat, or already asked you to double-check, cite, or review — the skill file explains these boundaries and the exact output format.

doc-coauthoring

Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.

docx

Use this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of

frontend-design

Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.

internal-comms

A set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. Claude should use this skill whenever asked to write some sort of internal communications (status reports, leadership updates, 3P updates, company newsletters, FAQs, incident reports, project updates, etc.).

pdf

Use this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.

pptx

Use this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions \

skill-creator

Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill

slack-gif-creator

Knowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like

theme-factory

Toolkit for styling artifacts with a theme. These artifacts can be slides, docs, reportings, HTML landing pages, etc. There are 10 pre-set themes with colors/fonts that you can apply to any artifact that has been creating, or can generate a new theme on-the-fly.

webapp-testing

Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.

web-artifacts-builder

Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.

xlsx

Use this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like \

Habilidades Relacionadas

steipete/bluebubbles

Send and manage iMessages via BlueBubbles, including attachments, tapbacks, edits, replies, and groups.

community

steipete/eightctl

Control Eight Sleep pods (status, temperature, alarms, schedules).

community

steipete/blucli

BluOS CLI (blu) for discovery, playback, grouping, and volume.

community

steipete/bear-notes

Create, search, and manage Bear notes via grizzly CLI.

community

steipete/camsnap

Capture frames or clips from RTSP/ONVIF cameras.

community

steipete/gifgrep

Search GIF providers with CLI/TUI, download results, and extract stills/sheets.

community
← More Programação e Desenvolvimento skills