Schnittstelle
Schnittstelle und KI-Agenten
Für Entwickler und für eigene KI-Agenten. RAPPORTWERX hat eine App-Schnittstelle (REST) und einen MCP-Server. Beide arbeiten mit den Rechten des Betriebs, jeder Betrieb sieht nur seine Daten.
Grundsätze
- Kein eingebauter KI-Assistent. RAPPORTWERX ruft nie ein Sprachmodell auf. Wer einen Agenten nutzt, bringt ihn selbst mit und verbindet ihn über MCP.
- Ab Werk aus. Der KI-Zugang ist je Betrieb abgeschaltet. Der Inhaber schaltet ihn unter „KI-Zugang“ im Konto ein und legt einen Schlüssel an.
- Menschen entscheiden. Kein Werkzeug unterschreibt oder schließt Rapporte ab, versendet Behinderungsanzeigen, schreibt Rechnungen fest, schaltet Abos oder löscht Konten und sperrt Nutzer.
- Eigene Rechte. Jeder Schlüssel trägt nur die Werkzeuge, die der Inhaber ihm gibt. Die Rolle der Person bleibt maßgeblich.
REST-Schnittstelle
Die Beschreibung steht als OpenAPI-Datei. Sie ist die Quelle der Wahrheit für Web, Apps und Agenten.
- Basis:
/api/v1, JSON, Fehler als{ "fehler": "<code>", "meldung": "…", "felder": {} }. - Anmeldung für Apps:
POST /api/v1/anmeldung/code, danachPOST /api/v1/anmeldung/token. Das Token geht alsAuthorization: Bearer …mit. - Schreibende Aufrufe sind idempotent: Rapport, Mangel und Zeitbuchung mit einer vom Client vergebenen UUID, alle schreibenden Fachaufrufe zusätzlich mit dem Header
Idempotency-Key. - Nach Ablauf von Test oder Abo antworten schreibende Aufrufe mit 402
berechtigung_abgelaufen. Lesen und Export bleiben möglich.
MCP-Server
- Endpunkt:
POST /mcp/v1(JSON-RPC, Streamable HTTP, Protokollversion 2025-06-18). - Erkennung:
GET /.well-known/mcp.jsonnennt Endpunkt, Anmeldeart und die Werkzeugliste. - Anmeldung: Kopfzeile
X-Makom-Api-Keymit einem Schlüssel, der mitmk_beginnt. Ohne Schlüssel antwortet der Server mit 401. - Methoden:
tools/listundtools/call.
Beispiel, Werkzeuge auflisten:
curl -s -X POST https://<deine-adresse>/mcp/v1 \
-H 'Content-Type: application/json' -H 'X-Makom-Api-Key: mk_…' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
Werkzeuge
| Bereich | Werkzeuge |
|---|---|
| Konto | kern.me |
| Aufträge und Rapporte | auftrag.liste, auftrag.anlegen, rapport.liste, rapport.lesen, rapport.entwurf |
| Kunden | kunde.suchen, kunde.anlegen |
| Zeit | zeit.woche |
| Plan | plan.woche, plan.termin_anlegen, plan.wartung_faellig, plan.wartung_anlegen, termin.angebote |
| Material | material.liste, material.buchen |
| Abnahme | abnahme.maengel, abnahme.mangel_anlegen, abnahme.behinderungsanzeige_entwurf |
| Zusatzleistung (Modul Rapport) | zusatz.liste, zusatz.entwurf (Senden bleibt beim Menschen) |
| Startansicht des Büros (Modul Rapport) | auftragsampel.lesen, wartet_auf_kunde.lesen (nur Lesen) |
| Übergabe und Auswertung | uebergabe.offene_positionen, auswertung.baustelle, geldradar.lesen |
| Nachweise | nachweise.faelligkeiten, nachweis.unterlagen, nachweis.unterweisungen, nachweis.unterlage_anlegen, checkliste.liste, objektakte.lesen |
Weitere Werkzeuge für Rechnung, Fristen, Endkunden-Links und Branchenwissen (rechnung.*, fristen.faelligkeiten, links.liste, wissen.*) schaltet der Betreiber der Installation getrennt zu. Die vollständige Liste einer Installation steht immer in /.well-known/mcp.json.
Rechte und Spuren
Lesende Werkzeuge liefern, was die Rolle des Schlüssels sehen darf. Schreibende Werkzeuge legen Entwürfe an (Rapport-Entwurf, Behinderungsanzeige-Entwurf), die ein Mensch prüft und abschließt.
Hinweis
Das ist technische Dokumentation, keine Rechtsberatung. Datenschutz und Auftragsverarbeitung für den KI-Zugang stehen in der KI-Transparenz und im Auftragsverarbeitungsvertrag.