FEDEO/docs/technik/mcp.md

FEDEO MCP

Dokumentenablage und Dateiübertragung

Die Werkzeuge unter documents.* stellen die Dokumentenablage und den Zugriff auf gespeicherte Dateien bereit. Alle arbeiten im aktiven Mandanten und schließen archivierte Dateien aus. Portalbenutzer haben keinen Zugriff, auch wenn ihrer Rolle Dokumentenrechte zugewiesen wurden.

Werkzeug	Funktion
documents.inbox.list / .count	Offene Dokumente suchen bzw. zählen
documents.folders.list / documents.types.list	Verfügbare Ordner und Dokumenttypen laden
documents.assignment_kinds.list	Unterstützte Zuordnungsarten anzeigen
documents.assignments.search	Zuordnungsziele nach kind und optional search suchen
documents.inbox.assignments.get	Bestehende Zuordnungen eines offenen Dokuments laden
documents.inbox.suggestion.get / .refresh	KI-Ablagevorschlag abrufen bzw. erneut anfordern
documents.inbox.file	Dokument mit Ordner, Typ und optionalen Zuordnungen ablegen
documents.inbox.archive	Offenes Dokument archivieren
documents.files.list / .get	Gespeicherte Dateien suchen bzw. Details und vorhandenen extrahierten Text laden
documents.files.download	Originaldatei als Download-URL oder Base64 abrufen
documents.files.upload	PDF oder Scan in die Dokumentenablage hochladen

Listen und Suchwerkzeuge verwenden limit und offset wie unten beschrieben. search ist auf 200 Zeichen begrenzt. documents.files.list unterstützt zusätzlich folder, type, mimeType sowie Zuordnungsfilter wie project, customer, incominginvoice und createddocument. folder: null filtert Dateien auf der Hauptebene; ohne folder werden alle Ordner durchsucht. Die id eines Dokuments ist immer die Datei-UUID, keine Rechnungs- oder Belegnummer.

Lesende Werkzeuge und Downloads benötigen documents.read; Upload, Ablegen, Archivieren und erneute KI-Erkennung benötigen documents.write. Beide Rechte sind in den Bootstrap-Administratorrechten enthalten. Anderen Rollen müssen sie ausdrücklich zugewiesen werden. Scanner-Zugangsdaten werden für MCP-Uploads nicht benötigt.

PDF-Download

Zunächst die Datei-UUID beispielsweise über documents.files.list mit createddocument oder incominginvoice ermitteln. Der Aufruf erfolgt über tools/call mit diesen Parametern:

{"name":"documents.files.download","arguments":{"id":"00000000-0000-4000-8000-000000000001"}}

Standardmäßig enthält das Ergebnis url, method: "GET", authentication: "Bearer", Dateiname, MIME-Type und Größe. Die URL verwendet API_BASE_URL und den Pfad /api/mcp/files/<id>/content; ohne konfigurierte Basis ist sie relativ. Bei https://app.fedeo.de/backend lautet der Pfad somit https://app.fedeo.de/backend/api/mcp/files/<id>/content.

Die URL ist kein öffentlicher Freigabelink: Der GET-Aufruf benötigt denselben Authorization: Bearer <MCP-Token>-Header wie der MCP-Aufruf. Berechtigung, Mandant, Portalzugang und Archivstatus werden beim Download erneut geprüft. Der Inhalt wird als Attachment gestreamt; interne Speicherpfade und Tokens erscheinen nicht im Werkzeugergebnis.

Mit "format":"base64" liefert das Werkzeug stattdessen contentBase64 direkt im Ergebnis, begrenzt auf 20 MiB. Für größere Dateien den URL-Abruf verwenden. Der Download gibt die gespeicherte Originaldatei unverändert zurück; er erzeugt oder konvertiert keine PDFs.

Upload und Ablage

{"name":"documents.files.upload","arguments":{"filename":"rechnung.pdf","contentBase64":"<Base64-Dateiinhalt>"}}

Uploads unterstützen vollständige PDF-, JPEG-, PNG- und TIFF-Dateien bis 20 MiB. contentBase64 muss normales, gepaddetes Base64 ohne Data-URL-Präfix enthalten. Dateiname, Dateisignatur und bei PDFs die Abschlussmarkierung werden geprüft. Die Größenbegrenzung des MCP-JSON-Endpunkts berücksichtigt den Base64-Aufschlag; sie gilt für den gesamten Request einschließlich etwaiger Batch-Aufrufe.

Der Upload liefert id, created, checksum, filename, mimeType und size. Er speichert das Original in der Dokumentenablage und stellt die bestehende KI-Vorbereitung in die Warteschlange. Gleicher Dateiname und gleicher Inhalt liefern bei Wiederholung dieselbe ID mit created: false, auch nach Ablage oder Archivierung. Ein anderer Inhalt unter demselben Namen wird abgewiesen. Fehlgeschlagene Uploads rollen die Datenbankänderungen zurück und bereinigen das Speicherobjekt.

Anschließend Ordner und Dokumenttyp auswählen und die zurückgegebene UUID ablegen:

{"name":"documents.inbox.file","arguments":{"id":"00000000-0000-4000-8000-000000000001","folder":null,"type":"00000000-0000-4000-8000-000000000002","assignments":{"project":42}}}

folder: null steht für die Hauptebene. type ist erforderlich. Zuordnungen verwenden numerische IDs, außer check und authProfile (UUIDs). Nur angegebene Zuordnungen werden geändert; null entfernt eine Zuordnung. Ordner, Dokumenttyp und Zuordnungsziele müssen im aktiven Mandanten verfügbar sein. Ein fester Dokumenttyp des Ordners wird berücksichtigt. Nach erfolgreicher Ablage verschwindet das Dokument aus inbox.list, bleibt aber über files.list, .get und .download erreichbar.

Listen und Pagination

Alle datensatzbasierten MCP-Listen und Suchwerkzeuge unterstützen limit (ganze Zahl 1–100, Standard 25) und offset (ganze Zahl ab 0). Das Wiki behält Standard 50. Die statische Liste der Beleg-Steuertypen benötigt keine Pagination.

Die Antwort behält rows und ergänzt:

{"pagination":{"limit":25,"offset":0,"hasMore":true,"nextOffset":25}}

Für die nächste Seite dieselben Filter und limit mit offset = pagination.nextOffset verwenden. Bei hasMore = false ist nextOffset = null. Die Sortierung enthält eine eindeutige ID als Tie-Breaker. Gleichzeitiges Anlegen, Archivieren oder Ändern sortierrelevanter Felder kann wie bei jeder Offset-Pagination Seiten verschieben; die Abfragen bilden keinen gemeinsamen Datenbanksnapshot.

Auch accounting.incoming_invoices.files.list ist paginiert. Archivierte Einträge bleiben entsprechend der bisherigen MCP-Regel ausgeblendet.

Ausgangsbeleg-Schemas

tools/list beschreibt die Unterfelder von rows, address und report für Beleg-Erstellung und -Bearbeitung sowie Positionen und Report beim Finalisieren. Positionen verwenden costCentre, der Beleg selbst costcentre. unit ist die numerische Einheiten-ID. Preise werden numerisch übergeben. Reportwerte liefert der Aufrufer; MCP berechnet sie nicht. Zusätzliche modulspezifische Objektfelder bleiben zulässig.

Stammdaten und Kostenstellen

Die folgenden Namensräume besitzen jeweils create, update und archive:

Namensraum nach masterdata.	Anlegen: Pflichtfelder	Automatischer Nummernkreis
customers	name	customerNumber
vendors	name	vendorNumber
contacts	fullName oder firstName/lastName	–
products	name, unit	–
services	name	–
cost_centres	name	number
branches	name	number
teams	name	–
vehicles	name	–
inventory_items	name	articleNumber

Nummernfelder sind beim Anlegen optional; ohne Angabe wird der bestehende Mandanten-Nummernkreis verwendet. Dieser muss in FEDEO eingerichtet sein. Bereits belegte Nummern werden übersprungen; explizite doppelte Nummern werden abgewiesen, auch wenn der vorhandene Eintrag archiviert ist.

update verlangt id und mindestens ein bearbeitbares Feld. Kostenstellen verwenden UUIDs, die übrigen Bereiche numerische IDs. Nur angegebene Felder werden geändert. Nullable Felder lassen sich mit null leeren, Arrays werden vollständig ersetzt. Die Unterfelder von infoData werden beim Update zusammengeführt. Systemfelder wie Mandant, ID beim Anlegen, Archivstatus und Änderungsautor sind nicht frei schreibbar.

Beispiel zum Anlegen einer Kostenstelle:

{"name":"masterdata.cost_centres.create","arguments":{"name":"Werkstatt","description":"Kosten der Werkstatt","branch":3}}

Über cost_centres.update lassen sich parentCostcentre, project, branch, vehicle, inventoryitem und profiles pflegen. Eltern müssen zum aktiven Mandanten gehören und dürfen nicht archiviert sein; Selbstbezüge und neue Hierarchie-Zyklen werden abgewiesen. Die HTTP-Ressourcenroute und MCP verwenden denselben Hierarchieprüfer.

Fremdschlüssel und bekannte Verknüpfungen in JSON-Feldern werden auf Mandantenzugehörigkeit und Verfügbarkeit geprüft. Globale Mengeneinheiten bleiben lesbar; es werden keine Schreibwerkzeuge für diese mandantenübergreifenden Daten registriert.

Artikel- und Leistungsänderungen stoßen die bestehende Leistungspreisberechnung an. Bei zusammengesetzten Leistungen stammen Preise aus der Zusammensetzung; für eine manuelle Preisvorgabe die Leistung mit priceUpdateLocked: true sperren. Manuelle sellingPrice-Werte werden mit sellingPriceComposed.total synchronisiert.

Schreibvorgänge einschließlich Nummernvergabe und Preisberechnung laufen in einer Transaktion. Historieneinträge werden über den vorhandenen History-Service erstellt; für Niederlassungen und Teams unterstützt dieser derzeit keine entitätsbezogene Historie. Die Änderungsfelder enthalten auch dort den ausführenden Benutzer und Zeitpunkt. Archivieren liefert { "id": ..., "success": true, "action": "archived" }; der archivierte Datensatz wird entsprechend der MCP-Regel nicht zurückgegeben.

Zusätzlich verfügbar: masterdata.customers.search sowie get für Kontakte, Niederlassungen, Teams und Fahrzeuge. Die vorhandene Kundensuche unter organisation.customers.search bleibt erhalten.

Berechtigungen

Schreibwerkzeuge benötigen masterdata.<Namensraum>.write, lesende Werkzeuge .read. Die neuen Schreibrechte sind in den Bootstrap-Administratorrechten enthalten. Bestehende Nicht-Administratorrollen erhalten nicht automatisch Schreibzugriff; ihnen müssen die gewünschten Rechte ausdrücklich zugewiesen werden. Globale Administratoren verwenden die bestehende Admin-Ausnahme.

Verifikation

Die MCP-Tests prüfen unter anderem seitenweisen Abruf, Tenant-Filter in den erzeugten SQL-Abfragen, Create/Update/Archive, unbekannte Systemfelder, Fremdmandanten-Verknüpfungen, Kostenstellen-Zyklen, Nummernkollisionen, Transaktions-Rollback und die Preisneuberechnung. Die Datenbanktests verwenden isolierte Fixtures bzw. den Drizzle-Proxy; sie schreiben keine produktiven Daten.