lucasfdigital/mcp-builder

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

• [ ] Nomes de ferramentas claros e orientados à ação.
• [ ] Schemas de entrada completos com descrições.
• [ ] Saída JSON estruturada.
• [ ] Tratamento de erros para todos os casos.
• [ ] Validação de entradas.
• [ ] Configuração baseada em ambiente.
• [ ] Logging para depuração.

---

Lembre-se: As ferramentas MCP devem ser simples, focadas e bem documentadas. A IA depende das descrições para usá-las corretamente.