importproof

importproof

Before goods move, an importer wants a short paper trail: is this EORI number structurally sound and known, which TARIC codes might describe the product, what EU measures attach to a candidate code for a given origin, and what a small consignment is likely to cost once duty relief and destination VAT are accounted for. importproof puts those five preflight questions behind one MCP surface.

The checks themselves run on a hosted service. This package is the local half: it answers the tool list from the definitions captured from that service and relays every call to it, returning the reply exactly as it arrived. The answers are evidence for a declarant to confirm, not determinations. Candidate classifications stay candidates, measures from a dated snapshot can return a review signal instead of a verdict, and a cost figure is an estimate built from what was supplied, with missing inputs reported as missing rather than filled in by guesswork.

Nothing here files a customs declaration, collects or pays a duty, books transport, or submits the receipt anywhere. The receipt tool only bundles the caller's own earlier checks into a signed record of what was checked and when.

Tools

• validate_eori — check an EORI number. Takes eori (up to 20 characters). The reply separates structural validity from an authoritative existence result, and an unavailable provider is reported as such rather than as a failed check.
• search_taric_codes — propose candidate TARIC/CN codes for a product. Takes productDescription (up to 500 characters) and optionally knownProperties, a list of short attribute strings such as material or intended use. Candidates come from a dated snapshot, ranked with their evidence.
• check_eu_import_measures — list EU-level measures for a candidate code. Takes code, originCountry and destinationCountry (ISO alpha-2), and optionally date, goodsValueEur and itemCount. Covers third-country duty, preferences, prohibitions and restrictions, and surveillance from a dated snapshot.
• estimate_low_value_import_cost — estimate landed cost for a consignment whose intrinsic value is at most EUR 150. Takes destinationCountry, currency and items (each item needs intrinsicValue, with an optional taricCandidate), and optionally originCountry, asOfDate, which selects the duty regime, iossUsed, and destinationVatRatePercent.
• prepare_import_preflight_receipt — assemble the earlier checks into one signed receipt. Requires bundle (the preflight results to attest) and createdAt (the ISO timestamp the bundle was put together). The receipt attests the checks; it does not attest a compliance or clearance outcome.

For the first four tools the captured schemas carry no required-field list; only the receipt tool requires its bundle and createdAt arguments.

Configuration

• EU_IMPORT_MCP_URL (optional) — replace the upstream endpoint, which otherwise defaults to https://import.mcp.jithox.com/mcp. This override hook is a labelled reconstruction of this rebuild.
• EU_IMPORT_API_KEY (optional) — when present, every upstream request includes an Authorization: Bearer <value> header carrying the caller's key; when absent, no key header is sent. The header name follows the original service's registry record. The record does not pin a package environment name, so the env name, the Bearer form and the forwarding behaviour are labelled reconstructions; the original surface was captured without a key.

How a call travels

The first call from a client opens a session with three JSON-RPC posts in order: initialize with protocol version 2025-03-26 and client name importproof, then the notifications/initialized notification, then the tools/call itself with the caller's arguments unchanged. If the initialize reply sets an Mcp-Session-Id header, that value is sent on the following requests and the session is reused afterwards. Replies in plain JSON and in server-sent-event framing are both understood.

A reply that succeeds is passed back verbatim, including any error flag the upstream itself set. A call that cannot be completed — an upstream JSON-RPC error, a non-success HTTP status, a body that cannot be read as JSON-RPC, or a transport failure — becomes an error result whose text begins with importproof error: (that wording is a labelled reconstruction of this rebuild).

CLI

Each tool is also available as a subcommand whose single argument is a JSON object string:

npx @reneturcios/importproof validate_eori '{"eori":"BE0123456749"}'
npx @reneturcios/importproof search_taric_codes '{"productDescription":"cotton t-shirt"}'
npx @reneturcios/importproof --version

Exit codes are 0 for a successful call, 1 for an error result, and 2 for a usage error.

MCP server

npx -y @reneturcios/importproof mcp

MCP client config:

{
  "mcpServers": {
    "importproof": {
      "command": "npx",
      "args": ["-y", "@reneturcios/importproof", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/importproof
docker run --rm ghcr.io/cloudcorprecords/importproof --version

With no arguments the container starts the MCP server over stdio; any other arguments are handled by the CLI.

Development

npm install
npm run build
npm test
npm run dev

Tests stub the upstream JSON-RPC service, so the suite makes no live network calls.

License

MIT — see LICENSE.