io.github.CloudCorpRecords/hullcheck

hullcheck

Screen a vessel before you fix it, charter it, or let it into a supply chain. hullcheck is a thin client for the ArcNautical vessel-screening API, keyed by IMO number: is this hull on a sanctions list, who really owns it, how does it grade on vetting, and how risky is the voyage it is about to make? Seven tools cover the lookup, the deep screen, the batch run, and the route score.

Two tools need no key at all — a quick sanctions and vetting check on a single IMO, and a port resolver that turns a port name or country into UN/LOCODEs. The other five use your API key: the stored full screening record, batch screening for up to fifty hulls at once, retrieval of a record you already paid for, a voyage risk score between two ports, and a usage readout so you can see what allowance is left.

Successful calls return the upstream JSON exactly as the API sent it. Nothing is reshaped or summarised on the way through, except the batch tool, which waits for the batch to settle and then returns the final batch object together with its items.

Configuration

• ARCNAUTICAL_API_KEY (required for the keyed tools) — sent as Authorization: Bearer <key>. The keyless tools (check_vessel, find_port) ignore it and send no auth header at all. When it is not set, every keyed tool fails with ARCNAUTICAL_API_KEY is not set and no request is made.
• ARCNAUTICAL_BASE_URL (optional) — API base URL. Defaults to https://arcnautical.com.

Creating a record twice should not charge you twice. Every resource-creating call (screen_vessel, screen_vessels, score_voyage) sends an Idempotency-Key header derived from the question — the hull (or route, or batch) and the UTC day — so repeating the same screening on the same day returns the stored record and spends nothing. The derivation is the service's documented behaviour; the exact key string formats are this client's rendering of it:

• screen_vessel: hullcheck:<imo>:<yyyy-mm-dd>
• screen_vessels: hullcheck:batch:<first imo>:<count>:<yyyy-mm-dd>
• score_voyage: hullcheck:voyage:<origin locode>:<destination locode>:<yyyy-mm-dd>

Tools

• check_vessel — sanctions status across the major lists, an ownership-opacity score, and an A–E vetting grade for one imo. Keyless.
• find_port — resolve a query (a port name or a country) to UN/LOCODEs, with an optional limit. Keyless.
• screen_vessel — the full screening record for one imo: every match with its source list, programme and confidence class, graded vetting factors, per-source freshness, and a retained record id. Optional customer_reference, vessel_name, and include_vetting.
• screen_vessels — batch-screen an imos array of 1 to 50 IMO strings and wait for the results. Optional batch-level include_vetting. The client creates the batch, polls its status every 250 ms (at most 10 polls; the interval and cap are this client's rendering) until it reads completed or failed, then fetches the batch items and returns {"batch": ..., "items": ...}. If the create response is already terminal, polling is skipped.
• get_screening — retrieve a stored screening record by its id.
• score_voyage — route risk between origin_locode and destination_locode: a score, a level, the drivers behind it, a confidence figure, and any missing sources. Optional route inputs vessel_type (container, bulk, tanker, lng, general), load_condition (laden, ballast), speed_knots (8–25), dwt_tonnes (1–600000), fuel_type (hfo, vlsfo, mgo, lng) and bunker_price_usd_per_tonne (non-negative) travel inside the request's route object, whose endpoints are {locode} objects; customer_reference and include_geometry travel at the top level.
• get_usage — remaining allowance and limits for the configured key.

Validation fails before any request with a specific message, among them imo must be a non-empty string, query must be a non-empty string, id must be a non-empty string, imos must be an array of 1 to 50 IMO strings, origin_locode must be a non-empty string, destination_locode must be a non-empty string, limit must be a positive integer, and one message per voyage enum or range (for example speed_knots must be a number between 8 and 25). An upstream non-2xx reply fails with arcnautical error: HTTP <status> and an unreachable API with arcnautical unreachable.

CLI

Each tool is a subcommand taking one JSON argument string:

npx @reneturcios/hullcheck check_vessel '{"imo":"9074729"}'
npx @reneturcios/hullcheck find_port '{"query":"rotterdam","limit":5}'
export ARCNAUTICAL_API_KEY="<your key>"
npx @reneturcios/hullcheck screen_vessel '{"imo":"9074729","vessel_name":"Example"}'
npx @reneturcios/hullcheck screen_vessels '{"imos":["9074729","8814275"]}'
npx @reneturcios/hullcheck get_screening '{"id":"scr_123"}'
npx @reneturcios/hullcheck score_voyage '{"origin_locode":"NLRTM","destination_locode":"SGSIN","vessel_type":"container"}'
npx @reneturcios/hullcheck get_usage '{}'
npx @reneturcios/hullcheck --version

Output is the tool's result text (the upstream JSON on success). Exit codes: 0 on success, 1 on a runtime error (including a validation, missing-key or upstream failure), 2 on a usage error.

MCP server

npx -y @reneturcios/hullcheck mcp

MCP client config (provide the key through the client's environment; the two keyless tools work without it):

{
  "mcpServers": {
    "hullcheck": {
      "command": "npx",
      "args": ["-y", "@reneturcios/hullcheck", "mcp"],
      "env": {
        "ARCNAUTICAL_API_KEY": "<your key>"
      }
    }
  }
}

Docker

docker run -i -e ARCNAUTICAL_API_KEY="<your key>" ghcr.io/cloudcorprecords/hullcheck
docker run --rm ghcr.io/cloudcorprecords/hullcheck check_vessel '{"imo":"9074729"}'

Development

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch only, no network)
npm run dev     # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios