ELO ECM MCP

[!NOTE] Inglês: Servidor MCP para o ELO ECM Suite (ELO Digital Office). Executa localmente ao lado do ELO Client (ELO 25) ou ELO Java Client e faz login com a conta ELO do próprio usuário, então o ELO aplica as permissões desse usuário. Além de pesquisa e extração de texto, pode arquivar documentos, definir campos de índice, iniciar e encaminhar fluxos de trabalho e (opcionalmente) construir modelos de fluxo de trabalho e regras ELOas/scripts IX com verificações de sintaxe. Toda escrita é uma prévia em duas etapas + token de uso único. A documentação está em alemão porque a base de usuários do ELO é majoritariamente DACH; problemas em inglês são bem-vindos.

Um servidor MCP para o ELO ECM da ELO Digital Office GmbH. Você pergunta em linguagem natural, por exemplo, "Mostre-me as tarefas abertas para a fatura 4711" ou "Construa-me um modelo de aprovação com dois revisores paralelos", e a IA trabalha diretamente com o seu arquivo.

De relance

• Qualquer cliente MCP: Claude Code, Claude Desktop, Codex, GitHub Copilot, Gemini CLI, Cursor, … (docs/CLIENTS.md)
• Direitos por pessoa: O servidor roda localmente no usuário e faz login com a conta ELO do próprio usuário. O ELO verifica cada acesso por conta própria. Sem conta de serviço, sem replicação de direitos.
• Mais que pesquisar: Pesquisa de texto completo e por campos, extração de texto de PDF/Office/E-mail, direitos efetivos com origem, ler, iniciar e encaminhar fluxos de trabalho.
• Construir com verificações: Exportar, alterar e gravar de volta modelos de fluxo de trabalho como plano de construção JSON. Enviar regras ELOas, scripts IX e páginas de formulário, previamente compilados e verificados contra armadilhas conhecidas.
• Três níveis: Leitura está sempre ativa. Escrita (-Schreiben) e construção (-Bauen) são liberadas individualmente. Sem o interruptor, a IA nem vê as ferramentas.
• Escrita em duas etapas: Cada alteração fornece primeiro uma prévia e um token de uso único. Somente uma segunda chamada com o token executa.
• Suave para o servidor de índice: uma solicitação por vez, limites máximos rígidos, sem consultas em massa sobre fluxos de trabalho.
• Sem downloads adicionais: usa Java, Rhino, biblioteca do cliente IX, PDFBox e POI do ELO Client ou ELO Java Client instalado.

Pré-requisitos

	Testado ou exigido
Servidor ELO	Indexserver 25.00 (ELO 25). Versões mais antigas com API Java devem funcionar, mas não foram testadas.
ELO Client	instalado no computador onde a IA roda: o ELO Client 25 ou o mais antigo ELO Java Client. Testado contra Indexserver 25.00 com o ELO Client 25 (biblioteca do cliente IX 25.00, Rhino 1.9, PDFBox 3) e com o ELO Java Client (biblioteca do cliente IX 20.09). Procurado em Programme\ELO Client, depois Programme\ELO Java Client, caso contrário -ClientDir.
Windows	Windows 10/11 com Windows PowerShell 5.1 (powershell.exe). PowerShell 7 não é suficiente, o pré-carregador precisa de System.Web.Extensions.
Conta ELO	uma conta de usuário normal. A IA pode exatamente o que a conta permite.
Certificado	Em https, o certificado do servidor deve ser confiável no armazenamento de certificados do Windows (Java usa Windows-ROOT).

[!IMPORTANT] Cada sessão estabelece uma conexão IX própria com a sua conta (nome do cliente elo-mcp). Se isso ocupa uma licença ELO adicional no seu caso, por favor, esclareça com o seu parceiro ELO.

Início rápido

1. Obter, por exemplo, em C:\Tools\elo-mcp:

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

2. Armazenar credenciais, uma vez e você mesmo no terminal (não deixe a IA digitar). A senha é criptografada via DPAPI para a sua conta Windows:

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

3. Verificar, sem conexão ELO:

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

4. Registrar, aqui no Claude Code (outros clientes: docs/CLIENTS.md). A URL IX está no perfil de login do ELO Java Client ou vem do seu 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. Testar: Em uma nova sessão, pergunte "Quem sou eu no ELO?". Isso chama elo_whoami e mostra conta, servidor, versão IX e níveis liberados.

Quer que a sua IA configure isso sozinha? Dê a ela esta frase: "Configure o ELO-MCP-Server de acordo com o AGENTS.md nesta pasta."

Claude Desktop: instalar como pacote

Para o Claude Desktop, o servidor também está disponível como pacote (MCPB), sem Git e sem arquivo de configuração:

1. Baixar do último release elo-mcp-<version>.mcpb e Set-EloCredential.ps1.
2. Armazenar credenciais, você mesmo no terminal:

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

3. No Claude Desktop, em Configurações → Extensões → Configurações avançadas → Instalar extensão (Settings → Extensions → Advanced settings → Install Extension), escolher o arquivo .mcpb.
4. Inserir a URL IX. Ativar escrita e construção somente se necessário. O arquivo de credenciais e a pasta do cliente permanecem vazios enquanto você usa os padrões. Para um segundo arquivo (por exemplo, teste), preencher os campos "Arquivo 2" e dar um nome curto a ambos os arquivos, veja Dois arquivos.
5. Em um novo chat, perguntar "Quem sou eu no ELO?".

No pacote estão apenas os scripts deste repositório (cerca de 70 KB). Java e as bibliotecas ELO vêm, como de costume, do ELO Client instalado. Para uma atualização, basta instalar o novo .mcpb.

Interruptores

Todos os interruptores ficam atrás do caminho do script na configuração do cliente.

Interruptor	Efeito
-IxUrl <url>	URL IX do servidor ELO (obrigatório, alternativamente variável de ambiente ELO_IX_URL)
-Schreiben	Liberar nível 2: arquivar, nova versão, campos de índice, iniciar fluxo de trabalho, encaminhar tarefa
-Bauen	Liberar nível 3: modelos de fluxo de trabalho, scripts, regras ELOas, páginas de formulário. Preferencialmente apenas contra um arquivo de teste.
-CredentialFile <pfad>	outras credenciais, por exemplo, uma segunda conta para o arquivo de teste. Padrão %LOCALAPPDATA%\elo-mcp\elo-credential.xml
-ClientDir <pfad>	pasta do ELO Client ou ELO Java Client, se não estiver em Programme
-Archiv "<name>"	nome do arquivo nas instruções para a IA, por exemplo, "der Muster GmbH (Test)"
-TextDatumJJJJMMTT	regra interna de alguns arquivos: campos de texto cujo nome termina em DAT/DATUM recebem datas como JJJJMMTT
-LeerlaufMinuten <n>	encerrar Java após tantos minutos sem chamada (padrão 10, não menos que 5)
-Direkt	sem pré-carregador, iniciar Java imediatamente (fallback em caso de problemas, apenas um arquivo)
-IxUrl2 <url>	segundo arquivo, por exemplo, o arquivo de teste (veja abaixo)
-Name <name>, -Name2 <name>	nomes curtos dos dois arquivos para o parâmetro archiv, por exemplo, Produktiv e Test (padrão 1 e 2)
-Schreiben2, -Bauen2	níveis apenas para o segundo arquivo
-CredentialFile2 <pfad>, -Archiv2 "<name>"	credenciais (padrão: as mesmas do primeiro) e nome do arquivo para o segundo arquivo

Dois arquivos

Uma entrada pode atender dois arquivos, por exemplo, produção somente leitura e teste com todos os níveis:

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 ferramenta tem então o parâmetro archiv (Produktiv ou Test). Sem especificação, vale o primeiro arquivo. Você simplesmente diz à IA "no teste" ou "em produção".
• Os níveis valem por arquivo. No exemplo, a IA não pode alterar nada em produção, mesmo que tente. As ferramentas de escrita e construção dizem em sua descrição em qual arquivo funcionam.
• Cada arquivo roda em um processo Java próprio, que só inicia na primeira chamada. Conexões, caches e tokens não se misturam. Um token de uma prévia no teste nunca funciona em produção.
• elo_whoami, cada prévia e o protocolo mencionam o arquivo. IDs de objetos, máscaras e modelos valem apenas no respectivo arquivo.

Ferramentas

Nível 1: ler (sempre ativo)

Ferramenta	Finalidade
elo_whoami	conta, servidor, versão IX, níveis liberados
elo_search	iSearch sobre título, texto completo e campos de índice, opcionalmente limitado a uma pasta com subpastas, no máximo 50 resultados
elo_find_by_fields	pesquisa no banco de dados por máscara e campos de índice, curinga *. Sem campo ou nome, é rejeitado
elo_list	conteúdo da pasta, um nível, no máximo 300
elo_get_object	metadados, campos de índice com rótulo, caminho, versão atual, link elodms://
elo_get_versions	lista de versões, mais recente primeiro
elo_get_text	texto de PDF (com camada de texto), DOCX, XLSX, PPTX, XLS, EML e arquivos de texto, no máximo 50.000 caracteres por chamada, continuar lendo com abZeichen
elo_user_rights	direitos funcionais efetivos de um usuário com origem (direto ou por qual grupo, também aninhado)
elo_workflow_templates	todos os modelos de fluxo de trabalho
elo_workflow	modelo ou fluxo de trabalho em execução/concluído em detalhe: nós, responsáveis, scripts, formulário, configuração JSON, conexões
elo_workflows_of_object	fluxos de trabalho em execução (com nós ativos) ou concluídos para exatamente um objeto
elo_my_tasks	próprias tarefas, também por grupos
elo_workflow_export	modelo como plano de construção JSON (formato)

Nível 2: trabalhar (-Schreiben)

Ferramenta	Finalidade
elo_create_folder	criar pasta (somente máscaras de pasta), avisa sobre nomes iguais e campos obrigatórios vazios
elo_create_document	arquivar arquivo local como documento (somente máscaras de documento), no máximo 50 MB
elo_new_version	nova versão. Rejeita um arquivo idêntico, avisa sobre extensão diferente
elo_set_fields	definir campos de índice e nome curto, prévia anterior → novo
elo_start_workflow	iniciar fluxo de trabalho a partir de modelo, avisa se o mesmo modelo já está em execução
elo_forward_task	encaminhar tarefa. Com vários sucessores, é obrigatório especificar. Nós com formulário somente com trotzFormular, porque as validações de formulário não rodam pela API

Os valores dos campos são verificados antes contra a máscara: campo existente, comprimento, número, data (31.02. é rejeitado), lista de palavras-chave em "somente lista". Campos de data são gravados pelo servidor no formato ELO JJJJMMTT000000.

Nível 3: construir (-Bauen)

Ferramenta	Finalidade
elo_workflow_build	criar ou substituir modelo a partir do plano de construção (ID e nome permanecem). Prévia com lista de alterações, backup .ewf antes e depois
elo_script_update	nova versão de um documento em Administration (regra ELOas, script IX, página de formulário …), prévia com comparação de linhas, codificação permanece
elo_script_create	novo documento em Administration, máscara, direitos e tipo do modelo

As verificações ao construir vêm todas de falhas reais:

• Fluxos de trabalho: exatamente um início, pelo menos um fim, todas as arestas para nós existentes, cada nó alcançável e com caminho até o fim, cada nó exceto o fim tem um sucessor (caso contrário, o processo fica travado), decisão com condição, coletor com contador fixo (0 encaminha no primeiro predecessor, -1 fica travado após ramos IF pulados), responsáveis e formulários existem.
• Regras ELOas: XML bem formado, cada parte de script é compilada com Rhino.
• Scripts IX: compilados, cada //@include é resolvível, @include está apenas nos cabeçalhos, somente ASCII. Um include não resolvível para, caso contrário, o motor de script inteiro do servidor de índice. Neu laden (ELOas, IX-Skripte) e „Aktualisieren" no formulardesigner continuam sendo manuais. O servidor informa isso após cada alteração.

Segurança

• Conta própria: O ELO verifica cada acesso com os direitos da pessoa conectada. Um servidor central precisaria de uma conta de serviço com direito de administrador principal: O login em nome de outros (runAsUser) é rejeitado pelo indexserver para contas normais. Este servidor evita conscientemente tal conta; ele roda localmente com a conta da pessoa.
• Credenciais: criptografadas via DPAPI, legíveis apenas para a sua conta do Windows. O pré-processador as descriptografa somente na inicialização do Java e as repassa apenas ao processo Java.
• Em duas etapas: Primeira chamada = verificação + pré-visualização + token. O token vale por 5 minutos, uso único, apenas para exatamente os mesmos argumentos e somente se o objeto não tiver sido alterado desde a pré-visualização (impressão digital baseada em nome, máscara, campos de índice, bloqueio, versão). As instruções para a IA exigem mostrar a pré-visualização e aguardar a aprovação.
• Não no código: Excluir, mover, alterar direitos e máscaras. Isso não está desativado; simplesmente não existe.
• Protocolo: Cada execução, inclusive as que falharam, está registrada em %LOCALAPPDATA%\elo-mcp\protokoll-JJJJ-MM.jsonl (hora, conta, servidor, ferramenta, argumentos, resultado).
• Sem repetição na escrita: Ferramentas de leitura se reconectam uma vez após uma sessão expirada. As de escrita nunca, para que nada aconteça em dobro.
• Texto externo: Conteúdos de documentos (elo_get_text) podem conter instruções para a IA (injeção de prompt). Por isso, leiam cada pré-visualização antes de aprovar.

Inicialização e memória

Clientes MCP iniciam cada servidor uma vez por sessão. Uma JVM por sessão custa cerca de 650 MB, mesmo que o ELO nunca seja usado. Por isso, elo-mcp.ps1 atua como um pré-processador leve (cerca de 75 MB) antes do Java:

• initialize, tools/list e ping são respondidos pelo pré-processador a partir de %LOCALAPPDATA%\elo-mcp\werkzeuge-<hash>.txt. Após uma alteração no código ou nas opções, a primeira sessão busca a lista uma vez do Java.
• O Java inicia apenas na primeira chamada de ferramenta (2–8 s) e encerra após 10 minutos sem chamadas. A JVM roda com -XX:+UseSerialGC -Xms32m -XX:TieredStopAtLevel=1 (cerca de 90–130 MB). No caso de dois arquivos, isso vale para cada arquivo.

Limitações

• Apenas Windows e apenas stdio (sem servidor HTTP). O núcleo em src\ roda em qualquer lugar onde Rhino e a biblioteca do cliente IX rodam. Ainda não há um script de inicialização para outros sistemas.
• Sem texto de .doc, .msg e digitalizações sem camada de texto (sem OCR).
• Links apenas como elodms://(GUID) para o Java Client, ainda não para o Web Client.
• Na construção, apenas os tipos de nó 1–6 (início, pessoa, distribuidor, decisão, coletor, fim). Modelos com ciclo, transferência de servidor ou subfluxo de trabalho podem ser exportados, mas não gravados de volta.
• Sem recarregamento de scripts ELOas/IX e sem publicação.

Estrutura

Arquivo	Finalidade
elo-mcp.ps1	Script de inicialização e pré-processador
Set-EloCredential.ps1	Armazenar credenciais criptografadas
src/elo.js	Conexão IX, caminhos de arquivo
src/elo-mcp.js	Núcleo, protocolo, extração de texto, nível 1
src/elo-mcp-schreiben.js	Nível 2, pré-visualização/token, verificação de campos, protocolo
src/elo-mcp-bauen.js	Nível 3, plano de construção, verificações de script
src/elo-mcp-start.js	Loop principal
test/offline.ps1	Verificações sem ELO (protocolo, níveis, plano de construção, scripts)
test/test-mcp.py	Chamadas contra um ELO real, ex.: python -I test\test-mcp.py test\beispiel-lesen.json -- -IxUrl <url>
mcpb/	Pacote para Claude Desktop: manifest.json, script de inicialização mcpb-start.ps1 (Configurações → Opções), ícone
tools/build-mcpb.ps1	Compila dist\elo-mcp-<version>.mcpb e insere soma de verificação e URL de download em server.json
server.json	Entrada para a MCP Registry
test/test-mcpb.py	Inicia o pacote compilado como Claude Desktop, ex.: python -I test\test-mcpb.py dist\elo-mcp-0.5.0.mcpb -- ix_url=<url>

As armadilhas da API IX que encontramos durante a construção estão em docs/FALLEN.md.

Contribuir

Issues e pull requests são bem-vindos, inclusive com experiências de outras versões do ELO. Por favor, não incluam dados internos (nomes de host, usuários, IDs de objeto, nomes de locatários) em issues, logs ou arquivos de teste. Antes de um pull request, execute test\offline.ps1. Vulnerabilidades de segurança não devem ser relatadas publicamente, mas conforme descrito em SECURITY.md.

Licença e marcas

MIT, veja LICENSE. Sem garantia: Testem gravação e construção primeiro em um arquivo de teste.

Este não é um produto da ELO Digital Office GmbH e não é suportado nem revisado por ela. ELO é uma marca da ELO Digital Office GmbH. As bibliotecas ELO não fazem parte deste repositório e não estão no pacote. Elas vêm do seu ELO Java Client licenciado.