# 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:

```bash
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

```bash
npx -y @reneturcios/hullcheck mcp
```

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

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

## Docker

```bash
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

```bash
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