Fluig Dev MCP

Servidor MCP (Model Context Protocol) para desenvolvimento TOTVS Fluig. Transforma o Claude num copiloto real — entendendo a estrutura do projeto Eclipse, o Style Guide e as APIs REST.

~142 tools  ·  Python + FastMCP  ·  OAuth 1.0  ·  MIT

Arquitetura

O MCP combina conhecimento estatico do Style Guide com chamadas reais a API REST do Fluig, em duas camadas complementares:

┌─────────────────────────────────────────────────┐
│                  Claude Code / IDE              │
│                      ▼ stdio                    │
│  ┌───────────────────────────────────────────┐  │
│  │           fluig-dev-mcp (server.py)       │  │
│  ├───────────────────┬───────────────────────┤  │
│  │  Camada 1 · Dev   │   Camada 2 · API      │  │
│  │  Sempre ativa     │   Requer OAuth         │  │
│  │                   │                        │  │
│  │  · scaffold       │   · datasets (v2)      │  │
│  │  · validators     │   · documents (v2)     │  │
│  │  · knowledge      │   · workflows (v2)     │  │
│  │  · scanner        │   · users (v1)         │  │
│  │  · skills         │   · groups (v1)        │  │
│  │                   │   · cards (v2)         │  │
│  │  28 tools         │   · forms (v2)         │  │
│  │                   │   · alerts (v2)        │  │
│  │                   │   · search             │  │
│  │                   │   · social (v3)        │  │
│  │                   │   · admin              │  │
│  │                   │   114 tools            │  │
│  └───────────────────┴───────────────────────┘  │
└─────────────────────────────────────────────────┘

Camada 1 (Dev Tools) funciona sem credenciais — gera formularios, datasets, widgets, valida codigo e consulta o Style Guide.

Camada 2 (API Tools) conecta ao servidor Fluig via OAuth 1.0 — CRUD completo de datasets, documentos, workflows, usuarios, comunidades e mais.

Instalacao rapida

Pre-requisitos

| Dependencia | Versao | Obrigatorio | |-------------|--------|-------------| | Node.js | >= 16.7 | Sim | | npm / npx | (incluso no Node) | Sim | | Python | >= 3.8 | Apenas para serve |

Via npx (recomendado)

npx @fs-fluigexperts/fluig-mcp

O wizard interativo vai:

1. Verificar ambiente — detecta Node.js, npm, Python
2. Credenciais OAuth — pede URL do Fluig + Consumer Key/Secret + Access Token/Secret
3. Testar conexao — valida conectividade e autenticacao com o servidor
4. Salvar configuracao — grava .env e registra o MCP no Claude Code
5. Instalar skills — seleciona skills e destinos (Claude Code, Cursor, Windsurf, Roo, Cline)

Via git clone

# 1. Clonar o repositorio
git clone https://github.com/future-station/fluig-mcp.git
cd fluig-mcp

# 2. Criar ambiente virtual e instalar dependencias
cd mcp
python3 -m venv .venv
source .venv/bin/activate    # Linux/macOS
# .venv\Scripts\activate     # Windows

pip install -r requirements.txt

# 3. Rodar o setup interativo
python3 setup.py

Registro manual no Claude Code

# Via npx (recomendado)
claude mcp add fluig-mcp -- npx @fs-fluigexperts/fluig-mcp serve

# Via Python (sem OAuth, apenas Dev Tools)
claude mcp add fluig -- /caminho/para/fluig-mcp/mcp/.venv/bin/python /caminho/para/fluig-mcp/mcp/server.py

Comandos disponiveis

O pacote oferece tres modos de execucao via npx:

| Comando | Descricao | |---------|-----------| | npx @fs-fluigexperts/fluig-mcp | Wizard completo: credenciais, teste de conexao, registro no MCP e skills | | npx @fs-fluigexperts/fluig-mcp skills | Instala apenas as skills (SKILL.md) nos destinos selecionados | | npx @fs-fluigexperts/fluig-mcp serve | Inicia o servidor MCP (Python) para uso via stdio |

Credenciais OAuth

As credenciais OAuth 1.0 sao obtidas no Fluig:

1. Acesse Painel de Controle > OAuth > Aplicacoes
2. Crie uma nova aplicacao OAuth (ou use uma existente)
3. Copie Consumer Key e Consumer Secret
4. Gere o Access Token e Token Secret

O wizard salva automaticamente no arquivo ~/.fluig-mcp/.env:

FLUIG_SERVER=https://seu-servidor.fluig.com
FLUIG_CONSUMER_KEY=sua_consumer_key
FLUIG_CONSUMER_SECRET=seu_consumer_secret
FLUIG_ACCESS_TOKEN=seu_access_token
FLUIG_TOKEN_SECRET=seu_token_secret

Tools disponiveis

Dev Tools (28) — sem OAuth

| Modulo | Tools | Descricao | |--------|-------|-----------| | scaffold | 7 | Gera formularios, datasets, widgets, eventos, chamadas REST, templates Mustache | | validators | 3 | Valida HTML de formulario, JS de dataset, JS de evento | | knowledge | 6 | Consulta Style Guide, FLUIGC, SDK, eventos, JS plugins, imports obrigatorios | | scanner | 1 | Escaneia projeto Eclipse e retorna estrutura | | skills_installer | 4 | Listar, instalar, remover e verificar status de skills |

API Tools (114) — requer OAuth

| Modulo | Tools | Endpoint base | |--------|-------|---------------| | datasets | 15 | /api/v2/datasets | | documents | 17 | /api/v2/documents, /api/v2/folders | | workflows | 16 | /api/v2/processes, /api/v2/activities | | users | 11 | /api/v1/users | | groups | 11 | /api/v1/groups | | cards | 15 | /api/v2/cardindex | | forms | 8 | /api/v2/forms | | alerts | 6 | /api/v2/alerts | | search | 4 | /api/v2/search, /api/v1/users/search | | social | 11 | /api/v3/communities, /api/v3/posts, /api/v3/timeline | | admin | 12 | /api/v1/roles, /api/v2/jobs, /api/v2/globalparameters | | widget_tools | 2 | /api/v2/documents, /api/v2/apps, /api/v2/wcm/widgets |

Mapeamento do projeto Eclipse

Cada pasta do projeto Eclipse vira um grupo de tools. O MCP entende onde cada arquivo mora:

Projeto Eclipse Fluig/
├── datasets/        → list_datasets, query_dataset, scaffold_dataset, validate_dataset_js, sync_dataset
├── forms/           → scaffold_form, get_form_component, get_form_records, validate_form_html
│   └── events/      → scaffold_form_event, validate_event_js
├── workflow/
│   ├── diagrams/    → list_processes, get_process_diagram, get_process_instances
│   ├── scripts/     → scaffold_workflow_event, get_workflow_tasks
│   └── literals/    → manage_literals
├── wcm/widget/      → scaffold_widget, get_fluigc_component, scaffold_rest_call, scaffold_mustache_template
├── events/          → list_global_events, scaffold_form_event, validate_event_js, get_sdk_reference
└── mechanisms/      → get_sdk_reference

Exemplo de uso

Usuario: Cria um dataset que busca usuarios de um departamento pelo codigo

AI:     Vou usar o scaffold e a documentacao de API para gerar o dataset correto.
        [tool: scaffold_dataset { type: "ecm_query", source: "users_by_dept" }]
        [tool: query_dataset { id: "ColleagueDS", filters: [{field:"colleagueDepartmentCode"}] }]

Usuario: O formulario do processo "Novos com Usados" nao esta salvando os anexos.
         Analisa o padrao que temos no processo de Admissao e replica pra esse.

AI:     [tool: validate_form_html { path: "forms/Admissao/" }]
        [tool: validate_form_html { path: "forms/Novos com Usados/" }]
        Encontrei a diferenca: falta o atributo data-process-id obrigatorio. Gerando o patch...

Skills

Skills sao prompts especializados para Fluig, instalaveis em varios editores:

| Skill | Descricao | |-------|-----------| | fluig-datasets | Datasets customizados (JS/JDBC/ServiceManager) | | fluig-eventos-formulario | Eventos de formulario (validateForm, afterSave...) | | fluig-eventos-processo | Eventos de processo (afterTaskComplete, beforeStateEntry...) | | fluig-formularios | Formularios HTML com Style Guide | | fluig-integracoes | Integracoes REST e ServiceManager | | fluig-process-reader | Leitura e analise de arquivos .process | | fluig-scripts-avancados | Scripts avancados (subprocesso, notificacoes...) | | fluig-widgets | Widgets WCM com SuperWidget |

Destinos suportados

| Editor | Local | |--------|-------| | Claude Code (projeto) | .claude/skills/ | | Claude Code (global) | ~/.claude/skills/ | | Cursor | .cursor/skills/ | | Windsurf | .windsurf/skills/ | | Roo Code | .roo/skills/ | | Cline | .cline/skills/ |

Instale via wizard ou separadamente:

npx @fs-fluigexperts/fluig-mcp skills

Estrutura do projeto

fluig-mcp/
├── bin/
│   ├── fluig-mcp.js             # CLI wrapper Node.js (serve/setup/skills)
│   └── fluig-skills.js          # CLI para instalacao de skills
├── mcp/
│   ├── server.py                # Entry point do servidor MCP
│   ├── config.py                # Carrega .env, expoe credenciais
│   ├── http_client.py           # HTTP async com OAuth 1.0 (authlib + httpx)
│   ├── setup.py                 # Wizard de instalacao interativo
│   ├── install_skills.py        # Menu de skills interativo
│   ├── requirements.txt         # Dependencias Python
│   ├── knowledge/               # Base de conhecimento em JSON
│   │   ├── style_guide.json
│   │   ├── fluigc_components.json
│   │   ├── sdk_reference.json
│   │   ├── events_reference.json
│   │   └── js_plugins.json
│   └── tools/
│       ├── dev/                 # Dev Tools (sem OAuth)
│       │   ├── scaffold.py
│       │   ├── validators.py
│       │   ├── knowledge.py
│       │   ├── scanner.py
│       │   └── skills_installer.py
│       └── api/                 # API Tools (requer OAuth)
│           ├── datasets.py
│           ├── documents.py
│           ├── workflows.py
│           ├── users.py
│           ├── groups.py
│           ├── cards.py
│           ├── forms.py
│           ├── alerts.py
│           ├── search.py
│           ├── social.py
│           └── admin.py
├── Skills Fluig/                # Arquivos-fonte das skills
├── Exemplo Projeto Fluig Eclipse/
├── package.json                 # npm package @fs-fluigexperts/fluig-mcp
└── README.md

Stack tecnica

| Tecnologia | Uso | |------------|-----| | Node.js 16.7+ | CLI wrapper e wizard interativo | | Python 3.8+ | Runtime do servidor MCP | | FastMCP (mcp >= 1.26) | SDK do protocolo MCP com decorators | | authlib | OAuth 1.0 signing para APIs Fluig | | httpx | HTTP client async | | python-dotenv | Configuracao via .env | | inquirer | Prompts interativos do wizard Node.js |

Autores

• Matheus Nevoa (@matheusnevoa)
• Igor Rodrigues (@igorskater)

Licenca

MIT — Future Station

Fluig Dev MCP · Future Station · @fs-fluigexperts/fluig-mcp · GitHub