# 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

```
┌─────────────────────────────────────────────────┐
│                  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

### Pre-requisitos

- Python 3.8+
- pip
- Claude Code (ou qualquer cliente MCP)

### Passo a passo

```bash
# 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
```

O setup vai:
1. Verificar dependencias
2. Pedir URL do Fluig + credenciais OAuth
3. Testar a conexao
4. Salvar `.env` e registrar no Claude Code
5. (Opcional) Instalar skills para Claude Code, Codex CLI, Copilot ou Cursor

### Registro manual no Claude Code

Se preferir pular o setup e registrar direto:

```bash
# Sem OAuth (apenas Dev Tools)
claude mcp add fluig -- /caminho/para/fluig-mcp/mcp/.venv/bin/python /caminho/para/fluig-mcp/mcp/server.py

# Com OAuth — crie o arquivo mcp/.env antes:
# FLUIG_SERVER=https://seu-servidor.fluig.com
# FLUIG_CONSUMER_KEY=...
# FLUIG_CONSUMER_SECRET=...
# FLUIG_ACCESS_TOKEN=...
# FLUIG_TOKEN_SECRET=...
```

---

## 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**

Salve no arquivo `mcp/.env`:

```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 | 13 | `/api/v2/datasets` |
| documents | 17 | `/api/v2/documents`, `/api/v2/folders` |
| workflows | 14 | `/api/v2/processes`, `/api/v2/activities` |
| users | 11 | `/api/v1/users` |
| groups | 11 | `/api/v1/groups` |
| cards | 15 | `/api/v2/cardindex` |
| forms | 7 | `/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` |

---

## 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

- **Claude Code** — `~/.claude/skills/` (global) ou `.claude/skills/` (projeto)
- **Codex CLI** — `~/.codex/instructions.md`
- **GitHub Copilot** — `.github/copilot-instructions.md`
- **Cursor** — `.cursor/rules/*.mdc`

Instale via setup wizard ou pelo menu interativo:

```bash
cd mcp
source .venv/bin/activate
python3 install_skills.py
```

---

## Estrutura do projeto

```
fluig-mcp/
├── bin/
│   └── fluig-mcp.js          # CLI wrapper Node.js (serve/setup/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 @future-station/fluig-mcp
└── README.md
```

---

## Stack tecnica

| Tecnologia | Uso |
|------------|-----|
| **Python 3.8+** | Runtime do servidor |
| **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 |

---

## Licenca

MIT — Future Station

---

*Fluig Dev MCP · Future Station · [@future-station/fluig-mcp](https://github.com/future-station/fluig-mcp)*
