name: mcp-builder
description: Princípios de construção de servidores MCP (Model Context Protocol). Design de ferramentas, padrões de recursos e melhores práticas.
allowed-tools: Read, Write, Edit, Glob, Grep
Construtor de MCP
Princípios para construção de servidores MCP.
1. Visão Geral do MCP
O que é MCP?
Model Context Protocol - um padrão para conectar sistemas de IA com ferramentas externas e fontes de dados.
Conceitos Centrais
| Conceito | Propósito |
|---|
| Ferramentas (Tools) | Funções que a IA pode chamar |
| Recursos (Resources) | Dados que a IA pode ler |
| Prompts | Templates de prompt pré-definidos |
2. Arquitetura do Servidor
Estrutura do Projeto
meu-servidor-mcp/
├── src/
│ └── index.ts # Entrada principal
├── package.json
└── tsconfig.json
Tipos de Transporte
| Tipo | Uso |
|---|
| Stdio | Local, baseado em CLI |
| SSE | Baseado na web, streaming |
| WebSocket | Tempo real, bidirecional |
3. Princípios de Design de Ferramentas
Bom Design de Ferramenta
| Princípio | Descrição |
|---|
| Nome claro | Orientado à ação (get_weather, create_user) |
| Propósito único | Faz uma coisa bem feita |
| Entrada validada | Schema com tipos e descrições |
| Saída estruturada | Formato de resposta previsível |
Design de Schema de Entrada
| Campo | Obrigatório? |
|---|
| Tipo (Type) | Sim - object |
| Propriedades | Define cada parâmetro |
| Obrigatório | Lista parâmetros mandatórios |
| Descrição | Legível para humanos |
4. Padrões de Recursos
Tipos de Recurso
| Tipo | Uso |
|---|
| Estático | Dados fixos (config, docs) |
| Dinâmico | Gerado sob demanda |
| Template | URI com parâmetros |
Padrões de URI
| Padrão | Exemplo |
|---|
| Fixo | docs://readme |
| Parametrizado | users://{userId} |
| Coleção | files://projeto/* |
5. Tratamento de Erros
Tipos de Erro
| Situação | Resposta |
|---|
| Parâmetros inválidos | Mensagem de erro de validação |
| Não encontrado | Mensagem clara de "não encontrado" |
| Erro do servidor | Erro genérico, logar detalhes |
Melhores Práticas
- Retorne erros estruturados.
- Não exponha detalhes internos.
- Logue para fins de depuração.
- Forneça mensagens acionáveis.
6. Tratamento Multimodal
Tipos Suportados
| Tipo | Codificação |
|---|
| Texto | Texto simples (Plain text) |
| Imagens | Base64 + tipo MIME |
| Arquivos | Base64 + tipo MIME |
7. Princípios de Segurança
Validação de Entrada
- Valide todas as entradas de ferramentas.
- Higienize (sanitize) os dados fornecidos pelo usuário.
- Limite o acesso aos recursos.
Chaves de API
- Use variáveis de ambiente.
- Não logue segredos.
- Valide permissões.
8. Configuração
Configuração do Claude Desktop
| Campo | Propósito |
|---|
| command | Executável a ser rodado |
| args | Argumentos do comando |
| env | Variáveis de ambiente |
9. Testes
Categorias de Teste
| Tipo | Foco |
|---|
| Unitário | Lógica da ferramenta |
| Integração | Servidor completo |
| Contrato | Validação de schema |
10. Checklist de Melhores Práticas
Lembre-se: As ferramentas MCP devem ser simples, focadas e bem documentadas. A IA depende das descrições para usá-las corretamente.