Communitygithub.com

ASoudy/AGS

Guia para criar servidores MCP (Model Context Protocol) de alta qualidade que permitem LLMs interagirem 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 é AGS?

Este guia fornece um processo abrangente para o desenvolvimento de servidores MCP (Model Context Protocol) eficazes, capacitando LLMs a interagir com APIs e serviços externos. O foco está em equilibrar cobertura de API com ferramentas de alto nível, nomes de ferramentas descritivos, gerenciamento de contexto e mensagens de erro acionáveis. A implementação recomendada usa TypeScript com o SDK oficial MCP, mas o guia também cobre Python. O processo é dividido em quatro fases: pesquisa e planejamento, implementação (configuração do projeto, criação de ferramentas com esquemas de entrada/saída), revisão e teste (qualidade do código, uso do MCP Inspector) e criação de avaliações (10 perguntas complexas em formato XML). O guia inclui referências a documentações como práticas recomendadas do MCP, guias de implementação específicos para cada linguagem e um guia de avaliação. O público-alvo são desenvolvedores que desejam construir integrações MCP robustas com boa experiência do desenvolvedor (SDK TypeScript, Python) e capacidade de teste.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ASoudy/AGS/tree/HEAD/claude_skills_libraries/landing-page-mastery/skills/mcp-builder

Perguntar na sua IA favorita

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

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 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 e Planejamento Aprofundados

1.1 Entenda o Design Moderno de MCP

Cobertura de API vs. Ferramentas de Fluxo de Trabalho: Equilibre cobertura abrangente de endpoints 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 conforme 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 em dúvida, priorize a cobertura abrangente da API.

Nomenclatura 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 nomenclatura orientada à 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 os agentes a filtrar e processar dados de forma eficiente.

Mensagens de Erro Acionáveis: 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 mapa do site para encontrar páginas relevantes: https://modelcontextprotocol.io/sitemap.xml

Depois, busque páginas específicas com o sufixo .md para formato markdown (por exemplo, https://modelcontextprotocol.io/specification/draft.md).

Principais páginas para revisar:

  • Visão geral da especificação e arquitetura
  • Mecanismos de transporte (HTTP streamable, stdio)
  • Definições de ferramenta, recurso e prompt

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, 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, em oposição a sessões com estado e respostas em streaming). stdio para servidores locais.

Carregue a documentação do framework:

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

2.2 Implemente a Infraestrutura Principal

Crie utilitários compartilhados:

  • Cliente de 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 outputSchema quando possível para dados estruturados
  • Use structuredContent nas 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 adequado de erros 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/falso
  • destructiveHint: verdadeiro/falso
  • idempotentHint: verdadeiro/falso
  • openWorldHint: 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 build para verificar a compilação
  • Teste com MCP Inspector: npx @modelcontextprotocol/inspector

Python:

  • Verifique a sintaxe: python -m py_compile seu_servidor.py
  • Teste com 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 ✅ 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 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 de Ferramentas: Liste as ferramentas disponíveis e entenda suas capacidades
  2. Exploração de 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 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: Apenas operações não destrutivas são necessárias
  • Complexa: Exigindo 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 ao longo do 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 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 pelo mapa do site em https://modelcontextprotocol.io/sitemap.xml, depois busque páginas específicas com o sufixo .md
  • 📋 Melhores Práticas MCP - Diretrizes universais 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)

  • SDK Python: Busque de https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
  • SDK TypeScript: Busque 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 modelos Pydantic
    • Registro de ferramentas com @mcp.tool
    • Exemplos funcionais completos
    • 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 funcionais completos
    • 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çõ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 20 individual skills — each has its own dedicated page.

ASoudy/AGS

Advanced JavaScript animation library skill for creating complex, high-performance web animations.

ASoudy/AGS

Astropy is the core Python package for astronomy, providing essential functionality for astronomical research and data analysis.

ASoudy/AGS

Build content-focused websites with Astro — zero JS by default, islands architecture, multi-framework components, and Markdown/MDX support.

ASoudy/AGS

One sentence - what this skill does and when to invoke it

ASoudy/AGS

Audit and fix animation performance issues including layout thrashing, compositor properties, scroll-linked motion, and blur effects. Use when animations stutter, transitions jank, or reviewing CSS/JS animation performance.

ASoudy/AGS

Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support.

ASoudy/AGS

Pull a YouTube video transcript into a queryable markdown vault with yt-dlp subtitle discovery, VTT cleanup, metadata frontmatter, and capture-seed stubs.

ASoudy/AGS

Expert in building portfolios that actually land jobs and clients - not just showing work, but creating memorable experiences. Covers developer portfolios, designer portfolios, creative portfolios, and portfolios that convert visitors into opportunities.

ASoudy/AGS

Generates high-converting Next.js/React landing pages with Tailwind CSS. Uses PAS, AIDA, and BAB frameworks for optimized copy/components (Heroes, Features, Pricing). Focuses on Core Web Vitals/SEO.

ASoudy/AGS

AI-powered animation tool for creating motion in logos, UI, icons, and social media assets.

ASoudy/AGS

CRITICAL: Use for Makepad animation system. Triggers on: makepad animation, makepad animator, makepad hover, makepad state, makepad transition, "from: { all: Forward", makepad pressed, makepad 动画, makepad 状态, makepad 过渡, makepad 悬停效果

ASoudy/AGS

Comprehensive patterns for Next.js 14+ App Router architecture, Server Components, and modern full-stack React development.

ASoudy/AGS

Next.js App Router principles. Server Components, data fetching, routing patterns.

ASoudy/AGS

Expert integration of Supabase Auth with Next.js App Router

ASoudy/AGS

React and Next.js 14+ application development with App Router, Server Components, TypeScript, Tailwind CSS, and modern frontend patterns.

ASoudy/AGS

Best practices for Remotion - Video creation in React

ASoudy/AGS

Generate walkthrough videos from Stitch projects using Remotion with smooth transitions, zooming, and text overlays

ASoudy/AGS

Seek and analyze video content using Memories.ai Large Visual Memory Model for persistent video intelligence

ASoudy/AGS

Writes complete, structured landing pages optimized for SEO ranking, AEO citation, and visitor conversion. Activate when the user wants to write or generate a landing page for a product, service, or offer.

ASoudy/AGS

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

Habilidades Relacionadas