ELO ECM MCP

[!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.

Un servidor MCP para ELO ECM de ELO Digital Office GmbH. Ustedes preguntan en lenguaje natural, por ejemplo: „Muéstrame las tareas abiertas de la factura 4711" o „Construye una plantilla de aprobación con dos revisores en paralelo", y la IA trabaja directamente con su archivo.

De un vistazo

• Cualquier cliente MCP: Claude Code, Claude Desktop, Codex, GitHub Copilot, Gemini CLI, Cursor, … (docs/CLIENTS.md)
• Permisos por persona: El servidor se ejecuta localmente junto al usuario y se registra con su propia cuenta ELO. ELO verifica cada acceso por sí mismo. Sin cuenta de servicio, sin réplica de permisos.
• Más que buscar: Búsqueda de texto completo y por campos, extracción de texto de PDF/Office/correo electrónico, permisos efectivos con origen, leer, iniciar y reenviar flujos de trabajo.
• Construir con verificaciones: Exportar, modificar y reescribir plantillas de flujo de trabajo como plan de construcción JSON. Subir reglas ELOas, scripts IX y páginas de formulario, previamente compilados y verificados contra trampas conocidas.
• Tres niveles: La lectura siempre está activa. Escribir (-Schreiben) y construir (-Bauen) se activan por separado. Sin el interruptor, la IA ni siquiera ve las herramientas.
• Escritura en dos pasos: Cada cambio entrega primero una vista previa y un token de un solo uso. Solo una segunda llamada con el token ejecuta la acción.
• Cuidadoso con el servidor de índices: una solicitud a la vez, límites máximos estrictos, sin consultas masivas sobre flujos de trabajo.
• Sin descargas adicionales: utiliza Java, Rhino, la biblioteca del cliente IX, PDFBox y POI del ELO Client o ELO Java Client instalado.

Requisitos

	Probado o requerido
Servidor ELO	Indexserver 25.00 (ELO 25). Las versiones anteriores con API Java deberían funcionar, pero no están verificadas.
ELO Client	instalado en el equipo donde se ejecuta la IA: el ELO Client 25 o el más antiguo ELO Java Client. Probado contra Indexserver 25.00 con el ELO Client 25 (biblioteca del cliente IX 25.00, Rhino 1.9, PDFBox 3) y con el ELO Java Client (biblioteca del cliente IX 20.09). Se busca en Programme\ELO Client, luego Programme\ELO Java Client, de lo contrario -ClientDir.
Windows	Windows 10/11 con Windows PowerShell 5.1 (powershell.exe). PowerShell 7 no es suficiente; el prelanzador necesita System.Web.Extensions.
Cuenta ELO	una cuenta de usuario normal. La IA puede hacer exactamente lo que la cuenta permite.
Certificado	En https, el certificado del servidor debe ser de confianza en el almacén de certificados de Windows (Java usa Windows-ROOT).

[!IMPORTANT] Cada sesión establece su propia conexión IX con su cuenta (nombre de cliente elo-mcp). Si esto ocupa una licencia ELO adicional en su caso, aclárelo con su socio ELO.

Inicio rápido

1. Obtener, por ejemplo, en C:\Tools\elo-mcp:

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

2. Guardar las credenciales, una sola vez y usted mismo en la terminal (no deje que la IA las escriba). La contraseña se cifra con DPAPI para su cuenta de Windows:

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

3. Verificar, sin conexión ELO:

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

4. Registrar, aquí en Claude Code (otros clientes: docs/CLIENTS.md). La URL IX está en el perfil de inicio de sesión del ELO Java Client o la proporciona su administrador ELO:

   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. Probar: En una nueva sesión, pregunte „¿Quién soy en ELO?". Esto llama a elo_whoami y muestra cuenta, servidor, versión IX y niveles activados.

¿Quiere que su IA haga la configuración por sí misma? Dele esta frase: „Configura el ELO-MCP-Server según la AGENTS.md en esta carpeta."

Claude Desktop: instalar como paquete

Para Claude Desktop, el servidor también está disponible como paquete (MCPB), sin Git y sin archivo de configuración:

1. Descargar del último release elo-mcp-<version>.mcpb y Set-EloCredential.ps1.
2. Guardar las credenciales, usted mismo en la terminal:

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

3. En Claude Desktop, en Configuración → Extensiones → Configuración avanzada → Instalar extensión (Settings → Extensions → Advanced settings → Install Extension), seleccione el archivo .mcpb.
4. Ingresar la URL IX. Active escritura y construcción solo si es necesario. El archivo de credenciales y la carpeta del cliente permanecen vacíos mientras use los estándares. Para un segundo archivo (p. ej., prueba), complete los campos „Archivo 2" y asigne un nombre corto a ambos archivos; consulte Dos archivos.
5. En un nuevo chat, pregunte „¿Quién soy en ELO?".

El paquete contiene solo los scripts de este repositorio (aproximadamente 70 KB). Java y las bibliotecas ELO provienen, como siempre, del ELO Client instalado. Para una actualización, simplemente instale el nuevo .mcpb.

Interruptores

Todos los interruptores están detrás de la ruta del script en la configuración del cliente.

Interruptor	Efecto
-IxUrl <url>	URL IX del servidor ELO (obligatorio, alternativamente variable de entorno ELO_IX_URL)
-Schreiben	Activar nivel 2: archivar, nueva versión, campos de índice, iniciar flujo de trabajo, reenviar tarea
-Bauen	Activar nivel 3: plantillas de flujo de trabajo, scripts, reglas ELOas, páginas de formulario. Preferiblemente solo contra un archivo de prueba.
-CredentialFile <pfad>	otras credenciales, p. ej., una segunda cuenta para el archivo de prueba. Estándar %LOCALAPPDATA%\elo-mcp\elo-credential.xml
-ClientDir <pfad>	carpeta del ELO Client o ELO Java Client, si no está en Programme
-Archiv "<name>"	nombre del archivo en las indicaciones para la IA, p. ej., "der Muster GmbH (Test)"
-TextDatumJJJJMMTT	regla interna de algunos archivos: los campos de texto cuyo nombre termina en DAT/DATUM reciben fechas como JJJJMMTT
-LeerlaufMinuten <n>	finalizar Java después de tantos minutos sin llamadas (estándar 10, no menos de 5)
-Direkt	sin prelanzador, iniciar Java inmediatamente (alternativa en caso de problemas, solo un archivo)
-IxUrl2 <url>	segundo archivo, p. ej., el archivo de prueba (ver más abajo)
-Name <name>, -Name2 <name>	nombres cortos de los dos archivos para el parámetro archiv, p. ej., Produktiv y Test (estándar 1 y 2)
-Schreiben2, -Bauen2	niveles solo para el segundo archivo
-CredentialFile2 <pfad>, -Archiv2 "<name>"	credenciales (estándar: las mismas que para el primero) y nombre del archivo para el segundo archivo

Dos archivos

Una entrada puede atender dos archivos, p. ej., producción solo lectura y prueba con todos los niveles:

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

• Cada herramienta tiene entonces el parámetro archiv (Produktiv o Test). Sin especificar, se aplica el primer archivo. Simplemente diga a la IA „en prueba" o „en producción".
• Los niveles se aplican por archivo. En el ejemplo, la IA no puede cambiar nada en producción, incluso si lo intenta. Las herramientas de escritura y construcción indican en su descripción en qué archivo funcionan.
• Cada archivo se ejecuta en su propio proceso Java, que solo se inicia con la primera llamada. Las conexiones, cachés y tokens no se mezclan. Un token de una vista previa en prueba nunca funciona en producción.
• elo_whoami, cada vista previa y el protocolo mencionan el archivo. Los IDs de objeto, máscaras y plantillas solo son válidos en el archivo respectivo.

Herramientas

Nivel 1: leer (siempre activo)

Herramienta	Propósito
elo_whoami	cuenta, servidor, versión IX, niveles activados
elo_search	iSearch sobre título, texto completo y campos de índice, opcionalmente limitado a una carpeta con sus subcarpetas, máximo 50 resultados
elo_find_by_fields	búsqueda en base de datos por máscara y campos de índice, comodín *. Sin campo o nombre, se rechaza
elo_list	contenido de carpeta, un nivel, máximo 300
elo_get_object	metadatos, campos de índice con etiqueta, ruta, versión actual, enlace elodms://
elo_get_versions	lista de versiones, más reciente primero
elo_get_text	texto de PDF (con capa de texto), DOCX, XLSX, PPTX, XLS, EML y archivos de texto, máximo 50.000 caracteres por llamada, continuar leyendo con abZeichen
elo_user_rights	permisos funcionales efectivos de un usuario con origen (directo o a través de qué grupo, también anidado)
elo_workflow_templates	todas las plantillas de flujo de trabajo
elo_workflow	plantilla o flujo de trabajo en ejecución/finalizado en detalle: nodos, responsables, scripts, formulario, configuración JSON, conexiones
elo_workflows_of_object	flujos de trabajo en ejecución (con nodos activos) o finalizados para exactamente un objeto
elo_my_tasks	tareas propias, también a través de grupos
elo_workflow_export	plantilla como plan de construcción JSON (formato)

Nivel 2: trabajar (-Schreiben)

Herramienta	Propósito
elo_create_folder	crear carpeta (solo máscaras de carpeta), advierte sobre nombres duplicados y campos obligatorios vacíos
elo_create_document	archivar archivo local como documento (solo máscaras de documento), máximo 50 MB
elo_new_version	nueva versión. Rechaza un archivo idéntico, advierte sobre extensión diferente
elo_set_fields	establecer campos de índice y nombre corto, vista previa anterior → nuevo
elo_start_workflow	iniciar flujo de trabajo desde plantilla, advierte si la misma plantilla ya está en ejecución
elo_forward_task	reenviar tarea. Con varios sucesores, es obligatorio especificar. Nodos con formulario solo con trotzFormular, porque las validaciones de formulario no se ejecutan a través de la API

Los valores de campo se verifican previamente contra la máscara: campo existente, longitud, número, fecha (31.02. se rechaza), lista de palabras clave en „solo lista". Los campos de fecha se escriben en formato ELO JJJJMMTT000000.

Nivel 3: construir (-Bauen)

Herramienta	Propósito
elo_workflow_build	crear o reemplazar plantilla desde plan de construcción (ID y nombre se mantienen). Vista previa con lista de cambios, copia de seguridad .ewf antes y después
elo_script_update	nueva versión de un documento bajo Administration (regla ELOas, script IX, página de formulario …), vista previa con comparación de líneas, la codificación se mantiene
elo_script_create	nuevo documento bajo Administration, máscara, permisos y tipo del modelo

Las verificaciones al construir provienen todas de fallos reales:

• Flujos de trabajo: exactamente un inicio, al menos un final, todas las aristas apuntan a nodos existentes, cada nodo alcanzable y con camino al final, cada nodo excepto el final tiene un sucesor (de lo contrario, el proceso se queda colgado), decisión con condición, recolector con contador fijo (0 reenvía al primer predecesor, -1 se queda colgado después de ramas IF omitidas), responsables y formularios existen.
• Reglas ELOas: XML bien formado, cada parte de script se compila con Rhino.
• Scripts IX: compilados, cada //@include es resoluble, @include solo está en las líneas de cabecera, solo ASCII. Un include no resoluble detiene de lo contrario todo el motor de scripts del Indexserver. 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

Datei	Zweck
elo-mcp.ps1	Startskript und Vorschalt
Set-EloCredential.ps1	Zugangsdaten verschlüsselt hinterlegen
src/elo.js	IX-Verbindung, Archivpfade
src/elo-mcp.js	Kern, Protokoll, Textauszug, Stufe 1
src/elo-mcp-schreiben.js	Stufe 2, Vorschau/Token, Feldprüfung, Protokoll
src/elo-mcp-bauen.js	Stufe 3, Bauplan, Skriptprüfungen
src/elo-mcp-start.js	Hauptschleife
test/offline.ps1	Prüfungen ohne ELO (Protokoll, Stufen, Bauplan, Skripte)
test/test-mcp.py	Aufrufe gegen ein echtes ELO, z. B. python -I test\test-mcp.py test\beispiel-lesen.json -- -IxUrl <url>
mcpb/	Paket für Claude Desktop: manifest.json, Startskript mcpb-start.ps1 (Einstellungen → Schalter), Symbol
tools/build-mcpb.ps1	baut dist\elo-mcp-<version>.mcpb und trägt Prüfsumme und Download-URL in server.json ein
server.json	Eintrag für die MCP Registry
test/test-mcpb.py	startet das gebaute Paket wie Claude Desktop, z. B. python -I test\test-mcpb.py dist\elo-mcp-0.5.0.mcpb -- ix_url=<url>

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.