
comexscope
io.github.CloudCorpRecords/comexscope
Brazil foreign-trade data by HS code: exports, imports, partners, balances, climate, reports.
Documentation
comexscope
Brazil's foreign-trade data — Comex Stat figures and the vendor's derived readings on top of them — sits behind the hosted Kyrodata MCP service. comexscope is a small local bridge to that service: you can compare exports or imports between like-for-like windows, read a heading's totals and monthly series, rank partner countries, pull a commodity hub's forecast verdict or climate reading, check a supply and demand balance sheet, search the public catalogue, and run the product's pre-built reports.
Nothing is stored or computed on your own machine. This package answers tools/list locally from the captured tool definitions and forwards every tools/call to the hosted service over a streamable-HTTP JSON-RPC session, returning whatever the service sends back unchanged.
The tools
Every tool in this surface reads published Brazil foreign-trade data (Comex Stat) and the vendor's derived readings. kyrodata_get_credit_balance reports the balance and limits of the caller's own API key; no tool writes anything, buys anything, starts a subscription, checks out, or creates an API key.
kyrodata_compare_trade— Compares exports or imports between two equal-length windows, in value (USD FOB) and volume (kg), with the % change of each metric and the monthly series spanning both windows.codesandcountryIdsfilter both windows alike.kyrodata_explain_pyramid_level— Explains the forecast pyramid's arithmetic for one commodity and horizon: the seven levels side by side, or one level followed across all four horizons vialevelKey.kyrodata_fetch— Opens one public trade document by an id fromkyrodata_search(heading:1201,country:160) and returns it as citable prose with a public URL.kyrodata_get_climate_reading— Current climate reading for a commodity: risk level, measured production shock, and projected physical loss in tonnes per horizon, at country, region or state scope.kyrodata_get_credit_balance— The credit balance and limits of the API key making the request: credits left, reset timing, daily ceilings, and which tools the key reaches.kyrodata_get_data_coverage— The calendar of the trade data: first and last published month, whether the current year is partial, the last fully closed month, and the last refresh.kyrodata_get_heading_overview— Structured read of one HS heading (SH4): published-year totals, last closed month against the previous one, and a monthly price-by-volume series.kyrodata_get_hub_summary— The pyramid verdict for a commodity hub: direction, expected move per horizon, the 80% band, which levels drive the verdict, and measured accuracy.kyrodata_get_supply_demand_balance— Published supply and demand balance (in tonnes) for one agricultural hub, season by season, optionally closed seasons only.kyrodata_list_trade_partners— Ranks Brazil's partner countries for exports or imports in a window, with value, volume, price per kg, share, and optional growth.kyrodata_list_trade_series— Brazil's monthly export or import series as rows, narrowed by HS codes and partner countries; gaps stay absent rather than reading as zero.kyrodata_resolve_comparison_window— Resolves an equal-length comparison window and returns only its metadata: from, to, label, months, and whether it crosses a season.kyrodata_resolve_entity— Resolves a free-text name into platform identifiers for filtering other tools: commodity hubs, HS headings, NCM codes and partner countries.kyrodata_run_report— Runs one of the product's pre-built catalogue reports by id and returns its rows, with the report's own parameters and an optional column projection.kyrodata_search— Searches the public Brazilian foreign-trade catalogue and returns document ids forkyrodata_fetch— HS headings and partner countries, each with a public URL.
Install and run
As an MCP server via npm:
npx -y @reneturcios/comexscope mcp
MCP client configuration:
{
"mcpServers": {
"comexscope": {
"command": "npx",
"args": ["-y", "@reneturcios/comexscope", "mcp"]
}
}
}
As a container:
docker run -i ghcr.io/cloudcorprecords/comexscope
docker run --rm ghcr.io/cloudcorprecords/comexscope kyrodata_search '{"query":"soja"}'
CLI
One binary serves both the command line and the MCP server. Each tool is a subcommand taking a single JSON string with that tool's arguments:
comexscope kyrodata_compare_trade '{"flow":"export","mode":"ytd"}'
comexscope kyrodata_get_heading_overview '{"sh4":"1201","flow":"export"}'
comexscope kyrodata_resolve_entity '{"q":"China"}'
comexscope kyrodata_search '{"query":"soja"}'
comexscope kyrodata_get_data_coverage '{}'
comexscope --version
Exit codes: 0 when the forwarded call succeeds, 1 when the upstream result is an error, and 2 for usage problems such as an unknown subcommand or a malformed JSON argument.
Configuration
KYRODATA_MCP_URL— Overrides the upstream endpoint. The default is the pinned hosted endpoint,https://mcp.kyrodata.com/mcp. (The override variable is a reconstruction added by this rebuild.)KYRODATA_API_KEY— When set, its value is sent to the upstream on every request as anAuthorization: Bearer <value>header; the upstream's registry record pins a secretAuthorizationheader on its remote. When it is not set, no key header is sent at all, matching the keyless behaviour the tool surface was captured with. (The env forwarding is a reconstruction added by this rebuild; the captures were keyless.)
Upstream failures — a JSON-RPC error from the service, a non-2xx response, an unreadable body, or a request that fails outright — are reported to the caller as an error result whose text starts with comexscope error:.
How forwarding works
The first forwarded call opens a session: an initialize request (protocol version 2025-03-26), followed by a notifications/initialized notification, then the tools/call itself. If the service answers the initialize request with an Mcp-Session-Id header, that value is carried on every later request, and the open session is reused for the rest of the process. Replies are accepted either as plain JSON or as server-sent events. Successful results pass through verbatim, including any isError flag and any extra fields the service includes.
Development
npm install
npm run build # tsc -> dist/ (dist/cli.js is the bin)
npm test # tsx --test test/*.test.ts — stubbed upstream, no network
npm run dev # run the CLI from source
The test suite checks the served tool list against the captured surface tool by tool, exercises the session handshake and its reuse, covers both key-header branches, and verifies that arguments go upstream untouched and results come back untouched.
License
MIT — see LICENSE. Copyright (c) 2026 Rene Turcios.
@reneturcios/comexscopenpm install @reneturcios/comexscopeghcr.io/cloudcorprecords/comexscope:0.1.0docker pull ghcr.io/cloudcorprecords/comexscope:0.1.0:undefinedRelated Servers
io.github.CloudCorpRecords/abandoncheck
Judge whether a dependency is maintained, from factual signals: releases, commits, archival.
io.github.CloudCorpRecords/actionbridge
Zapier exposed actions as MCP tools via a generic action runner.
io.github.CloudCorpRecords/actionpin
GitHub Actions supply-chain hardener: audit workflows for unpinned actions and build a SHA pin plan.