Desenvolvedor de Ferramentas MCP

Visão Geral

Especialista na construção de servidores do Protocolo de Contexto de Modelo (MCP) que oferecem novas capacidades aos agentes de IA. Abrange todo o ciclo de vida do desenvolvimento MCP: especificação, implementação, teste, implantação e publicação no registro. Suporta TypeScript e Python com padrões prontos para produção.

Esta habilidade entende os primitivos da especificação MCP (ferramentas, recursos, prompts, amostragem), opções de transporte (stdio, SSE, HTTP Streamable) e os padrões de design de ferramentas que tornam os servidores MCP confiáveis e compostos.

Quando Usar Esta Habilidade

• Use ao construir um novo servidor MCP do zero
• Use ao encapsular uma API existente como uma ferramenta MCP
• Use ao depurar problemas de servidor MCP
• Use ao projetar o esquema da ferramenta para um servidor MCP
• Use ao publicar um servidor MCP em um registro

Como Funciona

Passo 1: Definir o Escopo do Servidor MCP

Identifique quais capacidades o servidor deve expor:

• Ferramentas - Funções que o LLM pode chamar (caso de uso principal)
• Recursos - Dados que o LLM pode ler (arquivos, APIs, bancos de dados)
• Prompts - Modelos de prompt reutilizáveis

Escolha o transporte:

• stdio - Para ferramentas CLI locais (Claude Code, Cursor)
• SSE (Server-Sent Events) - Para ferramentas remotas/hospedadas
• HTTP Streamable - Novo na especificação MCP para implantações modernas

Passo 2: Projetar o Esquema da Ferramenta

Defina os esquemas de entrada/saída antes de escrever a implementação:

{
  name: "tool_name",
  description: "What this tool does (visible to the LLM)",
  inputSchema: {
    type: "object",
    properties: { ... },
    required: [ ... ]
  }
}

Passo 3: Implementar o Servidor

Crie o servidor com tratamento de erros adequado, validação e logging. Use o SDK oficial do MCP para TypeScript (@modelcontextprotocol/sdk) ou Python (mcp).

Passo 4: Testar e Implantar

Teste com o MCP Inspector, valide os esquemas das ferramentas, trate casos extremos e, em seguida, implante localmente ou remotamente.

Exemplos

Exemplo 1: Servidor MCP TypeScript

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "my-tools", version: "1.0.0" });

server.tool("greet", "Greet someone by name",
  { name: z.string().describe("Person's name") },
  async ({ name }) => ({ content: [{ type: "text", text: `Hello, ${name}!` }] })
);

const transport = new StdioServerTransport();
await server.connect(transport);

Exemplo 2: Padrão de Wrapper de API

Encapsule uma API externa como uma ferramenta MCP com autenticação, limitação de taxa e tratamento de erros:

• Mapeie endpoints de API para ferramentas
• Lide com autenticação via variáveis de ambiente
• Transforme respostas de API em formato amigável para LLM
• Adicione lógica de retentativa com backoff exponencial

Melhores Práticas

• Construa ferramentas pequenas e focadas que possam ser encadeadas em vez de ferramentas monolíticas
• Retorne erros estruturados, não falhas - as ferramentas devem falhar graciosamente
• Defina esquemas antes da implementação
• Inclua descrições que ajudem o LLM a entender quando e como usar cada ferramenta
• Valide todas as entradas contra o esquema
• Adicione limitação de taxa para chamadas de API externas
• Use variáveis de ambiente para segredos, nunca codifique credenciais

Limitações

• Esta habilidade fornece orientação e geração de código; testes de tempo de execução reais exigem um ambiente de desenvolvimento
• A especificação MCP está em evolução; sempre verifique a versão mais recente da especificação
• A revisão de segurança é essencial antes de implantar ferramentas que lidam com dados sensíveis

Notas de Segurança e Proteção

• Nunca codifique chaves de API ou credenciais em implementações de ferramentas
• Use variáveis de ambiente ou gerenciadores de segredos para toda a autenticação
• Valide e sanitize todas as entradas para prevenir ataques de injeção
• Limite a taxa de chamadas de API externas para prevenir abusos
• Revise cuidadosamente as permissões das ferramentas - as ferramentas podem acessar arquivos, redes e executar código

Armadilhas Comuns

• Problema: LLM chama ferramentas com parâmetros errados Solução: Melhore as descrições das ferramentas e adicione exemplos no campo de descrição. O LLM lê as descrições para decidir como chamar as ferramentas.

• Problema: Ferramenta expira em entradas grandes Solução: Adicione validação de tamanho de entrada e paginação. Transmita respostas grandes em vez de armazená-las em buffer.

Habilidades Relacionadas

• api-integration-architect - Para padrões de design de API usados em ferramentas MCP
• security-audit-code-reviewer - Para revisar a segurança do código do servidor MCP