chore: update n8n to 2.1.5 and bump version to 2.31.6 (#521)

- Updated n8n from 2.1.4 to 2.1.5
- Updated n8n-core from 2.1.3 to 2.1.4
- Updated @n8n/n8n-nodes-langchain from 2.1.3 to 2.1.4
- Rebuilt node database with 540 nodes (434 from n8n-nodes-base, 106 from @n8n/n8n-nodes-langchain)
- Updated README badge with new n8n version
- Updated CHANGELOG with dependency changes

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

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

Co-authored-by: Romuald Członkowski <romualdczlonkowski@MacBook-Pro-Romuald.local>
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.

.claude/agents/n8n-mcp-tester.md

@@ -1,7 +1,7 @@
 ---
 name: n8n-mcp-tester
 description: Use this agent when you need to test n8n-mcp functionality after implementing fixes or new features. This agent should be invoked proactively after code changes to validate that the MCP tools work correctly with real n8n workflows. The agent tests the actual MCP server tools, not just unit tests. Examples:\n\n<example>\nContext: Developer has just fixed a validation bug in the n8n-mcp server\nuser: "I've fixed the validation issue for HTTP Request nodes"\nassistant: "I've completed the fix. Now let me build the project and then test it."\n<builds project>\nassistant: "Project built successfully. Please reload the MCP server in Claude Desktop to apply the changes."\nuser: "Reloaded"\nassistant: "Great! Now let me invoke the n8n-mcp-tester agent to verify the fix works correctly."\n<commentary>\nSince a fix has been implemented and the MCP server reloaded, use the n8n-mcp-tester agent to validate the fix works in real-world usage.\n</commentary>\n</example>\n\n<example>\nContext: Developer has added a new MCP tool for workflow validation\nuser: "I've implemented the new workflow validation tool"\nassistant: "Implementation complete. Let me build and prepare for testing."\n<builds project>\nassistant: "Build successful. Please reload the MCP server to load the new tool."\nuser: "Done"\nassistant: "Perfect! I'll now use the n8n-mcp-tester agent to test the new workflow validation tool."\n<commentary>\nAfter implementing new MCP functionality and reloading the server, invoke n8n-mcp-tester to verify it works correctly.\n</commentary>\n</example>
-tools: Glob, Grep, LS, Read, WebFetch, TodoWrite, WebSearch, mcp__puppeteer__puppeteer_navigate, mcp__puppeteer__puppeteer_screenshot, mcp__puppeteer__puppeteer_click, mcp__puppeteer__puppeteer_fill, mcp__puppeteer__puppeteer_select, mcp__puppeteer__puppeteer_hover, mcp__puppeteer__puppeteer_evaluate, ListMcpResourcesTool, ReadMcpResourceTool, mcp__supabase__list_organizations, mcp__supabase__get_organization, mcp__supabase__list_projects, mcp__supabase__get_project, mcp__supabase__get_cost, mcp__supabase__confirm_cost, mcp__supabase__create_project, mcp__supabase__pause_project, mcp__supabase__restore_project, mcp__supabase__create_branch, mcp__supabase__list_branches, mcp__supabase__delete_branch, mcp__supabase__merge_branch, mcp__supabase__reset_branch, mcp__supabase__rebase_branch, mcp__supabase__list_tables, mcp__supabase__list_extensions, mcp__supabase__list_migrations, mcp__supabase__apply_migration, mcp__supabase__execute_sql, mcp__supabase__get_logs, mcp__supabase__get_advisors, mcp__supabase__get_project_url, mcp__supabase__get_anon_key, mcp__supabase__generate_typescript_types, mcp__supabase__search_docs, mcp__supabase__list_edge_functions, mcp__supabase__deploy_edge_function, mcp__n8n-mcp__tools_documentation, mcp__n8n-mcp__list_nodes, mcp__n8n-mcp__get_node_info, mcp__n8n-mcp__search_nodes, mcp__n8n-mcp__list_ai_tools, mcp__n8n-mcp__get_node_documentation, mcp__n8n-mcp__get_database_statistics, mcp__n8n-mcp__get_node_essentials, mcp__n8n-mcp__search_node_properties, mcp__n8n-mcp__get_node_for_task, mcp__n8n-mcp__list_tasks, mcp__n8n-mcp__validate_node_operation, mcp__n8n-mcp__validate_node_minimal, mcp__n8n-mcp__get_property_dependencies, mcp__n8n-mcp__get_node_as_tool_info, mcp__n8n-mcp__list_node_templates, mcp__n8n-mcp__get_template, mcp__n8n-mcp__search_templates, mcp__n8n-mcp__get_templates_for_task, mcp__n8n-mcp__validate_workflow, mcp__n8n-mcp__validate_workflow_connections, mcp__n8n-mcp__validate_workflow_expressions, mcp__n8n-mcp__n8n_create_workflow, mcp__n8n-mcp__n8n_get_workflow, mcp__n8n-mcp__n8n_get_workflow_details, mcp__n8n-mcp__n8n_get_workflow_structure, mcp__n8n-mcp__n8n_get_workflow_minimal, mcp__n8n-mcp__n8n_update_full_workflow, mcp__n8n-mcp__n8n_update_partial_workflow, mcp__n8n-mcp__n8n_delete_workflow, mcp__n8n-mcp__n8n_list_workflows, mcp__n8n-mcp__n8n_validate_workflow, mcp__n8n-mcp__n8n_trigger_webhook_workflow, mcp__n8n-mcp__n8n_get_execution, mcp__n8n-mcp__n8n_list_executions, mcp__n8n-mcp__n8n_delete_execution, mcp__n8n-mcp__n8n_health_check, mcp__n8n-mcp__n8n_list_available_tools, mcp__n8n-mcp__n8n_diagnostic
+tools: Glob, Grep, Read, WebFetch, TodoWrite, WebSearch, mcp__supabase__create_branch, mcp__supabase__list_branches, mcp__supabase__delete_branch, mcp__supabase__merge_branch, mcp__supabase__reset_branch, mcp__supabase__rebase_branch, mcp__supabase__list_tables, mcp__supabase__list_extensions, mcp__supabase__list_migrations, mcp__supabase__apply_migration, mcp__supabase__execute_sql, mcp__supabase__get_logs, mcp__supabase__get_advisors, mcp__supabase__get_project_url, mcp__supabase__generate_typescript_types, mcp__supabase__search_docs, mcp__supabase__list_edge_functions, mcp__supabase__deploy_edge_function, mcp__n8n-mcp__tools_documentation, mcp__n8n-mcp__search_nodes, mcp__n8n-mcp__get_template, mcp__n8n-mcp__search_templates, mcp__n8n-mcp__validate_workflow, mcp__n8n-mcp__n8n_create_workflow, mcp__n8n-mcp__n8n_get_workflow, mcp__n8n-mcp__n8n_update_full_workflow, mcp__n8n-mcp__n8n_update_partial_workflow, mcp__n8n-mcp__n8n_delete_workflow, mcp__n8n-mcp__n8n_list_workflows, mcp__n8n-mcp__n8n_validate_workflow, mcp__n8n-mcp__n8n_trigger_webhook_workflow, mcp__n8n-mcp__n8n_health_check, mcp__brightdata-mcp__search_engine, mcp__brightdata-mcp__scrape_as_markdown, mcp__brightdata-mcp__search_engine_batch, mcp__brightdata-mcp__scrape_batch, mcp__supabase__get_publishable_keys, mcp__supabase__get_edge_function, mcp__n8n-mcp__get_node, mcp__n8n-mcp__validate_node, mcp__n8n-mcp__n8n_autofix_workflow, mcp__n8n-mcp__n8n_executions, mcp__n8n-mcp__n8n_workflow_versions, mcp__n8n-mcp__n8n_deploy_template, mcp__ide__getDiagnostics, mcp__ide__executeCode
 model: sonnet
 ---
 

.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

.github/workflows/docker-build-n8n.yml

@@ -52,6 +52,9 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 

.github/workflows/release.yml

@@ -311,14 +311,14 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
-      
+
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
           node-version: 20
           cache: 'npm'
           registry-url: 'https://registry.npmjs.org'
-      
+
       - name: Install dependencies
         run: npm ci
       
@@ -396,7 +396,7 @@ jobs:
             npm publish --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-      
+
       - name: Clean up
         if: always()
         run: rm -rf npm-publish-temp

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 (configurable via N8N_MCP_MAX_SESSIONS env var)
+
+**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%

Dockerfile

@@ -13,9 +13,9 @@ COPY tsconfig*.json ./
 RUN --mount=type=cache,target=/root/.npm \
     echo '{}' > package.json && \
     npm install --no-save typescript@^5.8.3 @types/node@^22.15.30 @types/express@^5.0.3 \
-        @modelcontextprotocol/sdk@^1.12.1 dotenv@^16.5.0 express@^5.1.0 axios@^1.10.0 \
+        @modelcontextprotocol/sdk@1.20.1 dotenv@^16.5.0 express@^5.1.0 axios@^1.10.0 \
         n8n-workflow@^1.96.0 uuid@^11.0.5 @types/uuid@^10.0.0 \
-        openai@^4.77.0 zod@^3.24.1 lru-cache@^11.2.1 @supabase/supabase-js@^2.57.4
+        openai@^4.77.0 zod@3.24.1 lru-cache@^11.2.1 @supabase/supabase-js@^2.57.4
 
 # Copy source and build
 COPY src ./src

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,17 +5,17 @@
 [![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.118.1-orange.svg)](https://github.com/n8n-io/n8n)
+[![n8n version](https://img.shields.io/badge/n8n-2.1.5-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 541 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
 
 n8n-MCP serves as a bridge between n8n's workflow automation platform and AI models, enabling them to understand and work with n8n nodes effectively. It provides structured access to:
 
-- 📚 **541 n8n nodes** from both n8n-nodes-base and @n8n/n8n-nodes-langchain
+- 📚 **543 n8n nodes** from both n8n-nodes-base and @n8n/n8n-nodes-langchain
 - 🔧 **Node properties** - 99% coverage with detailed schemas
 - ⚡ **Node operations** - 63.6% coverage of available actions
 - 📄 **Documentation** - 87% coverage from official n8n docs (including AI nodes)
@@ -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)
 
@@ -503,6 +501,9 @@ Complete guide for integrating n8n-MCP with Windsurf using project rules.
 ### [Codex](./docs/CODEX_SETUP.md)
 Complete guide for integrating n8n-MCP with Codex.
 
+### [Antigravity](./docs/ANTIGRAVITY_SETUP.md)
+Complete guide for integrating n8n-MCP with Antigravity.
+
 ## 🎓 Add Claude Skills (Optional)
 
 Supercharge your n8n workflow building with specialized skills that teach AI how to build production-ready workflows!
@@ -524,7 +525,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 +537,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 +548,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 +562,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**
@@ -595,7 +598,7 @@ ALWAYS explicitly configure ALL parameters that control node behavior.
    - `n8n_create_workflow(workflow)` - Deploy
    - `n8n_validate_workflow({id})` - Post-deployment check
    - `n8n_update_partial_workflow({id, operations: [...]})` - Batch updates
-   - `n8n_trigger_webhook_workflow()` - Test webhooks
+   - `n8n_test_workflow({workflowId})` - Test workflow execution
 
 ## Critical Warnings
 
@@ -612,15 +615,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 +631,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 +777,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 +802,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 +864,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 +928,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 +938,111 @@ 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 with auto-fix
 
 #### 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_test_workflow`** - Test/trigger workflow execution:
+  - Auto-detects trigger type (webhook, form, chat) from workflow
+  - Supports custom data, headers, and HTTP methods for webhooks
+  - Chat triggers support message and sessionId for conversations
+- **`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 +1135,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_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_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_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)

dist/config/n8n-api.d.ts

@@ -0,0 +1,15 @@
+export declare function getN8nApiConfig(): {
+    baseUrl: string;
+    apiKey: string;
+    timeout: number;
+    maxRetries: number;
+} | null;
+export declare function isN8nApiConfigured(): boolean;
+export declare function getN8nApiConfigFromContext(context: {
+    n8nApiUrl?: string;
+    n8nApiKey?: string;
+    n8nApiTimeout?: number;
+    n8nApiMaxRetries?: number;
+}): N8nApiConfig | null;
+export type N8nApiConfig = NonNullable<ReturnType<typeof getN8nApiConfig>>;
+//# sourceMappingURL=n8n-api.d.ts.map

dist/config/n8n-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"n8n-api.d.ts","sourceRoot":"","sources":["../../src/config/n8n-api.ts"],"names":[],"mappings":"AAgBA,wBAAgB,eAAe;;;;;SA0B9B;AAGD,wBAAgB,kBAAkB,IAAI,OAAO,CAG5C;AAMD,wBAAgB,0BAA0B,CAAC,OAAO,EAAE;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,GAAG,YAAY,GAAG,IAAI,CAWtB;AAGD,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC"}

dist/config/n8n-api.js

@@ -0,0 +1,53 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getN8nApiConfig = getN8nApiConfig;
+exports.isN8nApiConfigured = isN8nApiConfigured;
+exports.getN8nApiConfigFromContext = getN8nApiConfigFromContext;
+const zod_1 = require("zod");
+const dotenv_1 = __importDefault(require("dotenv"));
+const n8nApiConfigSchema = zod_1.z.object({
+    N8N_API_URL: zod_1.z.string().url().optional(),
+    N8N_API_KEY: zod_1.z.string().min(1).optional(),
+    N8N_API_TIMEOUT: zod_1.z.coerce.number().positive().default(30000),
+    N8N_API_MAX_RETRIES: zod_1.z.coerce.number().positive().default(3),
+});
+let envLoaded = false;
+function getN8nApiConfig() {
+    if (!envLoaded) {
+        dotenv_1.default.config();
+        envLoaded = true;
+    }
+    const result = n8nApiConfigSchema.safeParse(process.env);
+    if (!result.success) {
+        return null;
+    }
+    const config = result.data;
+    if (!config.N8N_API_URL || !config.N8N_API_KEY) {
+        return null;
+    }
+    return {
+        baseUrl: config.N8N_API_URL,
+        apiKey: config.N8N_API_KEY,
+        timeout: config.N8N_API_TIMEOUT,
+        maxRetries: config.N8N_API_MAX_RETRIES,
+    };
+}
+function isN8nApiConfigured() {
+    const config = getN8nApiConfig();
+    return config !== null;
+}
+function getN8nApiConfigFromContext(context) {
+    if (!context.n8nApiUrl || !context.n8nApiKey) {
+        return null;
+    }
+    return {
+        baseUrl: context.n8nApiUrl,
+        apiKey: context.n8nApiKey,
+        timeout: context.n8nApiTimeout ?? 30000,
+        maxRetries: context.n8nApiMaxRetries ?? 3,
+    };
+}
+//# sourceMappingURL=n8n-api.js.map

dist/config/n8n-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"n8n-api.js","sourceRoot":"","sources":["../../src/config/n8n-api.ts"],"names":[],"mappings":";;;;;AAgBA,0CA0BC;AAGD,gDAGC;AAMD,gEAgBC;AAtED,6BAAwB;AACxB,oDAA4B;AAI5B,MAAM,kBAAkB,GAAG,OAAC,CAAC,MAAM,CAAC;IAClC,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACxC,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACzC,eAAe,EAAE,OAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IAC5D,mBAAmB,EAAE,OAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;CAC7D,CAAC,CAAC;AAGH,IAAI,SAAS,GAAG,KAAK,CAAC;AAGtB,SAAgB,eAAe;IAE7B,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,gBAAM,CAAC,MAAM,EAAE,CAAC;QAChB,SAAS,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,MAAM,MAAM,GAAG,kBAAkB,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAEzD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC;IAG3B,IAAI,CAAC,MAAM,CAAC,WAAW,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;QAC/C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO;QACL,OAAO,EAAE,MAAM,CAAC,WAAW;QAC3B,MAAM,EAAE,MAAM,CAAC,WAAW;QAC1B,OAAO,EAAE,MAAM,CAAC,eAAe;QAC/B,UAAU,EAAE,MAAM,CAAC,mBAAmB;KACvC,CAAC;AACJ,CAAC;AAGD,SAAgB,kBAAkB;IAChC,MAAM,MAAM,GAAG,eAAe,EAAE,CAAC;IACjC,OAAO,MAAM,KAAK,IAAI,CAAC;AACzB,CAAC;AAMD,SAAgB,0BAA0B,CAAC,OAK1C;IACC,IAAI,CAAC,OAAO,CAAC,SAAS,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;QAC7C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO;QACL,OAAO,EAAE,OAAO,CAAC,SAAS;QAC1B,MAAM,EAAE,OAAO,CAAC,SAAS;QACzB,OAAO,EAAE,OAAO,CAAC,aAAa,IAAI,KAAK;QACvC,UAAU,EAAE,OAAO,CAAC,gBAAgB,IAAI,CAAC;KAC1C,CAAC;AACJ,CAAC"}

dist/constants/type-structures.d.ts

@@ -0,0 +1,123 @@
+import type { NodePropertyTypes } from 'n8n-workflow';
+import type { TypeStructure } from '../types/type-structures';
+export declare const TYPE_STRUCTURES: Record<NodePropertyTypes, TypeStructure>;
+export declare const COMPLEX_TYPE_EXAMPLES: {
+    collection: {
+        basic: {
+            name: string;
+            email: string;
+        };
+        nested: {
+            user: {
+                firstName: string;
+                lastName: string;
+            };
+            preferences: {
+                theme: string;
+                notifications: boolean;
+            };
+        };
+        withExpressions: {
+            id: string;
+            timestamp: string;
+            data: string;
+        };
+    };
+    fixedCollection: {
+        httpHeaders: {
+            headers: {
+                name: string;
+                value: string;
+            }[];
+        };
+        queryParameters: {
+            queryParameters: {
+                name: string;
+                value: string;
+            }[];
+        };
+        multipleCollections: {
+            headers: {
+                name: string;
+                value: string;
+            }[];
+            queryParameters: {
+                name: string;
+                value: string;
+            }[];
+        };
+    };
+    filter: {
+        simple: {
+            conditions: {
+                id: string;
+                leftValue: string;
+                operator: {
+                    type: string;
+                    operation: string;
+                };
+                rightValue: string;
+            }[];
+            combinator: string;
+        };
+        complex: {
+            conditions: ({
+                id: string;
+                leftValue: string;
+                operator: {
+                    type: string;
+                    operation: string;
+                };
+                rightValue: number;
+            } | {
+                id: string;
+                leftValue: string;
+                operator: {
+                    type: string;
+                    operation: string;
+                };
+                rightValue: string;
+            })[];
+            combinator: string;
+        };
+    };
+    resourceMapper: {
+        autoMap: {
+            mappingMode: string;
+            value: {};
+        };
+        manual: {
+            mappingMode: string;
+            value: {
+                firstName: string;
+                lastName: string;
+                email: string;
+                status: string;
+            };
+        };
+    };
+    assignmentCollection: {
+        basic: {
+            assignments: {
+                id: string;
+                name: string;
+                value: string;
+                type: string;
+            }[];
+        };
+        multiple: {
+            assignments: ({
+                id: string;
+                name: string;
+                value: string;
+                type: string;
+            } | {
+                id: string;
+                name: string;
+                value: boolean;
+                type: string;
+            })[];
+        };
+    };
+};
+//# sourceMappingURL=type-structures.d.ts.map

dist/constants/type-structures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-structures.d.ts","sourceRoot":"","sources":["../../src/constants/type-structures.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAe9D,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,iBAAiB,EAAE,aAAa,CAilBpE,CAAC;AAUF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4GjC,CAAC"}

dist/constants/type-structures.js

@@ -0,0 +1,654 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMPLEX_TYPE_EXAMPLES = exports.TYPE_STRUCTURES = void 0;
+exports.TYPE_STRUCTURES = {
+    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'],
+    },
+    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: {
+        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',
+        ],
+    },
+    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',
+        ],
+    },
+    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',
+        ],
+    },
+    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'],
+    },
+    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',
+        ],
+    },
+};
+exports.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' },
+            ],
+        },
+    },
+};
+//# sourceMappingURL=type-structures.js.map

dist/database/database-adapter.d.ts

@@ -0,0 +1,33 @@
+export interface DatabaseAdapter {
+    prepare(sql: string): PreparedStatement;
+    exec(sql: string): void;
+    close(): void;
+    pragma(key: string, value?: any): any;
+    readonly inTransaction: boolean;
+    transaction<T>(fn: () => T): T;
+    checkFTS5Support(): boolean;
+}
+export interface PreparedStatement {
+    run(...params: any[]): RunResult;
+    get(...params: any[]): any;
+    all(...params: any[]): any[];
+    iterate(...params: any[]): IterableIterator<any>;
+    pluck(toggle?: boolean): this;
+    expand(toggle?: boolean): this;
+    raw(toggle?: boolean): this;
+    columns(): ColumnDefinition[];
+    bind(...params: any[]): this;
+}
+export interface RunResult {
+    changes: number;
+    lastInsertRowid: number | bigint;
+}
+export interface ColumnDefinition {
+    name: string;
+    column: string | null;
+    table: string | null;
+    database: string | null;
+    type: string | null;
+}
+export declare function createDatabaseAdapter(dbPath: string): Promise<DatabaseAdapter>;
+//# sourceMappingURL=database-adapter.d.ts.map

dist/database/database-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-adapter.d.ts","sourceRoot":"","sources":["../../src/database/database-adapter.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAAC;IACxC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,IAAI,IAAI,CAAC;IACd,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,GAAG,GAAG,CAAC;IACtC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IAC/B,gBAAgB,IAAI,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,GAAG,MAAM,EAAE,GAAG,EAAE,GAAG,SAAS,CAAC;IACjC,GAAG,CAAC,GAAG,MAAM,EAAE,GAAG,EAAE,GAAG,GAAG,CAAC;IAC3B,GAAG,CAAC,GAAG,MAAM,EAAE,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC;IAC7B,OAAO,CAAC,GAAG,MAAM,EAAE,GAAG,EAAE,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACjD,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/B,GAAG,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5B,OAAO,IAAI,gBAAgB,EAAE,CAAC;IAC9B,IAAI,CAAC,GAAG,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,GAAG,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAMD,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAoDpF"}

dist/database/database-adapter.js

@@ -0,0 +1,420 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDatabaseAdapter = createDatabaseAdapter;
+const fs_1 = require("fs");
+const fsSync = __importStar(require("fs"));
+const path_1 = __importDefault(require("path"));
+const logger_1 = require("../utils/logger");
+async function createDatabaseAdapter(dbPath) {
+    if (process.env.MCP_MODE !== 'stdio') {
+        logger_1.logger.info(`Node.js version: ${process.version}`);
+    }
+    if (process.env.MCP_MODE !== 'stdio') {
+        logger_1.logger.info(`Platform: ${process.platform} ${process.arch}`);
+    }
+    try {
+        if (process.env.MCP_MODE !== 'stdio') {
+            logger_1.logger.info('Attempting to use better-sqlite3...');
+        }
+        const adapter = await createBetterSQLiteAdapter(dbPath);
+        if (process.env.MCP_MODE !== 'stdio') {
+            logger_1.logger.info('Successfully initialized better-sqlite3 adapter');
+        }
+        return adapter;
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        if (errorMessage.includes('NODE_MODULE_VERSION') || errorMessage.includes('was compiled against a different Node.js version')) {
+            if (process.env.MCP_MODE !== 'stdio') {
+                logger_1.logger.warn(`Node.js version mismatch detected. Better-sqlite3 was compiled for a different Node.js version.`);
+            }
+            if (process.env.MCP_MODE !== 'stdio') {
+                logger_1.logger.warn(`Current Node.js version: ${process.version}`);
+            }
+        }
+        if (process.env.MCP_MODE !== 'stdio') {
+            logger_1.logger.warn('Failed to initialize better-sqlite3, falling back to sql.js', error);
+        }
+        try {
+            const adapter = await createSQLJSAdapter(dbPath);
+            if (process.env.MCP_MODE !== 'stdio') {
+                logger_1.logger.info('Successfully initialized sql.js adapter (pure JavaScript, no native dependencies)');
+            }
+            return adapter;
+        }
+        catch (sqlJsError) {
+            if (process.env.MCP_MODE !== 'stdio') {
+                logger_1.logger.error('Failed to initialize sql.js adapter', sqlJsError);
+            }
+            throw new Error('Failed to initialize any database adapter');
+        }
+    }
+}
+async function createBetterSQLiteAdapter(dbPath) {
+    try {
+        const Database = require('better-sqlite3');
+        const db = new Database(dbPath);
+        return new BetterSQLiteAdapter(db);
+    }
+    catch (error) {
+        throw new Error(`Failed to create better-sqlite3 adapter: ${error}`);
+    }
+}
+async function createSQLJSAdapter(dbPath) {
+    let initSqlJs;
+    try {
+        initSqlJs = require('sql.js');
+    }
+    catch (error) {
+        logger_1.logger.error('Failed to load sql.js module:', error);
+        throw new Error('sql.js module not found. This might be an issue with npm package installation.');
+    }
+    const SQL = await initSqlJs({
+        locateFile: (file) => {
+            if (file.endsWith('.wasm')) {
+                const possiblePaths = [
+                    path_1.default.join(__dirname, '../../node_modules/sql.js/dist/', file),
+                    path_1.default.join(__dirname, '../../../sql.js/dist/', file),
+                    path_1.default.join(process.cwd(), 'node_modules/sql.js/dist/', file),
+                    path_1.default.join(path_1.default.dirname(require.resolve('sql.js')), '../dist/', file)
+                ];
+                for (const tryPath of possiblePaths) {
+                    if (fsSync.existsSync(tryPath)) {
+                        if (process.env.MCP_MODE !== 'stdio') {
+                            logger_1.logger.debug(`Found WASM file at: ${tryPath}`);
+                        }
+                        return tryPath;
+                    }
+                }
+                try {
+                    const wasmPath = require.resolve('sql.js/dist/sql-wasm.wasm');
+                    if (process.env.MCP_MODE !== 'stdio') {
+                        logger_1.logger.debug(`Found WASM file via require.resolve: ${wasmPath}`);
+                    }
+                    return wasmPath;
+                }
+                catch (e) {
+                    logger_1.logger.warn(`Could not find WASM file, using default path: ${file}`);
+                    return file;
+                }
+            }
+            return file;
+        }
+    });
+    let db;
+    try {
+        const data = await fs_1.promises.readFile(dbPath);
+        db = new SQL.Database(new Uint8Array(data));
+        logger_1.logger.info(`Loaded existing database from ${dbPath}`);
+    }
+    catch (error) {
+        db = new SQL.Database();
+        logger_1.logger.info(`Created new database at ${dbPath}`);
+    }
+    return new SQLJSAdapter(db, dbPath);
+}
+class BetterSQLiteAdapter {
+    constructor(db) {
+        this.db = db;
+    }
+    prepare(sql) {
+        const stmt = this.db.prepare(sql);
+        return new BetterSQLiteStatement(stmt);
+    }
+    exec(sql) {
+        this.db.exec(sql);
+    }
+    close() {
+        this.db.close();
+    }
+    pragma(key, value) {
+        return this.db.pragma(key, value);
+    }
+    get inTransaction() {
+        return this.db.inTransaction;
+    }
+    transaction(fn) {
+        return this.db.transaction(fn)();
+    }
+    checkFTS5Support() {
+        try {
+            this.exec("CREATE VIRTUAL TABLE IF NOT EXISTS test_fts5 USING fts5(content);");
+            this.exec("DROP TABLE IF EXISTS test_fts5;");
+            return true;
+        }
+        catch (error) {
+            return false;
+        }
+    }
+}
+class SQLJSAdapter {
+    constructor(db, dbPath) {
+        this.db = db;
+        this.dbPath = dbPath;
+        this.saveTimer = null;
+        this.closed = false;
+        const envInterval = process.env.SQLJS_SAVE_INTERVAL_MS;
+        this.saveIntervalMs = envInterval ? parseInt(envInterval, 10) : SQLJSAdapter.DEFAULT_SAVE_INTERVAL_MS;
+        if (isNaN(this.saveIntervalMs) || this.saveIntervalMs < 100 || this.saveIntervalMs > 60000) {
+            logger_1.logger.warn(`Invalid SQLJS_SAVE_INTERVAL_MS value: ${envInterval} (must be 100-60000ms), ` +
+                `using default ${SQLJSAdapter.DEFAULT_SAVE_INTERVAL_MS}ms`);
+            this.saveIntervalMs = SQLJSAdapter.DEFAULT_SAVE_INTERVAL_MS;
+        }
+        logger_1.logger.debug(`SQLJSAdapter initialized with save interval: ${this.saveIntervalMs}ms`);
+    }
+    prepare(sql) {
+        const stmt = this.db.prepare(sql);
+        return new SQLJSStatement(stmt, () => this.scheduleSave());
+    }
+    exec(sql) {
+        this.db.exec(sql);
+        this.scheduleSave();
+    }
+    close() {
+        if (this.closed) {
+            logger_1.logger.debug('SQLJSAdapter already closed, skipping');
+            return;
+        }
+        this.saveToFile();
+        if (this.saveTimer) {
+            clearTimeout(this.saveTimer);
+            this.saveTimer = null;
+        }
+        this.db.close();
+        this.closed = true;
+    }
+    pragma(key, value) {
+        if (key === 'journal_mode' && value === 'WAL') {
+            return 'memory';
+        }
+        return null;
+    }
+    get inTransaction() {
+        return false;
+    }
+    transaction(fn) {
+        try {
+            this.exec('BEGIN');
+            const result = fn();
+            this.exec('COMMIT');
+            return result;
+        }
+        catch (error) {
+            this.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    checkFTS5Support() {
+        try {
+            this.exec("CREATE VIRTUAL TABLE IF NOT EXISTS test_fts5 USING fts5(content);");
+            this.exec("DROP TABLE IF EXISTS test_fts5;");
+            return true;
+        }
+        catch (error) {
+            return false;
+        }
+    }
+    scheduleSave() {
+        if (this.saveTimer) {
+            clearTimeout(this.saveTimer);
+        }
+        this.saveTimer = setTimeout(() => {
+            this.saveToFile();
+        }, this.saveIntervalMs);
+    }
+    saveToFile() {
+        try {
+            const data = this.db.export();
+            fsSync.writeFileSync(this.dbPath, data);
+            logger_1.logger.debug(`Database saved to ${this.dbPath}`);
+        }
+        catch (error) {
+            logger_1.logger.error('Failed to save database', error);
+        }
+    }
+}
+SQLJSAdapter.DEFAULT_SAVE_INTERVAL_MS = 5000;
+class BetterSQLiteStatement {
+    constructor(stmt) {
+        this.stmt = stmt;
+    }
+    run(...params) {
+        return this.stmt.run(...params);
+    }
+    get(...params) {
+        return this.stmt.get(...params);
+    }
+    all(...params) {
+        return this.stmt.all(...params);
+    }
+    iterate(...params) {
+        return this.stmt.iterate(...params);
+    }
+    pluck(toggle) {
+        this.stmt.pluck(toggle);
+        return this;
+    }
+    expand(toggle) {
+        this.stmt.expand(toggle);
+        return this;
+    }
+    raw(toggle) {
+        this.stmt.raw(toggle);
+        return this;
+    }
+    columns() {
+        return this.stmt.columns();
+    }
+    bind(...params) {
+        this.stmt.bind(...params);
+        return this;
+    }
+}
+class SQLJSStatement {
+    constructor(stmt, onModify) {
+        this.stmt = stmt;
+        this.onModify = onModify;
+        this.boundParams = null;
+    }
+    run(...params) {
+        try {
+            if (params.length > 0) {
+                this.bindParams(params);
+                if (this.boundParams) {
+                    this.stmt.bind(this.boundParams);
+                }
+            }
+            this.stmt.run();
+            this.onModify();
+            return {
+                changes: 1,
+                lastInsertRowid: 0
+            };
+        }
+        catch (error) {
+            this.stmt.reset();
+            throw error;
+        }
+    }
+    get(...params) {
+        try {
+            if (params.length > 0) {
+                this.bindParams(params);
+                if (this.boundParams) {
+                    this.stmt.bind(this.boundParams);
+                }
+            }
+            if (this.stmt.step()) {
+                const result = this.stmt.getAsObject();
+                this.stmt.reset();
+                return this.convertIntegerColumns(result);
+            }
+            this.stmt.reset();
+            return undefined;
+        }
+        catch (error) {
+            this.stmt.reset();
+            throw error;
+        }
+    }
+    all(...params) {
+        try {
+            if (params.length > 0) {
+                this.bindParams(params);
+                if (this.boundParams) {
+                    this.stmt.bind(this.boundParams);
+                }
+            }
+            const results = [];
+            while (this.stmt.step()) {
+                results.push(this.convertIntegerColumns(this.stmt.getAsObject()));
+            }
+            this.stmt.reset();
+            return results;
+        }
+        catch (error) {
+            this.stmt.reset();
+            throw error;
+        }
+    }
+    iterate(...params) {
+        return this.all(...params)[Symbol.iterator]();
+    }
+    pluck(toggle) {
+        return this;
+    }
+    expand(toggle) {
+        return this;
+    }
+    raw(toggle) {
+        return this;
+    }
+    columns() {
+        return [];
+    }
+    bind(...params) {
+        this.bindParams(params);
+        return this;
+    }
+    bindParams(params) {
+        if (params.length === 0) {
+            this.boundParams = null;
+            return;
+        }
+        if (params.length === 1 && typeof params[0] === 'object' && !Array.isArray(params[0]) && params[0] !== null) {
+            this.boundParams = params[0];
+        }
+        else {
+            this.boundParams = params.map(p => p === undefined ? null : p);
+        }
+    }
+    convertIntegerColumns(row) {
+        if (!row)
+            return row;
+        const integerColumns = ['is_ai_tool', 'is_trigger', 'is_webhook', 'is_versioned'];
+        const converted = { ...row };
+        for (const col of integerColumns) {
+            if (col in converted && typeof converted[col] === 'string') {
+                converted[col] = parseInt(converted[col], 10);
+            }
+        }
+        return converted;
+    }
+}
+//# sourceMappingURL=database-adapter.js.map

dist/database/node-repository.d.ts

@@ -0,0 +1,95 @@
+import { DatabaseAdapter } from './database-adapter';
+import { ParsedNode } from '../parsers/node-parser';
+import { SQLiteStorageService } from '../services/sqlite-storage-service';
+export declare class NodeRepository {
+    private db;
+    constructor(dbOrService: DatabaseAdapter | SQLiteStorageService);
+    saveNode(node: ParsedNode): void;
+    getNode(nodeType: string): any;
+    getAITools(): any[];
+    private safeJsonParse;
+    upsertNode(node: ParsedNode): void;
+    getNodeByType(nodeType: string): any;
+    getNodesByCategory(category: string): any[];
+    searchNodes(query: string, mode?: 'OR' | 'AND' | 'FUZZY', limit?: number): any[];
+    getAllNodes(limit?: number): any[];
+    getNodeCount(): number;
+    getAIToolNodes(): any[];
+    getToolVariant(baseNodeType: string): any | null;
+    getBaseNodeForToolVariant(toolNodeType: string): any | null;
+    getToolVariants(): any[];
+    getToolVariantCount(): number;
+    getNodesByPackage(packageName: string): any[];
+    searchNodeProperties(nodeType: string, query: string, maxResults?: number): any[];
+    private parseNodeRow;
+    getNodeOperations(nodeType: string, resource?: string): any[];
+    getNodeResources(nodeType: string): any[];
+    getOperationsForResource(nodeType: string, resource: string): any[];
+    getAllOperations(): Map<string, any[]>;
+    getAllResources(): Map<string, any[]>;
+    getNodePropertyDefaults(nodeType: string): Record<string, any>;
+    getDefaultOperationForResource(nodeType: string, resource?: string): string | undefined;
+    saveNodeVersion(versionData: {
+        nodeType: string;
+        version: string;
+        packageName: string;
+        displayName: string;
+        description?: string;
+        category?: string;
+        isCurrentMax?: boolean;
+        propertiesSchema?: any;
+        operations?: any;
+        credentialsRequired?: any;
+        outputs?: any;
+        minimumN8nVersion?: string;
+        breakingChanges?: any[];
+        deprecatedProperties?: string[];
+        addedProperties?: string[];
+        releasedAt?: Date;
+    }): void;
+    getNodeVersions(nodeType: string): any[];
+    getLatestNodeVersion(nodeType: string): any | null;
+    getNodeVersion(nodeType: string, version: string): any | null;
+    savePropertyChange(changeData: {
+        nodeType: string;
+        fromVersion: string;
+        toVersion: string;
+        propertyName: string;
+        changeType: 'added' | 'removed' | 'renamed' | 'type_changed' | 'requirement_changed' | 'default_changed';
+        isBreaking?: boolean;
+        oldValue?: string;
+        newValue?: string;
+        migrationHint?: string;
+        autoMigratable?: boolean;
+        migrationStrategy?: any;
+        severity?: 'LOW' | 'MEDIUM' | 'HIGH';
+    }): void;
+    getPropertyChanges(nodeType: string, fromVersion: string, toVersion: string): any[];
+    getBreakingChanges(nodeType: string, fromVersion: string, toVersion?: string): any[];
+    getAutoMigratableChanges(nodeType: string, fromVersion: string, toVersion: string): any[];
+    hasVersionUpgradePath(nodeType: string, fromVersion: string, toVersion: string): boolean;
+    getVersionedNodesCount(): number;
+    private parseNodeVersionRow;
+    private parsePropertyChangeRow;
+    createWorkflowVersion(data: {
+        workflowId: string;
+        versionNumber: number;
+        workflowName: string;
+        workflowSnapshot: any;
+        trigger: 'partial_update' | 'full_update' | 'autofix';
+        operations?: any[];
+        fixTypes?: string[];
+        metadata?: any;
+    }): number;
+    getWorkflowVersions(workflowId: string, limit?: number): any[];
+    getWorkflowVersion(versionId: number): any | null;
+    getLatestWorkflowVersion(workflowId: string): any | null;
+    deleteWorkflowVersion(versionId: number): void;
+    deleteWorkflowVersionsByWorkflowId(workflowId: string): number;
+    pruneWorkflowVersions(workflowId: string, keepCount: number): number;
+    truncateWorkflowVersions(): number;
+    getWorkflowVersionCount(workflowId: string): number;
+    getVersionStorageStats(): any;
+    private parseWorkflowVersionRow;
+}
+//# sourceMappingURL=node-repository.d.ts.map

dist/database/node-repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-repository.d.ts","sourceRoot":"","sources":["../../src/database/node-repository.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAG1E,qBAAa,cAAc;IACzB,OAAO,CAAC,EAAE,CAAkB;gBAEhB,WAAW,EAAE,eAAe,GAAG,oBAAoB;IAY/D,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAwChC,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,GAAG;IA2B9B,UAAU,IAAI,GAAG,EAAE;IAgBnB,OAAO,CAAC,aAAa;IASrB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAIlC,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,GAAG;IAIpC,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,GAAG,EAAE;IAqB3C,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,IAAI,GAAG,KAAK,GAAG,OAAc,EAAE,KAAK,GAAE,MAAW,GAAG,GAAG,EAAE;IAwC1F,WAAW,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,GAAG,EAAE;IAUlC,YAAY,IAAI,MAAM;IAKtB,cAAc,IAAI,GAAG,EAAE;IAOvB,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI;IAYhD,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI;IAY3D,eAAe,IAAI,GAAG,EAAE;IAoBxB,mBAAmB,IAAI,MAAM;IAK7B,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,GAAG,EAAE;IAS7C,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,GAAE,MAAW,GAAG,GAAG,EAAE;IAmCrF,OAAO,CAAC,YAAY;IA4BpB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,GAAG,EAAE;IAmD7D,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,GAAG,EAAE;IAmBzC,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,GAAG,EAAE;IAyBnE,gBAAgB,IAAI,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC;IAiBtC,eAAe,IAAI,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC;IAiBrC,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAwB9D,8BAA8B,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAuDvF,eAAe,CAAC,WAAW,EAAE;QAC3B,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,gBAAgB,CAAC,EAAE,GAAG,CAAC;QACvB,UAAU,CAAC,EAAE,GAAG,CAAC;QACjB,mBAAmB,CAAC,EAAE,GAAG,CAAC;QAC1B,OAAO,CAAC,EAAE,GAAG,CAAC;QACd,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,eAAe,CAAC,EAAE,GAAG,EAAE,CAAC;QACxB,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;QAChC,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;QAC3B,UAAU,CAAC,EAAE,IAAI,CAAC;KACnB,GAAG,IAAI;IAkCR,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,GAAG,EAAE;IAexC,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI;IAgBlD,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI;IAe7D,kBAAkB,CAAC,UAAU,EAAE;QAC7B,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,UAAU,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,cAAc,GAAG,qBAAqB,GAAG,iBAAiB,CAAC;QACzG,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,iBAAiB,CAAC,EAAE,GAAG,CAAC;QACxB,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;KACtC,GAAG,IAAI;IA4BR,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,GAAG,EAAE;IAgBnF,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,GAAG,EAAE;IA4BpF,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,GAAG,EAAE;IAkBzF,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAcxF,sBAAsB,IAAI,MAAM;IAWhC,OAAO,CAAC,mBAAmB;IA0B3B,OAAO,CAAC,sBAAsB;IA0B9B,qBAAqB,CAAC,IAAI,EAAE;QAC1B,UAAU,EAAE,MAAM,CAAC;QACnB,aAAa,EAAE,MAAM,CAAC;QACtB,YAAY,EAAE,MAAM,CAAC;QACrB,gBAAgB,EAAE,GAAG,CAAC;QACtB,OAAO,EAAE,gBAAgB,GAAG,aAAa,GAAG,SAAS,CAAC;QACtD,UAAU,CAAC,EAAE,GAAG,EAAE,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,QAAQ,CAAC,EAAE,GAAG,CAAC;KAChB,GAAG,MAAM;IAyBV,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,GAAG,EAAE;IAoB9D,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI;IAYjD,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI;IAexD,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAS9C,kCAAkC,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IAY9D,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IAiCpE,wBAAwB,IAAI,MAAM;IAWlC,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IAWnD,sBAAsB,IAAI,GAAG;IAwC7B,OAAO,CAAC,uBAAuB;CAchC"}

dist/database/node-repository.js

@@ -0,0 +1,641 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeRepository = void 0;
+const sqlite_storage_service_1 = require("../services/sqlite-storage-service");
+const node_type_normalizer_1 = require("../utils/node-type-normalizer");
+class NodeRepository {
+    constructor(dbOrService) {
+        if (dbOrService instanceof sqlite_storage_service_1.SQLiteStorageService) {
+            this.db = dbOrService.db;
+            return;
+        }
+        this.db = dbOrService;
+    }
+    saveNode(node) {
+        const stmt = this.db.prepare(`
+      INSERT OR REPLACE INTO nodes (
+        node_type, package_name, display_name, description,
+        category, development_style, is_ai_tool, is_trigger,
+        is_webhook, is_versioned, is_tool_variant, tool_variant_of,
+        has_tool_variant, version, documentation,
+        properties_schema, operations, credentials_required,
+        outputs, output_names
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+        stmt.run(node.nodeType, node.packageName, node.displayName, node.description, node.category, node.style, node.isAITool ? 1 : 0, node.isTrigger ? 1 : 0, node.isWebhook ? 1 : 0, node.isVersioned ? 1 : 0, node.isToolVariant ? 1 : 0, node.toolVariantOf || null, node.hasToolVariant ? 1 : 0, node.version, node.documentation || null, JSON.stringify(node.properties, null, 2), JSON.stringify(node.operations, null, 2), JSON.stringify(node.credentials, null, 2), node.outputs ? JSON.stringify(node.outputs, null, 2) : null, node.outputNames ? JSON.stringify(node.outputNames, null, 2) : null);
+    }
+    getNode(nodeType) {
+        const normalizedType = node_type_normalizer_1.NodeTypeNormalizer.normalizeToFullForm(nodeType);
+        const row = this.db.prepare(`
+      SELECT * FROM nodes WHERE node_type = ?
+    `).get(normalizedType);
+        if (!row && normalizedType !== nodeType) {
+            const originalRow = this.db.prepare(`
+        SELECT * FROM nodes WHERE node_type = ?
+      `).get(nodeType);
+            if (originalRow) {
+                return this.parseNodeRow(originalRow);
+            }
+        }
+        if (!row)
+            return null;
+        return this.parseNodeRow(row);
+    }
+    getAITools() {
+        const rows = this.db.prepare(`
+      SELECT node_type, display_name, description, package_name
+      FROM nodes 
+      WHERE is_ai_tool = 1
+      ORDER BY display_name
+    `).all();
+        return rows.map(row => ({
+            nodeType: row.node_type,
+            displayName: row.display_name,
+            description: row.description,
+            package: row.package_name
+        }));
+    }
+    safeJsonParse(json, defaultValue) {
+        try {
+            return JSON.parse(json);
+        }
+        catch {
+            return defaultValue;
+        }
+    }
+    upsertNode(node) {
+        this.saveNode(node);
+    }
+    getNodeByType(nodeType) {
+        return this.getNode(nodeType);
+    }
+    getNodesByCategory(category) {
+        const rows = this.db.prepare(`
+      SELECT * FROM nodes WHERE category = ?
+      ORDER BY display_name
+    `).all(category);
+        return rows.map(row => this.parseNodeRow(row));
+    }
+    searchNodes(query, mode = 'OR', limit = 20) {
+        let sql = '';
+        const params = [];
+        if (mode === 'FUZZY') {
+            sql = `
+        SELECT * FROM nodes 
+        WHERE node_type LIKE ? OR display_name LIKE ? OR description LIKE ?
+        ORDER BY display_name
+        LIMIT ?
+      `;
+            const fuzzyQuery = `%${query}%`;
+            params.push(fuzzyQuery, fuzzyQuery, fuzzyQuery, limit);
+        }
+        else {
+            const words = query.split(/\s+/).filter(w => w.length > 0);
+            const conditions = words.map(() => '(node_type LIKE ? OR display_name LIKE ? OR description LIKE ?)');
+            const operator = mode === 'AND' ? ' AND ' : ' OR ';
+            sql = `
+        SELECT * FROM nodes 
+        WHERE ${conditions.join(operator)}
+        ORDER BY display_name
+        LIMIT ?
+      `;
+            for (const word of words) {
+                const searchTerm = `%${word}%`;
+                params.push(searchTerm, searchTerm, searchTerm);
+            }
+            params.push(limit);
+        }
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map(row => this.parseNodeRow(row));
+    }
+    getAllNodes(limit) {
+        let sql = 'SELECT * FROM nodes ORDER BY display_name';
+        if (limit) {
+            sql += ` LIMIT ${limit}`;
+        }
+        const rows = this.db.prepare(sql).all();
+        return rows.map(row => this.parseNodeRow(row));
+    }
+    getNodeCount() {
+        const result = this.db.prepare('SELECT COUNT(*) as count FROM nodes').get();
+        return result.count;
+    }
+    getAIToolNodes() {
+        return this.getAITools();
+    }
+    getToolVariant(baseNodeType) {
+        if (!baseNodeType || typeof baseNodeType !== 'string' || !baseNodeType.includes('.')) {
+            return null;
+        }
+        const toolNodeType = `${baseNodeType}Tool`;
+        return this.getNode(toolNodeType);
+    }
+    getBaseNodeForToolVariant(toolNodeType) {
+        const row = this.db.prepare(`
+      SELECT tool_variant_of FROM nodes WHERE node_type = ?
+    `).get(toolNodeType);
+        if (!row?.tool_variant_of)
+            return null;
+        return this.getNode(row.tool_variant_of);
+    }
+    getToolVariants() {
+        const rows = this.db.prepare(`
+      SELECT node_type, display_name, description, package_name, tool_variant_of
+      FROM nodes
+      WHERE is_tool_variant = 1
+      ORDER BY display_name
+    `).all();
+        return rows.map(row => ({
+            nodeType: row.node_type,
+            displayName: row.display_name,
+            description: row.description,
+            package: row.package_name,
+            toolVariantOf: row.tool_variant_of
+        }));
+    }
+    getToolVariantCount() {
+        const result = this.db.prepare('SELECT COUNT(*) as count FROM nodes WHERE is_tool_variant = 1').get();
+        return result.count;
+    }
+    getNodesByPackage(packageName) {
+        const rows = this.db.prepare(`
+      SELECT * FROM nodes WHERE package_name = ?
+      ORDER BY display_name
+    `).all(packageName);
+        return rows.map(row => this.parseNodeRow(row));
+    }
+    searchNodeProperties(nodeType, query, maxResults = 20) {
+        const node = this.getNode(nodeType);
+        if (!node || !node.properties)
+            return [];
+        const results = [];
+        const searchLower = query.toLowerCase();
+        function searchProperties(properties, path = []) {
+            for (const prop of properties) {
+                if (results.length >= maxResults)
+                    break;
+                const currentPath = [...path, prop.name || prop.displayName];
+                const pathString = currentPath.join('.');
+                if (prop.name?.toLowerCase().includes(searchLower) ||
+                    prop.displayName?.toLowerCase().includes(searchLower) ||
+                    prop.description?.toLowerCase().includes(searchLower)) {
+                    results.push({
+                        path: pathString,
+                        property: prop,
+                        description: prop.description
+                    });
+                }
+                if (prop.options) {
+                    searchProperties(prop.options, currentPath);
+                }
+            }
+        }
+        searchProperties(node.properties);
+        return results;
+    }
+    parseNodeRow(row) {
+        return {
+            nodeType: row.node_type,
+            displayName: row.display_name,
+            description: row.description,
+            category: row.category,
+            developmentStyle: row.development_style,
+            package: row.package_name,
+            isAITool: Number(row.is_ai_tool) === 1,
+            isTrigger: Number(row.is_trigger) === 1,
+            isWebhook: Number(row.is_webhook) === 1,
+            isVersioned: Number(row.is_versioned) === 1,
+            isToolVariant: Number(row.is_tool_variant) === 1,
+            toolVariantOf: row.tool_variant_of || null,
+            hasToolVariant: Number(row.has_tool_variant) === 1,
+            version: row.version,
+            properties: this.safeJsonParse(row.properties_schema, []),
+            operations: this.safeJsonParse(row.operations, []),
+            credentials: this.safeJsonParse(row.credentials_required, []),
+            hasDocumentation: !!row.documentation,
+            outputs: row.outputs ? this.safeJsonParse(row.outputs, null) : null,
+            outputNames: row.output_names ? this.safeJsonParse(row.output_names, null) : null
+        };
+    }
+    getNodeOperations(nodeType, resource) {
+        const node = this.getNode(nodeType);
+        if (!node)
+            return [];
+        const operations = [];
+        if (node.operations) {
+            if (Array.isArray(node.operations)) {
+                operations.push(...node.operations);
+            }
+            else if (typeof node.operations === 'object') {
+                if (resource && node.operations[resource]) {
+                    return node.operations[resource];
+                }
+                else {
+                    Object.values(node.operations).forEach(ops => {
+                        if (Array.isArray(ops)) {
+                            operations.push(...ops);
+                        }
+                    });
+                }
+            }
+        }
+        if (node.properties && Array.isArray(node.properties)) {
+            for (const prop of node.properties) {
+                if (prop.name === 'operation' && prop.options) {
+                    if (resource && prop.displayOptions?.show?.resource) {
+                        const allowedResources = Array.isArray(prop.displayOptions.show.resource)
+                            ? prop.displayOptions.show.resource
+                            : [prop.displayOptions.show.resource];
+                        if (!allowedResources.includes(resource)) {
+                            continue;
+                        }
+                    }
+                    operations.push(...prop.options);
+                }
+            }
+        }
+        return operations;
+    }
+    getNodeResources(nodeType) {
+        const node = this.getNode(nodeType);
+        if (!node || !node.properties)
+            return [];
+        const resources = [];
+        for (const prop of node.properties) {
+            if (prop.name === 'resource' && prop.options) {
+                resources.push(...prop.options);
+            }
+        }
+        return resources;
+    }
+    getOperationsForResource(nodeType, resource) {
+        const node = this.getNode(nodeType);
+        if (!node || !node.properties)
+            return [];
+        const operations = [];
+        for (const prop of node.properties) {
+            if (prop.name === 'operation' && prop.displayOptions?.show?.resource) {
+                const allowedResources = Array.isArray(prop.displayOptions.show.resource)
+                    ? prop.displayOptions.show.resource
+                    : [prop.displayOptions.show.resource];
+                if (allowedResources.includes(resource) && prop.options) {
+                    operations.push(...prop.options);
+                }
+            }
+        }
+        return operations;
+    }
+    getAllOperations() {
+        const allOperations = new Map();
+        const nodes = this.getAllNodes();
+        for (const node of nodes) {
+            const operations = this.getNodeOperations(node.nodeType);
+            if (operations.length > 0) {
+                allOperations.set(node.nodeType, operations);
+            }
+        }
+        return allOperations;
+    }
+    getAllResources() {
+        const allResources = new Map();
+        const nodes = this.getAllNodes();
+        for (const node of nodes) {
+            const resources = this.getNodeResources(node.nodeType);
+            if (resources.length > 0) {
+                allResources.set(node.nodeType, resources);
+            }
+        }
+        return allResources;
+    }
+    getNodePropertyDefaults(nodeType) {
+        try {
+            const node = this.getNode(nodeType);
+            if (!node || !node.properties)
+                return {};
+            const defaults = {};
+            for (const prop of node.properties) {
+                if (prop.name && prop.default !== undefined) {
+                    defaults[prop.name] = prop.default;
+                }
+            }
+            return defaults;
+        }
+        catch (error) {
+            console.error(`Error getting property defaults for ${nodeType}:`, error);
+            return {};
+        }
+    }
+    getDefaultOperationForResource(nodeType, resource) {
+        try {
+            const node = this.getNode(nodeType);
+            if (!node || !node.properties)
+                return undefined;
+            for (const prop of node.properties) {
+                if (prop.name === 'operation') {
+                    if (resource && prop.displayOptions?.show?.resource) {
+                        const resourceDep = prop.displayOptions.show.resource;
+                        if (!Array.isArray(resourceDep) && typeof resourceDep !== 'string') {
+                            continue;
+                        }
+                        const allowedResources = Array.isArray(resourceDep)
+                            ? resourceDep
+                            : [resourceDep];
+                        if (!allowedResources.includes(resource)) {
+                            continue;
+                        }
+                    }
+                    if (prop.default !== undefined) {
+                        return prop.default;
+                    }
+                    if (prop.options && Array.isArray(prop.options) && prop.options.length > 0) {
+                        const firstOption = prop.options[0];
+                        return typeof firstOption === 'string' ? firstOption : firstOption.value;
+                    }
+                }
+            }
+        }
+        catch (error) {
+            console.error(`Error getting default operation for ${nodeType}:`, error);
+            return undefined;
+        }
+        return undefined;
+    }
+    saveNodeVersion(versionData) {
+        const stmt = this.db.prepare(`
+      INSERT OR REPLACE INTO node_versions (
+        node_type, version, package_name, display_name, description,
+        category, is_current_max, properties_schema, operations,
+        credentials_required, outputs, minimum_n8n_version,
+        breaking_changes, deprecated_properties, added_properties,
+        released_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+        stmt.run(versionData.nodeType, versionData.version, versionData.packageName, versionData.displayName, versionData.description || null, versionData.category || null, versionData.isCurrentMax ? 1 : 0, versionData.propertiesSchema ? JSON.stringify(versionData.propertiesSchema) : null, versionData.operations ? JSON.stringify(versionData.operations) : null, versionData.credentialsRequired ? JSON.stringify(versionData.credentialsRequired) : null, versionData.outputs ? JSON.stringify(versionData.outputs) : null, versionData.minimumN8nVersion || null, versionData.breakingChanges ? JSON.stringify(versionData.breakingChanges) : null, versionData.deprecatedProperties ? JSON.stringify(versionData.deprecatedProperties) : null, versionData.addedProperties ? JSON.stringify(versionData.addedProperties) : null, versionData.releasedAt || null);
+    }
+    getNodeVersions(nodeType) {
+        const normalizedType = node_type_normalizer_1.NodeTypeNormalizer.normalizeToFullForm(nodeType);
+        const rows = this.db.prepare(`
+      SELECT * FROM node_versions
+      WHERE node_type = ?
+      ORDER BY version DESC
+    `).all(normalizedType);
+        return rows.map(row => this.parseNodeVersionRow(row));
+    }
+    getLatestNodeVersion(nodeType) {
+        const normalizedType = node_type_normalizer_1.NodeTypeNormalizer.normalizeToFullForm(nodeType);
+        const row = this.db.prepare(`
+      SELECT * FROM node_versions
+      WHERE node_type = ? AND is_current_max = 1
+      LIMIT 1
+    `).get(normalizedType);
+        if (!row)
+            return null;
+        return this.parseNodeVersionRow(row);
+    }
+    getNodeVersion(nodeType, version) {
+        const normalizedType = node_type_normalizer_1.NodeTypeNormalizer.normalizeToFullForm(nodeType);
+        const row = this.db.prepare(`
+      SELECT * FROM node_versions
+      WHERE node_type = ? AND version = ?
+    `).get(normalizedType, version);
+        if (!row)
+            return null;
+        return this.parseNodeVersionRow(row);
+    }
+    savePropertyChange(changeData) {
+        const stmt = this.db.prepare(`
+      INSERT INTO version_property_changes (
+        node_type, from_version, to_version, property_name, change_type,
+        is_breaking, old_value, new_value, migration_hint, auto_migratable,
+        migration_strategy, severity
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+        stmt.run(changeData.nodeType, changeData.fromVersion, changeData.toVersion, changeData.propertyName, changeData.changeType, changeData.isBreaking ? 1 : 0, changeData.oldValue || null, changeData.newValue || null, changeData.migrationHint || null, changeData.autoMigratable ? 1 : 0, changeData.migrationStrategy ? JSON.stringify(changeData.migrationStrategy) : null, changeData.severity || 'MEDIUM');
+    }
+    getPropertyChanges(nodeType, fromVersion, toVersion) {
+        const normalizedType = node_type_normalizer_1.NodeTypeNormalizer.normalizeToFullForm(nodeType);
+        const rows = this.db.prepare(`
+      SELECT * FROM version_property_changes
+      WHERE node_type = ? AND from_version = ? AND to_version = ?
+      ORDER BY severity DESC, property_name
+    `).all(normalizedType, fromVersion, toVersion);
+        return rows.map(row => this.parsePropertyChangeRow(row));
+    }
+    getBreakingChanges(nodeType, fromVersion, toVersion) {
+        const normalizedType = node_type_normalizer_1.NodeTypeNormalizer.normalizeToFullForm(nodeType);
+        let sql = `
+      SELECT * FROM version_property_changes
+      WHERE node_type = ? AND is_breaking = 1
+    `;
+        const params = [normalizedType];
+        if (toVersion) {
+            sql += ` AND from_version >= ? AND to_version <= ?`;
+            params.push(fromVersion, toVersion);
+        }
+        else {
+            sql += ` AND from_version >= ?`;
+            params.push(fromVersion);
+        }
+        sql += ` ORDER BY from_version, to_version, severity DESC`;
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map(row => this.parsePropertyChangeRow(row));
+    }
+    getAutoMigratableChanges(nodeType, fromVersion, toVersion) {
+        const normalizedType = node_type_normalizer_1.NodeTypeNormalizer.normalizeToFullForm(nodeType);
+        const rows = this.db.prepare(`
+      SELECT * FROM version_property_changes
+      WHERE node_type = ?
+        AND from_version = ?
+        AND to_version = ?
+        AND auto_migratable = 1
+      ORDER BY severity DESC
+    `).all(normalizedType, fromVersion, toVersion);
+        return rows.map(row => this.parsePropertyChangeRow(row));
+    }
+    hasVersionUpgradePath(nodeType, fromVersion, toVersion) {
+        const versions = this.getNodeVersions(nodeType);
+        if (versions.length === 0)
+            return false;
+        const fromExists = versions.some(v => v.version === fromVersion);
+        const toExists = versions.some(v => v.version === toVersion);
+        return fromExists && toExists;
+    }
+    getVersionedNodesCount() {
+        const result = this.db.prepare(`
+      SELECT COUNT(DISTINCT node_type) as count
+      FROM node_versions
+    `).get();
+        return result.count;
+    }
+    parseNodeVersionRow(row) {
+        return {
+            id: row.id,
+            nodeType: row.node_type,
+            version: row.version,
+            packageName: row.package_name,
+            displayName: row.display_name,
+            description: row.description,
+            category: row.category,
+            isCurrentMax: Number(row.is_current_max) === 1,
+            propertiesSchema: row.properties_schema ? this.safeJsonParse(row.properties_schema, []) : null,
+            operations: row.operations ? this.safeJsonParse(row.operations, []) : null,
+            credentialsRequired: row.credentials_required ? this.safeJsonParse(row.credentials_required, []) : null,
+            outputs: row.outputs ? this.safeJsonParse(row.outputs, null) : null,
+            minimumN8nVersion: row.minimum_n8n_version,
+            breakingChanges: row.breaking_changes ? this.safeJsonParse(row.breaking_changes, []) : [],
+            deprecatedProperties: row.deprecated_properties ? this.safeJsonParse(row.deprecated_properties, []) : [],
+            addedProperties: row.added_properties ? this.safeJsonParse(row.added_properties, []) : [],
+            releasedAt: row.released_at,
+            createdAt: row.created_at
+        };
+    }
+    parsePropertyChangeRow(row) {
+        return {
+            id: row.id,
+            nodeType: row.node_type,
+            fromVersion: row.from_version,
+            toVersion: row.to_version,
+            propertyName: row.property_name,
+            changeType: row.change_type,
+            isBreaking: Number(row.is_breaking) === 1,
+            oldValue: row.old_value,
+            newValue: row.new_value,
+            migrationHint: row.migration_hint,
+            autoMigratable: Number(row.auto_migratable) === 1,
+            migrationStrategy: row.migration_strategy ? this.safeJsonParse(row.migration_strategy, null) : null,
+            severity: row.severity,
+            createdAt: row.created_at
+        };
+    }
+    createWorkflowVersion(data) {
+        const stmt = this.db.prepare(`
+      INSERT INTO workflow_versions (
+        workflow_id, version_number, workflow_name, workflow_snapshot,
+        trigger, operations, fix_types, metadata
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+        const result = stmt.run(data.workflowId, data.versionNumber, data.workflowName, JSON.stringify(data.workflowSnapshot), data.trigger, data.operations ? JSON.stringify(data.operations) : null, data.fixTypes ? JSON.stringify(data.fixTypes) : null, data.metadata ? JSON.stringify(data.metadata) : null);
+        return result.lastInsertRowid;
+    }
+    getWorkflowVersions(workflowId, limit) {
+        let sql = `
+      SELECT * FROM workflow_versions
+      WHERE workflow_id = ?
+      ORDER BY version_number DESC
+    `;
+        if (limit) {
+            sql += ` LIMIT ?`;
+            const rows = this.db.prepare(sql).all(workflowId, limit);
+            return rows.map(row => this.parseWorkflowVersionRow(row));
+        }
+        const rows = this.db.prepare(sql).all(workflowId);
+        return rows.map(row => this.parseWorkflowVersionRow(row));
+    }
+    getWorkflowVersion(versionId) {
+        const row = this.db.prepare(`
+      SELECT * FROM workflow_versions WHERE id = ?
+    `).get(versionId);
+        if (!row)
+            return null;
+        return this.parseWorkflowVersionRow(row);
+    }
+    getLatestWorkflowVersion(workflowId) {
+        const row = this.db.prepare(`
+      SELECT * FROM workflow_versions
+      WHERE workflow_id = ?
+      ORDER BY version_number DESC
+      LIMIT 1
+    `).get(workflowId);
+        if (!row)
+            return null;
+        return this.parseWorkflowVersionRow(row);
+    }
+    deleteWorkflowVersion(versionId) {
+        this.db.prepare(`
+      DELETE FROM workflow_versions WHERE id = ?
+    `).run(versionId);
+    }
+    deleteWorkflowVersionsByWorkflowId(workflowId) {
+        const result = this.db.prepare(`
+      DELETE FROM workflow_versions WHERE workflow_id = ?
+    `).run(workflowId);
+        return result.changes;
+    }
+    pruneWorkflowVersions(workflowId, keepCount) {
+        const versions = this.db.prepare(`
+      SELECT id FROM workflow_versions
+      WHERE workflow_id = ?
+      ORDER BY version_number DESC
+    `).all(workflowId);
+        if (versions.length <= keepCount) {
+            return 0;
+        }
+        const idsToDelete = versions.slice(keepCount).map(v => v.id);
+        if (idsToDelete.length === 0) {
+            return 0;
+        }
+        const placeholders = idsToDelete.map(() => '?').join(',');
+        const result = this.db.prepare(`
+      DELETE FROM workflow_versions WHERE id IN (${placeholders})
+    `).run(...idsToDelete);
+        return result.changes;
+    }
+    truncateWorkflowVersions() {
+        const result = this.db.prepare(`
+      DELETE FROM workflow_versions
+    `).run();
+        return result.changes;
+    }
+    getWorkflowVersionCount(workflowId) {
+        const result = this.db.prepare(`
+      SELECT COUNT(*) as count FROM workflow_versions WHERE workflow_id = ?
+    `).get(workflowId);
+        return result.count;
+    }
+    getVersionStorageStats() {
+        const totalResult = this.db.prepare(`
+      SELECT COUNT(*) as count FROM workflow_versions
+    `).get();
+        const sizeResult = this.db.prepare(`
+      SELECT SUM(LENGTH(workflow_snapshot)) as total_size FROM workflow_versions
+    `).get();
+        const byWorkflow = this.db.prepare(`
+      SELECT
+        workflow_id,
+        workflow_name,
+        COUNT(*) as version_count,
+        SUM(LENGTH(workflow_snapshot)) as total_size,
+        MAX(created_at) as last_backup
+      FROM workflow_versions
+      GROUP BY workflow_id
+      ORDER BY version_count DESC
+    `).all();
+        return {
+            totalVersions: totalResult.count,
+            totalSize: sizeResult.total_size || 0,
+            byWorkflow: byWorkflow.map(row => ({
+                workflowId: row.workflow_id,
+                workflowName: row.workflow_name,
+                versionCount: row.version_count,
+                totalSize: row.total_size,
+                lastBackup: row.last_backup
+            }))
+        };
+    }
+    parseWorkflowVersionRow(row) {
+        return {
+            id: row.id,
+            workflowId: row.workflow_id,
+            versionNumber: row.version_number,
+            workflowName: row.workflow_name,
+            workflowSnapshot: this.safeJsonParse(row.workflow_snapshot, null),
+            trigger: row.trigger,
+            operations: row.operations ? this.safeJsonParse(row.operations, null) : null,
+            fixTypes: row.fix_types ? this.safeJsonParse(row.fix_types, null) : null,
+            metadata: row.metadata ? this.safeJsonParse(row.metadata, null) : null,
+            createdAt: row.created_at
+        };
+    }
+}
+exports.NodeRepository = NodeRepository;
+//# sourceMappingURL=node-repository.js.map

dist/errors/validation-service-error.d.ts

@@ -0,0 +1,10 @@
+export declare class ValidationServiceError extends Error {
+    readonly nodeType?: string | undefined;
+    readonly property?: string | undefined;
+    readonly cause?: Error | undefined;
+    constructor(message: string, nodeType?: string | undefined, property?: string | undefined, cause?: Error | undefined);
+    static jsonParseError(nodeType: string, cause: Error): ValidationServiceError;
+    static nodeNotFound(nodeType: string): ValidationServiceError;
+    static dataExtractionError(nodeType: string, dataType: string, cause?: Error): ValidationServiceError;
+}
+//# sourceMappingURL=validation-service-error.d.ts.map

dist/errors/validation-service-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation-service-error.d.ts","sourceRoot":"","sources":["../../src/errors/validation-service-error.ts"],"names":[],"mappings":"AAGA,qBAAa,sBAAuB,SAAQ,KAAK;aAG7B,QAAQ,CAAC,EAAE,MAAM;aACjB,QAAQ,CAAC,EAAE,MAAM;aACjB,KAAK,CAAC,EAAE,KAAK;gBAH7B,OAAO,EAAE,MAAM,EACC,QAAQ,CAAC,EAAE,MAAM,YAAA,EACjB,QAAQ,CAAC,EAAE,MAAM,YAAA,EACjB,KAAK,CAAC,EAAE,KAAK,YAAA;IAc/B,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,sBAAsB;IAY7E,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,sBAAsB;IAU7D,MAAM,CAAC,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,GAAG,sBAAsB;CAQtG"}

dist/errors/validation-service-error.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValidationServiceError = void 0;
+class ValidationServiceError extends Error {
+    constructor(message, nodeType, property, cause) {
+        super(message);
+        this.nodeType = nodeType;
+        this.property = property;
+        this.cause = cause;
+        this.name = 'ValidationServiceError';
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, ValidationServiceError);
+        }
+    }
+    static jsonParseError(nodeType, cause) {
+        return new ValidationServiceError(`Failed to parse JSON data for node ${nodeType}`, nodeType, undefined, cause);
+    }
+    static nodeNotFound(nodeType) {
+        return new ValidationServiceError(`Node type ${nodeType} not found in repository`, nodeType);
+    }
+    static dataExtractionError(nodeType, dataType, cause) {
+        return new ValidationServiceError(`Failed to extract ${dataType} for node ${nodeType}`, nodeType, dataType, cause);
+    }
+}
+exports.ValidationServiceError = ValidationServiceError;
+//# sourceMappingURL=validation-service-error.js.map

dist/errors/validation-service-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation-service-error.js","sourceRoot":"","sources":["../../src/errors/validation-service-error.ts"],"names":[],"mappings":";;;AAGA,MAAa,sBAAuB,SAAQ,KAAK;IAC/C,YACE,OAAe,EACC,QAAiB,EACjB,QAAiB,EACjB,KAAa;QAE7B,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,aAAQ,GAAR,QAAQ,CAAS;QACjB,aAAQ,GAAR,QAAQ,CAAS;QACjB,UAAK,GAAL,KAAK,CAAQ;QAG7B,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QAGrC,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,sBAAsB,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IAKD,MAAM,CAAC,cAAc,CAAC,QAAgB,EAAE,KAAY;QAClD,OAAO,IAAI,sBAAsB,CAC/B,sCAAsC,QAAQ,EAAE,EAChD,QAAQ,EACR,SAAS,EACT,KAAK,CACN,CAAC;IACJ,CAAC;IAKD,MAAM,CAAC,YAAY,CAAC,QAAgB;QAClC,OAAO,IAAI,sBAAsB,CAC/B,aAAa,QAAQ,0BAA0B,EAC/C,QAAQ,CACT,CAAC;IACJ,CAAC;IAKD,MAAM,CAAC,mBAAmB,CAAC,QAAgB,EAAE,QAAgB,EAAE,KAAa;QAC1E,OAAO,IAAI,sBAAsB,CAC/B,qBAAqB,QAAQ,aAAa,QAAQ,EAAE,EACpD,QAAQ,EACR,QAAQ,EACR,KAAK,CACN,CAAC;IACJ,CAAC;CACF;AAjDD,wDAiDC"}

dist/http-server-single-session.d.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import express from 'express';
+import { InstanceContext } from './types/instance-context';
+import { SessionState } from './types/session-state';
+export declare class SingleSessionHTTPServer {
+    private transports;
+    private servers;
+    private sessionMetadata;
+    private sessionContexts;
+    private contextSwitchLocks;
+    private session;
+    private consoleManager;
+    private expressServer;
+    private sessionTimeout;
+    private authToken;
+    private cleanupTimer;
+    constructor();
+    private startSessionCleanup;
+    private cleanupExpiredSessions;
+    private removeSession;
+    private getActiveSessionCount;
+    private canCreateSession;
+    private isValidSessionId;
+    private sanitizeErrorForClient;
+    private updateSessionAccess;
+    private switchSessionContext;
+    private performContextSwitch;
+    private getSessionMetrics;
+    private loadAuthToken;
+    private validateEnvironment;
+    handleRequest(req: express.Request, res: express.Response, instanceContext?: InstanceContext): Promise<void>;
+    private resetSessionSSE;
+    private isExpired;
+    private isSessionExpired;
+    start(): Promise<void>;
+    shutdown(): Promise<void>;
+    getSessionInfo(): {
+        active: boolean;
+        sessionId?: string;
+        age?: number;
+        sessions?: {
+            total: number;
+            active: number;
+            expired: number;
+            max: number;
+            sessionIds: string[];
+        };
+    };
+    exportSessionState(): SessionState[];
+    restoreSessionState(sessions: SessionState[]): number;
+}
+//# sourceMappingURL=http-server-single-session.d.ts.map

dist/http-server-single-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-server-single-session.d.ts","sourceRoot":"","sources":["../src/http-server-single-session.ts"],"names":[],"mappings":";AAMA,OAAO,OAAO,MAAM,SAAS,CAAC;AAoB9B,OAAO,EAAE,eAAe,EAA2B,MAAM,0BAA0B,CAAC;AACpF,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAuErD,qBAAa,uBAAuB;IAElC,OAAO,CAAC,UAAU,CAA8D;IAChF,OAAO,CAAC,OAAO,CAA0D;IACzE,OAAO,CAAC,eAAe,CAAsE;IAC7F,OAAO,CAAC,eAAe,CAA4D;IACnF,OAAO,CAAC,kBAAkB,CAAyC;IACnE,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,cAAc,CAAwB;IAC9C,OAAO,CAAC,aAAa,CAAM;IAC3B,OAAO,CAAC,cAAc,CAAkB;IACxC,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,YAAY,CAA+B;;IAcnD,OAAO,CAAC,mBAAmB;IAmB3B,OAAO,CAAC,sBAAsB;YAqChB,aAAa;IAuC3B,OAAO,CAAC,qBAAqB;IAO7B,OAAO,CAAC,gBAAgB;IAkBxB,OAAO,CAAC,gBAAgB;IASxB,OAAO,CAAC,sBAAsB;IAkC9B,OAAO,CAAC,mBAAmB;YASb,oBAAoB;YAwBpB,oBAAoB;IAwBlC,OAAO,CAAC,iBAAiB;IAsBzB,OAAO,CAAC,aAAa;IA2BrB,OAAO,CAAC,mBAAmB;IAoDrB,aAAa,CACjB,GAAG,EAAE,OAAO,CAAC,OAAO,EACpB,GAAG,EAAE,OAAO,CAAC,QAAQ,EACrB,eAAe,CAAC,EAAE,eAAe,GAChC,OAAO,CAAC,IAAI,CAAC;YAmOF,eAAe;IA8C7B,OAAO,CAAC,SAAS;IAYjB,OAAO,CAAC,gBAAgB;IASlB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAgnBtB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAkD/B,cAAc,IAAI;QAChB,MAAM,EAAE,OAAO,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,QAAQ,CAAC,EAAE;YACT,KAAK,EAAE,MAAM,CAAC;YACd,MAAM,EAAE,MAAM,CAAC;YACf,OAAO,EAAE,MAAM,CAAC;YAChB,GAAG,EAAE,MAAM,CAAC;YACZ,UAAU,EAAE,MAAM,EAAE,CAAC;SACtB,CAAC;KACH;IAmDM,kBAAkB,IAAI,YAAY,EAAE;IAoEpC,mBAAmB,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,MAAM;CAsG7D"}

dist/http-server.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+export declare function loadAuthToken(): string | null;
+export declare function startFixedHTTPServer(): Promise<void>;
+declare module './mcp/server' {
+    interface N8NDocumentationMCPServer {
+        executeTool(name: string, args: any): Promise<any>;
+    }
+}
+//# sourceMappingURL=http-server.d.ts.map

dist/http-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-server.d.ts","sourceRoot":"","sources":["../src/http-server.ts"],"names":[],"mappings":";AA0CA,wBAAgB,aAAa,IAAI,MAAM,GAAG,IAAI,CAsB7C;AA+DD,wBAAsB,oBAAoB,kBA+dzC;AAGD,OAAO,QAAQ,cAAc,CAAC;IAC5B,UAAU,yBAAyB;QACjC,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;KACpD;CACF"}

dist/http-server.js

@@ -0,0 +1,478 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadAuthToken = loadAuthToken;
+exports.startFixedHTTPServer = startFixedHTTPServer;
+const express_1 = __importDefault(require("express"));
+const tools_1 = require("./mcp/tools");
+const tools_n8n_manager_1 = require("./mcp/tools-n8n-manager");
+const server_1 = require("./mcp/server");
+const logger_1 = require("./utils/logger");
+const auth_1 = require("./utils/auth");
+const version_1 = require("./utils/version");
+const n8n_api_1 = require("./config/n8n-api");
+const dotenv_1 = __importDefault(require("dotenv"));
+const fs_1 = require("fs");
+const url_detector_1 = require("./utils/url-detector");
+const protocol_version_1 = require("./utils/protocol-version");
+dotenv_1.default.config();
+let expressServer;
+let authToken = null;
+function loadAuthToken() {
+    if (process.env.AUTH_TOKEN) {
+        logger_1.logger.info('Using AUTH_TOKEN from environment variable');
+        return process.env.AUTH_TOKEN;
+    }
+    if (process.env.AUTH_TOKEN_FILE) {
+        try {
+            const token = (0, fs_1.readFileSync)(process.env.AUTH_TOKEN_FILE, 'utf-8').trim();
+            logger_1.logger.info(`Loaded AUTH_TOKEN from file: ${process.env.AUTH_TOKEN_FILE}`);
+            return token;
+        }
+        catch (error) {
+            logger_1.logger.error(`Failed to read AUTH_TOKEN_FILE: ${process.env.AUTH_TOKEN_FILE}`, error);
+            console.error(`ERROR: Failed to read AUTH_TOKEN_FILE: ${process.env.AUTH_TOKEN_FILE}`);
+            console.error(error instanceof Error ? error.message : 'Unknown error');
+            return null;
+        }
+    }
+    return null;
+}
+function validateEnvironment() {
+    authToken = loadAuthToken();
+    if (!authToken || authToken.trim() === '') {
+        logger_1.logger.error('No authentication token found or token is empty');
+        console.error('ERROR: AUTH_TOKEN is required for HTTP mode and cannot be empty');
+        console.error('Set AUTH_TOKEN environment variable or AUTH_TOKEN_FILE pointing to a file containing the token');
+        console.error('Generate AUTH_TOKEN with: openssl rand -base64 32');
+        process.exit(1);
+    }
+    authToken = authToken.trim();
+    if (authToken.length < 32) {
+        logger_1.logger.warn('AUTH_TOKEN should be at least 32 characters for security');
+        console.warn('WARNING: AUTH_TOKEN should be at least 32 characters for security');
+    }
+    if (authToken === 'REPLACE_THIS_AUTH_TOKEN_32_CHARS_MIN_abcdefgh') {
+        logger_1.logger.warn('⚠️ SECURITY WARNING: Using default AUTH_TOKEN - CHANGE IMMEDIATELY!');
+        logger_1.logger.warn('Generate secure token with: openssl rand -base64 32');
+        if (process.env.MCP_MODE === 'http') {
+            console.warn('\n⚠️  SECURITY WARNING ⚠️');
+            console.warn('Using default AUTH_TOKEN - CHANGE IMMEDIATELY!');
+            console.warn('Generate secure token: openssl rand -base64 32');
+            console.warn('Update via Railway dashboard environment variables\n');
+        }
+    }
+}
+async function shutdown() {
+    logger_1.logger.info('Shutting down HTTP server...');
+    console.log('Shutting down HTTP server...');
+    if (expressServer) {
+        expressServer.close(() => {
+            logger_1.logger.info('HTTP server closed');
+            console.log('HTTP server closed');
+            process.exit(0);
+        });
+        setTimeout(() => {
+            logger_1.logger.error('Forced shutdown after timeout');
+            process.exit(1);
+        }, 10000);
+    }
+    else {
+        process.exit(0);
+    }
+}
+async function startFixedHTTPServer() {
+    validateEnvironment();
+    const app = (0, express_1.default)();
+    const trustProxy = process.env.TRUST_PROXY ? Number(process.env.TRUST_PROXY) : 0;
+    if (trustProxy > 0) {
+        app.set('trust proxy', trustProxy);
+        logger_1.logger.info(`Trust proxy enabled with ${trustProxy} hop(s)`);
+    }
+    app.use((req, res, next) => {
+        res.setHeader('X-Content-Type-Options', 'nosniff');
+        res.setHeader('X-Frame-Options', 'DENY');
+        res.setHeader('X-XSS-Protection', '1; mode=block');
+        res.setHeader('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
+        next();
+    });
+    app.use((req, res, next) => {
+        const allowedOrigin = process.env.CORS_ORIGIN || '*';
+        res.setHeader('Access-Control-Allow-Origin', allowedOrigin);
+        res.setHeader('Access-Control-Allow-Methods', 'POST, GET, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, Accept');
+        res.setHeader('Access-Control-Max-Age', '86400');
+        if (req.method === 'OPTIONS') {
+            res.sendStatus(204);
+            return;
+        }
+        next();
+    });
+    app.use((req, res, next) => {
+        logger_1.logger.info(`${req.method} ${req.path}`, {
+            ip: req.ip,
+            userAgent: req.get('user-agent'),
+            contentLength: req.get('content-length')
+        });
+        next();
+    });
+    const mcpServer = new server_1.N8NDocumentationMCPServer();
+    logger_1.logger.info('Created persistent MCP server instance');
+    app.get('/', (req, res) => {
+        const port = parseInt(process.env.PORT || '3000');
+        const host = process.env.HOST || '0.0.0.0';
+        const baseUrl = (0, url_detector_1.detectBaseUrl)(req, host, port);
+        const endpoints = (0, url_detector_1.formatEndpointUrls)(baseUrl);
+        res.json({
+            name: 'n8n Documentation MCP Server',
+            version: version_1.PROJECT_VERSION,
+            description: 'Model Context Protocol server providing comprehensive n8n node documentation and workflow management',
+            endpoints: {
+                health: {
+                    url: endpoints.health,
+                    method: 'GET',
+                    description: 'Health check and status information'
+                },
+                mcp: {
+                    url: endpoints.mcp,
+                    method: 'GET/POST',
+                    description: 'MCP endpoint - GET for info, POST for JSON-RPC'
+                }
+            },
+            authentication: {
+                type: 'Bearer Token',
+                header: 'Authorization: Bearer <token>',
+                required_for: ['POST /mcp']
+            },
+            documentation: 'https://github.com/czlonkowski/n8n-mcp'
+        });
+    });
+    app.get('/health', (req, res) => {
+        res.json({
+            status: 'ok',
+            mode: 'http-fixed',
+            version: version_1.PROJECT_VERSION,
+            uptime: Math.floor(process.uptime()),
+            memory: {
+                used: Math.round(process.memoryUsage().heapUsed / 1024 / 1024),
+                total: Math.round(process.memoryUsage().heapTotal / 1024 / 1024),
+                unit: 'MB'
+            },
+            timestamp: new Date().toISOString()
+        });
+    });
+    app.get('/version', (req, res) => {
+        res.json({
+            version: version_1.PROJECT_VERSION,
+            buildTime: new Date().toISOString(),
+            tools: tools_1.n8nDocumentationToolsFinal.map(t => t.name),
+            commit: process.env.GIT_COMMIT || 'unknown'
+        });
+    });
+    app.get('/test-tools', async (req, res) => {
+        try {
+            const result = await mcpServer.executeTool('get_node_essentials', { nodeType: 'nodes-base.httpRequest' });
+            res.json({ status: 'ok', hasData: !!result, toolCount: tools_1.n8nDocumentationToolsFinal.length });
+        }
+        catch (error) {
+            res.json({ status: 'error', message: error instanceof Error ? error.message : 'Unknown error' });
+        }
+    });
+    app.get('/mcp', (req, res) => {
+        res.json({
+            description: 'n8n Documentation MCP Server',
+            version: version_1.PROJECT_VERSION,
+            endpoints: {
+                mcp: {
+                    method: 'POST',
+                    path: '/mcp',
+                    description: 'Main MCP JSON-RPC endpoint',
+                    authentication: 'Bearer token required'
+                },
+                health: {
+                    method: 'GET',
+                    path: '/health',
+                    description: 'Health check endpoint',
+                    authentication: 'None'
+                },
+                root: {
+                    method: 'GET',
+                    path: '/',
+                    description: 'API information',
+                    authentication: 'None'
+                }
+            },
+            documentation: 'https://github.com/czlonkowski/n8n-mcp'
+        });
+    });
+    app.post('/mcp', async (req, res) => {
+        const startTime = Date.now();
+        const authHeader = req.headers.authorization;
+        if (!authHeader) {
+            logger_1.logger.warn('Authentication failed: Missing Authorization header', {
+                ip: req.ip,
+                userAgent: req.get('user-agent'),
+                reason: 'no_auth_header'
+            });
+            res.status(401).json({
+                jsonrpc: '2.0',
+                error: {
+                    code: -32001,
+                    message: 'Unauthorized'
+                },
+                id: null
+            });
+            return;
+        }
+        if (!authHeader.startsWith('Bearer ')) {
+            logger_1.logger.warn('Authentication failed: Invalid Authorization header format (expected Bearer token)', {
+                ip: req.ip,
+                userAgent: req.get('user-agent'),
+                reason: 'invalid_auth_format',
+                headerPrefix: authHeader.substring(0, Math.min(authHeader.length, 10)) + '...'
+            });
+            res.status(401).json({
+                jsonrpc: '2.0',
+                error: {
+                    code: -32001,
+                    message: 'Unauthorized'
+                },
+                id: null
+            });
+            return;
+        }
+        const token = authHeader.slice(7).trim();
+        const isValidToken = authToken &&
+            auth_1.AuthManager.timingSafeCompare(token, authToken);
+        if (!isValidToken) {
+            logger_1.logger.warn('Authentication failed: Invalid token', {
+                ip: req.ip,
+                userAgent: req.get('user-agent'),
+                reason: 'invalid_token'
+            });
+            res.status(401).json({
+                jsonrpc: '2.0',
+                error: {
+                    code: -32001,
+                    message: 'Unauthorized'
+                },
+                id: null
+            });
+            return;
+        }
+        try {
+            let body = '';
+            req.on('data', chunk => {
+                body += chunk.toString();
+            });
+            req.on('end', async () => {
+                try {
+                    const jsonRpcRequest = JSON.parse(body);
+                    logger_1.logger.debug('Received JSON-RPC request:', { method: jsonRpcRequest.method });
+                    let response;
+                    switch (jsonRpcRequest.method) {
+                        case 'initialize':
+                            const negotiationResult = (0, protocol_version_1.negotiateProtocolVersion)(jsonRpcRequest.params?.protocolVersion, jsonRpcRequest.params?.clientInfo, req.get('user-agent'), req.headers);
+                            (0, protocol_version_1.logProtocolNegotiation)(negotiationResult, logger_1.logger, 'HTTP_SERVER_INITIALIZE');
+                            response = {
+                                jsonrpc: '2.0',
+                                result: {
+                                    protocolVersion: negotiationResult.version,
+                                    capabilities: {
+                                        tools: {},
+                                        resources: {}
+                                    },
+                                    serverInfo: {
+                                        name: 'n8n-documentation-mcp',
+                                        version: version_1.PROJECT_VERSION
+                                    }
+                                },
+                                id: jsonRpcRequest.id
+                            };
+                            break;
+                        case 'tools/list':
+                            const tools = [...tools_1.n8nDocumentationToolsFinal];
+                            if ((0, n8n_api_1.isN8nApiConfigured)()) {
+                                tools.push(...tools_n8n_manager_1.n8nManagementTools);
+                            }
+                            response = {
+                                jsonrpc: '2.0',
+                                result: {
+                                    tools
+                                },
+                                id: jsonRpcRequest.id
+                            };
+                            break;
+                        case 'tools/call':
+                            const toolName = jsonRpcRequest.params?.name;
+                            const toolArgs = jsonRpcRequest.params?.arguments || {};
+                            try {
+                                const result = await mcpServer.executeTool(toolName, toolArgs);
+                                let responseText = JSON.stringify(result, null, 2);
+                                const mcpResult = {
+                                    content: [
+                                        {
+                                            type: 'text',
+                                            text: responseText
+                                        }
+                                    ]
+                                };
+                                if (toolName.startsWith('validate_')) {
+                                    const resultSize = responseText.length;
+                                    if (resultSize > 1000000) {
+                                        logger_1.logger.warn(`Validation tool ${toolName} response is very large (${resultSize} chars). ` +
+                                            `Truncating for HTTP transport safety.`);
+                                        mcpResult.content[0].text = responseText.substring(0, 999000) +
+                                            '\n\n[Response truncated due to size limits]';
+                                    }
+                                    else {
+                                        mcpResult.structuredContent = result;
+                                    }
+                                }
+                                response = {
+                                    jsonrpc: '2.0',
+                                    result: mcpResult,
+                                    id: jsonRpcRequest.id
+                                };
+                            }
+                            catch (error) {
+                                response = {
+                                    jsonrpc: '2.0',
+                                    error: {
+                                        code: -32603,
+                                        message: `Error executing tool ${toolName}: ${error instanceof Error ? error.message : 'Unknown error'}`
+                                    },
+                                    id: jsonRpcRequest.id
+                                };
+                            }
+                            break;
+                        default:
+                            response = {
+                                jsonrpc: '2.0',
+                                error: {
+                                    code: -32601,
+                                    message: `Method not found: ${jsonRpcRequest.method}`
+                                },
+                                id: jsonRpcRequest.id
+                            };
+                    }
+                    res.setHeader('Content-Type', 'application/json');
+                    res.json(response);
+                    const duration = Date.now() - startTime;
+                    logger_1.logger.info('MCP request completed', {
+                        duration,
+                        method: jsonRpcRequest.method
+                    });
+                }
+                catch (error) {
+                    logger_1.logger.error('Error processing request:', error);
+                    res.status(400).json({
+                        jsonrpc: '2.0',
+                        error: {
+                            code: -32700,
+                            message: 'Parse error',
+                            data: error instanceof Error ? error.message : 'Unknown error'
+                        },
+                        id: null
+                    });
+                }
+            });
+        }
+        catch (error) {
+            logger_1.logger.error('MCP request error:', error);
+            if (!res.headersSent) {
+                res.status(500).json({
+                    jsonrpc: '2.0',
+                    error: {
+                        code: -32603,
+                        message: 'Internal server error',
+                        data: process.env.NODE_ENV === 'development'
+                            ? error.message
+                            : undefined
+                    },
+                    id: null
+                });
+            }
+        }
+    });
+    app.use((req, res) => {
+        res.status(404).json({
+            error: 'Not found',
+            message: `Cannot ${req.method} ${req.path}`
+        });
+    });
+    app.use((err, req, res, next) => {
+        logger_1.logger.error('Express error handler:', err);
+        if (!res.headersSent) {
+            res.status(500).json({
+                jsonrpc: '2.0',
+                error: {
+                    code: -32603,
+                    message: 'Internal server error',
+                    data: process.env.NODE_ENV === 'development' ? err.message : undefined
+                },
+                id: null
+            });
+        }
+    });
+    const port = parseInt(process.env.PORT || '3000');
+    const host = process.env.HOST || '0.0.0.0';
+    expressServer = app.listen(port, host, () => {
+        logger_1.logger.info(`n8n MCP Fixed HTTP Server started`, { port, host });
+        const baseUrl = (0, url_detector_1.getStartupBaseUrl)(host, port);
+        const endpoints = (0, url_detector_1.formatEndpointUrls)(baseUrl);
+        console.log(`n8n MCP Fixed HTTP Server running on ${host}:${port}`);
+        console.log(`Health check: ${endpoints.health}`);
+        console.log(`MCP endpoint: ${endpoints.mcp}`);
+        console.log('\nPress Ctrl+C to stop the server');
+        if (authToken === 'REPLACE_THIS_AUTH_TOKEN_32_CHARS_MIN_abcdefgh') {
+            setInterval(() => {
+                logger_1.logger.warn('⚠️ Still using default AUTH_TOKEN - security risk!');
+                if (process.env.MCP_MODE === 'http') {
+                    console.warn('⚠️ REMINDER: Still using default AUTH_TOKEN - please change it!');
+                }
+            }, 300000);
+        }
+        if (process.env.BASE_URL || process.env.PUBLIC_URL) {
+            console.log(`\nPublic URL configured: ${baseUrl}`);
+        }
+        else if (process.env.TRUST_PROXY && Number(process.env.TRUST_PROXY) > 0) {
+            console.log(`\nNote: TRUST_PROXY is enabled. URLs will be auto-detected from proxy headers.`);
+        }
+    });
+    expressServer.on('error', (error) => {
+        if (error.code === 'EADDRINUSE') {
+            logger_1.logger.error(`Port ${port} is already in use`);
+            console.error(`ERROR: Port ${port} is already in use`);
+            process.exit(1);
+        }
+        else {
+            logger_1.logger.error('Server error:', error);
+            console.error('Server error:', error);
+            process.exit(1);
+        }
+    });
+    process.on('SIGTERM', shutdown);
+    process.on('SIGINT', shutdown);
+    process.on('uncaughtException', (error) => {
+        logger_1.logger.error('Uncaught exception:', error);
+        console.error('Uncaught exception:', error);
+        shutdown();
+    });
+    process.on('unhandledRejection', (reason, promise) => {
+        logger_1.logger.error('Unhandled rejection:', reason);
+        console.error('Unhandled rejection at:', promise, 'reason:', reason);
+        shutdown();
+    });
+}
+if (typeof require !== 'undefined' && require.main === module) {
+    startFixedHTTPServer().catch(error => {
+        logger_1.logger.error('Failed to start Fixed HTTP server:', error);
+        console.error('Failed to start Fixed HTTP server:', error);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=http-server.js.map

dist/index.d.ts

@@ -0,0 +1,11 @@
+export { N8NMCPEngine, EngineHealth, EngineOptions } from './mcp-engine';
+export { SingleSessionHTTPServer } from './http-server-single-session';
+export { ConsoleManager } from './utils/console-manager';
+export { N8NDocumentationMCPServer } from './mcp/server';
+export type { InstanceContext } from './types/instance-context';
+export { validateInstanceContext, isInstanceContext } from './types/instance-context';
+export type { SessionState } from './types/session-state';
+export type { Tool, CallToolResult, ListToolsResult } from '@modelcontextprotocol/sdk/types.js';
+import N8NMCPEngine from './mcp-engine';
+export default N8NMCPEngine;
+//# sourceMappingURL=index.d.ts.map

dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACzE,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAGzD,YAAY,EACV,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,uBAAuB,EACvB,iBAAiB,EAClB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,YAAY,EACb,MAAM,uBAAuB,CAAC;AAG/B,YAAY,EACV,IAAI,EACJ,cAAc,EACd,eAAe,EAChB,MAAM,oCAAoC,CAAC;AAG5C,OAAO,YAAY,MAAM,cAAc,CAAC;AACxC,eAAe,YAAY,CAAC"}

dist/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isInstanceContext = exports.validateInstanceContext = exports.N8NDocumentationMCPServer = exports.ConsoleManager = exports.SingleSessionHTTPServer = exports.N8NMCPEngine = void 0;
+var mcp_engine_1 = require("./mcp-engine");
+Object.defineProperty(exports, "N8NMCPEngine", { enumerable: true, get: function () { return mcp_engine_1.N8NMCPEngine; } });
+var http_server_single_session_1 = require("./http-server-single-session");
+Object.defineProperty(exports, "SingleSessionHTTPServer", { enumerable: true, get: function () { return http_server_single_session_1.SingleSessionHTTPServer; } });
+var console_manager_1 = require("./utils/console-manager");
+Object.defineProperty(exports, "ConsoleManager", { enumerable: true, get: function () { return console_manager_1.ConsoleManager; } });
+var server_1 = require("./mcp/server");
+Object.defineProperty(exports, "N8NDocumentationMCPServer", { enumerable: true, get: function () { return server_1.N8NDocumentationMCPServer; } });
+var instance_context_1 = require("./types/instance-context");
+Object.defineProperty(exports, "validateInstanceContext", { enumerable: true, get: function () { return instance_context_1.validateInstanceContext; } });
+Object.defineProperty(exports, "isInstanceContext", { enumerable: true, get: function () { return instance_context_1.isInstanceContext; } });
+const mcp_engine_2 = __importDefault(require("./mcp-engine"));
+exports.default = mcp_engine_2.default;
+//# sourceMappingURL=index.js.map

dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;AAOA,2CAAyE;AAAhE,0GAAA,YAAY,OAAA;AACrB,2EAAuE;AAA9D,qIAAA,uBAAuB,OAAA;AAChC,2DAAyD;AAAhD,iHAAA,cAAc,OAAA;AACvB,uCAAyD;AAAhD,mHAAA,yBAAyB,OAAA;AAMlC,6DAGkC;AAFhC,2HAAA,uBAAuB,OAAA;AACvB,qHAAA,iBAAiB,OAAA;AAcnB,8DAAwC;AACxC,kBAAe,oBAAY,CAAC"}

dist/loaders/node-loader.d.ts

@@ -0,0 +1,11 @@
+export interface LoadedNode {
+    packageName: string;
+    nodeName: string;
+    NodeClass: any;
+}
+export declare class N8nNodeLoader {
+    private readonly CORE_PACKAGES;
+    loadAllNodes(): Promise<LoadedNode[]>;
+    private loadPackageNodes;
+}
+//# sourceMappingURL=node-loader.d.ts.map

dist/loaders/node-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-loader.d.ts","sourceRoot":"","sources":["../../src/loaders/node-loader.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,GAAG,CAAC;CAChB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAG5B;IAEI,YAAY,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;YAmB7B,gBAAgB;CAqD/B"}

dist/loaders/node-loader.js

@@ -0,0 +1,79 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.N8nNodeLoader = void 0;
+const path_1 = __importDefault(require("path"));
+class N8nNodeLoader {
+    constructor() {
+        this.CORE_PACKAGES = [
+            { name: 'n8n-nodes-base', path: 'n8n-nodes-base' },
+            { name: '@n8n/n8n-nodes-langchain', path: '@n8n/n8n-nodes-langchain' }
+        ];
+    }
+    async loadAllNodes() {
+        const results = [];
+        for (const pkg of this.CORE_PACKAGES) {
+            try {
+                console.log(`\n📦 Loading package: ${pkg.name} from ${pkg.path}`);
+                const packageJson = require(`${pkg.path}/package.json`);
+                console.log(`  Found ${Object.keys(packageJson.n8n?.nodes || {}).length} nodes in package.json`);
+                const nodes = await this.loadPackageNodes(pkg.name, pkg.path, packageJson);
+                results.push(...nodes);
+            }
+            catch (error) {
+                console.error(`Failed to load ${pkg.name}:`, error);
+            }
+        }
+        return results;
+    }
+    async loadPackageNodes(packageName, packagePath, packageJson) {
+        const n8nConfig = packageJson.n8n || {};
+        const nodes = [];
+        const nodesList = n8nConfig.nodes || [];
+        if (Array.isArray(nodesList)) {
+            for (const nodePath of nodesList) {
+                try {
+                    const fullPath = require.resolve(`${packagePath}/${nodePath}`);
+                    const nodeModule = require(fullPath);
+                    const nodeNameMatch = nodePath.match(/\/([^\/]+)\.node\.(js|ts)$/);
+                    const nodeName = nodeNameMatch ? nodeNameMatch[1] : path_1.default.basename(nodePath, '.node.js');
+                    const NodeClass = nodeModule.default || nodeModule[nodeName] || Object.values(nodeModule)[0];
+                    if (NodeClass) {
+                        nodes.push({ packageName, nodeName, NodeClass });
+                        console.log(`  ✓ Loaded ${nodeName} from ${packageName}`);
+                    }
+                    else {
+                        console.warn(`  ⚠ No valid export found for ${nodeName} in ${packageName}`);
+                    }
+                }
+                catch (error) {
+                    console.error(`  ✗ Failed to load node from ${packageName}/${nodePath}:`, error.message);
+                }
+            }
+        }
+        else {
+            for (const [nodeName, nodePath] of Object.entries(nodesList)) {
+                try {
+                    const fullPath = require.resolve(`${packagePath}/${nodePath}`);
+                    const nodeModule = require(fullPath);
+                    const NodeClass = nodeModule.default || nodeModule[nodeName] || Object.values(nodeModule)[0];
+                    if (NodeClass) {
+                        nodes.push({ packageName, nodeName, NodeClass });
+                        console.log(`  ✓ Loaded ${nodeName} from ${packageName}`);
+                    }
+                    else {
+                        console.warn(`  ⚠ No valid export found for ${nodeName} in ${packageName}`);
+                    }
+                }
+                catch (error) {
+                    console.error(`  ✗ Failed to load node ${nodeName} from ${packageName}:`, error.message);
+                }
+            }
+        }
+        return nodes;
+    }
+}
+exports.N8nNodeLoader = N8nNodeLoader;
+//# sourceMappingURL=node-loader.js.map

dist/loaders/node-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-loader.js","sourceRoot":"","sources":["../../src/loaders/node-loader.ts"],"names":[],"mappings":"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"}

dist/mappers/docs-mapper.d.ts

@@ -0,0 +1,7 @@
+export declare class DocsMapper {
+    private docsPath;
+    private readonly KNOWN_FIXES;
+    fetchDocumentation(nodeType: string): Promise<string | null>;
+    private enhanceLoopNodeDocumentation;
+}
+//# sourceMappingURL=docs-mapper.d.ts.map

dist/mappers/docs-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-mapper.d.ts","sourceRoot":"","sources":["../../src/mappers/docs-mapper.ts"],"names":[],"mappings":"AAGA,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAwC;IAGxD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAU1B;IAEI,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAkDlE,OAAO,CAAC,4BAA4B;CAmDrC"}

dist/mappers/docs-mapper.js

@@ -0,0 +1,106 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DocsMapper = void 0;
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+class DocsMapper {
+    constructor() {
+        this.docsPath = path_1.default.join(process.cwd(), 'n8n-docs');
+        this.KNOWN_FIXES = {
+            'httpRequest': 'httprequest',
+            'code': 'code',
+            'webhook': 'webhook',
+            'respondToWebhook': 'respondtowebhook',
+            'n8n-nodes-base.httpRequest': 'httprequest',
+            'n8n-nodes-base.code': 'code',
+            'n8n-nodes-base.webhook': 'webhook',
+            'n8n-nodes-base.respondToWebhook': 'respondtowebhook'
+        };
+    }
+    async fetchDocumentation(nodeType) {
+        const fixedType = this.KNOWN_FIXES[nodeType] || nodeType;
+        const nodeName = fixedType.split('.').pop()?.toLowerCase();
+        if (!nodeName) {
+            console.log(`⚠️  Could not extract node name from: ${nodeType}`);
+            return null;
+        }
+        console.log(`📄 Looking for docs for: ${nodeType} -> ${nodeName}`);
+        const possiblePaths = [
+            `docs/integrations/builtin/core-nodes/n8n-nodes-base.${nodeName}.md`,
+            `docs/integrations/builtin/app-nodes/n8n-nodes-base.${nodeName}.md`,
+            `docs/integrations/builtin/trigger-nodes/n8n-nodes-base.${nodeName}.md`,
+            `docs/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.${nodeName}.md`,
+            `docs/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.${nodeName}.md`,
+            `docs/integrations/builtin/core-nodes/n8n-nodes-base.${nodeName}/index.md`,
+            `docs/integrations/builtin/app-nodes/n8n-nodes-base.${nodeName}/index.md`,
+            `docs/integrations/builtin/trigger-nodes/n8n-nodes-base.${nodeName}/index.md`,
+            `docs/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.${nodeName}/index.md`,
+            `docs/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.${nodeName}/index.md`
+        ];
+        for (const relativePath of possiblePaths) {
+            try {
+                const fullPath = path_1.default.join(this.docsPath, relativePath);
+                let content = await fs_1.promises.readFile(fullPath, 'utf-8');
+                console.log(`  ✓ Found docs at: ${relativePath}`);
+                content = this.enhanceLoopNodeDocumentation(nodeType, content);
+                return content;
+            }
+            catch (error) {
+                continue;
+            }
+        }
+        console.log(`  ✗ No docs found for ${nodeName}`);
+        return null;
+    }
+    enhanceLoopNodeDocumentation(nodeType, content) {
+        if (nodeType.includes('splitInBatches')) {
+            const outputGuidance = `
+
+## CRITICAL OUTPUT CONNECTION INFORMATION
+
+**⚠️ OUTPUT INDICES ARE COUNTERINTUITIVE ⚠️**
+
+The SplitInBatches node has TWO outputs with specific indices:
+- **Output 0 (index 0) = "done"**: Receives final processed data when loop completes
+- **Output 1 (index 1) = "loop"**: Receives current batch data during iteration
+
+### Correct Connection Pattern:
+1. Connect nodes that PROCESS items inside the loop to **Output 1 ("loop")**
+2. Connect nodes that run AFTER the loop completes to **Output 0 ("done")**
+3. The last processing node in the loop must connect back to the SplitInBatches node
+
+### Common Mistake:
+AI assistants often connect these backwards because the logical flow (loop first, then done) doesn't match the technical indices (done=0, loop=1).
+
+`;
+            const insertPoint = content.indexOf('## When to use');
+            if (insertPoint > -1) {
+                content = content.slice(0, insertPoint) + outputGuidance + content.slice(insertPoint);
+            }
+            else {
+                content = outputGuidance + '\n' + content;
+            }
+        }
+        if (nodeType.includes('.if')) {
+            const outputGuidance = `
+
+## Output Connection Information
+
+The IF node has TWO outputs:
+- **Output 0 (index 0) = "true"**: Items that match the condition
+- **Output 1 (index 1) = "false"**: Items that do not match the condition
+
+`;
+            const insertPoint = content.indexOf('## Node parameters');
+            if (insertPoint > -1) {
+                content = content.slice(0, insertPoint) + outputGuidance + content.slice(insertPoint);
+            }
+        }
+        return content;
+    }
+}
+exports.DocsMapper = DocsMapper;
+//# sourceMappingURL=docs-mapper.js.map

dist/mappers/docs-mapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-mapper.js","sourceRoot":"","sources":["../../src/mappers/docs-mapper.ts"],"names":[],"mappings":"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"}

dist/mcp-engine.d.ts

@@ -0,0 +1,36 @@
+import { Request, Response } from 'express';
+import { InstanceContext } from './types/instance-context';
+import { SessionState } from './types/session-state';
+export interface EngineHealth {
+    status: 'healthy' | 'unhealthy';
+    uptime: number;
+    sessionActive: boolean;
+    memoryUsage: {
+        used: number;
+        total: number;
+        unit: string;
+    };
+    version: string;
+}
+export interface EngineOptions {
+    sessionTimeout?: number;
+    logLevel?: 'error' | 'warn' | 'info' | 'debug';
+}
+export declare class N8NMCPEngine {
+    private server;
+    private startTime;
+    constructor(options?: EngineOptions);
+    processRequest(req: Request, res: Response, instanceContext?: InstanceContext): Promise<void>;
+    healthCheck(): Promise<EngineHealth>;
+    getSessionInfo(): {
+        active: boolean;
+        sessionId?: string;
+        age?: number;
+    };
+    exportSessionState(): SessionState[];
+    restoreSessionState(sessions: SessionState[]): number;
+    shutdown(): Promise<void>;
+    start(): Promise<void>;
+}
+export default N8NMCPEngine;
+//# sourceMappingURL=mcp-engine.d.ts.map

dist/mcp-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-engine.d.ts","sourceRoot":"","sources":["../src/mcp-engine.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAG5C,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAErD,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,SAAS,GAAG,WAAW,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,OAAO,CAAC;IACvB,WAAW,EAAE;QACX,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;CAChD;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAA0B;IACxC,OAAO,CAAC,SAAS,CAAO;gBAEZ,OAAO,GAAE,aAAkB;IA8BjC,cAAc,CAClB,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,eAAe,CAAC,EAAE,eAAe,GAChC,OAAO,CAAC,IAAI,CAAC;IAkBV,WAAW,IAAI,OAAO,CAAC,YAAY,CAAC;IAgC1C,cAAc,IAAI;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE;IAoBvE,kBAAkB,IAAI,YAAY,EAAE;IAwBpC,mBAAmB,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,MAAM;IAiB/C,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IASzB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B;AA2CD,eAAe,YAAY,CAAC"}

dist/mcp-engine.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.N8NMCPEngine = void 0;
+const http_server_single_session_1 = require("./http-server-single-session");
+const logger_1 = require("./utils/logger");
+class N8NMCPEngine {
+    constructor(options = {}) {
+        this.server = new http_server_single_session_1.SingleSessionHTTPServer();
+        this.startTime = new Date();
+        if (options.logLevel) {
+            process.env.LOG_LEVEL = options.logLevel;
+        }
+    }
+    async processRequest(req, res, instanceContext) {
+        try {
+            await this.server.handleRequest(req, res, instanceContext);
+        }
+        catch (error) {
+            logger_1.logger.error('Engine processRequest error:', error);
+            throw error;
+        }
+    }
+    async healthCheck() {
+        try {
+            const sessionInfo = this.server.getSessionInfo();
+            const memoryUsage = process.memoryUsage();
+            return {
+                status: 'healthy',
+                uptime: Math.floor((Date.now() - this.startTime.getTime()) / 1000),
+                sessionActive: sessionInfo.active,
+                memoryUsage: {
+                    used: Math.round(memoryUsage.heapUsed / 1024 / 1024),
+                    total: Math.round(memoryUsage.heapTotal / 1024 / 1024),
+                    unit: 'MB'
+                },
+                version: '2.24.1'
+            };
+        }
+        catch (error) {
+            logger_1.logger.error('Health check failed:', error);
+            return {
+                status: 'unhealthy',
+                uptime: 0,
+                sessionActive: false,
+                memoryUsage: { used: 0, total: 0, unit: 'MB' },
+                version: '2.24.1'
+            };
+        }
+    }
+    getSessionInfo() {
+        return this.server.getSessionInfo();
+    }
+    exportSessionState() {
+        if (!this.server) {
+            logger_1.logger.warn('Cannot export sessions: server not initialized');
+            return [];
+        }
+        return this.server.exportSessionState();
+    }
+    restoreSessionState(sessions) {
+        if (!this.server) {
+            logger_1.logger.warn('Cannot restore sessions: server not initialized');
+            return 0;
+        }
+        return this.server.restoreSessionState(sessions);
+    }
+    async shutdown() {
+        logger_1.logger.info('Shutting down N8N MCP Engine...');
+        await this.server.shutdown();
+    }
+    async start() {
+        await this.server.start();
+    }
+}
+exports.N8NMCPEngine = N8NMCPEngine;
+exports.default = N8NMCPEngine;
+//# sourceMappingURL=mcp-engine.js.map

dist/mcp-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-engine.js","sourceRoot":"","sources":["../src/mcp-engine.ts"],"names":[],"mappings":"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"}

dist/mcp-tools-engine.d.ts

@@ -0,0 +1,47 @@
+import { NodeRepository } from './database/node-repository';
+import { WorkflowValidationResult } from './services/workflow-validator';
+export declare class MCPEngine {
+    private repository;
+    private workflowValidator;
+    constructor(repository: NodeRepository);
+    listNodes(args?: any): Promise<any[]>;
+    searchNodes(args: any): Promise<any[]>;
+    getNodeInfo(args: any): Promise<any>;
+    getNodeEssentials(args: any): Promise<{
+        nodeType: any;
+        displayName: any;
+        description: any;
+        category: any;
+        required: import("./services/property-filter").SimplifiedProperty[];
+        common: import("./services/property-filter").SimplifiedProperty[];
+    } | null>;
+    getNodeDocumentation(args: any): Promise<any>;
+    validateNodeOperation(args: any): Promise<import("./services/config-validator").ValidationResult | {
+        valid: boolean;
+        errors: {
+            type: string;
+            property: string;
+            message: string;
+        }[];
+        warnings: never[];
+        suggestions: never[];
+        visibleProperties: never[];
+        hiddenProperties: never[];
+    }>;
+    validateNodeMinimal(args: any): Promise<{
+        missingFields: never[];
+        error: string;
+    } | {
+        missingFields: string[];
+        error?: undefined;
+    }>;
+    searchNodeProperties(args: any): Promise<any[]>;
+    listAITools(args: any): Promise<any[]>;
+    getDatabaseStatistics(args: any): Promise<{
+        totalNodes: number;
+        aiToolsCount: number;
+        categories: string[];
+    }>;
+    validateWorkflow(args: any): Promise<WorkflowValidationResult>;
+}
+//# sourceMappingURL=mcp-tools-engine.d.ts.map

dist/mcp-tools-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-tools-engine.d.ts","sourceRoot":"","sources":["../src/mcp-tools-engine.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAK5D,OAAO,EAAqB,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAE5F,qBAAa,SAAS;IAGR,OAAO,CAAC,UAAU;IAF9B,OAAO,CAAC,iBAAiB,CAAoB;gBAEzB,UAAU,EAAE,cAAc;IAIxC,SAAS,CAAC,IAAI,GAAE,GAAQ;IAIxB,WAAW,CAAC,IAAI,EAAE,GAAG;IAIrB,WAAW,CAAC,IAAI,EAAE,GAAG;IAIrB,iBAAiB,CAAC,IAAI,EAAE,GAAG;;;;;;;;IAgB3B,oBAAoB,CAAC,IAAI,EAAE,GAAG;IAK9B,qBAAqB,CAAC,IAAI,EAAE,GAAG;;;;;;;;;;;;IAqB/B,mBAAmB,CAAC,IAAI,EAAE,GAAG;;;;;;;IAmB7B,oBAAoB,CAAC,IAAI,EAAE,GAAG;IAI9B,WAAW,CAAC,IAAI,EAAE,GAAG;IAIrB,qBAAqB,CAAC,IAAI,EAAE,GAAG;;;;;IAU/B,gBAAgB,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,wBAAwB,CAAC;CAGrE"}

dist/mcp-tools-engine.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCPEngine = void 0;
+const property_filter_1 = require("./services/property-filter");
+const config_validator_1 = require("./services/config-validator");
+const enhanced_config_validator_1 = require("./services/enhanced-config-validator");
+const workflow_validator_1 = require("./services/workflow-validator");
+class MCPEngine {
+    constructor(repository) {
+        this.repository = repository;
+        this.workflowValidator = new workflow_validator_1.WorkflowValidator(repository, enhanced_config_validator_1.EnhancedConfigValidator);
+    }
+    async listNodes(args = {}) {
+        return this.repository.getAllNodes(args.limit);
+    }
+    async searchNodes(args) {
+        return this.repository.searchNodes(args.query, args.mode || 'OR', args.limit || 20);
+    }
+    async getNodeInfo(args) {
+        return this.repository.getNodeByType(args.nodeType);
+    }
+    async getNodeEssentials(args) {
+        const node = await this.repository.getNodeByType(args.nodeType);
+        if (!node)
+            return null;
+        const essentials = property_filter_1.PropertyFilter.getEssentials(node.properties || [], args.nodeType);
+        return {
+            nodeType: node.nodeType,
+            displayName: node.displayName,
+            description: node.description,
+            category: node.category,
+            required: essentials.required,
+            common: essentials.common
+        };
+    }
+    async getNodeDocumentation(args) {
+        const node = await this.repository.getNodeByType(args.nodeType);
+        return node?.documentation || null;
+    }
+    async validateNodeOperation(args) {
+        const node = await this.repository.getNodeByType(args.nodeType);
+        if (!node) {
+            return {
+                valid: false,
+                errors: [{ type: 'invalid_configuration', property: '', message: 'Node type not found' }],
+                warnings: [],
+                suggestions: [],
+                visibleProperties: [],
+                hiddenProperties: []
+            };
+        }
+        const userProvidedKeys = new Set(Object.keys(args.config || {}));
+        return config_validator_1.ConfigValidator.validate(args.nodeType, args.config, node.properties || [], userProvidedKeys);
+    }
+    async validateNodeMinimal(args) {
+        const node = await this.repository.getNodeByType(args.nodeType);
+        if (!node) {
+            return { missingFields: [], error: 'Node type not found' };
+        }
+        const missingFields = [];
+        const requiredFields = property_filter_1.PropertyFilter.getEssentials(node.properties || [], args.nodeType).required;
+        for (const field of requiredFields) {
+            if (!args.config[field.name]) {
+                missingFields.push(field.name);
+            }
+        }
+        return { missingFields };
+    }
+    async searchNodeProperties(args) {
+        return this.repository.searchNodeProperties(args.nodeType, args.query, args.maxResults || 20);
+    }
+    async listAITools(args) {
+        return this.repository.getAIToolNodes();
+    }
+    async getDatabaseStatistics(args) {
+        const count = await this.repository.getNodeCount();
+        const aiTools = await this.repository.getAIToolNodes();
+        return {
+            totalNodes: count,
+            aiToolsCount: aiTools.length,
+            categories: ['trigger', 'transform', 'output', 'input']
+        };
+    }
+    async validateWorkflow(args) {
+        return this.workflowValidator.validateWorkflow(args.workflow, args.options);
+    }
+}
+exports.MCPEngine = MCPEngine;
+//# sourceMappingURL=mcp-tools-engine.js.map

dist/mcp-tools-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-tools-engine.js","sourceRoot":"","sources":["../src/mcp-tools-engine.ts"],"names":[],"mappings":"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"}

dist/mcp/handlers-n8n-manager.d.ts

@@ -0,0 +1,29 @@
+import { N8nApiClient } from '../services/n8n-api-client';
+import { McpToolResponse } from '../types/n8n-api';
+import { NodeRepository } from '../database/node-repository';
+import { InstanceContext } from '../types/instance-context';
+import { TemplateService } from '../templates/template-service';
+export declare function getInstanceCacheStatistics(): string;
+export declare function getInstanceCacheMetrics(): import("../utils/cache-utils").CacheMetrics;
+export declare function clearInstanceCache(): void;
+export declare function getN8nApiClient(context?: InstanceContext): N8nApiClient | null;
+export declare function handleCreateWorkflow(args: unknown, context?: InstanceContext): Promise<McpToolResponse>;
+export declare function handleGetWorkflow(args: unknown, context?: InstanceContext): Promise<McpToolResponse>;
+export declare function handleGetWorkflowDetails(args: unknown, context?: InstanceContext): Promise<McpToolResponse>;
+export declare function handleGetWorkflowStructure(args: unknown, context?: InstanceContext): Promise<McpToolResponse>;
+export declare function handleGetWorkflowMinimal(args: unknown, context?: InstanceContext): Promise<McpToolResponse>;
+export declare function handleUpdateWorkflow(args: unknown, repository: NodeRepository, context?: InstanceContext): Promise<McpToolResponse>;
+export declare function handleDeleteWorkflow(args: unknown, context?: InstanceContext): Promise<McpToolResponse>;
+export declare function handleListWorkflows(args: unknown, context?: InstanceContext): Promise<McpToolResponse>;
+export declare function handleValidateWorkflow(args: unknown, repository: NodeRepository, context?: InstanceContext): Promise<McpToolResponse>;
+export declare function handleAutofixWorkflow(args: unknown, repository: NodeRepository, context?: InstanceContext): Promise<McpToolResponse>;
+export declare function handleTestWorkflow(args: unknown, context?: InstanceContext): Promise<McpToolResponse>;
+export declare function handleGetExecution(args: unknown, context?: InstanceContext): Promise<McpToolResponse>;
+export declare function handleListExecutions(args: unknown, context?: InstanceContext): Promise<McpToolResponse>;
+export declare function handleDeleteExecution(args: unknown, context?: InstanceContext): Promise<McpToolResponse>;
+export declare function handleHealthCheck(context?: InstanceContext): Promise<McpToolResponse>;
+export declare function handleDiagnostic(request: any, context?: InstanceContext): Promise<McpToolResponse>;
+export declare function handleWorkflowVersions(args: unknown, repository: NodeRepository, context?: InstanceContext): Promise<McpToolResponse>;
+export declare function handleDeployTemplate(args: unknown, templateService: TemplateService, repository: NodeRepository, context?: InstanceContext): Promise<McpToolResponse>;
+export declare function handleTriggerWebhookWorkflow(args: unknown, context?: InstanceContext): Promise<McpToolResponse>;
+//# sourceMappingURL=handlers-n8n-manager.d.ts.map

dist/mcp/handlers-n8n-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers-n8n-manager.d.ts","sourceRoot":"","sources":["../../src/mcp/handlers-n8n-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE1D,OAAO,EAML,eAAe,EAGhB,MAAM,kBAAkB,CAAC;AAkB1B,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,eAAe,EAA2B,MAAM,2BAA2B,CAAC;AAOrF,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAqNhE,wBAAgB,0BAA0B,IAAI,MAAM,CAEnD;AAMD,wBAAgB,uBAAuB,gDAEtC;AAKD,wBAAgB,kBAAkB,IAAI,IAAI,CAIzC;AAED,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,YAAY,GAAG,IAAI,CAgF9E;AAqHD,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAmF7G;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAiC1G;AAED,wBAAsB,wBAAwB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAoDjH;AAED,wBAAsB,0BAA0B,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAmDnH;AAED,wBAAsB,wBAAwB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAyCjH;AAED,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,OAAO,EACb,UAAU,EAAE,cAAc,EAC1B,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,eAAe,CAAC,CA8H1B;AAeD,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAsC7G;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAiE5G;AAED,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,OAAO,EACb,UAAU,EAAE,cAAc,EAC1B,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,eAAe,CAAC,CA0F1B;AAED,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,OAAO,EACb,UAAU,EAAE,cAAc,EAC1B,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,eAAe,CAAC,CAoK1B;AAQD,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAwJ3G;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CA8H3G;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAgD7G;AAED,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAiC9G;AAID,wBAAsB,iBAAiB,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAwG3F;AAkLD,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAkQxG;AAED,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,OAAO,EACb,UAAU,EAAE,cAAc,EAC1B,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,eAAe,CAAC,CAsL1B;AA+BD,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,OAAO,EACb,eAAe,EAAE,eAAe,EAChC,UAAU,EAAE,cAAc,EAC1B,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,eAAe,CAAC,CAoM1B;AAQD,wBAAsB,4BAA4B,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAyErH"}

dist/mcp/handlers-workflow-diff.d.ts

@@ -0,0 +1,5 @@
+import { McpToolResponse } from '../types/n8n-api';
+import { InstanceContext } from '../types/instance-context';
+import { NodeRepository } from '../database/node-repository';
+export declare function handleUpdatePartialWorkflow(args: unknown, repository: NodeRepository, context?: InstanceContext): Promise<McpToolResponse>;
+//# sourceMappingURL=handlers-workflow-diff.d.ts.map

dist/mcp/handlers-workflow-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers-workflow-diff.d.ts","sourceRoot":"","sources":["../../src/mcp/handlers-workflow-diff.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAMnD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAE5D,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AA0D7D,wBAAsB,2BAA2B,CAC/C,IAAI,EAAE,OAAO,EACb,UAAU,EAAE,cAAc,EAC1B,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,eAAe,CAAC,CA6V1B"}

dist/mcp/handlers-workflow-diff.js

@@ -0,0 +1,461 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleUpdatePartialWorkflow = handleUpdatePartialWorkflow;
+const zod_1 = require("zod");
+const workflow_diff_engine_1 = require("../services/workflow-diff-engine");
+const handlers_n8n_manager_1 = require("./handlers-n8n-manager");
+const n8n_errors_1 = require("../utils/n8n-errors");
+const logger_1 = require("../utils/logger");
+const n8n_validation_1 = require("../services/n8n-validation");
+const workflow_versioning_service_1 = require("../services/workflow-versioning-service");
+const workflow_validator_1 = require("../services/workflow-validator");
+const enhanced_config_validator_1 = require("../services/enhanced-config-validator");
+let cachedValidator = null;
+function getValidator(repository) {
+    if (!cachedValidator) {
+        cachedValidator = new workflow_validator_1.WorkflowValidator(repository, enhanced_config_validator_1.EnhancedConfigValidator);
+    }
+    return cachedValidator;
+}
+const workflowDiffSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    operations: zod_1.z.array(zod_1.z.object({
+        type: zod_1.z.string(),
+        description: zod_1.z.string().optional(),
+        node: zod_1.z.any().optional(),
+        nodeId: zod_1.z.string().optional(),
+        nodeName: zod_1.z.string().optional(),
+        updates: zod_1.z.any().optional(),
+        position: zod_1.z.tuple([zod_1.z.number(), zod_1.z.number()]).optional(),
+        source: zod_1.z.string().optional(),
+        target: zod_1.z.string().optional(),
+        from: zod_1.z.string().optional(),
+        to: zod_1.z.string().optional(),
+        sourceOutput: zod_1.z.string().optional(),
+        targetInput: zod_1.z.string().optional(),
+        sourceIndex: zod_1.z.number().optional(),
+        targetIndex: zod_1.z.number().optional(),
+        branch: zod_1.z.enum(['true', 'false']).optional(),
+        case: zod_1.z.number().optional(),
+        ignoreErrors: zod_1.z.boolean().optional(),
+        dryRun: zod_1.z.boolean().optional(),
+        connections: zod_1.z.any().optional(),
+        settings: zod_1.z.any().optional(),
+        name: zod_1.z.string().optional(),
+        tag: zod_1.z.string().optional(),
+    })),
+    validateOnly: zod_1.z.boolean().optional(),
+    continueOnError: zod_1.z.boolean().optional(),
+    createBackup: zod_1.z.boolean().optional(),
+    intent: zod_1.z.string().optional(),
+});
+async function handleUpdatePartialWorkflow(args, repository, context) {
+    const startTime = Date.now();
+    const sessionId = `mutation_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`;
+    let workflowBefore = null;
+    let validationBefore = null;
+    let validationAfter = null;
+    try {
+        if (process.env.DEBUG_MCP === 'true') {
+            logger_1.logger.debug('Workflow diff request received', {
+                argsType: typeof args,
+                hasWorkflowId: args && typeof args === 'object' && 'workflowId' in args,
+                operationCount: args && typeof args === 'object' && 'operations' in args ?
+                    args.operations?.length : 0
+            });
+        }
+        const input = workflowDiffSchema.parse(args);
+        const client = (0, handlers_n8n_manager_1.getN8nApiClient)(context);
+        if (!client) {
+            return {
+                success: false,
+                error: 'n8n API not configured. Please set N8N_API_URL and N8N_API_KEY environment variables.'
+            };
+        }
+        let workflow;
+        try {
+            workflow = await client.getWorkflow(input.id);
+            workflowBefore = JSON.parse(JSON.stringify(workflow));
+            try {
+                const validator = getValidator(repository);
+                validationBefore = await validator.validateWorkflow(workflowBefore, {
+                    validateNodes: true,
+                    validateConnections: true,
+                    validateExpressions: true,
+                    profile: 'runtime'
+                });
+            }
+            catch (validationError) {
+                logger_1.logger.debug('Pre-mutation validation failed (non-blocking):', validationError);
+                validationBefore = {
+                    valid: false,
+                    errors: [{ type: 'validation_error', message: 'Validation failed' }]
+                };
+            }
+        }
+        catch (error) {
+            if (error instanceof n8n_errors_1.N8nApiError) {
+                return {
+                    success: false,
+                    error: (0, n8n_errors_1.getUserFriendlyErrorMessage)(error),
+                    code: error.code
+                };
+            }
+            throw error;
+        }
+        if (input.createBackup !== false && !input.validateOnly) {
+            try {
+                const versioningService = new workflow_versioning_service_1.WorkflowVersioningService(repository, client);
+                const backupResult = await versioningService.createBackup(input.id, workflow, {
+                    trigger: 'partial_update',
+                    operations: input.operations
+                });
+                logger_1.logger.info('Workflow backup created', {
+                    workflowId: input.id,
+                    versionId: backupResult.versionId,
+                    versionNumber: backupResult.versionNumber,
+                    pruned: backupResult.pruned
+                });
+            }
+            catch (error) {
+                logger_1.logger.warn('Failed to create workflow backup', {
+                    workflowId: input.id,
+                    error: error.message
+                });
+            }
+        }
+        const diffEngine = new workflow_diff_engine_1.WorkflowDiffEngine();
+        const diffRequest = input;
+        const diffResult = await diffEngine.applyDiff(workflow, diffRequest);
+        if (!diffResult.success) {
+            if (diffRequest.continueOnError && diffResult.workflow && diffResult.operationsApplied && diffResult.operationsApplied > 0) {
+                logger_1.logger.info(`continueOnError mode: Applying ${diffResult.operationsApplied} successful operations despite ${diffResult.failed?.length || 0} failures`);
+            }
+            else {
+                return {
+                    success: false,
+                    error: 'Failed to apply diff operations',
+                    details: {
+                        errors: diffResult.errors,
+                        warnings: diffResult.warnings,
+                        operationsApplied: diffResult.operationsApplied,
+                        applied: diffResult.applied,
+                        failed: diffResult.failed
+                    }
+                };
+            }
+        }
+        if (input.validateOnly) {
+            return {
+                success: true,
+                message: diffResult.message,
+                data: {
+                    valid: true,
+                    operationsToApply: input.operations.length
+                },
+                details: {
+                    warnings: diffResult.warnings
+                }
+            };
+        }
+        if (diffResult.workflow) {
+            const structureErrors = (0, n8n_validation_1.validateWorkflowStructure)(diffResult.workflow);
+            if (structureErrors.length > 0) {
+                const skipValidation = process.env.SKIP_WORKFLOW_VALIDATION === 'true';
+                logger_1.logger.warn('Workflow structure validation failed after applying diff operations', {
+                    workflowId: input.id,
+                    errors: structureErrors,
+                    blocking: !skipValidation
+                });
+                const errorTypes = new Set();
+                structureErrors.forEach(err => {
+                    if (err.includes('operator') || err.includes('singleValue'))
+                        errorTypes.add('operator_issues');
+                    if (err.includes('connection') || err.includes('referenced'))
+                        errorTypes.add('connection_issues');
+                    if (err.includes('Missing') || err.includes('missing'))
+                        errorTypes.add('missing_metadata');
+                    if (err.includes('branch') || err.includes('output'))
+                        errorTypes.add('branch_mismatch');
+                });
+                const recoverySteps = [];
+                if (errorTypes.has('operator_issues')) {
+                    recoverySteps.push('Operator structure issue detected. Use validate_node_operation to check specific nodes.');
+                    recoverySteps.push('Binary operators (equals, contains, greaterThan, etc.) must NOT have singleValue:true');
+                    recoverySteps.push('Unary operators (isEmpty, isNotEmpty, true, false) REQUIRE singleValue:true');
+                }
+                if (errorTypes.has('connection_issues')) {
+                    recoverySteps.push('Connection validation failed. Check all node connections reference existing nodes.');
+                    recoverySteps.push('Use cleanStaleConnections operation to remove connections to non-existent nodes.');
+                }
+                if (errorTypes.has('missing_metadata')) {
+                    recoverySteps.push('Missing metadata detected. Ensure filter-based nodes (IF v2.2+, Switch v3.2+) have complete conditions.options.');
+                    recoverySteps.push('Required options: {version: 2, leftValue: "", caseSensitive: true, typeValidation: "strict"}');
+                }
+                if (errorTypes.has('branch_mismatch')) {
+                    recoverySteps.push('Branch count mismatch. Ensure Switch nodes have outputs for all rules (e.g., 3 rules = 3 output branches).');
+                }
+                if (recoverySteps.length === 0) {
+                    recoverySteps.push('Review the validation errors listed above');
+                    recoverySteps.push('Fix issues using updateNode or cleanStaleConnections operations');
+                    recoverySteps.push('Run validate_workflow again to verify fixes');
+                }
+                const errorMessage = structureErrors.length === 1
+                    ? `Workflow validation failed: ${structureErrors[0]}`
+                    : `Workflow validation failed with ${structureErrors.length} structural issues`;
+                if (!skipValidation) {
+                    return {
+                        success: false,
+                        error: errorMessage,
+                        details: {
+                            errors: structureErrors,
+                            errorCount: structureErrors.length,
+                            operationsApplied: diffResult.operationsApplied,
+                            applied: diffResult.applied,
+                            recoveryGuidance: recoverySteps,
+                            note: 'Operations were applied but created an invalid workflow structure. The workflow was NOT saved to n8n to prevent UI rendering errors.',
+                            autoSanitizationNote: 'Auto-sanitization runs on all nodes during updates to fix operator structures and add missing metadata. However, it cannot fix all issues (e.g., broken connections, branch mismatches). Use the recovery guidance above to resolve remaining issues.'
+                        }
+                    };
+                }
+                logger_1.logger.info('Workflow validation skipped (SKIP_WORKFLOW_VALIDATION=true): Allowing workflow with validation warnings to proceed', {
+                    workflowId: input.id,
+                    warningCount: structureErrors.length
+                });
+            }
+        }
+        try {
+            const updatedWorkflow = await client.updateWorkflow(input.id, diffResult.workflow);
+            let finalWorkflow = updatedWorkflow;
+            let activationMessage = '';
+            try {
+                const validator = getValidator(repository);
+                validationAfter = await validator.validateWorkflow(finalWorkflow, {
+                    validateNodes: true,
+                    validateConnections: true,
+                    validateExpressions: true,
+                    profile: 'runtime'
+                });
+            }
+            catch (validationError) {
+                logger_1.logger.debug('Post-mutation validation failed (non-blocking):', validationError);
+                validationAfter = {
+                    valid: false,
+                    errors: [{ type: 'validation_error', message: 'Validation failed' }]
+                };
+            }
+            if (diffResult.shouldActivate) {
+                try {
+                    finalWorkflow = await client.activateWorkflow(input.id);
+                    activationMessage = ' Workflow activated.';
+                }
+                catch (activationError) {
+                    logger_1.logger.error('Failed to activate workflow after update', activationError);
+                    return {
+                        success: false,
+                        error: 'Workflow updated successfully but activation failed',
+                        details: {
+                            workflowUpdated: true,
+                            activationError: activationError instanceof Error ? activationError.message : 'Unknown error'
+                        }
+                    };
+                }
+            }
+            else if (diffResult.shouldDeactivate) {
+                try {
+                    finalWorkflow = await client.deactivateWorkflow(input.id);
+                    activationMessage = ' Workflow deactivated.';
+                }
+                catch (deactivationError) {
+                    logger_1.logger.error('Failed to deactivate workflow after update', deactivationError);
+                    return {
+                        success: false,
+                        error: 'Workflow updated successfully but deactivation failed',
+                        details: {
+                            workflowUpdated: true,
+                            deactivationError: deactivationError instanceof Error ? deactivationError.message : 'Unknown error'
+                        }
+                    };
+                }
+            }
+            if (workflowBefore && !input.validateOnly) {
+                trackWorkflowMutation({
+                    sessionId,
+                    toolName: 'n8n_update_partial_workflow',
+                    userIntent: input.intent || 'Partial workflow update',
+                    operations: input.operations,
+                    workflowBefore,
+                    workflowAfter: finalWorkflow,
+                    validationBefore,
+                    validationAfter,
+                    mutationSuccess: true,
+                    durationMs: Date.now() - startTime,
+                }).catch(err => {
+                    logger_1.logger.debug('Failed to track mutation telemetry:', err);
+                });
+            }
+            return {
+                success: true,
+                data: {
+                    id: finalWorkflow.id,
+                    name: finalWorkflow.name,
+                    active: finalWorkflow.active,
+                    nodeCount: finalWorkflow.nodes?.length || 0,
+                    operationsApplied: diffResult.operationsApplied
+                },
+                message: `Workflow "${finalWorkflow.name}" updated successfully. Applied ${diffResult.operationsApplied} operations.${activationMessage} Use n8n_get_workflow with mode 'structure' to verify current state.`,
+                details: {
+                    applied: diffResult.applied,
+                    failed: diffResult.failed,
+                    errors: diffResult.errors,
+                    warnings: diffResult.warnings
+                }
+            };
+        }
+        catch (error) {
+            if (workflowBefore && !input.validateOnly) {
+                trackWorkflowMutation({
+                    sessionId,
+                    toolName: 'n8n_update_partial_workflow',
+                    userIntent: input.intent || 'Partial workflow update',
+                    operations: input.operations,
+                    workflowBefore,
+                    workflowAfter: workflowBefore,
+                    validationBefore,
+                    validationAfter: validationBefore,
+                    mutationSuccess: false,
+                    mutationError: error instanceof Error ? error.message : 'Unknown error',
+                    durationMs: Date.now() - startTime,
+                }).catch(err => {
+                    logger_1.logger.warn('Failed to track mutation telemetry for failed operation:', err);
+                });
+            }
+            if (error instanceof n8n_errors_1.N8nApiError) {
+                return {
+                    success: false,
+                    error: (0, n8n_errors_1.getUserFriendlyErrorMessage)(error),
+                    code: error.code,
+                    details: error.details
+                };
+            }
+            throw error;
+        }
+    }
+    catch (error) {
+        if (error instanceof zod_1.z.ZodError) {
+            return {
+                success: false,
+                error: 'Invalid input',
+                details: { errors: error.errors }
+            };
+        }
+        logger_1.logger.error('Failed to update partial workflow', error);
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Unknown error occurred'
+        };
+    }
+}
+function inferIntentFromOperations(operations) {
+    if (!operations || operations.length === 0) {
+        return 'Partial workflow update';
+    }
+    const opTypes = operations.map((op) => op.type);
+    const opCount = operations.length;
+    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}`;
+        }
+    }
+    const typeSet = new Set(opTypes);
+    const summary = [];
+    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`;
+}
+async function trackWorkflowMutation(data) {
+    try {
+        if (!data.userIntent ||
+            data.userIntent === 'Partial workflow update' ||
+            data.userIntent.length < 10) {
+            data.userIntent = inferIntentFromOperations(data.operations);
+        }
+        const { telemetry } = await Promise.resolve().then(() => __importStar(require('../telemetry/telemetry-manager.js')));
+        await telemetry.trackWorkflowMutation(data);
+    }
+    catch (error) {
+        logger_1.logger.debug('Telemetry tracking failed:', error);
+    }
+}
+//# sourceMappingURL=handlers-workflow-diff.js.map

dist/mcp/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

dist/mcp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":""}

dist/mcp/index.js

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const server_1 = require("./server");
+const logger_1 = require("../utils/logger");
+const config_manager_1 = require("../telemetry/config-manager");
+const early_error_logger_1 = require("../telemetry/early-error-logger");
+const startup_checkpoints_1 = require("../telemetry/startup-checkpoints");
+const fs_1 = require("fs");
+process.on('uncaughtException', (error) => {
+    if (process.env.MCP_MODE !== 'stdio') {
+        console.error('Uncaught Exception:', error);
+    }
+    logger_1.logger.error('Uncaught Exception:', error);
+    process.exit(1);
+});
+process.on('unhandledRejection', (reason, promise) => {
+    if (process.env.MCP_MODE !== 'stdio') {
+        console.error('Unhandled Rejection at:', promise, 'reason:', reason);
+    }
+    logger_1.logger.error('Unhandled Rejection:', reason);
+    process.exit(1);
+});
+function isContainerEnvironment() {
+    const dockerEnv = (process.env.IS_DOCKER || '').toLowerCase();
+    const containerEnv = (process.env.IS_CONTAINER || '').toLowerCase();
+    if (['true', '1', 'yes'].includes(dockerEnv)) {
+        return true;
+    }
+    if (['true', '1', 'yes'].includes(containerEnv)) {
+        return true;
+    }
+    try {
+        return (0, fs_1.existsSync)('/.dockerenv') || (0, fs_1.existsSync)('/run/.containerenv');
+    }
+    catch (error) {
+        logger_1.logger.debug('Container detection filesystem check failed:', error);
+        return false;
+    }
+}
+async function main() {
+    const startTime = Date.now();
+    const earlyLogger = early_error_logger_1.EarlyErrorLogger.getInstance();
+    const checkpoints = [];
+    try {
+        earlyLogger.logCheckpoint(startup_checkpoints_1.STARTUP_CHECKPOINTS.PROCESS_STARTED);
+        checkpoints.push(startup_checkpoints_1.STARTUP_CHECKPOINTS.PROCESS_STARTED);
+        const args = process.argv.slice(2);
+        if (args.length > 0 && args[0] === 'telemetry') {
+            const telemetryConfig = config_manager_1.TelemetryConfigManager.getInstance();
+            const action = args[1];
+            switch (action) {
+                case 'enable':
+                    telemetryConfig.enable();
+                    process.exit(0);
+                    break;
+                case 'disable':
+                    telemetryConfig.disable();
+                    process.exit(0);
+                    break;
+                case 'status':
+                    console.log(telemetryConfig.getStatus());
+                    process.exit(0);
+                    break;
+                default:
+                    console.log(`
+Usage: n8n-mcp telemetry [command]
+
+Commands:
+  enable   Enable anonymous telemetry
+  disable  Disable anonymous telemetry
+  status   Show current telemetry status
+
+Learn more: https://github.com/czlonkowski/n8n-mcp/blob/main/PRIVACY.md
+`);
+                    process.exit(args[1] ? 1 : 0);
+            }
+        }
+        const mode = process.env.MCP_MODE || 'stdio';
+        earlyLogger.logCheckpoint(startup_checkpoints_1.STARTUP_CHECKPOINTS.TELEMETRY_INITIALIZING);
+        checkpoints.push(startup_checkpoints_1.STARTUP_CHECKPOINTS.TELEMETRY_INITIALIZING);
+        earlyLogger.logCheckpoint(startup_checkpoints_1.STARTUP_CHECKPOINTS.TELEMETRY_READY);
+        checkpoints.push(startup_checkpoints_1.STARTUP_CHECKPOINTS.TELEMETRY_READY);
+        try {
+            if (mode === 'http') {
+                console.error(`Starting n8n Documentation MCP Server in ${mode} mode...`);
+                console.error('Current directory:', process.cwd());
+                console.error('Node version:', process.version);
+            }
+            earlyLogger.logCheckpoint(startup_checkpoints_1.STARTUP_CHECKPOINTS.MCP_HANDSHAKE_STARTING);
+            checkpoints.push(startup_checkpoints_1.STARTUP_CHECKPOINTS.MCP_HANDSHAKE_STARTING);
+            if (mode === 'http') {
+                if (process.env.USE_FIXED_HTTP === 'true') {
+                    const { startFixedHTTPServer } = await Promise.resolve().then(() => __importStar(require('../http-server')));
+                    await startFixedHTTPServer();
+                }
+                else {
+                    const { SingleSessionHTTPServer } = await Promise.resolve().then(() => __importStar(require('../http-server-single-session')));
+                    const server = new SingleSessionHTTPServer();
+                    const shutdown = async () => {
+                        await server.shutdown();
+                        process.exit(0);
+                    };
+                    process.on('SIGTERM', shutdown);
+                    process.on('SIGINT', shutdown);
+                    await server.start();
+                }
+            }
+            else {
+                const server = new server_1.N8NDocumentationMCPServer(undefined, earlyLogger);
+                let isShuttingDown = false;
+                const shutdown = async (signal = 'UNKNOWN') => {
+                    if (isShuttingDown)
+                        return;
+                    isShuttingDown = true;
+                    try {
+                        logger_1.logger.info(`Shutdown initiated by: ${signal}`);
+                        await server.shutdown();
+                        if (process.stdin && !process.stdin.destroyed) {
+                            process.stdin.pause();
+                            process.stdin.destroy();
+                        }
+                        setTimeout(() => {
+                            logger_1.logger.warn('Shutdown timeout exceeded, forcing exit');
+                            process.exit(0);
+                        }, 1000).unref();
+                    }
+                    catch (error) {
+                        logger_1.logger.error('Error during shutdown:', error);
+                        process.exit(1);
+                    }
+                };
+                process.on('SIGTERM', () => shutdown('SIGTERM'));
+                process.on('SIGINT', () => shutdown('SIGINT'));
+                process.on('SIGHUP', () => shutdown('SIGHUP'));
+                const isContainer = isContainerEnvironment();
+                if (!isContainer && process.stdin.readable && !process.stdin.destroyed) {
+                    try {
+                        process.stdin.on('end', () => shutdown('STDIN_END'));
+                        process.stdin.on('close', () => shutdown('STDIN_CLOSE'));
+                    }
+                    catch (error) {
+                        logger_1.logger.error('Failed to register stdin handlers, using signal handlers only:', error);
+                    }
+                }
+                await server.run();
+            }
+            earlyLogger.logCheckpoint(startup_checkpoints_1.STARTUP_CHECKPOINTS.MCP_HANDSHAKE_COMPLETE);
+            checkpoints.push(startup_checkpoints_1.STARTUP_CHECKPOINTS.MCP_HANDSHAKE_COMPLETE);
+            earlyLogger.logCheckpoint(startup_checkpoints_1.STARTUP_CHECKPOINTS.SERVER_READY);
+            checkpoints.push(startup_checkpoints_1.STARTUP_CHECKPOINTS.SERVER_READY);
+            const startupDuration = Date.now() - startTime;
+            earlyLogger.logStartupSuccess(checkpoints, startupDuration);
+            logger_1.logger.info(`Server startup completed in ${startupDuration}ms (${checkpoints.length} checkpoints passed)`);
+        }
+        catch (error) {
+            const failedCheckpoint = (0, startup_checkpoints_1.findFailedCheckpoint)(checkpoints);
+            earlyLogger.logStartupError(failedCheckpoint, error);
+            if (mode !== 'stdio') {
+                console.error('Failed to start MCP server:', error);
+                logger_1.logger.error('Failed to start MCP server', error);
+                if (error instanceof Error && error.message.includes('nodes.db not found')) {
+                    console.error('\nTo fix this issue:');
+                    console.error('1. cd to the n8n-mcp directory');
+                    console.error('2. Run: npm run build');
+                    console.error('3. Run: npm run rebuild');
+                }
+                else if (error instanceof Error && error.message.includes('NODE_MODULE_VERSION')) {
+                    console.error('\nTo fix this Node.js version mismatch:');
+                    console.error('1. cd to the n8n-mcp directory');
+                    console.error('2. Run: npm rebuild better-sqlite3');
+                    console.error('3. If that doesn\'t work, try: rm -rf node_modules && npm install');
+                }
+            }
+            process.exit(1);
+        }
+    }
+    catch (outerError) {
+        logger_1.logger.error('Critical startup error:', outerError);
+        process.exit(1);
+    }
+}
+if (require.main === module) {
+    main().catch(console.error);
+}
+//# sourceMappingURL=index.js.map

dist/mcp/server.d.ts

@@ -0,0 +1,81 @@
+import { InstanceContext } from '../types/instance-context';
+import { EarlyErrorLogger } from '../telemetry/early-error-logger';
+export declare class N8NDocumentationMCPServer {
+    private server;
+    private db;
+    private repository;
+    private templateService;
+    private initialized;
+    private cache;
+    private clientInfo;
+    private instanceContext?;
+    private previousTool;
+    private previousToolTimestamp;
+    private earlyLogger;
+    private disabledToolsCache;
+    constructor(instanceContext?: InstanceContext, earlyLogger?: EarlyErrorLogger);
+    close(): Promise<void>;
+    private initializeDatabase;
+    private initializeInMemorySchema;
+    private parseSQLStatements;
+    private ensureInitialized;
+    private dbHealthChecked;
+    private validateDatabaseHealth;
+    private getDisabledTools;
+    private setupHandlers;
+    private sanitizeValidationResult;
+    private validateToolParams;
+    private validateToolParamsBasic;
+    private validateExtractedArgs;
+    private listNodes;
+    private getNodeInfo;
+    private searchNodes;
+    private searchNodesFTS;
+    private searchNodesFuzzy;
+    private calculateFuzzyScore;
+    private getEditDistance;
+    private searchNodesLIKE;
+    private calculateRelevance;
+    private calculateRelevanceScore;
+    private rankSearchResults;
+    private listAITools;
+    private getNodeDocumentation;
+    private getDatabaseStatistics;
+    private getNodeEssentials;
+    private getNode;
+    private handleInfoMode;
+    private handleVersionMode;
+    private getVersionSummary;
+    private getVersionHistory;
+    private compareVersions;
+    private getBreakingChanges;
+    private getMigrations;
+    private enrichPropertyWithTypeInfo;
+    private enrichPropertiesWithTypeInfo;
+    private searchNodeProperties;
+    private getPropertyValue;
+    private listTasks;
+    private validateNodeConfig;
+    private getPropertyDependencies;
+    private getNodeAsToolInfo;
+    private getOutputDescriptions;
+    private getCommonAIToolUseCases;
+    private buildToolVariantGuidance;
+    private getAIToolExamples;
+    private validateNodeMinimal;
+    private getToolsDocumentation;
+    connect(transport: any): Promise<void>;
+    private listTemplates;
+    private listNodeTemplates;
+    private getTemplate;
+    private searchTemplates;
+    private getTemplatesForTask;
+    private searchTemplatesByMetadata;
+    private getTaskDescription;
+    private validateWorkflow;
+    private validateWorkflowConnections;
+    private validateWorkflowExpressions;
+    run(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=server.d.ts.map

dist/mcp/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAsCA,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAE5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAgGnE,qBAAa,yBAAyB;IACpC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,EAAE,CAAgC;IAC1C,OAAO,CAAC,UAAU,CAA+B;IACjD,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,WAAW,CAAgB;IACnC,OAAO,CAAC,KAAK,CAAqB;IAClC,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,eAAe,CAAC,CAAkB;IAC1C,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,qBAAqB,CAAsB;IACnD,OAAO,CAAC,WAAW,CAAiC;IACpD,OAAO,CAAC,kBAAkB,CAA4B;gBAE1C,eAAe,CAAC,EAAE,eAAe,EAAE,WAAW,CAAC,EAAE,gBAAgB;IAiGvE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YA6Bd,kBAAkB;YAwClB,wBAAwB;IA0BtC,OAAO,CAAC,kBAAkB;YA6CZ,iBAAiB;IAa/B,OAAO,CAAC,eAAe,CAAkB;YAE3B,sBAAsB;IAgDpC,OAAO,CAAC,gBAAgB;IAqCxB,OAAO,CAAC,aAAa;IAoTrB,OAAO,CAAC,wBAAwB;IAoFhC,OAAO,CAAC,kBAAkB;IAqE1B,OAAO,CAAC,uBAAuB;IAwB/B,OAAO,CAAC,qBAAqB;YAgTf,SAAS;YA2DT,WAAW;YAkFX,WAAW;YAyCX,cAAc;YAyKd,gBAAgB;IAqD9B,OAAO,CAAC,mBAAmB;IAwE3B,OAAO,CAAC,eAAe;YAsBT,eAAe;IAqI7B,OAAO,CAAC,kBAAkB;IAQ1B,OAAO,CAAC,uBAAuB;IA0D/B,OAAO,CAAC,iBAAiB;YAqFX,WAAW;YAgCX,oBAAoB;YA2EpB,qBAAqB;YAwDrB,iBAAiB;YAiKjB,OAAO;YAgDP,cAAc;YAwFd,iBAAiB;IAqC/B,OAAO,CAAC,iBAAiB;IA0BzB,OAAO,CAAC,iBAAiB;IA0BzB,OAAO,CAAC,eAAe;IAwCvB,OAAO,CAAC,kBAAkB;IAiC1B,OAAO,CAAC,aAAa;IAoCrB,OAAO,CAAC,0BAA0B;IAgClC,OAAO,CAAC,4BAA4B;YAKtB,oBAAoB;IAsDlC,OAAO,CAAC,gBAAgB;YAiBV,SAAS;YA6CT,kBAAkB;YAqElB,uBAAuB;YAsDvB,iBAAiB;IAqE/B,OAAO,CAAC,qBAAqB;IA8C7B,OAAO,CAAC,uBAAuB;IA4D/B,OAAO,CAAC,wBAAwB;IAkChC,OAAO,CAAC,iBAAiB;YAoDX,mBAAmB;YAoEnB,qBAAqB;IAS7B,OAAO,CAAC,SAAS,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;YAS9B,aAAa;YAcb,iBAAiB;YAoBjB,WAAW;YAwBX,eAAe;YAqBf,mBAAmB;YAwBnB,yBAAyB;IA4CvC,OAAO,CAAC,kBAAkB;YAiBZ,gBAAgB;YA6HhB,2BAA2B;YAiE3B,2BAA2B;IAyEnC,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IA0BpB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAuBhC"}

dist/mcp/stdio-wrapper.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=stdio-wrapper.d.ts.map

dist/mcp/stdio-wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio-wrapper.d.ts","sourceRoot":"","sources":["../../src/mcp/stdio-wrapper.ts"],"names":[],"mappings":""}

dist/mcp/stdio-wrapper.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+process.env.MCP_MODE = 'stdio';
+process.env.DISABLE_CONSOLE_OUTPUT = 'true';
+process.env.LOG_LEVEL = 'error';
+const originalConsoleLog = console.log;
+const originalConsoleError = console.error;
+const originalConsoleWarn = console.warn;
+const originalConsoleInfo = console.info;
+const originalConsoleDebug = console.debug;
+const originalConsoleTrace = console.trace;
+const originalConsoleDir = console.dir;
+const originalConsoleTime = console.time;
+const originalConsoleTimeEnd = console.timeEnd;
+console.log = () => { };
+console.error = () => { };
+console.warn = () => { };
+console.info = () => { };
+console.debug = () => { };
+console.trace = () => { };
+console.dir = () => { };
+console.time = () => { };
+console.timeEnd = () => { };
+console.timeLog = () => { };
+console.group = () => { };
+console.groupEnd = () => { };
+console.table = () => { };
+console.clear = () => { };
+console.count = () => { };
+console.countReset = () => { };
+const server_1 = require("./server");
+let server = null;
+async function main() {
+    try {
+        server = new server_1.N8NDocumentationMCPServer();
+        await server.run();
+    }
+    catch (error) {
+        originalConsoleError('Fatal error:', error);
+        process.exit(1);
+    }
+}
+process.on('uncaughtException', (error) => {
+    originalConsoleError('Uncaught exception:', error);
+    process.exit(1);
+});
+process.on('unhandledRejection', (reason) => {
+    originalConsoleError('Unhandled rejection:', reason);
+    process.exit(1);
+});
+let isShuttingDown = false;
+async function shutdown(signal) {
+    if (isShuttingDown)
+        return;
+    isShuttingDown = true;
+    originalConsoleError(`Received ${signal}, shutting down gracefully...`);
+    try {
+        if (server) {
+            await server.shutdown();
+        }
+    }
+    catch (error) {
+        originalConsoleError('Error during shutdown:', error);
+    }
+    process.stdin.pause();
+    process.stdin.destroy();
+    setTimeout(() => {
+        process.exit(0);
+    }, 500).unref();
+    process.exit(0);
+}
+process.on('SIGTERM', () => void shutdown('SIGTERM'));
+process.on('SIGINT', () => void shutdown('SIGINT'));
+process.on('SIGHUP', () => void shutdown('SIGHUP'));
+process.stdin.on('end', () => {
+    originalConsoleError('stdin closed, shutting down...');
+    void shutdown('STDIN_CLOSE');
+});
+main();
+//# sourceMappingURL=stdio-wrapper.js.map

dist/mcp/stdio-wrapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio-wrapper.js","sourceRoot":"","sources":["../../src/mcp/stdio-wrapper.ts"],"names":[],"mappings":"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"}

dist/mcp/tool-docs/configuration/get-node.d.ts

@@ -0,0 +1,3 @@
+import { ToolDocumentation } from '../types';
+export declare const getNodeDoc: ToolDocumentation;
+//# sourceMappingURL=get-node.d.ts.map

dist/mcp/tool-docs/configuration/get-node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-node.d.ts","sourceRoot":"","sources":["../../../../src/mcp/tool-docs/configuration/get-node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE7C,eAAO,MAAM,UAAU,EAAE,iBAqFxB,CAAC"}

dist/mcp/tool-docs/configuration/get-node.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getNodeDoc = void 0;
+exports.getNodeDoc = {
+    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']
+    }
+};
+//# sourceMappingURL=get-node.js.map

dist/mcp/tool-docs/configuration/get-node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-node.js","sourceRoot":"","sources":["../../../../src/mcp/tool-docs/configuration/get-node.ts"],"names":[],"mappings":";;;AAEa,QAAA,UAAU,GAAsB;IAC3C,IAAI,EAAE,UAAU;IAChB,QAAQ,EAAE,eAAe;IACzB,UAAU,EAAE;QACV,WAAW,EAAE,6IAA6I;QAC1J,aAAa,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,iBAAiB,EAAE,iBAAiB,CAAC;QACnF,OAAO,EAAE,oEAAoE;QAC7E,WAAW,EAAE,yDAAyD;QACtE,IAAI,EAAE;YACJ,wEAAwE;YACxE,qDAAqD;YACrD,yEAAyE;YACzE,mEAAmE;YACnE,mEAAmE;SACpE;KACF;IACD,IAAI,EAAE;QACJ,WAAW,EAAE;;;;;;;;;;;;4DAY2C;QACxD,UAAU,EAAE;YACV,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,iFAAiF,EAAE;YAC5I,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,qEAAqE,EAAE;YAC/H,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,gHAAgH,EAAE;YACxK,eAAe,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,gGAAgG,EAAE;YACpK,eAAe,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,4FAA4F,EAAE;YAChK,aAAa,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,6FAA6F,EAAE;YAC9J,kBAAkB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,sDAAsD,EAAE;YAC5H,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,qEAAqE,EAAE;YACpI,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,oEAAoE,EAAE;SAClI;QACD,OAAO,EAAE;;;;;0DAK6C;QACtD,QAAQ,EAAE;YACR,gGAAgG;YAChG,kGAAkG;YAClG,sHAAsH;YACtH,yFAAyF;YACzF,2IAA2I;YAC3I,gGAAgG;YAChG,qIAAqI;SACtI;QACD,QAAQ,EAAE;YACR,6DAA6D;YAC7D,kEAAkE;YAClE,uDAAuD;YACvD,wEAAwE;YACxE,oDAAoD;SACrD;QACD,WAAW,EAAE;;;;;;kCAMiB;QAC9B,aAAa,EAAE;YACb,2DAA2D;YAC3D,mEAAmE;YACnE,gDAAgD;YAChD,yEAAyE;YACzE,0DAA0D;SAC3D;QACD,QAAQ,EAAE;YACR,gEAAgE;YAChE,iEAAiE;YACjE,+DAA+D;YAC/D,gEAAgE;SACjE;QACD,YAAY,EAAE,CAAC,cAAc,EAAE,eAAe,EAAE,mBAAmB,CAAC;KACrE;CACF,CAAC"}

dist/mcp/tool-docs/configuration/index.d.ts

@@ -0,0 +1,2 @@
+export { getNodeDoc } from './get-node';
+//# sourceMappingURL=index.d.ts.map

dist/mcp/tool-docs/configuration/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/mcp/tool-docs/configuration/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

dist/mcp/tool-docs/configuration/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getNodeDoc = void 0;
+var get_node_1 = require("./get-node");
+Object.defineProperty(exports, "getNodeDoc", { enumerable: true, get: function () { return get_node_1.getNodeDoc; } });
+//# sourceMappingURL=index.js.map

dist/mcp/tool-docs/configuration/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/mcp/tool-docs/configuration/index.ts"],"names":[],"mappings":";;;AAAA,uCAAwC;AAA/B,sGAAA,UAAU,OAAA"}

dist/mcp/tool-docs/discovery/index.d.ts

@@ -0,0 +1,2 @@
+export { searchNodesDoc } from './search-nodes';
+//# sourceMappingURL=index.d.ts.map

dist/mcp/tool-docs/discovery/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/mcp/tool-docs/discovery/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC"}

dist/mcp/tool-docs/discovery/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchNodesDoc = void 0;
+var search_nodes_1 = require("./search-nodes");
+Object.defineProperty(exports, "searchNodesDoc", { enumerable: true, get: function () { return search_nodes_1.searchNodesDoc; } });
+//# sourceMappingURL=index.js.map

dist/mcp/tool-docs/discovery/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/mcp/tool-docs/discovery/index.ts"],"names":[],"mappings":";;;AAAA,+CAAgD;AAAvC,8GAAA,cAAc,OAAA"}