@pagelines/n8n-mcp 0.2.0 → 0.3.0

package/docs/node-config.md

@@ -0,0 +1,205 @@
+# Node Configuration Guidelines
+
+> Settings that make AI-created nodes human-editable.
+>
+> **Node types are validated.** Invalid types are blocked with suggestions before hitting n8n. Use `node_types_list` to discover available nodes.
+
+## Resource Locator Pattern
+
+n8n uses `__rl` (resource locator) format for dropdown fields. Always include `cachedResultName` so humans see friendly names.
+
+```javascript
+// Human-editable: shows "My Spreadsheet" in UI
+"documentId": {
+  "__rl": true,
+  "value": "1abc123...",
+  "mode": "list",
+  "cachedResultName": "My Spreadsheet",
+  "cachedResultUrl": "https://docs.google.com/spreadsheets/d/1abc123"
+}
+
+// Hard to edit: shows raw ID only
+"documentId": {
+  "__rl": true,
+  "value": "1abc123...",
+  "mode": "id"
+}
+```
+
+| Mode | When to Use |
+|------|-------------|
+| `list` | Default. Shows dropdown with cached name |
+| `id` | Only when ID is dynamic (from expression) |
+
+## Set Node
+
+**Use JSON mode** for MCP-created nodes. Manual mapping is error-prone via API.
+
+```javascript
+// JSON mode (reliable)
+{
+  "mode": "raw",
+  "jsonOutput": "={ \"channel_id\": \"{{ $json.channelId || '123' }}\" }"
+}
+
+// Manual mapping (fragile via API)
+{
+  "mode": "manual",
+  "assignments": { ... }  // Complex structure, easy to break
+}
+```
+
+## Google Sheets
+
+Required fields (partial updates lose these):
+
+```javascript
+{
+  "operation": "append",
+  "documentId": {
+    "__rl": true,
+    "value": "1abc...",
+    "mode": "list",
+    "cachedResultName": "Sheet Name"
+  },
+  "sheetName": {
+    "__rl": true,
+    "value": "gid=0",
+    "mode": "list",
+    "cachedResultName": "Sheet1"
+  },
+  "columns": { /* mappings */ }
+}
+```
+
+## Gmail
+
+Required fields:
+
+```javascript
+{
+  "operation": "addLabels",  // or send, get, etc.
+  "messageId": "={{ $('source').item.json.id }}",
+  "labelIds": ["Label_123", "Label_456"]
+}
+```
+
+Labels need full IDs (`Label_xxx`), not display names.
+
+## Discord
+
+```javascript
+{
+  "authentication": "webhook",
+  "webhookUri": {
+    "__rl": true,
+    "value": "={{ $env.DISCORD_WEBHOOK }}",
+    "mode": "id"
+  },
+  "content": "Message text"
+}
+```
+
+For bot mode with guild/channel selection:
+
+```javascript
+{
+  "guildId": {
+    "__rl": true,
+    "value": "123456789",
+    "mode": "list",
+    "cachedResultName": "My Server"
+  },
+  "channelId": {
+    "__rl": true,
+    "value": "987654321",
+    "mode": "list",
+    "cachedResultName": "#general"
+  }
+}
+```
+
+## AI Nodes (Agent, Chain)
+
+Always include structured output settings:
+
+```javascript
+{
+  "promptType": "define",
+  "hasOutputParser": true,
+  "schemaType": "manual",  // Required for nullable fields
+  "schema": { /* JSON Schema */ }
+}
+```
+
+Without these, AI outputs are unpredictable strings.
+
+## HTTP Request
+
+Include authentication method explicitly:
+
+```javascript
+{
+  "method": "POST",
+  "url": "https://api.example.com",
+  "authentication": "predefinedCredentialType",
+  "nodeCredentialType": "anthropicApi",
+  "sendBody": true,
+  "bodyParameters": { ... }
+}
+```
+
+## Switch vs If
+
+Always use Switch (not If):
+
+```javascript
+// Switch: named outputs, extensible
+{
+  "type": "n8n-nodes-base.switch",
+  "parameters": {
+    "rules": {
+      "rules": [
+        { "output": 0, "conditions": { ... } },
+        { "output": 1, "conditions": { ... } }
+      ]
+    }
+  }
+}
+```
+
+If node only has true/false outputs - Switch scales better.
+
+## Expression Patterns
+
+Always explicit references:
+
+```javascript
+// Good
+"={{ $('config').item.json.channel_id }}"
+
+// Bad - breaks on node reorder
+"={{ $json.channel_id }}"
+```
+
+Environment variables for secrets:
+
+```javascript
+"={{ $env.API_KEY }}"
+```
+
+## Error Handling
+
+Set `onError` for API nodes:
+
+```javascript
+{
+  "parameters": { ... },
+  "onError": "continueRegularOutput"  // or "continueErrorOutput"
+}
+```
+
+Options:
+- `stopWorkflow` - default, halts on error
+- `continueRegularOutput` - ignore errors, continue
+- `continueErrorOutput` - route errors to second output

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pagelines/n8n-mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Opinionated MCP server for n8n workflow automation",
   "type": "module",
   "main": "dist/index.js",

package/plans/ai-guidelines.md

@@ -0,0 +1,233 @@
+# AI Guidelines for @pagelines/n8n-mcp
+
+Entry point for AI assistants working on this codebase.
+
+## Quick Start
+
+```bash
+npm run dev      # Watch mode
+npm run test     # Run tests
+npm run build    # Compile TypeScript
+```
+
+## Codebase Map
+
+| File | Purpose | When to modify |
+|------|---------|----------------|
+| `src/index.ts` | MCP server, tool dispatch | Adding new tools |
+| `src/types.ts` | Type definitions | New data structures |
+| `src/tools.ts` | Tool JSON schemas | New tool definitions |
+| `src/n8n-client.ts` | n8n REST API calls | New API operations |
+| `src/validators.ts` | Validation rules | New lint rules |
+| `src/expressions.ts` | Expression parsing | Expression handling |
+| `src/autofix.ts` | Auto-fix transforms | New auto-fixes |
+| `src/versions.ts` | Version control | Version features |
+
+## Coding Standards
+
+### Do
+- Write pure functions that return values
+- Use async/await, never callbacks
+- Add types for all parameters and returns
+- Keep functions under 50 lines
+- Name variables descriptively
+- Write tests for new validators
+
+### Don't
+- Use `any` type
+- Mutate input parameters
+- Add external dependencies without strong justification
+- Create abstraction before duplication (rule of 3)
+- Add features not explicitly requested
+
+## Adding a New Tool
+
+1. **Define type** in `types.ts` (if needed)
+2. **Add schema** in `tools.ts`:
+```typescript
+{
+  name: 'my_tool',
+  description: 'What it does',
+  inputSchema: {
+    type: 'object',
+    properties: { /* ... */ },
+    required: ['param1']
+  }
+}
+```
+3. **Add handler** in `index.ts`:
+```typescript
+case 'my_tool':
+  return await handleMyTool(args);
+```
+4. **Implement logic** in appropriate module
+5. **Add test** in `*.test.ts`
+
+## Adding a Validation Rule
+
+1. **Add rule function** in `validators.ts`:
+```typescript
+function checkMyRule(workflow: N8nWorkflow): ValidationWarning[] {
+  const warnings: ValidationWarning[] = [];
+  // validation logic
+  if (problem) {
+    warnings.push({
+      rule: 'my_rule',
+      severity: 'warning', // or 'error' | 'info'
+      message: 'Description of issue',
+      nodeId: node.id,
+      nodeName: node.name,
+      suggestion: 'How to fix'
+    });
+  }
+  return warnings;
+}
+```
+
+2. **Add to composition** in `validateWorkflow()`:
+```typescript
+...checkMyRule(workflow),
+```
+
+3. **Add test** in `validators.test.ts`:
+```typescript
+it('detects my_rule violations', () => {
+  const workflow = createWorkflow({
+    // problematic config
+  });
+  const warnings = validateWorkflow(workflow);
+  expect(warnings).toContainEqual(
+    expect.objectContaining({ rule: 'my_rule' })
+  );
+});
+```
+
+## Adding an Auto-Fix
+
+1. **Check if fixable** - some issues require human judgment
+2. **Add fix logic** in `autofix.ts`:
+```typescript
+if (warning.rule === 'my_rule') {
+  // transform workflow
+  fixed.push(warning);
+} else {
+  unfixed.push(warning);
+}
+```
+3. **Update references** if renaming anything
+4. **Test both dry-run and apply modes**
+
+## Patterns to Follow
+
+### Safe Mutations
+```typescript
+// Always clone before mutating
+const copy = JSON.parse(JSON.stringify(original));
+// Modify copy, return copy
+```
+
+### Async Operations
+```typescript
+// All file/network operations are async
+async function doThing(): Promise<Result> {
+  const data = await fetchData();
+  return transform(data);
+}
+```
+
+### Error Responses
+```typescript
+// MCP error format
+return {
+  content: [{ type: 'text', text: 'Error message' }],
+  isError: true
+};
+```
+
+### Validation Returns
+```typescript
+// Always return array (empty if valid)
+function validate(): ValidationWarning[] {
+  const warnings: ValidationWarning[] = [];
+  // ... checks ...
+  return warnings;
+}
+```
+
+## Testing Patterns
+
+### Fixture Factory
+```typescript
+function createWorkflow(overrides: Partial<N8nWorkflow> = {}): N8nWorkflow {
+  return {
+    id: 'test-id',
+    name: 'test_workflow',
+    nodes: [],
+    connections: {},
+    ...overrides
+  };
+}
+```
+
+### Assertion Patterns
+```typescript
+// Check warning exists
+expect(warnings).toContainEqual(
+  expect.objectContaining({ rule: 'rule_name' })
+);
+
+// Check no warnings
+expect(warnings).toHaveLength(0);
+
+// Check severity
+expect(warnings[0].severity).toBe('error');
+```
+
+## Out of Scope
+
+Do not implement:
+- Node documentation/search (use web search)
+- Template marketplace features
+- Credential management
+- Multi-instance sync
+- Real-time execution monitoring
+
+These are either security risks or solved problems (Google, n8n UI).
+
+## Questions to Ask
+
+Before adding a feature:
+1. Does this serve workflow editing/validation/versioning?
+2. Can this be solved with existing web search?
+3. Does this add runtime dependencies?
+4. Is there duplication that justifies abstraction?
+
+If any answer suggests bloat, reconsider.
+
+## File Locations
+
+```
+~/.n8n-mcp/versions/     # Version control storage
+  {workflowId}/
+    {timestamp}_{hash}.json
+```
+
+## Environment Variables
+
+```bash
+N8N_API_URL=http://localhost:5678  # n8n instance URL
+N8N_API_KEY=your-api-key           # n8n API key
+```
+
+## Debugging
+
+```bash
+# Run with verbose output
+DEBUG=* npm run dev
+
+# Test single file
+npx vitest run src/validators.test.ts
+
+# Watch single test
+npx vitest watch src/validators.test.ts
+```

package/plans/architecture.md

@@ -0,0 +1,220 @@
+# Architecture
+
+**Opinionated** n8n workflow automation. Enforces conventions, blocks mistakes, auto-fixes issues.
+
+## vs czlonkowski/n8n-mcp
+
+| Concern | czlonkowski | @pagelines |
+|---------|-------------|------------|
+| Philosophy | Permissive | Opinionated |
+| Node docs | 70MB SQLite, 1084 nodes | None (use Google) |
+| Templates | 2,709 indexed | None (use n8n.io) |
+| Update mode | Full replace | Patch (preserves params) |
+| After mutations | Nothing | Auto-validate, auto-fix, format |
+| Invalid node types | API error | Blocked with suggestions |
+| Version control | Limited | Auto-snapshot, diff, rollback |
+| Validation | Basic | Rules + expressions + circular refs |
+| Auto-fix | No | Yes (automatic) |
+| Dependencies | SQLite, heavy | Zero runtime |
+| Lines of code | ~10k+ | ~1,500 |
+
+## Modules
+
+```
+src/
+├── index.ts           # MCP server, tool dispatch
+├── types.ts           # Type definitions
+├── tools.ts           # Tool schemas (JSON Schema)
+├── n8n-client.ts      # n8n REST API client
+├── validators.ts      # Validation rules + node type validation
+├── expressions.ts     # Expression parsing ({{ }})
+├── autofix.ts         # Auto-fix transforms
+├── versions.ts        # Version control (local fs)
+└── response-format.ts # Token-efficient response formatting
+```
+
+## Data Flow
+
+```
+Claude Request
+    ↓
+MCP Server (stdio)
+    ↓
+Tool Handler
+    ↓
+┌─────────────────────────────────┐
+│  n8n-client     validators      │
+│  expressions    autofix         │
+│  versions       response-format │
+└─────────────────────────────────┘
+    ↓
+JSON Response → Claude
+```
+
+## Auto-Cleanup Pipeline
+
+Every `workflow_create` and `workflow_update` runs this automatically:
+
+```
+1. Validate node types → Block if invalid (with suggestions)
+2. Execute operation
+3. Validate workflow → Get warnings
+4. Auto-fix fixable issues → snake_case, $json refs, AI settings
+5. Format workflow → Sort nodes, remove nulls
+6. Update if changes → Apply cleanup to n8n
+7. Return result → Only unfixable warnings shown
+```
+
+## Tools (20 total)
+
+### Workflow (8)
+| Tool | Description |
+|------|-------------|
+| `workflow_list` | List workflows, filter by active |
+| `workflow_get` | Get full workflow |
+| `workflow_create` | Create with nodes/connections (auto-validates, auto-fixes) |
+| `workflow_update` | Patch operations (auto-validates, auto-fixes) |
+| `workflow_delete` | Delete workflow |
+| `workflow_activate` | Enable triggers |
+| `workflow_deactivate` | Disable triggers |
+| `workflow_execute` | Trigger via webhook |
+
+### Execution (2)
+| Tool | Description |
+|------|-------------|
+| `execution_list` | List executions, filter by status |
+| `execution_get` | Get execution with run data |
+
+### Validation (3)
+| Tool | Description |
+|------|-------------|
+| `workflow_validate` | Check rules + expressions + circular refs |
+| `workflow_autofix` | Fix auto-fixable issues (dry-run default) |
+| `workflow_format` | Sort nodes, clean nulls |
+
+### Discovery (1)
+| Tool | Description |
+|------|-------------|
+| `node_types_list` | Search available node types by name/category |
+
+### Version Control (6)
+| Tool | Description |
+|------|-------------|
+| `version_list` | List snapshots for workflow |
+| `version_get` | Get specific version |
+| `version_save` | Manual snapshot with reason |
+| `version_rollback` | Restore previous (auto-saves current first) |
+| `version_diff` | Compare versions |
+| `version_stats` | Version control statistics |
+
+## Patch Operations
+
+`workflow_update` accepts these operation types:
+
+```
+addNode, removeNode, updateNode
+addConnection, removeConnection
+updateSettings, updateName
+```
+
+Key: Preserves unmodified parameters.
+
+## Node Type Validation
+
+Before `workflow_create` or `workflow_update` with `addNode`:
+
+1. Fetch available types from n8n API
+2. Validate all node types exist
+3. **Block** if invalid with suggestions (fuzzy matching)
+
+```
+Error: Invalid node types detected:
+Invalid node type "n8n-nodes-base.webhok" for node "trigger".
+Did you mean: n8n-nodes-base.webhook?
+
+Use node_types_list to discover available node types.
+```
+
+## Validation Rules
+
+All rules are checked automatically on every `workflow_create` and `workflow_update`:
+
+| Rule | Severity | Auto-fix | Description |
+|------|----------|----------|-------------|
+| `snake_case` | warning | Yes | Names should be snake_case |
+| `explicit_reference` | warning | Yes | Use `$('node')` not `$json` |
+| `ai_structured_output` | warning | Yes | AI node missing structured output |
+| `no_hardcoded_ids` | info | No | Avoid hardcoded IDs |
+| `no_hardcoded_secrets` | info | No | Consider using $env vars |
+| `code_node_usage` | info | No | Code node detected |
+| `in_memory_storage` | warning | No | Non-persistent storage |
+| `orphan_node` | warning | No | Node has no connections |
+| `node_exists` | error | No | Node doesn't exist (for updates) |
+| `parameter_preservation` | error | No | Update would lose parameters |
+
+## Expression Validation
+
+| Issue | Severity | Pattern |
+|-------|----------|---------|
+| Uses `$json` | warning | `$json.` without `$('` prefix |
+| Uses `$input` | info | `$input.` usage |
+| Missing node reference | error | `$('node')` where node doesn't exist |
+| Unclosed `}}` | error | Unmatched delimiters |
+| Unbalanced parens/brackets | error | `(` vs `)`, `[` vs `]` |
+| Deprecated `$node` | warning | `$node.` pattern |
+| Deep property without `?.` | info | Missing optional chaining |
+
+Plus: **Circular reference detection** across all expressions.
+
+## Auto-Fix
+
+| Rule | Transform |
+|------|-----------|
+| `snake_case` | Rename + update all references |
+| `explicit_reference` | `$json.x` → `$('prev_node').item.json.x` |
+| `ai_structured_output` | Add `promptType: "define"`, `hasOutputParser: true` |
+
+**Not fixable** (require judgment): secrets, hardcoded IDs, orphan nodes, code nodes, memory storage.
+
+## Version Control
+
+Storage: `~/.n8n-mcp/versions/{workflowId}/{timestamp}_{hash}.json`
+
+```json
+{
+  "id": "1704067200000_abc123",
+  "workflowId": "123",
+  "timestamp": "2024-01-01T00:00:00.000Z",
+  "reason": "before update",
+  "metadata": {
+    "name": "my_workflow",
+    "nodeCount": 5,
+    "contentHash": "abc123"
+  },
+  "workflow": { /* full snapshot */ }
+}
+```
+
+Features:
+- Hash-based deduplication (no duplicate saves)
+- Max versions pruning (default: 20)
+- Auto-save before `workflow_update` and `version_rollback`
+
+## Extension
+
+Add validation rule:
+```typescript
+// validators.ts
+function checkMyRule(workflow: N8nWorkflow): ValidationWarning[] {
+  // return warnings
+}
+// Add to validateWorkflow()
+```
+
+Add auto-fix:
+```typescript
+// autofix.ts
+if (warning.rule === 'my_rule' && fixable) {
+  // transform workflow
+}
+```