Communitygithub.com

agencelutie/LP-lutie

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 Node/TypeScript (MCP SDK).

O que é LP-lutie?

Este guia fornece uma abordagem abrangente e passo a passo para o desenvolvimento de servidores MCP (Model Context Protocol) de alta qualidade, que permitem que Grandes Modelos de Linguagem (LLMs) interajam com serviços externos através de ferramentas bem projetadas. Ele cobre desde o planejamento inicial, passando pela implementação em TypeScript ou Python, até a criação de avaliações para testar a eficácia do servidor. O guia enfatiza o equilíbrio entre a cobertura abrangente de endpoints de API e a criação de ferramentas de fluxo de trabalho especializadas, além de fornecer práticas recomendadas para nomenclatura, gerenciamento de contexto e mensagens de erro acionáveis. Projetado para plataformas como Claude Code, Cursor e Codex, o guia inclui referências detalhadas à documentação do protocolo MCP e SDKs específicos (TypeScript/MCP SDK e Python/FastMCP), bem como listas de verificação de qualidade e modelos de avaliação. O resultado é um processo estruturado que garante a criação de servidores MCP robustos, fáceis de usar e que maximizam a capacidade dos agentes de IA de realizar tarefas do mundo real.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/agencelutie/LP-lutie/tree/main/skills-export/examples/mcp-builder
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 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 e Planejamento Aprofundados

1.1 Entenda o Design Moderno de MCP

Cobertura de API vs. Ferramentas de Fluxo de Trabalho: Equilibre a 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 estiver em dúvida, priorize a cobertura abrangente de 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 ações.

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 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 principais a 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, ex. 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 de API. Liste os endpoints a implementar, 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 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 E/S
  • Tratamento de erros adequado com mensagens acionáveis
  • Suporte a paginação quando aplicável
  • Retorne tanto conteúdo textual quanto 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 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 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 se importariam
  • Verificável: Resposta única e clara que pode 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:

<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 em homenagem a 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 sitemap em https://modelcontextprotocol.io/sitemap.xml, depois busque páginas específicas com o sufixo .md
  • 📋 Melhores Práticas 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)

  • SDK Python: Busque em https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
  • SDK TypeScript: Busque em 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
    • Executando uma avaliação com os scripts fornecidos

Individual skills in this repo

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

agencelutie/LP-lutie

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' work to avoid copyright violations.

agencelutie/LP-lutie

Submit expense reimbursements through Benepass (app.getbenepass.com). For users whose employer uses Benepass as their benefits platform. Handles login, benefit selection, form filling, receipt upload, and submission. Requires browser/computer-use capabilities.

agencelutie/LP-lutie

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.

agencelutie/LP-lutie

Make a phone call to book an appointment or reservation. Checks calendar first, gets explicit consent before dialing, discloses AI identity on the call, and adds the booking to calendar when done.

agencelutie/LP-lutie

Cancel a subscription or unsubscribe from a service. Works from a description, a pasted charge line, a URL, or a photo/screenshot. Can also audit a full statement for recurring charges and cancel several at once. Finds the right contact method and handles the cancellation — including phone calls.

agencelutie/LP-lutie

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' work to avoid copyright violations.

agencelutie/LP-lutie

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.

agencelutie/LP-lutie

Help plan an event — from a birthday dinner to a wedding. Scales to the size of the occasion. Handles venue research, guest lists, timelines, vendors, and budgets.

agencelutie/LP-lutie

Help submit an expense or reimbursement on any platform. Detects the right tool (Benepass, Brex, Concur, Expensify, etc.), finds receipts, checks for duplicates, and walks through submission.

agencelutie/LP-lutie

Handle small bureaucratic tasks — jury duty responses, parking tickets, passport renewals, DMV forms, permit applications, and other government or administrative paperwork.

agencelutie/LP-lutie

Run financial calculations and scenario comparisons — tax estimates, loan comparisons, retirement projections, rent vs. buy, investment scenarios, and more. Pure math, no accounts or logins needed.

agencelutie/LP-lutie

Help order groceries for delivery. Concierge-style flow — store selection, occasion-based list building, budget tracking, and cart assembly.

agencelutie/LP-lutie

Help find and book a service provider for a task — cleaning, handyman, moving, assembly, yard work, errands, etc. Searches TaskRabbit, Handy, Thumbtack, and similar platforms.

agencelutie/LP-lutie

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.).

agencelutie/LP-lutie

Help order food timed to arrive at a specific time. Works backward from target arrival, suggests restaurants, builds cart, and monitors delivery.

agencelutie/LP-lutie

Refill a prescription at a pharmacy. Works from a medication name, an Rx number, a photo of the bottle, or just "I'm running low." Confirms exactly what's being requested, gathers everything the pharmacy will ask for up front, and handles the refill online or by phone — whichever is fastest.

agencelutie/LP-lutie

Help return an item or request a refund from any retailer. Identifies the item, finds the return policy, navigates the process, and handles shipping labels or phone calls.

agencelutie/LP-lutie

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.

agencelutie/LP-lutie

Landing page quality assessment for paid advertising campaigns. Evaluates message match, page speed, mobile experience, trust signals, form optimization, and conversion rate potential. Use when user says "landing page", "post-click experience", "landing page audit", "conversion rate", or "landing page optimization".

agencelutie/LP-lutie

Generate structured landing page copy with hero, body, proof, and CTA sections. Framework-agnostic - adapts approach based on awareness level and offer type.

Habilidades Relacionadas

steipete/sag

ElevenLabs text-to-speech with mac-style say UX.

community

steipete/oracle

Oracle CLI second-model review/debug/refactor/design with selected files, dry-run token checks, API or browser engine.

community

steipete/peekaboo

Capture and automate macOS UI with the Peekaboo CLI.

community

mattpocock/design-an-interface

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

community

mattpocock/prototype

Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.

community

mattpocock/grill-me

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

community