hullcheck

hullcheck

船舶を修理、傭船、またはサプライチェーンに組み入れる前にスクリーニングできます。hullcheck は、IMO 番号をキーに ArcNautical の船舶スクリーニング API を利用する軽量クライアントです。この船体は制裁リストに載っているか、実際の所有者は誰か、検査ではどのように評価されているか、これから航行する航路にはどの程度のリスクがあるかを確認できます。検索、詳細スクリーニング、一括処理、航路スコアの 7 つのツールを備えています。

キーなしで使えるツールが 2 つあります。単一の IMO を対象に制裁と検査をすばやく確認するツールと、港名または国名を UN/LOCODE に変換する港検索ツールです。残りの 5 つのツールでは API キーを使用します。保存済みの完全なスクリーニング記録、一度に最大 50 隻を対象とする一括スクリーニング、すでに料金を支払った記録の取得、2 つの港間の航海リスクスコアの算出、残りの利用枠を確認できる使用状況の表示です。

成功した呼び出しでは、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 です。

同じ記録を 2 回作成しても、料金が 2 回発生することはありません。リソースを作成する呼び出し（screen_vessel、screen_vessels、score_voyage）はそれぞれ、質問（船体、航路、またはバッチ）と UTC の日付に基づく Idempotency-Key ヘッダーを送信します。そのため、同じ日に同じスクリーニングを繰り返すと、保存済みの記録が返され、利用枠は消費されません。この生成方法はサービスのドキュメントに記載された動作です。キー文字列の正確な形式は、このクライアントによる表現です。

• 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 — 主要なリストにおける制裁対象状況、所有者の不透明性スコア、および1つのimoに対するA～Eの審査評価を返します。キー不要です。
• find_port — query（港名または国）をUN/LOCODEに解決します。limitは任意です。キー不要です。
• screen_vessel — 1つのimoに対する完全なスクリーニング記録を返します。各照合結果のソースリスト、プログラム、信頼度クラス、評価済みの審査要因、ソースごとの鮮度、および保持されたレコードIDが含まれます。customer_reference、vessel_name、include_vettingは任意です。
• screen_vessels — 1～50個のIMO文字列からなるimos配列を一括スクリーニングし、結果を待ちます。一括処理レベルのinclude_vettingは任意です。クライアントは一括処理を作成し、completedまたはfailedが読み取れるまで、ステータスを250 msごとに（最大10回ポーリング。この間隔と上限はこのクライアントによる表示処理です）ポーリングした後、一括処理項目を取得し、{"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（0以上）は、エンドポイントが{locode}オブジェクトとなるリクエストのrouteオブジェクト内に渡します。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が返されます。

CLI

各ツールは、1つの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 クライアント設定（キーはクライアントの環境変数を通じて指定します。キー不要の2つのツールはキーなしで動作します）：

{
  "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 — Copyright (c) 2026 Rene Turcios