Read/Write Split Captura Erro Null-Pointer em Servidor MCP GraphQL do Lambda

A equipe executa nove ferramentas MCP estreitamente escopo com um modelo de mutação deny-by-default. A arquitetura capturou uma falha crítica de produção que testes unitários não conseguiram: um erro null-pointer em Lambda no resolver create_collection.

O servidor MCP executa em Go usando a biblioteca mcp-go e se comunica com AWS AppSync via GraphQL. Autenticação usa bearer tokens OIDC—short-lived e scoped por usuário, impostos via diretiva @aws_oidc do AppSync. Chaves de API compartilhadas foram rejeitadas: toda requisição LLM carregaria acesso idêntico independentemente da identidade do chamador. OIDC preserva trail de auditoria e scoping de dados. O servidor também suporta assinatura AWS SigV4 e autenticação por chave de API como fallbacks. O método ativo é logado na inicialização: level=INFO msg=starting mcp-server auth=oidc mutations=false tools=8 resources=2 prompts=2.

Seis ferramentas somente-leitura cobrem search_companies (busca por palavra-chave com filtro de país, máx 100 resultados), get_company, get_companies_batch (deduplicação, máx 50 IDs), ai_search (linguagem natural com limite 5 requisições por minuto), list_collections, e get_collection_items. Três ferramentas de mutação—create_collection, add_to_collection, e request_email_discovery—são porteiras por uma flag CLI --allow-mutations que padrão é false. Apenas oito de nove ferramentas foram ativadas. Testes de integração expuseram o erro null-pointer no resolver backend de create_collection. A ferramenta não tem sinal de teste unitário para esta falha e foi comentada do caminho de registro. O log de inicialização reportando tools=8 em vez de 9 foi o sinal imediato do bloqueio de deployment.

O portão de mutação vive no nível do construtor de registro. Cada ferramenta de mutação armazena o booleano allowMutations e verifica na entrada Execute antes de tocar GraphQL. Sem a flag, o erro aparece imediatamente: mutações desabilitadas; use a flag --allow-mutations para habilitar operações de escrita. O cliente GraphQL nunca recebe a requisição. Separação read/write é imposta em código, não em convenção de nomes.

Testes usaram clientes GraphQL mockados via Testify Mock para lógica de ferramentas em nível unitário, depois validaram toda ferramenta contra o endpoint AppSync real através de MCP Inspector antes de conectar um cliente LLM. Capturar as variáveis GraphQL reais que o mock recebeu—não apenas a forma final de resposta—foi crítico. Esta abordagem capturou dois bugs pré-produção: uma falha de normalização de código de país (a ferramenta enviou US onde AppSync esperava countries;United States) e um limite faltante. Ambos os bugs passaram em assertivas de forma de saída limpo. Captura de variáveis revelou as entradas malformadas. Descoberta de email carrega um teto de taxa separado de 10 requisições por hora.

Três modos de falha merecem atenção. Primeiro, o erro null-pointer de create_collection falhou em toda chamada de integração contra o estágio de teste dev-team-a. Testes mockados verificam lógica de ferramentas mas não podem substituir validação de backend real. Segundo, chamadas bare de search_companies sem filtro de país ou categoria combinam o dataset inteiro de mais de um milhão de perfis e retornam páginas quase-aleatórias, acionando consultas de follow-up LLM que compõem a amplitude. A equipe limitou isso construindo filtros de categoria no contrato de ferramenta. Terceiro, a implementação atual não tem logging estruturado por requisição. Nome da ferramenta, latência, forma de entrada, e tipo de erro não são capturados como entradas de log independentes. Respostas de erro tipadas superficializam diagnósticos, mas telemetria de produção foi adiada como próximo passo.