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.

Beide liegen in sdk/ in diesem Repo, sind noch nicht in einer Registry veröffentlicht (offene Lizenz, aber bewusst kein PyPI-/npm-Release bisher — Installation direkt aus dem Pfad oder einem Git-Checkout), und teilen sich dasselbe Auth-Modell wie alles andere in COMPASS: Kopfzeile X-Compass-Key, ein Schlüssel je Aufruf.

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`)
`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).