MCP-Werkzeuge-Referenz

49 Werkzeuge, registriert in mcp/server.py (31 direkt) und fünf Zusatzmodulen (agents_tools.py, beurteilung_tools.py, hall_of_fame_tools.py, lehren_tools.py, statistik_tools.py). Jedes Werkzeug ruft genau eine Kern-REST-Route auf — kein Werkzeug trägt eigene Fachlogik oder eigene Invarianten; ein 409/422 des Kerns kommt beim aufrufenden Modell als strukturierter ToolError an, nie verschluckt. Siehe Claude Code, Cursor und Codex anbinden für die Authentifizierung eines Clients.

Zwei Lese-Werkzeuge behandeln ein dokumentiertes leeres Ergebnis als gültige Antwort, nicht als Fehler: gilt liefert bei einem 404 des Kerns {"gilt": false, ...}, prozess_bild liefert bei dessen 404 {"bild_url": null, ...}. Jedes andere Werkzeug reicht eine Nicht-2xx-Antwort als Fehler durch.

Eine Sache lesen

Werkzeug	Parameter	Liefert
`sache_list`	`bereich?, stufe?, suche?, persona_slug?, alle=False, gehoert_persona?`	Sachen mit Frage und geltender Regel. `persona_slug` filtert auf das Sichtfeld der aufrufenden Persona (gesendet als `sichtfeld=`); `gehoert_persona` filtert auf Eigentum (gesendet als `persona=`) — unabhängige Filter.
`sache_get`	`slug`	Die Sache plus jede Aussage, nach Art, plus Historie. Kein Sichtbarkeits-Filter — Einzel-Lookup, keine Liste.
`gilt`	`slug, subjekt_id?, persona_slug?, alle=False`	Die eine geltende Regel, oder ein gültiges leeres Ergebnis.
`gilt_am`	`slug, datum, subjekt_id?, persona_slug?, alle=False`	Was am Datum galt, mit Status.
`warum`	`slug`	Entscheidungstext der Regel, Historie, letztes Prüfweg-Ergebnis.
`suche`	`q, subjekt_id?, persona_slug?, alle=False`	Volltextsuche über Aussagen und Ereignisse.
`konflikte`	—	Sachen mit Konflikt.
`graph`	`slug?, id?, tiefe=2`	Knoten und Kanten rund um eine Sache/Aussage/einen Prozess.

Eine Sache oder Aussage schreiben

Werkzeug	Parameter	Liefert
`sache_put`	`slug, titel, frage, bereich?, stufe?, eltern_slug?, subjekt_typ?`	Legt eine Sache an, idempotent auf `slug`.
`aussage_put`	`sache, art, text, herkunft, angelegt_von, subjekt_id=1, gilt_seit?, gilt_bis?, beobachtet_am?, quelle?, sicherheit?, ort?, pruefweg_slug?, beleg?, ersetzt?, status="gilt", frist?, prozess_slug?, schritt_key?, frame_ref?`	Neue Aussage. `409` mit der geltenden Aussage im Fehlertext, wenn `ersetzt` fehlt und schon eine gilt.
`hypothese_put`	`sache, text, frist, pruefweg_slug, sicherheit, quelle, angelegt_von`	Neue Hypothese. Das Werkzeug selbst weist `sicherheit >= 1` ab, bevor der Kern gefragt wird.
`hypothese_bewerten`	`id, ergebnis, quelle, neue_frist?`	Löst eine Hypothese auf (`bestaetigt`\|`widerlegt`\|`verlaengert`, clientseitig geprüft).
`pruefweg_run`	`slug`	Führt einen Prüfweg aus, speichert das Ergebnis, schreibt einen Fakt.
`abweichungen`	`seit?`	Listet Abweichungen.
`ereignis_put`	`subjekt_id, typ, zeitpunkt, inhalt_ref, text?`	Erfasst ein Ereignis.
`frage_stellen`	`sache, frage, optionen, gestellt_von, empfehlung_key?, frist?`	Stellt eine Schaltzentrale-Frage. Das Werkzeug weist weniger als zwei Optionen, oder eine Option ohne `folge`, vor dem Kern-Aufruf ab.
`offen_fuer_mensch`	—	Alles, was gerade einen menschlichen Klick braucht. Eine offene Frage kommt vollständig: die Frage selbst und je Option Schlüssel, Beschriftung und Folge — damit ein Agent sie einem Menschen vorlegen kann, ohne etwas zu erfinden.
`frage_beantworten`	`id, key, notiz?`	Beantwortet eine offene Frage. Nur als angemeldeter Mensch über eine OAuth-Verbindung — mit einem Schlüssel oder nach `persona_waehlen` wird der Aufruf abgewiesen. Die Antwort trägt den Namen des Angemeldeten (aus der Sitzung, nicht aus dem Aufruf) und den Vermerk „im Chat".
`seit_wann_neu`	`seit`	Beantwortete Fragen seit einem Zeitpunkt (siehe den Abweichungs-Hinweis auf der REST-Referenz).

Prozesse

Werkzeug	Parameter	Liefert
`prozess_get`	`slug, version?`	Ein Stand eines Prozesses: Schritte, Regeln je Schritt, Lücken, `ueberholt` und `versionen` (jeder Stand mit `gilt_seit`/`gilt_bis`). Ohne `version` der aktuelle, mit `version` genau dieser — so ist nachlesbar, was vor einer Änderung galt. Ein Stand, den es nicht gibt, ist ein Fehler und nicht der neueste.
`prozess_put`	`slug, titel, diagramm_md, schritte, angelegt_von, subjekt_typ?, ersetzt_slug?`	Legt einen Prozess an oder eine neue Version.
`prozess_beenden`	`slug, grund, angelegt_von`	Beendet einen Prozess ohne Nachfolger. Bewusst kein `aussage_beenden`-Werkzeug — das Beenden einer einzelnen Aussage ist eine Menschen-Entscheidung über Web/REST, kein Agenten-Werkzeug; ein Prozess ist die eine Ausnahme, weil sein Beenden Teil der routinemäßigen Regelwerk-Pflege eines Agenten ist.
`prozess_bild`	`slug, schritt`	Das Bild des Schritts, oder ein benanntes leeres Ergebnis.
`kern_render`	`subjekt_id`	Der erzeugte Kern als Markdown, plus Hash.

Personas, Gedächtnis und Vorlagen

persona_put und from_vorlage sind bewusst keine MCP-Werkzeuge — Aufgabe, Grenzen, Stil und Regeln ändert nur ein Mensch mit rw-Schlüssel über die Web-Fläche. Über sich selbst Gedächtnis zu schreiben ist die eine Ausnahme, die Agenten bekommen.

Werkzeug	Parameter	Liefert
`persona_list`	—	Jede Persona mit ihren Kennzahlen.
`persona_get`	`slug`	Eine Persona vollständig, plus ihre Regeln und die 10 jüngsten Gedächtnis-Einträge.
`persona_brief`	`slug, max_gedaechtnis?, max_lehren?`	Der deterministische Markdown-Brief.
`persona_waehlen`	`slug`	Bindet diesen Chat an eine Persona: ab dann gelten ihre Werkzeug-Freigaben und ihr Sichtfeld, und sie ist die Urheberin dessen, was geschrieben wird. Nur über eine OAuth-Verbindung — ein Schlüssel trägt seine Bindung bereits selbst. Nur aktive Personas des eigenen Projekts; jeder Aufruf wird protokolliert. Ohne Wahl bleibt alles wie zuvor.
`firma_get`	—	Die sechs Firmengedächtnis-Felder, lesend. Ändern darf nur ein angemeldeter Mensch — auch über die Schnittstelle; ein Agent in der Sitzung eines Menschen zählt dazu, ein Schlüssel allein nicht.
`memory_search`	`persona_slug, q, art?, limit=20, lesende_persona?, alle=False`	Volltextsuche im Gedächtnis einer Persona. `lesende_persona` ist hier der Sichtbarkeits-Filter (nicht `persona_slug`, das schon bestimmt, wessen Gedächtnis durchsucht wird — bewusst ein anderer Parametername für eine andere Frage).
`memory_put`	`persona_slug, art, text, tags=[], gilt_bis?`	Schreibt einen Gedächtnis-Eintrag.
`vorlagen_list`	—	Der Persona-Vorlagen-Katalog.
`vorlagen_vorschlag`	`bedarf`	Bis zu 3 gerankte Vorlagen für einen Freitext-Bedarf.

Agents: Anwesenheit und Postfach

Modul mcp/agents_tools.py.

Werkzeug	Parameter	Liefert
`agent_herzschlag`	`persona_slug, sitzung, client, status="online", arbeitet_an?, kontext_zeichen?, modell?`	Lebenszeichen einer Sitzung; ein Lese-Schlüssel reicht — ein Herzschlag ist kein Schreiben an Wissen.
`agent_offline`	`persona_slug, sitzung`	Meldet eine Sitzung ausdrücklich ab.
`agents_liste`	—	Jede aktive Persona mit Anwesenheit und Postfach-Zählern, auch ohne je gesendeten Herzschlag.
`nachricht_senden`	`an_persona, text, art="info", betreff?, von_persona?, antwort_auf?, prioritaet="normal"`	Sendet eine Nachricht.
`auftrag_senden`	`an_persona, text, betreff?, von_persona?, prioritaet="normal"`	Kurzform von `nachricht_senden(art="auftrag")`.
`auftrag_status`	`id, status, notiz?`	Setzt den Status eines Auftrags.
`nachricht_an_mensch`	`von_persona, von_sitzung, text, betreff?, art="info", prioritaet="normal", schwere?`	Nachricht/Auftrag an den Menschen — erscheint in „Euer Postfach" der Schaltzentrale. Für Regel-ändernde Entscheidungen bleibt `frage_stellen` der Weg, für Erkenntnisse `hinweis_an_mensch`.
`nachrichten_abholen`	`persona_slug, sitzung, nur_neue=True`	Liest das Postfach einer Sitzung; markiert unzugestellte Nachrichten als zugestellt.
`postfach_stand`	`persona_slug`	Wie viel im Postfach liegt — ohne es anzufassen (kein Zustell-Stempel, kein Schreiben).
`nachricht_gelesen`	`id, persona_slug?`	Markiert eine oder mehrere Nachrichten als gelesen (`id` nimmt auch eine Liste). Bei einem Runden-Beitrag ist `persona_slug` Pflicht — quittiert wird nur der eigene Lesestand.
`runde_eroeffnen`	`titel, frage, teilnehmer, von_persona?, von_sitzung?, slug?`	Eröffnet eine Runde: ein Gespräch mehrerer Personas zu einer Frage (mit Fragezeichen), mindestens zwei Teilnehmer.
`runden_liste`	`persona_slug?, nur_offene=True`	Listet Runden, neueste zuerst.
`runde_lesen`	`slug`	Eine Runde mit allen Beiträgen, dem Deckel je Teilnehmer und den offenen, ausdrücklich gestellten Fragen.
`runde_beitrag`	`slug, text, von_persona?, von_sitzung?, antwort_auf?, frage_an?`	Schreibt in eine Runde. Höchstens drei Beiträge je Persona; danach nur als Antwort auf eine Frage, die ausdrücklich an sie ging. Wer zustimmt, schweigt.
`runde_schliessen`	`slug, ergebnis, von_persona?`	Schließt eine Runde — nur wer sie eröffnet hat, mit einem Ergebnis in einem Satz.

Hall of Lessons

Modul mcp/lehren_tools.py.

Werkzeug	Parameter	Liefert
`lehre_put`	`art, titel, was, lehre, bereich, ursache?, wirkung?, persona_slug?, belege?, regel_vorschlag?, quelle_ref?, herkunft?`	Trägt eine Lehre ein. `ursache` ist clientseitig Pflicht bei `art="fehler"`. `bereich` ist Pflicht — kennen Sie die Zuordnung noch nicht, nehmen Sie `unsortiert`.
`lehre_korrigieren`	`id, bereich?, titel?, was?, lehre?, grund?`	Korrigiert Bereich oder Wortlaut einer bestehenden Lehre. Nicht änderbar: Art, Ursache, Belege, Status, Persona. Wer den Wortlaut korrigiert, schickt den ganzen Text — die Korrektur ersetzt das Feld, sie ergänzt es nicht. Muss der Grund der Korrektur aus der Ursache verschwinden, geht das mit einer Korrektur nicht: dann löst eine neue Lehre die alte ab.
`lehren_suche`	`q?, art?, status?, bereich?, lesende_persona?, limit?`	Durchsucht Lehren; `lesende_persona` filtert nach Sichtbarkeit, dasselbe Muster wie `memory_search`.
`hinweis_an_mensch`	`titel, was, lehre, persona_slug, wirkung?, herkunft?`	Derselbe Schreibweg wie `lehre_put`, fest auf `art="hinweis"`.
`lehre_aufnehmen`	`id, von, notiz?`	Markiert eine Lehre als gesehen und für richtig befunden. `von` ist hier Pflicht — die Kern-Route verlangt es, ein Werkzeug ohne dieses Feld würde immer mit `422` scheitern.
`lehre_regel_vorschlagen`	`id, sache, regel_text, von, titel?, frage?`	Stellt eine Schaltzentrale-Frage, um aus einer Lehre eine Regel zu machen — schreibt sie nie direkt. Gleicher `von`-Hinweis wie oben.

Beurteilung (Personalakte)

Modul mcp/beurteilung_tools.py.

Werkzeug	Parameter	Liefert
`beurteilung_get`	`persona_slug`	Die fünfteilige Personalakten-Ansicht (offene Vorschläge, Gelungenes, selbst gemeldete Fehler, Rückfälle, Rückmeldungen des Menschen).
`rollen_vorschlag`	`persona_slug, feld, neu, begruendung, lehre_ids, von?, alt?`	Schlägt eine Änderung an einem Persona-Feld vor, mit Lehren belegt.

Hall of Fame

Modul mcp/hall_of_fame_tools.py. Nur lesend — die Punktevergabe selbst geschieht im Kern in dem Moment, in dem das zugrundeliegende Ereignis eintritt; kein Agenten-Werkzeug vergibt Punkte oder Daumen.

Werkzeug	Parameter	Liefert
`hall_of_fame`	`woche?`	Die Wochen-Rangliste.
`meine_anerkennung`	`persona_slug`	Eigene Daumen-Gesamtzahl und jüngste Historie einer Persona.

Statistik

Modul mcp/statistik_tools.py.

Werkzeug	Parameter	Liefert
`statistik`	—	Dieselben sechs Blöcke wie `GET /statistik`, unverändert.

Export

Modul mcp/export_tools.py — „Eure Daten gehören euch".

Werkzeug	Parameter	Liefert
`export`	`format?` (`json`\|`markdown`, Standard `json`)	Nur Kopf + Zählung (`GET /export/kopf`) plus Hinweis auf den vollen REST-Weg — der volle Export (jede Aussage mit Geschichte bzw. das komplette Regelwerk) wäre als Werkzeug-Ausgabe eines Sprachmodells unnötig groß. Für den vollen Export: `GET /export?format=json` bzw. `?format=markdown` direkt gegen den Kern.

Sichtfeld

gilt, gilt_am, suche und memory_search (dort als lesende_persona) nehmen die eigene Kennung der aufrufenden Persona entgegen und filtern die Antwort auf ihr sichtfeld (Sichtbarkeit — eine Liste von Bereichen). sache_list macht dasselbe, aber unter einem anderen Parameter (persona_slug, weil persona= auf /sachen schon „gehört dieser Persona" bedeutet) — derselbe Grund, aus dem gehoert_persona ein zweiter, unabhängiger Filter ist. alle=True hebt den Filter bewusst auf und wird als Ereignis protokolliert. Ein 403 („außerhalb des Sichtfelds") ist bei diesen Werkzeugen ein echter Fehler, kein leeres Ergebnis — anders als das dokumentierte 404 von gilt.

Was bewusst kein MCP-Werkzeug ist

persona_put / from_vorlage — Aufgabe, Grenzen, Stil und Regeln ändert nur ein Mensch über die Web-Fläche mit rw-Schlüssel.
aussage_beenden — das Beenden einer einzelnen Aussage ist dieselbe Art Menschen-Entscheidung wie persona_put; nur prozess_beenden bekommt eine Ausnahme, weil das Beenden eines Prozesses Teil der routinemäßigen Regelwerk-Pflege eines Agenten ist.
Ein Daumen-Werkzeug — „Stufe eins: nur der Mensch vergibt."

Beim Schreiben dieser Seite gefundene Abweichung

mcp/beurteilung_tools.pys rollen_vorschlag ruft CoreClient.request(..., json=body) auf, aber CoreClient.request() nimmt json_body, nicht json entgegen — so geschrieben löst das einen TypeError aus, bevor der Kern je erreicht wird; der Aufruf übergibt außerdem kein rw=True, obwohl er schreibt. Hier gemeldet, nicht repariert — außerhalb des Auftrags dieser Dokumentation.