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