# mcp-n8n

MCP (Model Context Protocol) server para **N8N** focado em **CONSTRUÇÃO DE WORKFLOWS** pela Samara. 18 tools em 5 categorias, rodando via **stdio**.

> **Diferencial:** Paule descreve em linguagem natural o que quer ("Samara, monta um workflow que recebe WhatsApp, classifica com IA, e responde") e a Samara monta o workflow no N8N automaticamente — usando 1 dos 3 modos inteligentes (template / scaffold / LLM).

---

## Tools (18)

### 1. CRUD (5) — manipular workflows existentes
- `list_workflows` — lista workflows do N8N
- `get_workflow` — pega JSON completo por id
- `create_workflow` — cria novo workflow
- `update_workflow` — atualiza workflow existente
- `delete_workflow` — ⚠ destrutivo, pede confirmação

### 2. Execução (3)
- `execute_workflow` — dispara workflow (com payload opcional)
- `get_execution` — status + dados de uma execution
- `list_executions` — histórico de execuções

### 3. Import / Export + Templates (2)
- `import_workflow` — importa JSON local pro N8N
- `export_workflow` — exporta workflow do N8N pra JSON

### 4. Sync local (2)
- `sync_from_templates` — importa todos os JSONs de `N8N_TEMPLATES_DIR` pro N8N
- `sync_to_templates` — exporta todos os workflows do N8N pra `N8N_TEMPLATES_DIR`

### 5. **CONSTRUÇÃO** (6) — o coração do "Samara monta fluxos"
- `build_workflow_from_spec` — **a principal**: spec em linguagem natural → workflow JSON
- `list_node_types` — descobre nodes disponíveis no N8N
- `get_node_schema` — schema detalhado de 1 node
- `validate_workflow` — valida JSON antes de criar (pega nodes inválidos, ciclos, connections quebradas)
- `export_workflow_diagram` — gera diagrama Mermaid
- `workflow_versions` — versionamento git-like (list, save, restore, diff)

---

## Os 3 modos de construção

`build_workflow_from_spec` é inteligente — escolhe o melhor modo baseado na spec:

| Modo         | Quando                                              | Como funciona                                              |
|--------------|-----------------------------------------------------|------------------------------------------------------------|
| **template** | Spec menciona keyword que casa com template salvo   | Carrega template de `N8N_TEMPLATES_DIR/`, adapta nome, devolve JSON |
| **scaffold** | Spec lista nodes separados por `→`, `->` ou vírgulas | Monta workflow linear com esses nodes conectados            |
| **llm**      | Spec vaga em linguagem natural                       | Detecta palavras-chave (webhook/cron/ia/http/if) e gera scaffold heurístico |

Paule pode forçar modo com `mode: "template" | "scaffold" | "llm"`. Default: `auto` (Samara escolhe).

### Exemplo de uso

**Paule:** "Samara, monta um workflow que recebe POST no webhook, valida JWT, salva no Supabase e responde 200"

**Samara:**
1. Detecta keywords: webhook, valida, salva, responde → modo **scaffold** (lista nodes)
2. Invoca `mcp__n8n__build_workflow_from_spec` com a spec
3. Samara no Claude Code refina o JSON retornado (adiciona nodes de validação JWT, ajusta Supabase, etc)
4. Invoca `mcp__n8n__validate_workflow` pra confirmar
5. Invoca `mcp__n8n__export_workflow_diagram` pra Paule ver visual
6. Paule aprova → invoca `mcp__n8n__create_workflow`
7. Retorna URL do webhook + ID

---

## Instalação

### 1. Pré-requisitos
- Node.js 22.6+ (com `--experimental-strip-types`)
- N8N rodando em algum lugar (cloud ou self-hosted) com API habilitada
- API key do N8N (Settings → API)

### 2. Instalar

```powershell
cd "C:\Users\paule\Documents\PROGRAMAÇÃO\mcp-n8n"
npm install
```

### 3. Configurar `.env`

```powershell
Copy-Item .env.example .env
notepad .env
```

Preencha:
- `N8N_API_KEY` — key criada no N8N UI (Settings → API → Create API Key)
- `N8N_BASE_URL` — `http://localhost:5678/api/v1` pra self-hosted, ou `https://api.n8n.cloud/api/v1` pra cloud
- `N8N_TEMPLATES_DIR` — opcional, default já aponta pra `C:\Users\paule\Documents\PROGRAMAÇÃO\N8N\TEMPLETES`

### 4. Registrar no Claude Code

Edite `C:\Users\paule\.claude.json` e adicione na seção `mcpServers`:

```json
{
  "mcpServers": {
    "n8n": {
      "type": "stdio",
      "command": "node",
      "args": [
        "--experimental-strip-types",
        "--no-warnings",
        "C:\\Users\\paule\\Documents\\PROGRAMAÇÃO\\mcp-n8n\\src\\server.ts"
      ],
      "env": {
        "N8N_API_KEY": "sua-key-aqui",
        "N8N_BASE_URL": "http://localhost:5678/api/v1",
        "N8N_TEMPLATES_DIR": "C:\\Users\\paule\\Documents\\PROGRAMAÇÃO\\N8N\\TEMPLETES"
      }
    }
  }
}
```

Reinicie o Claude Code. Tools aparecem como `mcp__n8n__<tool_name>`.

---

## Como a Samara usa

Samara detecta pedidos relacionados a N8N e invoca o MCP automaticamente. Exemplos em linguagem natural:

### Construção
- "Samara, monta um workflow que recebe WhatsApp e classifica com IA" → `build_workflow_from_spec` (modo `llm`)
- "Samara, faz um workflow parecido com o de WhatsApp que tenho em TEMPLATES" → `build_workflow_from_spec` (modo `template`)
- "Samara, cria workflow Webhook → IF → HTTP Request → Responder" → `build_workflow_from_spec` (modo `scaffold`)

### Discovery e validação
- "Samara, quais nodes N8N eu tenho disponível?" → `list_node_types`
- "Samara, me mostra o schema do OpenAI node" → `get_node_schema`
- "Samara, valida esse workflow antes de criar" → `validate_workflow`

### Visualização
- "Samara, gera o diagrama Mermaid desse workflow" → `export_workflow_diagram`
- "Samara, me mostra o fluxo visual antes de criar" → `build_workflow_from_spec` + `export_workflow_diagram`

### Versionamento
- "Samara, salva versão desse workflow" → `workflow_versions(action="save")`
- "Samara, lista versões" → `workflow_versions(action="list")`
- "Samara, restaura versão 2026-07-01" → `workflow_versions(action="restore")`

### CRUD tradicional
- "Samara, lista workflows" → `list_workflows`
- "Samara, executa workflow abc" → `execute_workflow`
- "Samara, deleta workflow xyz" → ⚠ pede confirmação inline → `delete_workflow`

---

## Política de confirmação (honra 06/07/2026)

- **Criações automáticas** (sem perguntar): `create_workflow`, `build_workflow_from_spec`, `import_workflow`, `sync_from_templates`, `validate_workflow`, `export_workflow_diagram`, `workflow_versions save`
- **Execução** (`execute_workflow`): automática se workflow já foi usado antes; pede confirmação se for primeira vez
- **Destruição** (`delete_workflow`, `update_workflow`): **SEMPRE** pede confirmação inline
- **Leitura** (`list_*`, `get_*`): automática, sem side effects

Samara aplica essa política antes de invocar a tool.

---

## Arquitetura

```
Claude Code (Paule)
   │
   │  mcp__n8n__<tool_name>
   ▼
mcp-n8n v0.2 (stdio, Node 22 + TypeScript strip-types, 18 tools)
   │
   │  fetch + X-N8N-API-KEY
   ▼
N8N REST API (cloud ou self-hosted)
   │
   ├── /workflows
   ├── /executions
   ├── /node-types
   └── /workflows/{id}/execute

Local:
- C:\Users\paule\Documents\PROGRAMAÇÃO\N8N\TEMPLETES\         (25+ templates salvos)
- C:\Users\paule\Documents\PROGRAMAÇÃO\N8N\TEMPLETES\.versions\ (git-like backup)
```

---

## Teste rápido

Com o server registrado e N8N rodando:

1. Abra nova conversa com Claude Code
2. Diga: "Samara, monta um workflow que recebe webhook POST, valida, e responde 200"
3. Samara invoca `mcp__n8n__build_workflow_from_spec`
4. Você vê o JSON gerado + diagrama Mermaid
5. Se aprovar, Samara invoca `mcp__n8n__create_workflow`
6. Retorna ID do workflow + URL do webhook

Se aparecer erro 401: API key não configurada. Defina no `.claude.json`.

---

## Troubleshooting

### "Tool not found: mcp__n8n__list_workflows"
- Claude Code não detectou o MCP. Reinicie.
- Verifique path absoluto em `mcp.json`.

### "N8N_API_KEY não configurada"
- Defina no `.claude.json` em `mcpServers.n8n.env.N8N_API_KEY`.
- Ou crie `.env` no projeto mcp-n8n.

### "fetch failed: ECONNREFUSED"
- N8N não está rodando. Inicie: `npx n8n` ou `docker run -p 5678:5678 n8nio/n8n`.
- Verifique `N8N_BASE_URL` (default 5678).

### `build_workflow_from_spec` retorna scaffold estranha
- Samara refina antes de criar. Use `validate_workflow` + `export_workflow_diagram` pra revisar.
- Force modo específico: `mode: "scaffold"` se spec lista nodes, ou `mode: "template"` se tem base.

### Versão restaurada não funciona
- Versões ficam em `N8N_VERSIONS_DIR/.versions/`. Verifique que o arquivo existe.
- Use `workflow_versions(action="list")` pra ver todas.

---

## Roadmap (Fase futura)

- Cache local de workflows (evita chamada API repetida)
- Validação de schema de workflow mais rigorosa (TS validation)
- Webhook server embutido pra receber notificações de execução concluída
- CLI wrapper (`npx mcp-n8n list`) pra uso fora do MCP
- Diff visual (além de node count)
- Templates como recipes com metadados (tags, descrição, autor)

---

## Inspirado em

- `mcp-meta-ads` do Paule (MCP similar pra Meta Ads)
- `@modelcontextprotocol/sdk` oficial
- N8N REST API: https://docs.n8n.io/api/

---

*mcp-n8n v0.2 — criado 07/07/2026. Samara agora não só gerencia N8N, ela CONSTRÓI workflows.*