PingPoint — 貨物追跡MCPサーバーとSDK

物流ソフトウェアとAIエージェント向けのリアルタイム貨物追跡と積荷可視化: 米国トラック輸送におけるトラック積荷のライブ運転手GPS位置を任意のエージェントに提供するMCPサーバーとTypeScript SDKです。APIで積荷を作成し、運転手がSMSリンクから約1分で接続すると、以降は位置、ETA、停車タイムライン、運行後統計が1回の呼び出しで取得できます。ELDプロバイダー統合も、法人契約も、営業電話も不要です。

完全なAPIドキュメント: https://pingpoint.suverse.io/docs · OpenAPI 3.1仕様: /docs/openapi.json

問題

米国トラック輸送のほとんどの運送会社は1〜2台のトラックを所有する小規模企業です。企業向けテレマティクス基盤も、可視化契約も、IT部門もありません。トラックこそが会社です。ブローカーが積荷の位置を知る必要があるとき、唯一信頼できる手段は運転手への電話です。

そのため、現在の多くのベンダーが提供する「AI追跡・トレース」とは、人間に電話して尋ねるロボットのことです。位置データ自体は機械可読になることはなく、1回の電話ごとに1人の運転手の頭の中に留まります。PingPointは位置自体をAPIで利用可能にします。運転手がSMSリンクから1つのアプリをインストールすると、その瞬間から任意のソフトウェア — またはMCP経由の任意のAIエージェント — がダイヤルを依頼する代わりにライブGPSを読み取ります。

Related MCP server: ThinAir Geo

仕組み

1. APIで積荷を作成

POST /v1/agent/loads に運転手の電話番号と停車地を指定します。必須: driverPhone（E.164 — 運転手リンクがこの番号にSMS送信されます）と pickups / deliveries 配列。各停車地には address、city、state、zip が必要です。複数停車地の積荷も対応しています — 複数のピックアップと複数の配達を配列順に指定します。

レスポンスには loadNumber（以降のすべての呼び出しで使用）、顧客向けの公開 trackingLink、運転手向けのWeb/アプリリンクが含まれます。二重請求を防ぐ2つの安全策:

• customerRef は重複排除キーを兼ねます — 同じ参照を再送すると、重複を作成する代わりに既存の積荷を返します（deduplicated: true）;

• Idempotency-Key ヘッダーにより、ネットワーク障害後の再試行が安全になります — 残高の引き落としと積荷の作成は最大1回だけ行われます。

2. 運転手がSMSリンクから接続

PingPointが運転手にリンクを自動送信します。リンクを開くとオンボーディングが始まります: アプリのインストール、同意のタップ、完了 — 運転手の時間は約1分、一度だけです。内部では、リンクには一回限りの積荷トークンが含まれており、アプリがそれを永続的なデバイストークンと交換するため、同じ電話番号への次の積荷は新しい設定なしでバインドされます。

3. 位置は2つの独立したチャネルで流れ込む

• 運転手のスマートフォン — アプリからのバックグラウンド位置情報。

• トラックの診断ポートに接続されたELDドングル — 車両データをBluetooth経由でアプリにストリーミングし、アプリがそれを中継します。IOSiXおよびPacific Track PT30ハードウェアでテスト済み。ドングルは1Hzでフレームを出力します。アプリはアップロード前に間引きを行い、保存されるトラックがジオフェンシングに十分な密度を保ちつつ、パイプラインを圧迫しないようにします。

電話は両チャネルのゲートウェイのままです — ドングルはネットワークではなくアプリと通信します。2つのソースのポイントは、障害の仕方が異なることです。ドングルは、電話のGPSが測位できない場合やOSがバックグラウンド位置情報を抑制した場合でも、エンジンが動いている限り位置を送り続けます。ドングルのフレームには独自のタイムスタンプも含まれており、アップロード時ではなくフレーム自体から取得されます。そのため、オフライン期間後にバッファされたバックログがフラッシュされるとき、記録される時刻は実際のものです。

4. ステータスはジオフェンスから進む — キーボードからではない

各ピックアップおよび配達停車地にはジオフェンスが設定されます。ピックアップゾーンに入ると積荷は AT_PICKUP に移行し、離れると IN_TRANSIT に、配達ゾーンに入ると AT_DELIVERY に移行します。そして DELIVERED は、トラックが最終配達ゾーンを出発したときに設定されます（到着時ではありません）。唯一のショートカットは、明示的な（無料の）delivery-confirm 呼び出し（BOL入手済み）で、トラックが配達停車地に到着した時点で積荷を完了します。停車地の arrivedAt / departedAt タイムスタンプも同じジオフェンスイベントから取得されます。

外部からのステータス書き込みは意図的に閉じられています: PATCH …/status は常に 410 STATUS_DOOR_CLOSED を返します。これはデータ整合性の保証であり、機能の欠落ではありません — 読み取ったステータスは誰かが手動で設定したものではなく、その背後には記録された位置があります。

5. 読み取り

GET /v1/agent/loads/{loadNumber} はライブ状態を返します: ステータス、GPSトラック（最大500の最新ポイント）、到着/出発タイムスタンプ付きの停車タイムライン、走行距離、滞留時間、定時フラグ、保存されたルート形状と最新位置から計算されたETAブロック。運行後は GET …/trip-stats で、記録されたすべてのピングから計算された集計サマリーを返します。Webhookは積荷イベントを発生時にエンドポイントへプッシュできます（ドキュメント参照）。

 SMS link          +---------------------+
 (sent by  ------> |  Driver phone app   |--- background GPS ---+
  PingPoint)       +---------------------+                      |
                                                                v
                   +---------------------+   1 Hz frames   +--------------------+
                   |  ELD dongle on the  |---------------->| ingest (thinning)  |
                   |  diagnostic port,   |   via the app   +--------------------+
                   |  BLE (IOSiX, PT30)  |                      |
                   +---------------------+                      v
                                                       +-----------------+
                                                       |  position store |
                                                       +-----------------+
                                                            |        |
                                     geofence engine <------+        |
                                            |                        |
        PLANNED -> AT_PICKUP -> IN_TRANSIT -> AT_DELIVERY -> DELIVERED
                                            |                        |
                                            v                        v
                  webhooks -> your endpoint      GET /v1/agent/loads/{n}   (position, ETA)
                                                 GET .../trip-stats        (post-trip summary)

クイックスタート

キーを取得

1. pingpoint.suverse.io でサインアップ（メールまたはGoogle/GitHub）。

2. キャビネットで Integrations → Agent API を開き、Issue key を押します。

3. sup_agent_… キーがメールで届きます。PingPointは秘密鍵を保存しません — 紛失した場合は、同じページから新しいものを再発行してください。

最初の呼び出し

curl -X POST https://api.suverse.io/v1/agent/loads \
  -H "Authorization: Bearer sup_agent_…" \
  -H "Content-Type: application/json" \
  -d '{
    "driverPhone": "+15551234567",
    "pickups":    [{ "address": "6492 Tower Lane", "city": "Claremore", "state": "OK", "zip": "74017" }],
    "deliveries": [{ "address": "6499 Caldwell Park Dr", "city": "Charlotte", "state": "NC", "zip": "28269" }],
    "customerRef": "PO-483920"
  }'

{
  "success": true,
  "loadId": "3b9f6a2e-1c47-4d8a-9e02-7f5b1c8d4a63",
  "loadNumber": "LD-2026-042317",
  "trackingLink": "https://pingpoint.suverse.io/track/trk_…",
  "driverWebLink": "https://pingpoint.suverse.io/driver/drv_…",
  "driverAppLink": "pingpoint://driver/drv_…",
  "driverResolution": "none"
}

運転手リンクはすでにSMSで +15551234567 に送信されています。ここから GET /v1/agent/loads/LD-2026-042317 でライブ位置を読み取ります。

MCPサーバーを接続

Claude Code、1行:

claude mcp add pingpoint --env PINGPOINT_AGENT_KEY=sup_agent_… -- npx -y @suverselabs/pingpoint-mcp

Claude Desktop（claude_desktop_config.json）または任意のMCP対応エージェント:

{
  "mcpServers": {
    "pingpoint": {
      "command": "npx",
      "args": ["-y", "@suverselabs/pingpoint-mcp"],
      "env": {
        "PINGPOINT_AGENT_KEY": "sup_agent_…"
      }
    }
  }
}

エージェントを再起動するとツールが表示されます。

MCPツール

完全なリクエスト/レスポンス例を含むツールごとの詳細リファレンス: docs/tools/。

ツールの説明は呼び出し元モデル向けに書かれています: 各ツールはコスト、使用すべきタイミング、使用すべきでないタイミングを示します（例: get_load_position は「トラックは今どこか」に答え、get_trip_stats は「完了した運行はどうだったか」に答え、両方ともすべての呼び出しが課金されるためループでのポーリングを警告します）。

SDK

npm install @suverselabs/pingpoint-sdk

import { PingPointAgent, InsufficientFundsError, DeliveryNotReadyError } from "@suverselabs/pingpoint-sdk";

const pp = new PingPointAgent({ apiKey: process.env.PINGPOINT_AGENT_KEY! });

// $0.65 — driver gets the app link by SMS
const load = await pp.createLoad(
  {
    driverPhone: "+15551234567",
    pickups: [{ address: "6492 Tower Lane", city: "Claremore", state: "OK", zip: "74017" }],
    deliveries: [{ address: "6499 Caldwell Park Dr", city: "Charlotte", state: "NC", zip: "28269" }],
    customerRef: "PO-483920",
  },
  { idempotencyKey: "PO-483920" },
);

const pos = await pp.getPosition(load.loadNumber);   // $0.02
const trip = await pp.getTripStats(load.loadNumber); // $0.02, best after DELIVERED
await pp.confirmDelivery(load.loadNumber, { bolReceivedAt: new Date() }); // free

メソッド: createLoad(input, { idempotencyKey? })、getPosition(loadNumber)、getTripStats(loadNumber)、updateStatus(loadNumber, status)（意図的な410を投げることが文書化されている）、confirmDelivery(loadNumber, { bolReceivedAt? })、getPricing()、getBalance()。完全なリファレンス: docs/sdk.md。

すべての非2xx応答は、.status と生の .body を保持する PingPointAgentError の型付きサブクラスを投げます:

try {
  await pp.createLoad(input);
} catch (err) {
  if (err instanceof InsufficientFundsError) {
    console.log(`balance $${err.balanceUsd}, need $${err.priceUsd} — nothing was charged`);
  } else if (err instanceof DeliveryNotReadyError) {
    // driver hasn't arrived yet — do NOT retry; the load completes automatically when the truck departs the delivery zone
  }
}

Node ≥ 18（グローバル fetch を使用）、ESM + CJS、ランタイム依存関係ゼロ。

データモデル

位置（get_load_position / getPosition）

トリップ統計 (get_trip_stats / getTripStats)

エラーコード

料金

プリペイド残高、呼び出しごとの課金、サブスクリプションはありません。詳細: docs/billing.md

• 残高は、管理画面の Billing からチャージできます。無料の操作は残高ゼロでも動作します。

• 402 は、何かが行われる前に呼び出しが拒否されたことを意味します。何も作成されておらず、何も請求されていません。

• createLoad のリトライは、同じ Idempotency-Key を使えば安全です。引き落としは最大でも 1 回だけです。また、customerRef がビジネスレベルで重複を排除します。

• 価格は GET /v1/agent/pricing で常時提供されています。この値を正情報源として扱い、ハードコーディングしないでください。

これは対象外

• 認定された ELD ではありません。 PingPoint は可視化に GPS（およびドングル経由のエンジンバスデータ）を読み取ります。FMCSA 登録の ELD ではなく、HOS / RODS のコンプライアンス記録を作成するものではありません。

• 運送会社の審査ではありません。 リアルタイム位置はトラックがどこにいるかを示しますが、運送会社が安全か、保険に加入しているか、実在するかを判別するものではありません。現在行っているオンボーディングチェックをそのまま続行してください。

• ドライバーによるアプリのインストールが必要です。 SMS リンクを 1 回開いてインストール、約 1 分です — ただし、ドライバーの協力を要する実際の工程です。接続された電話もドングルもない荷物は、位置を一切生成しません。

ほかのソリューションとの比較

エンタープライズ向け可視化プラットフォームは、運送会社に既にテレマティクスがあり、ブローカーに既に契約があることを前提としています。コールによる追跡ベンダーは、確認のたびに（人間またはロボットによる）電話を挟みます。PingPoint の取り組みは異なります。ドライバーへのインストール 1 回と引き換えに、公開された価格と最低料金のない API をコールごとに提供します。両カテゴリとの実際の比較（キー発行、公開価格、API サーフェス、MCP/SDK 提供状況）を、pingpoint.suverse.io/compare で項目ごとに掲載しています。

リンク

• API ドキュメント: https://pingpoint.suverse.io/docs

• OpenAPI 3.1 スペック: https://pingpoint.suverse.io/docs/openapi.json

• 代替ソリューションとの比較: https://pingpoint.suverse.io/compare

• npm 上の MCP サーバー: https://www.npmjs.com/package/@suverselabs/pingpoint-mcp

• npm 上の SDK: https://www.npmjs.com/package/@suverselabs/pingpoint-sdk

• リポジトリ内リファレンス: architecture · billing · SDK reference · MCP tools

• お問い合わせ先: info@suverse.io

ライセンス

MIT © 2026 Sudzik Group Inc.