mcp-comex-brasil

브라질 대외무역 데이터용 MCP 서버 — 데이터셋의 함정을 응답에서 바로잡은 버전.

거짓말하지 않는 도구 네 개, 알지 못하는 도구 마흔 개 대신.

이 서버가 해결하는 문제

단지 데이터셋을 노출할 뿐인 MCP 서버는 에이전트에게 잘못된 숫자를 돌려주는 깔끔한 API를 건네줍니다. 내부 배관은 그 필드가 거짓말한다는 사실을 모릅니다.

Comex Stat — Secretaria de Comércio Exterior / Receita Federal이 발행하는 브라질 공식 대외무역 데이터베이스 — 에는 어떤 문서도 알려주지 않는 결함이 있습니다:

AÉREA로 운송 모드 필드를 필터링하면 2026년 1~7월 중국 수입 1억 3,960만 kg이 반환됩니다. 같은 레코드를 통관 지점과 교차 확인하면 단 3,400만 kg(24%)만 공항을 거쳤습니다. 나머지 8,970만 kg은 해상 항구에서 통관되었으며, 이는 날지 않는 화물인 황산암모늄과 인산염 비료입니다. 운임은 US$0.29/kg입니다.

수정하지 않으면: 항공 중량 4.1배 과대계상, kg당 운임 70% 과소평가. 오류는 조용합니다. 쿼리에서는 아무것도 지적하지 않습니다.

이 서버는 수정을 적용하고, 왜 필요한지에 대한 증거를 함께 반환합니다.

Related MCP server: mcp-comtrade

두 가지 보장

1. 모든 응답에는 해당 조회에 적용되는 알려진 결함이 포함되며, 측정된 증거와 검증 출처를 함께 제공합니다.

2. 중대한 수정은 단순히 알림만이 아니라 결과에 적용됩니다. air 채널은 이제 '공항에서 통관된 항공'을 의미합니다. 오염된 블록은 의도적으로 air_declared_at_port로 계속 조회할 수 있습니다. 검사하고 싶은 사람을 위해서요.

게시된 요약이 버리는 데이터셋의 내용

수입 파일에는 VL_FRETE와 VL_SEGURO가 포함되어 있습니다 — 세관에 신고된 운임과 보험입니다. 이는 공개적으로 이용 가능한 실현 비용의 가장 체계적인 측정치이며, 사실상 아무도 사용하지 않습니다.

중국 → 브라질, 2026년 1~7월, 이미 수정됨:

항공은 kg당 76배 더 비싸고, 상품 1달러당 1.65배만 더 비쌉니다. 이 회랑의 운송 모드 분할은 운임 결정이 아니라 가치 밀도 결정입니다.

설치

Node ≥ 22.5 필요 (내장 SQLite 사용 — 네이티브 의존성 0, node-gyp 없음).

git clone <repo> && cd mcp-comex-brasil
npm install && npm run build
npm run db:build -- --years 2025,2026        # baixa da fonte oficial e monta o SQLite

db:build는 balanca.economia.gov.br에서 파일을 직접 가져옵니다. 이 패키지는 어떤 데이터도 재배포하지 않습니다 — 데이터베이스는 항상 출처에서 갓 가져온 상태로 여러분의 머신에 구축됩니다.

유용한 옵션:

npm run db:build -- --years 2026 --countries 160        # só China, base pequena e rápida
npm run db:build -- --years 2024,2025,2026 --flows import,export

MCP 클라이언트 구성

{
  "mcpServers": {
    "comex": {
      "command": "node",
      "args": ["--experimental-sqlite", "/caminho/para/mcp-comex-brasil/dist/index.js"],
      "env": { "COMEX_LANG": "pt" }
    }
  }
}

COMEX_LANG은 pt(기본값) 또는 en을 허용합니다. COMEX_DB는 데이터베이스 경로를 재정의합니다.

네 가지 도구

응답에 수반되는 주의사항

simplified_regime_absent에 대해: POSTAL 및 COURIER에 대한 운송 모드 코드가 존재하지만 비어 있습니다 (2026년 전체에 걸쳐 중국에서 13건, 72kg이며, 보고된 국제 소포 약 1억 8,000만 건과 대조적입니다). 저가의 소포는 간이 통관 제도를 거치며 무역 통계에 포함되지 않습니다. 공식 통계와 소포 물량은 분리된 세계입니다 — 합산하지 말고, 산술적으로 비교하지 마십시오.

검증

집계 결과는 교차 구현으로 검증되었습니다. 동일한 범위를 원시 CSV에 대한 단일 awk 패스와 이 서버의 SQL 뷰로 처리하면 마지막 자릿수까지 동일한 숫자가 생성됩니다 (349,250개 레코드, 7개 채널, 운임 및 중량 값).

npm test     # 12 testes da lógica de classificação e do registro de caveats

라이선스 및 출처

MIT. 데이터: Comex Stat, Secretaria de Comércio Exterior / Receita Federal do Brasil (balanca.economia.gov.br) — 데이터베이스 구축 시점에 조회되는 공개 출처.

저자: Luis Delfin

영어

브라질 대외무역 데이터용 MCP 서버 — 데이터셋의 함정을 응답에서 바로잡은 버전.

거짓말하지 않는 도구 네 개, 알지 못하는 도구 마흔 개 대신.

문제

단지 데이터셋을 노출할 뿐인 MCP 서버는 에이전트에게 잘못된 숫자를 돌려주는 깔끔한 API를 건네줍니다. 내부 배관은 그 필드가 거짓말한다는 사실을 모릅니다.

브라질 공식 무역 데이터셋(Comex Stat, Foreign Trade Secretariat / Federal Revenue Service 발행)에는 어떤 문서도 경고하지 않는 결함이 있습니다:

운송 모드 필드를 AIR로 필터링하면 2026년 1~7월 중국 수입 1억 3,960만 kg이 반환됩니다. 같은 레코드를 통관 지점과 교차 참조하면 단 3,400만 kg(24%)만 공항을 통과했습니다. 나머지 8,970만 kg은 해상 항구에서 통관되었으며, 이는 황산암모늄과 인산염 비료로 구성되어 있습니다 — 날지 않는 화물이며, 운임은 US$0.29/kg입니다.

수정하지 않으면: 항공 중량 4.1배 과대계상, kg당 운임 70% 과소평가. 오류는 조용합니다 — 쿼리는 이를 표시하지 않습니다.

이 서버는 수정을 적용하고, 왜 필요한지에 대한 증거를 반환합니다.

두 가지 보장

1. 모든 응답에는 해당 조회에 적용되는 알려진 결함이 포함되며, 측정된 증거와 검증 출처를 포함합니다.

2. 중대한 수정은 단순히 경고만이 아니라 적용됩니다. air 채널은 이미 '공항에서 통관된 항공 모드'를 의미합니다. 오염된 블록은 의도적으로 air_declared_at_port로 계속 조회할 수 있습니다 — 검사하고 싶은 사람을 위해.

게시된 요약이 버리는 데이터셋의 내용

수입 파일에는 VL_FRETE와 VL_SEGURO가 포함되어 있습니다 — 세관에 신고된 운임과 보험. 이는 공개적으로 이용 가능한 실현 비용의 가장 체계적인 측정치이며, 거의 아무도 사용하지 않습니다.

중국 → 브라질, 2026년 1~7월, 수정됨:

항공은 kg당 76배 더 비싸고, 상품 1달러당 1.65배만 더 비쌉니다. 이 회랑의 운송 모드 분할은 운임 결정이 아니라 가치 밀도 결정입니다.

설치

Node ≥ 22.5 필요 (내장 SQLite 사용 — 네이티브 의존성 0, node-gyp 없음).

npm install && npm run build
npm run db:build -- --years 2025,2026        # fetches from the official source, builds SQLite

db:build는 balanca.economia.gov.br에서 파일을 직접 가져옵니다. 이 패키지는 어떤 데이터도 재배포하지 않습니다 — 데이터베이스는 항상 출처에서 갓 가져온 상태로 여러분의 머신에 구축됩니다.

네 가지 도구

검증

집계 결과는 교차 구현으로 검증되었습니다. 동일한 부분을 원시 CSV에 대한 단일 awk 패스와 이 서버의 SQL 뷰로 처리하면 마지막 자릿수까지 동일한 수치가 생성됩니다 (349,250개 레코드, 7개 채널, 운임 및 중량 값).

npm test     # 12 tests covering the classification logic and the caveat registry

MIT. 데이터: Comex Stat, Brazilian Foreign Trade Secretariat / Federal Revenue Service. 저자: Luis Delfin