@pagelines/n8n-mcp 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.2.1] - 2025-01-13
+
+### Added
+- [Node Config Guide](docs/node-config.md) - Human-editable node settings (`__rl` resource locator, Set node JSON mode, AI structured output)
+
+### Changed
+- Sharpened documentation (31% line reduction, higher data-ink ratio)
+- README: Lead with differentiation, compact tool/validation tables
+- Best Practices: Quick reference at top, focused on MCP-validated patterns
+- Architecture: Technical reference, removed redundant philosophy sections
+
 ## [0.2.0] - 2025-01-12
 
 ### Added

package/README.md

@@ -1,9 +1,20 @@
 # n8n MCP Server
 
-> Version control, validation, and patch-based updates for n8n workflows.
+Workflow validation, version control, and patch-based updates for n8n.
 
-[![npm version](https://img.shields.io/npm/v/@pagelines/n8n-mcp.svg)](https://www.npmjs.com/package/@pagelines/n8n-mcp)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+## The Problem
+
+Other n8n MCPs replace entire nodes on update—losing parameters you didn't touch. No rollback. 70MB of SQLite for node docs you can Google.
+
+## This MCP
+
+| Feature | This | Others |
+|---------|------|--------|
+| Update approach | Patch (preserves params) | Replace (loses params) |
+| Version control | Auto-snapshot before mutations | Manual/none |
+| Validation | Expression syntax, circular refs, secrets | Basic |
+| Auto-fix | snake_case, $json→$('node'), AI settings | None |
+| Size | ~1,200 LOC, zero deps | 10k+ LOC, 70MB SQLite |
 
 ## Install
 
@@ -11,7 +22,7 @@
 npx @pagelines/n8n-mcp
 ```
 
-Add to MCP config (`~/.claude/mcp.json`):
+Add to `~/.claude/mcp.json`:
 
 ```json
 {
@@ -30,56 +41,39 @@ Add to MCP config (`~/.claude/mcp.json`):
 
 ## Tools
 
-### Workflow Operations
-
-| Tool | Description |
-|------|-------------|
-| `workflow_list` | List all workflows |
-| `workflow_get` | Get workflow by ID |
-| `workflow_create` | Create new workflow |
-| `workflow_update` | Patch-based updates (preserves parameters) |
-| `workflow_delete` | Delete workflow |
-| `workflow_activate` | Enable triggers |
-| `workflow_deactivate` | Disable triggers |
-| `workflow_execute` | Execute via webhook |
-
-### Quality & Validation
-
-| Tool | Description |
-|------|-------------|
-| `workflow_validate` | Check best practices, expressions, circular refs |
-| `workflow_autofix` | Auto-fix snake_case, explicit refs, AI settings |
-| `workflow_format` | Sort nodes, clean nulls |
-
-### Version Control
-
-| Tool | Description |
-|------|-------------|
-| `version_list` | List saved versions |
-| `version_get` | Get specific version |
-| `version_save` | Manual snapshot |
-| `version_rollback` | Restore previous version |
-| `version_diff` | Compare versions |
-
-## Validation Rules
-
-| Rule | Severity |
-|------|----------|
-| `snake_case` naming | warning |
-| Explicit refs (`$('node')` not `$json`) | warning |
-| No hardcoded secrets | error |
-| No orphan nodes | warning |
-| AI structured output | warning |
-| Expression syntax | error |
-
-## Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `N8N_API_URL` | Your n8n instance URL |
-| `N8N_API_KEY` | API key from n8n settings |
-| `N8N_MCP_VERSIONS` | Enable version control (default: true) |
-| `N8N_MCP_MAX_VERSIONS` | Max versions per workflow (default: 20) |
+| Category | Tools |
+|----------|-------|
+| Workflow | `list` `get` `create` `update` `delete` `activate` `deactivate` `execute` |
+| Execution | `list` `get` |
+| Validation | `validate` `autofix` `format` |
+| Versions | `list` `get` `save` `rollback` `diff` `stats` |
+
+## Validation
+
+| Rule | Severity | Auto-fix |
+|------|----------|----------|
+| snake_case naming | warning | Yes |
+| Explicit refs (`$('node')` not `$json`) | warning | Yes |
+| AI structured output | warning | Yes |
+| Hardcoded secrets | error | No |
+| Orphan nodes | warning | No |
+| Expression syntax | error | No |
+| Circular references | error | No |
+
+## Config
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `N8N_API_URL` | required | n8n instance URL |
+| `N8N_API_KEY` | required | API key |
+| `N8N_MCP_VERSIONS` | `true` | Enable version control |
+| `N8N_MCP_MAX_VERSIONS` | `20` | Max snapshots per workflow |
+
+## Docs
+
+- [Best Practices](docs/best-practices.md) - Expression patterns, config nodes, AI settings
+- [Node Config](docs/node-config.md) - Human-editable node settings (`__rl`, Set node, etc.)
+- [Architecture](plans/architecture.md) - Technical reference
 
 ## License
 

package/docs/best-practices.md

@@ -1,107 +1,84 @@
 # n8n Best Practices
 
-> Enforced by `@pagelines/n8n-mcp`
+## Quick Reference
 
-## Guiding Principle
+```javascript
+// Explicit reference (always use this)
+{{ $('node_name').item.json.field }}
 
-**What is most stable and easiest to maintain?**
+// Environment variable
+{{ $env.API_KEY }}
 
-| Rule | Why |
-|------|-----|
-| Minimize nodes | Fewer failure points, easier debugging |
-| YAGNI | Build only what's needed now |
-| Explicit references | `$('node_name')` not `$json` - traceable, stable |
-| snake_case | `node_name` not `NodeName` - consistent, readable |
+// Config node reference
+{{ $('config').item.json.setting }}
 
----
+// Fallback
+{{ $('source').item.json.text || 'default' }}
+
+// Date
+{{ $now.format('yyyy-MM-dd') }}
+```
 
-## Naming Convention
+## The Rules
 
-**snake_case everywhere**
+### 1. snake_case
 
 ```
-Workflows: content_factory, publish_linkedin, upload_image
-Nodes: trigger_webhook, fetch_articles, check_approved
+Good: fetch_articles, check_approved, generate_content
+Bad:  FetchArticles, Check Approved, generate-content
 ```
 
-Never `NodeName`. Always `node_name`.
-
----
-
-## Expression References
+Why: Consistency, readability, auto-fixable.
 
-**NEVER use `$json`. Always explicit node references.**
+### 2. Explicit References
 
 ```javascript
 // Bad - breaks when flow changes
 {{ $json.field }}
 
-// Good - traceable and debuggable
+// Good - traceable, stable
 {{ $('node_name').item.json.field }}
-
-// Parallel branch (lookup nodes)
-{{ $('lookup_node').all().length > 0 }}
-
-// Environment variable
-{{ $env.API_KEY }}
-
-// Fallback pattern
-{{ $('source').item.json.text || $('source').item.json.media_url }}
 ```
 
----
-
-## Secrets and Configuration
-
-**Secrets in environment variables. Always.**
-
-```javascript
-// Bad
-{ "apiKey": "sk_live_abc123" }
+Why: `$json` references "previous node" implicitly. Reorder nodes, it breaks.
 
-// Good
-{{ $env.API_KEY }}
-```
+### 3. Config Node
 
-**For workflow-specific settings, use a config node:**
+Single source for workflow settings:
 
 ```
 [trigger] → [config] → [rest of workflow]
 ```
 
-Config node uses JSON output mode:
+Config node (JSON mode):
 ```javascript
 ={
-  "channel_id": "{{ $json.body.channelId || '1234567890' }}",
+  "channel_id": "{{ $json.body.channelId || '123456' }}",
   "max_items": 10,
   "ai_model": "gpt-4.1-mini"
 }
 ```
 
-Then reference: `{{ $('config').item.json.channel_id }}`
+Reference everywhere: `{{ $('config').item.json.channel_id }}`
 
----
+Why: Change once, not in 5 nodes.
 
-## Workflow Editing Safety
+### 4. Secrets in Environment
 
-### The Golden Rule
-
-**Never edit a workflow without explicit confirmation and backup.**
-
-### Pre-Edit Checklist
+```javascript
+// Bad
+{ "apiKey": "sk_live_abc123" }
 
-1. **Confirm** - Get explicit user approval
-2. **List versions** - Know your rollback point
-3. **Read full state** - Understand current config
-4. **Make targeted change** - Use patch operations only
-5. **Verify** - Confirm expected state
+// Good
+{{ $env.API_KEY }}
+```
 
-### Parameter Preservation
+## Parameter Preservation
 
-**CRITICAL:** Partial updates REPLACE the entire `parameters` object.
+**Critical:** Partial updates REPLACE the entire `parameters` object.
 
 ```javascript
-// Bad: Only updates messageId, loses operation and labelIds
+// Bad - loses operation and labelIds
 {
   "type": "updateNode",
   "nodeName": "archive_email",
@@ -112,7 +89,7 @@ Then reference: `{{ $('config').item.json.channel_id }}`
   }
 }
 
-// Good: Include ALL required parameters
+// Good - include ALL parameters
 {
   "type": "updateNode",
   "nodeName": "archive_email",
@@ -120,122 +97,64 @@ Then reference: `{{ $('config').item.json.channel_id }}`
     "parameters": {
       "operation": "addLabels",
       "messageId": "={{ $json.message_id }}",
-      "labelIds": ["Label_123", "Label_456"]
+      "labelIds": ["Label_123"]
     }
   }
 }
 ```
 
----
-
-## Code Nodes
-
-**Code nodes are a last resort.** Exhaust built-in options first:
-
-| Need | Use Instead |
-|------|-------------|
-| Transform fields | Set node with expressions |
-| Filter items | Filter node or If/Switch |
-| Merge data | Merge node |
-| Loop processing | n8n processes arrays natively |
-| Date formatting | `{{ $now.format('yyyy-MM-dd') }}` |
-
-**When code IS necessary:**
-- Re-establishing `pairedItem` after chain breaks
-- Complex conditional logic
-- API response parsing expressions can't handle
-
-**Code node rules:**
-- Single responsibility (one clear purpose)
-- Name it for what it does: `merge_context`, `parse_response`
-- No side effects - pure data transformation
-
----
+Before updating: read current state with `workflow_get`.
 
-## AI Agent Best Practices
+## AI Nodes
 
 ### Structured Output
 
-**Always enable "Require Specific Output Format"** for reliable JSON:
-
-```javascript
-{
-  "promptType": "define",
-  "hasOutputParser": true,
-  "schemaType": "manual"  // Required for nullable fields
-}
-```
-
-Without these, AI outputs are unpredictable.
+Always set for predictable JSON:
 
-### Memory Storage
+| Setting | Value |
+|---------|-------|
+| `promptType` | `"define"` |
+| `hasOutputParser` | `true` |
+| `schemaType` | `"manual"` (for nullable fields) |
 
-**Never use in-memory storage in production:**
+### Memory
 
 | Don't Use | Use Instead |
 |-----------|-------------|
 | Windowed Buffer Memory | Postgres Chat Memory |
 | In-Memory Vector Store | Postgres pgvector |
 
-In-memory dies with restart and doesn't scale.
-
----
-
-## Architecture Patterns
-
-### Single Responsibility
-
-Don't build monolith workflows:
-
-```
-Bad: One workflow doing signup → email → CRM → calendar → reports
-
-Good: Five focused workflows that communicate via webhooks
-```
-
-### Switch > If Node
-
-Always use Switch instead of If:
-- Named outputs (not just true/false)
-- Unlimited conditional branches
-- Send to all matching option
-
----
+In-memory dies on restart, doesn't scale.
 
-## Validation Rules Enforced
+## Code Nodes: Last Resort
 
-| Rule | Severity | Description |
-|------|----------|-------------|
-| `snake_case` | warning | Names should be snake_case |
-| `explicit_reference` | warning | Use `$('node')` not `$json` |
-| `no_hardcoded_ids` | info | Avoid hardcoded IDs |
-| `no_hardcoded_secrets` | error | Never hardcode secrets |
-| `orphan_node` | warning | Node has no connections |
-| `parameter_preservation` | error | Update would remove parameters |
-| `code_node_usage` | info | Code node detected |
-| `ai_structured_output` | warning | AI node missing structured output |
-| `in_memory_storage` | warning | Using non-persistent storage |
-
----
-
-## Quick Reference
-
-```javascript
-// Explicit reference
-{{ $('node_name').item.json.field }}
-
-// Environment variable
-{{ $env.VAR_NAME }}
-
-// Config node reference
-{{ $('config').item.json.setting }}
+| Need | Use Instead |
+|------|-------------|
+| Transform fields | Set node with expressions |
+| Filter items | Filter node or Switch |
+| Merge data | Merge node |
+| Loop | n8n processes arrays natively |
+| Date formatting | `{{ $now.format('yyyy-MM-dd') }}` |
 
-// Parallel branch query
-{{ $('lookup').all().some(i => i.json.id === $json.id) }}
+When code IS necessary:
+- Re-establishing `pairedItem` after chain breaks
+- Complex conditional logic
+- API parsing expressions can't handle
 
-// Date formatting
-{{ $now.format('yyyy-MM-dd') }}
+## Pre-Edit Checklist
 
-// Fallback
-{{ $json.text || $json.description || 'default' }}
-```
+| Step | Why |
+|------|-----|
+| 1. Get explicit user approval | Don't surprise |
+| 2. List versions | Know rollback point |
+| 3. Read full workflow | Understand current state |
+| 4. Make targeted change | Minimal surface area |
+| 5. Validate after | Catch issues immediately |
+
+## Node-Specific Settings
+
+See [Node Config](node-config.md) for:
+- Resource locator (`__rl`) format with `cachedResultName`
+- Google Sheets, Gmail, Discord required fields
+- Set node JSON mode vs manual mapping
+- Error handling options

package/docs/node-config.md

@@ -0,0 +1,203 @@
+# Node Configuration Guidelines
+
+> Settings that make AI-created nodes human-editable
+
+## 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.2.1",
   "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,177 @@
+# Architecture
+
+## vs czlonkowski/n8n-mcp
+
+| Concern | czlonkowski | @pagelines |
+|---------|-------------|------------|
+| Node docs | 70MB SQLite, 1084 nodes | None (use Google) |
+| Templates | 2,709 indexed | None (use n8n.io) |
+| Update mode | Full replace | Patch (preserves params) |
+| Version control | Limited | Auto-snapshot, diff, rollback |
+| Validation | Basic | Rules + expressions + circular refs |
+| Auto-fix | No | Yes |
+| Dependencies | SQLite, heavy | Zero runtime |
+| Lines of code | ~10k+ | ~1,200 |
+
+## 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
+├── expressions.ts  # Expression parsing ({{ }})
+├── autofix.ts      # Auto-fix transforms
+└── versions.ts     # Version control (local fs)
+```
+
+## Data Flow
+
+```
+Claude Request
+    ↓
+MCP Server (stdio)
+    ↓
+Tool Handler
+    ↓
+┌─────────────────────────────────┐
+│  n8n-client     validators      │
+│  expressions    autofix         │
+│  versions                       │
+└─────────────────────────────────┘
+    ↓
+JSON Response → Claude
+```
+
+## Tools (19 total)
+
+### Workflow (8)
+| Tool | Description |
+|------|-------------|
+| `workflow_list` | List workflows, filter by active |
+| `workflow_get` | Get full workflow |
+| `workflow_create` | Create with nodes/connections |
+| `workflow_update` | Patch operations |
+| `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 |
+
+### 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.
+
+## Validation Rules
+
+| Rule | Severity | Description |
+|------|----------|-------------|
+| `snake_case` | warning | Names should be snake_case |
+| `explicit_reference` | warning | Use `$('node')` not `$json` |
+| `no_hardcoded_ids` | info | Avoid hardcoded IDs |
+| `no_hardcoded_secrets` | error | Never hardcode secrets |
+| `code_node_usage` | info | Code node detected |
+| `ai_structured_output` | warning | AI node missing structured output |
+| `in_memory_storage` | warning | Non-persistent storage |
+| `orphan_node` | warning | Node has no connections |
+| `node_exists` | error | Node doesn't exist (for updates) |
+| `parameter_preservation` | error | 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
+}
+```