SDKs verwenden

Für einen Agenten, der keinen MCP-Server starten kann (oder schlicht eine direkte Abhängigkeit statt eines Unterprozesses will), sprechen zwei dünne Client-Bibliotheken direkt die REST-API des Kerns an — kein MCP dazwischen. Sie decken dieselben sieben Verben ab, die der MCP für den üblichen Weg anbietet: prüfen, was gilt, fragen warum, eine Sache anlegen, eine Regel setzen/ablösen, eine Lehre festhalten, suchen und das Regelwerk exportieren.

Der Python-Client liegt öffentlich in github.com/Athron-new/compass-agents unter sdk/python (MIT; Installation aus einem Checkout mit pip install -e sdk/python). Keiner der beiden Clients ist auf PyPI oder npm veröffentlicht. Beide teilen sich dasselbe Auth-Modell wie alles andere in COMPASS: Kopfzeile X-Compass-Key, ein Schlüssel je Aufruf.

Regeln setzt ein Mensch. regel_setzen / regelSetzen braucht zusätzlich das Sitzungs-Token einer angemeldeten Person (Compass(..., menschen_sitzung=...) in Python, new Compass(url, key, { menschenSitzung }) in TypeScript oder die Umgebungsvariable COMPASS_MENSCHEN_SITZUNG; es kommt aus POST /auth/anmelden, s. Quickstart). Ohne es antwortet der Kern mit 403. Das Token ist wie der Schlüssel ein Geheimnis. COMPASS_MENSCHEN_SITZUNG gehört nie in die Umgebung eines Agenten: Der Kern kann Mensch und Agent dann nicht mehr trennen, und die Regel „Regeln setzt der Mensch" ist für diesen Agenten aufgehoben.

Python — `compass_client`

from compass_client import Compass

c = Compass("http://localhost:18080", "<euer-schluessel>")
regel = c.gilt("deploy-freigabe")

Lokale Installation mit pip install -e sdk/python. Einzige Laufzeit-Abhängigkeit: httpx. Ein asynchrones Gegenstück, AsyncCompass, spiegelt jede Methode als async def.

TypeScript — `@athron/compass`

import { Compass } from "@athron/compass";

const c = new Compass("http://localhost:18080", "<euer-schluessel>");
const regel = await c.gilt("deploy-freigabe");

Gebaut mit tsc (npm run build in sdk/typescript) nach dist/ (ESM, mit .d.ts). Keine Laufzeit-Abhängigkeiten — nutzt das globale fetch.

Das Paket ist nicht veröffentlicht. npm install @athron/compass schlägt fehl (die Registry antwortet 404, gemessen am 02.10.2026) — @athron/compass ist der Name im Repo, keine Bezugsquelle. Bis es veröffentlicht ist, wird das SDK lokal eingebunden, so wie das Python-Gegenstück: npm install ./sdk/typescript oder ein "@athron/compass": "file:../sdk/typescript" in der eigenen package.json. Der import darüber bleibt dadurch unverändert.

Methoden-zu-Route-Übersicht

Beide SDKs bieten dieselben sieben Aufrufe, jeweils in der Namenskonvention der Sprache (snake_case in Python, camelCase in TypeScript):

Python	TypeScript	Route
`c.gilt(sache, ...)`	`c.gilt(sache, ...)`	`GET /gilt/{sache}`
`c.warum(sache, ...)`	`c.warum(sache, ...)`	`GET /warum/{sache}`
`c.sache_anlegen(slug, titel, frage, bereich=None, ...)`	`c.sacheAnlegen(slug, titel, frage, bereich?, ...)`	`POST /sachen`
`c.regel_setzen(sache, text, ersetzt=None, ...)`	`c.regelSetzen(sache, text, { ersetzt?, ... })`	`POST /aussagen` (`art=regel`; braucht die Sitzung eines Menschen)
`c.lehre_festhalten(art, titel, was, lehre, ...)`	`c.lehreFesthalten(art, titel, was, lehre, ...)`	`POST /lehren`
`c.suche(q, ...)`	`c.suche(q, ...)`	`GET /suche` — liefert `{treffer, gesamt, abgeschnitten, weiter}`, kein Array (seit 05.10.2026)
`c.export(art="claude-md-section0", ...)`	`c.export(art?, ...)`	`GET /export/claude-md-section0` (auch `agents-md`, `cursor-rules`)

Jede Nicht-2xx-Antwort wirft einen strukturierten Fehler — CompassFehler in Python, CompassError in TypeScript — mit status, detail (dem Klartext-Satz, „Fehlerform"), feld (das Feld, das ein 409/422 nennt, falls vorhanden) und allem Übrigen aus dem Antwort-Body (z.B. der geltenden Regel bei einem 409 aus regel_setzen).

Wann SDK statt MCP

Der MCP (mcp/server.py, siehe Claude Code, Cursor und Codex anbinden) passt für einen Agenten, der ohnehin MCP spricht — Claude Code, Cursor, Codex. Die SDKs sind für alles andere: ein CI-Job, ein Backend-Dienst, ein Skript, das nur gilt() braucht, bevor es handelt, ohne Unterprozess oder MCP-Client-Bibliothek dazwischen. Beide sprechen denselben Kern, über denselben REST-Vertrag — keines ist ein zweiter Wahrheitsweg.

Tests

Jedes SDK bringt seine eigene Test-Suite neben dem Quelltext mit (sdk/python/tests, sdk/typescript/tests) — Anfrageform (Pfad, Methode, Kopfzeile, Body) und Fehlerabbildung gegen einen simulierten Kern, dazu eine statische Prüfung, dass jede vom SDK aufgerufene Route tatsächlich im laufenden Kern existiert (dieselbe Gegenprobe, die diese Doku-Seite selbst für ihre eigenen REST-Erwähnungen fährt).