OneMap8 MCP Server

Macht eine OneMap8-Flottenverfolgungsinstallation für Claude, ChatGPT und jeden anderen MCP-Client zugänglich, sodass Menschen Fragen in natürlicher Sprache stellen können, anstatt die Berichts-UI zu bedienen:

Wo ist Truck 12 gerade? Wie viele Kilometer hat die Lieferflotte letzte Woche zurückgelegt? Schick mir den Fahrtenbericht für die Transporter per E-Mail, Montag bis Freitag. Welche Fahrzeuge haben über Nacht Alarme ausgelöst?

32 Tools, die die gesamte API-Oberfläche abdecken — Geräte, Positionen, alle sieben Berichtstypen, Geofences, Fahrer, Wartung, Benachrichtigungen, Kalender, Benutzer, Berechtigungen und Gerätebefehlsübermittlung.

Schnellstart

npm install && npm run build

Kopieren Sie .env.example in .env und füllen Sie Ihre Server-URL und ein Token aus:

cp .env.example .env

Verifizieren Sie die Verbindung Ende-zu-Ende:

npm test

Related MCP server: OpenStreetMap MCP Server

Authentifizierung

Das Plugin hat nie mehr Zugriff als das OneMap-Konto dahinter. Welche Geräte, Gruppen und Berichte dieser Benutzer über die Weboberfläche sehen kann, ist genau das, was das Modell erreichen kann — OneMaps eigenes Berechtigungssystem übernimmt die Durchsetzung, und es gibt kein separates Berechtigungsmodell, das synchron gehalten werden muss.

Zwei Optionen, festgelegt in .env:

• ONEMAP_TOKEN (empfohlen) — ein für das Konto erstelltes API-Token. Wird als Bearer-Token gesendet. Widerrufbar, ohne das Passwort zu ändern.

• ONEMAP_EMAIL + ONEMAP_PASSWORD — Basis-Authentifizierung. Funktioniert, lässt aber das Passwort im Klartext auf der Festplatte; verwenden Sie es nur zum Einstieg.

Verbinden eines Clients

Claude Desktop / Claude Code (stdio)

Fügen Sie zu claude_desktop_config.json (oder .mcp.json für Claude Code) hinzu:

{
  "mcpServers": {
    "onemap8": {
      "command": "node",
      "args": ["/absolute/path/to/ai-plugin/dist/stdio.js"],
      "env": {
        "ONEMAP_URL": "https://mcp.onemap8.com/api",
        "ONEMAP_TOKEN": "your-token-here",
        "ONEMAP_ALLOW_COMMANDS": "false"
      }
    }
  }
}

Remote / ChatGPT-Connector (HTTP)

npm run start:http

Bietet Streamable HTTP auf POST /mcp (Health-Check unter /health). Es läuft zustandslos — ein frischer Server pro Anfrage, nichts wird zwischen Aufrufern geteilt — sodass eine Bereitstellung vielen Benutzern dienen kann.

Mit ONEMAP_HTTP_PASSTHROUGH_AUTH=true (Standard) liefert der Authorization: Bearer <token>-Header jeder Anfrage das eigene OneMap-Token des Aufrufers, sodass jeder Benutzer auf seine eigenen Berechtigungen beschränkt ist, anstatt ein gemeinsames Dienstkonto zu teilen.

Bevor Sie es öffentlich bereitstellen:

• Beenden Sie TLS vor dem Prozess — Token reisen in Headern.

• Setzen Sie ONEMAP_ALLOWED_ORIGINS, wenn browserbasierte Clients sich verbinden; nicht gelistete Ursprünge werden abgelehnt.

• Dies implementiert kein OAuth. Stellen Sie entweder ein Gateway davor, das dies tut, oder geben Sie jedem Benutzer ein OneMap-API-Token zum Einfügen in seinen Client.

Schutzmaßnahmen

Die eigenen Berechtigungen des Kontos sind die eigentliche Sicherheitsgrenze. Diese Flags sind die zweite Schicht — sie begrenzen, was das Modell mit diesem Konto tun kann, was eine andere Frage ist als das, was das Konto tun darf.

Zwei Tools erfordern zusätzlich ein explizites confirm: true-Argument, zusätzlich zu den obigen Flags: onemap_send_command und onemap_delete_positions.

Speziell zu Gerätebefehlen: onemap_send_command erreicht physische Hardware — Motor-Immobilisierer, Türschlösser, Relais. Wenn Sie es aktivieren, ist ein Sprachmodell nur einen Tool-Aufruf davon entfernt, ein Fahrzeug zu stoppen. Es ist standardmäßig aktiviert, weil Sie die volle Oberfläche angefordert haben, aber erwägen Sie ONEMAP_ALLOW_COMMANDS=false für jede Bereitstellung, bei der andere Benutzer als Sie darauf zugreifen können, und überlassen Sie die Befehlsübermittlung der eigenen UI der Bediener.

Geplante Berichte

Die OneMap-API hat keinen Endpunkt für wiederkehrende Zeitpläne. Sie kann einen Bericht einmalig per E-Mail senden, auf Anfrage — onemap_report mit delivery: "mail" trifft /reports/{type}/mail, und der Server sendet die Tabelle asynchron an den Kontoinhaber.

Das zu wiederholen ist ein externer Planer, der dasselbe in einem Rhythmus aufruft:

Für alles, wovon ein Unternehmen abhängt, verwenden Sie die erste. Die Eingabeaufforderung schedule_recurring_report führt durch die Auswahl des Berichts und der Parameter, führt ihn einmal aus, damit Sie die Ausgabe prüfen können, und legt dann beide Optionen dar.

Eine n8n-Version ist ungefähr: Schedule Trigger → HTTP Request GET {ONEMAP_URL}/reports/trips/mail mit deviceId, from, to und einem Authorization: Bearer-Header.

Tool-Referenz

Fahrzeugstatus — onemap_list_devices, onemap_get_device, onemap_list_groups, onemap_live_positions, onemap_position_history, onemap_get_event, onemap_geocode, onemap_whoami, onemap_statistics, onemap_audit_log

Berichte — onemap_report (Route, Ereignisse, Fahrten, Stopps, Zusammenfassung, Geofences, kombiniert × json/xlsx/mail), onemap_report_devices_xlsx

Konfiguration — onemap_geofences, onemap_drivers, onemap_maintenance, onemap_calendars, onemap_notifications, onemap_computed_attributes, onemap_orders (jedes nimmt eine action: list/get/create/update/delete)

Befehle — onemap_command_types, onemap_saved_commands, onemap_send_command

Administration — onemap_manage_device, onemap_manage_group, onemap_users, onemap_permissions, onemap_share, onemap_send_notification, onemap_session_token, onemap_stream_url, onemap_server_settings, onemap_delete_positions

Designhinweise

Zwei Entscheidungen, die beim Erweitern wissenswert sind:

• Namen werden serverseitig zu IDs aufgelöst. Tools akzeptieren deviceNames: ["Truck 12"] und schlagen die ID nach, weil Benutzer Namen sagen und Modelle IDs raten. Mehrdeutige Namen werden mit den Kandidaten abgelehnt, anstatt zu einer Vermutung aufgelöst zu werden — stillschweigend das falsche Fahrzeug zu wählen ist schlimmer als zu scheitern.

• Ein Berichtstool, nicht acht. Die sieben Berichts-Endpunkte unterscheiden sich nur durch das Pfadsegment, also sind sie ein Tool mit einem report-Diskriminator. Kurze Tool-Listen verbessern nachweislich die Modellauswahlgenauigkeit; dieselbe Logik fasst Entity-CRUD in jeweils ein action-verwaltetes Tool zusammen.

Benannte Zeiträume (period: "lastWeek") werden ebenfalls serverseitig aufgelöst — Wochen beginnen montags — weil Datumsarithmetik eine zuverlässige Quelle für stille Modellfehler ist.

Zwei API-Eigenheiten, die Sie kennen sollten, bevor Sie diese Codepfade anfassen, beide durch Tests gegen den Live-Server gefunden, nicht durch Lesen der Spezifikation:

• GET /session ignoriert Authorization: Bearer. Es berichtet über die Cookie-Sitzung und antwortet mit 404, wenn keine vorhanden ist. Token-Clients müssen ?token= übergeben, was OneMapClient.getSessionUser() nur als Fallback tut — das setzt die Anmeldeinformationen in das Zugriffsprotokoll des Servers, also ist es nie der erste Versuch.

• id auf /positions bedeutet Positions-ID, nicht Geräte-ID, und deviceId erfordert ein explizites from/to. „Letzte Position" ist daher GET /positions ohne Parameter, clientseitig gefiltert. Das Übergeben einer Geräte-ID als id führt zu einem 500 (NullPointerException) vom Server.

Entwicklung

npm run dev        # tsc --watch
npm test           # build + smoke tests against a mock API
npm run inspect    # MCP Inspector against the stdio server

test/smoke.mjs stellt eine gefälschte OneMap-API auf und treibt den echten Server über einen In-Memory-MCP-Client, abdeckend Namensauflösung, Zeitraum-Erweiterung, Array-Abfragekodierung, E-Mail-Zustellung und jede Schutzmaßnahme.