ELO ECM

[!NOTE] English: MCP server for the ELO ECM Suite (ELO Digital Office). Runs locally next to the ELO Client (ELO 25) or ELO Java Client and signs in with the user's own ELO account, so ELO enforces that user's permissions. Beyond search and text extraction it can file documents, set index fields, start and forward workflows, and (optionally) build workflow templates and ELOas rules/IX scripts with syntax checks. Every write is a two-step preview + one-time token. Docs are in German because ELO's user base is mostly DACH; issues in English are welcome.

Ein MCP-Server für das ELO ECM der ELO Digital Office GmbH. Ihr fragt in normaler Sprache, etwa „Zeig mir die offenen Aufgaben zu Rechnung 4711" oder „Bau mir eine Freigabe-Vorlage mit zwei parallelen Prüfern", und die KI arbeitet direkt mit eurem Archiv.

Auf einen Blick

• Jeder MCP-Client: Claude Code, Claude Desktop, Codex, GitHub Copilot, Gemini CLI, Cursor, … (docs/CLIENTS.md)
• Rechte je Person: Der Server läuft lokal beim Anwender und meldet sich mit dessen eigenem ELO-Konto an. ELO prüft jeden Zugriff selbst. Kein Dienstkonto, kein Nachbau von Rechten.
• Mehr als Suchen: Volltext- und Feldsuche, Textauszug aus PDF/Office/E-Mail, wirksame Rechte mit Herkunft, Workflows lesen, starten und weiterleiten.
• Bauen mit Prüfungen: Workflow-Vorlagen als JSON-Bauplan exportieren, ändern und zurückschreiben. ELOas-Regeln, IX-Skripte und Formularseiten hochladen, vorher kompiliert und auf bekannte Fallen geprüft.
• Drei Stufen: Lesen ist immer an. Schreiben (-Schreiben) und Bauen (-Bauen) schaltet ihr einzeln frei. Ohne Schalter sieht die KI die Werkzeuge gar nicht.
• Zweistufig schreiben: Jede Änderung liefert zuerst eine Vorschau und ein Einmal-Token. Erst ein zweiter Aufruf mit Token führt aus.
• Schonend für den Indexserver: eine Anfrage zur Zeit, harte Obergrenzen, keine Massenabfragen über Workflows.
• Keine zusätzlichen Downloads: nutzt Java, Rhino, IX-Client-Bibliothek, PDFBox und POI aus dem installierten ELO Client bzw. ELO Java Client.

Voraussetzungen

[!IMPORTANT] Jede Sitzung baut eine eigene IX-Verbindung mit eurem Konto auf (Client-Name elo-mcp). Ob das bei euch eine zusätzliche ELO-Lizenz belegt, klärt bitte mit eurem ELO-Partner.

Schnellstart

1. Holen, z. B. nach C:\Tools\elo-mcp:
   powershell

   git clone https://github.com/Herzog-GmbH/elo-mcp.git C:\Tools\elo-mcp

2. Zugangsdaten hinterlegen, einmalig und selbst im Terminal (nicht von der KI eintippen lassen). Das Passwort wird per DPAPI für euer Windows-Konto verschlüsselt:
   powershell

   powershell -NoProfile -ExecutionPolicy Bypass -File C:\Tools\elo-mcp\Set-EloCredential.ps1

3. Prüfen, ohne ELO-Verbindung:
   powershell

   powershell -NoProfile -ExecutionPolicy Bypass -File C:\Tools\elo-mcp\test\offline.ps1

4. Eintragen, hier in Claude Code (andere Clients: docs/CLIENTS.md). Die IX-URL steht im Anmeldeprofil des ELO Java Client oder kommt von eurem ELO-Administrator:
   powershell

   claude mcp add elo --scope user -- powershell -NoProfile -ExecutionPolicy Bypass -File "C:\Tools\elo-mcp\elo-mcp.ps1" -IxUrl "https://elo.example.com:9093/ix-Archiv/ix"

5. Testen: In einer neuen Sitzung „Wer bin ich in ELO?" fragen. Das ruft elo_whoami auf und zeigt Konto, Server, IX-Version und freigeschaltete Stufen.

Ihr wollt, dass eure KI das selbst einrichtet? Gebt ihr diesen Satz: „Richte den ELO-MCP-Server nach der AGENTS.md in diesem Ordner ein."

Claude Desktop: als Paket installieren

Für Claude Desktop gibt es den Server auch als Paket (MCPB), ohne Git und ohne Konfigurationsdatei:

1. Aus dem neuesten Release elo-mcp-<version>.mcpb und Set-EloCredential.ps1 laden.
2. Zugangsdaten hinterlegen, selbst im Terminal:
   powershell

   powershell -NoProfile -ExecutionPolicy Bypass -File "$env:USERPROFILE\Downloads\Set-EloCredential.ps1"

3. In Claude Desktop unter Einstellungen → Erweiterungen → Erweiterte Einstellungen → Erweiterung installieren (Settings → Extensions → Advanced settings → Install Extension) die .mcpb-Datei wählen.
4. IX-URL eintragen. Schreiben und Bauen nur bei Bedarf einschalten. Zugangsdatei und Client-Ordner bleiben leer, solange ihr die Standards nutzt. Für ein zweites Archiv (z. B. Test) die Felder „Archiv 2“ ausfüllen und beiden Archiven einen Kurznamen geben, siehe Zwei Archive.
5. In einem neuen Chat „Wer bin ich in ELO?" fragen.

Im Paket stecken nur die Skripte aus diesem Repo (rund 70 KB). Java und die ELO-Bibliotheken kommen wie sonst aus dem installierten ELO Client. Für ein Update installiert ihr einfach die neue .mcpb.

Schalter

Alle Schalter stehen hinter dem Skriptpfad in der Client-Konfiguration.

Zwei Archive

Ein Eintrag kann zwei Archive bedienen, z. B. Produktiv nur lesend und Test mit allen Stufen:

claude mcp add elo --scope user -- powershell -NoProfile -ExecutionPolicy Bypass -File "C:\Tools\elo-mcp\elo-mcp.ps1" -IxUrl "https://elo.example.com:9093/ix-Archiv/ix" -Name Produktiv -IxUrl2 "https://elo-test.example.com:9093/ix-Archiv/ix" -Name2 Test -Schreiben2 -Bauen2

• Jedes Werkzeug hat dann den Parameter archiv (Produktiv oder Test). Ohne Angabe gilt das erste Archiv. Ihr sagt der KI einfach „im Test“ oder „in Produktiv“.
• Die Stufen gelten je Archiv. Im Beispiel kann die KI in Produktiv nichts ändern, auch wenn sie es versucht. Schreib- und Bauwerkzeuge sagen in ihrer Beschreibung, in welchem Archiv sie gehen.
• Jedes Archiv läuft in einem eigenen Java-Prozess, der erst beim ersten Aufruf startet. Verbindungen, Zwischenspeicher und Tokens mischen sich nicht. Ein Token aus einer Vorschau im Test wirkt nie in Produktiv.
• elo_whoami, jede Vorschau und das Protokoll nennen das Archiv. Objekt-IDs, Masken und Vorlagen gelten nur im jeweiligen Archiv.

Werkzeuge

Stufe 1: lesen (immer an)

Stufe 2: arbeiten (-Schreiben)

Feldwerte werden vorher gegen die Maske geprüft: Feld vorhanden, Länge, Zahl, Datum (31.02. wird abgelehnt), Stichwortliste bei „nur Liste". Datumsfelder schreibt der Server im ELO-Format JJJJMMTT000000.

Stufe 3: bauen (-Bauen)

Die Prüfungen beim Bauen stammen alle aus echten Störungen:

• Workflows: genau ein Start, mindestens ein Ende, alle Kanten auf vorhandene Knoten, jeder Knoten erreichbar und mit Weg zum Ende, jeder Knoten außer Ende hat einen Nachfolger (sonst bleibt der Vorgang hängen), Entscheidung mit Bedingung, Sammler mit festem Zähler (0 leitet beim ersten Vorgänger weiter, -1 bleibt nach übersprungenen IF-Zweigen hängen), Bearbeiter und Formulare existieren.
• ELOas-Regeln: XML wohlgeformt, jeder Skriptteil wird mit Rhino kompiliert.
• IX-Skripte: kompiliert, jeder //@include ist auflösbar, @include steht nur in den Kopfzeilen, nur ASCII. Ein nicht auflösbarer Include stoppt sonst den ganzen Skript-Motor des Indexservers.

Neu laden (ELOas, IX-Skripte) und „Aktualisieren" im Formulardesigner bleiben Handarbeit. Das sagt der Server nach jeder Änderung dazu.

Sicherheit

• Eigenes Konto: ELO prüft jeden Zugriff mit den Rechten der angemeldeten Person. Ein zentraler Server bräuchte ein Dienstkonto mit Hauptadministrator-Recht: Die Anmeldung im Namen anderer (runAsUser) lehnt der Indexserver für normale Konten ab. Ein solches Konto vermeidet dieser Server bewusst, er läuft lokal mit dem Konto der Person.
• Zugangsdaten: per DPAPI verschlüsselt, nur für euer Windows-Konto lesbar. Der Vorschalt entschlüsselt sie erst beim Java-Start und gibt sie nur an den Java-Prozess weiter.
• Zweistufig: Erster Aufruf = Prüfung + Vorschau + Token. Das Token gilt 5 Minuten, einmal, nur für exakt dieselben Argumente und nur, wenn sich das Objekt seit der Vorschau nicht verändert hat (Fingerabdruck aus Name, Maske, Indexfeldern, Sperre, Version). Die Hinweise an die KI verlangen, die Vorschau zu zeigen und auf Zustimmung zu warten.
• Nicht im Code: Löschen, Verschieben, Rechte und Masken ändern. Das ist nicht abgeschaltet, das gibt es schlicht nicht.
• Protokoll: Jede Ausführung, auch fehlgeschlagene, steht in %LOCALAPPDATA%\elo-mcp\protokoll-JJJJ-MM.jsonl (Zeit, Konto, Server, Werkzeug, Argumente, Ergebnis).
• Keine Wiederholung beim Schreiben: Lesewerkzeuge melden sich nach einer abgelaufenen Sitzung einmal neu an. Schreibende nie, damit nichts doppelt passiert.
• Fremder Text: Dokumentinhalte (elo_get_text) können Anweisungen an die KI enthalten (Prompt-Injection). Lest deshalb jede Vorschau, bevor ihr zustimmt.

Start und Speicher

MCP-Clients starten jeden Server einmal je Sitzung. Eine JVM je Sitzung kostet rund 650 MB, auch wenn ELO nie gebraucht wird. Deshalb steht elo-mcp.ps1 als schlanker Vorschalt (rund 75 MB) vor Java:

• initialize, tools/list und ping beantwortet der Vorschalt aus %LOCALAPPDATA%\elo-mcp\werkzeuge-<hash>.txt. Nach einer Änderung an Code oder Schaltern holt die erste Sitzung die Liste einmal von Java.
• Java startet erst beim ersten Werkzeugaufruf (2–8 s) und endet nach 10 Minuten ohne Aufruf. Die JVM läuft mit -XX:+UseSerialGC -Xms32m -XX:TieredStopAtLevel=1 (rund 90–130 MB). Bei zwei Archiven gilt das je Archiv.

Grenzen

• Nur Windows und nur stdio (kein HTTP-Server). Der Kern unter src\ läuft überall, wo Rhino und die IX-Client-Bibliothek laufen. Ein Startskript für andere Systeme gibt es noch nicht.
• Kein Text aus .doc, .msg und Scans ohne Textebene (kein OCR).
• Links nur als elodms://(GUID) für den Java Client, noch nicht für den Web Client.
• Beim Bauen nur die Knotentypen 1–6 (Start, Person, Verteiler, Entscheidung, Sammler, Ende). Vorlagen mit Zyklus, Serverübergabe oder Subworkflow lassen sich exportieren, aber nicht zurückschreiben.
• Kein Neuladen von ELOas/IX-Skripten und kein Veröffentlichen.

Aufbau

Fallen der IX-API, auf die wir beim Bau gestoßen sind, stehen in docs/FALLEN.md.

Mitmachen

Issues und Pull Requests sind willkommen, gern auch mit Erfahrungen aus anderen ELO-Versionen. Bitte keine internen Daten (Hostnamen, Benutzer, Objekt-IDs, Mandantennamen) in Issues, Logs oder Testdateien. Vor einem Pull Request test\offline.ps1 laufen lassen. Sicherheitslücken bitte nicht öffentlich melden, sondern wie in SECURITY.md beschrieben.

Lizenz und Marken

MIT, siehe LICENSE. Ohne Gewähr: Probiert Schreiben und Bauen zuerst an einem Testarchiv aus.

Dies ist kein Produkt der ELO Digital Office GmbH und wird von ihr weder unterstützt noch geprüft. ELO ist eine Marke der ELO Digital Office GmbH. Die ELO-Bibliotheken sind nicht Teil dieses Repos und nicht im Paket. Sie kommen aus eurem lizenzierten ELO Java Client.