Princípios de construção de servidores MCP (Model Context Protocol). Design de ferramentas, padrões de recursos e melhores práticas.
Princípios para construção de servidores MCP.
Model Context Protocol - um padrão para conectar sistemas de IA com ferramentas externas e fontes de dados.
| 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 |
meu-servidor-mcp/
├── src/
│ └── index.ts # Entrada principal
├── package.json
└── tsconfig.json
| Tipo | Uso |
|---|---|
| Stdio | Local, baseado em CLI |
| SSE | Baseado na web, streaming |
| WebSocket | Tempo real, bidirecional |
| 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 |
| 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 |
| Tipo | Uso |
|---|---|
| Estático | Dados fixos (config, docs) |
| Dinâmico | Gerado sob demanda |
| Template | URI com parâmetros |
| Padrão | Exemplo |
|---|---|
| Fixo | docs://readme |
| Parametrizado | users://{userId} |
| Coleção | files://projeto/* |
| 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 |
| Tipo | Codificação |
|---|---|
| Texto | Texto simples (Plain text) |
| Imagens | Base64 + tipo MIME |
| Arquivos | Base64 + tipo MIME |
| Campo | Propósito |
|---|---|
| command | Executável a ser rodado |
| args | Argumentos do comando |
| env | Variáveis de ambiente |
| Tipo | Foco |
|---|---|
| Unitário | Lógica da ferramenta |
| Integração | Servidor completo |
| Contrato | Validação de schema |
Lembre-se: As ferramentas MCP devem ser simples, focadas e bem documentadas. A IA depende das descrições para usá-las corretamente.