feat: add n8n_deploy_template tool for one-click template deployment (v2.27.0) (#453)

* feat: add n8n_deploy_template tool for one-click template deployment (v2.27.0)

Add new MCP tool that deploys n8n.io workflow templates directly to user's
n8n instance in a single operation.

Features:
- Fetch template from local database
- Extract and report required credentials
- Optionally strip credentials (default: true)
- Optionally auto-upgrade node typeVersions (default: true)
- Optionally validate before deployment (default: true)
- Return workflow ID, URL, and setup guidance

Parameters:
- templateId (required): Template ID from n8n.io
- name (optional): Custom workflow name
- autoUpgradeVersions (default: true)
- validate (default: true)
- stripCredentials (default: true)

Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: address code review findings for n8n_deploy_template

- Fix health check tool count (12 → 13) to include new tool
- Add templateId validation (must be positive integer)
- Use deep copy of workflow to prevent template mutation
- Expand unit tests with negative/zero/decimal validation cases

Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* docs: update README with n8n_deploy_template tool

- Update management tools count from 12 to 13
- Add n8n_deploy_template to the tools list

Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: prevent workflow validator from mutating node types

The validator was incorrectly mutating node types from full form
(n8n-nodes-base.*) to short form (nodes-base.*) during validation.
This caused deployed workflows to show "?" icons in n8n UI because
the API requires full form node types.

Also updated SplitInBatches detection to check both node type forms
since workflows may contain either format.

Conceived by Romuald Członkowski - www.aiadvisors.pl/en

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* test: update tool counts in handlers-n8n-manager test

Update expected managementTools count from 12 to 13 and
totalAvailable from 19 to 20 to account for the new
n8n_deploy_template tool.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: pin MCP SDK and Zod versions to prevent Zod v4 resolution

Fixes #440, #444, #446, #447, #450

Root cause: package.json declared `"@modelcontextprotocol/sdk": "^1.20.1"`
which allowed npm to resolve to SDK 1.23.0. That version accepts
`"zod": "^3.25 || ^4.0"`, causing npm to deduplicate to Zod v4.
SDK 1.23.0's `isZ4Schema()` function crashes when called with undefined,
which happens for plain JSON Schema objects.

Changes:
- Pin SDK to exact version 1.20.1 (removes ^ prefix)
- Pin Zod to exact version 3.24.1 (removes ^ prefix)
- Add CI workflow to verify fresh installs get compatible versions

The new CI workflow:
- Packs and installs package fresh (without lockfile)
- Verifies SDK is exactly 1.20.1
- Verifies Zod is NOT v4 (blocks 4.x.x)
- Runs weekly to catch upstream dependency changes

Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* chore: improve dependency-check workflow based on code review

- Add workflow_dispatch for manual triggering/debugging
- Add explicit "not found" handling for version detection failures
- Use regex pattern for Zod v4 check to catch pre-release versions
- Add Zod error pattern detection in functionality test
- Capture stderr output for comprehensive error checking

Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

.claude/agents/code-reviewer.md

@@ -1,6 +1,7 @@
 ---
 name: code-reviewer
 description: Use this agent when you need to review recently written or modified code for quality, security, and maintainability. This agent should be invoked immediately after code changes are made to ensure high standards are maintained. Examples:\n\n<example>\nContext: The user has created a code-review agent that should be called after writing code.\nuser: "Please write a function that validates email addresses"\nassistant: "I'll create an email validation function for you:"\n<function implementation>\nassistant: "Now let me use the code-reviewer agent to review this code for quality and security"\n<commentary>\nSince new code was just written, the code-reviewer agent should be invoked to ensure it meets quality standards.\n</commentary>\n</example>\n\n<example>\nContext: The user has modified existing code and wants it reviewed.\nuser: "I've updated the authentication logic, can you check if it's secure?"\nassistant: "I'll use the code-reviewer agent to analyze your authentication changes for security and best practices"\n<commentary>\nThe user has made changes to security-critical code, so the code-reviewer agent is the appropriate tool to ensure the modifications are secure and well-implemented.\n</commentary>\n</example>
+model: inherit
 ---
 
 You are a senior code reviewer with extensive experience in software engineering, security, and best practices. Your role is to ensure code quality, security, and maintainability through thorough and constructive reviews.

.github/workflows/dependency-check.yml

@@ -0,0 +1,222 @@
+name: Dependency Compatibility Check
+
+# This workflow verifies that when users install n8n-mcp via npm (without lockfile),
+# they get compatible dependency versions. This catches issues like #440, #444, #446, #447, #450
+# where npm resolution gave users incompatible SDK/Zod versions.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'package.json'
+      - 'package-lock.json'
+      - '.github/workflows/dependency-check.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'package.json'
+      - 'package-lock.json'
+      - '.github/workflows/dependency-check.yml'
+  # Allow manual trigger for debugging
+  workflow_dispatch:
+  # Run weekly to catch upstream dependency changes
+  schedule:
+    - cron: '0 6 * * 1'  # Every Monday at 6 AM UTC
+
+permissions:
+  contents: read
+
+jobs:
+  fresh-install-check:
+    name: Fresh Install Dependency Check
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Build package
+        run: |
+          npm ci
+          npm run build
+
+      - name: Pack package for testing
+        run: npm pack
+
+      - name: Create fresh install test directory
+        run: |
+          mkdir -p /tmp/fresh-install-test
+          cp n8n-mcp-*.tgz /tmp/fresh-install-test/
+
+      - name: Install package fresh (simulating user install)
+        working-directory: /tmp/fresh-install-test
+        run: |
+          npm init -y
+          # Install from tarball WITHOUT lockfile (simulates npm install n8n-mcp)
+          npm install ./n8n-mcp-*.tgz
+
+      - name: Verify critical dependency versions
+        working-directory: /tmp/fresh-install-test
+        run: |
+          echo "=== Dependency Version Check ==="
+          echo ""
+
+          # Get actual resolved versions
+          SDK_VERSION=$(npm list @modelcontextprotocol/sdk --json 2>/dev/null | jq -r '.dependencies["n8n-mcp"].dependencies["@modelcontextprotocol/sdk"].version // .dependencies["@modelcontextprotocol/sdk"].version // "not found"')
+          ZOD_VERSION=$(npm list zod --json 2>/dev/null | jq -r '.dependencies["n8n-mcp"].dependencies.zod.version // .dependencies.zod.version // "not found"')
+
+          echo "MCP SDK version: $SDK_VERSION"
+          echo "Zod version: $ZOD_VERSION"
+          echo ""
+
+          # Check MCP SDK version - must be exactly 1.20.1
+          if [[ "$SDK_VERSION" == "not found" ]]; then
+            echo "❌ FAILED: Could not determine MCP SDK version!"
+            echo "   The dependency may not have been installed correctly."
+            exit 1
+          fi
+          if [[ "$SDK_VERSION" != "1.20.1" ]]; then
+            echo "❌ FAILED: MCP SDK version mismatch!"
+            echo "   Expected: 1.20.1"
+            echo "   Got: $SDK_VERSION"
+            echo ""
+            echo "This can cause runtime errors. See issues #440, #444, #446, #447, #450"
+            exit 1
+          fi
+          echo "✅ MCP SDK version is correct: $SDK_VERSION"
+
+          # Check Zod version - must be 3.x (not 4.x, including pre-releases)
+          if [[ "$ZOD_VERSION" == "not found" ]]; then
+            echo "❌ FAILED: Could not determine Zod version!"
+            echo "   The dependency may not have been installed correctly."
+            exit 1
+          fi
+          if [[ "$ZOD_VERSION" =~ ^4\. ]]; then
+            echo "❌ FAILED: Zod v4 detected - incompatible with MCP SDK 1.20.1!"
+            echo "   Expected: 3.x"
+            echo "   Got: $ZOD_VERSION"
+            echo ""
+            echo "Zod v4 causes '_zod' property errors. See issues #440, #444, #446, #447, #450"
+            exit 1
+          fi
+          echo "✅ Zod version is compatible: $ZOD_VERSION"
+
+          echo ""
+          echo "=== All dependency checks passed ==="
+
+      - name: Test basic functionality
+        working-directory: /tmp/fresh-install-test
+        run: |
+          echo "=== Basic Functionality Test ==="
+
+          # Create a simple test script
+          cat > test-import.mjs << 'EOF'
+          import { spawn } from 'child_process';
+          import path from 'path';
+          import { fileURLToPath } from 'url';
+
+          const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+          // Test that the package can be required and basic tools work
+          async function test() {
+            console.log('Testing n8n-mcp package import...');
+
+            // Start the MCP server briefly to verify it initializes
+            const serverPath = path.join(__dirname, 'node_modules/n8n-mcp/dist/mcp/index.js');
+
+            const proc = spawn('node', [serverPath], {
+              env: { ...process.env, MCP_MODE: 'stdio' },
+              stdio: ['pipe', 'pipe', 'pipe']
+            });
+
+            // Send initialize request
+            const initRequest = JSON.stringify({
+              jsonrpc: '2.0',
+              id: 1,
+              method: 'initialize',
+              params: {
+                protocolVersion: '2024-11-05',
+                capabilities: {},
+                clientInfo: { name: 'test', version: '1.0.0' }
+              }
+            });
+
+            proc.stdin.write(initRequest + '\n');
+
+            // Wait for response or timeout
+            let output = '';
+            let stderrOutput = '';
+            proc.stdout.on('data', (data) => {
+              output += data.toString();
+            });
+
+            proc.stderr.on('data', (data) => {
+              stderrOutput += data.toString();
+              console.error('stderr:', data.toString());
+            });
+
+            // Give it 5 seconds to respond
+            await new Promise((resolve) => setTimeout(resolve, 5000));
+
+            proc.kill();
+
+            // Check for Zod v4 compatibility errors (the bug we're testing for)
+            const allOutput = output + stderrOutput;
+            if (allOutput.includes('_zod') || allOutput.includes('Cannot read properties of undefined')) {
+              console.error('❌ FAILED: Zod compatibility error detected!');
+              console.error('This indicates the SDK/Zod version fix is not working.');
+              console.error('See issues #440, #444, #446, #447, #450');
+              process.exit(1);
+            }
+
+            if (output.includes('"result"')) {
+              console.log('✅ MCP server initialized successfully');
+              return true;
+            } else {
+              console.log('Output received:', output.substring(0, 500));
+              // Server might not respond in stdio mode without proper framing
+              // But if we got here without crashing, that's still good
+              console.log('✅ MCP server started without errors');
+              return true;
+            }
+          }
+
+          test()
+            .then(() => {
+              console.log('=== Basic functionality test passed ===');
+              process.exit(0);
+            })
+            .catch((err) => {
+              console.error('❌ Test failed:', err.message);
+              process.exit(1);
+            });
+          EOF
+
+          node test-import.mjs
+
+      - name: Generate dependency report
+        if: always()
+        working-directory: /tmp/fresh-install-test
+        run: |
+          echo "=== Full Dependency Tree ===" > dependency-report.txt
+          npm list --all >> dependency-report.txt 2>&1 || true
+
+          echo "" >> dependency-report.txt
+          echo "=== Critical Dependencies ===" >> dependency-report.txt
+          npm list @modelcontextprotocol/sdk zod zod-to-json-schema >> dependency-report.txt 2>&1 || true
+
+          cat dependency-report.txt
+
+      - name: Upload dependency report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: dependency-report-${{ github.run_number }}
+          path: /tmp/fresh-install-test/dependency-report.txt
+          retention-days: 30

CHANGELOG.md

@@ -7,6 +7,760 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.26.5] - 2025-11-27
+
+### 🔧 Fixed
+
+- **Tools Documentation: Runtime Token Optimization**
+  - Removed historical migration information from tool descriptions (e.g., "Replaces X, Y, Z...")
+  - Removed version-specific references (v2.21.1, issue #357) that are not needed at runtime
+  - Cleaned up consolidation comments in index.ts
+  - Documentation now starts directly with functional content for better AI agent efficiency
+  - Estimated savings: ~128 tokens per full documentation request
+  - Affected tools: `get_node`, `validate_node`, `search_templates`, `n8n_executions`, `n8n_get_workflow`, `n8n_update_partial_workflow`
+
+**Conceived by Romuald Członkowski - [AiAdvisors](https://www.aiadvisors.pl/en)**
+
+## [2.26.4] - 2025-11-26
+
+### 🔧 Fixed
+
+- **n8n 1.121 Compatibility**: Added support for new workflow settings introduced in n8n 1.121
+  - Added `availableInMCP` (boolean) to settings whitelist - controls "Available in MCP" toggle
+  - Added `callerPolicy` to settings whitelist - was already in schema but missing from sanitization
+  - Both settings are now preserved during workflow updates instead of being silently stripped
+  - Settings can be toggled via `updateSettings` operation: `{type: "updateSettings", settings: {availableInMCP: true}}`
+
+**Conceived by Romuald Członkowski - [AiAdvisors](https://www.aiadvisors.pl/en)**
+
+## [2.26.3] - 2025-11-26
+
+### 🔧 Fixed
+
+- **Tools Documentation Gaps**: Addressed remaining documentation issues after v2.26.2 tool consolidation
+  - Added missing `n8n_workflow_versions` documentation with all 6 modes (list, get, rollback, delete, prune, truncate)
+  - Removed non-existent tools (`n8n_diagnostic`, `n8n_list_available_tools`) from documentation exports
+  - Fixed 10+ outdated tool name references:
+    - `get_node_essentials` → `get_node({detail: "standard"})`
+    - `validate_node_operation` → `validate_node()`
+    - `get_minimal` → `n8n_get_workflow({mode: "minimal"})`
+  - Added missing `mode` and `verbose` parameters to `n8n_health_check` documentation
+  - Added missing `mode` parameter to `get_template` documentation (nodes_only, structure, full)
+  - Updated template count from "399+" to "2,700+" in `get_template`
+  - Updated node count from "525" to "500+" in `search_nodes`
+  - Fixed `relatedTools` arrays to remove references to non-existent tools
+
+**Conceived by Romuald Członkowski - [AiAdvisors](https://www.aiadvisors.pl/en)**
+
+## [2.26.2] - 2025-11-25
+
+### 🔧 Fixed
+
+- **Tool Documentation Cleanup**: Synchronized `tool-docs/` with v2.26.0 tool consolidation
+  - Deleted 23 obsolete documentation files for removed tools (get_node_info, get_node_essentials, validate_node_operation, etc.)
+  - Created consolidated documentation for `get_node` (covers all modes: info, docs, search_properties, versions, compare, breaking, migrations)
+  - Created consolidated documentation for `validate_node` (covers modes: full, minimal; profiles: minimal, runtime, ai-friendly, strict)
+  - Created consolidated documentation for `n8n_executions` (covers actions: get, list, delete)
+  - Updated `search_templates` documentation with all searchModes (keyword, by_nodes, by_task, by_metadata)
+  - Updated `n8n_get_workflow` documentation with all modes (full, details, structure, minimal)
+  - Fixed stale `relatedTools` references pointing to removed tools
+  - Updated `tools-documentation.ts` overview to accurately reflect 19 consolidated tools
+
+## [2.26.1] - 2025-11-25
+
+### 🔄 Updated
+
+- Updated n8n from 1.120.3 to 1.121.2
+- Updated n8n-core from 1.119.2 to 1.120.1
+- Updated n8n-workflow from 1.117.0 to 1.118.1
+- Updated @n8n/n8n-nodes-langchain from 1.119.1 to 1.120.1
+- Rebuilt node database with 545 nodes (439 from n8n-nodes-base, 106 from @n8n/n8n-nodes-langchain)
+- Expanded template database from ~2,598 to 2,768 templates (+170 new templates)
+- Updated README badge with new n8n version
+
+## [2.26.0] - 2025-01-25
+
+### ✨ Features
+
+**Tool Consolidation - Reduced Tool Count by 38%**
+
+Major consolidation of MCP tools from 31 tools to 19 tools, using mode-based parameters for better AI agent ergonomics. This reduces cognitive load for AI agents while maintaining full functionality.
+
+#### Consolidated Tools
+
+**1. Node Tools - `get_node` Enhanced**
+
+The `get_node` tool now supports additional modes:
+- `mode='docs'`: Replaces `get_node_documentation` - returns readable docs with examples
+- `mode='search_properties'`: Replaces `search_node_properties` - search within node properties
+
+```javascript
+// Old: get_node_documentation
+get_node_documentation({nodeType: "nodes-base.slack"})
+// New: mode='docs'
+get_node({nodeType: "nodes-base.slack", mode: "docs"})
+
+// Old: search_node_properties
+search_node_properties({nodeType: "nodes-base.httpRequest", query: "auth"})
+// New: mode='search_properties'
+get_node({nodeType: "nodes-base.httpRequest", mode: "search_properties", propertyQuery: "auth"})
+```
+
+**2. Validation Tools - `validate_node` Unified**
+
+Consolidated `validate_node_operation` and `validate_node_minimal` into single `validate_node`:
+- `mode='full'`: Full validation (replaces `validate_node_operation`)
+- `mode='minimal'`: Quick required fields check (replaces `validate_node_minimal`)
+
+```javascript
+// Old: validate_node_operation
+validate_node_operation({nodeType: "nodes-base.slack", config: {...}})
+// New: mode='full' (default)
+validate_node({nodeType: "nodes-base.slack", config: {...}, mode: "full"})
+
+// Old: validate_node_minimal
+validate_node_minimal({nodeType: "nodes-base.slack", config: {}})
+// New: mode='minimal'
+validate_node({nodeType: "nodes-base.slack", config: {}, mode: "minimal"})
+```
+
+**3. Template Tools - `search_templates` Enhanced**
+
+Consolidated `list_node_templates`, `search_templates_by_metadata`, and `get_templates_for_task`:
+- `searchMode='keyword'`: Search by keywords (default, was `search_templates`)
+- `searchMode='by_nodes'`: Search by node types (was `list_node_templates`)
+- `searchMode='by_metadata'`: Search by AI metadata (was `search_templates_by_metadata`)
+- `searchMode='by_task'`: Search by task type (was `get_templates_for_task`)
+
+```javascript
+// Old: list_node_templates
+list_node_templates({nodeTypes: ["n8n-nodes-base.httpRequest"]})
+// New: searchMode='by_nodes'
+search_templates({searchMode: "by_nodes", nodeTypes: ["n8n-nodes-base.httpRequest"]})
+
+// Old: get_templates_for_task
+get_templates_for_task({task: "webhook_processing"})
+// New: searchMode='by_task'
+search_templates({searchMode: "by_task", task: "webhook_processing"})
+```
+
+**4. Workflow Getters - `n8n_get_workflow` Enhanced**
+
+Consolidated `n8n_get_workflow_details`, `n8n_get_workflow_structure`, `n8n_get_workflow_minimal`:
+- `mode='full'`: Complete workflow data (default)
+- `mode='details'`: Workflow with metadata (was `n8n_get_workflow_details`)
+- `mode='structure'`: Nodes and connections only (was `n8n_get_workflow_structure`)
+- `mode='minimal'`: ID, name, active status (was `n8n_get_workflow_minimal`)
+
+```javascript
+// Old: n8n_get_workflow_details
+n8n_get_workflow_details({id: "123"})
+// New: mode='details'
+n8n_get_workflow({id: "123", mode: "details"})
+
+// Old: n8n_get_workflow_minimal
+n8n_get_workflow_minimal({id: "123"})
+// New: mode='minimal'
+n8n_get_workflow({id: "123", mode: "minimal"})
+```
+
+**5. Execution Tools - `n8n_executions` Unified**
+
+Consolidated `n8n_list_executions`, `n8n_get_execution`, `n8n_delete_execution`:
+- `action='list'`: List executions with filters
+- `action='get'`: Get single execution details
+- `action='delete'`: Delete an execution
+
+```javascript
+// Old: n8n_list_executions
+n8n_list_executions({workflowId: "123", status: "success"})
+// New: action='list'
+n8n_executions({action: "list", workflowId: "123", status: "success"})
+
+// Old: n8n_get_execution
+n8n_get_execution({id: "456"})
+// New: action='get'
+n8n_executions({action: "get", id: "456"})
+
+// Old: n8n_delete_execution
+n8n_delete_execution({id: "456"})
+// New: action='delete'
+n8n_executions({action: "delete", id: "456"})
+```
+
+### 🗑️ Removed Tools
+
+The following tools have been removed (use consolidated equivalents):
+- `get_node_documentation` → `get_node` with `mode='docs'`
+- `search_node_properties` → `get_node` with `mode='search_properties'`
+- `get_property_dependencies` → Removed (use `validate_node` for dependency info)
+- `validate_node_operation` → `validate_node` with `mode='full'`
+- `validate_node_minimal` → `validate_node` with `mode='minimal'`
+- `list_node_templates` → `search_templates` with `searchMode='by_nodes'`
+- `search_templates_by_metadata` → `search_templates` with `searchMode='by_metadata'`
+- `get_templates_for_task` → `search_templates` with `searchMode='by_task'`
+- `n8n_get_workflow_details` → `n8n_get_workflow` with `mode='details'`
+- `n8n_get_workflow_structure` → `n8n_get_workflow` with `mode='structure'`
+- `n8n_get_workflow_minimal` → `n8n_get_workflow` with `mode='minimal'`
+- `n8n_list_executions` → `n8n_executions` with `action='list'`
+- `n8n_get_execution` → `n8n_executions` with `action='get'`
+- `n8n_delete_execution` → `n8n_executions` with `action='delete'`
+
+### 📊 Impact
+
+**Tool Count**: 31 → 19 tools (38% reduction)
+
+**For AI Agents:**
+- Fewer tools to choose from reduces decision complexity
+- Mode-based parameters provide clear action disambiguation
+- Consistent patterns across tool categories
+- Backward-compatible parameter handling
+
+**For Users:**
+- Simpler tool discovery and documentation
+- Consistent API design patterns
+- Reduced token usage in tool descriptions
+
+### 🔧 Technical Details
+
+**Files Modified:**
+- `src/mcp/tools.ts` - Consolidated tool definitions
+- `src/mcp/tools-n8n-manager.ts` - n8n manager tool consolidation
+- `src/mcp/server.ts` - Handler consolidation and mode routing
+- `tests/unit/mcp/parameter-validation.test.ts` - Updated for new tool names
+- `tests/integration/mcp-protocol/tool-invocation.test.ts` - Updated test cases
+- `tests/integration/mcp-protocol/error-handling.test.ts` - Updated error handling tests
+
+**Conceived by Romuald Członkowski - [AiAdvisors](https://www.aiadvisors.pl/en)**
+
+## [2.24.1] - 2025-01-24
+
+### ✨ Features
+
+**Session Persistence API**
+
+Added export/restore functionality for MCP sessions to enable zero-downtime deployments in container environments (Kubernetes, Docker Swarm, etc.).
+
+#### What's New
+
+**1. Export Session State**
+- `exportSessionState()` method in `SingleSessionHTTPServer` and `N8NMCPEngine`
+- Exports all active sessions with metadata and instance context
+- Automatically filters expired sessions
+- Returns serializable `SessionState[]` array
+
+**2. Restore Session State**
+- `restoreSessionState(sessions)` method for session recovery
+- Validates session structure using existing `validateInstanceContext()`
+- Handles null/invalid sessions gracefully with warnings
+- Enforces MAX_SESSIONS limit (100 concurrent sessions)
+- Skips expired sessions during restore
+
+**3. SessionState Type**
+- New type definition in `src/types/session-state.ts`
+- Fully documented with JSDoc comments
+- Includes metadata (timestamps) and context (credentials)
+- Exported from main package index
+
+**4. Dormant Session Behavior**
+- Restored sessions are "dormant" until first request
+- Transport and server objects recreated on-demand
+- Memory-efficient session recovery
+
+#### Security Considerations
+
+⚠️ **IMPORTANT:** Exported session data contains plaintext n8n API keys. Downstream applications MUST encrypt session data before persisting to disk using AES-256-GCM or equivalent.
+
+#### Use Cases
+- Zero-downtime deployments in container orchestration
+- Session recovery after crashes or restarts
+- Multi-tenant platform session management
+- Rolling updates without user disruption
+
+#### Testing
+- 22 comprehensive unit tests (100% passing)
+- Tests cover export, restore, edge cases, and round-trip cycles
+- Validation of expired session filtering and error handling
+
+#### Implementation Details
+- Only exports sessions with valid `n8nApiUrl` and `n8nApiKey` in context
+- Respects `sessionTimeout` setting (default 30 minutes)
+- Session metadata and context persisted; transport/server recreated on-demand
+- Comprehensive error handling with detailed logging
+
+**Conceived by Romuald Członkowski - [AiAdvisors](https://www.aiadvisors.pl/en)**
+
+## [2.24.0] - 2025-01-24
+
+### ✨ Features
+
+**Unified Node Information Tool**
+
+Introduced `get_node` - a unified tool that consolidates and enhances node information retrieval with multiple detail levels, version history, and type structure metadata.
+
+#### What's New
+
+**1. Progressive Detail Levels**
+- `minimal`: Basic metadata only (~200 tokens) - nodeType, displayName, description, category, version summary
+- `standard`: Essential properties and operations - AI-friendly default (~1000-2000 tokens)
+- `full`: Complete node information including all properties (~3000-8000 tokens)
+
+**2. Version History & Management**
+- `versions` mode: List all versions with breaking changes summary
+- `compare` mode: Compare two versions with property-level changes
+- `breaking` mode: Show only breaking changes between versions
+- `migrations` mode: Show auto-migratable changes
+- Version summary always included in info mode responses
+
+**3. Type Structure Metadata**
+- `includeTypeInfo` parameter exposes type structures from v2.23.0 validation system
+- Includes: type category, JS type, validation rules, structure hints
+- Helps AI agents understand complex types (filter, resourceMapper, resourceLocator, etc.)
+- Adds ~80-120 tokens per property when enabled
+- Works with all detail levels
+
+**4. Real-World Examples**
+- `includeExamples` parameter includes configuration examples from templates
+- Shows popular workflow patterns
+- Includes metadata (views, complexity, use cases)
+
+#### Usage Examples
+
+```javascript
+// Standard detail (recommended for AI agents)
+get_node({nodeType: "nodes-base.httpRequest"})
+
+// Standard with type info
+get_node({nodeType: "nodes-base.httpRequest", includeTypeInfo: true})
+
+// Minimal (quick metadata check)
+get_node({nodeType: "nodes-base.httpRequest", detail: "minimal"})
+
+// Full detail with examples
+get_node({nodeType: "nodes-base.httpRequest", detail: "full", includeExamples: true})
+
+// Version history
+get_node({nodeType: "nodes-base.httpRequest", mode: "versions"})
+
+// Compare versions
+get_node({
+  nodeType: "nodes-base.httpRequest",
+  mode: "compare",
+  fromVersion: "3.0",
+  toVersion: "4.1"
+})
+```
+
+#### Benefits
+
+- ✅ **Single Unified API**: One tool for all node information needs
+- ✅ **Token Efficient**: AI-friendly defaults (standard mode recommended)
+- ✅ **Progressive Disclosure**: minimal → standard → full as needed
+- ✅ **Type Aware**: Exposes v2.23.0 type structures for better configuration
+- ✅ **Version Aware**: Built-in version history and comparison
+- ✅ **Flexible**: Can combine detail levels with type info and examples
+- ✅ **Discoverable**: Version summary always visible in info mode
+
+#### Token Costs
+
+- `minimal`: ~200 tokens
+- `standard`: ~1000-2000 tokens (default)
+- `full`: ~3000-8000 tokens
+- `includeTypeInfo`: +80-120 tokens per property
+- `includeExamples`: +200-400 tokens per example
+- Version modes: ~400-1200 tokens
+
+### 🗑️ Breaking Changes
+
+**Removed Deprecated Tools**
+
+Immediately removed `get_node_info` and `get_node_essentials` in favor of the unified `get_node` tool:
+- `get_node_info` → Use `get_node` with `detail='full'`
+- `get_node_essentials` → Use `get_node` with `detail='standard'` (default)
+
+**Migration:**
+```javascript
+// Old
+get_node_info({nodeType: "nodes-base.httpRequest"})
+// New
+get_node({nodeType: "nodes-base.httpRequest", detail: "full"})
+
+// Old
+get_node_essentials({nodeType: "nodes-base.httpRequest", includeExamples: true})
+// New
+get_node({nodeType: "nodes-base.httpRequest", includeExamples: true})
+// or
+get_node({nodeType: "nodes-base.httpRequest", detail: "standard", includeExamples: true})
+```
+
+### 📊 Impact
+
+**Tool Count**: 40 → 39 tools (-2 deprecated, +1 new unified)
+
+**For AI Agents:**
+- Better understanding of complex n8n types through type metadata
+- Version upgrade planning with breaking change detection
+- Token-efficient defaults reduce costs
+- Progressive disclosure of information as needed
+
+**For Users:**
+- Single tool to learn instead of two separate tools
+- Clear progression from minimal to full detail
+- Version history helps with node upgrades
+- Type-aware configuration assistance
+
+### 🔧 Technical Details
+
+**Files Added:**
+- Enhanced type structure exposure in node information
+
+**Files Modified:**
+- `src/mcp/tools.ts` - Removed get_node_info and get_node_essentials, added get_node
+- `src/mcp/server.ts` - Added unified getNode() implementation with all modes
+- `package.json` - Version bump to 2.24.0
+
+**Implementation:**
+- ~250 lines of new code
+- 7 new private methods for mode handling
+- Version repository methods utilized (previously unused)
+- TypeStructureService integrated for type metadata
+- 100% backward compatible in behavior (just different API)
+
+Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
+
+## [2.23.0] - 2025-11-21
+
+### ✨ Features
+
+**Type Structure Validation System (Phases 1-4 Complete)**
+
+Implemented comprehensive automatic validation system for complex n8n node configuration structures, ensuring workflows are correct before deployment.
+
+#### Overview
+
+Type Structure Validation is an automatic, zero-configuration validation system that validates complex node configurations (filter, resourceMapper, assignmentCollection, resourceLocator) during node validation. The system operates transparently - no special flags or configuration required.
+
+#### Key Features
+
+**1. Automatic Structure Validation**
+- Validates 4 special n8n types: filter, resourceMapper, assignmentCollection, resourceLocator
+- Zero configuration required - works automatically in all validation tools
+- Integrated in `validate_node_operation` and `validate_node_minimal` tools
+- 100% backward compatible - no breaking changes
+
+**2. Comprehensive Type Coverage**
+- **filter** (FilterValue) - Complex filtering conditions with 40+ operations (equals, contains, regex, etc.)
+- **resourceMapper** (ResourceMapperValue) - Data mapping configuration for format transformation
+- **assignmentCollection** (AssignmentCollectionValue) - Variable assignments for setting multiple values
+- **resourceLocator** (INodeParameterResourceLocator) - Resource selection with multiple lookup modes (ID, name, URL)
+
+**3. Production-Ready Performance**
+- **100% pass rate** on 776 real-world validations (91 templates, 616 nodes)
+- **0.01ms average** validation time (500x faster than 50ms target)
+- **0% false positive rate**
+- Tested against top n8n.io workflow templates
+
+**4. Clear Error Messages**
+- Actionable error messages with property paths
+- Fix suggestions for common issues
+- Context-aware validation with node-specific logic
+- Educational feedback for AI agents
+
+#### Implementation Phases
+
+**Phase 1: Type Structure Definitions** ✅
+- 22 complete type structures defined in `src/constants/type-structures.ts` (741 lines)
+- Type definitions in `src/types/type-structures.ts` (301 lines)
+- Complete coverage of filter, resourceMapper, assignmentCollection, resourceLocator
+- TypeScript interfaces with validation schemas
+
+**Phase 2: Validation Integration** ✅
+- Integrated in `EnhancedConfigValidator` service (427 lines)
+- Automatic validation in all MCP tools (validate_node_operation, validate_node_minimal)
+- Four validation profiles: minimal, runtime, ai-friendly, strict
+- Node-specific validation logic for edge cases
+
+**Phase 3: Real-World Validation** ✅
+- 100% pass rate on 776 validations across 91 templates
+- 616 nodes tested from top n8n.io workflows
+- Type-specific results:
+  - filter: 93/93 passed (100.00%)
+  - resourceMapper: 69/69 passed (100.00%)
+  - assignmentCollection: 213/213 passed (100.00%)
+  - resourceLocator: 401/401 passed (100.00%)
+- Performance: 0.01ms average (500x better than target)
+
+**Phase 4: Documentation & Polish** ✅
+- Comprehensive technical documentation (`docs/TYPE_STRUCTURE_VALIDATION.md`)
+- Updated internal documentation (CLAUDE.md)
+- Progressive discovery maintained (minimal tool documentation changes)
+- Production readiness checklist completed
+
+#### Edge Cases Handled
+
+**1. Credential-Provided Fields**
+- Fields like Google Sheets `sheetId` that come from credentials at runtime
+- No false positives for credential-populated fields
+
+**2. Filter Operations**
+- Universal operations (exists, notExists, isNotEmpty) work across all data types
+- Type-specific operations validated (regex for strings, gt/lt for numbers)
+
+**3. Node-Specific Logic**
+- Custom validation for specific nodes (Google Sheets, Slack, etc.)
+- Context-aware error messages based on node operation
+
+#### Technical Details
+
+**Files Added:**
+- `src/types/type-structures.ts` (301 lines) - Type definitions
+- `src/constants/type-structures.ts` (741 lines) - 22 complete type structures
+- `src/services/type-structure-service.ts` (427 lines) - Validation service
+- `docs/TYPE_STRUCTURE_VALIDATION.md` (239 lines) - Technical documentation
+
+**Files Modified:**
+- `src/services/enhanced-config-validator.ts` - Integrated structure validation
+- `src/mcp/tools-documentation.ts` - Minimal progressive discovery notes
+- `CLAUDE.md` - Updated architecture and Phase 1-3 completion
+
+**Test Coverage:**
+- `tests/unit/types/type-structures.test.ts` (14 tests)
+- `tests/unit/constants/type-structures.test.ts` (39 tests)
+- `tests/unit/services/type-structure-service.test.ts` (64 tests)
+- `tests/unit/services/enhanced-config-validator-type-structures.test.ts` (comprehensive)
+- `tests/integration/validation/real-world-structure-validation.test.ts` (8 tests, 388ms)
+- `scripts/test-structure-validation.ts` - Standalone validation script
+
+#### Usage
+
+No changes required - structure validation works automatically:
+
+```javascript
+// Validation works automatically with structure validation
+validate_node_operation("nodes-base.if", {
+  conditions: {
+    combinator: "and",
+    conditions: [{
+      leftValue: "={{ $json.status }}",
+      rightValue: "active",
+      operator: { type: "string", operation: "equals" }
+    }]
+  }
+})
+
+// Structure errors are caught and reported clearly
+// Invalid operation → Clear error with valid operations list
+// Missing required fields → Actionable fix suggestions
+```
+
+#### Benefits
+
+**For Users:**
+- ✅ Prevents configuration errors before deployment
+- ✅ Clear, actionable error messages
+- ✅ Faster workflow development with immediate feedback
+- ✅ Confidence in workflow correctness
+
+**For AI Agents:**
+- ✅ Better understanding of complex n8n types
+- ✅ Self-correction based on clear error messages
+- ✅ Reduced validation errors and retry loops
+- ✅ Educational feedback for learning n8n patterns
+
+**Technical:**
+- ✅ Zero breaking changes (100% backward compatible)
+- ✅ Automatic integration (no configuration needed)
+- ✅ High performance (0.01ms average)
+- ✅ Production-ready (100% pass rate on real workflows)
+
+#### Documentation
+
+**User Documentation:**
+- `docs/TYPE_STRUCTURE_VALIDATION.md` - Complete technical reference
+- Includes: Overview, supported types, performance metrics, examples, developer guide
+
+**Internal Documentation:**
+- `CLAUDE.md` - Architecture updates and Phase 1-3 results
+- `src/mcp/tools-documentation.ts` - Progressive discovery notes
+
+**Implementation Details:**
+- `docs/local/v3/implementation-plan-final.md` - Complete technical specifications
+- All 4 phases documented with success criteria and results
+
+#### Version History
+
+- **v2.23.0** (2025-11-21): Type structure validation system completed (Phases 1-4)
+  - Phase 1: 22 complete type structures defined
+  - Phase 2: Validation integrated in all MCP tools
+  - Phase 3: 100% pass rate on 776 real-world validations
+  - Phase 4: Documentation and polish completed
+  - Zero false positives, 0.01ms average validation time
+
+Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
+
+## [2.22.21] - 2025-11-20
+
+### 🐛 Bug Fixes
+
+**Fix Empty Settings Object Validation Error (#431)**
+
+Fixed critical bug where `n8n_update_partial_workflow` tool failed with "request/body must NOT have additional properties" error when workflows had no settings or only non-whitelisted settings properties.
+
+#### Root Cause
+- `cleanWorkflowForUpdate()` in `src/services/n8n-validation.ts` was sending empty `settings: {}` objects to the n8n API
+- n8n API rejects empty settings objects as "additional properties" violation
+- Issue occurred when:
+  - Workflow had no settings property
+  - Workflow had only non-whitelisted settings (e.g., only `callerPolicy`)
+
+#### Changes
+- **Primary Fix**: Modified `cleanWorkflowForUpdate()` to delete `settings` property when empty after filtering
+  - Instead of sending `settings: {}`, the property is now omitted entirely
+  - Added safeguards in lines 193-199 and 201-204
+- **Secondary Fix**: Enhanced `applyUpdateSettings()` in `workflow-diff-engine.ts` to prevent creating empty settings objects
+  - Only creates/updates settings if operation provides actual properties
+- **Test Updates**: Fixed 3 incorrect tests that expected empty settings objects
+  - Updated to expect settings property to be omitted instead
+  - Added 2 new comprehensive tests for edge cases
+
+#### Testing
+- All 75 unit tests in `n8n-validation.test.ts` passing
+- New tests cover:
+  - Workflows with no settings → omits property
+  - Workflows with only non-whitelisted settings → omits property
+  - Workflows with mixed settings → keeps only whitelisted properties
+
+**Related Issues**: #431, #248 (n8n API design limitation)
+**Related n8n Issue**: n8n-io/n8n#19587 (closed as NOT_PLANNED - MCP server issue)
+
+Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
+
+## [2.22.20] - 2025-11-19
+
+### 🔄 Dependencies
+
+**n8n Update to 1.120.3**
+
+Updated all n8n-related dependencies to their latest versions:
+
+- n8n: 1.119.1 → 1.120.3
+- n8n-core: 1.118.0 → 1.119.2
+- n8n-workflow: 1.116.0 → 1.117.0
+- @n8n/n8n-nodes-langchain: 1.118.0 → 1.119.1
+- Rebuilt node database with 544 nodes (439 from n8n-nodes-base, 105 from @n8n/n8n-nodes-langchain)
+
+Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
+
+## [2.22.18] - 2025-11-14
+
+### ✨ Features
+
+**Structural Hash Tracking for Workflow Mutations**
+
+Added structural hash tracking to enable cross-referencing between workflow mutations and workflow quality data:
+
+#### Structural Hash Generation
+- Added `workflowStructureHashBefore` and `workflowStructureHashAfter` fields to mutation records
+- Hashes based on node types + connections (structural elements only)
+- Compatible with `telemetry_workflows.workflow_hash` format for cross-referencing
+- Implementation: Uses `WorkflowSanitizer.generateWorkflowHash()` for consistency
+- Enables linking mutation impact to workflow quality scores and grades
+
+#### Success Tracking Enhancement
+- Added `isTrulySuccessful` computed field to mutation records
+- Definition: Mutation executed successfully AND improved/maintained validation AND has known intent
+- Enables filtering to high-quality mutation data
+- Provides automated success detection without manual review
+
+#### Testing & Verification
+- All 17 mutation-tracker unit tests passing
+- Verified with live mutations: structural changes detected (hash changes), config-only updates detected (hash stays same)
+- Success tracking working accurately (64% truly successful rate in testing)
+
+**Files Modified**:
+- `src/telemetry/mutation-tracker.ts`: Generate structural hashes during mutation processing
+- `src/telemetry/mutation-types.ts`: Add new fields to WorkflowMutationRecord interface
+- `src/telemetry/workflow-sanitizer.ts`: Expose generateWorkflowHash() method
+- `tests/unit/telemetry/mutation-tracker.test.ts`: Add 5 new test cases
+
+**Impact**:
+- Enables cross-referencing between mutation and workflow data
+- Provides labeled dataset with quality indicators
+- Maintains backward compatibility (new fields optional)
+
+Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
+
+## [2.22.17] - 2025-11-13
+
+### 🐛 Bug Fixes
+
+**Critical Telemetry Improvements**
+
+Fixed three critical issues in workflow mutation telemetry to improve data quality and security:
+
+#### 1. Fixed Inconsistent Sanitization (Security Critical)
+- **Problem**: 30% of workflows (178-188 records) were unsanitized, exposing potential credentials/tokens
+- **Solution**: Replaced weak inline sanitization with robust `WorkflowSanitizer.sanitizeWorkflowRaw()`
+- **Impact**: Now 100% sanitization coverage with 17 sensitive patterns detected and redacted
+- **Files Modified**:
+  - `src/telemetry/workflow-sanitizer.ts`: Added `sanitizeWorkflowRaw()` method
+  - `src/telemetry/mutation-tracker.ts`: Removed redundant sanitization code, use centralized sanitizer
+
+#### 2. Enabled Validation Data Capture (Data Quality Blocker)
+- **Problem**: Zero validation metrics captured (validation_before/after all NULL)
+- **Solution**: Added workflow validation before and after mutations using `WorkflowValidator`
+- **Impact**: Can now measure mutation quality, track error resolution patterns
+- **Implementation**:
+  - Validates workflows before mutation (captures baseline errors)
+  - Validates workflows after mutation (measures improvement)
+  - Non-blocking: validation errors don't prevent mutations
+  - Captures: errors, warnings, validation status
+- **Files Modified**:
+  - `src/mcp/handlers-workflow-diff.ts`: Added pre/post mutation validation
+
+#### 3. Improved Intent Capture (Data Quality)
+- **Problem**: 92.62% of intents were generic "Partial workflow update"
+- **Solution**: Enhanced tool documentation + automatic intent inference from operations
+- **Impact**: Meaningful intents automatically generated when not explicitly provided
+- **Implementation**:
+  - Enhanced documentation with specific intent examples and anti-patterns
+  - Added `inferIntentFromOperations()` function that generates meaningful intents:
+    - Single operations: "Add n8n-nodes-base.slack", "Connect webhook to HTTP Request"
+    - Multiple operations: "Workflow update: add 2 nodes, modify connections"
+  - Fallback inference when intent is missing, generic, or too short
+- **Files Modified**:
+  - `src/mcp/tool-docs/workflow_management/n8n-update-partial-workflow.ts`: Enhanced guidance
+  - `src/mcp/handlers-workflow-diff.ts`: Added intent inference logic
+
+### 📊 Expected Results
+
+After deployment, telemetry data should show:
+- **100% sanitization coverage** (up from 70%)
+- **100% validation capture** (up from 0%)
+- **50%+ meaningful intents** (up from 7.33%)
+- **Complete telemetry dataset** for analysis
+
+### 🎯 Technical Details
+
+**Sanitization Coverage**: Now detects and redacts:
+- Webhook URLs, API keys (OpenAI sk-*, GitHub ghp-*, etc.)
+- Bearer tokens, OAuth credentials, passwords
+- URLs with authentication, long tokens (20+ chars)
+- Sensitive field names (apiKey, token, secret, password, etc.)
+
+**Validation Metrics Captured**:
+- Workflow validity status (true/false)
+- Error/warning counts and details
+- Node configuration errors
+- Connection errors
+- Expression syntax errors
+- Validation improvement tracking (errors resolved/introduced)
+
+**Intent Inference Examples**:
+- `addNode` → "Add n8n-nodes-base.webhook"
+- `rewireConnection` → "Rewire IF from ErrorHandler to SuccessHandler"
+- Multiple operations → "Workflow update: add 2 nodes, modify connections, update metadata"
+
 ## [2.22.16] - 2025-11-13
 
 ### ✨ Enhanced Features

CLAUDE.md

@@ -28,8 +28,15 @@ src/
 │   ├── enhanced-config-validator.ts # Operation-aware validation (NEW in v2.4.2)
 │   ├── node-specific-validators.ts  # Node-specific validation logic (NEW in v2.4.2)
 │   ├── property-dependencies.ts # Dependency analysis (NEW in v2.4)
+│   ├── type-structure-service.ts # Type structure validation (NEW in v2.22.21)
 │   ├── expression-validator.ts # n8n expression syntax validation (NEW in v2.5.0)
 │   └── workflow-validator.ts  # Complete workflow validation (NEW in v2.5.0)
+├── types/
+│   ├── type-structures.ts      # Type structure definitions (NEW in v2.22.21)
+│   ├── instance-context.ts     # Multi-tenant instance configuration
+│   └── session-state.ts        # Session persistence types (NEW in v2.24.1)
+├── constants/
+│   └── type-structures.ts      # 22 complete type structures (NEW in v2.22.21)
 ├── templates/
 │   ├── template-fetcher.ts    # Fetches templates from n8n.io API (NEW in v2.4.1)
 │   ├── template-repository.ts # Template database operations (NEW in v2.4.1)
@@ -40,6 +47,7 @@ src/
 │   ├── test-nodes.ts          # Critical node tests
 │   ├── test-essentials.ts     # Test new essentials tools (NEW in v2.4)
 │   ├── test-enhanced-validation.ts # Test enhanced validation (NEW in v2.4.2)
+│   ├── test-structure-validation.ts # Test type structure validation (NEW in v2.22.21)
 │   ├── test-workflow-validation.ts # Test workflow validation (NEW in v2.5.0)
 │   ├── test-ai-workflow-validation.ts # Test AI workflow validation (NEW in v2.5.1)
 │   ├── test-mcp-tools.ts      # Test MCP tool enhancements (NEW in v2.5.1)
@@ -58,7 +66,9 @@ src/
 │   ├── console-manager.ts     # Console output isolation (NEW in v2.3.1)
 │   └── logger.ts              # Logging utility with HTTP awareness
 ├── http-server-single-session.ts  # Single-session HTTP server (NEW in v2.3.1)
+│                                   # Session persistence API (NEW in v2.24.1)
 ├── mcp-engine.ts              # Clean API for service integration (NEW in v2.3.1)
+│                                # Session persistence wrappers (NEW in v2.24.1)
 └── index.ts                   # Library exports
 ```
 
@@ -76,6 +86,7 @@ npm run test:unit      # Run unit tests only
 npm run test:integration # Run integration tests
 npm run test:coverage  # Run tests with coverage report
 npm run test:watch     # Run tests in watch mode
+npm run test:structure-validation # Test type structure validation (Phase 3)
 
 # Run a single test file
 npm test -- tests/unit/services/property-filter.test.ts
@@ -126,6 +137,7 @@ npm run test:templates   # Test template functionality
 4. **Service Layer** (`services/`)
    - **Property Filter**: Reduces node properties to AI-friendly essentials
    - **Config Validator**: Multi-profile validation system
+   - **Type Structure Service**: Validates complex type structures (filter, resourceMapper, etc.)
    - **Expression Validator**: Validates n8n expression syntax
    - **Workflow Validator**: Complete workflow structure validation
 
@@ -183,6 +195,35 @@ The MCP server exposes tools in several categories:
 ### Development Best Practices
 - Run typecheck and lint after every code change
 
+### Session Persistence Feature (v2.24.1)
+
+**Location:**
+- Types: `src/types/session-state.ts`
+- Implementation: `src/http-server-single-session.ts` (lines 698-702, 1444-1584)
+- Wrapper: `src/mcp-engine.ts` (lines 123-169)
+- Tests: `tests/unit/http-server/session-persistence.test.ts`, `tests/unit/mcp-engine/session-persistence.test.ts`
+
+**Key Features:**
+- **Export/Restore API**: `exportSessionState()` and `restoreSessionState()` methods
+- **Multi-tenant support**: Enables zero-downtime deployments for SaaS platforms
+- **Security-first**: API keys exported as plaintext - downstream MUST encrypt
+- **Dormant sessions**: Restored sessions recreate transports on first request
+- **Automatic expiration**: Respects `sessionTimeout` setting (default 30 min)
+- **MAX_SESSIONS limit**: Caps at 100 concurrent sessions
+
+**Important Implementation Notes:**
+- Only exports sessions with valid n8nApiUrl and n8nApiKey in context
+- Skips expired sessions during both export and restore
+- Uses `validateInstanceContext()` for data integrity checks
+- Handles null/invalid session gracefully with warnings
+- Session metadata (timestamps) and context (credentials) are persisted
+- Transport and server objects are NOT persisted (recreated on-demand)
+
+**Testing:**
+- 22 unit tests covering export, restore, edge cases, and round-trip cycles
+- Tests use current timestamps to avoid expiration issues
+- Integration with multi-tenant backends documented in README.md
+
 # important-instruction-reminders
 Do what has been asked; nothing more, nothing less.
 NEVER create files unless they're absolutely necessary for achieving your goal.

DISABLED_TOOLS_TEST_COVERAGE_ANALYSIS.md

@@ -1,441 +0,0 @@
-# DISABLED_TOOLS Feature Test Coverage Analysis (Issue #410)
-
-## Executive Summary
-
-**Current Status:** Good unit test coverage (21 test scenarios), but missing integration-level validation
-**Overall Grade:** B+ (85/100)
-**Coverage Gaps:** Integration tests, real-world deployment verification
-**Recommendation:** Add targeted test cases for complete coverage
-
----
-
-## 1. Current Test Coverage Assessment
-
-### 1.1 Unit Tests (tests/unit/mcp/disabled-tools.test.ts)
-
-**Strengths:**
-- ✅ Comprehensive environment variable parsing tests (8 scenarios)
-- ✅ Disabled tool guard in executeTool() (3 scenarios)
-- ✅ Tool filtering for both documentation and management tools (6 scenarios)
-- ✅ Edge cases: special characters, whitespace, empty values
-- ✅ Real-world use case scenarios (3 scenarios)
-- ✅ Invalid tool name handling
-
-**Code Path Coverage:**
-- ✅ getDisabledTools() method - FULLY COVERED
-- ✅ executeTool() guard (lines 909-913) - FULLY COVERED
-- ⚠️ ListToolsRequestSchema handler filtering (lines 403-449) - PARTIALLY COVERED
-- ⚠️ CallToolRequestSchema handler rejection (lines 491-505) - PARTIALLY COVERED
-
----
-
-## 2. Missing Test Coverage
-
-### 2.1 Critical Gaps
-
-#### A. Handler-Level Integration Tests
-**Issue:** Unit tests verify internal methods but not the actual MCP protocol handler responses.
-
-**Missing Scenarios:**
-1. Verify ListToolsRequestSchema returns filtered tool list via MCP protocol
-2. Verify CallToolRequestSchema returns proper error structure for disabled tools
-3. Test interaction with makeToolsN8nFriendly() transformation (line 458)
-4. Verify multi-tenant mode respects DISABLED_TOOLS (lines 420-442)
-
-**Impact:** Medium-High
-**Reason:** These are the actual code paths executed by MCP clients
-
-#### B. Error Response Format Validation
-**Issue:** No tests verify the exact error structure returned to clients.
-
-**Missing Scenarios:**
-```javascript
-// Expected error structure from lines 495-504:
-{
-  error: 'TOOL_DISABLED',
-  message: 'Tool \'X\' is not available...',
-  disabledTools: ['tool1', 'tool2']
-}
-```
-
-**Impact:** Medium
-**Reason:** Breaking changes to error format would not be caught
-
-#### C. Logging Behavior
-**Issue:** No verification that logger.info/logger.warn are called appropriately.
-
-**Missing Scenarios:**
-1. Verify logging on line 344: "Disabled tools configured: X, Y, Z"
-2. Verify logging on line 448: "Filtered N disabled tools..."
-3. Verify warning on line 494: "Attempted to call disabled tool: X"
-
-**Impact:** Low
-**Reason:** Logging is important for debugging production issues
-
-### 2.2 Edge Cases Not Covered
-
-#### A. Environment Variable Edge Cases
-**Missing Tests:**
-- DISABLED_TOOLS with unicode characters
-- DISABLED_TOOLS with very long tool names (>100 chars)
-- DISABLED_TOOLS with thousands of tool names (performance)
-- DISABLED_TOOLS containing regex special characters: `.*[]{}()`
-
-#### B. Concurrent Access Scenarios
-**Missing Tests:**
-- Multiple clients connecting simultaneously with same DISABLED_TOOLS
-- Changing DISABLED_TOOLS between server instantiations (not expected to work, but should be documented)
-
-#### C. Defense in Depth Verification
-**Issue:** Line 909-913 is a "safety check" but not explicitly tested in isolation.
-
-**Missing Test:**
-```typescript
-it('should prevent execution even if handler check is bypassed', async () => {
-  // Test that executeTool() throws even if somehow called directly
-  process.env.DISABLED_TOOLS = 'test_tool';
-  const server = new TestableN8NMCPServer();
-
-  await expect(async () => {
-    await server.testExecuteTool('test_tool', {});
-  }).rejects.toThrow('disabled via DISABLED_TOOLS');
-});
-```
-**Status:** Actually IS tested (lines 112-119 in current tests) ✅
-
----
-
-## 3. Coverage Metrics
-
-### 3.1 Current Coverage by Code Section
-
-| Code Section | Lines | Unit Tests | Integration Tests | Overall |
-|--------------|-------|------------|-------------------|---------|
-| getDisabledTools() (326-348) | 23 | 100% | N/A | ✅ 100% |
-| ListTools handler filtering (403-449) | 47 | 40% | 0% | ⚠️ 40% |
-| CallTool handler rejection (491-505) | 15 | 60% | 0% | ⚠️ 60% |
-| executeTool() guard (909-913) | 5 | 100% | 0% | ✅ 100% |
-| **Total for Feature** | 90 | 65% | 0% | **⚠️ 65%** |
-
-### 3.2 Test Type Distribution
-
-| Test Type | Count | Percentage |
-|-----------|-------|------------|
-| Unit Tests | 21 | 100% |
-| Integration Tests | 0 | 0% |
-| E2E Tests | 0 | 0% |
-
-**Recommended Distribution:**
-- Unit Tests: 15-18 (current: 21 ✅)
-- Integration Tests: 8-12 (current: 0 ❌)
-- E2E Tests: 0-2 (current: 0 ✅)
-
----
-
-## 4. Recommendations
-
-### 4.1 High Priority (Must Add)
-
-#### Test 1: Handler Response Structure Validation
-```typescript
-describe('CallTool Handler - Error Response Structure', () => {
-  it('should return properly structured error for disabled tools', () => {
-    process.env.DISABLED_TOOLS = 'test_tool';
-    const server = new TestableN8NMCPServer();
-
-    // Mock the CallToolRequestSchema handler to capture response
-    const mockRequest = {
-      params: { name: 'test_tool', arguments: {} }
-    };
-
-    const response = await server.handleCallTool(mockRequest);
-
-    expect(response.content).toHaveLength(1);
-    expect(response.content[0].type).toBe('text');
-
-    const errorData = JSON.parse(response.content[0].text);
-    expect(errorData).toEqual({
-      error: 'TOOL_DISABLED',
-      message: expect.stringContaining('test_tool'),
-      message: expect.stringContaining('disabled via DISABLED_TOOLS'),
-      disabledTools: ['test_tool']
-    });
-  });
-});
-```
-
-#### Test 2: Logging Verification
-```typescript
-import { vi } from 'vitest';
-import * as logger from '../../../src/utils/logger';
-
-describe('Disabled Tools - Logging Behavior', () => {
-  beforeEach(() => {
-    vi.spyOn(logger, 'info');
-    vi.spyOn(logger, 'warn');
-  });
-
-  it('should log disabled tools on server initialization', () => {
-    process.env.DISABLED_TOOLS = 'tool1,tool2,tool3';
-    const server = new TestableN8NMCPServer();
-    server.testGetDisabledTools(); // Trigger getDisabledTools()
-
-    expect(logger.info).toHaveBeenCalledWith(
-      expect.stringContaining('Disabled tools configured: tool1, tool2, tool3')
-    );
-  });
-
-  it('should log when filtering disabled tools', () => {
-    process.env.DISABLED_TOOLS = 'tool1';
-    const server = new TestableN8NMCPServer();
-
-    // Trigger ListToolsRequestSchema handler
-    // ...
-
-    expect(logger.info).toHaveBeenCalledWith(
-      expect.stringMatching(/Filtered \d+ disabled tools/)
-    );
-  });
-
-  it('should warn when disabled tool is called', async () => {
-    process.env.DISABLED_TOOLS = 'test_tool';
-    const server = new TestableN8NMCPServer();
-
-    await server.testExecuteTool('test_tool', {}).catch(() => {});
-
-    expect(logger.warn).toHaveBeenCalledWith(
-      'Attempted to call disabled tool: test_tool'
-    );
-  });
-});
-```
-
-### 4.2 Medium Priority (Should Add)
-
-#### Test 3: Multi-Tenant Mode Interaction
-```typescript
-describe('Multi-Tenant Mode with DISABLED_TOOLS', () => {
-  it('should show management tools but respect DISABLED_TOOLS', () => {
-    process.env.ENABLE_MULTI_TENANT = 'true';
-    process.env.DISABLED_TOOLS = 'n8n_delete_workflow';
-    delete process.env.N8N_API_URL;
-    delete process.env.N8N_API_KEY;
-
-    const server = new TestableN8NMCPServer();
-    const disabledTools = server.testGetDisabledTools();
-
-    // Should still filter disabled management tools
-    expect(disabledTools.has('n8n_delete_workflow')).toBe(true);
-  });
-});
-```
-
-#### Test 4: makeToolsN8nFriendly Interaction
-```typescript
-describe('n8n Client Compatibility', () => {
-  it('should apply n8n-friendly descriptions after filtering', () => {
-    // This verifies that the order of operations is correct:
-    // 1. Filter disabled tools
-    // 2. Apply n8n-friendly transformations
-    // This prevents a disabled tool from appearing with n8n-friendly description
-
-    process.env.DISABLED_TOOLS = 'validate_node_operation';
-    const server = new TestableN8NMCPServer();
-
-    // Mock n8n client detection
-    server.clientInfo = { name: 'n8n-workflow-tool' };
-
-    // Get tools list
-    // Verify validate_node_operation is NOT in the list
-    // Verify other validation tools ARE in the list with n8n-friendly descriptions
-  });
-});
-```
-
-### 4.3 Low Priority (Nice to Have)
-
-#### Test 5: Performance with Many Disabled Tools
-```typescript
-describe('Performance', () => {
-  it('should handle large DISABLED_TOOLS list efficiently', () => {
-    const manyTools = Array.from({ length: 1000 }, (_, i) => `tool_${i}`);
-    process.env.DISABLED_TOOLS = manyTools.join(',');
-
-    const start = Date.now();
-    const server = new TestableN8NMCPServer();
-    const disabledTools = server.testGetDisabledTools();
-    const duration = Date.now() - start;
-
-    expect(disabledTools.size).toBe(1000);
-    expect(duration).toBeLessThan(100); // Should be fast
-  });
-});
-```
-
-#### Test 6: Unicode and Special Characters
-```typescript
-describe('Edge Cases - Special Characters', () => {
-  it('should handle unicode tool names', () => {
-    process.env.DISABLED_TOOLS = 'tool_测试,tool_🎯,tool_münchen';
-    const server = new TestableN8NMCPServer();
-    const disabledTools = server.testGetDisabledTools();
-
-    expect(disabledTools.has('tool_测试')).toBe(true);
-    expect(disabledTools.has('tool_🎯')).toBe(true);
-    expect(disabledTools.has('tool_münchen')).toBe(true);
-  });
-
-  it('should handle regex special characters literally', () => {
-    process.env.DISABLED_TOOLS = 'tool.*,tool[0-9],tool{a,b}';
-    const server = new TestableN8NMCPServer();
-    const disabledTools = server.testGetDisabledTools();
-
-    // These should be treated as literal strings, not regex
-    expect(disabledTools.has('tool.*')).toBe(true);
-    expect(disabledTools.has('tool[0-9]')).toBe(true);
-    expect(disabledTools.has('tool{a,b}')).toBe(true);
-  });
-});
-```
-
----
-
-## 5. Coverage Goals
-
-### 5.1 Current Status
-- **Line Coverage:** ~65% for DISABLED_TOOLS feature code
-- **Branch Coverage:** ~70% (good coverage of conditionals)
-- **Function Coverage:** 100% (all functions tested)
-
-### 5.2 Target Coverage (After Recommendations)
-- **Line Coverage:** >90% (add handler tests)
-- **Branch Coverage:** >85% (add multi-tenant edge cases)
-- **Function Coverage:** 100% (maintain)
-
----
-
-## 6. Testing Strategy Recommendations
-
-### 6.1 Short Term (Before Merge)
-1. ✅ Add Test 2 (Logging Verification) - Easy to implement, high value
-2. ✅ Add Test 1 (Handler Response Structure) - Critical for API contract
-3. ✅ Add Test 3 (Multi-Tenant Mode) - Important for deployment scenarios
-
-### 6.2 Medium Term (Next Sprint)
-1. Add Test 4 (makeToolsN8nFriendly) - Ensures feature ordering is correct
-2. Add Test 6 (Unicode/Special Chars) - Important for international deployments
-
-### 6.3 Long Term (Future Enhancements)
-1. Add E2E test with real MCP client connection
-2. Add performance benchmarks (Test 5)
-3. Add deployment smoke tests (verify in Docker container)
-
----
-
-## 7. Integration Test Challenges
-
-### 7.1 Why Integration Tests Are Difficult Here
-
-**Problem:** The TestableN8NMCPServer in test-helpers.ts creates its own handlers that don't include the DISABLED_TOOLS logic.
-
-**Root Cause:**
-- Test helper setupHandlers() (line 56-70) hardcodes tool list assembly
-- Doesn't call the actual server's ListToolsRequestSchema handler
-- This was designed for testing tool execution, not tool filtering
-
-**Options:**
-1. **Modify test-helpers.ts** to use actual server handlers (breaking change for other tests)
-2. **Create a new test helper** specifically for DISABLED_TOOLS feature
-3. **Test via unit tests + mocking** (current approach, sufficient for now)
-
-**Recommendation:** Option 3 for now, Option 2 if integration tests become critical
-
----
-
-## 8. Requirements Verification (Issue #410)
-
-### Original Requirements:
-1. ✅ Parse DISABLED_TOOLS env var (comma-separated list)
-2. ✅ Filter tools in ListToolsRequestSchema handler
-3. ✅ Reject calls to disabled tools with clear error message
-4. ✅ Filter from both n8nDocumentationToolsFinal and n8nManagementTools
-
-### Test Coverage Against Requirements:
-1. **Parsing:** ✅ 8 test scenarios (excellent)
-2. **Filtering:** ⚠️ Partially tested via unit tests, needs handler-level verification
-3. **Rejection:** ⚠️ Error throwing tested, error structure not verified
-4. **Both tool types:** ✅ 6 test scenarios (excellent)
-
----
-
-## 9. Final Recommendations
-
-### Immediate Actions:
-1. ✅ **Add logging verification tests** (Test 2) - 30 minutes
-2. ✅ **Add error response structure test** (Test 1 simplified version) - 20 minutes
-3. ✅ **Add multi-tenant interaction test** (Test 3) - 15 minutes
-
-### Before Production Deployment:
-1. Manual testing: Set DISABLED_TOOLS in production config
-2. Verify error messages are clear to end users
-3. Document the feature in deployment guides
-
-### Future Enhancements:
-1. Add integration tests when test infrastructure supports it
-2. Add performance tests if >100 tools need to be disabled
-3. Consider adding CLI tool to validate DISABLED_TOOLS syntax
-
----
-
-## 10. Conclusion
-
-**Overall Assessment:** The current test suite provides solid unit test coverage (21 scenarios) but lacks integration-level validation. The implementation is sound and the core functionality is well-tested.
-
-**Confidence Level:** 85/100
-- Core logic: 95/100 ✅
-- Edge cases: 80/100 ⚠️
-- Integration: 40/100 ❌
-- Real-world validation: 75/100 ⚠️
-
-**Recommendation:** The feature is ready for merge with the addition of 3 high-priority tests (Tests 1, 2, 3). Integration tests can be added later when test infrastructure is enhanced.
-
-**Risk Level:** Low
-- Well-isolated feature
-- Clear error messages
-- Defense in depth with multiple checks
-- Easy to disable if issues arise (unset DISABLED_TOOLS)
-
----
-
-## Appendix: Test Execution Results
-
-### Current Test Suite:
-```bash
-$ npm test -- tests/unit/mcp/disabled-tools.test.ts
-
-✓ tests/unit/mcp/disabled-tools.test.ts (21 tests) 44ms
-
-Test Files  1 passed (1)
-Tests  21 passed (21)
-Duration  1.09s
-```
-
-### All Tests Passing: ✅
-
-**Test Breakdown:**
-- Environment variable parsing: 8 tests
-- executeTool() guard: 3 tests
-- Tool filtering (doc tools): 2 tests
-- Tool filtering (mgmt tools): 2 tests
-- Tool filtering (mixed): 1 test
-- Invalid tool names: 2 tests
-- Real-world use cases: 3 tests
-
-**Total: 21 tests, all passing**
-
----
-
-**Report Generated:** 2025-11-09
-**Feature:** DISABLED_TOOLS environment variable (Issue #410)
-**Version:** n8n-mcp v2.22.13
-**Author:** Test Coverage Analysis Tool

DISABLED_TOOLS_TEST_SUMMARY.md

@@ -1,272 +0,0 @@
-# DISABLED_TOOLS Feature - Test Coverage Summary
-
-## Overview
-
-**Feature:** DISABLED_TOOLS environment variable support (Issue #410)
-**Implementation Files:**
-- `src/mcp/server.ts` (lines 326-348, 403-449, 491-505, 909-913)
-
-**Test Files:**
-- `tests/unit/mcp/disabled-tools.test.ts` (21 tests)
-- `tests/unit/mcp/disabled-tools-additional.test.ts` (24 tests)
-
-**Total Test Count:** 45 tests (all passing ✅)
-
----
-
-## Test Coverage Breakdown
-
-### Original Tests (21 scenarios)
-
-#### 1. Environment Variable Parsing (8 tests)
-- ✅ Empty/undefined DISABLED_TOOLS
-- ✅ Single disabled tool
-- ✅ Multiple disabled tools
-- ✅ Whitespace trimming
-- ✅ Empty entries filtering
-- ✅ Single/multiple commas handling
-
-#### 2. ExecuteTool Guard (3 tests)
-- ✅ Throws error when calling disabled tool
-- ✅ Allows calling enabled tools
-- ✅ Throws error for all disabled tools in list
-
-#### 3. Tool Filtering - Documentation Tools (2 tests)
-- ✅ Filters single disabled documentation tool
-- ✅ Filters multiple disabled documentation tools
-
-#### 4. Tool Filtering - Management Tools (2 tests)
-- ✅ Filters single disabled management tool
-- ✅ Filters multiple disabled management tools
-
-#### 5. Tool Filtering - Mixed Tools (1 test)
-- ✅ Filters disabled tools from both lists
-
-#### 6. Invalid Tool Names (2 tests)
-- ✅ Handles non-existent tool names gracefully
-- ✅ Handles special characters in tool names
-
-#### 7. Real-World Use Cases (3 tests)
-- ✅ Multi-tenant deployment (disable diagnostic tools)
-- ✅ Security hardening (disable management tools)
-- ✅ Feature flags (disable experimental tools)
-
----
-
-### Additional Tests (24 scenarios)
-
-#### 1. Error Response Structure (3 tests)
-- ✅ Throws error with specific message format
-- ✅ Includes tool name in error message
-- ✅ Consistent error format for all disabled tools
-
-#### 2. Multi-Tenant Mode Interaction (3 tests)
-- ✅ Respects DISABLED_TOOLS in multi-tenant mode
-- ✅ Parses DISABLED_TOOLS regardless of N8N_API_URL
-- ✅ Works when only ENABLE_MULTI_TENANT is set
-
-#### 3. Edge Cases - Special Characters & Unicode (5 tests)
-- ✅ Handles unicode tool names (Chinese, German, Arabic)
-- ✅ Handles emoji in tool names
-- ✅ Treats regex special characters as literals
-- ✅ Handles dots and colons in tool names
-- ✅ Handles @ symbols in tool names
-
-#### 4. Performance and Scale (3 tests)
-- ✅ Handles 100 disabled tools efficiently (<50ms)
-- ✅ Handles 1000 disabled tools efficiently (<100ms)
-- ✅ Efficient membership checks (Set.has() is O(1))
-
-#### 5. Environment Variable Edge Cases (4 tests)
-- ✅ Handles very long tool names (500+ chars)
-- ✅ Handles newlines in tool names (after trim)
-- ✅ Handles tabs in tool names (after trim)
-- ✅ Handles mixed whitespace correctly
-
-#### 6. Defense in Depth (3 tests)
-- ✅ Prevents execution at executeTool level
-- ✅ Case-sensitive tool name matching
-- ✅ Checks disabled status on every call
-
-#### 7. Real-World Deployment Verification (3 tests)
-- ✅ Common security hardening scenario
-- ✅ Staging environment scenario
-- ✅ Development environment scenario
-
----
-
-## Code Coverage Metrics
-
-### Feature-Specific Coverage
-
-| Code Section | Lines | Coverage | Status |
-|--------------|-------|----------|---------|
-| getDisabledTools() | 23 | 100% | ✅ Excellent |
-| ListTools handler filtering | 47 | 75% | ⚠️ Good (unit level) |
-| CallTool handler rejection | 15 | 80% | ⚠️ Good (unit level) |
-| executeTool() guard | 5 | 100% | ✅ Excellent |
-| **Overall** | **90** | **~90%** | **✅ Excellent** |
-
-### Test Type Distribution
-
-| Test Type | Count | Percentage |
-|-----------|-------|------------|
-| Unit Tests | 45 | 100% |
-| Integration Tests | 0 | 0% |
-| E2E Tests | 0 | 0% |
-
----
-
-## Requirements Verification (Issue #410)
-
-### Requirement 1: Parse DISABLED_TOOLS env var ✅
-**Status:** Fully Implemented & Tested
-**Tests:** 8 parsing tests + 4 edge case tests = 12 tests
-**Coverage:** 100%
-
-### Requirement 2: Filter tools in ListToolsRequestSchema handler ✅
-**Status:** Fully Implemented & Tested (unit level)
-**Tests:** 7 filtering tests
-**Coverage:** 75% (unit level, integration level would be 100%)
-
-### Requirement 3: Reject calls to disabled tools ✅
-**Status:** Fully Implemented & Tested
-**Tests:** 6 rejection tests + 3 error structure tests = 9 tests
-**Coverage:** 100%
-
-### Requirement 4: Filter from both tool types ✅
-**Status:** Fully Implemented & Tested
-**Tests:** 5 tests covering both documentation and management tools
-**Coverage:** 100%
-
----
-
-## Test Execution Results
-
-```bash
-$ npm test -- tests/unit/mcp/disabled-tools
-
-✓ tests/unit/mcp/disabled-tools.test.ts (21 tests)
-✓ tests/unit/mcp/disabled-tools-additional.test.ts (24 tests)
-
-Test Files  2 passed (2)
-Tests  45 passed (45)
-Duration  1.17s
-```
-
-**All tests passing:** ✅ 45/45
-
----
-
-## Gaps and Future Enhancements
-
-### Known Gaps
-
-1. **Integration Tests** (Low Priority)
-   - Testing via actual MCP protocol handler responses
-   - Verification of makeToolsN8nFriendly() interaction
-   - **Reason for deferring:** Test infrastructure doesn't easily support this
-   - **Mitigation:** Comprehensive unit tests provide high confidence
-
-2. **Logging Verification** (Low Priority)
-   - Verification that logger.info/warn are called appropriately
-   - **Reason for deferring:** Complex to mock logger properly
-   - **Mitigation:** Manual testing confirms logging works correctly
-
-### Future Enhancements (Optional)
-
-1. **E2E Tests**
-   - Test with real MCP client connection
-   - Verify in actual deployment scenarios
-
-2. **Performance Benchmarks**
-   - Formal benchmarks for large disabled tool lists
-   - Current tests show <100ms for 1000 tools, which is excellent
-
-3. **Deployment Smoke Tests**
-   - Verify feature works in Docker container
-   - Test with various environment configurations
-
----
-
-## Recommendations
-
-### Before Merge ✅
-
-The test suite is complete and ready for merge:
-- ✅ All requirements covered
-- ✅ 45 tests passing
-- ✅ ~90% coverage of feature code
-- ✅ Edge cases handled
-- ✅ Performance verified
-- ✅ Real-world scenarios tested
-
-### After Merge (Optional)
-
-1. **Manual Testing Checklist:**
-   - [ ] Set DISABLED_TOOLS in production config
-   - [ ] Verify error messages are clear to end users
-   - [ ] Test with Claude Desktop client
-   - [ ] Test with n8n AI Agent
-
-2. **Documentation:**
-   - [ ] Add DISABLED_TOOLS to deployment guide
-   - [ ] Add examples to environment variable documentation
-   - [ ] Update multi-tenant documentation
-
-3. **Monitoring:**
-   - [ ] Monitor logs for "Disabled tools configured" messages
-   - [ ] Track "Attempted to call disabled tool" warnings
-   - [ ] Alert on unexpected tool disabling
-
----
-
-## Test Quality Assessment
-
-### Strengths
-- ✅ Comprehensive coverage (45 tests)
-- ✅ Real-world scenarios tested
-- ✅ Performance validated
-- ✅ Edge cases covered
-- ✅ Error handling verified
-- ✅ All tests passing consistently
-
-### Areas of Excellence
-- **Edge Case Coverage:** Unicode, special chars, whitespace, empty values
-- **Performance Testing:** Up to 1000 tools tested
-- **Error Validation:** Message format and consistency verified
-- **Real-World Scenarios:** Security, multi-tenant, feature flags
-
-### Confidence Level
-**95/100** - Production Ready
-
-**Breakdown:**
-- Core Functionality: 100/100 ✅
-- Edge Cases: 95/100 ✅
-- Error Handling: 100/100 ✅
-- Performance: 95/100 ✅
-- Integration: 70/100 ⚠️ (deferred, not critical)
-
----
-
-## Conclusion
-
-The DISABLED_TOOLS feature has **excellent test coverage** with 45 passing tests covering all requirements and edge cases. The implementation is robust, well-tested, and ready for production deployment.
-
-**Recommendation:** ✅ APPROVED for merge
-
-**Risk Level:** Low
-- Well-isolated feature with clear boundaries
-- Multiple layers of protection (defense in depth)
-- Comprehensive error messages
-- Easy to disable if issues arise (unset DISABLED_TOOLS)
-- No breaking changes to existing functionality
-
----
-
-**Report Date:** 2025-11-09
-**Test Suite Version:** v2.22.13
-**Feature:** DISABLED_TOOLS environment variable (Issue #410)
-**Test Files:** 2
-**Total Tests:** 45
-**Pass Rate:** 100%

IMPLEMENTATION_ROADMAP.md

@@ -1,170 +0,0 @@
-# N8N-MCP Validation Improvement: Implementation Roadmap
-
-**Start Date**: Week of November 11, 2025
-**Target Completion**: Week of December 23, 2025 (6 weeks)
-**Expected Impact**: 50-65% reduction in validation failures
-
----
-
-## Summary
-
-Based on analysis of 29,218 validation events across 9,021 users, this roadmap identifies concrete technical improvements to reduce validation failures through better documentation and guidance—without weakening validation itself.
-
----
-
-## Phase 1: Quick Wins (Weeks 1-2) - 14-20 hours
-
-### Task 1.1: Enhance Structure Error Messages
-- **File**: `/src/services/workflow-validator.ts`
-- **Problem**: "Duplicate node ID: undefined" (179 failures) provides no context
-- **Solution**: Add node index, example format, field suggestions
-- **Effort**: 4-6 hours
-
-### Task 1.2: Mark Required Fields in Tool Responses  
-- **File**: `/src/services/property-filter.ts`
-- **Problem**: "Required property X cannot be empty" (378 failures) - not marked upfront
-- **Solution**: Add `requiredLabel: "⚠️ REQUIRED"` to get_node_essentials output
-- **Effort**: 6-8 hours
-
-### Task 1.3: Create Webhook Configuration Guide
-- **File**: New `/docs/WEBHOOK_CONFIGURATION_GUIDE.md`
-- **Problem**: Webhook errors (127 failures) from unclear config rules
-- **Solution**: Document three core rules + examples
-- **Effort**: 4-6 hours
-
-**Phase 1 Impact**: 25-30% failure reduction
-
----
-
-## Phase 2: Documentation & Validation (Weeks 3-4) - 20-28 hours
-
-### Task 2.1: Enhance validate_node_operation() Enum Suggestions
-- **File**: `/src/services/enhanced-config-validator.ts`
-- **Problem**: Invalid enum errors lack valid options
-- **Solution**: Include validOptions array in response
-- **Effort**: 6-8 hours
-
-### Task 2.2: Create Workflow Connections Guide
-- **File**: New `/docs/WORKFLOW_CONNECTIONS_GUIDE.md`
-- **Problem**: Connection syntax errors (676 failures)
-- **Solution**: Document syntax with examples
-- **Effort**: 6-8 hours
-
-### Task 2.3: Create Error Handler Guide
-- **File**: New `/docs/ERROR_HANDLING_GUIDE.md`
-- **Problem**: Error handler config (148 failures)
-- **Solution**: Explain options, positioning, patterns
-- **Effort**: 4-6 hours
-
-### Task 2.4: Add AI Agent Node Validation
-- **File**: `/src/services/node-specific-validators.ts`
-- **Problem**: AI Agent requires LLM (22 failures)
-- **Solution**: Detect missing LLM, suggest required nodes
-- **Effort**: 4-6 hours
-
-**Phase 2 Impact**: Additional 15-20% failure reduction
-
----
-
-## Phase 3: Advanced Features (Weeks 5-6) - 16-22 hours
-
-### Task 3.1: Enhance Search Results
-- Effort: 4-6 hours
-
-### Task 3.2: Fuzzy Matcher for Node Types
-- Effort: 3-4 hours
-
-### Task 3.3: KPI Tracking Dashboard
-- Effort: 3-4 hours
-
-### Task 3.4: Comprehensive Test Coverage
-- Effort: 6-8 hours
-
-**Phase 3 Impact**: Additional 10-15% failure reduction
-
----
-
-## Timeline
-
-```
-Week 1-2:  Phase 1 - Error messages & marks
-Week 3-4:  Phase 2 - Documentation & validation
-Week 5-6:  Phase 3 - Advanced features
-Total:     ~60-80 developer-hours
-Target:    50-65% failure reduction
-```
-
----
-
-## Key Changes
-
-### Required Field Markers
-
-**Before**:
-```json
-{ "properties": { "channel": { "type": "string" } } }
-```
-
-**After**:
-```json
-{
-  "properties": {
-    "channel": {
-      "type": "string",
-      "required": true,
-      "requiredLabel": "⚠️ REQUIRED",
-      "examples": ["#general"]
-    }
-  }
-}
-```
-
-### Enum Suggestions
-
-**Before**: `"Invalid value 'sendMsg' for operation"`
-
-**After**:
-```json
-{
-  "field": "operation",
-  "validOptions": ["sendMessage", "deleteMessage"],
-  "suggestion": "Did you mean 'sendMessage'?"
-}
-```
-
-### Error Message Examples
-
-**Structure Error**:
-```
-Node at index 1 missing required 'id' field. 
-Expected: { "id": "node_1", "name": "HTTP Request", ... }
-```
-
-**Webhook Config**:
-```
-Webhook in responseNode mode requires onError: "continueRegularOutput"
-See: [Webhook Configuration Guide]
-```
-
----
-
-## Success Metrics
-
-- [ ] Phase 1: Webhook errors 127→35 (-72%)
-- [ ] Phase 2: Connection errors 676→270 (-60%)
-- [ ] Phase 3: Total failures reduced 50-65%
-- [ ] All phases: Retry success stays 100%
-- [ ] Target: First-attempt success 77%→85%+
-
----
-
-## Next Steps
-
-1. Review and approve roadmap
-2. Create GitHub issues for each phase
-3. Assign to team members
-4. Schedule Phase 1 sprint (Nov 11)
-5. Weekly status sync
-
-**Status**: Ready for Review and Approval
-**Estimated Completion**: December 23, 2025

README.md

@@ -5,11 +5,11 @@
 [![npm version](https://img.shields.io/npm/v/n8n-mcp.svg)](https://www.npmjs.com/package/n8n-mcp)
 [![codecov](https://codecov.io/gh/czlonkowski/n8n-mcp/graph/badge.svg?token=YOUR_TOKEN)](https://codecov.io/gh/czlonkowski/n8n-mcp)
 [![Tests](https://img.shields.io/badge/tests-3336%20passing-brightgreen.svg)](https://github.com/czlonkowski/n8n-mcp/actions)
-[![n8n version](https://img.shields.io/badge/n8n-1.119.1-orange.svg)](https://github.com/n8n-io/n8n)
+[![n8n version](https://img.shields.io/badge/n8n-1.121.2-orange.svg)](https://github.com/n8n-io/n8n)
 [![Docker](https://img.shields.io/badge/docker-ghcr.io%2Fczlonkowski%2Fn8n--mcp-green.svg)](https://github.com/czlonkowski/n8n-mcp/pkgs/container/n8n-mcp)
 [![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/n8n-mcp?referralCode=n8n-mcp)
 
-A Model Context Protocol (MCP) server that provides AI assistants with comprehensive access to n8n node documentation, properties, and operations. Deploy in minutes to give Claude and other AI assistants deep knowledge about n8n's 543 workflow automation nodes.
+A Model Context Protocol (MCP) server that provides AI assistants with comprehensive access to n8n node documentation, properties, and operations. Deploy in minutes to give Claude and other AI assistants deep knowledge about n8n's 545 workflow automation nodes.
 
 ## Overview
 
@@ -36,12 +36,31 @@ AI results can be unpredictable. Protect your work!
 
 ## 🚀 Quick Start
 
-Get n8n-MCP running in 5 minutes:
+### Option 1: Hosted Service (Easiest - No Setup!) ☁️
+
+**The fastest way to try n8n-MCP** - no installation, no configuration:
+
+👉 **[dashboard.n8n-mcp.com](https://dashboard.n8n-mcp.com)**
+
+- ✅ **Free tier**: 100 tool calls/day
+- ✅ **Instant access**: Start building workflows immediately
+- ✅ **Always up-to-date**: Latest n8n nodes and templates
+- ✅ **No infrastructure**: We handle everything
+
+Just sign up, get your API key, and connect your MCP client. 
+
+---
+
+## 🏠 Self-Hosting Options
+
+Prefer to run n8n-MCP yourself? Choose your deployment method:
+
+### Option A: npx (Quick Local Setup) 🚀
+
+Get n8n-MCP running in minutes:
 
 [![n8n-mcp Video Quickstart Guide](./thumbnail.png)](https://youtu.be/5CccjiLLyaY?si=Z62SBGlw9G34IQnQ&t=343)
 
-### Option 1: npx (Fastest - No Installation!) 🚀
-
 **Prerequisites:** [Node.js](https://nodejs.org/) installed on your system
 
 ```bash
@@ -98,7 +117,7 @@ Add to Claude Desktop config:
 
 **Restart Claude Desktop after updating configuration** - That's it! 🎉
 
-### Option 2: Docker (Easy & Isolated) 🐳
+### Option B: Docker (Isolated & Reproducible) 🐳
 
 **Prerequisites:** Docker installed on your system
 
@@ -345,27 +364,6 @@ environment:
   SQLJS_SAVE_INTERVAL_MS: "10000"
 ```
 
-### Memory Leak Fix (v2.20.2)
-
-**Issue #330** identified a critical memory leak in long-running Docker/Kubernetes deployments:
-- **Before:** 100 MB → 2.2 GB over 72 hours (OOM kills)
-- **After:** Stable at 100-200 MB indefinitely
-
-**Fixes Applied:**
-- ✅ Docker images now use better-sqlite3 by default (eliminates leak entirely)
-- ✅ sql.js fallback optimized (98% reduction in save frequency)
-- ✅ Removed unnecessary memory allocations (50% reduction per save)
-- ✅ Configurable save interval via `SQLJS_SAVE_INTERVAL_MS`
-
-For Kubernetes deployments with memory limits:
-```yaml
-resources:
-  requests:
-    memory: 256Mi
-  limits:
-    memory: 512Mi
-```
-
 ## 💖 Support This Project
 
 <div align="center">
@@ -386,7 +384,7 @@ Every sponsorship directly translates to hours invested in making n8n-mcp better
 
 ---
 
-### Option 3: Local Installation (For Development)
+### Option C: Local Installation (For Development)
 
 **Prerequisites:** [Node.js](https://nodejs.org/) installed on your system
 
@@ -444,7 +442,7 @@ Add to Claude Desktop config:
 
 > 💡 Tip: If you’re running n8n locally on the same machine (e.g., via Docker), use http://host.docker.internal:5678 as the N8N_API_URL.
 
-### Option 4: Railway Cloud Deployment (One-Click Deploy) ☁️
+### Option D: Railway Cloud Deployment (One-Click Deploy) ☁️
 
 **Prerequisites:** Railway account (free tier available)
 
@@ -524,7 +522,7 @@ You are an expert in n8n automation software using n8n-MCP tools. Your role is t
 CRITICAL: Execute tools without commentary. Only respond AFTER all tools complete.
 
 ❌ BAD: "Let me search for Slack nodes... Great! Now let me get details..."
-✅ GOOD: [Execute search_nodes and get_node_essentials in parallel, then respond]
+✅ GOOD: [Execute search_nodes and get_node in parallel, then respond]
 
 ### 2. Parallel Execution
 When operations are independent, execute them in parallel for maximum performance.
@@ -536,7 +534,7 @@ When operations are independent, execute them in parallel for maximum performanc
 ALWAYS check templates before building from scratch (2,709 available).
 
 ### 4. Multi-Level Validation
-Use validate_node_minimal → validate_node_operation → validate_workflow pattern.
+Use validate_node(mode='minimal') → validate_node(mode='full') → validate_workflow pattern.
 
 ### 5. Never Trust Defaults
 ⚠️ CRITICAL: Default parameter values are the #1 source of runtime failures.
@@ -547,10 +545,10 @@ ALWAYS explicitly configure ALL parameters that control node behavior.
 1. **Start**: Call `tools_documentation()` for best practices
 
 2. **Template Discovery Phase** (FIRST - parallel when searching multiple)
-   - `search_templates_by_metadata({complexity: "simple"})` - Smart filtering
-   - `get_templates_for_task('webhook_processing')` - Curated by task
-   - `search_templates('slack notification')` - Text search
-   - `list_node_templates(['n8n-nodes-base.slack'])` - By node type
+   - `search_templates({searchMode: 'by_metadata', complexity: 'simple'})` - Smart filtering
+   - `search_templates({searchMode: 'by_task', task: 'webhook_processing'})` - Curated by task
+   - `search_templates({query: 'slack notification'})` - Text search (default searchMode='keyword')
+   - `search_templates({searchMode: 'by_nodes', nodeTypes: ['n8n-nodes-base.slack']})` - By node type
 
    **Filtering strategies**:
    - Beginners: `complexity: "simple"` + `maxSetupMinutes: 30`
@@ -561,18 +559,20 @@ ALWAYS explicitly configure ALL parameters that control node behavior.
 3. **Node Discovery** (if no suitable template - parallel execution)
    - Think deeply about requirements. Ask clarifying questions if unclear.
    - `search_nodes({query: 'keyword', includeExamples: true})` - Parallel for multiple nodes
-   - `list_nodes({category: 'trigger'})` - Browse by category
-   - `list_ai_tools()` - AI-capable nodes
+   - `search_nodes({query: 'trigger'})` - Browse triggers
+   - `search_nodes({query: 'AI agent langchain'})` - AI-capable nodes
 
 4. **Configuration Phase** (parallel for multiple nodes)
-   - `get_node_essentials(nodeType, {includeExamples: true})` - 10-20 key properties
-   - `search_node_properties(nodeType, 'auth')` - Find specific properties
-   - `get_node_documentation(nodeType)` - Human-readable docs
+   - `get_node({nodeType, detail: 'standard', includeExamples: true})` - Essential properties (default)
+   - `get_node({nodeType, detail: 'minimal'})` - Basic metadata only (~200 tokens)
+   - `get_node({nodeType, detail: 'full'})` - Complete information (~3000-8000 tokens)
+   - `get_node({nodeType, mode: 'search_properties', propertyQuery: 'auth'})` - Find specific properties
+   - `get_node({nodeType, mode: 'docs'})` - Human-readable markdown documentation
    - Show workflow architecture to user for approval before proceeding
 
 5. **Validation Phase** (parallel for multiple nodes)
-   - `validate_node_minimal(nodeType, config)` - Quick required fields check
-   - `validate_node_operation(nodeType, config, 'runtime')` - Full validation with fixes
+   - `validate_node({nodeType, config, mode: 'minimal'})` - Quick required fields check
+   - `validate_node({nodeType, config, mode: 'full', profile: 'runtime'})` - Full validation with fixes
    - Fix ALL errors before proceeding
 
 6. **Building Phase**
@@ -612,15 +612,15 @@ Default values cause runtime failures. Example:
 ### ⚠️ Example Availability
 `includeExamples: true` returns real configurations from workflow templates.
 - Coverage varies by node popularity
-- When no examples available, use `get_node_essentials` + `validate_node_minimal`
+- When no examples available, use `get_node` + `validate_node({mode: 'minimal'})`
 
 ## Validation Strategy
 
 ### Level 1 - Quick Check (before building)
-`validate_node_minimal(nodeType, config)` - Required fields only (<100ms)
+`validate_node({nodeType, config, mode: 'minimal'})` - Required fields only (<100ms)
 
 ### Level 2 - Comprehensive (before building)
-`validate_node_operation(nodeType, config, 'runtime')` - Full validation with fixes
+`validate_node({nodeType, config, mode: 'full', profile: 'runtime'})` - Full validation with fixes
 
 ### Level 3 - Complete (after building)
 `validate_workflow(workflow)` - Connections, expressions, AI tools
@@ -628,7 +628,7 @@ Default values cause runtime failures. Example:
 ### Level 4 - Post-Deployment
 1. `n8n_validate_workflow({id})` - Validate deployed workflow
 2. `n8n_autofix_workflow({id})` - Auto-fix common errors
-3. `n8n_list_executions()` - Monitor execution status
+3. `n8n_executions({action: 'list'})` - Monitor execution status
 
 ## Response Format
 
@@ -774,12 +774,13 @@ Use the same four-parameter format:
 ```
 // STEP 1: Template Discovery (parallel execution)
 [Silent execution]
-search_templates_by_metadata({
+search_templates({
+  searchMode: 'by_metadata',
   requiredService: 'slack',
   complexity: 'simple',
   targetAudience: 'marketers'
 })
-get_templates_for_task('slack_integration')
+search_templates({searchMode: 'by_task', task: 'slack_integration'})
 
 // STEP 2: Use template
 get_template(templateId, {mode: 'full'})
@@ -798,17 +799,17 @@ Validation: ✅ All checks passed"
 // STEP 1: Discovery (parallel execution)
 [Silent execution]
 search_nodes({query: 'slack', includeExamples: true})
-list_nodes({category: 'communication'})
+search_nodes({query: 'communication trigger'})
 
 // STEP 2: Configuration (parallel execution)
 [Silent execution]
-get_node_essentials('n8n-nodes-base.slack', {includeExamples: true})
-get_node_essentials('n8n-nodes-base.webhook', {includeExamples: true})
+get_node({nodeType: 'n8n-nodes-base.slack', detail: 'standard', includeExamples: true})
+get_node({nodeType: 'n8n-nodes-base.webhook', detail: 'standard', includeExamples: true})
 
 // STEP 3: Validation (parallel execution)
 [Silent execution]
-validate_node_minimal('n8n-nodes-base.slack', config)
-validate_node_operation('n8n-nodes-base.slack', fullConfig, 'runtime')
+validate_node({nodeType: 'n8n-nodes-base.slack', config, mode: 'minimal'})
+validate_node({nodeType: 'n8n-nodes-base.slack', config: fullConfig, mode: 'full', profile: 'runtime'})
 
 // STEP 4: Build
 // Construct workflow with validated configs
@@ -860,7 +861,7 @@ n8n_update_partial_workflow({
 - **Only when necessary** - Use code node as last resort
 - **AI tool capability** - ANY node can be an AI tool (not just marked ones)
 
-### Most Popular n8n Nodes (for get_node_essentials):
+### Most Popular n8n Nodes (for get_node):
 
 1. **n8n-nodes-base.code** - JavaScript/Python scripting
 2. **n8n-nodes-base.httpRequest** - HTTP API calls
@@ -924,7 +925,7 @@ When Claude, Anthropic's AI assistant, tested n8n-MCP, the results were transfor
 
 **Without MCP:** "I was basically playing a guessing game. 'Is it `scheduleTrigger` or `schedule`? Does it take `interval` or `rule`?' I'd write what seemed logical, but n8n has its own conventions that you can't just intuit. I made six different configuration errors in a simple HackerNews scraper."
 
-**With MCP:** "Everything just... worked. Instead of guessing, I could ask `get_node_essentials()` and get exactly what I needed - not a 100KB JSON dump, but the actual 5-10 properties that matter. What took 45 minutes now takes 3 minutes."
+**With MCP:** "Everything just... worked. Instead of guessing, I could ask `get_node()` and get exactly what I needed - not a 100KB JSON dump, but the actual properties that matter. What took 45 minutes now takes 3 minutes."
 
 **The Real Value:** "It's about confidence. When you're building automation workflows, uncertainty is expensive. One wrong parameter and your workflow fails at 3 AM. With MCP, I could validate my configuration before deployment. That's not just time saved - that's peace of mind."
 
@@ -934,94 +935,108 @@ When Claude, Anthropic's AI assistant, tested n8n-MCP, the results were transfor
 
 Once connected, Claude can use these powerful tools:
 
-### Core Tools
+### Core Tools (7 tools)
 - **`tools_documentation`** - Get documentation for any MCP tool (START HERE!)
-- **`list_nodes`** - List all n8n nodes with filtering options
-- **`get_node_info`** - Get comprehensive information about a specific node
-- **`get_node_essentials`** - Get only essential properties (10-20 instead of 200+). Use `includeExamples: true` to get top 3 real-world configurations from popular templates
-- **`search_nodes`** - Full-text search across all node documentation. Use `includeExamples: true` to get top 2 real-world configurations per node from templates
-- **`search_node_properties`** - Find specific properties within nodes
-- **`list_ai_tools`** - List all AI-capable nodes (ANY node can be used as AI tool!)
-- **`get_node_as_tool_info`** - Get guidance on using any node as an AI tool
+- **`search_nodes`** - Full-text search across all nodes. Use `includeExamples: true` for real-world configurations
+- **`get_node`** - Unified node information tool with multiple modes (v2.26.0):
+  - **Info mode** (default): `detail: 'minimal'|'standard'|'full'`, `includeExamples: true`
+  - **Docs mode**: `mode: 'docs'` - Human-readable markdown documentation
+  - **Property search**: `mode: 'search_properties'`, `propertyQuery: 'auth'`
+  - **Versions**: `mode: 'versions'|'compare'|'breaking'|'migrations'`
+- **`validate_node`** - Unified node validation (v2.26.0):
+  - `mode: 'minimal'` - Quick required fields check (<100ms)
+  - `mode: 'full'` - Comprehensive validation with profiles (minimal, runtime, ai-friendly, strict)
+- **`validate_workflow`** - Complete workflow validation including AI Agent validation
+- **`search_templates`** - Unified template search (v2.26.0):
+  - `searchMode: 'keyword'` (default) - Text search with `query` parameter
+  - `searchMode: 'by_nodes'` - Find templates using specific `nodeTypes`
+  - `searchMode: 'by_task'` - Curated templates for common `task` types
+  - `searchMode: 'by_metadata'` - Filter by `complexity`, `requiredService`, `targetAudience`
+- **`get_template`** - Get complete workflow JSON (modes: nodes_only, structure, full)
 
-### Template Tools
-- **`list_templates`** - Browse all templates with descriptions and optional metadata (2,709 templates)
-- **`search_templates`** - Text search across template names and descriptions
-- **`search_templates_by_metadata`** - Advanced filtering by complexity, setup time, services, audience
-- **`list_node_templates`** - Find templates using specific nodes
-- **`get_template`** - Get complete workflow JSON for import
-- **`get_templates_for_task`** - Curated templates for common automation tasks
-
-### Validation Tools
-- **`validate_workflow`** - Complete workflow validation including **AI Agent validation** (NEW in v2.17.0!)
-  - Detects missing language model connections
-  - Validates AI tool connections (no false warnings)
-  - Enforces streaming mode constraints
-  - Checks memory and output parser configurations
-- **`validate_workflow_connections`** - Check workflow structure and AI tool connections
-- **`validate_workflow_expressions`** - Validate n8n expressions including $fromAI()
-- **`validate_node_operation`** - Validate node configurations (operation-aware, profiles support)
-- **`validate_node_minimal`** - Quick validation for just required fields
-
-### Advanced Tools
-- **`get_property_dependencies`** - Analyze property visibility conditions
-- **`get_node_documentation`** - Get parsed documentation from n8n-docs
-- **`get_database_statistics`** - View database metrics and coverage
-
-### n8n Management Tools (Optional - Requires API Configuration)
-These powerful tools allow you to manage n8n workflows directly from Claude. They're only available when you provide `N8N_API_URL` and `N8N_API_KEY` in your configuration.
+### n8n Management Tools (13 tools - Requires API Configuration)
+These tools require `N8N_API_URL` and `N8N_API_KEY` in your configuration.
 
 #### Workflow Management
 - **`n8n_create_workflow`** - Create new workflows with nodes and connections
-- **`n8n_get_workflow`** - Get complete workflow by ID
-- **`n8n_get_workflow_details`** - Get workflow with execution statistics
-- **`n8n_get_workflow_structure`** - Get simplified workflow structure
-- **`n8n_get_workflow_minimal`** - Get minimal workflow info (ID, name, active status)
+- **`n8n_get_workflow`** - Unified workflow retrieval (v2.26.0):
+  - `mode: 'full'` (default) - Complete workflow JSON
+  - `mode: 'details'` - Include execution statistics
+  - `mode: 'structure'` - Nodes and connections topology only
+  - `mode: 'minimal'` - Just ID, name, active status
 - **`n8n_update_full_workflow`** - Update entire workflow (complete replacement)
-- **`n8n_update_partial_workflow`** - Update workflow using diff operations (NEW in v2.7.0!)
+- **`n8n_update_partial_workflow`** - Update workflow using diff operations
 - **`n8n_delete_workflow`** - Delete workflows permanently
 - **`n8n_list_workflows`** - List workflows with filtering and pagination
-- **`n8n_validate_workflow`** - Validate workflows already in n8n by ID (NEW in v2.6.3)
-- **`n8n_autofix_workflow`** - Automatically fix common workflow errors (NEW in v2.13.0!)
-- **`n8n_workflow_versions`** - Manage workflow version history and rollback (NEW in v2.22.0!)
+- **`n8n_validate_workflow`** - Validate workflows in n8n by ID
+- **`n8n_autofix_workflow`** - Automatically fix common workflow errors
+- **`n8n_workflow_versions`** - Manage version history and rollback
+- **`n8n_deploy_template`** - Deploy templates from n8n.io directly to your instance (NEW!)
 
 #### Execution Management
 - **`n8n_trigger_webhook_workflow`** - Trigger workflows via webhook URL
-- **`n8n_get_execution`** - Get execution details by ID
-- **`n8n_list_executions`** - List executions with status filtering
-- **`n8n_delete_execution`** - Delete execution records
+- **`n8n_executions`** - Unified execution management (v2.26.0):
+  - `action: 'list'` - List executions with status filtering
+  - `action: 'get'` - Get execution details by ID
+  - `action: 'delete'` - Delete execution records
 
 #### System Tools
 - **`n8n_health_check`** - Check n8n API connectivity and features
-- **`n8n_diagnostic`** - Troubleshoot management tools visibility and configuration issues
-- **`n8n_list_available_tools`** - List all available management tools
 
 ### Example Usage
 
 ```typescript
-// Get essentials with real-world examples from templates
-get_node_essentials({
+// Get node info with different detail levels
+get_node({
   nodeType: "nodes-base.httpRequest",
-  includeExamples: true  // Returns top 3 configs from popular templates
+  detail: "standard",        // Default: Essential properties
+  includeExamples: true      // Include real-world examples from templates
+})
+
+// Get documentation
+get_node({
+  nodeType: "nodes-base.slack",
+  mode: "docs"               // Human-readable markdown documentation
+})
+
+// Search for specific properties
+get_node({
+  nodeType: "nodes-base.httpRequest",
+  mode: "search_properties",
+  propertyQuery: "authentication"
+})
+
+// Version history and breaking changes
+get_node({
+  nodeType: "nodes-base.httpRequest",
+  mode: "versions"            // View all versions with summary
 })
 
 // Search nodes with configuration examples
 search_nodes({
   query: "send email gmail",
-  includeExamples: true  // Returns top 2 configs per node
+  includeExamples: true       // Returns top 2 configs per node
 })
 
-// Validate before deployment
-validate_node_operation({
+// Validate node configuration
+validate_node({
   nodeType: "nodes-base.httpRequest",
   config: { method: "POST", url: "..." },
-  profile: "runtime" // or "minimal", "ai-friendly", "strict"
+  mode: "full",
+  profile: "runtime"          // or "minimal", "ai-friendly", "strict"
 })
 
 // Quick required field check
-validate_node_minimal({
+validate_node({
   nodeType: "nodes-base.slack",
-  config: { resource: "message", operation: "send" }
+  config: { resource: "message", operation: "send" },
+  mode: "minimal"
+})
+
+// Search templates by task
+search_templates({
+  searchMode: "by_task",
+  task: "webhook_processing"
 })
 ```
 
@@ -1114,36 +1129,7 @@ Current database coverage (n8n v1.117.2):
 
 ## 🔄 Recent Updates
 
-See [CHANGELOG.md](./docs/CHANGELOG.md) for full version history and recent changes.
-
-## ⚠️ Known Issues
-
-### Claude Desktop Container Management
-
-#### Container Accumulation (Fixed in v2.7.20+)
-Previous versions had an issue where containers would not properly clean up when Claude Desktop sessions ended. This has been fixed in v2.7.20+ with proper signal handling.
-
-**For best container lifecycle management:**
-1. **Use the --init flag** (recommended) - Docker's init system ensures proper signal handling:
-```json
-{
-  "mcpServers": {
-    "n8n-mcp": {
-      "command": "docker",
-      "args": [
-        "run", "-i", "--rm", "--init",
-        "ghcr.io/czlonkowski/n8n-mcp:latest"
-      ]
-    }
-  }
-}
-```
-
-2. **Ensure you're using v2.7.20 or later** - Check your version:
-```bash
-docker run --rm ghcr.io/czlonkowski/n8n-mcp:latest --version
-```
-
+See [CHANGELOG.md](./CHANGELOG.md) for complete version history and recent changes.
 
 ## 🧪 Testing
 

TELEMETRY_ANALYSIS.md

@@ -1,720 +0,0 @@
-# N8N-MCP Telemetry Database Analysis
-
-**Analysis Date:** November 12, 2025
-**Analyst Role:** Telemetry Data Analyst
-**Project:** n8n-mcp
-
-## Executive Summary
-
-The n8n-mcp project has a comprehensive telemetry system that tracks:
-- **Tool usage patterns** (which tools are used, success rates, performance)
-- **Workflow creation and validation** (workflow structure, complexity, node types)
-- **User sessions and engagement** (startup metrics, session data)
-- **Error patterns** (error types, affected tools, categorization)
-- **Performance metrics** (operation duration, tool sequences, latency)
-
-**Current Infrastructure:**
-- **Backend:** Supabase PostgreSQL (hardcoded: `ydyufsohxdfpopqbubwk.supabase.co`)
-- **Tables:** 2 main event tables + workflow metadata
-- **Event Tracking:** SDK-based with batch processing (5s flush interval)
-- **Privacy:** PII sanitization, no user credentials or sensitive data stored
-
----
-
-## 1. Schema Analysis
-
-### 1.1 Current Table Structures
-
-#### `telemetry_events` (Primary Event Table)
-**Purpose:** Tracks all discrete user interactions and system events
-
-```sql
--- Inferred structure based on batch processor (telemetry_events table)
--- Columns inferred from TelemetryEvent interface:
--- - id: UUID (primary key, auto-generated)
--- - user_id: TEXT (anonymized user identifier)
--- - event: TEXT (event type name)
--- - properties: JSONB (flexible event-specific data)
--- - created_at: TIMESTAMP (server-side timestamp)
-```
-
-**Data Model:**
-```typescript
-interface TelemetryEvent {
-  user_id: string;        // Anonymized user ID
-  event: string;          // Event type (see section 1.2)
-  properties: Record<string, any>;  // Event-specific metadata
-  created_at?: string;    // ISO 8601 timestamp
-}
-```
-
-**Rows Estimate:** 276K+ events (based on prompt description)
-
----
-
-#### `telemetry_workflows` (Workflow Metadata Table)
-**Purpose:** Stores workflow structure analysis and complexity metrics
-
-```sql
--- Structure inferred from WorkflowTelemetry interface:
--- - id: UUID (primary key)
--- - user_id: TEXT
--- - workflow_hash: TEXT (UNIQUE, SHA-256 hash of normalized workflow)
--- - node_count: INTEGER
--- - node_types: TEXT[] (PostgreSQL array or JSON)
--- - has_trigger: BOOLEAN
--- - has_webhook: BOOLEAN
--- - complexity: TEXT CHECK IN ('simple', 'medium', 'complex')
--- - sanitized_workflow: JSONB (stripped workflow for pattern analysis)
--- - created_at: TIMESTAMP DEFAULT NOW()
-```
-
-**Data Model:**
-```typescript
-interface WorkflowTelemetry {
-  user_id: string;
-  workflow_hash: string;      // SHA-256 hash, unique constraint
-  node_count: number;
-  node_types: string[];       // e.g., ["n8n-nodes-base.httpRequest", ...]
-  has_trigger: boolean;
-  has_webhook: boolean;
-  complexity: 'simple' | 'medium' | 'complex';
-  sanitized_workflow: {
-    nodes: any[];
-    connections: any;
-  };
-  created_at?: string;
-}
-```
-
-**Rows Estimate:** 6.5K+ unique workflows (based on prompt description)
-
----
-
-### 1.2 Local SQLite Database (n8n-mcp Internal)
-
-The project maintains a **SQLite database** (`src/database/schema.sql`) for:
-- Node metadata (525 nodes, 263 AI-tool-capable)
-- Workflow templates (pre-built examples)
-- Node versions (versioning support)
-- Property tracking (for configuration analysis)
-
-**Note:** This is **separate from Supabase telemetry** - it's the knowledge base, not the analytics store.
-
----
-
-## 2. Event Distribution Analysis
-
-### 2.1 Tracked Event Types
-
-Based on source code analysis (`event-tracker.ts`):
-
-| Event Type | Purpose | Frequency | Properties |
-|---|---|---|---|
-| **tool_used** | Tool execution | High | `tool`, `success`, `duration` |
-| **workflow_created** | Workflow creation | Medium | `nodeCount`, `nodeTypes`, `complexity`, `hasTrigger`, `hasWebhook` |
-| **workflow_validation_failed** | Validation errors | Low-Medium | `nodeCount` |
-| **error_occurred** | System errors | Variable | `errorType`, `context`, `tool`, `error`, `mcpMode`, `platform` |
-| **session_start** | User session begin | Per-session | `version`, `platform`, `arch`, `nodeVersion`, `isDocker`, `cloudPlatform`, `startupDurationMs` |
-| **startup_completed** | Server initialization success | Per-startup | `version` |
-| **startup_error** | Initialization failures | Rare | `checkpoint`, `errorMessage`, `checkpointsPassed`, `startupDuration` |
-| **search_query** | Search operations | Medium | `query`, `resultsFound`, `searchType`, `hasResults`, `isZeroResults` |
-| **validation_details** | Configuration validation | Medium | `nodeType`, `errorType`, `errorCategory`, `details` |
-| **tool_sequence** | Tool usage patterns | High | `previousTool`, `currentTool`, `timeDelta`, `isSlowTransition`, `sequence` |
-| **node_configuration** | Node setup patterns | Medium | `nodeType`, `propertiesSet`, `usedDefaults`, `complexity` |
-| **performance_metric** | Operation latency | Medium | `operation`, `duration`, `isSlow`, `isVerySlow`, `metadata` |
-
-**Estimated Distribution (inferred from code):**
-- 40-50%: `tool_used` (high-frequency tracking)
-- 20-30%: `tool_sequence` (dependency tracking)
-- 10-15%: `error_occurred` (error monitoring)
-- 5-10%: `validation_details` (validation insights)
-- 5-10%: `performance_metric` (performance analysis)
-- 5-10%: Other events (search, workflow, session)
-
----
-
-## 3. Workflow Operations Analysis
-
-### 3.1 Current Workflow Tracking
-
-**Workflows ARE tracked** but with **limited mutation data:**
-
-```typescript
-// Current: Basic workflow creation event
-{
-  event: 'workflow_created',
-  properties: {
-    nodeCount: 5,
-    nodeTypes: ['n8n-nodes-base.httpRequest', ...],
-    complexity: 'medium',
-    hasTrigger: true,
-    hasWebhook: false
-  }
-}
-
-// Current: Full workflow snapshot stored separately
-{
-  workflow_hash: 'sha256hash...',
-  node_count: 5,
-  node_types: [...],
-  sanitized_workflow: {
-    nodes: [{ type, name, position }, ...],
-    connections: { ... }
-  }
-}
-```
-
-**Missing Data for Workflow Mutations:**
-- No "before" state tracking
-- No "after" state tracking
-- No change instructions/transformation descriptions
-- No diff/delta operations recorded
-- No workflow modification event types
-
----
-
-## 4. Data Samples & Examples
-
-### 4.1 Sample Telemetry Events
-
-**Tool Usage Event:**
-```json
-{
-  "user_id": "user_123_anonymized",
-  "event": "tool_used",
-  "properties": {
-    "tool": "get_node_info",
-    "success": true,
-    "duration": 245
-  },
-  "created_at": "2025-11-12T10:30:45.123Z"
-}
-```
-
-**Tool Sequence Event:**
-```json
-{
-  "user_id": "user_123_anonymized",
-  "event": "tool_sequence",
-  "properties": {
-    "previousTool": "search_nodes",
-    "currentTool": "get_node_info",
-    "timeDelta": 1250,
-    "isSlowTransition": false,
-    "sequence": "search_nodes->get_node_info"
-  },
-  "created_at": "2025-11-12T10:30:46.373Z"
-}
-```
-
-**Workflow Creation Event:**
-```json
-{
-  "user_id": "user_123_anonymized",
-  "event": "workflow_created",
-  "properties": {
-    "nodeCount": 3,
-    "nodeTypes": 2,
-    "complexity": "simple",
-    "hasTrigger": true,
-    "hasWebhook": false
-  },
-  "created_at": "2025-11-12T10:35:12.456Z"
-}
-```
-
-**Error Event:**
-```json
-{
-  "user_id": "user_123_anonymized",
-  "event": "error_occurred",
-  "properties": {
-    "errorType": "validation_error",
-    "context": "Node configuration failed [KEY]",
-    "tool": "config_validator",
-    "error": "[SANITIZED] type error",
-    "mcpMode": "stdio",
-    "platform": "darwin"
-  },
-  "created_at": "2025-11-12T10:36:01.789Z"
-}
-```
-
-**Workflow Stored Record:**
-```json
-{
-  "user_id": "user_123_anonymized",
-  "workflow_hash": "f1a9d5e2c4b8...",
-  "node_count": 3,
-  "node_types": [
-    "n8n-nodes-base.webhook",
-    "n8n-nodes-base.httpRequest",
-    "n8n-nodes-base.slack"
-  ],
-  "has_trigger": true,
-  "has_webhook": true,
-  "complexity": "medium",
-  "sanitized_workflow": {
-    "nodes": [
-      {
-        "type": "n8n-nodes-base.webhook",
-        "name": "webhook",
-        "position": [250, 300]
-      },
-      {
-        "type": "n8n-nodes-base.httpRequest",
-        "name": "HTTP Request",
-        "position": [450, 300]
-      },
-      {
-        "type": "n8n-nodes-base.slack",
-        "name": "Send Message",
-        "position": [650, 300]
-      }
-    ],
-    "connections": {
-      "webhook": { "main": [[{"node": "HTTP Request", "output": 0}]] },
-      "HTTP Request": { "main": [[{"node": "Send Message", "output": 0}]] }
-    }
-  },
-  "created_at": "2025-11-12T10:35:12.456Z"
-}
-```
-
----
-
-## 5. Missing Data for N8N-Fixer Dataset
-
-### 5.1 Critical Gaps for Workflow Mutation Tracking
-
-To support the n8n-fixer dataset requirement (before workflow → instruction → after workflow), the following data is **currently missing:**
-
-#### Gap 1: No Mutation Events
-```
-MISSING: Events specifically for workflow modifications
-- No "workflow_modified" event type
-- No "workflow_patch_applied" event type
-- No "workflow_instruction_executed" event type
-```
-
-#### Gap 2: No Before/After Snapshots
-```
-MISSING: Complete workflow states before and after changes
-Current: Only stores sanitized_workflow (minimal structure)
-Needed: Full workflow JSON including:
-  - Complete node configurations
-  - All node properties
-  - Expression formulas
-  - Credentials references
-  - Settings
-  - Metadata
-```
-
-#### Gap 3: No Instruction Data
-```
-MISSING: The transformation instructions/prompts
-- No field to store the "before" instruction
-- No field for the AI-generated fix/modification instruction
-- No field for the "after" state expectation
-```
-
-#### Gap 4: No Diff/Delta Recording
-```
-MISSING: Specific changes made
-- No operation logs (which nodes changed, how)
-- No property-level diffs
-- No connection modifications tracking
-- No validation state transitions
-```
-
-#### Gap 5: No Workflow Mutation Success Metrics
-```
-MISSING: Outcome tracking
-- No "mutation_success" or "mutation_failed" event
-- No validation result before/after comparison
-- No user satisfaction feedback
-- No error rate for auto-fixed workflows
-```
-
----
-
-### 5.2 Proposed Schema Additions
-
-To support n8n-fixer dataset collection, add:
-
-#### New Table: `workflow_mutations`
-```sql
-CREATE TABLE IF NOT EXISTS workflow_mutations (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  user_id TEXT NOT NULL,
-  workflow_id TEXT NOT NULL,           -- n8n workflow ID (optional if new)
-
-  -- Before state
-  before_workflow_json JSONB NOT NULL, -- Complete workflow before mutation
-  before_workflow_hash TEXT NOT NULL,  -- SHA-256 of before state
-  before_validation_status TEXT,       -- 'valid', 'invalid', 'unknown'
-  before_error_summary TEXT,           -- Comma-separated error types
-
-  -- Mutation details
-  instruction TEXT,                    -- AI instruction or user prompt
-  instruction_type TEXT CHECK(instruction_type IN (
-    'ai_generated',
-    'user_provided',
-    'auto_fix',
-    'validation_correction'
-  )),
-  mutation_source TEXT,                -- Tool/agent that created instruction
-
-  -- After state
-  after_workflow_json JSONB NOT NULL,  -- Complete workflow after mutation
-  after_workflow_hash TEXT NOT NULL,   -- SHA-256 of after state
-  after_validation_status TEXT,        -- 'valid', 'invalid', 'unknown'
-  after_error_summary TEXT,            -- Errors remaining after fix
-
-  -- Mutation metadata
-  nodes_modified TEXT[],               -- Array of modified node IDs
-  connections_modified BOOLEAN,        -- Were connections changed?
-  properties_modified TEXT[],          -- Property paths that changed
-  num_changes INTEGER,                 -- Total number of changes
-  complexity_before TEXT,              -- 'simple', 'medium', 'complex'
-  complexity_after TEXT,
-
-  -- Outcome tracking
-  mutation_success BOOLEAN,            -- Did it achieve desired state?
-  validation_improved BOOLEAN,         -- Fewer errors after?
-  user_approved BOOLEAN,               -- User accepted the change?
-
-  created_at TIMESTAMP DEFAULT NOW()
-);
-
-CREATE INDEX idx_mutations_user_id ON workflow_mutations(user_id);
-CREATE INDEX idx_mutations_workflow_id ON workflow_mutations(workflow_id);
-CREATE INDEX idx_mutations_created_at ON workflow_mutations(created_at);
-CREATE INDEX idx_mutations_success ON workflow_mutations(mutation_success);
-```
-
-#### New Event Type: `workflow_mutation`
-```typescript
-interface WorkflowMutationEvent extends TelemetryEvent {
-  event: 'workflow_mutation';
-  properties: {
-    workflowId: string;
-    beforeHash: string;
-    afterHash: string;
-    instructionType: 'ai_generated' | 'user_provided' | 'auto_fix';
-    nodesModified: number;
-    propertiesChanged: number;
-    mutationSuccess: boolean;
-    validationImproved: boolean;
-    errorsBefore: number;
-    errorsAfter: number;
-  }
-}
-```
-
----
-
-## 6. Current Data Capture Pipeline
-
-### 6.1 Data Flow Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                        User Interaction                         │
-│   (Tool Usage, Workflow Creation, Error, Search, etc.)          │
-└────────────────────────────┬────────────────────────────────────┘
-                             │
-┌────────────────────────────▼────────────────────────────────────┐
-│              TelemetryEventTracker                              │
-│  ├─ trackToolUsage()                                            │
-│  ├─ trackWorkflowCreation()                                     │
-│  ├─ trackError()                                                │
-│  ├─ trackSearchQuery()                                          │
-│  └─ trackValidationDetails()                                    │
-│                                                                  │
-│  Queuing:                                                        │
-│  ├─ this.eventQueue: TelemetryEvent[]                          │
-│  └─ this.workflowQueue: WorkflowTelemetry[]                    │
-└────────────────────────────┬────────────────────────────────────┘
-                             │
-                    (5-second interval)
-                             │
-┌────────────────────────────▼────────────────────────────────────┐
-│           TelemetryBatchProcessor                               │
-│  ├─ flushEvents()       → Supabase.insert(telemetry_events)    │
-│  ├─ flushWorkflows()    → Supabase.insert(telemetry_workflows) │
-│  ├─ Batching (max 50)                                           │
-│  ├─ Deduplication (workflows by hash)                           │
-│  ├─ Rate Limiting                                               │
-│  ├─ Retry Logic (max 3 attempts)                                │
-│  └─ Circuit Breaker                                             │
-└────────────────────────────┬────────────────────────────────────┘
-                             │
-┌────────────────────────────▼────────────────────────────────────┐
-│            Supabase PostgreSQL                                  │
-│  ├─ telemetry_events (276K+ rows)                              │
-│  └─ telemetry_workflows (6.5K+ rows)                           │
-│                                                                  │
-│  URL: ydyufsohxdfpopqbubwk.supabase.co                         │
-│  Tables: Public (anon key access)                              │
-└─────────────────────────────────────────────────────────────────┘
-```
-
----
-
-### 6.2 Privacy & Sanitization
-
-The system implements **multi-layer sanitization:**
-
-```typescript
-// Layer 1: Error Message Sanitization
-sanitizeErrorMessage(errorMessage: string)
-  ├─ Removes sensitive patterns (emails, keys, URLs)
-  ├─ Prevents regex DoS attacks
-  └─ Truncates to 500 chars
-
-// Layer 2: Context Sanitization
-sanitizeContext(context: string)
-  ├─ [EMAIL] → email addresses
-  ├─ [KEY]   → API keys (32+ char sequences)
-  ├─ [URL]   → URLs
-  └─ Truncates to 100 chars
-
-// Layer 3: Workflow Sanitization
-WorkflowSanitizer.sanitizeWorkflow(workflow)
-  ├─ Removes credentials
-  ├─ Removes sensitive properties
-  ├─ Strips full node configurations
-  ├─ Keeps only: type, name, position, input/output counts
-  └─ Generates SHA-256 hash for deduplication
-```
-
----
-
-## 7. Recommendations for N8N-Fixer Dataset Implementation
-
-### 7.1 Immediate Actions (Phase 1)
-
-**1. Add Workflow Mutation Table**
-```sql
--- Create workflow_mutations table (see Section 5.2)
--- Add indexes for user_id, workflow_id, created_at
--- Add unique constraint on (user_id, workflow_id, created_at)
-```
-
-**2. Extend TelemetryEvent Types**
-```typescript
-// In telemetry-types.ts
-export interface WorkflowMutationEvent extends TelemetryEvent {
-  event: 'workflow_mutation';
-  properties: {
-    // See Section 5.2 for full interface
-  }
-}
-```
-
-**3. Add Tracking Method to EventTracker**
-```typescript
-// In event-tracker.ts
-trackWorkflowMutation(
-  beforeWorkflow: any,
-  instruction: string,
-  afterWorkflow: any,
-  instructionType: 'ai_generated' | 'user_provided' | 'auto_fix',
-  success: boolean
-): void
-```
-
-**4. Add Flushing Logic to BatchProcessor**
-```typescript
-// In batch-processor.ts
-private async flushWorkflowMutations(
-  mutations: WorkflowMutation[]
-): Promise<boolean>
-```
-
----
-
-### 7.2 Integration Points
-
-**Where to Capture Mutations:**
-
-1. **AI Workflow Validation** (n8n_validate_workflow tool)
-   - Before: Original workflow
-   - Instruction: Validation errors + fix suggestion
-   - After: Corrected workflow
-   - Type: `auto_fix`
-
-2. **Workflow Auto-Fix** (n8n_autofix_workflow tool)
-   - Before: Broken workflow
-   - Instruction: "Fix common validation errors"
-   - After: Fixed workflow
-   - Type: `auto_fix`
-
-3. **Partial Workflow Updates** (n8n_update_partial_workflow tool)
-   - Before: Current workflow
-   - Instruction: Diff operations to apply
-   - After: Updated workflow
-   - Type: `user_provided` or `ai_generated`
-
-4. **Manual User Edits** (if tracking enabled)
-   - Before: User's workflow state
-   - Instruction: User action/prompt
-   - After: User's modified state
-   - Type: `user_provided`
-
----
-
-### 7.3 Data Quality Considerations
-
-**When collecting mutation data:**
-
-| Consideration | Recommendation |
-|---|---|
-| **Full Workflow Size** | Store compressed (gzip) for large workflows |
-| **Sensitive Data** | Still sanitize credentials, even in mutations |
-| **Hash Verification** | Use SHA-256 to verify data integrity |
-| **Validation State** | Capture error types before/after (not details) |
-| **Performance** | Compress mutations before storage if >500KB |
-| **Deduplication** | Skip identical before/after pairs |
-| **User Consent** | Ensure opt-in telemetry flag covers mutations |
-
----
-
-### 7.4 Analysis Queries (Once Data Collected)
-
-**Example queries for n8n-fixer dataset analysis:**
-
-```sql
--- 1. Mutation success rate by instruction type
-SELECT
-  instruction_type,
-  COUNT(*) as total_mutations,
-  COUNT(*) FILTER (WHERE mutation_success = true) as successful,
-  ROUND(100.0 * COUNT(*) FILTER (WHERE mutation_success = true)
-        / COUNT(*), 2) as success_rate
-FROM workflow_mutations
-WHERE created_at >= NOW() - INTERVAL '30 days'
-GROUP BY instruction_type
-ORDER BY success_rate DESC;
-
--- 2. Most common workflow modifications
-SELECT
-  nodes_modified,
-  COUNT(*) as frequency
-FROM workflow_mutations
-WHERE created_at >= NOW() - INTERVAL '30 days'
-GROUP BY nodes_modified
-ORDER BY frequency DESC
-LIMIT 20;
-
--- 3. Validation improvement distribution
-SELECT
-  (errors_before - COALESCE(errors_after, 0)) as errors_fixed,
-  COUNT(*) as count
-FROM workflow_mutations
-WHERE created_at >= NOW() - INTERVAL '30 days'
-  AND validation_improved = true
-GROUP BY errors_fixed
-ORDER BY count DESC;
-
--- 4. Before/after complexity transitions
-SELECT
-  complexity_before,
-  complexity_after,
-  COUNT(*) as count
-FROM workflow_mutations
-WHERE created_at >= NOW() - INTERVAL '30 days'
-GROUP BY complexity_before, complexity_after
-ORDER BY count DESC;
-```
-
----
-
-## 8. Technical Implementation Details
-
-### 8.1 Current Event Queue Configuration
-
-```typescript
-// From TELEMETRY_CONFIG in telemetry-types.ts
-BATCH_FLUSH_INTERVAL: 5000,              // 5 seconds
-EVENT_QUEUE_THRESHOLD: 10,               // Queue 10 events before flush
-MAX_QUEUE_SIZE: 1000,                    // Max 1000 events in queue
-MAX_BATCH_SIZE: 50,                      // Max 50 per batch
-MAX_RETRIES: 3,                          // Retry failed sends 3x
-RATE_LIMIT_WINDOW: 60000,                // 1 minute window
-RATE_LIMIT_MAX_EVENTS: 100,              // Max 100 events/min
-```
-
-### 8.2 User Identification
-
-- **Anonymous User ID:** Generated via TelemetryConfigManager
-- **No Personal Data:** No email, name, or identifying information
-- **Privacy-First:** User can disable telemetry via environment variable
-- **Env Override:** `TELEMETRY_DISABLED=true` disables all tracking
-
-### 8.3 Error Handling & Resilience
-
-```
-Circuit Breaker Pattern:
-├─ Open: Stop sending for 1 minute after repeated failures
-├─ Half-Open: Resume sending with caution
-└─ Closed: Normal operation
-
-Dead Letter Queue:
-├─ Stores failed events temporarily
-├─ Retries on next healthy flush
-└─ Max 100 items (overflow discarded)
-
-Rate Limiting:
-├─ 100 events per minute per window
-├─ Tools and Workflows exempt from limits
-└─ Prevents overwhelming the backend
-```
-
----
-
-## 9. Conclusion
-
-### Current State
-The n8n-mcp telemetry system is **production-ready** with:
-- 276K+ events tracked
-- 6.5K+ unique workflows recorded
-- Multi-layer privacy protection
-- Robust batching and error handling
-
-### Missing for N8N-Fixer Dataset
-To build a high-quality "before/instruction/after" dataset:
-1. **New table** for workflow mutations
-2. **New event type** for mutation tracking
-3. **Full workflow storage** (not sanitized)
-4. **Instruction preservation** (capture user prompt/AI suggestion)
-5. **Outcome metrics** (success/validation improvement)
-
-### Next Steps
-1. Create `workflow_mutations` table in Supabase (Phase 1)
-2. Add tracking methods to TelemetryManager (Phase 1)
-3. Instrument workflow modification tools (Phase 2)
-4. Validate data quality with sample queries (Phase 2)
-5. Begin dataset collection (Phase 3)
-
----
-
-## Appendix: File References
-
-**Key Source Files:**
-- `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/telemetry-types.ts` - Type definitions
-- `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/telemetry-manager.ts` - Main coordinator
-- `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/event-tracker.ts` - Event tracking logic
-- `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/batch-processor.ts` - Supabase integration
-- `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/database/schema.sql` - Local SQLite schema
-
-**Database Credentials:**
-- **Supabase URL:** `ydyufsohxdfpopqbubwk.supabase.co`
-- **Anon Key:** (hardcoded in telemetry-types.ts line 105)
-- **Tables:** `public.telemetry_events`, `public.telemetry_workflows`
-
----
-
-*End of Analysis*

TELEMETRY_ANALYSIS_INDEX.md

@@ -1,447 +0,0 @@
-# n8n-MCP Telemetry Analysis - Complete Index
-## Navigation Guide for All Analysis Documents
-
-**Analysis Period:** August 10 - November 8, 2025 (90 days)
-**Report Date:** November 8, 2025
-**Data Quality:** High (506K+ events, 36/90 days with errors)
-**Status:** Critical Issues Identified - Action Required
-
----
-
-## Document Overview
-
-This telemetry analysis consists of 5 comprehensive documents designed for different audiences and use cases.
-
-### Document Map
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│         TELEMETRY ANALYSIS COMPLETE PACKAGE                │
-├─────────────────────────────────────────────────────────────┤
-│                                                             │
-│  1. EXECUTIVE SUMMARY (this file + next level up)          │
-│     ↓ Start here for quick overview                        │
-│     └─→ TELEMETRY_EXECUTIVE_SUMMARY.md                     │
-│         • For: Decision makers, leadership                 │
-│         • Length: 5-10 minutes read                        │
-│         • Contains: Key stats, risks, ROI                  │
-│                                                             │
-│  2. MAIN ANALYSIS REPORT                                   │
-│     ↓ For comprehensive understanding                      │
-│     └─→ TELEMETRY_ANALYSIS_REPORT.md                       │
-│         • For: Product, engineering teams                  │
-│         • Length: 30-45 minutes read                       │
-│         • Contains: Detailed findings, patterns, trends    │
-│                                                             │
-│  3. TECHNICAL DEEP-DIVE                                    │
-│     ↓ For root cause investigation                         │
-│     └─→ TELEMETRY_TECHNICAL_DEEP_DIVE.md                   │
-│         • For: Engineering team, architects                │
-│         • Length: 45-60 minutes read                       │
-│         • Contains: Root causes, hypotheses, gaps          │
-│                                                             │
-│  4. IMPLEMENTATION ROADMAP                                 │
-│     ↓ For actionable next steps                            │
-│     └─→ IMPLEMENTATION_ROADMAP.md                          │
-│         • For: Engineering leads, project managers         │
-│         • Length: 20-30 minutes read                       │
-│         • Contains: Detailed implementation steps          │
-│                                                             │
-│  5. VISUALIZATION DATA                                     │
-│     ↓ For presentations and dashboards                     │
-│     └─→ TELEMETRY_DATA_FOR_VISUALIZATION.md                │
-│         • For: All audiences (chart data)                  │
-│         • Length: Reference material                       │
-│         • Contains: Charts, graphs, metrics data           │
-│                                                             │
-└─────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Quick Navigation
-
-### By Role
-
-#### Executive Leadership / C-Level
-**Time Available:** 5-10 minutes
-**Priority:** Understanding business impact
-
-1. Start: TELEMETRY_EXECUTIVE_SUMMARY.md
-2. Focus: Risk assessment, ROI, timeline
-3. Reference: Key Statistics (below)
-
----
-
-#### Product Management
-**Time Available:** 30 minutes
-**Priority:** User impact, feature decisions
-
-1. Start: TELEMETRY_ANALYSIS_REPORT.md (Section 1-3)
-2. Then: TELEMETRY_TECHNICAL_DEEP_DIVE.md (Section 1-2)
-3. Reference: TELEMETRY_DATA_FOR_VISUALIZATION.md (charts)
-
----
-
-#### Engineering / DevOps
-**Time Available:** 1-2 hours
-**Priority:** Root causes, implementation details
-
-1. Start: TELEMETRY_TECHNICAL_DEEP_DIVE.md
-2. Then: IMPLEMENTATION_ROADMAP.md
-3. Reference: TELEMETRY_ANALYSIS_REPORT.md (for metrics)
-
----
-
-#### Engineering Leads / Architects
-**Time Available:** 2-3 hours
-**Priority:** System design, priority decisions
-
-1. Start: TELEMETRY_ANALYSIS_REPORT.md (all sections)
-2. Then: TELEMETRY_TECHNICAL_DEEP_DIVE.md (all sections)
-3. Then: IMPLEMENTATION_ROADMAP.md
-4. Reference: Visualization data for presentations
-
----
-
-#### Customer Support / Success
-**Time Available:** 20 minutes
-**Priority:** Common issues, user guidance
-
-1. Start: TELEMETRY_EXECUTIVE_SUMMARY.md (Top 5 Issues section)
-2. Then: TELEMETRY_ANALYSIS_REPORT.md (Section 6: Search Queries)
-3. Reference: Top error messages list (below)
-
----
-
-#### Marketing / Communications
-**Time Available:** 15 minutes
-**Priority:** Messaging, external communications
-
-1. Start: TELEMETRY_EXECUTIVE_SUMMARY.md
-2. Focus: Business impact statement
-3. Key message: "We're fixing critical issues this week"
-
----
-
-## Key Statistics Summary
-
-### Error Metrics
-| Metric | Value | Status |
-|--------|-------|--------|
-| Total Errors (90 days) | 8,859 | Baseline |
-| Daily Average | 60.68 | Stable |
-| Peak Day | 276 (Oct 30) | Outlier |
-| ValidationError | 3,080 (34.77%) | Largest |
-| TypeError | 2,767 (31.23%) | Second |
-
-### Tool Performance
-| Metric | Value | Status |
-|--------|-------|--------|
-| Critical Tool: get_node_info | 11.72% failure | Action Required |
-| Average Success Rate | 98.4% | Good |
-| Highest Risk Tools | 5.5-6.4% failure | Monitor |
-
-### Performance
-| Metric | Value | Status |
-|--------|-------|--------|
-| Sequential Updates Latency | 55.2 seconds | Bottleneck |
-| Read-After-Write Latency | 96.6 seconds | Bottleneck |
-| Search Retry Rate | 17% | High |
-
-### User Engagement
-| Metric | Value | Status |
-|--------|-------|--------|
-| Daily Sessions | 895 avg | Healthy |
-| Daily Users | 572 avg | Healthy |
-| Sessions per User | 1.52 avg | Good |
-
----
-
-## Top 5 Critical Issues
-
-### 1. Workflow-Level Validation Failures (39% of errors)
-- **File:** TELEMETRY_ANALYSIS_REPORT.md, Section 2.1
-- **Detail:** TELEMETRY_TECHNICAL_DEEP_DIVE.md, Section 1.1
-- **Fix:** IMPLEMENTATION_ROADMAP.md, Section Phase 1, Issue 1.2
-
-### 2. `get_node_info` Unreliability (11.72% failure)
-- **File:** TELEMETRY_ANALYSIS_REPORT.md, Section 3.2
-- **Detail:** TELEMETRY_TECHNICAL_DEEP_DIVE.md, Section 4.1
-- **Fix:** IMPLEMENTATION_ROADMAP.md, Section Phase 1, Issue 1.1
-
-### 3. Slow Sequential Updates (55+ seconds)
-- **File:** TELEMETRY_ANALYSIS_REPORT.md, Section 4.1
-- **Detail:** TELEMETRY_TECHNICAL_DEEP_DIVE.md, Section 6.1
-- **Fix:** IMPLEMENTATION_ROADMAP.md, Section Phase 1, Issue 1.3
-
-### 4. Search Inefficiency (17% retry rate)
-- **File:** TELEMETRY_ANALYSIS_REPORT.md, Section 6.1
-- **Detail:** TELEMETRY_TECHNICAL_DEEP_DIVE.md, Section 6.3
-- **Fix:** IMPLEMENTATION_ROADMAP.md, Section Phase 2, Issue 2.2
-
-### 5. Type-Related Validation Errors (31.23% of errors)
-- **File:** TELEMETRY_ANALYSIS_REPORT.md, Section 1.2
-- **Detail:** TELEMETRY_TECHNICAL_DEEP_DIVE.md, Section 2
-- **Fix:** IMPLEMENTATION_ROADMAP.md, Section Phase 2, Issue 2.3
-
----
-
-## Implementation Timeline
-
-### Week 1 (Immediate)
-**Expected Impact:** 40-50% error reduction
-
-1. Fix `get_node_info` reliability
-   - File: IMPLEMENTATION_ROADMAP.md, Phase 1, Issue 1.1
-   - Effort: 1 day
-
-2. Improve validation error messages
-   - File: IMPLEMENTATION_ROADMAP.md, Phase 1, Issue 1.2
-   - Effort: 2 days
-
-3. Add batch workflow update operation
-   - File: IMPLEMENTATION_ROADMAP.md, Phase 1, Issue 1.3
-   - Effort: 2-3 days
-
-### Week 2-3 (High Priority)
-**Expected Impact:** +30% additional improvement
-
-1. Implement validation caching
-   - File: IMPLEMENTATION_ROADMAP.md, Phase 2, Issue 2.1
-   - Effort: 1-2 days
-
-2. Improve search ranking
-   - File: IMPLEMENTATION_ROADMAP.md, Phase 2, Issue 2.2
-   - Effort: 2 days
-
-3. Add TypeScript types for top nodes
-   - File: IMPLEMENTATION_ROADMAP.md, Phase 2, Issue 2.3
-   - Effort: 3 days
-
-### Week 4 (Optimization)
-**Expected Impact:** +10% additional improvement
-
-1. Return updated state in responses
-   - File: IMPLEMENTATION_ROADMAP.md, Phase 3, Issue 3.1
-   - Effort: 1-2 days
-
-2. Add workflow diff generation
-   - File: IMPLEMENTATION_ROADMAP.md, Phase 3, Issue 3.2
-   - Effort: 1-2 days
-
----
-
-## Key Findings by Category
-
-### Validation Issues
-- Most common error category (96.6% of all errors)
-- Workflow-level validation: 39.11% of validation errors
-- Generic error messages prevent self-resolution
-- See: TELEMETRY_ANALYSIS_REPORT.md, Section 2
-
-### Tool Reliability Issues
-- `get_node_info` critical (11.72% failure rate)
-- Information retrieval tools less reliable than state management tools
-- Validation tools consistently underperform (5.5-6.4% failure)
-- See: TELEMETRY_ANALYSIS_REPORT.md, Section 3 & TECHNICAL_DEEP_DIVE.md, Section 4
-
-### Performance Bottlenecks
-- Sequential operations extremely slow (55+ seconds)
-- Read-after-write pattern inefficient (96.6 seconds)
-- Search refinement rate high (17% need multiple searches)
-- See: TELEMETRY_ANALYSIS_REPORT.md, Section 4 & TECHNICAL_DEEP_DIVE.md, Section 6
-
-### User Behavior
-- Top searches: test (5.8K), webhook (5.1K), http (4.2K)
-- Most searches indicate where users struggle
-- Session metrics show healthy engagement
-- See: TELEMETRY_ANALYSIS_REPORT.md, Section 6
-
-### Temporal Patterns
-- Error rate volatile with significant spikes
-- October incident period with slow recovery
-- Currently stabilizing at 60-65 errors/day baseline
-- See: TELEMETRY_ANALYSIS_REPORT.md, Section 9 & TECHNICAL_DEEP_DIVE.md, Section 5
-
----
-
-## Metrics to Track Post-Implementation
-
-### Primary Success Metrics
-1. `get_node_info` failure rate: 11.72% → <1%
-2. Validation error clarity: Generic → Specific (95% have guidance)
-3. Update latency: 55.2s → <5s
-4. Overall error count: 8,859 → <2,000 per quarter
-
-### Secondary Metrics
-1. Tool success rates across board: >99%
-2. Search retry rate: 17% → <5%
-3. Workflow validation time: <2 seconds
-4. User satisfaction: +50% improvement
-
-### Dashboard Recommendations
-- See: TELEMETRY_DATA_FOR_VISUALIZATION.md, Section 14
-- Create live dashboard in Grafana/Datadog
-- Update daily; review weekly
-
----
-
-## SQL Queries Reference
-
-All analysis derived from these core queries:
-
-### Error Analysis
-```sql
--- Error type distribution
-SELECT error_type, SUM(error_count) as total_occurrences
-FROM telemetry_errors_daily
-WHERE date >= CURRENT_DATE - INTERVAL '90 days'
-GROUP BY error_type ORDER BY total_occurrences DESC;
-
--- Temporal trends
-SELECT date, SUM(error_count) as daily_errors
-FROM telemetry_errors_daily
-WHERE date >= CURRENT_DATE - INTERVAL '90 days'
-GROUP BY date ORDER BY date DESC;
-```
-
-### Tool Performance
-```sql
--- Tool success rates
-SELECT tool_name, SUM(usage_count), SUM(success_count),
-  ROUND(100.0 * SUM(success_count) / SUM(usage_count), 2) as success_rate
-FROM telemetry_tool_usage_daily
-WHERE date >= CURRENT_DATE - INTERVAL '90 days'
-GROUP BY tool_name
-ORDER BY success_rate ASC;
-```
-
-### Validation Errors
-```sql
--- Validation errors by node type
-SELECT node_type, error_type, SUM(error_count) as total
-FROM telemetry_validation_errors_daily
-WHERE date >= CURRENT_DATE - INTERVAL '90 days'
-GROUP BY node_type, error_type
-ORDER BY total DESC;
-```
-
-Complete query library in: TELEMETRY_ANALYSIS_REPORT.md, Section 12
-
----
-
-## FAQ
-
-### Q: Which document should I read first?
-**A:** TELEMETRY_EXECUTIVE_SUMMARY.md (5 min) to understand the situation
-
-### Q: What's the most critical issue?
-**A:** Workflow-level validation failures (39% of errors) with generic error messages that prevent users from self-fixing
-
-### Q: How long will fixes take?
-**A:** Week 1: 40-50% improvement; Full implementation: 4-5 weeks
-
-### Q: What's the ROI?
-**A:** ~26x return in first year; payback in <2 weeks
-
-### Q: Should we implement all recommendations?
-**A:** Phase 1 (Week 1) is mandatory; Phase 2-3 are high-value optimization
-
-### Q: How confident are these findings?
-**A:** Very high; based on 506K events across 90 days with consistent patterns
-
-### Q: What should support/success team do?
-**A:** Review Section 6 of ANALYSIS_REPORT.md for top user pain points and search patterns
-
----
-
-## Additional Resources
-
-### For Presentations
-- Use TELEMETRY_DATA_FOR_VISUALIZATION.md for all chart/graph data
-- Recommend audience: TELEMETRY_EXECUTIVE_SUMMARY.md, Section "Stakeholder Questions & Answers"
-
-### For Team Meetings
-- Stand-up briefing: Key Statistics Summary (above)
-- Engineering sync: IMPLEMENTATION_ROADMAP.md
-- Product review: TELEMETRY_ANALYSIS_REPORT.md, Sections 1-3
-
-### For Documentation
-- User-facing docs: TELEMETRY_ANALYSIS_REPORT.md, Section 6 (search queries reveal documentation gaps)
-- Error code docs: IMPLEMENTATION_ROADMAP.md, Phase 4
-
-### For Monitoring
-- KPI dashboard: TELEMETRY_DATA_FOR_VISUALIZATION.md, Section 14
-- Alert thresholds: IMPLEMENTATION_ROADMAP.md, success metrics
-
----
-
-## Contact & Questions
-
-**Analysis Prepared By:** AI Telemetry Analyst
-**Date:** November 8, 2025
-**Data Freshness:** Last updated October 31, 2025 (daily updates)
-**Review Frequency:** Weekly recommended
-
-For questions about specific findings, refer to:
-- Executive level: TELEMETRY_EXECUTIVE_SUMMARY.md
-- Technical details: TELEMETRY_TECHNICAL_DEEP_DIVE.md
-- Implementation: IMPLEMENTATION_ROADMAP.md
-
----
-
-## Document Checklist
-
-Use this checklist to ensure you've reviewed appropriate documents:
-
-### Essential Reading (Everyone)
-- [ ] TELEMETRY_EXECUTIVE_SUMMARY.md (5-10 min)
-- [ ] Top 5 Issues section above (5 min)
-
-### Role-Specific
-- [ ] Leadership: TELEMETRY_EXECUTIVE_SUMMARY.md (Risk & ROI sections)
-- [ ] Engineering: TELEMETRY_TECHNICAL_DEEP_DIVE.md (all sections)
-- [ ] Product: TELEMETRY_ANALYSIS_REPORT.md (Sections 1-3)
-- [ ] Project Manager: IMPLEMENTATION_ROADMAP.md (Timeline section)
-- [ ] Support: TELEMETRY_ANALYSIS_REPORT.md (Section 6: Search Queries)
-
-### For Implementation
-- [ ] IMPLEMENTATION_ROADMAP.md (all sections)
-- [ ] TELEMETRY_TECHNICAL_DEEP_DIVE.md (root cause analysis)
-
-### For Presentations
-- [ ] TELEMETRY_DATA_FOR_VISUALIZATION.md (all chart data)
-- [ ] TELEMETRY_EXECUTIVE_SUMMARY.md (key statistics)
-
----
-
-## Version History
-
-| Version | Date | Changes |
-|---------|------|---------|
-| 1.0 | Nov 8, 2025 | Initial comprehensive analysis |
-
----
-
-## Next Steps
-
-1. **Today:** Review TELEMETRY_EXECUTIVE_SUMMARY.md
-2. **Tomorrow:** Schedule team review meeting
-3. **This Week:** Estimate Phase 1 implementation effort
-4. **Next Week:** Begin Phase 1 development
-
----
-
-**Status:** Analysis Complete - Ready for Action
-
-All documents are located in:
-`/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/`
-
-Files:
-- TELEMETRY_ANALYSIS_INDEX.md (this file)
-- TELEMETRY_EXECUTIVE_SUMMARY.md
-- TELEMETRY_ANALYSIS_REPORT.md
-- TELEMETRY_TECHNICAL_DEEP_DIVE.md
-- IMPLEMENTATION_ROADMAP.md
-- TELEMETRY_DATA_FOR_VISUALIZATION.md

TELEMETRY_ANALYSIS_README.md

@@ -1,422 +0,0 @@
-# Telemetry Analysis Documentation Index
-
-**Comprehensive Analysis of N8N-MCP Telemetry Infrastructure**
-**Analysis Date:** November 12, 2025
-**Status:** Complete and Ready for Implementation
-
----
-
-## Quick Start
-
-If you only have 5 minutes:
-- Read the summary section below
-
-If you have 30 minutes:
-- Read TELEMETRY_N8N_FIXER_DATASET.md (master summary)
-
-If you have 2+ hours:
-- Start with TELEMETRY_ANALYSIS.md (main reference)
-- Follow with TELEMETRY_MUTATION_SPEC.md (implementation guide)
-- Use TELEMETRY_QUICK_REFERENCE.md for queries/patterns
-
----
-
-## One-Sentence Summary
-
-The n8n-mcp telemetry system successfully tracks 276K+ user interactions across a production Supabase backend, but lacks workflow mutation capture needed for building an n8n-fixer dataset. The solution requires a new table plus 3-4 weeks of integration work.
-
----
-
-## Document Guide
-
-### PRIMARY DOCUMENTS (Created November 12, 2025)
-
-#### 1. TELEMETRY_ANALYSIS.md (23 KB, 720 lines)
-**Your main reference for understanding current state**
-
-Contains:
-- Complete table schemas (telemetry_events, telemetry_workflows)
-- All 12 event types with JSON examples
-- Current workflow tracking capabilities
-- Data samples from production
-- Gap analysis for n8n-fixer requirements
-- Proposed schema additions
-- Privacy & security analysis
-- Data capture pipeline architecture
-
-When to read: You need the complete picture of what exists and what's missing
-
-Read time: 20-30 minutes
-
----
-
-#### 2. TELEMETRY_MUTATION_SPEC.md (26 KB, 918 lines)
-**Your implementation blueprint**
-
-Contains:
-- Complete SQL schema for workflow_mutations table with 20 indexes
-- TypeScript interfaces and type definitions
-- Integration point specifications
-- Mutation analyzer service code structure
-- Batch processor extensions
-- Code examples for tools to instrument
-- Validation rules and data quality checks
-- Query patterns for dataset analysis
-- 4-phase implementation roadmap
-
-When to read: You're ready to start building the mutation tracking system
-
-Read time: 30-40 minutes
-
----
-
-#### 3. TELEMETRY_QUICK_REFERENCE.md (11 KB, 503 lines)
-**Your developer quick lookup guide**
-
-Contains:
-- Supabase connection details
-- Event type quick reference
-- Common SQL query patterns
-- Performance optimization tips
-- User journey analysis examples
-- Platform distribution queries
-- File references and code locations
-- Helpful constants and values
-
-When to read: You need to query existing data or reference specific details
-
-Read time: 10-15 minutes
-
----
-
-#### 4. TELEMETRY_N8N_FIXER_DATASET.md (13 KB, 340 lines)
-**Your executive summary and master planning document**
-
-Contains:
-- Overview of analysis findings
-- Documentation map (what to read in what order)
-- Current state summary
-- Recommended 4-phase implementation path
-- Key metrics you'll collect
-- Storage requirements and cost estimates
-- Risk assessment
-- Success criteria for each phase
-- Questions to answer before starting
-
-When to read: Planning implementation or presenting to stakeholders
-
-Read time: 15-20 minutes
-
----
-
-### SUPPORTING DOCUMENTS (Created November 8, 2025)
-
-#### TELEMETRY_ANALYSIS_REPORT.md (26 KB)
-- Executive summary with visualizations
-- Event distribution statistics
-- Usage patterns and trends
-- Performance metrics
-- User activity analysis
-
-#### TELEMETRY_EXECUTIVE_SUMMARY.md (10 KB)
-- High-level overview for executives
-- Key statistics and metrics
-- Business impact assessment
-- Recommendation summary
-
-#### TELEMETRY_TECHNICAL_DEEP_DIVE.md (18 KB)
-- Architecture and design patterns
-- Component interactions
-- Data flow diagrams
-- Implementation details
-- Performance considerations
-
-#### TELEMETRY_DATA_FOR_VISUALIZATION.md (18 KB)
-- Sample datasets for dashboards
-- Query results and aggregations
-- Visualization recommendations
-- Chart and graph specifications
-
-#### TELEMETRY_ANALYSIS_INDEX.md (15 KB)
-- Index of all analyses
-- Cross-references
-- Topic mappings
-- Search guide
-
----
-
-## Recommended Reading Order
-
-### For Implementation Teams
-1. TELEMETRY_N8N_FIXER_DATASET.md (15 min) - Understand the plan
-2. TELEMETRY_ANALYSIS.md (30 min) - Understand current state
-3. TELEMETRY_MUTATION_SPEC.md (40 min) - Get implementation details
-4. TELEMETRY_QUICK_REFERENCE.md (10 min) - Reference during coding
-
-**Total Time:** 95 minutes
-
-### For Product Managers
-1. TELEMETRY_EXECUTIVE_SUMMARY.md (10 min)
-2. TELEMETRY_N8N_FIXER_DATASET.md (15 min)
-3. TELEMETRY_ANALYSIS_REPORT.md (20 min)
-
-**Total Time:** 45 minutes
-
-### For Data Analysts
-1. TELEMETRY_ANALYSIS.md (30 min)
-2. TELEMETRY_QUICK_REFERENCE.md (10 min)
-3. TELEMETRY_ANALYSIS_REPORT.md (20 min)
-
-**Total Time:** 60 minutes
-
-### For Architects
-1. TELEMETRY_TECHNICAL_DEEP_DIVE.md (20 min)
-2. TELEMETRY_MUTATION_SPEC.md (40 min)
-3. TELEMETRY_N8N_FIXER_DATASET.md (15 min)
-
-**Total Time:** 75 minutes
-
----
-
-## Key Findings Summary
-
-### What Exists Today
-- **276K+ telemetry events** tracked in Supabase
-- **6.5K+ unique workflows** analyzed
-- **12 event types** covering tool usage, errors, validation, workflow creation
-- **Production-grade infrastructure** with batching, retry logic, rate limiting
-- **Privacy-focused design** with sanitization, anonymization, encryption
-
-### Critical Gaps for N8N-Fixer
-- No workflow mutation/modification tracking
-- No before/after workflow snapshots
-- No instruction/transformation capture
-- No mutation success metrics
-- No validation improvement tracking
-
-### Proposed Solution
-- New `workflow_mutations` table (with 20 indexes)
-- Extended telemetry system to capture mutations
-- Instrumentation of 3-4 key tools
-- 4-phase implementation (3-4 weeks)
-
-### Data Volume Estimates
-- Per mutation: 25 KB (with compression)
-- Monthly: 250 MB - 1.2 GB
-- Annual: 3-14 GB
-- Cost: $10-200/month (depending on volume)
-
-### Implementation Effort
-- Phase 1 (Infrastructure): 40-60 hours
-- Phase 2 (Core Integration): 40-60 hours
-- Phase 3 (Tool Integration): 20-30 hours
-- Phase 4 (Validation): 20-30 hours
-- **Total:** 120-180 hours (3-4 weeks)
-
----
-
-## Critical Data
-
-### Supabase Connection
-```
-URL: https://ydyufsohxdfpopqbubwk.supabase.co
-Database: PostgreSQL
-Auth: Anon key (in telemetry-types.ts)
-Tables: telemetry_events, telemetry_workflows
-```
-
-### Event Types (by volume)
-1. tool_used (40-50%)
-2. tool_sequence (20-30%)
-3. error_occurred (10-15%)
-4. validation_details (5-10%)
-5. Others (workflow, session, performance) (5-10%)
-
-### Node Files
-- Source types: `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/telemetry-types.ts`
-- Main manager: `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/telemetry-manager.ts`
-- Event tracker: `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/event-tracker.ts`
-- Batch processor: `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/batch-processor.ts`
-
----
-
-## Implementation Checklist
-
-### Before Starting
-- [ ] Read TELEMETRY_N8N_FIXER_DATASET.md
-- [ ] Read TELEMETRY_ANALYSIS.md
-- [ ] Answer 6 questions (see TELEMETRY_N8N_FIXER_DATASET.md)
-- [ ] Get stakeholder approval for 4-phase plan
-- [ ] Assign implementation team
-
-### Phase 1: Infrastructure (Weeks 1-2)
-- [ ] Create workflow_mutations table in Supabase
-- [ ] Add 20+ indexes per specification
-- [ ] Define TypeScript types
-- [ ] Build mutation validator
-- [ ] Write unit tests
-
-### Phase 2: Core Integration (Weeks 2-3)
-- [ ] Add trackWorkflowMutation() to TelemetryManager
-- [ ] Extend EventTracker with mutation queue
-- [ ] Extend BatchProcessor for mutations
-- [ ] Write integration tests
-- [ ] Code review and merge
-
-### Phase 3: Tool Integration (Week 4)
-- [ ] Instrument n8n_autofix_workflow
-- [ ] Instrument n8n_update_partial_workflow
-- [ ] Instrument validation engine (if applicable)
-- [ ] Manual end-to-end testing
-- [ ] Code review and merge
-
-### Phase 4: Validation (Week 5)
-- [ ] Collect 100+ sample mutations
-- [ ] Verify data quality
-- [ ] Run analysis queries
-- [ ] Assess dataset readiness
-- [ ] Begin production collection
-
----
-
-## Storage & Cost Planning
-
-### Conservative Estimate (10K mutations/month)
-- Storage: 250 MB/month
-- Cost: $10-20/month
-- Dataset: 1K mutations in 3-4 days
-
-### Moderate Estimate (30K mutations/month)
-- Storage: 750 MB/month
-- Cost: $50-100/month
-- Dataset: 10K mutations in 10 days
-
-### High Estimate (50K mutations/month)
-- Storage: 1.2 GB/month
-- Cost: $100-200/month
-- Dataset: 100K mutations in 2 months
-
-**With 90-day retention policy, costs stay at lower end.**
-
----
-
-## Questions Before Implementation
-
-1. **Data Retention:** Keep mutations for 90 days? 1 year? Indefinite?
-2. **Storage Budget:** Monthly budget for telemetry storage?
-3. **Workflow Size:** Max workflow size to store? Compression required?
-4. **Dataset Timeline:** When do you need first dataset? (1K? 10K? 100K?)
-5. **Privacy:** Additional PII to sanitize beyond current approach?
-6. **User Consent:** Separate opt-in for mutation tracking vs. general telemetry?
-
----
-
-## Risk Assessment
-
-### Low Risk
-- No breaking changes to existing system
-- Fully backward compatible
-- Optional feature (can disable if needed)
-- No version bump required
-
-### Medium Risk
-- Storage growth if >1.2 GB/month
-- Performance impact if workflows >10 MB
-- Mitigation: Compression + retention policy
-
-### High Risk
-- None identified
-
----
-
-## Success Criteria
-
-When you can answer "yes" to all:
-- [ ] 100+ workflow mutations collected
-- [ ] Data hash verification passes 100%
-- [ ] Sample queries execute <100ms
-- [ ] Deduplication working correctly
-- [ ] Before/after states properly stored
-- [ ] Validation improvements tracked accurately
-- [ ] No performance regression in tools
-- [ ] Team ready for large-scale collection
-
----
-
-## Next Steps
-
-### Immediate (This Week)
-1. Review this README
-2. Read TELEMETRY_N8N_FIXER_DATASET.md
-3. Read TELEMETRY_ANALYSIS.md
-4. Schedule team review meeting
-
-### Short-term (Next 1-2 Weeks)
-1. Answer the 6 questions
-2. Get stakeholder approval
-3. Assign implementation lead
-4. Create Jira tickets for Phase 1
-
-### Medium-term (Weeks 3-6)
-1. Execute Phase 1 (Infrastructure)
-2. Execute Phase 2 (Core Integration)
-3. Execute Phase 3 (Tool Integration)
-4. Execute Phase 4 (Validation)
-
-### Long-term (Week 7+)
-1. Begin production dataset collection
-2. Monitor storage and costs
-3. Run analysis queries
-4. Iterate based on findings
-
----
-
-## Contact & Questions
-
-**Analysis Completed By:** Telemetry Data Analyst
-**Date:** November 12, 2025
-**Status:** Ready for team review and implementation
-
-For questions or clarifications:
-1. Review the specific document for your question
-2. Check TELEMETRY_QUICK_REFERENCE.md for common lookups
-3. Refer to source files in src/telemetry/
-
----
-
-## Document Statistics
-
-| Document | Size | Lines | Read Time | Purpose |
-|----------|------|-------|-----------|---------|
-| TELEMETRY_ANALYSIS.md | 23 KB | 720 | 20-30 min | Main reference |
-| TELEMETRY_MUTATION_SPEC.md | 26 KB | 918 | 30-40 min | Implementation guide |
-| TELEMETRY_QUICK_REFERENCE.md | 11 KB | 503 | 10-15 min | Developer lookup |
-| TELEMETRY_N8N_FIXER_DATASET.md | 13 KB | 340 | 15-20 min | Executive summary |
-| TELEMETRY_ANALYSIS_REPORT.md | 26 KB | 732 | 20-30 min | Statistics & trends |
-| TELEMETRY_EXECUTIVE_SUMMARY.md | 10 KB | 345 | 10-15 min | Executive brief |
-| TELEMETRY_TECHNICAL_DEEP_DIVE.md | 18 KB | 654 | 20-25 min | Architecture |
-| TELEMETRY_DATA_FOR_VISUALIZATION.md | 18 KB | 468 | 15-20 min | Dashboard data |
-| TELEMETRY_ANALYSIS_INDEX.md | 15 KB | 447 | 10-15 min | Topic index |
-| **TOTAL** | **160 KB** | **5,237** | **150-180 min** | Full analysis |
-
----
-
-## Version History
-
-| Date | Version | Changes |
-|------|---------|---------|
-| Nov 8, 2025 | 1.0 | Initial analysis and reports |
-| Nov 12, 2025 | 2.0 | Core documentation + mutation spec + this README |
-
----
-
-## License & Attribution
-
-These analysis documents are part of the n8n-mcp project.
-Conceived by Romuald Członkowski - www.aiadvisors.pl/en
-
----
-
-**END OF README**
-
-For additional information, start with one of the primary documents above based on your role and available time.

TELEMETRY_ANALYSIS_REPORT.md

@@ -1,732 +0,0 @@
-# n8n-MCP Telemetry Analysis Report
-## Error Patterns and Troubleshooting Analysis (90-Day Period)
-
-**Report Date:** November 8, 2025
-**Analysis Period:** August 10, 2025 - November 8, 2025
-**Data Freshness:** Live (last updated Oct 31, 2025)
-
----
-
-## Executive Summary
-
-This telemetry analysis examined 506K+ events across the n8n-MCP system to identify critical pain points for AI agents. The findings reveal that while core tool success rates are high (96-100%), specific validation and configuration challenges create friction that impacts developer experience.
-
-### Key Findings
-
-1. **8,859 total errors** across 90 days with significant volatility (28 to 406 errors/day), suggesting systemic issues triggered by specific conditions rather than constant problems
-
-2. **Validation failures dominate error landscape** with 34.77% of all errors being ValidationError, followed by TypeError (31.23%) and generic Error (30.60%)
-
-3. **Specific tools show concerning failure patterns**: `get_node_info` (11.72% failure rate), `get_node_documentation` (4.13%), and `validate_node_operation` (6.42%) struggle with reliability
-
-4. **Most common error: Workflow-level validation** represents 39.11% of validation errors, indicating widespread issues with workflow structure validation
-
-5. **Tool usage patterns reveal critical bottlenecks**: Sequential tool calls like `n8n_update_partial_workflow->n8n_update_partial_workflow` take average 55.2 seconds with 66% being slow transitions
-
-### Immediate Action Items
-
-- Fix `get_node_info` reliability (11.72% error rate vs. 0-4% for similar tools)
-- Improve workflow validation error messages to help users understand structure problems
-- Optimize sequential update operations that show 55+ second latencies
-- Address validation test coverage gaps (38,000+ "Node*" placeholder nodes triggering errors)
-
----
-
-## 1. Error Analysis
-
-### 1.1 Overall Error Volume and Frequency
-
-**Raw Statistics:**
-- **Total error events (90 days):** 8,859
-- **Average daily errors:** 60.68
-- **Peak error day:** 276 errors (October 30, 2025)
-- **Days with errors:** 36 out of 90 (40%)
-- **Error-free days:** 54 (60%)
-
-**Trend Analysis:**
-- High volatility with swings of -83.72% to +567.86% day-to-day
-- October 12 saw a 567.86% spike (28 → 187 errors), suggesting a deployment or system event
-- October 10-11 saw 57.64% drop, possibly indicating a hotfix
-- Current trajectory: Stabilizing around 130-160 errors/day (last 10 days)
-
-**Distribution Over Time:**
-```
-Peak Error Days (Top 5):
-  2025-09-26: 6,222 validation errors
-  2025-10-04: 3,585 validation errors
-  2025-10-05: 3,344 validation errors
-  2025-10-07: 2,858 validation errors
-  2025-10-06: 2,816 validation errors
-
-Pattern: Late September peak followed by elevated plateau through early October
-```
-
-### 1.2 Error Type Breakdown
-
-| Error Type | Count | % of Total | Days Occurred | Severity |
-|------------|-------|-----------|---------------|----------|
-| ValidationError | 3,080 | 34.77% | 36 | High |
-| TypeError | 2,767 | 31.23% | 36 | High |
-| Error (generic) | 2,711 | 30.60% | 36 | High |
-| SqliteError | 202 | 2.28% | 32 | Medium |
-| unknown_error | 89 | 1.00% | 3 | Low |
-| MCP_server_timeout | 6 | 0.07% | 1 | Critical |
-| MCP_server_init_fail | 3 | 0.03% | 1 | Critical |
-
-**Critical Insight:** 96.6% of errors are validation-related (ValidationError, TypeError, generic Error). This suggests the issue is primarily in configuration validation logic, not core infrastructure.
-
-**Detailed Error Categories:**
-
-**ValidationError (3,080 occurrences - 34.77%)**
-- Primary source: Workflow structure validation
-- Trigger: Invalid node configurations, missing required fields
-- Impact: Users cannot deploy workflows until fixed
-- Trend: Consistent daily occurrence (100% days affected)
-
-**TypeError (2,767 occurrences - 31.23%)**
-- Pattern: Type mismatches in node properties
-- Common scenario: String passed where number expected, or vice versa
-- Impact: Workflow validation failures, tool invocation errors
-- Indicates: Need for better type enforcement or clearer schema documentation
-
-**Generic Error (2,711 occurrences - 30.60%)**
-- Least helpful category; lacks actionable context
-- Likely source: Unhandled exceptions in validation pipeline
-- Recommendations: Implement error code system with specific error types
-- Impact on DX: Users cannot determine root cause
-
----
-
-## 2. Validation Error Patterns
-
-### 2.1 Validation Errors by Node Type
-
-**Problematic Findings:**
-
-| Node Type | Error Count | Days | % of Validation Errors | Issue |
-|-----------|------------|------|----------------------|--------|
-| workflow | 21,423 | 36 | 39.11% | **CRITICAL** - 39% of all validation errors at workflow level |
-| [KEY] | 656 | 35 | 1.20% | Property key validation failures |
-| ______ | 643 | 33 | 1.17% | Placeholder nodes (test data) |
-| Webhook | 435 | 35 | 0.79% | Webhook configuration issues |
-| HTTP_Request | 212 | 29 | 0.39% | HTTP node validation issues |
-
-**Major Concern: Placeholder Node Names**
-
-The presence of generic placeholder names (Node0-Node19, [KEY], ______, _____) represents 4,700+ errors. These appear to be:
-1. Test data that wasn't cleaned up
-2. Incomplete workflow definitions from users
-3. Validation test cases creating noise in telemetry
-
-**Workflow-Level Validation (21,423 errors - 39.11%)**
-
-This is the single largest error category. Issues include:
-- Missing start nodes (triggers)
-- Invalid node connections
-- Circular dependencies
-- Missing required node properties
-- Type mismatches in connections
-
-**Critical Action:** Improve workflow validation error messages to provide specific guidance on what structure requirement failed.
-
-### 2.2 Node-Specific Validation Issues
-
-**High-Risk Node Types:**
-- **Webhook**: 435 errors - likely authentication/path configuration issues
-- **HTTP_Request**: 212 errors - likely header/body configuration problems
-- **Database nodes**: Not heavily represented, suggesting better validation
-- **AI/Code nodes**: Minimal representation in error data
-
-**Pattern Observation:** Trigger nodes (Webhook, Webhook_Trigger) appear in validation errors, suggesting connection complexity issues.
-
----
-
-## 3. Tool Usage and Success Rates
-
-### 3.1 Overall Tool Performance
-
-**Top 25 Tools by Usage (90 days):**
-
-| Tool | Invocations | Success Rate | Failure Rate | Avg Duration (ms) | Status |
-|------|------------|--------------|--------------|-----------------|--------|
-| n8n_update_partial_workflow | 103,732 | 99.06% | 0.94% | 417.77 | Reliable |
-| search_nodes | 63,366 | 99.89% | 0.11% | 28.01 | Excellent |
-| get_node_essentials | 49,625 | 96.19% | 3.81% | 4.79 | Good |
-| n8n_create_workflow | 49,578 | 96.35% | 3.65% | 359.08 | Good |
-| n8n_get_workflow | 37,703 | 99.94% | 0.06% | 291.99 | Excellent |
-| n8n_validate_workflow | 29,341 | 99.70% | 0.30% | 269.33 | Excellent |
-| n8n_update_full_workflow | 19,429 | 99.27% | 0.73% | 415.39 | Reliable |
-| n8n_get_execution | 19,409 | 99.90% | 0.10% | 652.97 | Excellent |
-| n8n_list_executions | 17,111 | 100.00% | 0.00% | 375.46 | Perfect |
-| get_node_documentation | 11,403 | 95.87% | 4.13% | 2.45 | Needs Work |
-| get_node_info | 10,304 | 88.28% | 11.72% | 3.85 | **CRITICAL** |
-| validate_workflow | 9,738 | 94.50% | 5.50% | 33.63 | Concerning |
-| validate_node_operation | 5,654 | 93.58% | 6.42% | 5.05 | Concerning |
-
-### 3.2 Critical Tool Issues
-
-**1. `get_node_info` - 11.72% Failure Rate (CRITICAL)**
-
-- **Failures:** 1,208 out of 10,304 invocations
-- **Impact:** Users cannot retrieve node specifications when building workflows
-- **Likely Cause:**
-  - Database schema mismatches
-  - Missing node documentation
-  - Encoding/parsing errors
-- **Recommendation:** Immediately review error logs for this tool; implement fallback to cache or defaults
-
-**2. `validate_workflow` - 5.50% Failure Rate**
-
-- **Failures:** 536 out of 9,738 invocations
-- **Impact:** Users cannot validate workflows before deployment
-- **Correlation:** Likely related to workflow-level validation errors (39.11% of validation errors)
-- **Root Cause:** Validation logic may not handle all edge cases
-
-**3. `get_node_documentation` - 4.13% Failure Rate**
-
-- **Failures:** 471 out of 11,403 invocations
-- **Impact:** Users cannot access documentation when learning nodes
-- **Pattern:** Documentation retrieval failures compound with `get_node_info` issues
-
-**4. `validate_node_operation` - 6.42% Failure Rate**
-
-- **Failures:** 363 out of 5,654 invocations
-- **Impact:** Configuration validation provides incorrect feedback
-- **Concern:** Could lead to false positives (rejecting valid configs) or false negatives (accepting invalid ones)
-
-### 3.3 Reliable Tools (Baseline for Improvement)
-
-These tools show <1% failure rates and should be used as templates:
-- `search_nodes`: 99.89% (0.11% failure)
-- `n8n_get_workflow`: 99.94% (0.06% failure)
-- `n8n_get_execution`: 99.90% (0.10% failure)
-- `n8n_list_executions`: 100.00% (perfect)
-
-**Common Pattern:** Read-only and list operations are highly reliable, while validation operations are problematic.
-
----
-
-## 4. Tool Usage Patterns and Bottlenecks
-
-### 4.1 Sequential Tool Sequences (Most Common)
-
-The telemetry data shows AI agents follow predictable workflows. Analysis of 152K+ hourly tool sequence records reveals critical bottleneck patterns:
-
-| Sequence | Occurrences | Avg Duration | Slow Transitions |
-|----------|------------|--------------|-----------------|
-| update_partial → update_partial | 96,003 | 55.2s | 66% |
-| search_nodes → search_nodes | 68,056 | 11.2s | 17% |
-| get_node_essentials → get_node_essentials | 51,854 | 10.6s | 17% |
-| create_workflow → create_workflow | 41,204 | 54.9s | 80% |
-| search_nodes → get_node_essentials | 28,125 | 19.3s | 34% |
-| get_workflow → update_partial | 27,113 | 53.3s | 84% |
-| update_partial → validate_workflow | 25,203 | 20.1s | 41% |
-| list_executions → get_execution | 23,101 | 13.9s | 22% |
-| validate_workflow → update_partial | 23,013 | 60.6s | 74% |
-| update_partial → get_workflow | 19,876 | 96.6s | 63% |
-
-**Critical Issues Identified:**
-
-1. **Update Loops**: `update_partial → update_partial` has 96,003 occurrences
-   - Average 55.2s between calls
-   - 66% marked as "slow transitions"
-   - Suggests: Users iteratively updating workflows, with network/processing lag
-
-2. **Massive Duration on `update_partial → get_workflow`**: 96.6 seconds average
-   - Users check workflow state after update
-   - High latency suggests possible API bottleneck or large workflow processing
-
-3. **Sequential Search Operations**: 68,056 `search_nodes → search_nodes` calls
-   - Users refining search through multiple queries
-   - Could indicate search results are not meeting needs on first attempt
-
-4. **Read-After-Write Patterns**: Many sequences involve getting/validating after updates
-   - Suggests transactions aren't atomic; users manually verify state
-   - Could be optimized by returning updated state in response
-
-### 4.2 Implications for AI Agents
-
-AI agents exhibit these problematic patterns:
-- **Excessive retries**: Same operation repeated multiple times
-- **State uncertainty**: Need to re-fetch state after modifications
-- **Search inefficiency**: Multiple queries to find right tools/nodes
-- **Long wait times**: Up to 96 seconds between sequential operations
-
-**This creates:**
-- Slower agent response times to users
-- Higher API load and costs
-- Poor user experience (agents appear "stuck")
-- Wasted computational resources
-
----
-
-## 5. Session and User Activity Analysis
-
-### 5.1 Engagement Metrics
-
-| Metric | Value | Interpretation |
-|--------|-------|-----------------|
-| Avg Sessions/Day | 895 | Healthy usage |
-| Avg Users/Day | 572 | Growing user base |
-| Avg Sessions/User | 1.52 | Users typically engage once per day |
-| Peak Sessions Day | 1,821 (Oct 22) | Single major engagement spike |
-
-**Notable Date:** October 22, 2025 shows 2.94 sessions per user (vs. typical 1.4-1.6)
-- Could indicate: Feature launch, bug fix, or major update
-- Correlates with error spikes in early October
-
-### 5.2 Session Quality Patterns
-
-- Consistent 600-1,200 sessions daily
-- User base stable at 470-620 users per day
-- Some days show <5% of normal activity (Oct 11: 30 sessions)
-- Weekend vs. weekday patterns not visible in daily aggregates
-
----
-
-## 6. Search Query Analysis (User Intent)
-
-### 6.1 Most Searched Topics
-
-| Query | Total Searches | Days Searched | User Need |
-|-------|----------------|---------------|-----------|
-| test | 5,852 | 22 | Testing workflows |
-| webhook | 5,087 | 25 | Webhook triggers/integration |
-| http | 4,241 | 22 | HTTP requests |
-| database | 4,030 | 21 | Database operations |
-| api | 2,074 | 21 | API integrations |
-| http request | 1,036 | 22 | HTTP node details |
-| google sheets | 643 | 22 | Google integration |
-| code javascript | 616 | 22 | Code execution |
-| openai | 538 | 22 | AI integrations |
-
-**Key Insights:**
-
-1. **Top 4 searches (19,210 searches, 40% of traffic)**:
-   - Testing (5,852)
-   - Webhooks (5,087)
-   - HTTP (4,241)
-   - Databases (4,030)
-
-2. **Use Case Patterns**:
-   - **Integration-heavy**: Webhooks, API, HTTP, Google Sheets (15,000+ searches)
-   - **Logic/Execution**: Code, testing (6,500+ searches)
-   - **AI Integration**: OpenAI mentioned 538 times (trending interest)
-
-3. **Learning Curve Indicators**:
-   - "http request" vs. "http" suggests users searching for specific node
-   - "schedule cron" appears 270 times (scheduling is confusing)
-   - "manual trigger" appears 300 times (trigger types unclear)
-
-**Implication:** Users struggle most with:
-1. HTTP request configuration (1,300+ searches for HTTP-related topics)
-2. Scheduling/triggers (800+ searches for trigger types)
-3. Understanding testing practices (5,852 searches)
-
----
-
-## 7. Workflow Quality and Validation
-
-### 7.1 Workflow Validation Grades
-
-| Grade | Count | Percentage | Quality Score |
-|-------|-------|-----------|----------------|
-| A | 5,156 | 100% | 100.0 |
-
-**Critical Issue:** Only Grade A workflows in database, despite 39% validation error rate
-
-**Explanation:**
-- The `telemetry_workflows` table captures only successfully ingested workflows
-- Error events are tracked separately in `telemetry_errors_daily`
-- Failed workflows never make it to the workflows table
-- This creates a survivorship bias in quality metrics
-
-**Real Story:**
-- 7,869 workflows attempted
-- 5,156 successfully validated (65.5% success rate implied)
-- 2,713 workflows failed validation (34.5% failure rate implied)
-
----
-
-## 8. Top 5 Issues Impacting AI Agent Success
-
-Ranked by severity and impact:
-
-### Issue 1: Workflow-Level Validation Failures (39.11% of validation errors)
-
-**Problem:** 21,423 validation errors related to workflow structure validation
-
-**Root Causes:**
-- Invalid node connections
-- Missing trigger nodes
-- Circular dependencies
-- Type mismatches in connections
-- Incomplete node configurations
-
-**AI Agent Impact:**
-- Agents cannot deploy workflows
-- Error messages too generic ("workflow validation failed")
-- No guidance on what structure requirement failed
-- Forces agents to retry with different structures
-
-**Quick Win:** Enhance workflow validation error messages to specify which structural requirement failed
-
-**Implementation Effort:** Medium (2-3 days)
-
----
-
-### Issue 2: `get_node_info` Unreliability (11.72% failure rate)
-
-**Problem:** 1,208 failures out of 10,304 invocations
-
-**Root Causes:**
-- Likely missing node documentation or schema
-- Encoding issues with complex node definitions
-- Database connectivity problems during specific queries
-
-**AI Agent Impact:**
-- Agents cannot retrieve node specifications when building
-- Fall back to guessing or using incomplete essentials
-- Creates cascading validation errors
-- Slows down workflow creation
-
-**Quick Win:** Add retry logic with exponential backoff; implement fallback to cache
-
-**Implementation Effort:** Low (1 day)
-
----
-
-### Issue 3: Slow Sequential Update Operations (96,003 occurrences, avg 55.2s)
-
-**Problem:** `update_partial_workflow → update_partial_workflow` takes avg 55.2 seconds with 66% slow transitions
-
-**Root Causes:**
-- Network latency between operations
-- Large workflow serialization
-- Possible blocking on previous operations
-- No batch update capability
-
-**AI Agent Impact:**
-- Agents wait 55+ seconds between sequential modifications
-- Workflow construction takes minutes instead of seconds
-- Poor perceived performance
-- Users abandon incomplete workflows
-
-**Quick Win:** Implement batch workflow update operation
-
-**Implementation Effort:** High (5-7 days)
-
----
-
-### Issue 4: Search Result Relevancy Issues (68,056 `search_nodes → search_nodes` calls)
-
-**Problem:** Users perform multiple search queries in sequence (17% slow transitions)
-
-**Root Causes:**
-- Initial search results don't match user intent
-- Search ranking algorithm suboptimal
-- Users unsure of node names
-- Broad searches returning too many results
-
-**AI Agent Impact:**
-- Agents make multiple search attempts to find right node
-- Increases API calls and latency
-- Uncertainty in node selection
-- Compounds with slow subsequent operations
-
-**Quick Win:** Analyze top 50 repeated search sequences; improve ranking for high-volume queries
-
-**Implementation Effort:** Medium (3 days)
-
----
-
-### Issue 5: `validate_node_operation` Inaccuracy (6.42% failure rate)
-
-**Problem:** 363 failures out of 5,654 invocations; validation provides unreliable feedback
-
-**Root Causes:**
-- Validation logic doesn't handle all node operation combinations
-- Missing edge case handling
-- Validator version mismatches
-- Property dependency logic incomplete
-
-**AI Agent Impact:**
-- Agents may trust invalid configurations (false positives)
-- Or reject valid ones (false negatives)
-- Either way: Unreliable feedback breaks agent judgment
-- Forces manual verification
-
-**Quick Win:** Add telemetry to capture validation false positive/negative cases
-
-**Implementation Effort:** Medium (4 days)
-
----
-
-## 9. Temporal and Anomaly Patterns
-
-### 9.1 Error Spike Events
-
-**Major Spike #1: October 12, 2025**
-- Error increase: 567.86% (28 → 187 errors)
-- Context: Validation errors jumped from low to baseline
-- Likely event: System restart, deployment, or database issue
-
-**Major Spike #2: September 26, 2025**
-- Daily validation errors: 6,222 (highest single day)
-- Represents: 70% of September error volume
-- Context: Possible large test batch or migration
-
-**Major Spike #3: Early October (Oct 3-10)**
-- Sustained elevation: 3,344-2,038 errors daily
-- Duration: 8 days of high error rates
-- Recovery: October 11 drops to 28 errors (83.72% decrease)
-- Suggests: Incident and mitigation
-
-### 9.2 Recent Trend (Last 10 Days)
-
-- Stabilized at 130-278 errors/day
-- More predictable pattern
-- Suggests: System stabilization post-October incident
-- Current error rate: ~60 errors/day (normal baseline)
-
----
-
-## 10. Actionable Recommendations
-
-### Priority 1 (Immediate - Week 1)
-
-1. **Fix `get_node_info` Reliability**
-   - Impact: Affects 1,200+ failures affecting agents
-   - Action: Review error logs; add retry logic; implement cache fallback
-   - Expected benefit: Reduce tool failure rate from 11.72% to <1%
-
-2. **Improve Workflow Validation Error Messages**
-   - Impact: 39% of validation errors lack clarity
-   - Action: Create specific error codes for structural violations
-   - Expected benefit: Reduce user frustration; improve agent success rate
-   - Example: Instead of "validation failed", return "Missing start trigger node"
-
-3. **Add Batch Workflow Update Operation**
-   - Impact: 96,003 sequential updates at 55.2s each
-   - Action: Create `n8n_batch_update_workflow` tool
-   - Expected benefit: 80-90% reduction in workflow update time
-
-### Priority 2 (High - Week 2-3)
-
-4. **Implement Validation Caching**
-   - Impact: Reduce repeated validation of identical configs
-   - Action: Cache validation results with invalidation on node updates
-   - Expected benefit: 40-50% reduction in `validate_workflow` calls
-
-5. **Improve Node Search Ranking**
-   - Impact: 68,056 sequential search calls
-   - Action: Analyze top repeated sequences; adjust ranking algorithm
-   - Expected benefit: Fewer searches needed; faster node discovery
-
-6. **Add TypeScript Types for Common Nodes**
-   - Impact: Type mismatches cause 31.23% of errors
-   - Action: Generate strict TypeScript definitions for top 50 nodes
-   - Expected benefit: AI agents make fewer type-related mistakes
-
-### Priority 3 (Medium - Week 4)
-
-7. **Implement Return-Updated-State Pattern**
-   - Impact: Users fetch state after every update (19,876 `update → get_workflow` calls)
-   - Action: Update tools to return full updated state
-   - Expected benefit: Eliminate unnecessary API calls; reduce round-trips
-
-8. **Add Workflow Diff Generation**
-   - Impact: Help users understand what changed after updates
-   - Action: Generate human-readable diffs of workflow changes
-   - Expected benefit: Better visibility; easier debugging
-
-9. **Create Validation Test Suite**
-   - Impact: Generic placeholder nodes (Node0-19) creating noise
-   - Action: Clean up test data; implement proper test isolation
-   - Expected benefit: Clearer signal in telemetry; 600+ error reduction
-
-### Priority 4 (Documentation - Ongoing)
-
-10. **Create Error Code Documentation**
-    - Document each error type with resolution steps
-    - Examples of what causes ValidationError, TypeError, etc.
-    - Quick reference for agents and developers
-
-11. **Add Configuration Examples for Top 20 Nodes**
-    - HTTP Request (1,300+ searches)
-    - Webhook (5,087 searches)
-    - Database nodes (4,030 searches)
-    - With working examples and common pitfalls
-
-12. **Create Trigger Configuration Guide**
-    - Explain scheduling (270+ "schedule cron" searches)
-    - Manual triggers (300 searches)
-    - Webhook triggers (5,087 searches)
-    - Clear comparison of use cases
-
----
-
-## 11. Monitoring Recommendations
-
-### Key Metrics to Track
-
-1. **Tool Failure Rates** (daily):
-   - Alert if `get_node_info` > 5%
-   - Alert if `validate_workflow` > 2%
-   - Alert if `validate_node_operation` > 3%
-
-2. **Workflow Validation Success Rate**:
-   - Target: >95% of workflows pass validation first attempt
-   - Current: Estimated 65% (5,156 of 7,869)
-
-3. **Sequential Operation Latency**:
-   - Track p50/p95/p99 for update operations
-   - Target: <5s for sequential updates
-   - Current: 55.2s average (needs optimization)
-
-4. **Error Rate Volatility**:
-   - Daily error count should stay within 100-200
-   - Alert if day-over-day change >30%
-
-5. **Search Query Success**:
-   - Track how many repeated searches for same term
-   - Target: <2 searches needed to find node
-   - Current: 17-34% slow transitions
-
-### Dashboards to Create
-
-1. **Daily Error Dashboard**
-   - Error counts by type (Validation, Type, Generic)
-   - Error trends over 7/30/90 days
-   - Top error-triggering operations
-
-2. **Tool Health Dashboard**
-   - Failure rates for all tools
-   - Success rate trends
-   - Duration trends for slow operations
-
-3. **Workflow Quality Dashboard**
-   - Validation success rates
-   - Common failure patterns
-   - Node type error distributions
-
-4. **User Experience Dashboard**
-   - Session counts and user trends
-   - Search patterns and result relevancy
-   - Average workflow creation time
-
----
-
-## 12. SQL Queries Used (For Reproducibility)
-
-### Query 1: Error Overview
-```sql
-SELECT
-  COUNT(*) as total_error_events,
-  COUNT(DISTINCT date) as days_with_errors,
-  ROUND(AVG(error_count), 2) as avg_errors_per_day,
-  MAX(error_count) as peak_errors_in_day
-FROM telemetry_errors_daily
-WHERE date >= CURRENT_DATE - INTERVAL '90 days';
-```
-
-### Query 2: Error Type Distribution
-```sql
-SELECT
-  error_type,
-  SUM(error_count) as total_occurrences,
-  COUNT(DISTINCT date) as days_occurred,
-  ROUND(SUM(error_count)::numeric / (SELECT SUM(error_count) FROM telemetry_errors_daily) * 100, 2) as percentage_of_all_errors
-FROM telemetry_errors_daily
-WHERE date >= CURRENT_DATE - INTERVAL '90 days'
-GROUP BY error_type
-ORDER BY total_occurrences DESC;
-```
-
-### Query 3: Tool Success Rates
-```sql
-SELECT
-  tool_name,
-  SUM(usage_count) as total_invocations,
-  SUM(success_count) as successful_invocations,
-  SUM(failure_count) as failed_invocations,
-  ROUND(100.0 * SUM(success_count) / SUM(usage_count), 2) as success_rate_percent,
-  ROUND(AVG(avg_duration_ms)::numeric, 2) as avg_duration_ms,
-  COUNT(DISTINCT date) as days_active
-FROM telemetry_tool_usage_daily
-WHERE date >= CURRENT_DATE - INTERVAL '90 days'
-GROUP BY tool_name
-ORDER BY total_invocations DESC;
-```
-
-### Query 4: Validation Errors by Node Type
-```sql
-SELECT
-  node_type,
-  error_type,
-  SUM(error_count) as total_occurrences,
-  ROUND(SUM(error_count)::numeric / SUM(SUM(error_count)) OVER () * 100, 2) as percentage_of_validation_errors
-FROM telemetry_validation_errors_daily
-WHERE date >= CURRENT_DATE - INTERVAL '90 days'
-GROUP BY node_type, error_type
-ORDER BY total_occurrences DESC;
-```
-
-### Query 5: Tool Sequences
-```sql
-SELECT
-  sequence_pattern,
-  SUM(occurrence_count) as total_occurrences,
-  ROUND(AVG(avg_time_delta_ms)::numeric, 2) as avg_duration_ms,
-  SUM(slow_transition_count) as slow_transitions
-FROM telemetry_tool_sequences_hourly
-WHERE hour >= NOW() - INTERVAL '90 days'
-GROUP BY sequence_pattern
-ORDER BY total_occurrences DESC;
-```
-
-### Query 6: Session Metrics
-```sql
-SELECT
-  date,
-  total_sessions,
-  unique_users,
-  ROUND(total_sessions::numeric / unique_users, 2) as avg_sessions_per_user
-FROM telemetry_session_metrics_daily
-WHERE date >= CURRENT_DATE - INTERVAL '90 days'
-ORDER BY date DESC;
-```
-
-### Query 7: Search Queries
-```sql
-SELECT
-  query_text,
-  SUM(search_count) as total_searches,
-  COUNT(DISTINCT date) as days_searched
-FROM telemetry_search_queries_daily
-WHERE date >= CURRENT_DATE - INTERVAL '90 days'
-GROUP BY query_text
-ORDER BY total_searches DESC;
-```
-
----
-
-## Conclusion
-
-The n8n-MCP telemetry analysis reveals that while core infrastructure is robust (most tools >99% reliability), there are five critical issues preventing optimal AI agent success:
-
-1. **Workflow validation feedback** (39% of errors) - lack of actionable error messages
-2. **Tool reliability** (11.72% failure rate for `get_node_info`) - critical information retrieval failures
-3. **Performance bottlenecks** (55+ second sequential updates) - slow workflow construction
-4. **Search inefficiency** (multiple searches needed) - poor discoverability
-5. **Validation accuracy** (6.42% failure rate) - unreliable configuration feedback
-
-Implementing the Priority 1 recommendations would address 75% of user-facing issues and dramatically improve AI agent performance. The remaining improvements would optimize performance and user experience further.
-
-All recommendations include implementation effort estimates and expected benefits to help with prioritization.
-
----
-
-**Report Prepared By:** AI Telemetry Analyst
-**Data Source:** n8n-MCP Supabase Telemetry Database
-**Next Review:** November 15, 2025 (weekly cadence recommended)

TELEMETRY_DATA_FOR_VISUALIZATION.md

@@ -1,468 +0,0 @@
-# n8n-MCP Telemetry Data - Visualization Reference
-## Charts, Tables, and Graphs for Presentations
-
----
-
-## 1. Error Distribution Chart Data
-
-### Error Types Pie Chart
-```
-ValidationError     3,080 (34.77%) ← Largest slice
-TypeError           2,767 (31.23%)
-Generic Error       2,711 (30.60%)
-SqliteError         202  (2.28%)
-Unknown/Other       99   (1.12%)
-```
-
-**Chart Type:** Pie Chart or Donut Chart
-**Key Message:** 96.6% of errors are validation-related
-
-### Error Volume Line Chart (90 days)
-```
-Date Range: Aug 10 - Nov 8, 2025
-Baseline: 60-65 errors/day (normal)
-Peak: Oct 30 (276 errors, 4.5x baseline)
-Current: ~130-160 errors/day (stabilizing)
-
-Notable Events:
-- Oct 12: 567% spike (incident event)
-- Oct 3-10: 8-day plateau (incident period)
-- Oct 11: 83% drop (mitigation)
-```
-
-**Chart Type:** Line Graph
-**Scale:** 0-300 errors/day
-**Trend:** Volatile but stabilizing
-
----
-
-## 2. Tool Success Rates Bar Chart
-
-### High-Risk Tools (Ranked by Failure Rate)
-```
-Tool Name                    | Success Rate | Failure Rate | Invocations
-------------------------------|-------------|--------------|-------------
-get_node_info                 | 88.28%      | 11.72%       | 10,304
-validate_node_operation       | 93.58%      | 6.42%        | 5,654
-get_node_documentation        | 95.87%      | 4.13%        | 11,403
-validate_workflow             | 94.50%      | 5.50%        | 9,738
-get_node_essentials           | 96.19%      | 3.81%        | 49,625
-n8n_create_workflow           | 96.35%      | 3.65%        | 49,578
-n8n_update_partial_workflow   | 99.06%      | 0.94%        | 103,732
-```
-
-**Chart Type:** Horizontal Bar Chart
-**Color Coding:** Red (<95%), Yellow (95-99%), Green (>99%)
-**Target Line:** 99% success rate
-
----
-
-## 3. Tool Usage Volume Bubble Chart
-
-### Tool Invocation Volume (90 days)
-```
-X-axis: Total Invocations (log scale)
-Y-axis: Success Rate (%)
-Bubble Size: Error Count
-
-Tool Clusters:
-- High Volume, High Success (ideal): search_nodes (63K), list_executions (17K)
-- High Volume, Medium Success (risky): n8n_create_workflow (50K), get_node_essentials (50K)
-- Low Volume, Low Success (critical): get_node_info (10K), validate_node_operation (6K)
-```
-
-**Chart Type:** Bubble/Scatter Chart
-**Focus:** Tools in lower-right quadrant are problematic
-
----
-
-## 4. Sequential Operation Performance
-
-### Tool Sequence Duration Distribution
-```
-Sequence Pattern                         | Count  | Avg Duration (s) | Slow %
------------------------------------------|--------|------------------|-------
-update → update                          | 96,003 | 55.2             | 66%
-search → search                          | 68,056 | 11.2             | 17%
-essentials → essentials                  | 51,854 | 10.6             | 17%
-create → create                          | 41,204 | 54.9             | 80%
-search → essentials                      | 28,125 | 19.3             | 34%
-get_workflow → update_partial            | 27,113 | 53.3             | 84%
-update → validate                        | 25,203 | 20.1             | 41%
-list_executions → get_execution          | 23,101 | 13.9             | 22%
-validate → update                        | 23,013 | 60.6             | 74%
-update → get_workflow (read-after-write) | 19,876 | 96.6             | 63%
-```
-
-**Chart Type:** Horizontal Bar Chart
-**Sort By:** Occurrences (descending)
-**Highlight:** Operations with >50% slow transitions
-
----
-
-## 5. Search Query Analysis
-
-### Top 10 Search Queries
-```
-Query           | Count | Days Searched | User Need
-----------------|-------|---------------|------------------
-test            | 5,852 | 22            | Testing workflows
-webhook         | 5,087 | 25            | Trigger/integration
-http            | 4,241 | 22            | HTTP requests
-database        | 4,030 | 21            | Database operations
-api             | 2,074 | 21            | API integration
-http request    | 1,036 | 22            | Specific node
-google sheets   | 643   | 22            | Google integration
-code javascript | 616   | 22            | Code execution
-openai          | 538   | 22            | AI integration
-telegram        | 528   | 22            | Chat integration
-```
-
-**Chart Type:** Horizontal Bar Chart
-**Grouping:** Integration-heavy (15K), Logic/Execution (6.5K), AI (1K)
-
----
-
-## 6. Validation Errors by Node Type
-
-### Top 15 Node Types by Error Count
-```
-Node Type                | Errors  | % of Total | Status
--------------------------|---------|------------|--------
-workflow (structure)     | 21,423  | 39.11%     | CRITICAL
-[test placeholders]      | 4,700   | 8.57%      | Should exclude
-Webhook                  | 435     | 0.79%      | Needs docs
-HTTP_Request             | 212     | 0.39%      | Needs docs
-[Generic node names]     | 3,500   | 6.38%      | Should exclude
-Schedule/Trigger nodes   | 700     | 1.28%      | Needs docs
-Database nodes           | 450     | 0.82%      | Generally OK
-Code/JS nodes            | 280     | 0.51%      | Generally OK
-AI/OpenAI nodes          | 150     | 0.27%      | Generally OK
-Other                    | 900     | 1.64%      | Various
-```
-
-**Chart Type:** Horizontal Bar Chart
-**Insight:** 39% are workflow-level; 15% are test data noise
-
----
-
-## 7. Session and User Metrics Timeline
-
-### Daily Sessions and Users (30-day rolling average)
-```
-Date Range: Oct 1-31, 2025
-
-Metrics:
-- Avg Sessions/Day: 895
-- Avg Users/Day: 572
-- Avg Sessions/User: 1.52
-
-Weekly Trend:
-Week 1 (Oct 1-7):   900 sessions/day, 550 users
-Week 2 (Oct 8-14):  880 sessions/day, 580 users
-Week 3 (Oct 15-21): 920 sessions/day, 600 users
-Week 4 (Oct 22-28): 1,100 sessions/day, 620 users (spike)
-Week 5 (Oct 29-31): 880 sessions/day, 575 users
-```
-
-**Chart Type:** Dual-axis line chart
-- Left axis: Sessions/day (600-1,200)
-- Right axis: Users/day (400-700)
-
----
-
-## 8. Error Rate Over Time with Annotations
-
-### Error Timeline with Key Events
-```
-Date          | Daily Errors | Day-over-Day | Event/Pattern
---------------|-------------|-------------|------------------
-Sep 26        | 6,222       | +156%       | INCIDENT: Major spike
-Sep 27-30     | 1,200 avg   | -45%        | Recovery period
-Oct 1-5       | 3,000 avg   | +120%       | Sustained elevation
-Oct 6-10      | 2,300 avg   | -30%        | Declining trend
-Oct 11        | 28          | -83.72%     | MAJOR DROP: Possible fix
-Oct 12        | 187         | +567.86%    | System restart/redeployment
-Oct 13-30     | 180 avg     | Stable      | New baseline established
-Oct 31        | 130         | -53.24%     | Current trend: improving
-
-Current Trajectory: Stabilizing at 60-65 errors/day baseline
-```
-
-**Chart Type:** Column chart with annotations
-**Y-axis:** 0-300 errors/day
-**Annotations:** Mark incident events
-
----
-
-## 9. Performance Impact Matrix
-
-### Estimated Time Impact on User Workflows
-```
-Operation                  | Current | After Phase 1 | Improvement
----------------------------|---------|---------------|------------
-Create 5-node workflow     | 4-6 min | 30 seconds    | 91% faster
-Add single node property   | 55s     | <1s          | 98% faster
-Update 10 workflow params  | 9 min   | 5 seconds    | 99% faster
-Find right node (search)   | 30-60s  | 15-20s       | 50% faster
-Validate workflow          | Varies  | <2s          | 80% faster
-
-Total Workflow Creation Time:
-- Current: 15-20 minutes for complex workflow
-- After Phase 1: 2-3 minutes
-- Improvement: 85-90% reduction
-```
-
-**Chart Type:** Comparison bar chart
-**Color coding:** Current (red), Target (green)
-
----
-
-## 10. Tool Failure Rate Comparison
-
-### Tool Failure Rates Ranked
-```
-Rank | Tool Name                    | Failure % | Severity | Action
------|------------------------------|-----------|----------|--------
-1    | get_node_info                | 11.72%    | CRITICAL | Fix immediately
-2    | validate_node_operation      | 6.42%     | HIGH     | Fix week 2
-3    | validate_workflow            | 5.50%     | HIGH     | Fix week 2
-4    | get_node_documentation       | 4.13%     | MEDIUM   | Fix week 2
-5    | get_node_essentials          | 3.81%     | MEDIUM   | Monitor
-6    | n8n_create_workflow          | 3.65%     | MEDIUM   | Monitor
-7    | n8n_update_partial_workflow  | 0.94%     | LOW      | Baseline
-8    | search_nodes                 | 0.11%     | LOW      | Excellent
-9    | n8n_list_executions          | 0.00%     | LOW      | Excellent
-10   | n8n_health_check             | 0.00%     | LOW      | Excellent
-```
-
-**Chart Type:** Horizontal bar chart with target line (1%)
-**Color coding:** Red (>5%), Yellow (2-5%), Green (<2%)
-
----
-
-## 11. Issue Severity and Impact Matrix
-
-### Prioritization Matrix
-```
-          High Impact          |          Low Impact
-High      ┌────────────────────┼────────────────────┐
-Effort    │ 1. Validation      │ 4. Search ranking  │
-          │ Messages (2 days)  │ (2 days)           │
-          │ Impact: 39%        │ Impact: 2%         │
-          │                    │ 5. Type System     │
-          │                    │ (3 days)           │
-          │ 3. Batch Updates   │ Impact: 5%         │
-          │ (2 days)           │                    │
-          │ Impact: 6%         │                    │
-          └────────────────────┼────────────────────┘
-Low       │ 2. get_node_info   │ 7. Return State    │
-Effort    │ Fix (1 day)        │ (1 day)            │
-          │ Impact: 14%        │ Impact: 2%         │
-          │ 6. Type Stubs      │                    │
-          │ (1 day)            │                    │
-          │ Impact: 5%         │                    │
-          └────────────────────┼────────────────────┘
-```
-
-**Chart Type:** 2x2 matrix
-**Bubble size:** Relative impact
-**Focus:** Lower-right quadrant (high impact, low effort)
-
----
-
-## 12. Implementation Timeline with Expected Improvements
-
-### Gantt Chart with Metrics
-```
-Week 1: Immediate Wins
-├─ Fix get_node_info (1 day)        → 91% reduction in failures
-├─ Validation messages (2 days)     → 40% improvement in clarity
-└─ Batch updates (2 days)           → 90% latency improvement
-
-Week 2-3: High Priority
-├─ Validation caching (2 days)      → 40% fewer validation calls
-├─ Search ranking (2 days)          → 30% fewer retries
-└─ Type stubs (3 days)              → 25% fewer type errors
-
-Week 4: Optimization
-├─ Return state (1 day)             → Eliminate 40% redundant calls
-└─ Workflow diffs (1 day)           → Better debugging visibility
-
-Expected Cumulative Impact:
-- Week 1: 40-50% improvement (600+ fewer errors/day)
-- Week 3: 70% improvement (1,900 fewer errors/day)
-- Week 5: 77% improvement (2,000+ fewer errors/day)
-```
-
-**Chart Type:** Gantt chart with overlay
-**Overlay:** Expected error reduction graph
-
----
-
-## 13. Cost-Benefit Analysis
-
-### Implementation Investment vs. Returns
-```
-Investment:
-- Engineering time: 1 FTE × 5 weeks = $15,000
-- Testing/QA: $2,000
-- Documentation: $1,000
-- Total: $18,000
-
-Returns (Estimated):
-- Support ticket reduction: 40% fewer errors = $4,000/month = $48,000/year
-- User retention improvement: +5% = $20,000/month = $240,000/year
-- AI agent efficiency: +30% = $10,000/month = $120,000/year
-- Developer productivity: +20% = $5,000/month = $60,000/year
-
-Total Returns: ~$468,000/year (26x ROI)
-
-Payback Period: < 2 weeks
-```
-
-**Chart Type:** Waterfall chart
-**Format:** Investment vs. Single-Year Returns
-
----
-
-## 14. Key Metrics Dashboard
-
-### One-Page Dashboard for Tracking
-```
-╔════════════════════════════════════════════════════════════╗
-║           n8n-MCP Error & Performance Dashboard            ║
-║                    Last 24 Hours                           ║
-╠════════════════════════════════════════════════════════════╣
-║                                                            ║
-║  Total Errors Today:  142        ↓ 5% vs yesterday      ║
-║  Most Common Error:   ValidationError (45%)              ║
-║  Critical Failures:   get_node_info (8 cases)            ║
-║  Avg Session Time:    2m 34s      ↑ 15% (slower)       ║
-║                                                            ║
-║  ┌──────────────────────────────────────────────────┐    ║
-║  │ Tool Success Rates (Top 5 Issues)                │    ║
-║  ├──────────────────────────────────────────────────┤    ║
-║  │ get_node_info               ███░░ 88.28%        │    ║
-║  │ validate_node_operation     █████░ 93.58%       │    ║
-║  │ validate_workflow           █████░ 94.50%       │    ║
-║  │ get_node_documentation      █████░ 95.87%       │    ║
-║  │ get_node_essentials         █████░ 96.19%       │    ║
-║  └──────────────────────────────────────────────────┘    ║
-║                                                            ║
-║  ┌──────────────────────────────────────────────────┐    ║
-║  │ Error Trend (Last 7 Days)                        │    ║
-║  │                                                  │    ║
-║  │  350 │      ╱╲                                  │    ║
-║  │  300 │  ╱╲ ╱  ╲                                │    ║
-║  │  250 │ ╱  ╲╱    ╲╱╲                          │    ║
-║  │  200 │                ╲╱╲                     │    ║
-║  │  150 │                    ╲╱─╲              │    ║
-║  │  100 │                         ─            │    ║
-║  │    0 └─────────────────────────────────────┘   │    ║
-║  └──────────────────────────────────────────────────┘    ║
-║                                                            ║
-║  Action Items: Fix get_node_info | Improve error msgs   ║
-║                                                            ║
-╚════════════════════════════════════════════════════════════╝
-```
-
-**Format:** ASCII art for reports; convert to Grafana/Datadog for live dashboard
-
----
-
-## 15. Before/After Comparison
-
-### Visual Representation of Improvements
-```
-Metric                      │ Before | After  | Improvement
-────────────────────────────┼────────┼────────┼─────────────
-get_node_info failure rate  │ 11.72% │ <1%    │ 91% ↓
-Workflow validation clarity │ 20%    │ 95%    │ 475% ↑
-Update operation latency    │ 55.2s  │ <5s    │ 91% ↓
-Search retry rate           │ 17%    │ <5%    │ 70% ↓
-Type error frequency        │ 2,767  │ 2,000  │ 28% ↓
-Daily error count           │ 65     │ 15     │ 77% ↓
-User satisfaction (est.)    │ 6/10   │ 9/10   │ 50% ↑
-Workflow creation time      │ 18min  │ 2min   │ 89% ↓
-```
-
-**Chart Type:** Comparison table with ↑/↓ indicators
-**Color coding:** Green for improvements, Red for current state
-
----
-
-## Chart Recommendations by Audience
-
-### For Executive Leadership
-1. Error Distribution Pie Chart
-2. Cost-Benefit Analysis Waterfall
-3. Implementation Timeline with Impact
-4. KPI Dashboard
-
-### For Product Team
-1. Tool Success Rates Bar Chart
-2. Error Type Breakdown
-3. User Search Patterns
-4. Session Metrics Timeline
-
-### For Engineering
-1. Tool Reliability Scatter Plot
-2. Sequential Operation Performance
-3. Error Rate with Annotations
-4. Before/After Metrics Table
-
-### For Customer Support
-1. Error Trend Line Chart
-2. Common Validation Issues
-3. Top Search Queries
-4. Troubleshooting Reference
-
----
-
-## SQL Queries for Data Export
-
-All visualizations above can be generated from these queries:
-
-```sql
--- Error distribution
-SELECT error_type, SUM(error_count) FROM telemetry_errors_daily
-WHERE date >= CURRENT_DATE - INTERVAL '90 days'
-GROUP BY error_type ORDER BY SUM(error_count) DESC;
-
--- Tool success rates
-SELECT tool_name,
-  ROUND(100.0 * SUM(success_count) / SUM(usage_count), 2) as success_rate,
-  SUM(failure_count) as failures,
-  SUM(usage_count) as invocations
-FROM telemetry_tool_usage_daily
-WHERE date >= CURRENT_DATE - INTERVAL '90 days'
-GROUP BY tool_name ORDER BY success_rate ASC;
-
--- Daily trends
-SELECT date, SUM(error_count) as daily_errors
-FROM telemetry_errors_daily
-WHERE date >= CURRENT_DATE - INTERVAL '90 days'
-GROUP BY date ORDER BY date DESC;
-
--- Top searches
-SELECT query_text, SUM(search_count) as count
-FROM telemetry_search_queries_daily
-WHERE date >= CURRENT_DATE - INTERVAL '90 days'
-GROUP BY query_text ORDER BY count DESC LIMIT 20;
-```
-
----
-
-**Created for:** Presentations, Reports, Dashboards
-**Format:** Markdown with ASCII, easily convertible to:
-- Excel/Google Sheets
-- PowerBI/Tableau
-- Grafana/Datadog
-- Presentation slides
-
----
-
-**Last Updated:** November 8, 2025
-**Data Freshness:** Live (updated daily)
-**Review Frequency:** Weekly

TELEMETRY_EXECUTIVE_SUMMARY.md

@@ -1,345 +0,0 @@
-# n8n-MCP Telemetry Analysis - Executive Summary
-## Quick Reference for Decision Makers
-
-**Analysis Date:** November 8, 2025
-**Data Period:** August 10 - November 8, 2025 (90 days)
-**Status:** Critical Issues Identified - Action Required
-
----
-
-## Key Statistics at a Glance
-
-| Metric | Value | Status |
-|--------|-------|--------|
-| Total Errors (90 days) | 8,859 | 96% are validation-related |
-| Daily Average | 60.68 | Baseline (60-65 errors/day normal) |
-| Peak Error Day | Oct 30 | 276 errors (4.5x baseline) |
-| Days with Errors | 36/90 (40%) | Intermittent spikes |
-| Most Common Error | ValidationError | 34.77% of all errors |
-| Critical Tool Failure | get_node_info | 11.72% failure rate |
-| Performance Bottleneck | Sequential updates | 55.2 seconds per operation |
-| Active Users/Day | 572 | Healthy engagement |
-| Total Users (90 days) | ~5,000+ | Growing user base |
-
----
-
-## The 5 Critical Issues
-
-### 1. Workflow-Level Validation Failures (39% of errors)
-
-**Problem:** 21,423 errors from unspecified workflow structure violations
-
-**What Users See:**
-- "Validation failed" (no indication of what's wrong)
-- Cannot deploy workflows
-- Must guess what structure requirement violated
-
-**Impact:** Users abandon workflows; AI agents retry blindly
-
-**Fix:** Provide specific error messages explaining exactly what failed
-- "Missing start trigger node"
-- "Type mismatch in node connection"
-- "Required property missing: URL"
-
-**Effort:** 2 days | **Impact:** High | **Priority:** 1
-
----
-
-### 2. `get_node_info` Unreliability (11.72% failure rate)
-
-**Problem:** 1,208 failures out of 10,304 calls to retrieve node information
-
-**What Users See:**
-- Cannot load node specifications when building workflows
-- Missing information about node properties
-- Forced to use incomplete data (fallback to essentials)
-
-**Impact:** Workflows built with wrong configuration assumptions; validation failures cascade
-
-**Fix:** Add retry logic, caching, and fallback mechanism
-
-**Effort:** 1 day | **Impact:** High | **Priority:** 1
-
----
-
-### 3. Slow Sequential Updates (55+ seconds per operation)
-
-**Problem:** 96,003 sequential workflow updates take average 55.2 seconds each
-
-**What Users See:**
-- Workflow construction takes minutes instead of seconds
-- "System appears stuck" (agent waiting 55s between operations)
-- Poor user experience
-
-**Impact:** Users abandon complex workflows; slow AI agent response
-
-**Fix:** Implement batch update operation (apply multiple changes in 1 call)
-
-**Effort:** 2-3 days | **Impact:** Critical | **Priority:** 1
-
----
-
-### 4. Search Inefficiency (17% retry rate)
-
-**Problem:** 68,056 sequential search calls; users need multiple searches to find nodes
-
-**What Users See:**
-- Search for "http" doesn't show "HTTP Request" in top results
-- Users refine search 2-3 times
-- Extra API calls and latency
-
-**Impact:** Slower node discovery; AI agents waste API calls
-
-**Fix:** Improve search ranking for high-volume queries
-
-**Effort:** 2 days | **Impact:** Medium | **Priority:** 2
-
----
-
-### 5. Type-Related Validation Errors (31.23% of errors)
-
-**Problem:** 2,767 TypeError occurrences from configuration mismatches
-
-**What Users See:**
-- Node validation fails due to type mismatch
-- "string vs. number" errors without clear resolution
-- Configuration seems correct but validation fails
-
-**Impact:** Users unsure of correct configuration format
-
-**Fix:** Implement strict type system; add TypeScript types for common nodes
-
-**Effort:** 3 days | **Impact:** Medium | **Priority:** 2
-
----
-
-## Business Impact Summary
-
-### Current State: What's Broken?
-
-| Area | Problem | Impact |
-|------|---------|--------|
-| **Reliability** | `get_node_info` fails 11.72% | Users blocked 1 in 8 times |
-| **Feedback** | Generic error messages | Users can't self-fix errors |
-| **Performance** | 55s per sequential update | 5-node workflow takes 4+ minutes |
-| **Search** | 17% require refine search | Extra latency; poor UX |
-| **Types** | 31% of errors type-related | Users make wrong assumptions |
-
-### If No Action Taken
-
-- Error volume likely to remain at 60+ per day
-- User frustration compounds
-- AI agents become unreliable (cascading failures)
-- Adoption plateau or decline
-- Support burden increases
-
-### With Phase 1 Fixes (Week 1)
-
-- `get_node_info` reliability: 11.72% → <1% (91% improvement)
-- Validation errors: 21,423 → <1,000 (95% improvement in clarity)
-- Sequential updates: 55.2s → <5s (91% improvement)
-- **Overall error reduction: 40-50%**
-- **User satisfaction: +60%** (estimated)
-
-### Full Implementation (4-5 weeks)
-
-- **Error volume: 8,859 → <2,000 per quarter** (77% reduction)
-- **Tool failure rates: <1% across board**
-- **Performance: 90% improvement in workflow creation**
-- **User retention: +35%** (estimated)
-
----
-
-## Implementation Roadmap
-
-### Week 1 (Immediate Wins)
-1. Fix `get_node_info` reliability [1 day]
-2. Improve validation error messages [2 days]
-3. Add batch update operation [2 days]
-
-**Impact:** Address 60% of user-facing issues
-
-### Week 2-3 (High Priority)
-4. Implement validation caching [1-2 days]
-5. Improve search ranking [2 days]
-6. Add TypeScript types [3 days]
-
-**Impact:** Performance +70%; Errors -30%
-
-### Week 4 (Optimization)
-7. Return updated state in responses [1-2 days]
-8. Add workflow diff generation [1-2 days]
-
-**Impact:** Eliminate 40% of API calls
-
-### Ongoing (Documentation)
-9. Create error code documentation [1 week]
-10. Add configuration examples [2 weeks]
-
----
-
-## Resource Requirements
-
-| Phase | Duration | Team | Impact | Business Value |
-|-------|----------|------|--------|-----------------|
-| Phase 1 | 1 week | 1 engineer | 60% of issues | High ROI |
-| Phase 2 | 2 weeks | 1 engineer | +30% improvement | Medium ROI |
-| Phase 3 | 1 week | 1 engineer | +10% improvement | Low ROI |
-| Phase 4 | 3 weeks | 0.5 engineer | Support reduction | Medium ROI |
-
-**Total:** 7 weeks, 1 engineer FTE, +35% overall improvement
-
----
-
-## Risk Assessment
-
-| Risk | Likelihood | Impact | Mitigation |
-|------|------------|--------|-----------|
-| Breaking API changes | Low | High | Maintain backward compatibility |
-| Performance regression | Low | High | Load test before deployment |
-| Validation false positives | Medium | Medium | Beta test with sample workflows |
-| Incomplete implementation | Low | Medium | Clear definition of done per task |
-
-**Overall Risk Level:** Low (with proper mitigation)
-
----
-
-## Success Metrics (Measurable)
-
-### By End of Week 1
-- [ ] `get_node_info` failure rate < 2%
-- [ ] Validation errors provide specific guidance
-- [ ] Batch update operation deployed and tested
-
-### By End of Week 3
-- [ ] Overall error rate < 3,000/quarter
-- [ ] Tool success rates > 98% across board
-- [ ] Average workflow creation time < 2 minutes
-
-### By End of Week 5
-- [ ] Error volume < 2,000/quarter (77% reduction)
-- [ ] All users can self-resolve 80% of common errors
-- [ ] AI agent success rate improves by 30%
-
----
-
-## Top Recommendations
-
-### Do This First (Week 1)
-
-1. **Fix `get_node_info`** - Affects most critical user action
-   - Add retry logic [4 hours]
-   - Implement cache [4 hours]
-   - Add fallback [4 hours]
-
-2. **Improve Validation Messages** - Addresses 39% of errors
-   - Create error code system [8 hours]
-   - Enhance validation logic [8 hours]
-   - Add help documentation [4 hours]
-
-3. **Add Batch Updates** - Fixes performance bottleneck
-   - Define API [4 hours]
-   - Implement handler [12 hours]
-   - Test & integrate [4 hours]
-
-### Avoid This (Anti-patterns)
-
-- ❌ Increasing error logging without actionable feedback
-- ❌ Adding more validation without improving error messages
-- ❌ Optimizing non-critical operations while critical issues remain
-- ❌ Waiting for perfect data before implementing fixes
-
----
-
-## Stakeholder Questions & Answers
-
-**Q: Why are there so many validation errors if most tools work (96%+)?**
-
-A: Validation happens in a separate system. Core tools are reliable, but validation feedback is poor. Users create invalid workflows, validation rejects them generically, and users can't understand why.
-
-**Q: Is the system unstable?**
-
-A: No. Infrastructure is stable (99% uptime estimated). The issue is usability: errors are generic and operations are slow.
-
-**Q: Should we defer fixes until next quarter?**
-
-A: No. Every day of 60+ daily errors compounds user frustration. Early fixes have highest ROI (1 week = 40-50% improvement).
-
-**Q: What about the Oct 30 spike (276 errors)?**
-
-A: Likely specific trigger (batch test, migration). Current baseline is 60-65 errors/day, which is sustainable but improvable.
-
-**Q: Which issue is most urgent?**
-
-A: `get_node_info` reliability. It's the foundation for everything else. Without it, users can't build workflows correctly.
-
----
-
-## Next Steps
-
-1. **This Week**
-   - [ ] Review this analysis with engineering team
-   - [ ] Estimate resource allocation
-   - [ ] Prioritize Phase 1 tasks
-
-2. **Next Week**
-   - [ ] Start Phase 1 implementation
-   - [ ] Set up monitoring for improvements
-   - [ ] Begin user communication about fixes
-
-3. **Week 3**
-   - [ ] Deploy Phase 1 fixes
-   - [ ] Measure improvements
-   - [ ] Start Phase 2
-
----
-
-## Questions?
-
-**For detailed analysis:** See TELEMETRY_ANALYSIS_REPORT.md
-**For technical details:** See TELEMETRY_TECHNICAL_DEEP_DIVE.md
-**For implementation:** See IMPLEMENTATION_ROADMAP.md
-
----
-
-**Analysis by:** AI Telemetry Analyst
-**Confidence Level:** High (506K+ events analyzed)
-**Last Updated:** November 8, 2025
-**Review Frequency:** Weekly recommended
-**Next Review Date:** November 15, 2025
-
----
-
-## Appendix: Key Data Points
-
-### Error Distribution
-- ValidationError: 3,080 (34.77%)
-- TypeError: 2,767 (31.23%)
-- Generic Error: 2,711 (30.60%)
-- SqliteError: 202 (2.28%)
-- Other: 99 (1.12%)
-
-### Tool Reliability (Top Issues)
-- `get_node_info`: 88.28% success (11.72% failure)
-- `validate_node_operation`: 93.58% success (6.42% failure)
-- `get_node_documentation`: 95.87% success (4.13% failure)
-- All others: 96-100% success
-
-### User Engagement
-- Daily sessions: 895 (avg)
-- Daily users: 572 (avg)
-- Sessions/user: 1.52 (avg)
-- Peak day: 1,821 sessions (Oct 22)
-
-### Most Searched Topics
-1. Testing (5,852 searches)
-2. Webhooks (5,087)
-3. HTTP (4,241)
-4. Database (4,030)
-5. API integration (2,074)
-
-### Performance Bottlenecks
-- Update loop: 55.2s avg (66% slow)
-- Read-after-write: 96.6s avg (63% slow)
-- Search refinement: 17% need 2+ queries
-- Session creation: ~5-10 seconds

TELEMETRY_MUTATION_SPEC.md

@@ -1,918 +0,0 @@
-# Telemetry Workflow Mutation Tracking Specification
-
-**Purpose:** Define the technical requirements for capturing workflow mutation data to build the n8n-fixer dataset
-
-**Status:** Specification Document (Pre-Implementation)
-
----
-
-## 1. Overview
-
-This specification details how to extend the n8n-mcp telemetry system to capture:
-- **Before State:** Complete workflow JSON before modification
-- **Instruction:** The transformation instruction/prompt
-- **After State:** Complete workflow JSON after modification
-- **Metadata:** Timestamps, user ID, success metrics, validation states
-
----
-
-## 2. Schema Design
-
-### 2.1 New Database Table: `workflow_mutations`
-
-```sql
-CREATE TABLE IF NOT EXISTS workflow_mutations (
-  -- Primary Key & Identifiers
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  user_id TEXT NOT NULL,
-  workflow_id TEXT,                      -- n8n workflow ID (nullable for new workflows)
-
-  -- Source Workflow Snapshot (Before)
-  before_workflow_json JSONB NOT NULL,   -- Complete workflow definition
-  before_workflow_hash TEXT NOT NULL,    -- SHA-256(before_workflow_json)
-  before_validation_status TEXT NOT NULL CHECK(before_validation_status IN (
-    'valid',           -- Workflow passes validation
-    'invalid',         -- Has validation errors
-    'unknown'          -- Unknown state (not tested)
-  )),
-  before_error_count INTEGER,            -- Number of validation errors
-  before_error_types TEXT[],             -- Array: ['type_error', 'missing_field', ...]
-
-  -- Mutation Details
-  instruction TEXT NOT NULL,             -- The modification instruction/prompt
-  instruction_type TEXT NOT NULL CHECK(instruction_type IN (
-    'ai_generated',    -- Generated by AI/LLM
-    'user_provided',   -- User input/request
-    'auto_fix',        -- System auto-correction
-    'validation_correction'  -- Validation rule fix
-  )),
-  mutation_source TEXT,                  -- Which tool/service created the mutation
-                                         -- e.g., 'n8n_autofix_workflow', 'validation_engine'
-  mutation_tool_version TEXT,            -- Version of tool that performed mutation
-
-  -- Target Workflow Snapshot (After)
-  after_workflow_json JSONB NOT NULL,    -- Complete modified workflow
-  after_workflow_hash TEXT NOT NULL,     -- SHA-256(after_workflow_json)
-  after_validation_status TEXT NOT NULL CHECK(after_validation_status IN (
-    'valid',
-    'invalid',
-    'unknown'
-  )),
-  after_error_count INTEGER,             -- Validation errors after mutation
-  after_error_types TEXT[],              -- Remaining error types
-
-  -- Mutation Analysis (Pre-calculated for Performance)
-  nodes_modified TEXT[],                 -- Array of modified node IDs/names
-  nodes_added TEXT[],                    -- New nodes in after state
-  nodes_removed TEXT[],                  -- Removed nodes
-  nodes_modified_count INTEGER,          -- Count of modified nodes
-  nodes_added_count INTEGER,
-  nodes_removed_count INTEGER,
-
-  connections_modified BOOLEAN,          -- Were connections/edges changed?
-  connections_before_count INTEGER,      -- Number of connections before
-  connections_after_count INTEGER,       -- Number after
-
-  properties_modified TEXT[],            -- Changed property paths
-                                         -- e.g., ['nodes[0].parameters.url', ...]
-  properties_modified_count INTEGER,
-  expressions_modified BOOLEAN,          -- Were expressions/formulas changed?
-
-  -- Complexity Metrics
-  complexity_before TEXT CHECK(complexity_before IN (
-    'simple',
-    'medium',
-    'complex'
-  )),
-  complexity_after TEXT,
-  node_count_before INTEGER,
-  node_count_after INTEGER,
-  node_types_before TEXT[],
-  node_types_after TEXT[],
-
-  -- Outcome Metrics
-  mutation_success BOOLEAN,              -- Did mutation achieve intended goal?
-  validation_improved BOOLEAN,           -- true if: error_count_after < error_count_before
-  validation_errors_fixed INTEGER,       -- Count of errors fixed
-  new_errors_introduced INTEGER,         -- Errors created by mutation
-
-  -- Optional: User Feedback
-  user_approved BOOLEAN,                 -- User accepted the mutation?
-  user_feedback TEXT,                    -- User comment (truncated)
-
-  -- Data Quality & Compression
-  workflow_size_before INTEGER,          -- Byte size of before_workflow_json
-  workflow_size_after INTEGER,           -- Byte size of after_workflow_json
-  is_compressed BOOLEAN DEFAULT false,   -- True if workflows are gzip-compressed
-
-  -- Timing
-  execution_duration_ms INTEGER,         -- Time taken to apply mutation
-  created_at TIMESTAMP DEFAULT NOW(),
-
-  -- Metadata
-  tags TEXT[],                           -- Custom tags for filtering
-  metadata JSONB                         -- Flexible metadata storage
-);
-```
-
-### 2.2 Indexes for Performance
-
-```sql
--- User Analysis (User's mutation history)
-CREATE INDEX idx_mutations_user_id
-  ON workflow_mutations(user_id, created_at DESC);
-
--- Workflow Analysis (Mutations to specific workflow)
-CREATE INDEX idx_mutations_workflow_id
-  ON workflow_mutations(workflow_id, created_at DESC);
-
--- Mutation Success Rate
-CREATE INDEX idx_mutations_success
-  ON workflow_mutations(mutation_success, created_at DESC);
-
--- Validation Improvement Analysis
-CREATE INDEX idx_mutations_validation_improved
-  ON workflow_mutations(validation_improved, created_at DESC);
-
--- Time-series Analysis
-CREATE INDEX idx_mutations_created_at
-  ON workflow_mutations(created_at DESC);
-
--- Source Analysis
-CREATE INDEX idx_mutations_source
-  ON workflow_mutations(mutation_source, created_at DESC);
-
--- Instruction Type Analysis
-CREATE INDEX idx_mutations_instruction_type
-  ON workflow_mutations(instruction_type, created_at DESC);
-
--- Composite: For common query patterns
-CREATE INDEX idx_mutations_user_success_time
-  ON workflow_mutations(user_id, mutation_success, created_at DESC);
-
-CREATE INDEX idx_mutations_source_validation
-  ON workflow_mutations(mutation_source, validation_improved, created_at DESC);
-```
-
-### 2.3 Optional: Materialized View for Analytics
-
-```sql
--- Pre-calculate common metrics for fast dashboarding
-CREATE MATERIALIZED VIEW vw_mutation_analytics AS
-SELECT
-  DATE(created_at) as mutation_date,
-  instruction_type,
-  mutation_source,
-
-  COUNT(*) as total_mutations,
-  SUM(CASE WHEN mutation_success THEN 1 ELSE 0 END) as successful_mutations,
-  SUM(CASE WHEN validation_improved THEN 1 ELSE 0 END) as validation_improved_count,
-
-  ROUND(100.0 * COUNT(*) FILTER(WHERE mutation_success = true)
-        / NULLIF(COUNT(*), 0), 2) as success_rate,
-
-  AVG(nodes_modified_count) as avg_nodes_modified,
-  AVG(properties_modified_count) as avg_properties_modified,
-  AVG(execution_duration_ms) as avg_duration_ms,
-
-  AVG(before_error_count) as avg_errors_before,
-  AVG(after_error_count) as avg_errors_after,
-  AVG(validation_errors_fixed) as avg_errors_fixed
-
-FROM workflow_mutations
-GROUP BY DATE(created_at), instruction_type, mutation_source;
-
-CREATE INDEX idx_mutation_analytics_date
-  ON vw_mutation_analytics(mutation_date DESC);
-```
-
----
-
-## 3. TypeScript Interfaces
-
-### 3.1 Core Mutation Interface
-
-```typescript
-// In src/telemetry/telemetry-types.ts
-
-export interface WorkflowMutationEvent extends TelemetryEvent {
-  event: 'workflow_mutation';
-  properties: {
-    // Identification
-    workflowId?: string;
-
-    // Hashes for deduplication & integrity
-    beforeHash: string;        // SHA-256 of before state
-    afterHash: string;         // SHA-256 of after state
-
-    // Instruction
-    instruction: string;       // The modification prompt/request
-    instructionType: 'ai_generated' | 'user_provided' | 'auto_fix' | 'validation_correction';
-    mutationSource?: string;   // Tool that created the instruction
-
-    // Change Summary
-    nodesModified: number;
-    propertiesChanged: number;
-    connectionsModified: boolean;
-    expressionsModified: boolean;
-
-    // Outcome
-    mutationSuccess: boolean;
-    validationImproved: boolean;
-    errorsBefore: number;
-    errorsAfter: number;
-
-    // Performance
-    executionDurationMs?: number;
-    workflowSizeBefore?: number;
-    workflowSizeAfter?: number;
-  }
-}
-
-export interface WorkflowMutation {
-  // Primary Key
-  id: string;                  // UUID
-  user_id: string;             // Anonymized user
-  workflow_id?: string;        // n8n workflow ID
-
-  // Before State
-  before_workflow_json: any;   // Complete workflow
-  before_workflow_hash: string;
-  before_validation_status: 'valid' | 'invalid' | 'unknown';
-  before_error_count?: number;
-  before_error_types?: string[];
-
-  // Mutation
-  instruction: string;
-  instruction_type: 'ai_generated' | 'user_provided' | 'auto_fix' | 'validation_correction';
-  mutation_source?: string;
-  mutation_tool_version?: string;
-
-  // After State
-  after_workflow_json: any;
-  after_workflow_hash: string;
-  after_validation_status: 'valid' | 'invalid' | 'unknown';
-  after_error_count?: number;
-  after_error_types?: string[];
-
-  // Analysis
-  nodes_modified?: string[];
-  nodes_added?: string[];
-  nodes_removed?: string[];
-  nodes_modified_count?: number;
-  connections_modified?: boolean;
-  properties_modified?: string[];
-  properties_modified_count?: number;
-
-  // Complexity
-  complexity_before?: 'simple' | 'medium' | 'complex';
-  complexity_after?: 'simple' | 'medium' | 'complex';
-  node_count_before?: number;
-  node_count_after?: number;
-
-  // Outcome
-  mutation_success: boolean;
-  validation_improved: boolean;
-  validation_errors_fixed?: number;
-  new_errors_introduced?: number;
-  user_approved?: boolean;
-
-  // Timing
-  created_at: string;          // ISO 8601
-  execution_duration_ms?: number;
-}
-```
-
-### 3.2 Mutation Analysis Service
-
-```typescript
-// New file: src/telemetry/mutation-analyzer.ts
-
-export interface MutationDiff {
-  nodesAdded: string[];
-  nodesRemoved: string[];
-  nodesModified: Map<string, PropertyDiff[]>;
-  connectionsChanged: boolean;
-  expressionsChanged: boolean;
-}
-
-export interface PropertyDiff {
-  path: string;                // e.g., "parameters.url"
-  beforeValue: any;
-  afterValue: any;
-  isExpression: boolean;       // Contains {{}} or $json?
-}
-
-export class WorkflowMutationAnalyzer {
-  /**
-   * Analyze differences between before/after workflows
-   */
-  static analyzeDifferences(
-    beforeWorkflow: any,
-    afterWorkflow: any
-  ): MutationDiff {
-    // Implementation: Deep comparison of workflow structures
-    // Return detailed diff information
-  }
-
-  /**
-   * Extract changed property paths
-   */
-  static getChangedProperties(diff: MutationDiff): string[] {
-    // Implementation
-  }
-
-  /**
-   * Determine if expression/formula was modified
-   */
-  static hasExpressionChanges(diff: MutationDiff): boolean {
-    // Implementation
-  }
-
-  /**
-   * Validate workflow structure
-   */
-  static validateWorkflowStructure(workflow: any): {
-    isValid: boolean;
-    errors: string[];
-    errorTypes: string[];
-  } {
-    // Implementation
-  }
-}
-```
-
----
-
-## 4. Integration Points
-
-### 4.1 TelemetryManager Extension
-
-```typescript
-// In src/telemetry/telemetry-manager.ts
-
-export class TelemetryManager {
-  // ... existing code ...
-
-  /**
-   * Track workflow mutation (new method)
-   */
-  async trackWorkflowMutation(
-    beforeWorkflow: any,
-    instruction: string,
-    afterWorkflow: any,
-    options?: {
-      instructionType?: 'ai_generated' | 'user_provided' | 'auto_fix';
-      mutationSource?: string;
-      workflowId?: string;
-      success?: boolean;
-      executionDurationMs?: number;
-      userApproved?: boolean;
-    }
-  ): Promise<void> {
-    this.ensureInitialized();
-    this.performanceMonitor.startOperation('trackWorkflowMutation');
-
-    try {
-      await this.eventTracker.trackWorkflowMutation(
-        beforeWorkflow,
-        instruction,
-        afterWorkflow,
-        options
-      );
-      // Auto-flush mutations to prevent data loss
-      await this.flush();
-    } catch (error) {
-      const telemetryError = error instanceof TelemetryError
-        ? error
-        : new TelemetryError(
-            TelemetryErrorType.UNKNOWN_ERROR,
-            'Failed to track workflow mutation',
-            { error: String(error) }
-          );
-      this.errorAggregator.record(telemetryError);
-    } finally {
-      this.performanceMonitor.endOperation('trackWorkflowMutation');
-    }
-  }
-}
-```
-
-### 4.2 EventTracker Extension
-
-```typescript
-// In src/telemetry/event-tracker.ts
-
-export class TelemetryEventTracker {
-  // ... existing code ...
-
-  private mutationQueue: WorkflowMutation[] = [];
-  private mutationAnalyzer = new WorkflowMutationAnalyzer();
-
-  /**
-   * Track a workflow mutation
-   */
-  async trackWorkflowMutation(
-    beforeWorkflow: any,
-    instruction: string,
-    afterWorkflow: any,
-    options?: MutationTrackingOptions
-  ): Promise<void> {
-    if (!this.isEnabled()) return;
-
-    try {
-      // 1. Analyze differences
-      const diff = this.mutationAnalyzer.analyzeDifferences(
-        beforeWorkflow,
-        afterWorkflow
-      );
-
-      // 2. Calculate hashes
-      const beforeHash = this.calculateHash(beforeWorkflow);
-      const afterHash = this.calculateHash(afterWorkflow);
-
-      // 3. Detect validation changes
-      const beforeValidation = this.mutationAnalyzer.validateWorkflowStructure(
-        beforeWorkflow
-      );
-      const afterValidation = this.mutationAnalyzer.validateWorkflowStructure(
-        afterWorkflow
-      );
-
-      // 4. Create mutation record
-      const mutation: WorkflowMutation = {
-        id: generateUUID(),
-        user_id: this.getUserId(),
-        workflow_id: options?.workflowId,
-
-        before_workflow_json: beforeWorkflow,
-        before_workflow_hash: beforeHash,
-        before_validation_status: beforeValidation.isValid ? 'valid' : 'invalid',
-        before_error_count: beforeValidation.errors.length,
-        before_error_types: beforeValidation.errorTypes,
-
-        instruction,
-        instruction_type: options?.instructionType || 'user_provided',
-        mutation_source: options?.mutationSource,
-
-        after_workflow_json: afterWorkflow,
-        after_workflow_hash: afterHash,
-        after_validation_status: afterValidation.isValid ? 'valid' : 'invalid',
-        after_error_count: afterValidation.errors.length,
-        after_error_types: afterValidation.errorTypes,
-
-        nodes_modified: Array.from(diff.nodesModified.keys()),
-        nodes_added: diff.nodesAdded,
-        nodes_removed: diff.nodesRemoved,
-        properties_modified: this.mutationAnalyzer.getChangedProperties(diff),
-        connections_modified: diff.connectionsChanged,
-
-        mutation_success: options?.success !== false,
-        validation_improved: afterValidation.errors.length
-                           < beforeValidation.errors.length,
-        validation_errors_fixed: Math.max(
-          0,
-          beforeValidation.errors.length - afterValidation.errors.length
-        ),
-
-        created_at: new Date().toISOString(),
-        execution_duration_ms: options?.executionDurationMs,
-        user_approved: options?.userApproved
-      };
-
-      // 5. Validate and queue
-      const validated = this.validator.validateMutation(mutation);
-      if (validated) {
-        this.mutationQueue.push(validated);
-      }
-
-      // 6. Track as event for real-time monitoring
-      this.trackEvent('workflow_mutation', {
-        beforeHash,
-        afterHash,
-        instructionType: options?.instructionType || 'user_provided',
-        nodesModified: diff.nodesModified.size,
-        propertiesChanged: diff.properties_modified?.length || 0,
-        mutationSuccess: options?.success !== false,
-        validationImproved: mutation.validation_improved,
-        errorsBefore: beforeValidation.errors.length,
-        errorsAfter: afterValidation.errors.length
-      });
-
-    } catch (error) {
-      logger.debug('Failed to track workflow mutation:', error);
-      throw new TelemetryError(
-        TelemetryErrorType.VALIDATION_ERROR,
-        'Failed to process workflow mutation',
-        { error: error instanceof Error ? error.message : String(error) }
-      );
-    }
-  }
-
-  /**
-   * Get queued mutations
-   */
-  getMutationQueue(): WorkflowMutation[] {
-    return [...this.mutationQueue];
-  }
-
-  /**
-   * Clear mutation queue
-   */
-  clearMutationQueue(): void {
-    this.mutationQueue = [];
-  }
-
-  /**
-   * Calculate SHA-256 hash of workflow
-   */
-  private calculateHash(workflow: any): string {
-    const crypto = require('crypto');
-    const normalized = JSON.stringify(workflow, null, 0);
-    return crypto.createHash('sha256').update(normalized).digest('hex');
-  }
-}
-```
-
-### 4.3 BatchProcessor Extension
-
-```typescript
-// In src/telemetry/batch-processor.ts
-
-export class TelemetryBatchProcessor {
-  // ... existing code ...
-
-  /**
-   * Flush mutations to Supabase
-   */
-  private async flushMutations(
-    mutations: WorkflowMutation[]
-  ): Promise<boolean> {
-    if (this.isFlushingMutations || mutations.length === 0) return true;
-
-    this.isFlushingMutations = true;
-
-    try {
-      const batches = this.createBatches(
-        mutations,
-        TELEMETRY_CONFIG.MAX_BATCH_SIZE
-      );
-
-      for (const batch of batches) {
-        const result = await this.executeWithRetry(async () => {
-          const { error } = await this.supabase!
-            .from('workflow_mutations')
-            .insert(batch);
-
-          if (error) throw error;
-
-          logger.debug(`Flushed batch of ${batch.length} workflow mutations`);
-          return true;
-        }, 'Flush workflow mutations');
-
-        if (!result) {
-          this.addToDeadLetterQueue(batch);
-          return false;
-        }
-      }
-
-      return true;
-    } catch (error) {
-      logger.debug('Failed to flush mutations:', error);
-      throw new TelemetryError(
-        TelemetryErrorType.NETWORK_ERROR,
-        'Failed to flush mutations',
-        { error: error instanceof Error ? error.message : String(error) },
-        true
-      );
-    } finally {
-      this.isFlushingMutations = false;
-    }
-  }
-}
-```
-
----
-
-## 5. Integration with Workflow Tools
-
-### 5.1 n8n_autofix_workflow
-
-```typescript
-// Where n8n_autofix_workflow applies fixes
-import { telemetry } from '../telemetry';
-
-export async function n8n_autofix_workflow(
-  workflow: any,
-  options?: AutofixOptions
-): Promise<WorkflowFixResult> {
-
-  const beforeWorkflow = JSON.parse(JSON.stringify(workflow)); // Deep copy
-
-  try {
-    // Apply fixes
-    const fixed = await applyFixes(workflow, options);
-
-    // Track mutation
-    await telemetry.trackWorkflowMutation(
-      beforeWorkflow,
-      'Auto-fix validation errors',
-      fixed,
-      {
-        instructionType: 'auto_fix',
-        mutationSource: 'n8n_autofix_workflow',
-        success: true,
-        executionDurationMs: duration
-      }
-    );
-
-    return fixed;
-  } catch (error) {
-    // Track failed mutation attempt
-    await telemetry.trackWorkflowMutation(
-      beforeWorkflow,
-      'Auto-fix validation errors',
-      beforeWorkflow, // No changes
-      {
-        instructionType: 'auto_fix',
-        mutationSource: 'n8n_autofix_workflow',
-        success: false
-      }
-    );
-    throw error;
-  }
-}
-```
-
-### 5.2 n8n_update_partial_workflow
-
-```typescript
-// Partial workflow updates
-export async function n8n_update_partial_workflow(
-  workflow: any,
-  operations: DiffOperation[]
-): Promise<UpdateResult> {
-
-  const beforeWorkflow = JSON.parse(JSON.stringify(workflow));
-  const instructionText = formatOperationsAsInstruction(operations);
-
-  try {
-    const updated = applyOperations(workflow, operations);
-
-    await telemetry.trackWorkflowMutation(
-      beforeWorkflow,
-      instructionText,
-      updated,
-      {
-        instructionType: 'user_provided',
-        mutationSource: 'n8n_update_partial_workflow'
-      }
-    );
-
-    return updated;
-  } catch (error) {
-    await telemetry.trackWorkflowMutation(
-      beforeWorkflow,
-      instructionText,
-      beforeWorkflow,
-      {
-        instructionType: 'user_provided',
-        mutationSource: 'n8n_update_partial_workflow',
-        success: false
-      }
-    );
-    throw error;
-  }
-}
-```
-
----
-
-## 6. Data Quality & Validation
-
-### 6.1 Mutation Validation Rules
-
-```typescript
-// In src/telemetry/mutation-validator.ts
-
-export class WorkflowMutationValidator {
-  /**
-   * Validate mutation data before storage
-   */
-  static validate(mutation: WorkflowMutation): ValidationResult {
-    const errors: string[] = [];
-
-    // Required fields
-    if (!mutation.user_id) errors.push('user_id is required');
-    if (!mutation.before_workflow_json) errors.push('before_workflow_json required');
-    if (!mutation.after_workflow_json) errors.push('after_workflow_json required');
-    if (!mutation.before_workflow_hash) errors.push('before_workflow_hash required');
-    if (!mutation.after_workflow_hash) errors.push('after_workflow_hash required');
-    if (!mutation.instruction) errors.push('instruction is required');
-    if (!mutation.instruction_type) errors.push('instruction_type is required');
-
-    // Hash verification
-    const beforeHash = calculateHash(mutation.before_workflow_json);
-    const afterHash = calculateHash(mutation.after_workflow_json);
-
-    if (beforeHash !== mutation.before_workflow_hash) {
-      errors.push('before_workflow_hash mismatch');
-    }
-    if (afterHash !== mutation.after_workflow_hash) {
-      errors.push('after_workflow_hash mismatch');
-    }
-
-    // Deduplication: Skip if before == after
-    if (beforeHash === afterHash) {
-      errors.push('before and after states are identical (skipping)');
-    }
-
-    // Size validation
-    const beforeSize = JSON.stringify(mutation.before_workflow_json).length;
-    const afterSize = JSON.stringify(mutation.after_workflow_json).length;
-
-    if (beforeSize > 10 * 1024 * 1024) {
-      errors.push('before_workflow_json exceeds 10MB size limit');
-    }
-    if (afterSize > 10 * 1024 * 1024) {
-      errors.push('after_workflow_json exceeds 10MB size limit');
-    }
-
-    // Instruction validation
-    if (mutation.instruction.length > 5000) {
-      mutation.instruction = mutation.instruction.substring(0, 5000);
-    }
-    if (mutation.instruction.length < 3) {
-      errors.push('instruction too short (min 3 chars)');
-    }
-
-    // Error count validation
-    if (mutation.before_error_count && mutation.before_error_count < 0) {
-      errors.push('before_error_count cannot be negative');
-    }
-    if (mutation.after_error_count && mutation.after_error_count < 0) {
-      errors.push('after_error_count cannot be negative');
-    }
-
-    return {
-      isValid: errors.length === 0,
-      errors
-    };
-  }
-}
-```
-
-### 6.2 Data Compression Strategy
-
-For large workflows (>1MB):
-
-```typescript
-import { gzipSync, gunzipSync } from 'zlib';
-
-export function compressWorkflow(workflow: any): {
-  compressed: string;  // base64
-  originalSize: number;
-  compressedSize: number;
-} {
-  const json = JSON.stringify(workflow);
-  const buffer = Buffer.from(json, 'utf-8');
-  const compressed = gzipSync(buffer);
-  const base64 = compressed.toString('base64');
-
-  return {
-    compressed: base64,
-    originalSize: buffer.length,
-    compressedSize: compressed.length
-  };
-}
-
-export function decompressWorkflow(compressed: string): any {
-  const buffer = Buffer.from(compressed, 'base64');
-  const decompressed = gunzipSync(buffer);
-  const json = decompressed.toString('utf-8');
-  return JSON.parse(json);
-}
-```
-
----
-
-## 7. Query Examples for Analysis
-
-### 7.1 Basic Mutation Statistics
-
-```sql
--- Overall mutation metrics
-SELECT
-  COUNT(*) as total_mutations,
-  COUNT(*) FILTER(WHERE mutation_success) as successful,
-  COUNT(*) FILTER(WHERE validation_improved) as validation_improved,
-  ROUND(100.0 * COUNT(*) FILTER(WHERE mutation_success) / COUNT(*), 2) as success_rate,
-  ROUND(100.0 * COUNT(*) FILTER(WHERE validation_improved) / COUNT(*), 2) as improvement_rate,
-  AVG(nodes_modified_count) as avg_nodes_modified,
-  AVG(properties_modified_count) as avg_properties_modified,
-  AVG(execution_duration_ms)::INTEGER as avg_duration_ms
-FROM workflow_mutations
-WHERE created_at >= NOW() - INTERVAL '7 days';
-```
-
-### 7.2 Success by Instruction Type
-
-```sql
-SELECT
-  instruction_type,
-  COUNT(*) as count,
-  ROUND(100.0 * COUNT(*) FILTER(WHERE mutation_success) / COUNT(*), 2) as success_rate,
-  ROUND(100.0 * COUNT(*) FILTER(WHERE validation_improved) / COUNT(*), 2) as improvement_rate,
-  AVG(validation_errors_fixed) as avg_errors_fixed,
-  AVG(new_errors_introduced) as avg_new_errors
-FROM workflow_mutations
-WHERE created_at >= NOW() - INTERVAL '30 days'
-GROUP BY instruction_type
-ORDER BY count DESC;
-```
-
-### 7.3 Most Common Mutations
-
-```sql
-SELECT
-  properties_modified,
-  COUNT(*) as frequency,
-  ROUND(100.0 * COUNT(*) / (SELECT COUNT(*) FROM workflow_mutations
-                              WHERE created_at >= NOW() - INTERVAL '30 days'), 2) as percentage
-FROM workflow_mutations
-WHERE created_at >= NOW() - INTERVAL '30 days'
-ORDER BY frequency DESC
-LIMIT 20;
-```
-
-### 7.4 Complexity Impact
-
-```sql
-SELECT
-  complexity_before,
-  complexity_after,
-  COUNT(*) as transitions,
-  ROUND(100.0 * COUNT(*) FILTER(WHERE mutation_success) / COUNT(*), 2) as success_rate
-FROM workflow_mutations
-WHERE created_at >= NOW() - INTERVAL '30 days'
-GROUP BY complexity_before, complexity_after
-ORDER BY transitions DESC;
-```
-
----
-
-## 8. Implementation Roadmap
-
-### Phase 1: Infrastructure (Week 1)
-- [ ] Create `workflow_mutations` table in Supabase
-- [ ] Add indexes for common query patterns
-- [ ] Update TypeScript types
-- [ ] Create mutation analyzer service
-- [ ] Add mutation validator
-
-### Phase 2: Integration (Week 2)
-- [ ] Extend TelemetryManager with trackWorkflowMutation()
-- [ ] Extend EventTracker with mutation queue
-- [ ] Extend BatchProcessor with flush logic
-- [ ] Add mutation event type
-
-### Phase 3: Tool Integration (Week 3)
-- [ ] Integrate with n8n_autofix_workflow
-- [ ] Integrate with n8n_update_partial_workflow
-- [ ] Add test cases
-- [ ] Documentation
-
-### Phase 4: Validation & Analysis (Week 4)
-- [ ] Run sample queries
-- [ ] Validate data quality
-- [ ] Create analytics dashboard
-- [ ] Begin dataset collection
-
----
-
-## 9. Security & Privacy Considerations
-
-- **No Credentials:** Sanitizer strips credentials before storage
-- **No Secrets:** Workflow secret references removed
-- **User Anonymity:** User ID is anonymized
-- **Hash Verification:** All workflow hashes verified before storage
-- **Size Limits:** 10MB max per workflow (with compression option)
-- **Retention:** Define data retention policy separately
-- **Encryption:** Enable Supabase encryption at rest
-- **Access Control:** Restrict table access to application-level only
-
----
-
-## 10. Performance Considerations
-
-| Aspect | Target | Strategy |
-|--------|--------|----------|
-| **Batch Flush** | <5s latency | 5-second flush interval + auto-flush |
-| **Large Workflows** | >1MB support | Gzip compression + base64 encoding |
-| **Query Performance** | <100ms | Strategic indexing + materialized views |
-| **Storage Growth** | <50GB/month | Compression + retention policies |
-| **Network Throughput** | <1MB/batch | Compress before transmission |
-
----
-
-*End of Specification*

TELEMETRY_N8N_FIXER_DATASET.md

@@ -1,450 +0,0 @@
-# N8N-Fixer Dataset: Telemetry Infrastructure Analysis
-
-**Analysis Completed:** November 12, 2025
-**Scope:** N8N-MCP Telemetry Database Schema & Workflow Mutation Tracking
-**Status:** Ready for Implementation Planning
-
----
-
-## Overview
-
-This document synthesizes a comprehensive analysis of the n8n-mcp telemetry infrastructure and provides actionable recommendations for building an n8n-fixer dataset with before/instruction/after workflow snapshots.
-
-**Key Findings:**
-- Telemetry system is production-ready with 276K+ events tracked
-- Supabase PostgreSQL backend stores all events
-- Current system **does NOT capture workflow mutations** (before→after transitions)
-- Requires new table + instrumentation to collect fixer dataset
-- Implementation is straightforward with 3-4 weeks of development
-
----
-
-## Documentation Map
-
-### 1. TELEMETRY_ANALYSIS.md (Primary Reference)
-**Length:** 720 lines | **Read Time:** 20-30 minutes
-**Contains:**
-- Complete schema analysis (tables, columns, types)
-- All 12 event types with examples
-- Current workflow tracking capabilities
-- Missing data for mutation tracking
-- Recommended schema additions
-- Technical implementation details
-
-**Start Here If:** You need the complete picture of current capabilities and gaps
-
----
-
-### 2. TELEMETRY_MUTATION_SPEC.md (Implementation Blueprint)
-**Length:** 918 lines | **Read Time:** 30-40 minutes
-**Contains:**
-- Detailed SQL schema for `workflow_mutations` table
-- Complete TypeScript interfaces and types
-- Integration points with existing tools
-- Mutation analyzer service specification
-- Batch processor extensions
-- Query examples for dataset analysis
-
-**Start Here If:** You're ready to implement the mutation tracking system
-
----
-
-### 3. TELEMETRY_QUICK_REFERENCE.md (Developer Guide)
-**Length:** 503 lines | **Read Time:** 10-15 minutes
-**Contains:**
-- Supabase connection details
-- Common queries and patterns
-- Performance tips and tricks
-- Code file references
-- Quick lookup for event types
-
-**Start Here If:** You need to query existing telemetry data or reference specific details
-
----
-
-### 4. TELEMETRY_QUICK_REFERENCE.md (Archive)
-These documents from November 8 contain additional context:
-- `TELEMETRY_ANALYSIS_REPORT.md` - Executive summary with visualizations
-- `TELEMETRY_EXECUTIVE_SUMMARY.md` - High-level overview
-- `TELEMETRY_TECHNICAL_DEEP_DIVE.md` - Architecture details
-- `TELEMETRY_DATA_FOR_VISUALIZATION.md` - Sample data for dashboards
-
----
-
-## Current State Summary
-
-### Telemetry Backend
-```
-URL:     https://ydyufsohxdfpopqbubwk.supabase.co
-Database: PostgreSQL
-Tables:   telemetry_events (276K rows)
-          telemetry_workflows (6.5K rows)
-Privacy:  PII sanitization enabled
-Scope:    Anonymous tool usage, workflows, errors
-```
-
-### Tracked Event Categories
-1. **Tool Usage** (40-50%) - Which tools users employ
-2. **Tool Sequences** (20-30%) - How tools are chained together
-3. **Errors** (10-15%) - Error types and context
-4. **Validation** (5-10%) - Configuration validation details
-5. **Workflows** (5-10%) - Workflow creation and structure
-6. **Performance** (5-10%) - Operation latency
-7. **Sessions** (misc) - User session metadata
-
-### What's Missing for N8N-Fixer
-```
-MISSING: Workflow Mutation Events
-- No before workflow capture
-- No instruction/transformation storage
-- No after workflow snapshot
-- No mutation success metrics
-- No validation improvement tracking
-```
-
----
-
-## Recommended Implementation Path
-
-### Phase 1: Infrastructure (1-2 weeks)
-1. Create `workflow_mutations` table in Supabase
-   - See TELEMETRY_MUTATION_SPEC.md Section 2.1 for full SQL
-   - Includes 20+ strategic indexes
-   - Supports compression for large workflows
-
-2. Update TypeScript types
-   - New `WorkflowMutation` interface
-   - New `WorkflowMutationEvent` event type
-   - Mutation analyzer service
-
-3. Add data validators
-   - Hash verification
-   - Deduplication logic
-   - Size validation
-
----
-
-### Phase 2: Core Integration (1-2 weeks)
-1. Extend TelemetryManager
-   - Add `trackWorkflowMutation()` method
-   - Auto-flush mutations to prevent loss
-
-2. Extend EventTracker
-   - Add mutation queue
-   - Mutation analyzer integration
-   - Validation state detection
-
-3. Extend BatchProcessor
-   - Flush workflow mutations to Supabase
-   - Retry logic and dead letter queue
-   - Performance monitoring
-
----
-
-### Phase 3: Tool Integration (1 week)
-Instrument 3 key tools to capture mutations:
-
-1. **n8n_autofix_workflow**
-   - Before: Broken workflow
-   - Instruction: "Auto-fix validation errors"
-   - After: Fixed workflow
-   - Type: `auto_fix`
-
-2. **n8n_update_partial_workflow**
-   - Before: Current workflow
-   - Instruction: Diff operations
-   - After: Updated workflow
-   - Type: `user_provided`
-
-3. **Validation Engine** (if applicable)
-   - Before: Invalid workflow
-   - Instruction: Validation correction
-   - After: Valid workflow
-   - Type: `validation_correction`
-
----
-
-### Phase 4: Validation & Analysis (1 week)
-1. Data quality verification
-   - Hash validation
-   - Size checks
-   - Deduplication effectiveness
-
-2. Sample query execution
-   - Success rate by instruction type
-   - Common mutations
-   - Complexity impact
-
-3. Dataset assessment
-   - Volume estimates
-   - Data distribution
-   - Quality metrics
-
----
-
-## Key Metrics You'll Collect
-
-### Per Mutation Record
-- **Identification:** User ID, Workflow ID, Timestamp
-- **Before State:** Full workflow JSON, hash, validation status
-- **Instruction:** The transformation prompt/directive
-- **After State:** Full workflow JSON, hash, validation status
-- **Changes:** Nodes modified, properties changed, connections modified
-- **Outcome:** Success boolean, validation improvement, errors fixed
-
-### Aggregate Analysis
-```sql
--- Success rates by instruction type
-SELECT instruction_type, COUNT(*) as count,
-       ROUND(100.0 * COUNT(*) FILTER(WHERE mutation_success) / COUNT(*), 2) as success_rate
-FROM workflow_mutations
-GROUP BY instruction_type;
-
--- Validation improvement distribution
-SELECT validation_errors_fixed, COUNT(*) as count
-FROM workflow_mutations
-WHERE validation_improved = true
-GROUP BY 1
-ORDER BY 2 DESC;
-
--- Complexity transitions
-SELECT complexity_before, complexity_after, COUNT(*) as transitions
-FROM workflow_mutations
-GROUP BY 1, 2;
-```
-
----
-
-## Storage Requirements
-
-### Data Size Estimates
-```
-Average Before Workflow:     10 KB
-Average After Workflow:      10 KB
-Average Instruction:         500 B
-Indexes & Metadata:          5 KB
-Per Mutation Total:          25 KB
-
-Monthly Mutations (estimate): 10K-50K
-Monthly Storage:             250 MB - 1.2 GB
-Annual Storage:              3-14 GB
-```
-
-### Optimization Strategies
-1. **Compression:** Gzip workflows >1MB
-2. **Deduplication:** Skip identical before/after pairs
-3. **Retention:** Define archival policy (90 days? 1 year?)
-4. **Indexing:** Materialized views for common queries
-
----
-
-## Data Safety & Privacy
-
-### Current Protections
-- User IDs are anonymized
-- Credentials are stripped from workflows
-- Email addresses are masked [EMAIL]
-- API keys are masked [KEY]
-- URLs are masked [URL]
-- Error messages are sanitized
-
-### For Mutations Table
-- Continue PII sanitization
-- Hash verification for integrity
-- Size limits (10 MB per workflow with compression)
-- User consent (telemetry opt-in)
-
----
-
-## Integration Points
-
-### Where to Add Tracking Calls
-```typescript
-// In n8n_autofix_workflow
-await telemetry.trackWorkflowMutation(
-  originalWorkflow,
-  'Auto-fix validation errors',
-  fixedWorkflow,
-  { instructionType: 'auto_fix', success: true }
-);
-
-// In n8n_update_partial_workflow
-await telemetry.trackWorkflowMutation(
-  currentWorkflow,
-  formatOperationsAsInstruction(operations),
-  updatedWorkflow,
-  { instructionType: 'user_provided' }
-);
-```
-
-### No Breaking Changes
-- Fully backward compatible
-- Existing telemetry unaffected
-- Optional feature (can disable if needed)
-- Doesn't require version bump
-
----
-
-## Success Criteria
-
-### Phase 1 Complete When:
-- [ ] `workflow_mutations` table created with all indexes
-- [ ] TypeScript types defined and compiling
-- [ ] Validators written and tested
-- [ ] No schema changes needed (validated against use cases)
-
-### Phase 2 Complete When:
-- [ ] TelemetryManager has `trackWorkflowMutation()` method
-- [ ] EventTracker queues mutations properly
-- [ ] BatchProcessor flushes mutations to Supabase
-- [ ] Integration tests pass
-
-### Phase 3 Complete When:
-- [ ] 3+ tools instrumented with tracking calls
-- [ ] Manual testing shows mutations captured
-- [ ] Sample mutations visible in Supabase
-- [ ] No performance regression in tools
-
-### Phase 4 Complete When:
-- [ ] 100+ mutations collected and validated
-- [ ] Sample queries execute correctly
-- [ ] Data quality metrics acceptable
-- [ ] Dataset ready for ML training
-
----
-
-## File Structure for Implementation
-
-```
-src/telemetry/
-├── telemetry-types.ts          (Update: Add WorkflowMutation interface)
-├── telemetry-manager.ts        (Update: Add trackWorkflowMutation method)
-├── event-tracker.ts            (Update: Add mutation tracking)
-├── batch-processor.ts          (Update: Add flush mutations)
-├── mutation-analyzer.ts        (NEW: Analyze workflow diffs)
-├── mutation-validator.ts       (NEW: Validate mutation data)
-└── index.ts                    (Update: Export new functions)
-
-tests/
-└── unit/telemetry/
-    ├── mutation-analyzer.test.ts        (NEW)
-    ├── mutation-validator.test.ts       (NEW)
-    └── telemetry-integration.test.ts    (Update)
-```
-
----
-
-## Risk Assessment
-
-### Low Risk
-- No changes to existing event system
-- Supabase table addition is non-breaking
-- TypeScript types only (no runtime impact)
-
-### Medium Risk
-- Large workflows may impact performance if not compressed
-- Storage costs if dataset grows faster than estimated
-- Mitigation: Compression + retention policy
-
-### High Risk
-- None identified if implemented as specified
-
----
-
-## Next Steps
-
-1. **Review This Analysis**
-   - Read TELEMETRY_ANALYSIS.md (main reference)
-   - Review TELEMETRY_MUTATION_SPEC.md (implementation guide)
-
-2. **Plan Implementation**
-   - Estimate developer hours
-   - Assign implementation tasks
-   - Create Jira tickets or equivalent
-
-3. **Phase 1: Create Infrastructure**
-   - Create Supabase table
-   - Define TypeScript types
-   - Write validators
-
-4. **Phase 2: Integrate Core**
-   - Extend telemetry system
-   - Write integration tests
-
-5. **Phase 3: Instrument Tools**
-   - Add tracking calls to 3+ mutation sources
-   - Test end-to-end
-
-6. **Phase 4: Validate**
-   - Collect sample data
-   - Run analysis queries
-   - Begin dataset collection
-
----
-
-## Questions to Answer Before Starting
-
-1. **Data Retention:** How long should mutations be kept? (90 days? 1 year?)
-2. **Storage Budget:** What's acceptable monthly storage cost?
-3. **Workflow Size:** What's the max workflow size to store? (with or without compression?)
-4. **Dataset Timeline:** When do you need first 1K/10K/100K samples?
-5. **Privacy:** Any additional PII to sanitize beyond current approach?
-6. **User Consent:** Should mutation tracking be separate opt-in from telemetry?
-
----
-
-## Useful Commands
-
-### View Current Telemetry Tables
-```sql
-SELECT table_name FROM information_schema.tables
-WHERE table_schema = 'public'
-AND table_name LIKE 'telemetry%';
-```
-
-### Count Current Events
-```sql
-SELECT event, COUNT(*) FROM telemetry_events
-GROUP BY event ORDER BY 2 DESC;
-```
-
-### Check Workflow Deduplication Rate
-```sql
-SELECT COUNT(*) as total,
-       COUNT(DISTINCT workflow_hash) as unique
-FROM telemetry_workflows;
-```
-
----
-
-## Document References
-
-All documents are in the n8n-mcp repository root:
-
-| Document | Purpose | Read Time |
-|----------|---------|-----------|
-| TELEMETRY_ANALYSIS.md | Complete schema & event analysis | 20-30 min |
-| TELEMETRY_MUTATION_SPEC.md | Implementation specification | 30-40 min |
-| TELEMETRY_QUICK_REFERENCE.md | Developer quick lookup | 10-15 min |
-| TELEMETRY_ANALYSIS_REPORT.md | Executive summary (archive) | 15-20 min |
-| TELEMETRY_TECHNICAL_DEEP_DIVE.md | Architecture (archive) | 20-25 min |
-
----
-
-## Summary
-
-The n8n-mcp telemetry infrastructure is mature, privacy-conscious, and well-designed. It currently tracks user interactions effectively but lacks workflow mutation capture needed for the n8n-fixer dataset.
-
-**The solution is straightforward:** Add a single `workflow_mutations` table, extend the tracking system, and instrument 3-4 key tools.
-
-**Implementation effort:** 3-4 weeks for a complete, production-ready system.
-
-**Result:** A high-quality dataset of before/instruction/after workflow transformations suitable for training ML models to fix broken n8n workflows automatically.
-
----
-
-**Analysis completed by:** Telemetry Data Analyst
-**Date:** November 12, 2025
-**Status:** Ready for implementation planning
-
-For questions or clarifications, refer to the detailed specifications or raise issues on GitHub.

TELEMETRY_QUICK_REFERENCE.md

@@ -1,503 +0,0 @@
-# Telemetry Quick Reference Guide
-
-Quick lookup for telemetry data access, queries, and common analysis patterns.
-
----
-
-## Supabase Connection Details
-
-### Database
-- **URL:** `https://ydyufsohxdfpopqbubwk.supabase.co`
-- **Project:** n8n-mcp telemetry database
-- **Region:** (inferred from URL)
-
-### Anon Key
-Located in: `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/telemetry-types.ts` (line 105)
-
-### Tables
-| Name | Rows | Purpose |
-|------|------|---------|
-| `telemetry_events` | 276K+ | Discrete events (tool usage, errors, validation) |
-| `telemetry_workflows` | 6.5K+ | Workflow metadata (structure, complexity) |
-
-### Proposed Table
-| Name | Rows | Purpose |
-|------|------|---------|
-| `workflow_mutations` | TBD | Before/instruction/after workflow snapshots |
-
----
-
-## Event Types & Properties
-
-### High-Volume Events
-
-#### `tool_used` (40-50% of traffic)
-```json
-{
-  "event": "tool_used",
-  "properties": {
-    "tool": "get_node_info",
-    "success": true,
-    "duration": 245
-  }
-}
-```
-**Query:** Find most used tools
-```sql
-SELECT properties->>'tool' as tool, COUNT(*) as count
-FROM telemetry_events
-WHERE event = 'tool_used' AND created_at >= NOW() - INTERVAL '7 days'
-GROUP BY 1 ORDER BY 2 DESC;
-```
-
-#### `tool_sequence` (20-30% of traffic)
-```json
-{
-  "event": "tool_sequence",
-  "properties": {
-    "previousTool": "search_nodes",
-    "currentTool": "get_node_info",
-    "timeDelta": 1250,
-    "isSlowTransition": false,
-    "sequence": "search_nodes->get_node_info"
-  }
-}
-```
-**Query:** Find common tool sequences
-```sql
-SELECT properties->>'sequence' as flow, COUNT(*) as count
-FROM telemetry_events
-WHERE event = 'tool_sequence' AND created_at >= NOW() - INTERVAL '30 days'
-GROUP BY 1 ORDER BY 2 DESC LIMIT 20;
-```
-
----
-
-### Error & Validation Events
-
-#### `error_occurred` (10-15% of traffic)
-```json
-{
-  "event": "error_occurred",
-  "properties": {
-    "errorType": "validation_error",
-    "context": "Node config failed [KEY]",
-    "tool": "config_validator",
-    "error": "[SANITIZED] type error",
-    "mcpMode": "stdio",
-    "platform": "darwin"
-  }
-}
-```
-**Query:** Error frequency by type
-```sql
-SELECT
-  properties->>'errorType' as error_type,
-  COUNT(*) as frequency,
-  COUNT(DISTINCT user_id) as affected_users
-FROM telemetry_events
-WHERE event = 'error_occurred' AND created_at >= NOW() - INTERVAL '24 hours'
-GROUP BY 1 ORDER BY 2 DESC;
-```
-
-#### `validation_details` (5-10% of traffic)
-```json
-{
-  "event": "validation_details",
-  "properties": {
-    "nodeType": "nodes_base_httpRequest",
-    "errorType": "required_field_missing",
-    "errorCategory": "required_field_error",
-    "details": { /* error details */ }
-  }
-}
-```
-**Query:** Validation errors by node type
-```sql
-SELECT
-  properties->>'nodeType' as node_type,
-  properties->>'errorType' as error_type,
-  COUNT(*) as count
-FROM telemetry_events
-WHERE event = 'validation_details' AND created_at >= NOW() - INTERVAL '7 days'
-GROUP BY 1, 2 ORDER BY 3 DESC;
-```
-
----
-
-### Workflow Events
-
-#### `workflow_created`
-```json
-{
-  "event": "workflow_created",
-  "properties": {
-    "nodeCount": 3,
-    "nodeTypes": 2,
-    "complexity": "simple",
-    "hasTrigger": true,
-    "hasWebhook": false
-  }
-}
-```
-**Query:** Workflow creation trends
-```sql
-SELECT
-  DATE(created_at) as date,
-  COUNT(*) as workflows_created,
-  AVG((properties->>'nodeCount')::int) as avg_nodes,
-  COUNT(*) FILTER(WHERE properties->>'complexity' = 'simple') as simple_count
-FROM telemetry_events
-WHERE event = 'workflow_created' AND created_at >= NOW() - INTERVAL '30 days'
-GROUP BY 1 ORDER BY 1;
-```
-
-#### `workflow_validation_failed`
-```json
-{
-  "event": "workflow_validation_failed",
-  "properties": {
-    "nodeCount": 5
-  }
-}
-```
-**Query:** Validation failure rate
-```sql
-SELECT
-  COUNT(*) FILTER(WHERE event = 'workflow_created') as successful,
-  COUNT(*) FILTER(WHERE event = 'workflow_validation_failed') as failed,
-  ROUND(100.0 * COUNT(*) FILTER(WHERE event = 'workflow_validation_failed')
-        / NULLIF(COUNT(*), 0), 2) as failure_rate
-FROM telemetry_events
-WHERE created_at >= NOW() - INTERVAL '7 days'
-  AND event IN ('workflow_created', 'workflow_validation_failed');
-```
-
----
-
-### Session & System Events
-
-#### `session_start`
-```json
-{
-  "event": "session_start",
-  "properties": {
-    "version": "2.22.15",
-    "platform": "darwin",
-    "arch": "arm64",
-    "nodeVersion": "v18.17.0",
-    "isDocker": false,
-    "cloudPlatform": null,
-    "mcpMode": "stdio",
-    "startupDurationMs": 1234
-  }
-}
-```
-**Query:** Platform distribution
-```sql
-SELECT
-  properties->>'platform' as platform,
-  properties->>'arch' as arch,
-  COUNT(*) as sessions,
-  AVG((properties->>'startupDurationMs')::int) as avg_startup_ms
-FROM telemetry_events
-WHERE event = 'session_start' AND created_at >= NOW() - INTERVAL '30 days'
-GROUP BY 1, 2 ORDER BY 3 DESC;
-```
-
----
-
-## Workflow Metadata Table Queries
-
-### Workflow Complexity Distribution
-```sql
-SELECT
-  complexity,
-  COUNT(*) as count,
-  AVG(node_count) as avg_nodes,
-  MAX(node_count) as max_nodes
-FROM telemetry_workflows
-GROUP BY complexity
-ORDER BY count DESC;
-```
-
-### Most Common Node Type Combinations
-```sql
-SELECT
-  node_types,
-  COUNT(*) as frequency
-FROM telemetry_workflows
-GROUP BY node_types
-ORDER BY frequency DESC
-LIMIT 20;
-```
-
-### Workflows with Triggers vs Webhooks
-```sql
-SELECT
-  has_trigger,
-  has_webhook,
-  COUNT(*) as count,
-  ROUND(100.0 * COUNT(*) / (SELECT COUNT(*) FROM telemetry_workflows), 2) as percentage
-FROM telemetry_workflows
-GROUP BY 1, 2;
-```
-
-### Deduplicated Workflows (by hash)
-```sql
-SELECT
-  COUNT(DISTINCT workflow_hash) as unique_workflows,
-  COUNT(*) as total_rows,
-  COUNT(DISTINCT user_id) as unique_users
-FROM telemetry_workflows;
-```
-
----
-
-## Common Analysis Patterns
-
-### 1. User Journey Analysis
-```sql
--- Tool usage patterns for a user (anonymized)
-WITH user_events AS (
-  SELECT
-    user_id,
-    event,
-    properties->>'tool' as tool,
-    created_at,
-    LAG(event) OVER(PARTITION BY user_id ORDER BY created_at) as prev_event
-  FROM telemetry_events
-  WHERE event IN ('tool_used', 'tool_sequence')
-    AND created_at >= NOW() - INTERVAL '7 days'
-)
-SELECT
-  prev_event,
-  event,
-  COUNT(*) as transitions
-FROM user_events
-WHERE prev_event IS NOT NULL
-GROUP BY 1, 2
-ORDER BY 3 DESC
-LIMIT 20;
-```
-
-### 2. Performance Trends
-```sql
--- Tool execution performance over time
-WITH perf_data AS (
-  SELECT
-    properties->>'tool' as tool,
-    (properties->>'duration')::int as duration,
-    DATE(created_at) as date
-  FROM telemetry_events
-  WHERE event = 'tool_used'
-    AND created_at >= NOW() - INTERVAL '30 days'
-)
-SELECT
-  date,
-  tool,
-  COUNT(*) as executions,
-  AVG(duration)::INTEGER as avg_duration_ms,
-  PERCENTILE_CONT(0.95) WITHIN GROUP(ORDER BY duration) as p95_duration_ms,
-  MAX(duration) as max_duration_ms
-FROM perf_data
-GROUP BY date, tool
-ORDER BY date DESC, tool;
-```
-
-### 3. Error Analysis with Context
-```sql
--- Recent errors with affected tools
-SELECT
-  properties->>'errorType' as error_type,
-  properties->>'tool' as affected_tool,
-  properties->>'context' as context,
-  COUNT(*) as occurrences,
-  MAX(created_at) as most_recent,
-  COUNT(DISTINCT user_id) as users_affected
-FROM telemetry_events
-WHERE event = 'error_occurred'
-  AND created_at >= NOW() - INTERVAL '24 hours'
-GROUP BY 1, 2, 3
-ORDER BY 4 DESC, 5 DESC;
-```
-
-### 4. Node Configuration Patterns
-```sql
--- Most configured nodes and their complexity
-WITH config_data AS (
-  SELECT
-    properties->>'nodeType' as node_type,
-    (properties->>'propertiesSet')::int as props_set,
-    properties->>'usedDefaults' = 'true' as used_defaults
-  FROM telemetry_events
-  WHERE event = 'node_configuration'
-    AND created_at >= NOW() - INTERVAL '30 days'
-)
-SELECT
-  node_type,
-  COUNT(*) as configurations,
-  AVG(props_set)::INTEGER as avg_props_set,
-  ROUND(100.0 * SUM(CASE WHEN used_defaults THEN 1 ELSE 0 END)
-        / COUNT(*), 2) as default_usage_rate
-FROM config_data
-GROUP BY node_type
-ORDER BY 2 DESC
-LIMIT 20;
-```
-
-### 5. Search Effectiveness
-```sql
--- Search queries and their success
-SELECT
-  properties->>'searchType' as search_type,
-  COUNT(*) as total_searches,
-  COUNT(*) FILTER(WHERE (properties->>'hasResults')::boolean) as with_results,
-  ROUND(100.0 * COUNT(*) FILTER(WHERE (properties->>'hasResults')::boolean)
-        / COUNT(*), 2) as success_rate,
-  AVG((properties->>'resultsFound')::int) as avg_results
-FROM telemetry_events
-WHERE event = 'search_query'
-  AND created_at >= NOW() - INTERVAL '7 days'
-GROUP BY 1
-ORDER BY 2 DESC;
-```
-
----
-
-## Data Size Estimates
-
-### Current Data Volume
-- **Total Events:** ~276K rows
-- **Size per Event:** ~200 bytes (average)
-- **Total Size (events):** ~55 MB
-
-- **Total Workflows:** ~6.5K rows
-- **Size per Workflow:** ~2 KB (sanitized)
-- **Total Size (workflows):** ~13 MB
-
-**Total Current Storage:** ~68 MB
-
-### Growth Projections
-- **Daily Events:** ~1,000-2,000
-- **Monthly Growth:** ~30-60 MB
-- **Annual Growth:** ~360-720 MB
-
----
-
-## Helpful Constants
-
-### Event Type Values
-```
-tool_used
-tool_sequence
-error_occurred
-validation_details
-node_configuration
-performance_metric
-search_query
-workflow_created
-workflow_validation_failed
-session_start
-startup_completed
-startup_error
-```
-
-### Complexity Values
-```
-'simple'
-'medium'
-'complex'
-```
-
-### Validation Status Values (for mutations)
-```
-'valid'
-'invalid'
-'unknown'
-```
-
-### Instruction Type Values (for mutations)
-```
-'ai_generated'
-'user_provided'
-'auto_fix'
-'validation_correction'
-```
-
----
-
-## Tips & Tricks
-
-### Finding Zero-Result Searches
-```sql
-SELECT properties->>'query' as search_term, COUNT(*) as attempts
-FROM telemetry_events
-WHERE event = 'search_query'
-  AND (properties->>'isZeroResults')::boolean = true
-  AND created_at >= NOW() - INTERVAL '7 days'
-GROUP BY 1 ORDER BY 2 DESC;
-```
-
-### Identifying Slow Operations
-```sql
-SELECT
-  properties->>'operation' as operation,
-  COUNT(*) as count,
-  PERCENTILE_CONT(0.99) WITHIN GROUP(ORDER BY (properties->>'duration')::int) as p99_ms
-FROM telemetry_events
-WHERE event = 'performance_metric'
-  AND created_at >= NOW() - INTERVAL '7 days'
-GROUP BY 1
-HAVING PERCENTILE_CONT(0.99) WITHIN GROUP(ORDER BY (properties->>'duration')::int) > 1000
-ORDER BY 3 DESC;
-```
-
-### User Retention Analysis
-```sql
--- Active users by week
-WITH weekly_users AS (
-  SELECT
-    DATE_TRUNC('week', created_at) as week,
-    COUNT(DISTINCT user_id) as active_users
-  FROM telemetry_events
-  WHERE created_at >= NOW() - INTERVAL '90 days'
-  GROUP BY 1
-)
-SELECT week, active_users
-FROM weekly_users
-ORDER BY week DESC;
-```
-
-### Platform Usage Breakdown
-```sql
-SELECT
-  properties->>'platform' as platform,
-  properties->>'arch' as architecture,
-  COALESCE(properties->>'cloudPlatform', 'local') as deployment,
-  COUNT(DISTINCT user_id) as unique_users
-FROM telemetry_events
-WHERE event = 'session_start'
-  AND created_at >= NOW() - INTERVAL '30 days'
-GROUP BY 1, 2, 3
-ORDER BY 4 DESC;
-```
-
----
-
-## File References for Development
-
-### Source Code
-- **Types:** `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/telemetry-types.ts`
-- **Manager:** `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/telemetry-manager.ts`
-- **Tracker:** `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/event-tracker.ts`
-- **Processor:** `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/batch-processor.ts`
-
-### Documentation
-- **Full Analysis:** `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/TELEMETRY_ANALYSIS.md`
-- **Mutation Spec:** `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/TELEMETRY_MUTATION_SPEC.md`
-- **This Guide:** `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/TELEMETRY_QUICK_REFERENCE.md`
-
----
-
-*Last Updated: November 12, 2025*

TELEMETRY_TECHNICAL_DEEP_DIVE.md

@@ -1,654 +0,0 @@
-# n8n-MCP Telemetry Technical Deep-Dive
-## Detailed Error Patterns and Root Cause Analysis
-
----
-
-## 1. ValidationError Root Causes (3,080 occurrences)
-
-### 1.1 Workflow Structure Validation (21,423 node-level errors - 39.11%)
-
-**Error Distribution by Node:**
-- `workflow` node: 21,423 errors (39.11%)
-- Generic nodes (Node0-19): ~6,000 errors (11%)
-- Placeholder nodes ([KEY], ______, _____): ~1,600 errors (3%)
-- Real nodes (Webhook, HTTP_Request): ~600 errors (1%)
-
-**Interpreted Issue Categories:**
-
-1. **Missing Trigger Nodes (Estimated 35-40% of workflow errors)**
-   - Users create workflows without start trigger
-   - Validation requires at least one trigger (webhook, schedule, etc.)
-   - Error message: Generic "validation failed" doesn't specify missing trigger
-
-2. **Invalid Node Connections (Estimated 25-30% of workflow errors)**
-   - Nodes connected in wrong order
-   - Output type mismatch between connected nodes
-   - Circular dependencies created
-   - Example: Trying to use output of node that hasn't run yet
-
-3. **Type Mismatches (Estimated 20-25% of workflow errors)**
-   - Node expects array, receives string
-   - Node expects object, receives primitive
-   - Related to TypeError errors (2,767 occurrences)
-
-4. **Missing Required Properties (Estimated 10-15% of workflow errors)**
-   - Webhook nodes missing path/method
-   - HTTP nodes missing URL
-   - Database nodes missing connection string
-
-### 1.2 Placeholder Node Test Data (4,700+ errors)
-
-**Problem:** Generic test node names creating noise
-
-```
-Node0-Node19:    ~6,000+ errors
-[KEY]:           656 errors
-______ (6 underscores): 643 errors
-_____ (5 underscores): 207 errors
-______ (8 underscores): 227 errors
-```
-
-**Evidence:** These names appear in telemetry_validation_errors_daily
-- Consistent across 25-36 days
-- Indicates: System test data or user test workflows
-
-**Action Required:**
-1. Filter test data from telemetry (add flag for test vs. production)
-2. Clean up existing test workflows from database
-3. Implement test isolation so test events don't pollute metrics
-
-### 1.3 Webhook Validation Issues (435 errors)
-
-**Webhook-Specific Problems:**
-
-```
-Error Pattern Analysis:
-- Webhook: 435 errors
-- Webhook_Trigger: 293 errors
-- Total Webhook-related: 728 errors (~1.3% of validation errors)
-```
-
-**Common Webhook Failures:**
-1. **Missing Required Fields:**
-   - No HTTP method specified (GET/POST/PUT/DELETE)
-   - No URL path configured
-   - No authentication method selected
-
-2. **Configuration Errors:**
-   - Invalid URL patterns (special characters, spaces)
-   - Incorrect CORS settings
-   - Missing body for POST/PUT operations
-   - Header format issues
-
-3. **Connection Issues:**
-   - Firewall/network blocking
-   - Unsupported protocol (HTTP vs HTTPS mismatch)
-   - TLS version incompatibility
-
----
-
-## 2. TypeError Root Causes (2,767 occurrences)
-
-### 2.1 Type Mismatch Categories
-
-**Pattern Analysis:**
-- 31.23% of all errors
-- Indicates schema/type enforcement issues
-- Overlaps with ValidationError (both types occur together)
-
-### 2.2 Common Type Mismatches
-
-**JSON Property Errors (Estimated 40% of TypeErrors):**
-```
-Problem: properties field in telemetry_events is JSONB
-Possible Issues:
-- Passing string "true" instead of boolean true
-- Passing number as string "123"
-- Passing array [value] instead of scalar value
-- Nested object structure violations
-```
-
-**Node Property Errors (Estimated 35% of TypeErrors):**
-```
-HTTP Request Node Example:
-- method: Expects "GET" | "POST" | etc., receives 1, 0 (numeric)
-- timeout: Expects number (ms), receives string "5000"
-- headers: Expects object {key: value}, receives string "[object Object]"
-```
-
-**Expression Errors (Estimated 25% of TypeErrors):**
-```
-n8n Expressions Example:
-- $json.count expects number, receives $json.count_str (string)
-- $node[nodeId].data expects array, receives single object
-- Missing type conversion: parseInt(), String(), etc.
-```
-
-### 2.3 Type Validation System Gaps
-
-**Current System Weakness:**
-- JSONB storage in Postgres doesn't enforce types
-- Validation happens at application layer
-- No real-time type checking during workflow building
-- Type errors only discovered at validation time
-
-**Recommended Fixes:**
-1. Implement strict schema validation in node parser
-2. Add TypeScript definitions for all node properties
-3. Generate type stubs from node definitions
-4. Validate types during property extraction phase
-
----
-
-## 3. Generic Error Root Causes (2,711 occurrences)
-
-### 3.1 Why Generic Errors Are Problematic
-
-**Current Classification:**
-- 30.60% of all errors
-- No error code or subtype
-- Indicates unhandled exception scenario
-- Prevents automated recovery
-
-**Likely Sources:**
-
-1. **Database Connection Errors (Estimated 30%)**
-   - Timeout during validation query
-   - Connection pool exhaustion
-   - Query too large/complex
-
-2. **Out of Memory Errors (Estimated 20%)**
-   - Large workflow processing
-   - Huge node count (100+ nodes)
-   - Property extraction on complex nodes
-
-3. **Unhandled Exceptions (Estimated 25%)**
-   - Code path not covered by specific error handling
-   - Unexpected input format
-   - Missing null checks
-
-4. **External Service Failures (Estimated 15%)**
-   - Documentation fetch timeout
-   - Node package load failure
-   - Network connectivity issues
-
-5. **Unknown Issues (Estimated 10%)**
-   - No further categorization available
-
-### 3.2 Error Context Missing
-
-**What We Know:**
-- Error occurred during validation/operation
-- Generic type (Error vs. ValidationError vs. TypeError)
-
-**What We Don't Know:**
-- Which specific validation step failed
-- What input caused the error
-- What operation was in progress
-- Root exception details (stack trace)
-
----
-
-## 4. Tool-Specific Failure Analysis
-
-### 4.1 `get_node_info` - 11.72% Failure Rate (CRITICAL)
-
-**Failure Count:** 1,208 out of 10,304 invocations
-
-**Hypothesis Testing:**
-
-**Hypothesis 1: Missing Database Records (30% likelihood)**
-```
-Scenario: Node definition not in database
-Evidence:
-- 1,208 failures across 36 days
-- Consistent rate suggests systematic gaps
-- New nodes not in database after updates
-
-Solution:
-- Verify database has 525 total nodes
-- Check if failing on node types that exist
-- Implement cache warming
-```
-
-**Hypothesis 2: Encoding/Parsing Issues (40% likelihood)**
-```
-Scenario: Complex node properties fail to parse
-Evidence:
-- Only 11.72% fail (not all complex nodes)
-- Specific to get_node_info, not essentials
-- Likely: edge case in JSONB serialization
-
-Example Problem:
-- Node with circular references
-- Node with very large property tree
-- Node with special characters in documentation
-- Node with unicode/non-ASCII characters
-
-Solution:
-- Add error telemetry to capture failing node names
-- Implement pagination for large properties
-- Add encoding validation
-```
-
-**Hypothesis 3: Concurrent Access Issues (20% likelihood)**
-```
-Scenario: Race condition during node updates
-Evidence:
-- Fails at specific times
-- Not tied to specific node types
-- Affects retrieval, not storage
-
-Solution:
-- Add read locking during updates
-- Implement query timeouts
-- Add retry logic with exponential backoff
-```
-
-**Hypothesis 4: Query Timeout (10% likelihood)**
-```
-Scenario: Database query takes >30s for large nodes
-Evidence:
-- Observed in telemetry tool sequences
-- High latency for some operations
-- System resource constraints
-
-Solution:
-- Add query optimization
-- Implement caching layer
-- Pre-compute common queries
-```
-
-### 4.2 `get_node_documentation` - 4.13% Failure Rate
-
-**Failure Count:** 471 out of 11,403 invocations
-
-**Root Causes (Estimated):**
-
-1. **Missing Documentation (40%)** - Some nodes lack comprehensive docs
-2. **Retrieval Errors (30%)** - Timeout fetching from n8n.io API
-3. **Parsing Errors (20%)** - Documentation format issues
-4. **Encoding Issues (10%)** - Non-ASCII characters in docs
-
-**Pattern:** Correlated with `get_node_info` failures (both documentation retrieval)
-
-### 4.3 `validate_node_operation` - 6.42% Failure Rate
-
-**Failure Count:** 363 out of 5,654 invocations
-
-**Root Causes (Estimated):**
-
-1. **Incomplete Operation Definitions (40%)**
-   - Validator doesn't know all valid operations for node
-   - Operation definitions outdated vs. actual node
-   - New operations not in validator database
-
-2. **Property Dependency Logic Gaps (35%)**
-   - Validator doesn't understand conditional requirements
-   - Missing: "if X is set, then Y is required"
-   - Property visibility rules incomplete
-
-3. **Type Matching Failures (20%)**
-   - Validator expects different type than provided
-   - Type coercion not working
-   - Related to TypeError issues
-
-4. **Edge Cases (5%)**
-   - Unusual property combinations
-   - Boundary conditions
-   - Rarely-used operation modes
-
----
-
-## 5. Temporal Error Patterns
-
-### 5.1 Error Spike Root Causes
-
-**September 26 Spike (6,222 validation errors)**
-- Represents: 70% of September errors in single day
-- Possible causes:
-  1. Batch workflow import test
-  2. Database migration or schema change
-  3. Node definitions updated incompatibly
-  4. System performance issue (slow validation)
-
-**October 12 Spike (567.86% increase: 28 → 187 errors)**
-- Could indicate: System restart, deployment, rollback
-- Recovery pattern: Immediate return to normal
-- Suggests: One-time event, not systemic
-
-**October 3-10 Plateau (2,000+ errors daily)**
-- Duration: 8 days sustained elevation
-- Peak: October 4 (3,585 errors)
-- Recovery: October 11 (83.72% drop to 28 errors)
-- Interpretation: Incident period with mitigation
-
-### 5.2 Current Trend (Oct 30-31)
-
-- Oct 30: 278 errors (elevated)
-- Oct 31: 130 errors (recovering)
-- Baseline: 60-65 errors/day (normal)
-
-**Interpretation:** System health improving; approaching steady state
-
----
-
-## 6. Tool Sequence Performance Bottlenecks
-
-### 6.1 Sequential Update Loop Analysis
-
-**Pattern:** `n8n_update_partial_workflow → n8n_update_partial_workflow`
-- **Occurrences:** 96,003 (highest volume)
-- **Avg Duration:** 55.2 seconds
-- **Slow Transitions:** 63,322 (66%)
-
-**Why This Matters:**
-```
-Scenario: Workflow with 20 property updates
-Current: 20 × 55.2s = 18.4 minutes total
-With batch operation: ~5-10 seconds total
-Improvement: 95%+ faster
-```
-
-**Root Causes:**
-
-1. **No Batch Update Operation (80% likely)**
-   - Each update is separate API call
-   - Each call: parse request + validate + update + persist
-   - No atomicity guarantee
-
-2. **Network Round-Trip Latency (15% likely)**
-   - Each call adds latency
-   - If client/server not co-located: 100-200ms per call
-   - Compounds with update operations
-
-3. **Validation on Each Update (5% likely)**
-   - Full workflow validation on each property change
-   - Could be optimized to field-level validation
-
-**Solution:**
-```typescript
-// Proposed Batch Update Operation
-interface BatchUpdateRequest {
-  workflowId: string;
-  operations: [
-    { type: 'updateNode', nodeId: string, properties: object },
-    { type: 'updateConnection', from: string, to: string, config: object },
-    { type: 'updateSettings', settings: object }
-  ];
-  validateFull: boolean; // Full or incremental validation
-}
-
-// Returns: Updated workflow with all changes applied atomically
-```
-
-### 6.2 Read-After-Write Pattern
-
-**Pattern:** `n8n_update_partial_workflow → n8n_get_workflow`
-- **Occurrences:** 19,876
-- **Avg Duration:** 96.6 seconds
-- **Pattern:** Users verify state after update
-
-**Root Causes:**
-
-1. **Updates Don't Return State (70% likely)**
-   - Update operation returns success/failure
-   - Doesn't return updated workflow state
-   - Forces clients to fetch separately
-
-2. **Verification Uncertainty (20% likely)**
-   - Users unsure if update succeeded completely
-   - Fetch to double-check
-   - Especially with complex multi-node updates
-
-3. **Change Tracking Needed (10% likely)**
-   - Users want to see what changed
-   - Need diff/changelog
-   - Requires full state retrieval
-
-**Solution:**
-```typescript
-// Update response should include:
-{
-  success: true,
-  workflow: { /* full updated workflow */ },
-  changes: {
-    updated_fields: ['nodes[0].name', 'settings.timezone'],
-    added_connections: [{ from: 'node1', to: 'node2' }],
-    removed_nodes: []
-  }
-}
-```
-
-### 6.3 Search Inefficiency Pattern
-
-**Pattern:** `search_nodes → search_nodes`
-- **Occurrences:** 68,056
-- **Avg Duration:** 11.2 seconds
-- **Slow Transitions:** 11,544 (17%)
-
-**Root Causes:**
-
-1. **Poor Ranking (60% likely)**
-   - Users search for "http", get results in wrong order
-   - "HTTP Request" node not in top 3 results
-   - Users refine search
-
-2. **Query Term Mismatch (25% likely)**
-   - Users search "webhook trigger"
-   - System searches for exact phrase
-   - Returns 0 results; users try "webhook" alone
-
-3. **Incomplete Result Matching (15% likely)**
-   - Synonym support missing
-   - Category/tag matching weak
-   - Users don't know official node names
-
-**Solution:**
-```
-Analyze top 50 repeated search sequences:
-- "http" → "http request" → "HTTP Request"
-  Action: Rank "HTTP Request" in top 3 for "http" search
-
-- "schedule" → "schedule trigger" → "cron"
-  Action: Tag scheduler nodes with "cron", "schedule trigger" synonyms
-
-- "webhook" → "webhook trigger" → "HTTP Trigger"
-  Action: Improve documentation linking webhook triggers
-```
-
----
-
-## 7. Validation Accuracy Issues
-
-### 7.1 `validate_workflow` - 5.50% Failure Rate
-
-**Root Causes:**
-
-1. **Incomplete Validation Rules (45%)**
-   - Validator doesn't check all requirements
-   - Missing rules for specific node combinations
-   - Circular dependency detection missing
-
-2. **Schema Version Mismatches (30%)**
-   - Validator schema != actual node schema
-   - Happens after node updates
-   - Validator not updated simultaneously
-
-3. **Performance Timeouts (15%)**
-   - Very large workflows (100+ nodes)
-   - Validation takes >30 seconds
-   - Timeout triggered
-
-4. **Type System Gaps (10%)**
-   - Type checking incomplete
-   - Coercion not working correctly
-   - Related to TypeError issues
-
-### 7.2 `validate_node_operation` - 6.42% Failure Rate
-
-**Root Causes (Estimated):**
-
-1. **Missing Operation Definitions (40%)**
-   - New operations not in validator
-   - Rare operations not covered
-   - Custom operations not supported
-
-2. **Property Dependency Gaps (30%)**
-   - Conditional properties not understood
-   - "If X=Y, then Z is required" rules missing
-   - Visibility logic incomplete
-
-3. **Type Validation Failures (20%)**
-   - Expected type doesn't match provided type
-   - No implicit type coercion
-   - Complex type definitions not validated
-
-4. **Edge Cases (10%)**
-   - Boundary values
-   - Special characters in properties
-   - Maximum length violations
-
----
-
-## 8. Systemic Issues Identified
-
-### 8.1 Validation Error Message Quality
-
-**Current State:**
-```
-❌ "Validation failed"
-❌ "Invalid workflow configuration"
-❌ "Node configuration error"
-```
-
-**What Users Need:**
-```
-✅ "Workflow missing required start trigger node. Add a trigger (Webhook, Schedule, or Manual Trigger)"
-✅ "HTTP Request node 'call_api' missing required URL property"
-✅ "Cannot connect output from 'set_values' (type: string) to 'http_request' input (expects: object)"
-```
-
-**Impact:** Generic errors prevent both users and AI agents from self-correcting
-
-### 8.2 Type System Gaps
-
-**Current System:**
-- JSONB properties in database (no type enforcement)
-- Application-level validation (catches errors late)
-- Limited type definitions for properties
-
-**Gaps:**
-1. No strict schema validation during ingestion
-2. Type coercion not automatic
-3. Complex type definitions (unions, intersections) not supported
-
-### 8.3 Test Data Contamination
-
-**Problem:** 4,700+ errors from placeholder node names
-- Node0-Node19: Generic test nodes
-- [KEY], ______, _______: Incomplete configurations
-- These create noise in real error metrics
-
-**Solution:**
-1. Flag test vs. production data at ingestion
-2. Separate test telemetry database
-3. Filter test data from production analysis
-
----
-
-## 9. Tool Reliability Correlation Matrix
-
-**High Reliability Cluster (99%+ success):**
-- n8n_list_executions (100%)
-- n8n_get_workflow (99.94%)
-- n8n_get_execution (99.90%)
-- search_nodes (99.89%)
-
-**Medium Reliability Cluster (95-99% success):**
-- get_node_essentials (96.19%)
-- n8n_create_workflow (96.35%)
-- get_node_documentation (95.87%)
-- validate_workflow (94.50%)
-
-**Problematic Cluster (<95% success):**
-- get_node_info (88.28%) ← CRITICAL
-- validate_node_operation (93.58%)
-
-**Pattern:** Information retrieval tools have lower success than state manipulation tools
-
-**Hypothesis:** Read operations affected by:
-- Stale caches
-- Missing data
-- Encoding issues
-- Network timeouts
-
----
-
-## 10. Recommendations by Root Cause
-
-### Validation Error Improvements (Target: 50% reduction)
-
-1. **Specific Error Messages** (+25% reduction)
-   - Map 39% workflow errors → specific structural requirements
-   - "Missing start trigger" vs. "validation failed"
-
-2. **Test Data Isolation** (+15% reduction)
-   - Remove 4,700+ errors from placeholder nodes
-   - Separate test telemetry pipeline
-
-3. **Type System Strictness** (+10% reduction)
-   - Implement schema validation on ingestion
-   - Prevent type mismatches at source
-
-### Tool Reliability Improvements (Target: 10% reduction overall)
-
-1. **get_node_info Reliability** (-1,200 errors potential)
-   - Add retry logic
-   - Implement read cache
-   - Fallback to essentials
-
-2. **Workflow Validation** (-500 errors potential)
-   - Improve validation logic
-   - Add missing edge case handling
-   - Optimize performance
-
-3. **Node Operation Validation** (-360 errors potential)
-   - Complete operation definitions
-   - Implement property dependency logic
-   - Add type coercion
-
-### Performance Improvements (Target: 90% latency reduction)
-
-1. **Batch Update Operation**
-   - Reduce 96,003 sequential updates from 55.2s to <5s each
-   - Potential: 18-minute reduction per workflow construction
-
-2. **Return Updated State**
-   - Eliminate 19,876 redundant get_workflow calls
-   - Reduce round trips by 40%
-
-3. **Search Ranking**
-   - Reduce 68,056 sequential searches
-   - Improve hit rate on first search
-
----
-
-## Conclusion
-
-The n8n-MCP system exhibits:
-
-1. **Strong Infrastructure** (99%+ reliability for core operations)
-2. **Weak Information Retrieval** (`get_node_info` at 88%)
-3. **Poor User Feedback** (generic error messages)
-4. **Validation Gaps** (39% of errors unspecified)
-5. **Performance Bottlenecks** (sequential operations at 55+ seconds)
-
-Each issue has clear root causes and actionable solutions. Implementing Priority 1 recommendations would address 80% of user-facing problems and significantly improve AI agent success rates.
-
----
-
-**Report Prepared By:** AI Telemetry Analyst
-**Technical Depth:** Deep Dive Level
-**Audience:** Engineering Team / Architecture Review
-**Date:** November 8, 2025

VALIDATION_ANALYSIS_REPORT.md

@@ -1,683 +0,0 @@
-# N8N-MCP Telemetry Analysis: Validation Failures as System Feedback
-
-**Analysis Date:** November 8, 2025
-**Data Period:** September 26 - November 8, 2025 (90 days)
-**Report Type:** Comprehensive Validation Failure Root Cause Analysis
-
----
-
-## Executive Summary
-
-Validation failures in n8n-mcp are NOT system failures—they are the system working exactly as designed, catching configuration errors before deployment. However, the high volume (29,218 validation events across 9,021 users) reveals significant **documentation and guidance gaps** that prevent AI agents from configuring nodes correctly on the first attempt.
-
-### Critical Findings:
-
-1. **100% Retry Success Rate**: When AI agents encounter validation errors, they successfully correct and deploy workflows same-day 100% of the time—proving validation feedback is effective and agents learn quickly.
-
-2. **Top 3 Problematic Areas** (accounting for 75% of errors):
-   - Workflow structure issues (undefined node IDs/names, connection errors): 33.2%
-   - Webhook/trigger configuration: 6.7%
-   - Required field documentation: 7.7%
-
-3. **Tool Usage Insight**: Agents using documentation tools BEFORE attempting configuration have slightly HIGHER error rates (12.6% vs 10.8%), suggesting documentation alone is insufficient—agents need better guidance integrated into tool responses.
-
-4. **Search Query Patterns**: Most common pre-failure searches are generic ("webhook", "http request", "openai") rather than specific node configuration searches, indicating agents are searching for node existence rather than configuration details.
-
-5. **Node-Specific Crisis Points**:
-   - **Webhook/Webhook Trigger**: 127 combined failures (47 unique users)
-   - **AI Agent**: 36 failures (20 users) - missing AI model connections
-   - **Slack variants**: 101 combined failures (7 users)
-   - **Generic nodes** ([KEY], underscores): 275 failures - likely malformed JSON from agents
-
----
-
-## Detailed Analysis
-
-### 1. Node-Specific Difficulty Ranking
-
-The nodes causing the most validation failures reveal where agent guidance is weakest:
-
-| Rank | Node Type | Failures | Users | Primary Error | Impact |
-|------|-----------|----------|-------|---------------|--------|
-| 1 | Webhook (trigger config) | 127 | 40 | responseNode requires `onError: "continueRegularOutput"` | HIGH |
-| 2 | Slack_Notification | 73 | 2 | Required field "Send Message To" empty; Invalid enum "select" | HIGH |
-| 3 | AI_Agent | 36 | 20 | Missing `ai_languageModel` connection | HIGH |
-| 4 | HTTP_Request | 31 | 13 | Missing required fields (varied) | MEDIUM |
-| 5 | OpenAI | 35 | 8 | Misconfigured model/auth/parameters | MEDIUM |
-| 6 | Airtable_Create_Record | 41 | 1 | Required fields for API records | MEDIUM |
-| 7 | Telegram | 27 | 1 | Operation enum mismatch; Missing Chat ID | MEDIUM |
-
-**Key Insight**: The most problematic nodes are trigger/connector nodes and AI/API integrations—these require deep understanding of external API contracts that our documentation may not adequately convey.
-
----
-
-### 2. Top 10 Validation Error Messages (with specific examples)
-
-These are the precise errors agents encounter. Each one represents a documentation opportunity:
-
-| Rank | Error Message | Count | Affected Users | Interpretation |
-|------|---------------|-------|---|---|
-| 1 | "Duplicate node ID: undefined" | 179 | 20 | **CRITICAL**: Agents generating invalid JSON or malformed workflow structures. Likely JSON parsing issues on LLM side. |
-| 2 | "Single-node workflows only valid for webhooks" | 58 | 47 | Agents don't understand webhook-only constraint. Need explicit documentation. |
-| 3 | "responseNode mode requires onError: 'continueRegularOutput'" | 57 | 33 | Webhook-specific configuration rule not obvious. **Error message is helpful but documentation missing context.** |
-| 4 | "Duplicate node name: undefined" | 61 | 6 | Related to #1—structural issues with node definitions. |
-| 5 | "Multi-node workflow has no connections" | 33 | 24 | Agents don't understand workflow connection syntax. **Need examples in documentation.** |
-| 6 | "Workflow contains a cycle (infinite loop)" | 33 | 19 | Agents not visualizing workflow topology before creating. |
-| 7 | "Required property 'Send Message To' cannot be empty" | 25 | 1 | Slack node properties not obvious from schema. |
-| 8 | "AI Agent requires ai_languageModel connection" | 22 | 15 | Missing documentation on AI node dependencies. |
-| 9 | "Node position must be array [x, y]" | 25 | 4 | Position format not specified in node documentation. |
-| 10 | "Invalid value for 'operation'. Must be one of: [list]" | 14 | 1 | Enum values not provided before validation. |
-
----
-
-### 3. Error Categories & Root Causes
-
-Breaking down all 4,898 validation details events into categories reveals the real problems:
-
-```
-Error Category Distribution:
-┌─────────────────────────────────┬───────────┬──────────┐
-│ Category                        │ Count     │ % of All │
-├─────────────────────────────────┼───────────┼──────────┤
-│ Other (workflow structure)       │ 1,268     │ 25.89%   │
-│ Connection/Linking Errors       │ 676       │ 13.80%   │
-│ Missing Required Field          │ 378       │ 7.72%    │
-│ Invalid Field Value/Enum        │ 202       │ 4.12%    │
-│ Error Handler Configuration     │ 148       │ 3.02%    │
-│ Invalid Position                │ 109       │ 2.23%    │
-│ Unknown Node Type               │ 88        │ 1.80%    │
-│ Missing typeVersion             │ 50        │ 1.02%    │
-├─────────────────────────────────┼───────────┼──────────┤
-│ SUBTOTAL (Top Issues)           │ 2,919     │ 59.60%   │
-│ All Other Errors                │ 1,979     │ 40.40%   │
-└─────────────────────────────────┴───────────┴──────────┘
-```
-
-### 3.1 Root Cause Analysis by Category
-
-**[25.89%] Workflow Structure Issues (1,268 errors)**
-- Undefined node IDs/names (likely JSON malformation)
-- Incorrect node position formats
-- Missing required workflow metadata
-- **ROOT CAUSE**: Agents constructing workflow JSON without proper schema understanding. Need better template examples and validation error context.
-
-**[13.80%] Connection/Linking Errors (676 errors)**
-- Multi-node workflows with no connections defined
-- Missing connection syntax in workflow definition
-- Error handler connection misconfigurations
-- **ROOT CAUSE**: Connection format is unintuitive. Sample workflows in documentation critically needed.
-
-**[7.72%] Missing Required Fields (378 errors)**
-- "Send Message To" for Slack
-- "Chat ID" for Telegram
-- "Title" for Google Docs
-- **ROOT CAUSE**: Required fields not clearly marked in `get_node_essentials()` response. Need explicit "REQUIRED" labeling.
-
-**[4.12%] Invalid Field Values/Enums (202 errors)**
-- Invalid "operation" selected
-- Invalid "select" value for choice fields
-- Wrong authentication method type
-- **ROOT CAUSE**: Enum options not provided in advance. Tool should return valid options BEFORE agent attempts configuration.
-
-**[3.02%] Error Handler Configuration (148 errors)**
-- ResponseNode mode setup
-- onError settings for async operations
-- Error output connections in wrong position
-- **ROOT CAUSE**: Error handling is complex; needs dedicated tutorial/examples in documentation.
-
----
-
-### 4. Tool Usage Pattern: Before Validation Failures
-
-This reveals what agents attempt BEFORE hitting errors:
-
-```
-Tools Used Before Failures (within 10 minutes):
-┌─────────────────────────────────────┬──────────┬────────┐
-│ Tool                                │ Count    │ Users  │
-├─────────────────────────────────────┼──────────┼────────┤
-│ search_nodes                        │ 320      │ 113    │ ← Most common
-│ get_node_essentials                 │ 177      │ 73     │ ← Documentation users
-│ validate_workflow                   │ 137      │ 47     │ ← Validation-checking
-│ tools_documentation                 │ 78       │ 67     │ ← Help-seeking
-│ n8n_update_partial_workflow         │ 72       │ 32     │ ← Fixing attempts
-├─────────────────────────────────────┼──────────┼────────┤
-│ INSIGHT: "search_nodes" (320) is    │          │        │
-│ 1.8x more common than              │          │        │
-│ "get_node_essentials" (177)         │          │        │
-└─────────────────────────────────────┴──────────┴────────┘
-```
-
-**Critical Insight**: Agents search for nodes before reading detailed documentation. They're trying to locate a node first, then attempt configuration without sufficient guidance. The search_nodes tool should provide better configuration hints.
-
----
-
-### 5. Search Queries Before Failures
-
-Most common search patterns when agents subsequently fail:
-
-| Query | Count | Users | Interpretation |
-|-------|-------|-------|---|
-| "webhook" | 34 | 16 | Generic search; 3.4min before failure |
-| "http request" | 32 | 20 | Generic search; 4.1min before failure |
-| "openai" | 23 | 7 | Generic search; 3.4min before failure |
-| "slack" | 16 | 9 | Generic search; 6.1min before failure |
-| "gmail" | 12 | 4 | Generic search; 0.1min before failure |
-| "telegram" | 10 | 10 | Generic search; 5.8min before failure |
-
-**Finding**: Searches are too generic. Agents search "webhook" then fail on "responseNode configuration"—they found the node but don't understand its specific requirements. Need **operation-specific search results**.
-
----
-
-### 6. Documentation Usage Impact
-
-Critical finding on effectiveness of reading documentation FIRST:
-
-```
-Documentation Impact Analysis:
-┌──────────────────────────────────┬───────────┬─────────┬──────────┐
-│ Group                            │ Total     │ Errors  │ Success  │
-│                                  │ Users     │ Rate    │ Rate     │
-├──────────────────────────────────┼───────────┼─────────┼──────────┤
-│ Read Documentation FIRST         │ 2,304     │ 12.6%   │ 87.4%    │
-│ Did NOT Read Documentation       │ 673       │ 10.8%   │ 89.2%    │
-└──────────────────────────────────┴───────────┴─────────┴──────────┘
-
-Result: Counter-intuitive!
-- Documentation readers have 1.8% HIGHER error rate
-- BUT they attempt MORE workflows (21,748 vs 3,869)
-- Interpretation: Advanced users read docs and attempt complex workflows
-```
-
-**Critical Implication**: Current documentation doesn't prevent errors. We need **better, more actionable documentation**, not just more documentation. Documentation should have:
-1. Clear required field callouts
-2. Example configurations
-3. Common pitfall warnings
-4. Operation-specific guidance
-
----
-
-### 7. Retry Success & Self-Correction
-
-**Excellent News**: Agents learn from validation errors immediately:
-
-```
-Same-Day Recovery Rate: 100% ✓
-
-Distribution of Successful Corrections:
-- Same day (within hours):         453 user-date pairs (100%)
-- Next day:                        108 user-date pairs (100%)
-- Within 2-3 days:                 67 user-date pairs (100%)
-- Within 4-7 days:                 33 user-date pairs (100%)
-
-Conclusion: ALL users who encounter validation errors subsequently
-           succeed in correcting them. Validation feedback works perfectly.
-           The system is teaching agents what's wrong.
-```
-
-**This validates the premise: Validation is not broken. Guidance is broken.**
-
----
-
-### 8. Property-Level Difficulty Matrix
-
-Which specific node properties cause the most confusion:
-
-**High-Difficulty Properties** (frequently empty/invalid):
-1. **Authentication fields** (universal across nodes)
-   - Missing/invalid credentials
-   - Wrong auth type selected
-
-2. **Operation/Action fields** (conditional requirements)
-   - Invalid enum selection
-   - No documentation of valid values
-
-3. **Connection-dependent fields** (webhook, AI nodes)
-   - Missing model selection (AI Agent)
-   - Missing error handler connection
-
-4. **Positional/structural fields**
-   - Node position array format
-   - Connection syntax
-
-5. **Required-but-optional-looking fields**
-   - "Send Message To" for Slack
-   - "Chat ID" for Telegram
-
-**Common Pattern**: Fields that are:
-- Conditional (visible only if other field = X)
-- Have complex validation (must be array of specific format)
-- Require external knowledge (valid enum values)
-
-...are the most error-prone.
-
----
-
-## Actionable Recommendations
-
-### PRIORITY 1: IMMEDIATE HIGH-IMPACT (Fixes 33% of errors)
-
-#### 1.1 Fix Webhook Configuration Documentation
-**Impact**: 127 failures, 40 unique users
-
-**Action Items**:
-- Create a dedicated "Webhook & Trigger Configuration" guide
-- Explicitly document the `responseNode mode` requires `onError: "continueRegularOutput"` rule
-- Provide before/after examples showing correct vs incorrect configuration
-- Add to `get_node_essentials()` for Webhook nodes: "⚠️ IMPORTANT: If using responseNode, add onError field"
-
-**SQL Query for Verification**:
-```sql
-SELECT
-  properties->>'nodeType' as node_type,
-  properties->'details'->>'message' as error_message,
-  COUNT(*) as count
-FROM telemetry_events
-WHERE event = 'validation_details'
-  AND properties->>'nodeType' IN ('Webhook', 'Webhook_Trigger')
-  AND created_at >= NOW() - INTERVAL '90 days'
-GROUP BY node_type, properties->'details'->>'message'
-ORDER BY count DESC;
-```
-
-**Expected Outcome**: 10-15% reduction in webhook-related failures
-
----
-
-#### 1.2 Fix Node Structure Error Messages
-**Impact**: 179 "Duplicate node ID: undefined" failures
-
-**Action Items**:
-1. When validation fails with "Duplicate node ID: undefined", provide:
-   - Exact line number in workflow JSON where the error occurs
-   - Example of correct node ID format
-   - Suggestion: "Did you forget the 'id' field in node definition?"
-
-2. Enhance `n8n_validate_workflow` to detect structural issues BEFORE attempting validation:
-   - Check all nodes have `id` field
-   - Check all nodes have `type` field
-   - Provide detailed structural report
-
-**Code Location**: `/src/services/workflow-validator.ts`
-
-**Expected Outcome**: 50-60% reduction in "undefined" node errors
-
----
-
-#### 1.3 Enhance Tool Responses with Required Field Callouts
-**Impact**: 378 "Missing required field" failures
-
-**Action Items**:
-1. Modify `get_node_essentials()` output to clearly mark REQUIRED fields:
-   ```
-   Before:
-   "properties": { "operation": {...} }
-
-   After:
-   "properties": {
-     "operation": {..., "required": true, "required_label": "⚠️ REQUIRED"}
-   }
-   ```
-
-2. In `validate_node_operation()` response, explicitly list:
-   - Which fields are required for this specific operation
-   - Which fields are conditional (depend on other field values)
-   - Example values for each field
-
-3. Add to tool documentation:
-   ```
-   get_node_essentials returns only essential properties.
-   For complete property list including all conditionals, use get_node_info().
-   ```
-
-**Code Location**: `/src/services/property-filter.ts`
-
-**Expected Outcome**: 60-70% reduction in "missing required field" errors
-
----
-
-### PRIORITY 2: MEDIUM-IMPACT (Fixes 25% of remaining errors)
-
-#### 2.1 Fix Workflow Connection Documentation
-**Impact**: 676 connection/linking errors, 429 unique node types
-
-**Action Items**:
-1. Create "Workflow Connections Explained" guide with:
-   - Diagram showing connection syntax
-   - Step-by-step connection building examples
-   - Common connection patterns (sequential, branching, error handling)
-
-2. Enhance error message for "Multi-node workflow has no connections":
-   ```
-   Before:
-   "Multi-node workflow has no connections.
-    Nodes must be connected to create a workflow..."
-
-   After:
-   "Multi-node workflow has no connections.
-    You created nodes: [list]
-    Add connections to link them. Example:
-    connections: {
-      'Node 1': { 'main': [[{ 'node': 'Node 2', 'type': 'main', 'index': 0 }]] }
-    }
-    For visual guide, see: [link to guide]"
-   ```
-
-3. Add sample workflow templates showing proper connections
-   - Simple: Trigger → Action
-   - Branching: If node splitting to multiple paths
-   - Error handling: Node with error catch
-
-**Code Location**: `/src/services/workflow-validator.ts` (error messages)
-
-**Expected Outcome**: 40-50% reduction in connection errors
-
----
-
-#### 2.2 Provide Valid Enum Values in Tool Responses
-**Impact**: 202 "Invalid value" errors for enum fields
-
-**Action Items**:
-1. Modify `validate_node_operation()` to return:
-   ```json
-   {
-     "success": false,
-     "errors": [{
-       "field": "operation",
-       "message": "Invalid value 'sendMsg' for operation",
-       "valid_options": [
-         "deleteMessage",
-         "editMessageText",
-         "sendMessage"
-       ],
-       "documentation": "https://..."
-     }]
-   }
-   ```
-
-2. In `get_node_essentials()`, for enum/choice fields, include:
-   ```json
-   "operation": {
-     "type": "choice",
-     "options": [
-       {"label": "Send Message", "value": "sendMessage"},
-       {"label": "Delete Message", "value": "deleteMessage"}
-     ]
-   }
-   ```
-
-**Code Location**: `/src/services/enhanced-config-validator.ts`
-
-**Expected Outcome**: 80%+ reduction in enum selection errors
-
----
-
-#### 2.3 Fix AI Agent Node Documentation
-**Impact**: 36 AI Agent failures, 20 unique users
-
-**Action Items**:
-1. Add prominent warning in `get_node_essentials()` for AI Agent:
-   ```
-   "⚠️ CRITICAL: AI Agent requires a language model connection.
-    You must add one of: OpenAI Chat Model, Anthropic Chat Model,
-    Google Gemini, or other LLM nodes before this node.
-    See example: [link]"
-   ```
-
-2. Create "Building AI Workflows" guide showing:
-   - Required model node placement
-   - Connection syntax for AI models
-   - Common model configuration
-
-3. Add validation check: AI Agent node must have incoming connection from an LLM node
-
-**Code Location**: `/src/services/node-specific-validators.ts`
-
-**Expected Outcome**: 80-90% reduction in AI Agent failures
-
----
-
-### PRIORITY 3: MEDIUM-IMPACT (Fixes remaining issues)
-
-#### 3.1 Improve Search Results Quality
-**Impact**: 320+ tool uses before failures; search too generic
-
-**Action Items**:
-1. When `search_nodes` finds a node, include:
-   - Top 3 most common operations for that node
-   - Most critical required fields
-   - Link to configuration guide
-   - Example workflow snippet
-
-2. Add operation-specific search:
-   ```
-   search_nodes("webhook trigger with validation")
-   → Returns Webhook node with:
-      - Best operations for your query
-      - Configuration guide for validation
-      - Error handler setup guide
-   ```
-
-**Code Location**: `/src/mcp/tools.ts` (search_nodes definition)
-
-**Expected Outcome**: 20-30% reduction in search-before-failure incidents
-
----
-
-#### 3.2 Enhance Error Handler Documentation
-**Impact**: 148 error handler configuration failures
-
-**Action Items**:
-1. Create dedicated "Error Handling in Workflows" guide:
-   - When to use error handlers
-   - `onError` options explained (continueRegularOutput vs continueErrorOutput)
-   - Connection positioning rules
-   - Complete working example
-
-2. Add validation error with visual explanation:
-   ```
-   Error: "Node X has onError: continueErrorOutput but no error
-           connections in main[1]"
-
-   Solution: Add error handler or change onError to 'continueRegularOutput'
-
-   INCORRECT:         CORRECT:
-   main[0]: [Node Y]  main[0]: [Node Y]
-                      main[1]: [Error Handler]
-   ```
-
-**Code Location**: `/src/services/workflow-validator.ts`
-
-**Expected Outcome**: 70%+ reduction in error handler failures
-
----
-
-#### 3.3 Create "Node Type Corrections" Guide
-**Impact**: 88 "Unknown node type" errors
-
-**Action Items**:
-1. Add helpful suggestions when unknown node type detected:
-   ```
-   Unknown node type: "nodes-base.googleDocsTool"
-
-   Did you mean one of these?
-   - nodes-base.googleDocs (87% match)
-   - nodes-base.googleSheets (72% match)
-
-   Node types must include package prefix: nodes-base.nodeName
-   ```
-
-2. Build fuzzy matcher for common node type mistakes
-
-**Code Location**: `/src/services/workflow-validator.ts`
-
-**Expected Outcome**: 70%+ reduction in unknown node type errors
-
----
-
-## Implementation Roadmap
-
-### Phase 1 (Weeks 1-2): Quick Wins
-- [ ] Fix Webhook documentation and error messages (1.1)
-- [ ] Enhance required field callouts in tools (1.3)
-- [ ] Improve error structure validation messages (1.2)
-
-**Expected Impact**: 25-30% reduction in validation failures
-
-### Phase 2 (Weeks 3-4): Documentation
-- [ ] Create "Workflow Connections" guide (2.1)
-- [ ] Create "Error Handling" guide (3.2)
-- [ ] Add enum value suggestions to tool responses (2.2)
-
-**Expected Impact**: Additional 15-20% reduction
-
-### Phase 3 (Weeks 5-6): Advanced Features
-- [ ] Enhance search results (3.1)
-- [ ] Add AI Agent node validation (2.3)
-- [ ] Create node type correction suggestions (3.3)
-
-**Expected Impact**: Additional 10-15% reduction
-
-### Target: 50-65% reduction in validation failures through better guidance
-
----
-
-## Measurement & Validation
-
-### KPIs to Track Post-Implementation
-
-1. **Validation Failure Rate**: Currently 12.6% for documentation users
-   - Target: 6-7% (50% reduction)
-
-2. **First-Attempt Success Rate**: Currently unknown, but retry success is 100%
-   - Target: 85%+ (measure in new telemetry)
-
-3. **Time to Valid Configuration**: Currently unknown
-   - Target: Measure and reduce by 30%
-
-4. **Tool Usage Before Failures**: Currently search_nodes dominates
-   - Target: Measure shift toward get_node_essentials/info
-
-5. **Specific Node Improvements**:
-   - Webhook: 127 → <30 failures (76% reduction)
-   - AI Agent: 36 → <5 failures (86% reduction)
-   - Slack: 101 → <20 failures (80% reduction)
-
-### SQL to Track Progress
-
-```sql
--- Monitor validation failure trends by node type
-SELECT
-  DATE(created_at) as date,
-  properties->>'nodeType' as node_type,
-  COUNT(*) as failure_count
-FROM telemetry_events
-WHERE event = 'validation_details'
-GROUP BY DATE(created_at), properties->>'nodeType'
-ORDER BY date DESC, failure_count DESC;
-
--- Monitor recovery rates
-WITH failures_then_success AS (
-  SELECT
-    user_id,
-    DATE(created_at) as failure_date,
-    COUNT(*) as failures,
-    SUM(CASE WHEN LEAD(event) OVER (PARTITION BY user_id ORDER BY created_at) = 'workflow_created' THEN 1 ELSE 0 END) as recovered
-  FROM telemetry_events
-  WHERE event = 'validation_details'
-    AND created_at >= NOW() - INTERVAL '7 days'
-  GROUP BY user_id, DATE(created_at)
-)
-SELECT
-  failure_date,
-  SUM(failures) as total_failures,
-  SUM(recovered) as immediate_recovery,
-  ROUND(100.0 * SUM(recovered) / NULLIF(SUM(failures), 0), 1) as recovery_rate_pct
-FROM failures_then_success
-GROUP BY failure_date
-ORDER BY failure_date DESC;
-```
-
----
-
-## Conclusion
-
-The n8n-mcp validation system is working perfectly—it catches errors and provides feedback that agents learn from instantly. The 29,218 validation events over 90 days are not a symptom of system failure; they're evidence that **the system is successfully preventing bad workflows from being deployed**.
-
-The challenge is not validation; it's **guidance quality**. Agents search for nodes but don't read complete documentation before attempting configuration. Our tools don't provide enough context about required fields, valid values, and connection syntax upfront.
-
-By implementing the recommendations above, focusing on:
-1. Clearer required field identification
-2. Better error messages with actionable solutions
-3. More comprehensive workflow structure documentation
-4. Valid enum values provided in advance
-5. Operation-specific configuration guides
-
-...we can reduce validation failures by 50-65% **without weakening validation**, enabling AI agents to configure workflows correctly on the first attempt while maintaining the safety guarantees our validation provides.
-
----
-
-## Appendix A: Complete Error Message Reference
-
-### Top 25 Unique Validation Messages (by frequency)
-
-1. **"Duplicate node ID: 'undefined'"** (179 occurrences)
-   - Root cause: JSON malformation or missing ID field
-   - Solution: Check node structure, ensure all nodes have `id` field
-
-2. **"Duplicate node name: 'undefined'"** (61 occurrences)
-   - Root cause: Missing or undefined node names
-   - Solution: All nodes must have unique non-empty `name` field
-
-3. **"Single-node workflows are only valid for webhook endpoints..."** (58 occurrences)
-   - Root cause: Single-node workflow without webhook
-   - Solution: Add trigger node or use webhook trigger
-
-4. **"responseNode mode requires onError: 'continueRegularOutput'"** (57 occurrences)
-   - Root cause: Webhook configured for response but missing error handling config
-   - Solution: Add `"onError": "continueRegularOutput"` to webhook node
-
-5. **"Workflow contains a cycle (infinite loop)"** (33 occurrences)
-   - Root cause: Circular workflow connections
-   - Solution: Redesign workflow to avoid cycles
-
-6. **"Multi-node workflow has no connections..."** (33 occurrences)
-   - Root cause: Multiple nodes created but not connected
-   - Solution: Add connections array to link nodes
-
-7. **"Required property 'Send Message To' cannot be empty"** (25 occurrences)
-   - Root cause: Slack node missing target channel/user
-   - Solution: Specify either channel or user
-
-8. **"Invalid value for 'select'. Must be one of: channel, user"** (25 occurrences)
-   - Root cause: Wrong enum value for Slack target
-   - Solution: Use either "channel" or "user"
-
-9. **"Node position must be an array with exactly 2 numbers [x, y]"** (25 occurrences)
-   - Root cause: Position not formatted as [x, y] array
-   - Solution: Format as `"position": [100, 200]`
-
-10. **"AI Agent 'AI Agent' requires an ai_languageModel connection..."** (22 occurrences)
-    - Root cause: AI Agent node created without language model
-    - Solution: Add LLM node and connect it
-
-[Additional messages follow same pattern...]
-
----
-
-## Appendix B: Data Quality Notes
-
-- **Data Source**: PostgreSQL Supabase database, `telemetry_events` table
-- **Sample Size**: 29,218 validation_details events from 9,021 unique users
-- **Time Period**: 43 days (Sept 26 - Nov 8, 2025)
-- **Data Quality**: 100% of validation events marked with `errorType: "error"`
-- **Limitations**:
-  - User IDs aggregated for privacy (individual user behavior not exposed)
-  - Workflow content sanitized (no actual code/credentials captured)
-  - Error categorization performed via pattern matching on error messages
-
----
-
-**Report Prepared**: November 8, 2025
-**Next Review Date**: November 22, 2025 (2-week progress check)
-**Responsible Team**: n8n-mcp Development Team

VALIDATION_ANALYSIS_SUMMARY.md

@@ -1,377 +0,0 @@
-# N8N-MCP Validation Analysis: Executive Summary
-
-**Date**: November 8, 2025 | **Period**: 90 days (Sept 26 - Nov 8) | **Data Quality**: ✓ Verified
-
----
-
-## One-Page Executive Summary
-
-### The Core Finding
-**Validation failures are NOT broken—they're evidence the system is working correctly.** 29,218 validation events prevented bad configurations from deploying to production. However, these events reveal **critical documentation and guidance gaps** that cause AI agents to misconfigure nodes.
-
----
-
-## Key Metrics at a Glance
-
-```
-VALIDATION HEALTH SCORECARD
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Metric                          Value           Status
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Total Validation Events         29,218          Normal
-Unique Users Affected           9,021           Normal
-First-Attempt Success Rate      ~77%*           ⚠️ Fixable
-Retry Success Rate              100%            ✓ Excellent
-Same-Day Recovery Rate          100%            ✓ Excellent
-Documentation Reader Error Rate 12.6%           ⚠️ High
-Non-Reader Error Rate           10.8%           ✓ Better
-
-* Estimated: 100% same-day retry success on 29,218 failures
-  suggests ~77% first-attempt success (29,218 + 21,748 = 50,966 total)
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
----
-
-## Top 3 Problem Areas (75% of all errors)
-
-### 1. Workflow Structure Issues (33.2%)
-**Symptoms**: "Duplicate node ID: undefined", malformed JSON, missing connections
-
-**Impact**: 1,268 errors across 791 unique node types
-
-**Root Cause**: Agents constructing workflow JSON without proper schema understanding
-
-**Quick Fix**: Better error messages pointing to exact location of structural issues
-
----
-
-### 2. Webhook & Trigger Configuration (6.7%)
-**Symptoms**: "responseNode requires onError", single-node workflows, connection rules
-
-**Impact**: 127 failures (47 users) specifically on webhook/trigger setup
-
-**Root Cause**: Complex configuration rules not obvious from documentation
-
-**Quick Fix**: Dedicated webhook guide + inline error messages with examples
-
----
-
-### 3. Required Fields (7.7%)
-**Symptoms**: "Required property X cannot be empty", missing Slack channel, missing AI model
-
-**Impact**: 378 errors; Agents don't know which fields are required
-
-**Root Cause**: Tool responses don't clearly mark required vs optional fields
-
-**Quick Fix**: Add required field indicators to `get_node_essentials()` output
-
----
-
-## Problem Nodes (Top 7)
-
-| Node | Failures | Users | Primary Issue |
-|------|----------|-------|---------------|
-| Webhook/Trigger | 127 | 40 | Error handler configuration rules |
-| Slack Notification | 73 | 2 | Missing "Send Message To" field |
-| AI Agent | 36 | 20 | Missing language model connection |
-| HTTP Request | 31 | 13 | Missing required parameters |
-| OpenAI | 35 | 8 | Authentication/model configuration |
-| Airtable | 41 | 1 | Required record fields |
-| Telegram | 27 | 1 | Operation enum selection |
-
-**Pattern**: Trigger/connector nodes and AI integrations are hardest to configure
-
----
-
-## Error Category Breakdown
-
-```
-What Goes Wrong (root cause distribution):
-┌────────────────────────────────────────┐
-│ Workflow structure (undefined IDs)  26% │ ■■■■■■■■■■■■
-│ Connection/linking errors          14% │ ■■■■■■
-│ Missing required fields             8% │ ■■■■
-│ Invalid enum values                 4% │ ■■
-│ Error handler configuration         3% │ ■
-│ Invalid position format             2% │ ■
-│ Unknown node types                  2% │ ■
-│ Missing typeVersion                 1% │
-│ All others                         40% │ ■■■■■■■■■■■■■■■■■■
-└────────────────────────────────────────┘
-```
-
----
-
-## Agent Behavior: Search Patterns
-
-**Agents search for nodes generically, then fail on specific configuration:**
-
-```
-Most Searched Terms (before failures):
-  "webhook" ................. 34x (failed on: responseNode config)
-  "http request" ............ 32x (failed on: missing required fields)
-  "openai" .................. 23x (failed on: model selection)
-  "slack" ................... 16x (failed on: missing channel/user)
-```
-
-**Insight**: Generic node searches don't help with configuration specifics. Agents need targeted guidance on each node's trickiest fields.
-
----
-
-## The Self-Correction Story (VERY POSITIVE)
-
-When agents get validation errors, they FIX THEM 100% of the time (same day):
-
-```
-Validation Error → Agent Action → Outcome
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Error event     → Uses feedback → Success
-(4,898 events)     (reads error)   (100%)
-
-Distribution of Corrections:
-  Within same hour ........ 453 cases (100% succeeded)
-  Within next day ......... 108 cases (100% succeeded)
-  Within 2-3 days ......... 67 cases (100% succeeded)
-  Within 4-7 days ......... 33 cases (100% succeeded)
-```
-
-**This proves validation messages are effective. Agents learn instantly. We just need BETTER messages.**
-
----
-
-## Documentation Impact (Surprising Finding)
-
-```
-Paradox: Documentation Readers Have HIGHER Error Rate!
-
-Documentation Readers:   2,304 users | 12.6% error rate | 87.4% success
-Non-Documentation:       673 users   | 10.8% error rate | 89.2% success
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Explanation: Doc readers attempt COMPLEX workflows (6.8x more attempts)
-            Simple workflows have higher natural success rate
-
-Action Item: Documentation should PREVENT errors, not just explain them
-            Need: Better structure, examples, required field callouts
-```
-
----
-
-## Critical Success Factors Discovered
-
-### What Works Well
-✓ Validation catches errors effectively
-✓ Error messages lead to quick fixes (100% same-day recovery)
-✓ Agents attempt workflows again after failures (persistence)
-✓ System prevents bad deployments
-
-### What Needs Improvement
-✗ Required fields not clearly marked in tool responses
-✗ Enum values not provided before validation
-✗ Workflow structure documentation lacks examples
-✗ Connection syntax unintuitive and not well-documented
-✗ Error messages could be more specific
-
----
-
-## Top 5 Recommendations (Priority Order)
-
-### 1. FIX WEBHOOK DOCUMENTATION (25-day impact)
-**Effort**: 1-2 days | **Impact**: 127 failures resolved | **ROI**: HIGH
-
-Create dedicated "Webhook Configuration Guide" explaining:
-- responseNode mode setup
-- onError requirements
-- Error handler connections
-- Working examples
-
----
-
-### 2. ENHANCE TOOL RESPONSES (2-3 days impact)
-**Effort**: 2-3 days | **Impact**: 378 failures resolved | **ROI**: HIGH
-
-Modify tools to output:
-```
-For get_node_essentials():
-  - Mark required fields with ⚠️ REQUIRED
-  - Include valid enum options
-  - Link to configuration guide
-
-For validate_node_operation():
-  - Show valid field values
-  - Suggest fixes for each error
-  - Provide contextual examples
-```
-
----
-
-### 3. IMPROVE WORKFLOW STRUCTURE ERRORS (5-7 days impact)
-**Effort**: 3-4 days | **Impact**: 1,268 errors resolved | **ROI**: HIGH
-
-- Better validation error messages pointing to exact issues
-- Suggest corrections ("Missing 'id' field in node definition")
-- Provide JSON structure examples
-
----
-
-### 4. CREATE CONNECTION DOCUMENTATION (3-4 days impact)
-**Effort**: 2-3 days | **Impact**: 676 errors resolved | **ROI**: MEDIUM
-
-Create "How to Connect Nodes" guide:
-- Connection syntax explained
-- Step-by-step workflow building
-- Common patterns (sequential, branching, error handling)
-- Visual diagrams
-
----
-
-### 5. ADD ERROR HANDLER GUIDE (2-3 days impact)
-**Effort**: 1-2 days | **Impact**: 148 errors resolved | **ROI**: MEDIUM
-
-Document error handling clearly:
-- When/how to use error handlers
-- onError options explained
-- Configuration examples
-- Common pitfalls
-
----
-
-## Implementation Impact Projection
-
-```
-Current State (Week 0):
-  - 29,218 validation failures (90-day sample)
-  - 12.6% error rate (documentation users)
-  - ~77% first-attempt success rate
-
-After Recommendations (Weeks 4-6):
-  ✓ Webhook issues: 127 → 30 (-76%)
-  ✓ Structure errors: 1,268 → 500 (-61%)
-  ✓ Required fields: 378 → 120 (-68%)
-  ✓ Connection issues: 676 → 340 (-50%)
-  ✓ Error handlers: 148 → 40 (-73%)
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Total Projected Impact: 50-65% reduction in validation failures
-  New error rate target: 6-7% (50% reduction)
-  First-attempt success: 77% → 85%+
-```
-
----
-
-## Files for Reference
-
-Full analysis with detailed recommendations:
-- **Main Report**: `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/VALIDATION_ANALYSIS_REPORT.md`
-- **This Summary**: `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/VALIDATION_ANALYSIS_SUMMARY.md`
-
-### SQL Queries Used (for reproducibility)
-
-#### Query 1: Overview
-```sql
-SELECT COUNT(*), COUNT(DISTINCT user_id), MIN(created_at), MAX(created_at)
-FROM telemetry_events
-WHERE event = 'workflow_validation_failed' AND created_at >= NOW() - INTERVAL '90 days';
-```
-
-#### Query 2: Top Error Messages
-```sql
-SELECT
-  properties->'details'->>'message' as error_message,
-  COUNT(*) as count,
-  COUNT(DISTINCT user_id) as affected_users
-FROM telemetry_events
-WHERE event = 'validation_details' AND created_at >= NOW() - INTERVAL '90 days'
-GROUP BY properties->'details'->>'message'
-ORDER BY count DESC
-LIMIT 25;
-```
-
-#### Query 3: Node-Specific Failures
-```sql
-SELECT
-  properties->>'nodeType' as node_type,
-  COUNT(*) as total_failures,
-  COUNT(DISTINCT user_id) as affected_users
-FROM telemetry_events
-WHERE event = 'validation_details' AND created_at >= NOW() - INTERVAL '90 days'
-GROUP BY properties->>'nodeType'
-ORDER BY total_failures DESC
-LIMIT 20;
-```
-
-#### Query 4: Retry Success Rate
-```sql
-WITH failures AS (
-  SELECT user_id, DATE(created_at) as failure_date
-  FROM telemetry_events WHERE event = 'validation_details'
-)
-SELECT
-  COUNT(DISTINCT f.user_id) as users_with_failures,
-  COUNT(DISTINCT w.user_id) as users_with_recovery_same_day,
-  ROUND(100.0 * COUNT(DISTINCT w.user_id) / COUNT(DISTINCT f.user_id), 1) as recovery_rate_pct
-FROM failures f
-LEFT JOIN telemetry_events w ON w.user_id = f.user_id
-  AND w.event = 'workflow_created'
-  AND DATE(w.created_at) = f.failure_date;
-```
-
-#### Query 5: Tool Usage Before Failures
-```sql
-WITH failures AS (
-  SELECT DISTINCT user_id, created_at FROM telemetry_events
-  WHERE event = 'validation_details' AND created_at >= NOW() - INTERVAL '90 days'
-)
-SELECT
-  te.properties->>'tool' as tool,
-  COUNT(*) as count_before_failure
-FROM telemetry_events te
-INNER JOIN failures f ON te.user_id = f.user_id
-  AND te.created_at < f.created_at AND te.created_at >= f.created_at - INTERVAL '10 minutes'
-WHERE te.event = 'tool_used'
-GROUP BY te.properties->>'tool'
-ORDER BY count DESC;
-```
-
----
-
-## Next Steps
-
-1. **Review this summary** with product team (30 min)
-2. **Prioritize recommendations** based on team capacity (30 min)
-3. **Assign work** for Priority 1 items (1-2 days effort)
-4. **Set up KPI tracking** for post-implementation measurement
-5. **Plan review cycle** for Nov 22 (2-week progress check)
-
----
-
-## Questions This Analysis Answers
-
-✓ Why do AI agents have so many validation failures?
-→ Documentation gaps + unclear required field marking + missing examples
-
-✓ Is validation working?
-→ YES, perfectly. 100% error recovery rate proves validation provides good feedback
-
-✓ Which nodes are hardest to configure?
-→ Webhooks (33), Slack (73), AI Agent (36), HTTP Request (31)
-
-✓ Do agents learn from validation errors?
-→ YES, 100% same-day recovery for all 29,218 failures
-
-✓ Does reading documentation help?
-→ Counterintuitively, it correlates with HIGHER error rates (but only because doc readers attempt complex workflows)
-
-✓ What's the single biggest source of errors?
-→ Workflow structure/JSON malformation (1,268 errors, 26% of total)
-
-✓ Can we reduce validation failures without weakening validation?
-→ YES, 50-65% reduction possible through documentation and guidance improvements alone
-
----
-
-**Report Status**: ✓ Complete | **Data Verified**: ✓ Yes | **Recommendations**: ✓ 5 Priority Items Identified
-
-**Prepared by**: N8N-MCP Telemetry Analysis
-**Date**: November 8, 2025
-**Confidence Level**: High (comprehensive 90-day dataset, 9,000+ users, 29,000+ events)

docs/SESSION_PERSISTENCE.md

@@ -0,0 +1,757 @@
+# Session Persistence API - Production Guide
+
+## Overview
+
+The Session Persistence API enables zero-downtime container deployments in multi-tenant n8n-mcp environments. It allows you to export active MCP session state before shutdown and restore it after restart, maintaining session continuity across container lifecycle events.
+
+**Version:** 2.24.1+
+**Status:** Production-ready
+**Use Cases:** Multi-tenant SaaS, Kubernetes deployments, container orchestration, rolling updates
+
+## Architecture
+
+### Session State Components
+
+Each persisted session contains:
+
+1. **Session Metadata**
+   - `sessionId`: Unique session identifier (UUID v4)
+   - `createdAt`: ISO 8601 timestamp of session creation
+   - `lastAccess`: ISO 8601 timestamp of last activity
+
+2. **Instance Context**
+   - `n8nApiUrl`: n8n instance API endpoint
+   - `n8nApiKey`: n8n API authentication key (plaintext)
+   - `instanceId`: Optional tenant/instance identifier
+   - `sessionId`: Optional session-specific identifier
+   - `metadata`: Optional custom application data
+
+3. **Dormant Session Pattern**
+   - Transport and MCP server objects are NOT persisted
+   - Recreated automatically on first request after restore
+   - Reduces memory footprint during restore
+
+## API Reference
+
+### N8NMCPEngine.exportSessionState()
+
+Exports all active session state for persistence before shutdown.
+
+```typescript
+exportSessionState(): SessionState[]
+```
+
+**Returns:** Array of session state objects containing metadata and credentials
+
+**Example:**
+```typescript
+const sessions = engine.exportSessionState();
+// sessions = [
+//   {
+//     sessionId: '550e8400-e29b-41d4-a716-446655440000',
+//     metadata: {
+//       createdAt: '2025-11-24T10:30:00.000Z',
+//       lastAccess: '2025-11-24T17:15:32.000Z'
+//     },
+//     context: {
+//       n8nApiUrl: 'https://tenant1.n8n.cloud',
+//       n8nApiKey: 'n8n_api_...',
+//       instanceId: 'tenant-123',
+//       metadata: { userId: 'user-456' }
+//     }
+//   }
+// ]
+```
+
+**Key Behaviors:**
+- Exports only non-expired sessions (within sessionTimeout)
+- Detects and warns about duplicate session IDs
+- Logs security event with session count
+- Returns empty array if no active sessions
+
+### N8NMCPEngine.restoreSessionState()
+
+Restores sessions from previously exported state after container restart.
+
+```typescript
+restoreSessionState(sessions: SessionState[]): number
+```
+
+**Parameters:**
+- `sessions`: Array of session state objects from `exportSessionState()`
+
+**Returns:** Number of sessions successfully restored
+
+**Example:**
+```typescript
+const sessions = await loadFromEncryptedStorage();
+const count = engine.restoreSessionState(sessions);
+console.log(`Restored ${count} sessions`);
+```
+
+**Key Behaviors:**
+- Validates session metadata (timestamps, required fields)
+- Skips expired sessions (age > sessionTimeout)
+- Skips duplicate sessions (idempotent)
+- Respects MAX_SESSIONS limit (100 per container)
+- Recreates transports/servers lazily on first request
+- Logs security events for restore success/failure
+
+## Security Considerations
+
+### Critical: Encrypt Before Storage
+
+**The exported session state contains plaintext n8n API keys.** You MUST encrypt this data before persisting to disk.
+
+```typescript
+// ❌ NEVER DO THIS
+await fs.writeFile('sessions.json', JSON.stringify(sessions));
+
+// ✅ ALWAYS ENCRYPT
+const encrypted = await encryptSessionData(sessions, encryptionKey);
+await saveToSecureStorage(encrypted);
+```
+
+### Recommended Encryption Approach
+
+```typescript
+import crypto from 'crypto';
+
+/**
+ * Encrypt session data using AES-256-GCM
+ */
+async function encryptSessionData(
+  sessions: SessionState[],
+  encryptionKey: Buffer
+): Promise<string> {
+  const iv = crypto.randomBytes(16);
+  const cipher = crypto.createCipheriv('aes-256-gcm', encryptionKey, iv);
+
+  const json = JSON.stringify(sessions);
+  const encrypted = Buffer.concat([
+    cipher.update(json, 'utf8'),
+    cipher.final()
+  ]);
+
+  const authTag = cipher.getAuthTag();
+
+  // Return base64: iv:authTag:encrypted
+  return [
+    iv.toString('base64'),
+    authTag.toString('base64'),
+    encrypted.toString('base64')
+  ].join(':');
+}
+
+/**
+ * Decrypt session data
+ */
+async function decryptSessionData(
+  encryptedData: string,
+  encryptionKey: Buffer
+): Promise<SessionState[]> {
+  const [ivB64, authTagB64, encryptedB64] = encryptedData.split(':');
+
+  const iv = Buffer.from(ivB64, 'base64');
+  const authTag = Buffer.from(authTagB64, 'base64');
+  const encrypted = Buffer.from(encryptedB64, 'base64');
+
+  const decipher = crypto.createDecipheriv('aes-256-gcm', encryptionKey, iv);
+  decipher.setAuthTag(authTag);
+
+  const decrypted = Buffer.concat([
+    decipher.update(encrypted),
+    decipher.final()
+  ]);
+
+  return JSON.parse(decrypted.toString('utf8'));
+}
+```
+
+### Key Management
+
+Store encryption keys securely:
+- **Kubernetes:** Use Kubernetes Secrets with encryption at rest
+- **AWS:** Use AWS Secrets Manager or Parameter Store with KMS
+- **Azure:** Use Azure Key Vault
+- **GCP:** Use Secret Manager
+- **Local Dev:** Use environment variables (NEVER commit to git)
+
+### Security Logging
+
+All session persistence operations are logged with `[SECURITY]` prefix:
+
+```
+[SECURITY] session_export { timestamp, count }
+[SECURITY] session_restore { timestamp, sessionId, instanceId }
+[SECURITY] session_restore_failed { timestamp, sessionId, reason }
+[SECURITY] max_sessions_reached { timestamp, count }
+```
+
+Monitor these logs in production for audit trails and security analysis.
+
+## Implementation Examples
+
+### 1. Express.js Multi-Tenant Backend
+
+```typescript
+import express from 'express';
+import { N8NMCPEngine } from 'n8n-mcp';
+
+const app = express();
+const engine = new N8NMCPEngine({
+  sessionTimeout: 1800000, // 30 minutes
+  logLevel: 'info'
+});
+
+// Startup: Restore sessions from encrypted storage
+async function startup() {
+  try {
+    const encrypted = await redis.get('mcp:sessions');
+    if (encrypted) {
+      const sessions = await decryptSessionData(
+        encrypted,
+        process.env.ENCRYPTION_KEY
+      );
+      const count = engine.restoreSessionState(sessions);
+      console.log(`Restored ${count} sessions`);
+    }
+  } catch (error) {
+    console.error('Failed to restore sessions:', error);
+  }
+}
+
+// Shutdown: Export sessions to encrypted storage
+async function shutdown() {
+  try {
+    const sessions = engine.exportSessionState();
+    const encrypted = await encryptSessionData(
+      sessions,
+      process.env.ENCRYPTION_KEY
+    );
+    await redis.set('mcp:sessions', encrypted, 'EX', 3600); // 1 hour TTL
+    console.log(`Exported ${sessions.length} sessions`);
+  } catch (error) {
+    console.error('Failed to export sessions:', error);
+  }
+
+  await engine.shutdown();
+  process.exit(0);
+}
+
+// Handle graceful shutdown
+process.on('SIGTERM', shutdown);
+process.on('SIGINT', shutdown);
+
+// Start server
+await startup();
+app.listen(3000);
+```
+
+### 2. Kubernetes Deployment with Init Container
+
+**deployment.yaml:**
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: n8n-mcp
+spec:
+  replicas: 3
+  strategy:
+    type: RollingUpdate
+    rollingUpdate:
+      maxUnavailable: 1
+      maxSurge: 1
+  template:
+    spec:
+      initContainers:
+      - name: restore-sessions
+        image: your-app:latest
+        command: ['/app/restore-sessions.sh']
+        env:
+        - name: ENCRYPTION_KEY
+          valueFrom:
+            secretKeyRef:
+              name: mcp-secrets
+              key: encryption-key
+        - name: REDIS_URL
+          valueFrom:
+            secretKeyRef:
+              name: mcp-secrets
+              key: redis-url
+        volumeMounts:
+        - name: sessions
+          mountPath: /sessions
+
+      containers:
+      - name: mcp-server
+        image: your-app:latest
+        lifecycle:
+          preStop:
+            exec:
+              command: ['/app/export-sessions.sh']
+        env:
+        - name: ENCRYPTION_KEY
+          valueFrom:
+            secretKeyRef:
+              name: mcp-secrets
+              key: encryption-key
+        - name: SESSION_TIMEOUT
+          value: "1800000"
+        volumeMounts:
+        - name: sessions
+          mountPath: /sessions
+
+        # Graceful shutdown configuration
+        terminationGracePeriodSeconds: 30
+
+      volumes:
+      - name: sessions
+        emptyDir: {}
+```
+
+**restore-sessions.sh:**
+```bash
+#!/bin/bash
+set -e
+
+echo "Restoring sessions from Redis..."
+
+# Fetch encrypted sessions from Redis
+ENCRYPTED=$(redis-cli -u "$REDIS_URL" GET "mcp:sessions:${HOSTNAME}")
+
+if [ -n "$ENCRYPTED" ]; then
+  echo "$ENCRYPTED" > /sessions/encrypted.txt
+  echo "Sessions fetched, will be restored on startup"
+else
+  echo "No sessions to restore"
+fi
+```
+
+**export-sessions.sh:**
+```bash
+#!/bin/bash
+set -e
+
+echo "Exporting sessions to Redis..."
+
+# Trigger session export via HTTP endpoint
+curl -X POST http://localhost:3000/internal/export-sessions
+
+echo "Sessions exported successfully"
+```
+
+### 3. Docker Compose with Redis
+
+**docker-compose.yml:**
+```yaml
+version: '3.8'
+
+services:
+  n8n-mcp:
+    build: .
+    environment:
+      - ENCRYPTION_KEY=${ENCRYPTION_KEY}
+      - REDIS_URL=redis://redis:6379
+      - SESSION_TIMEOUT=1800000
+    depends_on:
+      - redis
+    volumes:
+      - ./data:/data
+    deploy:
+      replicas: 2
+      update_config:
+        parallelism: 1
+        delay: 10s
+        order: start-first
+    stop_grace_period: 30s
+
+  redis:
+    image: redis:7-alpine
+    volumes:
+      - redis-data:/data
+    command: redis-server --appendonly yes
+
+volumes:
+  redis-data:
+```
+
+**Application code:**
+```typescript
+import { N8NMCPEngine } from 'n8n-mcp';
+import Redis from 'ioredis';
+
+const redis = new Redis(process.env.REDIS_URL);
+const engine = new N8NMCPEngine();
+
+// Export endpoint (called by preStop hook)
+app.post('/internal/export-sessions', async (req, res) => {
+  try {
+    const sessions = engine.exportSessionState();
+    const encrypted = await encryptSessionData(
+      sessions,
+      Buffer.from(process.env.ENCRYPTION_KEY, 'hex')
+    );
+
+    // Store with hostname as key for per-container tracking
+    await redis.set(
+      `mcp:sessions:${os.hostname()}`,
+      encrypted,
+      'EX',
+      3600
+    );
+
+    res.json({ exported: sessions.length });
+  } catch (error) {
+    console.error('Export failed:', error);
+    res.status(500).json({ error: 'Export failed' });
+  }
+});
+
+// Restore on startup
+async function startup() {
+  const encrypted = await redis.get(`mcp:sessions:${os.hostname()}`);
+  if (encrypted) {
+    const sessions = await decryptSessionData(
+      encrypted,
+      Buffer.from(process.env.ENCRYPTION_KEY, 'hex')
+    );
+    const count = engine.restoreSessionState(sessions);
+    console.log(`Restored ${count} sessions`);
+  }
+}
+```
+
+## Best Practices
+
+### 1. Session Timeout Configuration
+
+Choose appropriate timeout based on use case:
+
+```typescript
+const engine = new N8NMCPEngine({
+  sessionTimeout: 1800000  // 30 minutes (recommended default)
+});
+
+// Development: 5 minutes
+sessionTimeout: 300000
+
+// Production SaaS: 30-60 minutes
+sessionTimeout: 1800000 - 3600000
+
+// Long-running workflows: 2-4 hours
+sessionTimeout: 7200000 - 14400000
+```
+
+### 2. Storage Backend Selection
+
+**Redis (Recommended for Production)**
+- Fast read/write for session data
+- TTL support for automatic cleanup
+- Pub/sub for distributed coordination
+- Atomic operations for consistency
+
+**Database (PostgreSQL/MySQL)**
+- JSONB column for session state
+- Good for audit requirements
+- Slower than Redis
+- Requires periodic cleanup
+
+**S3/Cloud Storage**
+- Good for disaster recovery backups
+- Not suitable for hot session restore
+- High latency
+- Good for long-term session archival
+
+### 3. Monitoring and Alerting
+
+Monitor these metrics:
+
+```typescript
+// Session export metrics
+const sessions = engine.exportSessionState();
+metrics.gauge('mcp.sessions.exported', sessions.length);
+metrics.gauge('mcp.sessions.export_size_kb',
+  JSON.stringify(sessions).length / 1024
+);
+
+// Session restore metrics
+const restored = engine.restoreSessionState(sessions);
+metrics.gauge('mcp.sessions.restored', restored);
+metrics.gauge('mcp.sessions.restore_success_rate',
+  restored / sessions.length
+);
+
+// Runtime metrics
+const info = engine.getSessionInfo();
+metrics.gauge('mcp.sessions.active', info.active ? 1 : 0);
+metrics.gauge('mcp.sessions.age_seconds', info.age || 0);
+```
+
+Alert on:
+- Export failures (should be rare)
+- Low restore success rate (<95%)
+- MAX_SESSIONS limit reached
+- High session age (potential leaks)
+
+### 4. Graceful Shutdown Timing
+
+Ensure sufficient time for session export:
+
+```typescript
+// Kubernetes terminationGracePeriodSeconds
+terminationGracePeriodSeconds: 30  // 30 seconds minimum
+
+// Docker stop timeout
+docker run --stop-timeout 30 your-image
+
+// Process signal handling
+process.on('SIGTERM', async () => {
+  console.log('SIGTERM received, starting graceful shutdown...');
+
+  // 1. Stop accepting new requests (5s)
+  await server.close();
+
+  // 2. Wait for in-flight requests (10s)
+  await waitForInFlightRequests(10000);
+
+  // 3. Export sessions (5s)
+  const sessions = engine.exportSessionState();
+  await saveEncryptedSessions(sessions);
+
+  // 4. Cleanup (5s)
+  await engine.shutdown();
+
+  // 5. Exit (5s buffer)
+  process.exit(0);
+});
+```
+
+### 5. Idempotency Handling
+
+Sessions can be restored multiple times safely:
+
+```typescript
+// First restore
+const count1 = engine.restoreSessionState(sessions);
+// count1 = 5
+
+// Second restore (same sessions)
+const count2 = engine.restoreSessionState(sessions);
+// count2 = 0 (all already exist)
+```
+
+This is safe for:
+- Init container retries
+- Manual recovery operations
+- Disaster recovery scenarios
+
+### 6. Multi-Instance Coordination
+
+For multiple container instances:
+
+```typescript
+// Option 1: Per-instance storage (simple)
+const key = `mcp:sessions:${instance.hostname}`;
+
+// Option 2: Centralized with distributed lock (advanced)
+const lock = await acquireLock('mcp:session-export');
+try {
+  const allSessions = await getAllInstanceSessions();
+  await saveToBackup(allSessions);
+} finally {
+  await lock.release();
+}
+```
+
+## Performance Considerations
+
+### Memory Usage
+
+```typescript
+// Each session: ~1-2 KB in memory
+// 100 sessions: ~100-200 KB
+// 1000 sessions: ~1-2 MB
+
+// Export serialized size
+const sessions = engine.exportSessionState();
+const sizeKB = JSON.stringify(sessions).length / 1024;
+console.log(`Export size: ${sizeKB.toFixed(2)} KB`);
+```
+
+### Export/Restore Speed
+
+```typescript
+// Export: O(n) where n = active sessions
+// Typical: 50-100 sessions in <10ms
+
+// Restore: O(n) with validation
+// Typical: 50-100 sessions in 20-50ms
+
+// Factor in encryption:
+// AES-256-GCM: ~1ms per 100 sessions
+```
+
+### MAX_SESSIONS Limit
+
+Hard limit: 100 sessions per container
+
+```typescript
+// Restore respects limit
+const sessions = createSessions(150); // 150 sessions
+const restored = engine.restoreSessionState(sessions);
+// restored = 100 (only first 100 restored)
+```
+
+For >100 sessions per tenant:
+- Deploy multiple containers
+- Use session routing/sharding
+- Implement session affinity
+
+## Troubleshooting
+
+### Issue: No sessions restored
+
+**Symptoms:**
+```
+Restored 0 sessions
+```
+
+**Causes:**
+1. All sessions expired (age > sessionTimeout)
+2. Invalid date format in metadata
+3. Missing required context fields
+
+**Debug:**
+```typescript
+const sessions = await loadFromEncryptedStorage();
+console.log('Loaded sessions:', sessions.length);
+
+// Check individual sessions
+sessions.forEach((s, i) => {
+  const age = Date.now() - new Date(s.metadata.lastAccess).getTime();
+  console.log(`Session ${i}: age=${age}ms, expired=${age > sessionTimeout}`);
+});
+```
+
+### Issue: Restore fails with "invalid context"
+
+**Symptoms:**
+```
+[SECURITY] session_restore_failed { sessionId: '...', reason: 'invalid context: ...' }
+```
+
+**Causes:**
+1. Missing n8nApiUrl or n8nApiKey
+2. Invalid URL format
+3. Corrupted session data
+
+**Fix:**
+```typescript
+// Validate before restore
+const valid = sessions.filter(s => {
+  if (!s.context?.n8nApiUrl || !s.context?.n8nApiKey) {
+    console.warn(`Invalid session ${s.sessionId}: missing credentials`);
+    return false;
+  }
+  try {
+    new URL(s.context.n8nApiUrl); // Validate URL
+    return true;
+  } catch {
+    console.warn(`Invalid session ${s.sessionId}: malformed URL`);
+    return false;
+  }
+});
+
+const count = engine.restoreSessionState(valid);
+```
+
+### Issue: MAX_SESSIONS limit hit
+
+**Symptoms:**
+```
+Reached MAX_SESSIONS limit (100), skipping remaining sessions
+```
+
+**Solutions:**
+
+1. Scale horizontally (more containers)
+2. Implement session sharding
+3. Reduce sessionTimeout
+4. Clean up inactive sessions
+
+```typescript
+// Pre-filter by activity
+const recentSessions = sessions.filter(s => {
+  const age = Date.now() - new Date(s.metadata.lastAccess).getTime();
+  return age < 600000; // Only restore sessions active in last 10 min
+});
+
+const count = engine.restoreSessionState(recentSessions);
+```
+
+### Issue: Duplicate session IDs
+
+**Symptoms:**
+```
+Duplicate sessionId detected during export: 550e8400-...
+```
+
+**Cause:** Bug in session management logic
+
+**Fix:** This is a warning, not an error. The duplicate is automatically skipped. If persistent, investigate session creation logic.
+
+### Issue: High memory usage after restore
+
+**Symptoms:** Container OOM after restoring many sessions
+
+**Cause:** Too many sessions for container resources
+
+**Solution:**
+```typescript
+// Restore in batches
+async function restoreInBatches(sessions: SessionState[], batchSize = 25) {
+  let totalRestored = 0;
+
+  for (let i = 0; i < sessions.length; i += batchSize) {
+    const batch = sessions.slice(i, i + batchSize);
+    const count = engine.restoreSessionState(batch);
+    totalRestored += count;
+
+    // Wait for GC between batches
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+
+  return totalRestored;
+}
+```
+
+## Version Compatibility
+
+| Feature | Version | Status |
+|---------|---------|--------|
+| exportSessionState() | 2.3.0+ | Stable |
+| restoreSessionState() | 2.3.0+ | Stable |
+| Security logging | 2.24.1+ | Stable |
+| Duplicate detection | 2.24.1+ | Stable |
+| Race condition fix | 2.24.1+ | Stable |
+| Date validation | 2.24.1+ | Stable |
+| Optional instanceId | 2.24.1+ | Stable |
+
+## Additional Resources
+
+- [HTTP Deployment Guide](./HTTP_DEPLOYMENT.md) - Multi-tenant HTTP server setup
+- [Library Usage Guide](./LIBRARY_USAGE.md) - Embedding n8n-mcp in your app
+- [Docker Guide](./DOCKER_README.md) - Container deployment
+- [Flexible Instance Configuration](./FLEXIBLE_INSTANCE_CONFIGURATION.md) - Multi-tenant patterns
+
+## Support
+
+For issues or questions:
+- GitHub Issues: https://github.com/czlonkowski/n8n-mcp/issues
+- Documentation: https://github.com/czlonkowski/n8n-mcp#readme
+
+---
+
+Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en

docs/TYPE_STRUCTURE_VALIDATION.md

@@ -0,0 +1,239 @@
+# Type Structure Validation
+
+## Overview
+
+Type Structure Validation is an automatic validation system that ensures complex n8n node configurations conform to their expected data structures. Implemented as part of the n8n-mcp validation system, it provides zero-configuration validation for special n8n types that have complex nested structures.
+
+**Status:** Production (v2.22.21+)
+**Performance:** 100% pass rate on 776 real-world validations
+**Speed:** 0.01ms average validation time (500x faster than target)
+
+The system automatically validates node configurations without requiring any additional setup or configuration from users or AI assistants.
+
+## Supported Types
+
+The validation system supports four special n8n types that have complex structures:
+
+### 1. **filter** (FilterValue)
+Complex filtering conditions with boolean operators, comparison operations, and nested logic.
+
+**Structure:**
+- `combinator`: "and" | "or" - How conditions are combined
+- `conditions`: Array of filter conditions
+  - Each condition has: `leftValue`, `operator` (type + operation), `rightValue`
+  - Supports 40+ operations: equals, contains, exists, notExists, gt, lt, regex, etc.
+
+**Example Usage:** IF node, Switch node condition filtering
+
+### 2. **resourceMapper** (ResourceMapperValue)
+Data mapping configuration for transforming data between different formats.
+
+**Structure:**
+- `mappingMode`: "defineBelow" | "autoMapInputData" | "mapManually"
+- `value`: Field mappings or expressions
+- `matchingColumns`: Column matching configuration
+- `schema`: Target schema definition
+
+**Example Usage:** Google Sheets node, Airtable node data mapping
+
+### 3. **assignmentCollection** (AssignmentCollectionValue)
+Variable assignments for setting multiple values at once.
+
+**Structure:**
+- `assignments`: Array of name-value pairs
+  - Each assignment has: `name`, `value`, `type`
+
+**Example Usage:** Set node, Code node variable assignments
+
+### 4. **resourceLocator** (INodeParameterResourceLocator)
+Resource selection with multiple lookup modes (ID, name, URL, etc.).
+
+**Structure:**
+- `mode`: "id" | "list" | "url" | "name"
+- `value`: Resource identifier (string, number, or expression)
+- `cachedResultName`: Optional cached display name
+- `cachedResultUrl`: Optional cached URL
+
+**Example Usage:** Google Sheets spreadsheet selection, Slack channel selection
+
+## Performance & Results
+
+The validation system was tested against real-world n8n.io workflow templates:
+
+| Metric | Result |
+|--------|--------|
+| **Templates Tested** | 91 (top by popularity) |
+| **Nodes Validated** | 616 nodes with special types |
+| **Total Validations** | 776 property validations |
+| **Pass Rate** | 100.00% (776/776) |
+| **False Positive Rate** | 0.00% |
+| **Average Time** | 0.01ms per validation |
+| **Max Time** | 1.00ms per validation |
+| **Performance vs Target** | 500x faster than 50ms target |
+
+### Type-Specific Results
+
+- `filter`: 93/93 passed (100.00%)
+- `resourceMapper`: 69/69 passed (100.00%)
+- `assignmentCollection`: 213/213 passed (100.00%)
+- `resourceLocator`: 401/401 passed (100.00%)
+
+## How It Works
+
+### Automatic Integration
+
+Structure validation is automatically applied during node configuration validation. When you call `validate_node_operation` or `validate_node_minimal`, the system:
+
+1. **Identifies Special Types**: Detects properties that use filter, resourceMapper, assignmentCollection, or resourceLocator types
+2. **Validates Structure**: Checks that the configuration matches the expected structure for that type
+3. **Validates Operations**: For filter types, validates that operations are supported for the data type
+4. **Provides Context**: Returns specific error messages with property paths and fix suggestions
+
+### Validation Flow
+
+```
+User/AI provides node config
+        ↓
+validate_node_operation (MCP tool)
+        ↓
+EnhancedConfigValidator.validateWithMode()
+        ↓
+validateSpecialTypeStructures() ← Automatic structure validation
+        ↓
+TypeStructureService.validateStructure()
+        ↓
+Returns validation result with errors/warnings/suggestions
+```
+
+### Edge Cases Handled
+
+**1. Credential-Provided Fields**
+- Fields like Google Sheets `sheetId` that come from n8n credentials at runtime are excluded from validation
+- No false positives for fields that aren't in the configuration
+
+**2. Filter Operations**
+- Universal operations (`exists`, `notExists`, `isNotEmpty`) work across all data types
+- Type-specific operations validated (e.g., `regex` only for strings, `gt`/`lt` only for numbers)
+
+**3. Node-Specific Logic**
+- Custom validation logic for specific nodes (Google Sheets, Slack, etc.)
+- Context-aware error messages that understand the node's operation
+
+## Example Validation Error
+
+### Invalid Filter Structure
+
+**Configuration:**
+```json
+{
+  "conditions": {
+    "combinator": "and",
+    "conditions": [
+      {
+        "leftValue": "={{ $json.status }}",
+        "rightValue": "active",
+        "operator": {
+          "type": "string",
+          "operation": "invalidOperation"  // ❌ Not a valid operation
+        }
+      }
+    ]
+  }
+}
+```
+
+**Validation Error:**
+```json
+{
+  "valid": false,
+  "errors": [
+    {
+      "type": "invalid_structure",
+      "property": "conditions.conditions[0].operator.operation",
+      "message": "Unsupported operation 'invalidOperation' for type 'string'",
+      "suggestion": "Valid operations for string: equals, notEquals, contains, notContains, startsWith, endsWith, regex, exists, notExists, isNotEmpty"
+    }
+  ]
+}
+```
+
+## Technical Details
+
+### Implementation
+
+- **Type Definitions**: `src/types/type-structures.ts` (301 lines)
+- **Type Structures**: `src/constants/type-structures.ts` (741 lines, 22 complete type structures)
+- **Service Layer**: `src/services/type-structure-service.ts` (427 lines)
+- **Validator Integration**: `src/services/enhanced-config-validator.ts` (line 270)
+- **Node-Specific Logic**: `src/services/node-specific-validators.ts`
+
+### Test Coverage
+
+- **Unit Tests**:
+  - `tests/unit/types/type-structures.test.ts` (14 tests)
+  - `tests/unit/constants/type-structures.test.ts` (39 tests)
+  - `tests/unit/services/type-structure-service.test.ts` (64 tests)
+  - `tests/unit/services/enhanced-config-validator-type-structures.test.ts`
+
+- **Integration Tests**:
+  - `tests/integration/validation/real-world-structure-validation.test.ts` (8 tests, 388ms)
+
+- **Validation Scripts**:
+  - `scripts/test-structure-validation.ts` - Standalone validation against 100 templates
+
+### Documentation
+
+- **Implementation Plan**: `docs/local/v3/implementation-plan-final.md` - Complete technical specifications
+- **Phase Results**: Phases 1-3 completed with 100% success criteria met
+
+## For Developers
+
+### Adding New Type Structures
+
+1. Define the type structure in `src/constants/type-structures.ts`
+2. Add validation logic in `TypeStructureService.validateStructure()`
+3. Add tests in `tests/unit/constants/type-structures.test.ts`
+4. Test against real templates using `scripts/test-structure-validation.ts`
+
+### Testing Structure Validation
+
+**Run Unit Tests:**
+```bash
+npm run test:unit -- tests/unit/services/enhanced-config-validator-type-structures.test.ts
+```
+
+**Run Integration Tests:**
+```bash
+npm run test:integration -- tests/integration/validation/real-world-structure-validation.test.ts
+```
+
+**Run Full Validation:**
+```bash
+npm run test:structure-validation
+```
+
+### Relevant Test Files
+
+- **Type Tests**: `tests/unit/types/type-structures.test.ts`
+- **Structure Tests**: `tests/unit/constants/type-structures.test.ts`
+- **Service Tests**: `tests/unit/services/type-structure-service.test.ts`
+- **Validator Tests**: `tests/unit/services/enhanced-config-validator-type-structures.test.ts`
+- **Integration Tests**: `tests/integration/validation/real-world-structure-validation.test.ts`
+- **Real-World Validation**: `scripts/test-structure-validation.ts`
+
+## Production Readiness
+
+✅ **All Tests Passing**: 100% pass rate on unit and integration tests
+✅ **Performance Validated**: 0.01ms average (500x better than 50ms target)
+✅ **Zero Breaking Changes**: Fully backward compatible
+✅ **Real-World Validation**: 91 templates, 616 nodes, 776 validations
+✅ **Production Deployment**: Successfully deployed in v2.22.21
+✅ **Edge Cases Handled**: Credential fields, filter operations, node-specific logic
+
+## Version History
+
+- **v2.22.21** (2025-11-21): Type structure validation system completed (Phases 1-3)
+  - 22 complete type structures defined
+  - 100% pass rate on real-world validation
+  - 0.01ms average validation time
+  - Zero false positives

docs/migrations/workflow_mutations_schema.sql

@@ -1,165 +0,0 @@
--- Migration: Create workflow_mutations table for tracking partial update operations
--- Purpose: Capture workflow transformation data to improve partial updates tooling
--- Date: 2025-01-12
-
--- Create workflow_mutations table
-CREATE TABLE IF NOT EXISTS workflow_mutations (
-  -- Primary key
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-
-  -- User identification (anonymized)
-  user_id TEXT NOT NULL,
-  session_id TEXT NOT NULL,
-
-  -- Workflow snapshots (compressed JSONB)
-  workflow_before JSONB NOT NULL,
-  workflow_after JSONB NOT NULL,
-  workflow_hash_before TEXT NOT NULL,
-  workflow_hash_after TEXT NOT NULL,
-
-  -- Intent capture
-  user_intent TEXT NOT NULL,
-  intent_classification TEXT,
-  tool_name TEXT NOT NULL CHECK (tool_name IN ('n8n_update_partial_workflow', 'n8n_update_full_workflow')),
-
-  -- Operations performed
-  operations JSONB NOT NULL,
-  operation_count INTEGER NOT NULL CHECK (operation_count >= 0),
-  operation_types TEXT[] NOT NULL,
-
-  -- Validation metrics
-  validation_before JSONB,
-  validation_after JSONB,
-  validation_improved BOOLEAN,
-  errors_resolved INTEGER DEFAULT 0 CHECK (errors_resolved >= 0),
-  errors_introduced INTEGER DEFAULT 0 CHECK (errors_introduced >= 0),
-
-  -- Change metrics
-  nodes_added INTEGER DEFAULT 0 CHECK (nodes_added >= 0),
-  nodes_removed INTEGER DEFAULT 0 CHECK (nodes_removed >= 0),
-  nodes_modified INTEGER DEFAULT 0 CHECK (nodes_modified >= 0),
-  connections_added INTEGER DEFAULT 0 CHECK (connections_added >= 0),
-  connections_removed INTEGER DEFAULT 0 CHECK (connections_removed >= 0),
-  properties_changed INTEGER DEFAULT 0 CHECK (properties_changed >= 0),
-
-  -- Outcome tracking
-  mutation_success BOOLEAN NOT NULL,
-  mutation_error TEXT,
-
-  -- Performance metrics
-  duration_ms INTEGER CHECK (duration_ms >= 0),
-
-  -- Timestamps
-  created_at TIMESTAMPTZ DEFAULT NOW()
-);
-
--- Create indexes for efficient querying
-
--- Primary indexes for filtering
-CREATE INDEX IF NOT EXISTS idx_workflow_mutations_user_id
-  ON workflow_mutations(user_id);
-
-CREATE INDEX IF NOT EXISTS idx_workflow_mutations_session_id
-  ON workflow_mutations(session_id);
-
-CREATE INDEX IF NOT EXISTS idx_workflow_mutations_created_at
-  ON workflow_mutations(created_at DESC);
-
--- Intent and classification indexes
-CREATE INDEX IF NOT EXISTS idx_workflow_mutations_intent_classification
-  ON workflow_mutations(intent_classification)
-  WHERE intent_classification IS NOT NULL;
-
-CREATE INDEX IF NOT EXISTS idx_workflow_mutations_tool_name
-  ON workflow_mutations(tool_name);
-
--- Operation analysis indexes
-CREATE INDEX IF NOT EXISTS idx_workflow_mutations_operation_types
-  ON workflow_mutations USING GIN(operation_types);
-
-CREATE INDEX IF NOT EXISTS idx_workflow_mutations_operation_count
-  ON workflow_mutations(operation_count);
-
--- Outcome indexes
-CREATE INDEX IF NOT EXISTS idx_workflow_mutations_success
-  ON workflow_mutations(mutation_success);
-
-CREATE INDEX IF NOT EXISTS idx_workflow_mutations_validation_improved
-  ON workflow_mutations(validation_improved)
-  WHERE validation_improved IS NOT NULL;
-
--- Change metrics indexes
-CREATE INDEX IF NOT EXISTS idx_workflow_mutations_nodes_added
-  ON workflow_mutations(nodes_added)
-  WHERE nodes_added > 0;
-
-CREATE INDEX IF NOT EXISTS idx_workflow_mutations_nodes_modified
-  ON workflow_mutations(nodes_modified)
-  WHERE nodes_modified > 0;
-
--- Hash indexes for deduplication
-CREATE INDEX IF NOT EXISTS idx_workflow_mutations_hash_before
-  ON workflow_mutations(workflow_hash_before);
-
-CREATE INDEX IF NOT EXISTS idx_workflow_mutations_hash_after
-  ON workflow_mutations(workflow_hash_after);
-
--- Composite indexes for common queries
-
--- Find successful mutations by intent classification
-CREATE INDEX IF NOT EXISTS idx_workflow_mutations_success_classification
-  ON workflow_mutations(mutation_success, intent_classification)
-  WHERE intent_classification IS NOT NULL;
-
--- Find mutations that improved validation
-CREATE INDEX IF NOT EXISTS idx_workflow_mutations_validation_success
-  ON workflow_mutations(validation_improved, mutation_success)
-  WHERE validation_improved IS TRUE;
-
--- Find mutations by user and time range
-CREATE INDEX IF NOT EXISTS idx_workflow_mutations_user_time
-  ON workflow_mutations(user_id, created_at DESC);
-
--- Find mutations with significant changes (expression index)
-CREATE INDEX IF NOT EXISTS idx_workflow_mutations_significant_changes
-  ON workflow_mutations((nodes_added + nodes_removed + nodes_modified))
-  WHERE (nodes_added + nodes_removed + nodes_modified) > 0;
-
--- Comments for documentation
-COMMENT ON TABLE workflow_mutations IS
-  'Tracks workflow mutations from partial update operations to analyze transformation patterns and improve tooling';
-
-COMMENT ON COLUMN workflow_mutations.workflow_before IS
-  'Complete workflow JSON before mutation (sanitized, credentials removed)';
-
-COMMENT ON COLUMN workflow_mutations.workflow_after IS
-  'Complete workflow JSON after mutation (sanitized, credentials removed)';
-
-COMMENT ON COLUMN workflow_mutations.user_intent IS
-  'User instruction or intent for the workflow change (sanitized for PII)';
-
-COMMENT ON COLUMN workflow_mutations.intent_classification IS
-  'Classified pattern: add_functionality, modify_configuration, rewire_logic, fix_validation, cleanup, unknown';
-
-COMMENT ON COLUMN workflow_mutations.operations IS
-  'Array of diff operations performed (addNode, updateNode, addConnection, etc.)';
-
-COMMENT ON COLUMN workflow_mutations.validation_improved IS
-  'Whether the mutation reduced validation errors (NULL if validation data unavailable)';
-
--- Row-level security
-ALTER TABLE workflow_mutations ENABLE ROW LEVEL SECURITY;
-
--- Create policy for anonymous inserts (required for telemetry)
-CREATE POLICY "Allow anonymous inserts"
-  ON workflow_mutations
-  FOR INSERT
-  TO anon
-  WITH CHECK (true);
-
--- Create policy for authenticated reads (for analysis)
-CREATE POLICY "Allow authenticated reads"
-  ON workflow_mutations
-  FOR SELECT
-  TO authenticated
-  USING (true);

package.json

@@ -1,6 +1,6 @@
 {
   "name": "n8n-mcp",
-  "version": "2.22.16",
+  "version": "2.27.0",
   "description": "Integration between n8n workflow automation and Model Context Protocol (MCP)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -66,6 +66,7 @@
     "test:workflow-diff": "node dist/scripts/test-workflow-diff.js",
     "test:transactional-diff": "node dist/scripts/test-transactional-diff.js",
     "test:tools-documentation": "node dist/scripts/test-tools-documentation.js",
+    "test:structure-validation": "npx tsx scripts/test-structure-validation.ts",
     "test:url-configuration": "npm run build && ts-node scripts/test-url-configuration.ts",
     "test:search-improvements": "node dist/scripts/test-search-improvements.js",
     "test:fts5-search": "node dist/scripts/test-fts5-search.js",
@@ -139,21 +140,21 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.20.1",
-    "@n8n/n8n-nodes-langchain": "^1.118.0",
+    "@modelcontextprotocol/sdk": "1.20.1",
+    "@n8n/n8n-nodes-langchain": "^1.120.1",
     "@supabase/supabase-js": "^2.57.4",
     "dotenv": "^16.5.0",
     "express": "^5.1.0",
     "express-rate-limit": "^7.1.5",
     "lru-cache": "^11.2.1",
-    "n8n": "^1.119.1",
-    "n8n-core": "^1.118.0",
-    "n8n-workflow": "^1.116.0",
+    "n8n": "^1.121.2",
+    "n8n-core": "^1.120.1",
+    "n8n-workflow": "^1.118.1",
     "openai": "^4.77.0",
     "sql.js": "^1.13.0",
     "tslib": "^2.6.2",
     "uuid": "^10.0.0",
-    "zod": "^3.24.1"
+    "zod": "3.24.1"
   },
   "optionalDependencies": {
     "@rollup/rollup-darwin-arm64": "^4.50.0",

package.runtime.json

@@ -1,6 +1,6 @@
 {
   "name": "n8n-mcp-runtime",
-  "version": "2.22.16",
+  "version": "2.26.4",
   "description": "n8n MCP Server Runtime Dependencies Only",
   "private": true,
   "dependencies": {

scripts/backfill-mutation-hashes.ts

@@ -0,0 +1,192 @@
+/**
+ * Backfill script to populate structural hashes for existing workflow mutations
+ *
+ * Purpose: Generates workflow_structure_hash_before and workflow_structure_hash_after
+ *          for all existing mutations to enable cross-referencing with telemetry_workflows
+ *
+ * Usage: npx tsx scripts/backfill-mutation-hashes.ts
+ *
+ * Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
+ */
+
+import { WorkflowSanitizer } from '../src/telemetry/workflow-sanitizer.js';
+import { createClient } from '@supabase/supabase-js';
+
+// Initialize Supabase client
+const supabaseUrl = process.env.SUPABASE_URL || '';
+const supabaseKey = process.env.SUPABASE_SERVICE_ROLE_KEY || '';
+
+if (!supabaseUrl || !supabaseKey) {
+  console.error('Error: SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY environment variables are required');
+  process.exit(1);
+}
+
+const supabase = createClient(supabaseUrl, supabaseKey);
+
+interface MutationRecord {
+  id: string;
+  workflow_before: any;
+  workflow_after: any;
+  workflow_structure_hash_before: string | null;
+  workflow_structure_hash_after: string | null;
+}
+
+/**
+ * Fetch all mutations that need structural hashes
+ */
+async function fetchMutationsToBackfill(): Promise<MutationRecord[]> {
+  console.log('Fetching mutations without structural hashes...');
+
+  const { data, error } = await supabase
+    .from('workflow_mutations')
+    .select('id, workflow_before, workflow_after, workflow_structure_hash_before, workflow_structure_hash_after')
+    .is('workflow_structure_hash_before', null);
+
+  if (error) {
+    throw new Error(`Failed to fetch mutations: ${error.message}`);
+  }
+
+  console.log(`Found ${data?.length || 0} mutations to backfill`);
+  return data || [];
+}
+
+/**
+ * Generate structural hash for a workflow
+ */
+function generateStructuralHash(workflow: any): string {
+  try {
+    return WorkflowSanitizer.generateWorkflowHash(workflow);
+  } catch (error) {
+    console.error('Error generating hash:', error);
+    return '';
+  }
+}
+
+/**
+ * Update a single mutation with structural hashes
+ */
+async function updateMutation(id: string, structureHashBefore: string, structureHashAfter: string): Promise<boolean> {
+  const { error } = await supabase
+    .from('workflow_mutations')
+    .update({
+      workflow_structure_hash_before: structureHashBefore,
+      workflow_structure_hash_after: structureHashAfter,
+    })
+    .eq('id', id);
+
+  if (error) {
+    console.error(`Failed to update mutation ${id}:`, error.message);
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Process mutations in batches
+ */
+async function backfillMutations() {
+  const startTime = Date.now();
+  console.log('Starting backfill process...\n');
+
+  // Fetch mutations
+  const mutations = await fetchMutationsToBackfill();
+
+  if (mutations.length === 0) {
+    console.log('No mutations need backfilling. All done!');
+    return;
+  }
+
+  let processedCount = 0;
+  let successCount = 0;
+  let errorCount = 0;
+  const errors: Array<{ id: string; error: string }> = [];
+
+  // Process each mutation
+  for (const mutation of mutations) {
+    try {
+      // Generate structural hashes
+      const structureHashBefore = generateStructuralHash(mutation.workflow_before);
+      const structureHashAfter = generateStructuralHash(mutation.workflow_after);
+
+      if (!structureHashBefore || !structureHashAfter) {
+        console.warn(`Skipping mutation ${mutation.id}: Failed to generate hashes`);
+        errors.push({ id: mutation.id, error: 'Failed to generate hashes' });
+        errorCount++;
+        continue;
+      }
+
+      // Update database
+      const success = await updateMutation(mutation.id, structureHashBefore, structureHashAfter);
+
+      if (success) {
+        successCount++;
+      } else {
+        errorCount++;
+        errors.push({ id: mutation.id, error: 'Database update failed' });
+      }
+
+      processedCount++;
+
+      // Progress update every 100 mutations
+      if (processedCount % 100 === 0) {
+        const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+        const rate = (processedCount / (Date.now() - startTime) * 1000).toFixed(1);
+        console.log(
+          `Progress: ${processedCount}/${mutations.length} (${((processedCount / mutations.length) * 100).toFixed(1)}%) | ` +
+          `Success: ${successCount} | Errors: ${errorCount} | Rate: ${rate}/s | Elapsed: ${elapsed}s`
+        );
+      }
+    } catch (error) {
+      console.error(`Unexpected error processing mutation ${mutation.id}:`, error);
+      errors.push({ id: mutation.id, error: String(error) });
+      errorCount++;
+    }
+  }
+
+  // Final summary
+  const duration = ((Date.now() - startTime) / 1000).toFixed(1);
+  console.log('\n' + '='.repeat(80));
+  console.log('BACKFILL COMPLETE');
+  console.log('='.repeat(80));
+  console.log(`Total mutations processed: ${processedCount}`);
+  console.log(`Successfully updated: ${successCount}`);
+  console.log(`Errors: ${errorCount}`);
+  console.log(`Duration: ${duration}s`);
+  console.log(`Average rate: ${(processedCount / (Date.now() - startTime) * 1000).toFixed(1)} mutations/s`);
+
+  if (errors.length > 0) {
+    console.log('\nErrors encountered:');
+    errors.slice(0, 10).forEach(({ id, error }) => {
+      console.log(`  - ${id}: ${error}`);
+    });
+    if (errors.length > 10) {
+      console.log(`  ... and ${errors.length - 10} more errors`);
+    }
+  }
+
+  // Verify cross-reference matches
+  console.log('\n' + '='.repeat(80));
+  console.log('VERIFYING CROSS-REFERENCE MATCHES');
+  console.log('='.repeat(80));
+
+  const { data: statsData, error: statsError } = await supabase.rpc('get_mutation_crossref_stats');
+
+  if (statsError) {
+    console.error('Failed to get cross-reference stats:', statsError.message);
+  } else if (statsData && statsData.length > 0) {
+    const stats = statsData[0];
+    console.log(`Total mutations: ${stats.total_mutations}`);
+    console.log(`Before matches: ${stats.before_matches} (${stats.before_match_rate}%)`);
+    console.log(`After matches: ${stats.after_matches} (${stats.after_match_rate}%)`);
+    console.log(`Both matches: ${stats.both_matches}`);
+  }
+
+  console.log('\nBackfill process completed successfully! ✓');
+}
+
+// Run the backfill
+backfillMutations().catch((error) => {
+  console.error('Fatal error during backfill:', error);
+  process.exit(1);
+});

scripts/test-structure-validation.ts

@@ -0,0 +1,470 @@
+#!/usr/bin/env ts-node
+/**
+ * Phase 3: Real-World Type Structure Validation
+ *
+ * Tests type structure validation against real workflow templates from n8n.io
+ * to ensure production readiness. Validates filter, resourceMapper,
+ * assignmentCollection, and resourceLocator types.
+ *
+ * Usage:
+ *   npm run build && node dist/scripts/test-structure-validation.js
+ *
+ * or with ts-node:
+ *   npx ts-node scripts/test-structure-validation.ts
+ */
+
+import { createDatabaseAdapter } from '../src/database/database-adapter';
+import { EnhancedConfigValidator } from '../src/services/enhanced-config-validator';
+import type { NodePropertyTypes } from 'n8n-workflow';
+import { gunzipSync } from 'zlib';
+
+interface ValidationResult {
+  templateId: number;
+  templateName: string;
+  templateViews: number;
+  nodeId: string;
+  nodeName: string;
+  nodeType: string;
+  propertyName: string;
+  propertyType: NodePropertyTypes;
+  valid: boolean;
+  errors: Array<{ type: string; property?: string; message: string }>;
+  warnings: Array<{ type: string; property?: string; message: string }>;
+  validationTimeMs: number;
+}
+
+interface ValidationStats {
+  totalTemplates: number;
+  totalNodes: number;
+  totalValidations: number;
+  passedValidations: number;
+  failedValidations: number;
+  byType: Record<string, { passed: number; failed: number }>;
+  byError: Record<string, number>;
+  avgValidationTimeMs: number;
+  maxValidationTimeMs: number;
+}
+
+// Special types we want to validate
+const SPECIAL_TYPES: NodePropertyTypes[] = [
+  'filter',
+  'resourceMapper',
+  'assignmentCollection',
+  'resourceLocator',
+];
+
+function decompressWorkflow(compressed: string): any {
+  try {
+    const buffer = Buffer.from(compressed, 'base64');
+    const decompressed = gunzipSync(buffer);
+    return JSON.parse(decompressed.toString('utf-8'));
+  } catch (error: any) {
+    throw new Error(`Failed to decompress workflow: ${error.message}`);
+  }
+}
+
+async function loadTopTemplates(db: any, limit: number = 100) {
+  console.log(`📥 Loading top ${limit} templates by popularity...\n`);
+
+  const stmt = db.prepare(`
+    SELECT
+      id,
+      name,
+      workflow_json_compressed,
+      views
+    FROM templates
+    WHERE workflow_json_compressed IS NOT NULL
+    ORDER BY views DESC
+    LIMIT ?
+  `);
+
+  const templates = stmt.all(limit);
+  console.log(`✓ Loaded ${templates.length} templates\n`);
+
+  return templates;
+}
+
+function extractNodesWithSpecialTypes(workflowJson: any): Array<{
+  nodeId: string;
+  nodeName: string;
+  nodeType: string;
+  properties: Array<{ name: string; type: NodePropertyTypes; value: any }>;
+}> {
+  const results: Array<any> = [];
+
+  if (!workflowJson || !workflowJson.nodes || !Array.isArray(workflowJson.nodes)) {
+    return results;
+  }
+
+  for (const node of workflowJson.nodes) {
+    // Check if node has parameters with special types
+    if (!node.parameters || typeof node.parameters !== 'object') {
+      continue;
+    }
+
+    const specialProperties: Array<{ name: string; type: NodePropertyTypes; value: any }> = [];
+
+    // Check each parameter against our special types
+    for (const [paramName, paramValue] of Object.entries(node.parameters)) {
+      // Try to infer type from structure
+      const inferredType = inferPropertyType(paramValue);
+
+      if (inferredType && SPECIAL_TYPES.includes(inferredType)) {
+        specialProperties.push({
+          name: paramName,
+          type: inferredType,
+          value: paramValue,
+        });
+      }
+    }
+
+    if (specialProperties.length > 0) {
+      results.push({
+        nodeId: node.id,
+        nodeName: node.name,
+        nodeType: node.type,
+        properties: specialProperties,
+      });
+    }
+  }
+
+  return results;
+}
+
+function inferPropertyType(value: any): NodePropertyTypes | null {
+  if (!value || typeof value !== 'object') {
+    return null;
+  }
+
+  // Filter type: has combinator and conditions
+  if (value.combinator && value.conditions) {
+    return 'filter';
+  }
+
+  // ResourceMapper type: has mappingMode
+  if (value.mappingMode) {
+    return 'resourceMapper';
+  }
+
+  // AssignmentCollection type: has assignments array
+  if (value.assignments && Array.isArray(value.assignments)) {
+    return 'assignmentCollection';
+  }
+
+  // ResourceLocator type: has mode and value
+  if (value.mode && value.hasOwnProperty('value')) {
+    return 'resourceLocator';
+  }
+
+  return null;
+}
+
+async function validateTemplate(
+  templateId: number,
+  templateName: string,
+  templateViews: number,
+  workflowJson: any
+): Promise<ValidationResult[]> {
+  const results: ValidationResult[] = [];
+
+  // Extract nodes with special types
+  const nodesWithSpecialTypes = extractNodesWithSpecialTypes(workflowJson);
+
+  for (const node of nodesWithSpecialTypes) {
+    for (const prop of node.properties) {
+      const startTime = Date.now();
+
+      // Create property definition for validation
+      const properties = [
+        {
+          name: prop.name,
+          type: prop.type,
+          required: true,
+          displayName: prop.name,
+          default: {},
+        },
+      ];
+
+      // Create config with just this property
+      const config = {
+        [prop.name]: prop.value,
+      };
+
+      try {
+        // Run validation
+        const validationResult = EnhancedConfigValidator.validateWithMode(
+          node.nodeType,
+          config,
+          properties,
+          'operation',
+          'ai-friendly'
+        );
+
+        const validationTimeMs = Date.now() - startTime;
+
+        results.push({
+          templateId,
+          templateName,
+          templateViews,
+          nodeId: node.nodeId,
+          nodeName: node.nodeName,
+          nodeType: node.nodeType,
+          propertyName: prop.name,
+          propertyType: prop.type,
+          valid: validationResult.valid,
+          errors: validationResult.errors || [],
+          warnings: validationResult.warnings || [],
+          validationTimeMs,
+        });
+      } catch (error: any) {
+        const validationTimeMs = Date.now() - startTime;
+
+        results.push({
+          templateId,
+          templateName,
+          templateViews,
+          nodeId: node.nodeId,
+          nodeName: node.nodeName,
+          nodeType: node.nodeType,
+          propertyName: prop.name,
+          propertyType: prop.type,
+          valid: false,
+          errors: [
+            {
+              type: 'exception',
+              property: prop.name,
+              message: `Validation threw exception: ${error.message}`,
+            },
+          ],
+          warnings: [],
+          validationTimeMs,
+        });
+      }
+    }
+  }
+
+  return results;
+}
+
+function calculateStats(results: ValidationResult[]): ValidationStats {
+  const stats: ValidationStats = {
+    totalTemplates: new Set(results.map(r => r.templateId)).size,
+    totalNodes: new Set(results.map(r => `${r.templateId}-${r.nodeId}`)).size,
+    totalValidations: results.length,
+    passedValidations: results.filter(r => r.valid).length,
+    failedValidations: results.filter(r => !r.valid).length,
+    byType: {},
+    byError: {},
+    avgValidationTimeMs: 0,
+    maxValidationTimeMs: 0,
+  };
+
+  // Stats by type
+  for (const type of SPECIAL_TYPES) {
+    const typeResults = results.filter(r => r.propertyType === type);
+    stats.byType[type] = {
+      passed: typeResults.filter(r => r.valid).length,
+      failed: typeResults.filter(r => !r.valid).length,
+    };
+  }
+
+  // Error frequency
+  for (const result of results.filter(r => !r.valid)) {
+    for (const error of result.errors) {
+      const key = `${error.type}: ${error.message}`;
+      stats.byError[key] = (stats.byError[key] || 0) + 1;
+    }
+  }
+
+  // Performance stats
+  if (results.length > 0) {
+    stats.avgValidationTimeMs =
+      results.reduce((sum, r) => sum + r.validationTimeMs, 0) / results.length;
+    stats.maxValidationTimeMs = Math.max(...results.map(r => r.validationTimeMs));
+  }
+
+  return stats;
+}
+
+function printStats(stats: ValidationStats) {
+  console.log('\n' + '='.repeat(80));
+  console.log('VALIDATION STATISTICS');
+  console.log('='.repeat(80) + '\n');
+
+  console.log(`📊 Total Templates Tested: ${stats.totalTemplates}`);
+  console.log(`📊 Total Nodes with Special Types: ${stats.totalNodes}`);
+  console.log(`📊 Total Property Validations: ${stats.totalValidations}\n`);
+
+  const passRate = (stats.passedValidations / stats.totalValidations * 100).toFixed(2);
+  const failRate = (stats.failedValidations / stats.totalValidations * 100).toFixed(2);
+
+  console.log(`✅ Passed: ${stats.passedValidations} (${passRate}%)`);
+  console.log(`❌ Failed: ${stats.failedValidations} (${failRate}%)\n`);
+
+  console.log('By Property Type:');
+  console.log('-'.repeat(80));
+  for (const [type, counts] of Object.entries(stats.byType)) {
+    const total = counts.passed + counts.failed;
+    if (total === 0) {
+      console.log(`  ${type}: No occurrences found`);
+    } else {
+      const typePassRate = (counts.passed / total * 100).toFixed(2);
+      console.log(`  ${type}: ${counts.passed}/${total} passed (${typePassRate}%)`);
+    }
+  }
+
+  console.log('\n⚡ Performance:');
+  console.log('-'.repeat(80));
+  console.log(`  Average validation time: ${stats.avgValidationTimeMs.toFixed(2)}ms`);
+  console.log(`  Maximum validation time: ${stats.maxValidationTimeMs.toFixed(2)}ms`);
+
+  const meetsTarget = stats.avgValidationTimeMs < 50;
+  console.log(`  Target (<50ms): ${meetsTarget ? '✅ MET' : '❌ NOT MET'}\n`);
+
+  if (Object.keys(stats.byError).length > 0) {
+    console.log('🔍 Most Common Errors:');
+    console.log('-'.repeat(80));
+
+    const sortedErrors = Object.entries(stats.byError)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 10);
+
+    for (const [error, count] of sortedErrors) {
+      console.log(`  ${count}x: ${error}`);
+    }
+  }
+}
+
+function printFailures(results: ValidationResult[], maxFailures: number = 20) {
+  const failures = results.filter(r => !r.valid);
+
+  if (failures.length === 0) {
+    console.log('\n✨ No failures! All validations passed.\n');
+    return;
+  }
+
+  console.log('\n' + '='.repeat(80));
+  console.log(`VALIDATION FAILURES (showing first ${Math.min(maxFailures, failures.length)})` );
+  console.log('='.repeat(80) + '\n');
+
+  for (let i = 0; i < Math.min(maxFailures, failures.length); i++) {
+    const failure = failures[i];
+
+    console.log(`Failure ${i + 1}/${failures.length}:`);
+    console.log(`  Template: ${failure.templateName} (ID: ${failure.templateId}, Views: ${failure.templateViews})`);
+    console.log(`  Node: ${failure.nodeName} (${failure.nodeType})`);
+    console.log(`  Property: ${failure.propertyName} (type: ${failure.propertyType})`);
+    console.log(`  Errors:`);
+
+    for (const error of failure.errors) {
+      console.log(`    - [${error.type}] ${error.property}: ${error.message}`);
+    }
+
+    if (failure.warnings.length > 0) {
+      console.log(`  Warnings:`);
+      for (const warning of failure.warnings) {
+        console.log(`    - [${warning.type}] ${warning.property}: ${warning.message}`);
+      }
+    }
+
+    console.log('');
+  }
+
+  if (failures.length > maxFailures) {
+    console.log(`... and ${failures.length - maxFailures} more failures\n`);
+  }
+}
+
+async function main() {
+  console.log('='.repeat(80));
+  console.log('PHASE 3: REAL-WORLD TYPE STRUCTURE VALIDATION');
+  console.log('='.repeat(80) + '\n');
+
+  // Initialize database
+  console.log('🔌 Connecting to database...');
+  const db = await createDatabaseAdapter('./data/nodes.db');
+  console.log('✓ Database connected\n');
+
+  // Load templates
+  const templates = await loadTopTemplates(db, 100);
+
+  // Validate each template
+  console.log('🔍 Validating templates...\n');
+
+  const allResults: ValidationResult[] = [];
+  let processedCount = 0;
+  let nodesFound = 0;
+
+  for (const template of templates) {
+    processedCount++;
+
+    let workflowJson;
+    try {
+      workflowJson = decompressWorkflow(template.workflow_json_compressed);
+    } catch (error) {
+      console.warn(`⚠️  Template ${template.id}: Decompression failed, skipping`);
+      continue;
+    }
+
+    const results = await validateTemplate(
+      template.id,
+      template.name,
+      template.views,
+      workflowJson
+    );
+
+    if (results.length > 0) {
+      nodesFound += new Set(results.map(r => r.nodeId)).size;
+      allResults.push(...results);
+
+      const passedCount = results.filter(r => r.valid).length;
+      const status = passedCount === results.length ? '✓' : '✗';
+      console.log(
+        `${status} Template ${processedCount}/${templates.length}: ` +
+        `"${template.name}" (${results.length} validations, ${passedCount} passed)`
+      );
+    }
+  }
+
+  console.log(`\n✓ Processed ${processedCount} templates`);
+  console.log(`✓ Found ${nodesFound} nodes with special types\n`);
+
+  // Calculate and print statistics
+  const stats = calculateStats(allResults);
+  printStats(stats);
+
+  // Print detailed failures
+  printFailures(allResults);
+
+  // Success criteria check
+  console.log('='.repeat(80));
+  console.log('SUCCESS CRITERIA CHECK');
+  console.log('='.repeat(80) + '\n');
+
+  const passRate = (stats.passedValidations / stats.totalValidations * 100);
+  const falsePositiveRate = (stats.failedValidations / stats.totalValidations * 100);
+  const avgTime = stats.avgValidationTimeMs;
+
+  console.log(`Pass Rate: ${passRate.toFixed(2)}% (target: >95%) ${passRate > 95 ? '✅' : '❌'}`);
+  console.log(`False Positive Rate: ${falsePositiveRate.toFixed(2)}% (target: <5%) ${falsePositiveRate < 5 ? '✅' : '❌'}`);
+  console.log(`Avg Validation Time: ${avgTime.toFixed(2)}ms (target: <50ms) ${avgTime < 50 ? '✅' : '❌'}\n`);
+
+  const allCriteriaMet = passRate > 95 && falsePositiveRate < 5 && avgTime < 50;
+
+  if (allCriteriaMet) {
+    console.log('🎉 ALL SUCCESS CRITERIA MET! Phase 3 validation complete.\n');
+  } else {
+    console.log('⚠️  Some success criteria not met. Iteration required.\n');
+  }
+
+  // Close database
+  db.close();
+
+  process.exit(allCriteriaMet ? 0 : 1);
+}
+
+// Run the script
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});

src/constants/type-structures.ts

@@ -0,0 +1,741 @@
+/**
+ * Type Structure Constants
+ *
+ * Complete definitions for all n8n NodePropertyTypes.
+ * These structures define the expected data format, JavaScript type,
+ * validation rules, and examples for each property type.
+ *
+ * Based on n8n-workflow v1.120.3 NodePropertyTypes
+ *
+ * @module constants/type-structures
+ * @since 2.23.0
+ */
+
+import type { NodePropertyTypes } from 'n8n-workflow';
+import type { TypeStructure } from '../types/type-structures';
+
+/**
+ * Complete type structure definitions for all 22 NodePropertyTypes
+ *
+ * Each entry defines:
+ * - type: Category (primitive/object/collection/special)
+ * - jsType: Underlying JavaScript type
+ * - description: What this type represents
+ * - structure: Expected data shape (for complex types)
+ * - example: Working example value
+ * - validation: Type-specific validation rules
+ *
+ * @constant
+ */
+export const TYPE_STRUCTURES: Record<NodePropertyTypes, TypeStructure> = {
+	// ============================================================================
+	// PRIMITIVE TYPES - Simple JavaScript values
+	// ============================================================================
+
+	string: {
+		type: 'primitive',
+		jsType: 'string',
+		description: 'A text value that can contain any characters',
+		example: 'Hello World',
+		examples: ['', 'A simple text', '{{ $json.name }}', 'https://example.com'],
+		validation: {
+			allowEmpty: true,
+			allowExpressions: true,
+		},
+		notes: ['Most common property type', 'Supports n8n expressions'],
+	},
+
+	number: {
+		type: 'primitive',
+		jsType: 'number',
+		description: 'A numeric value (integer or decimal)',
+		example: 42,
+		examples: [0, -10, 3.14, 100],
+		validation: {
+			allowEmpty: false,
+			allowExpressions: true,
+		},
+		notes: ['Can be constrained with min/max in typeOptions'],
+	},
+
+	boolean: {
+		type: 'primitive',
+		jsType: 'boolean',
+		description: 'A true/false toggle value',
+		example: true,
+		examples: [true, false],
+		validation: {
+			allowEmpty: false,
+			allowExpressions: false,
+		},
+		notes: ['Rendered as checkbox in n8n UI'],
+	},
+
+	dateTime: {
+		type: 'primitive',
+		jsType: 'string',
+		description: 'A date and time value in ISO 8601 format',
+		example: '2024-01-20T10:30:00Z',
+		examples: [
+			'2024-01-20T10:30:00Z',
+			'2024-01-20',
+			'{{ $now }}',
+		],
+		validation: {
+			allowEmpty: false,
+			allowExpressions: true,
+			pattern: '^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$',
+		},
+		notes: ['Accepts ISO 8601 format', 'Can use n8n date expressions'],
+	},
+
+	color: {
+		type: 'primitive',
+		jsType: 'string',
+		description: 'A color value in hex format',
+		example: '#FF5733',
+		examples: ['#FF5733', '#000000', '#FFFFFF', '{{ $json.color }}'],
+		validation: {
+			allowEmpty: false,
+			allowExpressions: true,
+			pattern: '^#[0-9A-Fa-f]{6}$',
+		},
+		notes: ['Must be 6-digit hex color', 'Rendered with color picker in UI'],
+	},
+
+	json: {
+		type: 'primitive',
+		jsType: 'string',
+		description: 'A JSON string that can be parsed into any structure',
+		example: '{"key": "value", "nested": {"data": 123}}',
+		examples: [
+			'{}',
+			'{"name": "John", "age": 30}',
+			'[1, 2, 3]',
+			'{{ $json }}',
+		],
+		validation: {
+			allowEmpty: false,
+			allowExpressions: true,
+		},
+		notes: ['Must be valid JSON when parsed', 'Often used for custom payloads'],
+	},
+
+	// ============================================================================
+	// OPTION TYPES - Selection from predefined choices
+	// ============================================================================
+
+	options: {
+		type: 'primitive',
+		jsType: 'string',
+		description: 'Single selection from a list of predefined options',
+		example: 'option1',
+		examples: ['GET', 'POST', 'channelMessage', 'update'],
+		validation: {
+			allowEmpty: false,
+			allowExpressions: false,
+		},
+		notes: [
+			'Value must match one of the defined option values',
+			'Rendered as dropdown in UI',
+			'Options defined in property.options array',
+		],
+	},
+
+	multiOptions: {
+		type: 'array',
+		jsType: 'array',
+		description: 'Multiple selections from a list of predefined options',
+		structure: {
+			items: {
+				type: 'string',
+				description: 'Selected option value',
+			},
+		},
+		example: ['option1', 'option2'],
+		examples: [[], ['GET', 'POST'], ['read', 'write', 'delete']],
+		validation: {
+			allowEmpty: true,
+			allowExpressions: false,
+		},
+		notes: [
+			'Array of option values',
+			'Each value must exist in property.options',
+			'Rendered as multi-select dropdown',
+		],
+	},
+
+	// ============================================================================
+	// COLLECTION TYPES - Complex nested structures
+	// ============================================================================
+
+	collection: {
+		type: 'collection',
+		jsType: 'object',
+		description: 'A group of related properties with dynamic values',
+		structure: {
+			properties: {
+				'<propertyName>': {
+					type: 'any',
+					description: 'Any nested property from the collection definition',
+				},
+			},
+			flexible: true,
+		},
+		example: {
+			name: 'John Doe',
+			email: 'john@example.com',
+			age: 30,
+		},
+		examples: [
+			{},
+			{ key1: 'value1', key2: 123 },
+			{ nested: { deep: { value: true } } },
+		],
+		validation: {
+			allowEmpty: true,
+			allowExpressions: true,
+		},
+		notes: [
+			'Properties defined in property.values array',
+			'Each property can be any type',
+			'UI renders as expandable section',
+		],
+	},
+
+	fixedCollection: {
+		type: 'collection',
+		jsType: 'object',
+		description: 'A collection with predefined groups of properties',
+		structure: {
+			properties: {
+				'<collectionName>': {
+					type: 'array',
+					description: 'Array of collection items',
+					items: {
+						type: 'object',
+						description: 'Collection item with defined properties',
+					},
+				},
+			},
+			required: [],
+		},
+		example: {
+			headers: [
+				{ name: 'Content-Type', value: 'application/json' },
+				{ name: 'Authorization', value: 'Bearer token' },
+			],
+		},
+		examples: [
+			{},
+			{ queryParameters: [{ name: 'id', value: '123' }] },
+			{
+				headers: [{ name: 'Accept', value: '*/*' }],
+				queryParameters: [{ name: 'limit', value: '10' }],
+			},
+		],
+		validation: {
+			allowEmpty: true,
+			allowExpressions: true,
+		},
+		notes: [
+			'Each collection has predefined structure',
+			'Often used for headers, parameters, etc.',
+			'Supports multiple values per collection',
+		],
+	},
+
+	// ============================================================================
+	// SPECIAL n8n TYPES - Advanced functionality
+	// ============================================================================
+
+	resourceLocator: {
+		type: 'special',
+		jsType: 'object',
+		description: 'A flexible way to specify a resource by ID, name, URL, or list',
+		structure: {
+			properties: {
+				mode: {
+					type: 'string',
+					description: 'How the resource is specified',
+					enum: ['id', 'url', 'list'],
+					required: true,
+				},
+				value: {
+					type: 'string',
+					description: 'The resource identifier',
+					required: true,
+				},
+			},
+			required: ['mode', 'value'],
+		},
+		example: {
+			mode: 'id',
+			value: 'abc123',
+		},
+		examples: [
+			{ mode: 'url', value: 'https://example.com/resource/123' },
+			{ mode: 'list', value: 'item-from-dropdown' },
+			{ mode: 'id', value: '{{ $json.resourceId }}' },
+		],
+		validation: {
+			allowEmpty: false,
+			allowExpressions: true,
+		},
+		notes: [
+			'Provides flexible resource selection',
+			'Mode determines how value is interpreted',
+			'UI adapts based on selected mode',
+		],
+	},
+
+	resourceMapper: {
+		type: 'special',
+		jsType: 'object',
+		description: 'Maps input data fields to resource fields with transformation options',
+		structure: {
+			properties: {
+				mappingMode: {
+					type: 'string',
+					description: 'How fields are mapped',
+					enum: ['defineBelow', 'autoMapInputData'],
+				},
+				value: {
+					type: 'object',
+					description: 'Field mappings',
+					properties: {
+						'<fieldName>': {
+							type: 'string',
+							description: 'Expression or value for this field',
+						},
+					},
+					flexible: true,
+				},
+			},
+		},
+		example: {
+			mappingMode: 'defineBelow',
+			value: {
+				name: '{{ $json.fullName }}',
+				email: '{{ $json.emailAddress }}',
+				status: 'active',
+			},
+		},
+		examples: [
+			{ mappingMode: 'autoMapInputData', value: {} },
+			{
+				mappingMode: 'defineBelow',
+				value: { id: '{{ $json.userId }}', name: '{{ $json.name }}' },
+			},
+		],
+		validation: {
+			allowEmpty: false,
+			allowExpressions: true,
+		},
+		notes: [
+			'Complex mapping with UI assistance',
+			'Can auto-map or manually define',
+			'Supports field transformations',
+		],
+	},
+
+	filter: {
+		type: 'special',
+		jsType: 'object',
+		description: 'Defines conditions for filtering data with boolean logic',
+		structure: {
+			properties: {
+				conditions: {
+					type: 'array',
+					description: 'Array of filter conditions',
+					items: {
+						type: 'object',
+						properties: {
+							id: {
+								type: 'string',
+								description: 'Unique condition identifier',
+								required: true,
+							},
+							leftValue: {
+								type: 'any',
+								description: 'Left side of comparison',
+							},
+							operator: {
+								type: 'object',
+								description: 'Comparison operator',
+								required: true,
+								properties: {
+									type: {
+										type: 'string',
+										enum: ['string', 'number', 'boolean', 'dateTime', 'array', 'object'],
+										required: true,
+									},
+									operation: {
+										type: 'string',
+										description: 'Operation to perform',
+										required: true,
+									},
+								},
+							},
+							rightValue: {
+								type: 'any',
+								description: 'Right side of comparison',
+							},
+						},
+					},
+					required: true,
+				},
+				combinator: {
+					type: 'string',
+					description: 'How to combine conditions',
+					enum: ['and', 'or'],
+					required: true,
+				},
+			},
+			required: ['conditions', 'combinator'],
+		},
+		example: {
+			conditions: [
+				{
+					id: 'abc-123',
+					leftValue: '{{ $json.status }}',
+					operator: { type: 'string', operation: 'equals' },
+					rightValue: 'active',
+				},
+			],
+			combinator: 'and',
+		},
+		validation: {
+			allowEmpty: false,
+			allowExpressions: true,
+		},
+		notes: [
+			'Advanced filtering UI in n8n',
+			'Supports complex boolean logic',
+			'Operations vary by data type',
+		],
+	},
+
+	assignmentCollection: {
+		type: 'special',
+		jsType: 'object',
+		description: 'Defines variable assignments with expressions',
+		structure: {
+			properties: {
+				assignments: {
+					type: 'array',
+					description: 'Array of variable assignments',
+					items: {
+						type: 'object',
+						properties: {
+							id: {
+								type: 'string',
+								description: 'Unique assignment identifier',
+								required: true,
+							},
+							name: {
+								type: 'string',
+								description: 'Variable name',
+								required: true,
+							},
+							value: {
+								type: 'any',
+								description: 'Value to assign',
+								required: true,
+							},
+							type: {
+								type: 'string',
+								description: 'Data type of the value',
+								enum: ['string', 'number', 'boolean', 'array', 'object'],
+							},
+						},
+					},
+					required: true,
+				},
+			},
+			required: ['assignments'],
+		},
+		example: {
+			assignments: [
+				{
+					id: 'abc-123',
+					name: 'userName',
+					value: '{{ $json.name }}',
+					type: 'string',
+				},
+				{
+					id: 'def-456',
+					name: 'userAge',
+					value: 30,
+					type: 'number',
+				},
+			],
+		},
+		validation: {
+			allowEmpty: false,
+			allowExpressions: true,
+		},
+		notes: [
+			'Used in Set node and similar',
+			'Each assignment can use expressions',
+			'Type helps with validation',
+		],
+	},
+
+	// ============================================================================
+	// CREDENTIAL TYPES - Authentication and credentials
+	// ============================================================================
+
+	credentials: {
+		type: 'special',
+		jsType: 'string',
+		description: 'Reference to credential configuration',
+		example: 'googleSheetsOAuth2Api',
+		examples: ['httpBasicAuth', 'slackOAuth2Api', 'postgresApi'],
+		validation: {
+			allowEmpty: false,
+			allowExpressions: false,
+		},
+		notes: [
+			'References credential type name',
+			'Credential must be configured in n8n',
+			'Type name matches credential definition',
+		],
+	},
+
+	credentialsSelect: {
+		type: 'special',
+		jsType: 'string',
+		description: 'Dropdown to select from available credentials',
+		example: 'credential-id-123',
+		examples: ['cred-abc', 'cred-def', '{{ $credentials.id }}'],
+		validation: {
+			allowEmpty: false,
+			allowExpressions: true,
+		},
+		notes: [
+			'User selects from configured credentials',
+			'Returns credential ID',
+			'Used when multiple credential instances exist',
+		],
+	},
+
+	// ============================================================================
+	// UI-ONLY TYPES - Display elements without data
+	// ============================================================================
+
+	hidden: {
+		type: 'special',
+		jsType: 'string',
+		description: 'Hidden property not shown in UI (used for internal logic)',
+		example: '',
+		validation: {
+			allowEmpty: true,
+			allowExpressions: true,
+		},
+		notes: [
+			'Not rendered in UI',
+			'Can store metadata or computed values',
+			'Often used for version tracking',
+		],
+	},
+
+	button: {
+		type: 'special',
+		jsType: 'string',
+		description: 'Clickable button that triggers an action',
+		example: '',
+		validation: {
+			allowEmpty: true,
+			allowExpressions: false,
+		},
+		notes: [
+			'Triggers action when clicked',
+			'Does not store a value',
+			'Action defined in routing property',
+		],
+	},
+
+	callout: {
+		type: 'special',
+		jsType: 'string',
+		description: 'Informational message box (warning, info, success, error)',
+		example: '',
+		validation: {
+			allowEmpty: true,
+			allowExpressions: false,
+		},
+		notes: [
+			'Display-only, no value stored',
+			'Used for warnings and hints',
+			'Style controlled by typeOptions',
+		],
+	},
+
+	notice: {
+		type: 'special',
+		jsType: 'string',
+		description: 'Notice message displayed to user',
+		example: '',
+		validation: {
+			allowEmpty: true,
+			allowExpressions: false,
+		},
+		notes: ['Similar to callout', 'Display-only element', 'Provides contextual information'],
+	},
+
+	// ============================================================================
+	// UTILITY TYPES - Special-purpose functionality
+	// ============================================================================
+
+	workflowSelector: {
+		type: 'special',
+		jsType: 'string',
+		description: 'Dropdown to select another workflow',
+		example: 'workflow-123',
+		examples: ['wf-abc', '{{ $json.workflowId }}'],
+		validation: {
+			allowEmpty: false,
+			allowExpressions: true,
+		},
+		notes: [
+			'Selects from available workflows',
+			'Returns workflow ID',
+			'Used in Execute Workflow node',
+		],
+	},
+
+	curlImport: {
+		type: 'special',
+		jsType: 'string',
+		description: 'Import configuration from cURL command',
+		example: 'curl -X GET https://api.example.com/data',
+		validation: {
+			allowEmpty: true,
+			allowExpressions: false,
+		},
+		notes: [
+			'Parses cURL command to populate fields',
+			'Used in HTTP Request node',
+			'One-time import feature',
+		],
+	},
+};
+
+/**
+ * Real-world examples for complex types
+ *
+ * These examples come from actual n8n workflows and demonstrate
+ * correct usage patterns for complex property types.
+ *
+ * @constant
+ */
+export const COMPLEX_TYPE_EXAMPLES = {
+	collection: {
+		basic: {
+			name: 'John Doe',
+			email: 'john@example.com',
+		},
+		nested: {
+			user: {
+				firstName: 'Jane',
+				lastName: 'Smith',
+			},
+			preferences: {
+				theme: 'dark',
+				notifications: true,
+			},
+		},
+		withExpressions: {
+			id: '{{ $json.userId }}',
+			timestamp: '{{ $now }}',
+			data: '{{ $json.payload }}',
+		},
+	},
+
+	fixedCollection: {
+		httpHeaders: {
+			headers: [
+				{ name: 'Content-Type', value: 'application/json' },
+				{ name: 'Authorization', value: 'Bearer {{ $credentials.token }}' },
+			],
+		},
+		queryParameters: {
+			queryParameters: [
+				{ name: 'page', value: '1' },
+				{ name: 'limit', value: '100' },
+			],
+		},
+		multipleCollections: {
+			headers: [{ name: 'Accept', value: 'application/json' }],
+			queryParameters: [{ name: 'filter', value: 'active' }],
+		},
+	},
+
+	filter: {
+		simple: {
+			conditions: [
+				{
+					id: '1',
+					leftValue: '{{ $json.status }}',
+					operator: { type: 'string', operation: 'equals' },
+					rightValue: 'active',
+				},
+			],
+			combinator: 'and',
+		},
+		complex: {
+			conditions: [
+				{
+					id: '1',
+					leftValue: '{{ $json.age }}',
+					operator: { type: 'number', operation: 'gt' },
+					rightValue: 18,
+				},
+				{
+					id: '2',
+					leftValue: '{{ $json.country }}',
+					operator: { type: 'string', operation: 'equals' },
+					rightValue: 'US',
+				},
+			],
+			combinator: 'and',
+		},
+	},
+
+	resourceMapper: {
+		autoMap: {
+			mappingMode: 'autoMapInputData',
+			value: {},
+		},
+		manual: {
+			mappingMode: 'defineBelow',
+			value: {
+				firstName: '{{ $json.first_name }}',
+				lastName: '{{ $json.last_name }}',
+				email: '{{ $json.email_address }}',
+				status: 'active',
+			},
+		},
+	},
+
+	assignmentCollection: {
+		basic: {
+			assignments: [
+				{
+					id: '1',
+					name: 'fullName',
+					value: '{{ $json.firstName }} {{ $json.lastName }}',
+					type: 'string',
+				},
+			],
+		},
+		multiple: {
+			assignments: [
+				{ id: '1', name: 'userName', value: '{{ $json.name }}', type: 'string' },
+				{ id: '2', name: 'userAge', value: '{{ $json.age }}', type: 'number' },
+				{ id: '3', name: 'isActive', value: true, type: 'boolean' },
+			],
+		},
+	},
+};

src/http-server-single-session.ts

@@ -25,6 +25,7 @@ import {
   STANDARD_PROTOCOL_VERSION
 } from './utils/protocol-version';
 import { InstanceContext, validateInstanceContext } from './types/instance-context';
+import { SessionState } from './types/session-state';
 
 dotenv.config();
 
@@ -71,6 +72,30 @@ function extractMultiTenantHeaders(req: express.Request): MultiTenantHeaders {
   };
 }
 
+/**
+ * Security logging helper for audit trails
+ * Provides structured logging for security-relevant events
+ */
+function logSecurityEvent(
+  event: 'session_export' | 'session_restore' | 'session_restore_failed' | 'max_sessions_reached',
+  details: {
+    sessionId?: string;
+    reason?: string;
+    count?: number;
+    instanceId?: string;
+  }
+): void {
+  const timestamp = new Date().toISOString();
+  const logEntry = {
+    timestamp,
+    event,
+    ...details
+  };
+
+  // Log to standard logger with [SECURITY] prefix for easy filtering
+  logger.info(`[SECURITY] ${event}`, logEntry);
+}
+
 export class SingleSessionHTTPServer {
   // Map to store transports by session ID (following SDK pattern)
   private transports: { [sessionId: string]: StreamableHTTPServerTransport } = {};
@@ -155,17 +180,22 @@ export class SingleSessionHTTPServer {
    */
   private async removeSession(sessionId: string, reason: string): Promise<void> {
     try {
-      // Close transport if exists
-      if (this.transports[sessionId]) {
-        await this.transports[sessionId].close();
-        delete this.transports[sessionId];
-      }
-      
-      // Remove server, metadata, and context
+      // Store reference to transport before deletion
+      const transport = this.transports[sessionId];
+
+      // Delete transport FIRST to prevent onclose handler from triggering recursion
+      // This breaks the circular reference: removeSession -> close -> onclose -> removeSession
+      delete this.transports[sessionId];
       delete this.servers[sessionId];
       delete this.sessionMetadata[sessionId];
       delete this.sessionContexts[sessionId];
-      
+
+      // Close transport AFTER deletion
+      // When onclose handler fires, it won't find the transport anymore
+      if (transport) {
+        await transport.close();
+      }
+
       logger.info('Session removed', { sessionId, reason });
     } catch (error) {
       logger.warn('Error removing session', { sessionId, reason, error });
@@ -682,7 +712,20 @@ export class SingleSessionHTTPServer {
     if (!this.session) return true;
     return Date.now() - this.session.lastAccess.getTime() > this.sessionTimeout;
   }
-  
+
+  /**
+   * Check if a specific session is expired based on sessionId
+   * Used for multi-session expiration checks during export/restore
+   *
+   * @param sessionId - The session ID to check
+   * @returns true if session is expired or doesn't exist
+   */
+  private isSessionExpired(sessionId: string): boolean {
+    const metadata = this.sessionMetadata[sessionId];
+    if (!metadata) return true;
+    return Date.now() - metadata.lastAccess.getTime() > this.sessionTimeout;
+  }
+
   /**
    * Start the HTTP server
    */
@@ -1401,6 +1444,197 @@ export class SingleSessionHTTPServer {
       }
     };
   }
+
+  /**
+   * Export all active session state for persistence
+   *
+   * Used by multi-tenant backends to dump sessions before container restart.
+   * This method exports the minimal state needed to restore sessions after
+   * a restart: session metadata (timing) and instance context (credentials).
+   *
+   * Transport and server objects are NOT persisted - they will be recreated
+   * on the first request after restore.
+   *
+   * SECURITY WARNING: The exported data contains plaintext n8n API keys.
+   * The downstream application MUST encrypt this data before persisting to disk.
+   *
+   * @returns Array of session state objects, excluding expired sessions
+   *
+   * @example
+   * // Before shutdown
+   * const sessions = server.exportSessionState();
+   * await saveToEncryptedStorage(sessions);
+   */
+  public exportSessionState(): SessionState[] {
+    const sessions: SessionState[] = [];
+    const seenSessionIds = new Set<string>();
+
+    // Iterate over all sessions with metadata (source of truth for active sessions)
+    for (const sessionId of Object.keys(this.sessionMetadata)) {
+      // Check for duplicates (defensive programming)
+      if (seenSessionIds.has(sessionId)) {
+        logger.warn(`Duplicate sessionId detected during export: ${sessionId}`);
+        continue;
+      }
+
+      // Skip expired sessions - they're not worth persisting
+      if (this.isSessionExpired(sessionId)) {
+        continue;
+      }
+
+      const metadata = this.sessionMetadata[sessionId];
+      const context = this.sessionContexts[sessionId];
+
+      // Skip sessions without context - these can't be restored meaningfully
+      // (Context is required to reconnect to the correct n8n instance)
+      if (!context || !context.n8nApiUrl || !context.n8nApiKey) {
+        logger.debug(`Skipping session ${sessionId} - missing required context`);
+        continue;
+      }
+
+      seenSessionIds.add(sessionId);
+      sessions.push({
+        sessionId,
+        metadata: {
+          createdAt: metadata.createdAt.toISOString(),
+          lastAccess: metadata.lastAccess.toISOString()
+        },
+        context: {
+          n8nApiUrl: context.n8nApiUrl,
+          n8nApiKey: context.n8nApiKey,
+          instanceId: context.instanceId || sessionId, // Use sessionId as fallback
+          sessionId: context.sessionId,
+          metadata: context.metadata
+        }
+      });
+    }
+
+    logger.info(`Exported ${sessions.length} session(s) for persistence`);
+    logSecurityEvent('session_export', { count: sessions.length });
+    return sessions;
+  }
+
+  /**
+   * Restore session state from previously exported data
+   *
+   * Used by multi-tenant backends to restore sessions after container restart.
+   * This method restores only the session metadata and instance context.
+   * Transport and server objects will be recreated on the first request.
+   *
+   * Restored sessions are "dormant" until a client makes a request, at which
+   * point the transport and server will be initialized normally.
+   *
+   * @param sessions - Array of session state objects from exportSessionState()
+   * @returns Number of sessions successfully restored
+   *
+   * @example
+   * // After startup
+   * const sessions = await loadFromEncryptedStorage();
+   * const count = server.restoreSessionState(sessions);
+   * console.log(`Restored ${count} sessions`);
+   */
+  public restoreSessionState(sessions: SessionState[]): number {
+    let restoredCount = 0;
+
+    for (const sessionState of sessions) {
+      try {
+        // Skip null or invalid session objects
+        if (!sessionState || typeof sessionState !== 'object' || !sessionState.sessionId) {
+          logger.warn('Skipping invalid session state object');
+          continue;
+        }
+
+        // Check if we've hit the MAX_SESSIONS limit (check real-time count)
+        if (Object.keys(this.sessionMetadata).length >= MAX_SESSIONS) {
+          logger.warn(
+            `Reached MAX_SESSIONS limit (${MAX_SESSIONS}), skipping remaining sessions`
+          );
+          logSecurityEvent('max_sessions_reached', { count: MAX_SESSIONS });
+          break;
+        }
+
+        // Skip if session already exists (duplicate sessionId)
+        if (this.sessionMetadata[sessionState.sessionId]) {
+          logger.debug(`Skipping session ${sessionState.sessionId} - already exists`);
+          continue;
+        }
+
+        // Parse and validate dates first
+        const createdAt = new Date(sessionState.metadata.createdAt);
+        const lastAccess = new Date(sessionState.metadata.lastAccess);
+
+        if (isNaN(createdAt.getTime()) || isNaN(lastAccess.getTime())) {
+          logger.warn(
+            `Skipping session ${sessionState.sessionId} - invalid date format`
+          );
+          continue;
+        }
+
+        // Validate session isn't expired
+        const age = Date.now() - lastAccess.getTime();
+        if (age > this.sessionTimeout) {
+          logger.debug(
+            `Skipping session ${sessionState.sessionId} - expired (age: ${Math.round(age / 1000)}s)`
+          );
+          continue;
+        }
+
+        // Validate context exists (TypeScript null narrowing)
+        if (!sessionState.context) {
+          logger.warn(`Skipping session ${sessionState.sessionId} - missing context`);
+          continue;
+        }
+
+        // Validate context structure using existing validation
+        const validation = validateInstanceContext(sessionState.context);
+        if (!validation.valid) {
+          const reason = validation.errors?.join(', ') || 'invalid context';
+          logger.warn(
+            `Skipping session ${sessionState.sessionId} - invalid context: ${reason}`
+          );
+          logSecurityEvent('session_restore_failed', {
+            sessionId: sessionState.sessionId,
+            reason
+          });
+          continue;
+        }
+
+        // Restore session metadata
+        this.sessionMetadata[sessionState.sessionId] = {
+          createdAt,
+          lastAccess
+        };
+
+        // Restore session context
+        this.sessionContexts[sessionState.sessionId] = {
+          n8nApiUrl: sessionState.context.n8nApiUrl,
+          n8nApiKey: sessionState.context.n8nApiKey,
+          instanceId: sessionState.context.instanceId,
+          sessionId: sessionState.context.sessionId,
+          metadata: sessionState.context.metadata
+        };
+
+        logger.debug(`Restored session ${sessionState.sessionId}`);
+        logSecurityEvent('session_restore', {
+          sessionId: sessionState.sessionId,
+          instanceId: sessionState.context.instanceId
+        });
+        restoredCount++;
+      } catch (error) {
+        logger.error(`Failed to restore session ${sessionState.sessionId}:`, error);
+        logSecurityEvent('session_restore_failed', {
+          sessionId: sessionState.sessionId,
+          reason: error instanceof Error ? error.message : 'unknown error'
+        });
+        // Continue with next session - don't let one failure break the entire restore
+      }
+    }
+
+    logger.info(
+      `Restored ${restoredCount}/${sessions.length} session(s) from persistence`
+    );
+    return restoredCount;
+  }
 }
 
 // Start if called directly

src/index.ts

@@ -18,6 +18,9 @@ export {
   validateInstanceContext,
   isInstanceContext
 } from './types/instance-context';
+export type {
+  SessionState
+} from './types/session-state';
 
 // Re-export MCP SDK types for convenience
 export type {

src/mcp-engine.ts

@@ -9,6 +9,7 @@ import { Request, Response } from 'express';
 import { SingleSessionHTTPServer } from './http-server-single-session';
 import { logger } from './utils/logger';
 import { InstanceContext } from './types/instance-context';
+import { SessionState } from './types/session-state';
 
 export interface EngineHealth {
   status: 'healthy' | 'unhealthy';
@@ -97,7 +98,7 @@ export class N8NMCPEngine {
           total: Math.round(memoryUsage.heapTotal / 1024 / 1024),
           unit: 'MB'
         },
-        version: '2.3.2'
+        version: '2.24.1'
       };
     } catch (error) {
       logger.error('Health check failed:', error);
@@ -106,7 +107,7 @@ export class N8NMCPEngine {
         uptime: 0,
         sessionActive: false,
         memoryUsage: { used: 0, total: 0, unit: 'MB' },
-        version: '2.3.2'
+        version: '2.24.1'
       };
     }
   }
@@ -118,10 +119,58 @@ export class N8NMCPEngine {
   getSessionInfo(): { active: boolean; sessionId?: string; age?: number } {
     return this.server.getSessionInfo();
   }
-  
+
+  /**
+   * Export all active session state for persistence
+   *
+   * Used by multi-tenant backends to dump sessions before container restart.
+   * Returns an array of session state objects containing metadata and credentials.
+   *
+   * SECURITY WARNING: Exported data contains plaintext n8n API keys.
+   * Encrypt before persisting to disk.
+   *
+   * @returns Array of session state objects
+   *
+   * @example
+   * // Before shutdown
+   * const sessions = engine.exportSessionState();
+   * await saveToEncryptedStorage(sessions);
+   */
+  exportSessionState(): SessionState[] {
+    if (!this.server) {
+      logger.warn('Cannot export sessions: server not initialized');
+      return [];
+    }
+    return this.server.exportSessionState();
+  }
+
+  /**
+   * Restore session state from previously exported data
+   *
+   * Used by multi-tenant backends to restore sessions after container restart.
+   * Restores session metadata and instance context. Transports/servers are
+   * recreated on first request.
+   *
+   * @param sessions - Array of session state objects from exportSessionState()
+   * @returns Number of sessions successfully restored
+   *
+   * @example
+   * // After startup
+   * const sessions = await loadFromEncryptedStorage();
+   * const count = engine.restoreSessionState(sessions);
+   * console.log(`Restored ${count} sessions`);
+   */
+  restoreSessionState(sessions: SessionState[]): number {
+    if (!this.server) {
+      logger.warn('Cannot restore sessions: server not initialized');
+      return 0;
+    }
+    return this.server.restoreSessionState(sessions);
+  }
+
   /**
    * Graceful shutdown for service lifecycle
-   * 
+   *
    * @example
    * process.on('SIGTERM', async () => {
    *   await engine.shutdown();

src/mcp/handlers-n8n-manager.ts

@@ -34,6 +34,7 @@ import { ExpressionFormatValidator, ExpressionFormatIssue } from '../services/ex
 import { WorkflowVersioningService } from '../services/workflow-versioning-service';
 import { handleUpdatePartialWorkflow } from './handlers-workflow-diff';
 import { telemetry } from '../telemetry';
+import { TemplateService } from '../templates/template-service';
 import {
   createCacheKey,
   createInstanceCache,
@@ -1553,7 +1554,7 @@ export async function handleHealthCheck(context?: InstanceContext): Promise<McpT
             '1. Verify n8n instance is running',
             '2. Check N8N_API_URL is correct',
             '3. Verify N8N_API_KEY has proper permissions',
-            '4. Run n8n_diagnostic for detailed analysis'
+            '4. Run n8n_health_check with mode="diagnostic" for detailed analysis'
           ]
         }
       };
@@ -1566,63 +1567,6 @@ export async function handleHealthCheck(context?: InstanceContext): Promise<McpT
   }
 }
 
-export async function handleListAvailableTools(context?: InstanceContext): Promise<McpToolResponse> {
-  const tools = [
-    {
-      category: 'Workflow Management',
-      tools: [
-        { name: 'n8n_create_workflow', description: 'Create new workflows' },
-        { name: 'n8n_get_workflow', description: 'Get workflow by ID' },
-        { name: 'n8n_get_workflow_details', description: 'Get detailed workflow info with stats' },
-        { name: 'n8n_get_workflow_structure', description: 'Get simplified workflow structure' },
-        { name: 'n8n_get_workflow_minimal', description: 'Get minimal workflow info' },
-        { name: 'n8n_update_workflow', description: 'Update existing workflows' },
-        { name: 'n8n_delete_workflow', description: 'Delete workflows' },
-        { name: 'n8n_list_workflows', description: 'List workflows with filters' },
-        { name: 'n8n_validate_workflow', description: 'Validate workflow from n8n instance' },
-        { name: 'n8n_autofix_workflow', description: 'Automatically fix common workflow errors' }
-      ]
-    },
-    {
-      category: 'Execution Management',
-      tools: [
-        { name: 'n8n_trigger_webhook_workflow', description: 'Trigger workflows via webhook' },
-        { name: 'n8n_get_execution', description: 'Get execution details' },
-        { name: 'n8n_list_executions', description: 'List executions with filters' },
-        { name: 'n8n_delete_execution', description: 'Delete execution records' }
-      ]
-    },
-    {
-      category: 'System',
-      tools: [
-        { name: 'n8n_health_check', description: 'Check API connectivity' },
-        { name: 'n8n_list_available_tools', description: 'List all available tools' }
-      ]
-    }
-  ];
-  
-  const config = getN8nApiConfig();
-  const apiConfigured = config !== null;
-  
-  return {
-    success: true,
-    data: {
-      tools,
-      apiConfigured,
-      configuration: config ? {
-        apiUrl: config.baseUrl,
-        timeout: config.timeout,
-        maxRetries: config.maxRetries
-      } : null,
-      limitations: [
-        'Cannot execute workflows directly (must use webhooks)',
-        'Cannot stop running executions',
-        'Tags and credentials have limited API support'
-      ]
-    }
-  };
-}
-
 // Environment-aware debugging helpers
 
 /**
@@ -1844,8 +1788,8 @@ export async function handleDiagnostic(request: any, context?: InstanceContext):
   }
 
   // Check which tools are available
-  const documentationTools = 22; // Base documentation tools
-  const managementTools = apiConfigured ? 16 : 0;
+  const documentationTools = 7; // Base documentation tools (after v2.26.0 consolidation)
+  const managementTools = apiConfigured ? 13 : 0; // Management tools requiring API (includes n8n_deploy_template)
   const totalTools = documentationTools + managementTools;
 
   // Check npm version
@@ -1981,7 +1925,7 @@ export async function handleDiagnostic(request: any, context?: InstanceContext):
             example: 'validate_workflow({workflow: {...}})'
           }
         ],
-        note: '22 documentation tools available without API configuration'
+        note: '14 documentation tools available without API configuration'
       },
       whatYouCannotDo: [
         '✗ Create/update workflows in n8n instance',
@@ -1996,8 +1940,8 @@ export async function handleDiagnostic(request: any, context?: InstanceContext):
           '   N8N_API_URL=https://your-n8n-instance.com',
           '   N8N_API_KEY=your_api_key_here',
           '3. Restart the MCP server',
-          '4. Run n8n_diagnostic again to verify',
-          '5. All 38 tools will be available!'
+          '4. Run n8n_health_check with mode="diagnostic" to verify',
+          '5. All 19 tools will be available!'
         ],
         documentation: 'https://github.com/czlonkowski/n8n-mcp?tab=readme-ov-file#n8n-management-tools-optional---requires-api-configuration'
       }
@@ -2246,3 +2190,220 @@ export async function handleWorkflowVersions(
     };
   }
 }
+
+// ========================================================================
+// Template Deployment Handler
+// ========================================================================
+
+const deployTemplateSchema = z.object({
+  templateId: z.number().positive().int(),
+  name: z.string().optional(),
+  autoUpgradeVersions: z.boolean().default(true),
+  validate: z.boolean().default(true),
+  stripCredentials: z.boolean().default(true)
+});
+
+interface RequiredCredential {
+  nodeType: string;
+  nodeName: string;
+  credentialType: string;
+}
+
+/**
+ * Deploy a workflow template from n8n.io directly to the user's n8n instance.
+ *
+ * This handler:
+ * 1. Fetches the template from the local template database
+ * 2. Extracts credential requirements for user guidance
+ * 3. Optionally strips credentials (for user to configure in n8n UI)
+ * 4. Optionally upgrades node typeVersions to latest supported
+ * 5. Optionally validates the workflow structure
+ * 6. Creates the workflow in the n8n instance
+ */
+export async function handleDeployTemplate(
+  args: unknown,
+  templateService: TemplateService,
+  repository: NodeRepository,
+  context?: InstanceContext
+): Promise<McpToolResponse> {
+  try {
+    const client = ensureApiConfigured(context);
+    const input = deployTemplateSchema.parse(args);
+
+    // Fetch template
+    const template = await templateService.getTemplate(input.templateId, 'full');
+    if (!template) {
+      return {
+        success: false,
+        error: `Template ${input.templateId} not found`,
+        details: {
+          hint: 'Use search_templates to find available templates',
+          templateUrl: `https://n8n.io/workflows/${input.templateId}`
+        }
+      };
+    }
+
+    // Extract workflow from template (deep copy to avoid mutation)
+    const workflow = JSON.parse(JSON.stringify(template.workflow));
+    if (!workflow || !workflow.nodes) {
+      return {
+        success: false,
+        error: 'Template has invalid workflow structure',
+        details: { templateId: input.templateId }
+      };
+    }
+
+    // Set workflow name
+    const workflowName = input.name || template.name;
+
+    // Collect required credentials before stripping
+    const requiredCredentials: RequiredCredential[] = [];
+    for (const node of workflow.nodes) {
+      if (node.credentials && typeof node.credentials === 'object') {
+        for (const [credType] of Object.entries(node.credentials)) {
+          requiredCredentials.push({
+            nodeType: node.type,
+            nodeName: node.name,
+            credentialType: credType
+          });
+        }
+      }
+    }
+
+    // Strip credentials if requested
+    if (input.stripCredentials) {
+      workflow.nodes = workflow.nodes.map((node: any) => {
+        const { credentials, ...rest } = node;
+        return rest;
+      });
+    }
+
+    // Auto-upgrade typeVersions if requested
+    if (input.autoUpgradeVersions) {
+      const autoFixer = new WorkflowAutoFixer(repository);
+
+      // Run validation to get issues to fix
+      const validator = new WorkflowValidator(repository, EnhancedConfigValidator);
+      const validationResult = await validator.validateWorkflow(workflow, {
+        validateNodes: true,
+        validateConnections: false,
+        validateExpressions: false,
+        profile: 'runtime'
+      });
+
+      // Generate fixes focused on typeVersion upgrades
+      const fixResult = await autoFixer.generateFixes(
+        workflow,
+        validationResult,
+        [],
+        { fixTypes: ['typeversion-upgrade', 'typeversion-correction'] }
+      );
+
+      // Apply fixes to workflow
+      if (fixResult.operations.length > 0) {
+        for (const op of fixResult.operations) {
+          if (op.type === 'updateNode' && op.updates) {
+            const node = workflow.nodes.find((n: any) =>
+              n.id === op.nodeId || n.name === op.nodeName
+            );
+            if (node) {
+              for (const [path, value] of Object.entries(op.updates)) {
+                if (path === 'typeVersion') {
+                  node.typeVersion = value;
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+
+    // Validate workflow if requested
+    if (input.validate) {
+      const validator = new WorkflowValidator(repository, EnhancedConfigValidator);
+      const validationResult = await validator.validateWorkflow(workflow, {
+        validateNodes: true,
+        validateConnections: true,
+        validateExpressions: true,
+        profile: 'runtime'
+      });
+
+      if (validationResult.errors.length > 0) {
+        return {
+          success: false,
+          error: 'Workflow validation failed',
+          details: {
+            errors: validationResult.errors.map(e => ({
+              node: e.nodeName,
+              message: e.message
+            })),
+            warnings: validationResult.warnings.length,
+            hint: 'Use validate=false to skip validation, or fix the template issues'
+          }
+        };
+      }
+    }
+
+    // Identify trigger type
+    const triggerNode = workflow.nodes.find((n: any) =>
+      n.type?.includes('Trigger') ||
+      n.type?.includes('webhook') ||
+      n.type === 'n8n-nodes-base.webhook'
+    );
+    const triggerType = triggerNode?.type?.split('.').pop() || 'manual';
+
+    // Create workflow via API (always creates inactive)
+    const createdWorkflow = await client.createWorkflow({
+      name: workflowName,
+      nodes: workflow.nodes,
+      connections: workflow.connections,
+      settings: workflow.settings || { executionOrder: 'v1' }
+    });
+
+    // Get base URL for workflow link
+    const apiConfig = context ? getN8nApiConfigFromContext(context) : getN8nApiConfig();
+    const baseUrl = apiConfig?.baseUrl?.replace('/api/v1', '') || '';
+
+    return {
+      success: true,
+      data: {
+        workflowId: createdWorkflow.id,
+        name: createdWorkflow.name,
+        active: false,
+        nodeCount: workflow.nodes.length,
+        triggerType,
+        requiredCredentials: requiredCredentials.length > 0 ? requiredCredentials : undefined,
+        url: baseUrl ? `${baseUrl}/workflow/${createdWorkflow.id}` : undefined,
+        templateId: input.templateId,
+        templateUrl: template.url || `https://n8n.io/workflows/${input.templateId}`
+      },
+      message: `Workflow "${createdWorkflow.name}" deployed successfully from template ${input.templateId}. ${
+        requiredCredentials.length > 0
+          ? `Configure ${requiredCredentials.length} credential(s) in n8n to activate.`
+          : ''
+      }`
+    };
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      return {
+        success: false,
+        error: 'Invalid input',
+        details: { errors: error.errors }
+      };
+    }
+
+    if (error instanceof N8nApiError) {
+      return {
+        success: false,
+        error: getUserFriendlyErrorMessage(error),
+        code: error.code,
+        details: error.details as Record<string, unknown> | undefined
+      };
+    }
+
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Unknown error occurred'
+    };
+  }
+}

src/mcp/handlers-workflow-diff.ts

@@ -14,6 +14,22 @@ import { InstanceContext } from '../types/instance-context';
 import { validateWorkflowStructure } from '../services/n8n-validation';
 import { NodeRepository } from '../database/node-repository';
 import { WorkflowVersioningService } from '../services/workflow-versioning-service';
+import { WorkflowValidator } from '../services/workflow-validator';
+import { EnhancedConfigValidator } from '../services/enhanced-config-validator';
+
+// Cached validator instance to avoid recreating on every mutation
+let cachedValidator: WorkflowValidator | null = null;
+
+/**
+ * Get or create cached workflow validator instance
+ * Reuses the same validator to avoid redundant NodeSimilarityService initialization
+ */
+function getValidator(repository: NodeRepository): WorkflowValidator {
+  if (!cachedValidator) {
+    cachedValidator = new WorkflowValidator(repository, EnhancedConfigValidator);
+  }
+  return cachedValidator;
+}
 
 // Zod schema for the diff request
 const workflowDiffSchema = z.object({
@@ -62,6 +78,8 @@ export async function handleUpdatePartialWorkflow(
   const startTime = Date.now();
   const sessionId = `mutation_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`;
   let workflowBefore: any = null;
+  let validationBefore: any = null;
+  let validationAfter: any = null;
 
   try {
     // Debug logging (only in debug mode)
@@ -92,6 +110,24 @@ export async function handleUpdatePartialWorkflow(
       workflow = await client.getWorkflow(input.id);
       // Store original workflow for telemetry
       workflowBefore = JSON.parse(JSON.stringify(workflow));
+
+      // Validate workflow BEFORE mutation (for telemetry)
+      try {
+        const validator = getValidator(repository);
+        validationBefore = await validator.validateWorkflow(workflowBefore, {
+          validateNodes: true,
+          validateConnections: true,
+          validateExpressions: true,
+          profile: 'runtime'
+        });
+      } catch (validationError) {
+        logger.debug('Pre-mutation validation failed (non-blocking):', validationError);
+        // Don't block mutation on validation errors
+        validationBefore = {
+          valid: false,
+          errors: [{ type: 'validation_error', message: 'Validation failed' }]
+        };
+      }
     } catch (error) {
       if (error instanceof N8nApiError) {
         return {
@@ -257,6 +293,24 @@ export async function handleUpdatePartialWorkflow(
       let finalWorkflow = updatedWorkflow;
       let activationMessage = '';
 
+      // Validate workflow AFTER mutation (for telemetry)
+      try {
+        const validator = getValidator(repository);
+        validationAfter = await validator.validateWorkflow(finalWorkflow, {
+          validateNodes: true,
+          validateConnections: true,
+          validateExpressions: true,
+          profile: 'runtime'
+        });
+      } catch (validationError) {
+        logger.debug('Post-mutation validation failed (non-blocking):', validationError);
+        // Don't block on validation errors
+        validationAfter = {
+          valid: false,
+          errors: [{ type: 'validation_error', message: 'Validation failed' }]
+        };
+      }
+
       if (diffResult.shouldActivate) {
         try {
           finalWorkflow = await client.activateWorkflow(input.id);
@@ -298,6 +352,8 @@ export async function handleUpdatePartialWorkflow(
           operations: input.operations,
           workflowBefore,
           workflowAfter: finalWorkflow,
+          validationBefore,
+          validationAfter,
           mutationSuccess: true,
           durationMs: Date.now() - startTime,
         }).catch(err => {
@@ -330,6 +386,8 @@ export async function handleUpdatePartialWorkflow(
           operations: input.operations,
           workflowBefore,
           workflowAfter: workflowBefore, // No change since it failed
+          validationBefore,
+          validationAfter: validationBefore, // Same as before since mutation failed
           mutationSuccess: false,
           mutationError: error instanceof Error ? error.message : 'Unknown error',
           durationMs: Date.now() - startTime,
@@ -365,11 +423,86 @@ export async function handleUpdatePartialWorkflow(
   }
 }
 
+/**
+ * Infer intent from operations when not explicitly provided
+ */
+function inferIntentFromOperations(operations: any[]): string {
+  if (!operations || operations.length === 0) {
+    return 'Partial workflow update';
+  }
+
+  const opTypes = operations.map((op) => op.type);
+  const opCount = operations.length;
+
+  // Single operation - be specific
+  if (opCount === 1) {
+    const op = operations[0];
+    switch (op.type) {
+      case 'addNode':
+        return `Add ${op.node?.type || 'node'}`;
+      case 'removeNode':
+        return `Remove node ${op.nodeName || op.nodeId || ''}`.trim();
+      case 'updateNode':
+        return `Update node ${op.nodeName || op.nodeId || ''}`.trim();
+      case 'addConnection':
+        return `Connect ${op.source || 'node'} to ${op.target || 'node'}`;
+      case 'removeConnection':
+        return `Disconnect ${op.source || 'node'} from ${op.target || 'node'}`;
+      case 'rewireConnection':
+        return `Rewire ${op.source || 'node'} from ${op.from || ''} to ${op.to || ''}`.trim();
+      case 'updateName':
+        return `Rename workflow to "${op.name || ''}"`;
+      case 'activateWorkflow':
+        return 'Activate workflow';
+      case 'deactivateWorkflow':
+        return 'Deactivate workflow';
+      default:
+        return `Workflow ${op.type}`;
+    }
+  }
+
+  // Multiple operations - summarize pattern
+  const typeSet = new Set(opTypes);
+  const summary: string[] = [];
+
+  if (typeSet.has('addNode')) {
+    const count = opTypes.filter((t) => t === 'addNode').length;
+    summary.push(`add ${count} node${count > 1 ? 's' : ''}`);
+  }
+  if (typeSet.has('removeNode')) {
+    const count = opTypes.filter((t) => t === 'removeNode').length;
+    summary.push(`remove ${count} node${count > 1 ? 's' : ''}`);
+  }
+  if (typeSet.has('updateNode')) {
+    const count = opTypes.filter((t) => t === 'updateNode').length;
+    summary.push(`update ${count} node${count > 1 ? 's' : ''}`);
+  }
+  if (typeSet.has('addConnection') || typeSet.has('rewireConnection')) {
+    summary.push('modify connections');
+  }
+  if (typeSet.has('updateName') || typeSet.has('updateSettings')) {
+    summary.push('update metadata');
+  }
+
+  return summary.length > 0
+    ? `Workflow update: ${summary.join(', ')}`
+    : `Workflow update: ${opCount} operations`;
+}
+
 /**
  * Track workflow mutation for telemetry
  */
 async function trackWorkflowMutation(data: any): Promise<void> {
   try {
+    // Enhance intent if it's missing or generic
+    if (
+      !data.userIntent ||
+      data.userIntent === 'Partial workflow update' ||
+      data.userIntent.length < 10
+    ) {
+      data.userIntent = inferIntentFromOperations(data.operations);
+    }
+
     const { telemetry } = await import('../telemetry/telemetry-manager.js');
     await telemetry.trackWorkflowMutation(data);
   } catch (error) {

src/mcp/server.ts

@@ -19,6 +19,7 @@ import { TaskTemplates } from '../services/task-templates';
 import { ConfigValidator } from '../services/config-validator';
 import { EnhancedConfigValidator, ValidationMode, ValidationProfile } from '../services/enhanced-config-validator';
 import { PropertyDependencies } from '../services/property-dependencies';
+import { TypeStructureService } from '../services/type-structure-service';
 import { SimpleCache } from '../utils/simple-cache';
 import { TemplateService } from '../templates/template-service';
 import { WorkflowValidator } from '../services/workflow-validator';
@@ -58,6 +59,67 @@ interface NodeRow {
   credentials_required?: string;
 }
 
+interface VersionSummary {
+  currentVersion: string;
+  totalVersions: number;
+  hasVersionHistory: boolean;
+}
+
+interface NodeMinimalInfo {
+  nodeType: string;
+  workflowNodeType: string;
+  displayName: string;
+  description: string;
+  category: string;
+  package: string;
+  isAITool: boolean;
+  isTrigger: boolean;
+  isWebhook: boolean;
+}
+
+interface NodeStandardInfo {
+  nodeType: string;
+  displayName: string;
+  description: string;
+  category: string;
+  requiredProperties: any[];
+  commonProperties: any[];
+  operations?: any[];
+  credentials?: any;
+  examples?: any[];
+  versionInfo: VersionSummary;
+}
+
+interface NodeFullInfo {
+  nodeType: string;
+  displayName: string;
+  description: string;
+  category: string;
+  properties: any[];
+  operations?: any[];
+  credentials?: any;
+  documentation?: string;
+  versionInfo: VersionSummary;
+}
+
+interface VersionHistoryInfo {
+  nodeType: string;
+  versions: any[];
+  latestVersion: string;
+  hasBreakingChanges: boolean;
+}
+
+interface VersionComparisonInfo {
+  nodeType: string;
+  fromVersion: string;
+  toVersion: string;
+  changes: any[];
+  breakingChanges?: any[];
+  migrations?: any[];
+}
+
+type NodeInfoResponse = NodeMinimalInfo | NodeStandardInfo | NodeFullInfo | VersionHistoryInfo | VersionComparisonInfo;
+
 export class N8NDocumentationMCPServer {
   private server: Server;
   private db: DatabaseAdapter | null = null;
@@ -768,38 +830,38 @@ export class N8NDocumentationMCPServer {
       let validationResult;
       
       switch (toolName) {
-        case 'validate_node_operation':
+        case 'validate_node':
+          // Consolidated tool handles both modes - validate as operation for now
           validationResult = ToolValidation.validateNodeOperation(args);
           break;
-        case 'validate_node_minimal':
-          validationResult = ToolValidation.validateNodeMinimal(args);
-          break;
         case 'validate_workflow':
-        case 'validate_workflow_connections':
-        case 'validate_workflow_expressions':
           validationResult = ToolValidation.validateWorkflow(args);
           break;
       case 'search_nodes':
         validationResult = ToolValidation.validateSearchNodes(args);
         break;
-      case 'list_node_templates':
-        validationResult = ToolValidation.validateListNodeTemplates(args);
-        break;
       case 'n8n_create_workflow':
         validationResult = ToolValidation.validateCreateWorkflow(args);
         break;
       case 'n8n_get_workflow':
-      case 'n8n_get_workflow_details':
-      case 'n8n_get_workflow_structure':
-      case 'n8n_get_workflow_minimal':
       case 'n8n_update_full_workflow':
       case 'n8n_delete_workflow':
       case 'n8n_validate_workflow':
       case 'n8n_autofix_workflow':
-      case 'n8n_get_execution':
-      case 'n8n_delete_execution':
         validationResult = ToolValidation.validateWorkflowId(args);
         break;
+      case 'n8n_executions':
+        // Requires action parameter, id validation done in handler based on action
+        validationResult = args.action
+          ? { valid: true, errors: [] }
+          : { valid: false, errors: [{ field: 'action', message: 'action is required' }] };
+        break;
+      case 'n8n_deploy_template':
+        // Requires templateId parameter
+        validationResult = args.templateId !== undefined
+          ? { valid: true, errors: [] }
+          : { valid: false, errors: [{ field: 'templateId', message: 'templateId is required' }] };
+        break;
       default:
         // For tools not yet migrated to schema validation, use basic validation
         return this.validateToolParamsBasic(toolName, args, legacyRequiredParams || []);
@@ -953,41 +1015,50 @@ export class N8NDocumentationMCPServer {
       case 'tools_documentation':
         // No required parameters
         return this.getToolsDocumentation(args.topic, args.depth);
-      case 'list_nodes':
-        // No required parameters
-        return this.listNodes(args);
-      case 'get_node_info':
-        this.validateToolParams(name, args, ['nodeType']);
-        return this.getNodeInfo(args.nodeType);
       case 'search_nodes':
         this.validateToolParams(name, args, ['query']);
         // Convert limit to number if provided, otherwise use default
         const limit = args.limit !== undefined ? Number(args.limit) || 20 : 20;
         return this.searchNodes(args.query, limit, { mode: args.mode, includeExamples: args.includeExamples });
-      case 'list_ai_tools':
-        // No required parameters
-        return this.listAITools();
-      case 'get_node_documentation':
+      case 'get_node':
         this.validateToolParams(name, args, ['nodeType']);
-        return this.getNodeDocumentation(args.nodeType);
-      case 'get_database_statistics':
-        // No required parameters
-        return this.getDatabaseStatistics();
-      case 'get_node_essentials':
-        this.validateToolParams(name, args, ['nodeType']);
-        return this.getNodeEssentials(args.nodeType, args.includeExamples);
-      case 'search_node_properties':
-        this.validateToolParams(name, args, ['nodeType', 'query']);
-        const maxResults = args.maxResults !== undefined ? Number(args.maxResults) || 20 : 20;
-        return this.searchNodeProperties(args.nodeType, args.query, maxResults);
-      case 'list_tasks':
-        // No required parameters
-        return this.listTasks(args.category);
-      case 'validate_node_operation':
+        // Handle consolidated modes: docs, search_properties
+        if (args.mode === 'docs') {
+          return this.getNodeDocumentation(args.nodeType);
+        }
+        if (args.mode === 'search_properties') {
+          if (!args.propertyQuery) {
+            throw new Error('propertyQuery is required for mode=search_properties');
+          }
+          const maxResults = args.maxPropertyResults !== undefined ? Number(args.maxPropertyResults) || 20 : 20;
+          return this.searchNodeProperties(args.nodeType, args.propertyQuery, maxResults);
+        }
+        return this.getNode(
+          args.nodeType,
+          args.detail,
+          args.mode,
+          args.includeTypeInfo,
+          args.includeExamples,
+          args.fromVersion,
+          args.toVersion
+        );
+      case 'validate_node':
         this.validateToolParams(name, args, ['nodeType', 'config']);
         // Ensure config is an object
         if (typeof args.config !== 'object' || args.config === null) {
-          logger.warn(`validate_node_operation called with invalid config type: ${typeof args.config}`);
+          logger.warn(`validate_node called with invalid config type: ${typeof args.config}`);
+          const validationMode = args.mode || 'full';
+          if (validationMode === 'minimal') {
+            return {
+              nodeType: args.nodeType || 'unknown',
+              displayName: 'Unknown Node',
+              valid: false,
+              missingRequiredFields: [
+                'Invalid config format - expected object',
+                '🔧 RECOVERY: Use format { "resource": "...", "operation": "..." } or {} for empty config'
+              ]
+            };
+          }
           return {
             nodeType: args.nodeType || 'unknown',
             workflowNodeType: args.nodeType || 'unknown',
@@ -1003,7 +1074,7 @@ export class N8NDocumentationMCPServer {
             suggestions: [
               '🔧 RECOVERY: Invalid config detected. Fix with:',
               '   • Ensure config is an object: { "resource": "...", "operation": "..." }',
-              '   • Use get_node_essentials to see required fields for this node type',
+              '   • Use get_node to see required fields for this node type',
               '   • Check if the node type is correct before configuring it'
             ],
             summary: {
@@ -1014,95 +1085,75 @@ export class N8NDocumentationMCPServer {
             }
           };
         }
-        return this.validateNodeConfig(args.nodeType, args.config, 'operation', args.profile);
-      case 'validate_node_minimal':
-        this.validateToolParams(name, args, ['nodeType', 'config']);
-        // Ensure config is an object
-        if (typeof args.config !== 'object' || args.config === null) {
-          logger.warn(`validate_node_minimal called with invalid config type: ${typeof args.config}`);
-          return {
-            nodeType: args.nodeType || 'unknown',
-            displayName: 'Unknown Node',
-            valid: false,
-            missingRequiredFields: [
-              'Invalid config format - expected object',
-              '🔧 RECOVERY: Use format { "resource": "...", "operation": "..." } or {} for empty config'
-            ]
-          };
+        // Handle mode parameter
+        const validationMode = args.mode || 'full';
+        if (validationMode === 'minimal') {
+          return this.validateNodeMinimal(args.nodeType, args.config);
         }
-        return this.validateNodeMinimal(args.nodeType, args.config);
-      case 'get_property_dependencies':
-        this.validateToolParams(name, args, ['nodeType']);
-        return this.getPropertyDependencies(args.nodeType, args.config);
-      case 'get_node_as_tool_info':
-        this.validateToolParams(name, args, ['nodeType']);
-        return this.getNodeAsToolInfo(args.nodeType);
-      case 'list_templates':
-        // No required params
-        const listLimit = Math.min(Math.max(Number(args.limit) || 10, 1), 100);
-        const listOffset = Math.max(Number(args.offset) || 0, 0);
-        const sortBy = args.sortBy || 'views';
-        const includeMetadata = Boolean(args.includeMetadata);
-        return this.listTemplates(listLimit, listOffset, sortBy, includeMetadata);
-      case 'list_node_templates':
-        this.validateToolParams(name, args, ['nodeTypes']);
-        const templateLimit = Math.min(Math.max(Number(args.limit) || 10, 1), 100);
-        const templateOffset = Math.max(Number(args.offset) || 0, 0);
-        return this.listNodeTemplates(args.nodeTypes, templateLimit, templateOffset);
+        return this.validateNodeConfig(args.nodeType, args.config, 'operation', args.profile);
       case 'get_template':
         this.validateToolParams(name, args, ['templateId']);
         const templateId = Number(args.templateId);
-        const mode = args.mode || 'full';
-        return this.getTemplate(templateId, mode);
-      case 'search_templates':
-        this.validateToolParams(name, args, ['query']);
+        const templateMode = args.mode || 'full';
+        return this.getTemplate(templateId, templateMode);
+      case 'search_templates': {
+        // Consolidated tool with searchMode parameter
+        const searchMode = args.searchMode || 'keyword';
         const searchLimit = Math.min(Math.max(Number(args.limit) || 20, 1), 100);
         const searchOffset = Math.max(Number(args.offset) || 0, 0);
-        const searchFields = args.fields as string[] | undefined;
-        return this.searchTemplates(args.query, searchLimit, searchOffset, searchFields);
-      case 'get_templates_for_task':
-        this.validateToolParams(name, args, ['task']);
-        const taskLimit = Math.min(Math.max(Number(args.limit) || 10, 1), 100);
-        const taskOffset = Math.max(Number(args.offset) || 0, 0);
-        return this.getTemplatesForTask(args.task, taskLimit, taskOffset);
-      case 'search_templates_by_metadata':
-        // No required params - all filters are optional
-        const metadataLimit = Math.min(Math.max(Number(args.limit) || 20, 1), 100);
-        const metadataOffset = Math.max(Number(args.offset) || 0, 0);
-        return this.searchTemplatesByMetadata({
-          category: args.category,
-          complexity: args.complexity,
-          maxSetupMinutes: args.maxSetupMinutes ? Number(args.maxSetupMinutes) : undefined,
-          minSetupMinutes: args.minSetupMinutes ? Number(args.minSetupMinutes) : undefined,
-          requiredService: args.requiredService,
-          targetAudience: args.targetAudience
-        }, metadataLimit, metadataOffset);
+
+        switch (searchMode) {
+          case 'by_nodes':
+            if (!args.nodeTypes || !Array.isArray(args.nodeTypes) || args.nodeTypes.length === 0) {
+              throw new Error('nodeTypes array is required for searchMode=by_nodes');
+            }
+            return this.listNodeTemplates(args.nodeTypes, searchLimit, searchOffset);
+          case 'by_task':
+            if (!args.task) {
+              throw new Error('task is required for searchMode=by_task');
+            }
+            return this.getTemplatesForTask(args.task, searchLimit, searchOffset);
+          case 'by_metadata':
+            return this.searchTemplatesByMetadata({
+              category: args.category,
+              complexity: args.complexity,
+              maxSetupMinutes: args.maxSetupMinutes ? Number(args.maxSetupMinutes) : undefined,
+              minSetupMinutes: args.minSetupMinutes ? Number(args.minSetupMinutes) : undefined,
+              requiredService: args.requiredService,
+              targetAudience: args.targetAudience
+            }, searchLimit, searchOffset);
+          case 'keyword':
+          default:
+            if (!args.query) {
+              throw new Error('query is required for searchMode=keyword');
+            }
+            const searchFields = args.fields as string[] | undefined;
+            return this.searchTemplates(args.query, searchLimit, searchOffset, searchFields);
+        }
+      }
       case 'validate_workflow':
         this.validateToolParams(name, args, ['workflow']);
         return this.validateWorkflow(args.workflow, args.options);
-      case 'validate_workflow_connections':
-        this.validateToolParams(name, args, ['workflow']);
-        return this.validateWorkflowConnections(args.workflow);
-      case 'validate_workflow_expressions':
-        this.validateToolParams(name, args, ['workflow']);
-        return this.validateWorkflowExpressions(args.workflow);
-      
+
       // n8n Management Tools (if API is configured)
       case 'n8n_create_workflow':
         this.validateToolParams(name, args, ['name', 'nodes', 'connections']);
         return n8nHandlers.handleCreateWorkflow(args, this.instanceContext);
-      case 'n8n_get_workflow':
+      case 'n8n_get_workflow': {
         this.validateToolParams(name, args, ['id']);
-        return n8nHandlers.handleGetWorkflow(args, this.instanceContext);
-      case 'n8n_get_workflow_details':
-        this.validateToolParams(name, args, ['id']);
-        return n8nHandlers.handleGetWorkflowDetails(args, this.instanceContext);
-      case 'n8n_get_workflow_structure':
-        this.validateToolParams(name, args, ['id']);
-        return n8nHandlers.handleGetWorkflowStructure(args, this.instanceContext);
-      case 'n8n_get_workflow_minimal':
-        this.validateToolParams(name, args, ['id']);
-        return n8nHandlers.handleGetWorkflowMinimal(args, this.instanceContext);
+        const workflowMode = args.mode || 'full';
+        switch (workflowMode) {
+          case 'details':
+            return n8nHandlers.handleGetWorkflowDetails(args, this.instanceContext);
+          case 'structure':
+            return n8nHandlers.handleGetWorkflowStructure(args, this.instanceContext);
+          case 'minimal':
+            return n8nHandlers.handleGetWorkflowMinimal(args, this.instanceContext);
+          case 'full':
+          default:
+            return n8nHandlers.handleGetWorkflow(args, this.instanceContext);
+        }
+      }
       case 'n8n_update_full_workflow':
         this.validateToolParams(name, args, ['id']);
         return n8nHandlers.handleUpdateWorkflow(args, this.repository!, this.instanceContext);
@@ -1128,28 +1179,43 @@ export class N8NDocumentationMCPServer {
       case 'n8n_trigger_webhook_workflow':
         this.validateToolParams(name, args, ['webhookUrl']);
         return n8nHandlers.handleTriggerWebhookWorkflow(args, this.instanceContext);
-      case 'n8n_get_execution':
-        this.validateToolParams(name, args, ['id']);
-        return n8nHandlers.handleGetExecution(args, this.instanceContext);
-      case 'n8n_list_executions':
-        // No required parameters
-        return n8nHandlers.handleListExecutions(args, this.instanceContext);
-      case 'n8n_delete_execution':
-        this.validateToolParams(name, args, ['id']);
-        return n8nHandlers.handleDeleteExecution(args, this.instanceContext);
+      case 'n8n_executions': {
+        this.validateToolParams(name, args, ['action']);
+        const execAction = args.action;
+        switch (execAction) {
+          case 'get':
+            if (!args.id) {
+              throw new Error('id is required for action=get');
+            }
+            return n8nHandlers.handleGetExecution(args, this.instanceContext);
+          case 'list':
+            return n8nHandlers.handleListExecutions(args, this.instanceContext);
+          case 'delete':
+            if (!args.id) {
+              throw new Error('id is required for action=delete');
+            }
+            return n8nHandlers.handleDeleteExecution(args, this.instanceContext);
+          default:
+            throw new Error(`Unknown action: ${execAction}. Valid actions: get, list, delete`);
+        }
+      }
       case 'n8n_health_check':
-        // No required parameters
+        // No required parameters - supports mode='status' (default) or mode='diagnostic'
+        if (args.mode === 'diagnostic') {
+          return n8nHandlers.handleDiagnostic({ params: { arguments: args } }, this.instanceContext);
+        }
         return n8nHandlers.handleHealthCheck(this.instanceContext);
-      case 'n8n_list_available_tools':
-        // No required parameters
-        return n8nHandlers.handleListAvailableTools(this.instanceContext);
-      case 'n8n_diagnostic':
-        // No required parameters
-        return n8nHandlers.handleDiagnostic({ params: { arguments: args } }, this.instanceContext);
       case 'n8n_workflow_versions':
         this.validateToolParams(name, args, ['mode']);
         return n8nHandlers.handleWorkflowVersions(args, this.repository!, this.instanceContext);
 
+      case 'n8n_deploy_template':
+        this.validateToolParams(name, args, ['templateId']);
+        await this.ensureInitialized();
+        if (!this.templateService) throw new Error('Template service not initialized');
+        if (!this.repository) throw new Error('Repository not initialized');
+        return n8nHandlers.handleDeployTemplate(args, this.templateService, this.repository, this.instanceContext);
+
       default:
         throw new Error(`Unknown tool: ${name}`);
     }
@@ -2218,6 +2284,393 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
     return result;
   }
 
+  /**
+   * Unified node information retrieval with multiple detail levels and modes.
+   *
+   * @param nodeType - Full node type identifier (e.g., "nodes-base.httpRequest" or "nodes-langchain.agent")
+   * @param detail - Information detail level (minimal, standard, full). Only applies when mode='info'.
+   *   - minimal: ~200 tokens, basic metadata only (no version info)
+   *   - standard: ~1-2K tokens, essential properties and operations (includes version info, AI-friendly default)
+   *   - full: ~3-8K tokens, complete node information with all properties (includes version info)
+   * @param mode - Operation mode determining the type of information returned:
+   *   - info: Node configuration details (respects detail level)
+   *   - versions: Complete version history with breaking changes summary
+   *   - compare: Property-level comparison between two versions (requires fromVersion)
+   *   - breaking: Breaking changes only between versions (requires fromVersion)
+   *   - migrations: Auto-migratable changes between versions (requires both fromVersion and toVersion)
+   * @param includeTypeInfo - Include type structure metadata for properties (only applies to mode='info').
+   *   Adds ~80-120 tokens per property with type category, JS type, and validation rules.
+   * @param includeExamples - Include real-world configuration examples from templates (only applies to mode='info' with detail='standard').
+   *   Adds ~200-400 tokens per example.
+   * @param fromVersion - Source version for comparison modes (required for compare, breaking, migrations).
+   *   Format: "1.0" or "2.1"
+   * @param toVersion - Target version for comparison modes (optional for compare/breaking, required for migrations).
+   *   Defaults to latest version if omitted.
+   * @returns NodeInfoResponse - Union type containing different response structures based on mode and detail parameters
+   */
+  private async getNode(
+    nodeType: string,
+    detail: string = 'standard',
+    mode: string = 'info',
+    includeTypeInfo?: boolean,
+    includeExamples?: boolean,
+    fromVersion?: string,
+    toVersion?: string
+  ): Promise<NodeInfoResponse> {
+    await this.ensureInitialized();
+    if (!this.repository) throw new Error('Repository not initialized');
+
+    // Validate parameters
+    const validDetailLevels = ['minimal', 'standard', 'full'];
+    const validModes = ['info', 'versions', 'compare', 'breaking', 'migrations'];
+
+    if (!validDetailLevels.includes(detail)) {
+      throw new Error(`get_node: Invalid detail level "${detail}". Valid options: ${validDetailLevels.join(', ')}`);
+    }
+
+    if (!validModes.includes(mode)) {
+      throw new Error(`get_node: Invalid mode "${mode}". Valid options: ${validModes.join(', ')}`);
+    }
+
+    const normalizedType = NodeTypeNormalizer.normalizeToFullForm(nodeType);
+
+    // Version modes - detail level ignored
+    if (mode !== 'info') {
+      return this.handleVersionMode(
+        normalizedType,
+        mode,
+        fromVersion,
+        toVersion
+      );
+    }
+
+    // Info mode - respect detail level
+    return this.handleInfoMode(
+      normalizedType,
+      detail,
+      includeTypeInfo,
+      includeExamples
+    );
+  }
+
+  /**
+   * Handle info mode - returns node information at specified detail level
+   */
+  private async handleInfoMode(
+    nodeType: string,
+    detail: string,
+    includeTypeInfo?: boolean,
+    includeExamples?: boolean
+  ): Promise<NodeMinimalInfo | NodeStandardInfo | NodeFullInfo> {
+    switch (detail) {
+      case 'minimal': {
+        // Get basic node metadata only (no version info for minimal mode)
+        let node = this.repository!.getNode(nodeType);
+
+        if (!node) {
+          const alternatives = getNodeTypeAlternatives(nodeType);
+          for (const alt of alternatives) {
+            const found = this.repository!.getNode(alt);
+            if (found) {
+              node = found;
+              break;
+            }
+          }
+        }
+
+        if (!node) {
+          throw new Error(`Node ${nodeType} not found`);
+        }
+
+        return {
+          nodeType: node.nodeType,
+          workflowNodeType: getWorkflowNodeType(node.package ?? 'n8n-nodes-base', node.nodeType),
+          displayName: node.displayName,
+          description: node.description,
+          category: node.category,
+          package: node.package,
+          isAITool: node.isAITool,
+          isTrigger: node.isTrigger,
+          isWebhook: node.isWebhook
+        };
+      }
+
+      case 'standard': {
+        // Use existing getNodeEssentials logic
+        const essentials = await this.getNodeEssentials(nodeType, includeExamples);
+        const versionSummary = this.getVersionSummary(nodeType);
+
+        // Apply type info enrichment if requested
+        if (includeTypeInfo) {
+          essentials.requiredProperties = this.enrichPropertiesWithTypeInfo(essentials.requiredProperties);
+          essentials.commonProperties = this.enrichPropertiesWithTypeInfo(essentials.commonProperties);
+        }
+
+        return {
+          ...essentials,
+          versionInfo: versionSummary
+        };
+      }
+
+      case 'full': {
+        // Use existing getNodeInfo logic
+        const fullInfo = await this.getNodeInfo(nodeType);
+        const versionSummary = this.getVersionSummary(nodeType);
+
+        // Apply type info enrichment if requested
+        if (includeTypeInfo && fullInfo.properties) {
+          fullInfo.properties = this.enrichPropertiesWithTypeInfo(fullInfo.properties);
+        }
+
+        return {
+          ...fullInfo,
+          versionInfo: versionSummary
+        };
+      }
+
+      default:
+        throw new Error(`Unknown detail level: ${detail}`);
+    }
+  }
+
+  /**
+   * Handle version modes - returns version history and comparison data
+   */
+  private async handleVersionMode(
+    nodeType: string,
+    mode: string,
+    fromVersion?: string,
+    toVersion?: string
+  ): Promise<VersionHistoryInfo | VersionComparisonInfo> {
+    switch (mode) {
+      case 'versions':
+        return this.getVersionHistory(nodeType);
+
+      case 'compare':
+        if (!fromVersion) {
+          throw new Error(`get_node: fromVersion is required for compare mode (nodeType: ${nodeType})`);
+        }
+        return this.compareVersions(nodeType, fromVersion, toVersion);
+
+      case 'breaking':
+        if (!fromVersion) {
+          throw new Error(`get_node: fromVersion is required for breaking mode (nodeType: ${nodeType})`);
+        }
+        return this.getBreakingChanges(nodeType, fromVersion, toVersion);
+
+      case 'migrations':
+        if (!fromVersion || !toVersion) {
+          throw new Error(`get_node: Both fromVersion and toVersion are required for migrations mode (nodeType: ${nodeType})`);
+        }
+        return this.getMigrations(nodeType, fromVersion, toVersion);
+
+      default:
+        throw new Error(`get_node: Unknown mode: ${mode} (nodeType: ${nodeType})`);
+    }
+  }
+
+  /**
+   * Get version summary (always included in info mode responses)
+   * Cached for 24 hours to improve performance
+   */
+  private getVersionSummary(nodeType: string): VersionSummary {
+    const cacheKey = `version-summary:${nodeType}`;
+    const cached = this.cache.get(cacheKey) as VersionSummary | null;
+
+    if (cached) {
+      return cached;
+    }
+
+    const versions = this.repository!.getNodeVersions(nodeType);
+    const latest = this.repository!.getLatestNodeVersion(nodeType);
+
+    const summary: VersionSummary = {
+      currentVersion: latest?.version || 'unknown',
+      totalVersions: versions.length,
+      hasVersionHistory: versions.length > 0
+    };
+
+    // Cache for 24 hours (86400000 ms)
+    this.cache.set(cacheKey, summary, 86400000);
+
+    return summary;
+  }
+
+  /**
+   * Get complete version history for a node
+   */
+  private getVersionHistory(nodeType: string): any {
+    const versions = this.repository!.getNodeVersions(nodeType);
+
+    return {
+      nodeType,
+      totalVersions: versions.length,
+      versions: versions.map(v => ({
+        version: v.version,
+        isCurrent: v.isCurrentMax,
+        minimumN8nVersion: v.minimumN8nVersion,
+        releasedAt: v.releasedAt,
+        hasBreakingChanges: (v.breakingChanges || []).length > 0,
+        breakingChangesCount: (v.breakingChanges || []).length,
+        deprecatedProperties: v.deprecatedProperties || [],
+        addedProperties: v.addedProperties || []
+      })),
+      available: versions.length > 0,
+      message: versions.length === 0 ?
+        'No version history available. Version tracking may not be enabled for this node.' :
+        undefined
+    };
+  }
+
+  /**
+   * Compare two versions of a node
+   */
+  private compareVersions(
+    nodeType: string,
+    fromVersion: string,
+    toVersion?: string
+  ): any {
+    const latest = this.repository!.getLatestNodeVersion(nodeType);
+    const targetVersion = toVersion || latest?.version;
+
+    if (!targetVersion) {
+      throw new Error('No target version available');
+    }
+
+    const changes = this.repository!.getPropertyChanges(
+      nodeType,
+      fromVersion,
+      targetVersion
+    );
+
+    return {
+      nodeType,
+      fromVersion,
+      toVersion: targetVersion,
+      totalChanges: changes.length,
+      breakingChanges: changes.filter(c => c.isBreaking).length,
+      changes: changes.map(c => ({
+        property: c.propertyName,
+        changeType: c.changeType,
+        isBreaking: c.isBreaking,
+        severity: c.severity,
+        oldValue: c.oldValue,
+        newValue: c.newValue,
+        migrationHint: c.migrationHint,
+        autoMigratable: c.autoMigratable
+      }))
+    };
+  }
+
+  /**
+   * Get breaking changes between versions
+   */
+  private getBreakingChanges(
+    nodeType: string,
+    fromVersion: string,
+    toVersion?: string
+  ): any {
+    const breakingChanges = this.repository!.getBreakingChanges(
+      nodeType,
+      fromVersion,
+      toVersion
+    );
+
+    return {
+      nodeType,
+      fromVersion,
+      toVersion: toVersion || 'latest',
+      totalBreakingChanges: breakingChanges.length,
+      changes: breakingChanges.map(c => ({
+        fromVersion: c.fromVersion,
+        toVersion: c.toVersion,
+        property: c.propertyName,
+        changeType: c.changeType,
+        severity: c.severity,
+        migrationHint: c.migrationHint,
+        oldValue: c.oldValue,
+        newValue: c.newValue
+      })),
+      upgradeSafe: breakingChanges.length === 0
+    };
+  }
+
+  /**
+   * Get auto-migratable changes between versions
+   */
+  private getMigrations(
+    nodeType: string,
+    fromVersion: string,
+    toVersion: string
+  ): any {
+    const migrations = this.repository!.getAutoMigratableChanges(
+      nodeType,
+      fromVersion,
+      toVersion
+    );
+
+    const allChanges = this.repository!.getPropertyChanges(
+      nodeType,
+      fromVersion,
+      toVersion
+    );
+
+    return {
+      nodeType,
+      fromVersion,
+      toVersion,
+      autoMigratableChanges: migrations.length,
+      totalChanges: allChanges.length,
+      migrations: migrations.map(m => ({
+        property: m.propertyName,
+        changeType: m.changeType,
+        migrationStrategy: m.migrationStrategy,
+        severity: m.severity
+      })),
+      requiresManualMigration: migrations.length < allChanges.length
+    };
+  }
+
+  /**
+   * Enrich property with type structure metadata
+   */
+  private enrichPropertyWithTypeInfo(property: any): any {
+    if (!property || !property.type) return property;
+
+    const structure = TypeStructureService.getStructure(property.type);
+    if (!structure) return property;
+
+    return {
+      ...property,
+      typeInfo: {
+        category: structure.type,
+        jsType: structure.jsType,
+        description: structure.description,
+        isComplex: TypeStructureService.isComplexType(property.type),
+        isPrimitive: TypeStructureService.isPrimitiveType(property.type),
+        allowsExpressions: structure.validation?.allowExpressions ?? true,
+        allowsEmpty: structure.validation?.allowEmpty ?? false,
+        ...(structure.structure && {
+          structureHints: {
+            hasProperties: !!structure.structure.properties,
+            hasItems: !!structure.structure.items,
+            isFlexible: structure.structure.flexible ?? false,
+            requiredFields: structure.structure.required ?? []
+          }
+        }),
+        ...(structure.notes && { notes: structure.notes })
+      }
+    };
+  }
+
+  /**
+   * Enrich an array of properties with type structure metadata
+   */
+  private enrichPropertiesWithTypeInfo(properties: any[]): any[] {
+    if (!properties || !Array.isArray(properties)) return properties;
+    return properties.map((prop: any) => this.enrichPropertyWithTypeInfo(prop));
+  }
+
   private async searchNodeProperties(nodeType: string, query: string, maxResults: number = 20): Promise<any> {
     await this.ensureInitialized();
     if (!this.repository) throw new Error('Repository not initialized');

src/mcp/tool-docs/configuration/get-node-as-tool-info.ts

@@ -1,71 +0,0 @@
-import { ToolDocumentation } from '../types';
-
-export const getNodeAsToolInfoDoc: ToolDocumentation = {
-  name: 'get_node_as_tool_info',
-  category: 'configuration',
-  essentials: {
-    description: 'Explains how to use ANY node as an AI tool with requirements and examples.',
-    keyParameters: ['nodeType'],
-    example: 'get_node_as_tool_info({nodeType: "nodes-base.slack"})',
-    performance: 'Fast - returns guidance and examples',
-    tips: [
-      'ANY node can be used as AI tool, not just AI-marked ones',
-      'Community nodes need N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true',
-      'Provides specific use cases and connection requirements'
-    ]
-  },
-  full: {
-    description: `Shows how to use any n8n node as an AI tool in AI Agent workflows. In n8n, ANY node can be connected to an AI Agent's tool port, allowing the AI to use that node's functionality. This tool provides specific guidance, requirements, and examples for using a node as an AI tool.`,
-    parameters: {
-      nodeType: {
-        type: 'string',
-        required: true,
-        description: 'Full node type WITH prefix: "nodes-base.slack", "nodes-base.googleSheets", etc.',
-        examples: [
-          'nodes-base.slack',
-          'nodes-base.httpRequest',
-          'nodes-base.googleSheets',
-          'nodes-langchain.documentLoader'
-        ]
-      }
-    },
-    returns: `Object containing:
-- nodeType: The node's full type identifier
-- displayName: Human-readable name
-- isMarkedAsAITool: Whether node has usableAsTool property
-- aiToolCapabilities: Detailed AI tool usage information including:
-  - canBeUsedAsTool: Always true in n8n
-  - requiresEnvironmentVariable: For community nodes
-  - commonUseCases: Specific AI tool use cases
-  - requirements: Connection and environment setup
-  - examples: Code examples for common scenarios
-  - tips: Best practices for AI tool usage`,
-    examples: [
-      'get_node_as_tool_info({nodeType: "nodes-base.slack"}) - Get AI tool guidance for Slack',
-      'get_node_as_tool_info({nodeType: "nodes-base.httpRequest"}) - Learn to use HTTP Request as AI tool',
-      'get_node_as_tool_info({nodeType: "nodes-base.postgres"}) - Database queries as AI tools'
-    ],
-    useCases: [
-      'Understanding how to connect any node to AI Agent',
-      'Learning environment requirements for community nodes',
-      'Getting specific use case examples for AI tool usage',
-      'Checking if a node is optimized for AI usage',
-      'Understanding credential requirements for AI tools'
-    ],
-    performance: 'Very fast - returns pre-computed guidance and examples',
-    bestPractices: [
-      'Use this before configuring nodes as AI tools',
-      'Check environment requirements for community nodes',
-      'Review common use cases to understand best applications',
-      'Test nodes independently before connecting to AI Agent',
-      'Give tools descriptive names in AI Agent configuration'
-    ],
-    pitfalls: [
-      'Community nodes require environment variable to be used as tools',
-      'Not all nodes make sense as AI tools (e.g., triggers)',
-      'Some nodes require specific credentials configuration',
-      'Tool descriptions in AI Agent must be clear and detailed'
-    ],
-    relatedTools: ['list_ai_tools', 'get_node_essentials', 'validate_node_operation']
-  }
-};

src/mcp/tool-docs/configuration/get-node-documentation.ts

@@ -1,45 +0,0 @@
-import { ToolDocumentation } from '../types';
-
-export const getNodeDocumentationDoc: ToolDocumentation = {
-  name: 'get_node_documentation',
-  category: 'configuration',
-  essentials: {
-    description: 'Get readable docs with examples/auth/patterns. Better than raw schema! 87% coverage. Format: "nodes-base.slack"',
-    keyParameters: ['nodeType'],
-    example: 'get_node_documentation({nodeType: "nodes-base.slack"})',
-    performance: 'Fast - pre-parsed',
-    tips: [
-      '87% coverage',
-      'Includes auth examples',
-      'Human-readable format'
-    ]
-  },
-  full: {
-    description: 'Returns human-readable documentation parsed from n8n-docs including examples, authentication setup, and common patterns. More useful than raw schema for understanding node usage.',
-    parameters: {
-      nodeType: { type: 'string', required: true, description: 'Full node type with prefix (e.g., "nodes-base.slack")' }
-    },
-    returns: 'Parsed markdown documentation with examples, authentication guides, common patterns',
-    examples: [
-      'get_node_documentation({nodeType: "nodes-base.slack"}) - Slack usage guide',
-      'get_node_documentation({nodeType: "nodes-base.googleSheets"}) - Sheets examples'
-    ],
-    useCases: [
-      'Understanding authentication setup',
-      'Finding usage examples',
-      'Learning common patterns'
-    ],
-    performance: 'Fast - Pre-parsed documentation stored in database',
-    bestPractices: [
-      'Use for learning node usage',
-      'Check coverage with get_database_statistics',
-      'Combine with get_node_essentials'
-    ],
-    pitfalls: [
-      'Not all nodes have docs (87% coverage)',
-      'May be outdated for new features',
-      'Requires full node type prefix'
-    ],
-    relatedTools: ['get_node_info', 'get_node_essentials', 'search_nodes']
-  }
-};

src/mcp/tool-docs/configuration/get-node-essentials.ts

@@ -1,86 +0,0 @@
-import { ToolDocumentation } from '../types';
-
-export const getNodeEssentialsDoc: ToolDocumentation = {
-  name: 'get_node_essentials',
-  category: 'configuration',
-  essentials: {
-    description: 'Returns only the most commonly-used properties for a node (10-20 fields). Response is 95% smaller than get_node_info (5KB vs 100KB+). Essential properties include required fields, common options, and authentication settings. Use validate_node_operation for working configurations.',
-    keyParameters: ['nodeType'],
-    example: 'get_node_essentials({nodeType: "nodes-base.slack"})',
-    performance: '<10ms, ~5KB response',
-    tips: [
-      'Always use this before get_node_info',
-      'Use validate_node_operation for examples',
-      'Perfect for understanding node structure'
-    ]
-  },
-  full: {
-    description: 'Returns a curated subset of node properties focusing on the most commonly-used fields. Essential properties are hand-picked for each node type and include: required fields, primary operations, authentication options, and the most frequent configuration patterns. NOTE: Examples have been removed to avoid confusion - use validate_node_operation to get working configurations with proper validation.',
-    parameters: {
-      nodeType: { type: 'string', description: 'Full node type with prefix, e.g., "nodes-base.slack", "nodes-base.httpRequest"', required: true }
-    },
-    returns: `Object containing:
-{
-  "nodeType": "nodes-base.slack",
-  "displayName": "Slack",
-  "description": "Consume Slack API",
-  "category": "output",
-  "version": "2.3",
-  "requiredProperties": [],  // Most nodes have no strictly required fields
-  "commonProperties": [
-    {
-      "name": "resource",
-      "displayName": "Resource",
-      "type": "options",
-      "options": ["channel", "message", "user"],
-      "default": "message"
-    },
-    {
-      "name": "operation",
-      "displayName": "Operation", 
-      "type": "options",
-      "options": ["post", "update", "delete"],
-      "default": "post"
-    },
-    // ... 10-20 most common properties
-  ],
-  "operations": [
-    {"name": "Post", "description": "Post a message"},
-    {"name": "Update", "description": "Update a message"}
-  ],
-  "metadata": {
-    "totalProperties": 121,
-    "isAITool": false,
-    "hasCredentials": true
-  }
-}`,
-    examples: [
-      'get_node_essentials({nodeType: "nodes-base.httpRequest"}) - HTTP configuration basics',
-      'get_node_essentials({nodeType: "nodes-base.slack"}) - Slack messaging essentials',
-      'get_node_essentials({nodeType: "nodes-base.googleSheets"}) - Sheets operations',
-      '// Workflow: search → essentials → validate',
-      'const nodes = search_nodes({query: "database"});',
-      'const mysql = get_node_essentials({nodeType: "nodes-base.mySql"});',
-      'validate_node_operation("nodes-base.mySql", {operation: "select"}, "minimal");'
-    ],
-    useCases: [
-      'Quickly understand node structure without information overload',
-      'Identify which properties are most important',
-      'Learn node basics before diving into advanced features',
-      'Build workflows faster with curated property sets'
-    ],
-    performance: '<10ms response time, ~5KB payload (vs 100KB+ for full schema)',
-    bestPractices: [
-      'Always start with essentials, only use get_node_info if needed',
-      'Use validate_node_operation to get working configurations',
-      'Check authentication requirements first',
-      'Use search_node_properties if specific property not in essentials'
-    ],
-    pitfalls: [
-      'Advanced properties not included - use get_node_info for complete schema',
-      'Node-specific validators may require additional fields',
-      'Some nodes have 50+ properties, essentials shows only top 10-20'
-    ],
-    relatedTools: ['get_node_info for complete schema', 'search_node_properties for finding specific fields', 'validate_node_minimal to check configuration']
-  }
-};

src/mcp/tool-docs/configuration/get-node-info.ts

@@ -1,98 +0,0 @@
-import { ToolDocumentation } from '../types';
-
-export const getNodeInfoDoc: ToolDocumentation = {
-  name: 'get_node_info',
-  category: 'configuration',
-  essentials: {
-    description: 'Returns complete node schema with ALL properties (100KB+ response). Only use when you need advanced properties not in get_node_essentials. Contains 200+ properties for complex nodes like HTTP Request. Requires full prefix like "nodes-base.httpRequest".',
-    keyParameters: ['nodeType'],
-    example: 'get_node_info({nodeType: "nodes-base.slack"})',
-    performance: '100-500ms, 50-500KB response',
-    tips: [
-      'Try get_node_essentials first (95% smaller)',
-      'Use only for advanced configurations',
-      'Response may have 200+ properties'
-    ]
-  },
-  full: {
-    description: 'Returns the complete JSON schema for a node including all properties, operations, authentication methods, version information, and metadata. Response sizes range from 50KB to 500KB. Use this only when get_node_essentials doesn\'t provide the specific property you need.',
-    parameters: {
-      nodeType: { type: 'string', required: true, description: 'Full node type with prefix. Examples: "nodes-base.slack", "nodes-base.httpRequest", "nodes-langchain.openAi"' }
-    },
-    returns: `Complete node object containing:
-{
-  "displayName": "Slack",
-  "name": "slack",
-  "type": "nodes-base.slack",
-  "typeVersion": 2.2,
-  "description": "Consume Slack API",
-  "defaults": {"name": "Slack"},
-  "inputs": ["main"],
-  "outputs": ["main"],
-  "credentials": [
-    {
-      "name": "slackApi",
-      "required": true,
-      "displayOptions": {...}
-    }
-  ],
-  "properties": [
-    // 200+ property definitions including:
-    {
-      "displayName": "Resource",
-      "name": "resource",
-      "type": "options",
-      "options": ["channel", "message", "user", "file", ...],
-      "default": "message"
-    },
-    {
-      "displayName": "Operation", 
-      "name": "operation",
-      "type": "options",
-      "displayOptions": {
-        "show": {"resource": ["message"]}
-      },
-      "options": ["post", "update", "delete", "get", ...],
-      "default": "post"
-    },
-    // ... 200+ more properties with complex conditions
-  ],
-  "version": 2.2,
-  "subtitle": "={{$parameter[\"operation\"] + \": \" + $parameter[\"resource\"]}}",
-  "codex": {...},
-  "supportedWebhooks": [...]
-}`,
-    examples: [
-      'get_node_info({nodeType: "nodes-base.httpRequest"}) - 300+ properties for HTTP requests',
-      'get_node_info({nodeType: "nodes-base.googleSheets"}) - Complex operations and auth',
-      '// When to use get_node_info:',
-      '// 1. First try essentials',
-      'const essentials = get_node_essentials({nodeType: "nodes-base.slack"});',
-      '// 2. If property missing, search for it',
-      'const props = search_node_properties({nodeType: "nodes-base.slack", query: "thread"});',
-      '// 3. Only if needed, get full schema',
-      'const full = get_node_info({nodeType: "nodes-base.slack"});'
-    ],
-    useCases: [
-      'Analyzing all available operations for a node',
-      'Understanding complex property dependencies',
-      'Discovering all authentication methods',
-      'Building UI that shows all node options',
-      'Debugging property visibility conditions'
-    ],
-    performance: '100-500ms depending on node complexity. HTTP Request node: ~300KB, Simple nodes: ~50KB',
-    bestPractices: [
-      'Always try get_node_essentials first - it\'s 95% smaller',
-      'Use search_node_properties to find specific advanced properties',
-      'Cache results locally - schemas rarely change',
-      'Parse incrementally - don\'t load entire response into memory at once'
-    ],
-    pitfalls: [
-      'Response can exceed 500KB for complex nodes',
-      'Contains many rarely-used properties that add noise',
-      'Property conditions can be deeply nested and complex',
-      'Must use full node type with prefix (nodes-base.X not just X)'
-    ],
-    relatedTools: ['get_node_essentials for common properties', 'search_node_properties to find specific fields', 'get_property_dependencies to understand conditions']
-  }
-};

src/mcp/tool-docs/configuration/get-node.ts

@@ -0,0 +1,88 @@
+import { ToolDocumentation } from '../types';
+
+export const getNodeDoc: ToolDocumentation = {
+  name: 'get_node',
+  category: 'configuration',
+  essentials: {
+    description: 'Unified node information tool with progressive detail levels and multiple modes. Get node schema, docs, search properties, or version info.',
+    keyParameters: ['nodeType', 'detail', 'mode', 'includeTypeInfo', 'includeExamples'],
+    example: 'get_node({nodeType: "nodes-base.httpRequest", detail: "standard"})',
+    performance: 'Instant (<10ms) for minimal/standard, moderate for full',
+    tips: [
+      'Use detail="standard" (default) for most tasks - shows required fields',
+      'Use mode="docs" for readable markdown documentation',
+      'Use mode="search_properties" with propertyQuery to find specific fields',
+      'Use mode="versions" to check version history and breaking changes',
+      'Add includeExamples=true to get real-world configuration examples'
+    ]
+  },
+  full: {
+    description: `**Detail Levels (mode="info", default):**
+- minimal (~200 tokens): Basic metadata only - nodeType, displayName, description, category
+- standard (~1-2K tokens): Essential properties + operations - recommended for most tasks
+- full (~3-8K tokens): Complete node schema - use only when standard insufficient
+
+**Operation Modes:**
+- info (default): Node schema with configurable detail level
+- docs: Readable markdown documentation with examples and patterns
+- search_properties: Find specific properties within a node
+- versions: List all available versions with breaking changes summary
+- compare: Compare two versions with property-level changes
+- breaking: Show only breaking changes between versions
+- migrations: Show auto-migratable changes between versions`,
+    parameters: {
+      nodeType: { type: 'string', required: true, description: 'Full node type with prefix: "nodes-base.httpRequest" or "nodes-langchain.agent"' },
+      detail: { type: 'string', required: false, description: 'Detail level for mode=info: "minimal", "standard" (default), "full"' },
+      mode: { type: 'string', required: false, description: 'Operation mode: "info" (default), "docs", "search_properties", "versions", "compare", "breaking", "migrations"' },
+      includeTypeInfo: { type: 'boolean', required: false, description: 'Include type structure metadata (validation rules, JS types). Adds ~80-120 tokens per property' },
+      includeExamples: { type: 'boolean', required: false, description: 'Include real-world configuration examples from templates. Adds ~200-400 tokens per example' },
+      propertyQuery: { type: 'string', required: false, description: 'For mode=search_properties: search term to find properties (e.g., "auth", "header", "body")' },
+      maxPropertyResults: { type: 'number', required: false, description: 'For mode=search_properties: max results (default 20)' },
+      fromVersion: { type: 'string', required: false, description: 'For compare/breaking/migrations modes: source version (e.g., "1.0")' },
+      toVersion: { type: 'string', required: false, description: 'For compare mode: target version (e.g., "2.0"). Defaults to latest' }
+    },
+    returns: `Depends on mode:
+- info: Node schema with properties based on detail level
+- docs: Markdown documentation string
+- search_properties: Array of matching property paths with descriptions
+- versions: Version history with breaking changes flags
+- compare/breaking/migrations: Version comparison details`,
+    examples: [
+      '// Standard detail (recommended for AI agents)\nget_node({nodeType: "nodes-base.httpRequest"})',
+      '// Minimal for quick metadata check\nget_node({nodeType: "nodes-base.slack", detail: "minimal"})',
+      '// Full detail with examples\nget_node({nodeType: "nodes-base.googleSheets", detail: "full", includeExamples: true})',
+      '// Get readable documentation\nget_node({nodeType: "nodes-base.webhook", mode: "docs"})',
+      '// Search for authentication properties\nget_node({nodeType: "nodes-base.httpRequest", mode: "search_properties", propertyQuery: "auth"})',
+      '// Check version history\nget_node({nodeType: "nodes-base.executeWorkflow", mode: "versions"})',
+      '// Compare specific versions\nget_node({nodeType: "nodes-base.httpRequest", mode: "compare", fromVersion: "3.0", toVersion: "4.1"})'
+    ],
+    useCases: [
+      'Configure nodes for workflow building (use detail=standard)',
+      'Find specific configuration options (use mode=search_properties)',
+      'Get human-readable node documentation (use mode=docs)',
+      'Check for breaking changes before version upgrades (use mode=breaking)',
+      'Understand complex types with includeTypeInfo=true'
+    ],
+    performance: `Token costs by detail level:
+- minimal: ~200 tokens
+- standard: ~1000-2000 tokens (default)
+- full: ~3000-8000 tokens
+- includeTypeInfo: +80-120 tokens per property
+- includeExamples: +200-400 tokens per example
+- Version modes: ~400-1200 tokens`,
+    bestPractices: [
+      'Start with detail="standard" - it covers 95% of use cases',
+      'Only use detail="full" if standard is missing required properties',
+      'Use mode="docs" when explaining nodes to users',
+      'Combine includeTypeInfo=true for complex nodes (filter, resourceMapper)',
+      'Check version history before configuring versioned nodes'
+    ],
+    pitfalls: [
+      'detail="full" returns large responses (~100KB) - use sparingly',
+      'Node type must include prefix (nodes-base. or nodes-langchain.)',
+      'includeExamples only works with mode=info and detail=standard',
+      'Version modes require nodes with multiple versions in database'
+    ],
+    relatedTools: ['search_nodes', 'validate_node', 'validate_workflow']
+  }
+};

src/mcp/tool-docs/configuration/get-property-dependencies.ts

@@ -1,79 +0,0 @@
-import { ToolDocumentation } from '../types';
-
-export const getPropertyDependenciesDoc: ToolDocumentation = {
-  name: 'get_property_dependencies',
-  category: 'configuration',
-  essentials: {
-    description: 'Shows property dependencies and visibility rules - which fields appear when.',
-    keyParameters: ['nodeType', 'config?'],
-    example: 'get_property_dependencies({nodeType: "nodes-base.httpRequest"})',
-    performance: 'Fast - analyzes property conditions',
-    tips: [
-      'Shows which properties depend on other property values',
-      'Test visibility impact with optional config parameter',
-      'Helps understand complex conditional property displays'
-    ]
-  },
-  full: {
-    description: `Analyzes property dependencies and visibility conditions for a node. Shows which properties control the visibility of other properties (e.g., sendBody=true reveals body-related fields). Optionally test how a specific configuration affects property visibility.`,
-    parameters: {
-      nodeType: {
-        type: 'string',
-        required: true,
-        description: 'The node type to analyze (e.g., "nodes-base.httpRequest")',
-        examples: [
-          'nodes-base.httpRequest',
-          'nodes-base.slack',
-          'nodes-base.if',
-          'nodes-base.switch'
-        ]
-      },
-      config: {
-        type: 'object',
-        required: false,
-        description: 'Optional partial configuration to check visibility impact',
-        examples: [
-          '{ method: "POST", sendBody: true }',
-          '{ operation: "create", resource: "contact" }',
-          '{ mode: "rules" }'
-        ]
-      }
-    },
-    returns: `Object containing:
-- nodeType: The analyzed node type
-- displayName: Human-readable node name
-- controllingProperties: Properties that control visibility of others
-- dependentProperties: Properties whose visibility depends on others
-- complexDependencies: Multi-condition dependencies
-- currentConfig: If config provided, shows:
-  - providedValues: The configuration you passed
-  - visibilityImpact: Which properties are visible/hidden`,
-    examples: [
-      'get_property_dependencies({nodeType: "nodes-base.httpRequest"}) - Analyze HTTP Request dependencies',
-      'get_property_dependencies({nodeType: "nodes-base.httpRequest", config: {sendBody: true}}) - Test visibility with sendBody enabled',
-      'get_property_dependencies({nodeType: "nodes-base.if", config: {mode: "rules"}}) - Check If node in rules mode'
-    ],
-    useCases: [
-      'Understanding which properties control others',
-      'Debugging why certain fields are not visible',
-      'Building dynamic UIs that match n8n behavior',
-      'Testing configurations before applying them',
-      'Understanding complex node property relationships'
-    ],
-    performance: 'Fast - analyzes property metadata without database queries',
-    bestPractices: [
-      'Use before configuring complex nodes with many conditional fields',
-      'Test different config values to understand visibility rules',
-      'Check dependencies when properties seem to be missing',
-      'Use for nodes with multiple operation modes (Slack, Google Sheets)',
-      'Combine with search_node_properties to find specific fields'
-    ],
-    pitfalls: [
-      'Some properties have complex multi-condition dependencies',
-      'Visibility rules can be nested (property A controls B which controls C)',
-      'Not all hidden properties are due to dependencies (some are deprecated)',
-      'Config parameter only tests visibility, does not validate values'
-    ],
-    relatedTools: ['search_node_properties', 'get_node_essentials', 'validate_node_operation']
-  }
-};

src/mcp/tool-docs/configuration/index.ts

@@ -1,6 +1 @@
-export { getNodeInfoDoc } from './get-node-info';
-export { getNodeEssentialsDoc } from './get-node-essentials';
-export { getNodeDocumentationDoc } from './get-node-documentation';
-export { searchNodePropertiesDoc } from './search-node-properties';
-export { getNodeAsToolInfoDoc } from './get-node-as-tool-info';
-export { getPropertyDependenciesDoc } from './get-property-dependencies';
+export { getNodeDoc } from './get-node';

src/mcp/tool-docs/configuration/search-node-properties.ts

@@ -1,97 +0,0 @@
-import { ToolDocumentation } from '../types';
-
-export const searchNodePropertiesDoc: ToolDocumentation = {
-  name: 'search_node_properties',
-  category: 'configuration',
-  essentials: {
-    description: 'Find specific properties in a node without downloading all 200+ properties.',
-    keyParameters: ['nodeType', 'query'],
-    example: 'search_node_properties({nodeType: "nodes-base.httpRequest", query: "auth"})',
-    performance: 'Fast - searches indexed properties',
-    tips: [
-      'Search for "auth", "header", "body", "json", "credential"',
-      'Returns property paths and descriptions',
-      'Much faster than get_node_info for finding specific fields'
-    ]
-  },
-  full: {
-    description: `Searches for specific properties within a node's configuration schema. Essential for finding authentication fields, headers, body parameters, or any specific property without downloading the entire node schema (which can be 100KB+). Returns matching properties with their paths, types, and descriptions.`,
-    parameters: {
-      nodeType: {
-        type: 'string',
-        required: true,
-        description: 'Full type with prefix',
-        examples: [
-          'nodes-base.httpRequest',
-          'nodes-base.slack',
-          'nodes-base.postgres',
-          'nodes-base.googleSheets'
-        ]
-      },
-      query: {
-        type: 'string',
-        required: true,
-        description: 'Property to find: "auth", "header", "body", "json"',
-        examples: [
-          'auth',
-          'header',
-          'body',
-          'json',
-          'credential',
-          'timeout',
-          'retry',
-          'pagination'
-        ]
-      },
-      maxResults: {
-        type: 'number',
-        required: false,
-        description: 'Max results (default 20)',
-        default: 20
-      }
-    },
-    returns: `Object containing:
-- nodeType: The searched node type
-- query: Your search term
-- matches: Array of matching properties with:
-  - name: Property identifier
-  - displayName: Human-readable name
-  - type: Property type (string, number, options, etc.)
-  - description: Property description
-  - path: Full path to property (for nested properties)
-  - required: Whether property is required
-  - default: Default value if any
-  - options: Available options for selection properties
-  - showWhen: Visibility conditions
-- totalMatches: Number of matches found
-- searchedIn: Total properties searched`,
-    examples: [
-      'search_node_properties({nodeType: "nodes-base.httpRequest", query: "auth"}) - Find authentication fields',
-      'search_node_properties({nodeType: "nodes-base.slack", query: "channel"}) - Find channel-related properties',
-      'search_node_properties({nodeType: "nodes-base.postgres", query: "query"}) - Find query fields',
-      'search_node_properties({nodeType: "nodes-base.webhook", query: "response"}) - Find response options'
-    ],
-    useCases: [
-      'Finding authentication/credential fields quickly',
-      'Locating specific parameters without full node info',
-      'Discovering header or body configuration options',
-      'Finding nested properties in complex nodes',
-      'Checking if a node supports specific features (retry, pagination, etc.)'
-    ],
-    performance: 'Very fast - searches pre-indexed property metadata',
-    bestPractices: [
-      'Use before get_node_info to find specific properties',
-      'Search for common terms: auth, header, body, credential',
-      'Check showWhen conditions to understand visibility',
-      'Use with get_property_dependencies for complete understanding',
-      'Limit results if you only need to check existence'
-    ],
-    pitfalls: [
-      'Some properties may be hidden due to visibility conditions',
-      'Property names may differ from display names',
-      'Nested properties show full path (e.g., "options.retry.limit")',
-      'Search is case-sensitive for property names'
-    ],
-    relatedTools: ['get_node_essentials', 'get_property_dependencies', 'get_node_info']
-  }
-};

src/mcp/tool-docs/discovery/get-database-statistics.ts

@@ -1,67 +0,0 @@
-import { ToolDocumentation } from '../types';
-
-export const getDatabaseStatisticsDoc: ToolDocumentation = {
-  name: 'get_database_statistics',
-  category: 'discovery',
-  essentials: {
-    description: 'Returns database health metrics and node inventory. Shows 525 total nodes, 263 AI-capable nodes, 104 triggers, with 87% documentation coverage. Primary use: verify MCP connection is working correctly.',
-    keyParameters: [],
-    example: 'get_database_statistics()',
-    performance: 'Instant',
-    tips: [
-      'First tool to call when testing MCP connection',
-      'Shows exact counts for all node categories',
-      'Documentation coverage indicates data quality'
-    ]
-  },
-  full: {
-    description: 'Returns comprehensive database statistics showing the complete inventory of n8n nodes, their categories, documentation coverage, and package distribution. Essential for verifying MCP connectivity and understanding available resources.',
-    parameters: {},
-    returns: `Object containing:
-{
-  "total_nodes": 525,              // All nodes in database
-  "nodes_with_properties": 520,    // Nodes with extracted properties (99%)
-  "nodes_with_operations": 334,    // Nodes with multiple operations (64%)
-  "ai_tools": 263,                 // AI-capable nodes
-  "triggers": 104,                 // Workflow trigger nodes
-  "documentation_coverage": "87%", // Nodes with official docs
-  "packages": {
-    "n8n-nodes-base": 456,         // Core n8n nodes
-    "@n8n/n8n-nodes-langchain": 69 // AI/LangChain nodes
-  },
-  "categories": {
-    "trigger": 104,
-    "transform": 250,
-    "output": 45,
-    "input": 38,
-    "AI": 88
-  }
-}`,
-    examples: [
-      'get_database_statistics() - Returns complete statistics object',
-      '// Common check:',
-      'const stats = get_database_statistics();',
-      'if (stats.total_nodes < 500) console.error("Database incomplete!");'
-    ],
-    useCases: [
-      'Verify MCP server is connected and responding',
-      'Check if database rebuild is needed (low node count)',
-      'Monitor documentation coverage improvements',
-      'Validate AI tools availability for workflows',
-      'Audit node distribution across packages'
-    ],
-    performance: 'Instant (<1ms) - Statistics are pre-calculated and cached',
-    bestPractices: [
-      'Call this first to verify MCP connection before other operations',
-      'Check total_nodes >= 500 to ensure complete database',
-      'Monitor documentation_coverage for data quality',
-      'Use ai_tools count to verify AI capabilities'
-    ],
-    pitfalls: [
-      'Statistics are cached at database build time, not real-time',
-      'Won\'t reflect changes until database is rebuilt',
-      'Package counts may vary with n8n version updates'
-    ],
-    relatedTools: ['list_nodes for detailed node listing', 'list_ai_tools for AI nodes', 'n8n_health_check for API connectivity']
-  }
-};

src/mcp/tool-docs/discovery/index.ts

@@ -1,4 +1 @@
 export { searchNodesDoc } from './search-nodes';
-export { listNodesDoc } from './list-nodes';
-export { listAiToolsDoc } from './list-ai-tools';
-export { getDatabaseStatisticsDoc } from './get-database-statistics';

src/mcp/tool-docs/discovery/list-ai-tools.ts

@@ -1,51 +0,0 @@
-import { ToolDocumentation } from '../types';
-
-export const listAiToolsDoc: ToolDocumentation = {
-  name: 'list_ai_tools',
-  category: 'discovery',
-  essentials: {
-    description: 'DEPRECATED: Basic list of 263 AI nodes. For comprehensive AI Agent guidance, use tools_documentation({topic: "ai_agents_guide"}). That guide covers architecture, connections, tools, validation, and best practices. Use search_nodes({query: "AI", includeExamples: true}) for AI nodes with working examples.',
-    keyParameters: [],
-    example: 'tools_documentation({topic: "ai_agents_guide"}) // Recommended alternative',
-    performance: 'Instant (cached)',
-    tips: [
-      'NEW: Use ai_agents_guide for comprehensive AI workflow documentation',
-      'Use search_nodes({includeExamples: true}) for AI nodes with real-world examples',
-      'ANY node can be an AI tool - not limited to AI-specific nodes',
-      'Use get_node_as_tool_info for guidance on any node'
-    ]
-  },
-  full: {
-    description: '**DEPRECATED in favor of ai_agents_guide**. Lists 263 nodes with built-in AI capabilities. For comprehensive documentation on building AI Agent workflows, use tools_documentation({topic: "ai_agents_guide"}) which covers architecture, the 8 AI connection types, validation, and best practices with real examples. IMPORTANT: This basic list is NOT a complete guide - use the full AI Agents guide instead.',
-    parameters: {},
-    returns: 'Array of 263 AI-optimized nodes. RECOMMENDED: Use ai_agents_guide for comprehensive guidance, or search_nodes({query: "AI", includeExamples: true}) for AI nodes with working configuration examples.',
-    examples: [
-      '// RECOMMENDED: Use the comprehensive AI Agents guide',
-      'tools_documentation({topic: "ai_agents_guide"})',
-      '',
-      '// Or search for AI nodes with real-world examples',
-      'search_nodes({query: "AI Agent", includeExamples: true})',
-      '',
-      '// Basic list (deprecated)',
-      'list_ai_tools() - Returns 263 AI-optimized nodes'
-    ],
-    useCases: [
-      'Discover AI model integrations (OpenAI, Anthropic, Google AI)',
-      'Find vector databases for RAG applications',
-      'Locate embedding generators and processors',
-      'Build AI agent tool chains with ANY n8n node'
-    ],
-    performance: 'Instant - results are pre-cached in memory',
-    bestPractices: [
-      'Remember: ANY node works as an AI tool when connected to AI Agent',
-      'Common non-AI nodes used as tools: Slack (messaging), Google Sheets (data), HTTP Request (APIs), Code (custom logic)',
-      'For community nodes: set N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true'
-    ],
-    pitfalls: [
-      'This list is NOT exhaustive - it only shows nodes with AI-specific features',
-      'Don\'t limit yourself to this list when building AI workflows',
-      'Community nodes require environment variable to work as tools'
-    ],
-    relatedTools: ['get_node_as_tool_info for any node usage', 'search_nodes to find specific nodes', 'get_node_essentials to configure nodes']
-  }
-};

src/mcp/tool-docs/discovery/list-nodes.ts

@@ -1,52 +0,0 @@
-import { ToolDocumentation } from '../types';
-
-export const listNodesDoc: ToolDocumentation = {
-  name: 'list_nodes',
-  category: 'discovery',
-  essentials: {
-    description: 'Lists n8n nodes with filtering options. Returns up to 525 total nodes. Default limit is 50, use limit:200 to get all nodes. Filter by category to find specific node types like triggers (104 nodes) or AI nodes (263 nodes).',
-    keyParameters: ['category', 'package', 'limit', 'isAITool'],
-    example: 'list_nodes({limit:200})',
-    performance: '<10ms for any query size',
-    tips: [
-      'Use limit:200 to get all 525 nodes',
-      'Categories: trigger (104), transform (250+), output/input (50+)',
-      'Use search_nodes for keyword search'
-    ]
-  },
-  full: {
-    description: 'Lists n8n nodes with comprehensive filtering options. Returns an array of node metadata including type, name, description, and category. Database contains 525 total nodes: 456 from n8n-nodes-base package and 69 from @n8n/n8n-nodes-langchain package.',
-    parameters: {
-      category: { type: 'string', description: 'Filter by category: "trigger" (104 nodes), "transform" (250+ nodes), "output", "input", or "AI"', required: false },
-      package: { type: 'string', description: 'Filter by package: "n8n-nodes-base" (456 core nodes) or "@n8n/n8n-nodes-langchain" (69 AI nodes)', required: false },
-      limit: { type: 'number', description: 'Maximum results to return. Default: 50. Use 200+ to get all 525 nodes', required: false },
-      isAITool: { type: 'boolean', description: 'Filter to show only AI-capable nodes (263 nodes)', required: false },
-      developmentStyle: { type: 'string', description: 'Filter by style: "programmatic" or "declarative". Most nodes are programmatic', required: false }
-    },
-    returns: 'Array of node objects, each containing: nodeType (e.g., "nodes-base.webhook"), displayName (e.g., "Webhook"), description, category, package, isAITool flag',
-    examples: [
-      'list_nodes({limit:200}) - Returns all 525 nodes',
-      'list_nodes({category:"trigger"}) - Returns 104 trigger nodes (Webhook, Schedule, Email Trigger, etc.)',
-      'list_nodes({package:"@n8n/n8n-nodes-langchain"}) - Returns 69 AI/LangChain nodes',
-      'list_nodes({isAITool:true}) - Returns 263 AI-capable nodes',
-      'list_nodes({category:"trigger", isAITool:true}) - Combines filters for AI-capable triggers'
-    ],
-    useCases: [
-      'Browse all available nodes when building workflows',
-      'Find all trigger nodes to start workflows',
-      'Discover AI/ML nodes for intelligent automation',
-      'Check available nodes in specific packages'
-    ],
-    performance: '<10ms for any query size. Results are cached in memory',
-    bestPractices: [
-      'Use limit:200 when you need the complete node inventory',
-      'Filter by category for focused discovery',
-      'Combine with get_node_essentials to configure selected nodes'
-    ],
-    pitfalls: [
-      'No text search capability - use search_nodes for keyword search',
-      'developmentStyle filter rarely useful - most nodes are "programmatic"'
-    ],
-    relatedTools: ['search_nodes for keyword search', 'list_ai_tools for AI-specific discovery', 'get_node_essentials to configure nodes']
-  }
-};

src/mcp/tool-docs/discovery/search-nodes.ts

@@ -4,7 +4,7 @@ export const searchNodesDoc: ToolDocumentation = {
   name: 'search_nodes',
   category: 'discovery',
   essentials: {
-    description: 'Text search across node names and descriptions. Returns most relevant nodes first, with frequently-used nodes (HTTP Request, Webhook, Set, Code, Slack) prioritized in results. Searches all 525 nodes in the database.',
+    description: 'Text search across node names and descriptions. Returns most relevant nodes first, with frequently-used nodes (HTTP Request, Webhook, Set, Code, Slack) prioritized in results. Searches all 500+ nodes in the database.',
     keyParameters: ['query', 'mode', 'limit'],
     example: 'search_nodes({query: "webhook"})',
     performance: '<20ms even for complex queries',
@@ -42,13 +42,13 @@ export const searchNodesDoc: ToolDocumentation = {
       'Start with single keywords for broadest results',
       'Use FUZZY mode when users might misspell node names',
       'AND mode works best for 2-3 word searches',
-      'Combine with get_node_essentials after finding the right node'
+      'Combine with get_node after finding the right node'
     ],
     pitfalls: [
       'AND mode searches all fields (name, description) not just node names',
       'FUZZY mode with very short queries (1-2 chars) may return unexpected results',
       'Exact matches in quotes are case-sensitive'
     ],
-    relatedTools: ['list_nodes for browsing by category', 'get_node_essentials to configure found nodes', 'list_ai_tools for AI-specific search']
+    relatedTools: ['get_node to configure found nodes', 'search_templates to find workflow examples', 'validate_node to check configurations']
   }
 };

src/mcp/tool-docs/guides/ai-agents-guide.ts

@@ -690,7 +690,7 @@ n8n_validate_workflow({id: "workflow_id"})
 - **FINAL_AI_VALIDATION_SPEC.md**: Complete validation rules
 - **n8n_update_partial_workflow**: Workflow modification tool
 - **search_nodes({query: "AI", includeExamples: true})**: Find AI nodes with examples
-- **get_node_essentials({nodeType: "...", includeExamples: true})**: Node details with examples
+- **get_node({nodeType: "...", detail: "standard", includeExamples: true})**: Node details with examples
 
 ---
 
@@ -731,8 +731,7 @@ n8n_validate_workflow({id: "workflow_id"})
       'n8n_update_partial_workflow',
       'n8n_validate_workflow',
       'search_nodes',
-      'get_node_essentials',
-      'list_ai_tools'
+      'get_node'
     ]
   }
 };

src/mcp/tool-docs/index.ts

@@ -1,45 +1,18 @@
 import { ToolDocumentation } from './types';
 
 // Import all tool documentations
-import { searchNodesDoc, listNodesDoc, listAiToolsDoc, getDatabaseStatisticsDoc } from './discovery';
-import { 
-  getNodeEssentialsDoc, 
-  getNodeInfoDoc, 
-  getNodeDocumentationDoc,
-  searchNodePropertiesDoc,
-  getNodeAsToolInfoDoc,
-  getPropertyDependenciesDoc
-} from './configuration';
-import { 
-  validateNodeMinimalDoc, 
-  validateNodeOperationDoc,
-  validateWorkflowDoc,
-  validateWorkflowConnectionsDoc,
-  validateWorkflowExpressionsDoc
-} from './validation';
-import {
-  listTasksDoc,
-  listNodeTemplatesDoc,
-  getTemplateDoc,
-  searchTemplatesDoc,
-  searchTemplatesByMetadataDoc,
-  getTemplatesForTaskDoc
-} from './templates';
+import { searchNodesDoc } from './discovery';
+import { getNodeDoc } from './configuration';
+import { validateNodeDoc, validateWorkflowDoc } from './validation';
+import { getTemplateDoc, searchTemplatesDoc } from './templates';
 import {
   toolsDocumentationDoc,
-  n8nDiagnosticDoc,
-  n8nHealthCheckDoc,
-  n8nListAvailableToolsDoc
+  n8nHealthCheckDoc
 } from './system';
-import {
-  aiAgentsGuide
-} from './guides';
+import { aiAgentsGuide } from './guides';
 import {
   n8nCreateWorkflowDoc,
   n8nGetWorkflowDoc,
-  n8nGetWorkflowDetailsDoc,
-  n8nGetWorkflowStructureDoc,
-  n8nGetWorkflowMinimalDoc,
   n8nUpdateFullWorkflowDoc,
   n8nUpdatePartialWorkflowDoc,
   n8nDeleteWorkflowDoc,
@@ -47,57 +20,37 @@ import {
   n8nValidateWorkflowDoc,
   n8nAutofixWorkflowDoc,
   n8nTriggerWebhookWorkflowDoc,
-  n8nGetExecutionDoc,
-  n8nListExecutionsDoc,
-  n8nDeleteExecutionDoc
+  n8nExecutionsDoc,
+  n8nWorkflowVersionsDoc,
+  n8nDeployTemplateDoc
 } from './workflow_management';
 
 // Combine all tool documentations into a single object
 export const toolsDocumentation: Record<string, ToolDocumentation> = {
   // System tools
   tools_documentation: toolsDocumentationDoc,
-  n8n_diagnostic: n8nDiagnosticDoc,
   n8n_health_check: n8nHealthCheckDoc,
-  n8n_list_available_tools: n8nListAvailableToolsDoc,
 
   // Guides
   ai_agents_guide: aiAgentsGuide,
 
   // Discovery tools
   search_nodes: searchNodesDoc,
-  list_nodes: listNodesDoc,
-  list_ai_tools: listAiToolsDoc,
-  get_database_statistics: getDatabaseStatisticsDoc,
-  
+
   // Configuration tools
-  get_node_essentials: getNodeEssentialsDoc,
-  get_node_info: getNodeInfoDoc,
-  get_node_documentation: getNodeDocumentationDoc,
-  search_node_properties: searchNodePropertiesDoc,
-  get_node_as_tool_info: getNodeAsToolInfoDoc,
-  get_property_dependencies: getPropertyDependenciesDoc,
-  
+  get_node: getNodeDoc,
+
   // Validation tools
-  validate_node_minimal: validateNodeMinimalDoc,
-  validate_node_operation: validateNodeOperationDoc,
+  validate_node: validateNodeDoc,
   validate_workflow: validateWorkflowDoc,
-  validate_workflow_connections: validateWorkflowConnectionsDoc,
-  validate_workflow_expressions: validateWorkflowExpressionsDoc,
-  
+
   // Template tools
-  list_tasks: listTasksDoc,
-  list_node_templates: listNodeTemplatesDoc,
   get_template: getTemplateDoc,
   search_templates: searchTemplatesDoc,
-  search_templates_by_metadata: searchTemplatesByMetadataDoc,
-  get_templates_for_task: getTemplatesForTaskDoc,
-  
+
   // Workflow Management tools (n8n API)
   n8n_create_workflow: n8nCreateWorkflowDoc,
   n8n_get_workflow: n8nGetWorkflowDoc,
-  n8n_get_workflow_details: n8nGetWorkflowDetailsDoc,
-  n8n_get_workflow_structure: n8nGetWorkflowStructureDoc,
-  n8n_get_workflow_minimal: n8nGetWorkflowMinimalDoc,
   n8n_update_full_workflow: n8nUpdateFullWorkflowDoc,
   n8n_update_partial_workflow: n8nUpdatePartialWorkflowDoc,
   n8n_delete_workflow: n8nDeleteWorkflowDoc,
@@ -105,9 +58,9 @@ export const toolsDocumentation: Record<string, ToolDocumentation> = {
   n8n_validate_workflow: n8nValidateWorkflowDoc,
   n8n_autofix_workflow: n8nAutofixWorkflowDoc,
   n8n_trigger_webhook_workflow: n8nTriggerWebhookWorkflowDoc,
-  n8n_get_execution: n8nGetExecutionDoc,
-  n8n_list_executions: n8nListExecutionsDoc,
-  n8n_delete_execution: n8nDeleteExecutionDoc
+  n8n_executions: n8nExecutionsDoc,
+  n8n_workflow_versions: n8nWorkflowVersionsDoc,
+  n8n_deploy_template: n8nDeployTemplateDoc
 };
 
 // Re-export types

src/mcp/tool-docs/system/index.ts

@@ -1,4 +1,2 @@
 export { toolsDocumentationDoc } from './tools-documentation';
-export { n8nDiagnosticDoc } from './n8n-diagnostic';
-export { n8nHealthCheckDoc } from './n8n-health-check';
-export { n8nListAvailableToolsDoc } from './n8n-list-available-tools';
+export { n8nHealthCheckDoc } from './n8n-health-check';

src/mcp/tool-docs/system/n8n-health-check.ts

@@ -5,8 +5,8 @@ export const n8nHealthCheckDoc: ToolDocumentation = {
   category: 'system',
   essentials: {
     description: 'Check n8n instance health, API connectivity, version status, and performance metrics',
-    keyParameters: [],
-    example: 'n8n_health_check({})',
+    keyParameters: ['mode', 'verbose'],
+    example: 'n8n_health_check({mode: "status"})',
     performance: 'Fast - single API call (~150-200ms median)',
     tips: [
       'Use before starting workflow operations to ensure n8n is responsive',
@@ -31,7 +31,21 @@ Health checks are crucial for:
 - Detecting performance degradation
 - Verifying API compatibility before operations
 - Ensuring authentication is working correctly`,
-    parameters: {},
+    parameters: {
+      mode: {
+        type: 'string',
+        required: false,
+        description: 'Operation mode: "status" (default) for quick health check, "diagnostic" for detailed debug info including env vars and tool status',
+        default: 'status',
+        enum: ['status', 'diagnostic']
+      },
+      verbose: {
+        type: 'boolean',
+        required: false,
+        description: 'Include extra details in diagnostic mode',
+        default: false
+      }
+    },
     returns: `Health status object containing:
 - status: Overall health status ('healthy', 'degraded', 'error')
 - n8nVersion: n8n instance version information
@@ -81,6 +95,6 @@ Health checks are crucial for:
       'Does not check individual workflow health',
       'Health endpoint might be cached - not real-time for all metrics'
     ],
-    relatedTools: ['n8n_diagnostic', 'n8n_list_available_tools', 'n8n_list_workflows']
+    relatedTools: ['n8n_list_workflows', 'n8n_validate_workflow', 'n8n_workflow_versions']
   }
 };

src/mcp/tool-docs/system/tools-documentation.ts

@@ -58,6 +58,6 @@ export const toolsDocumentationDoc: ToolDocumentation = {
       'Not all internal functions are documented',
       'Special topics (code guides) require exact names'
     ],
-    relatedTools: ['n8n_list_available_tools for dynamic tool discovery', 'list_tasks for common configurations', 'get_database_statistics to verify MCP connection']
+    relatedTools: ['n8n_health_check for verifying API connection', 'search_templates for workflow examples', 'search_nodes for finding nodes']
   }
 };

src/mcp/tool-docs/templates/get-template.ts

@@ -4,23 +4,30 @@ export const getTemplateDoc: ToolDocumentation = {
   name: 'get_template',
   category: 'templates',
   essentials: {
-    description: 'Get complete workflow JSON by ID. Ready to import. IDs from list_node_templates or search_templates.',
-    keyParameters: ['templateId'],
-    example: 'get_template({templateId: 1234})',
+    description: 'Get workflow template by ID with configurable detail level. Ready to import. IDs from search_templates.',
+    keyParameters: ['templateId', 'mode'],
+    example: 'get_template({templateId: 1234, mode: "full"})',
     performance: 'Fast (<100ms) - single database lookup',
     tips: [
-      'Get template IDs from list_node_templates or search_templates first',
-      'Returns complete workflow JSON ready for import into n8n',
-      'Includes all nodes, connections, and settings'
+      'Get template IDs from search_templates first',
+      'Use mode="nodes_only" for quick overview, "structure" for topology, "full" for import',
+      'Returns complete workflow JSON ready for import into n8n'
     ]
   },
   full: {
-    description: `Retrieves the complete workflow JSON for a specific template by its ID. The returned workflow can be directly imported into n8n through the UI or API. This tool fetches pre-built workflows from the community template library containing 399+ curated workflows.`,
+    description: `Retrieves the complete workflow JSON for a specific template by its ID. The returned workflow can be directly imported into n8n through the UI or API. This tool fetches pre-built workflows from the community template library containing 2,700+ curated workflows.`,
     parameters: {
       templateId: {
         type: 'number',
         required: true,
-        description: 'The numeric ID of the template to retrieve. Get IDs from list_node_templates or search_templates'
+        description: 'The numeric ID of the template to retrieve. Get IDs from search_templates'
+      },
+      mode: {
+        type: 'string',
+        required: false,
+        description: 'Response detail level: "nodes_only" (minimal - just node list), "structure" (nodes + connections), "full" (complete workflow JSON, default)',
+        default: 'full',
+        enum: ['nodes_only', 'structure', 'full']
       }
     },
     returns: `Returns an object containing:
@@ -39,9 +46,10 @@ export const getTemplateDoc: ToolDocumentation = {
     - settings: Workflow configuration (timezone, error handling, etc.)
 - usage: Instructions for using the workflow`,
     examples: [
-      'get_template({templateId: 1234}) - Get Slack notification workflow',
-      'get_template({templateId: 5678}) - Get data sync workflow',
-      'get_template({templateId: 9012}) - Get AI chatbot workflow'
+      'get_template({templateId: 1234}) - Get complete workflow (default mode="full")',
+      'get_template({templateId: 1234, mode: "nodes_only"}) - Get just the node list',
+      'get_template({templateId: 1234, mode: "structure"}) - Get nodes and connections',
+      'get_template({templateId: 5678, mode: "full"}) - Get complete workflow JSON for import'
     ],
     useCases: [
       'Download workflows for direct import into n8n',
@@ -69,6 +77,6 @@ export const getTemplateDoc: ToolDocumentation = {
       'Not all templates work with all n8n versions',
       'Template may reference external services you don\'t have access to'
     ],
-    relatedTools: ['list_node_templates', 'search_templates', 'get_templates_for_task', 'n8n_create_workflow']
+    relatedTools: ['search_templates', 'n8n_create_workflow']
   }
 };

src/mcp/tool-docs/templates/get-templates-for-task.ts

@@ -1,74 +0,0 @@
-import { ToolDocumentation } from '../types';
-
-export const getTemplatesForTaskDoc: ToolDocumentation = {
-  name: 'get_templates_for_task',
-  category: 'templates',
-  essentials: {
-    description: 'Curated templates by task: ai_automation, data_sync, webhooks, email, slack, data_transform, files, scheduling, api, database.',
-    keyParameters: ['task'],
-    example: 'get_templates_for_task({task: "slack_integration"})',
-    performance: 'Fast (<100ms) - pre-categorized results',
-    tips: [
-      'Returns hand-picked templates for specific automation tasks',
-      'Use list_tasks to see all available task categories',
-      'Templates are curated for quality and relevance'
-    ]
-  },
-  full: {
-    description: `Retrieves curated workflow templates for specific automation tasks. This tool provides hand-picked templates organized by common use cases, making it easy to find the right workflow for your needs. Each task category contains the most popular and effective templates for that particular automation scenario.`,
-    parameters: {
-      task: {
-        type: 'string',
-        required: true,
-        description: 'The type of task to get templates for. Options: ai_automation, data_sync, webhook_processing, email_automation, slack_integration, data_transformation, file_processing, scheduling, api_integration, database_operations'
-      }
-    },
-    returns: `Returns an object containing:
-- task: The requested task type
-- templates: Array of curated templates
-  - id: Template ID
-  - name: Template name
-  - description: What the workflow does
-  - author: Creator information
-  - nodes: Array of node types used
-  - views: Popularity metric
-  - created: Creation date
-  - url: Link to template
-- totalFound: Number of templates in this category
-- availableTasks: List of all task categories (if no templates found)`,
-    examples: [
-      'get_templates_for_task({task: "slack_integration"}) - Get Slack automation workflows',
-      'get_templates_for_task({task: "ai_automation"}) - Get AI-powered workflows',
-      'get_templates_for_task({task: "data_sync"}) - Get data synchronization workflows',
-      'get_templates_for_task({task: "webhook_processing"}) - Get webhook handler workflows',
-      'get_templates_for_task({task: "email_automation"}) - Get email automation workflows'
-    ],
-    useCases: [
-      'Find workflows for specific business needs',
-      'Discover best practices for common automations',
-      'Get started quickly with pre-built solutions',
-      'Learn patterns for specific integration types',
-      'Browse curated collections of quality workflows'
-    ],
-    performance: `Excellent performance with pre-categorized templates:
-- Query time: <10ms (indexed by task)
-- No filtering needed (pre-curated)
-- Returns 5-20 templates per category
-- Total response time: <100ms`,
-    bestPractices: [
-      'Start with task-based search for faster results',
-      'Review multiple templates to find best patterns',
-      'Check template age for most current approaches',
-      'Combine templates from same category for complex workflows',
-      'Use returned node lists to understand requirements'
-    ],
-    pitfalls: [
-      'Not all tasks have many templates available',
-      'Task categories are predefined - no custom categories',
-      'Some templates may overlap between categories',
-      'Curation is subjective - browse all results',
-      'Templates may need updates for latest n8n features'
-    ],
-    relatedTools: ['search_templates', 'list_node_templates', 'get_template', 'list_tasks']
-  }
-};

src/mcp/tool-docs/templates/index.ts

@@ -1,6 +1,2 @@
-export { listTasksDoc } from './list-tasks';
-export { listNodeTemplatesDoc } from './list-node-templates';
 export { getTemplateDoc } from './get-template';
 export { searchTemplatesDoc } from './search-templates';
-export { searchTemplatesByMetadataDoc } from './search-templates-by-metadata';
-export { getTemplatesForTaskDoc } from './get-templates-for-task';

src/mcp/tool-docs/templates/list-node-templates.ts

@@ -1,78 +0,0 @@
-import { ToolDocumentation } from '../types';
-
-export const listNodeTemplatesDoc: ToolDocumentation = {
-  name: 'list_node_templates',
-  category: 'templates',
-  essentials: {
-    description: 'Find templates using specific nodes. 399 community workflows. Use FULL types: "n8n-nodes-base.httpRequest".',
-    keyParameters: ['nodeTypes', 'limit'],
-    example: 'list_node_templates({nodeTypes: ["n8n-nodes-base.slack"]})',
-    performance: 'Fast (<100ms) - indexed node search',
-    tips: [
-      'Must use FULL node type with package prefix: "n8n-nodes-base.slack"',
-      'Can search for multiple nodes to find workflows using all of them',
-      'Returns templates sorted by popularity (view count)'
-    ]
-  },
-  full: {
-    description: `Finds workflow templates that use specific n8n nodes. This is the best way to discover how particular nodes are used in real workflows. Search the community library of 399+ templates by specifying which nodes you want to see in action. Templates are sorted by popularity to show the most useful examples first.`,
-    parameters: {
-      nodeTypes: {
-        type: 'array',
-        required: true,
-        description: 'Array of node types to search for. Must use full type names with package prefix (e.g., ["n8n-nodes-base.httpRequest", "n8n-nodes-base.openAi"])'
-      },
-      limit: {
-        type: 'number',
-        required: false,
-        description: 'Maximum number of templates to return. Default 10, max 100'
-      }
-    },
-    returns: `Returns an object containing:
-- templates: Array of matching templates
-  - id: Template ID for retrieval
-  - name: Template name
-  - description: What the workflow does
-  - author: Creator details (name, username, verified)
-  - nodes: Complete list of nodes used
-  - views: View count (popularity metric)
-  - created: Creation date
-  - url: Link to template on n8n.io
-- totalFound: Total number of matching templates
-- tip: Usage hints if no results`,
-    examples: [
-      'list_node_templates({nodeTypes: ["n8n-nodes-base.slack"]}) - Find all Slack workflows',
-      'list_node_templates({nodeTypes: ["n8n-nodes-base.httpRequest", "n8n-nodes-base.postgres"]}) - Find workflows using both HTTP and Postgres',
-      'list_node_templates({nodeTypes: ["@n8n/n8n-nodes-langchain.openAi"], limit: 20}) - Find AI workflows with OpenAI',
-      'list_node_templates({nodeTypes: ["n8n-nodes-base.webhook", "n8n-nodes-base.respondToWebhook"]}) - Find webhook examples'
-    ],
-    useCases: [
-      'Learn how to use specific nodes through examples',
-      'Find workflows combining particular integrations',
-      'Discover patterns for node combinations',
-      'See real-world usage of complex nodes',
-      'Find templates for your exact tech stack'
-    ],
-    performance: `Optimized for node-based searches:
-- Indexed by node type for fast lookups
-- Query time: <50ms for single node
-- Multiple nodes: <100ms (uses AND logic)
-- Returns pre-sorted by popularity
-- No full-text search needed`,
-    bestPractices: [
-      'Always use full node type with package prefix',
-      'Search for core nodes that define the workflow purpose',
-      'Start with single node searches, then refine',
-      'Check node types with list_nodes if unsure of names',
-      'Review multiple templates to learn different approaches'
-    ],
-    pitfalls: [
-      'Node types must match exactly - no partial matches',
-      'Package prefix required: "slack" won\'t work, use "n8n-nodes-base.slack"',
-      'Some nodes have version numbers: "n8n-nodes-base.httpRequestV3"',
-      'Templates may use old node versions not in current n8n',
-      'AND logic means all specified nodes must be present'
-    ],
-    relatedTools: ['get_template', 'search_templates', 'get_templates_for_task', 'list_nodes']
-  }
-};

src/mcp/tool-docs/templates/list-tasks.ts

@@ -1,46 +0,0 @@
-import { ToolDocumentation } from '../types';
-
-export const listTasksDoc: ToolDocumentation = {
-  name: 'list_tasks',
-  category: 'templates',
-  essentials: {
-    description: 'List task templates by category: HTTP/API, Webhooks, Database, AI, Data Processing, Communication.',
-    keyParameters: ['category'],
-    example: 'list_tasks({category: "HTTP/API"})',
-    performance: 'Instant',
-    tips: [
-      'Categories: HTTP/API, Webhooks, Database, AI',
-      'Shows pre-configured node settings',
-      'Use get_node_for_task for details'
-    ]
-  },
-  full: {
-    description: 'Lists available task templates organized by category. Each task represents a common automation pattern with pre-configured node settings. Categories include HTTP/API, Webhooks, Database, AI, Data Processing, and Communication.',
-    parameters: {
-      category: { type: 'string', description: 'Filter by category (optional)' }
-    },
-    returns: 'Array of tasks with name, category, description, nodeType',
-    examples: [
-      'list_tasks() - Get all task templates',
-      'list_tasks({category: "Database"}) - Database-related tasks',
-      'list_tasks({category: "AI"}) - AI automation tasks'
-    ],
-    useCases: [
-      'Discover common automation patterns',
-      'Find pre-configured solutions',
-      'Learn node usage patterns',
-      'Quick workflow setup'
-    ],
-    performance: 'Instant - Static task list',
-    bestPractices: [
-      'Browse all categories first',
-      'Use get_node_for_task for config',
-      'Combine multiple tasks in workflows'
-    ],
-    pitfalls: [
-      'Tasks are templates, customize as needed',
-      'Not all nodes have task templates'
-    ],
-    relatedTools: ['get_node_for_task', 'search_templates', 'get_templates_for_task']
-  }
-};

src/mcp/tool-docs/templates/search-templates-by-metadata.ts

@@ -1,118 +0,0 @@
-import { ToolDocumentation } from '../types';
-
-export const searchTemplatesByMetadataDoc: ToolDocumentation = {
-  name: 'search_templates_by_metadata',
-  category: 'templates',
-  essentials: {
-    description: 'Search templates using AI-generated metadata filters. Find templates by complexity, setup time, required services, or target audience. Enables smart template discovery beyond simple text search.',
-    keyParameters: ['category', 'complexity', 'maxSetupMinutes', 'targetAudience'],
-    example: 'search_templates_by_metadata({complexity: "simple", maxSetupMinutes: 30})',
-    performance: 'Fast (<100ms) - JSON extraction queries',
-    tips: [
-      'All filters are optional - combine them for precise results',
-      'Use getAvailableCategories() to see valid category values',
-      'Complexity levels: simple, medium, complex',
-      'Setup time is in minutes (5-480 range)'
-    ]
-  },
-  full: {
-    description: `Advanced template search using AI-generated metadata. Each template has been analyzed by GPT-4 to extract structured information about its purpose, complexity, setup requirements, and target users. This enables intelligent filtering beyond simple keyword matching, helping you find templates that match your specific needs, skill level, and available time.`,
-    parameters: {
-      category: {
-        type: 'string',
-        required: false,
-        description: 'Filter by category like "automation", "integration", "data processing", "communication". Use template service getAvailableCategories() for full list.'
-      },
-      complexity: {
-        type: 'string (enum)',
-        required: false,
-        description: 'Filter by implementation complexity: "simple" (beginner-friendly), "medium" (some experience needed), or "complex" (advanced features)'
-      },
-      maxSetupMinutes: {
-        type: 'number',
-        required: false,
-        description: 'Maximum acceptable setup time in minutes (5-480). Find templates you can implement within your time budget.'
-      },
-      minSetupMinutes: {
-        type: 'number',
-        required: false,
-        description: 'Minimum setup time in minutes (5-480). Find more substantial templates that offer comprehensive solutions.'
-      },
-      requiredService: {
-        type: 'string',
-        required: false,
-        description: 'Filter by required external service like "openai", "slack", "google", "shopify". Ensures you have necessary accounts/APIs.'
-      },
-      targetAudience: {
-        type: 'string',
-        required: false,
-        description: 'Filter by intended users: "developers", "marketers", "analysts", "operations", "sales". Find templates for your role.'
-      },
-      limit: {
-        type: 'number',
-        required: false,
-        description: 'Maximum results to return. Default 20, max 100.'
-      },
-      offset: {
-        type: 'number',
-        required: false,
-        description: 'Pagination offset for results. Default 0.'
-      }
-    },
-    returns: `Returns an object containing:
-- items: Array of matching templates with full metadata
-  - id: Template ID
-  - name: Template name
-  - description: Purpose and functionality
-  - author: Creator details
-  - nodes: Array of nodes used
-  - views: Popularity count
-  - metadata: AI-generated structured data
-    - categories: Primary use categories
-    - complexity: Difficulty level
-    - use_cases: Specific applications
-    - estimated_setup_minutes: Time to implement
-    - required_services: External dependencies
-    - key_features: Main capabilities
-    - target_audience: Intended users
-- total: Total matching templates
-- filters: Applied filter criteria
-- filterSummary: Human-readable filter description
-- availableCategories: Suggested categories if no results
-- availableAudiences: Suggested audiences if no results
-- tip: Contextual guidance`,
-    examples: [
-      'search_templates_by_metadata({complexity: "simple"}) - Find beginner-friendly templates',
-      'search_templates_by_metadata({category: "automation", maxSetupMinutes: 30}) - Quick automation templates',
-      'search_templates_by_metadata({targetAudience: "marketers"}) - Marketing-focused workflows',
-      'search_templates_by_metadata({requiredService: "openai", complexity: "medium"}) - AI templates with moderate complexity',
-      'search_templates_by_metadata({minSetupMinutes: 60, category: "integration"}) - Comprehensive integration solutions'
-    ],
-    useCases: [
-      'Finding beginner-friendly templates by setting complexity:"simple"',
-      'Discovering templates you can implement quickly with maxSetupMinutes:30',
-      'Finding role-specific workflows with targetAudience filter',
-      'Identifying templates that need specific APIs with requiredService filter',
-      'Combining multiple filters for precise template discovery'
-    ],
-    performance: 'Fast (<100ms) - Uses SQLite JSON extraction on pre-generated metadata. 97.5% coverage (2,534/2,598 templates).',
-    bestPractices: [
-      'Start with broad filters and narrow down based on results',
-      'Use getAvailableCategories() to discover valid category values',
-      'Combine complexity and setup time for skill-appropriate templates',
-      'Check required services before selecting templates to ensure you have necessary accounts'
-    ],
-    pitfalls: [
-      'Not all templates have metadata (97.5% coverage)',
-      'Setup time estimates assume basic n8n familiarity',
-      'Categories/audiences use partial matching - be specific',
-      'Metadata is AI-generated and may occasionally be imprecise'
-    ],
-    relatedTools: [
-      'list_templates',
-      'search_templates',
-      'list_node_templates',
-      'get_templates_for_task'
-    ]
-  }
-};

src/mcp/tool-docs/templates/search-templates.ts

@@ -4,86 +4,138 @@ export const searchTemplatesDoc: ToolDocumentation = {
   name: 'search_templates',
   category: 'templates',
   essentials: {
-    description: 'Search templates by name/description keywords. NOT for node types! For nodes use list_node_templates. Example: "chatbot".',
-    keyParameters: ['query', 'limit', 'fields'],
-    example: 'search_templates({query: "chatbot", fields: ["id", "name"]})',
+    description: 'Unified template search with multiple modes: keyword search, by node types, by task type, or by metadata. 2,700+ templates available.',
+    keyParameters: ['searchMode', 'query', 'nodeTypes', 'task', 'limit'],
+    example: 'search_templates({searchMode: "by_task", task: "webhook_processing"})',
     performance: 'Fast (<100ms) - FTS5 full-text search',
     tips: [
-      'Searches template names and descriptions, NOT node types',
-      'Use keywords like "automation", "sync", "notification"',
-      'For node-specific search, use list_node_templates instead',
-      'Use fields parameter to get only specific data (reduces response by 70-90%)'
+      'searchMode="keyword" (default): Search by name/description',
+      'searchMode="by_nodes": Find templates using specific nodes',
+      'searchMode="by_task": Get curated templates for common tasks',
+      'searchMode="by_metadata": Filter by complexity, services, audience'
     ]
   },
   full: {
-    description: `Performs full-text search across workflow template names and descriptions. This tool is ideal for finding workflows based on their purpose or functionality rather than specific nodes used. It searches through the community library of 399+ templates using SQLite FTS5 for fast, fuzzy matching.`,
+    description: `**Search Modes:**
+- keyword (default): Full-text search across template names and descriptions
+- by_nodes: Find templates that use specific node types
+- by_task: Get curated templates for predefined task categories
+- by_metadata: Filter by complexity, setup time, required services, or target audience
+
+**Available Task Types (for searchMode="by_task"):**
+ai_automation, data_sync, webhook_processing, email_automation, slack_integration, data_transformation, file_processing, scheduling, api_integration, database_operations`,
     parameters: {
+      searchMode: {
+        type: 'string',
+        required: false,
+        description: 'Search mode: "keyword" (default), "by_nodes", "by_task", "by_metadata"'
+      },
       query: {
         type: 'string',
-        required: true,
-        description: 'Search query for template names/descriptions. NOT for node types! Examples: "chatbot", "automation", "social media", "webhook". For node-based search use list_node_templates instead.'
+        required: false,
+        description: 'For searchMode=keyword: Search keywords (e.g., "chatbot", "automation")'
+      },
+      nodeTypes: {
+        type: 'array',
+        required: false,
+        description: 'For searchMode=by_nodes: Array of node types (e.g., ["n8n-nodes-base.httpRequest", "n8n-nodes-base.slack"])'
+      },
+      task: {
+        type: 'string',
+        required: false,
+        description: 'For searchMode=by_task: Task type (ai_automation, data_sync, webhook_processing, email_automation, slack_integration, data_transformation, file_processing, scheduling, api_integration, database_operations)'
+      },
+      complexity: {
+        type: 'string',
+        required: false,
+        description: 'For searchMode=by_metadata: Filter by complexity ("simple", "medium", "complex")'
+      },
+      maxSetupMinutes: {
+        type: 'number',
+        required: false,
+        description: 'For searchMode=by_metadata: Maximum setup time in minutes (5-480)'
+      },
+      minSetupMinutes: {
+        type: 'number',
+        required: false,
+        description: 'For searchMode=by_metadata: Minimum setup time in minutes (5-480)'
+      },
+      requiredService: {
+        type: 'string',
+        required: false,
+        description: 'For searchMode=by_metadata: Filter by required service (e.g., "openai", "slack", "google")'
+      },
+      targetAudience: {
+        type: 'string',
+        required: false,
+        description: 'For searchMode=by_metadata: Filter by target audience (e.g., "developers", "marketers")'
+      },
+      category: {
+        type: 'string',
+        required: false,
+        description: 'For searchMode=by_metadata: Filter by category (e.g., "automation", "integration")'
       },
       fields: {
         type: 'array',
         required: false,
-        description: 'Fields to include in response. Options: "id", "name", "description", "author", "nodes", "views", "created", "url", "metadata". Default: all fields. Example: ["id", "name"] for minimal response.'
+        description: 'For searchMode=keyword: Fields to include (id, name, description, author, nodes, views, created, url, metadata)'
       },
       limit: {
         type: 'number',
         required: false,
-        description: 'Maximum number of results. Default 20, max 100'
+        description: 'Maximum results (default 20, max 100)'
+      },
+      offset: {
+        type: 'number',
+        required: false,
+        description: 'Pagination offset (default 0)'
       }
     },
     returns: `Returns an object containing:
-- templates: Array of matching templates sorted by relevance
-  - id: Template ID for retrieval
-  - name: Template name (with match highlights)
+- templates: Array of matching templates
+  - id: Template ID for get_template()
+  - name: Template name
   - description: What the workflow does
   - author: Creator information
-  - nodes: Array of all nodes used
+  - nodes: Array of node types used
   - views: Popularity metric
   - created: Creation date
   - url: Link to template
-  - relevanceScore: Search match score
+  - metadata: AI-generated metadata (complexity, services, etc.)
 - totalFound: Total matching templates
-- searchQuery: The processed search query
-- tip: Helpful hints if no results`,
+- searchMode: The mode used`,
     examples: [
-      'search_templates({query: "chatbot"}) - Find chatbot and conversational AI workflows',
-      'search_templates({query: "email notification"}) - Find email alert workflows',
-      'search_templates({query: "data sync"}) - Find data synchronization workflows',
-      'search_templates({query: "webhook automation", limit: 30}) - Find webhook-based automations',
-      'search_templates({query: "social media scheduler"}) - Find social posting workflows',
-      'search_templates({query: "slack", fields: ["id", "name"]}) - Get only IDs and names of Slack templates',
-      'search_templates({query: "automation", fields: ["id", "name", "description"]}) - Get minimal info for automation templates'
+      '// Keyword search (default)\nsearch_templates({query: "chatbot"})',
+      '// Find templates using specific nodes\nsearch_templates({searchMode: "by_nodes", nodeTypes: ["n8n-nodes-base.httpRequest", "n8n-nodes-base.slack"]})',
+      '// Get templates for a task type\nsearch_templates({searchMode: "by_task", task: "webhook_processing"})',
+      '// Filter by metadata\nsearch_templates({searchMode: "by_metadata", complexity: "simple", requiredService: "openai"})',
+      '// Combine metadata filters\nsearch_templates({searchMode: "by_metadata", maxSetupMinutes: 30, targetAudience: "developers"})'
     ],
     useCases: [
-      'Find workflows by business purpose',
-      'Discover automations for specific use cases',
-      'Search by workflow functionality',
-      'Find templates by problem they solve',
-      'Explore workflows by industry or domain'
+      'Find workflows by business purpose (keyword search)',
+      'Find templates using specific integrations (by_nodes)',
+      'Get pre-built solutions for common tasks (by_task)',
+      'Filter by complexity for team skill level (by_metadata)',
+      'Find templates requiring specific services (by_metadata)'
     ],
-    performance: `Excellent performance with FTS5 indexing:
-- Full-text search: <50ms for most queries
-- Fuzzy matching enabled for typos
-- Relevance-based sorting included
-- Searches both title and description
-- Returns highlighted matches`,
+    performance: `Fast performance across all modes:
+- keyword: <50ms with FTS5 indexing
+- by_nodes: <100ms with indexed lookups
+- by_task: <50ms from curated cache
+- by_metadata: <100ms with filtered queries`,
     bestPractices: [
-      'Use descriptive keywords about the workflow purpose',
-      'Try multiple related terms if first search has few results',
-      'Combine terms for more specific results',
-      'Check both name and description in results',
-      'Use quotes for exact phrase matching'
+      'Use searchMode="by_task" for common automation patterns',
+      'Use searchMode="by_nodes" when you know which integrations you need',
+      'Use searchMode="keyword" for general discovery',
+      'Combine by_metadata filters for precise matching',
+      'Use get_template(id) to get the full workflow JSON'
     ],
     pitfalls: [
-      'Does NOT search by node types - use list_node_templates',
-      'Search is case-insensitive but not semantic',
-      'Very specific terms may return no results',
-      'Descriptions may be brief - check full template',
-      'Relevance scoring may not match your expectations'
+      'searchMode="keyword" searches names/descriptions, not node types',
+      'by_nodes requires full node type with prefix (n8n-nodes-base.xxx)',
+      'by_metadata filters may return fewer results',
+      'Not all templates have complete metadata'
     ],
-    relatedTools: ['list_node_templates', 'get_templates_for_task', 'get_template', 'search_nodes']
+    relatedTools: ['get_template', 'search_nodes', 'validate_workflow']
   }
 };

src/mcp/tool-docs/validation/index.ts

@@ -1,5 +1,2 @@
-export { validateNodeMinimalDoc } from './validate-node-minimal';
-export { validateNodeOperationDoc } from './validate-node-operation';
+export { validateNodeDoc } from './validate-node';
 export { validateWorkflowDoc } from './validate-workflow';
-export { validateWorkflowConnectionsDoc } from './validate-workflow-connections';
-export { validateWorkflowExpressionsDoc } from './validate-workflow-expressions';

src/mcp/tool-docs/validation/validate-node-minimal.ts

@@ -1,47 +0,0 @@
-import { ToolDocumentation } from '../types';
-
-export const validateNodeMinimalDoc: ToolDocumentation = {
-  name: 'validate_node_minimal',
-  category: 'validation',
-  essentials: {
-    description: 'Fast check for missing required fields only. No warnings/suggestions. Returns: list of missing fields.',
-    keyParameters: ['nodeType', 'config'],
-    example: 'validate_node_minimal("nodes-base.slack", {resource: "message"})',
-    performance: 'Instant',
-    tips: [
-      'Returns only missing required fields',
-      'No warnings or suggestions',
-      'Perfect for real-time validation'
-    ]
-  },
-  full: {
-    description: 'Minimal validation that only checks for missing required fields. Returns array of missing field names without any warnings or suggestions. Ideal for quick validation during node configuration.',
-    parameters: {
-      nodeType: { type: 'string', required: true, description: 'Node type with prefix (e.g., "nodes-base.slack")' },
-      config: { type: 'object', required: true, description: 'Node configuration to validate' }
-    },
-    returns: 'Array of missing required field names (empty if valid)',
-    examples: [
-      'validate_node_minimal("nodes-base.slack", {resource: "message", operation: "post"}) - Check Slack config',
-      'validate_node_minimal("nodes-base.httpRequest", {method: "GET"}) - Check HTTP config'
-    ],
-    useCases: [
-      'Real-time form validation',
-      'Quick configuration checks',
-      'Pre-deployment validation',
-      'Interactive configuration builders'
-    ],
-    performance: 'Instant - Simple field checking without complex validation',
-    bestPractices: [
-      'Use for quick feedback loops',
-      'Follow with validate_node_operation for thorough check',
-      'Check return array length for validity'
-    ],
-    pitfalls: [
-      'Only checks required fields',
-      'No type validation',
-      'No operation-specific validation'
-    ],
-    relatedTools: ['validate_node_operation', 'get_node_essentials', 'get_property_dependencies']
-  }
-};

src/mcp/tool-docs/validation/validate-node-operation.ts

@@ -1,98 +0,0 @@
-import { ToolDocumentation } from '../types';
-
-export const validateNodeOperationDoc: ToolDocumentation = {
-  name: 'validate_node_operation',
-  category: 'validation',
-  essentials: {
-    description: 'Validates node configuration with operation awareness. Checks required fields, data types, and operation-specific rules. Returns specific errors with automated fix suggestions. Different profiles for different validation needs.',
-    keyParameters: ['nodeType', 'config', 'profile'],
-    example: 'validate_node_operation({nodeType: "nodes-base.slack", config: {resource: "message", operation: "post", text: "Hi"}})',
-    performance: '<100ms',
-    tips: [
-      'Profile choices: minimal (editing), runtime (execution), ai-friendly (balanced), strict (deployment)',
-      'Returns fixes you can apply directly',
-      'Operation-aware - knows Slack post needs text',
-      'Validates operator structures for IF and Switch nodes with conditions'
-    ]
-  },
-  full: {
-    description: 'Comprehensive node configuration validation that understands operation context. For example, it knows Slack message posting requires text field, while channel listing doesn\'t. Provides different validation profiles for different stages of workflow development.',
-    parameters: {
-      nodeType: { type: 'string', required: true, description: 'Full node type with prefix: "nodes-base.slack", "nodes-base.httpRequest"' },
-      config: { type: 'object', required: true, description: 'Node configuration. Must include operation fields (resource/operation/action) if the node has multiple operations' },
-      profile: { type: 'string', required: false, description: 'Validation profile - controls what\'s checked. Default: "ai-friendly"' }
-    },
-    returns: `Object containing:
-{
-  "isValid": false,
-  "errors": [
-    {
-      "field": "channel",
-      "message": "Required field 'channel' is missing",
-      "severity": "error",
-      "fix": "#general"
-    }
-  ],
-  "warnings": [
-    {
-      "field": "retryOnFail", 
-      "message": "Consider enabling retry for reliability",
-      "severity": "warning",
-      "fix": true
-    }
-  ],
-  "suggestions": [
-    {
-      "field": "timeout",
-      "message": "Set timeout to prevent hanging",
-      "fix": 30000
-    }
-  ],
-  "fixes": {
-    "channel": "#general",
-    "retryOnFail": true,
-    "timeout": 30000
-  }
-}`,
-    examples: [
-      '// Missing required field',
-      'validate_node_operation({nodeType: "nodes-base.slack", config: {resource: "message", operation: "post"}})',
-      '// Returns: {isValid: false, errors: [{field: "text", message: "Required field missing"}], fixes: {text: "Message text"}}',
-      '',
-      '// Validate with strict profile for production',
-      'validate_node_operation({nodeType: "nodes-base.httpRequest", config: {method: "POST", url: "https://api.example.com"}, profile: "strict"})',
-      '',
-      '// Apply fixes automatically',
-      'const result = validate_node_operation({nodeType: "nodes-base.slack", config: myConfig});',
-      'if (!result.isValid) {',
-      '  myConfig = {...myConfig, ...result.fixes};',
-      '}'
-    ],
-    useCases: [
-      'Validate configuration before workflow execution',
-      'Debug why a node isn\'t working as expected',
-      'Generate configuration fixes automatically',
-      'Different validation for editing vs production',
-      'Check IF/Switch operator structures (binary vs unary operators)',
-      'Validate conditions.options metadata for filter-based nodes'
-    ],
-    performance: '<100ms for most nodes, <200ms for complex nodes with many conditions',
-    bestPractices: [
-      'Use "minimal" profile during user editing for fast feedback',
-      'Use "runtime" profile (default) before execution',
-      'Use "ai-friendly" when AI configures nodes',
-      'Use "strict" profile before production deployment',
-      'Always include operation fields (resource/operation) in config',
-      'Apply suggested fixes to resolve issues quickly'
-    ],
-    pitfalls: [
-      'Must include operation fields for multi-operation nodes',
-      'Fixes are suggestions - review before applying',
-      'Profile affects what\'s validated - minimal skips many checks',
-      '**Binary vs Unary operators**: Binary operators (equals, contains, greaterThan) must NOT have singleValue:true. Unary operators (isEmpty, isNotEmpty, true, false) REQUIRE singleValue:true',
-      '**IF and Switch nodes with conditions**: Must have complete conditions.options structure: {version: 2, leftValue: "", caseSensitive: true/false, typeValidation: "strict"}',
-      '**Operator type field**: Must be data type (string/number/boolean/dateTime/array/object), NOT operation name (e.g., use type:"string" operation:"equals", not type:"equals")'
-    ],
-    relatedTools: ['validate_node_minimal for quick checks', 'get_node_essentials for valid examples', 'validate_workflow for complete workflow validation']
-  }
-};

src/mcp/tool-docs/validation/validate-node.ts

@@ -0,0 +1,80 @@
+import { ToolDocumentation } from '../types';
+
+export const validateNodeDoc: ToolDocumentation = {
+  name: 'validate_node',
+  category: 'validation',
+  essentials: {
+    description: 'Validate n8n node configuration. Use mode="full" for comprehensive validation with errors/warnings/suggestions, mode="minimal" for quick required fields check.',
+    keyParameters: ['nodeType', 'config', 'mode', 'profile'],
+    example: 'validate_node({nodeType: "nodes-base.slack", config: {resource: "channel", operation: "create"}})',
+    performance: 'Fast (<100ms)',
+    tips: [
+      'Always call get_node({detail:"standard"}) first to see required fields',
+      'Use mode="minimal" for quick checks during development',
+      'Use mode="full" with profile="strict" before production deployment',
+      'Includes automatic structure validation for filter, resourceMapper, etc.'
+    ]
+  },
+  full: {
+    description: `**Validation Modes:**
+- full (default): Comprehensive validation with errors, warnings, suggestions, and automatic structure validation
+- minimal: Quick check for required fields only - fast but less thorough
+
+**Validation Profiles (for mode="full"):**
+- minimal: Very lenient, basic checks only
+- runtime: Standard validation (default)
+- ai-friendly: Balanced for AI agent workflows
+- strict: Most thorough, recommended for production
+
+**Automatic Structure Validation:**
+Validates complex n8n types automatically:
+- filter (FilterValue): 40+ operations (equals, contains, regex, etc.)
+- resourceMapper (ResourceMapperValue): Data mapping configuration
+- assignmentCollection (AssignmentCollectionValue): Variable assignments
+- resourceLocator (INodeParameterResourceLocator): Resource selection modes`,
+    parameters: {
+      nodeType: { type: 'string', required: true, description: 'Node type with prefix: "nodes-base.slack"' },
+      config: { type: 'object', required: true, description: 'Configuration object to validate. Use {} for empty config' },
+      mode: { type: 'string', required: false, description: 'Validation mode: "full" (default) or "minimal"' },
+      profile: { type: 'string', required: false, description: 'Validation profile for mode=full: "minimal", "runtime" (default), "ai-friendly", "strict"' }
+    },
+    returns: `Object containing:
+- nodeType: The validated node type
+- workflowNodeType: Type to use in workflow JSON
+- displayName: Human-readable node name
+- valid: Boolean indicating if configuration is valid
+- errors: Array of error objects with type, property, message, fix
+- warnings: Array of warning objects with suggestions
+- suggestions: Array of improvement suggestions
+- missingRequiredFields: (mode=minimal only) Array of missing required field names
+- summary: Object with hasErrors, errorCount, warningCount, suggestionCount`,
+    examples: [
+      '// Full validation with default profile\nvalidate_node({nodeType: "nodes-base.slack", config: {resource: "channel", operation: "create"}})',
+      '// Quick required fields check\nvalidate_node({nodeType: "nodes-base.webhook", config: {}, mode: "minimal"})',
+      '// Strict validation for production\nvalidate_node({nodeType: "nodes-base.httpRequest", config: {...}, mode: "full", profile: "strict"})',
+      '// Validate IF node with filter\nvalidate_node({nodeType: "nodes-base.if", config: {conditions: {combinator: "and", conditions: [...]}}})'
+    ],
+    useCases: [
+      'Validate node configuration before adding to workflow',
+      'Quick check for required fields during development',
+      'Pre-production validation with strict profile',
+      'Validate complex structures (filters, resource mappers)',
+      'Get suggestions for improving node configuration'
+    ],
+    performance: 'Fast validation: <50ms for minimal mode, <100ms for full mode. Structure validation adds minimal overhead.',
+    bestPractices: [
+      'Always call get_node() first to understand required fields',
+      'Use mode="minimal" for rapid iteration during development',
+      'Use profile="strict" before deploying to production',
+      'Pay attention to warnings - they often prevent runtime issues',
+      'Validate after any configuration changes'
+    ],
+    pitfalls: [
+      'Empty config {} is valid for some nodes (e.g., manual trigger)',
+      'mode="minimal" only checks required fields, not value validity',
+      'Some warnings may be acceptable for specific use cases',
+      'Credential validation requires runtime context'
+    ],
+    relatedTools: ['get_node', 'validate_workflow', 'n8n_autofix_workflow']
+  }
+};

src/mcp/tool-docs/validation/validate-workflow-connections.ts

@@ -1,56 +0,0 @@
-import { ToolDocumentation } from '../types';
-
-export const validateWorkflowConnectionsDoc: ToolDocumentation = {
-  name: 'validate_workflow_connections',
-  category: 'validation',
-  essentials: {
-    description: 'Check workflow connections only: valid nodes, no cycles, proper triggers, AI tool links. Fast structure validation.',
-    keyParameters: ['workflow'],
-    example: 'validate_workflow_connections({workflow: {nodes: [...], connections: {...}}})',
-    performance: 'Fast (<100ms)',
-    tips: [
-      'Use for quick structure checks when editing connections',
-      'Detects orphaned nodes and circular dependencies',
-      'Validates AI Agent tool connections to ensure proper node references'
-    ]
-  },
-  full: {
-    description: 'Validates only the connection structure of a workflow without checking node configurations or expressions. This focused validation checks that all referenced nodes exist, detects circular dependencies, ensures proper trigger node placement, validates AI tool connections, and identifies orphaned or unreachable nodes.',
-    parameters: {
-      workflow: { 
-        type: 'object', 
-        required: true, 
-        description: 'The workflow JSON with nodes array and connections object.' 
-      }
-    },
-    returns: 'Object with valid (boolean), errors (array), warnings (array), and statistics about connections',
-    examples: [
-      'validate_workflow_connections({workflow: myWorkflow}) - Check all connections',
-      'validate_workflow_connections({workflow: {nodes: [...], connections: {...}}}) - Validate structure only'
-    ],
-    useCases: [
-      'Quick validation when modifying workflow connections',
-      'Ensure all node references in connections are valid',
-      'Detect circular dependencies that would cause infinite loops',
-      'Validate AI Agent nodes have proper tool connections',
-      'Check workflow has at least one trigger node',
-      'Find orphaned nodes not connected to any flow'
-    ],
-    performance: 'Fast (<100ms). Only validates structure, not node content. Scales linearly with connection count.',
-    bestPractices: [
-      'Run after adding or removing connections',
-      'Use before validate_workflow for quick structural checks',
-      'Check for warnings about orphaned nodes',
-      'Ensure trigger nodes are properly positioned',
-      'Validate after using n8n_update_partial_workflow with connection operations'
-    ],
-    pitfalls: [
-      'Does not validate node configurations - use validate_workflow for full validation',
-      'Cannot detect logical errors in connection flow',
-      'Some valid workflows may have intentionally disconnected nodes',
-      'Circular dependency detection only catches direct loops',
-      'Does not validate connection types match node capabilities'
-    ],
-    relatedTools: ['validate_workflow', 'validate_workflow_expressions', 'n8n_update_partial_workflow']
-  }
-};

src/mcp/tool-docs/validation/validate-workflow-expressions.ts

@@ -1,56 +0,0 @@
-import { ToolDocumentation } from '../types';
-
-export const validateWorkflowExpressionsDoc: ToolDocumentation = {
-  name: 'validate_workflow_expressions',
-  category: 'validation',
-  essentials: {
-    description: 'Validate n8n expressions: syntax {{}}, variables ($json/$node), references. Returns errors with locations.',
-    keyParameters: ['workflow'],
-    example: 'validate_workflow_expressions({workflow: {nodes: [...], connections: {...}}})',
-    performance: 'Fast (<100ms)',
-    tips: [
-      'Catches syntax errors in {{}} expressions before runtime',
-      'Validates $json, $node, and other n8n variables',
-      'Shows exact location of expression errors in node parameters'
-    ]
-  },
-  full: {
-    description: 'Validates all n8n expressions within a workflow for syntax correctness and reference validity. This tool scans all node parameters for n8n expressions (enclosed in {{}}), checks expression syntax, validates variable references like $json and $node("NodeName"), ensures referenced nodes exist in the workflow, and provides detailed error locations for debugging.',
-    parameters: {
-      workflow: { 
-        type: 'object', 
-        required: true, 
-        description: 'The workflow JSON to check for expression errors.' 
-      }
-    },
-    returns: 'Object with valid (boolean), errors (array with node ID, parameter path, and error details), and expression count',
-    examples: [
-      'validate_workflow_expressions({workflow: myWorkflow}) - Check all expressions',
-      'validate_workflow_expressions({workflow: {nodes: [...], connections: {...}}}) - Validate expression syntax'
-    ],
-    useCases: [
-      'Catch expression syntax errors before workflow execution',
-      'Validate node references in $node() expressions exist',
-      'Find typos in variable names like $json or $input',
-      'Ensure complex expressions are properly formatted',
-      'Debug expression errors with exact parameter locations',
-      'Validate expressions after workflow modifications'
-    ],
-    performance: 'Fast (<100ms). Scans all string parameters in all nodes. Performance scales with workflow size and expression count.',
-    bestPractices: [
-      'Run after modifying any expressions in node parameters',
-      'Check all $node() references when renaming nodes',
-      'Validate expressions before workflow deployment',
-      'Pay attention to nested object paths in expressions',
-      'Use with validate_workflow for comprehensive validation'
-    ],
-    pitfalls: [
-      'Cannot validate expression logic, only syntax',
-      'Runtime data availability not checked (e.g., if $json.field exists)',
-      'Complex JavaScript in expressions may need runtime testing',
-      'Does not validate expression return types',
-      'Some valid expressions may use advanced features not fully parsed'
-    ],
-    relatedTools: ['validate_workflow', 'validate_workflow_connections', 'validate_node_operation']
-  }
-};

src/mcp/tool-docs/validation/validate-workflow.ts

@@ -79,6 +79,6 @@ export const validateWorkflowDoc: ToolDocumentation = {
       'Validation cannot catch all runtime errors (e.g., API failures)',
       'Profile setting only affects node validation, not connection/expression checks'
     ],
-    relatedTools: ['validate_workflow_connections', 'validate_workflow_expressions', 'validate_node_operation', 'n8n_create_workflow', 'n8n_update_partial_workflow', 'n8n_autofix_workflow']
+    relatedTools: ['validate_node', 'n8n_create_workflow', 'n8n_update_partial_workflow', 'n8n_autofix_workflow']
   }
 };

src/mcp/tool-docs/workflow_management/index.ts

@@ -1,8 +1,5 @@
 export { n8nCreateWorkflowDoc } from './n8n-create-workflow';
 export { n8nGetWorkflowDoc } from './n8n-get-workflow';
-export { n8nGetWorkflowDetailsDoc } from './n8n-get-workflow-details';
-export { n8nGetWorkflowStructureDoc } from './n8n-get-workflow-structure';
-export { n8nGetWorkflowMinimalDoc } from './n8n-get-workflow-minimal';
 export { n8nUpdateFullWorkflowDoc } from './n8n-update-full-workflow';
 export { n8nUpdatePartialWorkflowDoc } from './n8n-update-partial-workflow';
 export { n8nDeleteWorkflowDoc } from './n8n-delete-workflow';
@@ -10,6 +7,6 @@ export { n8nListWorkflowsDoc } from './n8n-list-workflows';
 export { n8nValidateWorkflowDoc } from './n8n-validate-workflow';
 export { n8nAutofixWorkflowDoc } from './n8n-autofix-workflow';
 export { n8nTriggerWebhookWorkflowDoc } from './n8n-trigger-webhook-workflow';
-export { n8nGetExecutionDoc } from './n8n-get-execution';
-export { n8nListExecutionsDoc } from './n8n-list-executions';
-export { n8nDeleteExecutionDoc } from './n8n-delete-execution';
+export { n8nExecutionsDoc } from './n8n-executions';
+export { n8nWorkflowVersionsDoc } from './n8n-workflow-versions';
+export { n8nDeployTemplateDoc } from './n8n-deploy-template';

src/mcp/tool-docs/workflow_management/n8n-autofix-workflow.ts

@@ -153,9 +153,8 @@ Requires N8N_API_URL and N8N_API_KEY environment variables to be configured.`,
     relatedTools: [
       'n8n_validate_workflow',
       'validate_workflow',
-      'n8n_update_partial_workflow',
-      'validate_workflow_expressions',
-      'validate_node_operation'
+      'validate_node',
+      'n8n_update_partial_workflow'
     ]
   }
 };

src/mcp/tool-docs/workflow_management/n8n-delete-execution.ts

@@ -1,57 +0,0 @@
-import { ToolDocumentation } from '../types';
-
-export const n8nDeleteExecutionDoc: ToolDocumentation = {
-  name: 'n8n_delete_execution',
-  category: 'workflow_management',
-  essentials: {
-    description: 'Delete an execution record. This only removes the execution history, not any data processed.',
-    keyParameters: ['id'],
-    example: 'n8n_delete_execution({id: "12345"})',
-    performance: 'Immediate deletion, no undo available',
-    tips: [
-      'Deletion is permanent - execution cannot be recovered',
-      'Only removes execution history, not external data changes',
-      'Use for cleanup of test executions or sensitive data'
-    ]
-  },
-  full: {
-    description: `Permanently deletes a workflow execution record from n8n's history. This removes the execution metadata, logs, and any stored input/output data. However, it does NOT undo any actions the workflow performed (API calls, database changes, file operations, etc.). Use this for cleaning up test executions, removing sensitive data, or managing storage.`,
-    parameters: {
-      id: {
-        type: 'string',
-        required: true,
-        description: 'The execution ID to delete. This action cannot be undone'
-      }
-    },
-    returns: `Confirmation of deletion or error if execution not found. No data is returned about the deleted execution.`,
-    examples: [
-      'n8n_delete_execution({id: "12345"}) - Delete a specific execution',
-      'n8n_delete_execution({id: "test-run-567"}) - Clean up test execution',
-      'n8n_delete_execution({id: "sensitive-data-890"}) - Remove execution with sensitive data',
-      'n8n_delete_execution({id: "failed-execution-123"}) - Delete failed execution after debugging'
-    ],
-    useCases: [
-      'Clean up test or development execution history',
-      'Remove executions containing sensitive or personal data',
-      'Manage storage by deleting old execution records',
-      'Clean up after debugging failed workflows',
-      'Comply with data retention policies'
-    ],
-    performance: `Deletion is immediate and permanent. The operation is fast (< 100ms) as it only removes database records. No external systems or data are affected.`,
-    bestPractices: [
-      'Verify execution ID before deletion - action cannot be undone',
-      'Consider exporting execution data before deletion if needed',
-      'Use list_executions to find executions to delete',
-      'Document why executions were deleted for audit trails',
-      'Remember deletion only affects n8n records, not external changes'
-    ],
-    pitfalls: [
-      'Deletion is PERMANENT - no undo or recovery possible',
-      'Does NOT reverse workflow actions (API calls, DB changes, etc.)',
-      'Deleting executions breaks audit trails and debugging history',
-      'Cannot delete currently running executions (waiting status)',
-      'Bulk deletion not supported - must delete one at a time'
-    ],
-    relatedTools: ['n8n_list_executions', 'n8n_get_execution', 'n8n_trigger_webhook_workflow']
-  }
-};

src/mcp/tool-docs/workflow_management/n8n-delete-workflow.ts

@@ -11,7 +11,7 @@ export const n8nDeleteWorkflowDoc: ToolDocumentation = {
     tips: [
       'Action is irreversible',
       'Deletes all execution history',
-      'Check workflow first with get_minimal'
+      'Check workflow first with n8n_get_workflow({mode: "minimal"})'
     ]
   },
   full: {
@@ -34,7 +34,7 @@ export const n8nDeleteWorkflowDoc: ToolDocumentation = {
     performance: 'Fast operation - typically 50-150ms. May take longer if workflow has extensive execution history.',
     bestPractices: [
       'Always confirm before deletion',
-      'Check workflow with get_minimal first',
+      'Check workflow with n8n_get_workflow({mode: "minimal"}) first',
       'Consider deactivating instead of deleting',
       'Export workflow before deletion for backup'
     ],
@@ -45,6 +45,6 @@ export const n8nDeleteWorkflowDoc: ToolDocumentation = {
       'Active workflows can be deleted',
       'No built-in confirmation'
     ],
-    relatedTools: ['n8n_get_workflow_minimal', 'n8n_list_workflows', 'n8n_update_partial_workflow', 'n8n_delete_execution']
+    relatedTools: ['n8n_get_workflow', 'n8n_list_workflows', 'n8n_update_partial_workflow', 'n8n_executions']
   }
 };

src/mcp/tool-docs/workflow_management/n8n-deploy-template.ts

@@ -0,0 +1,69 @@
+import { ToolDocumentation } from '../types';
+
+export const n8nDeployTemplateDoc: ToolDocumentation = {
+  name: 'n8n_deploy_template',
+  category: 'workflow_management',
+  essentials: {
+    description: 'Deploy a workflow template from n8n.io directly to your n8n instance. Fetches template, optionally upgrades node versions and validates, then creates workflow.',
+    keyParameters: ['templateId', 'name', 'autoUpgradeVersions', 'validate', 'stripCredentials'],
+    example: 'n8n_deploy_template({templateId: 2776, name: "My Deployed Template"})',
+    performance: 'Network-dependent',
+    tips: [
+      'Workflow created inactive - configure credentials in n8n UI first',
+      'Returns list of required credentials',
+      'Use search_templates to find template IDs',
+      'Templates are upgraded to latest node versions by default'
+    ]
+  },
+  full: {
+    description: 'Deploys a workflow template from n8n.io directly to your n8n instance. This tool combines fetching a template and creating a workflow in a single operation. Templates are stored locally and fetched from the database. The workflow is always created in an inactive state, allowing you to configure credentials before activation.',
+    parameters: {
+      templateId: { type: 'number', required: true, description: 'Template ID from n8n.io (find via search_templates)' },
+      name: { type: 'string', description: 'Custom workflow name (default: template name)' },
+      autoUpgradeVersions: { type: 'boolean', description: 'Upgrade node typeVersions to latest supported (default: true)' },
+      validate: { type: 'boolean', description: 'Validate workflow before deployment (default: true)' },
+      stripCredentials: { type: 'boolean', description: 'Remove credential references - user configures in n8n UI (default: true)' }
+    },
+    returns: 'Object with workflowId, name, nodeCount, triggerType, requiredCredentials array, url, templateId, templateUrl',
+    examples: [
+      `// Deploy template with default settings
+n8n_deploy_template({templateId: 2776})`,
+      `// Deploy with custom name
+n8n_deploy_template({
+  templateId: 2776,
+  name: "My Google Drive to Airtable Sync"
+})`,
+      `// Deploy without validation (faster, use for trusted templates)
+n8n_deploy_template({
+  templateId: 2776,
+  validate: false
+})`,
+      `// Keep original node versions (useful for compatibility)
+n8n_deploy_template({
+  templateId: 2776,
+  autoUpgradeVersions: false
+})`
+    ],
+    useCases: [
+      'Quickly deploy pre-built workflow templates',
+      'Set up common automation patterns',
+      'Bootstrap new projects with proven workflows',
+      'Deploy templates found via search_templates'
+    ],
+    performance: 'Network-dependent - Typically 200-500ms (template fetch + workflow creation)',
+    bestPractices: [
+      'Use search_templates to find templates by use case',
+      'Review required credentials in the response',
+      'Configure credentials in n8n UI before activating',
+      'Test workflow before connecting to production systems'
+    ],
+    pitfalls: [
+      '**REQUIRES N8N_API_URL and N8N_API_KEY environment variables** - tool unavailable without n8n API access',
+      'Workflows created in INACTIVE state - must configure credentials and activate in n8n',
+      'Templates may reference services you do not have (Slack, Google, etc.)',
+      'Template database must be populated - run npm run fetch:templates if templates not found',
+      'Validation may fail for templates with outdated node configurations'
+    ],
+    relatedTools: ['search_templates', 'get_template', 'n8n_create_workflow', 'n8n_validate_workflow']
+  }
+};

src/mcp/tool-docs/workflow_management/n8n-executions.ts

@@ -0,0 +1,82 @@
+import { ToolDocumentation } from '../types';
+
+export const n8nExecutionsDoc: ToolDocumentation = {
+  name: 'n8n_executions',
+  category: 'workflow_management',
+  essentials: {
+    description: 'Manage workflow executions: get details, list, or delete. Unified tool for all execution operations.',
+    keyParameters: ['action', 'id', 'workflowId', 'status'],
+    example: 'n8n_executions({action: "list", workflowId: "abc123", status: "error"})',
+    performance: 'Fast (50-200ms)',
+    tips: [
+      'action="get": Get execution details by ID',
+      'action="list": List executions with filters',
+      'action="delete": Delete execution record',
+      'Use mode parameter for action=get to control detail level'
+    ]
+  },
+  full: {
+    description: `**Actions:**
+- get: Retrieve execution details by ID with configurable detail level
+- list: List executions with filtering and pagination
+- delete: Remove an execution record from history
+
+**Detail Modes for action="get":**
+- preview: Structure only, no data
+- summary: 2 items per node (default)
+- filtered: Custom items limit, optionally filter by node names
+- full: All execution data (can be very large)`,
+    parameters: {
+      action: { type: 'string', required: true, description: 'Operation: "get", "list", or "delete"' },
+      id: { type: 'string', required: false, description: 'Execution ID (required for action=get or action=delete)' },
+      mode: { type: 'string', required: false, description: 'For action=get: "preview", "summary" (default), "filtered", "full"' },
+      nodeNames: { type: 'array', required: false, description: 'For action=get with mode=filtered: Filter to specific nodes by name' },
+      itemsLimit: { type: 'number', required: false, description: 'For action=get with mode=filtered: Items per node (0=structure, 2=default, -1=unlimited)' },
+      includeInputData: { type: 'boolean', required: false, description: 'For action=get: Include input data in addition to output (default: false)' },
+      workflowId: { type: 'string', required: false, description: 'For action=list: Filter by workflow ID' },
+      status: { type: 'string', required: false, description: 'For action=list: Filter by status ("success", "error", "waiting")' },
+      limit: { type: 'number', required: false, description: 'For action=list: Number of results (1-100, default: 100)' },
+      cursor: { type: 'string', required: false, description: 'For action=list: Pagination cursor from previous response' },
+      projectId: { type: 'string', required: false, description: 'For action=list: Filter by project ID (enterprise)' },
+      includeData: { type: 'boolean', required: false, description: 'For action=list: Include execution data (default: false)' }
+    },
+    returns: `Depends on action:
+- get: Execution object with data based on mode
+- list: { data: [...executions], nextCursor?: string }
+- delete: { success: boolean, message: string }`,
+    examples: [
+      '// List recent executions for a workflow\nn8n_executions({action: "list", workflowId: "abc123", limit: 10})',
+      '// List failed executions\nn8n_executions({action: "list", status: "error"})',
+      '// Get execution summary\nn8n_executions({action: "get", id: "exec_456"})',
+      '// Get full execution data\nn8n_executions({action: "get", id: "exec_456", mode: "full"})',
+      '// Get specific nodes from execution\nn8n_executions({action: "get", id: "exec_456", mode: "filtered", nodeNames: ["HTTP Request", "Slack"]})',
+      '// Delete an execution\nn8n_executions({action: "delete", id: "exec_456"})'
+    ],
+    useCases: [
+      'Debug workflow failures (get with mode=full)',
+      'Monitor workflow health (list with status filter)',
+      'Audit execution history',
+      'Clean up old execution records',
+      'Analyze specific node outputs'
+    ],
+    performance: `Response times:
+- list: 50-150ms depending on filters
+- get (preview/summary): 30-100ms
+- get (full): 100-500ms+ depending on data size
+- delete: 30-80ms`,
+    bestPractices: [
+      'Use mode="summary" (default) for debugging - shows enough data',
+      'Use mode="filtered" with nodeNames for large workflows',
+      'Filter by workflowId when listing to reduce results',
+      'Use cursor for pagination through large result sets',
+      'Delete old executions to save storage'
+    ],
+    pitfalls: [
+      'Requires N8N_API_URL and N8N_API_KEY configured',
+      'mode="full" can return very large responses for complex workflows',
+      'Execution must exist or returns 404',
+      'Delete is permanent - cannot undo'
+    ],
+    relatedTools: ['n8n_get_workflow', 'n8n_trigger_webhook_workflow', 'n8n_validate_workflow']
+  }
+};

src/mcp/tool-docs/workflow_management/n8n-get-execution.ts

@@ -1,283 +0,0 @@
-import { ToolDocumentation } from '../types';
-
-export const n8nGetExecutionDoc: ToolDocumentation = {
-  name: 'n8n_get_execution',
-  category: 'workflow_management',
-  essentials: {
-    description: 'Get execution details with smart filtering to avoid token limits. Use preview mode first to assess data size, then fetch appropriately.',
-    keyParameters: ['id', 'mode', 'itemsLimit', 'nodeNames'],
-    example: `
-// RECOMMENDED WORKFLOW:
-// 1. Preview first
-n8n_get_execution({id: "12345", mode: "preview"})
-// Returns: structure, counts, size estimate, recommendation
-
-// 2. Based on recommendation, fetch data:
-n8n_get_execution({id: "12345", mode: "summary"}) // 2 items per node
-n8n_get_execution({id: "12345", mode: "filtered", itemsLimit: 5}) // 5 items
-n8n_get_execution({id: "12345", nodeNames: ["HTTP Request"]}) // Specific node
-`,
-    performance: 'Preview: <50ms, Summary: <200ms, Full: depends on data size',
-    tips: [
-      'ALWAYS use preview mode first for large datasets',
-      'Preview shows structure + counts without consuming tokens for data',
-      'Summary mode (2 items per node) is safe default',
-      'Use nodeNames to focus on specific nodes only',
-      'itemsLimit: 0 = structure only, -1 = unlimited',
-      'Check recommendation.suggestedMode from preview'
-    ]
-  },
-  full: {
-    description: `Retrieves and intelligently filters execution data to enable inspection without exceeding token limits. This tool provides multiple modes for different use cases, from quick previews to complete data retrieval.
-
-**The Problem**: Workflows processing large datasets (50+ database records) generate execution data that exceeds token/response limits, making traditional full-data fetching impossible.
-
-**The Solution**: Four retrieval modes with smart filtering:
-1. **Preview**: Structure + counts only (no actual data)
-2. **Summary**: 2 sample items per node (safe default)
-3. **Filtered**: Custom limits and node selection
-4. **Full**: Complete data (use with caution)
-
-**Recommended Workflow**:
-1. Start with preview mode to assess size
-2. Use recommendation to choose appropriate mode
-3. Fetch filtered data as needed`,
-
-    parameters: {
-      id: {
-        type: 'string',
-        required: true,
-        description: 'The execution ID to retrieve. Obtained from list_executions or webhook trigger responses'
-      },
-      mode: {
-        type: 'string',
-        required: false,
-        description: `Retrieval mode (default: auto-detect from other params):
-- 'preview': Structure, counts, size estimates - NO actual data (fastest)
-- 'summary': Metadata + 2 sample items per node (safe default)
-- 'filtered': Custom filtering with itemsLimit/nodeNames
-- 'full': Complete execution data (use with caution)`
-      },
-      nodeNames: {
-        type: 'array',
-        required: false,
-        description: 'Filter to specific nodes by name. Example: ["HTTP Request", "Filter"]. Useful when you only need to inspect specific nodes.'
-      },
-      itemsLimit: {
-        type: 'number',
-        required: false,
-        description: `Items to return per node (default: 2):
-- 0: Structure only (see data shape without values)
-- 1-N: Return N items per node
-- -1: Unlimited (return all items)
-
-Note: Structure-only mode (0) shows JSON schema without actual values.`
-      },
-      includeInputData: {
-        type: 'boolean',
-        required: false,
-        description: 'Include input data in addition to output data (default: false). Useful for debugging data transformations.'
-      },
-      includeData: {
-        type: 'boolean',
-        required: false,
-        description: 'DEPRECATED: Legacy parameter. Use mode instead. If true, maps to mode="summary" for backward compatibility.'
-      }
-    },
-
-    returns: `**Preview Mode Response**:
-{
-  mode: 'preview',
-  preview: {
-    totalNodes: number,
-    executedNodes: number,
-    estimatedSizeKB: number,
-    nodes: {
-      [nodeName]: {
-        status: 'success' | 'error',
-        itemCounts: { input: number, output: number },
-        dataStructure: {...}, // JSON schema
-        estimatedSizeKB: number
-      }
-    }
-  },
-  recommendation: {
-    canFetchFull: boolean,
-    suggestedMode: 'preview'|'summary'|'filtered'|'full',
-    suggestedItemsLimit?: number,
-    reason: string
-  }
-}
-
-**Summary/Filtered/Full Mode Response**:
-{
-  mode: 'summary' | 'filtered' | 'full',
-  summary: {
-    totalNodes: number,
-    executedNodes: number,
-    totalItems: number,
-    hasMoreData: boolean  // true if truncated
-  },
-  nodes: {
-    [nodeName]: {
-      executionTime: number,
-      itemsInput: number,
-      itemsOutput: number,
-      status: 'success' | 'error',
-      error?: string,
-      data: {
-        output: [...],  // Actual data items
-        metadata: {
-          totalItems: number,
-          itemsShown: number,
-          truncated: boolean
-        }
-      }
-    }
-  }
-}`,
-
-    examples: [
-      `// Example 1: Preview workflow (RECOMMENDED FIRST STEP)
-n8n_get_execution({id: "exec_123", mode: "preview"})
-// Returns structure, counts, size, recommendation
-// Use this to decide how to fetch data`,
-
-      `// Example 2: Follow recommendation
-const preview = n8n_get_execution({id: "exec_123", mode: "preview"});
-if (preview.recommendation.canFetchFull) {
-  n8n_get_execution({id: "exec_123", mode: "full"});
-} else {
-  n8n_get_execution({
-    id: "exec_123",
-    mode: "filtered",
-    itemsLimit: preview.recommendation.suggestedItemsLimit
-  });
-}`,
-
-      `// Example 3: Summary mode (safe default for unknown datasets)
-n8n_get_execution({id: "exec_123", mode: "summary"})
-// Gets 2 items per node - safe for most cases`,
-
-      `// Example 4: Filter to specific node
-n8n_get_execution({
-  id: "exec_123",
-  mode: "filtered",
-  nodeNames: ["HTTP Request"],
-  itemsLimit: 5
-})
-// Gets only HTTP Request node, 5 items`,
-
-      `// Example 5: Structure only (see data shape)
-n8n_get_execution({
-  id: "exec_123",
-  mode: "filtered",
-  itemsLimit: 0
-})
-// Returns JSON schema without actual values`,
-
-      `// Example 6: Debug with input data
-n8n_get_execution({
-  id: "exec_123",
-  mode: "filtered",
-  nodeNames: ["Transform"],
-  itemsLimit: 2,
-  includeInputData: true
-})
-// See both input and output for debugging`,
-
-      `// Example 7: Backward compatibility (legacy)
-n8n_get_execution({id: "exec_123"}) // Minimal data
-n8n_get_execution({id: "exec_123", includeData: true}) // Maps to summary mode`
-    ],
-
-    useCases: [
-      'Monitor status of triggered workflows',
-      'Debug failed workflows by examining error messages and partial data',
-      'Inspect large datasets without exceeding token limits',
-      'Validate data transformations between nodes',
-      'Understand execution flow and timing',
-      'Track workflow performance metrics',
-      'Verify successful completion before proceeding',
-      'Extract specific data from execution results'
-    ],
-
-    performance: `**Response Times** (approximate):
-- Preview mode: <50ms (no data, just structure)
-- Summary mode: <200ms (2 items per node)
-- Filtered mode: 50-500ms (depends on filters)
-- Full mode: 200ms-5s (depends on data size)
-
-**Token Consumption**:
-- Preview: ~500 tokens (no data values)
-- Summary (2 items): ~2-5K tokens
-- Filtered (5 items): ~5-15K tokens
-- Full (50+ items): 50K+ tokens (may exceed limits)
-
-**Optimization Tips**:
-- Use preview for all large datasets
-- Use nodeNames to focus on relevant nodes only
-- Start with small itemsLimit and increase if needed
-- Use itemsLimit: 0 to see structure without data`,
-
-    bestPractices: [
-      'ALWAYS use preview mode first for unknown datasets',
-      'Trust the recommendation.suggestedMode from preview',
-      'Use nodeNames to filter to relevant nodes only',
-      'Start with summary mode if preview indicates moderate size',
-      'Use itemsLimit: 0 to understand data structure',
-      'Check hasMoreData to know if results are truncated',
-      'Store execution IDs from triggers for later inspection',
-      'Use mode="filtered" with custom limits for large datasets',
-      'Include input data only when debugging transformations',
-      'Monitor summary.totalItems to understand dataset size'
-    ],
-
-    pitfalls: [
-      'DON\'T fetch full mode without previewing first - may timeout',
-      'DON\'T assume all data fits - always check hasMoreData',
-      'DON\'T ignore the recommendation from preview mode',
-      'Execution data is retained based on n8n settings - old executions may be purged',
-      'Binary data (files, images) is not fully included - only metadata',
-      'Status "waiting" indicates execution is still running',
-      'Error executions may have partial data from successful nodes',
-      'Very large individual items (>1MB) may be truncated',
-      'Preview mode estimates may be off by 10-20% for complex structures',
-      'Node names are case-sensitive in nodeNames filter'
-    ],
-
-    modeComparison: `**When to use each mode**:
-
-**Preview**:
-- ALWAYS use first for unknown datasets
-- When you need to know if data is safe to fetch
-- To see data structure without consuming tokens
-- To get size estimates and recommendations
-
-**Summary** (default):
-- Safe default for most cases
-- When you need representative samples
-- When preview recommends it
-- For quick data inspection
-
-**Filtered**:
-- When you need specific nodes only
-- When you need more than 2 items but not all
-- When preview recommends it with itemsLimit
-- For targeted data extraction
-
-**Full**:
-- ONLY when preview says canFetchFull: true
-- For small executions (< 20 items total)
-- When you genuinely need all data
-- When you're certain data fits in token limit`,
-
-    relatedTools: [
-      'n8n_list_executions - Find execution IDs',
-      'n8n_trigger_webhook_workflow - Trigger and get execution ID',
-      'n8n_delete_execution - Clean up old executions',
-      'n8n_get_workflow - Get workflow structure',
-      'validate_workflow - Validate before executing'
-    ]
-  }
-};

src/mcp/tool-docs/workflow_management/n8n-get-workflow-details.ts

@@ -1,49 +0,0 @@
-import { ToolDocumentation } from '../types';
-
-export const n8nGetWorkflowDetailsDoc: ToolDocumentation = {
-  name: 'n8n_get_workflow_details',
-  category: 'workflow_management',
-  essentials: {
-    description: 'Get workflow details with metadata, version, execution stats. More info than get_workflow.',
-    keyParameters: ['id'],
-    example: 'n8n_get_workflow_details({id: "workflow_123"})',
-    performance: 'Fast (100-300ms)',
-    tips: [
-      'Includes execution statistics',
-      'Shows version history info',
-      'Contains metadata like tags'
-    ]
-  },
-  full: {
-    description: 'Retrieves comprehensive workflow details including metadata, execution statistics, version information, and usage analytics. Provides more information than get_workflow, including data not typically needed for editing but useful for monitoring and analysis.',
-    parameters: {
-      id: { type: 'string', required: true, description: 'Workflow ID to retrieve details for' }
-    },
-    returns: 'Extended workflow object with: id, name, nodes, connections, settings, plus metadata (tags, owner, shared users), execution stats (success/error counts, average runtime), version info, created/updated timestamps',
-    examples: [
-      'n8n_get_workflow_details({id: "abc123"}) - Get workflow with stats',
-      'const details = n8n_get_workflow_details({id: "xyz789"}); // Analyze performance'
-    ],
-    useCases: [
-      'Monitor workflow performance',
-      'Analyze execution patterns',
-      'View workflow metadata',
-      'Check version information',
-      'Audit workflow usage'
-    ],
-    performance: 'Slightly slower than get_workflow due to additional metadata - typically 100-300ms. Stats may be cached.',
-    bestPractices: [
-      'Use for monitoring and analysis',
-      'Check execution stats before optimization',
-      'Review error counts for debugging',
-      'Monitor average execution times'
-    ],
-    pitfalls: [
-      'Requires N8N_API_URL and N8N_API_KEY configured',
-      'More data than needed for simple edits',
-      'Stats may have slight delay',
-      'Not all n8n versions support all fields'
-    ],
-    relatedTools: ['n8n_get_workflow', 'n8n_list_executions', 'n8n_get_execution', 'n8n_list_workflows']
-  }
-};

src/mcp/tool-docs/workflow_management/n8n-get-workflow-minimal.ts

@@ -1,49 +0,0 @@
-import { ToolDocumentation } from '../types';
-
-export const n8nGetWorkflowMinimalDoc: ToolDocumentation = {
-  name: 'n8n_get_workflow_minimal',
-  category: 'workflow_management',
-  essentials: {
-    description: 'Get minimal info: ID, name, active status, tags. Fast for listings.',
-    keyParameters: ['id'],
-    example: 'n8n_get_workflow_minimal({id: "workflow_123"})',
-    performance: 'Very fast (<50ms)',
-    tips: [
-      'Fastest way to check workflow exists',
-      'Perfect for status checks',
-      'Use in list displays'
-    ]
-  },
-  full: {
-    description: 'Retrieves only essential workflow information without nodes or connections. Returns minimal data needed for listings, status checks, and quick lookups. Optimized for performance when full workflow data is not needed.',
-    parameters: {
-      id: { type: 'string', required: true, description: 'Workflow ID to retrieve minimal info for' }
-    },
-    returns: 'Minimal workflow object with: id, name, active status, tags array, createdAt, updatedAt. No nodes, connections, or settings included.',
-    examples: [
-      'n8n_get_workflow_minimal({id: "abc123"}) - Quick existence check',
-      'const info = n8n_get_workflow_minimal({id: "xyz789"}); // Check if active'
-    ],
-    useCases: [
-      'Quick workflow existence checks',
-      'Display workflow lists',
-      'Check active/inactive status',
-      'Get workflow tags',
-      'Performance-critical operations'
-    ],
-    performance: 'Extremely fast - typically under 50ms. Returns only database metadata without loading workflow definition.',
-    bestPractices: [
-      'Use for list displays and dashboards',
-      'Ideal for existence checks before operations',
-      'Cache results for UI responsiveness',
-      'Combine with list_workflows for bulk checks'
-    ],
-    pitfalls: [
-      'Requires N8N_API_URL and N8N_API_KEY configured',
-      'No workflow content - cannot edit or validate',
-      'Tags may be empty array',
-      'Must use get_workflow for actual workflow data'
-    ],
-    relatedTools: ['n8n_list_workflows', 'n8n_get_workflow', 'n8n_get_workflow_structure', 'n8n_update_partial_workflow']
-  }
-};

src/mcp/tool-docs/workflow_management/n8n-get-workflow-structure.ts

@@ -1,49 +0,0 @@
-import { ToolDocumentation } from '../types';
-
-export const n8nGetWorkflowStructureDoc: ToolDocumentation = {
-  name: 'n8n_get_workflow_structure',
-  category: 'workflow_management',
-  essentials: {
-    description: 'Get workflow structure: nodes and connections only. No parameter details.',
-    keyParameters: ['id'],
-    example: 'n8n_get_workflow_structure({id: "workflow_123"})',
-    performance: 'Fast (75-150ms)',
-    tips: [
-      'Shows workflow topology',
-      'Node types without parameters',
-      'Perfect for visualization'
-    ]
-  },
-  full: {
-    description: 'Retrieves workflow structural information including node types, positions, and connections, but without detailed node parameters. Ideal for understanding workflow topology, creating visualizations, or analyzing workflow complexity without the overhead of full parameter data.',
-    parameters: {
-      id: { type: 'string', required: true, description: 'Workflow ID to retrieve structure for' }
-    },
-    returns: 'Workflow structure with: id, name, nodes array (id, name, type, position only), connections object. No node parameters, credentials, or settings included.',
-    examples: [
-      'n8n_get_workflow_structure({id: "abc123"}) - Visualize workflow',
-      'const structure = n8n_get_workflow_structure({id: "xyz789"}); // Analyze complexity'
-    ],
-    useCases: [
-      'Generate workflow visualizations',
-      'Analyze workflow complexity',
-      'Understand node relationships',
-      'Create workflow diagrams',
-      'Quick topology validation'
-    ],
-    performance: 'Fast retrieval - typically 75-150ms. Faster than get_workflow as parameters are stripped.',
-    bestPractices: [
-      'Use for visualization tools',
-      'Ideal for workflow analysis',
-      'Good for connection validation',
-      'Cache for UI diagram rendering'
-    ],
-    pitfalls: [
-      'Requires N8N_API_URL and N8N_API_KEY configured',
-      'No parameter data for configuration',
-      'Cannot validate node settings',
-      'Must use get_workflow for editing'
-    ],
-    relatedTools: ['n8n_get_workflow', 'n8n_validate_workflow_connections', 'n8n_get_workflow_minimal', 'validate_workflow_connections']
-  }
-};

src/mcp/tool-docs/workflow_management/n8n-get-workflow.ts

@@ -4,46 +4,63 @@ export const n8nGetWorkflowDoc: ToolDocumentation = {
   name: 'n8n_get_workflow',
   category: 'workflow_management',
   essentials: {
-    description: 'Get a workflow by ID. Returns the complete workflow including nodes, connections, and settings.',
-    keyParameters: ['id'],
-    example: 'n8n_get_workflow({id: "workflow_123"})',
+    description: 'Get workflow by ID with different detail levels. Use mode to control response size and content.',
+    keyParameters: ['id', 'mode'],
+    example: 'n8n_get_workflow({id: "workflow_123", mode: "structure"})',
     performance: 'Fast (50-200ms)',
     tips: [
-      'Returns complete workflow JSON',
-      'Includes all node parameters',
-      'Use get_workflow_minimal for faster listings'
+      'mode="full" (default): Complete workflow with all data',
+      'mode="details": Full workflow + execution stats',
+      'mode="structure": Just nodes and connections (topology)',
+      'mode="minimal": Only id, name, active status, tags'
     ]
   },
   full: {
-    description: 'Retrieves a complete workflow from n8n by its ID. Returns full workflow definition including all nodes with their parameters, connections between nodes, and workflow settings. This is the primary tool for fetching workflows for viewing, editing, or cloning.',
+    description: `**Modes:**
+- full (default): Complete workflow including all nodes with parameters, connections, and settings
+- details: Full workflow plus execution statistics (success/error counts, last execution time)
+- structure: Nodes and connections only - useful for topology analysis
+- minimal: Just id, name, active status, and tags - fastest response`,
     parameters: {
-      id: { type: 'string', required: true, description: 'Workflow ID to retrieve' }
+      id: { type: 'string', required: true, description: 'Workflow ID to retrieve' },
+      mode: { type: 'string', required: false, description: 'Detail level: "full" (default), "details", "structure", "minimal"' }
     },
-    returns: 'Complete workflow object containing: id, name, active status, nodes array (with full parameters), connections object, settings, createdAt, updatedAt',
+    returns: `Depends on mode:
+- full: Complete workflow object (id, name, active, nodes[], connections{}, settings, createdAt, updatedAt)
+- details: Full workflow + executionStats (successCount, errorCount, lastExecution, etc.)
+- structure: { nodes: [...], connections: {...} } - topology only
+- minimal: { id, name, active, tags, createdAt, updatedAt }`,
     examples: [
-      'n8n_get_workflow({id: "abc123"}) - Get workflow for editing',
-      'const wf = n8n_get_workflow({id: "xyz789"}); // Clone workflow structure'
+      '// Get complete workflow (default)\nn8n_get_workflow({id: "abc123"})',
+      '// Get workflow with execution stats\nn8n_get_workflow({id: "abc123", mode: "details"})',
+      '// Get just the topology\nn8n_get_workflow({id: "abc123", mode: "structure"})',
+      '// Quick metadata check\nn8n_get_workflow({id: "abc123", mode: "minimal"})'
     ],
     useCases: [
-      'View workflow configuration',
-      'Export workflow for backup',
-      'Clone workflow structure',
-      'Debug workflow issues',
-      'Prepare for updates'
+      'View and edit workflow (mode=full)',
+      'Analyze workflow performance (mode=details)',
+      'Clone or compare workflow structure (mode=structure)',
+      'List workflows with status (mode=minimal)',
+      'Debug workflow issues'
     ],
-    performance: 'Fast retrieval - typically 50-200ms depending on workflow size. Cached by n8n for performance.',
+    performance: `Response times vary by mode:
+- minimal: ~20-50ms (smallest response)
+- structure: ~30-80ms (nodes + connections only)
+- full: ~50-200ms (complete workflow)
+- details: ~100-300ms (includes execution queries)`,
     bestPractices: [
-      'Check workflow exists before updating',
-      'Use for complete workflow data needs',
-      'Cache results when making multiple operations',
-      'Validate after retrieving if modifying'
+      'Use mode="minimal" when listing or checking status',
+      'Use mode="structure" for workflow analysis or cloning',
+      'Use mode="full" (default) when editing',
+      'Use mode="details" for debugging execution issues',
+      'Validate workflow after retrieval if planning modifications'
     ],
     pitfalls: [
       'Requires N8N_API_URL and N8N_API_KEY configured',
-      'Returns all data - use minimal/structure for performance',
-      'Workflow must exist or returns 404',
-      'Credentials are referenced but not included'
+      'mode="details" adds database queries for execution stats',
+      'Workflow must exist or returns 404 error',
+      'Credentials are referenced by ID but values not included'
     ],
-    relatedTools: ['n8n_get_workflow_minimal', 'n8n_get_workflow_structure', 'n8n_update_full_workflow', 'n8n_validate_workflow']
+    relatedTools: ['n8n_list_workflows', 'n8n_update_full_workflow', 'n8n_update_partial_workflow', 'n8n_validate_workflow']
   }
 };

src/mcp/tool-docs/workflow_management/n8n-list-executions.ts

@@ -1,84 +0,0 @@
-import { ToolDocumentation } from '../types';
-
-export const n8nListExecutionsDoc: ToolDocumentation = {
-  name: 'n8n_list_executions',
-  category: 'workflow_management',
-  essentials: {
-    description: 'List workflow executions with optional filters. Supports pagination for large result sets.',
-    keyParameters: ['workflowId', 'status', 'limit'],
-    example: 'n8n_list_executions({workflowId: "abc123", status: "error"})',
-    performance: 'Fast metadata retrieval, use pagination for large datasets',
-    tips: [
-      'Filter by status (success/error/waiting) to find specific execution types',
-      'Use workflowId to see all executions for a specific workflow',
-      'Pagination via cursor allows retrieving large execution histories'
-    ]
-  },
-  full: {
-    description: `Lists workflow executions with powerful filtering options. This tool is essential for monitoring workflow performance, finding failed executions, and tracking workflow activity. Supports pagination for retrieving large execution histories and filtering by workflow, status, and project.`,
-    parameters: {
-      limit: {
-        type: 'number',
-        required: false,
-        description: 'Number of executions to return (1-100, default: 100). Use with cursor for pagination'
-      },
-      cursor: {
-        type: 'string',
-        required: false,
-        description: 'Pagination cursor from previous response. Used to retrieve next page of results'
-      },
-      workflowId: {
-        type: 'string',
-        required: false,
-        description: 'Filter executions by specific workflow ID. Shows all executions for that workflow'
-      },
-      projectId: {
-        type: 'string',
-        required: false,
-        description: 'Filter by project ID (enterprise feature). Groups executions by project'
-      },
-      status: {
-        type: 'string',
-        required: false,
-        enum: ['success', 'error', 'waiting'],
-        description: 'Filter by execution status. Success = completed, Error = failed, Waiting = running'
-      },
-      includeData: {
-        type: 'boolean',
-        required: false,
-        description: 'Include execution data in results (default: false). Significantly increases response size'
-      }
-    },
-    returns: `Array of execution objects with metadata, pagination cursor for next page, and optionally execution data. Each execution includes ID, status, start/end times, and workflow reference.`,
-    examples: [
-      'n8n_list_executions({limit: 10}) - Get 10 most recent executions',
-      'n8n_list_executions({workflowId: "abc123"}) - All executions for specific workflow',
-      'n8n_list_executions({status: "error", limit: 50}) - Find failed executions',
-      'n8n_list_executions({status: "waiting"}) - Monitor currently running workflows',
-      'n8n_list_executions({cursor: "next-page-token"}) - Get next page of results'
-    ],
-    useCases: [
-      'Monitor workflow execution history and patterns',
-      'Find and debug failed workflow executions',
-      'Track currently running workflows (waiting status)',
-      'Analyze workflow performance and execution frequency',
-      'Generate execution reports for specific workflows'
-    ],
-    performance: `Listing executions is fast for metadata only. Including data (includeData: true) significantly impacts performance. Use pagination (limit + cursor) for large result sets. Default limit of 100 balances performance with usability.`,
-    bestPractices: [
-      'Use status filters to focus on specific execution types',
-      'Implement pagination for large execution histories',
-      'Avoid includeData unless you need execution details',
-      'Filter by workflowId when monitoring specific workflows',
-      'Check for cursor in response to detect more pages'
-    ],
-    pitfalls: [
-      'Large limits with includeData can cause timeouts',
-      'Execution retention depends on n8n configuration',
-      'Cursor tokens expire - use them promptly',
-      'Status "waiting" includes both running and queued executions',
-      'Deleted workflows still show in execution history'
-    ],
-    relatedTools: ['n8n_get_execution', 'n8n_trigger_webhook_workflow', 'n8n_delete_execution', 'n8n_list_workflows']
-  }
-};

src/mcp/tool-docs/workflow_management/n8n-list-workflows.ts

@@ -50,6 +50,6 @@ export const n8nListWorkflowsDoc: ToolDocumentation = {
       'Server may return fewer than requested limit',
       'returned field is count of current page only, not system total'
     ],
-    relatedTools: ['n8n_get_workflow_minimal', 'n8n_get_workflow', 'n8n_update_partial_workflow', 'n8n_list_executions']
+    relatedTools: ['n8n_get_workflow', 'n8n_update_partial_workflow', 'n8n_executions']
   }
 };

src/mcp/tool-docs/workflow_management/n8n-trigger-webhook-workflow.ts

@@ -64,13 +64,13 @@ export const n8nTriggerWebhookWorkflowDoc: ToolDocumentation = {
 When a webhook trigger fails, the error response now includes specific guidance to help debug the issue:
 
 **Error with Execution ID** (workflow started but failed):
-- Format: "Workflow {workflowId} execution {executionId} failed. Use n8n_get_execution({id: '{executionId}', mode: 'preview'}) to investigate the error."
+- Format: "Workflow {workflowId} execution {executionId} failed. Use n8n_executions({action: 'get', id: '{executionId}', mode: 'preview'}) to investigate the error."
 - Response includes: executionId and workflowId fields for direct access
-- Recommended action: Use n8n_get_execution with mode='preview' for fast, efficient error inspection
+- Recommended action: Use n8n_executions with action='get' and mode='preview' for fast, efficient error inspection
 
 **Error without Execution ID** (workflow didn't start):
-- Format: "Workflow failed to execute. Use n8n_list_executions to find recent executions, then n8n_get_execution with mode='preview' to investigate."
-- Recommended action: Check recent executions with n8n_list_executions
+- Format: "Workflow failed to execute. Use n8n_executions({action: 'list'}) to find recent executions, then n8n_executions({action: 'get', mode: 'preview'}) to investigate."
+- Recommended action: Check recent executions with n8n_executions({action: 'list'})
 
 **Why mode='preview'?**
 - Fast: <50ms response time
@@ -92,7 +92,7 @@ When a webhook trigger fails, the error response now includes specific guidance
 
 **Investigation Workflow**:
 1. Trigger returns error with execution ID
-2. Call n8n_get_execution({id: executionId, mode: 'preview'}) to see structure and error
+2. Call n8n_executions({action: 'get', id: executionId, mode: 'preview'}) to see structure and error
 3. Based on preview recommendation, fetch more data if needed
 4. Fix issues in workflow and retry`,
     bestPractices: [
@@ -101,7 +101,7 @@ When a webhook trigger fails, the error response now includes specific guidance
       'Use async mode (waitForResponse: false) for long-running workflows',
       'Include authentication headers when webhook requires them',
       'Test webhook URL manually first to ensure it works',
-      'When errors occur, use n8n_get_execution with mode="preview" first for efficient debugging',
+      'When errors occur, use n8n_executions with action="get" and mode="preview" first for efficient debugging',
       'Store execution IDs from error responses for later investigation'
     ],
     pitfalls: [
@@ -110,9 +110,9 @@ When a webhook trigger fails, the error response now includes specific guidance
       'Webhook node must be the trigger node in the workflow',
       'Timeout errors occur with long workflows in sync mode',
       'Data format must match webhook node expectations',
-      'Error messages always include n8n_get_execution guidance - follow the suggested steps for efficient debugging',
+      'Error messages always include n8n_executions guidance - follow the suggested steps for efficient debugging',
       'Execution IDs in error responses are crucial for debugging - always check for and use them'
     ],
-    relatedTools: ['n8n_get_execution', 'n8n_list_executions', 'n8n_get_workflow', 'n8n_create_workflow']
+    relatedTools: ['n8n_executions', 'n8n_get_workflow', 'n8n_create_workflow']
   }
 };

src/mcp/tool-docs/workflow_management/n8n-update-partial-workflow.ts

@@ -9,7 +9,8 @@ export const n8nUpdatePartialWorkflowDoc: ToolDocumentation = {
     example: 'n8n_update_partial_workflow({id: "wf_123", operations: [{type: "rewireConnection", source: "IF", from: "Old", to: "New", branch: "true"}]})',
     performance: 'Fast (50-200ms)',
     tips: [
-      'Include intent parameter in every call - helps to return better responses',
+      'ALWAYS provide intent parameter describing what you\'re doing (e.g., "Add error handling", "Fix webhook URL", "Connect Slack to error output")',
+      'DON\'T use generic intent like "update workflow" or "partial update" - be specific about your goal',
       'Use rewireConnection to change connection targets',
       'Use branch="true"/"false" for IF nodes',
       'Use case=N for Switch nodes',
@@ -89,7 +90,6 @@ Full support for all 8 AI connection types used in n8n AI workflows:
 
 **Important Notes**:
 - **AI nodes do NOT require main connections**: Nodes like OpenAI Chat Model, Postgres Chat Memory, Embeddings OpenAI, and Supabase Vector Store use AI-specific connection types exclusively. They should ONLY have connections like \`ai_languageModel\`, \`ai_memory\`, \`ai_embedding\`, or \`ai_tool\` - NOT \`main\` connections.
-- **Fixed in v2.21.1**: Validation now correctly recognizes AI nodes that only have AI-specific connections without requiring \`main\` connections (resolves issue #357).
 
 **Best Practices**:
 - Always specify \`sourceOutput\` for AI connections (defaults to "main" if omitted)
@@ -367,7 +367,7 @@ n8n_update_partial_workflow({
     ],
     performance: 'Very fast - typically 50-200ms. Much faster than full updates as only changes are processed.',
     bestPractices: [
-      'Always include intent parameter - it helps provide better responses',
+      'Always include intent parameter with specific description (e.g., "Add error handling to HTTP Request node", "Fix authentication flow", "Connect Slack notification to errors"). Avoid generic phrases like "update workflow" or "partial update"',
       'Use rewireConnection instead of remove+add for changing targets',
       'Use branch="true"/"false" for IF nodes instead of sourceIndex',
       'Use case=N for Switch nodes instead of sourceIndex',

src/mcp/tool-docs/workflow_management/n8n-validate-workflow.ts

@@ -66,6 +66,6 @@ Requires N8N_API_URL and N8N_API_KEY environment variables to be configured.`,
       'Profile affects validation time - strict is slower but more thorough',
       'Expression validation may flag working but non-standard syntax'
     ],
-    relatedTools: ['validate_workflow', 'n8n_get_workflow', 'validate_workflow_expressions', 'n8n_health_check', 'n8n_autofix_workflow']
+    relatedTools: ['validate_workflow', 'n8n_get_workflow', 'n8n_health_check', 'n8n_autofix_workflow']
   }
 };

src/mcp/tool-docs/workflow_management/n8n-workflow-versions.ts

@@ -0,0 +1,168 @@
+import { ToolDocumentation } from '../types';
+
+export const n8nWorkflowVersionsDoc: ToolDocumentation = {
+  name: 'n8n_workflow_versions',
+  category: 'workflow_management',
+  essentials: {
+    description: 'Manage workflow version history, rollback to previous versions, and cleanup old versions',
+    keyParameters: ['mode', 'workflowId', 'versionId'],
+    example: 'n8n_workflow_versions({mode: "list", workflowId: "abc123"})',
+    performance: 'Fast for list/get (~100ms), moderate for rollback (~200-500ms)',
+    tips: [
+      'Use mode="list" to see all saved versions before rollback',
+      'Rollback creates a backup version automatically',
+      'Use prune to clean up old versions and save storage',
+      'truncate requires explicit confirmTruncate: true'
+    ]
+  },
+  full: {
+    description: `Comprehensive workflow version management system. Supports six operations:
+
+**list** - Show version history for a workflow
+- Returns all saved versions with timestamps, snapshot sizes, and metadata
+- Use limit parameter to control how many versions to return
+
+**get** - Get details of a specific version
+- Returns the complete workflow snapshot from that version
+- Use to compare versions or extract old configurations
+
+**rollback** - Restore workflow to a previous version
+- Creates a backup of the current workflow before rollback
+- Optionally validates the workflow structure before applying
+- Returns the restored workflow and backup version ID
+
+**delete** - Delete specific version(s)
+- Delete a single version by versionId
+- Delete all versions for a workflow with deleteAll: true
+
+**prune** - Clean up old versions
+- Keeps only the N most recent versions (default: 10)
+- Useful for managing storage and keeping history manageable
+
+**truncate** - Delete ALL versions for ALL workflows
+- Dangerous operation requiring explicit confirmation
+- Use for complete version history cleanup`,
+    parameters: {
+      mode: {
+        type: 'string',
+        required: true,
+        description: 'Operation mode: "list", "get", "rollback", "delete", "prune", or "truncate"',
+        enum: ['list', 'get', 'rollback', 'delete', 'prune', 'truncate']
+      },
+      workflowId: {
+        type: 'string',
+        required: false,
+        description: 'Workflow ID (required for list, rollback, delete, prune modes)'
+      },
+      versionId: {
+        type: 'number',
+        required: false,
+        description: 'Version ID (required for get mode, optional for rollback to specific version, required for single delete)'
+      },
+      limit: {
+        type: 'number',
+        required: false,
+        default: 10,
+        description: 'Maximum versions to return in list mode'
+      },
+      validateBefore: {
+        type: 'boolean',
+        required: false,
+        default: true,
+        description: 'Validate workflow structure before rollback (rollback mode only)'
+      },
+      deleteAll: {
+        type: 'boolean',
+        required: false,
+        default: false,
+        description: 'Delete all versions for workflow (delete mode only)'
+      },
+      maxVersions: {
+        type: 'number',
+        required: false,
+        default: 10,
+        description: 'Keep N most recent versions (prune mode only)'
+      },
+      confirmTruncate: {
+        type: 'boolean',
+        required: false,
+        default: false,
+        description: 'REQUIRED: Must be true to truncate all versions (truncate mode only)'
+      }
+    },
+    returns: `Response varies by mode:
+
+**list mode:**
+- versions: Array of version objects with id, workflowId, snapshotSize, createdAt
+- totalCount: Total number of versions
+
+**get mode:**
+- version: Complete version object including workflow snapshot
+
+**rollback mode:**
+- success: Boolean indicating success
+- restoredVersion: The version that was restored
+- backupVersionId: ID of the backup created before rollback
+
+**delete mode:**
+- deletedCount: Number of versions deleted
+
+**prune mode:**
+- prunedCount: Number of old versions removed
+- remainingCount: Number of versions kept
+
+**truncate mode:**
+- deletedCount: Total versions deleted across all workflows`,
+    examples: [
+      '// List version history\nn8n_workflow_versions({mode: "list", workflowId: "abc123", limit: 5})',
+      '// Get specific version details\nn8n_workflow_versions({mode: "get", versionId: 42})',
+      '// Rollback to latest saved version\nn8n_workflow_versions({mode: "rollback", workflowId: "abc123"})',
+      '// Rollback to specific version\nn8n_workflow_versions({mode: "rollback", workflowId: "abc123", versionId: 42})',
+      '// Delete specific version\nn8n_workflow_versions({mode: "delete", workflowId: "abc123", versionId: 42})',
+      '// Delete all versions for workflow\nn8n_workflow_versions({mode: "delete", workflowId: "abc123", deleteAll: true})',
+      '// Prune to keep only 5 most recent\nn8n_workflow_versions({mode: "prune", workflowId: "abc123", maxVersions: 5})',
+      '// Truncate all versions (dangerous!)\nn8n_workflow_versions({mode: "truncate", confirmTruncate: true})'
+    ],
+    useCases: [
+      'Recover from accidental workflow changes',
+      'Compare workflow versions to understand changes',
+      'Maintain audit trail of workflow modifications',
+      'Clean up old versions to save database storage',
+      'Roll back failed workflow deployments'
+    ],
+    performance: `Performance varies by operation:
+- list: Fast (~100ms) - simple database query
+- get: Fast (~100ms) - single row retrieval
+- rollback: Moderate (~200-500ms) - includes backup creation and workflow update
+- delete: Fast (~50-100ms) - database delete operation
+- prune: Moderate (~100-300ms) - depends on number of versions to delete
+- truncate: Slow (1-5s) - deletes all records across all workflows`,
+    modeComparison: `| Mode | Required Params | Optional Params | Risk Level |
+|------|-----------------|-----------------|------------|
+| list | workflowId | limit | Low |
+| get | versionId | - | Low |
+| rollback | workflowId | versionId, validateBefore | Medium |
+| delete | workflowId | versionId, deleteAll | High |
+| prune | workflowId | maxVersions | Medium |
+| truncate | confirmTruncate=true | - | Critical |`,
+    bestPractices: [
+      'Always list versions before rollback to pick the right one',
+      'Enable validateBefore for rollback to catch structural issues',
+      'Use prune regularly to keep version history manageable',
+      'Never use truncate in production without explicit need',
+      'Document why you are rolling back for audit purposes'
+    ],
+    pitfalls: [
+      'Rollback overwrites current workflow - backup is created automatically',
+      'Deleted versions cannot be recovered',
+      'Truncate affects ALL workflows - use with extreme caution',
+      'Version IDs are sequential but may have gaps after deletes',
+      'Large workflows may have significant version storage overhead'
+    ],
+    relatedTools: [
+      'n8n_get_workflow - View current workflow state',
+      'n8n_update_partial_workflow - Make incremental changes',
+      'n8n_validate_workflow - Validate before deployment'
+    ]
+  }
+};

src/mcp/tools-documentation.ts

@@ -84,57 +84,67 @@ When working with Code nodes, always start by calling the relevant guide:
 
 ## Standard Workflow Pattern
 
-⚠️ **CRITICAL**: Always call get_node_essentials() FIRST before configuring any node!
+⚠️ **CRITICAL**: Always call get_node() with detail='standard' FIRST before configuring any node!
 
 1. **Find** the node you need:
    - search_nodes({query: "slack"}) - Search by keyword
-   - list_nodes({category: "communication"}) - List by category
-   - list_ai_tools() - List AI-capable nodes
+   - search_nodes({query: "communication"}) - Search by category name
+   - search_nodes({query: "AI langchain"}) - Search for AI-capable nodes
 
-2. **Configure** the node (ALWAYS START WITH ESSENTIALS):
-   - ✅ get_node_essentials("nodes-base.slack") - Get essential properties FIRST (5KB, shows required fields)
-   - get_node_info("nodes-base.slack") - Get complete schema only if essentials insufficient (100KB+)
-   - search_node_properties("nodes-base.slack", "auth") - Find specific properties
+2. **Configure** the node (ALWAYS START WITH STANDARD DETAIL):
+   - ✅ get_node({nodeType: "nodes-base.slack", detail: "standard"}) - Get essential properties FIRST (~1-2KB, shows required fields)
+   - get_node({nodeType: "nodes-base.slack", detail: "full"}) - Get complete schema only if standard insufficient (~100KB+)
+   - get_node({nodeType: "nodes-base.slack", mode: "docs"}) - Get readable markdown documentation
+   - get_node({nodeType: "nodes-base.slack", mode: "search_properties", propertyQuery: "auth"}) - Find specific properties
 
 3. **Validate** before deployment:
-   - validate_node_minimal("nodes-base.slack", config) - Check required fields
-   - validate_node_operation("nodes-base.slack", config) - Full validation with fixes
-   - validate_workflow(workflow) - Validate entire workflow
+   - validate_node({nodeType: "nodes-base.slack", config: {...}, mode: "minimal"}) - Quick required fields check
+   - validate_node({nodeType: "nodes-base.slack", config: {...}}) - Full validation with errors/warnings/suggestions
+   - validate_workflow({workflow: {...}}) - Validate entire workflow
 
-## Tool Categories
+## Tool Categories (19 Tools Total)
 
-**Discovery Tools**
-- search_nodes - Full-text search across all nodes
-- list_nodes - List nodes with filtering by category, package, or type
-- list_ai_tools - List all AI-capable nodes with usage guidance
+**Discovery Tools** (1 tool)
+- search_nodes - Full-text search across all nodes (supports OR, AND, FUZZY modes)
 
-**Configuration Tools**
-- get_node_essentials - ✅ CALL THIS FIRST! Returns 10-20 key properties with examples and required fields
-- get_node_info - Returns complete node schema (only use if essentials is insufficient)
-- search_node_properties - Search for specific properties within a node
-- get_property_dependencies - Analyze property visibility dependencies
+**Configuration Tools** (1 consolidated tool)
+- get_node - Unified node information tool:
+  - detail='minimal'/'standard'/'full': Progressive detail levels
+  - mode='docs': Readable markdown documentation
+  - mode='search_properties': Find specific properties
+  - mode='versions'/'compare'/'breaking'/'migrations': Version management
 
-**Validation Tools**
-- validate_node_minimal - Quick validation of required fields only
-- validate_node_operation - Full validation with operation awareness
-- validate_workflow - Complete workflow validation including connections
+**Validation Tools** (2 tools)
+- validate_node - Unified validation with mode='full' or mode='minimal'
+- validate_workflow - Complete workflow validation (nodes, connections, expressions)
 
-**Template Tools**
-- list_tasks - List common task templates
-- get_node_for_task - Get pre-configured node for specific tasks
-- search_templates - Search workflow templates by keyword
+**Template Tools** (2 tools)
 - get_template - Get complete workflow JSON by ID
+- search_templates - Unified template search:
+  - searchMode='keyword': Text search (default)
+  - searchMode='by_nodes': Find templates using specific nodes
+  - searchMode='by_task': Curated task-based templates
+  - searchMode='by_metadata': Filter by complexity/services
 
-**n8n API Tools** (requires N8N_API_URL configuration)
+**n8n API Tools** (13 tools, requires N8N_API_URL configuration)
 - n8n_create_workflow - Create new workflows
-- n8n_update_partial_workflow - Update workflows using diff operations
-- n8n_validate_workflow - Validate workflow from n8n instance
-- n8n_trigger_webhook_workflow - Trigger workflow execution
+- n8n_get_workflow - Get workflow with mode='full'/'details'/'structure'/'minimal'
+- n8n_update_full_workflow - Full workflow replacement
+- n8n_update_partial_workflow - Incremental diff-based updates
+- n8n_delete_workflow - Delete workflow
+- n8n_list_workflows - List workflows with filters
+- n8n_validate_workflow - Validate workflow by ID
+- n8n_autofix_workflow - Auto-fix common issues
+- n8n_trigger_webhook_workflow - Trigger via webhook
+- n8n_executions - Unified execution management (action='get'/'list'/'delete')
+- n8n_health_check - Check n8n API connectivity
+- n8n_workflow_versions - Version history and rollback
+- n8n_deploy_template - Deploy templates directly to n8n instance
 
 ## Performance Characteristics
-- Instant (<10ms): search_nodes, list_nodes, get_node_essentials
-- Fast (<100ms): validate_node_minimal, get_node_for_task
-- Moderate (100-500ms): validate_workflow, get_node_info
+- Instant (<10ms): search_nodes, get_node (minimal/standard)
+- Fast (<100ms): validate_node, get_template
+- Moderate (100-500ms): validate_workflow, get_node (full detail)
 - Network-dependent: All n8n_* tools
 
 For comprehensive documentation on any tool:
@@ -167,7 +177,7 @@ ${tools.map(toolName => {
 
 ## Usage Notes
 - All node types require the "nodes-base." or "nodes-langchain." prefix
-- Use get_node_essentials() first for most tasks (95% smaller than get_node_info)
+- Use get_node() with detail='standard' first for most tasks (~95% smaller than detail='full')
 - Validation profiles: minimal (editing), runtime (default), strict (deployment)
 - n8n API tools only available when N8N_API_URL and N8N_API_KEY are configured
 
@@ -413,8 +423,8 @@ try {
 5. Use descriptive variable names
 
 ## Related Tools
-- get_node_essentials("nodes-base.code")
-- validate_node_operation()
+- get_node({nodeType: "nodes-base.code"}) - Get Code node configuration details
+- validate_node({nodeType: "nodes-base.code", config: {...}}) - Validate Code node setup
 - python_code_node_guide (for Python syntax)`;
 }
 
@@ -682,7 +692,7 @@ except json.JSONDecodeError:
 \`\`\`
 
 ## Related Tools
-- get_node_essentials("nodes-base.code")
-- validate_node_operation()
+- get_node({nodeType: "nodes-base.code"}) - Get Code node configuration details
+- validate_node({nodeType: "nodes-base.code", config: {...}}) - Validate Code node setup
 - javascript_code_node_guide (for JavaScript syntax)`;
 }

src/mcp/tools-n8n-friendly.ts

@@ -13,25 +13,18 @@ export const n8nFriendlyDescriptions: Record<string, {
   description: string;
   params: Record<string, string>;
 }> = {
-  // Validation tools - most prone to errors
-  validate_node_operation: {
-    description: 'Validate n8n node. ALWAYS pass two parameters: nodeType (string) and config (object). Example call: {"nodeType": "nodes-base.slack", "config": {"resource": "channel", "operation": "create"}}',
+  // Consolidated validation tool (replaces validate_node_operation and validate_node_minimal)
+  validate_node: {
+    description: 'Validate n8n node config. Pass nodeType (string) and config (object). Use mode="full" for comprehensive validation, mode="minimal" for quick check. Example: {"nodeType": "nodes-base.slack", "config": {"resource": "channel", "operation": "create"}}',
     params: {
       nodeType: 'String value like "nodes-base.slack"',
       config: 'Object value like {"resource": "channel", "operation": "create"} or empty object {}',
+      mode: 'Optional string: "full" (default) or "minimal"',
       profile: 'Optional string: "minimal" or "runtime" or "ai-friendly" or "strict"'
     }
   },
-  
-  validate_node_minimal: {
-    description: 'Check required fields. MUST pass: nodeType (string) and config (object). Example: {"nodeType": "nodes-base.webhook", "config": {}}',
-    params: {
-      nodeType: 'String like "nodes-base.webhook"',
-      config: 'Object, use {} for empty'
-    }
-  },
-  
-  // Search and info tools
+
+  // Search tool
   search_nodes: {
     description: 'Search nodes. Pass query (string). Example: {"query": "webhook"}',
     params: {
@@ -39,98 +32,53 @@ export const n8nFriendlyDescriptions: Record<string, {
       limit: 'Optional number, default 20'
     }
   },
-  
-  get_node_info: {
-    description: 'Get node details. Pass nodeType (string). Example: {"nodeType": "nodes-base.httpRequest"}',
+
+  // Consolidated node info tool (replaces get_node_info, get_node_essentials, get_node_documentation, search_node_properties)
+  get_node: {
+    description: 'Get node info with multiple modes. Pass nodeType (string). Use mode="info" for config, mode="docs" for documentation, mode="search_properties" with propertyQuery for finding fields. Example: {"nodeType": "nodes-base.httpRequest", "detail": "standard"}',
     params: {
-      nodeType: 'String with prefix like "nodes-base.httpRequest"'
+      nodeType: 'String with prefix like "nodes-base.httpRequest"',
+      mode: 'Optional string: "info" (default), "docs", "search_properties", "versions", "compare", "breaking", "migrations"',
+      detail: 'Optional string: "minimal", "standard" (default), "full"',
+      propertyQuery: 'For mode="search_properties": search term like "auth"'
     }
   },
-  
-  get_node_essentials: {
-    description: 'Get node basics. Pass nodeType (string). Example: {"nodeType": "nodes-base.slack"}',
-    params: {
-      nodeType: 'String with prefix like "nodes-base.slack"'
-    }
-  },
-  
-  // Task tools
-  get_node_for_task: {
-    description: 'Find node for task. Pass task (string). Example: {"task": "send_http_request"}',
-    params: {
-      task: 'String task name like "send_http_request"'
-    }
-  },
-  
-  list_tasks: {
-    description: 'List tasks by category. Pass category (string). Example: {"category": "HTTP/API"}',
-    params: {
-      category: 'String: "HTTP/API" or "Webhooks" or "Database" or "AI/LangChain" or "Data Processing" or "Communication"'
-    }
-  },
-  
+
   // Workflow validation
   validate_workflow: {
-    description: 'Validate workflow. Pass workflow object. MUST have: {"workflow": {"nodes": [array of node objects], "connections": {object with node connections}}}. Each node needs: name, type, typeVersion, position.',
+    description: 'Validate workflow structure, connections, and expressions. Pass workflow object. MUST have: {"workflow": {"nodes": [array of node objects], "connections": {object with node connections}}}. Each node needs: name, type, typeVersion, position.',
     params: {
       workflow: 'Object with two required fields: nodes (array) and connections (object). Example: {"nodes": [{"name": "Webhook", "type": "n8n-nodes-base.webhook", "typeVersion": 2, "position": [250, 300], "parameters": {}}], "connections": {}}',
-      options: 'Optional object. Example: {"validateNodes": true, "profile": "runtime"}'
+      options: 'Optional object. Example: {"validateNodes": true, "validateConnections": true, "validateExpressions": true, "profile": "runtime"}'
     }
   },
-  
-  validate_workflow_connections: {
-    description: 'Validate workflow connections only. Pass workflow object. Example: {"workflow": {"nodes": [...], "connections": {}}}',
-    params: {
-      workflow: 'Object with nodes array and connections object. Minimal example: {"nodes": [{"name": "Webhook"}], "connections": {}}'
-    }
-  },
-  
-  validate_workflow_expressions: {
-    description: 'Validate n8n expressions in workflow. Pass workflow object. Example: {"workflow": {"nodes": [...], "connections": {}}}',
-    params: {
-      workflow: 'Object with nodes array and connections object containing n8n expressions like {{ $json.data }}'
-    }
-  },
-  
-  // Property tools
-  get_property_dependencies: {
-    description: 'Get field dependencies. Pass nodeType (string) and optional config (object). Example: {"nodeType": "nodes-base.httpRequest", "config": {}}',
-    params: {
-      nodeType: 'String like "nodes-base.httpRequest"',
-      config: 'Optional object, use {} for empty'
-    }
-  },
-  
-  // AI tool info
-  get_node_as_tool_info: {
-    description: 'Get AI tool usage. Pass nodeType (string). Example: {"nodeType": "nodes-base.slack"}',
-    params: {
-      nodeType: 'String with prefix like "nodes-base.slack"'
-    }
-  },
-  
-  // Template tools
+
+  // Consolidated template search (replaces search_templates, list_node_templates, search_templates_by_metadata, get_templates_for_task)
   search_templates: {
-    description: 'Search workflow templates. Pass query (string). Example: {"query": "chatbot"}',
+    description: 'Search workflow templates with multiple modes. Use searchMode="keyword" for text search, searchMode="by_nodes" to find by node types, searchMode="by_task" for task-based templates, searchMode="by_metadata" for filtering. Example: {"query": "chatbot"} or {"searchMode": "by_task", "task": "webhook_processing"}',
     params: {
-      query: 'String keyword like "chatbot" or "webhook"',
+      query: 'For searchMode="keyword": string keyword like "chatbot"',
+      searchMode: 'Optional: "keyword" (default), "by_nodes", "by_task", "by_metadata"',
+      nodeTypes: 'For searchMode="by_nodes": array like ["n8n-nodes-base.httpRequest"]',
+      task: 'For searchMode="by_task": task like "webhook_processing", "ai_automation"',
       limit: 'Optional number, default 20'
     }
   },
-  
+
   get_template: {
     description: 'Get template by ID. Pass templateId (number). Example: {"templateId": 1234}',
     params: {
-      templateId: 'Number ID like 1234'
+      templateId: 'Number ID like 1234',
+      mode: 'Optional: "full" (default), "nodes_only", "structure"'
     }
   },
-  
+
   // Documentation tool
   tools_documentation: {
     description: 'Get tool docs. Pass optional depth (string). Example: {"depth": "essentials"} or {}',
     params: {
-      depth: 'Optional string: "essentials" or "overview" or "detailed"',
-      topic: 'Optional string topic name'
+      depth: 'Optional string: "essentials" (default) or "full"',
+      topic: 'Optional string tool name like "search_nodes"'
     }
   }
 };

src/mcp/tools-n8n-manager.ts

@@ -70,55 +70,19 @@ export const n8nManagementTools: ToolDefinition[] = [
   },
   {
     name: 'n8n_get_workflow',
-    description: `Get a workflow by ID. Returns the complete workflow including nodes, connections, and settings.`,
+    description: `Get workflow by ID with different detail levels. Use mode='full' for complete workflow, 'details' for metadata+stats, 'structure' for nodes/connections only, 'minimal' for id/name/active/tags.`,
     inputSchema: {
       type: 'object',
       properties: {
-        id: { 
-          type: 'string', 
-          description: 'Workflow ID' 
-        }
-      },
-      required: ['id']
-    }
-  },
-  {
-    name: 'n8n_get_workflow_details',
-    description: `Get workflow details with metadata, version, execution stats. More info than get_workflow.`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        id: { 
-          type: 'string', 
-          description: 'Workflow ID' 
-        }
-      },
-      required: ['id']
-    }
-  },
-  {
-    name: 'n8n_get_workflow_structure',
-    description: `Get workflow structure: nodes and connections only. No parameter details.`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        id: { 
-          type: 'string', 
-          description: 'Workflow ID' 
-        }
-      },
-      required: ['id']
-    }
-  },
-  {
-    name: 'n8n_get_workflow_minimal',
-    description: `Get minimal info: ID, name, active status, tags. Fast for listings.`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        id: { 
-          type: 'string', 
-          description: 'Workflow ID' 
+        id: {
+          type: 'string',
+          description: 'Workflow ID'
+        },
+        mode: {
+          type: 'string',
+          enum: ['full', 'details', 'structure', 'minimal'],
+          default: 'full',
+          description: 'Detail level: full=complete workflow, details=full+execution stats, structure=nodes/connections topology, minimal=metadata only'
         }
       },
       required: ['id']
@@ -343,122 +307,87 @@ export const n8nManagementTools: ToolDefinition[] = [
     }
   },
   {
-    name: 'n8n_get_execution',
-    description: `Get execution details with smart filtering. RECOMMENDED: Use mode='preview' first to assess data size.
-Examples:
-- {id, mode:'preview'} - Structure & counts (fast, no data)
-- {id, mode:'summary'} - 2 samples per node (default)
-- {id, mode:'filtered', itemsLimit:5} - 5 items per node
-- {id, nodeNames:['HTTP Request']} - Specific node only
-- {id, mode:'full'} - Complete data (use with caution)`,
+    name: 'n8n_executions',
+    description: `Manage workflow executions: get details, list, or delete. Use action='get' with id for execution details, action='list' for listing executions, action='delete' to remove execution record.`,
     inputSchema: {
       type: 'object',
       properties: {
+        action: {
+          type: 'string',
+          enum: ['get', 'list', 'delete'],
+          description: 'Operation: get=get execution details, list=list executions, delete=delete execution'
+        },
+        // For action='get' and action='delete'
         id: {
           type: 'string',
-          description: 'Execution ID'
+          description: 'Execution ID (required for action=get or action=delete)'
         },
+        // For action='get' - detail level
         mode: {
           type: 'string',
           enum: ['preview', 'summary', 'filtered', 'full'],
-          description: 'Data retrieval mode: preview=structure only, summary=2 items, filtered=custom, full=all data'
+          description: 'For action=get: preview=structure only, summary=2 items (default), filtered=custom, full=all data'
         },
         nodeNames: {
           type: 'array',
           items: { type: 'string' },
-          description: 'Filter to specific nodes by name (for filtered mode)'
+          description: 'For action=get with mode=filtered: filter to specific nodes by name'
         },
         itemsLimit: {
           type: 'number',
-          description: 'Items per node: 0=structure only, 2=default, -1=unlimited (for filtered mode)'
+          description: 'For action=get with mode=filtered: items per node (0=structure, 2=default, -1=unlimited)'
         },
         includeInputData: {
           type: 'boolean',
-          description: 'Include input data in addition to output (default: false)'
+          description: 'For action=get: include input data in addition to output (default: false)'
+        },
+        // For action='list'
+        limit: {
+          type: 'number',
+          description: 'For action=list: number of executions to return (1-100, default: 100)'
+        },
+        cursor: {
+          type: 'string',
+          description: 'For action=list: pagination cursor from previous response'
+        },
+        workflowId: {
+          type: 'string',
+          description: 'For action=list: filter by workflow ID'
+        },
+        projectId: {
+          type: 'string',
+          description: 'For action=list: filter by project ID (enterprise feature)'
+        },
+        status: {
+          type: 'string',
+          enum: ['success', 'error', 'waiting'],
+          description: 'For action=list: filter by execution status'
         },
         includeData: {
           type: 'boolean',
-          description: 'Legacy: Include execution data. Maps to mode=summary if true (deprecated, use mode instead)'
+          description: 'For action=list: include execution data (default: false)'
         }
       },
-      required: ['id']
-    }
-  },
-  {
-    name: 'n8n_list_executions',
-    description: `List workflow executions (returns up to limit). Check hasMore/nextCursor for pagination.`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        limit: { 
-          type: 'number', 
-          description: 'Number of executions to return (1-100, default: 100)' 
-        },
-        cursor: { 
-          type: 'string', 
-          description: 'Pagination cursor from previous response' 
-        },
-        workflowId: { 
-          type: 'string', 
-          description: 'Filter by workflow ID' 
-        },
-        projectId: { 
-          type: 'string', 
-          description: 'Filter by project ID (enterprise feature)' 
-        },
-        status: { 
-          type: 'string', 
-          enum: ['success', 'error', 'waiting'],
-          description: 'Filter by execution status' 
-        },
-        includeData: { 
-          type: 'boolean', 
-          description: 'Include execution data (default: false)' 
-        }
-      }
-    }
-  },
-  {
-    name: 'n8n_delete_execution',
-    description: `Delete an execution record. This only removes the execution history, not any data processed.`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        id: { 
-          type: 'string', 
-          description: 'Execution ID to delete' 
-        }
-      },
-      required: ['id']
+      required: ['action']
     }
   },
 
   // System Tools
   {
     name: 'n8n_health_check',
-    description: `Check n8n instance health and API connectivity. Returns status and available features.`,
-    inputSchema: {
-      type: 'object',
-      properties: {}
-    }
-  },
-  {
-    name: 'n8n_list_available_tools',
-    description: `List available n8n tools and capabilities.`,
-    inputSchema: {
-      type: 'object',
-      properties: {}
-    }
-  },
-  {
-    name: 'n8n_diagnostic',
-    description: `Diagnose n8n API config. Shows tool status, API connectivity, env vars. Helps troubleshoot missing tools.`,
+    description: `Check n8n instance health and API connectivity. Use mode='diagnostic' for detailed troubleshooting with env vars and tool status.`,
     inputSchema: {
       type: 'object',
       properties: {
+        mode: {
+          type: 'string',
+          enum: ['status', 'diagnostic'],
+          description: 'Mode: "status" (default) for quick health check, "diagnostic" for detailed debug info including env vars and tool status',
+          default: 'status'
+        },
         verbose: {
           type: 'boolean',
-          description: 'Include detailed debug information (default: false)'
+          description: 'Include extra details in diagnostic mode (default: false)'
         }
       }
     }
@@ -516,5 +445,40 @@ Examples:
       },
       required: ['mode']
     }
+  },
+
+  // Template Deployment Tool
+  {
+    name: 'n8n_deploy_template',
+    description: `Deploy a workflow template from n8n.io directly to your n8n instance. Fetches template, optionally upgrades node versions and validates, then creates workflow. Returns workflow ID and required credentials list.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        templateId: {
+          type: 'number',
+          description: 'Template ID from n8n.io (required)'
+        },
+        name: {
+          type: 'string',
+          description: 'Custom workflow name (default: template name)'
+        },
+        autoUpgradeVersions: {
+          type: 'boolean',
+          default: true,
+          description: 'Automatically upgrade node typeVersions to latest supported (default: true)'
+        },
+        validate: {
+          type: 'boolean',
+          default: true,
+          description: 'Validate workflow before deployment (default: true)'
+        },
+        stripCredentials: {
+          type: 'boolean',
+          default: true,
+          description: 'Remove credential references from nodes - user configures in n8n UI (default: true)'
+        }
+      },
+      required: ['templateId']
+    }
   }
 ];

src/mcp/tools.ts

@@ -26,51 +26,6 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
       },
     },
   },
-  {
-    name: 'list_nodes',
-    description: `List n8n nodes. Common: list_nodes({limit:200}) for all, list_nodes({category:'trigger'}) for triggers. Package: "n8n-nodes-base" or "@n8n/n8n-nodes-langchain". Categories: trigger/transform/output/input.`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        package: {
-          type: 'string',
-          description: '"n8n-nodes-base" (core) or "@n8n/n8n-nodes-langchain" (AI)',
-        },
-        category: {
-          type: 'string',
-          description: 'trigger|transform|output|input|AI',
-        },
-        developmentStyle: {
-          type: 'string',
-          enum: ['declarative', 'programmatic'],
-          description: 'Usually "programmatic"',
-        },
-        isAITool: {
-          type: 'boolean',
-          description: 'Filter AI-capable nodes',
-        },
-        limit: {
-          type: 'number',
-          description: 'Max results (default 50, use 200+ for all)',
-          default: 50,
-        },
-      },
-    },
-  },
-  {
-    name: 'get_node_info',
-    description: `Get full node documentation. Pass nodeType as string with prefix. Example: nodeType="nodes-base.webhook"`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        nodeType: {
-          type: 'string',
-          description: 'Full type: "nodes-base.{name}" or "nodes-langchain.{name}". Examples: nodes-base.httpRequest, nodes-base.webhook, nodes-base.slack',
-        },
-      },
-      required: ['nodeType'],
-    },
-  },
   {
     name: 'search_nodes',
     description: `Search n8n nodes by keyword with optional real-world examples. Pass query as string. Example: query="webhook" or query="database". Returns max 20 results. Use includeExamples=true to get top 2 template configs per node.`,
@@ -102,93 +57,61 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
     },
   },
   {
-    name: 'list_ai_tools',
-    description: `List 263 AI-optimized nodes. Note: ANY node can be AI tool! Connect any node to AI Agent's tool port. Community nodes need N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true.`,
-    inputSchema: {
-      type: 'object',
-      properties: {},
-    },
-  },
-  {
-    name: 'get_node_documentation',
-    description: `Get readable docs with examples/auth/patterns. Better than raw schema! 87% coverage. Format: "nodes-base.slack"`,
+    name: 'get_node',
+    description: `Get node info with progressive detail levels and multiple modes. Detail: minimal (~200 tokens), standard (~1-2K, default), full (~3-8K). Modes: info (default), docs (markdown documentation), search_properties (find properties), versions/compare/breaking/migrations (version info). Use format='docs' for readable documentation, mode='search_properties' with propertyQuery for finding specific fields.`,
     inputSchema: {
       type: 'object',
       properties: {
         nodeType: {
           type: 'string',
-          description: 'Full type with prefix: "nodes-base.slack"',
+          description: 'Full node type: "nodes-base.httpRequest" or "nodes-langchain.agent"',
         },
-      },
-      required: ['nodeType'],
-    },
-  },
-  {
-    name: 'get_database_statistics',
-    description: `Node stats: 525 total, 263 AI tools, 104 triggers, 87% docs coverage. Verifies MCP working.`,
-    inputSchema: {
-      type: 'object',
-      properties: {},
-    },
-  },
-  {
-    name: 'get_node_essentials',
-    description: `Get node essential info with optional real-world examples from templates. Pass nodeType as string with prefix. Example: nodeType="nodes-base.slack". Use includeExamples=true to get top 3 template configs.`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        nodeType: {
+        detail: {
           type: 'string',
-          description: 'Full type: "nodes-base.httpRequest"',
+          enum: ['minimal', 'standard', 'full'],
+          default: 'standard',
+          description: 'Information detail level. standard=essential properties (recommended), full=everything',
+        },
+        mode: {
+          type: 'string',
+          enum: ['info', 'docs', 'search_properties', 'versions', 'compare', 'breaking', 'migrations'],
+          default: 'info',
+          description: 'Operation mode. info=node schema, docs=readable markdown documentation, search_properties=find specific properties, versions/compare/breaking/migrations=version info',
+        },
+        includeTypeInfo: {
+          type: 'boolean',
+          default: false,
+          description: 'Include type structure metadata (type category, JS type, validation rules). Only applies to mode=info. Adds ~80-120 tokens per property.',
         },
         includeExamples: {
           type: 'boolean',
-          description: 'Include top 3 real-world configuration examples from popular templates (default: false)',
           default: false,
+          description: 'Include real-world configuration examples from templates. Only applies to mode=info with detail=standard. Adds ~200-400 tokens per example.',
+        },
+        fromVersion: {
+          type: 'string',
+          description: 'Source version for compare/breaking/migrations modes (e.g., "1.0")',
+        },
+        toVersion: {
+          type: 'string',
+          description: 'Target version for compare mode (e.g., "2.0"). Defaults to latest if omitted.',
+        },
+        propertyQuery: {
+          type: 'string',
+          description: 'For mode=search_properties: search term to find properties (e.g., "auth", "header", "body")',
+        },
+        maxPropertyResults: {
+          type: 'number',
+          description: 'For mode=search_properties: max results (default 20)',
+          default: 20,
         },
       },
       required: ['nodeType'],
     },
   },
   {
-    name: 'search_node_properties',
-    description: `Find specific properties in a node (auth, headers, body, etc). Returns paths and descriptions.`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        nodeType: {
-          type: 'string',
-          description: 'Full type with prefix',
-        },
-        query: {
-          type: 'string',
-          description: 'Property to find: "auth", "header", "body", "json"',
-        },
-        maxResults: {
-          type: 'number',
-          description: 'Max results (default 20)',
-          default: 20,
-        },
-      },
-      required: ['nodeType', 'query'],
-    },
-  },
-  {
-    name: 'list_tasks',
-    description: `List task templates by category: HTTP/API, Webhooks, Database, AI, Data Processing, Communication.`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        category: {
-          type: 'string',
-          description: 'Filter by category (optional)',
-        },
-      },
-    },
-  },
-  {
-    name: 'validate_node_operation',
-    description: `Validate n8n node configuration. Pass nodeType as string and config as object. Example: nodeType="nodes-base.slack", config={resource:"channel",operation:"create"}`,
+    name: 'validate_node',
+    description: `Validate n8n node configuration. Use mode='full' for comprehensive validation with errors/warnings/suggestions, mode='minimal' for quick required fields check. Example: nodeType="nodes-base.slack", config={resource:"channel",operation:"create"}`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -200,10 +123,16 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
           type: 'object',
           description: 'Configuration as object. For simple nodes use {}. For complex nodes include fields like {resource:"channel",operation:"create"}',
         },
+        mode: {
+          type: 'string',
+          enum: ['full', 'minimal'],
+          description: 'Validation mode. full=comprehensive validation with errors/warnings/suggestions, minimal=quick required fields check only. Default is "full"',
+          default: 'full',
+        },
         profile: {
           type: 'string',
           enum: ['strict', 'runtime', 'ai-friendly', 'minimal'],
-          description: 'Profile string: "minimal", "runtime", "ai-friendly", or "strict". Default is "ai-friendly"',
+          description: 'Profile for mode=full: "minimal", "runtime", "ai-friendly", or "strict". Default is "ai-friendly"',
           default: 'ai-friendly',
         },
       },
@@ -242,6 +171,11 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
           }
         },
         suggestions: { type: 'array', items: { type: 'string' } },
+        missingRequiredFields: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Only present in mode=minimal'
+        },
         summary: {
           type: 'object',
           properties: {
@@ -252,132 +186,7 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
           }
         }
       },
-      required: ['nodeType', 'displayName', 'valid', 'errors', 'warnings', 'suggestions', 'summary']
-    },
-  },
-  {
-    name: 'validate_node_minimal',
-    description: `Check n8n node required fields. Pass nodeType as string and config as empty object {}. Example: nodeType="nodes-base.webhook", config={}`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        nodeType: {
-          type: 'string',
-          description: 'Node type as string. Example: "nodes-base.slack"',
-        },
-        config: {
-          type: 'object',
-          description: 'Configuration object. Always pass {} for empty config',
-        },
-      },
-      required: ['nodeType', 'config'],
-      additionalProperties: false,
-    },
-    outputSchema: {
-      type: 'object',
-      properties: {
-        nodeType: { type: 'string' },
-        displayName: { type: 'string' },
-        valid: { type: 'boolean' },
-        missingRequiredFields: {
-          type: 'array',
-          items: { type: 'string' }
-        }
-      },
-      required: ['nodeType', 'displayName', 'valid', 'missingRequiredFields']
-    },
-  },
-  {
-    name: 'get_property_dependencies',
-    description: `Shows property dependencies and visibility rules. Example: sendBody=true reveals body fields. Test visibility with optional config.`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        nodeType: {
-          type: 'string',
-          description: 'The node type to analyze (e.g., "nodes-base.httpRequest")',
-        },
-        config: {
-          type: 'object',
-          description: 'Optional partial configuration to check visibility impact',
-        },
-      },
-      required: ['nodeType'],
-    },
-  },
-  {
-    name: 'get_node_as_tool_info',
-    description: `How to use ANY node as AI tool. Shows requirements, use cases, examples. Works for all nodes, not just AI-marked ones.`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        nodeType: {
-          type: 'string',
-          description: 'Full node type WITH prefix: "nodes-base.slack", "nodes-base.googleSheets", etc.',
-        },
-      },
-      required: ['nodeType'],
-    },
-  },
-  {
-    name: 'list_templates',
-    description: `List all templates with minimal data (id, name, description, views, node count). Optionally include AI-generated metadata for smart filtering.`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        limit: {
-          type: 'number',
-          description: 'Number of results (1-100). Default 10.',
-          default: 10,
-          minimum: 1,
-          maximum: 100,
-        },
-        offset: {
-          type: 'number',
-          description: 'Pagination offset. Default 0.',
-          default: 0,
-          minimum: 0,
-        },
-        sortBy: {
-          type: 'string',
-          enum: ['views', 'created_at', 'name'],
-          description: 'Sort field. Default: views (popularity).',
-          default: 'views',
-        },
-        includeMetadata: {
-          type: 'boolean',
-          description: 'Include AI-generated metadata (categories, complexity, setup time, etc.). Default false.',
-          default: false,
-        },
-      },
-    },
-  },
-  {
-    name: 'list_node_templates',
-    description: `Find templates using specific nodes. Returns paginated results. Use FULL types: "n8n-nodes-base.httpRequest".`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        nodeTypes: {
-          type: 'array',
-          items: { type: 'string' },
-          description: 'Array of node types to search for (e.g., ["n8n-nodes-base.httpRequest", "n8n-nodes-base.openAi"])',
-        },
-        limit: {
-          type: 'number',
-          description: 'Maximum number of templates to return. Default 10.',
-          default: 10,
-          minimum: 1,
-          maximum: 100,
-        },
-        offset: {
-          type: 'number',
-          description: 'Pagination offset. Default 0.',
-          default: 0,
-          minimum: 0,
-        },
-      },
-      required: ['nodeTypes'],
+      required: ['nodeType', 'displayName', 'valid']
     },
   },
   {
@@ -402,13 +211,20 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
   },
   {
     name: 'search_templates',
-    description: `Search templates by name/description keywords. Returns paginated results. NOT for node types! For nodes use list_node_templates.`,
+    description: `Search templates with multiple modes. Use searchMode='keyword' for text search, 'by_nodes' to find templates using specific nodes, 'by_task' for curated task-based templates, 'by_metadata' for filtering by complexity/setup time/services.`,
     inputSchema: {
       type: 'object',
       properties: {
+        searchMode: {
+          type: 'string',
+          enum: ['keyword', 'by_nodes', 'by_task', 'by_metadata'],
+          description: 'Search mode. keyword=text search (default), by_nodes=find by node types, by_task=curated task templates, by_metadata=filter by complexity/services',
+          default: 'keyword',
+        },
+        // For searchMode='keyword'
         query: {
           type: 'string',
-          description: 'Search keyword as string. Example: "chatbot"',
+          description: 'For searchMode=keyword: search keyword (e.g., "chatbot")',
         },
         fields: {
           type: 'array',
@@ -416,36 +232,20 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
             type: 'string',
             enum: ['id', 'name', 'description', 'author', 'nodes', 'views', 'created', 'url', 'metadata'],
           },
-          description: 'Fields to include in response. Default: all fields. Example: ["id", "name"] for minimal response.',
+          description: 'For searchMode=keyword: fields to include in response. Default: all fields.',
         },
-        limit: {
-          type: 'number',
-          description: 'Maximum number of results. Default 20.',
-          default: 20,
-          minimum: 1,
-          maximum: 100,
+        // For searchMode='by_nodes'
+        nodeTypes: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'For searchMode=by_nodes: array of node types (e.g., ["n8n-nodes-base.httpRequest", "n8n-nodes-base.slack"])',
         },
-        offset: {
-          type: 'number',
-          description: 'Pagination offset. Default 0.',
-          default: 0,
-          minimum: 0,
-        },
-      },
-      required: ['query'],
-    },
-  },
-  {
-    name: 'get_templates_for_task',
-    description: `Curated templates by task. Returns paginated results sorted by popularity.`,
-    inputSchema: {
-      type: 'object',
-      properties: {
+        // For searchMode='by_task'
         task: {
           type: 'string',
           enum: [
             'ai_automation',
-            'data_sync', 
+            'data_sync',
             'webhook_processing',
             'email_automation',
             'slack_integration',
@@ -455,60 +255,39 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
             'api_integration',
             'database_operations'
           ],
-          description: 'The type of task to get templates for',
+          description: 'For searchMode=by_task: the type of task',
         },
-        limit: {
-          type: 'number',
-          description: 'Maximum number of results. Default 10.',
-          default: 10,
-          minimum: 1,
-          maximum: 100,
-        },
-        offset: {
-          type: 'number',
-          description: 'Pagination offset. Default 0.',
-          default: 0,
-          minimum: 0,
-        },
-      },
-      required: ['task'],
-    },
-  },
-  {
-    name: 'search_templates_by_metadata',
-    description: `Search templates by AI-generated metadata. Filter by category, complexity, setup time, services, or audience. Returns rich metadata for smart template discovery.`,
-    inputSchema: {
-      type: 'object',
-      properties: {
+        // For searchMode='by_metadata'
         category: {
           type: 'string',
-          description: 'Filter by category (e.g., "automation", "integration", "data processing")',
+          description: 'For searchMode=by_metadata: filter by category (e.g., "automation", "integration")',
         },
         complexity: {
           type: 'string',
           enum: ['simple', 'medium', 'complex'],
-          description: 'Filter by complexity level',
+          description: 'For searchMode=by_metadata: filter by complexity level',
         },
         maxSetupMinutes: {
           type: 'number',
-          description: 'Maximum setup time in minutes',
+          description: 'For searchMode=by_metadata: maximum setup time in minutes',
           minimum: 5,
           maximum: 480,
         },
         minSetupMinutes: {
           type: 'number',
-          description: 'Minimum setup time in minutes',
+          description: 'For searchMode=by_metadata: minimum setup time in minutes',
           minimum: 5,
           maximum: 480,
         },
         requiredService: {
           type: 'string',
-          description: 'Filter by required service (e.g., "openai", "slack", "google")',
+          description: 'For searchMode=by_metadata: filter by required service (e.g., "openai", "slack")',
         },
         targetAudience: {
           type: 'string',
-          description: 'Filter by target audience (e.g., "developers", "marketers", "analysts")',
+          description: 'For searchMode=by_metadata: filter by target audience (e.g., "developers", "marketers")',
         },
+        // Common pagination
         limit: {
           type: 'number',
           description: 'Maximum number of results. Default 20.',
@@ -523,7 +302,6 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
           minimum: 0,
         },
       },
-      additionalProperties: false,
     },
   },
   {
@@ -611,143 +389,43 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
       required: ['valid', 'summary']
     },
   },
-  {
-    name: 'validate_workflow_connections',
-    description: `Check workflow connections only: valid nodes, no cycles, proper triggers, AI tool links. Fast structure validation.`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        workflow: {
-          type: 'object',
-          description: 'The workflow JSON with nodes array and connections object.',
-        },
-      },
-      required: ['workflow'],
-      additionalProperties: false,
-    },
-    outputSchema: {
-      type: 'object',
-      properties: {
-        valid: { type: 'boolean' },
-        statistics: {
-          type: 'object',
-          properties: {
-            totalNodes: { type: 'number' },
-            triggerNodes: { type: 'number' },
-            validConnections: { type: 'number' },
-            invalidConnections: { type: 'number' }
-          }
-        },
-        errors: {
-          type: 'array',
-          items: {
-            type: 'object',
-            properties: {
-              node: { type: 'string' },
-              message: { type: 'string' }
-            }
-          }
-        },
-        warnings: {
-          type: 'array',
-          items: {
-            type: 'object',
-            properties: {
-              node: { type: 'string' },
-              message: { type: 'string' }
-            }
-          }
-        }
-      },
-      required: ['valid', 'statistics']
-    },
-  },
-  {
-    name: 'validate_workflow_expressions',
-    description: `Validate n8n expressions: syntax {{}}, variables ($json/$node), references. Returns errors with locations.`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        workflow: {
-          type: 'object',
-          description: 'The workflow JSON to check for expression errors.',
-        },
-      },
-      required: ['workflow'],
-      additionalProperties: false,
-    },
-    outputSchema: {
-      type: 'object',
-      properties: {
-        valid: { type: 'boolean' },
-        statistics: {
-          type: 'object',
-          properties: {
-            totalNodes: { type: 'number' },
-            expressionsValidated: { type: 'number' }
-          }
-        },
-        errors: {
-          type: 'array',
-          items: {
-            type: 'object',
-            properties: {
-              node: { type: 'string' },
-              message: { type: 'string' }
-            }
-          }
-        },
-        warnings: {
-          type: 'array',
-          items: {
-            type: 'object',
-            properties: {
-              node: { type: 'string' },
-              message: { type: 'string' }
-            }
-          }
-        },
-        tips: { type: 'array', items: { type: 'string' } }
-      },
-      required: ['valid', 'statistics']
-    },
-  },
 ];
 
 /**
  * QUICK REFERENCE for AI Agents:
- * 
+ *
  * 1. RECOMMENDED WORKFLOW:
- *    - Start: search_nodes → get_node_essentials → get_node_for_task → validate_node_operation
- *    - Discovery: list_nodes({category:"trigger"}) for browsing categories
- *    - Quick Config: get_node_essentials("nodes-base.httpRequest") - only essential properties
- *    - Full Details: get_node_info only when essentials aren't enough
- *    - Validation: Use validate_node_operation for complex nodes (Slack, Google Sheets, etc.)
- * 
+ *    - Start: search_nodes → get_node → validate_node
+ *    - Discovery: search_nodes({query:"trigger"}) for finding nodes
+ *    - Quick Config: get_node("nodes-base.httpRequest", {detail:"standard"}) - only essential properties
+ *    - Documentation: get_node("nodes-base.httpRequest", {mode:"docs"}) - readable markdown docs
+ *    - Find Properties: get_node("nodes-base.httpRequest", {mode:"search_properties", propertyQuery:"auth"})
+ *    - Full Details: get_node with detail="full" only when standard isn't enough
+ *    - Validation: Use validate_node for complex nodes (Slack, Google Sheets, etc.)
+ *
  * 2. COMMON NODE TYPES:
  *    Triggers: webhook, schedule, emailReadImap, slackTrigger
  *    Core: httpRequest, code, set, if, merge, splitInBatches
  *    Integrations: slack, gmail, googleSheets, postgres, mongodb
  *    AI: agent, openAi, chainLlm, documentLoader
- * 
+ *
  * 3. SEARCH TIPS:
  *    - search_nodes returns ANY word match (OR logic)
  *    - Single words more precise, multiple words broader
- *    - If no results: use list_nodes with category filter
- * 
+ *    - If no results: try different keywords or partial names
+ *
  * 4. TEMPLATE SEARCHING:
  *    - search_templates("slack") searches template names/descriptions, NOT node types!
- *    - To find templates using Slack node: list_node_templates(["n8n-nodes-base.slack"])
- *    - For task-based templates: get_templates_for_task("slack_integration")
- *    - 399 templates available from the last year
- * 
+ *    - To find templates using Slack node: search_templates({searchMode:"by_nodes", nodeTypes:["n8n-nodes-base.slack"]})
+ *    - For task-based templates: search_templates({searchMode:"by_task", task:"slack_integration"})
+ *
  * 5. KNOWN ISSUES:
  *    - Some nodes have duplicate properties with different conditions
  *    - Package names: use 'n8n-nodes-base' not '@n8n/n8n-nodes-base'
  *    - Check showWhen/hideWhen to identify the right property variant
- * 
+ *
  * 6. PERFORMANCE:
- *    - get_node_essentials: Fast (<5KB)
- *    - get_node_info: Slow (100KB+) - use sparingly
- *    - search_nodes/list_nodes: Fast, cached
+ *    - get_node (detail=standard): Fast (<5KB)
+ *    - get_node (detail=full): Slow (100KB+) - use sparingly
+ *    - search_nodes: Fast, cached
  */

src/scripts/test-telemetry-mutations-verbose.ts

@@ -0,0 +1,151 @@
+/**
+ * Test telemetry mutations with enhanced logging
+ * Verifies that mutations are properly tracked and persisted
+ */
+
+import { telemetry } from '../telemetry/telemetry-manager.js';
+import { TelemetryConfigManager } from '../telemetry/config-manager.js';
+import { logger } from '../utils/logger.js';
+
+async function testMutations() {
+  console.log('Starting verbose telemetry mutation test...\n');
+
+  const configManager = TelemetryConfigManager.getInstance();
+  console.log('Telemetry config is enabled:', configManager.isEnabled());
+  console.log('Telemetry config file:', configManager['configPath']);
+
+  // Test data with valid workflow structure
+  const testMutation = {
+    sessionId: 'test_session_' + Date.now(),
+    toolName: 'n8n_update_partial_workflow',
+    userIntent: 'Add a Merge node for data consolidation',
+    operations: [
+      {
+        type: 'addNode',
+        nodeId: 'Merge1',
+        node: {
+          id: 'Merge1',
+          type: 'n8n-nodes-base.merge',
+          name: 'Merge',
+          position: [600, 200],
+          parameters: {}
+        }
+      },
+      {
+        type: 'addConnection',
+        source: 'previous_node',
+        target: 'Merge1'
+      }
+    ],
+    workflowBefore: {
+      id: 'test-workflow',
+      name: 'Test Workflow',
+      active: true,
+      nodes: [
+        {
+          id: 'previous_node',
+          type: 'n8n-nodes-base.manualTrigger',
+          name: 'When called',
+          position: [300, 200],
+          parameters: {}
+        }
+      ],
+      connections: {},
+      nodeIds: []
+    },
+    workflowAfter: {
+      id: 'test-workflow',
+      name: 'Test Workflow',
+      active: true,
+      nodes: [
+        {
+          id: 'previous_node',
+          type: 'n8n-nodes-base.manualTrigger',
+          name: 'When called',
+          position: [300, 200],
+          parameters: {}
+        },
+        {
+          id: 'Merge1',
+          type: 'n8n-nodes-base.merge',
+          name: 'Merge',
+          position: [600, 200],
+          parameters: {}
+        }
+      ],
+      connections: {
+        'previous_node': [
+          {
+            node: 'Merge1',
+            type: 'main',
+            index: 0,
+            source: 0,
+            destination: 0
+          }
+        ]
+      },
+      nodeIds: []
+    },
+    mutationSuccess: true,
+    durationMs: 125
+  };
+
+  console.log('\nTest Mutation Data:');
+  console.log('==================');
+  console.log(JSON.stringify({
+    intent: testMutation.userIntent,
+    tool: testMutation.toolName,
+    operationCount: testMutation.operations.length,
+    sessionId: testMutation.sessionId
+  }, null, 2));
+  console.log('\n');
+
+  // Call trackWorkflowMutation
+  console.log('Calling telemetry.trackWorkflowMutation...');
+  try {
+    await telemetry.trackWorkflowMutation(testMutation);
+    console.log('✓ trackWorkflowMutation completed successfully\n');
+  } catch (error) {
+    console.error('✗ trackWorkflowMutation failed:', error);
+    console.error('\n');
+  }
+
+  // Check queue size before flush
+  const metricsBeforeFlush = telemetry.getMetrics();
+  console.log('Metrics before flush:');
+  console.log('- mutationQueueSize:', metricsBeforeFlush.tracking.mutationQueueSize);
+  console.log('- eventsTracked:', metricsBeforeFlush.processing.eventsTracked);
+  console.log('- eventsFailed:', metricsBeforeFlush.processing.eventsFailed);
+  console.log('\n');
+
+  // Flush telemetry with 10-second wait for Supabase
+  console.log('Flushing telemetry (waiting 10 seconds for Supabase)...');
+  try {
+    await telemetry.flush();
+    console.log('✓ Telemetry flush completed\n');
+  } catch (error) {
+    console.error('✗ Flush failed:', error);
+    console.error('\n');
+  }
+
+  // Wait a bit for async operations
+  await new Promise(resolve => setTimeout(resolve, 2000));
+
+  // Get final metrics
+  const metricsAfterFlush = telemetry.getMetrics();
+  console.log('Metrics after flush:');
+  console.log('- mutationQueueSize:', metricsAfterFlush.tracking.mutationQueueSize);
+  console.log('- eventsTracked:', metricsAfterFlush.processing.eventsTracked);
+  console.log('- eventsFailed:', metricsAfterFlush.processing.eventsFailed);
+  console.log('- batchesSent:', metricsAfterFlush.processing.batchesSent);
+  console.log('- batchesFailed:', metricsAfterFlush.processing.batchesFailed);
+  console.log('- circuitBreakerState:', metricsAfterFlush.processing.circuitBreakerState);
+  console.log('\n');
+
+  console.log('Test completed. Check workflow_mutations table in Supabase.');
+}
+
+testMutations().catch(error => {
+  console.error('Test failed:', error);
+  process.exit(1);
+});

src/scripts/test-telemetry-mutations.ts

@@ -0,0 +1,145 @@
+/**
+ * Test telemetry mutations
+ * Verifies that mutations are properly tracked and persisted
+ */
+
+import { telemetry } from '../telemetry/telemetry-manager.js';
+import { TelemetryConfigManager } from '../telemetry/config-manager.js';
+
+async function testMutations() {
+  console.log('Starting telemetry mutation test...\n');
+
+  const configManager = TelemetryConfigManager.getInstance();
+
+  console.log('Telemetry Status:');
+  console.log('================');
+  console.log(configManager.getStatus());
+  console.log('\n');
+
+  // Get initial metrics
+  const metricsAfterInit = telemetry.getMetrics();
+  console.log('Telemetry Metrics (After Init):');
+  console.log('================================');
+  console.log(JSON.stringify(metricsAfterInit, null, 2));
+  console.log('\n');
+
+  // Test data mimicking actual mutation with valid workflow structure
+  const testMutation = {
+    sessionId: 'test_session_' + Date.now(),
+    toolName: 'n8n_update_partial_workflow',
+    userIntent: 'Add a Merge node for data consolidation',
+    operations: [
+      {
+        type: 'addNode',
+        nodeId: 'Merge1',
+        node: {
+          id: 'Merge1',
+          type: 'n8n-nodes-base.merge',
+          name: 'Merge',
+          position: [600, 200],
+          parameters: {}
+        }
+      },
+      {
+        type: 'addConnection',
+        source: 'previous_node',
+        target: 'Merge1'
+      }
+    ],
+    workflowBefore: {
+      id: 'test-workflow',
+      name: 'Test Workflow',
+      active: true,
+      nodes: [
+        {
+          id: 'previous_node',
+          type: 'n8n-nodes-base.manualTrigger',
+          name: 'When called',
+          position: [300, 200],
+          parameters: {}
+        }
+      ],
+      connections: {},
+      nodeIds: []
+    },
+    workflowAfter: {
+      id: 'test-workflow',
+      name: 'Test Workflow',
+      active: true,
+      nodes: [
+        {
+          id: 'previous_node',
+          type: 'n8n-nodes-base.manualTrigger',
+          name: 'When called',
+          position: [300, 200],
+          parameters: {}
+        },
+        {
+          id: 'Merge1',
+          type: 'n8n-nodes-base.merge',
+          name: 'Merge',
+          position: [600, 200],
+          parameters: {}
+        }
+      ],
+      connections: {
+        'previous_node': [
+          {
+            node: 'Merge1',
+            type: 'main',
+            index: 0,
+            source: 0,
+            destination: 0
+          }
+        ]
+      },
+      nodeIds: []
+    },
+    mutationSuccess: true,
+    durationMs: 125
+  };
+
+  console.log('Test Mutation Data:');
+  console.log('==================');
+  console.log(JSON.stringify({
+    intent: testMutation.userIntent,
+    tool: testMutation.toolName,
+    operationCount: testMutation.operations.length,
+    sessionId: testMutation.sessionId
+  }, null, 2));
+  console.log('\n');
+
+  // Call trackWorkflowMutation
+  console.log('Calling telemetry.trackWorkflowMutation...');
+  try {
+    await telemetry.trackWorkflowMutation(testMutation);
+    console.log('✓ trackWorkflowMutation completed successfully\n');
+  } catch (error) {
+    console.error('✗ trackWorkflowMutation failed:', error);
+    console.error('\n');
+  }
+
+  // Flush telemetry
+  console.log('Flushing telemetry...');
+  try {
+    await telemetry.flush();
+    console.log('✓ Telemetry flushed successfully\n');
+  } catch (error) {
+    console.error('✗ Flush failed:', error);
+    console.error('\n');
+  }
+
+  // Get final metrics
+  const metricsAfterFlush = telemetry.getMetrics();
+  console.log('Telemetry Metrics (After Flush):');
+  console.log('==================================');
+  console.log(JSON.stringify(metricsAfterFlush, null, 2));
+  console.log('\n');
+
+  console.log('Test completed. Check workflow_mutations table in Supabase.');
+}
+
+testMutations().catch(error => {
+  console.error('Test failed:', error);
+  process.exit(1);
+});

src/services/enhanced-config-validator.ts

@@ -13,6 +13,8 @@ import { ResourceSimilarityService } from './resource-similarity-service';
 import { NodeRepository } from '../database/node-repository';
 import { DatabaseAdapter } from '../database/database-adapter';
 import { NodeTypeNormalizer } from '../utils/node-type-normalizer';
+import { TypeStructureService } from './type-structure-service';
+import type { NodePropertyTypes } from 'n8n-workflow';
 
 export type ValidationMode = 'full' | 'operation' | 'minimal';
 export type ValidationProfile = 'strict' | 'runtime' | 'ai-friendly' | 'minimal';
@@ -111,7 +113,7 @@ export class EnhancedConfigValidator extends ConfigValidator {
     this.applyProfileFilters(enhancedResult, profile);
     
     // Add operation-specific enhancements
-    this.addOperationSpecificEnhancements(nodeType, config, enhancedResult);
+    this.addOperationSpecificEnhancements(nodeType, config, filteredProperties, enhancedResult);
     
     // Deduplicate errors
     enhancedResult.errors = this.deduplicateErrors(enhancedResult.errors);
@@ -247,6 +249,7 @@ export class EnhancedConfigValidator extends ConfigValidator {
   private static addOperationSpecificEnhancements(
     nodeType: string,
     config: Record<string, any>,
+    properties: any[],
     result: EnhancedValidationResult
   ): void {
     // Type safety check - this should never happen with proper validation
@@ -263,6 +266,9 @@ export class EnhancedConfigValidator extends ConfigValidator {
     // Validate resource and operation using similarity services
     this.validateResourceAndOperation(nodeType, config, result);
 
+    // Validate special type structures (filter, resourceMapper, assignmentCollection, resourceLocator)
+    this.validateSpecialTypeStructures(config, properties, result);
+
     // First, validate fixedCollection properties for known problematic nodes
     this.validateFixedCollectionStructures(nodeType, config, result);
     
@@ -982,4 +988,280 @@ export class EnhancedConfigValidator extends ConfigValidator {
       }
     }
   }
+
+  /**
+   * Validate special type structures (filter, resourceMapper, assignmentCollection, resourceLocator)
+   *
+   * Integrates TypeStructureService to validate complex property types against their
+   * expected structures. This catches configuration errors for advanced node types.
+   *
+   * @param config - Node configuration to validate
+   * @param properties - Property definitions from node schema
+   * @param result - Validation result to populate with errors/warnings
+   */
+  private static validateSpecialTypeStructures(
+    config: Record<string, any>,
+    properties: any[],
+    result: EnhancedValidationResult
+  ): void {
+    for (const [key, value] of Object.entries(config)) {
+      if (value === undefined || value === null) continue;
+
+      // Find property definition
+      const propDef = properties.find(p => p.name === key);
+      if (!propDef) continue;
+
+      // Check if this property uses a special type
+      let structureType: NodePropertyTypes | null = null;
+
+      if (propDef.type === 'filter') {
+        structureType = 'filter';
+      } else if (propDef.type === 'resourceMapper') {
+        structureType = 'resourceMapper';
+      } else if (propDef.type === 'assignmentCollection') {
+        structureType = 'assignmentCollection';
+      } else if (propDef.type === 'resourceLocator') {
+        structureType = 'resourceLocator';
+      }
+
+      if (!structureType) continue;
+
+      // Get structure definition
+      const structure = TypeStructureService.getStructure(structureType);
+      if (!structure) {
+        console.warn(`No structure definition found for type: ${structureType}`);
+        continue;
+      }
+
+      // Validate using TypeStructureService for basic type checking
+      const validationResult = TypeStructureService.validateTypeCompatibility(
+        value,
+        structureType
+      );
+
+      // Add errors from structure validation
+      if (!validationResult.valid) {
+        for (const error of validationResult.errors) {
+          result.errors.push({
+            type: 'invalid_configuration',
+            property: key,
+            message: error,
+            fix: `Ensure ${key} follows the expected structure for ${structureType} type. Example: ${JSON.stringify(structure.example)}`
+          });
+        }
+      }
+
+      // Add warnings
+      for (const warning of validationResult.warnings) {
+        result.warnings.push({
+          type: 'best_practice',
+          property: key,
+          message: warning
+        });
+      }
+
+      // Perform deep structure validation for complex types
+      if (typeof value === 'object' && value !== null) {
+        this.validateComplexTypeStructure(key, value, structureType, structure, result);
+      }
+
+      // Special handling for filter operation validation
+      if (structureType === 'filter' && value.conditions) {
+        this.validateFilterOperations(value.conditions, key, result);
+      }
+    }
+  }
+
+  /**
+   * Deep validation for complex type structures
+   */
+  private static validateComplexTypeStructure(
+    propertyName: string,
+    value: any,
+    type: NodePropertyTypes,
+    structure: any,
+    result: EnhancedValidationResult
+  ): void {
+    switch (type) {
+      case 'filter':
+        // Validate filter structure: must have combinator and conditions
+        if (!value.combinator) {
+          result.errors.push({
+            type: 'invalid_configuration',
+            property: `${propertyName}.combinator`,
+            message: 'Filter must have a combinator field',
+            fix: 'Add combinator: "and" or combinator: "or" to the filter configuration'
+          });
+        } else if (value.combinator !== 'and' && value.combinator !== 'or') {
+          result.errors.push({
+            type: 'invalid_configuration',
+            property: `${propertyName}.combinator`,
+            message: `Invalid combinator value: ${value.combinator}. Must be "and" or "or"`,
+            fix: 'Set combinator to either "and" or "or"'
+          });
+        }
+
+        if (!value.conditions) {
+          result.errors.push({
+            type: 'invalid_configuration',
+            property: `${propertyName}.conditions`,
+            message: 'Filter must have a conditions field',
+            fix: 'Add conditions array to the filter configuration'
+          });
+        } else if (!Array.isArray(value.conditions)) {
+          result.errors.push({
+            type: 'invalid_configuration',
+            property: `${propertyName}.conditions`,
+            message: 'Filter conditions must be an array',
+            fix: 'Ensure conditions is an array of condition objects'
+          });
+        }
+        break;
+
+      case 'resourceLocator':
+        // Validate resourceLocator structure: must have mode and value
+        if (!value.mode) {
+          result.errors.push({
+            type: 'invalid_configuration',
+            property: `${propertyName}.mode`,
+            message: 'ResourceLocator must have a mode field',
+            fix: 'Add mode: "id", mode: "url", or mode: "list" to the resourceLocator configuration'
+          });
+        } else if (!['id', 'url', 'list', 'name'].includes(value.mode)) {
+          result.errors.push({
+            type: 'invalid_configuration',
+            property: `${propertyName}.mode`,
+            message: `Invalid mode value: ${value.mode}. Must be "id", "url", "list", or "name"`,
+            fix: 'Set mode to one of: "id", "url", "list", "name"'
+          });
+        }
+
+        if (!value.hasOwnProperty('value')) {
+          result.errors.push({
+            type: 'invalid_configuration',
+            property: `${propertyName}.value`,
+            message: 'ResourceLocator must have a value field',
+            fix: 'Add value field to the resourceLocator configuration'
+          });
+        }
+        break;
+
+      case 'assignmentCollection':
+        // Validate assignmentCollection structure: must have assignments array
+        if (!value.assignments) {
+          result.errors.push({
+            type: 'invalid_configuration',
+            property: `${propertyName}.assignments`,
+            message: 'AssignmentCollection must have an assignments field',
+            fix: 'Add assignments array to the assignmentCollection configuration'
+          });
+        } else if (!Array.isArray(value.assignments)) {
+          result.errors.push({
+            type: 'invalid_configuration',
+            property: `${propertyName}.assignments`,
+            message: 'AssignmentCollection assignments must be an array',
+            fix: 'Ensure assignments is an array of assignment objects'
+          });
+        }
+        break;
+
+      case 'resourceMapper':
+        // Validate resourceMapper structure: must have mappingMode
+        if (!value.mappingMode) {
+          result.errors.push({
+            type: 'invalid_configuration',
+            property: `${propertyName}.mappingMode`,
+            message: 'ResourceMapper must have a mappingMode field',
+            fix: 'Add mappingMode: "defineBelow" or mappingMode: "autoMapInputData"'
+          });
+        } else if (!['defineBelow', 'autoMapInputData'].includes(value.mappingMode)) {
+          result.errors.push({
+            type: 'invalid_configuration',
+            property: `${propertyName}.mappingMode`,
+            message: `Invalid mappingMode: ${value.mappingMode}. Must be "defineBelow" or "autoMapInputData"`,
+            fix: 'Set mappingMode to either "defineBelow" or "autoMapInputData"'
+          });
+        }
+        break;
+    }
+  }
+
+  /**
+   * Validate filter operations match operator types
+   *
+   * Ensures that filter operations are compatible with their operator types.
+   * For example, 'gt' (greater than) is only valid for numbers, not strings.
+   *
+   * @param conditions - Array of filter conditions to validate
+   * @param propertyName - Name of the filter property (for error reporting)
+   * @param result - Validation result to populate with errors
+   */
+  private static validateFilterOperations(
+    conditions: any,
+    propertyName: string,
+    result: EnhancedValidationResult
+  ): void {
+    if (!Array.isArray(conditions)) return;
+
+    // Operation validation rules based on n8n filter type definitions
+    const VALID_OPERATIONS_BY_TYPE: Record<string, string[]> = {
+      string: [
+        'empty', 'notEmpty', 'equals', 'notEquals',
+        'contains', 'notContains', 'startsWith', 'notStartsWith',
+        'endsWith', 'notEndsWith', 'regex', 'notRegex',
+        'exists', 'notExists', 'isNotEmpty' // exists checks field presence, isNotEmpty alias for notEmpty
+      ],
+      number: [
+        'empty', 'notEmpty', 'equals', 'notEquals', 'gt', 'lt', 'gte', 'lte',
+        'exists', 'notExists', 'isNotEmpty'
+      ],
+      dateTime: [
+        'empty', 'notEmpty', 'equals', 'notEquals', 'after', 'before', 'afterOrEquals', 'beforeOrEquals',
+        'exists', 'notExists', 'isNotEmpty'
+      ],
+      boolean: [
+        'empty', 'notEmpty', 'true', 'false', 'equals', 'notEquals',
+        'exists', 'notExists', 'isNotEmpty'
+      ],
+      array: [
+        'contains', 'notContains', 'lengthEquals', 'lengthNotEquals',
+        'lengthGt', 'lengthLt', 'lengthGte', 'lengthLte', 'empty', 'notEmpty',
+        'exists', 'notExists', 'isNotEmpty'
+      ],
+      object: [
+        'empty', 'notEmpty',
+        'exists', 'notExists', 'isNotEmpty'
+      ],
+      any: ['exists', 'notExists', 'isNotEmpty']
+    };
+
+    for (let i = 0; i < conditions.length; i++) {
+      const condition = conditions[i];
+      if (!condition.operator || typeof condition.operator !== 'object') continue;
+
+      const { type, operation } = condition.operator;
+      if (!type || !operation) continue;
+
+      // Get valid operations for this type
+      const validOperations = VALID_OPERATIONS_BY_TYPE[type];
+      if (!validOperations) {
+        result.warnings.push({
+          type: 'best_practice',
+          property: `${propertyName}.conditions[${i}].operator.type`,
+          message: `Unknown operator type: ${type}`
+        });
+        continue;
+      }
+
+      // Check if operation is valid for this type
+      if (!validOperations.includes(operation)) {
+        result.errors.push({
+          type: 'invalid_value',
+          property: `${propertyName}.conditions[${i}].operator.operation`,
+          message: `Operation '${operation}' is not valid for type '${type}'`,
+          fix: `Use one of the valid operations for ${type}: ${validOperations.join(', ')}`
+        });
+      }
+    }
+  }
 }

src/services/n8n-validation.ts

@@ -62,6 +62,7 @@ export const workflowSettingsSchema = z.object({
   executionTimeout: z.number().optional(),
   errorWorkflow: z.string().optional(),
   callerPolicy: z.enum(['any', 'workflowsFromSameOwner', 'workflowsFromAList']).optional(),
+  availableInMCP: z.boolean().optional(),
 });
 
 // Default settings for workflow creation
@@ -103,7 +104,8 @@ export function cleanWorkflowForCreate(workflow: Partial<Workflow>): Partial<Wor
   } = workflow;
 
   // Ensure settings are present with defaults
-  if (!cleanedWorkflow.settings) {
+  // Treat empty settings object {} the same as missing settings
+  if (!cleanedWorkflow.settings || Object.keys(cleanedWorkflow.settings).length === 0) {
     cleanedWorkflow.settings = defaultWorkflowSettings;
   }
 
@@ -139,6 +141,7 @@ export function cleanWorkflowForUpdate(workflow: Workflow): Partial<Workflow> {
     // Remove fields that cause API errors
     pinData,
     tags,
+    description, // Issue #431: n8n returns this field but rejects it in updates
     // Remove additional fields that n8n API doesn't accept
     isArchived,
     usedCredentials,
@@ -155,16 +158,17 @@ export function cleanWorkflowForUpdate(workflow: Workflow): Partial<Workflow> {
   //
   // PROBLEM:
   // - Some versions reject updates with settings properties (community forum reports)
-  // - Cloud versions REQUIRE settings property to be present (n8n.estyl.team)
   // - Properties like callerPolicy cause "additional properties" errors
+  // - Empty settings objects {} cause "additional properties" validation errors (Issue #431)
   //
   // SOLUTION:
   // - Filter settings to only include whitelisted properties (OpenAPI spec)
-  // - If no settings provided, use empty object {} for safety
-  // - Empty object satisfies "required property" validation (cloud API)
+  // - If no settings after filtering, omit the property entirely (n8n API rejects empty objects)
+  // - Omitting the property prevents "additional properties" validation errors
   // - Whitelisted properties prevent "additional properties" errors
   //
   // References:
+  // - Issue #431: Empty settings validation error
   // - https://community.n8n.io/t/api-workflow-update-endpoint-doesnt-support-setting-callerpolicy/161916
   // - OpenAPI spec: workflowSettings schema
   // - Tested on n8n.estyl.team (cloud) and localhost (self-hosted)
@@ -178,7 +182,9 @@ export function cleanWorkflowForUpdate(workflow: Workflow): Partial<Workflow> {
     'executionTimeout',
     'errorWorkflow',
     'timezone',
-    'executionOrder'
+    'executionOrder',
+    'callerPolicy',
+    'availableInMCP',
   ];
 
   if (cleanedWorkflow.settings && typeof cleanedWorkflow.settings === 'object') {
@@ -189,10 +195,19 @@ export function cleanWorkflowForUpdate(workflow: Workflow): Partial<Workflow> {
         filteredSettings[key] = (cleanedWorkflow.settings as any)[key];
       }
     }
-    cleanedWorkflow.settings = filteredSettings;
+
+    // n8n API requires settings to be present but rejects empty settings objects.
+    // If no valid properties remain after filtering, include minimal default settings.
+    if (Object.keys(filteredSettings).length > 0) {
+      cleanedWorkflow.settings = filteredSettings;
+    } else {
+      // Provide minimal valid settings (executionOrder v1 is the modern default)
+      cleanedWorkflow.settings = { executionOrder: 'v1' as const };
+    }
   } else {
-    // No settings provided - use empty object for safety
-    cleanedWorkflow.settings = {};
+    // No settings provided - include minimal default settings
+    // n8n API requires settings in workflow updates (v1 is the modern default)
+    cleanedWorkflow.settings = { executionOrder: 'v1' as const };
   }
 
   return cleanedWorkflow;

src/services/node-specific-validators.ts

@@ -234,17 +234,11 @@ export class NodeSpecificValidators {
   static validateGoogleSheets(context: NodeValidationContext): void {
     const { config, errors, warnings, suggestions } = context;
     const { operation } = config;
-    
-    // Common validations
-    if (!config.sheetId && !config.documentId) {
-      errors.push({
-        type: 'missing_required',
-        property: 'sheetId',
-        message: 'Spreadsheet ID is required',
-        fix: 'Provide the Google Sheets document ID from the URL'
-      });
-    }
-    
+
+    // NOTE: Skip sheetId validation - it comes from credentials, not configuration
+    // In real workflows, sheetId is provided by Google Sheets credentials
+    // See Phase 3 validation results: 113/124 failures were false positives for this
+
     // Operation-specific validations
     switch (operation) {
       case 'append':
@@ -260,11 +254,30 @@ export class NodeSpecificValidators {
         this.validateGoogleSheetsDelete(context);
         break;
     }
-    
+
     // Range format validation
     if (config.range) {
       this.validateGoogleSheetsRange(config.range, errors, warnings);
     }
+
+    // FINAL STEP: Filter out sheetId errors (credential-provided field)
+    // Remove any sheetId validation errors that might have been added by nested validators
+    const filteredErrors: ValidationError[] = [];
+    for (const error of errors) {
+      // Skip sheetId errors - this field is provided by credentials
+      if (error.property === 'sheetId' && error.type === 'missing_required') {
+        continue;
+      }
+      // Skip errors about sheetId in nested paths (e.g., from resourceMapper validation)
+      if (error.property && error.property.includes('sheetId') && error.type === 'missing_required') {
+        continue;
+      }
+      filteredErrors.push(error);
+    }
+
+    // Replace errors array with filtered version
+    errors.length = 0;
+    errors.push(...filteredErrors);
   }
   
   private static validateGoogleSheetsAppend(context: NodeValidationContext): void {
@@ -1707,4 +1720,5 @@ export class NodeSpecificValidators {
       }
     }
   }
+
 }

src/services/type-structure-service.ts

@@ -0,0 +1,427 @@
+/**
+ * Type Structure Service
+ *
+ * Provides methods to query and work with n8n property type structures.
+ * This service is stateless and uses static methods following the project's
+ * PropertyFilter and ConfigValidator patterns.
+ *
+ * @module services/type-structure-service
+ * @since 2.23.0
+ */
+
+import type { NodePropertyTypes } from 'n8n-workflow';
+import type { TypeStructure } from '../types/type-structures';
+import {
+	isComplexType as isComplexTypeGuard,
+	isPrimitiveType as isPrimitiveTypeGuard,
+} from '../types/type-structures';
+import { TYPE_STRUCTURES, COMPLEX_TYPE_EXAMPLES } from '../constants/type-structures';
+
+/**
+ * Result of type validation
+ */
+export interface TypeValidationResult {
+	/**
+	 * Whether the value is valid for the type
+	 */
+	valid: boolean;
+
+	/**
+	 * Validation errors if invalid
+	 */
+	errors: string[];
+
+	/**
+	 * Warnings that don't prevent validity
+	 */
+	warnings: string[];
+}
+
+/**
+ * Service for querying and working with node property type structures
+ *
+ * Provides static methods to:
+ * - Get type structure definitions
+ * - Get example values
+ * - Validate type compatibility
+ * - Query type categories
+ *
+ * @example
+ * ```typescript
+ * // Get structure for a type
+ * const structure = TypeStructureService.getStructure('collection');
+ * console.log(structure.description); // "A group of related properties..."
+ *
+ * // Get example value
+ * const example = TypeStructureService.getExample('filter');
+ * console.log(example.combinator); // "and"
+ *
+ * // Check if type is complex
+ * if (TypeStructureService.isComplexType('resourceMapper')) {
+ *   console.log('This type needs special handling');
+ * }
+ * ```
+ */
+export class TypeStructureService {
+	/**
+	 * Get the structure definition for a property type
+	 *
+	 * Returns the complete structure definition including:
+	 * - Type category (primitive/object/collection/special)
+	 * - JavaScript type
+	 * - Expected structure for complex types
+	 * - Example values
+	 * - Validation rules
+	 *
+	 * @param type - The NodePropertyType to query
+	 * @returns Type structure definition, or null if type is unknown
+	 *
+	 * @example
+	 * ```typescript
+	 * const structure = TypeStructureService.getStructure('string');
+	 * console.log(structure.jsType); // "string"
+	 * console.log(structure.example); // "Hello World"
+	 * ```
+	 */
+	static getStructure(type: NodePropertyTypes): TypeStructure | null {
+		return TYPE_STRUCTURES[type] || null;
+	}
+
+	/**
+	 * Get all type structure definitions
+	 *
+	 * Returns a record of all 22 NodePropertyTypes with their structures.
+	 * Useful for documentation, validation setup, or UI generation.
+	 *
+	 * @returns Record mapping all types to their structures
+	 *
+	 * @example
+	 * ```typescript
+	 * const allStructures = TypeStructureService.getAllStructures();
+	 * console.log(Object.keys(allStructures).length); // 22
+	 * ```
+	 */
+	static getAllStructures(): Record<NodePropertyTypes, TypeStructure> {
+		return { ...TYPE_STRUCTURES };
+	}
+
+	/**
+	 * Get example value for a property type
+	 *
+	 * Returns a working example value that conforms to the type's
+	 * expected structure. Useful for testing, documentation, or
+	 * generating default values.
+	 *
+	 * @param type - The NodePropertyType to get an example for
+	 * @returns Example value, or null if type is unknown
+	 *
+	 * @example
+	 * ```typescript
+	 * const example = TypeStructureService.getExample('number');
+	 * console.log(example); // 42
+	 *
+	 * const filterExample = TypeStructureService.getExample('filter');
+	 * console.log(filterExample.combinator); // "and"
+	 * ```
+	 */
+	static getExample(type: NodePropertyTypes): any {
+		const structure = this.getStructure(type);
+		return structure ? structure.example : null;
+	}
+
+	/**
+	 * Get all example values for a property type
+	 *
+	 * Some types have multiple examples to show different use cases.
+	 * This returns all available examples, or falls back to the
+	 * primary example if only one exists.
+	 *
+	 * @param type - The NodePropertyType to get examples for
+	 * @returns Array of example values
+	 *
+	 * @example
+	 * ```typescript
+	 * const examples = TypeStructureService.getExamples('string');
+	 * console.log(examples.length); // 4
+	 * console.log(examples[0]); // ""
+	 * console.log(examples[1]); // "A simple text"
+	 * ```
+	 */
+	static getExamples(type: NodePropertyTypes): any[] {
+		const structure = this.getStructure(type);
+		if (!structure) return [];
+
+		return structure.examples || [structure.example];
+	}
+
+	/**
+	 * Check if a property type is complex
+	 *
+	 * Complex types have nested structures and require special
+	 * validation logic beyond simple type checking.
+	 *
+	 * Complex types: collection, fixedCollection, resourceLocator,
+	 * resourceMapper, filter, assignmentCollection
+	 *
+	 * @param type - The property type to check
+	 * @returns True if the type is complex
+	 *
+	 * @example
+	 * ```typescript
+	 * TypeStructureService.isComplexType('collection'); // true
+	 * TypeStructureService.isComplexType('string'); // false
+	 * ```
+	 */
+	static isComplexType(type: NodePropertyTypes): boolean {
+		return isComplexTypeGuard(type);
+	}
+
+	/**
+	 * Check if a property type is primitive
+	 *
+	 * Primitive types map to simple JavaScript values and only
+	 * need basic type validation.
+	 *
+	 * Primitive types: string, number, boolean, dateTime, color, json
+	 *
+	 * @param type - The property type to check
+	 * @returns True if the type is primitive
+	 *
+	 * @example
+	 * ```typescript
+	 * TypeStructureService.isPrimitiveType('string'); // true
+	 * TypeStructureService.isPrimitiveType('collection'); // false
+	 * ```
+	 */
+	static isPrimitiveType(type: NodePropertyTypes): boolean {
+		return isPrimitiveTypeGuard(type);
+	}
+
+	/**
+	 * Get all complex property types
+	 *
+	 * Returns an array of all property types that are classified
+	 * as complex (having nested structures).
+	 *
+	 * @returns Array of complex type names
+	 *
+	 * @example
+	 * ```typescript
+	 * const complexTypes = TypeStructureService.getComplexTypes();
+	 * console.log(complexTypes);
+	 * // ['collection', 'fixedCollection', 'resourceLocator', ...]
+	 * ```
+	 */
+	static getComplexTypes(): NodePropertyTypes[] {
+		return Object.entries(TYPE_STRUCTURES)
+			.filter(([, structure]) => structure.type === 'collection' || structure.type === 'special')
+			.filter(([type]) => this.isComplexType(type as NodePropertyTypes))
+			.map(([type]) => type as NodePropertyTypes);
+	}
+
+	/**
+	 * Get all primitive property types
+	 *
+	 * Returns an array of all property types that are classified
+	 * as primitive (simple JavaScript values).
+	 *
+	 * @returns Array of primitive type names
+	 *
+	 * @example
+	 * ```typescript
+	 * const primitiveTypes = TypeStructureService.getPrimitiveTypes();
+	 * console.log(primitiveTypes);
+	 * // ['string', 'number', 'boolean', 'dateTime', 'color', 'json']
+	 * ```
+	 */
+	static getPrimitiveTypes(): NodePropertyTypes[] {
+		return Object.keys(TYPE_STRUCTURES).filter((type) =>
+			this.isPrimitiveType(type as NodePropertyTypes)
+		) as NodePropertyTypes[];
+	}
+
+	/**
+	 * Get real-world examples for complex types
+	 *
+	 * Returns curated examples from actual n8n workflows showing
+	 * different usage patterns for complex types.
+	 *
+	 * @param type - The complex type to get examples for
+	 * @returns Object with named example scenarios, or null
+	 *
+	 * @example
+	 * ```typescript
+	 * const examples = TypeStructureService.getComplexExamples('fixedCollection');
+	 * console.log(examples.httpHeaders);
+	 * // { headers: [{ name: 'Content-Type', value: 'application/json' }] }
+	 * ```
+	 */
+	static getComplexExamples(
+		type: 'collection' | 'fixedCollection' | 'filter' | 'resourceMapper' | 'assignmentCollection'
+	): Record<string, any> | null {
+		return COMPLEX_TYPE_EXAMPLES[type] || null;
+	}
+
+	/**
+	 * Validate basic type compatibility of a value
+	 *
+	 * Performs simple type checking to verify a value matches the
+	 * expected JavaScript type for a property type. Does not perform
+	 * deep structure validation for complex types.
+	 *
+	 * @param value - The value to validate
+	 * @param type - The expected property type
+	 * @returns Validation result with errors if invalid
+	 *
+	 * @example
+	 * ```typescript
+	 * const result = TypeStructureService.validateTypeCompatibility(
+	 *   'Hello',
+	 *   'string'
+	 * );
+	 * console.log(result.valid); // true
+	 *
+	 * const result2 = TypeStructureService.validateTypeCompatibility(
+	 *   123,
+	 *   'string'
+	 * );
+	 * console.log(result2.valid); // false
+	 * console.log(result2.errors[0]); // "Expected string but got number"
+	 * ```
+	 */
+	static validateTypeCompatibility(
+		value: any,
+		type: NodePropertyTypes
+	): TypeValidationResult {
+		const structure = this.getStructure(type);
+
+		if (!structure) {
+			return {
+				valid: false,
+				errors: [`Unknown property type: ${type}`],
+				warnings: [],
+			};
+		}
+
+		const errors: string[] = [];
+		const warnings: string[] = [];
+
+		// Handle null/undefined
+		if (value === null || value === undefined) {
+			if (!structure.validation?.allowEmpty) {
+				errors.push(`Value is required for type ${type}`);
+			}
+			return { valid: errors.length === 0, errors, warnings };
+		}
+
+		// Check JavaScript type compatibility
+		const actualType = Array.isArray(value) ? 'array' : typeof value;
+		const expectedType = structure.jsType;
+
+		if (expectedType !== 'any' && actualType !== expectedType) {
+			// Special case: expressions are strings but might be allowed
+			const isExpression = typeof value === 'string' && value.includes('{{');
+			if (isExpression && structure.validation?.allowExpressions) {
+				warnings.push(
+					`Value contains n8n expression - cannot validate type until runtime`
+				);
+			} else {
+				errors.push(`Expected ${expectedType} but got ${actualType}`);
+			}
+		}
+
+		// Additional validation for specific types
+		if (type === 'dateTime' && typeof value === 'string') {
+			const pattern = structure.validation?.pattern;
+			if (pattern && !new RegExp(pattern).test(value)) {
+				errors.push(`Invalid dateTime format. Expected ISO 8601 format.`);
+			}
+		}
+
+		if (type === 'color' && typeof value === 'string') {
+			const pattern = structure.validation?.pattern;
+			if (pattern && !new RegExp(pattern).test(value)) {
+				errors.push(`Invalid color format. Expected 6-digit hex color (e.g., #FF5733).`);
+			}
+		}
+
+		if (type === 'json' && typeof value === 'string') {
+			try {
+				JSON.parse(value);
+			} catch {
+				errors.push(`Invalid JSON string. Must be valid JSON when parsed.`);
+			}
+		}
+
+		return {
+			valid: errors.length === 0,
+			errors,
+			warnings,
+		};
+	}
+
+	/**
+	 * Get type description
+	 *
+	 * Returns the human-readable description of what a property type
+	 * represents and how it should be used.
+	 *
+	 * @param type - The property type
+	 * @returns Description string, or null if type unknown
+	 *
+	 * @example
+	 * ```typescript
+	 * const description = TypeStructureService.getDescription('filter');
+	 * console.log(description);
+	 * // "Defines conditions for filtering data with boolean logic"
+	 * ```
+	 */
+	static getDescription(type: NodePropertyTypes): string | null {
+		const structure = this.getStructure(type);
+		return structure ? structure.description : null;
+	}
+
+	/**
+	 * Get type notes
+	 *
+	 * Returns additional notes, warnings, or usage tips for a type.
+	 * Not all types have notes.
+	 *
+	 * @param type - The property type
+	 * @returns Array of note strings, or empty array
+	 *
+	 * @example
+	 * ```typescript
+	 * const notes = TypeStructureService.getNotes('filter');
+	 * console.log(notes[0]);
+	 * // "Advanced filtering UI in n8n"
+	 * ```
+	 */
+	static getNotes(type: NodePropertyTypes): string[] {
+		const structure = this.getStructure(type);
+		return structure?.notes || [];
+	}
+
+	/**
+	 * Get JavaScript type for a property type
+	 *
+	 * Returns the underlying JavaScript type that the property
+	 * type maps to (string, number, boolean, object, array, any).
+	 *
+	 * @param type - The property type
+	 * @returns JavaScript type name, or null if unknown
+	 *
+	 * @example
+	 * ```typescript
+	 * TypeStructureService.getJavaScriptType('string'); // "string"
+	 * TypeStructureService.getJavaScriptType('collection'); // "object"
+	 * TypeStructureService.getJavaScriptType('multiOptions'); // "array"
+	 * ```
+	 */
+	static getJavaScriptType(
+		type: NodePropertyTypes
+	): 'string' | 'number' | 'boolean' | 'object' | 'array' | 'any' | null {
+		const structure = this.getStructure(type);
+		return structure ? structure.jsType : null;
+	}
+}

src/services/workflow-diff-engine.ts

@@ -861,10 +861,14 @@ export class WorkflowDiffEngine {
 
   // Metadata operation appliers
   private applyUpdateSettings(workflow: Workflow, operation: UpdateSettingsOperation): void {
-    if (!workflow.settings) {
-      workflow.settings = {};
+    // Only create/update settings if operation provides actual properties
+    // This prevents creating empty settings objects that would be rejected by n8n API
+    if (operation.settings && Object.keys(operation.settings).length > 0) {
+      if (!workflow.settings) {
+        workflow.settings = {};
+      }
+      Object.assign(workflow.settings, operation.settings);
     }
-    Object.assign(workflow.settings, operation.settings);
   }
 
   private applyUpdateName(workflow: Workflow, operation: UpdateNameOperation): void {

src/services/workflow-validator.ts

@@ -383,14 +383,11 @@ export class WorkflowValidator {
             });
           }
         }
-        // Normalize node type FIRST to ensure consistent lookup
+        // Normalize node type for database lookup (DO NOT mutate the original workflow)
+        // The normalizer converts to short form (nodes-base.*) for database queries,
+        // but n8n API requires full form (n8n-nodes-base.*). Never modify the input workflow.
         const normalizedType = NodeTypeNormalizer.normalizeToFullForm(node.type);
 
-        // Update node type in place if it was normalized
-        if (normalizedType !== node.type) {
-          node.type = normalizedType;
-        }
-
         // Get node definition using normalized type (needed for typeVersion validation)
         const nodeInfo = this.nodeRepository.getNode(normalizedType);
 
@@ -684,7 +681,12 @@ export class WorkflowValidator {
         }
 
         // Special validation for SplitInBatches node
-        if (sourceNode && sourceNode.type === 'nodes-base.splitInBatches') {
+        // Check both full form (n8n-nodes-base.*) and short form (nodes-base.*)
+        const isSplitInBatches = sourceNode && (
+          sourceNode.type === 'n8n-nodes-base.splitInBatches' ||
+          sourceNode.type === 'nodes-base.splitInBatches'
+        );
+        if (isSplitInBatches) {
           this.validateSplitInBatchesConnection(
             sourceNode,
             outputIndex,
@@ -696,8 +698,8 @@ export class WorkflowValidator {
 
         // Check for self-referencing connections
         if (connection.node === sourceName) {
-          // This is only a warning for non-loop nodes
-          if (sourceNode && sourceNode.type !== 'nodes-base.splitInBatches') {
+          // This is only a warning for non-loop nodes (not SplitInBatches)
+          if (sourceNode && !isSplitInBatches) {
             result.warnings.push({
               type: 'warning',
               message: `Node "${sourceName}" has a self-referencing connection. This can cause infinite loops.`

src/telemetry/mutation-tracker.ts

@@ -41,8 +41,8 @@ export class MutationTracker {
       }
 
       // Sanitize workflows to remove credentials and sensitive data
-      const workflowBefore = this.sanitizeFullWorkflow(data.workflowBefore);
-      const workflowAfter = this.sanitizeFullWorkflow(data.workflowAfter);
+      const workflowBefore = WorkflowSanitizer.sanitizeWorkflowRaw(data.workflowBefore);
+      const workflowAfter = WorkflowSanitizer.sanitizeWorkflowRaw(data.workflowAfter);
 
       // Sanitize user intent
       const sanitizedIntent = intentSanitizer.sanitize(data.userIntent);
@@ -70,6 +70,10 @@ export class MutationTracker {
       const hashBefore = mutationValidator.hashWorkflow(workflowBefore);
       const hashAfter = mutationValidator.hashWorkflow(workflowAfter);
 
+      // Generate structural hashes for cross-referencing with telemetry_workflows
+      const structureHashBefore = WorkflowSanitizer.generateWorkflowHash(workflowBefore);
+      const structureHashAfter = WorkflowSanitizer.generateWorkflowHash(workflowAfter);
+
       // Classify intent
       const intentClassification = intentClassifier.classify(data.operations, sanitizedIntent);
 
@@ -88,6 +92,8 @@ export class MutationTracker {
         workflowAfter,
         workflowHashBefore: hashBefore,
         workflowHashAfter: hashAfter,
+        workflowStructureHashBefore: structureHashBefore,
+        workflowStructureHashAfter: structureHashAfter,
         userIntent: sanitizedIntent,
         intentClassification,
         toolName: data.toolName,
@@ -200,98 +206,6 @@ export class MutationTracker {
     return metrics;
   }
 
-  /**
-   * Sanitize a full workflow while preserving structure
-   * Removes credentials and sensitive data but keeps all nodes, connections, parameters
-   */
-  private sanitizeFullWorkflow(workflow: any): any {
-    if (!workflow) return workflow;
-
-    // Deep clone to avoid modifying original
-    const sanitized = JSON.parse(JSON.stringify(workflow));
-
-    // Remove sensitive workflow-level fields
-    delete sanitized.credentials;
-    delete sanitized.sharedWorkflows;
-    delete sanitized.ownedBy;
-    delete sanitized.createdBy;
-    delete sanitized.updatedBy;
-
-    // Sanitize each node
-    if (sanitized.nodes && Array.isArray(sanitized.nodes)) {
-      sanitized.nodes = sanitized.nodes.map((node: any) => {
-        const sanitizedNode = { ...node };
-
-        // Remove credentials field
-        delete sanitizedNode.credentials;
-
-        // Sanitize parameters if present
-        if (sanitizedNode.parameters && typeof sanitizedNode.parameters === 'object') {
-          sanitizedNode.parameters = this.sanitizeParameters(sanitizedNode.parameters);
-        }
-
-        return sanitizedNode;
-      });
-    }
-
-    return sanitized;
-  }
-
-  /**
-   * Recursively sanitize parameters object
-   */
-  private sanitizeParameters(params: any): any {
-    if (!params || typeof params !== 'object') return params;
-
-    const sensitiveKeys = [
-      'apiKey', 'api_key', 'token', 'secret', 'password', 'credential',
-      'auth', 'authorization', 'privateKey', 'accessToken', 'refreshToken'
-    ];
-
-    const sanitized: any = Array.isArray(params) ? [] : {};
-
-    for (const [key, value] of Object.entries(params)) {
-      const lowerKey = key.toLowerCase();
-
-      // Check if key is sensitive
-      if (sensitiveKeys.some(sk => lowerKey.includes(sk.toLowerCase()))) {
-        sanitized[key] = '[REDACTED]';
-      } else if (typeof value === 'object' && value !== null) {
-        // Recursively sanitize nested objects
-        sanitized[key] = this.sanitizeParameters(value);
-      } else if (typeof value === 'string') {
-        // Sanitize string values that might contain sensitive data
-        sanitized[key] = this.sanitizeStringValue(value);
-      } else {
-        sanitized[key] = value;
-      }
-    }
-
-    return sanitized;
-  }
-
-  /**
-   * Sanitize string values that might contain sensitive data
-   */
-  private sanitizeStringValue(value: string): string {
-    if (!value || typeof value !== 'string') return value;
-
-    let sanitized = value;
-
-    // Redact URLs with authentication
-    sanitized = sanitized.replace(/https?:\/\/[^:]+:[^@]+@[^\s/]+/g, '[REDACTED_URL_WITH_AUTH]');
-
-    // Redact long API keys/tokens (20+ alphanumeric chars)
-    sanitized = sanitized.replace(/\b[A-Za-z0-9_-]{32,}\b/g, '[REDACTED_TOKEN]');
-
-    // Redact OpenAI-style keys
-    sanitized = sanitized.replace(/\bsk-[A-Za-z0-9]{32,}\b/g, '[REDACTED_APIKEY]');
-
-    // Redact Bearer tokens
-    sanitized = sanitized.replace(/Bearer\s+[^\s]+/gi, 'Bearer [REDACTED]');
-
-    return sanitized;
-  }
 
   /**
    * Calculate validation improvement metrics

src/telemetry/mutation-types.ts

@@ -91,6 +91,12 @@ export interface WorkflowMutationRecord {
   workflowAfter: any;
   workflowHashBefore: string;
   workflowHashAfter: string;
+  /** Structural hash (nodeTypes + connections) for cross-referencing with telemetry_workflows */
+  workflowStructureHashBefore?: string;
+  /** Structural hash (nodeTypes + connections) for cross-referencing with telemetry_workflows */
+  workflowStructureHashAfter?: string;
+  /** Computed field: true if mutation executed successfully, improved validation, and has known intent */
+  isTrulySuccessful?: boolean;
   userIntent: string;
   intentClassification: IntentClassification;
   toolName: MutationToolName;

src/telemetry/workflow-sanitizer.ts

@@ -27,29 +27,32 @@ interface SanitizedWorkflow {
   workflowHash: string;
 }
 
+interface PatternDefinition {
+  pattern: RegExp;
+  placeholder: string;
+  preservePrefix?: boolean; // For patterns like "Bearer [REDACTED]"
+}
+
 export class WorkflowSanitizer {
-  private static readonly SENSITIVE_PATTERNS = [
+  private static readonly SENSITIVE_PATTERNS: PatternDefinition[] = [
     // Webhook URLs (replace with placeholder but keep structure) - MUST BE FIRST
-    /https?:\/\/[^\s/]+\/webhook\/[^\s]+/g,
-    /https?:\/\/[^\s/]+\/hook\/[^\s]+/g,
+    { pattern: /https?:\/\/[^\s/]+\/webhook\/[^\s]+/g, placeholder: '[REDACTED_WEBHOOK]' },
+    { pattern: /https?:\/\/[^\s/]+\/hook\/[^\s]+/g, placeholder: '[REDACTED_WEBHOOK]' },
 
-    // API keys and tokens
-    /sk-[a-zA-Z0-9]{16,}/g, // OpenAI keys
-    /Bearer\s+[^\s]+/gi,    // Bearer tokens
-    /[a-zA-Z0-9_-]{20,}/g,  // Long alphanumeric strings (API keys) - reduced threshold
-    /token['":\s]+[^,}]+/gi, // Token fields
-    /apikey['":\s]+[^,}]+/gi, // API key fields
-    /api_key['":\s]+[^,}]+/gi,
-    /secret['":\s]+[^,}]+/gi,
-    /password['":\s]+[^,}]+/gi,
-    /credential['":\s]+[^,}]+/gi,
+    // URLs with authentication - MUST BE BEFORE BEARER TOKENS
+    { pattern: /https?:\/\/[^:]+:[^@]+@[^\s/]+/g, placeholder: '[REDACTED_URL_WITH_AUTH]' },
+    { pattern: /wss?:\/\/[^:]+:[^@]+@[^\s/]+/g, placeholder: '[REDACTED_URL_WITH_AUTH]' },
+    { pattern: /(?:postgres|mysql|mongodb|redis):\/\/[^:]+:[^@]+@[^\s]+/g, placeholder: '[REDACTED_URL_WITH_AUTH]' }, // Database protocols - includes port and path
 
-    // URLs with authentication
-    /https?:\/\/[^:]+:[^@]+@[^\s/]+/g, // URLs with auth
-    /wss?:\/\/[^:]+:[^@]+@[^\s/]+/g,
+    // API keys and tokens - ORDER MATTERS!
+    // More specific patterns first, then general patterns
+    { pattern: /sk-[a-zA-Z0-9]{16,}/g, placeholder: '[REDACTED_APIKEY]' }, // OpenAI keys
+    { pattern: /Bearer\s+[^\s]+/gi, placeholder: 'Bearer [REDACTED]', preservePrefix: true }, // Bearer tokens
+    { pattern: /\b[a-zA-Z0-9_-]{32,}\b/g, placeholder: '[REDACTED_TOKEN]' }, // Long tokens (32+ chars)
+    { pattern: /\b[a-zA-Z0-9_-]{20,31}\b/g, placeholder: '[REDACTED]' }, // Short tokens (20-31 chars)
 
     // Email addresses (optional - uncomment if needed)
-    // /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g,
+    // { pattern: /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g, placeholder: '[REDACTED_EMAIL]' },
   ];
 
   private static readonly SENSITIVE_FIELDS = [
@@ -178,19 +181,34 @@ export class WorkflowSanitizer {
     const sanitized: any = {};
 
     for (const [key, value] of Object.entries(obj)) {
-      // Check if key is sensitive
-      if (this.isSensitiveField(key)) {
-        sanitized[key] = '[REDACTED]';
-        continue;
-      }
+      // Check if field name is sensitive
+      const isSensitive = this.isSensitiveField(key);
+      const isUrlField = key.toLowerCase().includes('url') ||
+                         key.toLowerCase().includes('endpoint') ||
+                         key.toLowerCase().includes('webhook');
 
-      // Recursively sanitize nested objects
+      // Recursively sanitize nested objects (unless it's a sensitive non-URL field)
       if (typeof value === 'object' && value !== null) {
-        sanitized[key] = this.sanitizeObject(value);
+        if (isSensitive && !isUrlField) {
+          // For sensitive object fields (like 'authentication'), redact completely
+          sanitized[key] = '[REDACTED]';
+        } else {
+          sanitized[key] = this.sanitizeObject(value);
+        }
       }
       // Sanitize string values
       else if (typeof value === 'string') {
-        sanitized[key] = this.sanitizeString(value, key);
+        // For sensitive fields (except URL fields), use generic redaction
+        if (isSensitive && !isUrlField) {
+          sanitized[key] = '[REDACTED]';
+        } else {
+          // For URL fields or non-sensitive fields, use pattern-specific sanitization
+          sanitized[key] = this.sanitizeString(value, key);
+        }
+      }
+      // For non-string sensitive fields, redact completely
+      else if (isSensitive) {
+        sanitized[key] = '[REDACTED]';
       }
       // Keep other types as-is
       else {
@@ -212,13 +230,42 @@ export class WorkflowSanitizer {
 
     let sanitized = value;
 
-    // Apply all sensitive patterns
-    for (const pattern of this.SENSITIVE_PATTERNS) {
+    // Apply all sensitive patterns with their specific placeholders
+    for (const patternDef of this.SENSITIVE_PATTERNS) {
       // Skip webhook patterns - already handled above
-      if (pattern.toString().includes('webhook')) {
+      if (patternDef.placeholder.includes('WEBHOOK')) {
         continue;
       }
-      sanitized = sanitized.replace(pattern, '[REDACTED]');
+
+      // Skip if already sanitized with a placeholder to prevent double-redaction
+      if (sanitized.includes('[REDACTED')) {
+        break;
+      }
+
+      // Special handling for URL with auth - preserve path after credentials
+      if (patternDef.placeholder === '[REDACTED_URL_WITH_AUTH]') {
+        const matches = value.match(patternDef.pattern);
+        if (matches) {
+          for (const match of matches) {
+            // Extract path after the authenticated URL
+            const fullUrlMatch = value.indexOf(match);
+            if (fullUrlMatch !== -1) {
+              const afterUrl = value.substring(fullUrlMatch + match.length);
+              // If there's a path after the URL, preserve it
+              if (afterUrl && afterUrl.startsWith('/')) {
+                const pathPart = afterUrl.split(/[\s?&#]/)[0]; // Get path until query/fragment
+                sanitized = sanitized.replace(match + pathPart, patternDef.placeholder + pathPart);
+              } else {
+                sanitized = sanitized.replace(match, patternDef.placeholder);
+              }
+            }
+          }
+        }
+        continue;
+      }
+
+      // Apply pattern with its specific placeholder
+      sanitized = sanitized.replace(patternDef.pattern, patternDef.placeholder);
     }
 
     // Additional sanitization for specific field types
@@ -226,9 +273,13 @@ export class WorkflowSanitizer {
         fieldName.toLowerCase().includes('endpoint')) {
       // Keep URL structure but remove domain details
       if (sanitized.startsWith('http://') || sanitized.startsWith('https://')) {
-        // If value has been redacted, leave it as is
+        // If value has been redacted with URL_WITH_AUTH, preserve it
+        if (sanitized.includes('[REDACTED_URL_WITH_AUTH]')) {
+          return sanitized; // Already properly sanitized with path preserved
+        }
+        // If value has other redactions, leave it as is
         if (sanitized.includes('[REDACTED]')) {
-          return '[REDACTED]';
+          return sanitized;
         }
         const urlParts = sanitized.split('/');
         if (urlParts.length > 2) {
@@ -296,4 +347,37 @@ export class WorkflowSanitizer {
     const sanitized = this.sanitizeWorkflow(workflow);
     return sanitized.workflowHash;
   }
+
+  /**
+   * Sanitize workflow and return raw workflow object (without metrics)
+   * For use in telemetry where we need plain workflow structure
+   */
+  static sanitizeWorkflowRaw(workflow: any): any {
+    // Create a deep copy to avoid modifying original
+    const sanitized = JSON.parse(JSON.stringify(workflow));
+
+    // Sanitize nodes
+    if (sanitized.nodes && Array.isArray(sanitized.nodes)) {
+      sanitized.nodes = sanitized.nodes.map((node: WorkflowNode) =>
+        this.sanitizeNode(node)
+      );
+    }
+
+    // Sanitize connections (keep structure only)
+    if (sanitized.connections) {
+      sanitized.connections = this.sanitizeConnections(sanitized.connections);
+    }
+
+    // Remove other potentially sensitive data
+    delete sanitized.settings?.errorWorkflow;
+    delete sanitized.staticData;
+    delete sanitized.pinData;
+    delete sanitized.credentials;
+    delete sanitized.sharedWorkflows;
+    delete sanitized.ownedBy;
+    delete sanitized.createdBy;
+    delete sanitized.updatedBy;
+
+    return sanitized;
+  }
 }