n8n-manager

What this skill does

# n8n Manager

## Configuration

- **Server**: Read from `N8N_HOST` environment variable (never hardcoded)
- **API Auth**: `X-N8N-API-KEY` header via `N8N_API_KEY` env var
- **Instance MCP**: Native n8n MCP at `N8N_HOST/mcp-server/http` (bearer token from `N8N_MCP_TOKEN`)
- **Docs MCP**: czlonkowski/n8n-mcp for node documentation and templates
- **Version**: n8n Community Edition v2.14.x
- **Scripts**: `plugins/psd-productivity/skills/n8n-manager/scripts/`

All scripts use `bun` and read credentials from `secrets.js` (env vars → Geoffrey .env).

## Community Edition Limitations

PSD runs n8n Community Edition. These features are **not available**:

- **No Settings → Variables** — environment variables are enterprise/pro only. All config values (API keys, URLs, folder IDs) must be hardcoded directly in workflow node parameters.
- **No instance-level error workflow** — must set `errorWorkflow` in each workflow's `settings` object individually.
- **Credentials API returns 403** — credential listing/reading is restricted. Get credential IDs from the user via the n8n UI.
- **No source control / Git integration** — workflows must be managed via API or UI exports.

## Command Reference

### Workflow Management

| Command | Script | Description |
|---------|--------|-------------|
| `/n8n status` | `bun health_check.js` | Server health, version, workflow count |
| `/n8n list` | `bun list_workflows.js` | List all workflows |
| `/n8n list '{"active":true}'` | `bun list_workflows.js '{"active":true}'` | Filter by status |
| `/n8n list '{"tag":"psd-production"}'` | `bun list_workflows.js '{"tag":"psd-production"}'` | Filter by tag |
| `/n8n show <id>` | `bun get_workflow.js <id>` | Get full workflow JSON |
| `/n8n activate <id>` | `bun activate_workflow.js <id>` | Activate workflow |
| `/n8n deactivate <id>` | `bun deactivate_workflow.js <id>` | Deactivate workflow |
| `/n8n delete <id>` | `bun delete_workflow.js <id>` | Delete workflow (**confirm first**) |

### Workflow Builder

| Command | Description |
|---------|-------------|
| `/n8n build "<description>"` | Build workflow from natural language (see protocol below) |
| `/n8n deploy '<json>'` | `bun deploy_workflow.js '<json>'` — validate + create |
| `/n8n trigger <url> [data]` | `bun trigger_workflow.js <url> '<json>'` — trigger via webhook |

### Executions

| Command | Script | Description |
|---------|--------|-------------|
| `/n8n executions` | `bun list_executions.js` | Recent executions |
| `/n8n executions '{"status":"error"}'` | `bun list_executions.js '{"status":"error"}'` | Failed only |
| `/n8n execution <id>` | `bun get_execution.js <id>` | Execution details |
| `/n8n execution <id> --full` | `bun get_execution.js <id> --full` | With node data |
| `/n8n retry <id>` | `bun retry_execution.js <id>` | Retry failed execution |

### Credentials & Configuration

| Command | Script | Description |
|---------|--------|-------------|
| `/n8n creds` | `bun list_credentials.js` | List credentials (metadata only) |
| `/n8n cred-schema <type>` | `bun get_credential_schema.js <type>` | Schema for credential type |
| `/n8n cred-create '<json>'` | `bun create_credential.js '<json>'` | Create credential |
| `/n8n tags` | `bun list_tags.js` | List all tags |
| `/n8n tag-create <name>` | `bun create_tag.js <name>` | Create tag |
| `/n8n vars` | `bun list_variables.js` | List variables |
| `/n8n var-create <key> <val>` | `bun create_variable.js <key> <val>` | Create variable |
| `/n8n audit` | `bun run_audit.js` | Security audit |
| `/n8n rotate-documenso-key <old> <new>` | `bun rotate_documenso_key.js <old> <new>` | Rotate the Documenso API key across every workflow that uses it. Add `--dry-run` first to preview. |

### Folder & Organization (MCP-based)

| Command | Script | Description |
|---------|--------|-------------|
| `/n8n folders` | `bun manage_folders.js list` | List all folders |
| `/n8n folders search <query>` | `bun manage_folders.js search <query>` | Search folders by name |
| `/n8n folders map` | `bun manage_folders.js map` | Map workflows to suggested folders |
| `/n8n folders organize` | `bun manage_folders.js organize` | Full organization report |
| `/n8n folders ensure-tags` | `bun manage_folders.js ensure-tags` | Create standard PSD tags |
| `/n8n folders tag <wfId> <tagId>` | `bun manage_folders.js tag <wfId> <tagId>` | Add tag to workflow |

**Note:** Folder creation must be done in the n8n UI. The public API does not support it. Use `manage_folders.js organize` to see which folders need to be created. New workflows can be placed in folders automatically via the MCP `create_workflow_from_code` tool with `folderId`.

## Workflow Builder Protocol

When building a workflow from a natural language description:

### Step 1: Research
- Read `references/n8n-node-catalog.md` for available node types and JSON snippets
- Read `references/psd-integration-map.md` if PSD systems are involved
- Read `references/psd-workflow-templates.md` for similar pre-built patterns
- Use n8n-docs MCP tools if available: `search_nodes` for node discovery, `get_node_details` for parameter schemas

### Step 2: Design
Present the workflow to the user as a numbered list:
```
1. [Trigger] Schedule - Every 5 Minutes (scheduleTrigger)
2. [Action] Fetch Tickets from Freshservice (httpRequest)
3. [Logic] Filter High Priority Only (if)
4. [Action] Send Slack Alert (slack)
```
Get user approval before generating JSON.

### Step 3: Generate
- Read `references/n8n-workflow-json-spec.md` for the exact JSON format
- Use unique, descriptive node names (NEVER default names like "HTTP Request")
- Space nodes ~250px apart horizontally
- Wire connections using exact node names

### Step 4: Validate
```bash
bun plugins/psd-productivity/skills/n8n-manager/scripts/validate_workflow.js '<json>'
```
Fix any errors before deploying.

### Step 5: Deploy
```bash
bun plugins/psd-productivity/skills/n8n-manager/scripts/deploy_workflow.js '<json>'
```
Returns the workflow ID and editor URL.

### Step 6: Test & Activate
- If webhook trigger: offer to send test data via `trigger_workflow.js`
- Check execution result via `list_executions.js`
- After successful test, activate with `activate_workflow.js`
- Suggest tagging with `psd-production`

## Safety Guardrails

### Always confirm before:
- **Deleting** a workflow (show name and active status first)
- **Deactivating** an active workflow (warn: webhook listeners will stop)
- **Overwriting** a workflow (show what changed)
- **Deleting** credentials (warn: workflows using them will break)

### Naming conventions:

- Node names must be **unique and descriptive** — e.g., "Fetch Freshservice Tickets" not "HTTP Request"
- Connections use node **NAMES as keys, NOT IDs** — duplicate names break wiring silently

| Type | Pattern | Example |
|------|---------|---------|
| Department workflows | `{Dept} - {Document Type}` | `ESS - Classified Performance Evaluation` |
| Infrastructure workflows | `PSD - {Service Name}` | `PSD - Logo Server`, `PSD - Template Server` |
| Router workflows | `{System} - {Function} Router` | `Documenso - Document Completion Router` |
| Documenso envelopes | `{Document Type} - {Name} - {Year}` | `Central Leadership Evaluation - Jane Smith - 2025-2026` |
| PDF templates (server) | `{type-slug}` | `classified-evaluation`, `central-leadership` |
| Google Drive files | `{Document Type} - {Name} - {Year}.pdf` | Matches envelope title |

### Folder structure:

| n8n Folder | Contains |
|------------|----------|
| ESS Evaluations | Employee evaluation workflows |
| ESS Timesheets | Centralized timesheet workflows (no per-department timesheets) |
| ESS Compliance | COI disclosures, attestations, policy acknowledgments |
| PSD Infrastructure | Router, completion handlers, error handler |
| PSD Servers | Template server, logo server |

- Every workflow must be in a folder, never root
- Workflow name prefix must match folder category (`ESS -`, `PSD -`, `Documenso -`)
- Create folders in the U