hullcheck

hullcheck

在维修船舶、租用船舶或让其进入供应链之前，先对其进行筛查。hullcheck 是 ArcNautical 船舶筛查 API 的轻量客户端，以 IMO 编号为键： 这艘船是否在制裁名单上？它的实际所有者是谁？它的审查评级如何？它即将执行的航程风险有多高？七种工具涵盖查询、深度筛查、批量运行和航线评分。

其中两种工具完全无需密钥——可快速检查单艘船的制裁和审查情况，以及将港口名称或国家转换为 UN/LOCODE 的港口解析器。其余五种工具需要使用你的 API 密钥：获取已保存的完整筛查记录、一次批量筛查最多五十艘船、检索你已付费获取的记录、计算两个港口之间的航程风险评分，以及查看用量，以了解剩余额度。

成功调用会原样返回上游 JSON，不会对其进行任何重塑或摘要处理；批量工具除外，它会等待批次处理完成，然后返回最终批次对象及其项目。

配置

• ARCNAUTICAL_API_KEY（密钥工具必需）— 作为 Authorization: Bearer <key> 发送。无需密钥的工具 （check_vessel、find_port）会忽略此项，完全不发送身份验证 标头。若未设置该项，所有需要密钥的工具都会失败并返回 ARCNAUTICAL_API_KEY is not set，且不会发起请求。
• ARCNAUTICAL_BASE_URL（可选）— API 基础 URL。 默认值为 https://arcnautical.com。

重复创建记录不应导致重复收费。每次创建资源的调用（screen_vessel、 screen_vessels、score_voyage）都会发送一个 Idempotency-Key 标头，其值根据请求内容生成——船舶（或航线、或批次）和 UTC 日期——因此，在同一天重复进行相同的筛查会返回已保存的 记录，且不会产生任何费用。这种生成方式是服务文档中说明的行为；具体的键字符串格式是此客户端对其的呈现方式：

• 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>

工具

• check_vessel — 查询某个 imo 在主要名单中的制裁状态、所有权不透明度评分以及 A–E 级审查等级。无需密钥。
• find_port — 将 query（港口名称或国家）解析为 UN/LOCODE，可选提供 limit。无需密钥。
• screen_vessel — 获取某个 imo 的完整筛查记录：每项匹配及其来源名单、计划和置信度类别、分级审查因素、各来源数据的新鲜度，以及保留的记录 ID。可选参数：customer_reference、vessel_name 和 include_vetting。
• screen_vessels — 对包含 1 至 50 个 IMO 字符串的 imos 数组进行批量筛查并等待结果。可选批次级参数 include_vetting。客户端创建批次，每隔 250 ms 轮询其状态（最多轮询 10 次；间隔和上限由此客户端设定），直到读取到 completed 或 failed，然后获取批次条目并返回 {"batch": ..., "items": ...}。如果创建响应已处于终止状态，则跳过轮询。
• get_screening — 根据 id 检索已存储的筛查记录。
• score_voyage — 评估 origin_locode 和 destination_locode 之间航线的风险：提供评分、等级、风险因素、置信度以及任何缺失的数据源。可选航线输入参数 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）和 bunker_price_usd_per_tonne（非负值）会放在请求的 route 对象中，该对象的端点为 {locode} 对象；customer_reference 和 include_geometry 则放在顶层。
• get_usage — 查询已配置密钥的剩余额度和限制。

任何请求发出前都会执行验证，并在验证失败时返回特定提示，包括 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，以及针对每个航程枚举值或范围的提示（例如 speed_knots must be a number between 8 and 25）。上游返回非 2xx 响应时会报错 arcnautical error: HTTP <status>；API 无法访问时会报错 arcnautical unreachable。

命令行工具

每个工具都是一个子命令，接受一个 JSON 参数字符串：

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

输出为工具的结果文本（成功时为上游 JSON）。退出代码：成功时为 0，运行时错误（包括验证失败、缺少密钥或上游错误）时为 1，用法错误时为 2。

MCP 服务

npx -y @reneturcios/hullcheck mcp

MCP 客户端配置（通过客户端环境提供密钥；两个无需密钥的工具可在没有密钥的情况下使用）：

{
  "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"}'

开发

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

许可证

MIT — 版权所有 (c) 2026 Rene Turcios