fluig-mcp

Opere um ambiente TOTVS Fluig por um agente de IA ou pelo terminal — datasets, formulários, eventos globais e definições de processo BPM — sem abrir o Fluig Studio.

Por quê

Desenvolver no Fluig normalmente passa pelo Fluig Studio, uma distribuição do Eclipse. Ler um evento de formulário, descobrir qual dataset um workflow chama ou subir uma correção de uma linha num service task significa abrir a IDE, exportar um pacote, importar de volta e publicar na mão. Nada desse ciclo é automatizável, e nada dele é acessível a um agente.

Tudo o que o Fluig Studio faz, ele faz por HTTP. O fluig-mcp fala os mesmos três protocolos da plataforma — o cookie de sessão do login.do, os serviços SOAP legados em /webdesk/* e a API REST v2 — de dentro de um processo Node comum. Isso expõe a plataforma inteira como ferramentas Model Context Protocol: o assistente lê o validateForm de um formulário, rastreia por que uma tarefa caiu na pessoa errada ou publica uma versão corrigida de processo na mesma conversa em que a pergunta apareceu.

Related MCP server: Operaton MCP

O que faz

• Datasets — listar, ler o código de um dataset custom, inspecionar a estrutura sem executar, executar, criar, atualizar e apagar.

• Formulários — listar, ler todos os arquivos e eventos, e publicar nova versão.

• Eventos globais — ler e gravar.

• Definições de processo BPM — exportar o .ecm30.xml, ler e alterar o código dos eventos de processo, publicar nova versão, retirar do ar para reverter e apagar versões.

• Solicitações — iniciar, assumir, mover, cancelar; ler o card, o histórico, os anexos, os estados ativos e disponíveis, e quem pode receber a tarefa.

• SQL passthrough — SELECT read-only no banco do Fluig e no TOTVS RM, direto ou pela sentença registrada.

• Escape hatches — GET/POST autenticado em qualquer caminho da API.

São 56 ferramentas. node server.js --list mostra todas — e não pede credencial nenhuma, para você auditar a superfície antes de confiar alguma a ela.

Evento de processo sem widget

O código dos eventos de processo vive dentro do XML da definição, em <WorkflowProcessEvent><eventDescription>. O fluig-mcp lê de lá e grava de volta exportando a definição, alterando só aquele evento e reimportando — o que faz de cada escrita uma nova versão, revertível, que passou pela validação do servidor, num servidor sem nenhum add-on instalado. O round-trip é byte a byte: acentos, aspas e o $ do jQuery sobrevivem intactos (teste de regressão).

Requisitos

• Node.js 20 ou superior.

• Acesso de rede a um ambiente Fluig (testado contra Fluig 1.8.x).

• Um usuário do Fluig. A maioria das ferramentas quer perfil administrativo; as de solicitação agem como esse usuário e precisam dos papéis correspondentes.

Instalação

git clone https://github.com/alucardigo/fluig-mcp.git
cd fluig-mcp
npm install

Configuração

Toda a configuração vem de variáveis de ambiente. Não existe default de host nem de credencial — variável faltando é erro explícito, nunca um fallback silencioso.

Veja .env.example.

Claude Code

claude mcp add fluig \
  --env FLUIG_HOST=https://fluig.exemplo.com:8080 \
  --env FLUIG_USER=seu.usuario \
  --env FLUIG_PASS=sua-senha \
  -- node /caminho/absoluto/para/fluig-mcp/server.js

Claude Desktop, Cursor ou qualquer outro cliente MCP

{
  "mcpServers": {
    "fluig": {
      "command": "node",
      "args": ["/caminho/absoluto/para/fluig-mcp/server.js"],
      "env": {
        "FLUIG_HOST": "https://fluig.exemplo.com:8080",
        "FLUIG_USER": "seu.usuario",
        "FLUIG_PASS": "sua-senha",
        "FLUIG_READONLY": "1"
      }
    }
  }
}

Comece com FLUIG_READONLY=1. Tire quando já souber o que o agente faz com as ferramentas de leitura.

Testando

A CLI usa o mesmo cliente, então é o caminho mais rápido para provar credencial e conectividade antes de envolver um agente:

export FLUIG_HOST=https://fluig.exemplo.com:8080
export FLUIG_USER=seu.usuario
export FLUIG_PASS=sua-senha

node bin/cli.js ping
node bin/cli.js dataset list colleague
node bin/cli.js form list
node bin/cli.js process events MeuProcesso

node bin/cli.js --help lista todos os comandos. O que for baixado vai para ./out (fora do git).

Ferramentas

! marca ferramenta que altera o servidor. Essas desaparecem por completo com FLUIG_READONLY=1, e cada uma exige confirm: true explícito.

Sessão

Datasets

Formulários

Eventos globais

SQL

Definições de processo

Solicitações

Add-on FluiggersWidget (opcional) — dispensável; as ferramentas _xml acima resolvem o mesmo num servidor sem add-on.

Escape hatches

Como funciona por baixo

Resiliência de rede. Fluig quase sempre está atrás de DNS corporativo, e DNS corporativo mente: zonas split-horizon devolvem endereço inalcançável de onde você está, e um lookup azarado fica idêntico a uma queda de servidor. Então o cliente resolve o endereço ele mesmo — último IP bom, dns.resolve4, dns.lookup, seeds do operador —, sonda os candidatos por TCP em paralelo, fixa o primeiro que responde e preserva o Host original para o virtual host continuar funcionando. O endereço bom fica em cache curto e é re-sondado em qualquer falha. Toda chamada também tem retry com backoff, e só insiste em erro de fato transiente.

Segurança

Este servidor entrega a um LLM a capacidade de rodar SQL, publicar formulários e apagar definições de processo. Trate com o cuidado correspondente.

• FLUIG_READONLY=1 esconde as 18 ferramentas de escrita. Sobram 38, incluindo tudo o que é necessário para ler e diagnosticar.

• Toda operação destrutiva exige confirm: true explícito; não existe sim por omissão.

• fluig_process_event_set_xml e fluig_process_import_xml criam nova versão em vez de mexer na que está no ar, então fluig_process_version_withdraw reverte um deploy ruim.

• As ferramentas de consulta aceitam só SELECT/WITH, validado antes de a instrução sair do processo.

• Para rodar SQL, o servidor grava um dataset descartável chamado ${FLUIG_SCRATCH_PREFIX}* (por padrão ds_mcp_dbquery, ds_mcp_rmquery, …). Isso acontece em modo read-only também, porque é assim que a leitura funciona. Tudo com esse prefixo no seu servidor foi criado aqui e pode ser apagado com fluig_dataset_delete.

• Aponte primeiro para um ambiente de teste ou homologação.

Veja SECURITY.md.

Limitações

• Formulário é orientado a leitura: fluig_form_save substitui todo o conjunto de arquivos e eventos, então leia com fluig_form_full antes ou você perde o que não mandou.

• O datasource do RM costuma estar configurado como read-only. Quando está, o caminho suportado de escrita no RM é a API DataServer do RM, não o fluig_rm_db_exec.

• O dataset ponte de sentenças (FLUIG_RM_BRIDGE_DATASET) é convenção de integração, não garantia de plataforma — o nome e a existência variam por instalação.

• Código de dataset roda em Rhino: só ES5, sem let/const, arrow function ou template string.

• Verificado contra Fluig 1.8.x. Outras versões provavelmente funcionam, mas não foram testadas.

Desenvolvimento

npm test      # testes de unidade, não precisa de servidor
npm run check # checagem de sintaxe de todos os fontes
npm run list  # imprime a superfície de ferramentas

Os testes usam o runner nativo node:test e rodam offline — a camada de rede é stubada, então a suíte roda em qualquer lugar. Veja CONTRIBUTING.md.

Créditos

O protocolo de dataset e formulário foi originalmente mapeado pelo projeto comunitário fluig-vscode-extension (Fluiggers), que vale muito a pena se você escreve código Fluig no VS Code. As rotas de definição de processo, ciclo de vida de solicitação e deploy aqui foram mapeadas de forma independente contra um servidor real.

Aviso

Projeto independente e não oficial. Sem vínculo, endosso ou suporte da TOTVS. TOTVS, Fluig e RM são marcas da TOTVS S.A. Alguns endpoints usados aqui são internos ou não documentados e podem mudar entre versões.

Licença

MIT © Rodrigo de Souza Faria