Zum Inhalt

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, danach POST /api/v1/anmeldung/token. Das Token geht als Authorization: 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.json nennt Endpunkt, Anmeldeart und die Werkzeugliste.
  • Anmeldung: Kopfzeile X-Makom-Api-Key mit einem Schlüssel, der mit mk_ beginnt. Ohne Schlüssel antwortet der Server mit 401.
  • Methoden: tools/list und tools/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.