MCP server para dados de comercio exterior do Brasil (Comex Stat / Receita Federal) — com as armadilhas do dataset verificadas e corrigidas na resposta
Four well-defined tools with complete input schemas and detailed descriptions in Portuguese. All tools have proper enum constraints and parameter descriptions. However, output schemas are not documented in the visible code, and error handling guidance is minimal. Tool names follow verb_noun pattern (comex_*) but lack action verbs (get_, list_, search_). Descriptions are comprehensive (150-250 chars) and domain-specific, exceeding baseline quality. No security issues detected (read-only operations, no secrets in params). Composition is clean, each tool has a single responsibility.
Defeitos conhecidos do dataset do Comex Stat, cada um com evidencia quantificada, regra de correcao e procedencia da verificacao. Use ANTES de publicar qualquer numero derivado desta fonte — inclui o checklist de conferencia. Esta tool responde a pergunta que um wrapper de dados nunca responde: este campo quer dizer o que parece?
Frete e seguro DECLARADOS a aduana, por canal de transporte — em US$/kg e como % do valor FOB. Vem dos campos VL_FRETE e VL_SEGURO dos arquivos de importacao, que os resumos publicados descartam: e a melhor medida sistematica de custo realizado disponivel publicamente. Somente importacao (os arquivos de exportacao nao trazem frete). O canal 'air' ja esta corrigido pelo ponto de despacho.
Resolve codigos oficiais para nomes e vice-versa: pais, NCM, modal de transporte (VIA) e unidade da Receita de despacho (URF, com sua classificacao aeroporto/porto/outra). Necessario porque o dataset e todo codificado.
Fluxo de comercio exterior do Brasil (valor, peso e densidade de valor) a partir dos microdados aduaneiros oficiais do Comex Stat. Filtra por ano, mes, pais, NCM e canal de transporte, e agrupa como pedido. O canal 'air' JA vem corrigido pelo ponto de despacho — o campo de modal do dataset e contaminado e nao pode ser usado cru. A resposta inclui sempre os caveats aplicaveis e a procedencia dos arquivos.
Tool names lack action verbs. 'comex_trade_flow' and 'comex_freight_cost' do not start with get_, list_, search_, or similar. LLMs infer intent from verb-first naming; these names require reading descriptions to disambiguate.
Output schemas not documented in visible code. Tool descriptions mention what is returned (e.g., 'valor, peso e densidade de valor') but formal JSON Schema for response objects is absent. LLMs cannot plan downstream operations without knowing response structure.
No error handling guidance in tool descriptions. Tools do not document what errors are possible, whether they are retryable, or what the LLM should do if a query returns no results. E.g., 'comex_resolve_code' with an invalid 'kind' enum value.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 57 | 2026-07-28+ | v2 |
Parameter 'limit' in comex_trade_flow and comex_resolve_code lacks explicit min/max bounds in descriptions. Rubric baseline requires 'page_size 1 - 100' style constraints. Current text 'default 50, max 500' is present but not in parameter description itself.
No pagination or result-limiting guidance for comex_freight_cost. Tool accepts years/months/countries/ncm filters but does not document max result count or whether results are paginated. Large result sets could exhaust context window.