de en es ja ko ru zh

PingPoint Freight MCP Server

Name: PingPoint Freight MCP Server
Author: sudzikcoin

by sudzikcoin

Overview Schema Related Servers Score Discussions

TypeScript

Remote

PingPoint — MCP-Server und SDK für Frachtverfolgung

Echtzeit-Frachtverfolgung und Ladungssichtbarkeit für Logistiksoftware und KI-Agenten: ein MCP-Server und ein TypeScript-SDK, die jedem Agenten die Live-GPS-Position des Fahrers für eine LKW-Ladung im US-LKW-Verkehr liefern — erstellen Sie eine Ladung über die API, der Fahrer verbindet sich in etwa einer Minute über einen SMS-Link, und von da an sind Position, ETA, Stopp-Zeitachse und Statistiken nach der Fahrt nur einen Aufruf entfernt. Keine ELD-Anbieter-Integration, kein Firmenvertrag, kein Vertriebsgespräch.

Paket	npm	Was es ist
`@suverselabs/pingpoint-mcp`	`npm i @suverselabs/pingpoint-mcp`	MCP-Server — 7 Tools über stdio, für Claude und jeden MCP-fähigen Agenten
`@suverselabs/pingpoint-sdk`	`npm i @suverselabs/pingpoint-sdk`	Typisierter API-Client — keine Abhängigkeiten, typisierte Fehler, idempotente Wiederholungen

Vollständige API-Dokumentation: https://pingpoint.suverse.io/docs · OpenAPI-3.1-Spezifikation: /docs/openapi.json

Das Problem

Die meisten Transportunternehmen im US-LKW-Verkehr sind Ein- oder Zwei-LKW-Unternehmen. Sie haben keinen Unternehmens-Telematik-Stack, keinen Sichtbarkeitsvertrag und keine IT-Abteilung — der LKW ist das Unternehmen. Wenn ein Broker wissen muss, wo sich eine Ladung befindet, ist das einzige zuverlässige Instrument ein Anruf beim Fahrer.

Genau deshalb bedeutet „AI track & trace“ der meisten Anbieter heute einen Roboter, der einen Menschen anruft und fragt. Die Positionsdaten selbst werden nie maschinenlesbar — sie leben im Kopf eines einzigen Fahrers, ein Anruf nach dem anderen. PingPoint macht die Position selbst über eine API verfügbar: Der Fahrer installiert eine App über einen SMS-Link, und von diesem Moment an liest jede Software — oder jeder KI-Agent über MCP — Live-GPS, statt jemanden zu bitten, zu wählen.

Related MCP server: ThinAir Geo

So funktioniert es

1. Eine Ladung wird über die API erstellt

POST /v1/agent/loads mit der Telefonnummer des Fahrers und den Stopps. Erforderlich: driverPhone (E.164 — der Fahrerlink wird per SMS an diese Nummer gesendet) sowie die Arrays pickups / deliveries; jeder Stopp benötigt address, city, state, zip. Multi-Stopp-Ladungen werden unterstützt — mehrere Pickups und mehrere Lieferungen, in der Reihenfolge des Arrays.

Die Antwort enthält die loadNumber (die bei jedem späteren Aufruf verwendet wird), einen öffentlichen trackingLink für den Kunden sowie die Web-/App-Links des Fahrers. Zwei Sicherheitsnetze gegen Doppelverrechnung:

customerRef dient gleichzeitig als Dedup-Schlüssel — das erneute Senden derselben Referenz gibt die vorhandene Ladung zurück (deduplicated: true), anstatt ein Duplikat zu erstellen;
ein Idempotency-Key-Header macht Wiederholungen nach einem Netzwerkfehler sicher — das Guthaben wird höchstens einmal belastet und die Ladung höchstens einmal erstellt.

2. Der Fahrer verbindet sich über einen SMS-Link

PingPoint sendet dem Fahrer automatisch einen Link per SMS. Der Link öffnet das Onboarding: App installieren, Einwilligung durchtippen, fertig — etwa eine Minute Zeitaufwand für den Fahrer, einmalig. Unter der Haube trägt der Link ein einmaliges Ladungstoken, das die App gegen ein dauerhaftes Gerätetoken eintauscht, sodass sich die nächste Ladung an dieselbe Telefonnummer ohne neue Einrichtung bindet.

3. Position fließt über zwei unabhängige Kanäle ein

Das Telefon des Fahrers — Hintergrund-Geolokalisierung aus der App.
Ein ELD-Dongle am Diagnoseanschluss des LKWs — überträgt Fahrzeugdaten per Bluetooth an die App, die sie weiterleitet. Getestet mit IOSiX- und Pacific-Track-PT30-Hardware. Der Dongle sendet Frames mit 1 Hz; die App verdünnt sie vor dem Upload, sodass die gespeicherte Spur dicht genug für Geofencing bleibt, ohne die Pipeline zu überfluten.

Das Telefon bleibt das Gateway für beide Kanäle — der Dongle spricht mit der App, nicht mit dem Netzwerk. Der Sinn von zwei Quellen ist, dass sie auf unterschiedliche Weise ausfallen: Der Dongle liefert weiterhin Positionen, solange der Motor läuft, selbst wenn das GPS des Telefons keinen Fix bekommt oder das Betriebssystem die Hintergrund-Geolokalisierung gedrosselt hat. Dongle-Frames tragen außerdem ihre eigenen Zeitstempel, die aus dem Frame selbst stammen und nicht aus dem Moment des Uploads — wenn also nach einer Offline-Phase ein gepufferter Rückstand übertragen wird, sind die aufgezeichneten Zeiten die echten.

4. Statusänderungen erfolgen über Geofences — niemals über eine Tastatur

Jeder Pickup- und Lieferstopp erhält einen Geofence. Das Betreten der Pickup-Zone versetzt die Ladung in AT_PICKUP, das Verlassen in IN_TRANSIT, das Betreten der Lieferzone in AT_DELIVERY — und DELIVERED wird gesetzt, wenn der LKW die letzte Lieferzone verlässt, nicht bei der Ankunft. Die eine Abkürzung ist der explizite (kostenlose) delivery-confirm-Aufruf (BOL in der Hand), der die Ladung abschließt, sobald der LKW an seinem Lieferstopp ist. Die Zeitstempel arrivedAt / departedAt der Stopps stammen aus denselben Geofence-Ereignissen.

Externe Status-Schreibvorgänge sind bewusst geschlossen: PATCH …/status antwortet immer mit 410 STATUS_DOOR_CLOSED. Das ist eine Datenintegritätsgarantie, kein fehlendes Feature — ein Status, den Sie lesen, wurde nie von jemandem manuell gesetzt; dahinter steht eine aufgezeichnete Position.

5. Auslesen

GET /v1/agent/loads/{loadNumber} gibt den Live-Zustand zurück: Status, GPS-Track (bis zu den 500 neuesten Punkten), die Stopp-Zeitachse mit Ankunfts-/Abfahrtszeitstempeln, zurückgelegte Distanz, Verweilzeiten, Pünktlichkeits-Flag und einen ETA-Block, der aus der gespeicherten Routengeometrie und der neuesten Position berechnet wird. Nach der Fahrt gibt GET …/trip-stats eine aggregierte Zusammenfassung zurück, die über jeden aufgezeichneten Ping berechnet wird. Webhooks können Ladungsereignisse in Echtzeit an Ihren Endpunkt pushen (siehe Dokumentation).

 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)

Schnellstart

Einen Schlüssel erhalten

Registrieren Sie sich unter pingpoint.suverse.io (E-Mail oder Google/GitHub).
Öffnen Sie im Kundenbereich Integrations → Agent API und klicken Sie auf Issue key.
Der Schlüssel sup_agent_… kommt per E-Mail. PingPoint speichert das Geheimnis nie — falls er verloren geht, stellen Sie auf derselben Seite einen neuen aus.

Erster Aufruf

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

Der Fahrerlink ist bereits per SMS auf dem Weg zu +15551234567. Von hier aus liest GET /v1/agent/loads/LD-2026-042317 die Live-Position.

Den MCP-Server verbinden

Claude Code, eine Zeile:

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

Claude Desktop (claude_desktop_config.json) oder ein beliebiger MCP-fähiger Agent:

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

Starten Sie den Agenten neu, und die Tools erscheinen.

MCP-Tools

Detaillierte Referenz pro Tool mit vollständigen Anfrage-/Antwortbeispielen: docs/tools/.

Tool	Funktion	Parameter	Rückgabe	Preis
`create_load`	Erstellt eine Frachtladung; PingPoint sendet den Fahrerlink per SMS an `driverPhone`	`driverPhone`, `pickups[]`, `deliveries[]` (erforderlich); `shipperName`, `carrierName`, `equipmentType`, `customerRef`, `rate`, `miles`, `weight`, `truckNumber`, `idempotencyKey` (optional)	`loadNumber`, öffentlicher `trackingLink`, Web-/App-Links des Fahrers, `driverResolution`, Dedup-Flag	$0.65
`get_load_position`	Live-Zustand einer Ladung	`loadNumber`	Status, GPS-Track (letzte 500 Punkte), Stopps mit Ankunfts-/Abfahrtszeitstempeln, Distanz, Pünktlichkeits-Flag, Verweilzeiten, ETA-Block	$0.02
`get_trip_stats`	Aggregierte Zusammenfassung der gesamten GPS-Fahrt (gedacht für eine DELIVERED-Ladung; während der Fahrt wird die bisherige Fahrt zurückgegeben)	`loadNumber`	`stats`: Distanz, Dauer, Ø/MAX-Geschwindigkeit, Anzahl harter Beschleunigungen/Bremsungen, Anteile Stadt/Autobahn/geparkt/Nacht, GPS-Abdeckung, erster/letzter Ping	$0.02
`update_load_status`	Bewusst geschlossen — Status werden per GPS verifiziert	`loadNumber`, `status`	immer HTTP 410 `STATUS_DOOR_CLOSED`	kostenlos
`confirm_delivery`	BOL erhalten → Ladung an ihrem Lieferstopp wechselt zu DELIVERED (idempotent)	`loadNumber`, `bolReceivedAt` (optional, ISO 8601)	`{ ok, oldStatus, newStatus: "DELIVERED" }`	kostenlos
`get_pricing`	Aktuelle USD-Preisliste	—	`{ currency, prices }`	kostenlos
`get_balance`	Prepaid-Guthaben	—	`{ currency, balanceUsd }`	kostenlos

Die Tool-Beschreibungen sind für das aufrufende Modell geschrieben: Jedes Tool gibt an, was es kostet, wann man es verwenden sollte und wann nicht (z. B. beantwortet get_load_position „Wo ist der LKW jetzt?“, get_trip_stats beantwortet „Wie ist die abgeschlossene Fahrt gelaufen?“ – und beide warnen vor Polling in einer Schleife, weil jeder Aufruf abgerechnet wird).

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

Methoden: createLoad(input, { idempotencyKey? }), getPosition(loadNumber), getTripStats(loadNumber), updateStatus(loadNumber, status) (laut Dokumentation wird dabei absichtlich der 410 ausgelöst), confirmDelivery(loadNumber, { bolReceivedAt? }), getPricing(), getBalance(). Vollständige Referenz: docs/sdk.md.

Jede Nicht-2xx-Antwort wirft eine typisierte Unterklasse von PingPointAgentError, die .status und das rohe .body enthält:

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 (nutzt globales fetch), ESM + CJS, keine Laufzeitabhängigkeiten.

Datenmodell

Position (`get_load_position` / `getPosition`)

Feld	Einheit / Format	Bedeutung
`status`	enum	`PLANNED`, `AT_PICKUP`, `IN_TRANSIT`, `AT_DELIVERY`, `DELIVERED`, `CANCELLED` — wird automatisch aus GPS- und Geofence-Ereignissen fortgeschrieben
`gpsTrack[]`	—	Bis zu den 500 neuesten Punkten, älteste zuerst
`gpsTrack[].lat` / `lng`	Grad	Positionsfix
`gpsTrack[].speed`	mph, 1 Dezimalstelle	Geschwindigkeit über Grund; `null`, wenn der Fix keine enthält
`gpsTrack[].heading`	Grad 0–359, 0 = Norden	`null`, wenn unbekannt
`gpsTrack[].ts`	ISO 8601 UTC	Zeitstempel des Fixes
`distanceMiles`	Meilen	Haversine über die gesamte Strecke (nicht nur die 500 zurückgegebenen Punkte); `null`, bis ≥ 2 Pings vorliegen
`stops[].arrivedAt` / `departedAt`	ISO 8601 UTC	Wird durch Geofence-Ankunft/-Abfahrt gesetzt
`stops[].windowFrom` / `windowTo`	ISO 8601 UTC	Geplante Zeitfenster, `null`, wenn nicht gesetzt
`onTime`	boolean	Innerhalb des Lieferfensters zugestellt (15 Min. Toleranz); `null`, bis zugestellt oder ohne Zeitfenster
`delayMinutes`, `pickupDwellMinutes`, `deliveryDwellMinutes`	Minuten	`null`, wenn noch nicht bekannt
`pingCount`	Anzahl	Gesamtzahl der für die Ladung aufgezeichneten Pings
`eta`	Objekt	Nächster Stopp, Entfernung dorthin (mi), Fahrzeit (h), Bewegungsflag, ETA-Fenster; fail-soft — degradiert zu einem Nur-Grund-Objekt, wenn nicht genügend Daten vorliegen

Fahrtstatistiken (`get_trip_stats` / `getTripStats`)

Feld	Einheit	Bedeutung
`dataPoints`	Anzahl	Für die Ladung aufgezeichnete GPS-Pings
`durationSeconds`	s	`lastAt − firstAt`
`estimatedDistanceMiles`	Meilen	Haversine über die gesamte aufgezeichnete Strecke
`avgSpeedMph`	mph	Über den gesamten Zeitraum, Stopps eingeschlossen
`maxSpeedMph`	mph	Maximale aufgezeichnete Geschwindigkeit über Grund
`hardAccelCount`	Anzahl	Geschwindigkeitszunahme > +15 mph/min bei Bewegung > 20 mph
`hardBrakeCount`	Anzahl	Geschwindigkeitsabfall < −20 mph/min bei Bewegung > 20 mph
`cityMilesPct`	% 0–100	Anteil der Meilen bei 5–45 mph
`highwayMilesPct`	% 0–100	Anteil der Meilen über 45 mph
`parkedTimePct`	% 0–100	Anteil der Pings bei ≤ 5 mph
`nightPct`	% 0–100	Anteil der Pings zwischen 23:00–07:00 UTC
`coveragePct`	% ≤ 100	Pings im Verhältnis zur Erwartung von einem Ping pro Minute über den Zeitraum
`firstAt` / `lastAt`	ISO 8601 UTC	Erster/letzter aufgezeichneter Ping; `null`, wenn keine Pings vorliegen