Merge pull request #280 from czlonkowski/security/issue-265-pr2-rate-limiting-and-ssrf

Security Audit PR #2: Rate Limiting & SSRF Protection (HIGH-02, HIGH-03)

.env.example

@@ -69,6 +69,55 @@ AUTH_TOKEN=your-secure-token-here
 # Default: 0 (disabled)
 # TRUST_PROXY=0
 
+# =========================
+# SECURITY CONFIGURATION
+# =========================
+
+# Rate Limiting Configuration
+# Protects authentication endpoint from brute force attacks
+# Window: Time period in milliseconds (default: 900000 = 15 minutes)
+# Max: Maximum authentication attempts per IP within window (default: 20)
+# AUTH_RATE_LIMIT_WINDOW=900000
+# AUTH_RATE_LIMIT_MAX=20
+
+# SSRF Protection Mode
+# Prevents webhooks from accessing internal networks and cloud metadata
+#
+# Modes:
+# - strict (default): Block localhost + private IPs + cloud metadata
+#   Use for: Production deployments, cloud environments
+#   Security: Maximum
+#
+# - moderate: Allow localhost, block private IPs + cloud metadata
+#   Use for: Local development with local n8n instance
+#   Security: Good balance
+#   Example: n8n running on http://localhost:5678 or http://host.docker.internal:5678
+#
+# - permissive: Allow localhost + private IPs, block cloud metadata
+#   Use for: Internal network testing, private cloud (NOT for production)
+#   Security: Minimal - use with caution
+#
+# Default: strict
+# WEBHOOK_SECURITY_MODE=strict
+#
+# For local development with local n8n:
+# WEBHOOK_SECURITY_MODE=moderate
+
+# =========================
+# MULTI-TENANT CONFIGURATION
+# =========================
+# Enable multi-tenant mode for dynamic instance support
+# When enabled, n8n API tools will be available for all sessions,
+# and instance configuration will be determined from HTTP headers
+# Default: false (single-tenant mode using environment variables)
+ENABLE_MULTI_TENANT=false
+
+# Session isolation strategy for multi-tenant mode
+# - "instance": Create separate sessions per instance ID (recommended)
+# - "shared": Share sessions but switch contexts (advanced)
+# Default: instance
+# MULTI_TENANT_SESSION_STRATEGY=instance
+
 # =========================
 # N8N API CONFIGURATION
 # =========================
@@ -88,6 +137,17 @@ AUTH_TOKEN=your-secure-token-here
 # Maximum number of API request retries (default: 3)
 # N8N_API_MAX_RETRIES=3
 
+# =========================
+# CACHE CONFIGURATION
+# =========================
+# Optional: Configure instance cache settings for flexible instance support
+
+# Maximum number of cached instances (default: 100, min: 1, max: 10000)
+# INSTANCE_CACHE_MAX=100
+
+# Cache TTL in minutes (default: 30, min: 1, max: 1440/24 hours)
+# INSTANCE_CACHE_TTL_MINUTES=30
+
 # =========================
 # OPENAI API CONFIGURATION
 # =========================
@@ -106,4 +166,36 @@ AUTH_TOKEN=your-secure-token-here
 
 # Enable metadata generation during template fetch (default: false)
 # Set to true to automatically generate metadata when running fetch:templates
-# METADATA_GENERATION_ENABLED=false
+# METADATA_GENERATION_ENABLED=false
+
+# ========================================
+# INTEGRATION TESTING CONFIGURATION
+# ========================================
+# Configuration for integration tests that call real n8n instance API
+
+# n8n API Configuration for Integration Tests
+# For local development: Use your local n8n instance
+# For CI: These will be provided by GitHub secrets
+# N8N_API_URL=http://localhost:5678
+# N8N_API_KEY=
+
+# Pre-activated Webhook Workflows for Testing
+# These workflows must be created manually in n8n and activated
+# because n8n API doesn't support workflow activation.
+#
+# Setup Instructions:
+# 1. Create 4 workflows in n8n UI (one for each HTTP method)
+# 2. Each workflow should have a single Webhook node
+# 3. Configure webhook paths: mcp-test-get, mcp-test-post, mcp-test-put, mcp-test-delete
+# 4. ACTIVATE each workflow in n8n UI
+# 5. Copy the workflow IDs here
+#
+# N8N_TEST_WEBHOOK_GET_ID=      # Workflow ID for GET method webhook
+# N8N_TEST_WEBHOOK_POST_ID=     # Workflow ID for POST method webhook
+# N8N_TEST_WEBHOOK_PUT_ID=      # Workflow ID for PUT method webhook
+# N8N_TEST_WEBHOOK_DELETE_ID=   # Workflow ID for DELETE method webhook
+
+# Test Configuration
+N8N_TEST_CLEANUP_ENABLED=true         # Enable automatic cleanup of test workflows
+N8N_TEST_TAG=mcp-integration-test     # Tag applied to all test workflows
+N8N_TEST_NAME_PREFIX=[MCP-TEST]       # Name prefix for test workflows

.github/workflows/test.yml

@@ -72,6 +72,12 @@ jobs:
         run: npm run test:integration -- --reporter=default --reporter=junit
         env:
           CI: true
+          N8N_API_URL: ${{ secrets.N8N_API_URL }}
+          N8N_API_KEY: ${{ secrets.N8N_API_KEY }}
+          N8N_TEST_WEBHOOK_GET_URL: ${{ secrets.N8N_TEST_WEBHOOK_GET_URL }}
+          N8N_TEST_WEBHOOK_POST_URL: ${{ secrets.N8N_TEST_WEBHOOK_POST_URL }}
+          N8N_TEST_WEBHOOK_PUT_URL: ${{ secrets.N8N_TEST_WEBHOOK_PUT_URL }}
+          N8N_TEST_WEBHOOK_DELETE_URL: ${{ secrets.N8N_TEST_WEBHOOK_DELETE_URL }}
       
       # Generate test summary
       - name: Generate test summary

.gitignore

@@ -89,6 +89,13 @@ docker-compose.override.yml
 temp/
 tmp/
 
+# Batch processing error files (may contain API tokens from templates)
+docs/batch_*.jsonl
+**/batch_*_error.jsonl
+
+# Local documentation and analysis files
+docs/local/
+
 # Database files
 # Database files - nodes.db is now tracked directly
 # data/*.db
@@ -130,3 +137,6 @@ n8n-mcp-wrapper.sh
 
 # MCP configuration files
 .mcp.json
+
+# Telemetry configuration (user-specific)
+~/.n8n-mcp/

Dockerfile

@@ -15,7 +15,7 @@ RUN --mount=type=cache,target=/root/.npm \
     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 \
         n8n-workflow@^1.96.0 uuid@^11.0.5 @types/uuid@^10.0.0 \
-        openai@^4.77.0 zod@^3.24.1
+        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
@@ -74,6 +74,10 @@ USER nodejs
 # Set Docker environment flag
 ENV IS_DOCKER=true
 
+# Telemetry: Anonymous usage statistics are ENABLED by default
+# To opt-out, uncomment the following line:
+# ENV N8N_MCP_TELEMETRY_DISABLED=true
+
 # Expose HTTP port
 EXPOSE 3000
 

MEMORY_TEMPLATE_UPDATE.md

@@ -0,0 +1,336 @@
+# Template Update Process - Quick Reference
+
+## Overview
+
+The n8n-mcp project maintains a database of workflow templates from n8n.io. This guide explains how to update the template database incrementally without rebuilding from scratch.
+
+## Current Database State
+
+As of the last update:
+- **2,598 templates** in database
+- Templates from the last 12 months
+- Latest template: September 12, 2025
+
+## Quick Commands
+
+### Incremental Update (Recommended)
+```bash
+# Build if needed
+npm run build
+
+# Fetch only NEW templates (5-10 minutes)
+npm run fetch:templates:update
+```
+
+### Full Rebuild (Rare)
+```bash
+# Rebuild entire database from scratch (30-40 minutes)
+npm run fetch:templates
+```
+
+## How It Works
+
+### Incremental Update Mode (`--update`)
+
+The incremental update is **smart and efficient**:
+
+1. **Loads existing template IDs** from database (~2,598 templates)
+2. **Fetches template list** from n8n.io API (all templates from last 12 months)
+3. **Filters** to find only NEW templates not in database
+4. **Fetches details** for new templates only (saves time and API calls)
+5. **Saves** new templates to database (existing ones untouched)
+6. **Rebuilds FTS5** search index for new templates
+
+### Key Benefits
+
+✅ **Non-destructive**: All existing templates preserved
+✅ **Fast**: Only fetches new templates (5-10 min vs 30-40 min)
+✅ **API friendly**: Reduces load on n8n.io API
+✅ **Safe**: Preserves AI-generated metadata
+✅ **Smart**: Automatically skips duplicates
+
+## Performance Comparison
+
+| Mode | Templates Fetched | Time | Use Case |
+|------|------------------|------|----------|
+| **Update** | Only new (~50-200) | 5-10 min | Regular updates |
+| **Rebuild** | All (~8000+) | 30-40 min | Initial setup or corruption |
+
+## Command Options
+
+### Basic Update
+```bash
+npm run fetch:templates:update
+```
+
+### Full Rebuild
+```bash
+npm run fetch:templates
+```
+
+### With Metadata Generation
+```bash
+# Update templates and generate AI metadata
+npm run fetch:templates -- --update --generate-metadata
+
+# Or just generate metadata for existing templates
+npm run fetch:templates -- --metadata-only
+```
+
+### Help
+```bash
+npm run fetch:templates -- --help
+```
+
+## Update Frequency
+
+Recommended update schedule:
+- **Weekly**: Run incremental update to get latest templates
+- **Monthly**: Review database statistics
+- **As needed**: Rebuild only if database corruption suspected
+
+## Template Filtering
+
+The fetcher automatically filters templates:
+- ✅ **Includes**: Templates from last 12 months
+- ✅ **Includes**: Templates with >10 views
+- ❌ **Excludes**: Templates with ≤10 views (too niche)
+- ❌ **Excludes**: Templates older than 12 months
+
+## Workflow
+
+### Regular Update Workflow
+
+```bash
+# 1. Check current state
+sqlite3 data/nodes.db "SELECT COUNT(*) FROM templates"
+
+# 2. Build project (if code changed)
+npm run build
+
+# 3. Run incremental update
+npm run fetch:templates:update
+
+# 4. Verify new templates added
+sqlite3 data/nodes.db "SELECT COUNT(*) FROM templates"
+```
+
+### After n8n Dependency Update
+
+When you update n8n dependencies, templates remain compatible:
+```bash
+# 1. Update n8n (from MEMORY_N8N_UPDATE.md)
+npm run update:all
+
+# 2. Fetch new templates incrementally
+npm run fetch:templates:update
+
+# 3. Check how many templates were added
+sqlite3 data/nodes.db "SELECT COUNT(*) FROM templates"
+
+# 4. Generate AI metadata for new templates (optional, requires OPENAI_API_KEY)
+npm run fetch:templates -- --metadata-only
+
+# 5. IMPORTANT: Sanitize templates before pushing database
+npm run build
+npm run sanitize:templates
+```
+
+Templates are independent of n8n version - they're just workflow JSON data.
+
+**CRITICAL**: Always run `npm run sanitize:templates` before pushing the database to remove API tokens from template workflows.
+
+**Note**: New templates fetched via `--update` mode will NOT have AI-generated metadata by default. You need to run `--metadata-only` separately to generate metadata for templates that don't have it yet.
+
+## Troubleshooting
+
+### No New Templates Found
+
+This is normal! It means:
+- All recent templates are already in your database
+- n8n.io hasn't published many new templates recently
+- Your database is up to date
+
+```bash
+📊 Update mode: 0 new templates to fetch (skipping 2598 existing)
+✅ All templates already have metadata
+```
+
+### API Rate Limiting
+
+If you hit rate limits:
+- The fetcher includes built-in delays (150ms between requests)
+- Wait a few minutes and try again
+- Use `--update` mode instead of full rebuild
+
+### Database Corruption
+
+If you suspect corruption:
+```bash
+# Full rebuild from scratch
+npm run fetch:templates
+
+# This will:
+# - Drop and recreate templates table
+# - Fetch all templates fresh
+# - Rebuild search indexes
+```
+
+## Database Schema
+
+Templates are stored with:
+- Basic info (id, name, description, author, views, created_at)
+- Node types used (JSON array)
+- Complete workflow (gzip compressed, base64 encoded)
+- AI-generated metadata (optional, requires OpenAI API key)
+- FTS5 search index for fast text search
+
+## Metadata Generation
+
+Generate AI metadata for templates:
+```bash
+# Requires OPENAI_API_KEY in .env
+export OPENAI_API_KEY="sk-..."
+
+# Generate for templates without metadata (recommended after incremental update)
+npm run fetch:templates -- --metadata-only
+
+# Generate during template fetch (slower, but automatic)
+npm run fetch:templates:update -- --generate-metadata
+```
+
+**Important**: Incremental updates (`--update`) do NOT generate metadata by default. After running `npm run fetch:templates:update`, you'll have new templates without metadata. Run `--metadata-only` separately to generate metadata for them.
+
+### Check Metadata Coverage
+
+```bash
+# See how many templates have metadata
+sqlite3 data/nodes.db "SELECT
+  COUNT(*) as total,
+  SUM(CASE WHEN metadata_json IS NOT NULL THEN 1 ELSE 0 END) as with_metadata,
+  SUM(CASE WHEN metadata_json IS NULL THEN 1 ELSE 0 END) as without_metadata
+FROM templates"
+
+# See recent templates without metadata
+sqlite3 data/nodes.db "SELECT id, name, created_at
+FROM templates
+WHERE metadata_json IS NULL
+ORDER BY created_at DESC
+LIMIT 10"
+```
+
+Metadata includes:
+- Categories
+- Complexity level (simple/medium/complex)
+- Use cases
+- Estimated setup time
+- Required services
+- Key features
+- Target audience
+
+### Metadata Generation Troubleshooting
+
+If metadata generation fails:
+
+1. **Check error file**: Errors are saved to `temp/batch/batch_*_error.jsonl`
+2. **Common issues**:
+   - `"Unsupported value: 'temperature'"` - Model doesn't support custom temperature
+   - `"Invalid request"` - Check OPENAI_API_KEY is valid
+   - Model availability issues
+3. **Model**: Uses `gpt-5-mini-2025-08-07` by default
+4. **Token limit**: 3000 tokens per request for detailed metadata
+
+The system will automatically:
+- Process error files and assign default metadata to failed templates
+- Save error details for debugging
+- Continue processing even if some templates fail
+
+**Example error handling**:
+```bash
+# If you see: "No output file available for batch job"
+# Check: temp/batch/batch_*_error.jsonl for error details
+# The system now automatically processes errors and generates default metadata
+```
+
+## Environment Variables
+
+Optional configuration:
+```bash
+# OpenAI for metadata generation
+OPENAI_API_KEY=sk-...
+OPENAI_MODEL=gpt-4o-mini  # Default model
+OPENAI_BATCH_SIZE=50      # Batch size for metadata generation
+
+# Metadata generation limits
+METADATA_LIMIT=100        # Max templates to process (0 = all)
+```
+
+## Statistics
+
+After update, check stats:
+```bash
+# Template count
+sqlite3 data/nodes.db "SELECT COUNT(*) FROM templates"
+
+# Most recent template
+sqlite3 data/nodes.db "SELECT MAX(created_at) FROM templates"
+
+# Templates by view count
+sqlite3 data/nodes.db "SELECT COUNT(*),
+  CASE
+    WHEN views < 50 THEN '<50'
+    WHEN views < 100 THEN '50-100'
+    WHEN views < 500 THEN '100-500'
+    ELSE '500+'
+  END as view_range
+  FROM templates GROUP BY view_range"
+```
+
+## Integration with n8n-mcp
+
+Templates are available through MCP tools:
+- `list_templates`: List all templates
+- `get_template`: Get specific template with workflow
+- `search_templates`: Search by keyword
+- `list_node_templates`: Templates using specific nodes
+- `get_templates_for_task`: Templates for common tasks
+- `search_templates_by_metadata`: Advanced filtering
+
+See `npm run test:templates` for usage examples.
+
+## Time Estimates
+
+Typical incremental update:
+- Loading existing IDs: 1-2 seconds
+- Fetching template list: 2-3 minutes
+- Filtering new templates: instant
+- Fetching details for 100 new templates: ~15 seconds (0.15s each)
+- Saving and indexing: 5-10 seconds
+- **Total: 3-5 minutes**
+
+Full rebuild:
+- Fetching 8000+ templates: 25-30 minutes
+- Saving and indexing: 5-10 minutes
+- **Total: 30-40 minutes**
+
+## Best Practices
+
+1. **Use incremental updates** for regular maintenance
+2. **Rebuild only when necessary** (corruption, major changes)
+3. **Generate metadata incrementally** to avoid OpenAI costs
+4. **Monitor template count** to verify updates working
+5. **Keep database backed up** before major operations
+
+## Next Steps
+
+After updating templates:
+1. Test template search: `npm run test:templates`
+2. Verify MCP tools work: Test in Claude Desktop
+3. Check statistics in database
+4. Commit changes if desired (database changes)
+
+## Related Documentation
+
+- `MEMORY_N8N_UPDATE.md` - Updating n8n dependencies
+- `CLAUDE.md` - Project overview and architecture
+- `README.md` - User documentation

P0-R3-TEST-PLAN.md

@@ -0,0 +1,484 @@
+# P0-R3 Feature Test Coverage Plan
+
+## Executive Summary
+
+This document outlines comprehensive test coverage for the P0-R3 feature (Template-based Configuration Examples). The feature adds real-world configuration examples from popular templates to node search and essentials tools.
+
+**Feature Overview:**
+- New database table: `template_node_configs` (197 pre-extracted configurations)
+- Enhanced tools: `search_nodes({includeExamples: true})` and `get_node_essentials({includeExamples: true})`
+- Breaking changes: Removed `get_node_for_task` tool
+
+## Test Files Created
+
+### Unit Tests
+
+#### 1. `/tests/unit/scripts/fetch-templates-extraction.test.ts` ✅
+**Purpose:** Test template extraction logic from `fetch-templates.ts`
+
+**Coverage:**
+- `extractNodeConfigs()` - 90%+ coverage
+  - Valid workflows with multiple nodes
+  - Empty workflows
+  - Malformed compressed data
+  - Invalid JSON
+  - Nodes without parameters
+  - Sticky note filtering
+  - Credential handling
+  - Expression detection
+  - Special characters
+  - Large workflows (100 nodes)
+
+- `detectExpressions()` - 100% coverage
+  - `={{...}}` syntax detection
+  - `$json` references
+  - `$node` references
+  - Nested objects
+  - Arrays
+  - Null/undefined handling
+  - Multiple expression types
+
+**Test Count:** 27 tests
+**Expected Coverage:** 92%+
+
+---
+
+#### 2. `/tests/unit/mcp/search-nodes-examples.test.ts` ✅
+**Purpose:** Test `search_nodes` tool with includeExamples parameter
+
+**Coverage:**
+- includeExamples parameter behavior
+  - false: no examples returned
+  - undefined: no examples returned (default)
+  - true: examples returned
+- Example data structure validation
+- Top 2 limit enforcement
+- Backward compatibility
+- Performance (<100ms)
+- Error handling (malformed JSON, database errors)
+- searchNodesLIKE integration
+- searchNodesFTS integration
+
+**Test Count:** 12 tests
+**Expected Coverage:** 85%+
+
+---
+
+#### 3. `/tests/unit/mcp/get-node-essentials-examples.test.ts` ✅
+**Purpose:** Test `get_node_essentials` tool with includeExamples parameter
+
+**Coverage:**
+- includeExamples parameter behavior
+- Full metadata structure
+  - configuration object
+  - source (template, views, complexity)
+  - useCases (limited to 2)
+  - metadata (hasCredentials, hasExpressions)
+- Cache key differentiation
+- Backward compatibility
+- Performance (<100ms)
+- Error handling
+- Top 3 limit enforcement
+
+**Test Count:** 13 tests
+**Expected Coverage:** 88%+
+
+---
+
+### Integration Tests
+
+#### 4. `/tests/integration/database/template-node-configs.test.ts` ✅
+**Purpose:** Test database schema, migrations, and operations
+
+**Coverage:**
+- Schema validation
+  - Table creation
+  - All columns present
+  - Correct types and constraints
+  - CHECK constraint on complexity
+- Indexes
+  - idx_config_node_type_rank
+  - idx_config_complexity
+  - idx_config_auth
+- View: ranked_node_configs
+  - Top 5 per node_type
+  - Correct ordering
+- Foreign key constraints
+  - CASCADE delete
+  - Referential integrity
+- Data operations
+  - INSERT with all fields
+  - Nullable fields
+  - Rank updates
+  - Delete rank > 10
+- Performance
+  - 1000 records < 10ms queries
+- Migration idempotency
+
+**Test Count:** 19 tests
+**Expected Coverage:** 95%+
+
+---
+
+#### 5. `/tests/integration/mcp/template-examples-e2e.test.ts` ✅
+**Purpose:** End-to-end integration testing
+
+**Coverage:**
+- Direct SQL queries
+  - Top 2 examples for search_nodes
+  - Top 3 examples with metadata for get_node_essentials
+- Data structure validation
+  - Valid JSON in all fields
+  - Credentials when has_credentials=1
+- Ranked view functionality
+- Performance with 100+ configs
+  - Query performance < 5ms
+  - Complexity filtering
+- Edge cases
+  - Non-existent node types
+  - Long parameters_json (100 params)
+  - Special characters (Unicode, emojis, symbols)
+- Data integrity
+  - Foreign key constraints
+  - Cascade deletes
+
+**Test Count:** 14 tests
+**Expected Coverage:** 90%+
+
+---
+
+### Test Fixtures
+
+#### 6. `/tests/fixtures/template-configs.ts` ✅
+**Purpose:** Reusable test data
+
+**Provides:**
+- `sampleConfigs`: 7 realistic node configurations
+  - simpleWebhook
+  - webhookWithAuth
+  - httpRequestBasic
+  - httpRequestWithExpressions
+  - slackMessage
+  - codeNodeTransform
+  - codeNodeWithExpressions
+
+- `sampleWorkflows`: 3 complete workflows
+  - webhookToSlack
+  - apiWorkflow
+  - complexWorkflow
+
+- **Helper Functions:**
+  - `compressWorkflow()` - Compress to base64
+  - `createTemplateMetadata()` - Generate metadata
+  - `createConfigBatch()` - Batch create configs
+  - `getConfigByComplexity()` - Filter by complexity
+  - `getConfigsWithExpressions()` - Filter with expressions
+  - `getConfigsWithCredentials()` - Filter with credentials
+  - `createInsertStatement()` - SQL insert helper
+
+---
+
+## Existing Tests Requiring Updates
+
+### High Priority
+
+#### 1. `tests/unit/mcp/parameter-validation.test.ts`
+**Line 480:** Remove `get_node_for_task` from legacyValidationTools array
+
+```typescript
+// REMOVE THIS:
+{ name: 'get_node_for_task', args: {}, expected: 'Missing required parameters for get_node_for_task: task' },
+```
+
+**Status:** ⚠️ BREAKING CHANGE - Tool removed
+
+---
+
+#### 2. `tests/unit/mcp/tools.test.ts`
+**Update:** Remove `get_node_for_task` from templates category
+
+```typescript
+// BEFORE:
+templates: ['list_tasks', 'get_node_for_task', 'search_templates', ...]
+
+// AFTER:
+templates: ['list_tasks', 'search_templates', ...]
+```
+
+**Add:** Tests for new includeExamples parameter in tool definitions
+
+```typescript
+it('should have includeExamples parameter in search_nodes', () => {
+  const searchNodesTool = tools.find(t => t.name === 'search_nodes');
+  expect(searchNodesTool.inputSchema.properties.includeExamples).toBeDefined();
+  expect(searchNodesTool.inputSchema.properties.includeExamples.type).toBe('boolean');
+  expect(searchNodesTool.inputSchema.properties.includeExamples.default).toBe(false);
+});
+
+it('should have includeExamples parameter in get_node_essentials', () => {
+  const essentialsTool = tools.find(t => t.name === 'get_node_essentials');
+  expect(essentialsTool.inputSchema.properties.includeExamples).toBeDefined();
+});
+```
+
+**Status:** ⚠️ REQUIRED UPDATE
+
+---
+
+#### 3. `tests/integration/mcp-protocol/session-management.test.ts`
+**Remove:** Test case calling `get_node_for_task` with invalid task
+
+```typescript
+// REMOVE THIS TEST:
+client.callTool({ name: 'get_node_for_task', arguments: { task: 'invalid_task' } }).catch(e => e)
+```
+
+**Status:** ⚠️ BREAKING CHANGE
+
+---
+
+#### 4. `tests/integration/mcp-protocol/tool-invocation.test.ts`
+**Remove:** Entire `get_node_for_task` describe block
+
+**Add:** Tests for new includeExamples functionality
+
+```typescript
+describe('search_nodes with includeExamples', () => {
+  it('should return examples when includeExamples is true', async () => {
+    const response = await client.callTool({
+      name: 'search_nodes',
+      arguments: { query: 'webhook', includeExamples: true }
+    });
+
+    expect(response.results).toBeDefined();
+    // Examples may or may not be present depending on database
+  });
+
+  it('should not return examples when includeExamples is false', async () => {
+    const response = await client.callTool({
+      name: 'search_nodes',
+      arguments: { query: 'webhook', includeExamples: false }
+    });
+
+    expect(response.results).toBeDefined();
+    response.results.forEach(node => {
+      expect(node.examples).toBeUndefined();
+    });
+  });
+});
+
+describe('get_node_essentials with includeExamples', () => {
+  it('should return examples with metadata when includeExamples is true', async () => {
+    const response = await client.callTool({
+      name: 'get_node_essentials',
+      arguments: { nodeType: 'nodes-base.webhook', includeExamples: true }
+    });
+
+    expect(response.nodeType).toBeDefined();
+    // Examples may or may not be present depending on database
+  });
+});
+```
+
+**Status:** ⚠️ REQUIRED UPDATE
+
+---
+
+### Medium Priority
+
+#### 5. `tests/unit/services/task-templates.test.ts`
+**Status:** ✅ No changes needed (TaskTemplates marked as deprecated but not removed)
+
+**Note:** TaskTemplates remains for backward compatibility. Tests should continue to pass.
+
+---
+
+## Test Execution Plan
+
+### Phase 1: Unit Tests
+```bash
+# Run new unit tests
+npm test tests/unit/scripts/fetch-templates-extraction.test.ts
+npm test tests/unit/mcp/search-nodes-examples.test.ts
+npm test tests/unit/mcp/get-node-essentials-examples.test.ts
+
+# Expected: All pass, 52 tests
+```
+
+### Phase 2: Integration Tests
+```bash
+# Run new integration tests
+npm test tests/integration/database/template-node-configs.test.ts
+npm test tests/integration/mcp/template-examples-e2e.test.ts
+
+# Expected: All pass, 33 tests
+```
+
+### Phase 3: Update Existing Tests
+```bash
+# Update files as outlined above, then run:
+npm test tests/unit/mcp/parameter-validation.test.ts
+npm test tests/unit/mcp/tools.test.ts
+npm test tests/integration/mcp-protocol/session-management.test.ts
+npm test tests/integration/mcp-protocol/tool-invocation.test.ts
+
+# Expected: All pass after updates
+```
+
+### Phase 4: Full Test Suite
+```bash
+# Run all tests
+npm test
+
+# Run with coverage
+npm run test:coverage
+
+# Expected coverage improvements:
+# - src/scripts/fetch-templates.ts: +20% (60% → 80%)
+# - src/mcp/server.ts: +5% (75% → 80%)
+# - Overall project: +2% (current → current+2%)
+```
+
+---
+
+## Coverage Expectations
+
+### New Code Coverage
+
+| File | Function | Target | Tests |
+|------|----------|--------|-------|
+| fetch-templates.ts | extractNodeConfigs | 95% | 15 tests |
+| fetch-templates.ts | detectExpressions | 100% | 12 tests |
+| server.ts | searchNodes (with examples) | 90% | 8 tests |
+| server.ts | getNodeEssentials (with examples) | 90% | 10 tests |
+| Database migration | template_node_configs | 100% | 19 tests |
+
+### Overall Coverage Goals
+
+- **Unit Tests:** 90%+ coverage for new code
+- **Integration Tests:** All happy paths + critical error paths
+- **E2E Tests:** Complete feature workflows
+- **Performance:** All queries <10ms (database), <100ms (MCP)
+
+---
+
+## Test Infrastructure
+
+### Dependencies Required
+All dependencies already present in `package.json`:
+- vitest (test runner)
+- better-sqlite3 (database)
+- @vitest/coverage-v8 (coverage)
+
+### Test Utilities Used
+- TestDatabase helper (from existing test utils)
+- createTestDatabaseAdapter (from existing test utils)
+- Standard vitest matchers
+
+### No New Dependencies Required ✅
+
+---
+
+## Regression Prevention
+
+### Critical Paths Protected
+
+1. **Backward Compatibility**
+   - Tools work without includeExamples parameter
+   - Existing workflows unchanged
+   - Cache keys differentiated
+
+2. **Performance**
+   - No degradation when includeExamples=false
+   - Indexed queries <10ms
+   - Example fetch errors don't break responses
+
+3. **Data Integrity**
+   - Foreign key constraints enforced
+   - JSON validation in all fields
+   - Rank calculations correct
+
+---
+
+## CI/CD Integration
+
+### GitHub Actions Updates
+No changes required. Existing test commands will run new tests:
+
+```yaml
+- run: npm test
+- run: npm run test:coverage
+```
+
+### Coverage Thresholds
+Current thresholds maintained. Expected improvements:
+- Lines: +2%
+- Functions: +3%
+- Branches: +2%
+
+---
+
+## Manual Testing Checklist
+
+### Pre-Deployment Verification
+
+- [ ] Run `npm run rebuild` - Verify migration applies cleanly
+- [ ] Run `npm run fetch:templates --extract-only` - Verify extraction works
+- [ ] Check database: `SELECT COUNT(*) FROM template_node_configs` - Should be ~197
+- [ ] Test MCP tool: `search_nodes({query: "webhook", includeExamples: true})`
+- [ ] Test MCP tool: `get_node_essentials({nodeType: "nodes-base.webhook", includeExamples: true})`
+- [ ] Verify backward compatibility: Tools work without includeExamples parameter
+- [ ] Performance test: Query 100 nodes with examples < 200ms
+
+---
+
+## Rollback Plan
+
+If issues are detected:
+
+1. **Database Rollback:**
+   ```sql
+   DROP TABLE IF EXISTS template_node_configs;
+   DROP VIEW IF EXISTS ranked_node_configs;
+   ```
+
+2. **Code Rollback:**
+   - Revert server.ts changes
+   - Revert tools.ts changes
+   - Restore get_node_for_task tool (if critical)
+
+3. **Test Rollback:**
+   - Revert parameter-validation.test.ts
+   - Revert tools.test.ts
+   - Revert tool-invocation.test.ts
+
+---
+
+## Success Metrics
+
+### Test Metrics
+- ✅ 85+ new tests added
+- ✅ 0 tests failing after updates
+- ✅ Coverage increase 2%+
+- ✅ All performance tests pass
+
+### Feature Metrics
+- ✅ 197 template configs extracted
+- ✅ Top 2/3 examples returned correctly
+- ✅ Query performance <10ms
+- ✅ No backward compatibility breaks
+
+---
+
+## Conclusion
+
+This test plan provides **comprehensive coverage** for the P0-R3 feature with:
+- **85+ new tests** across unit, integration, and E2E levels
+- **Complete coverage** of extraction, storage, and retrieval
+- **Backward compatibility** protection
+- **Performance validation** (<10ms queries)
+- **Clear migration path** for existing tests
+
+**All test files are ready for execution.** Update the 4 existing test files as outlined, then run the full test suite.
+
+**Estimated Total Implementation Time:** 2-3 hours for updating existing tests + validation

PRIVACY.md

@@ -0,0 +1,69 @@
+# Privacy Policy for n8n-mcp Telemetry
+
+## Overview
+n8n-mcp collects anonymous usage statistics to help improve the tool. This data collection is designed to respect user privacy while providing valuable insights into how the tool is used.
+
+## What We Collect
+- **Anonymous User ID**: A hashed identifier derived from your machine characteristics (no personal information)
+- **Tool Usage**: Which MCP tools are used and their performance metrics
+- **Workflow Patterns**: Sanitized workflow structures (all sensitive data removed)
+- **Error Types**: Categories of errors encountered (no error messages with user data)
+- **System Information**: Platform, architecture, Node.js version, and n8n-mcp version
+
+## What We DON'T Collect
+- Personal information or usernames
+- API keys, tokens, or credentials
+- URLs, endpoints, or hostnames
+- Email addresses or contact information
+- File paths or directory structures
+- Actual workflow data or parameters
+- Database connection strings
+- Any authentication information
+
+## Data Sanitization
+All collected data undergoes automatic sanitization:
+- URLs are replaced with `[URL]` or `[REDACTED]`
+- Long alphanumeric strings (potential keys) are replaced with `[KEY]`
+- Email addresses are replaced with `[EMAIL]`
+- Authentication-related fields are completely removed
+
+## Data Storage
+- Data is stored securely using Supabase
+- Anonymous users have write-only access (cannot read data back)
+- Row Level Security (RLS) policies prevent data access by anonymous users
+
+## Opt-Out
+You can disable telemetry at any time:
+```bash
+npx n8n-mcp telemetry disable
+```
+
+To re-enable:
+```bash
+npx n8n-mcp telemetry enable
+```
+
+To check status:
+```bash
+npx n8n-mcp telemetry status
+```
+
+## Data Usage
+Collected data is used solely to:
+- Understand which features are most used
+- Identify common error patterns
+- Improve tool performance and reliability
+- Guide development priorities
+
+## Data Retention
+- Data is retained for analysis purposes
+- No personal identification is possible from the collected data
+
+## Changes to This Policy
+We may update this privacy policy from time to time. Updates will be reflected in this document.
+
+## Contact
+For questions about telemetry or privacy, please open an issue on GitHub:
+https://github.com/czlonkowski/n8n-mcp/issues
+
+Last updated: 2025-09-25

README.md

@@ -2,11 +2,10 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![GitHub stars](https://img.shields.io/github/stars/czlonkowski/n8n-mcp?style=social)](https://github.com/czlonkowski/n8n-mcp)
-[![Version](https://img.shields.io/badge/version-2.11.1-blue.svg)](https://github.com/czlonkowski/n8n-mcp)
 [![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-1728%20passing-brightgreen.svg)](https://github.com/czlonkowski/n8n-mcp/actions)
-[![n8n version](https://img.shields.io/badge/n8n-^1.110.1-orange.svg)](https://github.com/n8n-io/n8n)
+[![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.113.3-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)
 
@@ -16,11 +15,13 @@ A Model Context Protocol (MCP) server that provides AI assistants with comprehen
 
 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:
 
-- 📚 **535 n8n nodes** from both n8n-nodes-base and @n8n/n8n-nodes-langchain
+- 📚 **536 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** - 90% coverage from official n8n docs (including AI nodes)
 - 🤖 **AI tools** - 263 AI-capable nodes detected with full documentation
+- 💡 **Real-world examples** - 2,646 pre-extracted configurations from popular templates
+- 🎯 **Template library** - 2,500+ workflow templates with smart filtering
 
 
 ## ⚠️ Important Safety Warning
@@ -197,10 +198,36 @@ 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.
+>💡 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.
 
 > **Note**: The n8n API credentials are optional. Without them, you'll have access to all documentation and validation tools. With them, you'll additionally get workflow management capabilities (create, update, execute workflows).
 
+### 🏠 Local n8n Instance Configuration
+
+If you're running n8n locally (e.g., `http://localhost:5678` or Docker), you need to allow localhost webhooks:
+
+```json
+{
+  "mcpServers": {
+    "n8n-mcp": {
+      "command": "docker",
+      "args": [
+        "run", "-i", "--rm", "--init",
+        "-e", "MCP_MODE=stdio",
+        "-e", "LOG_LEVEL=error",
+        "-e", "DISABLE_CONSOLE_OUTPUT=true",
+        "-e", "N8N_API_URL=http://host.docker.internal:5678",
+        "-e", "N8N_API_KEY=your-api-key",
+        "-e", "WEBHOOK_SECURITY_MODE=moderate",
+        "ghcr.io/czlonkowski/n8n-mcp:latest"
+      ]
+    }
+  }
+}
+```
+
+> ⚠️ **Important:** Set `WEBHOOK_SECURITY_MODE=moderate` to allow webhooks to your local n8n instance. This is safe for local development while still blocking private networks and cloud metadata.
+
 **Important:** The `-i` flag is required for MCP stdio communication.
 
 > 🔧 If you encounter any issues with Docker, check our [Docker Troubleshooting Guide](./docs/DOCKER_TROUBLESHOOTING.md).
@@ -212,6 +239,51 @@ Add to Claude Desktop config:
 
 **Restart Claude Desktop after updating configuration** - That's it! 🎉
 
+## 🔐 Privacy & Telemetry
+
+n8n-mcp collects anonymous usage statistics to improve the tool. [View our privacy policy](./PRIVACY.md).
+
+### Opting Out
+
+**For npx users:**
+```bash
+npx n8n-mcp telemetry disable
+```
+
+**For Docker users:**
+Add the following environment variable to your Docker configuration:
+```json
+"-e", "N8N_MCP_TELEMETRY_DISABLED=true"
+```
+
+Example in Claude Desktop config:
+```json
+{
+  "mcpServers": {
+    "n8n-mcp": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "--init",
+        "-e", "MCP_MODE=stdio",
+        "-e", "LOG_LEVEL=error",
+        "-e", "N8N_MCP_TELEMETRY_DISABLED=true",
+        "ghcr.io/czlonkowski/n8n-mcp:latest"
+      ]
+    }
+  }
+}
+```
+
+**For docker-compose users:**
+Set in your environment file or docker-compose.yml:
+```yaml
+environment:
+  N8N_MCP_TELEMETRY_DISABLED: "true"
+```
+
 ## 💖 Support This Project
 
 <div align="center">
@@ -346,183 +418,267 @@ Step-by-step tutorial for connecting n8n-MCP to Cursor IDE with custom rules.
 ### [Windsurf](./docs/WINDSURF_SETUP.md)
 Complete guide for integrating n8n-MCP with Windsurf using project rules.
 
+### [Codex](./docs/CODEX_SETUP.md)
+Complete guide for integrating n8n-MCP with Codex.
+
 ## 🤖 Claude Project Setup
 
 For the best results when using n8n-MCP with Claude Projects, use these enhanced system instructions:
 
-```markdown
+````markdown
 You are an expert in n8n automation software using n8n-MCP tools. Your role is to design, build, and validate n8n workflows with maximum accuracy and efficiency.
 
-## Core Workflow Process
+## Core Principles
 
-1. **ALWAYS start new conversation with**: `tools_documentation()` to understand best practices and available tools.
+### 1. Silent Execution
+CRITICAL: Execute tools without commentary. Only respond AFTER all tools complete.
 
-2. **Template Discovery Phase** 
-   - `search_templates_by_metadata({complexity: "simple"})` - Find skill-appropriate templates
-   - `get_templates_for_task('webhook_processing')` - Get curated templates by task
-   - `search_templates('slack notification')` - Text search for specific needs
-   - `list_node_templates(['n8n-nodes-base.slack'])` - Find templates using specific nodes
-   
-   **Template filtering strategies**:
-   - **For beginners**: `complexity: "simple"` and `maxSetupMinutes: 30`
-   - **By role**: `targetAudience: "marketers"` or `"developers"` or `"analysts"`
-   - **By time**: `maxSetupMinutes: 15` for quick wins
-   - **By service**: `requiredService: "openai"` to find compatible templates
+❌ 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]
 
-3. **Discovery Phase** - Find the right nodes (if no suitable template):
-   - Think deeply about user request and the logic you are going to build to fulfill it. Ask follow-up questions to clarify the user's intent, if something is unclear. Then, proceed with the rest of your instructions.
-   - `search_nodes({query: 'keyword'})` - Search by functionality
+### 2. Parallel Execution
+When operations are independent, execute them in parallel for maximum performance.
+
+✅ GOOD: Call search_nodes, list_nodes, and search_templates simultaneously
+❌ BAD: Sequential tool calls (await each one before the next)
+
+### 3. Templates First
+ALWAYS check templates before building from scratch (2,500+ available).
+
+### 4. Multi-Level Validation
+Use validate_node_minimal → validate_node_operation → validate_workflow pattern.
+
+### 5. Never Trust Defaults
+⚠️ CRITICAL: Default parameter values are the #1 source of runtime failures.
+ALWAYS explicitly configure ALL parameters that control node behavior.
+
+## Workflow Process
+
+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
+
+   **Filtering strategies**:
+   - Beginners: `complexity: "simple"` + `maxSetupMinutes: 30`
+   - By role: `targetAudience: "marketers"` | `"developers"` | `"analysts"`
+   - By time: `maxSetupMinutes: 15` for quick wins
+   - By service: `requiredService: "openai"` for compatibility
+
+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()` - See AI-capable nodes (remember: ANY node can be an AI tool!)
+   - `list_ai_tools()` - AI-capable nodes
 
-4. **Configuration Phase** - Get node details efficiently:
-   - `get_node_essentials(nodeType)` - Start here! Only 10-20 essential properties
+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_for_task('send_email')` - Get pre-configured templates
-   - `get_node_documentation(nodeType)` - Human-readable docs when needed
-   - It is good common practice to show a visual representation of the workflow architecture to the user and asking for opinion, before moving forward. 
+   - `get_node_documentation(nodeType)` - Human-readable docs
+   - Show workflow architecture to user for approval before proceeding
 
-5. **Pre-Validation Phase** - Validate BEFORE building:
+5. **Validation Phase** (parallel for multiple nodes)
    - `validate_node_minimal(nodeType, config)` - Quick required fields check
-   - `validate_node_operation(nodeType, config, profile)` - Full operation-aware validation
-   - Fix any validation errors before proceeding
+   - `validate_node_operation(nodeType, config, 'runtime')` - Full validation with fixes
+   - Fix ALL errors before proceeding
 
-6. **Building Phase** - Create or customize the workflow:
+6. **Building Phase**
    - If using template: `get_template(templateId, {mode: "full"})`
-   - **MANDATORY ATTRIBUTION**: When using a template, ALWAYS inform the user:
-     - "This workflow is based on a template by **[author.name]** (@[author.username])"
-     - "View the original template at: [url]"
-     - Example: "This workflow is based on a template by **David Ashby** (@cfomodz). View the original at: https://n8n.io/workflows/2414"
-   - Customize template or build from validated configurations
+   - **MANDATORY ATTRIBUTION**: "Based on template by **[author.name]** (@[username]). View at: [url]"
+   - Build from validated configurations
+   - ⚠️ EXPLICITLY set ALL parameters - never rely on defaults
    - Connect nodes with proper structure
-   - Add error handling where appropriate
-   - Use expressions like $json, $node["NodeName"].json
-   - Build the workflow in an artifact for easy editing downstream (unless the user asked to create in n8n instance)
+   - Add error handling
+   - Use n8n expressions: $json, $node["NodeName"].json
+   - Build in artifact (unless deploying to n8n instance)
 
-7. **Workflow Validation Phase** - Validate complete workflow:
-   - `validate_workflow(workflow)` - Complete validation including connections
-   - `validate_workflow_connections(workflow)` - Check structure and AI tool connections
-   - `validate_workflow_expressions(workflow)` - Validate all n8n expressions
-   - Fix any issues found before deployment
+7. **Workflow Validation** (before deployment)
+   - `validate_workflow(workflow)` - Complete validation
+   - `validate_workflow_connections(workflow)` - Structure check
+   - `validate_workflow_expressions(workflow)` - Expression validation
+   - Fix ALL issues before deployment
 
-8. **Deployment Phase** (if n8n API configured):
-   - `n8n_create_workflow(workflow)` - Deploy validated workflow
-   - `n8n_validate_workflow({id: 'workflow-id'})` - Post-deployment validation
-   - `n8n_update_partial_workflow()` - Make incremental updates using diffs
-   - `n8n_trigger_webhook_workflow()` - Test webhook workflows
+8. **Deployment** (if n8n API configured)
+   - `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
 
-## Key Insights
+## Critical Warnings
 
-- **TEMPLATES FIRST** - Always check for existing templates before building from scratch (2,500+ available!)
-- **ATTRIBUTION REQUIRED** - Always credit template authors with name, username, and link to n8n.io
-- **SMART FILTERING** - Use metadata filters to find templates matching user skill level and time constraints
-- **USE CODE NODE ONLY WHEN IT IS NECESSARY** - always prefer to use standard nodes over code node. Use code node only when you are sure you need it.
-- **VALIDATE EARLY AND OFTEN** - Catch errors before they reach deployment
-- **USE DIFF UPDATES** - Use n8n_update_partial_workflow for 80-90% token savings
-- **ANY node can be an AI tool** - not just those with usableAsTool=true
-- **Pre-validate configurations** - Use validate_node_minimal before building
-- **Post-validate workflows** - Always validate complete workflows before deployment
-- **Incremental updates** - Use diff operations for existing workflows
-- **Test thoroughly** - Validate both locally and after deployment to n8n
+### ⚠️ Never Trust Defaults
+Default values cause runtime failures. Example:
+```json
+// ❌ FAILS at runtime
+{resource: "message", operation: "post", text: "Hello"}
+
+// ✅ WORKS - all parameters explicit
+{resource: "message", operation: "post", select: "channel", channelId: "C123", text: "Hello"}
+```
+
+### ⚠️ 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`
 
 ## Validation Strategy
 
-### Before Building:
-1. validate_node_minimal() - Check required fields
-2. validate_node_operation() - Full configuration validation
-3. Fix all errors before proceeding
+### Level 1 - Quick Check (before building)
+`validate_node_minimal(nodeType, config)` - Required fields only (<100ms)
 
-### After Building:
-1. validate_workflow() - Complete workflow validation
-2. validate_workflow_connections() - Structure validation
-3. validate_workflow_expressions() - Expression syntax check
+### Level 2 - Comprehensive (before building)
+`validate_node_operation(nodeType, config, 'runtime')` - Full validation with fixes
 
-### After Deployment:
-1. n8n_validate_workflow({id}) - Validate deployed workflow
-2. n8n_list_executions() - Monitor execution status
-3. n8n_update_partial_workflow() - Fix issues using diffs
+### Level 3 - Complete (after building)
+`validate_workflow(workflow)` - Connections, expressions, AI tools
 
-## Response Structure
+### 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
 
-1. **Discovery**: Show available nodes and options
-2. **Pre-Validation**: Validate node configurations first
-3. **Configuration**: Show only validated, working configs
-4. **Building**: Construct workflow with validated components
-5. **Workflow Validation**: Full workflow validation results
-6. **Deployment**: Deploy only after all validations pass
-7. **Post-Validation**: Verify deployment succeeded
+## Response Format
+
+### Initial Creation
+```
+[Silent tool execution in parallel]
+
+Created workflow:
+- Webhook trigger → Slack notification
+- Configured: POST /webhook → #general channel
+
+Validation: ✅ All checks passed
+```
+
+### Modifications
+```
+[Silent tool execution]
+
+Updated workflow:
+- Added error handling to HTTP node
+- Fixed required Slack parameters
+
+Changes validated successfully.
+```
+
+## Batch Operations
+
+Use `n8n_update_partial_workflow` with multiple operations in a single call:
+
+✅ GOOD - Batch multiple operations:
+```json
+n8n_update_partial_workflow({
+  id: "wf-123",
+  operations: [
+    {type: "updateNode", nodeId: "slack-1", changes: {...}},
+    {type: "updateNode", nodeId: "http-1", changes: {...}},
+    {type: "cleanStaleConnections"}
+  ]
+})
+```
+
+❌ BAD - Separate calls:
+```json
+n8n_update_partial_workflow({id: "wf-123", operations: [{...}]})
+n8n_update_partial_workflow({id: "wf-123", operations: [{...}]})
+```
 
 ## Example Workflow
 
-### Smart Template-First Approach
+### Template-First Approach
 
-#### 1. Find existing templates
-// Find simple Slack templates for marketers
-const templates = search_templates_by_metadata({
+```
+// STEP 1: Template Discovery (parallel execution)
+[Silent execution]
+search_templates_by_metadata({
   requiredService: 'slack',
   complexity: 'simple',
-  targetAudience: 'marketers',
-  maxSetupMinutes: 30
+  targetAudience: 'marketers'
 })
-
-// Or search by text
-search_templates('slack notification')
-
-// Or get curated templates
 get_templates_for_task('slack_integration')
 
-#### 2. Use and customize template
-const workflow = get_template(templates.items[0].id, {mode: 'full'})
+// STEP 2: Use template
+get_template(templateId, {mode: 'full'})
 validate_workflow(workflow)
 
-### Building from Scratch (if no suitable template)
+// Response after all tools complete:
+"Found template by **David Ashby** (@cfomodz).
+View at: https://n8n.io/workflows/2414
 
-#### 1. Discovery & Configuration
-search_nodes({query: 'slack'})
-get_node_essentials('n8n-nodes-base.slack')
+Validation: ✅ All checks passed"
+```
 
-#### 2. Pre-Validation
-validate_node_minimal('n8n-nodes-base.slack', {resource:'message', operation:'send'})
+### Building from Scratch (if no template)
+
+```
+// STEP 1: Discovery (parallel execution)
+[Silent execution]
+search_nodes({query: 'slack', includeExamples: true})
+list_nodes({category: 'communication'})
+
+// 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})
+
+// STEP 3: Validation (parallel execution)
+[Silent execution]
+validate_node_minimal('n8n-nodes-base.slack', config)
 validate_node_operation('n8n-nodes-base.slack', fullConfig, 'runtime')
 
-#### 3. Build Workflow
-// Create workflow JSON with validated configs
+// STEP 4: Build
+// Construct workflow with validated configs
+// ⚠️ Set ALL parameters explicitly
 
-#### 4. Workflow Validation
+// STEP 5: Validate
+[Silent execution]
 validate_workflow(workflowJson)
-validate_workflow_connections(workflowJson)
-validate_workflow_expressions(workflowJson)
 
-#### 5. Deploy (if configured)
-n8n_create_workflow(validatedWorkflow)
-n8n_validate_workflow({id: createdWorkflowId})
+// Response after all tools complete:
+"Created workflow: Webhook → Slack
+Validation: ✅ Passed"
+```
 
-#### 6. Update Using Diffs
+### Batch Updates
+
+```json
+// ONE call with multiple operations
 n8n_update_partial_workflow({
-  workflowId: id,
+  id: "wf-123",
   operations: [
-    {type: 'updateNode', nodeId: 'slack1', changes: {position: [100, 200]}}
+    {type: "updateNode", nodeId: "slack-1", changes: {position: [100, 200]}},
+    {type: "updateNode", nodeId: "http-1", changes: {position: [300, 200]}},
+    {type: "cleanStaleConnections"}
   ]
 })
+```
 
 ## Important Rules
 
-- ALWAYS check for existing templates before building from scratch
-- LEVERAGE metadata filters to find skill-appropriate templates
-- **ALWAYS ATTRIBUTE TEMPLATES**: When using any template, you MUST share the author's name, username, and link to the original template on n8n.io
-- VALIDATE templates before deployment (they may need updates)
-- USE diff operations for updates (80-90% token savings)
-- STATE validation results clearly
-- FIX all errors before proceeding
+### Core Behavior
+1. **Silent execution** - No commentary between tools
+2. **Parallel by default** - Execute independent operations simultaneously
+3. **Templates first** - Always check before building (2,500+ available)
+4. **Multi-level validation** - Quick check → Full validation → Workflow validation
+5. **Never trust defaults** - Explicitly configure ALL parameters
 
-## Template Discovery Tips
+### Attribution & Credits
+- **MANDATORY TEMPLATE ATTRIBUTION**: Share author name, username, and n8n.io link
+- **Template validation** - Always validate before deployment (may need updates)
 
-- **97.5% of templates have metadata** - Use smart filtering!
-- **Filter combinations work best** - Combine complexity + setup time + service
-- **Templates save 70-90% development time** - Always check first
-- **Metadata is AI-generated** - Occasionally imprecise but highly useful
-- **Use `includeMetadata: false` for fast browsing** - Add metadata only when needed
-```
+### Performance
+- **Batch operations** - Use diff operations with multiple changes in one call
+- **Parallel execution** - Search, validate, and configure simultaneously
+- **Template metadata** - Use smart filtering for faster discovery
+
+### Code Node Usage
+- **Avoid when possible** - Prefer standard nodes
+- **Only when necessary** - Use code node as last resort
+- **AI tool capability** - ANY node can be an AI tool (not just marked ones)
+````
 
 Save these instructions in your Claude Project for optimal n8n workflow assistance with intelligent template discovery.
 
@@ -540,11 +696,11 @@ This tool was created to benefit everyone in the n8n community without friction.
 ## Features
 
 - **🔍 Smart Node Search**: Find nodes by name, category, or functionality
-- **📖 Essential Properties**: Get only the 10-20 properties that matter (NEW in v2.4.0)
-- **🎯 Task Templates**: Pre-configured settings for common automation tasks
+- **📖 Essential Properties**: Get only the 10-20 properties that matter
+- **💡 Real-World Examples**: 2,646 pre-extracted configurations from popular templates
 - **✅ Config Validation**: Validate node configurations before deployment
 - **🔗 Dependency Analysis**: Understand property relationships and conditions
-- **💡 Working Examples**: Real-world examples for immediate use
+- **🎯 Template Discovery**: 2,500+ workflow templates with smart filtering
 - **⚡ Fast Response**: Average query time ~12ms with optimized SQLite
 - **🌐 Universal Compatibility**: Works with any Node.js version
 
@@ -570,8 +726,8 @@ Once connected, Claude can use these powerful 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 with examples (10-20 properties instead of 200+)
-- **`search_nodes`** - Full-text search across all node documentation
+- **`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
@@ -585,8 +741,6 @@ Once connected, Claude can use these powerful tools:
 - **`get_templates_for_task`** - Curated templates for common automation tasks
 
 ### Advanced Tools
-- **`get_node_for_task`** - Pre-configured node settings for common tasks
-- **`list_tasks`** - Discover available task templates
 - **`validate_node_operation`** - Validate node configurations (operation-aware, profiles support)
 - **`validate_node_minimal`** - Quick validation for just required fields
 - **`validate_workflow`** - Complete workflow validation including AI tool connections
@@ -610,6 +764,7 @@ These powerful tools allow you to manage n8n workflows directly from Claude. The
 - **`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!)
 
 #### Execution Management
 - **`n8n_trigger_webhook_workflow`** - Trigger workflows via webhook URL
@@ -625,14 +780,17 @@ These powerful tools allow you to manage n8n workflows directly from Claude. The
 ### Example Usage
 
 ```typescript
-// Get essentials for quick configuration
-get_node_essentials("nodes-base.httpRequest")
+// Get essentials with real-world examples from templates
+get_node_essentials({
+  nodeType: "nodes-base.httpRequest",
+  includeExamples: true  // Returns top 3 configs from popular templates
+})
 
-// Find nodes for a specific task
-search_nodes({ query: "send email gmail" })
-
-// Get pre-configured settings
-get_node_for_task("send_email")
+// Search nodes with configuration examples
+search_nodes({
+  query: "send email gmail",
+  includeExamples: true  // Returns top 2 configs per node
+})
 
 // Validate before deployment
 validate_node_operation({
@@ -723,12 +881,14 @@ npm run dev:http       # HTTP dev mode
 
 ## 📊 Metrics & Coverage
 
-Current database coverage (n8n v1.106.3):
+Current database coverage (n8n v1.113.3):
 
-- ✅ **535/535** nodes loaded (100%)
+- ✅ **536/536** nodes loaded (100%)
 - ✅ **528** nodes with properties (98.7%)
 - ✅ **470** nodes with documentation (88%)
 - ✅ **267** AI-capable tools detected
+- ✅ **2,646** pre-extracted template configurations
+- ✅ **2,500+** workflow templates available
 - ✅ **AI Agent & LangChain nodes** fully documented
 - ⚡ **Average response time**: ~12ms
 - 💾 **Database size**: ~15MB (optimized)
@@ -768,7 +928,7 @@ docker run --rm ghcr.io/czlonkowski/n8n-mcp:latest --version
 
 ## 🧪 Testing
 
-The project includes a comprehensive test suite with **1,356 tests** ensuring code quality and reliability:
+The project includes a comprehensive test suite with **2,883 tests** ensuring code quality and reliability:
 
 ```bash
 # Run all tests
@@ -788,9 +948,9 @@ npm run test:bench          # Performance benchmarks
 
 ### Test Suite Overview
 
-- **Total Tests**: 1,356 (100% passing)
-  - **Unit Tests**: 1,107 tests across 44 files
-  - **Integration Tests**: 249 tests across 14 files
+- **Total Tests**: 2,883 (100% passing)
+  - **Unit Tests**: 2,526 tests across 99 files
+  - **Integration Tests**: 357 tests across 20 files
 - **Execution Time**: ~2.5 minutes in CI
 - **Test Framework**: Vitest (for speed and TypeScript support)
 - **Mocking**: MSW for API mocking, custom mocks for databases
@@ -804,22 +964,24 @@ npm run test:bench          # Performance benchmarks
 
 ### Testing Architecture
 
-- **Unit Tests**: Isolated component testing with mocks
-  - Services layer: ~450 tests
-  - Parsers: ~200 tests
-  - Database repositories: ~100 tests
-  - MCP tools: ~180 tests
+**Total: 3,336 tests** across unit and integration test suites
 
-- **Integration Tests**: Full system behavior validation
-  - MCP Protocol compliance: 72 tests
-  - Database operations: 89 tests
-  - Error handling: 44 tests
-  - Performance: 44 tests
+- **Unit Tests** (2,766 tests): Isolated component testing with mocks
+  - Services layer: Enhanced validation, property filtering, workflow validation
+  - Parsers: Node parsing, property extraction, documentation mapping
+  - Database: Repositories, adapters, migrations, FTS5 search
+  - MCP tools: Tool definitions, documentation system
+  - HTTP server: Multi-tenant support, security, configuration
 
-- **Benchmarks**: Performance testing for critical paths
-  - Database queries
-  - Node loading
-  - Search operations
+- **Integration Tests** (570 tests): Full system behavior validation
+  - **n8n API Integration** (172 tests): All 18 MCP handler tools tested against real n8n instance
+    - Workflow management: Create, read, update, delete, list, validate, autofix
+    - Execution management: Trigger, retrieve, list, delete
+    - System tools: Health check, tool listing, diagnostics
+  - **MCP Protocol** (119 tests): Protocol compliance, session management, error handling
+  - **Database** (226 tests): Repository operations, transactions, performance, FTS5 search
+  - **Templates** (35 tests): Template fetching, storage, metadata operations
+  - **Docker** (18 tests): Configuration, entrypoint, security validation
 
 For detailed testing documentation, see [Testing Architecture](./docs/testing-architecture.md).
 

docker-compose.yml

@@ -23,7 +23,11 @@ services:
       # Database
       NODE_DB_PATH: ${NODE_DB_PATH:-/app/data/nodes.db}
       REBUILD_ON_START: ${REBUILD_ON_START:-false}
-      
+
+      # Telemetry: Anonymous usage statistics are ENABLED by default
+      # To opt-out, uncomment and set to 'true':
+      # N8N_MCP_TELEMETRY_DISABLED: ${N8N_MCP_TELEMETRY_DISABLED:-true}
+
       # Optional: n8n API configuration (enables 16 additional management tools)
       # Uncomment and configure to enable n8n workflow management
       # N8N_API_URL: ${N8N_API_URL}

docs/CHANGELOG.md

@@ -5,7 +5,305 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [Unreleased] - Phase 0: Connection Operations Critical Fixes
+
+### Fixed
+- **🐛 CRITICAL: Fixed `addConnection` sourceIndex handling (Issue #272, discovered in hands-on testing)**
+  - Multi-output nodes (IF, Switch) now work correctly with sourceIndex parameter
+  - Changed from `||` to `??` operator to properly handle explicit 0 values
+  - Added defensive array validation before accessing indices
+  - Improves rating from 3/10 to 8/10 for multi-output node scenarios
+  - **Impact**: IF nodes, Switch nodes, and all conditional routing now reliable
+
+- **🐛 CRITICAL: Added runtime validation for `updateConnection` (Issue #272, #204)**
+  - Prevents server crashes when `updates` object is missing
+  - Provides helpful error message with:
+    - Clear explanation of what's wrong
+    - Correct format example
+    - Suggestion to use removeConnection + addConnection for rewiring
+  - Validates `updates` is an object, not string or other type
+  - **Impact**: No more cryptic "Cannot read properties of undefined" crashes
+
+### Enhanced
+- **Error Messages**: `updateConnection` errors now include actionable guidance
+  - Example format shown in error
+  - Alternative approaches suggested (removeConnection + addConnection)
+  - Clear explanation that updateConnection modifies properties, not targets
+
+### Testing
+- Added 8 comprehensive tests for Phase 0 fixes
+  - 2 tests for updateConnection validation (missing updates, invalid type)
+  - 5 tests for sourceIndex handling (IF nodes, parallel execution, Switch nodes, explicit 0)
+  - 1 test for complex multi-output routing scenarios
+  - All 126 existing tests still passing
+
+### Documentation
+- Updated tool documentation to clarify:
+  - `addConnection` now properly handles sourceIndex (Phase 0 fix noted)
+  - `updateConnection` REQUIRES 'updates' object (Phase 0 validation noted)
+  - Added pitfalls about updateConnection limitations
+  - Clarified that updateConnection modifies properties, NOT connection targets
+
+### Developer Experience
+- More defensive programming throughout connection operations
+- Better use of nullish coalescing (??) vs. logical OR (||)
+- Clear inline comments explaining expected behavior
+- Improved type safety with runtime guards
+
+### References
+- Comprehensive analysis: `docs/local/connection-operations-deep-dive-and-improvement-plan.md`
+- Based on hands-on testing with n8n-mcp-tester agent
+- Overall experience rating improved from 4.5/10 to estimated 6/10
+
+## [2.14.4] - 2025-09-30
+
+### Added
+- **Workflow Cleanup Operations**: Two new operations for `n8n_update_partial_workflow` to handle broken workflow recovery
+  - `cleanStaleConnections`: Automatically removes all connections referencing non-existent nodes
+    - Essential after node renames or deletions that leave dangling connection references
+    - Supports `dryRun: true` mode to preview what would be removed
+    - Removes both source and target stale connections
+  - `replaceConnections`: Replace entire connections object in a single operation
+    - Faster than crafting many individual connection operations
+    - Useful for bulk connection rewiring
+
+- **Graceful Error Handling for Connection Operations**: Enhanced `removeConnection` operation
+  - New `ignoreErrors` flag: When `true`, operation succeeds even if connection doesn't exist
+  - Perfect for cleanup scenarios where you're not sure if connections exist
+  - Maintains backwards compatibility (defaults to `false` for strict validation)
+
+- **Best-Effort Mode**: New `continueOnError` mode for `WorkflowDiffRequest`
+  - Apply valid operations even if some fail
+  - Returns detailed results with `applied` and `failed` operation indices
+  - Breaks atomic guarantees intentionally for bulk cleanup scenarios
+  - Maintains atomic mode as default for safety
+
+### Enhanced
+- **Tool Documentation**: Updated `n8n_update_partial_workflow` documentation
+  - Added examples for cleanup scenarios
+  - Documented new operation types and modes
+  - Added best practices for workflow recovery
+  - Clarified atomic vs. best-effort behavior
+
+- **Type System**: Extended workflow diff types
+  - Added `CleanStaleConnectionsOperation` interface
+  - Added `ReplaceConnectionsOperation` interface
+  - Extended `WorkflowDiffResult` with `applied`, `failed`, and `staleConnectionsRemoved` fields
+  - Updated type guards for new connection operations
+
+### Testing
+- Added comprehensive test suite for v2.14.4 features
+  - 15 new tests covering all new operations and modes
+  - Tests for cleanStaleConnections with various stale scenarios
+  - Tests for replaceConnections validation
+  - Tests for ignoreErrors flag behavior
+  - Tests for continueOnError mode with mixed success/failure
+  - Backwards compatibility verification tests
+
+### Impact
+- **Time Saved**: Reduces broken workflow fix time from 10-15 minutes to 30 seconds
+- **Token Efficiency**: `cleanStaleConnections` is 1 operation vs 10+ manual operations
+- **User Experience**: Dramatically improved workflow recovery capabilities
+- **Backwards Compatibility**: 100% - all additions are optional and default to existing behavior
+
+## [2.13.2] - 2025-01-24
+
+### Added
+- **Operation and Resource Validation with Intelligent Suggestions**: New similarity services for n8n node configuration validation
+  - `OperationSimilarityService`: Validates operations and suggests similar alternatives using Levenshtein distance and pattern matching
+  - `ResourceSimilarityService`: Validates resources with automatic plural/singular conversion and typo detection
+  - Provides "Did you mean...?" suggestions when invalid operations or resources are used
+  - Example: `operation: "listFiles"` suggests `"search"` for Google Drive nodes
+  - Example: `resource: "files"` suggests singular `"file"` with 95% confidence
+  - Confidence-based suggestions (minimum 30% threshold) with contextual fix messages
+  - Resource-aware operation filtering ensures suggestions are contextually appropriate
+  - 5-minute cache duration for performance optimization
+  - Integrated into `EnhancedConfigValidator` for seamless validation flow
+
+- **Custom Error Handling**: New `ValidationServiceError` class for better error management
+  - Proper error chaining with cause tracking
+  - Specialized factory methods for common error scenarios
+  - Type-safe error propagation throughout the validation pipeline
+
+### Enhanced
+- **Code Quality and Security Improvements** (based on code review feedback):
+  - Safe JSON parsing with try-catch error boundaries
+  - Type guards for safe property access (`getOperationValue`, `getResourceValue`)
+  - Memory leak prevention with periodic cache cleanup
+  - Performance optimization with early termination for exact matches
+  - Replaced magic numbers with named constants for better maintainability
+  - Comprehensive JSDoc documentation for all public methods
+  - Improved confidence calculation for typos and transpositions
+
+### Fixed
+- **Test Compatibility**: Updated test expectations to correctly handle exact match scenarios
+- **Cache Management**: Fixed cache cleanup to prevent unbounded memory growth
+- **Validation Deduplication**: Enhanced config validator now properly replaces base validator errors with detailed suggestions
+
+### Testing
+- Added comprehensive test coverage for similarity services (37 new tests)
+- All unit tests passing with proper edge case handling
+- Integration confirmed via n8n-mcp-tester agent validation
+
+## [2.13.1] - 2025-01-24
+
+### Changed
+- **Removed 5-operation limit from n8n_update_partial_workflow**: The workflow diff engine now supports unlimited operations per request
+  - Previously limited to 5 operations for "transactional integrity"
+  - Analysis revealed the limit was unnecessary - the clone-validate-apply pattern already ensures atomicity
+  - All operations are validated before any are applied, maintaining data integrity
+  - Enables complex workflow refactoring in single API calls
+  - Updated documentation and examples to demonstrate large batch operations (26+ operations)
+
+## [2.13.0] - 2025-01-24
+
+### Added
+- **Webhook Path Autofixer**: Automatically generates UUIDs for webhook nodes missing path configuration
+  - Generates unique UUID for both `path` parameter and `webhookId` field
+  - Conditionally updates typeVersion to 2.1 only when < 2.1 to ensure compatibility
+  - High confidence fix (95%) as UUID generation is deterministic
+  - Resolves webhook nodes showing "?" in the n8n UI
+
+- **Enhanced Node Type Suggestions**: Intelligent node type correction with similarity matching
+  - Multi-factor scoring system: name similarity, category match, package match, pattern match
+  - Handles deprecated package prefixes (n8n-nodes-base. → nodes-base.)
+  - Corrects capitalization mistakes (HttpRequest → httpRequest)
+  - Suggests correct packages (nodes-base.openai → nodes-langchain.openAi)
+  - Only auto-fixes suggestions with ≥90% confidence
+  - 5-minute cache for performance optimization
+
+- **n8n_autofix_workflow Tool**: New MCP tool for automatic workflow error correction
+  - Comprehensive documentation with examples and best practices
+  - Supports 5 fix types: expression-format, typeversion-correction, error-output-config, node-type-correction, webhook-missing-path
+  - Confidence-based system (high/medium/low) for safe fixes
+  - Preview mode to review changes before applying
+  - Integrated with workflow validation pipeline
+
+### Fixed
+- **Security**: Eliminated ReDoS vulnerability in NodeSimilarityService
+  - Replaced all regex patterns with string-based matching
+  - No performance impact while maintaining accuracy
+
+- **Performance**: Optimized similarity matching algorithms
+  - Levenshtein distance algorithm optimized from O(m*n) space to O(n)
+  - Added early termination for performance improvement
+  - Cache invalidation with version tracking prevents memory leaks
+
+- **Code Quality**: Improved maintainability and type safety
+  - Extracted magic numbers into named constants
+  - Added proper type guards for runtime safety
+  - Created centralized node-type-utils for consistent type normalization
+  - Fixed silent failures in setNestedValue operations
+
+### Changed
+- Template sanitizer now includes defensive null checks for runtime safety
+- Workflow validator uses centralized type normalization utility
+
+## [2.12.2] - 2025-01-22
+
+### Changed
+- Updated n8n dependencies to latest versions:
+  - n8n: 1.111.0 → 1.112.3
+  - n8n-core: 1.110.0 → 1.111.0
+  - n8n-workflow: 1.108.0 → 1.109.0
+  - @n8n/n8n-nodes-langchain: 1.110.0 → 1.111.1
+- Rebuilt node database with 536 nodes (438 from n8n-nodes-base, 98 from langchain)
+
+## [2.12.1] - 2025-01-21
+
+### Added
+- **Comprehensive Expression Format Validation System**: Three-tier validation strategy for n8n expressions
+  - **Universal Expression Validator**: 100% reliable detection of expression format issues
+    - Enforces required `=` prefix for all expressions `{{ }}`
+    - Validates expression syntax (bracket matching, empty expressions)
+    - Detects common mistakes (template literals, nested brackets, double prefixes)
+    - Provides confidence score of 1.0 for universal rules
+  - **Confidence-Based Node-Specific Recommendations**: Intelligent resource locator suggestions
+    - Confidence scoring system (0.0 to 1.0) for field-specific recommendations
+    - High confidence (≥0.8): Exact field matches for known nodes (GitHub owner/repository, Slack channels)
+    - Medium confidence (≥0.5): Field pattern matches (fields ending in Id, Key, Name)
+    - Factors: exact field match, field patterns, value patterns, node category
+  - **Resource Locator Format Detection**: Identifies fields needing `__rl` structure
+    - Validates resource locator mode (id, url, expression, name, list)
+    - Auto-fixes missing prefixes in resource locator values
+    - Provides clear JSON examples showing correct format
+  - **Enhanced Safety Features**:
+    - Recursion depth protection (MAX_RECURSION_DEPTH = 100) prevents infinite loops
+    - Pattern matching precision using exact/prefix matching instead of includes()
+    - Circular reference detection with WeakSet
+  - **Separation of Concerns**: Clean architecture for maintainability
+    - Universal rules separated from node-specific intelligence
+    - Confidence-based application of suggestions
+    - Future-proof design that works with any n8n node
+
+## [2.12.1] - 2025-09-22
+
+### Fixed
+- **Error Output Validation**: Enhanced workflow validator to detect incorrect error output configurations
+  - Detects when multiple nodes are incorrectly placed in the same output array (main[0])
+  - Validates that error handlers are properly connected to main[1] (error output) instead of main[0]
+  - Cross-validates onError property ('continueErrorOutput') matches actual connection structure
+  - Provides clear, actionable error messages with JSON examples showing correct configuration
+  - Uses heuristic detection for error handler nodes (names containing "error", "fail", "catch", etc.)
+  - Added comprehensive test coverage with 16+ test cases
+
+### Improved
+- **Validation Messages**: Error messages now include detailed JSON examples showing both incorrect and correct configurations
+- **Pattern Detection**: Fixed `checkWorkflowPatterns` to check main[1] for error outputs instead of non-existent outputs.error
+- **Test Coverage**: Added new test file `workflow-validator-error-outputs.test.ts` with extensive error output validation scenarios
+
+## [2.12.0] - 2025-09-19
+
+### Added
+- **Flexible Instance Configuration**: Complete multi-instance support for serving multiple n8n instances dynamically
+  - New `InstanceContext` interface for runtime configuration without multi-tenancy implications
+  - Dual-mode API client supporting both singleton (env vars) and instance-specific configurations
+  - LRU cache with SHA-256 hashing for secure client management (100 instances, 30-min TTL)
+  - Comprehensive input validation preventing injection attacks and invalid configurations
+  - Session context management in HTTP server for per-session instance configuration
+  - 100% backward compatibility - existing deployments work unchanged
+  - Full test coverage with 83 new tests covering security, caching, and validation
+
+### Security
+- **SHA-256 Cache Key Hashing**: All instance identifiers are hashed before caching
+- **Input Validation**: Comprehensive validation for URLs, API keys, and numeric parameters
+- **Secure Logging**: Sensitive data never logged, only partial hashes for debugging
+- **Memory Management**: LRU eviction and TTL prevent unbounded growth
+- **URL Validation**: Blocks dangerous protocols (file://, javascript://, etc.)
+
+### Performance
+- **Efficient Caching**: LRU cache with automatic cleanup reduces API client creation
+- **Fast Lookups**: SHA-256 hashed keys for O(1) cache access
+- **Memory Optimized**: Maximum 100 concurrent instances with 30-minute TTL
+- **Token Savings**: Reuses existing clients instead of recreating
+
+### Documentation
+- Added comprehensive [Flexible Instance Configuration Guide](./FLEXIBLE_INSTANCE_CONFIGURATION.md)
+- Detailed architecture, usage examples, and security considerations
+- Migration guide for existing deployments
+- Complete API documentation for InstanceContext
+
+## [2.11.3] - 2025-09-17
+
+### Fixed
+- **n8n_update_partial_workflow Tool**: Fixed critical bug where updateNode and updateConnection operations were using incorrect property name
+  - Changed from `changes` property to `updates` property to match documentation and expected behavior
+  - Resolves issue where AI agents would break workflow connections when updating nodes
+  - Fixes GitHub issues #159 (update_partial_workflow is invalid) and #168 (partial workflow update returns error)
+  - All related tests updated to use correct property name
+
+## [2.11.2] - 2025-09-16
+
+### Updated
+- **n8n Dependencies**: Updated to latest versions for compatibility and new features
+  - n8n: 1.110.1 → 1.111.0
+  - n8n-core: 1.109.0 → 1.110.0
+  - n8n-workflow: 1.107.0 → 1.108.0
+  - @n8n/n8n-nodes-langchain: 1.109.1 → 1.110.0
+- **Node Database**: Rebuilt with 535 nodes from updated n8n packages
+- **Templates**: Preserved all 2,598 workflow templates with metadata intact
+- All critical nodes validated successfully (httpRequest, code, slack, agent)
+- Test suite: 1,911 tests passing, 5 flaky performance tests failing (99.7% pass rate)
 
 ## [2.11.1] - 2025-09-15
 
@@ -1297,6 +1595,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Basic n8n and MCP integration
 - Core workflow automation features
 
+[2.12.0]: https://github.com/czlonkowski/n8n-mcp/compare/v2.11.3...v2.12.0
+[2.11.3]: https://github.com/czlonkowski/n8n-mcp/compare/v2.11.2...v2.11.3
+[2.11.2]: https://github.com/czlonkowski/n8n-mcp/compare/v2.11.1...v2.11.2
 [2.11.1]: https://github.com/czlonkowski/n8n-mcp/compare/v2.11.0...v2.11.1
 [2.11.0]: https://github.com/czlonkowski/n8n-mcp/compare/v2.10.9...v2.11.0
 [2.10.9]: https://github.com/czlonkowski/n8n-mcp/compare/v2.10.8...v2.10.9

docs/CODEX_SETUP.md

@@ -0,0 +1,34 @@
+# Codex Setup
+
+Connect n8n-MCP to Codex for enhanced n8n workflow development.
+
+## Update your Codex configuration
+
+Go to your Codex settings at `~/.codex/config.toml` and add the following configuration:
+
+### Basic configuration (documentation tools only):
+```toml
+[mcp_servers.n8n]
+command = "npx"
+args = ["n8n-mcp"]
+env = { "MCP_MODE" = "stdio", "LOG_LEVEL" = "error", "DISABLE_CONSOLE_OUTPUT" = "true" }
+```
+
+### Full configuration (with n8n management tools):
+```toml
+[mcp_servers.n8n]
+command = "npx"
+args = ["n8n-mcp"]
+env = { "MCP_MODE" = "stdio", "LOG_LEVEL" = "error", "DISABLE_CONSOLE_OUTPUT" = "true", "N8N_API_URL" = "https://your-n8n-instance.com", "N8N_API_KEY" = "your-api-key" }
+```
+
+Make sure to replace `https://your-n8n-instance.com` with your actual n8n URL and `your-api-key` with your n8n API key.
+
+## Managing Your MCP Server
+Enter the Codex CLI and use the `/mcp` command to see server status and available tools.
+
+![n8n-MCP connected and showing 39 tools available](./img/codex_connected.png)
+
+## Project Instructions
+
+For optimal results, create a `AGENTS.md` file in your project root with the instructions same with [main README's Claude Project Setup section](../README.md#-claude-project-setup).

docs/DOCKER_README.md

@@ -65,6 +65,9 @@ docker run -d \
 | `NODE_ENV` | Environment: `development` or `production` | `production` | No |
 | `LOG_LEVEL` | Logging level: `debug`, `info`, `warn`, `error` | `info` | No |
 | `NODE_DB_PATH` | Custom database path (v2.7.16+) | `/app/data/nodes.db` | No |
+| `AUTH_RATE_LIMIT_WINDOW` | Rate limit window in ms (v2.16.3+) | `900000` (15 min) | No |
+| `AUTH_RATE_LIMIT_MAX` | Max auth attempts per window (v2.16.3+) | `20` | No |
+| `WEBHOOK_SECURITY_MODE` | SSRF protection: `strict`/`moderate`/`permissive` (v2.16.3+) | `strict` | No |
 
 *Either `AUTH_TOKEN` or `AUTH_TOKEN_FILE` must be set for HTTP mode. If both are set, `AUTH_TOKEN` takes precedence.
 
@@ -283,7 +286,36 @@ docker ps --format "table {{.Names}}\t{{.Status}}"
 docker inspect n8n-mcp | jq '.[0].State.Health'
 ```
 
-## 🔒 Security Considerations
+## 🔒 Security Features (v2.16.3+)
+
+### Rate Limiting
+
+Protects against brute force authentication attacks:
+
+```bash
+# Configure in .env or docker-compose.yml
+AUTH_RATE_LIMIT_WINDOW=900000  # 15 minutes in milliseconds
+AUTH_RATE_LIMIT_MAX=20         # 20 attempts per IP per window
+```
+
+### SSRF Protection
+
+Prevents Server-Side Request Forgery when using webhook triggers:
+
+```bash
+# For production (blocks localhost + private IPs + cloud metadata)
+WEBHOOK_SECURITY_MODE=strict
+
+# For local development with local n8n instance
+WEBHOOK_SECURITY_MODE=moderate
+
+# For internal testing only (allows private IPs)
+WEBHOOK_SECURITY_MODE=permissive
+```
+
+**Note:** Cloud metadata endpoints (169.254.169.254, metadata.google.internal, etc.) are ALWAYS blocked in all modes.
+
+## 🔒 Authentication
 
 ### Authentication
 

docs/DOCKER_TROUBLESHOOTING.md

@@ -196,6 +196,41 @@ docker ps -a | grep n8n-mcp | grep Exited | awk '{print $1}' | xargs -r docker r
 - Manually clean up containers periodically
 - Consider using HTTP mode instead
 
+### Webhooks to Local n8n Fail (v2.16.3+)
+
+**Symptoms:**
+- `n8n_trigger_webhook_workflow` fails with "SSRF protection" error
+- Error message: "SSRF protection: Localhost access is blocked"
+- Webhooks work from n8n UI but not from n8n-MCP
+
+**Root Cause:** Default strict SSRF protection blocks localhost access to prevent attacks.
+
+**Solution:** Use moderate security mode for local development
+
+```bash
+# For Docker run
+docker run -d \
+  --name n8n-mcp \
+  -e MCP_MODE=http \
+  -e AUTH_TOKEN=your-token \
+  -e WEBHOOK_SECURITY_MODE=moderate \
+  -p 3000:3000 \
+  ghcr.io/czlonkowski/n8n-mcp:latest
+
+# For Docker Compose - add to environment:
+services:
+  n8n-mcp:
+    environment:
+      WEBHOOK_SECURITY_MODE: moderate
+```
+
+**Security Modes Explained:**
+- `strict` (default): Blocks localhost + private IPs + cloud metadata (production)
+- `moderate`: Allows localhost, blocks private IPs + cloud metadata (local development)
+- `permissive`: Allows localhost + private IPs, blocks cloud metadata (testing only)
+
+**Important:** Always use `strict` mode in production. Cloud metadata is blocked in all modes.
+
 ### n8n API Connection Issues
 
 **Symptoms:**

docs/FLEXIBLE_INSTANCE_CONFIGURATION.md

@@ -0,0 +1,371 @@
+# Flexible Instance Configuration
+
+## Overview
+
+The Flexible Instance Configuration feature enables n8n-mcp to serve multiple users with different n8n instances dynamically, without requiring separate deployments for each user. This feature is designed for scenarios where n8n-mcp is hosted centrally and needs to connect to different n8n instances based on runtime context.
+
+## Architecture
+
+### Core Components
+
+1. **InstanceContext Interface** (`src/types/instance-context.ts`)
+   - Runtime configuration container for instance-specific settings
+   - Optional fields for backward compatibility
+   - Comprehensive validation with security checks
+
+2. **Dual-Mode API Client**
+   - **Singleton Mode**: Uses environment variables (backward compatible)
+   - **Instance Mode**: Uses runtime context for multi-instance support
+   - Automatic fallback between modes
+
+3. **LRU Cache with Security**
+   - SHA-256 hashed cache keys for security
+   - 30-minute TTL with automatic cleanup
+   - Maximum 100 concurrent instances
+   - Secure dispose callbacks without logging sensitive data
+
+4. **Session Management**
+   - HTTP server tracks session context
+   - Each session can have different instance configuration
+   - Automatic cleanup on session end
+
+## Configuration
+
+### Environment Variables
+
+New environment variables for cache configuration:
+
+- `INSTANCE_CACHE_MAX` - Maximum number of cached instances (default: 100, min: 1, max: 10000)
+- `INSTANCE_CACHE_TTL_MINUTES` - Cache TTL in minutes (default: 30, min: 1, max: 1440/24 hours)
+
+Example:
+```bash
+# Increase cache size for high-volume deployments
+export INSTANCE_CACHE_MAX=500
+export INSTANCE_CACHE_TTL_MINUTES=60
+```
+
+### InstanceContext Structure
+
+```typescript
+interface InstanceContext {
+  n8nApiUrl?: string;        // n8n instance URL
+  n8nApiKey?: string;        // API key for authentication
+  n8nApiTimeout?: number;    // Request timeout in ms (default: 30000)
+  n8nApiMaxRetries?: number; // Max retry attempts (default: 3)
+  instanceId?: string;       // Unique instance identifier
+  sessionId?: string;        // Session identifier
+  metadata?: Record<string, any>; // Additional metadata
+}
+```
+
+### Validation Rules
+
+1. **URL Validation**:
+   - Must be valid HTTP/HTTPS URL
+   - No file://, javascript:, or other dangerous protocols
+   - Proper URL format with protocol and host
+
+2. **API Key Validation**:
+   - Non-empty string required when provided
+   - No placeholder values (e.g., "YOUR_API_KEY")
+   - Case-insensitive placeholder detection
+
+3. **Numeric Validation**:
+   - Timeout must be positive number (>0)
+   - Max retries must be non-negative (≥0)
+   - No Infinity or NaN values
+
+## Usage Examples
+
+### Basic Usage
+
+```typescript
+import { getN8nApiClient } from './mcp/handlers-n8n-manager';
+import { InstanceContext } from './types/instance-context';
+
+// Create context for a specific instance
+const context: InstanceContext = {
+  n8nApiUrl: 'https://customer1.n8n.cloud',
+  n8nApiKey: 'customer1-api-key',
+  instanceId: 'customer1'
+};
+
+// Get client for this instance
+const client = getN8nApiClient(context);
+if (client) {
+  // Use client for API operations
+  const workflows = await client.getWorkflows();
+}
+```
+
+### HTTP Headers for Multi-Tenant Support
+
+When using the HTTP server mode, clients can pass instance-specific configuration via HTTP headers:
+
+```bash
+# Example curl request with instance headers
+curl -X POST http://localhost:3000/mcp \
+  -H "Authorization: Bearer your-auth-token" \
+  -H "Content-Type: application/json" \
+  -H "X-N8n-Url: https://instance1.n8n.cloud" \
+  -H "X-N8n-Key: instance1-api-key" \
+  -H "X-Instance-Id: instance-1" \
+  -H "X-Session-Id: session-123" \
+  -d '{"method": "n8n_list_workflows", "params": {}, "id": 1}'
+```
+
+#### Supported Headers
+
+- **X-N8n-Url**: The n8n instance URL (e.g., `https://instance.n8n.cloud`)
+- **X-N8n-Key**: The API key for authentication with the n8n instance
+- **X-Instance-Id**: A unique identifier for the instance (optional, for tracking)
+- **X-Session-Id**: A session identifier (optional, for session tracking)
+
+#### Header Extraction Logic
+
+1. If either `X-N8n-Url` or `X-N8n-Key` header is present, an instance context is created
+2. All headers are extracted and passed to the MCP server
+3. The server uses the instance-specific configuration instead of environment variables
+4. If no headers are present, the server falls back to environment variables (backward compatible)
+
+#### Example: JavaScript Client
+
+```javascript
+const headers = {
+  'Authorization': 'Bearer your-auth-token',
+  'Content-Type': 'application/json',
+  'X-N8n-Url': 'https://customer1.n8n.cloud',
+  'X-N8n-Key': 'customer1-api-key',
+  'X-Instance-Id': 'customer-1',
+  'X-Session-Id': 'session-456'
+};
+
+const response = await fetch('http://localhost:3000/mcp', {
+  method: 'POST',
+  headers: headers,
+  body: JSON.stringify({
+    method: 'n8n_list_workflows',
+    params: {},
+    id: 1
+  })
+});
+
+const result = await response.json();
+```
+
+### HTTP Server Integration
+
+```typescript
+// In HTTP request handler
+app.post('/mcp', (req, res) => {
+  const context: InstanceContext = {
+    n8nApiUrl: req.headers['x-n8n-url'],
+    n8nApiKey: req.headers['x-n8n-key'],
+    sessionId: req.sessionID
+  };
+
+  // Context passed to handlers
+  const result = await handleRequest(req.body, context);
+  res.json(result);
+});
+```
+
+### Validation Example
+
+```typescript
+import { validateInstanceContext } from './types/instance-context';
+
+const context: InstanceContext = {
+  n8nApiUrl: 'https://api.n8n.cloud',
+  n8nApiKey: 'valid-key'
+};
+
+const validation = validateInstanceContext(context);
+if (!validation.valid) {
+  console.error('Validation errors:', validation.errors);
+} else {
+  // Context is valid, proceed
+  const client = getN8nApiClient(context);
+}
+```
+
+## Security Features
+
+### 1. Cache Key Hashing
+- All cache keys use SHA-256 hashing with memoization
+- Prevents sensitive data exposure in logs
+- Example: `sha256(url:key:instance)` → 64-char hex string
+- Memoization cache limited to 1000 entries
+
+### 2. Enhanced Input Validation
+- Field-specific error messages with detailed reasons
+- URL protocol restrictions (HTTP/HTTPS only)
+- API key placeholder detection (case-insensitive)
+- Numeric range validation with specific error messages
+- Example: "Invalid n8nApiUrl: ftp://example.com - URL must use HTTP or HTTPS protocol"
+
+### 3. Secure Logging
+- Only first 8 characters of cache keys logged
+- No sensitive data in debug logs
+- URL sanitization (domain only, no paths)
+- Configuration fallback logging for debugging
+
+### 4. Memory Management
+- Configurable LRU cache with automatic eviction
+- TTL-based expiration (configurable, default 30 minutes)
+- Dispose callbacks for cleanup
+- Maximum cache size limits with bounds checking
+
+### 5. Concurrency Protection
+- Mutex-based locking for cache operations
+- Prevents duplicate client creation
+- Simple lock checking with timeout
+- Thread-safe cache operations
+
+## Performance Optimization
+
+### Cache Strategy
+- **Max Size**: Configurable via `INSTANCE_CACHE_MAX` (default: 100)
+- **TTL**: Configurable via `INSTANCE_CACHE_TTL_MINUTES` (default: 30)
+- **Update on Access**: Age refreshed on each use
+- **Eviction**: Least Recently Used (LRU) policy
+- **Memoization**: Hash creation uses memoization for frequently used keys
+
+### Cache Metrics
+The system tracks comprehensive metrics:
+- Cache hits and misses
+- Hit rate percentage
+- Eviction count
+- Current size vs maximum size
+- Operation timing
+
+Retrieve metrics using:
+```typescript
+import { getInstanceCacheStatistics } from './mcp/handlers-n8n-manager';
+console.log(getInstanceCacheStatistics());
+```
+
+### Benefits
+- **Performance**: ~12ms average response time
+- **Memory Efficient**: Minimal footprint per instance
+- **Thread Safe**: Mutex protection for concurrent operations
+- **Auto Cleanup**: Unused instances automatically evicted
+- **No Memory Leaks**: Proper disposal callbacks
+
+## Backward Compatibility
+
+The feature maintains 100% backward compatibility:
+
+1. **Environment Variables Still Work**:
+   - If no context provided, falls back to env vars
+   - Existing deployments continue working unchanged
+
+2. **Optional Parameters**:
+   - All context fields are optional
+   - Missing fields use defaults or env vars
+
+3. **API Unchanged**:
+   - Same handler signatures with optional context
+   - No breaking changes to existing code
+
+## Testing
+
+Comprehensive test coverage ensures reliability:
+
+```bash
+# Run all flexible instance tests
+npm test -- tests/unit/flexible-instance-security-advanced.test.ts
+npm test -- tests/unit/mcp/lru-cache-behavior.test.ts
+npm test -- tests/unit/types/instance-context-coverage.test.ts
+npm test -- tests/unit/mcp/handlers-n8n-manager-simple.test.ts
+```
+
+### Test Coverage Areas
+- Input validation edge cases
+- Cache behavior and eviction
+- Security (hashing, sanitization)
+- Session management
+- Memory leak prevention
+- Concurrent access patterns
+
+## Migration Guide
+
+### For Existing Deployments
+No changes required - environment variables continue to work.
+
+### For Multi-Instance Support
+
+1. **Update HTTP Server** (if using HTTP mode):
+```typescript
+// Add context extraction from headers
+const context = extractInstanceContext(req);
+```
+
+2. **Pass Context to Handlers**:
+```typescript
+// Old way (still works)
+await handleListWorkflows(params);
+
+// New way (with instance context)
+await handleListWorkflows(params, context);
+```
+
+3. **Configure Clients** to send instance information:
+```typescript
+// Client sends instance info in headers
+headers: {
+  'X-N8n-Url': 'https://instance.n8n.cloud',
+  'X-N8n-Key': 'api-key',
+  'X-Instance-Id': 'customer-123'
+}
+```
+
+## Monitoring
+
+### Metrics to Track
+- Cache hit/miss ratio
+- Instance count in cache
+- Average TTL utilization
+- Memory usage per instance
+- API client creation rate
+
+### Debug Logging
+Enable debug logs to monitor cache behavior:
+```bash
+LOG_LEVEL=debug npm start
+```
+
+## Limitations
+
+1. **Maximum Instances**: 100 concurrent instances (configurable)
+2. **TTL**: 30-minute cache lifetime (configurable)
+3. **Memory**: ~1MB per cached instance (estimated)
+4. **Validation**: Strict validation may reject edge cases
+
+## Security Considerations
+
+1. **Never Log Sensitive Data**: API keys are never logged
+2. **Hash All Identifiers**: Use SHA-256 for cache keys
+3. **Validate All Input**: Comprehensive validation before use
+4. **Limit Resources**: Cache size and TTL limits
+5. **Clean Up Properly**: Dispose callbacks for resource cleanup
+
+## Future Enhancements
+
+Potential improvements for future versions:
+
+1. **Configurable Cache Settings**: Runtime cache size/TTL configuration
+2. **Instance Metrics**: Per-instance usage tracking
+3. **Rate Limiting**: Per-instance rate limits
+4. **Instance Groups**: Logical grouping of instances
+5. **Persistent Cache**: Optional Redis/database backing
+6. **Instance Discovery**: Automatic instance detection
+
+## Support
+
+For issues or questions about flexible instance configuration:
+1. Check validation errors for specific problems
+2. Enable debug logging for detailed diagnostics
+3. Review test files for usage examples
+4. Open an issue on GitHub with details

docs/HTTP_DEPLOYMENT.md

@@ -73,6 +73,13 @@ PORT=3000
 # Optional: Enable n8n management tools
 # N8N_API_URL=https://your-n8n-instance.com
 # N8N_API_KEY=your-api-key-here
+# Security Configuration (v2.16.3+)
+# Rate limiting (default: 20 attempts per 15 minutes)
+AUTH_RATE_LIMIT_WINDOW=900000
+AUTH_RATE_LIMIT_MAX=20
+# SSRF protection mode (default: strict)
+# Use 'moderate' for local n8n, 'strict' for production
+WEBHOOK_SECURITY_MODE=strict
 EOF
 
 # 2. Deploy with Docker
@@ -592,6 +599,67 @@ curl -H "Authorization: Bearer $AUTH_TOKEN" \
 }
 ```
 
+## 🔒 Security Features (v2.16.3+)
+
+### Rate Limiting
+
+Built-in rate limiting protects authentication endpoints from brute force attacks:
+
+**Configuration:**
+```bash
+# Defaults (15 minutes window, 20 attempts per IP)
+AUTH_RATE_LIMIT_WINDOW=900000  # milliseconds
+AUTH_RATE_LIMIT_MAX=20
+```
+
+**Features:**
+- Per-IP rate limiting with configurable window and max attempts
+- Standard rate limit headers (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset)
+- JSON-RPC formatted error responses
+- Automatic IP tracking behind reverse proxies (requires TRUST_PROXY=1)
+
+**Behavior:**
+- First 20 attempts: Return 401 Unauthorized for invalid credentials
+- Attempts 21+: Return 429 Too Many Requests with Retry-After header
+- Counter resets after 15 minutes (configurable)
+
+### SSRF Protection
+
+Prevents Server-Side Request Forgery attacks when using webhook triggers:
+
+**Three Security Modes:**
+
+1. **Strict Mode (default)** - Production deployments
+   ```bash
+   WEBHOOK_SECURITY_MODE=strict
+   ```
+   - ✅ Block localhost (127.0.0.1, ::1)
+   - ✅ Block private IPs (10.x, 192.168.x, 172.16-31.x)
+   - ✅ Block cloud metadata (169.254.169.254, metadata.google.internal)
+   - ✅ DNS rebinding prevention
+   - 🎯 **Use for**: Cloud deployments, production environments
+
+2. **Moderate Mode** - Local development with local n8n
+   ```bash
+   WEBHOOK_SECURITY_MODE=moderate
+   ```
+   - ✅ Allow localhost (for local n8n instances)
+   - ✅ Block private IPs
+   - ✅ Block cloud metadata
+   - ✅ DNS rebinding prevention
+   - 🎯 **Use for**: Development with n8n on localhost:5678
+
+3. **Permissive Mode** - Internal networks only
+   ```bash
+   WEBHOOK_SECURITY_MODE=permissive
+   ```
+   - ✅ Allow localhost and private IPs
+   - ✅ Block cloud metadata (always blocked)
+   - ✅ DNS rebinding prevention
+   - 🎯 **Use for**: Internal testing (NOT for production)
+
+**Important:** Cloud metadata endpoints are ALWAYS blocked in all modes for security.
+
 ## 🔒 Security Best Practices
 
 ### 1. Token Management

docs/RAILWAY_DEPLOYMENT.md

@@ -105,6 +105,9 @@ These are automatically set by the Railway template:
 | `CORS_ORIGIN` | `*` | Allow any origin |
 | `HOST` | `0.0.0.0` | Listen on all interfaces |
 | `PORT` | (Railway provides) | Don't set manually |
+| `AUTH_RATE_LIMIT_WINDOW` | `900000` (15 min) | Rate limit window (v2.16.3+) |
+| `AUTH_RATE_LIMIT_MAX` | `20` | Max auth attempts (v2.16.3+) |
+| `WEBHOOK_SECURITY_MODE` | `strict` | SSRF protection mode (v2.16.3+) |
 
 ### Optional Variables
 
@@ -180,6 +183,46 @@ Claude Desktop → mcp-remote → Railway (HTTPS) → n8n-MCP Server
 - Ensure the URL is correct and includes `https://`
 - Check Railway logs for any errors
 
+**Windows: "The filename, directory name, or volume label syntax is incorrect" or npx command not found:**
+
+This is a common Windows issue with spaces in Node.js installation paths. The error occurs because Claude Desktop can't properly execute npx.
+
+**Solution 1: Use node directly (Recommended)**
+```json
+{
+  "mcpServers": {
+    "n8n-railway": {
+      "command": "node",
+      "args": [
+        "C:\\Program Files\\nodejs\\node_modules\\npm\\bin\\npx-cli.js",
+        "-y",
+        "mcp-remote",
+        "https://your-app-name.up.railway.app/mcp",
+        "--header",
+        "Authorization: Bearer YOUR_SECURE_TOKEN_HERE"
+      ]
+    }
+  }
+}
+```
+
+**Solution 2: Use cmd wrapper**
+```json
+{
+  "mcpServers": {
+    "n8n-railway": {
+      "command": "cmd",
+      "args": [
+        "/C",
+        "\"C:\\Program Files\\nodejs\\npx\" -y mcp-remote https://your-app-name.up.railway.app/mcp --header \"Authorization: Bearer YOUR_SECURE_TOKEN_HERE\""
+      ]
+    }
+  }
+}
+```
+
+To find your exact npx path, open Command Prompt and run: `where npx`
+
 ### Railway-Specific Issues
 
 **Build failures:**
@@ -244,6 +287,32 @@ Since the Railway template uses a specific Docker image tag, updates are manual:
 
 You could use the `latest` tag, but this may cause unexpected breaking changes.
 
+## 🔒 Security Features (v2.16.3+)
+
+Railway deployments include enhanced security features:
+
+### Rate Limiting
+- **Automatic brute force protection** - 20 attempts per 15 minutes per IP
+- **Configurable limits** via `AUTH_RATE_LIMIT_WINDOW` and `AUTH_RATE_LIMIT_MAX`
+- **Standard rate limit headers** for client awareness
+
+### SSRF Protection
+- **Default strict mode** blocks localhost, private IPs, and cloud metadata
+- **Cloud metadata always blocked** (169.254.169.254, metadata.google.internal, etc.)
+- **Use `moderate` mode only if** connecting to local n8n instance
+
+**Security Configuration:**
+```bash
+# In Railway Variables tab:
+WEBHOOK_SECURITY_MODE=strict          # Production (recommended)
+# or
+WEBHOOK_SECURITY_MODE=moderate        # If using local n8n with port forwarding
+
+# Rate limiting (defaults are good for most use cases)
+AUTH_RATE_LIMIT_WINDOW=900000         # 15 minutes
+AUTH_RATE_LIMIT_MAX=20                # 20 attempts per IP
+```
+
 ## 📝 Best Practices
 
 1. **Always change the default AUTH_TOKEN immediately**

docs/local/DEEP_DIVE_ANALYSIS_README.md

@@ -0,0 +1,225 @@
+# N8N-MCP Deep Dive Analysis - October 2, 2025
+
+## Overview
+
+This directory contains a comprehensive deep-dive analysis of n8n-mcp usage data from September 26 - October 2, 2025.
+
+**Data Volume Analyzed:**
+- 212,375 telemetry events
+- 5,751 workflow creations
+- 2,119 unique users
+- 6 days of usage data
+
+## Report Structure
+
+
+###: `DEEP_DIVE_ANALYSIS_2025-10-02.md` (Main Report)
+
+**Sections Covered:**
+1. **Executive Summary** - Key findings and recommendations
+2. **Tool Performance Analysis** - Success rates, performance metrics, critical findings
+3. **Validation Catastrophe** - The node type prefix disaster analysis
+4. **Usage Patterns & User Segmentation** - User distribution, daily trends
+5. **Tool Sequence Analysis** - How AI agents use tools together
+6. **Workflow Creation Patterns** - Complexity distribution, popular nodes
+7. **Platform & Version Distribution** - OS, architecture, version adoption
+8. **Error Patterns & Root Causes** - TypeErrors, validation errors, discovery failures
+9. **P0-P1 Refactoring Recommendations** - Detailed implementation guides
+
+**Sections Covered:**
+- Remaining P1 and P2 recommendations
+- Architectural refactoring suggestions
+- Telemetry enhancements
+- CHANGELOG integration
+- Final recommendations summary
+
+## Key Findings Summary
+
+### Critical Issues (P0 - Fix Immediately)
+
+1. **Node Type Prefix Validation Catastrophe**
+   - 5,000+ validation errors from single root cause
+   - `nodes-base.X` vs `n8n-nodes-base.X` confusion
+   - **Solution**: Auto-normalize prefixes (2-4 hours effort)
+
+2. **TypeError in Node Information Tools**
+   - 10-18% failure rate in get_node_essentials/info
+   - 1,000+ failures affecting hundreds of users
+   - **Solution**: Complete null-safety audit (1 day effort)
+
+3. **Task Discovery Failures**
+   - `get_node_for_task` failing 28% of the time
+   - Worst-performing tool in entire system
+   - **Solution**: Expand task library + fuzzy matching (3 days effort)
+
+### Performance Metrics
+
+**Excellent Reliability (96-100% success):**
+- n8n_update_partial_workflow: 98.7%
+- search_nodes: 99.8%
+- n8n_create_workflow: 96.1%
+- All workflow management tools: 100%
+
+**User Distribution:**
+- Power Users (12): 2,112 events/user, 33 workflows
+- Heavy Users (47): 673 events/user, 18 workflows
+- Regular Users (516): 199 events/user, 7 workflows (CORE AUDIENCE)
+- Active Users (919): 52 events/user, 2 workflows
+- Casual Users (625): 8 events/user, 1 workflow
+
+### Usage Insights
+
+**Most Used Tools:**
+1. n8n_update_partial_workflow: 10,177 calls (iterative refinement)
+2. search_nodes: 8,839 calls (node discovery)
+3. n8n_create_workflow: 6,046 calls (workflow creation)
+
+**Most Common Tool Sequences:**
+1. update → update → update (549x) - Iterative refinement pattern
+2. create → update (297x) - Create then refine
+3. update → get_workflow (265x) - Update then verify
+
+**Most Popular Nodes:**
+1. code (53% of workflows) - AI agents love programmatic control
+2. httpRequest (47%) - Integration-heavy usage
+3. webhook (32%) - Event-driven automation
+
+## SQL Analytical Views Created
+
+15 comprehensive views were created in Supabase for ongoing analysis:
+
+1. `vw_tool_performance` - Performance metrics per tool
+2. `vw_error_analysis` - Error patterns and frequencies
+3. `vw_validation_analysis` - Validation failure details
+4. `vw_tool_sequences` - Tool-to-tool transition patterns
+5. `vw_workflow_creation_patterns` - Workflow characteristics
+6. `vw_node_usage_analysis` - Node popularity and complexity
+7. `vw_node_cooccurrence` - Which nodes are used together
+8. `vw_user_activity` - Per-user activity metrics
+9. `vw_session_analysis` - Platform/version distribution
+10. `vw_workflow_validation_failures` - Workflow validation issues
+11. `vw_temporal_patterns` - Time-based usage patterns
+12. `vw_tool_funnel` - User progression through tools
+13. `vw_search_analysis` - Search behavior
+14. `vw_tool_success_summary` - Success/failure rates
+15. `vw_user_journeys` - Complete user session reconstruction
+
+## Priority Recommendations
+
+### Immediate Actions (This Week)
+
+✅ **P0-R1**: Auto-normalize node type prefixes → Eliminate 4,800 errors
+✅ **P0-R2**: Complete null-safety audit → Fix 10-18% TypeError failures
+✅ **P0-R3**: Expand get_node_for_task library → 72% → 95% success rate
+
+**Expected Impact**: Reduce error rate from 5-10% to <2% overall
+
+### Next Release (2-3 Weeks)
+
+✅ **P1-R4**: Batch workflow operations → Save 30-50% tokens
+✅ **P1-R5**: Proactive node suggestions → Reduce search iterations
+✅ **P1-R6**: Auto-fix suggestions in errors → Self-service recovery
+
+**Expected Impact**: 40% faster workflow creation, better UX
+
+### Future Roadmap (1-3 Months)
+
+✅ **A1**: Service layer consolidation → Cleaner architecture
+✅ **A2**: Repository caching → 50% faster node operations
+✅ **R10**: Workflow template library from usage → 80% coverage
+✅ **T1-T3**: Enhanced telemetry → Better observability
+
+**Expected Impact**: Scalable foundation for 10x growth
+
+## Methodology
+
+### Data Sources
+
+1. **Supabase Telemetry Database**
+   - `telemetry_events` table: 212,375 rows
+   - `telemetry_workflows` table: 5,751 rows
+
+2. **Analytical Views**
+   - Created 15 SQL views for multi-dimensional analysis
+   - Enabled complex queries and pattern recognition
+
+3. **CHANGELOG Review**
+   - Analyzed recent changes (v2.14.0 - v2.14.6)
+   - Correlated fixes with error patterns
+
+### Analysis Approach
+
+1. **Quantitative Analysis**
+   - Success/failure rates per tool
+   - Performance metrics (avg, median, p95, p99)
+   - User segmentation and cohort analysis
+   - Temporal trends and growth patterns
+
+2. **Pattern Recognition**
+   - Tool sequence analysis (Markov chains)
+   - Node co-occurrence patterns
+   - Workflow complexity distribution
+   - Error clustering and root cause analysis
+
+3. **Qualitative Insights**
+   - CHANGELOG integration
+   - Error message analysis
+   - User journey reconstruction
+   - Best practice identification
+
+## How to Use This Analysis
+
+### For Development Priorities
+
+1. Review **P0 Critical Recommendations** (Section 8)
+2. Check estimated effort and impact
+3. Prioritize based on ROI (impact/effort ratio)
+4. Follow implementation guides with code examples
+
+### For Architecture Decisions
+
+1. Review **Architectural Recommendations** (Section 9)
+2. Consider service layer consolidation
+3. Evaluate repository caching opportunities
+4. Plan for 10x scale
+
+### For Product Strategy
+
+1. Review **Usage Patterns** (Section 3 & 5)
+2. Understand user segments (power vs casual)
+3. Identify high-value features (most-used tools)
+4. Focus on reliability over features (96% success rate target)
+
+### For Telemetry Enhancement
+
+1. Review **Telemetry Enhancements** (Section 10)
+2. Add fine-grained timing metrics
+3. Track workflow creation funnels
+4. Monitor node-level analytics
+
+## Contact & Feedback
+
+For questions about this analysis or to request additional insights:
+- Data Analyst: Claude Code with Supabase MCP
+- Analysis Date: October 2, 2025
+- Data Period: September 26 - October 2, 2025
+
+## Change Log
+
+- **2025-10-02**: Initial comprehensive analysis completed
+  - 15 SQL analytical views created
+  - 13 sections of detailed findings
+  - P0/P1/P2 recommendations with implementation guides
+  - Code examples and effort estimates provided
+
+## Next Steps
+
+1. ✅ Review findings with development team
+2. ✅ Prioritize P0 recommendations for immediate implementation
+3. ✅ Plan P1 features for next release cycle
+4. ✅ Set up monitoring for key metrics
+5. ✅ Schedule follow-up analysis (weekly recommended)
+
+---
+
+*This analysis represents a snapshot of n8n-mcp usage during early adoption phase. Patterns may evolve as the user base grows and matures.*

docs/local/TEMPLATE_MINING_ANALYSIS.md

@@ -0,0 +1,369 @@
+# Template Mining Analysis - Alternative to P0-R3
+
+**Date**: 2025-10-02
+**Context**: Analyzing whether to fix `get_node_for_task` (28% failure rate) or replace it with template-based configuration extraction
+
+## Executive Summary
+
+**RECOMMENDATION**: Replace `get_node_for_task` with template-based configuration extraction. The template database contains 2,646 real-world workflows with rich node configurations that far exceed the 31 hardcoded task templates.
+
+## Key Findings
+
+### 1. Template Database Coverage
+
+- **Total Templates**: 2,646 production workflows from n8n.io
+- **Unique Node Types**: 543 (covers 103% of our 525 core nodes)
+- **Metadata Coverage**: 100% (AI-generated structured metadata)
+
+### 2. Node Type Coverage in Templates
+
+Top node types by template usage:
+```
+3,820 templates: n8n-nodes-base.httpRequest      (144% of total templates!)
+3,678 templates: n8n-nodes-base.set
+2,445 templates: n8n-nodes-base.code
+1,700 templates: n8n-nodes-base.googleSheets
+1,471 templates: @n8n/n8n-nodes-langchain.agent
+1,269 templates: @n8n/n8n-nodes-langchain.lmChatOpenAi
+  792 templates: n8n-nodes-base.telegram
+  702 templates: n8n-nodes-base.httpRequestTool
+  596 templates: n8n-nodes-base.gmail
+  466 templates: n8n-nodes-base.webhook
+```
+
+**Comparison**:
+- Hardcoded task templates: 31 tasks covering 5.9% of nodes
+- Real templates: 2,646 templates with 2-3k examples for common nodes
+
+### 3. Database Structure
+
+```sql
+CREATE TABLE templates (
+  id INTEGER PRIMARY KEY,
+  workflow_id INTEGER UNIQUE NOT NULL,
+  name TEXT NOT NULL,
+  description TEXT,
+  -- Node information
+  nodes_used TEXT,              -- JSON array: ["n8n-nodes-base.httpRequest", ...]
+  workflow_json_compressed TEXT, -- Base64 encoded gzip of full workflow
+  -- Metadata (100% coverage)
+  metadata_json TEXT,           -- AI-generated structured metadata
+  -- Stats
+  views INTEGER DEFAULT 0,
+  created_at DATETIME,
+  -- ...
+);
+```
+
+### 4. Real Configuration Examples
+
+#### HTTP Request Node Configurations
+
+**Simple URL fetch**:
+```json
+{
+  "url": "https://api.example.com/data",
+  "options": {}
+}
+```
+
+**With authentication**:
+```json
+{
+  "url": "=https://api.wavespeed.ai/api/v3/predictions/{{ $json.data.id }}/result",
+  "options": {},
+  "authentication": "genericCredentialType",
+  "genericAuthType": "httpHeaderAuth"
+}
+```
+
+**Complex expressions**:
+```json
+{
+  "url": "=https://image.pollinations.ai/prompt/{{$('Social Media Content Factory').item.json.output.description.replaceAll(' ','-').replaceAll(',','').replaceAll('.','') }}",
+  "options": {}
+}
+```
+
+#### Webhook Node Configurations
+
+**Basic webhook**:
+```json
+{
+  "path": "ytube",
+  "options": {},
+  "httpMethod": "POST",
+  "responseMode": "responseNode"
+}
+```
+
+**With binary data**:
+```json
+{
+  "path": "your-endpoint",
+  "options": {
+    "binaryPropertyName": "data"
+  },
+  "httpMethod": "POST"
+}
+```
+
+### 5. AI-Generated Metadata
+
+Each template has structured metadata including:
+
+```json
+{
+  "categories": ["automation", "integration", "data processing"],
+  "complexity": "medium",
+  "use_cases": [
+    "Extract transaction data from Gmail",
+    "Automate bookkeeping",
+    "Expense tracking"
+  ],
+  "estimated_setup_minutes": 30,
+  "required_services": ["Gmail", "Google Sheets", "Google Gemini"],
+  "key_features": [
+    "Fetch emails by label",
+    "Extract transaction data",
+    "Use LLM for structured output"
+  ],
+  "target_audience": ["Accountants", "Small business owners"]
+}
+```
+
+## Comparison: Task Templates vs Real Templates
+
+### Current Approach (get_node_for_task)
+
+**Pros**:
+- Curated configurations with best practices
+- Predictable, stable responses
+- Fast lookup (no decompression needed)
+
+**Cons**:
+- Only 31 tasks (5.9% node coverage)
+- 28% failure rate (users can't find what they need)
+- Requires manual maintenance
+- Static configurations without real-world context
+- Usage ratio 22.5:1 (search_nodes is preferred)
+
+### Template-Based Approach
+
+**Pros**:
+- 2,646 real workflows with 2-3k examples for common nodes
+- 100% metadata coverage for semantic matching
+- Real-world patterns and best practices
+- Covers 543 node types (103% coverage)
+- Self-updating (templates fetched from n8n.io)
+- Rich context (use cases, complexity, setup time)
+
+**Cons**:
+- Requires decompression for full workflow access
+- May contain template-specific context (but can be filtered)
+- Need ranking/filtering logic for best matches
+
+## Proposed Implementation Strategy
+
+### Phase 1: Extract Node Configurations from Templates
+
+Create a new service: `TemplateConfigExtractor`
+
+```typescript
+interface ExtractedNodeConfig {
+  nodeType: string;
+  configuration: Record<string, any>;
+  source: {
+    templateId: number;
+    templateName: string;
+    templateViews: number;
+    useCases: string[];
+    complexity: 'simple' | 'medium' | 'complex';
+  };
+  patterns: {
+    hasAuthentication: boolean;
+    hasExpressions: boolean;
+    hasOptionalFields: boolean;
+  };
+}
+
+class TemplateConfigExtractor {
+  async extractConfigsForNode(
+    nodeType: string,
+    options?: {
+      complexity?: 'simple' | 'medium' | 'complex';
+      requiresAuth?: boolean;
+      limit?: number;
+    }
+  ): Promise<ExtractedNodeConfig[]> {
+    // 1. Query templates containing nodeType
+    // 2. Decompress workflow_json_compressed
+    // 3. Extract node configurations
+    // 4. Rank by popularity + complexity match
+    // 5. Return top N configurations
+  }
+}
+```
+
+### Phase 2: Integrate with Existing Tools
+
+**Option A**: Enhance `get_node_essentials`
+- Add `includeExamples: boolean` parameter
+- Return 2-3 real configurations from templates
+- Preserve existing compact format
+
+**Option B**: Enhance `get_node_info`
+- Add `examples` section with template-sourced configs
+- Include source attribution (template name, views)
+
+**Option C**: New tool `get_node_examples`
+- Dedicated tool for retrieving configuration examples
+- Query by node type, complexity, use case
+- Returns ranked list of real configurations
+
+### Phase 3: Deprecate get_node_for_task
+
+- Mark as deprecated in tool documentation
+- Redirect to enhanced tools
+- Remove after 2-3 version cycles
+
+## Performance Considerations
+
+### Decompression Cost
+
+- Average compressed size: 6-12 KB
+- Decompression time: ~5-10ms per template
+- Caching strategy needed for frequently accessed templates
+
+### Query Strategy
+
+```sql
+-- Fast: Get templates for a node type (no decompression)
+SELECT id, name, views, metadata_json
+FROM templates
+WHERE nodes_used LIKE '%n8n-nodes-base.httpRequest%'
+ORDER BY views DESC
+LIMIT 10;
+
+-- Then decompress only top matches
+```
+
+### Caching
+
+- Cache decompressed workflows for popular templates (top 100)
+- TTL: 1 hour
+- Estimated memory: 100 * 50KB = 5MB
+
+## Impact on P0-R3
+
+**Original P0-R3 Plan**: Expand task library from 31 to 100+ tasks using fuzzy matching
+
+**New Approach**: Mine 2,646 templates for real configurations
+
+**Impact Assessment**:
+
+| Metric | Original Plan | Template Mining |
+|--------|--------------|-----------------|
+| Configuration examples | 100 (estimated) | 2,646+ actual |
+| Node coverage | ~20% | 103% |
+| Maintenance | High (manual) | Low (auto-fetch) |
+| Accuracy | Curated | Production-tested |
+| Context richness | Limited | Rich metadata |
+| Development time | 2-3 weeks | 1 week |
+
+**Recommendation**: PIVOT to template mining approach for P0-R3
+
+## Implementation Estimate
+
+### Week 1: Core Infrastructure
+- Day 1-2: Create `TemplateConfigExtractor` service
+- Day 3: Implement caching layer
+- Day 4-5: Testing and optimization
+
+### Week 2: Integration
+- Day 1-2: Enhance `get_node_essentials` with examples
+- Day 3: Update tool documentation
+- Day 4-5: Integration testing
+
+**Total**: 2 weeks vs 3 weeks for original plan
+
+## Validation Tests
+
+```typescript
+// Test: Extract HTTP Request configs
+const configs = await extractor.extractConfigsForNode(
+  'n8n-nodes-base.httpRequest',
+  { complexity: 'simple', limit: 5 }
+);
+
+// Expected: 5 configs from top templates
+// - Simple URL fetch
+// - With authentication
+// - With custom headers
+// - With expressions
+// - With error handling
+
+// Test: Extract webhook configs
+const webhookConfigs = await extractor.extractConfigsForNode(
+  'n8n-nodes-base.webhook',
+  { limit: 3 }
+);
+
+// Expected: 3 configs showing different patterns
+// - Basic POST webhook
+// - With response node
+// - With binary data handling
+```
+
+## Risks and Mitigation
+
+### Risk 1: Template Quality Varies
+- **Mitigation**: Filter by views (popularity) and metadata complexity rating
+- Only use templates with >1000 views for examples
+
+### Risk 2: Decompression Performance
+- **Mitigation**: Cache decompressed popular templates
+- Implement lazy loading (decompress on demand)
+
+### Risk 3: Template-Specific Context
+- **Mitigation**: Extract only node configuration, strip workflow-specific context
+- Provide source attribution for context
+
+### Risk 4: Breaking Changes in Template Structure
+- **Mitigation**: Robust error handling in decompression
+- Fallback to cached configs if template fetch fails
+
+## Success Metrics
+
+**Before** (get_node_for_task):
+- 392 calls, 72% success rate
+- 28% failure rate
+- 31 task templates
+- 5.9% node coverage
+
+**Target** (template-based):
+- 90%+ success rate for configuration discovery
+- 100%+ node coverage
+- 2,646+ real-world examples
+- Self-updating from n8n.io
+
+## Next Steps
+
+1. ✅ Complete template database analysis
+2. ⏳ Create `TemplateConfigExtractor` service
+3. ⏳ Implement caching layer
+4. ⏳ Enhance `get_node_essentials` with examples
+5. ⏳ Update P0 implementation plan
+6. ⏳ Begin implementation
+
+## Conclusion
+
+The template database provides a vastly superior alternative to hardcoded task templates:
+
+- **2,646 templates** vs 31 tasks (85x more examples)
+- **103% node coverage** vs 5.9% coverage (17x improvement)
+- **Real-world configurations** vs synthetic examples
+- **Self-updating** vs manual maintenance
+- **Rich metadata** for semantic matching
+
+**Recommendation**: Pivot P0-R3 from "expand task library" to "mine template configurations"

docs/local/integration-tests-phase1-summary.md

@@ -0,0 +1,260 @@
+# Integration Tests Phase 1: Foundation - COMPLETED
+
+## Overview
+Phase 1 establishes the foundation for n8n API integration testing. All core utilities, fixtures, and infrastructure are now in place.
+
+## Branch
+`feat/integration-tests-foundation`
+
+## Completed Tasks
+
+### 1. Environment Configuration
+- ✅ Updated `.env.example` with integration testing configuration
+- ✅ Added environment variables for:
+  - n8n API credentials (`N8N_API_URL`, `N8N_API_KEY`)
+  - Webhook workflow IDs (4 workflows for GET/POST/PUT/DELETE)
+  - Test configuration (cleanup, tags, naming)
+- ✅ Included detailed setup instructions in comments
+
+### 2. Directory Structure
+```
+tests/integration/n8n-api/
+├── workflows/        (empty - for Phase 2+)
+├── executions/       (empty - for Phase 2+)
+├── system/           (empty - for Phase 2+)
+├── scripts/
+│   └── cleanup-orphans.ts
+└── utils/
+    ├── credentials.ts
+    ├── n8n-client.ts
+    ├── test-context.ts
+    ├── cleanup-helpers.ts
+    ├── fixtures.ts
+    ├── factories.ts
+    └── webhook-workflows.ts
+```
+
+### 3. Core Utilities
+
+#### `credentials.ts` (200 lines)
+- Environment-aware credential loading
+- Detects CI vs local environment automatically
+- Validation functions with helpful error messages
+- Non-throwing credential check functions
+
+**Key Functions:**
+- `getN8nCredentials()` - Load credentials from .env or GitHub secrets
+- `validateCredentials()` - Ensure required credentials are present
+- `validateWebhookWorkflows()` - Check webhook workflow IDs with setup instructions
+- `hasCredentials()` - Non-throwing credential check
+- `hasWebhookWorkflows()` - Non-throwing webhook check
+
+#### `n8n-client.ts` (45 lines)
+- Singleton n8n API client wrapper
+- Pre-configured with test credentials
+- Health check functionality
+
+**Key Functions:**
+- `getTestN8nClient()` - Get/create configured API client
+- `resetTestN8nClient()` - Reset client instance
+- `isN8nApiAccessible()` - Check API connectivity
+
+#### `test-context.ts` (120 lines)
+- Resource tracking for automatic cleanup
+- Test workflow naming utilities
+- Tag management
+
+**Key Functions:**
+- `createTestContext()` - Create context for tracking resources
+- `TestContext.trackWorkflow()` - Track workflow for cleanup
+- `TestContext.trackExecution()` - Track execution for cleanup
+- `TestContext.cleanup()` - Delete all tracked resources
+- `createTestWorkflowName()` - Generate unique workflow names
+- `getTestTag()` - Get configured test tag
+
+#### `cleanup-helpers.ts` (275 lines)
+- Multi-level cleanup strategies
+- Orphaned resource detection
+- Age-based execution cleanup
+- Tag-based workflow cleanup
+
+**Key Functions:**
+- `cleanupOrphanedWorkflows()` - Find and delete test workflows
+- `cleanupOldExecutions()` - Delete executions older than X hours
+- `cleanupAllTestResources()` - Comprehensive cleanup
+- `cleanupWorkflowsByTag()` - Delete workflows by tag
+- `cleanupExecutionsByWorkflow()` - Delete workflow's executions
+
+#### `fixtures.ts` (310 lines)
+- Pre-built workflow templates
+- All using FULL node type format (n8n-nodes-base.*)
+
+**Available Fixtures:**
+- `SIMPLE_WEBHOOK_WORKFLOW` - Single webhook node
+- `SIMPLE_HTTP_WORKFLOW` - Webhook + HTTP Request
+- `MULTI_NODE_WORKFLOW` - Complex branching workflow
+- `ERROR_HANDLING_WORKFLOW` - Error output configuration
+- `AI_AGENT_WORKFLOW` - Langchain agent node
+- `EXPRESSION_WORKFLOW` - n8n expressions testing
+
+**Helper Functions:**
+- `getFixture()` - Get fixture by name (with deep clone)
+- `createCustomWorkflow()` - Build custom workflow from nodes
+
+#### `factories.ts` (315 lines)
+- Dynamic test data generation
+- Node builders with sensible defaults
+- Workflow composition helpers
+
+**Node Factories:**
+- `createWebhookNode()` - Webhook node with customization
+- `createHttpRequestNode()` - HTTP Request node
+- `createSetNode()` - Set node with assignments
+- `createManualTriggerNode()` - Manual trigger node
+
+**Connection Factories:**
+- `createConnection()` - Simple node connection
+- `createSequentialWorkflow()` - Auto-connected sequential nodes
+- `createParallelWorkflow()` - Trigger with parallel branches
+- `createErrorHandlingWorkflow()` - Workflow with error handling
+
+**Utilities:**
+- `randomString()` - Generate random test data
+- `uniqueId()` - Unique IDs for testing
+- `createTestTags()` - Test workflow tags
+- `createWorkflowSettings()` - Common settings
+
+#### `webhook-workflows.ts` (215 lines)
+- Webhook workflow configuration templates
+- Setup instructions generator
+- URL generation utilities
+
+**Key Features:**
+- `WEBHOOK_WORKFLOW_CONFIGS` - Configurations for all 4 HTTP methods
+- `printSetupInstructions()` - Print detailed setup guide
+- `generateWebhookWorkflowJson()` - Generate workflow JSON
+- `exportAllWebhookWorkflows()` - Export all 4 configs
+- `getWebhookUrl()` - Get webhook URL for testing
+- `isValidWebhookWorkflow()` - Validate workflow structure
+
+### 4. Scripts
+
+#### `cleanup-orphans.ts` (40 lines)
+- Standalone cleanup script
+- Can be run manually or in CI
+- Comprehensive output logging
+
+**Usage:**
+```bash
+npm run test:cleanup:orphans
+```
+
+### 5. npm Scripts
+Added to `package.json`:
+```json
+{
+  "test:integration:n8n": "vitest run tests/integration/n8n-api",
+  "test:cleanup:orphans": "tsx tests/integration/n8n-api/scripts/cleanup-orphans.ts"
+}
+```
+
+## Code Quality
+
+### TypeScript
+- ✅ All code passes `npm run typecheck`
+- ✅ All code compiles with `npm run build`
+- ✅ No TypeScript errors
+- ✅ Proper type annotations throughout
+
+### Error Handling
+- ✅ Comprehensive error messages
+- ✅ Helpful setup instructions in error messages
+- ✅ Non-throwing validation functions where appropriate
+- ✅ Graceful handling of missing credentials
+
+### Documentation
+- ✅ All functions have JSDoc comments
+- ✅ Usage examples in comments
+- ✅ Clear parameter descriptions
+- ✅ Return type documentation
+
+## Files Created
+
+### Documentation
+1. `docs/local/integration-testing-plan.md` (550 lines)
+2. `docs/local/integration-tests-phase1-summary.md` (this file)
+
+### Code
+1. `.env.example` - Updated with test configuration (32 new lines)
+2. `package.json` - Added 2 npm scripts
+3. `tests/integration/n8n-api/utils/credentials.ts` (200 lines)
+4. `tests/integration/n8n-api/utils/n8n-client.ts` (45 lines)
+5. `tests/integration/n8n-api/utils/test-context.ts` (120 lines)
+6. `tests/integration/n8n-api/utils/cleanup-helpers.ts` (275 lines)
+7. `tests/integration/n8n-api/utils/fixtures.ts` (310 lines)
+8. `tests/integration/n8n-api/utils/factories.ts` (315 lines)
+9. `tests/integration/n8n-api/utils/webhook-workflows.ts` (215 lines)
+10. `tests/integration/n8n-api/scripts/cleanup-orphans.ts` (40 lines)
+
+**Total New Code:** ~1,520 lines of production-ready TypeScript
+
+## Next Steps (Phase 2)
+
+Phase 2 will implement the first actual integration tests:
+- Create workflow creation tests (10+ scenarios)
+- Test P0 bug fix (SHORT vs FULL node types)
+- Test workflow retrieval
+- Test workflow deletion
+
+**Branch:** `feat/integration-tests-workflow-creation`
+
+## Prerequisites for Running Tests
+
+Before running integration tests, you need to:
+
+1. **Set up n8n instance:**
+   - Local: `npx n8n start`
+   - Or use cloud/self-hosted n8n
+
+2. **Configure credentials in `.env`:**
+   ```bash
+   N8N_API_URL=http://localhost:5678
+   N8N_API_KEY=<your-api-key>
+   ```
+
+3. **Create 4 webhook workflows manually:**
+   - One for each HTTP method (GET, POST, PUT, DELETE)
+   - Activate each workflow in n8n UI
+   - Set workflow IDs in `.env`:
+     ```bash
+     N8N_TEST_WEBHOOK_GET_ID=<workflow-id>
+     N8N_TEST_WEBHOOK_POST_ID=<workflow-id>
+     N8N_TEST_WEBHOOK_PUT_ID=<workflow-id>
+     N8N_TEST_WEBHOOK_DELETE_ID=<workflow-id>
+     ```
+
+See `docs/local/integration-testing-plan.md` for detailed setup instructions.
+
+## Success Metrics
+
+Phase 1 Success Criteria - ALL MET:
+- ✅ All utilities implemented and tested
+- ✅ TypeScript compiles without errors
+- ✅ Code follows project conventions
+- ✅ Comprehensive documentation
+- ✅ Environment configuration complete
+- ✅ Cleanup infrastructure in place
+- ✅ Ready for Phase 2 test implementation
+
+## Lessons Learned
+
+1. **N8nApiClient Constructor:** Uses config object, not separate parameters
+2. **Cursor Handling:** n8n API returns `null` for no more pages, need to convert to `undefined`
+3. **Workflow ID Validation:** Some workflows might have undefined IDs, need null checks
+4. **Connection Types:** Error connections need explicit typing to avoid TypeScript errors
+5. **Webhook Activation:** Cannot be done via API, must be manual - hence pre-activated workflow requirement
+
+## Time Invested
+
+Phase 1 actual time: ~2 hours (estimated 2-3 days in plan)
+- Faster than expected due to clear architecture and reusable patterns

docs/testing-architecture.md

@@ -2,21 +2,27 @@
 
 ## Overview
 
-This document describes the comprehensive testing infrastructure implemented for the n8n-MCP project. The testing suite includes over 1,100 tests split between unit and integration tests, benchmarks, and a complete CI/CD pipeline ensuring code quality and reliability.
+This document describes the comprehensive testing infrastructure implemented for the n8n-MCP project. The testing suite includes 3,336 tests split between unit and integration tests, benchmarks, and a complete CI/CD pipeline ensuring code quality and reliability.
 
-### Test Suite Statistics (from CI Run #41)
+### Test Suite Statistics (October 2025)
 
-- **Total Tests**: 1,182 tests
-  - **Unit Tests**: 933 tests (932 passed, 1 skipped)
-  - **Integration Tests**: 249 tests (245 passed, 4 skipped)
-- **Test Files**: 
-  - 30 unit test files
-  - 14 integration test files
-- **Test Execution Time**: 
+- **Total Tests**: 3,336 tests
+  - **Unit Tests**: 2,766 tests - Isolated component testing with mocks
+  - **Integration Tests**: 570 tests - Full system behavior validation
+    - n8n API Integration: 172 tests (all 18 MCP handler tools)
+    - MCP Protocol: 119 tests (protocol compliance, session management)
+    - Database: 226 tests (repository operations, transactions, FTS5)
+    - Templates: 35 tests (fetching, storage, metadata)
+    - Docker: 18 tests (configuration, security)
+- **Test Files**:
+  - 106 unit test files
+  - 41 integration test files
+  - Total: 147 test files
+- **Test Execution Time**:
   - Unit tests: ~2 minutes with coverage
-  - Integration tests: ~23 seconds
-  - Total CI time: ~2.5 minutes
-- **Success Rate**: 99.5% (only 5 tests skipped, 0 failures)
+  - Integration tests: ~30 seconds
+  - Total CI time: ~3 minutes
+- **Success Rate**: 100% (all tests passing in CI)
 - **CI/CD Pipeline**: Fully automated with GitHub Actions
 - **Test Artifacts**: JUnit XML, coverage reports, benchmark results
 - **Parallel Execution**: Configurable with thread pool
@@ -66,13 +72,20 @@ export default defineConfig({
 
 ```
 tests/
-├── unit/                        # Unit tests with mocks (933 tests, 30 files)
+├── unit/                        # Unit tests with mocks (2,766 tests, 106 files)
 │   ├── __mocks__/              # Mock implementations
 │   │   └── n8n-nodes-base.test.ts
 │   ├── database/               # Database layer tests
 │   │   ├── database-adapter-unit.test.ts
 │   │   ├── node-repository-core.test.ts
 │   │   └── template-repository-core.test.ts
+│   ├── docker/                 # Docker configuration tests
+│   │   ├── config-security.test.ts
+│   │   ├── edge-cases.test.ts
+│   │   ├── parse-config.test.ts
+│   │   └── serve-command.test.ts
+│   ├── http-server/            # HTTP server tests
+│   │   └── multi-tenant-support.test.ts
 │   ├── loaders/                # Node loader tests
 │   │   └── node-loader.test.ts
 │   ├── mappers/                # Data mapper tests
@@ -86,6 +99,8 @@ tests/
 │   │   ├── node-parser.test.ts
 │   │   ├── property-extractor.test.ts
 │   │   └── simple-parser.test.ts
+│   ├── scripts/                # Script tests
+│   │   └── fetch-templates-extraction.test.ts
 │   ├── services/               # Service layer tests (largest test suite)
 │   │   ├── config-validator.test.ts
 │   │   ├── enhanced-config-validator.test.ts
@@ -100,22 +115,56 @@ tests/
 │   │   ├── workflow-diff-engine.test.ts
 │   │   ├── workflow-validator-comprehensive.test.ts
 │   │   └── workflow-validator.test.ts
+│   ├── telemetry/              # Telemetry tests
+│   │   └── telemetry-manager.test.ts
 │   └── utils/                  # Utility function tests
+│       ├── cache-utils.test.ts
 │       └── database-utils.test.ts
-├── integration/                 # Integration tests (249 tests, 14 files)
-│   ├── database/               # Database integration tests
+├── integration/                 # Integration tests (570 tests, 41 files)
+│   ├── n8n-api/                # n8n API integration tests (172 tests, 18 files)
+│   │   ├── executions/         # Execution management tests
+│   │   │   ├── get-execution.test.ts
+│   │   │   └── list-executions.test.ts
+│   │   ├── system/             # System tool tests
+│   │   │   ├── diagnostic.test.ts
+│   │   │   ├── health-check.test.ts
+│   │   │   └── list-tools.test.ts
+│   │   ├── utils/              # Test utilities
+│   │   │   ├── mcp-context.ts
+│   │   │   └── response-types.ts
+│   │   └── workflows/          # Workflow management tests
+│   │       ├── autofix-workflow.test.ts
+│   │       ├── create-workflow.test.ts
+│   │       ├── delete-workflow.test.ts
+│   │       ├── get-workflow-details.test.ts
+│   │       ├── get-workflow-minimal.test.ts
+│   │       ├── get-workflow-structure.test.ts
+│   │       ├── get-workflow.test.ts
+│   │       ├── list-workflows.test.ts
+│   │       ├── update-full-workflow.test.ts
+│   │       ├── update-partial-workflow.test.ts
+│   │       └── validate-workflow.test.ts
+│   ├── database/               # Database integration tests (226 tests)
 │   │   ├── connection-management.test.ts
 │   │   ├── fts5-search.test.ts
 │   │   ├── node-repository.test.ts
 │   │   ├── performance.test.ts
+│   │   ├── template-node-configs.test.ts
+│   │   ├── template-repository.test.ts
 │   │   └── transactions.test.ts
-│   ├── mcp-protocol/           # MCP protocol tests
+│   ├── docker/                 # Docker integration tests (18 tests)
+│   │   ├── docker-config.test.ts
+│   │   └── docker-entrypoint.test.ts
+│   ├── mcp-protocol/           # MCP protocol tests (119 tests)
 │   │   ├── basic-connection.test.ts
 │   │   ├── error-handling.test.ts
 │   │   ├── performance.test.ts
 │   │   ├── protocol-compliance.test.ts
 │   │   ├── session-management.test.ts
-│   │   └── tool-invocation.test.ts
+│   │   ├── tool-invocation.test.ts
+│   │   └── workflow-error-validation.test.ts
+│   ├── templates/              # Template tests (35 tests)
+│   │   └── metadata-operations.test.ts
 │   └── setup/                  # Integration test setup
 │       ├── integration-setup.ts
 │       └── msw-test-server.ts
@@ -368,9 +417,54 @@ describe('n8n-nodes-base mock', () => {
 
 ## Integration Testing
 
-Our integration tests verify the complete system behavior:
+Our integration tests verify the complete system behavior across 570 tests in four major categories:
 
-### MCP Protocol Testing
+### n8n API Integration Testing (172 tests)
+
+The n8n API integration tests verify all 18 MCP handler tools against a real n8n instance. These tests ensure our product layer (MCP handlers) work correctly end-to-end, not just the raw API client.
+
+**Test Organization:**
+- **Workflows** (11 handlers): Create, read, update (full/partial), delete, list, validate, autofix
+- **Executions** (2 handlers): Get execution details, list executions
+- **System** (3 handlers): Health check, list available tools, diagnostics
+
+**Example:**
+```typescript
+// tests/integration/n8n-api/workflows/create-workflow.test.ts
+describe('Integration: handleCreateWorkflow', () => {
+  it('should create a simple two-node workflow', async () => {
+    const response = await handleCreateWorkflow(
+      {
+        params: {
+          arguments: {
+            name: 'Test Workflow',
+            nodes: [webhook, setNode],
+            connections: { Webhook: { main: [[{ node: 'Set', type: 'main', index: 0 }]] } }
+          }
+        }
+      },
+      mcpContext
+    );
+
+    expect(response.success).toBe(true);
+    const workflow = response.data as WorkflowData;
+    expect(workflow.id).toBeDefined();
+    expect(workflow.nodes).toHaveLength(2);
+
+    // Cleanup
+    await handleDeleteWorkflow({ params: { arguments: { id: workflow.id } } }, mcpContext);
+  });
+});
+```
+
+**Key Features Tested:**
+- Real workflow creation, modification, deletion with cleanup
+- TypeScript type safety with response interfaces
+- Complete coverage of all 18 n8n API tools
+- Proper error handling and edge cases
+- Response format validation
+
+### MCP Protocol Testing (119 tests)
 
 ```typescript
 // tests/integration/mcp-protocol/tool-invocation.test.ts
@@ -381,20 +475,20 @@ describe('MCP Tool Invocation', () => {
   beforeEach(async () => {
     mcpServer = new TestableN8NMCPServer();
     await mcpServer.initialize();
-    
+
     const [serverTransport, clientTransport] = InMemoryTransport.createLinkedPair();
     await mcpServer.connectToTransport(serverTransport);
-    
+
     client = new Client({ name: 'test-client', version: '1.0.0' }, {});
     await client.connect(clientTransport);
   });
 
   it('should list nodes with filtering', async () => {
-    const response = await client.callTool({ 
-      name: 'list_nodes', 
-      arguments: { category: 'trigger', limit: 10 } 
+    const response = await client.callTool({
+      name: 'list_nodes',
+      arguments: { category: 'trigger', limit: 10 }
     });
-    
+
     expectValidMCPResponse(response);
     const result = JSON.parse(response.content[0].text);
     expect(result.nodes).toHaveLength(10);
@@ -403,65 +497,104 @@ describe('MCP Tool Invocation', () => {
 });
 ```
 
-### Database Integration Testing
+### Database Integration Testing (226 tests)
 
 ```typescript
 // tests/integration/database/fts5-search.test.ts
 describe('FTS5 Search Integration', () => {
   it('should perform fuzzy search', async () => {
     const results = await nodeRepo.searchNodes('HTT', 'FUZZY');
-    
+
     expect(results.some(n => n.nodeType.includes('httpRequest'))).toBe(true);
     expect(results.some(n => n.displayName.includes('HTTP'))).toBe(true);
   });
 
   it('should handle complex boolean queries', async () => {
     const results = await nodeRepo.searchNodes('webhook OR http', 'OR');
-    
+
     expect(results.length).toBeGreaterThan(0);
-    expect(results.some(n => 
-      n.description?.includes('webhook') || 
+    expect(results.some(n =>
+      n.description?.includes('webhook') ||
       n.description?.includes('http')
     )).toBe(true);
   });
 });
 ```
 
+### Template Integration Testing (35 tests)
+
+Tests template fetching, storage, and metadata operations against the n8n.io API and local database.
+
+### Docker Integration Testing (18 tests)
+
+Tests Docker configuration parsing, entrypoint script, and security validation.
+
 ## Test Distribution and Coverage
 
 ### Test Distribution by Component
 
-Based on our 1,182 tests:
+Based on our 3,336 tests:
 
-1. **Services Layer** (~450 tests)
+**Integration Tests (570 tests):**
+1. **n8n API Integration** (172 tests)
+   - Workflow management handlers: 11 tools with comprehensive scenarios
+   - Execution management handlers: 2 tools
+   - System tool handlers: 3 tools
+   - TypeScript type safety with response interfaces
+
+2. **Database Integration** (226 tests)
+   - Repository operations and transactions
+   - FTS5 full-text search with fuzzy matching
+   - Performance and concurrent access tests
+   - Template node configurations
+
+3. **MCP Protocol** (119 tests)
+   - Protocol compliance and session management
+   - Tool invocation and error handling
+   - Performance and stress testing
+   - Workflow error validation
+
+4. **Templates & Docker** (53 tests)
+   - Template fetching and metadata operations
+   - Docker configuration and security validation
+
+**Unit Tests (2,766 tests):**
+1. **Services Layer** (largest suite)
    - `workflow-validator-comprehensive.test.ts`: 150+ tests
-   - `node-specific-validators.test.ts`: 120+ tests
-   - `n8n-validation.test.ts`: 80+ tests
-   - `n8n-api-client.test.ts`: 60+ tests
+   - `enhanced-config-validator.test.ts`: 120+ tests
+   - `node-specific-validators.test.ts`: 100+ tests
+   - `n8n-api-client.test.ts`: 80+ tests
+   - Config validation, property filtering, workflow diff engine
 
 2. **Parsers** (~200 tests)
-   - `simple-parser.test.ts`: 80+ tests
-   - `property-extractor.test.ts`: 70+ tests
-   - `node-parser.test.ts`: 50+ tests
+   - Node parsing with version support
+   - Property extraction and documentation mapping
+   - Simple parser for basic node information
 
-3. **MCP Integration** (~150 tests)
-   - `tool-invocation.test.ts`: 50+ tests
-   - `error-handling.test.ts`: 40+ tests
-   - `session-management.test.ts`: 30+ tests
+3. **Database Layer** (~150 tests)
+   - Repository core functionality with mocks
+   - Database adapter unit tests
+   - Template repository operations
 
-4. **Database** (~300 tests)
-   - Unit tests for repositories: 100+ tests
-   - Integration tests for FTS5 search: 80+ tests
-   - Transaction tests: 60+ tests
-   - Performance tests: 60+ tests
+4. **MCP Tools & HTTP Server** (~300 tests)
+   - Tool definitions and documentation system
+   - Multi-tenant support and security
+   - Configuration validation
+
+5. **Utils, Docker, Scripts, Telemetry** (remaining tests)
+   - Cache utilities, database helpers
+   - Docker config security and parsing
+   - Template extraction scripts
+   - Telemetry tracking
 
 ### Test Execution Performance
 
 From our CI runs:
 - **Fastest tests**: Unit tests with mocks (<1ms each)
-- **Slowest tests**: Integration tests with real database (100-5000ms)
+- **Slowest tests**: Integration tests with real database and n8n API (100-5000ms)
 - **Average test time**: ~20ms per test
-- **Total suite execution**: Under 3 minutes in CI
+- **Total suite execution**: ~3 minutes in CI (with coverage)
+- **Parallel execution**: Configurable thread pool for optimal performance
 
 ## CI/CD Pipeline
 

docs/workflow-diff-examples.md

@@ -116,17 +116,46 @@ The `n8n_update_partial_workflow` tool allows you to make targeted changes to wo
 }
 ```
 
-#### Update Connection (Change routing)
+#### Rewire Connection
 ```json
 {
-  "type": "updateConnection",
+  "type": "rewireConnection",
+  "source": "Webhook",
+  "from": "Old Handler",
+  "to": "New Handler",
+  "description": "Rewire connection to new handler"
+}
+```
+
+#### Smart Parameters for IF Nodes
+```json
+{
+  "type": "addConnection",
   "source": "IF",
-  "target": "Send Email",
-  "changes": {
-    "sourceOutput": "false",  // Change from 'true' to 'false' output
-    "targetInput": "main"
-  },
-  "description": "Route failed conditions to email"
+  "target": "Success Handler",
+  "branch": "true",  // Semantic parameter instead of sourceIndex
+  "description": "Route true branch to success handler"
+}
+```
+
+```json
+{
+  "type": "addConnection",
+  "source": "IF",
+  "target": "Error Handler",
+  "branch": "false",  // Routes to false branch (sourceIndex=1)
+  "description": "Route false branch to error handler"
+}
+```
+
+#### Smart Parameters for Switch Nodes
+```json
+{
+  "type": "addConnection",
+  "source": "Switch",
+  "target": "Handler A",
+  "case": 0,  // First output
+  "description": "Route case 0 to Handler A"
 }
 ```
 
@@ -296,6 +325,193 @@ The `n8n_update_partial_workflow` tool allows you to make targeted changes to wo
 }
 ```
 
+### Example 5: Large Batch Workflow Refactoring
+Demonstrates handling many operations in a single request - no longer limited to 5 operations!
+
+```json
+{
+  "id": "workflow-batch",
+  "operations": [
+    // Add 10 processing nodes
+    {
+      "type": "addNode",
+      "node": {
+        "name": "Filter Active Users",
+        "type": "n8n-nodes-base.filter",
+        "position": [400, 200],
+        "parameters": { "conditions": { "boolean": [{ "value1": "={{$json.active}}", "value2": true }] } }
+      }
+    },
+    {
+      "type": "addNode",
+      "node": {
+        "name": "Transform User Data",
+        "type": "n8n-nodes-base.set",
+        "position": [600, 200],
+        "parameters": { "values": { "string": [{ "name": "formatted_name", "value": "={{$json.firstName}} {{$json.lastName}}" }] } }
+      }
+    },
+    {
+      "type": "addNode",
+      "node": {
+        "name": "Validate Email",
+        "type": "n8n-nodes-base.if",
+        "position": [800, 200],
+        "parameters": { "conditions": { "string": [{ "value1": "={{$json.email}}", "operation": "contains", "value2": "@" }] } }
+      }
+    },
+    {
+      "type": "addNode",
+      "node": {
+        "name": "Enrich with API",
+        "type": "n8n-nodes-base.httpRequest",
+        "position": [1000, 150],
+        "parameters": { "url": "https://api.example.com/enrich", "method": "POST" }
+      }
+    },
+    {
+      "type": "addNode",
+      "node": {
+        "name": "Log Invalid Emails",
+        "type": "n8n-nodes-base.code",
+        "position": [1000, 350],
+        "parameters": { "jsCode": "console.log('Invalid email:', $json.email);\nreturn $json;" }
+      }
+    },
+    {
+      "type": "addNode",
+      "node": {
+        "name": "Merge Results",
+        "type": "n8n-nodes-base.merge",
+        "position": [1200, 250]
+      }
+    },
+    {
+      "type": "addNode",
+      "node": {
+        "name": "Deduplicate",
+        "type": "n8n-nodes-base.removeDuplicates",
+        "position": [1400, 250],
+        "parameters": { "propertyName": "id" }
+      }
+    },
+    {
+      "type": "addNode",
+      "node": {
+        "name": "Sort by Date",
+        "type": "n8n-nodes-base.sort",
+        "position": [1600, 250],
+        "parameters": { "sortFieldsUi": { "sortField": [{ "fieldName": "created_at", "order": "descending" }] } }
+      }
+    },
+    {
+      "type": "addNode",
+      "node": {
+        "name": "Batch for DB",
+        "type": "n8n-nodes-base.splitInBatches",
+        "position": [1800, 250],
+        "parameters": { "batchSize": 100 }
+      }
+    },
+    {
+      "type": "addNode",
+      "node": {
+        "name": "Save to Database",
+        "type": "n8n-nodes-base.postgres",
+        "position": [2000, 250],
+        "parameters": { "operation": "insert", "table": "processed_users" }
+      }
+    },
+    // Connect all the nodes
+    {
+      "type": "addConnection",
+      "source": "Get Users",
+      "target": "Filter Active Users"
+    },
+    {
+      "type": "addConnection",
+      "source": "Filter Active Users",
+      "target": "Transform User Data"
+    },
+    {
+      "type": "addConnection",
+      "source": "Transform User Data",
+      "target": "Validate Email"
+    },
+    {
+      "type": "addConnection",
+      "source": "Validate Email",
+      "sourceOutput": "true",
+      "target": "Enrich with API"
+    },
+    {
+      "type": "addConnection",
+      "source": "Validate Email",
+      "sourceOutput": "false",
+      "target": "Log Invalid Emails"
+    },
+    {
+      "type": "addConnection",
+      "source": "Enrich with API",
+      "target": "Merge Results"
+    },
+    {
+      "type": "addConnection",
+      "source": "Log Invalid Emails",
+      "target": "Merge Results",
+      "targetInput": "input2"
+    },
+    {
+      "type": "addConnection",
+      "source": "Merge Results",
+      "target": "Deduplicate"
+    },
+    {
+      "type": "addConnection",
+      "source": "Deduplicate",
+      "target": "Sort by Date"
+    },
+    {
+      "type": "addConnection",
+      "source": "Sort by Date",
+      "target": "Batch for DB"
+    },
+    {
+      "type": "addConnection",
+      "source": "Batch for DB",
+      "target": "Save to Database"
+    },
+    // Update workflow metadata
+    {
+      "type": "updateName",
+      "name": "User Processing Pipeline v2"
+    },
+    {
+      "type": "updateSettings",
+      "settings": {
+        "executionOrder": "v1",
+        "timezone": "UTC",
+        "saveDataSuccessExecution": "all"
+      }
+    },
+    {
+      "type": "addTag",
+      "tag": "production"
+    },
+    {
+      "type": "addTag",
+      "tag": "user-processing"
+    },
+    {
+      "type": "addTag",
+      "tag": "v2"
+    }
+  ]
+}
+```
+
+This example shows 26 operations in a single request, creating a complete data processing pipeline with proper error handling, validation, and batch processing.
+
 ## Best Practices
 
 1. **Use Descriptive Names**: Always provide clear node names and descriptions for operations
@@ -390,13 +606,13 @@ The tool validates all operations before applying any changes. Common errors inc
 
 Always check the response for validation errors and adjust your operations accordingly.
 
-## Transactional Updates (v2.7.0+)
+## Transactional Updates
 
 The diff engine now supports transactional updates using a **two-pass processing** approach:
 
 ### How It Works
 
-1. **Operation Limit**: Maximum 5 operations per request to ensure reliability
+1. **No Operation Limit**: Process unlimited operations in a single request
 2. **Two-Pass Processing**:
    - **Pass 1**: All node operations (add, remove, update, move, enable, disable)
    - **Pass 2**: All other operations (connections, settings, metadata)
@@ -446,9 +662,9 @@ This allows you to add nodes and connect them in the same request:
 ### Benefits
 
 - **Order Independence**: You don't need to worry about operation order
-- **Atomic Updates**: All operations succeed or all fail
+- **Atomic Updates**: All operations succeed or all fail (unless continueOnError is enabled)
 - **Intuitive Usage**: Add complex workflow structures in one call
-- **Clear Limits**: 5 operations max keeps things simple and reliable
+- **No Hard Limits**: Process unlimited operations efficiently
 
 ### Example: Complete Workflow Addition
 
@@ -507,4 +723,4 @@ This allows you to add nodes and connect them in the same request:
 }
 ```
 
-All 5 operations will be processed correctly regardless of order!
+All operations will be processed correctly regardless of order!

package.json

@@ -1,6 +1,6 @@
 {
   "name": "n8n-mcp",
-  "version": "2.11.1",
+  "version": "2.16.3",
   "description": "Integration between n8n workflow automation and Model Context Protocol (MCP)",
   "main": "dist/index.js",
   "bin": {
@@ -31,12 +31,16 @@
     "test:watch": "vitest watch",
     "test:unit": "vitest run tests/unit",
     "test:integration": "vitest run --config vitest.config.integration.ts",
+    "test:integration:n8n": "vitest run tests/integration/n8n-api",
+    "test:cleanup:orphans": "tsx tests/integration/n8n-api/scripts/cleanup-orphans.ts",
     "test:e2e": "vitest run tests/e2e",
     "lint": "tsc --noEmit",
     "typecheck": "tsc --noEmit",
     "update:n8n": "node scripts/update-n8n-deps.js",
     "update:n8n:check": "node scripts/update-n8n-deps.js --dry-run",
     "fetch:templates": "node dist/scripts/fetch-templates.js",
+    "fetch:templates:update": "node dist/scripts/fetch-templates.js --update",
+    "fetch:templates:extract": "node dist/scripts/fetch-templates.js --extract-only",
     "fetch:templates:robust": "node dist/scripts/fetch-templates-robust.js",
     "prebuild:fts5": "npx tsx scripts/prebuild-fts5.ts",
     "test:templates": "node dist/scripts/test-templates.js",
@@ -128,12 +132,15 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.13.2",
-    "@n8n/n8n-nodes-langchain": "^1.109.1",
+    "@n8n/n8n-nodes-langchain": "^1.112.2",
+    "@supabase/supabase-js": "^2.57.4",
     "dotenv": "^16.5.0",
     "express": "^5.1.0",
-    "n8n": "^1.110.1",
-    "n8n-core": "^1.109.0",
-    "n8n-workflow": "^1.107.0",
+    "express-rate-limit": "^7.1.5",
+    "lru-cache": "^11.2.1",
+    "n8n": "^1.113.3",
+    "n8n-core": "^1.112.1",
+    "n8n-workflow": "^1.110.0",
     "openai": "^4.77.0",
     "sql.js": "^1.13.0",
     "uuid": "^10.0.0",
@@ -143,5 +150,8 @@
     "@rollup/rollup-darwin-arm64": "^4.50.0",
     "@rollup/rollup-linux-x64-gnu": "^4.50.0",
     "better-sqlite3": "^11.10.0"
+  },
+  "overrides": {
+    "pyodide": "0.26.4"
   }
 }

package.runtime.json

@@ -1,12 +1,15 @@
 {
   "name": "n8n-mcp-runtime",
-  "version": "2.10.9",
+  "version": "2.16.3",
   "description": "n8n MCP Server Runtime Dependencies Only",
   "private": true,
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.13.2",
+    "@supabase/supabase-js": "^2.57.4",
     "express": "^5.1.0",
+    "express-rate-limit": "^7.1.5",
     "dotenv": "^16.5.0",
+    "lru-cache": "^11.2.1",
     "sql.js": "^1.13.0",
     "uuid": "^10.0.0",
     "axios": "^1.7.7"

scripts/export-webhook-workflows.ts

@@ -0,0 +1,41 @@
+#!/usr/bin/env tsx
+
+/**
+ * Export Webhook Workflow JSONs
+ *
+ * Generates the 4 webhook workflow JSON files needed for integration testing.
+ * These workflows must be imported into n8n and activated manually.
+ */
+
+import { writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { exportAllWebhookWorkflows } from '../tests/integration/n8n-api/utils/webhook-workflows';
+
+const OUTPUT_DIR = join(process.cwd(), 'workflows-for-import');
+
+// Create output directory
+mkdirSync(OUTPUT_DIR, { recursive: true });
+
+// Generate all workflow JSONs
+const workflows = exportAllWebhookWorkflows();
+
+// Write each workflow to a separate file
+Object.entries(workflows).forEach(([method, workflow]) => {
+  const filename = `webhook-${method.toLowerCase()}.json`;
+  const filepath = join(OUTPUT_DIR, filename);
+
+  writeFileSync(filepath, JSON.stringify(workflow, null, 2), 'utf-8');
+
+  console.log(`✓ Generated: ${filename}`);
+});
+
+console.log(`\n✓ All workflow JSONs written to: ${OUTPUT_DIR}`);
+console.log('\nNext steps:');
+console.log('1. Import each JSON file into your n8n instance');
+console.log('2. Activate each workflow in the n8n UI');
+console.log('3. Copy the webhook URLs from each workflow (open workflow → Webhook node → copy URL)');
+console.log('4. Add them to your .env file:');
+console.log('   N8N_TEST_WEBHOOK_GET_URL=https://your-n8n.com/webhook/mcp-test-get');
+console.log('   N8N_TEST_WEBHOOK_POST_URL=https://your-n8n.com/webhook/mcp-test-post');
+console.log('   N8N_TEST_WEBHOOK_PUT_URL=https://your-n8n.com/webhook/mcp-test-put');
+console.log('   N8N_TEST_WEBHOOK_DELETE_URL=https://your-n8n.com/webhook/mcp-test-delete');

scripts/test-error-message-tracking.ts

@@ -0,0 +1,58 @@
+/**
+ * Test script to verify error message tracking is working
+ */
+
+import { telemetry } from '../src/telemetry';
+
+async function testErrorTracking() {
+  console.log('=== Testing Error Message Tracking ===\n');
+
+  // Track session first
+  console.log('1. Starting session...');
+  telemetry.trackSessionStart();
+
+  // Track an error WITH a message
+  console.log('\n2. Tracking error WITH message:');
+  const testErrorMessage = 'This is a test error message with sensitive data: password=secret123 and test@example.com';
+  telemetry.trackError(
+    'TypeError',
+    'tool_execution',
+    'test_tool',
+    testErrorMessage
+  );
+  console.log(`   Original message: "${testErrorMessage}"`);
+
+  // Track an error WITHOUT a message
+  console.log('\n3. Tracking error WITHOUT message:');
+  telemetry.trackError(
+    'Error',
+    'tool_execution',
+    'test_tool2'
+  );
+
+  // Check the event queue
+  const metrics = telemetry.getMetrics();
+  console.log('\n4. Telemetry metrics:');
+  console.log('   Status:', metrics.status);
+  console.log('   Events queued:', metrics.tracking.eventsQueued);
+
+  // Get raw event queue to inspect
+  const eventTracker = (telemetry as any).eventTracker;
+  const queue = eventTracker.getEventQueue();
+
+  console.log('\n5. Event queue contents:');
+  queue.forEach((event, i) => {
+    console.log(`\n   Event ${i + 1}:`);
+    console.log(`   - Type: ${event.event}`);
+    console.log(`   - Properties:`, JSON.stringify(event.properties, null, 6));
+  });
+
+  // Flush to database
+  console.log('\n6. Flushing to database...');
+  await telemetry.flush();
+
+  console.log('\n7. Done! Check Supabase for error events with "error" field.');
+  console.log('   Query: SELECT * FROM telemetry_events WHERE event = \'error_occurred\' ORDER BY created_at DESC LIMIT 5;');
+}
+
+testErrorTracking().catch(console.error);

scripts/test-error-output-validation.ts

@@ -0,0 +1,274 @@
+#!/usr/bin/env npx tsx
+
+/**
+ * Test script for error output validation improvements
+ * Tests both incorrect and correct error output configurations
+ */
+
+import { WorkflowValidator } from '../dist/services/workflow-validator.js';
+import { NodeRepository } from '../dist/database/node-repository.js';
+import { EnhancedConfigValidator } from '../dist/services/enhanced-config-validator.js';
+import { DatabaseAdapter } from '../dist/database/database-adapter.js';
+import { Logger } from '../dist/utils/logger.js';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const logger = new Logger({ prefix: '[TestErrorValidation]' });
+
+async function runTests() {
+  // Initialize database
+  const dbPath = path.join(__dirname, '..', 'data', 'n8n-nodes.db');
+  const adapter = new DatabaseAdapter();
+  adapter.initialize({
+    type: 'better-sqlite3',
+    filename: dbPath
+  });
+  const db = adapter.getDatabase();
+
+  const nodeRepository = new NodeRepository(db);
+  const validator = new WorkflowValidator(nodeRepository, EnhancedConfigValidator);
+
+  console.log('\n🧪 Testing Error Output Validation Improvements\n');
+  console.log('=' .repeat(60));
+
+  // Test 1: Incorrect configuration - multiple nodes in same array
+  console.log('\n📝 Test 1: INCORRECT - Multiple nodes in main[0]');
+  console.log('-'.repeat(40));
+
+  const incorrectWorkflow = {
+    nodes: [
+      {
+        id: '132ef0dc-87af-41de-a95d-cabe3a0a5342',
+        name: 'Validate Input',
+        type: 'n8n-nodes-base.set',
+        typeVersion: 3.4,
+        position: [-400, 64] as [number, number],
+        parameters: {}
+      },
+      {
+        id: '5dedf217-63f9-409f-b34e-7780b22e199a',
+        name: 'Filter URLs',
+        type: 'n8n-nodes-base.filter',
+        typeVersion: 2.2,
+        position: [-176, 64] as [number, number],
+        parameters: {}
+      },
+      {
+        id: '9d5407cc-ca5a-4966-b4b7-0e5dfbf54ad3',
+        name: 'Error Response1',
+        type: 'n8n-nodes-base.respondToWebhook',
+        typeVersion: 1.5,
+        position: [-160, 240] as [number, number],
+        parameters: {}
+      }
+    ],
+    connections: {
+      'Validate Input': {
+        main: [
+          [
+            { node: 'Filter URLs', type: 'main', index: 0 },
+            { node: 'Error Response1', type: 'main', index: 0 }  // WRONG!
+          ]
+        ]
+      }
+    }
+  };
+
+  const result1 = await validator.validateWorkflow(incorrectWorkflow);
+
+  if (result1.errors.length > 0) {
+    console.log('❌ ERROR DETECTED (as expected):');
+    const errorMessage = result1.errors.find(e =>
+      e.message.includes('Incorrect error output configuration')
+    );
+    if (errorMessage) {
+      console.log('\n' + errorMessage.message);
+    }
+  } else {
+    console.log('✅ No errors found (but should have detected the issue!)');
+  }
+
+  // Test 2: Correct configuration - separate arrays
+  console.log('\n📝 Test 2: CORRECT - Separate main[0] and main[1]');
+  console.log('-'.repeat(40));
+
+  const correctWorkflow = {
+    nodes: [
+      {
+        id: '132ef0dc-87af-41de-a95d-cabe3a0a5342',
+        name: 'Validate Input',
+        type: 'n8n-nodes-base.set',
+        typeVersion: 3.4,
+        position: [-400, 64] as [number, number],
+        parameters: {},
+        onError: 'continueErrorOutput' as const
+      },
+      {
+        id: '5dedf217-63f9-409f-b34e-7780b22e199a',
+        name: 'Filter URLs',
+        type: 'n8n-nodes-base.filter',
+        typeVersion: 2.2,
+        position: [-176, 64] as [number, number],
+        parameters: {}
+      },
+      {
+        id: '9d5407cc-ca5a-4966-b4b7-0e5dfbf54ad3',
+        name: 'Error Response1',
+        type: 'n8n-nodes-base.respondToWebhook',
+        typeVersion: 1.5,
+        position: [-160, 240] as [number, number],
+        parameters: {}
+      }
+    ],
+    connections: {
+      'Validate Input': {
+        main: [
+          [
+            { node: 'Filter URLs', type: 'main', index: 0 }
+          ],
+          [
+            { node: 'Error Response1', type: 'main', index: 0 }  // CORRECT!
+          ]
+        ]
+      }
+    }
+  };
+
+  const result2 = await validator.validateWorkflow(correctWorkflow);
+
+  const hasIncorrectError = result2.errors.some(e =>
+    e.message.includes('Incorrect error output configuration')
+  );
+
+  if (!hasIncorrectError) {
+    console.log('✅ No error output configuration issues (correct!)');
+  } else {
+    console.log('❌ Unexpected error found');
+  }
+
+  // Test 3: onError without error connections
+  console.log('\n📝 Test 3: onError without error connections');
+  console.log('-'.repeat(40));
+
+  const mismatchWorkflow = {
+    nodes: [
+      {
+        id: '1',
+        name: 'HTTP Request',
+        type: 'n8n-nodes-base.httpRequest',
+        typeVersion: 4,
+        position: [100, 100] as [number, number],
+        parameters: {},
+        onError: 'continueErrorOutput' as const
+      },
+      {
+        id: '2',
+        name: 'Process Data',
+        type: 'n8n-nodes-base.set',
+        typeVersion: 2,
+        position: [300, 100] as [number, number],
+        parameters: {}
+      }
+    ],
+    connections: {
+      'HTTP Request': {
+        main: [
+          [
+            { node: 'Process Data', type: 'main', index: 0 }
+          ]
+          // No main[1] for error output
+        ]
+      }
+    }
+  };
+
+  const result3 = await validator.validateWorkflow(mismatchWorkflow);
+
+  const mismatchError = result3.errors.find(e =>
+    e.message.includes("has onError: 'continueErrorOutput' but no error output connections")
+  );
+
+  if (mismatchError) {
+    console.log('❌ ERROR DETECTED (as expected):');
+    console.log(`Node: ${mismatchError.nodeName}`);
+    console.log(`Message: ${mismatchError.message}`);
+  } else {
+    console.log('✅ No mismatch detected (but should have!)');
+  }
+
+  // Test 4: Error connections without onError
+  console.log('\n📝 Test 4: Error connections without onError property');
+  console.log('-'.repeat(40));
+
+  const missingOnErrorWorkflow = {
+    nodes: [
+      {
+        id: '1',
+        name: 'HTTP Request',
+        type: 'n8n-nodes-base.httpRequest',
+        typeVersion: 4,
+        position: [100, 100] as [number, number],
+        parameters: {}
+        // Missing onError property
+      },
+      {
+        id: '2',
+        name: 'Process Data',
+        type: 'n8n-nodes-base.set',
+        position: [300, 100] as [number, number],
+        parameters: {}
+      },
+      {
+        id: '3',
+        name: 'Error Handler',
+        type: 'n8n-nodes-base.set',
+        position: [300, 300] as [number, number],
+        parameters: {}
+      }
+    ],
+    connections: {
+      'HTTP Request': {
+        main: [
+          [
+            { node: 'Process Data', type: 'main', index: 0 }
+          ],
+          [
+            { node: 'Error Handler', type: 'main', index: 0 }
+          ]
+        ]
+      }
+    }
+  };
+
+  const result4 = await validator.validateWorkflow(missingOnErrorWorkflow);
+
+  const missingOnErrorWarning = result4.warnings.find(w =>
+    w.message.includes('error output connections in main[1] but missing onError')
+  );
+
+  if (missingOnErrorWarning) {
+    console.log('⚠️  WARNING DETECTED (as expected):');
+    console.log(`Node: ${missingOnErrorWarning.nodeName}`);
+    console.log(`Message: ${missingOnErrorWarning.message}`);
+  } else {
+    console.log('✅ No warning (but should have warned!)');
+  }
+
+  console.log('\n' + '='.repeat(60));
+  console.log('\n📊 Summary:');
+  console.log('- Error output validation is working correctly');
+  console.log('- Detects incorrect configurations (multiple nodes in main[0])');
+  console.log('- Validates onError property matches connections');
+  console.log('- Provides clear error messages with fix examples');
+
+  // Close database
+  adapter.close();
+}
+
+runTests().catch(error => {
+  console.error('Test failed:', error);
+  process.exit(1);
+});

scripts/test-error-validation.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+
+/**
+ * Test script for error output validation improvements
+ */
+
+const { WorkflowValidator } = require('../dist/services/workflow-validator.js');
+const { NodeRepository } = require('../dist/database/node-repository.js');
+const { EnhancedConfigValidator } = require('../dist/services/enhanced-config-validator.js');
+const Database = require('better-sqlite3');
+const path = require('path');
+
+async function runTests() {
+  // Initialize database
+  const dbPath = path.join(__dirname, '..', 'data', 'nodes.db');
+  const db = new Database(dbPath, { readonly: true });
+
+  const nodeRepository = new NodeRepository(db);
+  const validator = new WorkflowValidator(nodeRepository, EnhancedConfigValidator);
+
+  console.log('\n🧪 Testing Error Output Validation Improvements\n');
+  console.log('=' .repeat(60));
+
+  // Test 1: Incorrect configuration - multiple nodes in same array
+  console.log('\n📝 Test 1: INCORRECT - Multiple nodes in main[0]');
+  console.log('-'.repeat(40));
+
+  const incorrectWorkflow = {
+    nodes: [
+      {
+        id: '132ef0dc-87af-41de-a95d-cabe3a0a5342',
+        name: 'Validate Input',
+        type: 'n8n-nodes-base.set',
+        typeVersion: 3.4,
+        position: [-400, 64],
+        parameters: {}
+      },
+      {
+        id: '5dedf217-63f9-409f-b34e-7780b22e199a',
+        name: 'Filter URLs',
+        type: 'n8n-nodes-base.filter',
+        typeVersion: 2.2,
+        position: [-176, 64],
+        parameters: {}
+      },
+      {
+        id: '9d5407cc-ca5a-4966-b4b7-0e5dfbf54ad3',
+        name: 'Error Response1',
+        type: 'n8n-nodes-base.respondToWebhook',
+        typeVersion: 1.5,
+        position: [-160, 240],
+        parameters: {}
+      }
+    ],
+    connections: {
+      'Validate Input': {
+        main: [
+          [
+            { node: 'Filter URLs', type: 'main', index: 0 },
+            { node: 'Error Response1', type: 'main', index: 0 }  // WRONG!
+          ]
+        ]
+      }
+    }
+  };
+
+  const result1 = await validator.validateWorkflow(incorrectWorkflow);
+
+  if (result1.errors.length > 0) {
+    console.log('❌ ERROR DETECTED (as expected):');
+    const errorMessage = result1.errors.find(e =>
+      e.message.includes('Incorrect error output configuration')
+    );
+    if (errorMessage) {
+      console.log('\nError Summary:');
+      console.log(`Node: ${errorMessage.nodeName || 'Validate Input'}`);
+      console.log('\nFull Error Message:');
+      console.log(errorMessage.message);
+    } else {
+      console.log('Other errors found:', result1.errors.map(e => e.message));
+    }
+  } else {
+    console.log('⚠️  No errors found - validation may not be working correctly');
+  }
+
+  // Test 2: Correct configuration - separate arrays
+  console.log('\n📝 Test 2: CORRECT - Separate main[0] and main[1]');
+  console.log('-'.repeat(40));
+
+  const correctWorkflow = {
+    nodes: [
+      {
+        id: '132ef0dc-87af-41de-a95d-cabe3a0a5342',
+        name: 'Validate Input',
+        type: 'n8n-nodes-base.set',
+        typeVersion: 3.4,
+        position: [-400, 64],
+        parameters: {},
+        onError: 'continueErrorOutput'
+      },
+      {
+        id: '5dedf217-63f9-409f-b34e-7780b22e199a',
+        name: 'Filter URLs',
+        type: 'n8n-nodes-base.filter',
+        typeVersion: 2.2,
+        position: [-176, 64],
+        parameters: {}
+      },
+      {
+        id: '9d5407cc-ca5a-4966-b4b7-0e5dfbf54ad3',
+        name: 'Error Response1',
+        type: 'n8n-nodes-base.respondToWebhook',
+        typeVersion: 1.5,
+        position: [-160, 240],
+        parameters: {}
+      }
+    ],
+    connections: {
+      'Validate Input': {
+        main: [
+          [
+            { node: 'Filter URLs', type: 'main', index: 0 }
+          ],
+          [
+            { node: 'Error Response1', type: 'main', index: 0 }  // CORRECT!
+          ]
+        ]
+      }
+    }
+  };
+
+  const result2 = await validator.validateWorkflow(correctWorkflow);
+
+  const hasIncorrectError = result2.errors.some(e =>
+    e.message.includes('Incorrect error output configuration')
+  );
+
+  if (!hasIncorrectError) {
+    console.log('✅ No error output configuration issues (correct!)');
+  } else {
+    console.log('❌ Unexpected error found');
+  }
+
+  console.log('\n' + '='.repeat(60));
+  console.log('\n✨ Error output validation is working correctly!');
+  console.log('The validator now properly detects:');
+  console.log('  1. Multiple nodes incorrectly placed in main[0]');
+  console.log('  2. Provides clear JSON examples for fixing issues');
+  console.log('  3. Validates onError property matches connections');
+
+  // Close database
+  db.close();
+}
+
+runTests().catch(error => {
+  console.error('Test failed:', error);
+  process.exit(1);
+});

scripts/test-expression-format-validation.js

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+
+/**
+ * Test script for expression format validation
+ * Tests the validation of expression prefixes and resource locator formats
+ */
+
+const { WorkflowValidator } = require('../dist/services/workflow-validator.js');
+const { NodeRepository } = require('../dist/database/node-repository.js');
+const { EnhancedConfigValidator } = require('../dist/services/enhanced-config-validator.js');
+const { createDatabaseAdapter } = require('../dist/database/database-adapter.js');
+const path = require('path');
+
+async function runTests() {
+  // Initialize database
+  const dbPath = path.join(__dirname, '..', 'data', 'nodes.db');
+  const adapter = await createDatabaseAdapter(dbPath);
+  const db = adapter;
+
+  const nodeRepository = new NodeRepository(db);
+  const validator = new WorkflowValidator(nodeRepository, EnhancedConfigValidator);
+
+  console.log('\n🧪 Testing Expression Format Validation\n');
+  console.log('=' .repeat(60));
+
+  // Test 1: Email node with missing = prefix
+  console.log('\n📝 Test 1: Email Send node - Missing = prefix');
+  console.log('-'.repeat(40));
+
+  const emailWorkflowIncorrect = {
+    nodes: [
+      {
+        id: 'b9dd1cfd-ee66-4049-97e7-1af6d976a4e0',
+        name: 'Error Handler',
+        type: 'n8n-nodes-base.emailSend',
+        typeVersion: 2.1,
+        position: [-128, 400],
+        parameters: {
+          fromEmail: '{{ $env.ADMIN_EMAIL }}',  // INCORRECT - missing =
+          toEmail: 'admin@company.com',
+          subject: 'GitHub Issue Workflow Error - HIGH PRIORITY',
+          options: {}
+        },
+        credentials: {
+          smtp: {
+            id: '7AQ08VMFHubmfvzR',
+            name: 'romuald@aiadvisors.pl'
+          }
+        }
+      }
+    ],
+    connections: {}
+  };
+
+  const result1 = await validator.validateWorkflow(emailWorkflowIncorrect);
+
+  if (result1.errors.some(e => e.message.includes('Expression format'))) {
+    console.log('✅ ERROR DETECTED (correct behavior):');
+    const formatError = result1.errors.find(e => e.message.includes('Expression format'));
+    console.log('\n' + formatError.message);
+  } else {
+    console.log('❌ No expression format error detected (should have detected missing prefix)');
+  }
+
+  // Test 2: Email node with correct = prefix
+  console.log('\n📝 Test 2: Email Send node - Correct = prefix');
+  console.log('-'.repeat(40));
+
+  const emailWorkflowCorrect = {
+    nodes: [
+      {
+        id: 'b9dd1cfd-ee66-4049-97e7-1af6d976a4e0',
+        name: 'Error Handler',
+        type: 'n8n-nodes-base.emailSend',
+        typeVersion: 2.1,
+        position: [-128, 400],
+        parameters: {
+          fromEmail: '={{ $env.ADMIN_EMAIL }}',  // CORRECT - has =
+          toEmail: 'admin@company.com',
+          subject: 'GitHub Issue Workflow Error - HIGH PRIORITY',
+          options: {}
+        }
+      }
+    ],
+    connections: {}
+  };
+
+  const result2 = await validator.validateWorkflow(emailWorkflowCorrect);
+
+  if (result2.errors.some(e => e.message.includes('Expression format'))) {
+    console.log('❌ Unexpected expression format error (should accept = prefix)');
+  } else {
+    console.log('✅ No expression format errors (correct!)');
+  }
+
+  // Test 3: GitHub node without resource locator format
+  console.log('\n📝 Test 3: GitHub node - Missing resource locator format');
+  console.log('-'.repeat(40));
+
+  const githubWorkflowIncorrect = {
+    nodes: [
+      {
+        id: '3c742ca1-af8f-4d80-a47e-e68fb1ced491',
+        name: 'Send Welcome Comment',
+        type: 'n8n-nodes-base.github',
+        typeVersion: 1.1,
+        position: [-240, 96],
+        parameters: {
+          operation: 'createComment',
+          owner: '{{ $vars.GITHUB_OWNER }}',  // INCORRECT - needs RL format
+          repository: '{{ $vars.GITHUB_REPO }}',  // INCORRECT - needs RL format
+          issueNumber: null,
+          body: '👋 Hi @{{ $(\'Extract Issue Data\').first().json.author }}!'  // INCORRECT - missing =
+        },
+        credentials: {
+          githubApi: {
+            id: 'edgpwh6ldYN07MXx',
+            name: 'GitHub account'
+          }
+        }
+      }
+    ],
+    connections: {}
+  };
+
+  const result3 = await validator.validateWorkflow(githubWorkflowIncorrect);
+
+  const formatErrors = result3.errors.filter(e => e.message.includes('Expression format'));
+  console.log(`\nFound ${formatErrors.length} expression format errors:`);
+
+  if (formatErrors.length >= 3) {
+    console.log('✅ All format issues detected:');
+    formatErrors.forEach((error, index) => {
+      const field = error.message.match(/Field '([^']+)'/)?.[1] || 'unknown';
+      console.log(`  ${index + 1}. Field '${field}' - ${error.message.includes('resource locator') ? 'Needs RL format' : 'Missing = prefix'}`);
+    });
+  } else {
+    console.log('❌ Not all format issues detected');
+  }
+
+  // Test 4: GitHub node with correct resource locator format
+  console.log('\n📝 Test 4: GitHub node - Correct resource locator format');
+  console.log('-'.repeat(40));
+
+  const githubWorkflowCorrect = {
+    nodes: [
+      {
+        id: '3c742ca1-af8f-4d80-a47e-e68fb1ced491',
+        name: 'Send Welcome Comment',
+        type: 'n8n-nodes-base.github',
+        typeVersion: 1.1,
+        position: [-240, 96],
+        parameters: {
+          operation: 'createComment',
+          owner: {
+            __rl: true,
+            value: '={{ $vars.GITHUB_OWNER }}',  // CORRECT - RL format with =
+            mode: 'expression'
+          },
+          repository: {
+            __rl: true,
+            value: '={{ $vars.GITHUB_REPO }}',  // CORRECT - RL format with =
+            mode: 'expression'
+          },
+          issueNumber: 123,
+          body: '=👋 Hi @{{ $(\'Extract Issue Data\').first().json.author }}!'  // CORRECT - has =
+        }
+      }
+    ],
+    connections: {}
+  };
+
+  const result4 = await validator.validateWorkflow(githubWorkflowCorrect);
+
+  const formatErrors4 = result4.errors.filter(e => e.message.includes('Expression format'));
+  if (formatErrors4.length === 0) {
+    console.log('✅ No expression format errors (correct!)');
+  } else {
+    console.log(`❌ Unexpected expression format errors: ${formatErrors4.length}`);
+    formatErrors4.forEach(e => console.log('  - ' + e.message.split('\n')[0]));
+  }
+
+  // Test 5: Mixed content expressions
+  console.log('\n📝 Test 5: Mixed content with expressions');
+  console.log('-'.repeat(40));
+
+  const mixedContentWorkflow = {
+    nodes: [
+      {
+        id: '1',
+        name: 'HTTP Request',
+        type: 'n8n-nodes-base.httpRequest',
+        typeVersion: 4,
+        position: [0, 0],
+        parameters: {
+          url: 'https://api.example.com/users/{{ $json.userId }}',  // INCORRECT
+          headers: {
+            'Authorization': '=Bearer {{ $env.API_TOKEN }}'  // CORRECT
+          }
+        }
+      }
+    ],
+    connections: {}
+  };
+
+  const result5 = await validator.validateWorkflow(mixedContentWorkflow);
+
+  const urlError = result5.errors.find(e => e.message.includes('url') && e.message.includes('Expression format'));
+  if (urlError) {
+    console.log('✅ Mixed content error detected for URL field');
+    console.log('  Should be: "=https://api.example.com/users/{{ $json.userId }}"');
+  } else {
+    console.log('❌ Mixed content error not detected');
+  }
+
+  console.log('\n' + '='.repeat(60));
+  console.log('\n✨ Expression Format Validation Summary:');
+  console.log('  - Detects missing = prefix in expressions');
+  console.log('  - Identifies fields needing resource locator format');
+  console.log('  - Provides clear correction examples');
+  console.log('  - Handles mixed literal and expression content');
+
+  // Close database
+  db.close();
+}
+
+runTests().catch(error => {
+  console.error('Test failed:', error);
+  process.exit(1);
+});

scripts/test-multi-tenant-simple.ts

@@ -0,0 +1,126 @@
+#!/usr/bin/env ts-node
+
+/**
+ * Simple test for multi-tenant functionality
+ * Tests that tools are registered correctly based on configuration
+ */
+
+import { isN8nApiConfigured } from '../src/config/n8n-api';
+import { InstanceContext } from '../src/types/instance-context';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+async function testMultiTenant() {
+  console.log('🧪 Testing Multi-Tenant Tool Registration\n');
+  console.log('=' .repeat(60));
+
+  // Save original environment
+  const originalEnv = {
+    ENABLE_MULTI_TENANT: process.env.ENABLE_MULTI_TENANT,
+    N8N_API_URL: process.env.N8N_API_URL,
+    N8N_API_KEY: process.env.N8N_API_KEY
+  };
+
+  try {
+    // Test 1: Default - no API config
+    console.log('\n✅ Test 1: No API configuration');
+    delete process.env.N8N_API_URL;
+    delete process.env.N8N_API_KEY;
+    delete process.env.ENABLE_MULTI_TENANT;
+
+    const hasConfig1 = isN8nApiConfigured();
+    console.log(`  Environment API configured: ${hasConfig1}`);
+    console.log(`  Multi-tenant enabled: ${process.env.ENABLE_MULTI_TENANT === 'true'}`);
+    console.log(`  Should show tools: ${hasConfig1 || process.env.ENABLE_MULTI_TENANT === 'true'}`);
+
+    // Test 2: Multi-tenant enabled
+    console.log('\n✅ Test 2: Multi-tenant enabled (no env API)');
+    process.env.ENABLE_MULTI_TENANT = 'true';
+
+    const hasConfig2 = isN8nApiConfigured();
+    console.log(`  Environment API configured: ${hasConfig2}`);
+    console.log(`  Multi-tenant enabled: ${process.env.ENABLE_MULTI_TENANT === 'true'}`);
+    console.log(`  Should show tools: ${hasConfig2 || process.env.ENABLE_MULTI_TENANT === 'true'}`);
+
+    // Test 3: Environment variables set
+    console.log('\n✅ Test 3: Environment variables set');
+    process.env.ENABLE_MULTI_TENANT = 'false';
+    process.env.N8N_API_URL = 'https://test.n8n.cloud';
+    process.env.N8N_API_KEY = 'test-key';
+
+    const hasConfig3 = isN8nApiConfigured();
+    console.log(`  Environment API configured: ${hasConfig3}`);
+    console.log(`  Multi-tenant enabled: ${process.env.ENABLE_MULTI_TENANT === 'true'}`);
+    console.log(`  Should show tools: ${hasConfig3 || process.env.ENABLE_MULTI_TENANT === 'true'}`);
+
+    // Test 4: Instance context simulation
+    console.log('\n✅ Test 4: Instance context (simulated)');
+    const instanceContext: InstanceContext = {
+      n8nApiUrl: 'https://instance.n8n.cloud',
+      n8nApiKey: 'instance-key',
+      instanceId: 'test-instance'
+    };
+
+    const hasInstanceConfig = !!(instanceContext.n8nApiUrl && instanceContext.n8nApiKey);
+    console.log(`  Instance has API config: ${hasInstanceConfig}`);
+    console.log(`  Environment API configured: ${hasConfig3}`);
+    console.log(`  Multi-tenant enabled: ${process.env.ENABLE_MULTI_TENANT === 'true'}`);
+    console.log(`  Should show tools: ${hasConfig3 || hasInstanceConfig || process.env.ENABLE_MULTI_TENANT === 'true'}`);
+
+    // Test 5: Multi-tenant with instance strategy
+    console.log('\n✅ Test 5: Multi-tenant with instance strategy');
+    process.env.ENABLE_MULTI_TENANT = 'true';
+    process.env.MULTI_TENANT_SESSION_STRATEGY = 'instance';
+    delete process.env.N8N_API_URL;
+    delete process.env.N8N_API_KEY;
+
+    const hasConfig5 = isN8nApiConfigured();
+    const sessionStrategy = process.env.MULTI_TENANT_SESSION_STRATEGY || 'instance';
+    console.log(`  Environment API configured: ${hasConfig5}`);
+    console.log(`  Multi-tenant enabled: ${process.env.ENABLE_MULTI_TENANT === 'true'}`);
+    console.log(`  Session strategy: ${sessionStrategy}`);
+    console.log(`  Should show tools: ${hasConfig5 || process.env.ENABLE_MULTI_TENANT === 'true'}`);
+
+    if (instanceContext.instanceId) {
+      const sessionId = `instance-${instanceContext.instanceId}-uuid`;
+      console.log(`  Session ID format: ${sessionId}`);
+    }
+
+    console.log('\n' + '=' .repeat(60));
+    console.log('✅ All configuration tests passed!');
+    console.log('\n📝 Summary:');
+    console.log('  - Tools are shown when: env API configured OR multi-tenant enabled OR instance context provided');
+    console.log('  - Session isolation works with instance-based session IDs in multi-tenant mode');
+    console.log('  - Backward compatibility maintained for env-based configuration');
+
+  } catch (error) {
+    console.error('\n❌ Test failed:', error);
+    process.exit(1);
+  } finally {
+    // Restore original environment
+    if (originalEnv.ENABLE_MULTI_TENANT !== undefined) {
+      process.env.ENABLE_MULTI_TENANT = originalEnv.ENABLE_MULTI_TENANT;
+    } else {
+      delete process.env.ENABLE_MULTI_TENANT;
+    }
+
+    if (originalEnv.N8N_API_URL !== undefined) {
+      process.env.N8N_API_URL = originalEnv.N8N_API_URL;
+    } else {
+      delete process.env.N8N_API_URL;
+    }
+
+    if (originalEnv.N8N_API_KEY !== undefined) {
+      process.env.N8N_API_KEY = originalEnv.N8N_API_KEY;
+    } else {
+      delete process.env.N8N_API_KEY;
+    }
+  }
+}
+
+// Run tests
+testMultiTenant().catch(error => {
+  console.error('Test execution failed:', error);
+  process.exit(1);
+});

scripts/test-multi-tenant.ts

@@ -0,0 +1,136 @@
+#!/usr/bin/env ts-node
+
+/**
+ * Test script for multi-tenant functionality
+ * Verifies that instance context from headers enables n8n API tools
+ */
+
+import { N8NDocumentationMCPServer } from '../src/mcp/server';
+import { InstanceContext } from '../src/types/instance-context';
+import { logger } from '../src/utils/logger';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+async function testMultiTenant() {
+  console.log('🧪 Testing Multi-Tenant Functionality\n');
+  console.log('=' .repeat(60));
+
+  // Save original environment
+  const originalEnv = {
+    ENABLE_MULTI_TENANT: process.env.ENABLE_MULTI_TENANT,
+    N8N_API_URL: process.env.N8N_API_URL,
+    N8N_API_KEY: process.env.N8N_API_KEY
+  };
+
+  // Wait a moment for database initialization
+  await new Promise(resolve => setTimeout(resolve, 100));
+
+  try {
+    // Test 1: Without multi-tenant mode (default)
+    console.log('\n📌 Test 1: Without multi-tenant mode (no env vars)');
+    delete process.env.N8N_API_URL;
+    delete process.env.N8N_API_KEY;
+    process.env.ENABLE_MULTI_TENANT = 'false';
+
+    const server1 = new N8NDocumentationMCPServer();
+    const tools1 = await getToolsFromServer(server1);
+    const hasManagementTools1 = tools1.some(t => t.name.startsWith('n8n_'));
+    console.log(`  Tools available: ${tools1.length}`);
+    console.log(`  Has management tools: ${hasManagementTools1}`);
+    console.log(`  ✅ Expected: No management tools (correct: ${!hasManagementTools1})`);
+
+    // Test 2: With instance context but multi-tenant disabled
+    console.log('\n📌 Test 2: With instance context but multi-tenant disabled');
+    const instanceContext: InstanceContext = {
+      n8nApiUrl: 'https://instance1.n8n.cloud',
+      n8nApiKey: 'test-api-key',
+      instanceId: 'instance-1'
+    };
+
+    const server2 = new N8NDocumentationMCPServer(instanceContext);
+    const tools2 = await getToolsFromServer(server2);
+    const hasManagementTools2 = tools2.some(t => t.name.startsWith('n8n_'));
+    console.log(`  Tools available: ${tools2.length}`);
+    console.log(`  Has management tools: ${hasManagementTools2}`);
+    console.log(`  ✅ Expected: Has management tools (correct: ${hasManagementTools2})`);
+
+    // Test 3: With multi-tenant mode enabled
+    console.log('\n📌 Test 3: With multi-tenant mode enabled');
+    process.env.ENABLE_MULTI_TENANT = 'true';
+
+    const server3 = new N8NDocumentationMCPServer();
+    const tools3 = await getToolsFromServer(server3);
+    const hasManagementTools3 = tools3.some(t => t.name.startsWith('n8n_'));
+    console.log(`  Tools available: ${tools3.length}`);
+    console.log(`  Has management tools: ${hasManagementTools3}`);
+    console.log(`  ✅ Expected: Has management tools (correct: ${hasManagementTools3})`);
+
+    // Test 4: Multi-tenant with instance context
+    console.log('\n📌 Test 4: Multi-tenant with instance context');
+    const server4 = new N8NDocumentationMCPServer(instanceContext);
+    const tools4 = await getToolsFromServer(server4);
+    const hasManagementTools4 = tools4.some(t => t.name.startsWith('n8n_'));
+    console.log(`  Tools available: ${tools4.length}`);
+    console.log(`  Has management tools: ${hasManagementTools4}`);
+    console.log(`  ✅ Expected: Has management tools (correct: ${hasManagementTools4})`);
+
+    // Test 5: Environment variables (backward compatibility)
+    console.log('\n📌 Test 5: Environment variables (backward compatibility)');
+    process.env.ENABLE_MULTI_TENANT = 'false';
+    process.env.N8N_API_URL = 'https://env.n8n.cloud';
+    process.env.N8N_API_KEY = 'env-api-key';
+
+    const server5 = new N8NDocumentationMCPServer();
+    const tools5 = await getToolsFromServer(server5);
+    const hasManagementTools5 = tools5.some(t => t.name.startsWith('n8n_'));
+    console.log(`  Tools available: ${tools5.length}`);
+    console.log(`  Has management tools: ${hasManagementTools5}`);
+    console.log(`  ✅ Expected: Has management tools (correct: ${hasManagementTools5})`);
+
+    console.log('\n' + '=' .repeat(60));
+    console.log('✅ All multi-tenant tests passed!');
+
+  } catch (error) {
+    console.error('\n❌ Test failed:', error);
+    process.exit(1);
+  } finally {
+    // Restore original environment
+    Object.assign(process.env, originalEnv);
+  }
+}
+
+// Helper function to get tools from server
+async function getToolsFromServer(server: N8NDocumentationMCPServer): Promise<any[]> {
+  // Access the private server instance to simulate tool listing
+  const serverInstance = (server as any).server;
+  const handlers = (serverInstance as any)._requestHandlers;
+
+  // Find and call the ListToolsRequestSchema handler
+  if (handlers && handlers.size > 0) {
+    for (const [schema, handler] of handlers) {
+      // Check for the tools/list schema
+      if (schema && schema.method === 'tools/list') {
+        const result = await handler({ params: {} });
+        return result.tools || [];
+      }
+    }
+  }
+
+  // Fallback: directly check the handlers map
+  const ListToolsRequestSchema = { method: 'tools/list' };
+  const handler = handlers?.get(ListToolsRequestSchema);
+  if (handler) {
+    const result = await handler({ params: {} });
+    return result.tools || [];
+  }
+
+  console.log('  ⚠️  Warning: Could not find tools/list handler');
+  return [];
+}
+
+// Run tests
+testMultiTenant().catch(error => {
+  console.error('Test execution failed:', error);
+  process.exit(1);
+});

scripts/test-operation-validation.ts

@@ -0,0 +1,178 @@
+/**
+ * Test script for operation and resource validation with Google Drive example
+ */
+
+import { DatabaseAdapter } from '../src/database/database-adapter';
+import { NodeRepository } from '../src/database/node-repository';
+import { EnhancedConfigValidator } from '../src/services/enhanced-config-validator';
+import { WorkflowValidator } from '../src/services/workflow-validator';
+import { createDatabaseAdapter } from '../src/database/database-adapter';
+import { logger } from '../src/utils/logger';
+import chalk from 'chalk';
+
+async function testOperationValidation() {
+  console.log(chalk.blue('Testing Operation and Resource Validation'));
+  console.log('='.repeat(60));
+
+  // Initialize database
+  const dbPath = process.env.NODE_DB_PATH || 'data/nodes.db';
+  const db = await createDatabaseAdapter(dbPath);
+  const repository = new NodeRepository(db);
+
+  // Initialize similarity services
+  EnhancedConfigValidator.initializeSimilarityServices(repository);
+
+  // Test 1: Invalid operation "listFiles"
+  console.log(chalk.yellow('\n📝 Test 1: Google Drive with invalid operation "listFiles"'));
+  const invalidConfig = {
+    resource: 'fileFolder',
+    operation: 'listFiles'
+  };
+
+  const node = repository.getNode('nodes-base.googleDrive');
+  if (!node) {
+    console.error(chalk.red('Google Drive node not found in database'));
+    process.exit(1);
+  }
+
+  const result1 = EnhancedConfigValidator.validateWithMode(
+    'nodes-base.googleDrive',
+    invalidConfig,
+    node.properties,
+    'operation',
+    'ai-friendly'
+  );
+
+  console.log(`Valid: ${result1.valid ? chalk.green('✓') : chalk.red('✗')}`);
+  if (result1.errors.length > 0) {
+    console.log(chalk.red('Errors:'));
+    result1.errors.forEach(error => {
+      console.log(`  - ${error.property}: ${error.message}`);
+      if (error.fix) {
+        console.log(chalk.cyan(`    Fix: ${error.fix}`));
+      }
+    });
+  }
+
+  // Test 2: Invalid resource "files" (should be singular)
+  console.log(chalk.yellow('\n📝 Test 2: Google Drive with invalid resource "files"'));
+  const pluralResourceConfig = {
+    resource: 'files',
+    operation: 'download'
+  };
+
+  const result2 = EnhancedConfigValidator.validateWithMode(
+    'nodes-base.googleDrive',
+    pluralResourceConfig,
+    node.properties,
+    'operation',
+    'ai-friendly'
+  );
+
+  console.log(`Valid: ${result2.valid ? chalk.green('✓') : chalk.red('✗')}`);
+  if (result2.errors.length > 0) {
+    console.log(chalk.red('Errors:'));
+    result2.errors.forEach(error => {
+      console.log(`  - ${error.property}: ${error.message}`);
+      if (error.fix) {
+        console.log(chalk.cyan(`    Fix: ${error.fix}`));
+      }
+    });
+  }
+
+  // Test 3: Valid configuration
+  console.log(chalk.yellow('\n📝 Test 3: Google Drive with valid configuration'));
+  const validConfig = {
+    resource: 'file',
+    operation: 'download'
+  };
+
+  const result3 = EnhancedConfigValidator.validateWithMode(
+    'nodes-base.googleDrive',
+    validConfig,
+    node.properties,
+    'operation',
+    'ai-friendly'
+  );
+
+  console.log(`Valid: ${result3.valid ? chalk.green('✓') : chalk.red('✗')}`);
+  if (result3.errors.length > 0) {
+    console.log(chalk.red('Errors:'));
+    result3.errors.forEach(error => {
+      console.log(`  - ${error.property}: ${error.message}`);
+    });
+  } else {
+    console.log(chalk.green('No errors - configuration is valid!'));
+  }
+
+  // Test 4: Test in workflow context
+  console.log(chalk.yellow('\n📝 Test 4: Full workflow with invalid Google Drive node'));
+  const workflow = {
+    name: 'Test Workflow',
+    nodes: [
+      {
+        id: '1',
+        name: 'Google Drive',
+        type: 'n8n-nodes-base.googleDrive',
+        position: [100, 100] as [number, number],
+        parameters: {
+          resource: 'fileFolder',
+          operation: 'listFiles' // Invalid operation
+        }
+      }
+    ],
+    connections: {}
+  };
+
+  const validator = new WorkflowValidator(repository, EnhancedConfigValidator);
+  const workflowResult = await validator.validateWorkflow(workflow, {
+    validateNodes: true,
+    profile: 'ai-friendly'
+  });
+
+  console.log(`Workflow Valid: ${workflowResult.valid ? chalk.green('✓') : chalk.red('✗')}`);
+  if (workflowResult.errors.length > 0) {
+    console.log(chalk.red('Errors:'));
+    workflowResult.errors.forEach(error => {
+      console.log(`  - ${error.nodeName || 'Workflow'}: ${error.message}`);
+      if (error.details?.fix) {
+        console.log(chalk.cyan(`    Fix: ${error.details.fix}`));
+      }
+    });
+  }
+
+  // Test 5: Typo in operation
+  console.log(chalk.yellow('\n📝 Test 5: Typo in operation "downlod"'));
+  const typoConfig = {
+    resource: 'file',
+    operation: 'downlod' // Typo
+  };
+
+  const result5 = EnhancedConfigValidator.validateWithMode(
+    'nodes-base.googleDrive',
+    typoConfig,
+    node.properties,
+    'operation',
+    'ai-friendly'
+  );
+
+  console.log(`Valid: ${result5.valid ? chalk.green('✓') : chalk.red('✗')}`);
+  if (result5.errors.length > 0) {
+    console.log(chalk.red('Errors:'));
+    result5.errors.forEach(error => {
+      console.log(`  - ${error.property}: ${error.message}`);
+      if (error.fix) {
+        console.log(chalk.cyan(`    Fix: ${error.fix}`));
+      }
+    });
+  }
+
+  console.log(chalk.green('\n✅ All tests completed!'));
+  db.close();
+}
+
+// Run tests
+testOperationValidation().catch(error => {
+  console.error(chalk.red('Error running tests:'), error);
+  process.exit(1);
+});

scripts/test-telemetry-debug.ts

@@ -0,0 +1,118 @@
+#!/usr/bin/env npx tsx
+/**
+ * Debug script for telemetry integration
+ * Tests direct Supabase connection
+ */
+
+import { createClient } from '@supabase/supabase-js';
+import dotenv from 'dotenv';
+
+// Load environment variables
+dotenv.config();
+
+async function debugTelemetry() {
+  console.log('🔍 Debugging Telemetry Integration\n');
+
+  const supabaseUrl = process.env.SUPABASE_URL;
+  const supabaseAnonKey = process.env.SUPABASE_ANON_KEY;
+
+  if (!supabaseUrl || !supabaseAnonKey) {
+    console.error('❌ Missing SUPABASE_URL or SUPABASE_ANON_KEY');
+    process.exit(1);
+  }
+
+  console.log('Environment:');
+  console.log('  URL:', supabaseUrl);
+  console.log('  Key:', supabaseAnonKey.substring(0, 30) + '...');
+
+  // Create Supabase client
+  const supabase = createClient(supabaseUrl, supabaseAnonKey, {
+    auth: {
+      persistSession: false,
+      autoRefreshToken: false,
+    }
+  });
+
+  // Test 1: Direct insert to telemetry_events
+  console.log('\n📝 Test 1: Direct insert to telemetry_events...');
+  const testEvent = {
+    user_id: 'test-user-123',
+    event: 'test_event',
+    properties: {
+      test: true,
+      timestamp: new Date().toISOString()
+    }
+  };
+
+  const { data: eventData, error: eventError } = await supabase
+    .from('telemetry_events')
+    .insert([testEvent])
+    .select();
+
+  if (eventError) {
+    console.error('❌ Event insert failed:', eventError);
+  } else {
+    console.log('✅ Event inserted successfully:', eventData);
+  }
+
+  // Test 2: Direct insert to telemetry_workflows
+  console.log('\n📝 Test 2: Direct insert to telemetry_workflows...');
+  const testWorkflow = {
+    user_id: 'test-user-123',
+    workflow_hash: 'test-hash-' + Date.now(),
+    node_count: 3,
+    node_types: ['webhook', 'http', 'slack'],
+    has_trigger: true,
+    has_webhook: true,
+    complexity: 'simple',
+    sanitized_workflow: {
+      nodes: [],
+      connections: {}
+    }
+  };
+
+  const { data: workflowData, error: workflowError } = await supabase
+    .from('telemetry_workflows')
+    .insert([testWorkflow])
+    .select();
+
+  if (workflowError) {
+    console.error('❌ Workflow insert failed:', workflowError);
+  } else {
+    console.log('✅ Workflow inserted successfully:', workflowData);
+  }
+
+  // Test 3: Try to read data (should fail with anon key due to RLS)
+  console.log('\n📖 Test 3: Attempting to read data (should fail due to RLS)...');
+  const { data: readData, error: readError } = await supabase
+    .from('telemetry_events')
+    .select('*')
+    .limit(1);
+
+  if (readError) {
+    console.log('✅ Read correctly blocked by RLS:', readError.message);
+  } else {
+    console.log('⚠️  Unexpected: Read succeeded (RLS may not be working):', readData);
+  }
+
+  // Test 4: Check table existence
+  console.log('\n🔍 Test 4: Verifying tables exist...');
+  const { data: tables, error: tablesError } = await supabase
+    .rpc('get_tables', { schema_name: 'public' })
+    .select('*');
+
+  if (tablesError) {
+    // This is expected - the RPC function might not exist
+    console.log('ℹ️  Cannot list tables (RPC function not available)');
+  } else {
+    console.log('Tables found:', tables);
+  }
+
+  console.log('\n✨ Debug completed! Check your Supabase dashboard for the test data.');
+  console.log('Dashboard: https://supabase.com/dashboard/project/ydyufsohxdfpopqbubwk/editor');
+}
+
+debugTelemetry().catch(error => {
+  console.error('❌ Debug failed:', error);
+  process.exit(1);
+});

scripts/test-telemetry-direct.ts

@@ -0,0 +1,46 @@
+#!/usr/bin/env npx tsx
+/**
+ * Direct telemetry test with hardcoded credentials
+ */
+
+import { createClient } from '@supabase/supabase-js';
+
+const TELEMETRY_BACKEND = {
+  URL: 'https://ydyufsohxdfpopqbubwk.supabase.co',
+  ANON_KEY: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InlkeXVmc29oeGRmcG9wcWJ1YndrIiwicm9sZSI6ImFub24iLCJpYXQiOjE3Mzc2MzAxMDgsImV4cCI6MjA1MzIwNjEwOH0.LsUTx9OsNtnqg-jxXaJPc84aBHVDehHiMaFoF2Ir8s0'
+};
+
+async function testDirect() {
+  console.log('🧪 Direct Telemetry Test\n');
+
+  const supabase = createClient(TELEMETRY_BACKEND.URL, TELEMETRY_BACKEND.ANON_KEY, {
+    auth: {
+      persistSession: false,
+      autoRefreshToken: false,
+    }
+  });
+
+  const testEvent = {
+    user_id: 'direct-test-' + Date.now(),
+    event: 'direct_test',
+    properties: {
+      source: 'test-telemetry-direct.ts',
+      timestamp: new Date().toISOString()
+    }
+  };
+
+  console.log('Sending event:', testEvent);
+
+  const { data, error } = await supabase
+    .from('telemetry_events')
+    .insert([testEvent]);
+
+  if (error) {
+    console.error('❌ Failed:', error);
+  } else {
+    console.log('✅ Success! Event sent directly to Supabase');
+    console.log('Response:', data);
+  }
+}
+
+testDirect().catch(console.error);

scripts/test-telemetry-env.ts

@@ -0,0 +1,62 @@
+#!/usr/bin/env npx tsx
+/**
+ * Test telemetry environment variable override
+ */
+
+import { TelemetryConfigManager } from '../src/telemetry/config-manager';
+import { telemetry } from '../src/telemetry/telemetry-manager';
+
+async function testEnvOverride() {
+  console.log('🧪 Testing Telemetry Environment Variable Override\n');
+
+  const configManager = TelemetryConfigManager.getInstance();
+
+  // Test 1: Check current status without env var
+  console.log('Test 1: Without environment variable');
+  console.log('Is Enabled:', configManager.isEnabled());
+  console.log('Status:', configManager.getStatus());
+
+  // Test 2: Set environment variable and check again
+  console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+  console.log('Test 2: With N8N_MCP_TELEMETRY_DISABLED=true');
+  process.env.N8N_MCP_TELEMETRY_DISABLED = 'true';
+
+  // Force reload by creating new instance (for testing)
+  const newConfigManager = TelemetryConfigManager.getInstance();
+  console.log('Is Enabled:', newConfigManager.isEnabled());
+  console.log('Status:', newConfigManager.getStatus());
+
+  // Test 3: Try tracking with env disabled
+  console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+  console.log('Test 3: Attempting to track with telemetry disabled');
+  telemetry.trackToolUsage('test_tool', true, 100);
+  console.log('Tool usage tracking attempted (should be ignored)');
+
+  // Test 4: Alternative env vars
+  console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+  console.log('Test 4: Alternative environment variables');
+
+  delete process.env.N8N_MCP_TELEMETRY_DISABLED;
+  process.env.TELEMETRY_DISABLED = 'true';
+  console.log('With TELEMETRY_DISABLED=true:', newConfigManager.isEnabled());
+
+  delete process.env.TELEMETRY_DISABLED;
+  process.env.DISABLE_TELEMETRY = 'true';
+  console.log('With DISABLE_TELEMETRY=true:', newConfigManager.isEnabled());
+
+  // Test 5: Env var takes precedence over config
+  console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+  console.log('Test 5: Environment variable precedence');
+
+  // Enable via config
+  newConfigManager.enable();
+  console.log('After enabling via config:', newConfigManager.isEnabled());
+
+  // But env var should still override
+  process.env.N8N_MCP_TELEMETRY_DISABLED = 'true';
+  console.log('With env var set (should override config):', newConfigManager.isEnabled());
+
+  console.log('\n✅ All tests completed!');
+}
+
+testEnvOverride().catch(console.error);

scripts/test-telemetry-integration.ts

@@ -0,0 +1,94 @@
+#!/usr/bin/env npx tsx
+/**
+ * Integration test for the telemetry manager
+ */
+
+import { telemetry } from '../src/telemetry/telemetry-manager';
+
+async function testIntegration() {
+  console.log('🧪 Testing Telemetry Manager Integration\n');
+
+  // Check status
+  console.log('Status:', telemetry.getStatus());
+
+  // Track session start
+  console.log('\nTracking session start...');
+  telemetry.trackSessionStart();
+
+  // Track tool usage
+  console.log('Tracking tool usage...');
+  telemetry.trackToolUsage('search_nodes', true, 150);
+  telemetry.trackToolUsage('get_node_info', true, 75);
+  telemetry.trackToolUsage('validate_workflow', false, 200);
+
+  // Track errors
+  console.log('Tracking errors...');
+  telemetry.trackError('ValidationError', 'workflow_validation', 'validate_workflow', 'Required field missing: nodes array is empty');
+
+  // Track a test workflow
+  console.log('Tracking workflow creation...');
+  const testWorkflow = {
+    nodes: [
+      {
+        id: '1',
+        type: 'n8n-nodes-base.webhook',
+        name: 'Webhook',
+        position: [0, 0],
+        parameters: {
+          path: '/test-webhook',
+          httpMethod: 'POST'
+        }
+      },
+      {
+        id: '2',
+        type: 'n8n-nodes-base.httpRequest',
+        name: 'HTTP Request',
+        position: [250, 0],
+        parameters: {
+          url: 'https://api.example.com/endpoint',
+          method: 'POST',
+          authentication: 'genericCredentialType',
+          genericAuthType: 'httpHeaderAuth',
+          sendHeaders: true,
+          headerParameters: {
+            parameters: [
+              {
+                name: 'Authorization',
+                value: 'Bearer sk-1234567890abcdef'
+              }
+            ]
+          }
+        }
+      },
+      {
+        id: '3',
+        type: 'n8n-nodes-base.slack',
+        name: 'Slack',
+        position: [500, 0],
+        parameters: {
+          channel: '#notifications',
+          text: 'Workflow completed!'
+        }
+      }
+    ],
+    connections: {
+      '1': {
+        main: [[{ node: '2', type: 'main', index: 0 }]]
+      },
+      '2': {
+        main: [[{ node: '3', type: 'main', index: 0 }]]
+      }
+    }
+  };
+
+  telemetry.trackWorkflowCreation(testWorkflow, true);
+
+  // Force flush
+  console.log('\nFlushing telemetry data...');
+  await telemetry.flush();
+
+  console.log('\n✅ Telemetry integration test completed!');
+  console.log('Check your Supabase dashboard for the telemetry data.');
+}
+
+testIntegration().catch(console.error);

scripts/test-telemetry-no-select.ts

@@ -0,0 +1,68 @@
+#!/usr/bin/env npx tsx
+/**
+ * Test telemetry without requesting data back
+ */
+
+import { createClient } from '@supabase/supabase-js';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+async function testNoSelect() {
+  const supabaseUrl = process.env.SUPABASE_URL!;
+  const supabaseAnonKey = process.env.SUPABASE_ANON_KEY!;
+
+  console.log('🧪 Telemetry Test (No Select)\n');
+
+  const supabase = createClient(supabaseUrl, supabaseAnonKey, {
+    auth: {
+      persistSession: false,
+      autoRefreshToken: false,
+    }
+  });
+
+  // Insert WITHOUT .select() - just fire and forget
+  const testData = {
+    user_id: 'test-' + Date.now(),
+    event: 'test_event',
+    properties: { test: true }
+  };
+
+  console.log('Inserting:', testData);
+
+  const { error } = await supabase
+    .from('telemetry_events')
+    .insert([testData]);  // No .select() here!
+
+  if (error) {
+    console.error('❌ Failed:', error);
+  } else {
+    console.log('✅ Success! Data inserted (no response data)');
+  }
+
+  // Test workflow insert too
+  const testWorkflow = {
+    user_id: 'test-' + Date.now(),
+    workflow_hash: 'hash-' + Date.now(),
+    node_count: 3,
+    node_types: ['webhook', 'http', 'slack'],
+    has_trigger: true,
+    has_webhook: true,
+    complexity: 'simple',
+    sanitized_workflow: { nodes: [], connections: {} }
+  };
+
+  console.log('\nInserting workflow:', testWorkflow);
+
+  const { error: workflowError } = await supabase
+    .from('telemetry_workflows')
+    .insert([testWorkflow]);  // No .select() here!
+
+  if (workflowError) {
+    console.error('❌ Workflow failed:', workflowError);
+  } else {
+    console.log('✅ Workflow inserted successfully!');
+  }
+}
+
+testNoSelect().catch(console.error);

scripts/test-telemetry-security.ts

@@ -0,0 +1,87 @@
+#!/usr/bin/env npx tsx
+/**
+ * Test that RLS properly protects data
+ */
+
+import { createClient } from '@supabase/supabase-js';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+async function testSecurity() {
+  const supabaseUrl = process.env.SUPABASE_URL!;
+  const supabaseAnonKey = process.env.SUPABASE_ANON_KEY!;
+
+  console.log('🔒 Testing Telemetry Security (RLS)\n');
+
+  const supabase = createClient(supabaseUrl, supabaseAnonKey, {
+    auth: {
+      persistSession: false,
+      autoRefreshToken: false,
+    }
+  });
+
+  // Test 1: Verify anon can INSERT
+  console.log('Test 1: Anonymous INSERT (should succeed)...');
+  const testData = {
+    user_id: 'security-test-' + Date.now(),
+    event: 'security_test',
+    properties: { test: true }
+  };
+
+  const { error: insertError } = await supabase
+    .from('telemetry_events')
+    .insert([testData]);
+
+  if (insertError) {
+    console.error('❌ Insert failed:', insertError.message);
+  } else {
+    console.log('✅ Insert succeeded (as expected)');
+  }
+
+  // Test 2: Verify anon CANNOT SELECT
+  console.log('\nTest 2: Anonymous SELECT (should fail)...');
+  const { data, error: selectError } = await supabase
+    .from('telemetry_events')
+    .select('*')
+    .limit(1);
+
+  if (selectError) {
+    console.log('✅ Select blocked by RLS (as expected):', selectError.message);
+  } else if (data && data.length > 0) {
+    console.error('❌ SECURITY ISSUE: Anon can read data!', data);
+  } else if (data && data.length === 0) {
+    console.log('⚠️  Select returned empty array (might be RLS working)');
+  }
+
+  // Test 3: Verify anon CANNOT UPDATE
+  console.log('\nTest 3: Anonymous UPDATE (should fail)...');
+  const { error: updateError } = await supabase
+    .from('telemetry_events')
+    .update({ event: 'hacked' })
+    .eq('user_id', 'test');
+
+  if (updateError) {
+    console.log('✅ Update blocked (as expected):', updateError.message);
+  } else {
+    console.error('❌ SECURITY ISSUE: Anon can update data!');
+  }
+
+  // Test 4: Verify anon CANNOT DELETE
+  console.log('\nTest 4: Anonymous DELETE (should fail)...');
+  const { error: deleteError } = await supabase
+    .from('telemetry_events')
+    .delete()
+    .eq('user_id', 'test');
+
+  if (deleteError) {
+    console.log('✅ Delete blocked (as expected):', deleteError.message);
+  } else {
+    console.error('❌ SECURITY ISSUE: Anon can delete data!');
+  }
+
+  console.log('\n✨ Security test completed!');
+  console.log('Summary: Anonymous users can INSERT (for telemetry) but cannot READ/UPDATE/DELETE');
+}
+
+testSecurity().catch(console.error);

scripts/test-telemetry-simple.ts

@@ -0,0 +1,45 @@
+#!/usr/bin/env npx tsx
+/**
+ * Simple test to verify telemetry works
+ */
+
+import { createClient } from '@supabase/supabase-js';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+async function testSimple() {
+  const supabaseUrl = process.env.SUPABASE_URL!;
+  const supabaseAnonKey = process.env.SUPABASE_ANON_KEY!;
+
+  console.log('🧪 Simple Telemetry Test\n');
+
+  const supabase = createClient(supabaseUrl, supabaseAnonKey, {
+    auth: {
+      persistSession: false,
+      autoRefreshToken: false,
+    }
+  });
+
+  // Simple insert
+  const testData = {
+    user_id: 'simple-test-' + Date.now(),
+    event: 'test_event',
+    properties: { test: true }
+  };
+
+  console.log('Inserting:', testData);
+
+  const { data, error } = await supabase
+    .from('telemetry_events')
+    .insert([testData])
+    .select();
+
+  if (error) {
+    console.error('❌ Failed:', error);
+  } else {
+    console.log('✅ Success! Inserted:', data);
+  }
+}
+
+testSimple().catch(console.error);

scripts/test-workflow-insert.ts

@@ -0,0 +1,55 @@
+#!/usr/bin/env npx tsx
+/**
+ * Test direct workflow insert to Supabase
+ */
+
+import { createClient } from '@supabase/supabase-js';
+
+const TELEMETRY_BACKEND = {
+  URL: 'https://ydyufsohxdfpopqbubwk.supabase.co',
+  ANON_KEY: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InlkeXVmc29oeGRmcG9wcWJ1YndrIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NTg3OTYyMDAsImV4cCI6MjA3NDM3MjIwMH0.xESphg6h5ozaDsm4Vla3QnDJGc6Nc_cpfoqTHRynkCk'
+};
+
+async function testWorkflowInsert() {
+  const supabase = createClient(TELEMETRY_BACKEND.URL, TELEMETRY_BACKEND.ANON_KEY, {
+    auth: {
+      persistSession: false,
+      autoRefreshToken: false,
+    }
+  });
+
+  const testWorkflow = {
+    user_id: 'direct-test-' + Date.now(),
+    workflow_hash: 'hash-direct-' + Date.now(),
+    node_count: 2,
+    node_types: ['webhook', 'http'],
+    has_trigger: true,
+    has_webhook: true,
+    complexity: 'simple' as const,
+    sanitized_workflow: {
+      nodes: [
+        { id: '1', type: 'webhook', parameters: {} },
+        { id: '2', type: 'http', parameters: {} }
+      ],
+      connections: {}
+    }
+  };
+
+  console.log('Attempting direct insert to telemetry_workflows...');
+  console.log('Data:', JSON.stringify(testWorkflow, null, 2));
+
+  const { data, error } = await supabase
+    .from('telemetry_workflows')
+    .insert([testWorkflow]);
+
+  if (error) {
+    console.error('\n❌ Error:', error);
+  } else {
+    console.log('\n✅ Success! Workflow inserted');
+    if (data) {
+      console.log('Response:', data);
+    }
+  }
+}
+
+testWorkflowInsert().catch(console.error);

scripts/test-workflow-sanitizer.ts

@@ -0,0 +1,67 @@
+#!/usr/bin/env npx tsx
+/**
+ * Test workflow sanitizer
+ */
+
+import { WorkflowSanitizer } from '../src/telemetry/workflow-sanitizer';
+
+const testWorkflow = {
+  nodes: [
+    {
+      id: 'webhook1',
+      type: 'n8n-nodes-base.webhook',
+      name: 'Webhook',
+      position: [0, 0],
+      parameters: { 
+        path: '/test-webhook',
+        httpMethod: 'POST'
+      }
+    },
+    {
+      id: 'http1',
+      type: 'n8n-nodes-base.httpRequest',
+      name: 'HTTP Request',
+      position: [250, 0],
+      parameters: { 
+        url: 'https://api.example.com/endpoint',
+        method: 'GET',
+        authentication: 'genericCredentialType',
+        sendHeaders: true,
+        headerParameters: {
+          parameters: [
+            {
+              name: 'Authorization',
+              value: 'Bearer sk-1234567890abcdef'
+            }
+          ]
+        }
+      }
+    }
+  ],
+  connections: {
+    'webhook1': {
+      main: [[{ node: 'http1', type: 'main', index: 0 }]]
+    }
+  }
+};
+
+console.log('🧪 Testing Workflow Sanitizer\n');
+console.log('Original workflow has', testWorkflow.nodes.length, 'nodes');
+
+try {
+  const sanitized = WorkflowSanitizer.sanitizeWorkflow(testWorkflow);
+  
+  console.log('\n✅ Sanitization successful!');
+  console.log('\nSanitized output:');
+  console.log(JSON.stringify(sanitized, null, 2));
+  
+  console.log('\n📊 Metrics:');
+  console.log('- Workflow Hash:', sanitized.workflowHash);
+  console.log('- Node Count:', sanitized.nodeCount);
+  console.log('- Node Types:', sanitized.nodeTypes);
+  console.log('- Has Trigger:', sanitized.hasTrigger);
+  console.log('- Has Webhook:', sanitized.hasWebhook);
+  console.log('- Complexity:', sanitized.complexity);
+} catch (error) {
+  console.error('❌ Sanitization failed:', error);
+}

scripts/test-workflow-tracking-debug.ts

@@ -0,0 +1,71 @@
+#!/usr/bin/env npx tsx
+/**
+ * Debug workflow tracking in telemetry manager
+ */
+
+import { TelemetryManager } from '../src/telemetry/telemetry-manager';
+
+// Get the singleton instance
+const telemetry = TelemetryManager.getInstance();
+
+const testWorkflow = {
+  nodes: [
+    {
+      id: 'webhook1',
+      type: 'n8n-nodes-base.webhook',
+      name: 'Webhook',
+      position: [0, 0],
+      parameters: { 
+        path: '/test-' + Date.now(),
+        httpMethod: 'POST'
+      }
+    },
+    {
+      id: 'http1',
+      type: 'n8n-nodes-base.httpRequest',
+      name: 'HTTP Request',
+      position: [250, 0],
+      parameters: { 
+        url: 'https://api.example.com/data',
+        method: 'GET'
+      }
+    },
+    {
+      id: 'slack1',
+      type: 'n8n-nodes-base.slack',
+      name: 'Slack',
+      position: [500, 0],
+      parameters: {
+        channel: '#general',
+        text: 'Workflow complete!'
+      }
+    }
+  ],
+  connections: {
+    'webhook1': {
+      main: [[{ node: 'http1', type: 'main', index: 0 }]]
+    },
+    'http1': {
+      main: [[{ node: 'slack1', type: 'main', index: 0 }]]
+    }
+  }
+};
+
+console.log('🧪 Testing Workflow Tracking\n');
+console.log('Workflow has', testWorkflow.nodes.length, 'nodes');
+
+// Track the workflow
+console.log('Calling trackWorkflowCreation...');
+telemetry.trackWorkflowCreation(testWorkflow, true);
+
+console.log('Waiting for async processing...');
+
+// Wait for setImmediate to process
+setTimeout(async () => {
+  console.log('\nForcing flush...');
+  await telemetry.flush();
+  console.log('✅ Flush complete!');
+  
+  console.log('\nWorkflow should now be in the telemetry_workflows table.');
+  console.log('Check with: SELECT * FROM telemetry_workflows ORDER BY created_at DESC LIMIT 1;');
+}, 2000);

src/config/n8n-api.ts

@@ -48,5 +48,27 @@ export function isN8nApiConfigured(): boolean {
   return config !== null;
 }
 
+/**
+ * Create n8n API configuration from instance context
+ * Used for flexible instance configuration support
+ */
+export function getN8nApiConfigFromContext(context: {
+  n8nApiUrl?: string;
+  n8nApiKey?: string;
+  n8nApiTimeout?: number;
+  n8nApiMaxRetries?: number;
+}): N8nApiConfig | null {
+  if (!context.n8nApiUrl || !context.n8nApiKey) {
+    return null;
+  }
+
+  return {
+    baseUrl: context.n8nApiUrl,
+    apiKey: context.n8nApiKey,
+    timeout: context.n8nApiTimeout ?? 30000,
+    maxRetries: context.n8nApiMaxRetries ?? 3,
+  };
+}
+
 // Type export
 export type N8nApiConfig = NonNullable<ReturnType<typeof getN8nApiConfig>>;

src/database/migrations/add-template-node-configs.sql

@@ -0,0 +1,59 @@
+-- Migration: Add template_node_configs table
+-- Run during `npm run rebuild` or `npm run fetch:templates`
+-- This migration is idempotent - safe to run multiple times
+
+-- Create table if it doesn't exist
+CREATE TABLE IF NOT EXISTS template_node_configs (
+  id INTEGER PRIMARY KEY,
+  node_type TEXT NOT NULL,
+  template_id INTEGER NOT NULL,
+  template_name TEXT NOT NULL,
+  template_views INTEGER DEFAULT 0,
+
+  -- Node configuration (extracted from workflow)
+  node_name TEXT,                  -- Node name in workflow (e.g., "HTTP Request")
+  parameters_json TEXT NOT NULL,   -- JSON: node.parameters
+  credentials_json TEXT,            -- JSON: node.credentials (if present)
+
+  -- Pre-calculated metadata for filtering
+  has_credentials INTEGER DEFAULT 0,
+  has_expressions INTEGER DEFAULT 0,  -- Contains {{...}} or $json/$node
+  complexity TEXT CHECK(complexity IN ('simple', 'medium', 'complex')),
+  use_cases TEXT,                   -- JSON array from template.metadata.use_cases
+
+  -- Pre-calculated ranking (1 = best, 2 = second best, etc.)
+  rank INTEGER DEFAULT 0,
+
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (template_id) REFERENCES templates(id) ON DELETE CASCADE
+);
+
+-- Create indexes if they don't exist
+CREATE INDEX IF NOT EXISTS idx_config_node_type_rank
+  ON template_node_configs(node_type, rank);
+
+CREATE INDEX IF NOT EXISTS idx_config_complexity
+  ON template_node_configs(node_type, complexity, rank);
+
+CREATE INDEX IF NOT EXISTS idx_config_auth
+  ON template_node_configs(node_type, has_credentials, rank);
+
+-- Create view if it doesn't exist
+CREATE VIEW IF NOT EXISTS ranked_node_configs AS
+SELECT
+  node_type,
+  template_name,
+  template_views,
+  parameters_json,
+  credentials_json,
+  has_credentials,
+  has_expressions,
+  complexity,
+  use_cases,
+  rank
+FROM template_node_configs
+WHERE rank <= 5  -- Top 5 per node type
+ORDER BY node_type, rank;
+
+-- Note: Actual data population is handled by the fetch-templates script
+-- This migration only creates the schema

src/database/node-repository.ts

@@ -1,6 +1,7 @@
 import { DatabaseAdapter } from './database-adapter';
 import { ParsedNode } from '../parsers/node-parser';
 import { SQLiteStorageService } from '../services/sqlite-storage-service';
+import { NodeTypeNormalizer } from '../utils/node-type-normalizer';
 
 export class NodeRepository {
   private db: DatabaseAdapter;
@@ -50,33 +51,30 @@ export class NodeRepository {
   
   /**
    * Get node with proper JSON deserialization
+   * Automatically normalizes node type to full form for consistent lookups
    */
   getNode(nodeType: string): any {
+    // Normalize to full form first for consistent lookups
+    const normalizedType = NodeTypeNormalizer.normalizeToFullForm(nodeType);
+
     const row = this.db.prepare(`
       SELECT * FROM nodes WHERE node_type = ?
-    `).get(nodeType) as any;
-    
+    `).get(normalizedType) as any;
+
+    // Fallback: try original type if normalization didn't help (e.g., community nodes)
+    if (!row && normalizedType !== nodeType) {
+      const originalRow = this.db.prepare(`
+        SELECT * FROM nodes WHERE node_type = ?
+      `).get(nodeType) as any;
+
+      if (originalRow) {
+        return this.parseNodeRow(originalRow);
+      }
+    }
+
     if (!row) return null;
-    
-    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,
-      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
-    };
+
+    return this.parseNodeRow(row);
   }
   
   /**
@@ -248,4 +246,207 @@ export class NodeRepository {
       outputNames: row.output_names ? this.safeJsonParse(row.output_names, null) : null
     };
   }
+
+  /**
+   * Get operations for a specific node, optionally filtered by resource
+   */
+  getNodeOperations(nodeType: string, resource?: string): any[] {
+    const node = this.getNode(nodeType);
+    if (!node) return [];
+
+    const operations: any[] = [];
+
+    // Parse operations field
+    if (node.operations) {
+      if (Array.isArray(node.operations)) {
+        operations.push(...node.operations);
+      } else if (typeof node.operations === 'object') {
+        // Operations might be grouped by resource
+        if (resource && node.operations[resource]) {
+          return node.operations[resource];
+        } else {
+          // Return all operations
+          Object.values(node.operations).forEach(ops => {
+            if (Array.isArray(ops)) {
+              operations.push(...ops);
+            }
+          });
+        }
+      }
+    }
+
+    // Also check properties for operation fields
+    if (node.properties && Array.isArray(node.properties)) {
+      for (const prop of node.properties) {
+        if (prop.name === 'operation' && prop.options) {
+          // If resource is specified, filter by displayOptions
+          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;
+            }
+          }
+
+          // Add operations from this property
+          operations.push(...prop.options);
+        }
+      }
+    }
+
+    return operations;
+  }
+
+  /**
+   * Get all resources defined for a node
+   */
+  getNodeResources(nodeType: string): any[] {
+    const node = this.getNode(nodeType);
+    if (!node || !node.properties) return [];
+
+    const resources: any[] = [];
+
+    // Look for resource property
+    for (const prop of node.properties) {
+      if (prop.name === 'resource' && prop.options) {
+        resources.push(...prop.options);
+      }
+    }
+
+    return resources;
+  }
+
+  /**
+   * Get operations that are valid for a specific resource
+   */
+  getOperationsForResource(nodeType: string, resource: string): any[] {
+    const node = this.getNode(nodeType);
+    if (!node || !node.properties) return [];
+
+    const operations: any[] = [];
+
+    // Find operation properties that are visible for this resource
+    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;
+  }
+
+  /**
+   * Get all operations across all nodes (for analysis)
+   */
+  getAllOperations(): Map<string, any[]> {
+    const allOperations = new Map<string, any[]>();
+    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;
+  }
+
+  /**
+   * Get all resources across all nodes (for analysis)
+   */
+  getAllResources(): Map<string, any[]> {
+    const allResources = new Map<string, any[]>();
+    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;
+  }
+
+  /**
+   * Get default values for node properties
+   */
+  getNodePropertyDefaults(nodeType: string): Record<string, any> {
+    try {
+      const node = this.getNode(nodeType);
+      if (!node || !node.properties) return {};
+
+      const defaults: Record<string, any> = {};
+
+      for (const prop of node.properties) {
+        if (prop.name && prop.default !== undefined) {
+          defaults[prop.name] = prop.default;
+        }
+      }
+
+      return defaults;
+    } catch (error) {
+      // Log error and return empty defaults rather than throwing
+      console.error(`Error getting property defaults for ${nodeType}:`, error);
+      return {};
+    }
+  }
+
+  /**
+   * Get the default operation for a specific resource
+   */
+  getDefaultOperationForResource(nodeType: string, resource?: string): string | undefined {
+    try {
+      const node = this.getNode(nodeType);
+      if (!node || !node.properties) return undefined;
+
+      // Find operation property that's visible for this resource
+      for (const prop of node.properties) {
+        if (prop.name === 'operation') {
+          // If there's a resource dependency, check if it matches
+          if (resource && prop.displayOptions?.show?.resource) {
+            // Validate displayOptions structure
+            const resourceDep = prop.displayOptions.show.resource;
+            if (!Array.isArray(resourceDep) && typeof resourceDep !== 'string') {
+              continue; // Skip malformed displayOptions
+            }
+
+            const allowedResources = Array.isArray(resourceDep)
+              ? resourceDep
+              : [resourceDep];
+
+            if (!allowedResources.includes(resource)) {
+              continue; // This operation property doesn't apply to our resource
+            }
+          }
+
+          // Return the default value if it exists
+          if (prop.default !== undefined) {
+            return prop.default;
+          }
+
+          // If no default but has options, return the first option's value
+          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) {
+      // Log error and return undefined rather than throwing
+      // This ensures validation continues even with malformed node data
+      console.error(`Error getting default operation for ${nodeType}:`, error);
+      return undefined;
+    }
+
+    return undefined;
+  }
 }

src/database/schema.sql

@@ -53,5 +53,60 @@ CREATE INDEX IF NOT EXISTS idx_template_updated ON templates(updated_at);
 CREATE INDEX IF NOT EXISTS idx_template_name ON templates(name);
 CREATE INDEX IF NOT EXISTS idx_template_metadata ON templates(metadata_generated_at);
 
+-- Pre-extracted node configurations from templates
+-- This table stores the top node configurations from popular templates
+-- Provides fast access to real-world configuration examples
+CREATE TABLE IF NOT EXISTS template_node_configs (
+  id INTEGER PRIMARY KEY,
+  node_type TEXT NOT NULL,
+  template_id INTEGER NOT NULL,
+  template_name TEXT NOT NULL,
+  template_views INTEGER DEFAULT 0,
+
+  -- Node configuration (extracted from workflow)
+  node_name TEXT,                  -- Node name in workflow (e.g., "HTTP Request")
+  parameters_json TEXT NOT NULL,   -- JSON: node.parameters
+  credentials_json TEXT,            -- JSON: node.credentials (if present)
+
+  -- Pre-calculated metadata for filtering
+  has_credentials INTEGER DEFAULT 0,
+  has_expressions INTEGER DEFAULT 0,  -- Contains {{...}} or $json/$node
+  complexity TEXT CHECK(complexity IN ('simple', 'medium', 'complex')),
+  use_cases TEXT,                   -- JSON array from template.metadata.use_cases
+
+  -- Pre-calculated ranking (1 = best, 2 = second best, etc.)
+  rank INTEGER DEFAULT 0,
+
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (template_id) REFERENCES templates(id) ON DELETE CASCADE
+);
+
+-- Indexes for fast queries
+CREATE INDEX IF NOT EXISTS idx_config_node_type_rank
+  ON template_node_configs(node_type, rank);
+
+CREATE INDEX IF NOT EXISTS idx_config_complexity
+  ON template_node_configs(node_type, complexity, rank);
+
+CREATE INDEX IF NOT EXISTS idx_config_auth
+  ON template_node_configs(node_type, has_credentials, rank);
+
+-- View for easy querying of top configs
+CREATE VIEW IF NOT EXISTS ranked_node_configs AS
+SELECT
+  node_type,
+  template_name,
+  template_views,
+  parameters_json,
+  credentials_json,
+  has_credentials,
+  has_expressions,
+  complexity,
+  use_cases,
+  rank
+FROM template_node_configs
+WHERE rank <= 5  -- Top 5 per node type
+ORDER BY node_type, rank;
+
 -- Note: FTS5 tables are created conditionally at runtime if FTS5 is supported
 -- See template-repository.ts initializeFTS5() method

src/errors/validation-service-error.ts

@@ -0,0 +1,53 @@
+/**
+ * Custom error class for validation service failures
+ */
+export class ValidationServiceError extends Error {
+  constructor(
+    message: string,
+    public readonly nodeType?: string,
+    public readonly property?: string,
+    public readonly cause?: Error
+  ) {
+    super(message);
+    this.name = 'ValidationServiceError';
+
+    // Maintains proper stack trace for where our error was thrown (only available on V8)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, ValidationServiceError);
+    }
+  }
+
+  /**
+   * Create error for JSON parsing failure
+   */
+  static jsonParseError(nodeType: string, cause: Error): ValidationServiceError {
+    return new ValidationServiceError(
+      `Failed to parse JSON data for node ${nodeType}`,
+      nodeType,
+      undefined,
+      cause
+    );
+  }
+
+  /**
+   * Create error for node not found
+   */
+  static nodeNotFound(nodeType: string): ValidationServiceError {
+    return new ValidationServiceError(
+      `Node type ${nodeType} not found in repository`,
+      nodeType
+    );
+  }
+
+  /**
+   * Create error for critical data extraction failure
+   */
+  static dataExtractionError(nodeType: string, dataType: string, cause?: Error): ValidationServiceError {
+    return new ValidationServiceError(
+      `Failed to extract ${dataType} for node ${nodeType}`,
+      nodeType,
+      dataType,
+      cause
+    );
+  }
+}

src/http-server-single-session.ts

@@ -5,28 +5,40 @@
  * while maintaining simplicity for single-player use case
  */
 import express from 'express';
+import rateLimit from 'express-rate-limit';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
 import { N8NDocumentationMCPServer } from './mcp/server';
 import { ConsoleManager } from './utils/console-manager';
 import { logger } from './utils/logger';
+import { AuthManager } from './utils/auth';
 import { readFileSync } from 'fs';
 import dotenv from 'dotenv';
 import { getStartupBaseUrl, formatEndpointUrls, detectBaseUrl } from './utils/url-detector';
 import { PROJECT_VERSION } from './utils/version';
 import { v4 as uuidv4 } from 'uuid';
+import { createHash } from 'crypto';
 import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
-import { 
-  negotiateProtocolVersion, 
+import {
+  negotiateProtocolVersion,
   logProtocolNegotiation,
-  STANDARD_PROTOCOL_VERSION 
+  STANDARD_PROTOCOL_VERSION
 } from './utils/protocol-version';
+import { InstanceContext, validateInstanceContext } from './types/instance-context';
 
 dotenv.config();
 
 // Protocol version constant - will be negotiated per client
 const DEFAULT_PROTOCOL_VERSION = STANDARD_PROTOCOL_VERSION;
 
+// Type-safe headers interface for multi-tenant support
+interface MultiTenantHeaders {
+  'x-n8n-url'?: string;
+  'x-n8n-key'?: string;
+  'x-instance-id'?: string;
+  'x-session-id'?: string;
+}
+
 // Session management constants
 const MAX_SESSIONS = 100;
 const SESSION_CLEANUP_INTERVAL = 5 * 60 * 1000; // 5 minutes
@@ -47,11 +59,25 @@ interface SessionMetrics {
   lastCleanup: Date;
 }
 
+/**
+ * Extract multi-tenant headers in a type-safe manner
+ */
+function extractMultiTenantHeaders(req: express.Request): MultiTenantHeaders {
+  return {
+    'x-n8n-url': req.headers['x-n8n-url'] as string | undefined,
+    'x-n8n-key': req.headers['x-n8n-key'] as string | undefined,
+    'x-instance-id': req.headers['x-instance-id'] as string | undefined,
+    'x-session-id': req.headers['x-session-id'] as string | undefined,
+  };
+}
+
 export class SingleSessionHTTPServer {
   // Map to store transports by session ID (following SDK pattern)
   private transports: { [sessionId: string]: StreamableHTTPServerTransport } = {};
   private servers: { [sessionId: string]: N8NDocumentationMCPServer } = {};
   private sessionMetadata: { [sessionId: string]: { lastAccess: Date; createdAt: Date } } = {};
+  private sessionContexts: { [sessionId: string]: InstanceContext | undefined } = {};
+  private contextSwitchLocks: Map<string, Promise<void>> = new Map();
   private session: Session | null = null;  // Keep for SSE compatibility
   private consoleManager = new ConsoleManager();
   private expressServer: any;
@@ -93,7 +119,7 @@ export class SingleSessionHTTPServer {
   private cleanupExpiredSessions(): void {
     const now = Date.now();
     const expiredSessions: string[] = [];
-    
+
     // Check for expired sessions
     for (const sessionId in this.sessionMetadata) {
       const metadata = this.sessionMetadata[sessionId];
@@ -101,14 +127,23 @@ export class SingleSessionHTTPServer {
         expiredSessions.push(sessionId);
       }
     }
-    
+
+    // Also check for orphaned contexts (sessions that were removed but context remained)
+    for (const sessionId in this.sessionContexts) {
+      if (!this.sessionMetadata[sessionId]) {
+        // Context exists but session doesn't - clean it up
+        delete this.sessionContexts[sessionId];
+        logger.debug('Cleaned orphaned session context', { sessionId });
+      }
+    }
+
     // Remove expired sessions
     for (const sessionId of expiredSessions) {
       this.removeSession(sessionId, 'expired');
     }
-    
+
     if (expiredSessions.length > 0) {
-      logger.info('Cleaned up expired sessions', { 
+      logger.info('Cleaned up expired sessions', {
         removed: expiredSessions.length,
         remaining: this.getActiveSessionCount()
       });
@@ -126,9 +161,10 @@ export class SingleSessionHTTPServer {
         delete this.transports[sessionId];
       }
       
-      // Remove server and metadata
+      // Remove server, metadata, and context
       delete this.servers[sessionId];
       delete this.sessionMetadata[sessionId];
+      delete this.sessionContexts[sessionId];
       
       logger.info('Session removed', { sessionId, reason });
     } catch (error) {
@@ -201,7 +237,55 @@ export class SingleSessionHTTPServer {
       this.sessionMetadata[sessionId].lastAccess = new Date();
     }
   }
-  
+
+  /**
+   * Switch session context with locking to prevent race conditions
+   */
+  private async switchSessionContext(sessionId: string, newContext: InstanceContext): Promise<void> {
+    // Check if there's already a switch in progress for this session
+    const existingLock = this.contextSwitchLocks.get(sessionId);
+    if (existingLock) {
+      // Wait for the existing switch to complete
+      await existingLock;
+      return;
+    }
+
+    // Create a promise for this switch operation
+    const switchPromise = this.performContextSwitch(sessionId, newContext);
+    this.contextSwitchLocks.set(sessionId, switchPromise);
+
+    try {
+      await switchPromise;
+    } finally {
+      // Clean up the lock after completion
+      this.contextSwitchLocks.delete(sessionId);
+    }
+  }
+
+  /**
+   * Perform the actual context switch
+   */
+  private async performContextSwitch(sessionId: string, newContext: InstanceContext): Promise<void> {
+    const existingContext = this.sessionContexts[sessionId];
+
+    // Only switch if the context has actually changed
+    if (JSON.stringify(existingContext) !== JSON.stringify(newContext)) {
+      logger.info('Multi-tenant shared mode: Updating instance context for session', {
+        sessionId,
+        oldInstanceId: existingContext?.instanceId,
+        newInstanceId: newContext.instanceId
+      });
+
+      // Update the session context
+      this.sessionContexts[sessionId] = newContext;
+
+      // Update the MCP server's instance context if it exists
+      if (this.servers[sessionId]) {
+        (this.servers[sessionId] as any).instanceContext = newContext;
+      }
+    }
+  }
+
   /**
    * Get session metrics for monitoring
    */
@@ -301,8 +385,16 @@ export class SingleSessionHTTPServer {
 
   /**
    * Handle incoming MCP request using proper SDK pattern
+   *
+   * @param req - Express request object
+   * @param res - Express response object
+   * @param instanceContext - Optional instance-specific configuration
    */
-  async handleRequest(req: express.Request, res: express.Response): Promise<void> {
+  async handleRequest(
+    req: express.Request,
+    res: express.Response,
+    instanceContext?: InstanceContext
+  ): Promise<void> {
     const startTime = Date.now();
     
     // Wrap all operations to prevent console interference
@@ -346,10 +438,37 @@ export class SingleSessionHTTPServer {
           
           // For initialize requests: always create new transport and server
           logger.info('handleRequest: Creating new transport for initialize request');
-          
-          // Use client-provided session ID or generate one if not provided
-          const sessionIdToUse = sessionId || uuidv4();
-          const server = new N8NDocumentationMCPServer();
+
+          // Generate session ID based on multi-tenant configuration
+          let sessionIdToUse: string;
+
+          const isMultiTenantEnabled = process.env.ENABLE_MULTI_TENANT === 'true';
+          const sessionStrategy = process.env.MULTI_TENANT_SESSION_STRATEGY || 'instance';
+
+          if (isMultiTenantEnabled && sessionStrategy === 'instance' && instanceContext?.instanceId) {
+            // In multi-tenant mode with instance strategy, create session per instance
+            // This ensures each tenant gets isolated sessions
+            // Include configuration hash to prevent collisions with different configs
+            const configHash = createHash('sha256')
+              .update(JSON.stringify({
+                url: instanceContext.n8nApiUrl,
+                instanceId: instanceContext.instanceId
+              }))
+              .digest('hex')
+              .substring(0, 8);
+
+            sessionIdToUse = `instance-${instanceContext.instanceId}-${configHash}-${uuidv4()}`;
+            logger.info('Multi-tenant mode: Creating instance-specific session', {
+              instanceId: instanceContext.instanceId,
+              configHash,
+              sessionId: sessionIdToUse
+            });
+          } else {
+            // Use client-provided session ID or generate a standard one
+            sessionIdToUse = sessionId || uuidv4();
+          }
+
+          const server = new N8NDocumentationMCPServer(instanceContext);
           
           transport = new StreamableHTTPServerTransport({
             sessionIdGenerator: () => sessionIdToUse,
@@ -361,11 +480,12 @@ export class SingleSessionHTTPServer {
               this.transports[initializedSessionId] = transport;
               this.servers[initializedSessionId] = server;
               
-              // Store session metadata
+              // Store session metadata and context
               this.sessionMetadata[initializedSessionId] = {
                 lastAccess: new Date(),
                 createdAt: new Date()
               };
+              this.sessionContexts[initializedSessionId] = instanceContext;
             }
           });
           
@@ -411,7 +531,16 @@ export class SingleSessionHTTPServer {
           // For non-initialize requests: reuse existing transport for this session
           logger.info('handleRequest: Reusing existing transport for session', { sessionId });
           transport = this.transports[sessionId];
-          
+
+          // In multi-tenant shared mode, update instance context if provided
+          const isMultiTenantEnabled = process.env.ENABLE_MULTI_TENANT === 'true';
+          const sessionStrategy = process.env.MULTI_TENANT_SESSION_STRATEGY || 'instance';
+
+          if (isMultiTenantEnabled && sessionStrategy === 'shared' && instanceContext) {
+            // Update the context for this session with locking to prevent race conditions
+            await this.switchSessionContext(sessionId, instanceContext);
+          }
+
           // Update session access time
           this.updateSessionAccess(sessionId);
           
@@ -861,8 +990,41 @@ export class SingleSessionHTTPServer {
     });
 
 
-    // Main MCP endpoint with authentication
-    app.post('/mcp', jsonParser, async (req: express.Request, res: express.Response): Promise<void> => {
+    // SECURITY: Rate limiting for authentication endpoint
+    // Prevents brute force attacks and DoS
+    // See: https://github.com/czlonkowski/n8n-mcp/issues/265 (HIGH-02)
+    const authLimiter = rateLimit({
+      windowMs: parseInt(process.env.AUTH_RATE_LIMIT_WINDOW || '900000'), // 15 minutes
+      max: parseInt(process.env.AUTH_RATE_LIMIT_MAX || '20'), // 20 authentication attempts per IP
+      message: {
+        jsonrpc: '2.0',
+        error: {
+          code: -32000,
+          message: 'Too many authentication attempts. Please try again later.'
+        },
+        id: null
+      },
+      standardHeaders: true, // Return rate limit info in `RateLimit-*` headers
+      legacyHeaders: false, // Disable `X-RateLimit-*` headers
+      handler: (req, res) => {
+        logger.warn('Rate limit exceeded', {
+          ip: req.ip,
+          userAgent: req.get('user-agent'),
+          event: 'rate_limit'
+        });
+        res.status(429).json({
+          jsonrpc: '2.0',
+          error: {
+            code: -32000,
+            message: 'Too many authentication attempts'
+          },
+          id: null
+        });
+      }
+    });
+
+    // Main MCP endpoint with authentication and rate limiting
+    app.post('/mcp', authLimiter, jsonParser, async (req: express.Request, res: express.Response): Promise<void> => {
       // Log comprehensive debug info about the request
       logger.info('POST /mcp request received - DETAILED DEBUG', {
         headers: req.headers,
@@ -953,15 +1115,19 @@ export class SingleSessionHTTPServer {
       
       // Extract token and trim whitespace
       const token = authHeader.slice(7).trim();
-      
-      // Check if token matches
-      if (token !== this.authToken) {
-        logger.warn('Authentication failed: Invalid token', { 
+
+      // SECURITY: Use timing-safe comparison to prevent timing attacks
+      // See: https://github.com/czlonkowski/n8n-mcp/issues/265 (CRITICAL-02)
+      const isValidToken = this.authToken &&
+        AuthManager.timingSafeCompare(token, this.authToken);
+
+      if (!isValidToken) {
+        logger.warn('Authentication failed: Invalid token', {
           ip: req.ip,
           userAgent: req.get('user-agent'),
           reason: 'invalid_token'
         });
-        res.status(401).json({ 
+        res.status(401).json({
           jsonrpc: '2.0',
           error: {
             code: -32001,
@@ -978,8 +1144,59 @@ export class SingleSessionHTTPServer {
         sessionType: this.session?.isSSE ? 'SSE' : 'StreamableHTTP',
         sessionInitialized: this.session?.initialized
       });
-      
-      await this.handleRequest(req, res);
+
+      // Extract instance context from headers if present (for multi-tenant support)
+      const instanceContext: InstanceContext | undefined = (() => {
+        // Use type-safe header extraction
+        const headers = extractMultiTenantHeaders(req);
+        const hasUrl = headers['x-n8n-url'];
+        const hasKey = headers['x-n8n-key'];
+
+        if (!hasUrl && !hasKey) return undefined;
+
+        // Create context with proper type handling
+        const context: InstanceContext = {
+          n8nApiUrl: hasUrl || undefined,
+          n8nApiKey: hasKey || undefined,
+          instanceId: headers['x-instance-id'] || undefined,
+          sessionId: headers['x-session-id'] || undefined
+        };
+
+        // Add metadata if available
+        if (req.headers['user-agent'] || req.ip) {
+          context.metadata = {
+            userAgent: req.headers['user-agent'] as string | undefined,
+            ip: req.ip
+          };
+        }
+
+        // Validate the context
+        const validation = validateInstanceContext(context);
+        if (!validation.valid) {
+          logger.warn('Invalid instance context from headers', {
+            errors: validation.errors,
+            hasUrl: !!hasUrl,
+            hasKey: !!hasKey
+          });
+          return undefined;
+        }
+
+        return context;
+      })();
+
+      // Log context extraction for debugging (only if context exists)
+      if (instanceContext) {
+        // Use sanitized logging for security
+        logger.debug('Instance context extracted from headers', {
+          hasUrl: !!instanceContext.n8nApiUrl,
+          hasKey: !!instanceContext.n8nApiKey,
+          instanceId: instanceContext.instanceId ? instanceContext.instanceId.substring(0, 8) + '...' : undefined,
+          sessionId: instanceContext.sessionId ? instanceContext.sessionId.substring(0, 8) + '...' : undefined,
+          urlDomain: instanceContext.n8nApiUrl ? new URL(instanceContext.n8nApiUrl).hostname : undefined
+        });
+      }
+
+      await this.handleRequest(req, res, instanceContext);
       
       logger.info('POST /mcp request completed - checking response status', {
         responseHeadersSent: res.headersSent,

src/http-server.ts

@@ -9,6 +9,7 @@ import { n8nDocumentationToolsFinal } from './mcp/tools';
 import { n8nManagementTools } from './mcp/tools-n8n-manager';
 import { N8NDocumentationMCPServer } from './mcp/server';
 import { logger } from './utils/logger';
+import { AuthManager } from './utils/auth';
 import { PROJECT_VERSION } from './utils/version';
 import { isN8nApiConfigured } from './config/n8n-api';
 import dotenv from 'dotenv';
@@ -308,15 +309,19 @@ export async function startFixedHTTPServer() {
     
     // Extract token and trim whitespace
     const token = authHeader.slice(7).trim();
-    
-    // Check if token matches
-    if (token !== authToken) {
-      logger.warn('Authentication failed: Invalid token', { 
+
+    // SECURITY: Use timing-safe comparison to prevent timing attacks
+    // See: https://github.com/czlonkowski/n8n-mcp/issues/265 (CRITICAL-02)
+    const isValidToken = authToken &&
+      AuthManager.timingSafeCompare(token, authToken);
+
+    if (!isValidToken) {
+      logger.warn('Authentication failed: Invalid token', {
         ip: req.ip,
         userAgent: req.get('user-agent'),
         reason: 'invalid_token'
       });
-      res.status(401).json({ 
+      res.status(401).json({
         jsonrpc: '2.0',
         error: {
           code: -32001,

src/mcp-engine.ts

@@ -1,6 +1,6 @@
 /**
  * N8N MCP Engine - Clean interface for service integration
- * 
+ *
  * This class provides a simple API for integrating the n8n-MCP server
  * into larger services. The wrapping service handles authentication,
  * multi-tenancy, rate limiting, etc.
@@ -8,6 +8,7 @@
 import { Request, Response } from 'express';
 import { SingleSessionHTTPServer } from './http-server-single-session';
 import { logger } from './utils/logger';
+import { InstanceContext } from './types/instance-context';
 
 export interface EngineHealth {
   status: 'healthy' | 'unhealthy';
@@ -40,21 +41,33 @@ export class N8NMCPEngine {
   }
   
   /**
-   * Process a single MCP request
+   * Process a single MCP request with optional instance context
    * The wrapping service handles authentication, multi-tenancy, etc.
-   * 
+   *
+   * @param req - Express request object
+   * @param res - Express response object
+   * @param instanceContext - Optional instance-specific configuration
+   *
    * @example
-   * // In your service
-   * const engine = new N8NMCPEngine();
-   * 
-   * app.post('/api/users/:userId/mcp', authenticate, async (req, res) => {
-   *   // Your service handles auth, rate limiting, user context
-   *   await engine.processRequest(req, res);
-   * });
+   * // Basic usage (backward compatible)
+   * await engine.processRequest(req, res);
+   *
+   * @example
+   * // With instance context
+   * const context: InstanceContext = {
+   *   n8nApiUrl: 'https://instance1.n8n.cloud',
+   *   n8nApiKey: 'instance1-key',
+   *   instanceId: 'tenant-123'
+   * };
+   * await engine.processRequest(req, res, context);
    */
-  async processRequest(req: Request, res: Response): Promise<void> {
+  async processRequest(
+    req: Request,
+    res: Response,
+    instanceContext?: InstanceContext
+  ): Promise<void> {
     try {
-      await this.server.handleRequest(req, res);
+      await this.server.handleRequest(req, res, instanceContext);
     } catch (error) {
       logger.error('Engine processRequest error:', error);
       throw error;
@@ -130,36 +143,39 @@ export class N8NMCPEngine {
 }
 
 /**
- * Example usage in a multi-tenant service:
- * 
+ * Example usage with flexible instance configuration:
+ *
  * ```typescript
- * import { N8NMCPEngine } from 'n8n-mcp/engine';
+ * import { N8NMCPEngine, InstanceContext } from 'n8n-mcp';
  * import express from 'express';
- * 
+ *
  * const app = express();
  * const engine = new N8NMCPEngine();
- * 
+ *
  * // Middleware for authentication
  * const authenticate = (req, res, next) => {
  *   // Your auth logic
  *   req.userId = 'user123';
  *   next();
  * };
- * 
- * // MCP endpoint with multi-tenant support
- * app.post('/api/mcp/:userId', authenticate, async (req, res) => {
- *   // Log usage for billing
- *   await logUsage(req.userId, 'mcp-request');
- *   
- *   // Rate limiting
- *   if (await isRateLimited(req.userId)) {
- *     return res.status(429).json({ error: 'Rate limited' });
- *   }
- *   
- *   // Process request
- *   await engine.processRequest(req, res);
+ *
+ * // MCP endpoint with flexible instance support
+ * app.post('/api/instances/:instanceId/mcp', authenticate, async (req, res) => {
+ *   // Get instance configuration from your database
+ *   const instance = await getInstanceConfig(req.params.instanceId);
+ *
+ *   // Create instance context
+ *   const context: InstanceContext = {
+ *     n8nApiUrl: instance.n8nUrl,
+ *     n8nApiKey: instance.apiKey,
+ *     instanceId: instance.id,
+ *     metadata: { userId: req.userId }
+ *   };
+ *
+ *   // Process request with instance context
+ *   await engine.processRequest(req, res, context);
  * });
- * 
+ *
  * // Health endpoint
  * app.get('/health', async (req, res) => {
  *   const health = await engine.healthCheck();

src/mcp-tools-engine.ts

@@ -89,10 +89,6 @@ export class MCPEngine {
     return this.repository.searchNodeProperties(args.nodeType, args.query, args.maxResults || 20);
   }
 
-  async getNodeForTask(args: any) {
-    return TaskTemplates.getTaskTemplate(args.task);
-  }
-
   async listAITools(args: any) {
     return this.repository.getAIToolNodes();
   }

src/mcp/handlers-n8n-manager.ts

@@ -1,60 +1,202 @@
 import { N8nApiClient } from '../services/n8n-api-client';
-import { getN8nApiConfig } from '../config/n8n-api';
-import { 
-  Workflow, 
-  WorkflowNode, 
+import { getN8nApiConfig, getN8nApiConfigFromContext } from '../config/n8n-api';
+import {
+  Workflow,
+  WorkflowNode,
   WorkflowConnection,
   ExecutionStatus,
   WebhookRequest,
-  McpToolResponse 
+  McpToolResponse,
+  ExecutionFilterOptions,
+  ExecutionMode
 } from '../types/n8n-api';
-import { 
-  validateWorkflowStructure, 
+import {
+  validateWorkflowStructure,
   hasWebhookTrigger,
-  getWebhookUrl 
+  getWebhookUrl
 } from '../services/n8n-validation';
-import { 
-  N8nApiError, 
+import {
+  N8nApiError,
   N8nNotFoundError,
-  getUserFriendlyErrorMessage 
+  getUserFriendlyErrorMessage,
+  formatExecutionError,
+  formatNoExecutionError
 } from '../utils/n8n-errors';
 import { logger } from '../utils/logger';
 import { z } from 'zod';
 import { WorkflowValidator } from '../services/workflow-validator';
 import { EnhancedConfigValidator } from '../services/enhanced-config-validator';
 import { NodeRepository } from '../database/node-repository';
+import { InstanceContext, validateInstanceContext } from '../types/instance-context';
+import { NodeTypeNormalizer } from '../utils/node-type-normalizer';
+import { WorkflowAutoFixer, AutoFixConfig } from '../services/workflow-auto-fixer';
+import { ExpressionFormatValidator } from '../services/expression-format-validator';
+import { handleUpdatePartialWorkflow } from './handlers-workflow-diff';
+import { telemetry } from '../telemetry';
+import {
+  createCacheKey,
+  createInstanceCache,
+  CacheMutex,
+  cacheMetrics,
+  withRetry,
+  getCacheStatistics
+} from '../utils/cache-utils';
+import { processExecution } from '../services/execution-processor';
 
-// Singleton n8n API client instance
-let apiClient: N8nApiClient | null = null;
-let lastConfigUrl: string | null = null;
+// Singleton n8n API client instance (backward compatibility)
+let defaultApiClient: N8nApiClient | null = null;
+let lastDefaultConfigUrl: string | null = null;
 
-// Get or create API client (with lazy config loading)
-export function getN8nApiClient(): N8nApiClient | null {
+// Mutex for cache operations to prevent race conditions
+const cacheMutex = new CacheMutex();
+
+// Instance-specific API clients cache with LRU eviction and TTL
+const instanceClients = createInstanceCache<N8nApiClient>((client, key) => {
+  // Clean up when evicting from cache
+  logger.debug('Evicting API client from cache', {
+    cacheKey: key.substring(0, 8) + '...' // Only log partial key for security
+  });
+});
+
+/**
+ * Get or create API client with flexible instance support
+ * Supports both singleton mode (using environment variables) and instance-specific mode.
+ * Uses LRU cache with mutex protection for thread-safe operations.
+ *
+ * @param context - Optional instance context for instance-specific configuration
+ * @returns API client configured for the instance or environment, or null if not configured
+ *
+ * @example
+ * // Using environment variables (singleton mode)
+ * const client = getN8nApiClient();
+ *
+ * @example
+ * // Using instance context
+ * const client = getN8nApiClient({
+ *   n8nApiUrl: 'https://customer.n8n.cloud',
+ *   n8nApiKey: 'api-key-123',
+ *   instanceId: 'customer-1'
+ * });
+ */
+/**
+ * Get cache statistics for monitoring
+ * @returns Formatted cache statistics string
+ */
+export function getInstanceCacheStatistics(): string {
+  return getCacheStatistics();
+}
+
+/**
+ * Get raw cache metrics for detailed monitoring
+ * @returns Raw cache metrics object
+ */
+export function getInstanceCacheMetrics() {
+  return cacheMetrics.getMetrics();
+}
+
+/**
+ * Clear the instance cache for testing or maintenance
+ */
+export function clearInstanceCache(): void {
+  instanceClients.clear();
+  cacheMetrics.recordClear();
+  cacheMetrics.updateSize(0, instanceClients.max);
+}
+
+export function getN8nApiClient(context?: InstanceContext): N8nApiClient | null {
+  // If context provided with n8n config, use instance-specific client
+  if (context?.n8nApiUrl && context?.n8nApiKey) {
+    // Validate context before using
+    const validation = validateInstanceContext(context);
+    if (!validation.valid) {
+      logger.warn('Invalid instance context provided', {
+        instanceId: context.instanceId,
+        errors: validation.errors
+      });
+      return null;
+    }
+    // Create secure hash of credentials for cache key using memoization
+    const cacheKey = createCacheKey(
+      `${context.n8nApiUrl}:${context.n8nApiKey}:${context.instanceId || ''}`
+    );
+
+    // Check cache first
+    if (instanceClients.has(cacheKey)) {
+      cacheMetrics.recordHit();
+      return instanceClients.get(cacheKey) || null;
+    }
+
+    cacheMetrics.recordMiss();
+
+    // Check if already being created (simple lock check)
+    if (cacheMutex.isLocked(cacheKey)) {
+      // Wait briefly and check again
+      const waitTime = 100; // 100ms
+      const start = Date.now();
+      while (cacheMutex.isLocked(cacheKey) && (Date.now() - start) < 1000) {
+        // Busy wait for up to 1 second
+      }
+      // Check if it was created while waiting
+      if (instanceClients.has(cacheKey)) {
+        cacheMetrics.recordHit();
+        return instanceClients.get(cacheKey) || null;
+      }
+    }
+
+    const config = getN8nApiConfigFromContext(context);
+    if (config) {
+      // Sanitized logging - never log API keys
+      logger.info('Creating instance-specific n8n API client', {
+        url: config.baseUrl.replace(/^(https?:\/\/[^\/]+).*/, '$1'), // Only log domain
+        instanceId: context.instanceId,
+        cacheKey: cacheKey.substring(0, 8) + '...' // Only log partial hash
+      });
+
+      const client = new N8nApiClient(config);
+      instanceClients.set(cacheKey, client);
+      cacheMetrics.recordSet();
+      cacheMetrics.updateSize(instanceClients.size, instanceClients.max);
+      return client;
+    }
+
+    return null;
+  }
+
+  // Fall back to default singleton from environment
+  logger.info('Falling back to environment configuration for n8n API client');
   const config = getN8nApiConfig();
-  
+
   if (!config) {
-    if (apiClient) {
-      logger.info('n8n API configuration removed, clearing client');
-      apiClient = null;
-      lastConfigUrl = null;
+    if (defaultApiClient) {
+      logger.info('n8n API configuration removed, clearing default client');
+      defaultApiClient = null;
+      lastDefaultConfigUrl = null;
     }
     return null;
   }
-  
+
   // Check if config has changed
-  if (!apiClient || lastConfigUrl !== config.baseUrl) {
-    logger.info('n8n API client initialized', { url: config.baseUrl });
-    apiClient = new N8nApiClient(config);
-    lastConfigUrl = config.baseUrl;
+  if (!defaultApiClient || lastDefaultConfigUrl !== config.baseUrl) {
+    logger.info('n8n API client initialized from environment', { url: config.baseUrl });
+    defaultApiClient = new N8nApiClient(config);
+    lastDefaultConfigUrl = config.baseUrl;
   }
-  
-  return apiClient;
+
+  return defaultApiClient;
 }
 
-// Helper to ensure API is configured
-function ensureApiConfigured(): N8nApiClient {
-  const client = getN8nApiClient();
+/**
+ * Helper to ensure API is configured
+ * @param context - Optional instance context
+ * @returns Configured API client
+ * @throws Error if API is not configured
+ */
+function ensureApiConfigured(context?: InstanceContext): N8nApiClient {
+  const client = getN8nApiClient(context);
   if (!client) {
+    if (context?.instanceId) {
+      throw new Error(`n8n API not configured for instance ${context.instanceId}. Please provide n8nApiUrl and n8nApiKey in the instance context.`);
+    }
     throw new Error('n8n API not configured. Please set N8N_API_URL and N8N_API_KEY environment variables.');
   }
   return client;
@@ -104,6 +246,20 @@ const validateWorkflowSchema = z.object({
   }).optional(),
 });
 
+const autofixWorkflowSchema = z.object({
+  id: z.string(),
+  applyFixes: z.boolean().optional().default(false),
+  fixTypes: z.array(z.enum([
+    'expression-format',
+    'typeversion-correction',
+    'error-output-config',
+    'node-type-correction',
+    'webhook-missing-path'
+  ])).optional(),
+  confidenceThreshold: z.enum(['high', 'medium', 'low']).optional().default('medium'),
+  maxFixes: z.number().optional().default(50)
+});
+
 const triggerWebhookSchema = z.object({
   webhookUrl: z.string().url(),
   httpMethod: z.enum(['GET', 'POST', 'PUT', 'DELETE']).optional(),
@@ -123,24 +279,56 @@ const listExecutionsSchema = z.object({
 
 // Workflow Management Handlers
 
-export async function handleCreateWorkflow(args: unknown): Promise<McpToolResponse> {
+export async function handleCreateWorkflow(args: unknown, context?: InstanceContext): Promise<McpToolResponse> {
   try {
-    const client = ensureApiConfigured();
+    const client = ensureApiConfigured(context);
     const input = createWorkflowSchema.parse(args);
-    
-    // Validate workflow structure
+
+    // Proactively detect SHORT form node types (common mistake)
+    const shortFormErrors: string[] = [];
+    input.nodes?.forEach((node: any, index: number) => {
+      if (node.type?.startsWith('nodes-base.') || node.type?.startsWith('nodes-langchain.')) {
+        const fullForm = node.type.startsWith('nodes-base.')
+          ? node.type.replace('nodes-base.', 'n8n-nodes-base.')
+          : node.type.replace('nodes-langchain.', '@n8n/n8n-nodes-langchain.');
+        shortFormErrors.push(
+          `Node ${index} ("${node.name}") uses SHORT form "${node.type}". ` +
+          `The n8n API requires FULL form. Change to "${fullForm}"`
+        );
+      }
+    });
+
+    if (shortFormErrors.length > 0) {
+      telemetry.trackWorkflowCreation(input, false);
+      return {
+        success: false,
+        error: 'Node type format error: n8n API requires FULL form node types',
+        details: {
+          errors: shortFormErrors,
+          hint: 'Use n8n-nodes-base.* instead of nodes-base.* for standard nodes'
+        }
+      };
+    }
+
+    // Validate workflow structure (n8n API expects FULL form: n8n-nodes-base.*)
     const errors = validateWorkflowStructure(input);
     if (errors.length > 0) {
+      // Track validation failure
+      telemetry.trackWorkflowCreation(input, false);
+
       return {
         success: false,
         error: 'Workflow validation failed',
         details: { errors }
       };
     }
-    
-    // Create workflow
+
+    // Create workflow (n8n API expects node types in FULL form)
     const workflow = await client.createWorkflow(input);
-    
+
+    // Track successful workflow creation
+    telemetry.trackWorkflowCreation(workflow, true);
+
     return {
       success: true,
       data: workflow,
@@ -171,9 +359,9 @@ export async function handleCreateWorkflow(args: unknown): Promise<McpToolRespon
   }
 }
 
-export async function handleGetWorkflow(args: unknown): Promise<McpToolResponse> {
+export async function handleGetWorkflow(args: unknown, context?: InstanceContext): Promise<McpToolResponse> {
   try {
-    const client = ensureApiConfigured();
+    const client = ensureApiConfigured(context);
     const { id } = z.object({ id: z.string() }).parse(args);
     
     const workflow = await client.getWorkflow(id);
@@ -206,9 +394,9 @@ export async function handleGetWorkflow(args: unknown): Promise<McpToolResponse>
   }
 }
 
-export async function handleGetWorkflowDetails(args: unknown): Promise<McpToolResponse> {
+export async function handleGetWorkflowDetails(args: unknown, context?: InstanceContext): Promise<McpToolResponse> {
   try {
-    const client = ensureApiConfigured();
+    const client = ensureApiConfigured(context);
     const { id } = z.object({ id: z.string() }).parse(args);
     
     const workflow = await client.getWorkflow(id);
@@ -260,9 +448,9 @@ export async function handleGetWorkflowDetails(args: unknown): Promise<McpToolRe
   }
 }
 
-export async function handleGetWorkflowStructure(args: unknown): Promise<McpToolResponse> {
+export async function handleGetWorkflowStructure(args: unknown, context?: InstanceContext): Promise<McpToolResponse> {
   try {
-    const client = ensureApiConfigured();
+    const client = ensureApiConfigured(context);
     const { id } = z.object({ id: z.string() }).parse(args);
     
     const workflow = await client.getWorkflow(id);
@@ -313,9 +501,9 @@ export async function handleGetWorkflowStructure(args: unknown): Promise<McpTool
   }
 }
 
-export async function handleGetWorkflowMinimal(args: unknown): Promise<McpToolResponse> {
+export async function handleGetWorkflowMinimal(args: unknown, context?: InstanceContext): Promise<McpToolResponse> {
   try {
-    const client = ensureApiConfigured();
+    const client = ensureApiConfigured(context);
     const { id } = z.object({ id: z.string() }).parse(args);
     
     const workflow = await client.getWorkflow(id);
@@ -356,25 +544,22 @@ export async function handleGetWorkflowMinimal(args: unknown): Promise<McpToolRe
   }
 }
 
-export async function handleUpdateWorkflow(args: unknown): Promise<McpToolResponse> {
+export async function handleUpdateWorkflow(args: unknown, context?: InstanceContext): Promise<McpToolResponse> {
   try {
-    const client = ensureApiConfigured();
+    const client = ensureApiConfigured(context);
     const input = updateWorkflowSchema.parse(args);
     const { id, ...updateData } = input;
-    
+
     // If nodes/connections are being updated, validate the structure
     if (updateData.nodes || updateData.connections) {
-      // Fetch current workflow if only partial update
-      let fullWorkflow = updateData as Partial<Workflow>;
-      
-      if (!updateData.nodes || !updateData.connections) {
-        const current = await client.getWorkflow(id);
-        fullWorkflow = {
-          ...current,
-          ...updateData
-        };
-      }
-      
+      // Always fetch current workflow for validation (need all fields like name)
+      const current = await client.getWorkflow(id);
+      const fullWorkflow = {
+        ...current,
+        ...updateData
+      };
+
+      // Validate workflow structure (n8n API expects FULL form: n8n-nodes-base.*)
       const errors = validateWorkflowStructure(fullWorkflow);
       if (errors.length > 0) {
         return {
@@ -418,15 +603,16 @@ export async function handleUpdateWorkflow(args: unknown): Promise<McpToolRespon
   }
 }
 
-export async function handleDeleteWorkflow(args: unknown): Promise<McpToolResponse> {
+export async function handleDeleteWorkflow(args: unknown, context?: InstanceContext): Promise<McpToolResponse> {
   try {
-    const client = ensureApiConfigured();
+    const client = ensureApiConfigured(context);
     const { id } = z.object({ id: z.string() }).parse(args);
-    
-    await client.deleteWorkflow(id);
-    
+
+    const deleted = await client.deleteWorkflow(id);
+
     return {
       success: true,
+      data: deleted,
       message: `Workflow ${id} deleted successfully`
     };
   } catch (error) {
@@ -453,16 +639,21 @@ export async function handleDeleteWorkflow(args: unknown): Promise<McpToolRespon
   }
 }
 
-export async function handleListWorkflows(args: unknown): Promise<McpToolResponse> {
+export async function handleListWorkflows(args: unknown, context?: InstanceContext): Promise<McpToolResponse> {
   try {
-    const client = ensureApiConfigured();
+    const client = ensureApiConfigured(context);
     const input = listWorkflowsSchema.parse(args || {});
-    
+
+    // Convert tags array to comma-separated string (n8n API format)
+    const tagsParam = input.tags && input.tags.length > 0
+      ? input.tags.join(',')
+      : undefined;
+
     const response = await client.listWorkflows({
       limit: input.limit || 100,
       cursor: input.cursor,
       active: input.active,
-      tags: input.tags,
+      tags: tagsParam as any,  // API expects string, not array
       projectId: input.projectId,
       excludePinnedData: input.excludePinnedData ?? true
     });
@@ -516,11 +707,12 @@ export async function handleListWorkflows(args: unknown): Promise<McpToolRespons
 }
 
 export async function handleValidateWorkflow(
-  args: unknown, 
-  repository: NodeRepository
+  args: unknown,
+  repository: NodeRepository,
+  context?: InstanceContext
 ): Promise<McpToolResponse> {
   try {
-    const client = ensureApiConfigured();
+    const client = ensureApiConfigured(context);
     const input = validateWorkflowSchema.parse(args);
     
     // First, fetch the workflow from n8n
@@ -574,7 +766,12 @@ export async function handleValidateWorkflow(
     if (validationResult.suggestions.length > 0) {
       response.suggestions = validationResult.suggestions;
     }
-    
+
+    // Track successfully validated workflows in telemetry
+    if (validationResult.valid) {
+      telemetry.trackWorkflowCreation(workflow, true);
+    }
+
     return {
       success: true,
       data: response
@@ -603,13 +800,181 @@ export async function handleValidateWorkflow(
   }
 }
 
+export async function handleAutofixWorkflow(
+  args: unknown,
+  repository: NodeRepository,
+  context?: InstanceContext
+): Promise<McpToolResponse> {
+  try {
+    const client = ensureApiConfigured(context);
+    const input = autofixWorkflowSchema.parse(args);
+
+    // First, fetch the workflow from n8n
+    const workflowResponse = await handleGetWorkflow({ id: input.id }, context);
+
+    if (!workflowResponse.success) {
+      return workflowResponse; // Return the error from fetching
+    }
+
+    const workflow = workflowResponse.data as Workflow;
+
+    // Create validator instance using the provided repository
+    const validator = new WorkflowValidator(repository, EnhancedConfigValidator);
+
+    // Run validation to identify issues
+    const validationResult = await validator.validateWorkflow(workflow, {
+      validateNodes: true,
+      validateConnections: true,
+      validateExpressions: true,
+      profile: 'ai-friendly'
+    });
+
+    // Check for expression format issues
+    const allFormatIssues: any[] = [];
+    for (const node of workflow.nodes) {
+      const formatContext = {
+        nodeType: node.type,
+        nodeName: node.name,
+        nodeId: node.id
+      };
+
+      const nodeFormatIssues = ExpressionFormatValidator.validateNodeParameters(
+        node.parameters,
+        formatContext
+      );
+
+      // Add node information to each format issue
+      const enrichedIssues = nodeFormatIssues.map(issue => ({
+        ...issue,
+        nodeName: node.name,
+        nodeId: node.id
+      }));
+
+      allFormatIssues.push(...enrichedIssues);
+    }
+
+    // Generate fixes using WorkflowAutoFixer
+    const autoFixer = new WorkflowAutoFixer(repository);
+    const fixResult = autoFixer.generateFixes(
+      workflow,
+      validationResult,
+      allFormatIssues,
+      {
+        applyFixes: input.applyFixes,
+        fixTypes: input.fixTypes,
+        confidenceThreshold: input.confidenceThreshold,
+        maxFixes: input.maxFixes
+      }
+    );
+
+    // If no fixes available
+    if (fixResult.fixes.length === 0) {
+      return {
+        success: true,
+        data: {
+          workflowId: workflow.id,
+          workflowName: workflow.name,
+          message: 'No automatic fixes available for this workflow',
+          validationSummary: {
+            errors: validationResult.errors.length,
+            warnings: validationResult.warnings.length
+          }
+        }
+      };
+    }
+
+    // If preview mode (applyFixes = false)
+    if (!input.applyFixes) {
+      return {
+        success: true,
+        data: {
+          workflowId: workflow.id,
+          workflowName: workflow.name,
+          preview: true,
+          fixesAvailable: fixResult.fixes.length,
+          fixes: fixResult.fixes,
+          summary: fixResult.summary,
+          stats: fixResult.stats,
+          message: `${fixResult.fixes.length} fixes available. Set applyFixes=true to apply them.`
+        }
+      };
+    }
+
+    // Apply fixes using the diff engine
+    if (fixResult.operations.length > 0) {
+      const updateResult = await handleUpdatePartialWorkflow(
+        {
+          id: workflow.id,
+          operations: fixResult.operations
+        },
+        context
+      );
+
+      if (!updateResult.success) {
+        return {
+          success: false,
+          error: 'Failed to apply fixes',
+          details: {
+            fixes: fixResult.fixes,
+            updateError: updateResult.error
+          }
+        };
+      }
+
+      return {
+        success: true,
+        data: {
+          workflowId: workflow.id,
+          workflowName: workflow.name,
+          fixesApplied: fixResult.fixes.length,
+          fixes: fixResult.fixes,
+          summary: fixResult.summary,
+          stats: fixResult.stats,
+          message: `Successfully applied ${fixResult.fixes.length} fixes to workflow "${workflow.name}"`
+        }
+      };
+    }
+
+    return {
+      success: true,
+      data: {
+        workflowId: workflow.id,
+        workflowName: workflow.name,
+        message: 'No fixes needed'
+      }
+    };
+
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      return {
+        success: false,
+        error: 'Invalid input',
+        details: { errors: error.errors }
+      };
+    }
+
+    if (error instanceof N8nApiError) {
+      return {
+        success: false,
+        error: getUserFriendlyErrorMessage(error),
+        code: error.code
+      };
+    }
+
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Unknown error occurred'
+    };
+  }
+}
+
 // Execution Management Handlers
 
-export async function handleTriggerWebhookWorkflow(args: unknown): Promise<McpToolResponse> {
+export async function handleTriggerWebhookWorkflow(args: unknown, context?: InstanceContext): Promise<McpToolResponse> {
   try {
-    const client = ensureApiConfigured();
+    const client = ensureApiConfigured(context);
     const input = triggerWebhookSchema.parse(args);
-    
+
     const webhookRequest: WebhookRequest = {
       webhookUrl: input.webhookUrl,
       httpMethod: input.httpMethod || 'POST',
@@ -617,9 +982,9 @@ export async function handleTriggerWebhookWorkflow(args: unknown): Promise<McpTo
       headers: input.headers,
       waitForResponse: input.waitForResponse ?? true
     };
-    
+
     const response = await client.triggerWebhook(webhookRequest);
-    
+
     return {
       success: true,
       data: response,
@@ -633,8 +998,35 @@ export async function handleTriggerWebhookWorkflow(args: unknown): Promise<McpTo
         details: { errors: error.errors }
       };
     }
-    
+
     if (error instanceof N8nApiError) {
+      // Try to extract execution context from error response
+      const errorData = error.details as any;
+      const executionId = errorData?.executionId || errorData?.id || errorData?.execution?.id;
+      const workflowId = errorData?.workflowId || errorData?.workflow?.id;
+
+      // If we have execution ID, provide specific guidance with n8n_get_execution
+      if (executionId) {
+        return {
+          success: false,
+          error: formatExecutionError(executionId, workflowId),
+          code: error.code,
+          executionId,
+          workflowId: workflowId || undefined
+        };
+      }
+
+      // No execution ID available - workflow likely didn't start
+      // Provide guidance to check recent executions
+      if (error.code === 'SERVER_ERROR' || error.statusCode && error.statusCode >= 500) {
+        return {
+          success: false,
+          error: formatNoExecutionError(),
+          code: error.code
+        };
+      }
+
+      // For other errors (auth, validation, etc), use standard message
       return {
         success: false,
         error: getUserFriendlyErrorMessage(error),
@@ -642,7 +1034,7 @@ export async function handleTriggerWebhookWorkflow(args: unknown): Promise<McpTo
         details: error.details as Record<string, unknown> | undefined
       };
     }
-    
+
     return {
       success: false,
       error: error instanceof Error ? error.message : 'Unknown error occurred'
@@ -650,19 +1042,75 @@ export async function handleTriggerWebhookWorkflow(args: unknown): Promise<McpTo
   }
 }
 
-export async function handleGetExecution(args: unknown): Promise<McpToolResponse> {
+export async function handleGetExecution(args: unknown, context?: InstanceContext): Promise<McpToolResponse> {
   try {
-    const client = ensureApiConfigured();
-    const { id, includeData } = z.object({ 
+    const client = ensureApiConfigured(context);
+
+    // Parse and validate input with new parameters
+    const schema = z.object({
       id: z.string(),
+      // New filtering parameters
+      mode: z.enum(['preview', 'summary', 'filtered', 'full']).optional(),
+      nodeNames: z.array(z.string()).optional(),
+      itemsLimit: z.number().optional(),
+      includeInputData: z.boolean().optional(),
+      // Legacy parameter (backward compatibility)
       includeData: z.boolean().optional()
-    }).parse(args);
-    
-    const execution = await client.getExecution(id, includeData || false);
-    
+    });
+
+    const params = schema.parse(args);
+    const { id, mode, nodeNames, itemsLimit, includeInputData, includeData } = params;
+
+    /**
+     * Map legacy includeData parameter to mode for backward compatibility
+     *
+     * Legacy behavior:
+     * - includeData: undefined -> minimal execution summary (no data)
+     * - includeData: false -> minimal execution summary (no data)
+     * - includeData: true -> full execution data
+     *
+     * New behavior mapping:
+     * - includeData: undefined -> no mode (minimal)
+     * - includeData: false -> no mode (minimal)
+     * - includeData: true -> mode: 'summary' (2 items per node, not full)
+     *
+     * Note: Legacy true behavior returned ALL data, which could exceed token limits.
+     * New behavior caps at 2 items for safety. Users can use mode: 'full' for old behavior.
+     */
+    let effectiveMode = mode;
+    if (!effectiveMode && includeData !== undefined) {
+      effectiveMode = includeData ? 'summary' : undefined;
+    }
+
+    // Determine if we need to fetch full data from API
+    // We fetch full data if any mode is specified (including preview) or legacy includeData is true
+    // Preview mode needs the data to analyze structure and generate recommendations
+    const fetchFullData = effectiveMode !== undefined || includeData === true;
+
+    // Fetch execution from n8n API
+    const execution = await client.getExecution(id, fetchFullData);
+
+    // If no filtering options specified, return original execution (backward compatibility)
+    if (!effectiveMode && !nodeNames && itemsLimit === undefined) {
+      return {
+        success: true,
+        data: execution
+      };
+    }
+
+    // Apply filtering using ExecutionProcessor
+    const filterOptions: ExecutionFilterOptions = {
+      mode: effectiveMode,
+      nodeNames,
+      itemsLimit,
+      includeInputData
+    };
+
+    const processedExecution = processExecution(execution, filterOptions);
+
     return {
       success: true,
-      data: execution
+      data: processedExecution
     };
   } catch (error) {
     if (error instanceof z.ZodError) {
@@ -672,7 +1120,7 @@ export async function handleGetExecution(args: unknown): Promise<McpToolResponse
         details: { errors: error.errors }
       };
     }
-    
+
     if (error instanceof N8nApiError) {
       return {
         success: false,
@@ -680,7 +1128,7 @@ export async function handleGetExecution(args: unknown): Promise<McpToolResponse
         code: error.code
       };
     }
-    
+
     return {
       success: false,
       error: error instanceof Error ? error.message : 'Unknown error occurred'
@@ -688,9 +1136,9 @@ export async function handleGetExecution(args: unknown): Promise<McpToolResponse
   }
 }
 
-export async function handleListExecutions(args: unknown): Promise<McpToolResponse> {
+export async function handleListExecutions(args: unknown, context?: InstanceContext): Promise<McpToolResponse> {
   try {
-    const client = ensureApiConfigured();
+    const client = ensureApiConfigured(context);
     const input = listExecutionsSchema.parse(args || {});
     
     const response = await client.listExecutions({
@@ -738,9 +1186,9 @@ export async function handleListExecutions(args: unknown): Promise<McpToolRespon
   }
 }
 
-export async function handleDeleteExecution(args: unknown): Promise<McpToolResponse> {
+export async function handleDeleteExecution(args: unknown, context?: InstanceContext): Promise<McpToolResponse> {
   try {
-    const client = ensureApiConfigured();
+    const client = ensureApiConfigured(context);
     const { id } = z.object({ id: z.string() }).parse(args);
     
     await client.deleteExecution(id);
@@ -775,9 +1223,9 @@ export async function handleDeleteExecution(args: unknown): Promise<McpToolRespo
 
 // System Tools Handlers
 
-export async function handleHealthCheck(): Promise<McpToolResponse> {
+export async function handleHealthCheck(context?: InstanceContext): Promise<McpToolResponse> {
   try {
-    const client = ensureApiConfigured();
+    const client = ensureApiConfigured(context);
     const health = await client.healthCheck();
     
     // Get MCP version from package.json
@@ -818,7 +1266,7 @@ export async function handleHealthCheck(): Promise<McpToolResponse> {
   }
 }
 
-export async function handleListAvailableTools(): Promise<McpToolResponse> {
+export async function handleListAvailableTools(context?: InstanceContext): Promise<McpToolResponse> {
   const tools = [
     {
       category: 'Workflow Management',
@@ -831,7 +1279,8 @@ export async function handleListAvailableTools(): Promise<McpToolResponse> {
         { name: 'n8n_update_workflow', description: 'Update existing workflows' },
         { name: 'n8n_delete_workflow', description: 'Delete workflows' },
         { name: 'n8n_list_workflows', description: 'List workflows with filters' },
-        { name: 'n8n_validate_workflow', description: 'Validate workflow from n8n instance' }
+        { name: 'n8n_validate_workflow', description: 'Validate workflow from n8n instance' },
+        { name: 'n8n_autofix_workflow', description: 'Automatically fix common workflow errors' }
       ]
     },
     {
@@ -876,7 +1325,7 @@ export async function handleListAvailableTools(): Promise<McpToolResponse> {
 }
 
 // Handler: n8n_diagnostic
-export async function handleDiagnostic(request: any): Promise<McpToolResponse> {
+export async function handleDiagnostic(request: any, context?: InstanceContext): Promise<McpToolResponse> {
   const verbose = request.params?.arguments?.verbose || false;
   
   // Check environment variables
@@ -890,7 +1339,7 @@ export async function handleDiagnostic(request: any): Promise<McpToolResponse> {
   // Check API configuration
   const apiConfig = getN8nApiConfig();
   const apiConfigured = apiConfig !== null;
-  const apiClient = getN8nApiClient();
+  const apiClient = getN8nApiClient(context);
   
   // Test API connectivity if configured
   let apiStatus = {

src/mcp/handlers-workflow-diff.ts

@@ -10,6 +10,7 @@ import { WorkflowDiffEngine } from '../services/workflow-diff-engine';
 import { getN8nApiClient } from './handlers-n8n-manager';
 import { N8nApiError, getUserFriendlyErrorMessage } from '../utils/n8n-errors';
 import { logger } from '../utils/logger';
+import { InstanceContext } from '../types/instance-context';
 
 // Zod schema for the diff request
 const workflowDiffSchema = z.object({
@@ -21,24 +22,34 @@ const workflowDiffSchema = z.object({
     node: z.any().optional(),
     nodeId: z.string().optional(),
     nodeName: z.string().optional(),
-    changes: z.any().optional(),
+    updates: z.any().optional(),
     position: z.tuple([z.number(), z.number()]).optional(),
     // Connection operations
     source: z.string().optional(),
     target: z.string().optional(),
+    from: z.string().optional(),  // For rewireConnection
+    to: z.string().optional(),    // For rewireConnection
     sourceOutput: z.string().optional(),
     targetInput: z.string().optional(),
     sourceIndex: z.number().optional(),
     targetIndex: z.number().optional(),
+    // Smart parameters (Phase 1 UX improvement)
+    branch: z.enum(['true', 'false']).optional(),
+    case: z.number().optional(),
+    ignoreErrors: z.boolean().optional(),
+    // Connection cleanup operations
+    dryRun: z.boolean().optional(),
+    connections: z.any().optional(),
     // Metadata operations
     settings: z.any().optional(),
     name: z.string().optional(),
     tag: z.string().optional(),
   })),
   validateOnly: z.boolean().optional(),
+  continueOnError: z.boolean().optional(),
 });
 
-export async function handleUpdatePartialWorkflow(args: unknown): Promise<McpToolResponse> {
+export async function handleUpdatePartialWorkflow(args: unknown, context?: InstanceContext): Promise<McpToolResponse> {
   try {
     // Debug logging (only in debug mode)
     if (process.env.DEBUG_MCP === 'true') {
@@ -54,7 +65,7 @@ export async function handleUpdatePartialWorkflow(args: unknown): Promise<McpToo
     const input = workflowDiffSchema.parse(args);
     
     // Get API client
-    const client = getN8nApiClient();
+    const client = getN8nApiClient(context);
     if (!client) {
       return {
         success: false,
@@ -79,17 +90,28 @@ export async function handleUpdatePartialWorkflow(args: unknown): Promise<McpToo
     
     // Apply diff operations
     const diffEngine = new WorkflowDiffEngine();
-    const diffResult = await diffEngine.applyDiff(workflow, input as WorkflowDiffRequest);
-    
+    const diffRequest = input as WorkflowDiffRequest;
+    const diffResult = await diffEngine.applyDiff(workflow, diffRequest);
+
+    // Check if this is a complete failure or partial success in continueOnError mode
     if (!diffResult.success) {
-      return {
-        success: false,
-        error: 'Failed to apply diff operations',
-        details: {
-          errors: diffResult.errors,
-          operationsApplied: diffResult.operationsApplied
-        }
-      };
+      // In continueOnError mode, partial success is still valuable
+      if (diffRequest.continueOnError && diffResult.workflow && diffResult.operationsApplied && diffResult.operationsApplied > 0) {
+        logger.info(`continueOnError mode: Applying ${diffResult.operationsApplied} successful operations despite ${diffResult.failed?.length || 0} failures`);
+        // Continue to update workflow with partial changes
+      } else {
+        // Complete failure - return error
+        return {
+          success: false,
+          error: 'Failed to apply diff operations',
+          details: {
+            errors: diffResult.errors,
+            operationsApplied: diffResult.operationsApplied,
+            applied: diffResult.applied,
+            failed: diffResult.failed
+          }
+        };
+      }
     }
     
     // If validateOnly, return validation result
@@ -115,7 +137,10 @@ export async function handleUpdatePartialWorkflow(args: unknown): Promise<McpToo
         details: {
           operationsApplied: diffResult.operationsApplied,
           workflowId: updatedWorkflow.id,
-          workflowName: updatedWorkflow.name
+          workflowName: updatedWorkflow.name,
+          applied: diffResult.applied,
+          failed: diffResult.failed,
+          errors: diffResult.errors
         }
       };
     } catch (error) {

src/mcp/index.ts

@@ -2,6 +2,8 @@
 
 import { N8NDocumentationMCPServer } from './server';
 import { logger } from '../utils/logger';
+import { TelemetryConfigManager } from '../telemetry/config-manager';
+import { existsSync } from 'fs';
 
 // Add error details to stderr for Claude Desktop debugging
 process.on('uncaughtException', (error) => {
@@ -20,9 +22,73 @@ process.on('unhandledRejection', (reason, promise) => {
   process.exit(1);
 });
 
+/**
+ * Detects if running in a container environment (Docker, Podman, Kubernetes, etc.)
+ * Uses multiple detection methods for robustness:
+ * 1. Environment variables (IS_DOCKER, IS_CONTAINER with multiple formats)
+ * 2. Filesystem markers (/.dockerenv, /run/.containerenv)
+ */
+function isContainerEnvironment(): boolean {
+  // Check environment variables with multiple truthy formats
+  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;
+  }
+
+  // Fallback: Check filesystem markers
+  // /.dockerenv exists in Docker containers
+  // /run/.containerenv exists in Podman containers
+  try {
+    return existsSync('/.dockerenv') || existsSync('/run/.containerenv');
+  } catch (error) {
+    // If filesystem check fails, assume not in container
+    logger.debug('Container detection filesystem check failed:', error);
+    return false;
+  }
+}
+
 async function main() {
+  // Handle telemetry CLI commands
+  const args = process.argv.slice(2);
+  if (args.length > 0 && args[0] === 'telemetry') {
+    const telemetryConfig = 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';
-  
+
   try {
     // Only show debug messages in HTTP mode to avoid corrupting stdio communication
     if (mode === 'http') {
@@ -56,6 +122,67 @@ async function main() {
     } else {
       // Stdio mode - for local Claude Desktop
       const server = new N8NDocumentationMCPServer();
+
+      // Graceful shutdown handler (fixes Issue #277)
+      let isShuttingDown = false;
+      const shutdown = async (signal: string = 'UNKNOWN') => {
+        if (isShuttingDown) return; // Prevent multiple shutdown calls
+        isShuttingDown = true;
+
+        try {
+          logger.info(`Shutdown initiated by: ${signal}`);
+
+          await server.shutdown();
+
+          // Close stdin to signal we're done reading
+          if (process.stdin && !process.stdin.destroyed) {
+            process.stdin.pause();
+            process.stdin.destroy();
+          }
+
+          // Exit with timeout to ensure we don't hang
+          // Increased to 1000ms for slower systems
+          setTimeout(() => {
+            logger.warn('Shutdown timeout exceeded, forcing exit');
+            process.exit(0);
+          }, 1000).unref();
+
+          // Let the timeout handle the exit for graceful shutdown
+          // (removed immediate exit to allow cleanup to complete)
+        } catch (error) {
+          logger.error('Error during shutdown:', error);
+          process.exit(1);
+        }
+      };
+
+      // Handle termination signals (fixes Issue #277)
+      // Signal handling strategy:
+      // - Claude Desktop (Windows/macOS/Linux): stdin handlers + signal handlers
+      //   Primary: stdin close when Claude quits | Fallback: SIGTERM/SIGINT/SIGHUP
+      // - Container environments: signal handlers ONLY
+      //   stdin closed in detached mode would trigger immediate shutdown
+      //   Container detection via IS_DOCKER/IS_CONTAINER env vars + filesystem markers
+      // - Manual execution: Both stdin and signal handlers work
+      process.on('SIGTERM', () => shutdown('SIGTERM'));
+      process.on('SIGINT', () => shutdown('SIGINT'));
+      process.on('SIGHUP', () => shutdown('SIGHUP'));
+
+      // Handle stdio disconnect - PRIMARY shutdown mechanism for Claude Desktop
+      // Skip in container environments (Docker, Kubernetes, Podman) to prevent
+      // premature shutdown when stdin is closed in detached mode.
+      // Containers rely on signal handlers (SIGTERM/SIGINT/SIGHUP) for proper shutdown.
+      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.error('Failed to register stdin handlers, using signal handlers only:', error);
+          // Continue - signal handlers will still work
+        }
+      }
+
       await server.run();
     }
   } catch (error) {

src/mcp/server.ts

@@ -27,13 +27,16 @@ import * as n8nHandlers from './handlers-n8n-manager';
 import { handleUpdatePartialWorkflow } from './handlers-workflow-diff';
 import { getToolDocumentation, getToolsOverview } from './tools-documentation';
 import { PROJECT_VERSION } from '../utils/version';
-import { normalizeNodeType, getNodeTypeAlternatives, getWorkflowNodeType } from '../utils/node-utils';
+import { getNodeTypeAlternatives, getWorkflowNodeType } from '../utils/node-utils';
+import { NodeTypeNormalizer } from '../utils/node-type-normalizer';
 import { ToolValidation, Validator, ValidationError } from '../utils/validation-schemas';
-import { 
-  negotiateProtocolVersion, 
+import {
+  negotiateProtocolVersion,
   logProtocolNegotiation,
-  STANDARD_PROTOCOL_VERSION 
+  STANDARD_PROTOCOL_VERSION
 } from '../utils/protocol-version';
+import { InstanceContext } from '../types/instance-context';
+import { telemetry } from '../telemetry';
 
 interface NodeRow {
   node_type: string;
@@ -61,8 +64,12 @@ export class N8NDocumentationMCPServer {
   private initialized: Promise<void>;
   private cache = new SimpleCache();
   private clientInfo: any = null;
+  private instanceContext?: InstanceContext;
+  private previousTool: string | null = null;
+  private previousToolTimestamp: number = Date.now();
 
-  constructor() {
+  constructor(instanceContext?: InstanceContext) {
+    this.instanceContext = instanceContext;
     // Check for test environment first
     const envDbPath = process.env.NODE_DB_PATH;
     let dbPath: string | null = null;
@@ -131,6 +138,10 @@ export class N8NDocumentationMCPServer {
       
       this.repository = new NodeRepository(this.db);
       this.templateService = new TemplateService(this.db);
+
+      // Initialize similarity services for enhanced validation
+      EnhancedConfigValidator.initializeSimilarityServices(this.repository);
+
       logger.info(`Initialized database from: ${dbPath}`);
     } catch (error) {
       logger.error('Failed to initialize database:', error);
@@ -173,7 +184,10 @@ export class N8NDocumentationMCPServer {
         clientCapabilities,
         clientInfo
       });
-      
+
+      // Track session start
+      telemetry.trackSessionStart();
+
       // Store client info for later use
       this.clientInfo = clientInfo;
       
@@ -213,13 +227,30 @@ export class N8NDocumentationMCPServer {
     this.server.setRequestHandler(ListToolsRequestSchema, async (request) => {
       // Combine documentation tools with management tools if API is configured
       let tools = [...n8nDocumentationToolsFinal];
-      const isConfigured = isN8nApiConfigured();
-      
-      if (isConfigured) {
+
+      // Check if n8n API tools should be available
+      // 1. Environment variables (backward compatibility)
+      // 2. Instance context (multi-tenant support)
+      // 3. Multi-tenant mode enabled (always show tools, runtime checks will handle auth)
+      const hasEnvConfig = isN8nApiConfigured();
+      const hasInstanceConfig = !!(this.instanceContext?.n8nApiUrl && this.instanceContext?.n8nApiKey);
+      const isMultiTenantEnabled = process.env.ENABLE_MULTI_TENANT === 'true';
+
+      const shouldIncludeManagementTools = hasEnvConfig || hasInstanceConfig || isMultiTenantEnabled;
+
+      if (shouldIncludeManagementTools) {
         tools.push(...n8nManagementTools);
-        logger.debug(`Tool listing: ${tools.length} tools available (${n8nDocumentationToolsFinal.length} documentation + ${n8nManagementTools.length} management)`);
+        logger.debug(`Tool listing: ${tools.length} tools available (${n8nDocumentationToolsFinal.length} documentation + ${n8nManagementTools.length} management)`, {
+          hasEnvConfig,
+          hasInstanceConfig,
+          isMultiTenantEnabled
+        });
       } else {
-        logger.debug(`Tool listing: ${tools.length} tools available (documentation only)`);
+        logger.debug(`Tool listing: ${tools.length} tools available (documentation only)`, {
+          hasEnvConfig,
+          hasInstanceConfig,
+          isMultiTenantEnabled
+        });
       }
       
       // Check if client is n8n (from initialization)
@@ -298,8 +329,23 @@ export class N8NDocumentationMCPServer {
       
       try {
         logger.debug(`Executing tool: ${name}`, { args: processedArgs });
+        const startTime = Date.now();
         const result = await this.executeTool(name, processedArgs);
+        const duration = Date.now() - startTime;
         logger.debug(`Tool ${name} executed successfully`);
+
+        // Track tool usage and sequence
+        telemetry.trackToolUsage(name, true, duration);
+
+        // Track tool sequence if there was a previous tool
+        if (this.previousTool) {
+          const timeDelta = Date.now() - this.previousToolTimestamp;
+          telemetry.trackToolSequence(this.previousTool, name, timeDelta);
+        }
+
+        // Update previous tool tracking
+        this.previousTool = name;
+        this.previousToolTimestamp = Date.now();
         
         // Ensure the result is properly formatted for MCP
         let responseText: string;
@@ -346,7 +392,26 @@ export class N8NDocumentationMCPServer {
       } catch (error) {
         logger.error(`Error executing tool ${name}`, error);
         const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-        
+
+        // Track tool error
+        telemetry.trackToolUsage(name, false);
+        telemetry.trackError(
+          error instanceof Error ? error.constructor.name : 'UnknownError',
+          `tool_execution`,
+          name,
+          errorMessage
+        );
+
+        // Track tool sequence even for errors
+        if (this.previousTool) {
+          const timeDelta = Date.now() - this.previousToolTimestamp;
+          telemetry.trackToolSequence(this.previousTool, name, timeDelta);
+        }
+
+        // Update previous tool tracking (even for failed tools)
+        this.previousTool = name;
+        this.previousToolTimestamp = Date.now();
+
         // Provide more helpful error messages for common n8n issues
         let helpfulMessage = `Error executing tool ${name}: ${errorMessage}`;
         
@@ -496,6 +561,7 @@ export class N8NDocumentationMCPServer {
       case 'n8n_update_full_workflow':
       case 'n8n_delete_workflow':
       case 'n8n_validate_workflow':
+      case 'n8n_autofix_workflow':
       case 'n8n_get_execution':
       case 'n8n_delete_execution':
         validationResult = ToolValidation.validateWorkflowId(args);
@@ -533,16 +599,23 @@ export class N8NDocumentationMCPServer {
    */
   private validateToolParamsBasic(toolName: string, args: any, requiredParams: string[]): void {
     const missing: string[] = [];
-    
+    const invalid: string[] = [];
+
     for (const param of requiredParams) {
       if (!(param in args) || args[param] === undefined || args[param] === null) {
         missing.push(param);
+      } else if (typeof args[param] === 'string' && args[param].trim() === '') {
+        invalid.push(`${param} (empty string)`);
       }
     }
-    
+
     if (missing.length > 0) {
       throw new Error(`Missing required parameters for ${toolName}: ${missing.join(', ')}. Please provide the required parameters to use this tool.`);
     }
+
+    if (invalid.length > 0) {
+      throw new Error(`Invalid parameters for ${toolName}: ${invalid.join(', ')}. String parameters cannot be empty.`);
+    }
   }
 
   /**
@@ -648,7 +721,7 @@ export class N8NDocumentationMCPServer {
         this.validateToolParams(name, args, ['query']);
         // Convert limit to number if provided, otherwise use default
         const limit = args.limit !== undefined ? Number(args.limit) || 20 : 20;
-        return this.searchNodes(args.query, limit, { mode: args.mode });
+        return this.searchNodes(args.query, limit, { mode: args.mode, includeExamples: args.includeExamples });
       case 'list_ai_tools':
         // No required parameters
         return this.listAITools();
@@ -660,14 +733,11 @@ export class N8NDocumentationMCPServer {
         return this.getDatabaseStatistics();
       case 'get_node_essentials':
         this.validateToolParams(name, args, ['nodeType']);
-        return this.getNodeEssentials(args.nodeType);
+        return this.getNodeEssentials(args.nodeType, args.includeExamples);
       case 'search_node_properties':
         this.validateToolParams(name, args, ['nodeType', 'query']);
         const maxResults = args.maxResults !== undefined ? Number(args.maxResults) || 20 : 20;
         return this.searchNodeProperties(args.nodeType, args.query, maxResults);
-      case 'get_node_for_task':
-        this.validateToolParams(name, args, ['task']);
-        return this.getNodeForTask(args.task);
       case 'list_tasks':
         // No required parameters
         return this.listTasks(args.category);
@@ -778,57 +848,62 @@ export class N8NDocumentationMCPServer {
       // n8n Management Tools (if API is configured)
       case 'n8n_create_workflow':
         this.validateToolParams(name, args, ['name', 'nodes', 'connections']);
-        return n8nHandlers.handleCreateWorkflow(args);
+        return n8nHandlers.handleCreateWorkflow(args, this.instanceContext);
       case 'n8n_get_workflow':
         this.validateToolParams(name, args, ['id']);
-        return n8nHandlers.handleGetWorkflow(args);
+        return n8nHandlers.handleGetWorkflow(args, this.instanceContext);
       case 'n8n_get_workflow_details':
         this.validateToolParams(name, args, ['id']);
-        return n8nHandlers.handleGetWorkflowDetails(args);
+        return n8nHandlers.handleGetWorkflowDetails(args, this.instanceContext);
       case 'n8n_get_workflow_structure':
         this.validateToolParams(name, args, ['id']);
-        return n8nHandlers.handleGetWorkflowStructure(args);
+        return n8nHandlers.handleGetWorkflowStructure(args, this.instanceContext);
       case 'n8n_get_workflow_minimal':
         this.validateToolParams(name, args, ['id']);
-        return n8nHandlers.handleGetWorkflowMinimal(args);
+        return n8nHandlers.handleGetWorkflowMinimal(args, this.instanceContext);
       case 'n8n_update_full_workflow':
         this.validateToolParams(name, args, ['id']);
-        return n8nHandlers.handleUpdateWorkflow(args);
+        return n8nHandlers.handleUpdateWorkflow(args, this.instanceContext);
       case 'n8n_update_partial_workflow':
         this.validateToolParams(name, args, ['id', 'operations']);
-        return handleUpdatePartialWorkflow(args);
+        return handleUpdatePartialWorkflow(args, this.instanceContext);
       case 'n8n_delete_workflow':
         this.validateToolParams(name, args, ['id']);
-        return n8nHandlers.handleDeleteWorkflow(args);
+        return n8nHandlers.handleDeleteWorkflow(args, this.instanceContext);
       case 'n8n_list_workflows':
         // No required parameters
-        return n8nHandlers.handleListWorkflows(args);
+        return n8nHandlers.handleListWorkflows(args, this.instanceContext);
       case 'n8n_validate_workflow':
         this.validateToolParams(name, args, ['id']);
         await this.ensureInitialized();
         if (!this.repository) throw new Error('Repository not initialized');
-        return n8nHandlers.handleValidateWorkflow(args, this.repository);
+        return n8nHandlers.handleValidateWorkflow(args, this.repository, this.instanceContext);
+      case 'n8n_autofix_workflow':
+        this.validateToolParams(name, args, ['id']);
+        await this.ensureInitialized();
+        if (!this.repository) throw new Error('Repository not initialized');
+        return n8nHandlers.handleAutofixWorkflow(args, this.repository, this.instanceContext);
       case 'n8n_trigger_webhook_workflow':
         this.validateToolParams(name, args, ['webhookUrl']);
-        return n8nHandlers.handleTriggerWebhookWorkflow(args);
+        return n8nHandlers.handleTriggerWebhookWorkflow(args, this.instanceContext);
       case 'n8n_get_execution':
         this.validateToolParams(name, args, ['id']);
-        return n8nHandlers.handleGetExecution(args);
+        return n8nHandlers.handleGetExecution(args, this.instanceContext);
       case 'n8n_list_executions':
         // No required parameters
-        return n8nHandlers.handleListExecutions(args);
+        return n8nHandlers.handleListExecutions(args, this.instanceContext);
       case 'n8n_delete_execution':
         this.validateToolParams(name, args, ['id']);
-        return n8nHandlers.handleDeleteExecution(args);
+        return n8nHandlers.handleDeleteExecution(args, this.instanceContext);
       case 'n8n_health_check':
         // No required parameters
-        return n8nHandlers.handleHealthCheck();
+        return n8nHandlers.handleHealthCheck(this.instanceContext);
       case 'n8n_list_available_tools':
         // No required parameters
-        return n8nHandlers.handleListAvailableTools();
+        return n8nHandlers.handleListAvailableTools(this.instanceContext);
       case 'n8n_diagnostic':
         // No required parameters
-        return n8nHandlers.handleDiagnostic({ params: { arguments: args } });
+        return n8nHandlers.handleDiagnostic({ params: { arguments: args } }, this.instanceContext);
         
       default:
         throw new Error(`Unknown tool: ${name}`);
@@ -897,9 +972,9 @@ export class N8NDocumentationMCPServer {
   private async getNodeInfo(nodeType: string): Promise<any> {
     await this.ensureInitialized();
     if (!this.repository) throw new Error('Repository not initialized');
-    
-    // First try with normalized type
-    const normalizedType = normalizeNodeType(nodeType);
+
+    // First try with normalized type (repository will also normalize internally)
+    const normalizedType = NodeTypeNormalizer.normalizeToFullForm(nodeType);
     let node = this.repository.getNode(normalizedType);
     
     if (!node && normalizedType !== nodeType) {
@@ -924,47 +999,48 @@ export class N8NDocumentationMCPServer {
       throw new Error(`Node ${nodeType} not found`);
     }
     
-    // Add AI tool capabilities information
+    // Add AI tool capabilities information with null safety
     const aiToolCapabilities = {
       canBeUsedAsTool: true, // Any node can be used as a tool in n8n
-      hasUsableAsToolProperty: node.isAITool,
-      requiresEnvironmentVariable: !node.isAITool && node.package !== 'n8n-nodes-base',
+      hasUsableAsToolProperty: node.isAITool ?? false,
+      requiresEnvironmentVariable: !(node.isAITool ?? false) && node.package !== 'n8n-nodes-base',
       toolConnectionType: 'ai_tool',
       commonToolUseCases: this.getCommonAIToolUseCases(node.nodeType),
-      environmentRequirement: node.package !== 'n8n-nodes-base' ? 
-        'N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true' : 
+      environmentRequirement: node.package && node.package !== 'n8n-nodes-base' ?
+        'N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true' :
         null
     };
-    
-    // Process outputs to provide clear mapping
+
+    // Process outputs to provide clear mapping with null safety
     let outputs = undefined;
-    if (node.outputNames && node.outputNames.length > 0) {
+    if (node.outputNames && Array.isArray(node.outputNames) && node.outputNames.length > 0) {
       outputs = node.outputNames.map((name: string, index: number) => {
         // Special handling for loop nodes like SplitInBatches
         const descriptions = this.getOutputDescriptions(node.nodeType, name, index);
         return {
           index,
           name,
-          description: descriptions.description,
-          connectionGuidance: descriptions.connectionGuidance
+          description: descriptions?.description ?? '',
+          connectionGuidance: descriptions?.connectionGuidance ?? ''
         };
       });
     }
-    
+
     return {
       ...node,
-      workflowNodeType: getWorkflowNodeType(node.package, node.nodeType),
+      workflowNodeType: getWorkflowNodeType(node.package ?? 'n8n-nodes-base', node.nodeType),
       aiToolCapabilities,
       outputs
     };
   }
 
   private async searchNodes(
-    query: string, 
+    query: string,
     limit: number = 20,
-    options?: { 
+    options?: {
       mode?: 'OR' | 'AND' | 'FUZZY';
       includeSource?: boolean;
+      includeExamples?: boolean;
     }
   ): Promise<any> {
     await this.ensureInitialized();
@@ -990,16 +1066,23 @@ export class N8NDocumentationMCPServer {
     
     if (ftsExists) {
       // Use FTS5 search with normalized query
-      return this.searchNodesFTS(normalizedQuery, limit, searchMode);
+      logger.debug(`Using FTS5 search with includeExamples=${options?.includeExamples}`);
+      return this.searchNodesFTS(normalizedQuery, limit, searchMode, options);
     } else {
       // Fallback to LIKE search with normalized query
-      return this.searchNodesLIKE(normalizedQuery, limit);
+      logger.debug('Using LIKE search (no FTS5)');
+      return this.searchNodesLIKE(normalizedQuery, limit, options);
     }
   }
-  
-  private async searchNodesFTS(query: string, limit: number, mode: 'OR' | 'AND' | 'FUZZY'): Promise<any> {
+
+  private async searchNodesFTS(
+    query: string,
+    limit: number,
+    mode: 'OR' | 'AND' | 'FUZZY',
+    options?: { includeSource?: boolean; includeExamples?: boolean; }
+  ): Promise<any> {
     if (!this.db) throw new Error('Database not initialized');
-    
+
     // Clean and prepare the query
     const cleanedQuery = query.trim();
     if (!cleanedQuery) {
@@ -1098,12 +1181,43 @@ export class N8NDocumentationMCPServer {
         })),
         totalCount: scoredNodes.length
       };
-      
+
       // Only include mode if it's not the default
       if (mode !== 'OR') {
         result.mode = mode;
       }
-      
+
+      // Add examples if requested
+      if (options && options.includeExamples) {
+        try {
+          for (const nodeResult of result.results) {
+            const examples = this.db!.prepare(`
+              SELECT
+                parameters_json,
+                template_name,
+                template_views
+              FROM template_node_configs
+              WHERE node_type = ?
+              ORDER BY rank
+              LIMIT 2
+            `).all(nodeResult.workflowNodeType) as any[];
+
+            if (examples.length > 0) {
+              nodeResult.examples = examples.map((ex: any) => ({
+                configuration: JSON.parse(ex.parameters_json),
+                template: ex.template_name,
+                views: ex.template_views
+              }));
+            }
+          }
+        } catch (error: any) {
+          logger.error(`Failed to add examples:`, error);
+        }
+      }
+
+      // Track search query telemetry
+      telemetry.trackSearchQuery(query, scoredNodes.length, mode ?? 'OR');
+
       return result;
       
     } catch (error: any) {
@@ -1116,6 +1230,10 @@ export class N8NDocumentationMCPServer {
         
         // For problematic queries, use LIKE search with mode info
         const likeResult = await this.searchNodesLIKE(query, limit);
+
+        // Track search query telemetry for fallback
+        telemetry.trackSearchQuery(query, likeResult.results?.length ?? 0, `${mode}_LIKE_FALLBACK`);
+
         return {
           ...likeResult,
           mode
@@ -1273,24 +1391,28 @@ export class N8NDocumentationMCPServer {
     return dp[m][n];
   }
   
-  private async searchNodesLIKE(query: string, limit: number): Promise<any> {
+  private async searchNodesLIKE(
+    query: string,
+    limit: number,
+    options?: { includeSource?: boolean; includeExamples?: boolean; }
+  ): Promise<any> {
     if (!this.db) throw new Error('Database not initialized');
-    
+
     // This is the existing LIKE-based implementation
     // Handle exact phrase searches with quotes
     if (query.startsWith('"') && query.endsWith('"')) {
       const exactPhrase = query.slice(1, -1);
       const nodes = this.db!.prepare(`
-        SELECT * FROM nodes 
+        SELECT * FROM nodes
         WHERE node_type LIKE ? OR display_name LIKE ? OR description LIKE ?
         LIMIT ?
       `).all(`%${exactPhrase}%`, `%${exactPhrase}%`, `%${exactPhrase}%`, limit * 3) as NodeRow[];
-      
+
       // Apply relevance ranking for exact phrase search
       const rankedNodes = this.rankSearchResults(nodes, exactPhrase, limit);
-      
-      return { 
-        query, 
+
+      const result: any = {
+        query,
         results: rankedNodes.map(node => ({
           nodeType: node.node_type,
           workflowNodeType: getWorkflowNodeType(node.package_name, node.node_type),
@@ -1298,9 +1420,39 @@ export class N8NDocumentationMCPServer {
           description: node.description,
           category: node.category,
           package: node.package_name
-        })), 
-        totalCount: rankedNodes.length 
+        })),
+        totalCount: rankedNodes.length
       };
+
+      // Add examples if requested
+      if (options?.includeExamples) {
+        for (const nodeResult of result.results) {
+          try {
+            const examples = this.db!.prepare(`
+              SELECT
+                parameters_json,
+                template_name,
+                template_views
+              FROM template_node_configs
+              WHERE node_type = ?
+              ORDER BY rank
+              LIMIT 2
+            `).all(nodeResult.workflowNodeType) as any[];
+
+            if (examples.length > 0) {
+              nodeResult.examples = examples.map((ex: any) => ({
+                configuration: JSON.parse(ex.parameters_json),
+                template: ex.template_name,
+                views: ex.template_views
+              }));
+            }
+          } catch (error: any) {
+            logger.warn(`Failed to fetch examples for ${nodeResult.nodeType}:`, error.message);
+          }
+        }
+      }
+
+      return result;
     }
     
     // Split into words for normal search
@@ -1327,8 +1479,8 @@ export class N8NDocumentationMCPServer {
     
     // Apply relevance ranking
     const rankedNodes = this.rankSearchResults(nodes, query, limit);
-    
-    return {
+
+    const result: any = {
       query,
       results: rankedNodes.map(node => ({
         nodeType: node.node_type,
@@ -1340,6 +1492,36 @@ export class N8NDocumentationMCPServer {
       })),
       totalCount: rankedNodes.length
     };
+
+    // Add examples if requested
+    if (options?.includeExamples) {
+      for (const nodeResult of result.results) {
+        try {
+          const examples = this.db!.prepare(`
+            SELECT
+              parameters_json,
+              template_name,
+              template_views
+            FROM template_node_configs
+            WHERE node_type = ?
+            ORDER BY rank
+            LIMIT 2
+          `).all(nodeResult.workflowNodeType) as any[];
+
+          if (examples.length > 0) {
+            nodeResult.examples = examples.map((ex: any) => ({
+              configuration: JSON.parse(ex.parameters_json),
+              template: ex.template_name,
+              views: ex.template_views
+            }));
+          }
+        } catch (error: any) {
+          logger.warn(`Failed to fetch examples for ${nodeResult.nodeType}:`, error.message);
+        }
+      }
+    }
+
+    return result;
   }
 
   private calculateRelevance(node: NodeRow, query: string): string {
@@ -1528,9 +1710,9 @@ export class N8NDocumentationMCPServer {
   private async getNodeDocumentation(nodeType: string): Promise<any> {
     await this.ensureInitialized();
     if (!this.db) throw new Error('Database not initialized');
-    
+
     // First try with normalized type
-    const normalizedType = normalizeNodeType(nodeType);
+    const normalizedType = NodeTypeNormalizer.normalizeToFullForm(nodeType);
     let node = this.db!.prepare(`
       SELECT node_type, display_name, documentation, description 
       FROM nodes 
@@ -1565,23 +1747,25 @@ export class N8NDocumentationMCPServer {
       throw new Error(`Node ${nodeType} not found`);
     }
     
-    // If no documentation, generate fallback
+    // If no documentation, generate fallback with null safety
     if (!node.documentation) {
       const essentials = await this.getNodeEssentials(nodeType);
-      
+
       return {
         nodeType: node.node_type,
-        displayName: node.display_name,
+        displayName: node.display_name || 'Unknown Node',
         documentation: `
-# ${node.display_name}
+# ${node.display_name || 'Unknown Node'}
 
 ${node.description || 'No description available.'}
 
 ## Common Properties
 
-${essentials.commonProperties.map((p: any) => 
-  `### ${p.displayName}\n${p.description || `Type: ${p.type}`}`
-).join('\n\n')}
+${essentials?.commonProperties?.length > 0 ?
+  essentials.commonProperties.map((p: any) =>
+    `### ${p.displayName || 'Property'}\n${p.description || `Type: ${p.type || 'unknown'}`}`
+  ).join('\n\n') :
+  'No common properties available.'}
 
 ## Note
 Full documentation is being prepared. For now, use get_node_essentials for configuration help.
@@ -1589,10 +1773,10 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
         hasDocumentation: false
       };
     }
-    
+
     return {
       nodeType: node.node_type,
-      displayName: node.display_name,
+      displayName: node.display_name || 'Unknown Node',
       documentation: node.documentation,
       hasDocumentation: true,
     };
@@ -1654,18 +1838,18 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
     };
   }
 
-  private async getNodeEssentials(nodeType: string): Promise<any> {
+  private async getNodeEssentials(nodeType: string, includeExamples?: boolean): Promise<any> {
     await this.ensureInitialized();
     if (!this.repository) throw new Error('Repository not initialized');
-    
-    // Check cache first
-    const cacheKey = `essentials:${nodeType}`;
+
+    // Check cache first (cache key includes includeExamples)
+    const cacheKey = `essentials:${nodeType}:${includeExamples ? 'withExamples' : 'basic'}`;
     const cached = this.cache.get(cacheKey);
     if (cached) return cached;
     
     // Get the full node information
     // First try with normalized type
-    const normalizedType = normalizeNodeType(nodeType);
+    const normalizedType = NodeTypeNormalizer.normalizeToFullForm(nodeType);
     let node = this.repository.getNode(normalizedType);
     
     if (!node && normalizedType !== nodeType) {
@@ -1701,12 +1885,12 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
     
     const result = {
       nodeType: node.nodeType,
-      workflowNodeType: getWorkflowNodeType(node.package, node.nodeType),
+      workflowNodeType: getWorkflowNodeType(node.package ?? 'n8n-nodes-base', node.nodeType),
       displayName: node.displayName,
       description: node.description,
       category: node.category,
-      version: node.version || '1',
-      isVersioned: node.isVersioned || false,
+      version: node.version ?? '1',
+      isVersioned: node.isVersioned ?? false,
       requiredProperties: essentials.required,
       commonProperties: essentials.common,
       operations: operations.map((op: any) => ({
@@ -1718,28 +1902,74 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
       // Examples removed - use validate_node_operation for working configurations
       metadata: {
         totalProperties: allProperties.length,
-        isAITool: node.isAITool,
-        isTrigger: node.isTrigger,
-        isWebhook: node.isWebhook,
+        isAITool: node.isAITool ?? false,
+        isTrigger: node.isTrigger ?? false,
+        isWebhook: node.isWebhook ?? false,
         hasCredentials: node.credentials ? true : false,
-        package: node.package,
-        developmentStyle: node.developmentStyle || 'programmatic'
+        package: node.package ?? 'n8n-nodes-base',
+        developmentStyle: node.developmentStyle ?? 'programmatic'
       }
     };
-    
+
+    // Add examples from templates if requested
+    if (includeExamples) {
+      try {
+        const fullNodeType = getWorkflowNodeType(node.package ?? 'n8n-nodes-base', node.nodeType);
+        const examples = this.db!.prepare(`
+          SELECT
+            parameters_json,
+            template_name,
+            template_views,
+            complexity,
+            use_cases,
+            has_credentials,
+            has_expressions
+          FROM template_node_configs
+          WHERE node_type = ?
+          ORDER BY rank
+          LIMIT 3
+        `).all(fullNodeType) as any[];
+
+        if (examples.length > 0) {
+          (result as any).examples = examples.map((ex: any) => ({
+            configuration: JSON.parse(ex.parameters_json),
+            source: {
+              template: ex.template_name,
+              views: ex.template_views,
+              complexity: ex.complexity
+            },
+            useCases: ex.use_cases ? JSON.parse(ex.use_cases).slice(0, 2) : [],
+            metadata: {
+              hasCredentials: ex.has_credentials === 1,
+              hasExpressions: ex.has_expressions === 1
+            }
+          }));
+
+          (result as any).examplesCount = examples.length;
+        } else {
+          (result as any).examples = [];
+          (result as any).examplesCount = 0;
+        }
+      } catch (error: any) {
+        logger.warn(`Failed to fetch examples for ${nodeType}:`, error.message);
+        (result as any).examples = [];
+        (result as any).examplesCount = 0;
+      }
+    }
+
     // Cache for 1 hour
     this.cache.set(cacheKey, result, 3600);
-    
+
     return result;
   }
 
   private async searchNodeProperties(nodeType: string, query: string, maxResults: number = 20): Promise<any> {
     await this.ensureInitialized();
     if (!this.repository) throw new Error('Repository not initialized');
-    
+
     // Get the node
     // First try with normalized type
-    const normalizedType = normalizeNodeType(nodeType);
+    const normalizedType = NodeTypeNormalizer.normalizeToFullForm(nodeType);
     let node = this.repository.getNode(normalizedType);
     
     if (!node && normalizedType !== nodeType) {
@@ -1787,43 +2017,6 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
     };
   }
 
-  private async getNodeForTask(task: string): Promise<any> {
-    const template = TaskTemplates.getTaskTemplate(task);
-    
-    if (!template) {
-      // Try to find similar tasks
-      const similar = TaskTemplates.searchTasks(task);
-      throw new Error(
-        `Unknown task: ${task}. ` +
-        (similar.length > 0 
-          ? `Did you mean: ${similar.slice(0, 3).join(', ')}?`
-          : `Use 'list_tasks' to see available tasks.`)
-      );
-    }
-    
-    return {
-      task: template.task,
-      description: template.description,
-      nodeType: template.nodeType,
-      configuration: template.configuration,
-      userMustProvide: template.userMustProvide,
-      optionalEnhancements: template.optionalEnhancements || [],
-      notes: template.notes || [],
-      example: {
-        node: {
-          type: template.nodeType,
-          parameters: template.configuration
-        },
-        userInputsNeeded: template.userMustProvide.map(p => ({
-          property: p.property,
-          currentValue: this.getPropertyValue(template.configuration, p.property),
-          description: p.description,
-          example: p.example
-        }))
-      }
-    };
-  }
-  
   private getPropertyValue(config: any, path: string): any {
     const parts = path.split('.');
     let value = config;
@@ -1894,17 +2087,17 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
   ): Promise<any> {
     await this.ensureInitialized();
     if (!this.repository) throw new Error('Repository not initialized');
-    
+
     // Get node info to access properties
     // First try with normalized type
-    const normalizedType = normalizeNodeType(nodeType);
+    const normalizedType = NodeTypeNormalizer.normalizeToFullForm(nodeType);
     let node = this.repository.getNode(normalizedType);
-    
+
     if (!node && normalizedType !== nodeType) {
       // Try original if normalization changed it
       node = this.repository.getNode(nodeType);
     }
-    
+
     if (!node) {
       // Fallback to other alternatives for edge cases
       const alternatives = getNodeTypeAlternatives(normalizedType);
@@ -1952,10 +2145,10 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
   private async getPropertyDependencies(nodeType: string, config?: Record<string, any>): Promise<any> {
     await this.ensureInitialized();
     if (!this.repository) throw new Error('Repository not initialized');
-    
+
     // Get node info to access properties
     // First try with normalized type
-    const normalizedType = normalizeNodeType(nodeType);
+    const normalizedType = NodeTypeNormalizer.normalizeToFullForm(nodeType);
     let node = this.repository.getNode(normalizedType);
     
     if (!node && normalizedType !== nodeType) {
@@ -2006,10 +2199,10 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
   private async getNodeAsToolInfo(nodeType: string): Promise<any> {
     await this.ensureInitialized();
     if (!this.repository) throw new Error('Repository not initialized');
-    
+
     // Get node info
     // First try with normalized type
-    const normalizedType = normalizeNodeType(nodeType);
+    const normalizedType = NodeTypeNormalizer.normalizeToFullForm(nodeType);
     let node = this.repository.getNode(normalizedType);
     
     if (!node && normalizedType !== nodeType) {
@@ -2229,10 +2422,10 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
   private async validateNodeMinimal(nodeType: string, config: Record<string, any>): Promise<any> {
     await this.ensureInitialized();
     if (!this.repository) throw new Error('Repository not initialized');
-    
+
     // Get node info
     // First try with normalized type
-    const normalizedType = normalizeNodeType(nodeType);
+    const normalizedType = NodeTypeNormalizer.normalizeToFullForm(nodeType);
     let node = this.repository.getNode(normalizedType);
     
     if (!node && normalizedType !== nodeType) {
@@ -2581,29 +2774,45 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
           expressionsValidated: result.statistics.expressionsValidated,
           errorCount: result.errors.length,
           warningCount: result.warnings.length
-        }
-      };
-      
-      if (result.errors.length > 0) {
-        response.errors = result.errors.map(e => ({
+        },
+        // Always include errors and warnings arrays for consistent API response
+        errors: result.errors.map(e => ({
           node: e.nodeName || 'workflow',
           message: e.message,
           details: e.details
-        }));
-      }
-      
-      if (result.warnings.length > 0) {
-        response.warnings = result.warnings.map(w => ({
+        })),
+        warnings: result.warnings.map(w => ({
           node: w.nodeName || 'workflow',
           message: w.message,
           details: w.details
-        }));
-      }
+        }))
+      };
       
       if (result.suggestions.length > 0) {
         response.suggestions = result.suggestions;
       }
-      
+
+      // Track validation details in telemetry
+      if (!result.valid && result.errors.length > 0) {
+        // Track each validation error for analysis
+        result.errors.forEach(error => {
+          telemetry.trackValidationDetails(
+            error.nodeName || 'workflow',
+            error.type || 'validation_error',
+            {
+              message: error.message,
+              nodeCount: workflow.nodes?.length ?? 0,
+              hasConnections: Object.keys(workflow.connections || {}).length > 0
+            }
+          );
+        });
+      }
+
+      // Track successfully validated workflows in telemetry
+      if (result.valid) {
+        telemetry.trackWorkflowCreation(workflow, true);
+      }
+
       return response;
     } catch (error) {
       logger.error('Error validating workflow:', error);

src/mcp/tool-docs/index.ts

@@ -17,14 +17,13 @@ import {
   validateWorkflowConnectionsDoc,
   validateWorkflowExpressionsDoc
 } from './validation';
-import { 
-  listTasksDoc, 
-  getNodeForTaskDoc, 
-  listNodeTemplatesDoc, 
-  getTemplateDoc, 
+import {
+  listTasksDoc,
+  listNodeTemplatesDoc,
+  getTemplateDoc,
   searchTemplatesDoc,
-  searchTemplatesByMetadataDoc, 
-  getTemplatesForTaskDoc 
+  searchTemplatesByMetadataDoc,
+  getTemplatesForTaskDoc
 } from './templates';
 import { 
   toolsDocumentationDoc,
@@ -43,6 +42,7 @@ import {
   n8nDeleteWorkflowDoc,
   n8nListWorkflowsDoc,
   n8nValidateWorkflowDoc,
+  n8nAutofixWorkflowDoc,
   n8nTriggerWebhookWorkflowDoc,
   n8nGetExecutionDoc,
   n8nListExecutionsDoc,
@@ -80,7 +80,6 @@ export const toolsDocumentation: Record<string, ToolDocumentation> = {
   
   // Template tools
   list_tasks: listTasksDoc,
-  get_node_for_task: getNodeForTaskDoc,
   list_node_templates: listNodeTemplatesDoc,
   get_template: getTemplateDoc,
   search_templates: searchTemplatesDoc,
@@ -98,6 +97,7 @@ export const toolsDocumentation: Record<string, ToolDocumentation> = {
   n8n_delete_workflow: n8nDeleteWorkflowDoc,
   n8n_list_workflows: n8nListWorkflowsDoc,
   n8n_validate_workflow: n8nValidateWorkflowDoc,
+  n8n_autofix_workflow: n8nAutofixWorkflowDoc,
   n8n_trigger_webhook_workflow: n8nTriggerWebhookWorkflowDoc,
   n8n_get_execution: n8nGetExecutionDoc,
   n8n_list_executions: n8nListExecutionsDoc,

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

@@ -1,48 +0,0 @@
-import { ToolDocumentation } from '../types';
-
-export const getNodeForTaskDoc: ToolDocumentation = {
-  name: 'get_node_for_task',
-  category: 'templates',
-  essentials: {
-    description: 'Get pre-configured node for tasks: post_json_request, receive_webhook, query_database, send_slack_message, etc. Use list_tasks for all.',
-    keyParameters: ['task'],
-    example: 'get_node_for_task({task: "post_json_request"})',
-    performance: 'Instant',
-    tips: [
-      'Returns ready-to-use configuration',
-      'See list_tasks for available tasks',
-      'Includes credentials structure'
-    ]
-  },
-  full: {
-    description: 'Returns pre-configured node settings for common automation tasks. Each configuration includes the correct node type, essential parameters, and credential requirements. Perfect for quickly setting up standard automations.',
-    parameters: {
-      task: { type: 'string', required: true, description: 'Task name from list_tasks (e.g., "post_json_request", "send_email")' }
-    },
-    returns: 'Complete node configuration with type, displayName, parameters, credentials structure',
-    examples: [
-      'get_node_for_task({task: "post_json_request"}) - HTTP POST setup',
-      'get_node_for_task({task: "receive_webhook"}) - Webhook receiver',
-      'get_node_for_task({task: "send_slack_message"}) - Slack config'
-    ],
-    useCases: [
-      'Quick node configuration',
-      'Learning proper node setup',
-      'Standard automation patterns',
-      'Credential structure reference'
-    ],
-    performance: 'Instant - Pre-configured templates',
-    bestPractices: [
-      'Use list_tasks to discover options',
-      'Customize returned config as needed',
-      'Check credential requirements',
-      'Validate with validate_node_operation'
-    ],
-    pitfalls: [
-      'Templates may need customization',
-      'Credentials must be configured separately',
-      'Not all tasks available for all nodes'
-    ],
-    relatedTools: ['list_tasks', 'validate_node_operation', 'get_node_essentials']
-  }
-};

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

@@ -1,4 +1,3 @@
-export { getNodeForTaskDoc } from './get-node-for-task';
 export { listTasksDoc } from './list-tasks';
 export { listNodeTemplatesDoc } from './list-node-templates';
 export { getTemplateDoc } from './get-template';

src/mcp/tool-docs/types.ts

@@ -10,9 +10,9 @@ export interface ToolDocumentation {
   };
   full: {
     description: string;
-    parameters: Record<string, { 
-      type: string; 
-      description: string; 
+    parameters: Record<string, {
+      type: string;
+      description: string;
       required?: boolean;
       default?: any;
       examples?: string[];
@@ -22,8 +22,10 @@ export interface ToolDocumentation {
     examples: string[];
     useCases: string[];
     performance: string;
+    errorHandling?: string; // Optional: Documentation on error handling and debugging
     bestPractices: string[];
     pitfalls: string[];
+    modeComparison?: string; // Optional: Comparison of different modes for tools with multiple modes
     relatedTools: string[];
   };
 }

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

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

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

@@ -8,6 +8,7 @@ export { n8nUpdatePartialWorkflowDoc } from './n8n-update-partial-workflow';
 export { n8nDeleteWorkflowDoc } from './n8n-delete-workflow';
 export { n8nListWorkflowsDoc } from './n8n-list-workflows';
 export { n8nValidateWorkflowDoc } from './n8n-validate-workflow';
+export { n8nAutofixWorkflowDoc } from './n8n-autofix-workflow';
 export { n8nTriggerWebhookWorkflowDoc } from './n8n-trigger-webhook-workflow';
 export { n8nGetExecutionDoc } from './n8n-get-execution';
 export { n8nListExecutionsDoc } from './n8n-list-executions';

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

@@ -0,0 +1,125 @@
+import { ToolDocumentation } from '../types';
+
+export const n8nAutofixWorkflowDoc: ToolDocumentation = {
+  name: 'n8n_autofix_workflow',
+  category: 'workflow_management',
+  essentials: {
+    description: 'Automatically fix common workflow validation errors - expression formats, typeVersions, error outputs, webhook paths',
+    keyParameters: ['id', 'applyFixes'],
+    example: 'n8n_autofix_workflow({id: "wf_abc123", applyFixes: false})',
+    performance: 'Network-dependent (200-1000ms) - fetches, validates, and optionally updates workflow',
+    tips: [
+      'Use applyFixes: false to preview changes before applying',
+      'Set confidenceThreshold to control fix aggressiveness (high/medium/low)',
+      'Supports fixing expression formats, typeVersion issues, error outputs, node type corrections, and webhook paths',
+      'High-confidence fixes (≥90%) are safe for auto-application'
+    ]
+  },
+  full: {
+    description: `Automatically detects and fixes common workflow validation errors in n8n workflows. This tool:
+
+- Fetches the workflow from your n8n instance
+- Runs comprehensive validation to detect issues
+- Generates targeted fixes for common problems
+- Optionally applies the fixes back to the workflow
+
+The auto-fixer can resolve:
+1. **Expression Format Issues**: Missing '=' prefix in n8n expressions (e.g., {{ $json.field }} → ={{ $json.field }})
+2. **TypeVersion Corrections**: Downgrades nodes with unsupported typeVersions to maximum supported
+3. **Error Output Configuration**: Removes conflicting onError settings when error connections are missing
+4. **Node Type Corrections**: Intelligently fixes unknown node types using similarity matching:
+   - Handles deprecated package prefixes (n8n-nodes-base. → nodes-base.)
+   - Corrects capitalization mistakes (HttpRequest → httpRequest)
+   - Suggests correct packages (nodes-base.openai → nodes-langchain.openAi)
+   - Uses multi-factor scoring: name similarity, category match, package match, pattern match
+   - Only auto-fixes suggestions with ≥90% confidence
+   - Leverages NodeSimilarityService with 5-minute caching for performance
+5. **Webhook Path Generation**: Automatically generates UUIDs for webhook nodes missing path configuration:
+   - Generates a unique UUID for webhook path
+   - Sets both 'path' parameter and 'webhookId' field to the same UUID
+   - Ensures webhook nodes become functional with valid endpoints
+   - High confidence fix as UUID generation is deterministic
+
+The tool uses a confidence-based system to ensure safe fixes:
+- **High (≥90%)**: Safe to auto-apply (exact matches, known patterns)
+- **Medium (70-89%)**: Generally safe but review recommended
+- **Low (<70%)**: Manual review strongly recommended
+
+Requires N8N_API_URL and N8N_API_KEY environment variables to be configured.`,
+    parameters: {
+      id: {
+        type: 'string',
+        required: true,
+        description: 'The workflow ID to fix in your n8n instance'
+      },
+      applyFixes: {
+        type: 'boolean',
+        required: false,
+        description: 'Whether to apply fixes to the workflow (default: false - preview mode). When false, returns proposed fixes without modifying the workflow.'
+      },
+      fixTypes: {
+        type: 'array',
+        required: false,
+        description: 'Types of fixes to apply. Options: ["expression-format", "typeversion-correction", "error-output-config", "node-type-correction", "webhook-missing-path"]. Default: all types.'
+      },
+      confidenceThreshold: {
+        type: 'string',
+        required: false,
+        description: 'Minimum confidence level for fixes: "high" (≥90%), "medium" (≥70%), "low" (any). Default: "medium".'
+      },
+      maxFixes: {
+        type: 'number',
+        required: false,
+        description: 'Maximum number of fixes to apply (default: 50). Useful for limiting scope of changes.'
+      }
+    },
+    returns: `AutoFixResult object containing:
+- operations: Array of diff operations that will be/were applied
+- fixes: Detailed list of individual fixes with before/after values
+- summary: Human-readable summary of fixes
+- stats: Statistics by fix type and confidence level
+- applied: Boolean indicating if fixes were applied (when applyFixes: true)`,
+    examples: [
+      'n8n_autofix_workflow({id: "wf_abc123"}) - Preview all possible fixes',
+      'n8n_autofix_workflow({id: "wf_abc123", applyFixes: true}) - Apply all medium+ confidence fixes',
+      'n8n_autofix_workflow({id: "wf_abc123", applyFixes: true, confidenceThreshold: "high"}) - Only apply high-confidence fixes',
+      'n8n_autofix_workflow({id: "wf_abc123", fixTypes: ["expression-format"]}) - Only fix expression format issues',
+      'n8n_autofix_workflow({id: "wf_abc123", fixTypes: ["webhook-missing-path"]}) - Only fix webhook path issues',
+      'n8n_autofix_workflow({id: "wf_abc123", applyFixes: true, maxFixes: 10}) - Apply up to 10 fixes'
+    ],
+    useCases: [
+      'Fixing workflows imported from older n8n versions',
+      'Correcting expression syntax after manual edits',
+      'Resolving typeVersion conflicts after n8n upgrades',
+      'Cleaning up workflows before production deployment',
+      'Batch fixing common issues across multiple workflows',
+      'Migrating workflows between n8n instances with different versions',
+      'Repairing webhook nodes that lost their path configuration'
+    ],
+    performance: 'Depends on workflow size and number of issues. Preview mode: 200-500ms. Apply mode: 500-1000ms for medium workflows. Node similarity matching is cached for 5 minutes for improved performance on repeated validations.',
+    bestPractices: [
+      'Always preview fixes first (applyFixes: false) before applying',
+      'Start with high confidence threshold for production workflows',
+      'Review the fix summary to understand what changed',
+      'Test workflows after auto-fixing to ensure expected behavior',
+      'Use fixTypes parameter to target specific issue categories',
+      'Keep maxFixes reasonable to avoid too many changes at once'
+    ],
+    pitfalls: [
+      'Some fixes may change workflow behavior - always test after fixing',
+      'Low confidence fixes might not be the intended solution',
+      'Expression format fixes assume standard n8n syntax requirements',
+      'Node type corrections only work for known node types in the database',
+      'Cannot fix structural issues like missing nodes or invalid connections',
+      'TypeVersion downgrades might remove node features added in newer versions',
+      'Generated webhook paths are new UUIDs - existing webhook URLs will change'
+    ],
+    relatedTools: [
+      'n8n_validate_workflow',
+      'validate_workflow',
+      'n8n_update_partial_workflow',
+      'validate_workflow_expressions',
+      'validate_node_operation'
+    ]
+  }
+};

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

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

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

@@ -59,19 +59,59 @@ export const n8nTriggerWebhookWorkflowDoc: ToolDocumentation = {
       'Implement event-driven architectures with n8n'
     ],
     performance: `Performance varies based on workflow complexity and waitForResponse setting. Synchronous calls (waitForResponse: true) block until workflow completes. For long-running workflows, use async mode (waitForResponse: false) and monitor execution separately.`,
+    errorHandling: `**Enhanced Error Messages with Execution Guidance**
+
+When a webhook trigger fails, the error response now includes specific guidance to help debug the issue:
+
+**Error with Execution ID** (workflow started but failed):
+- Format: "Workflow {workflowId} execution {executionId} failed. Use n8n_get_execution({id: '{executionId}', mode: 'preview'}) to investigate the error."
+- Response includes: executionId and workflowId fields for direct access
+- Recommended action: Use n8n_get_execution with mode='preview' for fast, efficient error inspection
+
+**Error without Execution ID** (workflow didn't start):
+- Format: "Workflow failed to execute. Use n8n_list_executions to find recent executions, then n8n_get_execution with mode='preview' to investigate."
+- Recommended action: Check recent executions with n8n_list_executions
+
+**Why mode='preview'?**
+- Fast: <50ms response time
+- Efficient: ~500 tokens (vs 50K+ for full mode)
+- Safe: No timeout or token limit risks
+- Informative: Shows structure, counts, and error details
+- Provides recommendations for fetching more data if needed
+
+**Example Error Responses**:
+\`\`\`json
+{
+  "success": false,
+  "error": "Workflow wf_123 execution exec_456 failed. Use n8n_get_execution({id: 'exec_456', mode: 'preview'}) to investigate the error.",
+  "executionId": "exec_456",
+  "workflowId": "wf_123",
+  "code": "SERVER_ERROR"
+}
+\`\`\`
+
+**Investigation Workflow**:
+1. Trigger returns error with execution ID
+2. Call n8n_get_execution({id: executionId, mode: 'preview'}) to see structure and error
+3. Based on preview recommendation, fetch more data if needed
+4. Fix issues in workflow and retry`,
     bestPractices: [
       'Always verify workflow is active before attempting webhook triggers',
       'Match HTTP method exactly with webhook node configuration',
       'Use async mode (waitForResponse: false) for long-running workflows',
       'Include authentication headers when webhook requires them',
-      'Test webhook URL manually first to ensure it works'
+      'Test webhook URL manually first to ensure it works',
+      'When errors occur, use n8n_get_execution with mode="preview" first for efficient debugging',
+      'Store execution IDs from error responses for later investigation'
     ],
     pitfalls: [
       'Workflow must be ACTIVE - inactive workflows cannot be triggered',
       'HTTP method mismatch returns 404 even if URL is correct',
       'Webhook node must be the trigger node in the workflow',
       'Timeout errors occur with long workflows in sync mode',
-      'Data format must match webhook node expectations'
+      'Data format must match webhook node expectations',
+      'Error messages always include n8n_get_execution guidance - follow the suggested steps for efficient debugging',
+      'Execution IDs in error responses are crucial for debugging - always check for and use them'
     ],
     relatedTools: ['n8n_get_execution', 'n8n_list_executions', 'n8n_get_workflow', 'n8n_create_workflow']
   }

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

@@ -4,18 +4,22 @@ export const n8nUpdatePartialWorkflowDoc: ToolDocumentation = {
   name: 'n8n_update_partial_workflow',
   category: 'workflow_management',
   essentials: {
-    description: 'Update workflow incrementally with diff operations. Max 5 ops. Types: addNode, removeNode, updateNode, moveNode, enable/disableNode, addConnection, removeConnection, updateSettings, updateName, add/removeTag.',
-    keyParameters: ['id', 'operations'],
-    example: 'n8n_update_partial_workflow({id: "wf_123", operations: [{type: "updateNode", ...}]})',
+    description: 'Update workflow incrementally with diff operations. Types: addNode, removeNode, updateNode, moveNode, enable/disableNode, addConnection, removeConnection, rewireConnection, cleanStaleConnections, replaceConnections, updateSettings, updateName, add/removeTag. Supports smart parameters (branch, case) for multi-output nodes.',
+    keyParameters: ['id', 'operations', 'continueOnError'],
+    example: 'n8n_update_partial_workflow({id: "wf_123", operations: [{type: "rewireConnection", source: "IF", from: "Old", to: "New", branch: "true"}]})',
     performance: 'Fast (50-200ms)',
     tips: [
-      'Use for targeted changes',
-      'Supports up to 5 operations',
+      'Use rewireConnection to change connection targets',
+      'Use branch="true"/"false" for IF nodes',
+      'Use case=N for Switch nodes',
+      'Use cleanStaleConnections to auto-remove broken connections',
+      'Set ignoreErrors:true on removeConnection for cleanup',
+      'Use continueOnError mode for best-effort bulk operations',
       'Validate with validateOnly first'
     ]
   },
   full: {
-    description: `Updates workflows using surgical diff operations instead of full replacement. Supports 13 operation types for precise modifications. Operations are validated and applied atomically - all succeed or none are applied. Maximum 5 operations per call for safety.
+    description: `Updates workflows using surgical diff operations instead of full replacement. Supports 15 operation types for precise modifications. Operations are validated and applied atomically by default - all succeed or none are applied.
 
 ## Available Operations:
 
@@ -27,53 +31,107 @@ export const n8nUpdatePartialWorkflowDoc: ToolDocumentation = {
 - **enableNode**: Enable a disabled node
 - **disableNode**: Disable an active node
 
-### Connection Operations (3 types):
-- **addConnection**: Connect nodes (source→target)
-- **removeConnection**: Remove connection between nodes
-- **updateConnection**: Modify connection properties
+### Connection Operations (5 types):
+- **addConnection**: Connect nodes (source→target). Supports smart parameters: branch="true"/"false" for IF nodes, case=N for Switch nodes.
+- **removeConnection**: Remove connection between nodes (supports ignoreErrors flag)
+- **rewireConnection**: Change connection target from one node to another. Supports smart parameters.
+- **cleanStaleConnections**: Auto-remove all connections referencing non-existent nodes
+- **replaceConnections**: Replace entire connections object
 
 ### Metadata Operations (4 types):
 - **updateSettings**: Modify workflow settings
 - **updateName**: Rename the workflow
 - **addTag**: Add a workflow tag
-- **removeTag**: Remove a workflow tag`,
+- **removeTag**: Remove a workflow tag
+
+## Smart Parameters for Multi-Output Nodes
+
+For **IF nodes**, use semantic 'branch' parameter instead of technical sourceIndex:
+- **branch="true"**: Routes to true branch (sourceIndex=0)
+- **branch="false"**: Routes to false branch (sourceIndex=1)
+
+For **Switch nodes**, use semantic 'case' parameter:
+- **case=0**: First output
+- **case=1**: Second output
+- **case=N**: Nth output
+
+Works with addConnection and rewireConnection operations. Explicit sourceIndex overrides smart parameters.
+
+## Cleanup & Recovery Features
+
+### Automatic Cleanup
+The **cleanStaleConnections** operation automatically removes broken connection references after node renames/deletions. Essential for workflow recovery.
+
+### Best-Effort Mode
+Set **continueOnError: true** to apply valid operations even if some fail. Returns detailed results showing which operations succeeded/failed. Perfect for bulk cleanup operations.
+
+### Graceful Error Handling
+Add **ignoreErrors: true** to removeConnection operations to prevent failures when connections don't exist.`,
     parameters: {
       id: { type: 'string', required: true, description: 'Workflow ID to update' },
-      operations: { 
-        type: 'array', 
-        required: true, 
-        description: 'Array of diff operations. Each must have "type" field and operation-specific properties. Max 5 operations. Nodes can be referenced by ID or name.' 
+      operations: {
+        type: 'array',
+        required: true,
+        description: 'Array of diff operations. Each must have "type" field and operation-specific properties. Nodes can be referenced by ID or name.'
       },
-      validateOnly: { type: 'boolean', description: 'If true, only validate operations without applying them' }
+      validateOnly: { type: 'boolean', description: 'If true, only validate operations without applying them' },
+      continueOnError: { type: 'boolean', description: 'If true, apply valid operations even if some fail (best-effort mode). Returns applied and failed operation indices. Default: false (atomic)' }
     },
     returns: 'Updated workflow object or validation results if validateOnly=true',
     examples: [
-      '// Update node parameter\nn8n_update_partial_workflow({id: "abc", operations: [{type: "updateNode", nodeName: "HTTP Request", changes: {"parameters.url": "https://api.example.com"}}]})',
-      '// Add connection between nodes\nn8n_update_partial_workflow({id: "xyz", operations: [{type: "addConnection", source: "Webhook", target: "Slack", sourceOutput: "main", targetInput: "main"}]})',
-      '// Multiple operations in one call\nn8n_update_partial_workflow({id: "123", operations: [\n  {type: "addNode", node: {name: "Transform", type: "n8n-nodes-base.code", position: [400, 300]}},\n  {type: "addConnection", source: "Webhook", target: "Transform"},\n  {type: "updateSettings", settings: {timezone: "America/New_York"}}\n]})',
-      '// Validate before applying\nn8n_update_partial_workflow({id: "456", operations: [{type: "removeNode", nodeName: "Old Process"}], validateOnly: true})'
+      '// Add a basic node (minimal configuration)\nn8n_update_partial_workflow({id: "abc", operations: [{type: "addNode", node: {name: "Process Data", type: "n8n-nodes-base.set", position: [400, 300], parameters: {}}}]})',
+      '// Add node with full configuration\nn8n_update_partial_workflow({id: "def", operations: [{type: "addNode", node: {name: "Send Slack Alert", type: "n8n-nodes-base.slack", position: [600, 300], typeVersion: 2, parameters: {resource: "message", operation: "post", channel: "#alerts", text: "Success!"}}}]})',
+      '// Add node AND connect it (common pattern)\nn8n_update_partial_workflow({id: "ghi", operations: [\n  {type: "addNode", node: {name: "HTTP Request", type: "n8n-nodes-base.httpRequest", position: [400, 300], parameters: {url: "https://api.example.com", method: "GET"}}},\n  {type: "addConnection", source: "Webhook", target: "HTTP Request"}\n]})',
+      '// Rewire connection from one target to another\nn8n_update_partial_workflow({id: "xyz", operations: [{type: "rewireConnection", source: "Webhook", from: "Old Handler", to: "New Handler"}]})',
+      '// Smart parameter: IF node true branch\nn8n_update_partial_workflow({id: "abc", operations: [{type: "addConnection", source: "IF", target: "Success Handler", branch: "true"}]})',
+      '// Smart parameter: IF node false branch\nn8n_update_partial_workflow({id: "def", operations: [{type: "addConnection", source: "IF", target: "Error Handler", branch: "false"}]})',
+      '// Smart parameter: Switch node case routing\nn8n_update_partial_workflow({id: "ghi", operations: [\n  {type: "addConnection", source: "Switch", target: "Handler A", case: 0},\n  {type: "addConnection", source: "Switch", target: "Handler B", case: 1},\n  {type: "addConnection", source: "Switch", target: "Handler C", case: 2}\n]})',
+      '// Rewire with smart parameter\nn8n_update_partial_workflow({id: "jkl", operations: [{type: "rewireConnection", source: "IF", from: "Old True Handler", to: "New True Handler", branch: "true"}]})',
+      '// Add multiple nodes in batch\nn8n_update_partial_workflow({id: "mno", operations: [\n  {type: "addNode", node: {name: "Filter", type: "n8n-nodes-base.filter", position: [400, 300], parameters: {}}},\n  {type: "addNode", node: {name: "Transform", type: "n8n-nodes-base.set", position: [600, 300], parameters: {}}},\n  {type: "addConnection", source: "Filter", target: "Transform"}\n]})',
+      '// Clean up stale connections after node renames/deletions\nn8n_update_partial_workflow({id: "pqr", operations: [{type: "cleanStaleConnections"}]})',
+      '// Remove connection gracefully (no error if it doesn\'t exist)\nn8n_update_partial_workflow({id: "stu", operations: [{type: "removeConnection", source: "Old Node", target: "Target", ignoreErrors: true}]})',
+      '// Best-effort mode: apply what works, report what fails\nn8n_update_partial_workflow({id: "vwx", operations: [\n  {type: "updateName", name: "Fixed Workflow"},\n  {type: "removeConnection", source: "Broken", target: "Node"},\n  {type: "cleanStaleConnections"}\n], continueOnError: true})',
+      '// Update node parameter\nn8n_update_partial_workflow({id: "yza", operations: [{type: "updateNode", nodeName: "HTTP Request", updates: {"parameters.url": "https://api.example.com"}}]})',
+      '// Validate before applying\nn8n_update_partial_workflow({id: "bcd", operations: [{type: "removeNode", nodeName: "Old Process"}], validateOnly: true})'
     ],
     useCases: [
+      'Rewire connections when replacing nodes',
+      'Route IF/Switch node outputs with semantic parameters',
+      'Clean up broken workflows after node renames/deletions',
+      'Bulk connection cleanup with best-effort mode',
       'Update single node parameters',
-      'Add/remove connections',
+      'Replace all connections at once',
+      'Graceful cleanup operations that don\'t fail',
       'Enable/disable nodes',
       'Rename workflows or nodes',
       'Manage tags efficiently'
     ],
     performance: 'Very fast - typically 50-200ms. Much faster than full updates as only changes are processed.',
     bestPractices: [
-      'Use validateOnly to test operations',
+      'Use rewireConnection instead of remove+add for changing targets',
+      'Use branch="true"/"false" for IF nodes instead of sourceIndex',
+      'Use case=N for Switch nodes instead of sourceIndex',
+      'Use cleanStaleConnections after renaming/removing nodes',
+      'Use continueOnError for bulk cleanup operations',
+      'Set ignoreErrors:true on removeConnection for graceful cleanup',
+      'Use validateOnly to test operations before applying',
       'Group related changes in one call',
-      'Keep operations under 5 for clarity',
-      'Check operation order for dependencies'
+      'Check operation order for dependencies',
+      'Use atomic mode (default) for critical updates'
     ],
     pitfalls: [
       '**REQUIRES N8N_API_URL and N8N_API_KEY environment variables** - will not work without n8n API access',
-      'Maximum 5 operations per call - split larger updates',
-      'Operations validated together - all must be valid',
+      'Atomic mode (default): all operations must succeed or none are applied',
+      'continueOnError breaks atomic guarantees - use with caution',
       'Order matters for dependent operations (e.g., must add node before connecting to it)',
       'Node references accept ID or name, but name must be unique',
-      'Dot notation for nested updates: use "parameters.url" not nested objects'
+      'Node names with special characters (apostrophes, quotes) work correctly',
+      'For best compatibility, prefer node IDs over names when dealing with special characters',
+      'Use "updates" property for updateNode operations: {type: "updateNode", updates: {...}}',
+      'Smart parameters (branch, case) only work with IF and Switch nodes - ignored for other node types',
+      'Explicit sourceIndex overrides smart parameters (branch, case) if both provided',
+      'cleanStaleConnections removes ALL broken connections - cannot be selective',
+      'replaceConnections overwrites entire connections object - all previous connections lost'
     ],
     relatedTools: ['n8n_update_full_workflow', 'n8n_get_workflow', 'validate_workflow', 'tools_documentation']
   }

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

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

src/mcp/tools-n8n-manager.ts

@@ -160,7 +160,7 @@ export const n8nManagementTools: ToolDefinition[] = [
   },
   {
     name: 'n8n_update_partial_workflow',
-    description: `Update workflow incrementally with diff operations. Max 5 ops. Types: addNode, removeNode, updateNode, moveNode, enable/disableNode, addConnection, removeConnection, updateSettings, updateName, add/removeTag. See tools_documentation("n8n_update_partial_workflow", "full") for details.`,
+    description: `Update workflow incrementally with diff operations. Types: addNode, removeNode, updateNode, moveNode, enable/disableNode, addConnection, removeConnection, updateSettings, updateName, add/removeTag. See tools_documentation("n8n_update_partial_workflow", "full") for details.`,
     inputSchema: {
       type: 'object',
       additionalProperties: true,  // Allow any extra properties Claude Desktop might add
@@ -180,6 +180,10 @@ export const n8nManagementTools: ToolDefinition[] = [
         validateOnly: {
           type: 'boolean',
           description: 'If true, only validate operations without applying them'
+        },
+        continueOnError: {
+          type: 'boolean',
+          description: 'If true, apply valid operations even if some fail (best-effort mode). Returns applied and failed operation indices. Default: false (atomic)'
         }
       },
       required: ['id', 'operations']
@@ -270,6 +274,41 @@ export const n8nManagementTools: ToolDefinition[] = [
       required: ['id']
     }
   },
+  {
+    name: 'n8n_autofix_workflow',
+    description: `Automatically fix common workflow validation errors. Preview fixes or apply them. Fixes expression format, typeVersion, error output config, webhook paths.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: {
+          type: 'string',
+          description: 'Workflow ID to fix'
+        },
+        applyFixes: {
+          type: 'boolean',
+          description: 'Apply fixes to workflow (default: false - preview mode)'
+        },
+        fixTypes: {
+          type: 'array',
+          description: 'Types of fixes to apply (default: all)',
+          items: {
+            type: 'string',
+            enum: ['expression-format', 'typeversion-correction', 'error-output-config', 'node-type-correction', 'webhook-missing-path']
+          }
+        },
+        confidenceThreshold: {
+          type: 'string',
+          enum: ['high', 'medium', 'low'],
+          description: 'Minimum confidence level for fixes (default: medium)'
+        },
+        maxFixes: {
+          type: 'number',
+          description: 'Maximum number of fixes to apply (default: 50)'
+        }
+      },
+      required: ['id']
+    }
+  },
 
   // Execution Management Tools
   {
@@ -305,17 +344,41 @@ export const n8nManagementTools: ToolDefinition[] = [
   },
   {
     name: 'n8n_get_execution',
-    description: `Get details of a specific execution by ID.`,
+    description: `Get execution details with smart filtering. RECOMMENDED: Use mode='preview' first to assess data size.
+Examples:
+- {id, mode:'preview'} - Structure & counts (fast, no data)
+- {id, mode:'summary'} - 2 samples per node (default)
+- {id, mode:'filtered', itemsLimit:5} - 5 items per node
+- {id, nodeNames:['HTTP Request']} - Specific node only
+- {id, mode:'full'} - Complete data (use with caution)`,
     inputSchema: {
       type: 'object',
       properties: {
-        id: { 
-          type: 'string', 
-          description: 'Execution ID' 
+        id: {
+          type: 'string',
+          description: 'Execution ID'
         },
-        includeData: { 
-          type: 'boolean', 
-          description: 'Include full execution data (default: false)' 
+        mode: {
+          type: 'string',
+          enum: ['preview', 'summary', 'filtered', 'full'],
+          description: 'Data retrieval mode: preview=structure only, summary=2 items, filtered=custom, full=all data'
+        },
+        nodeNames: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Filter to specific nodes by name (for filtered mode)'
+        },
+        itemsLimit: {
+          type: 'number',
+          description: 'Items per node: 0=structure only, 2=default, -1=unlimited (for filtered mode)'
+        },
+        includeInputData: {
+          type: 'boolean',
+          description: 'Include input data in addition to output (default: false)'
+        },
+        includeData: {
+          type: 'boolean',
+          description: 'Legacy: Include execution data. Maps to mode=summary if true (deprecated, use mode instead)'
         }
       },
       required: ['id']

src/mcp/tools.ts

@@ -73,7 +73,7 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
   },
   {
     name: 'search_nodes',
-    description: `Search n8n nodes by keyword. Pass query as string. Example: query="webhook" or query="database". Returns max 20 results.`,
+    description: `Search n8n nodes by keyword with optional real-world examples. Pass query as string. Example: query="webhook" or query="database". Returns max 20 results. Use includeExamples=true to get top 2 template configs per node.`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -92,6 +92,11 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
           description: 'OR=any word, AND=all words, FUZZY=typo-tolerant',
           default: 'OR',
         },
+        includeExamples: {
+          type: 'boolean',
+          description: 'Include top 2 real-world configuration examples from popular templates (default: false)',
+          default: false,
+        },
       },
       required: ['query'],
     },
@@ -128,7 +133,7 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
   },
   {
     name: 'get_node_essentials',
-    description: `Get node essential info. Pass nodeType as string with prefix. Example: nodeType="nodes-base.slack"`,
+    description: `Get node essential info with optional real-world examples from templates. Pass nodeType as string with prefix. Example: nodeType="nodes-base.slack". Use includeExamples=true to get top 3 template configs.`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -136,6 +141,11 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
           type: 'string',
           description: 'Full type: "nodes-base.httpRequest"',
         },
+        includeExamples: {
+          type: 'boolean',
+          description: 'Include top 3 real-world configuration examples from popular templates (default: false)',
+          default: false,
+        },
       },
       required: ['nodeType'],
     },
@@ -163,20 +173,6 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
       required: ['nodeType', 'query'],
     },
   },
-  {
-    name: 'get_node_for_task',
-    description: `Get pre-configured node for tasks: post_json_request, receive_webhook, query_database, send_slack_message, etc. Use list_tasks for all.`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        task: {
-          type: 'string',
-          description: 'Task name. See list_tasks for options.',
-        },
-      },
-      required: ['task'],
-    },
-  },
   {
     name: 'list_tasks',
     description: `List task templates by category: HTTP/API, Webhooks, Database, AI, Data Processing, Communication.`,

src/scripts/debug-http-search.ts

@@ -0,0 +1,77 @@
+#!/usr/bin/env npx tsx
+
+import { createDatabaseAdapter } from '../database/database-adapter';
+import { NodeRepository } from '../database/node-repository';
+import { NodeSimilarityService } from '../services/node-similarity-service';
+import path from 'path';
+
+async function debugHttpSearch() {
+  const dbPath = path.join(process.cwd(), 'data/nodes.db');
+  const db = await createDatabaseAdapter(dbPath);
+  const repository = new NodeRepository(db);
+  const service = new NodeSimilarityService(repository);
+
+  console.log('Testing "http" search...\n');
+
+  // Check if httpRequest exists
+  const httpNode = repository.getNode('nodes-base.httpRequest');
+  console.log('HTTP Request node exists:', httpNode ? 'Yes' : 'No');
+  if (httpNode) {
+    console.log('  Display name:', httpNode.displayName);
+  }
+
+  // Test the search with internal details
+  const suggestions = await service.findSimilarNodes('http', 5);
+  console.log('\nSuggestions for "http":', suggestions.length);
+  suggestions.forEach(s => {
+    console.log(`  - ${s.nodeType} (${Math.round(s.confidence * 100)}%)`);
+  });
+
+  // Manually calculate score for httpRequest
+  console.log('\nManual score calculation for httpRequest:');
+  const testNode = {
+    nodeType: 'nodes-base.httpRequest',
+    displayName: 'HTTP Request',
+    category: 'Core Nodes'
+  };
+
+  const cleanInvalid = 'http';
+  const cleanValid = 'nodesbasehttprequest';
+  const displayNameClean = 'httprequest';
+
+  // Check substring
+  const hasSubstring = cleanValid.includes(cleanInvalid) || displayNameClean.includes(cleanInvalid);
+  console.log(`  Substring match: ${hasSubstring}`);
+
+  // This should give us pattern match score
+  const patternScore = hasSubstring ? 35 : 0; // Using 35 for short searches
+  console.log(`  Pattern score: ${patternScore}`);
+
+  // Name similarity would be low
+  console.log(`  Total score would need to be >= 50 to appear`);
+
+  // Get all nodes and check which ones contain 'http'
+  const allNodes = repository.getAllNodes();
+  const httpNodes = allNodes.filter(n =>
+    n.nodeType.toLowerCase().includes('http') ||
+    (n.displayName && n.displayName.toLowerCase().includes('http'))
+  );
+
+  console.log('\n\nNodes containing "http" in name:');
+  httpNodes.slice(0, 5).forEach(n => {
+    console.log(`  - ${n.nodeType} (${n.displayName})`);
+
+    // Calculate score for this node
+    const normalizedSearch = 'http';
+    const normalizedType = n.nodeType.toLowerCase().replace(/[^a-z0-9]/g, '');
+    const normalizedDisplay = (n.displayName || '').toLowerCase().replace(/[^a-z0-9]/g, '');
+
+    const containsInType = normalizedType.includes(normalizedSearch);
+    const containsInDisplay = normalizedDisplay.includes(normalizedSearch);
+
+    console.log(`    Type check: "${normalizedType}" includes "${normalizedSearch}" = ${containsInType}`);
+    console.log(`    Display check: "${normalizedDisplay}" includes "${normalizedSearch}" = ${containsInDisplay}`);
+  });
+}
+
+debugHttpSearch().catch(console.error);

src/scripts/fetch-templates.ts

@@ -10,21 +10,240 @@ import type { MetadataRequest } from '../templates/metadata-generator';
 // Load environment variables
 dotenv.config();
 
-async function fetchTemplates(mode: 'rebuild' | 'update' = 'rebuild', generateMetadata: boolean = false, metadataOnly: boolean = false) {
+/**
+ * Extract node configurations from a template workflow
+ */
+function extractNodeConfigs(
+  templateId: number,
+  templateName: string,
+  templateViews: number,
+  workflowCompressed: string,
+  metadata: any
+): Array<{
+  node_type: string;
+  template_id: number;
+  template_name: string;
+  template_views: number;
+  node_name: string;
+  parameters_json: string;
+  credentials_json: string | null;
+  has_credentials: number;
+  has_expressions: number;
+  complexity: string;
+  use_cases: string;
+}> {
+  try {
+    // Decompress workflow
+    const decompressed = zlib.gunzipSync(Buffer.from(workflowCompressed, 'base64'));
+    const workflow = JSON.parse(decompressed.toString('utf-8'));
+
+    const configs: any[] = [];
+
+    for (const node of workflow.nodes || []) {
+      // Skip UI-only nodes (sticky notes, etc.)
+      if (node.type.includes('stickyNote') || !node.parameters) {
+        continue;
+      }
+
+      configs.push({
+        node_type: node.type,
+        template_id: templateId,
+        template_name: templateName,
+        template_views: templateViews,
+        node_name: node.name,
+        parameters_json: JSON.stringify(node.parameters),
+        credentials_json: node.credentials ? JSON.stringify(node.credentials) : null,
+        has_credentials: node.credentials ? 1 : 0,
+        has_expressions: detectExpressions(node.parameters) ? 1 : 0,
+        complexity: metadata?.complexity || 'medium',
+        use_cases: JSON.stringify(metadata?.use_cases || [])
+      });
+    }
+
+    return configs;
+  } catch (error) {
+    console.error(`Error extracting configs from template ${templateId}:`, error);
+    return [];
+  }
+}
+
+/**
+ * Detect n8n expressions in parameters
+ */
+function detectExpressions(params: any): boolean {
+  if (!params) return false;
+  const json = JSON.stringify(params);
+  return json.includes('={{') || json.includes('$json') || json.includes('$node');
+}
+
+/**
+ * Insert extracted configs into database and rank them
+ */
+function insertAndRankConfigs(db: any, configs: any[]) {
+  if (configs.length === 0) {
+    console.log('No configs to insert');
+    return;
+  }
+
+  // Clear old configs for these templates
+  const templateIds = [...new Set(configs.map(c => c.template_id))];
+  const placeholders = templateIds.map(() => '?').join(',');
+  db.prepare(`DELETE FROM template_node_configs WHERE template_id IN (${placeholders})`).run(...templateIds);
+
+  // Insert new configs
+  const insertStmt = db.prepare(`
+    INSERT INTO template_node_configs (
+      node_type, template_id, template_name, template_views,
+      node_name, parameters_json, credentials_json,
+      has_credentials, has_expressions, complexity, use_cases
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+
+  for (const config of configs) {
+    insertStmt.run(
+      config.node_type,
+      config.template_id,
+      config.template_name,
+      config.template_views,
+      config.node_name,
+      config.parameters_json,
+      config.credentials_json,
+      config.has_credentials,
+      config.has_expressions,
+      config.complexity,
+      config.use_cases
+    );
+  }
+
+  // Rank configs per node_type by template popularity
+  db.exec(`
+    UPDATE template_node_configs
+    SET rank = (
+      SELECT COUNT(*) + 1
+      FROM template_node_configs AS t2
+      WHERE t2.node_type = template_node_configs.node_type
+        AND t2.template_views > template_node_configs.template_views
+    )
+  `);
+
+  // Keep only top 10 per node_type
+  db.exec(`
+    DELETE FROM template_node_configs
+    WHERE id NOT IN (
+      SELECT id FROM template_node_configs
+      WHERE rank <= 10
+      ORDER BY node_type, rank
+    )
+  `);
+
+  console.log(`✅ Extracted and ranked ${configs.length} node configurations`);
+}
+
+/**
+ * Extract node configurations from existing templates
+ */
+async function extractTemplateConfigs(db: any, service: TemplateService) {
+  console.log('📦 Extracting node configurations from templates...');
+  const repository = (service as any).repository;
+  const allTemplates = repository.getAllTemplates();
+
+  const allConfigs: any[] = [];
+  let configsExtracted = 0;
+
+  for (const template of allTemplates) {
+    if (template.workflow_json_compressed) {
+      const metadata = template.metadata_json ? JSON.parse(template.metadata_json) : null;
+      const configs = extractNodeConfigs(
+        template.id,
+        template.name,
+        template.views,
+        template.workflow_json_compressed,
+        metadata
+      );
+      allConfigs.push(...configs);
+      configsExtracted += configs.length;
+    }
+  }
+
+  if (allConfigs.length > 0) {
+    insertAndRankConfigs(db, allConfigs);
+
+    // Show stats
+    const configStats = db.prepare(`
+      SELECT
+        COUNT(DISTINCT node_type) as node_types,
+        COUNT(*) as total_configs,
+        AVG(rank) as avg_rank
+      FROM template_node_configs
+    `).get() as any;
+
+    console.log(`📊 Node config stats:`);
+    console.log(`   - Unique node types: ${configStats.node_types}`);
+    console.log(`   - Total configs stored: ${configStats.total_configs}`);
+    console.log(`   - Average rank: ${configStats.avg_rank?.toFixed(1) || 'N/A'}`);
+  } else {
+    console.log('⚠️  No node configurations extracted');
+  }
+}
+
+async function fetchTemplates(
+  mode: 'rebuild' | 'update' = 'rebuild',
+  generateMetadata: boolean = false,
+  metadataOnly: boolean = false,
+  extractOnly: boolean = false
+) {
+  // If extract-only mode, skip template fetching and only extract configs
+  if (extractOnly) {
+    console.log('📦 Extract-only mode: Extracting node configurations from existing templates...\n');
+
+    const db = await createDatabaseAdapter('./data/nodes.db');
+
+    // Ensure template_node_configs table exists
+    try {
+      const tableExists = db.prepare(`
+        SELECT name FROM sqlite_master
+        WHERE type='table' AND name='template_node_configs'
+      `).get();
+
+      if (!tableExists) {
+        console.log('📋 Creating template_node_configs table...');
+        const migrationPath = path.join(__dirname, '../../src/database/migrations/add-template-node-configs.sql');
+        const migration = fs.readFileSync(migrationPath, 'utf8');
+        db.exec(migration);
+        console.log('✅ Table created successfully\n');
+      }
+    } catch (error) {
+      console.error('❌ Error checking/creating template_node_configs table:', error);
+      if ('close' in db && typeof db.close === 'function') {
+        db.close();
+      }
+      process.exit(1);
+    }
+
+    const service = new TemplateService(db);
+
+    await extractTemplateConfigs(db, service);
+
+    if ('close' in db && typeof db.close === 'function') {
+      db.close();
+    }
+    return;
+  }
+
   // If metadata-only mode, skip template fetching entirely
   if (metadataOnly) {
     console.log('🤖 Metadata-only mode: Generating metadata for existing templates...\n');
-    
+
     if (!process.env.OPENAI_API_KEY) {
       console.error('❌ OPENAI_API_KEY not set in environment');
       process.exit(1);
     }
-    
+
     const db = await createDatabaseAdapter('./data/nodes.db');
     const service = new TemplateService(db);
-    
+
     await generateTemplateMetadata(db, service);
-    
+
     if ('close' in db && typeof db.close === 'function') {
       db.close();
     }
@@ -125,7 +344,11 @@ async function fetchTemplates(mode: 'rebuild' | 'update' = 'rebuild', generateMe
     stats.topUsedNodes.forEach((node: any, index: number) => {
       console.log(`   ${index + 1}. ${node.node} (${node.count} templates)`);
     });
-    
+
+    // Extract node configurations from templates
+    console.log('');
+    await extractTemplateConfigs(db, service);
+
     // Generate metadata if requested
     if (generateMetadata && process.env.OPENAI_API_KEY) {
       console.log('\n🤖 Generating metadata for templates...');
@@ -133,7 +356,7 @@ async function fetchTemplates(mode: 'rebuild' | 'update' = 'rebuild', generateMe
     } else if (generateMetadata && !process.env.OPENAI_API_KEY) {
       console.log('\n⚠️  Metadata generation requested but OPENAI_API_KEY not set');
     }
-    
+
   } catch (error) {
     console.error('\n❌ Error fetching templates:', error);
     process.exit(1);
@@ -237,39 +460,45 @@ async function generateTemplateMetadata(db: any, service: TemplateService) {
 }
 
 // Parse command line arguments
-function parseArgs(): { mode: 'rebuild' | 'update', generateMetadata: boolean, metadataOnly: boolean } {
+function parseArgs(): { mode: 'rebuild' | 'update', generateMetadata: boolean, metadataOnly: boolean, extractOnly: boolean } {
   const args = process.argv.slice(2);
-  
+
   let mode: 'rebuild' | 'update' = 'rebuild';
   let generateMetadata = false;
   let metadataOnly = false;
-  
+  let extractOnly = false;
+
   // Check for --mode flag
   const modeIndex = args.findIndex(arg => arg.startsWith('--mode'));
   if (modeIndex !== -1) {
     const modeArg = args[modeIndex];
     const modeValue = modeArg.includes('=') ? modeArg.split('=')[1] : args[modeIndex + 1];
-    
+
     if (modeValue === 'update') {
       mode = 'update';
     }
   }
-  
+
   // Check for --update flag as shorthand
   if (args.includes('--update')) {
     mode = 'update';
   }
-  
+
   // Check for --generate-metadata flag
   if (args.includes('--generate-metadata') || args.includes('--metadata')) {
     generateMetadata = true;
   }
-  
+
   // Check for --metadata-only flag
   if (args.includes('--metadata-only')) {
     metadataOnly = true;
   }
-  
+
+  // Check for --extract-only flag
+  if (args.includes('--extract-only') || args.includes('--extract')) {
+    extractOnly = true;
+  }
+
   // Show help if requested
   if (args.includes('--help') || args.includes('-h')) {
     console.log('Usage: npm run fetch:templates [options]\n');
@@ -279,17 +508,19 @@ function parseArgs(): { mode: 'rebuild' | 'update', generateMetadata: boolean, m
     console.log('  --generate-metadata    Generate AI metadata after fetching templates');
     console.log('  --metadata             Shorthand for --generate-metadata');
     console.log('  --metadata-only        Only generate metadata, skip template fetching');
+    console.log('  --extract-only         Only extract node configs, skip template fetching');
+    console.log('  --extract              Shorthand for --extract-only');
     console.log('  --help, -h             Show this help message');
     process.exit(0);
   }
-  
-  return { mode, generateMetadata, metadataOnly };
+
+  return { mode, generateMetadata, metadataOnly, extractOnly };
 }
 
 // Run if called directly
 if (require.main === module) {
-  const { mode, generateMetadata, metadataOnly } = parseArgs();
-  fetchTemplates(mode, generateMetadata, metadataOnly).catch(console.error);
+  const { mode, generateMetadata, metadataOnly, extractOnly } = parseArgs();
+  fetchTemplates(mode, generateMetadata, metadataOnly, extractOnly).catch(console.error);
 }
 
 export { fetchTemplates };

src/scripts/sanitize-templates.ts

@@ -2,40 +2,75 @@
 import { createDatabaseAdapter } from '../database/database-adapter';
 import { logger } from '../utils/logger';
 import { TemplateSanitizer } from '../utils/template-sanitizer';
+import { gunzipSync, gzipSync } from 'zlib';
 
 async function sanitizeTemplates() {
   console.log('🧹 Sanitizing workflow templates in database...\n');
-  
+
   const db = await createDatabaseAdapter('./data/nodes.db');
   const sanitizer = new TemplateSanitizer();
-  
+
   try {
-    // Get all templates
-    const templates = db.prepare('SELECT id, name, workflow_json FROM templates').all() as any[];
+    // Get all templates - check both old and new format
+    const templates = db.prepare('SELECT id, name, workflow_json, workflow_json_compressed FROM templates').all() as any[];
     console.log(`Found ${templates.length} templates to check\n`);
-    
+
     let sanitizedCount = 0;
     const problematicTemplates: any[] = [];
-    
+
     for (const template of templates) {
-      const originalWorkflow = JSON.parse(template.workflow_json);
+      let originalWorkflow: any = null;
+      let useCompressed = false;
+
+      // Try compressed format first (newer format)
+      if (template.workflow_json_compressed) {
+        try {
+          const buffer = Buffer.from(template.workflow_json_compressed, 'base64');
+          const decompressed = gunzipSync(buffer).toString('utf-8');
+          originalWorkflow = JSON.parse(decompressed);
+          useCompressed = true;
+        } catch (e) {
+          console.log(`⚠️ Failed to decompress template ${template.id}, trying uncompressed`);
+        }
+      }
+
+      // Fall back to uncompressed format (deprecated)
+      if (!originalWorkflow && template.workflow_json) {
+        try {
+          originalWorkflow = JSON.parse(template.workflow_json);
+        } catch (e) {
+          console.log(`⚠️ Skipping template ${template.id}: Invalid JSON in both formats`);
+          continue;
+        }
+      }
+
+      if (!originalWorkflow) {
+        continue; // Skip templates without workflow data
+      }
+
       const { sanitized: sanitizedWorkflow, wasModified } = sanitizer.sanitizeWorkflow(originalWorkflow);
-      
+
       if (wasModified) {
         // Get detected tokens for reporting
         const detectedTokens = sanitizer.detectTokens(originalWorkflow);
-        
-        // Update the template with sanitized version
-        const stmt = db.prepare('UPDATE templates SET workflow_json = ? WHERE id = ?');
-        stmt.run(JSON.stringify(sanitizedWorkflow), template.id);
-        
+
+        // Update the template with sanitized version in the same format
+        if (useCompressed) {
+          const compressed = gzipSync(JSON.stringify(sanitizedWorkflow)).toString('base64');
+          const stmt = db.prepare('UPDATE templates SET workflow_json_compressed = ? WHERE id = ?');
+          stmt.run(compressed, template.id);
+        } else {
+          const stmt = db.prepare('UPDATE templates SET workflow_json = ? WHERE id = ?');
+          stmt.run(JSON.stringify(sanitizedWorkflow), template.id);
+        }
+
         sanitizedCount++;
         problematicTemplates.push({
           id: template.id,
           name: template.name,
           tokens: detectedTokens
         });
-        
+
         console.log(`✅ Sanitized template ${template.id}: ${template.name}`);
         detectedTokens.forEach(token => {
           console.log(`   - Found: ${token.substring(0, 20)}...`);

src/scripts/test-autofix-documentation.ts

@@ -0,0 +1,121 @@
+#!/usr/bin/env npx tsx
+
+/**
+ * Test script to verify n8n_autofix_workflow documentation is properly integrated
+ */
+
+import { toolsDocumentation } from '../mcp/tool-docs';
+import { getToolDocumentation } from '../mcp/tools-documentation';
+import { Logger } from '../utils/logger';
+
+const logger = new Logger({ prefix: '[AutofixDoc Test]' });
+
+async function testAutofixDocumentation() {
+  logger.info('Testing n8n_autofix_workflow documentation...\n');
+
+  // Test 1: Check if documentation exists in the registry
+  logger.info('Test 1: Checking documentation registry');
+  const hasDoc = 'n8n_autofix_workflow' in toolsDocumentation;
+  if (hasDoc) {
+    logger.info('✅ Documentation found in registry');
+  } else {
+    logger.error('❌ Documentation NOT found in registry');
+    logger.info('Available tools:', Object.keys(toolsDocumentation).filter(k => k.includes('autofix')));
+  }
+
+  // Test 2: Check documentation structure
+  if (hasDoc) {
+    logger.info('\nTest 2: Checking documentation structure');
+    const doc = toolsDocumentation['n8n_autofix_workflow'];
+
+    const hasEssentials = doc.essentials &&
+                         doc.essentials.description &&
+                         doc.essentials.keyParameters &&
+                         doc.essentials.example;
+
+    const hasFull = doc.full &&
+                   doc.full.description &&
+                   doc.full.parameters &&
+                   doc.full.examples;
+
+    if (hasEssentials) {
+      logger.info('✅ Essentials documentation complete');
+      logger.info(`  Description: ${doc.essentials.description.substring(0, 80)}...`);
+      logger.info(`  Key params: ${doc.essentials.keyParameters.join(', ')}`);
+    } else {
+      logger.error('❌ Essentials documentation incomplete');
+    }
+
+    if (hasFull) {
+      logger.info('✅ Full documentation complete');
+      logger.info(`  Parameters: ${Object.keys(doc.full.parameters).join(', ')}`);
+      logger.info(`  Examples: ${doc.full.examples.length} provided`);
+    } else {
+      logger.error('❌ Full documentation incomplete');
+    }
+  }
+
+  // Test 3: Test getToolDocumentation function
+  logger.info('\nTest 3: Testing getToolDocumentation function');
+
+  try {
+    const essentialsDoc = getToolDocumentation('n8n_autofix_workflow', 'essentials');
+    if (essentialsDoc.includes("Tool 'n8n_autofix_workflow' not found")) {
+      logger.error('❌ Essentials documentation retrieval failed');
+    } else {
+      logger.info('✅ Essentials documentation retrieved');
+      const lines = essentialsDoc.split('\n').slice(0, 3);
+      lines.forEach(line => logger.info(`  ${line}`));
+    }
+  } catch (error) {
+    logger.error('❌ Error retrieving essentials documentation:', error);
+  }
+
+  try {
+    const fullDoc = getToolDocumentation('n8n_autofix_workflow', 'full');
+    if (fullDoc.includes("Tool 'n8n_autofix_workflow' not found")) {
+      logger.error('❌ Full documentation retrieval failed');
+    } else {
+      logger.info('✅ Full documentation retrieved');
+      const lines = fullDoc.split('\n').slice(0, 3);
+      lines.forEach(line => logger.info(`  ${line}`));
+    }
+  } catch (error) {
+    logger.error('❌ Error retrieving full documentation:', error);
+  }
+
+  // Test 4: Check if tool is listed in workflow management tools
+  logger.info('\nTest 4: Checking workflow management tools listing');
+  const workflowTools = Object.keys(toolsDocumentation).filter(k => k.startsWith('n8n_'));
+  const hasAutofix = workflowTools.includes('n8n_autofix_workflow');
+
+  if (hasAutofix) {
+    logger.info('✅ n8n_autofix_workflow is listed in workflow management tools');
+    logger.info(`  Total workflow tools: ${workflowTools.length}`);
+
+    // Show related tools
+    const relatedTools = workflowTools.filter(t =>
+      t.includes('validate') || t.includes('update') || t.includes('fix')
+    );
+    logger.info(`  Related tools: ${relatedTools.join(', ')}`);
+  } else {
+    logger.error('❌ n8n_autofix_workflow NOT listed in workflow management tools');
+  }
+
+  // Summary
+  logger.info('\n' + '='.repeat(60));
+  logger.info('Summary:');
+
+  if (hasDoc && hasAutofix) {
+    logger.info('✨ Documentation integration successful!');
+    logger.info('The n8n_autofix_workflow tool documentation is properly integrated.');
+    logger.info('\nTo use in MCP:');
+    logger.info('  - Essentials: tools_documentation({topic: "n8n_autofix_workflow"})');
+    logger.info('  - Full: tools_documentation({topic: "n8n_autofix_workflow", depth: "full"})');
+  } else {
+    logger.error('⚠️ Documentation integration incomplete');
+    logger.info('Please check the implementation and rebuild the project.');
+  }
+}
+
+testAutofixDocumentation().catch(console.error);

src/scripts/test-autofix-workflow.ts

@@ -0,0 +1,251 @@
+/**
+ * Test script for n8n_autofix_workflow functionality
+ *
+ * Tests the automatic fixing of common workflow validation errors:
+ * 1. Expression format errors (missing = prefix)
+ * 2. TypeVersion corrections
+ * 3. Error output configuration issues
+ */
+
+import { WorkflowAutoFixer } from '../services/workflow-auto-fixer';
+import { WorkflowValidator } from '../services/workflow-validator';
+import { EnhancedConfigValidator } from '../services/enhanced-config-validator';
+import { ExpressionFormatValidator } from '../services/expression-format-validator';
+import { NodeRepository } from '../database/node-repository';
+import { Logger } from '../utils/logger';
+import { createDatabaseAdapter } from '../database/database-adapter';
+import * as path from 'path';
+
+const logger = new Logger({ prefix: '[TestAutofix]' });
+
+async function testAutofix() {
+  // Initialize database and repository
+  const dbPath = path.join(__dirname, '../../data/nodes.db');
+  const dbAdapter = await createDatabaseAdapter(dbPath);
+  const repository = new NodeRepository(dbAdapter);
+
+  // Test workflow with various issues
+  const testWorkflow = {
+    id: 'test_workflow_1',
+    name: 'Test Workflow for Autofix',
+    nodes: [
+      {
+        id: 'webhook_1',
+        name: 'Webhook',
+        type: 'n8n-nodes-base.webhook',
+        typeVersion: 1.1,
+        position: [250, 300],
+        parameters: {
+          httpMethod: 'GET',
+          path: 'test-webhook',
+          responseMode: 'onReceived',
+          responseData: 'firstEntryJson'
+        }
+      },
+      {
+        id: 'http_1',
+        name: 'HTTP Request',
+        type: 'n8n-nodes-base.httpRequest',
+        typeVersion: 5.0, // Invalid - max is 4.2
+        position: [450, 300],
+        parameters: {
+          method: 'GET',
+          url: '{{ $json.webhookUrl }}', // Missing = prefix
+          sendHeaders: true,
+          headerParameters: {
+            parameters: [
+              {
+                name: 'Authorization',
+                value: '{{ $json.token }}' // Missing = prefix
+              }
+            ]
+          }
+        },
+        onError: 'continueErrorOutput' // Has onError but no error connections
+      },
+      {
+        id: 'set_1',
+        name: 'Set',
+        type: 'n8n-nodes-base.set',
+        typeVersion: 3.5, // Invalid version
+        position: [650, 300],
+        parameters: {
+          mode: 'manual',
+          duplicateItem: false,
+          values: {
+            values: [
+              {
+                name: 'status',
+                value: '{{ $json.success }}' // Missing = prefix
+              }
+            ]
+          }
+        }
+      }
+    ],
+    connections: {
+      'Webhook': {
+        main: [
+          [
+            {
+              node: 'HTTP Request',
+              type: 'main',
+              index: 0
+            }
+          ]
+        ]
+      },
+      'HTTP Request': {
+        main: [
+          [
+            {
+              node: 'Set',
+              type: 'main',
+              index: 0
+            }
+          ]
+          // Missing error output connection for onError: 'continueErrorOutput'
+        ]
+      }
+    }
+  };
+
+  logger.info('=== Testing Workflow Auto-Fixer ===\n');
+
+  // Step 1: Validate the workflow to identify issues
+  logger.info('Step 1: Validating workflow to identify issues...');
+  const validator = new WorkflowValidator(repository, EnhancedConfigValidator);
+  const validationResult = await validator.validateWorkflow(testWorkflow as any, {
+    validateNodes: true,
+    validateConnections: true,
+    validateExpressions: true,
+    profile: 'ai-friendly'
+  });
+
+  logger.info(`Found ${validationResult.errors.length} errors and ${validationResult.warnings.length} warnings`);
+
+  // Step 2: Check for expression format issues
+  logger.info('\nStep 2: Checking for expression format issues...');
+  const allFormatIssues: any[] = [];
+  for (const node of testWorkflow.nodes) {
+    const formatContext = {
+      nodeType: node.type,
+      nodeName: node.name,
+      nodeId: node.id
+    };
+
+    const nodeFormatIssues = ExpressionFormatValidator.validateNodeParameters(
+      node.parameters,
+      formatContext
+    );
+
+    // Add node information to each format issue
+    const enrichedIssues = nodeFormatIssues.map(issue => ({
+      ...issue,
+      nodeName: node.name,
+      nodeId: node.id
+    }));
+
+    allFormatIssues.push(...enrichedIssues);
+  }
+
+  logger.info(`Found ${allFormatIssues.length} expression format issues`);
+
+  // Debug: Show the actual format issues
+  if (allFormatIssues.length > 0) {
+    logger.info('\nExpression format issues found:');
+    for (const issue of allFormatIssues) {
+      logger.info(`  - ${issue.fieldPath}: ${issue.issueType} (${issue.severity})`);
+      logger.info(`    Current: ${JSON.stringify(issue.currentValue)}`);
+      logger.info(`    Fixed: ${JSON.stringify(issue.correctedValue)}`);
+    }
+  }
+
+  // Step 3: Generate fixes in preview mode
+  logger.info('\nStep 3: Generating fixes (preview mode)...');
+  const autoFixer = new WorkflowAutoFixer();
+  const previewResult = autoFixer.generateFixes(
+    testWorkflow as any,
+    validationResult,
+    allFormatIssues,
+    {
+      applyFixes: false, // Preview mode
+      confidenceThreshold: 'medium'
+    }
+  );
+
+  logger.info(`\nGenerated ${previewResult.fixes.length} fixes:`);
+  logger.info(`Summary: ${previewResult.summary}`);
+  logger.info('\nFixes by type:');
+  for (const [type, count] of Object.entries(previewResult.stats.byType)) {
+    if (count > 0) {
+      logger.info(`  - ${type}: ${count}`);
+    }
+  }
+
+  logger.info('\nFixes by confidence:');
+  for (const [confidence, count] of Object.entries(previewResult.stats.byConfidence)) {
+    if (count > 0) {
+      logger.info(`  - ${confidence}: ${count}`);
+    }
+  }
+
+  // Step 4: Display individual fixes
+  logger.info('\nDetailed fixes:');
+  for (const fix of previewResult.fixes) {
+    logger.info(`\n[${fix.confidence.toUpperCase()}] ${fix.node}.${fix.field} (${fix.type})`);
+    logger.info(`  Before: ${JSON.stringify(fix.before)}`);
+    logger.info(`  After:  ${JSON.stringify(fix.after)}`);
+    logger.info(`  Description: ${fix.description}`);
+  }
+
+  // Step 5: Display generated operations
+  logger.info('\n\nGenerated diff operations:');
+  for (const op of previewResult.operations) {
+    logger.info(`\nOperation: ${op.type}`);
+    logger.info(`  Details: ${JSON.stringify(op, null, 2)}`);
+  }
+
+  // Step 6: Test with different confidence thresholds
+  logger.info('\n\n=== Testing Different Confidence Thresholds ===');
+
+  for (const threshold of ['high', 'medium', 'low'] as const) {
+    const result = autoFixer.generateFixes(
+      testWorkflow as any,
+      validationResult,
+      allFormatIssues,
+      {
+        applyFixes: false,
+        confidenceThreshold: threshold
+      }
+    );
+    logger.info(`\nThreshold "${threshold}": ${result.fixes.length} fixes`);
+  }
+
+  // Step 7: Test with specific fix types
+  logger.info('\n\n=== Testing Specific Fix Types ===');
+
+  const fixTypes = ['expression-format', 'typeversion-correction', 'error-output-config'] as const;
+  for (const fixType of fixTypes) {
+    const result = autoFixer.generateFixes(
+      testWorkflow as any,
+      validationResult,
+      allFormatIssues,
+      {
+        applyFixes: false,
+        fixTypes: [fixType]
+      }
+    );
+    logger.info(`\nFix type "${fixType}": ${result.fixes.length} fixes`);
+  }
+
+  logger.info('\n\n✅ Autofix test completed successfully!');
+
+  await dbAdapter.close();
+}
+
+// Run the test
+testAutofix().catch(error => {
+  logger.error('Test failed:', error);
+  process.exit(1);
+});

src/scripts/test-execution-filtering.ts

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+/**
+ * Manual testing script for execution filtering feature
+ *
+ * This script demonstrates all modes of the n8n_get_execution tool
+ * with various filtering options.
+ *
+ * Usage: npx tsx src/scripts/test-execution-filtering.ts
+ */
+
+import {
+  generatePreview,
+  filterExecutionData,
+  processExecution,
+} from '../services/execution-processor';
+import { ExecutionFilterOptions, Execution, ExecutionStatus } from '../types/n8n-api';
+
+console.log('='.repeat(80));
+console.log('Execution Filtering Feature - Manual Test Suite');
+console.log('='.repeat(80));
+console.log('');
+
+/**
+ * Mock execution factory (simplified version for testing)
+ */
+function createTestExecution(itemCount: number): Execution {
+  const items = Array.from({ length: itemCount }, (_, i) => ({
+    json: {
+      id: i + 1,
+      name: `Item ${i + 1}`,
+      email: `user${i}@example.com`,
+      value: Math.random() * 1000,
+      metadata: {
+        createdAt: new Date().toISOString(),
+        tags: ['tag1', 'tag2'],
+      },
+    },
+  }));
+
+  return {
+    id: `test-exec-${Date.now()}`,
+    workflowId: 'workflow-test',
+    status: ExecutionStatus.SUCCESS,
+    mode: 'manual',
+    finished: true,
+    startedAt: '2024-01-01T10:00:00.000Z',
+    stoppedAt: '2024-01-01T10:00:05.000Z',
+    data: {
+      resultData: {
+        runData: {
+          'HTTP Request': [
+            {
+              startTime: Date.now(),
+              executionTime: 234,
+              data: {
+                main: [items],
+              },
+            },
+          ],
+          'Filter': [
+            {
+              startTime: Date.now(),
+              executionTime: 45,
+              data: {
+                main: [items.slice(0, Math.floor(itemCount / 2))],
+              },
+            },
+          ],
+          'Set': [
+            {
+              startTime: Date.now(),
+              executionTime: 12,
+              data: {
+                main: [items.slice(0, 5)],
+              },
+            },
+          ],
+        },
+      },
+    },
+  };
+}
+
+/**
+ * Test 1: Preview Mode
+ */
+console.log('📊 TEST 1: Preview Mode (No Data, Just Structure)');
+console.log('-'.repeat(80));
+
+const execution1 = createTestExecution(50);
+const { preview, recommendation } = generatePreview(execution1);
+
+console.log('Preview:', JSON.stringify(preview, null, 2));
+console.log('\nRecommendation:', JSON.stringify(recommendation, null, 2));
+console.log('\n✅ Preview mode shows structure without consuming tokens for data\n');
+
+/**
+ * Test 2: Summary Mode (Default)
+ */
+console.log('📝 TEST 2: Summary Mode (2 items per node)');
+console.log('-'.repeat(80));
+
+const execution2 = createTestExecution(50);
+const summaryResult = filterExecutionData(execution2, { mode: 'summary' });
+
+console.log('Summary Mode Result:');
+console.log('- Mode:', summaryResult.mode);
+console.log('- Summary:', JSON.stringify(summaryResult.summary, null, 2));
+console.log('- HTTP Request items shown:', summaryResult.nodes?.['HTTP Request']?.data?.metadata.itemsShown);
+console.log('- HTTP Request truncated:', summaryResult.nodes?.['HTTP Request']?.data?.metadata.truncated);
+console.log('\n✅ Summary mode returns 2 items per node (safe default)\n');
+
+/**
+ * Test 3: Filtered Mode with Custom Limit
+ */
+console.log('🎯 TEST 3: Filtered Mode (Custom itemsLimit: 5)');
+console.log('-'.repeat(80));
+
+const execution3 = createTestExecution(100);
+const filteredResult = filterExecutionData(execution3, {
+  mode: 'filtered',
+  itemsLimit: 5,
+});
+
+console.log('Filtered Mode Result:');
+console.log('- Items shown per node:', filteredResult.nodes?.['HTTP Request']?.data?.metadata.itemsShown);
+console.log('- Total items available:', filteredResult.nodes?.['HTTP Request']?.data?.metadata.totalItems);
+console.log('- More data available:', filteredResult.summary?.hasMoreData);
+console.log('\n✅ Filtered mode allows custom item limits\n');
+
+/**
+ * Test 4: Node Name Filtering
+ */
+console.log('🔍 TEST 4: Filter to Specific Nodes');
+console.log('-'.repeat(80));
+
+const execution4 = createTestExecution(30);
+const nodeFilterResult = filterExecutionData(execution4, {
+  mode: 'filtered',
+  nodeNames: ['HTTP Request'],
+  itemsLimit: 3,
+});
+
+console.log('Node Filter Result:');
+console.log('- Nodes in result:', Object.keys(nodeFilterResult.nodes || {}));
+console.log('- Expected: ["HTTP Request"]');
+console.log('- Executed nodes:', nodeFilterResult.summary?.executedNodes);
+console.log('- Total nodes:', nodeFilterResult.summary?.totalNodes);
+console.log('\n✅ Can filter to specific nodes only\n');
+
+/**
+ * Test 5: Structure-Only Mode (itemsLimit: 0)
+ */
+console.log('🏗️  TEST 5: Structure-Only Mode (itemsLimit: 0)');
+console.log('-'.repeat(80));
+
+const execution5 = createTestExecution(100);
+const structureResult = filterExecutionData(execution5, {
+  mode: 'filtered',
+  itemsLimit: 0,
+});
+
+console.log('Structure-Only Result:');
+console.log('- Items shown:', structureResult.nodes?.['HTTP Request']?.data?.metadata.itemsShown);
+console.log('- First item (structure):', JSON.stringify(
+  structureResult.nodes?.['HTTP Request']?.data?.output?.[0]?.[0],
+  null,
+  2
+));
+console.log('\n✅ Structure-only mode shows data shape without values\n');
+
+/**
+ * Test 6: Full Mode
+ */
+console.log('💾 TEST 6: Full Mode (All Data)');
+console.log('-'.repeat(80));
+
+const execution6 = createTestExecution(5); // Small dataset
+const fullResult = filterExecutionData(execution6, { mode: 'full' });
+
+console.log('Full Mode Result:');
+console.log('- Items shown:', fullResult.nodes?.['HTTP Request']?.data?.metadata.itemsShown);
+console.log('- Total items:', fullResult.nodes?.['HTTP Request']?.data?.metadata.totalItems);
+console.log('- Truncated:', fullResult.nodes?.['HTTP Request']?.data?.metadata.truncated);
+console.log('\n✅ Full mode returns all data (use with caution)\n');
+
+/**
+ * Test 7: Backward Compatibility
+ */
+console.log('🔄 TEST 7: Backward Compatibility (No Filtering)');
+console.log('-'.repeat(80));
+
+const execution7 = createTestExecution(10);
+const legacyResult = processExecution(execution7, {});
+
+console.log('Legacy Result:');
+console.log('- Returns original execution:', legacyResult === execution7);
+console.log('- Type:', typeof legacyResult);
+console.log('\n✅ Backward compatible - no options returns original execution\n');
+
+/**
+ * Test 8: Input Data Inclusion
+ */
+console.log('🔗 TEST 8: Include Input Data');
+console.log('-'.repeat(80));
+
+const execution8 = createTestExecution(5);
+const inputDataResult = filterExecutionData(execution8, {
+  mode: 'filtered',
+  itemsLimit: 2,
+  includeInputData: true,
+});
+
+console.log('Input Data Result:');
+console.log('- Has input data:', !!inputDataResult.nodes?.['HTTP Request']?.data?.input);
+console.log('- Has output data:', !!inputDataResult.nodes?.['HTTP Request']?.data?.output);
+console.log('\n✅ Can include input data for debugging\n');
+
+/**
+ * Test 9: itemsLimit Validation
+ */
+console.log('⚠️  TEST 9: itemsLimit Validation');
+console.log('-'.repeat(80));
+
+const execution9 = createTestExecution(50);
+
+// Test negative value
+const negativeResult = filterExecutionData(execution9, {
+  mode: 'filtered',
+  itemsLimit: -5,
+});
+console.log('- Negative itemsLimit (-5) handled:', negativeResult.nodes?.['HTTP Request']?.data?.metadata.itemsShown === 2);
+
+// Test very large value
+const largeResult = filterExecutionData(execution9, {
+  mode: 'filtered',
+  itemsLimit: 999999,
+});
+console.log('- Large itemsLimit (999999) capped:', (largeResult.nodes?.['HTTP Request']?.data?.metadata.itemsShown || 0) <= 1000);
+
+// Test unlimited (-1)
+const unlimitedResult = filterExecutionData(execution9, {
+  mode: 'filtered',
+  itemsLimit: -1,
+});
+console.log('- Unlimited itemsLimit (-1) works:', unlimitedResult.nodes?.['HTTP Request']?.data?.metadata.itemsShown === 50);
+
+console.log('\n✅ itemsLimit validation works correctly\n');
+
+/**
+ * Test 10: Recommendation Following
+ */
+console.log('🎯 TEST 10: Follow Recommendation Workflow');
+console.log('-'.repeat(80));
+
+const execution10 = createTestExecution(100);
+const { preview: preview10, recommendation: rec10 } = generatePreview(execution10);
+
+console.log('1. Preview shows:', {
+  totalItems: preview10.nodes['HTTP Request']?.itemCounts.output,
+  sizeKB: preview10.estimatedSizeKB,
+});
+
+console.log('\n2. Recommendation:', {
+  canFetchFull: rec10.canFetchFull,
+  suggestedMode: rec10.suggestedMode,
+  suggestedItemsLimit: rec10.suggestedItemsLimit,
+  reason: rec10.reason,
+});
+
+// Follow recommendation
+const options: ExecutionFilterOptions = {
+  mode: rec10.suggestedMode,
+  itemsLimit: rec10.suggestedItemsLimit,
+};
+
+const recommendedResult = filterExecutionData(execution10, options);
+
+console.log('\n3. Following recommendation gives:', {
+  mode: recommendedResult.mode,
+  itemsShown: recommendedResult.nodes?.['HTTP Request']?.data?.metadata.itemsShown,
+  hasMoreData: recommendedResult.summary?.hasMoreData,
+});
+
+console.log('\n✅ Recommendation workflow helps make optimal choices\n');
+
+/**
+ * Summary
+ */
+console.log('='.repeat(80));
+console.log('✨ All Tests Completed Successfully!');
+console.log('='.repeat(80));
+console.log('\n🎉 Execution Filtering Feature is Working!\n');
+console.log('Key Takeaways:');
+console.log('1. Always use preview mode first for unknown datasets');
+console.log('2. Follow the recommendation for optimal token usage');
+console.log('3. Use nodeNames to filter to relevant nodes');
+console.log('4. itemsLimit: 0 shows structure without data');
+console.log('5. itemsLimit: -1 returns unlimited items (use with caution)');
+console.log('6. Summary mode (2 items) is a safe default');
+console.log('7. Full mode should only be used for small datasets');
+console.log('');

src/scripts/test-node-suggestions.ts

@@ -0,0 +1,205 @@
+#!/usr/bin/env npx tsx
+/**
+ * Test script for enhanced node type suggestions
+ * Tests the NodeSimilarityService to ensure it provides helpful suggestions
+ * for unknown or incorrectly typed nodes in workflows.
+ */
+
+import { createDatabaseAdapter } from '../database/database-adapter';
+import { NodeRepository } from '../database/node-repository';
+import { NodeSimilarityService } from '../services/node-similarity-service';
+import { WorkflowValidator } from '../services/workflow-validator';
+import { EnhancedConfigValidator } from '../services/enhanced-config-validator';
+import { WorkflowAutoFixer } from '../services/workflow-auto-fixer';
+import { Logger } from '../utils/logger';
+import path from 'path';
+
+const logger = new Logger({ prefix: '[NodeSuggestions Test]' });
+const console = {
+  log: (msg: string) => logger.info(msg),
+  error: (msg: string, err?: any) => logger.error(msg, err)
+};
+
+async function testNodeSimilarity() {
+  console.log('🔍 Testing Enhanced Node Type Suggestions\n');
+
+  // Initialize database and services
+  const dbPath = path.join(process.cwd(), 'data/nodes.db');
+  const db = await createDatabaseAdapter(dbPath);
+  const repository = new NodeRepository(db);
+  const similarityService = new NodeSimilarityService(repository);
+  const validator = new WorkflowValidator(repository, EnhancedConfigValidator);
+
+  // Test cases with various invalid node types
+  const testCases = [
+    // Case variations
+    { invalid: 'HttpRequest', expected: 'nodes-base.httpRequest' },
+    { invalid: 'HTTPRequest', expected: 'nodes-base.httpRequest' },
+    { invalid: 'Webhook', expected: 'nodes-base.webhook' },
+    { invalid: 'WebHook', expected: 'nodes-base.webhook' },
+
+    // Missing package prefix
+    { invalid: 'slack', expected: 'nodes-base.slack' },
+    { invalid: 'googleSheets', expected: 'nodes-base.googleSheets' },
+    { invalid: 'telegram', expected: 'nodes-base.telegram' },
+
+    // Common typos
+    { invalid: 'htpRequest', expected: 'nodes-base.httpRequest' },
+    { invalid: 'webook', expected: 'nodes-base.webhook' },
+    { invalid: 'slak', expected: 'nodes-base.slack' },
+
+    // Partial names
+    { invalid: 'http', expected: 'nodes-base.httpRequest' },
+    { invalid: 'sheet', expected: 'nodes-base.googleSheets' },
+
+    // Wrong package prefix
+    { invalid: 'nodes-base.openai', expected: 'nodes-langchain.openAi' },
+    { invalid: 'n8n-nodes-base.httpRequest', expected: 'nodes-base.httpRequest' },
+
+    // Complete unknowns
+    { invalid: 'foobar', expected: null },
+    { invalid: 'xyz123', expected: null },
+  ];
+
+  console.log('Testing individual node type suggestions:');
+  console.log('=' .repeat(60));
+
+  for (const testCase of testCases) {
+    const suggestions = await similarityService.findSimilarNodes(testCase.invalid, 3);
+
+    console.log(`\n❌ Invalid type: "${testCase.invalid}"`);
+
+    if (suggestions.length > 0) {
+      console.log('✨ Suggestions:');
+      for (const suggestion of suggestions) {
+        const confidence = Math.round(suggestion.confidence * 100);
+        const marker = suggestion.nodeType === testCase.expected ? '✅' : '  ';
+        console.log(
+          `${marker} ${suggestion.nodeType} (${confidence}% match) - ${suggestion.reason}`
+        );
+
+        if (suggestion.confidence >= 0.9) {
+          console.log('   💡 Can be auto-fixed!');
+        }
+      }
+
+      // Check if expected match was found
+      if (testCase.expected) {
+        const found = suggestions.some(s => s.nodeType === testCase.expected);
+        if (!found) {
+          console.log(`   ⚠️  Expected "${testCase.expected}" was not suggested!`);
+        }
+      }
+    } else {
+      console.log('   No suggestions found');
+      if (testCase.expected) {
+        console.log(`   ⚠️  Expected "${testCase.expected}" was not suggested!`);
+      }
+    }
+  }
+
+  console.log('\n' + '='.repeat(60));
+  console.log('\n📋 Testing workflow validation with unknown nodes:');
+  console.log('='.repeat(60));
+
+  // Test with a sample workflow
+  const testWorkflow = {
+    id: 'test-workflow',
+    name: 'Test Workflow',
+    nodes: [
+      {
+        id: '1',
+        name: 'Start',
+        type: 'nodes-base.manualTrigger',
+        position: [100, 100] as [number, number],
+        parameters: {},
+        typeVersion: 1
+      },
+      {
+        id: '2',
+        name: 'HTTP Request',
+        type: 'HTTPRequest', // Wrong capitalization
+        position: [300, 100] as [number, number],
+        parameters: {},
+        typeVersion: 1
+      },
+      {
+        id: '3',
+        name: 'Slack',
+        type: 'slack', // Missing prefix
+        position: [500, 100] as [number, number],
+        parameters: {},
+        typeVersion: 1
+      },
+      {
+        id: '4',
+        name: 'Unknown',
+        type: 'foobar', // Completely unknown
+        position: [700, 100] as [number, number],
+        parameters: {},
+        typeVersion: 1
+      }
+    ],
+    connections: {
+      'Start': {
+        main: [[{ node: 'HTTP Request', type: 'main', index: 0 }]]
+      },
+      'HTTP Request': {
+        main: [[{ node: 'Slack', type: 'main', index: 0 }]]
+      },
+      'Slack': {
+        main: [[{ node: 'Unknown', type: 'main', index: 0 }]]
+      }
+    },
+    settings: {}
+  };
+
+  const validationResult = await validator.validateWorkflow(testWorkflow as any, {
+    validateNodes: true,
+    validateConnections: false,
+    validateExpressions: false,
+    profile: 'runtime'
+  });
+
+  console.log('\nValidation Results:');
+  for (const error of validationResult.errors) {
+    if (error.message?.includes('Unknown node type:')) {
+      console.log(`\n🔴 ${error.nodeName}: ${error.message}`);
+    }
+  }
+
+  console.log('\n' + '='.repeat(60));
+  console.log('\n🔧 Testing AutoFixer with node type corrections:');
+  console.log('='.repeat(60));
+
+  const autoFixer = new WorkflowAutoFixer(repository);
+  const fixResult = autoFixer.generateFixes(
+    testWorkflow as any,
+    validationResult,
+    [],
+    {
+      applyFixes: false,
+      fixTypes: ['node-type-correction'],
+      confidenceThreshold: 'high'
+    }
+  );
+
+  if (fixResult.fixes.length > 0) {
+    console.log('\n✅ Auto-fixable issues found:');
+    for (const fix of fixResult.fixes) {
+      console.log(`   • ${fix.description}`);
+    }
+    console.log(`\nSummary: ${fixResult.summary}`);
+  } else {
+    console.log('\n❌ No auto-fixable node type issues found (only high-confidence fixes are applied)');
+  }
+
+  console.log('\n' + '='.repeat(60));
+  console.log('\n✨ Test complete!');
+}
+
+// Run the test
+testNodeSimilarity().catch(error => {
+  console.error('Test failed:', error);
+  process.exit(1);
+});

src/scripts/test-summary.ts

@@ -0,0 +1,81 @@
+#!/usr/bin/env npx tsx
+
+import { createDatabaseAdapter } from '../database/database-adapter';
+import { NodeRepository } from '../database/node-repository';
+import { NodeSimilarityService } from '../services/node-similarity-service';
+import path from 'path';
+
+async function testSummary() {
+  const dbPath = path.join(process.cwd(), 'data/nodes.db');
+  const db = await createDatabaseAdapter(dbPath);
+  const repository = new NodeRepository(db);
+  const similarityService = new NodeSimilarityService(repository);
+
+  const testCases = [
+    { invalid: 'HttpRequest', expected: 'nodes-base.httpRequest' },
+    { invalid: 'HTTPRequest', expected: 'nodes-base.httpRequest' },
+    { invalid: 'Webhook', expected: 'nodes-base.webhook' },
+    { invalid: 'WebHook', expected: 'nodes-base.webhook' },
+    { invalid: 'slack', expected: 'nodes-base.slack' },
+    { invalid: 'googleSheets', expected: 'nodes-base.googleSheets' },
+    { invalid: 'telegram', expected: 'nodes-base.telegram' },
+    { invalid: 'htpRequest', expected: 'nodes-base.httpRequest' },
+    { invalid: 'webook', expected: 'nodes-base.webhook' },
+    { invalid: 'slak', expected: 'nodes-base.slack' },
+    { invalid: 'http', expected: 'nodes-base.httpRequest' },
+    { invalid: 'sheet', expected: 'nodes-base.googleSheets' },
+    { invalid: 'nodes-base.openai', expected: 'nodes-langchain.openAi' },
+    { invalid: 'n8n-nodes-base.httpRequest', expected: 'nodes-base.httpRequest' },
+    { invalid: 'foobar', expected: null },
+    { invalid: 'xyz123', expected: null },
+  ];
+
+  let passed = 0;
+  let failed = 0;
+
+  console.log('Test Results Summary:');
+  console.log('='.repeat(60));
+
+  for (const testCase of testCases) {
+    const suggestions = await similarityService.findSimilarNodes(testCase.invalid, 3);
+
+    let result = '❌';
+    let status = 'FAILED';
+
+    if (testCase.expected === null) {
+      // Should have no suggestions
+      if (suggestions.length === 0) {
+        result = '✅';
+        status = 'PASSED';
+        passed++;
+      } else {
+        failed++;
+      }
+    } else {
+      // Should have the expected suggestion
+      const found = suggestions.some(s => s.nodeType === testCase.expected);
+      if (found) {
+        const suggestion = suggestions.find(s => s.nodeType === testCase.expected);
+        const isAutoFixable = suggestion && suggestion.confidence >= 0.9;
+        result = '✅';
+        status = isAutoFixable ? 'PASSED (auto-fixable)' : 'PASSED';
+        passed++;
+      } else {
+        failed++;
+      }
+    }
+
+    console.log(`${result} "${testCase.invalid}" → ${testCase.expected || 'no suggestions'}: ${status}`);
+  }
+
+  console.log('='.repeat(60));
+  console.log(`\nTotal: ${passed}/${testCases.length} tests passed`);
+
+  if (failed === 0) {
+    console.log('🎉 All tests passed!');
+  } else {
+    console.log(`⚠️  ${failed} tests failed`);
+  }
+}
+
+testSummary().catch(console.error);

src/scripts/test-webhook-autofix.ts

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+
+/**
+ * Test script for webhook path autofixer functionality
+ */
+
+import { NodeRepository } from '../database/node-repository';
+import { createDatabaseAdapter } from '../database/database-adapter';
+import { WorkflowAutoFixer } from '../services/workflow-auto-fixer';
+import { WorkflowValidator } from '../services/workflow-validator';
+import { EnhancedConfigValidator } from '../services/enhanced-config-validator';
+import { Workflow } from '../types/n8n-api';
+import { Logger } from '../utils/logger';
+import { join } from 'path';
+
+const logger = new Logger({ prefix: '[TestWebhookAutofix]' });
+
+// Test workflow with webhook missing path
+const testWorkflow: Workflow = {
+  id: 'test_webhook_fix',
+  name: 'Test Webhook Autofix',
+  active: false,
+  nodes: [
+    {
+      id: '1',
+      name: 'Webhook',
+      type: 'n8n-nodes-base.webhook',
+      typeVersion: 2.1,
+      position: [250, 300],
+      parameters: {}, // Empty parameters - missing path
+    },
+    {
+      id: '2',
+      name: 'HTTP Request',
+      type: 'n8n-nodes-base.httpRequest',
+      typeVersion: 4.2,
+      position: [450, 300],
+      parameters: {
+        url: 'https://api.example.com/data',
+        method: 'GET'
+      }
+    }
+  ],
+  connections: {
+    'Webhook': {
+      main: [[{
+        node: 'HTTP Request',
+        type: 'main',
+        index: 0
+      }]]
+    }
+  },
+  settings: {
+    executionOrder: 'v1'
+  },
+  staticData: undefined
+};
+
+async function testWebhookAutofix() {
+  logger.info('Testing webhook path autofixer...');
+
+  // Initialize database and repository
+  const dbPath = join(process.cwd(), 'data', 'nodes.db');
+  const adapter = await createDatabaseAdapter(dbPath);
+  const repository = new NodeRepository(adapter);
+
+  // Create validators
+  const validator = new WorkflowValidator(repository, EnhancedConfigValidator);
+  const autoFixer = new WorkflowAutoFixer(repository);
+
+  // Step 1: Validate workflow to identify issues
+  logger.info('Step 1: Validating workflow to identify issues...');
+  const validationResult = await validator.validateWorkflow(testWorkflow);
+
+  console.log('\n📋 Validation Summary:');
+  console.log(`- Valid: ${validationResult.valid}`);
+  console.log(`- Errors: ${validationResult.errors.length}`);
+  console.log(`- Warnings: ${validationResult.warnings.length}`);
+
+  if (validationResult.errors.length > 0) {
+    console.log('\n❌ Errors found:');
+    validationResult.errors.forEach(error => {
+      console.log(`  - [${error.nodeName || error.nodeId}] ${error.message}`);
+    });
+  }
+
+  // Step 2: Generate fixes (preview mode)
+  logger.info('\nStep 2: Generating fixes in preview mode...');
+
+  const fixResult = autoFixer.generateFixes(
+    testWorkflow,
+    validationResult,
+    [], // No expression format issues to pass
+    {
+      applyFixes: false, // Preview mode
+      fixTypes: ['webhook-missing-path'] // Only test webhook fixes
+    }
+  );
+
+  console.log('\n🔧 Fix Results:');
+  console.log(`- Summary: ${fixResult.summary}`);
+  console.log(`- Total fixes: ${fixResult.stats.total}`);
+  console.log(`- Webhook path fixes: ${fixResult.stats.byType['webhook-missing-path']}`);
+
+  if (fixResult.fixes.length > 0) {
+    console.log('\n📝 Detailed Fixes:');
+    fixResult.fixes.forEach(fix => {
+      console.log(`  - Node: ${fix.node}`);
+      console.log(`    Field: ${fix.field}`);
+      console.log(`    Type: ${fix.type}`);
+      console.log(`    Before: ${fix.before || 'undefined'}`);
+      console.log(`    After: ${fix.after}`);
+      console.log(`    Confidence: ${fix.confidence}`);
+      console.log(`    Description: ${fix.description}`);
+    });
+  }
+
+  if (fixResult.operations.length > 0) {
+    console.log('\n🔄 Operations to Apply:');
+    fixResult.operations.forEach(op => {
+      if (op.type === 'updateNode') {
+        console.log(`  - Update Node: ${op.nodeId}`);
+        console.log(`    Updates: ${JSON.stringify(op.updates, null, 2)}`);
+      }
+    });
+  }
+
+  // Step 3: Verify UUID format
+  if (fixResult.fixes.length > 0) {
+    const webhookFix = fixResult.fixes.find(f => f.type === 'webhook-missing-path');
+    if (webhookFix) {
+      const uuid = webhookFix.after as string;
+      const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+      const isValidUUID = uuidRegex.test(uuid);
+
+      console.log('\n✅ UUID Validation:');
+      console.log(`  - Generated UUID: ${uuid}`);
+      console.log(`  - Valid format: ${isValidUUID ? 'Yes' : 'No'}`);
+    }
+  }
+
+  logger.info('\n✨ Webhook autofix test completed successfully!');
+}
+
+// Run test
+testWebhookAutofix().catch(error => {
+  logger.error('Test failed:', error);
+  process.exit(1);
+});

src/services/confidence-scorer.ts

@@ -0,0 +1,211 @@
+/**
+ * Confidence Scorer for node-specific validations
+ *
+ * Provides confidence scores for node-specific recommendations,
+ * allowing users to understand the reliability of suggestions.
+ */
+
+export interface ConfidenceScore {
+  value: number; // 0.0 to 1.0
+  reason: string;
+  factors: ConfidenceFactor[];
+}
+
+export interface ConfidenceFactor {
+  name: string;
+  weight: number;
+  matched: boolean;
+  description: string;
+}
+
+export class ConfidenceScorer {
+  /**
+   * Calculate confidence score for resource locator recommendation
+   */
+  static scoreResourceLocatorRecommendation(
+    fieldName: string,
+    nodeType: string,
+    value: string
+  ): ConfidenceScore {
+    const factors: ConfidenceFactor[] = [];
+    let totalWeight = 0;
+    let matchedWeight = 0;
+
+    // Factor 1: Exact field name match (highest confidence)
+    const exactFieldMatch = this.checkExactFieldMatch(fieldName, nodeType);
+    factors.push({
+      name: 'exact-field-match',
+      weight: 0.5,
+      matched: exactFieldMatch,
+      description: `Field name '${fieldName}' is known to use resource locator in ${nodeType}`
+    });
+
+    // Factor 2: Field name pattern (medium confidence)
+    const patternMatch = this.checkFieldPattern(fieldName);
+    factors.push({
+      name: 'field-pattern',
+      weight: 0.3,
+      matched: patternMatch,
+      description: `Field name '${fieldName}' matches common resource locator patterns`
+    });
+
+    // Factor 3: Value pattern (low confidence)
+    const valuePattern = this.checkValuePattern(value);
+    factors.push({
+      name: 'value-pattern',
+      weight: 0.1,
+      matched: valuePattern,
+      description: 'Value contains patterns typical of resource identifiers'
+    });
+
+    // Factor 4: Node type category (medium confidence)
+    const nodeCategory = this.checkNodeCategory(nodeType);
+    factors.push({
+      name: 'node-category',
+      weight: 0.1,
+      matched: nodeCategory,
+      description: `Node type '${nodeType}' typically uses resource locators`
+    });
+
+    // Calculate final score
+    for (const factor of factors) {
+      totalWeight += factor.weight;
+      if (factor.matched) {
+        matchedWeight += factor.weight;
+      }
+    }
+
+    const score = totalWeight > 0 ? matchedWeight / totalWeight : 0;
+
+    // Determine reason based on score
+    let reason: string;
+    if (score >= 0.8) {
+      reason = 'High confidence: Multiple strong indicators suggest resource locator format';
+    } else if (score >= 0.5) {
+      reason = 'Medium confidence: Some indicators suggest resource locator format';
+    } else if (score >= 0.3) {
+      reason = 'Low confidence: Weak indicators for resource locator format';
+    } else {
+      reason = 'Very low confidence: Minimal evidence for resource locator format';
+    }
+
+    return {
+      value: score,
+      reason,
+      factors
+    };
+  }
+
+  /**
+   * Known field mappings with exact matches
+   */
+  private static readonly EXACT_FIELD_MAPPINGS: Record<string, string[]> = {
+    'github': ['owner', 'repository', 'user', 'organization'],
+    'googlesheets': ['sheetId', 'documentId', 'spreadsheetId'],
+    'googledrive': ['fileId', 'folderId', 'driveId'],
+    'slack': ['channel', 'user', 'channelId', 'userId'],
+    'notion': ['databaseId', 'pageId', 'blockId'],
+    'airtable': ['baseId', 'tableId', 'viewId']
+  };
+
+  private static checkExactFieldMatch(fieldName: string, nodeType: string): boolean {
+    const nodeBase = nodeType.split('.').pop()?.toLowerCase() || '';
+
+    for (const [pattern, fields] of Object.entries(this.EXACT_FIELD_MAPPINGS)) {
+      if (nodeBase === pattern || nodeBase.startsWith(`${pattern}-`)) {
+        return fields.includes(fieldName);
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Common patterns in field names that suggest resource locators
+   */
+  private static readonly FIELD_PATTERNS = [
+    /^.*Id$/i,           // ends with Id
+    /^.*Ids$/i,          // ends with Ids
+    /^.*Key$/i,          // ends with Key
+    /^.*Name$/i,         // ends with Name
+    /^.*Path$/i,         // ends with Path
+    /^.*Url$/i,          // ends with Url
+    /^.*Uri$/i,          // ends with Uri
+    /^(table|database|collection|bucket|folder|file|document|sheet|board|project|issue|user|channel|team|organization|repository|owner)$/i
+  ];
+
+  private static checkFieldPattern(fieldName: string): boolean {
+    return this.FIELD_PATTERNS.some(pattern => pattern.test(fieldName));
+  }
+
+  /**
+   * Check if the value looks like it contains identifiers
+   */
+  private static checkValuePattern(value: string): boolean {
+    // Remove = prefix if present for analysis
+    const content = value.startsWith('=') ? value.substring(1) : value;
+
+    // Skip if not an expression
+    if (!content.includes('{{') || !content.includes('}}')) {
+      return false;
+    }
+
+    // Check for patterns that suggest IDs or resource references
+    const patterns = [
+      /\{\{.*\.(id|Id|ID|key|Key|name|Name|path|Path|url|Url|uri|Uri).*\}\}/i,
+      /\{\{.*_(id|Id|ID|key|Key|name|Name|path|Path|url|Url|uri|Uri).*\}\}/i,
+      /\{\{.*(id|Id|ID|key|Key|name|Name|path|Path|url|Url|uri|Uri).*\}\}/i
+    ];
+
+    return patterns.some(pattern => pattern.test(content));
+  }
+
+  /**
+   * Node categories that commonly use resource locators
+   */
+  private static readonly RESOURCE_HEAVY_NODES = [
+    'github', 'gitlab', 'bitbucket',           // Version control
+    'googlesheets', 'googledrive', 'dropbox',  // Cloud storage
+    'slack', 'discord', 'telegram',            // Communication
+    'notion', 'airtable', 'baserow',          // Databases
+    'jira', 'asana', 'trello', 'monday',      // Project management
+    'salesforce', 'hubspot', 'pipedrive',     // CRM
+    'stripe', 'paypal', 'square',             // Payment
+    'aws', 'gcp', 'azure',                    // Cloud providers
+    'mysql', 'postgres', 'mongodb', 'redis'   // Databases
+  ];
+
+  private static checkNodeCategory(nodeType: string): boolean {
+    const nodeBase = nodeType.split('.').pop()?.toLowerCase() || '';
+
+    return this.RESOURCE_HEAVY_NODES.some(category =>
+      nodeBase.includes(category)
+    );
+  }
+
+  /**
+   * Get confidence level as a string
+   */
+  static getConfidenceLevel(score: number): 'high' | 'medium' | 'low' | 'very-low' {
+    if (score >= 0.8) return 'high';
+    if (score >= 0.5) return 'medium';
+    if (score >= 0.3) return 'low';
+    return 'very-low';
+  }
+
+  /**
+   * Should apply recommendation based on confidence and threshold
+   */
+  static shouldApplyRecommendation(
+    score: number,
+    threshold: 'strict' | 'normal' | 'relaxed' = 'normal'
+  ): boolean {
+    const thresholds = {
+      strict: 0.8,   // Only apply high confidence recommendations
+      normal: 0.5,   // Apply medium and high confidence
+      relaxed: 0.3   // Apply low, medium, and high confidence
+    };
+
+    return score >= thresholds[threshold];
+  }
+}

src/services/config-validator.ts

@@ -19,7 +19,9 @@ export interface ValidationError {
   type: 'missing_required' | 'invalid_type' | 'invalid_value' | 'incompatible' | 'invalid_configuration' | 'syntax_error';
   property: string;
   message: string;
-  fix?: string;}
+  fix?: string;
+  suggestion?: string;
+}
 
 export interface ValidationWarning {
   type: 'missing_common' | 'deprecated' | 'inefficient' | 'security' | 'best_practice' | 'invalid_value';
@@ -106,16 +108,16 @@ export class ConfigValidator {
    * Check for missing required properties
    */
   private static checkRequiredProperties(
-    properties: any[], 
-    config: Record<string, any>, 
+    properties: any[],
+    config: Record<string, any>,
     errors: ValidationError[]
   ): void {
     for (const prop of properties) {
       if (!prop || !prop.name) continue; // Skip invalid properties
-      
+
       if (prop.required) {
         const value = config[prop.name];
-        
+
         // Check if property is missing or has null/undefined value
         if (!(prop.name in config)) {
           errors.push({
@@ -131,6 +133,14 @@ export class ConfigValidator {
             message: `Required property '${prop.displayName || prop.name}' cannot be null or undefined`,
             fix: `Provide a valid value for ${prop.name}`
           });
+        } else if (typeof value === 'string' && value.trim() === '') {
+          // Check for empty strings which are invalid for required string properties
+          errors.push({
+            type: 'missing_required',
+            property: prop.name,
+            message: `Required property '${prop.displayName || prop.name}' cannot be empty`,
+            fix: `Provide a valid value for ${prop.name}`
+          });
         }
       }
     }

src/services/enhanced-config-validator.ts

@@ -8,6 +8,11 @@
 import { ConfigValidator, ValidationResult, ValidationError, ValidationWarning } from './config-validator';
 import { NodeSpecificValidators, NodeValidationContext } from './node-specific-validators';
 import { FixedCollectionValidator } from '../utils/fixed-collection-validator';
+import { OperationSimilarityService } from './operation-similarity-service';
+import { ResourceSimilarityService } from './resource-similarity-service';
+import { NodeRepository } from '../database/node-repository';
+import { DatabaseAdapter } from '../database/database-adapter';
+import { NodeTypeNormalizer } from '../utils/node-type-normalizer';
 
 export type ValidationMode = 'full' | 'operation' | 'minimal';
 export type ValidationProfile = 'strict' | 'runtime' | 'ai-friendly' | 'minimal';
@@ -35,6 +40,18 @@ export interface OperationContext {
 }
 
 export class EnhancedConfigValidator extends ConfigValidator {
+  private static operationSimilarityService: OperationSimilarityService | null = null;
+  private static resourceSimilarityService: ResourceSimilarityService | null = null;
+  private static nodeRepository: NodeRepository | null = null;
+
+  /**
+   * Initialize similarity services (called once at startup)
+   */
+  static initializeSimilarityServices(repository: NodeRepository): void {
+    this.nodeRepository = repository;
+    this.operationSimilarityService = new OperationSimilarityService(repository);
+    this.resourceSimilarityService = new ResourceSimilarityService(repository);
+  }
   /**
    * Validate with operation awareness
    */
@@ -60,17 +77,17 @@ export class EnhancedConfigValidator extends ConfigValidator {
     
     // Extract operation context from config
     const operationContext = this.extractOperationContext(config);
-    
-    // Filter properties based on mode and operation
-    const filteredProperties = this.filterPropertiesByMode(
+
+    // Filter properties based on mode and operation, and get config with defaults
+    const { properties: filteredProperties, configWithDefaults } = this.filterPropertiesByMode(
       properties,
       config,
       mode,
       operationContext
     );
-    
-    // Perform base validation on filtered properties
-    const baseResult = super.validate(nodeType, config, filteredProperties);
+
+    // Perform base validation on filtered properties with defaults applied
+    const baseResult = super.validate(nodeType, configWithDefaults, filteredProperties);
     
     // Enhance the result
     const enhancedResult: EnhancedValidationResult = {
@@ -120,31 +137,56 @@ export class EnhancedConfigValidator extends ConfigValidator {
   
   /**
    * Filter properties based on validation mode and operation
+   * Returns both filtered properties and config with defaults
    */
   private static filterPropertiesByMode(
     properties: any[],
     config: Record<string, any>,
     mode: ValidationMode,
     operation: OperationContext
-  ): any[] {
+  ): { properties: any[], configWithDefaults: Record<string, any> } {
+    // Apply defaults for visibility checking
+    const configWithDefaults = this.applyNodeDefaults(properties, config);
+
+    let filteredProperties: any[];
     switch (mode) {
       case 'minimal':
         // Only required properties that are visible
-        return properties.filter(prop => 
-          prop.required && this.isPropertyVisible(prop, config)
+        filteredProperties = properties.filter(prop =>
+          prop.required && this.isPropertyVisible(prop, configWithDefaults)
         );
-        
+        break;
+
       case 'operation':
         // Only properties relevant to the current operation
-        return properties.filter(prop => 
-          this.isPropertyRelevantToOperation(prop, config, operation)
+        filteredProperties = properties.filter(prop =>
+          this.isPropertyRelevantToOperation(prop, configWithDefaults, operation)
         );
-        
+        break;
+
       case 'full':
       default:
         // All properties (current behavior)
-        return properties;
+        filteredProperties = properties;
+        break;
     }
+
+    return { properties: filteredProperties, configWithDefaults };
+  }
+
+  /**
+   * Apply node defaults to configuration for accurate visibility checking
+   */
+  private static applyNodeDefaults(properties: any[], config: Record<string, any>): Record<string, any> {
+    const result = { ...config };
+
+    for (const prop of properties) {
+      if (prop.name && prop.default !== undefined && result[prop.name] === undefined) {
+        result[prop.name] = prop.default;
+      }
+    }
+
+    return result;
   }
   
   /**
@@ -213,7 +255,10 @@ export class EnhancedConfigValidator extends ConfigValidator {
       });
       return;
     }
-    
+
+    // Validate resource and operation using similarity services
+    this.validateResourceAndOperation(nodeType, config, result);
+
     // First, validate fixedCollection properties for known problematic nodes
     this.validateFixedCollectionStructures(nodeType, config, result);
     
@@ -642,4 +687,190 @@ export class EnhancedConfigValidator extends ConfigValidator {
     
     // Add any Filter-node-specific validation here in the future
   }
+
+  /**
+   * Validate resource and operation values using similarity services
+   */
+  private static validateResourceAndOperation(
+    nodeType: string,
+    config: Record<string, any>,
+    result: EnhancedValidationResult
+  ): void {
+    // Skip if similarity services not initialized
+    if (!this.operationSimilarityService || !this.resourceSimilarityService || !this.nodeRepository) {
+      return;
+    }
+
+    // Normalize the node type for repository lookups
+    const normalizedNodeType = NodeTypeNormalizer.normalizeToFullForm(nodeType);
+
+    // Apply defaults for validation
+    const configWithDefaults = { ...config };
+
+    // If operation is undefined but resource is set, get the default operation for that resource
+    if (configWithDefaults.operation === undefined && configWithDefaults.resource !== undefined) {
+      const defaultOperation = this.nodeRepository.getDefaultOperationForResource(normalizedNodeType, configWithDefaults.resource);
+      if (defaultOperation !== undefined) {
+        configWithDefaults.operation = defaultOperation;
+      }
+    }
+
+    // Validate resource field if present
+    if (config.resource !== undefined) {
+      // Remove any existing resource error from base validator to replace with our enhanced version
+      result.errors = result.errors.filter(e => e.property !== 'resource');
+      const validResources = this.nodeRepository.getNodeResources(normalizedNodeType);
+      const resourceIsValid = validResources.some(r => {
+        const resourceValue = typeof r === 'string' ? r : r.value;
+        return resourceValue === config.resource;
+      });
+
+      if (!resourceIsValid && config.resource !== '') {
+        // Find similar resources
+        let suggestions: any[] = [];
+        try {
+          suggestions = this.resourceSimilarityService.findSimilarResources(
+            normalizedNodeType,
+            config.resource,
+            3
+          );
+        } catch (error) {
+          // If similarity service fails, continue with validation without suggestions
+          console.error('Resource similarity service error:', error);
+        }
+
+        // Build error message with suggestions
+        let errorMessage = `Invalid resource "${config.resource}" for node ${nodeType}.`;
+        let fix = '';
+
+        if (suggestions.length > 0) {
+          const topSuggestion = suggestions[0];
+          // Always use "Did you mean" for the top suggestion
+          errorMessage += ` Did you mean "${topSuggestion.value}"?`;
+          if (topSuggestion.confidence >= 0.8) {
+            fix = `Change resource to "${topSuggestion.value}". ${topSuggestion.reason}`;
+          } else {
+            // For lower confidence, still show valid resources in the fix
+            fix = `Valid resources: ${validResources.slice(0, 5).map(r => {
+              const val = typeof r === 'string' ? r : r.value;
+              return `"${val}"`;
+            }).join(', ')}${validResources.length > 5 ? '...' : ''}`;
+          }
+        } else {
+          // No similar resources found, list valid ones
+          fix = `Valid resources: ${validResources.slice(0, 5).map(r => {
+            const val = typeof r === 'string' ? r : r.value;
+            return `"${val}"`;
+          }).join(', ')}${validResources.length > 5 ? '...' : ''}`;
+        }
+
+        const error: any = {
+          type: 'invalid_value',
+          property: 'resource',
+          message: errorMessage,
+          fix
+        };
+
+        // Add suggestion property if we have high confidence suggestions
+        if (suggestions.length > 0 && suggestions[0].confidence >= 0.5) {
+          error.suggestion = `Did you mean "${suggestions[0].value}"? ${suggestions[0].reason}`;
+        }
+
+        result.errors.push(error);
+
+        // Add suggestions to result.suggestions array
+        if (suggestions.length > 0) {
+          for (const suggestion of suggestions) {
+            result.suggestions.push(
+              `Resource "${config.resource}" not found. Did you mean "${suggestion.value}"? ${suggestion.reason}`
+            );
+          }
+        }
+      }
+    }
+
+    // Validate operation field - now we check configWithDefaults which has defaults applied
+    // Only validate if operation was explicitly set (not undefined) OR if we're using a default
+    if (config.operation !== undefined || configWithDefaults.operation !== undefined) {
+      // Remove any existing operation error from base validator to replace with our enhanced version
+      result.errors = result.errors.filter(e => e.property !== 'operation');
+
+      // Use the operation from configWithDefaults for validation (which includes the default if applied)
+      const operationToValidate = configWithDefaults.operation || config.operation;
+      const validOperations = this.nodeRepository.getNodeOperations(normalizedNodeType, config.resource);
+      const operationIsValid = validOperations.some(op => {
+        const opValue = op.operation || op.value || op;
+        return opValue === operationToValidate;
+      });
+
+      // Only report error if the explicit operation is invalid (not for defaults)
+      if (!operationIsValid && config.operation !== undefined && config.operation !== '') {
+        // Find similar operations
+        let suggestions: any[] = [];
+        try {
+          suggestions = this.operationSimilarityService.findSimilarOperations(
+            normalizedNodeType,
+            config.operation,
+            config.resource,
+            3
+          );
+        } catch (error) {
+          // If similarity service fails, continue with validation without suggestions
+          console.error('Operation similarity service error:', error);
+        }
+
+        // Build error message with suggestions
+        let errorMessage = `Invalid operation "${config.operation}" for node ${nodeType}`;
+        if (config.resource) {
+          errorMessage += ` with resource "${config.resource}"`;
+        }
+        errorMessage += '.';
+
+        let fix = '';
+
+        if (suggestions.length > 0) {
+          const topSuggestion = suggestions[0];
+          if (topSuggestion.confidence >= 0.8) {
+            errorMessage += ` Did you mean "${topSuggestion.value}"?`;
+            fix = `Change operation to "${topSuggestion.value}". ${topSuggestion.reason}`;
+          } else {
+            errorMessage += ` Similar operations: ${suggestions.map(s => `"${s.value}"`).join(', ')}`;
+            fix = `Valid operations${config.resource ? ` for resource "${config.resource}"` : ''}: ${validOperations.slice(0, 5).map(op => {
+              const val = op.operation || op.value || op;
+              return `"${val}"`;
+            }).join(', ')}${validOperations.length > 5 ? '...' : ''}`;
+          }
+        } else {
+          // No similar operations found, list valid ones
+          fix = `Valid operations${config.resource ? ` for resource "${config.resource}"` : ''}: ${validOperations.slice(0, 5).map(op => {
+            const val = op.operation || op.value || op;
+            return `"${val}"`;
+          }).join(', ')}${validOperations.length > 5 ? '...' : ''}`;
+        }
+
+        const error: any = {
+          type: 'invalid_value',
+          property: 'operation',
+          message: errorMessage,
+          fix
+        };
+
+        // Add suggestion property if we have high confidence suggestions
+        if (suggestions.length > 0 && suggestions[0].confidence >= 0.5) {
+          error.suggestion = `Did you mean "${suggestions[0].value}"? ${suggestions[0].reason}`;
+        }
+
+        result.errors.push(error);
+
+        // Add suggestions to result.suggestions array
+        if (suggestions.length > 0) {
+          for (const suggestion of suggestions) {
+            result.suggestions.push(
+              `Operation "${config.operation}" not found. Did you mean "${suggestion.value}"? ${suggestion.reason}`
+            );
+          }
+        }
+      }
+    }
+  }
 }

src/services/execution-processor.ts

@@ -0,0 +1,519 @@
+/**
+ * Execution Processor Service
+ *
+ * Intelligent processing and filtering of n8n execution data to enable
+ * AI agents to inspect executions without exceeding token limits.
+ *
+ * Features:
+ * - Preview mode: Show structure and counts without values
+ * - Summary mode: Smart default with 2 sample items per node
+ * - Filtered mode: Granular control (node filtering, item limits)
+ * - Smart recommendations: Guide optimal retrieval strategy
+ */
+
+import {
+  Execution,
+  ExecutionMode,
+  ExecutionPreview,
+  NodePreview,
+  ExecutionRecommendation,
+  ExecutionFilterOptions,
+  FilteredExecutionResponse,
+  FilteredNodeData,
+  ExecutionStatus,
+} from '../types/n8n-api';
+import { logger } from '../utils/logger';
+
+/**
+ * Size estimation and threshold constants
+ */
+const THRESHOLDS = {
+  CHAR_SIZE_BYTES: 2, // UTF-16 characters
+  OVERHEAD_PER_OBJECT: 50, // Approximate JSON overhead
+  MAX_RECOMMENDED_SIZE_KB: 100, // Threshold for "can fetch full"
+  SMALL_DATASET_ITEMS: 20, // <= this is considered small
+  MODERATE_DATASET_ITEMS: 50, // <= this is considered moderate
+  MODERATE_DATASET_SIZE_KB: 200, // <= this is considered moderate
+  MAX_DEPTH: 3, // Maximum depth for structure extraction
+  MAX_ITEMS_LIMIT: 1000, // Maximum allowed itemsLimit value
+} as const;
+
+/**
+ * Helper function to extract error message from various error formats
+ */
+function extractErrorMessage(error: unknown): string {
+  if (typeof error === 'string') {
+    return error;
+  }
+  if (error && typeof error === 'object') {
+    if ('message' in error && typeof error.message === 'string') {
+      return error.message;
+    }
+    if ('error' in error && typeof error.error === 'string') {
+      return error.error;
+    }
+  }
+  return 'Unknown error';
+}
+
+/**
+ * Extract data structure (JSON schema-like) from items
+ */
+function extractStructure(data: unknown, maxDepth = THRESHOLDS.MAX_DEPTH, currentDepth = 0): Record<string, unknown> | string | unknown[] {
+  if (currentDepth >= maxDepth) {
+    return typeof data;
+  }
+
+  if (data === null || data === undefined) {
+    return 'null';
+  }
+
+  if (Array.isArray(data)) {
+    if (data.length === 0) {
+      return [];
+    }
+    // Extract structure from first item
+    return [extractStructure(data[0], maxDepth, currentDepth + 1)];
+  }
+
+  if (typeof data === 'object') {
+    const structure: Record<string, unknown> = {};
+    for (const key in data) {
+      if (Object.prototype.hasOwnProperty.call(data, key)) {
+        structure[key] = extractStructure((data as Record<string, unknown>)[key], maxDepth, currentDepth + 1);
+      }
+    }
+    return structure;
+  }
+
+  return typeof data;
+}
+
+/**
+ * Estimate size of data in KB
+ */
+function estimateDataSize(data: unknown): number {
+  try {
+    const jsonString = JSON.stringify(data);
+    const sizeBytes = jsonString.length * THRESHOLDS.CHAR_SIZE_BYTES;
+    return Math.ceil(sizeBytes / 1024);
+  } catch (error) {
+    logger.warn('Failed to estimate data size', { error });
+    return 0;
+  }
+}
+
+/**
+ * Count items in execution data
+ */
+function countItems(nodeData: unknown): { input: number; output: number } {
+  const counts = { input: 0, output: 0 };
+
+  if (!nodeData || !Array.isArray(nodeData)) {
+    return counts;
+  }
+
+  for (const run of nodeData) {
+    if (run?.data?.main) {
+      const mainData = run.data.main;
+      if (Array.isArray(mainData)) {
+        for (const output of mainData) {
+          if (Array.isArray(output)) {
+            counts.output += output.length;
+          }
+        }
+      }
+    }
+  }
+
+  return counts;
+}
+
+/**
+ * Generate preview for an execution
+ */
+export function generatePreview(execution: Execution): {
+  preview: ExecutionPreview;
+  recommendation: ExecutionRecommendation;
+} {
+  const preview: ExecutionPreview = {
+    totalNodes: 0,
+    executedNodes: 0,
+    estimatedSizeKB: 0,
+    nodes: {},
+  };
+
+  if (!execution.data?.resultData?.runData) {
+    return {
+      preview,
+      recommendation: {
+        canFetchFull: true,
+        suggestedMode: 'summary',
+        reason: 'No execution data available',
+      },
+    };
+  }
+
+  const runData = execution.data.resultData.runData;
+  const nodeNames = Object.keys(runData);
+  preview.totalNodes = nodeNames.length;
+
+  let totalItemsOutput = 0;
+  let largestNodeItems = 0;
+
+  for (const nodeName of nodeNames) {
+    const nodeData = runData[nodeName];
+    const itemCounts = countItems(nodeData);
+
+    // Extract structure from first run's first output item
+    let dataStructure: Record<string, unknown> = {};
+    if (Array.isArray(nodeData) && nodeData.length > 0) {
+      const firstRun = nodeData[0];
+      const firstItem = firstRun?.data?.main?.[0]?.[0];
+      if (firstItem) {
+        dataStructure = extractStructure(firstItem) as Record<string, unknown>;
+      }
+    }
+
+    const nodeSize = estimateDataSize(nodeData);
+
+    const nodePreview: NodePreview = {
+      status: 'success',
+      itemCounts,
+      dataStructure,
+      estimatedSizeKB: nodeSize,
+    };
+
+    // Check for errors
+    if (Array.isArray(nodeData)) {
+      for (const run of nodeData) {
+        if (run.error) {
+          nodePreview.status = 'error';
+          nodePreview.error = extractErrorMessage(run.error);
+          break;
+        }
+      }
+    }
+
+    preview.nodes[nodeName] = nodePreview;
+    preview.estimatedSizeKB += nodeSize;
+    preview.executedNodes++;
+    totalItemsOutput += itemCounts.output;
+    largestNodeItems = Math.max(largestNodeItems, itemCounts.output);
+  }
+
+  // Generate recommendation
+  const recommendation = generateRecommendation(
+    preview.estimatedSizeKB,
+    totalItemsOutput,
+    largestNodeItems
+  );
+
+  return { preview, recommendation };
+}
+
+/**
+ * Generate smart recommendation based on data characteristics
+ */
+function generateRecommendation(
+  totalSizeKB: number,
+  totalItems: number,
+  largestNodeItems: number
+): ExecutionRecommendation {
+  // Can safely fetch full data
+  if (totalSizeKB <= THRESHOLDS.MAX_RECOMMENDED_SIZE_KB && totalItems <= THRESHOLDS.SMALL_DATASET_ITEMS) {
+    return {
+      canFetchFull: true,
+      suggestedMode: 'full',
+      reason: `Small dataset (${totalSizeKB}KB, ${totalItems} items). Safe to fetch full data.`,
+    };
+  }
+
+  // Moderate size - use summary
+  if (totalSizeKB <= THRESHOLDS.MODERATE_DATASET_SIZE_KB && totalItems <= THRESHOLDS.MODERATE_DATASET_ITEMS) {
+    return {
+      canFetchFull: false,
+      suggestedMode: 'summary',
+      suggestedItemsLimit: 2,
+      reason: `Moderate dataset (${totalSizeKB}KB, ${totalItems} items). Summary mode recommended.`,
+    };
+  }
+
+  // Large dataset - filter with limits
+  const suggestedLimit = Math.max(1, Math.min(5, Math.floor(100 / largestNodeItems)));
+
+  return {
+    canFetchFull: false,
+    suggestedMode: 'filtered',
+    suggestedItemsLimit: suggestedLimit,
+    reason: `Large dataset (${totalSizeKB}KB, ${totalItems} items). Use filtered mode with itemsLimit: ${suggestedLimit}.`,
+  };
+}
+
+/**
+ * Truncate items array with metadata
+ */
+function truncateItems(
+  items: unknown[][],
+  limit: number
+): {
+  truncated: unknown[][];
+  metadata: { totalItems: number; itemsShown: number; truncated: boolean };
+} {
+  if (!Array.isArray(items) || items.length === 0) {
+    return {
+      truncated: items || [],
+      metadata: {
+        totalItems: 0,
+        itemsShown: 0,
+        truncated: false,
+      },
+    };
+  }
+
+  let totalItems = 0;
+  for (const output of items) {
+    if (Array.isArray(output)) {
+      totalItems += output.length;
+    }
+  }
+
+  // Special case: limit = 0 means structure only
+  if (limit === 0) {
+    const structureOnly = items.map(output => {
+      if (!Array.isArray(output) || output.length === 0) {
+        return [];
+      }
+      return [extractStructure(output[0])];
+    });
+
+    return {
+      truncated: structureOnly,
+      metadata: {
+        totalItems,
+        itemsShown: 0,
+        truncated: true,
+      },
+    };
+  }
+
+  // Limit = -1 means unlimited
+  if (limit < 0) {
+    return {
+      truncated: items,
+      metadata: {
+        totalItems,
+        itemsShown: totalItems,
+        truncated: false,
+      },
+    };
+  }
+
+  // Apply limit
+  const result: unknown[][] = [];
+  let itemsShown = 0;
+
+  for (const output of items) {
+    if (!Array.isArray(output)) {
+      result.push(output);
+      continue;
+    }
+
+    if (itemsShown >= limit) {
+      break;
+    }
+
+    const remaining = limit - itemsShown;
+    const toTake = Math.min(remaining, output.length);
+    result.push(output.slice(0, toTake));
+    itemsShown += toTake;
+  }
+
+  return {
+    truncated: result,
+    metadata: {
+      totalItems,
+      itemsShown,
+      truncated: itemsShown < totalItems,
+    },
+  };
+}
+
+/**
+ * Filter execution data based on options
+ */
+export function filterExecutionData(
+  execution: Execution,
+  options: ExecutionFilterOptions
+): FilteredExecutionResponse {
+  const mode = options.mode || 'summary';
+
+  // Validate and bound itemsLimit
+  let itemsLimit = options.itemsLimit !== undefined ? options.itemsLimit : 2;
+  if (itemsLimit !== -1) { // -1 means unlimited
+    if (itemsLimit < 0) {
+      logger.warn('Invalid itemsLimit, defaulting to 2', { provided: itemsLimit });
+      itemsLimit = 2;
+    }
+    if (itemsLimit > THRESHOLDS.MAX_ITEMS_LIMIT) {
+      logger.warn(`itemsLimit capped at ${THRESHOLDS.MAX_ITEMS_LIMIT}`, { provided: itemsLimit });
+      itemsLimit = THRESHOLDS.MAX_ITEMS_LIMIT;
+    }
+  }
+
+  const includeInputData = options.includeInputData || false;
+  const nodeNamesFilter = options.nodeNames;
+
+  // Calculate duration
+  const duration = execution.stoppedAt && execution.startedAt
+    ? new Date(execution.stoppedAt).getTime() - new Date(execution.startedAt).getTime()
+    : undefined;
+
+  const response: FilteredExecutionResponse = {
+    id: execution.id,
+    workflowId: execution.workflowId,
+    status: execution.status,
+    mode,
+    startedAt: execution.startedAt,
+    stoppedAt: execution.stoppedAt,
+    duration,
+    finished: execution.finished,
+  };
+
+  // Handle preview mode
+  if (mode === 'preview') {
+    const { preview, recommendation } = generatePreview(execution);
+    response.preview = preview;
+    response.recommendation = recommendation;
+    return response;
+  }
+
+  // Handle no data case
+  if (!execution.data?.resultData?.runData) {
+    response.summary = {
+      totalNodes: 0,
+      executedNodes: 0,
+      totalItems: 0,
+      hasMoreData: false,
+    };
+    response.nodes = {};
+
+    if (execution.data?.resultData?.error) {
+      response.error = execution.data.resultData.error;
+    }
+
+    return response;
+  }
+
+  const runData = execution.data.resultData.runData;
+  let nodeNames = Object.keys(runData);
+
+  // Apply node name filter
+  if (nodeNamesFilter && nodeNamesFilter.length > 0) {
+    nodeNames = nodeNames.filter(name => nodeNamesFilter.includes(name));
+  }
+
+  // Process nodes
+  const processedNodes: Record<string, FilteredNodeData> = {};
+  let totalItems = 0;
+  let hasMoreData = false;
+
+  for (const nodeName of nodeNames) {
+    const nodeData = runData[nodeName];
+
+    if (!Array.isArray(nodeData) || nodeData.length === 0) {
+      processedNodes[nodeName] = {
+        itemsInput: 0,
+        itemsOutput: 0,
+        status: 'success',
+      };
+      continue;
+    }
+
+    // Get first run data
+    const firstRun = nodeData[0];
+    const itemCounts = countItems(nodeData);
+    totalItems += itemCounts.output;
+
+    const nodeResult: FilteredNodeData = {
+      executionTime: firstRun.executionTime,
+      itemsInput: itemCounts.input,
+      itemsOutput: itemCounts.output,
+      status: 'success',
+    };
+
+    // Check for errors
+    if (firstRun.error) {
+      nodeResult.status = 'error';
+      nodeResult.error = extractErrorMessage(firstRun.error);
+    }
+
+    // Handle full mode - include all data
+    if (mode === 'full') {
+      nodeResult.data = {
+        output: firstRun.data?.main || [],
+        metadata: {
+          totalItems: itemCounts.output,
+          itemsShown: itemCounts.output,
+          truncated: false,
+        },
+      };
+
+      if (includeInputData && firstRun.inputData) {
+        nodeResult.data.input = firstRun.inputData;
+      }
+    } else {
+      // Summary or filtered mode - apply limits
+      const outputData = firstRun.data?.main || [];
+      const { truncated, metadata } = truncateItems(outputData, itemsLimit);
+
+      if (metadata.truncated) {
+        hasMoreData = true;
+      }
+
+      nodeResult.data = {
+        output: truncated,
+        metadata,
+      };
+
+      if (includeInputData && firstRun.inputData) {
+        nodeResult.data.input = firstRun.inputData;
+      }
+    }
+
+    processedNodes[nodeName] = nodeResult;
+  }
+
+  // Add summary
+  response.summary = {
+    totalNodes: Object.keys(runData).length,
+    executedNodes: nodeNames.length,
+    totalItems,
+    hasMoreData,
+  };
+
+  response.nodes = processedNodes;
+
+  // Include error if present
+  if (execution.data?.resultData?.error) {
+    response.error = execution.data.resultData.error;
+  }
+
+  return response;
+}
+
+/**
+ * Process execution based on mode and options
+ * Main entry point for the service
+ */
+export function processExecution(
+  execution: Execution,
+  options: ExecutionFilterOptions = {}
+): FilteredExecutionResponse | Execution {
+  // Legacy behavior: if no mode specified and no filtering options, return original
+  if (!options.mode && !options.nodeNames && options.itemsLimit === undefined) {
+    return execution;
+  }
+
+  return filterExecutionData(execution, options);
+}

src/services/expression-format-validator.ts

@@ -0,0 +1,340 @@
+/**
+ * Expression Format Validator for n8n expressions
+ *
+ * Combines universal expression validation with node-specific intelligence
+ * to provide comprehensive expression format validation. Uses the
+ * UniversalExpressionValidator for 100% reliable base validation and adds
+ * node-specific resource locator detection on top.
+ */
+
+import { UniversalExpressionValidator, UniversalValidationResult } from './universal-expression-validator';
+import { ConfidenceScorer } from './confidence-scorer';
+
+export interface ExpressionFormatIssue {
+  fieldPath: string;
+  currentValue: any;
+  correctedValue: any;
+  issueType: 'missing-prefix' | 'needs-resource-locator' | 'invalid-rl-structure' | 'mixed-format';
+  explanation: string;
+  severity: 'error' | 'warning';
+  confidence?: number; // 0.0 to 1.0, only for node-specific recommendations
+}
+
+export interface ResourceLocatorField {
+  __rl: true;
+  value: string;
+  mode: string;
+}
+
+export interface ValidationContext {
+  nodeType: string;
+  nodeName: string;
+  nodeId?: string;
+}
+
+export class ExpressionFormatValidator {
+  private static readonly VALID_RL_MODES = ['id', 'url', 'expression', 'name', 'list'] as const;
+  private static readonly MAX_RECURSION_DEPTH = 100;
+  private static readonly EXPRESSION_PREFIX = '='; // Keep for resource locator generation
+
+  /**
+   * Known fields that commonly use resource locator format
+   * Map of node type patterns to field names
+   */
+  private static readonly RESOURCE_LOCATOR_FIELDS: Record<string, string[]> = {
+    'github': ['owner', 'repository', 'user', 'organization'],
+    'googleSheets': ['sheetId', 'documentId', 'spreadsheetId', 'rangeDefinition'],
+    'googleDrive': ['fileId', 'folderId', 'driveId'],
+    'slack': ['channel', 'user', 'channelId', 'userId', 'teamId'],
+    'notion': ['databaseId', 'pageId', 'blockId'],
+    'airtable': ['baseId', 'tableId', 'viewId'],
+    'monday': ['boardId', 'itemId', 'groupId'],
+    'hubspot': ['contactId', 'companyId', 'dealId'],
+    'salesforce': ['recordId', 'objectName'],
+    'jira': ['projectKey', 'issueKey', 'boardId'],
+    'gitlab': ['projectId', 'mergeRequestId', 'issueId'],
+    'mysql': ['table', 'database', 'schema'],
+    'postgres': ['table', 'database', 'schema'],
+    'mongodb': ['collection', 'database'],
+    's3': ['bucketName', 'key', 'fileName'],
+    'ftp': ['path', 'fileName'],
+    'ssh': ['path', 'fileName'],
+    'redis': ['key'],
+  };
+
+
+  /**
+   * Determine if a field should use resource locator format based on node type and field name
+   */
+  private static shouldUseResourceLocator(fieldName: string, nodeType: string): boolean {
+    // Extract the base node type (e.g., 'github' from 'n8n-nodes-base.github')
+    const nodeBase = nodeType.split('.').pop()?.toLowerCase() || '';
+
+    // Check if this node type has resource locator fields
+    for (const [pattern, fields] of Object.entries(this.RESOURCE_LOCATOR_FIELDS)) {
+      // Use exact match or prefix matching for precision
+      // This prevents false positives like 'postgresqlAdvanced' matching 'postgres'
+      if ((nodeBase === pattern || nodeBase.startsWith(`${pattern}-`)) && fields.includes(fieldName)) {
+        return true;
+      }
+    }
+
+    // Don't apply resource locator to generic fields
+    return false;
+  }
+
+  /**
+   * Check if a value is a valid resource locator object
+   */
+  private static isResourceLocator(value: any): value is ResourceLocatorField {
+    if (typeof value !== 'object' || value === null || value.__rl !== true) {
+      return false;
+    }
+
+    if (!('value' in value) || !('mode' in value)) {
+      return false;
+    }
+
+    // Validate mode is one of the allowed values
+    if (typeof value.mode !== 'string' || !this.VALID_RL_MODES.includes(value.mode as any)) {
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Generate the corrected value for an expression
+   */
+  private static generateCorrection(
+    value: string,
+    needsResourceLocator: boolean
+  ): any {
+    const correctedValue = value.startsWith(this.EXPRESSION_PREFIX)
+      ? value
+      : `${this.EXPRESSION_PREFIX}${value}`;
+
+    if (needsResourceLocator) {
+      return {
+        __rl: true,
+        value: correctedValue,
+        mode: 'expression'
+      };
+    }
+
+    return correctedValue;
+  }
+
+  /**
+   * Validate and fix expression format for a single value
+   */
+  static validateAndFix(
+    value: any,
+    fieldPath: string,
+    context: ValidationContext
+  ): ExpressionFormatIssue | null {
+    // Skip non-string values unless they're resource locators
+    if (typeof value !== 'string' && !this.isResourceLocator(value)) {
+      return null;
+    }
+
+    // Handle resource locator objects
+    if (this.isResourceLocator(value)) {
+      // Use universal validator for the value inside RL
+      const universalResults = UniversalExpressionValidator.validate(value.value);
+      const invalidResult = universalResults.find(r => !r.isValid && r.needsPrefix);
+
+      if (invalidResult) {
+        return {
+          fieldPath,
+          currentValue: value,
+          correctedValue: {
+            ...value,
+            value: UniversalExpressionValidator.getCorrectedValue(value.value)
+          },
+          issueType: 'missing-prefix',
+          explanation: `Resource locator value: ${invalidResult.explanation}`,
+          severity: 'error'
+        };
+      }
+      return null;
+    }
+
+    // First, use universal validator for 100% reliable validation
+    const universalResults = UniversalExpressionValidator.validate(value);
+    const invalidResults = universalResults.filter(r => !r.isValid);
+
+    // If universal validator found issues, report them
+    if (invalidResults.length > 0) {
+      // Prioritize prefix issues
+      const prefixIssue = invalidResults.find(r => r.needsPrefix);
+      if (prefixIssue) {
+        // Check if this field should use resource locator format with confidence scoring
+        const fieldName = fieldPath.split('.').pop() || '';
+        const confidenceScore = ConfidenceScorer.scoreResourceLocatorRecommendation(
+          fieldName,
+          context.nodeType,
+          value
+        );
+
+        // Only suggest resource locator for high confidence matches when there's a prefix issue
+        if (confidenceScore.value >= 0.8) {
+          return {
+            fieldPath,
+            currentValue: value,
+            correctedValue: this.generateCorrection(value, true),
+            issueType: 'needs-resource-locator',
+            explanation: `Field '${fieldName}' contains expression but needs resource locator format with '${this.EXPRESSION_PREFIX}' prefix for evaluation.`,
+            severity: 'error',
+            confidence: confidenceScore.value
+          };
+        } else {
+          return {
+            fieldPath,
+            currentValue: value,
+            correctedValue: UniversalExpressionValidator.getCorrectedValue(value),
+            issueType: 'missing-prefix',
+            explanation: prefixIssue.explanation,
+            severity: 'error'
+          };
+        }
+      }
+
+      // Report other validation issues
+      const firstIssue = invalidResults[0];
+      return {
+        fieldPath,
+        currentValue: value,
+        correctedValue: value,
+        issueType: 'mixed-format',
+        explanation: firstIssue.explanation,
+        severity: 'error'
+      };
+    }
+
+    // Universal validation passed, now check for node-specific improvements
+    // Only if the value has expressions
+    const hasExpression = universalResults.some(r => r.hasExpression);
+    if (hasExpression && typeof value === 'string') {
+      const fieldName = fieldPath.split('.').pop() || '';
+      const confidenceScore = ConfidenceScorer.scoreResourceLocatorRecommendation(
+        fieldName,
+        context.nodeType,
+        value
+      );
+
+      // Only suggest resource locator for medium-high confidence as a warning
+      if (confidenceScore.value >= 0.5) {
+        // Has prefix but should use resource locator format
+        return {
+          fieldPath,
+          currentValue: value,
+          correctedValue: this.generateCorrection(value, true),
+          issueType: 'needs-resource-locator',
+          explanation: `Field '${fieldName}' should use resource locator format for better compatibility. (Confidence: ${Math.round(confidenceScore.value * 100)}%)`,
+          severity: 'warning',
+          confidence: confidenceScore.value
+        };
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Validate all expressions in a node's parameters recursively
+   */
+  static validateNodeParameters(
+    parameters: any,
+    context: ValidationContext
+  ): ExpressionFormatIssue[] {
+    const issues: ExpressionFormatIssue[] = [];
+    const visited = new WeakSet();
+
+    this.validateRecursive(parameters, '', context, issues, visited);
+
+    return issues;
+  }
+
+  /**
+   * Recursively validate parameters for expression format issues
+   */
+  private static validateRecursive(
+    obj: any,
+    path: string,
+    context: ValidationContext,
+    issues: ExpressionFormatIssue[],
+    visited: WeakSet<object>,
+    depth = 0
+  ): void {
+    // Prevent excessive recursion
+    if (depth > this.MAX_RECURSION_DEPTH) {
+      issues.push({
+        fieldPath: path,
+        currentValue: obj,
+        correctedValue: obj,
+        issueType: 'mixed-format',
+        explanation: `Maximum recursion depth (${this.MAX_RECURSION_DEPTH}) exceeded. Object may have circular references or be too deeply nested.`,
+        severity: 'warning'
+      });
+      return;
+    }
+
+    // Handle circular references
+    if (obj && typeof obj === 'object') {
+      if (visited.has(obj)) return;
+      visited.add(obj);
+    }
+
+    // Check current value
+    const issue = this.validateAndFix(obj, path, context);
+    if (issue) {
+      issues.push(issue);
+    }
+
+    // Recurse into objects and arrays
+    if (Array.isArray(obj)) {
+      obj.forEach((item, index) => {
+        const newPath = path ? `${path}[${index}]` : `[${index}]`;
+        this.validateRecursive(item, newPath, context, issues, visited, depth + 1);
+      });
+    } else if (obj && typeof obj === 'object') {
+      // Skip resource locator internals if already validated
+      if (this.isResourceLocator(obj)) {
+        return;
+      }
+
+      Object.entries(obj).forEach(([key, value]) => {
+        // Skip special keys
+        if (key.startsWith('__')) return;
+
+        const newPath = path ? `${path}.${key}` : key;
+        this.validateRecursive(value, newPath, context, issues, visited, depth + 1);
+      });
+    }
+  }
+
+  /**
+   * Generate a detailed error message with examples
+   */
+  static formatErrorMessage(issue: ExpressionFormatIssue, context: ValidationContext): string {
+    let message = `Expression format ${issue.severity} in node '${context.nodeName}':\n`;
+    message += `Field '${issue.fieldPath}' ${issue.explanation}\n\n`;
+
+    message += `Current (incorrect):\n`;
+    if (typeof issue.currentValue === 'string') {
+      message += `"${issue.fieldPath}": "${issue.currentValue}"\n\n`;
+    } else {
+      message += `"${issue.fieldPath}": ${JSON.stringify(issue.currentValue, null, 2)}\n\n`;
+    }
+
+    message += `Fixed (correct):\n`;
+    if (typeof issue.correctedValue === 'string') {
+      message += `"${issue.fieldPath}": "${issue.correctedValue}"`;
+    } else {
+      message += `"${issue.fieldPath}": ${JSON.stringify(issue.correctedValue, null, 2)}`;
+    }
+
+    return message;
+  }
+}

src/services/expression-validator.ts

@@ -141,12 +141,21 @@ export class ExpressionValidator {
     const jsonPattern = new RegExp(this.VARIABLE_PATTERNS.json.source, this.VARIABLE_PATTERNS.json.flags);
     while ((match = jsonPattern.exec(expr)) !== null) {
       result.usedVariables.add('$json');
-      
+
       if (!context.hasInputData && !context.isInLoop) {
         result.warnings.push(
           'Using $json but node might not have input data'
         );
       }
+
+      // Check for suspicious property names that might be test/invalid data
+      const fullMatch = match[0];
+      if (fullMatch.includes('.invalid') || fullMatch.includes('.undefined') ||
+          fullMatch.includes('.null') || fullMatch.includes('.test')) {
+        result.warnings.push(
+          `Property access '${fullMatch}' looks suspicious - verify this property exists in your data`
+        );
+      }
     }
 
     // Check for $node references

src/services/n8n-api-client.ts

@@ -161,9 +161,10 @@ export class N8nApiClient {
     }
   }
 
-  async deleteWorkflow(id: string): Promise<void> {
+  async deleteWorkflow(id: string): Promise<Workflow> {
     try {
-      await this.client.delete(`/workflows/${id}`);
+      const response = await this.client.delete(`/workflows/${id}`);
+      return response.data;
     } catch (error) {
       throw handleN8nApiError(error);
     }
@@ -211,7 +212,16 @@ export class N8nApiClient {
   async triggerWebhook(request: WebhookRequest): Promise<any> {
     try {
       const { webhookUrl, httpMethod, data, headers, waitForResponse = true } = request;
-      
+
+      // SECURITY: Validate URL for SSRF protection (includes DNS resolution)
+      // See: https://github.com/czlonkowski/n8n-mcp/issues/265 (HIGH-03)
+      const { SSRFProtection } = await import('../utils/ssrf-protection');
+      const validation = await SSRFProtection.validateWebhookUrl(webhookUrl);
+
+      if (!validation.valid) {
+        throw new Error(`SSRF protection: ${validation.reason}`);
+      }
+
       // Extract path from webhook URL
       const url = new URL(webhookUrl);
       const webhookPath = url.pathname;

src/services/n8n-validation.ts

@@ -45,6 +45,7 @@ export const workflowSettingsSchema = z.object({
   saveExecutionProgress: z.boolean().default(true),
   executionTimeout: z.number().optional(),
   errorWorkflow: z.string().optional(),
+  callerPolicy: z.enum(['any', 'workflowsFromSameOwner', 'workflowsFromAList']).optional(),
 });
 
 // Default settings for workflow creation
@@ -95,14 +96,17 @@ export function cleanWorkflowForCreate(workflow: Partial<Workflow>): Partial<Wor
 
 /**
  * Clean workflow data for update operations.
- * 
+ *
  * This function removes read-only and computed fields that should not be sent
  * in API update requests. It does NOT add any default values or new fields.
- * 
+ *
  * Note: Unlike cleanWorkflowForCreate, this function does not add default settings.
  * The n8n API will reject update requests that include properties not present in
  * the original workflow ("settings must NOT have additional properties" error).
- * 
+ *
+ * Settings are filtered to only include whitelisted properties to prevent API
+ * errors when workflows from n8n contain UI-only or deprecated properties.
+ *
  * @param workflow - The workflow object to clean
  * @returns A cleaned partial workflow suitable for API updates
  */
@@ -129,6 +133,51 @@ export function cleanWorkflowForUpdate(workflow: Workflow): Partial<Workflow> {
     ...cleanedWorkflow
   } = workflow as any;
 
+  // CRITICAL FIX for Issue #248:
+  // The n8n API has version-specific behavior for settings in workflow updates:
+  //
+  // PROBLEM:
+  // - Some versions reject updates with settings properties (community forum reports)
+  // - Cloud versions REQUIRE settings property to be present (n8n.estyl.team)
+  // - Properties like callerPolicy cause "additional properties" errors
+  //
+  // SOLUTION:
+  // - Filter settings to only include whitelisted properties (OpenAPI spec)
+  // - If no settings provided, use empty object {} for safety
+  // - Empty object satisfies "required property" validation (cloud API)
+  // - Whitelisted properties prevent "additional properties" errors
+  //
+  // References:
+  // - https://community.n8n.io/t/api-workflow-update-endpoint-doesnt-support-setting-callerpolicy/161916
+  // - OpenAPI spec: workflowSettings schema
+  // - Tested on n8n.estyl.team (cloud) and localhost (self-hosted)
+
+  // Whitelisted settings properties from n8n OpenAPI spec
+  const safeSettingsProperties = [
+    'saveExecutionProgress',
+    'saveManualExecutions',
+    'saveDataErrorExecution',
+    'saveDataSuccessExecution',
+    'executionTimeout',
+    'errorWorkflow',
+    'timezone',
+    'executionOrder'
+  ];
+
+  if (cleanedWorkflow.settings && typeof cleanedWorkflow.settings === 'object') {
+    // Filter to only safe properties
+    const filteredSettings: any = {};
+    for (const key of safeSettingsProperties) {
+      if (key in cleanedWorkflow.settings) {
+        filteredSettings[key] = (cleanedWorkflow.settings as any)[key];
+      }
+    }
+    cleanedWorkflow.settings = filteredSettings;
+  } else {
+    // No settings provided - use empty object for safety
+    cleanedWorkflow.settings = {};
+  }
+
   return cleanedWorkflow;
 }
 

src/services/node-similarity-service.ts

@@ -0,0 +1,512 @@
+import { NodeRepository } from '../database/node-repository';
+import { logger } from '../utils/logger';
+
+export interface NodeSuggestion {
+  nodeType: string;
+  displayName: string;
+  confidence: number;
+  reason: string;
+  category?: string;
+  description?: string;
+}
+
+export interface SimilarityScore {
+  nameSimilarity: number;
+  categoryMatch: number;
+  packageMatch: number;
+  patternMatch: number;
+  totalScore: number;
+}
+
+export interface CommonMistakePattern {
+  pattern: string;
+  suggestion: string;
+  confidence: number;
+  reason: string;
+}
+
+export class NodeSimilarityService {
+  // Constants to avoid magic numbers
+  private static readonly SCORING_THRESHOLD = 50; // Minimum 50% confidence to suggest
+  private static readonly TYPO_EDIT_DISTANCE = 2; // Max 2 character differences for typo detection
+  private static readonly SHORT_SEARCH_LENGTH = 5; // Searches ≤5 chars need special handling
+  private static readonly CACHE_DURATION_MS = 5 * 60 * 1000; // 5 minutes
+  private static readonly AUTO_FIX_CONFIDENCE = 0.9; // 90% confidence for auto-fix
+
+  private repository: NodeRepository;
+  private commonMistakes: Map<string, CommonMistakePattern[]>;
+  private nodeCache: any[] | null = null;
+  private cacheExpiry: number = 0;
+  private cacheVersion: number = 0; // Track cache version for invalidation
+
+  constructor(repository: NodeRepository) {
+    this.repository = repository;
+    this.commonMistakes = this.initializeCommonMistakes();
+  }
+
+  /**
+   * Initialize common mistake patterns
+   * Using safer string-based patterns instead of complex regex to avoid ReDoS
+   */
+  private initializeCommonMistakes(): Map<string, CommonMistakePattern[]> {
+    const patterns = new Map<string, CommonMistakePattern[]>();
+
+    // Case variations - using exact string matching (case-insensitive)
+    patterns.set('case_variations', [
+      { pattern: 'httprequest', suggestion: 'nodes-base.httpRequest', confidence: 0.95, reason: 'Incorrect capitalization' },
+      { pattern: 'webhook', suggestion: 'nodes-base.webhook', confidence: 0.95, reason: 'Incorrect capitalization' },
+      { pattern: 'slack', suggestion: 'nodes-base.slack', confidence: 0.9, reason: 'Missing package prefix' },
+      { pattern: 'gmail', suggestion: 'nodes-base.gmail', confidence: 0.9, reason: 'Missing package prefix' },
+      { pattern: 'googlesheets', suggestion: 'nodes-base.googleSheets', confidence: 0.9, reason: 'Missing package prefix' },
+      { pattern: 'telegram', suggestion: 'nodes-base.telegram', confidence: 0.9, reason: 'Missing package prefix' },
+    ]);
+
+    // Specific case variations that are common
+    patterns.set('specific_variations', [
+      { pattern: 'HttpRequest', suggestion: 'nodes-base.httpRequest', confidence: 0.95, reason: 'Incorrect capitalization' },
+      { pattern: 'HTTPRequest', suggestion: 'nodes-base.httpRequest', confidence: 0.95, reason: 'Common capitalization mistake' },
+      { pattern: 'Webhook', suggestion: 'nodes-base.webhook', confidence: 0.95, reason: 'Incorrect capitalization' },
+      { pattern: 'WebHook', suggestion: 'nodes-base.webhook', confidence: 0.95, reason: 'Common capitalization mistake' },
+    ]);
+
+    // Deprecated package prefixes
+    patterns.set('deprecated_prefixes', [
+      { pattern: 'n8n-nodes-base.', suggestion: 'nodes-base.', confidence: 0.95, reason: 'Full package name used instead of short form' },
+      { pattern: '@n8n/n8n-nodes-langchain.', suggestion: 'nodes-langchain.', confidence: 0.95, reason: 'Full package name used instead of short form' },
+    ]);
+
+    // Common typos - exact matches
+    patterns.set('typos', [
+      { pattern: 'htprequest', suggestion: 'nodes-base.httpRequest', confidence: 0.8, reason: 'Likely typo' },
+      { pattern: 'httpreqest', suggestion: 'nodes-base.httpRequest', confidence: 0.8, reason: 'Likely typo' },
+      { pattern: 'webook', suggestion: 'nodes-base.webhook', confidence: 0.8, reason: 'Likely typo' },
+      { pattern: 'slak', suggestion: 'nodes-base.slack', confidence: 0.8, reason: 'Likely typo' },
+      { pattern: 'googlesheets', suggestion: 'nodes-base.googleSheets', confidence: 0.8, reason: 'Likely typo' },
+    ]);
+
+    // AI/LangChain specific
+    patterns.set('ai_nodes', [
+      { pattern: 'openai', suggestion: 'nodes-langchain.openAi', confidence: 0.85, reason: 'AI node - incorrect package' },
+      { pattern: 'nodes-base.openai', suggestion: 'nodes-langchain.openAi', confidence: 0.9, reason: 'Wrong package - OpenAI is in LangChain package' },
+      { pattern: 'chatopenai', suggestion: 'nodes-langchain.lmChatOpenAi', confidence: 0.85, reason: 'LangChain node naming convention' },
+      { pattern: 'vectorstore', suggestion: 'nodes-langchain.vectorStoreInMemory', confidence: 0.7, reason: 'Generic vector store reference' },
+    ]);
+
+    return patterns;
+  }
+
+  /**
+   * Check if a type is a common node name without prefix
+   */
+  private isCommonNodeWithoutPrefix(type: string): string | null {
+    const commonNodes: Record<string, string> = {
+      'httprequest': 'nodes-base.httpRequest',
+      'webhook': 'nodes-base.webhook',
+      'slack': 'nodes-base.slack',
+      'gmail': 'nodes-base.gmail',
+      'googlesheets': 'nodes-base.googleSheets',
+      'telegram': 'nodes-base.telegram',
+      'discord': 'nodes-base.discord',
+      'notion': 'nodes-base.notion',
+      'airtable': 'nodes-base.airtable',
+      'postgres': 'nodes-base.postgres',
+      'mysql': 'nodes-base.mySql',
+      'mongodb': 'nodes-base.mongoDb',
+    };
+
+    const normalized = type.toLowerCase();
+    return commonNodes[normalized] || null;
+  }
+
+  /**
+   * Find similar nodes for an invalid type
+   */
+  async findSimilarNodes(invalidType: string, limit: number = 5): Promise<NodeSuggestion[]> {
+    if (!invalidType || invalidType.trim() === '') {
+      return [];
+    }
+
+    const suggestions: NodeSuggestion[] = [];
+
+    // First, check for exact common mistakes
+    const mistakeSuggestion = this.checkCommonMistakes(invalidType);
+    if (mistakeSuggestion) {
+      suggestions.push(mistakeSuggestion);
+    }
+
+    // Get all nodes (with caching)
+    const allNodes = await this.getCachedNodes();
+
+    // Calculate similarity scores for all nodes
+    const scores = allNodes.map(node => ({
+      node,
+      score: this.calculateSimilarityScore(invalidType, node)
+    }));
+
+    // Sort by total score and filter high scores
+    scores.sort((a, b) => b.score.totalScore - a.score.totalScore);
+
+    // Add top suggestions (excluding already added exact matches)
+    for (const { node, score } of scores) {
+      if (suggestions.some(s => s.nodeType === node.nodeType)) {
+        continue;
+      }
+
+      if (score.totalScore >= NodeSimilarityService.SCORING_THRESHOLD) {
+        suggestions.push(this.createSuggestion(node, score));
+      }
+
+      if (suggestions.length >= limit) {
+        break;
+      }
+    }
+
+    return suggestions;
+  }
+
+  /**
+   * Check for common mistake patterns (ReDoS-safe implementation)
+   */
+  private checkCommonMistakes(invalidType: string): NodeSuggestion | null {
+    const cleanType = invalidType.trim();
+    const lowerType = cleanType.toLowerCase();
+
+    // First check for common nodes without prefix
+    const commonNodeSuggestion = this.isCommonNodeWithoutPrefix(cleanType);
+    if (commonNodeSuggestion) {
+      const node = this.repository.getNode(commonNodeSuggestion);
+      if (node) {
+        return {
+          nodeType: commonNodeSuggestion,
+          displayName: node.displayName,
+          confidence: 0.9,
+          reason: 'Missing package prefix',
+          category: node.category,
+          description: node.description
+        };
+      }
+    }
+
+    // Check deprecated prefixes (string-based, no regex)
+    for (const [category, patterns] of this.commonMistakes) {
+      if (category === 'deprecated_prefixes') {
+        for (const pattern of patterns) {
+          if (cleanType.startsWith(pattern.pattern)) {
+            const actualSuggestion = cleanType.replace(pattern.pattern, pattern.suggestion);
+            const node = this.repository.getNode(actualSuggestion);
+            if (node) {
+              return {
+                nodeType: actualSuggestion,
+                displayName: node.displayName,
+                confidence: pattern.confidence,
+                reason: pattern.reason,
+                category: node.category,
+                description: node.description
+              };
+            }
+          }
+        }
+      }
+    }
+
+    // Check exact matches for typos and variations
+    for (const [category, patterns] of this.commonMistakes) {
+      if (category === 'deprecated_prefixes') continue; // Already handled
+
+      for (const pattern of patterns) {
+        // Simple string comparison (case-sensitive for specific_variations)
+        const match = category === 'specific_variations'
+          ? cleanType === pattern.pattern
+          : lowerType === pattern.pattern.toLowerCase();
+
+        if (match && pattern.suggestion) {
+          const node = this.repository.getNode(pattern.suggestion);
+          if (node) {
+            return {
+              nodeType: pattern.suggestion,
+              displayName: node.displayName,
+              confidence: pattern.confidence,
+              reason: pattern.reason,
+              category: node.category,
+              description: node.description
+            };
+          }
+        }
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Calculate multi-factor similarity score
+   */
+  private calculateSimilarityScore(invalidType: string, node: any): SimilarityScore {
+    const cleanInvalid = this.normalizeNodeType(invalidType);
+    const cleanValid = this.normalizeNodeType(node.nodeType);
+    const displayNameClean = this.normalizeNodeType(node.displayName);
+
+    // Special handling for very short search terms (e.g., "http", "sheet")
+    const isShortSearch = invalidType.length <= NodeSimilarityService.SHORT_SEARCH_LENGTH;
+
+    // Name similarity (40% weight)
+    let nameSimilarity = Math.max(
+      this.getStringSimilarity(cleanInvalid, cleanValid),
+      this.getStringSimilarity(cleanInvalid, displayNameClean)
+    ) * 40;
+
+    // For short searches that are substrings, give a small name similarity boost
+    if (isShortSearch && (cleanValid.includes(cleanInvalid) || displayNameClean.includes(cleanInvalid))) {
+      nameSimilarity = Math.max(nameSimilarity, 10);
+    }
+
+    // Category match (20% weight)
+    let categoryMatch = 0;
+    if (node.category) {
+      const categoryClean = this.normalizeNodeType(node.category);
+      if (cleanInvalid.includes(categoryClean) || categoryClean.includes(cleanInvalid)) {
+        categoryMatch = 20;
+      }
+    }
+
+    // Package match (15% weight)
+    let packageMatch = 0;
+    const invalidParts = cleanInvalid.split(/[.-]/);
+    const validParts = cleanValid.split(/[.-]/);
+
+    if (invalidParts[0] === validParts[0]) {
+      packageMatch = 15;
+    }
+
+    // Pattern match (25% weight)
+    let patternMatch = 0;
+
+    // Check if it's a substring match
+    if (cleanValid.includes(cleanInvalid) || displayNameClean.includes(cleanInvalid)) {
+      // Boost score significantly for short searches that are exact substring matches
+      // Short searches need more boost to reach the 50 threshold
+      patternMatch = isShortSearch ? 45 : 25;
+    } else if (this.getEditDistance(cleanInvalid, cleanValid) <= NodeSimilarityService.TYPO_EDIT_DISTANCE) {
+      // Small edit distance indicates likely typo
+      patternMatch = 20;
+    } else if (this.getEditDistance(cleanInvalid, displayNameClean) <= NodeSimilarityService.TYPO_EDIT_DISTANCE) {
+      patternMatch = 18;
+    }
+
+    // For very short searches, also check if the search term appears at the start
+    if (isShortSearch && (cleanValid.startsWith(cleanInvalid) || displayNameClean.startsWith(cleanInvalid))) {
+      patternMatch = Math.max(patternMatch, 40);
+    }
+
+    const totalScore = nameSimilarity + categoryMatch + packageMatch + patternMatch;
+
+    return {
+      nameSimilarity,
+      categoryMatch,
+      packageMatch,
+      patternMatch,
+      totalScore
+    };
+  }
+
+  /**
+   * Create a suggestion object from node and score
+   */
+  private createSuggestion(node: any, score: SimilarityScore): NodeSuggestion {
+    let reason = 'Similar node';
+
+    if (score.patternMatch >= 20) {
+      reason = 'Name similarity';
+    } else if (score.categoryMatch >= 15) {
+      reason = 'Same category';
+    } else if (score.packageMatch >= 10) {
+      reason = 'Same package';
+    }
+
+    // Calculate confidence (0-1 scale)
+    const confidence = Math.min(score.totalScore / 100, 1);
+
+    return {
+      nodeType: node.nodeType,
+      displayName: node.displayName,
+      confidence,
+      reason,
+      category: node.category,
+      description: node.description
+    };
+  }
+
+  /**
+   * Normalize node type for comparison
+   */
+  private normalizeNodeType(type: string): string {
+    return type
+      .toLowerCase()
+      .replace(/[^a-z0-9]/g, '')
+      .trim();
+  }
+
+  /**
+   * Calculate string similarity (0-1)
+   */
+  private getStringSimilarity(s1: string, s2: string): number {
+    if (s1 === s2) return 1;
+    if (!s1 || !s2) return 0;
+
+    const distance = this.getEditDistance(s1, s2);
+    const maxLen = Math.max(s1.length, s2.length);
+
+    return 1 - (distance / maxLen);
+  }
+
+  /**
+   * Calculate Levenshtein distance with optimizations
+   * - Early termination when difference exceeds threshold
+   * - Space-optimized to use only two rows instead of full matrix
+   * - Fast path for identical or vastly different strings
+   */
+  private getEditDistance(s1: string, s2: string, maxDistance: number = 5): number {
+    // Fast path: identical strings
+    if (s1 === s2) return 0;
+
+    const m = s1.length;
+    const n = s2.length;
+
+    // Fast path: length difference exceeds threshold
+    const lengthDiff = Math.abs(m - n);
+    if (lengthDiff > maxDistance) return maxDistance + 1;
+
+    // Fast path: empty strings
+    if (m === 0) return n;
+    if (n === 0) return m;
+
+    // Space optimization: only need previous and current row
+    let prev = Array(n + 1).fill(0).map((_, i) => i);
+
+    for (let i = 1; i <= m; i++) {
+      const curr = [i];
+      let minInRow = i;
+
+      for (let j = 1; j <= n; j++) {
+        const cost = s1[i - 1] === s2[j - 1] ? 0 : 1;
+        const val = Math.min(
+          curr[j - 1] + 1,      // deletion
+          prev[j] + 1,          // insertion
+          prev[j - 1] + cost    // substitution
+        );
+        curr.push(val);
+        minInRow = Math.min(minInRow, val);
+      }
+
+      // Early termination: if minimum in this row exceeds threshold
+      if (minInRow > maxDistance) {
+        return maxDistance + 1;
+      }
+
+      prev = curr;
+    }
+
+    return prev[n];
+  }
+
+  /**
+   * Get cached nodes or fetch from repository
+   * Implements proper cache invalidation with version tracking
+   */
+  private async getCachedNodes(): Promise<any[]> {
+    const now = Date.now();
+
+    if (!this.nodeCache || now > this.cacheExpiry) {
+      try {
+        const newNodes = this.repository.getAllNodes();
+
+        // Only update cache if we got valid data
+        if (newNodes && newNodes.length > 0) {
+          this.nodeCache = newNodes;
+          this.cacheExpiry = now + NodeSimilarityService.CACHE_DURATION_MS;
+          this.cacheVersion++;
+          logger.debug('Node cache refreshed', {
+            count: newNodes.length,
+            version: this.cacheVersion
+          });
+        } else if (this.nodeCache) {
+          // Return stale cache if new fetch returned empty
+          logger.warn('Node fetch returned empty, using stale cache');
+        }
+      } catch (error) {
+        logger.error('Failed to fetch nodes for similarity service', error);
+        // Return stale cache on error if available
+        if (this.nodeCache) {
+          logger.info('Using stale cache due to fetch error');
+          return this.nodeCache;
+        }
+        return [];
+      }
+    }
+
+    return this.nodeCache || [];
+  }
+
+  /**
+   * Invalidate the cache (e.g., after database updates)
+   */
+  public invalidateCache(): void {
+    this.nodeCache = null;
+    this.cacheExpiry = 0;
+    this.cacheVersion++;
+    logger.debug('Node cache invalidated', { version: this.cacheVersion });
+  }
+
+  /**
+   * Clear and refresh cache immediately
+   */
+  public async refreshCache(): Promise<void> {
+    this.invalidateCache();
+    await this.getCachedNodes();
+  }
+
+  /**
+   * Format suggestions into a user-friendly message
+   */
+  formatSuggestionMessage(suggestions: NodeSuggestion[], invalidType: string): string {
+    if (suggestions.length === 0) {
+      return `Unknown node type: "${invalidType}". No similar nodes found.`;
+    }
+
+    let message = `Unknown node type: "${invalidType}"\n\nDid you mean one of these?\n`;
+
+    for (const suggestion of suggestions) {
+      const confidence = Math.round(suggestion.confidence * 100);
+      message += `• ${suggestion.nodeType} (${confidence}% match)`;
+
+      if (suggestion.displayName) {
+        message += ` - ${suggestion.displayName}`;
+      }
+
+      message += `\n  → ${suggestion.reason}`;
+
+      if (suggestion.confidence >= 0.9) {
+        message += ' (can be auto-fixed)';
+      }
+
+      message += '\n';
+    }
+
+    return message;
+  }
+
+  /**
+   * Check if a suggestion is high confidence for auto-fixing
+   */
+  isAutoFixable(suggestion: NodeSuggestion): boolean {
+    return suggestion.confidence >= NodeSimilarityService.AUTO_FIX_CONFIDENCE;
+  }
+
+  /**
+   * Clear the node cache (useful after database updates)
+   * @deprecated Use invalidateCache() instead for proper version tracking
+   */
+  clearCache(): void {
+    this.invalidateCache();
+  }
+}

src/services/node-specific-validators.ts

@@ -1132,8 +1132,11 @@ export class NodeSpecificValidators {
     const syntaxPatterns = [
       { pattern: /const\s+const/, message: 'Duplicate const declaration' },
       { pattern: /let\s+let/, message: 'Duplicate let declaration' },
-      { pattern: /\)\s*\)\s*{/, message: 'Extra closing parenthesis before {' },
-      { pattern: /}\s*}$/, message: 'Extra closing brace at end' }
+      // Removed overly simplistic parenthesis check - it was causing false positives
+      // for valid patterns like $('NodeName').first().json or func()()
+      // { pattern: /\)\s*\)\s*{/, message: 'Extra closing parenthesis before {' },
+      // Only check for multiple closing braces at the very end (more likely to be an error)
+      { pattern: /}\s*}\s*}\s*}$/, message: 'Multiple closing braces at end - check your nesting' }
     ];
     
     syntaxPatterns.forEach(({ pattern, message }) => {

src/services/operation-similarity-service.ts

@@ -0,0 +1,502 @@
+import { NodeRepository } from '../database/node-repository';
+import { logger } from '../utils/logger';
+import { ValidationServiceError } from '../errors/validation-service-error';
+
+export interface OperationSuggestion {
+  value: string;
+  confidence: number;
+  reason: string;
+  resource?: string;
+  description?: string;
+}
+
+interface OperationPattern {
+  pattern: string;
+  suggestion: string;
+  confidence: number;
+  reason: string;
+}
+
+export class OperationSimilarityService {
+  private static readonly CACHE_DURATION_MS = 5 * 60 * 1000; // 5 minutes
+  private static readonly MIN_CONFIDENCE = 0.3; // 30% minimum confidence to suggest
+  private static readonly MAX_SUGGESTIONS = 5;
+
+  // Confidence thresholds for better code clarity
+  private static readonly CONFIDENCE_THRESHOLDS = {
+    EXACT: 1.0,
+    VERY_HIGH: 0.95,
+    HIGH: 0.8,
+    MEDIUM: 0.6,
+    MIN_SUBSTRING: 0.7
+  } as const;
+
+  private repository: NodeRepository;
+  private operationCache: Map<string, { operations: any[], timestamp: number }> = new Map();
+  private suggestionCache: Map<string, OperationSuggestion[]> = new Map();
+  private commonPatterns: Map<string, OperationPattern[]>;
+
+  constructor(repository: NodeRepository) {
+    this.repository = repository;
+    this.commonPatterns = this.initializeCommonPatterns();
+  }
+
+  /**
+   * Clean up expired cache entries to prevent memory leaks
+   * Should be called periodically or before cache operations
+   */
+  private cleanupExpiredEntries(): void {
+    const now = Date.now();
+
+    // Clean operation cache
+    for (const [key, value] of this.operationCache.entries()) {
+      if (now - value.timestamp >= OperationSimilarityService.CACHE_DURATION_MS) {
+        this.operationCache.delete(key);
+      }
+    }
+
+    // Clean suggestion cache - these don't have timestamps, so clear if cache is too large
+    if (this.suggestionCache.size > 100) {
+      // Keep only the most recent 50 entries
+      const entries = Array.from(this.suggestionCache.entries());
+      this.suggestionCache.clear();
+      entries.slice(-50).forEach(([key, value]) => {
+        this.suggestionCache.set(key, value);
+      });
+    }
+  }
+
+  /**
+   * Initialize common operation mistake patterns
+   */
+  private initializeCommonPatterns(): Map<string, OperationPattern[]> {
+    const patterns = new Map<string, OperationPattern[]>();
+
+    // Google Drive patterns
+    patterns.set('googleDrive', [
+      { pattern: 'listFiles', suggestion: 'search', confidence: 0.85, reason: 'Use "search" with resource: "fileFolder" to list files' },
+      { pattern: 'uploadFile', suggestion: 'upload', confidence: 0.95, reason: 'Use "upload" instead of "uploadFile"' },
+      { pattern: 'deleteFile', suggestion: 'deleteFile', confidence: 1.0, reason: 'Exact match' },
+      { pattern: 'downloadFile', suggestion: 'download', confidence: 0.95, reason: 'Use "download" instead of "downloadFile"' },
+      { pattern: 'getFile', suggestion: 'download', confidence: 0.8, reason: 'Use "download" to retrieve file content' },
+      { pattern: 'listFolders', suggestion: 'search', confidence: 0.85, reason: 'Use "search" with resource: "fileFolder"' },
+    ]);
+
+    // Slack patterns
+    patterns.set('slack', [
+      { pattern: 'sendMessage', suggestion: 'send', confidence: 0.95, reason: 'Use "send" instead of "sendMessage"' },
+      { pattern: 'getMessage', suggestion: 'get', confidence: 0.9, reason: 'Use "get" to retrieve messages' },
+      { pattern: 'postMessage', suggestion: 'send', confidence: 0.9, reason: 'Use "send" to post messages' },
+      { pattern: 'deleteMessage', suggestion: 'delete', confidence: 0.95, reason: 'Use "delete" instead of "deleteMessage"' },
+      { pattern: 'createChannel', suggestion: 'create', confidence: 0.9, reason: 'Use "create" with resource: "channel"' },
+    ]);
+
+    // Database patterns (postgres, mysql, mongodb)
+    patterns.set('database', [
+      { pattern: 'selectData', suggestion: 'select', confidence: 0.95, reason: 'Use "select" instead of "selectData"' },
+      { pattern: 'insertData', suggestion: 'insert', confidence: 0.95, reason: 'Use "insert" instead of "insertData"' },
+      { pattern: 'updateData', suggestion: 'update', confidence: 0.95, reason: 'Use "update" instead of "updateData"' },
+      { pattern: 'deleteData', suggestion: 'delete', confidence: 0.95, reason: 'Use "delete" instead of "deleteData"' },
+      { pattern: 'query', suggestion: 'select', confidence: 0.7, reason: 'Use "select" for queries' },
+      { pattern: 'fetch', suggestion: 'select', confidence: 0.7, reason: 'Use "select" to fetch data' },
+    ]);
+
+    // HTTP patterns
+    patterns.set('httpRequest', [
+      { pattern: 'fetch', suggestion: 'GET', confidence: 0.8, reason: 'Use "GET" method for fetching data' },
+      { pattern: 'send', suggestion: 'POST', confidence: 0.7, reason: 'Use "POST" method for sending data' },
+      { pattern: 'create', suggestion: 'POST', confidence: 0.8, reason: 'Use "POST" method for creating resources' },
+      { pattern: 'update', suggestion: 'PUT', confidence: 0.8, reason: 'Use "PUT" method for updating resources' },
+      { pattern: 'delete', suggestion: 'DELETE', confidence: 0.9, reason: 'Use "DELETE" method' },
+    ]);
+
+    // Generic patterns
+    patterns.set('generic', [
+      { pattern: 'list', suggestion: 'get', confidence: 0.6, reason: 'Consider using "get" or "search"' },
+      { pattern: 'retrieve', suggestion: 'get', confidence: 0.8, reason: 'Use "get" to retrieve data' },
+      { pattern: 'fetch', suggestion: 'get', confidence: 0.8, reason: 'Use "get" to fetch data' },
+      { pattern: 'remove', suggestion: 'delete', confidence: 0.85, reason: 'Use "delete" to remove items' },
+      { pattern: 'add', suggestion: 'create', confidence: 0.7, reason: 'Use "create" to add new items' },
+    ]);
+
+    return patterns;
+  }
+
+  /**
+   * Find similar operations for an invalid operation using Levenshtein distance
+   * and pattern matching algorithms
+   *
+   * @param nodeType - The n8n node type (e.g., 'nodes-base.slack')
+   * @param invalidOperation - The invalid operation provided by the user
+   * @param resource - Optional resource to filter operations
+   * @param maxSuggestions - Maximum number of suggestions to return (default: 5)
+   * @returns Array of operation suggestions sorted by confidence
+   *
+   * @example
+   * findSimilarOperations('nodes-base.googleDrive', 'listFiles', 'fileFolder')
+   * // Returns: [{ value: 'search', confidence: 0.85, reason: 'Use "search" with resource: "fileFolder" to list files' }]
+   */
+  findSimilarOperations(
+    nodeType: string,
+    invalidOperation: string,
+    resource?: string,
+    maxSuggestions: number = OperationSimilarityService.MAX_SUGGESTIONS
+  ): OperationSuggestion[] {
+    // Clean up expired cache entries periodically
+    if (Math.random() < 0.1) { // 10% chance to cleanup on each call
+      this.cleanupExpiredEntries();
+    }
+    // Check cache first
+    const cacheKey = `${nodeType}:${invalidOperation}:${resource || ''}`;
+    if (this.suggestionCache.has(cacheKey)) {
+      return this.suggestionCache.get(cacheKey)!;
+    }
+
+    const suggestions: OperationSuggestion[] = [];
+
+    // Get valid operations for the node
+    let nodeInfo;
+    try {
+      nodeInfo = this.repository.getNode(nodeType);
+      if (!nodeInfo) {
+        return [];
+      }
+    } catch (error) {
+      logger.warn(`Error getting node ${nodeType}:`, error);
+      return [];
+    }
+
+    const validOperations = this.getNodeOperations(nodeType, resource);
+
+    // Early termination for exact match - no suggestions needed
+    for (const op of validOperations) {
+      const opValue = this.getOperationValue(op);
+      if (opValue.toLowerCase() === invalidOperation.toLowerCase()) {
+        return []; // Valid operation, no suggestions needed
+      }
+    }
+
+    // Check for exact pattern matches first
+    const nodePatterns = this.getNodePatterns(nodeType);
+    for (const pattern of nodePatterns) {
+      if (pattern.pattern.toLowerCase() === invalidOperation.toLowerCase()) {
+        // Type-safe operation value extraction
+        const exists = validOperations.some(op => {
+          const opValue = this.getOperationValue(op);
+          return opValue === pattern.suggestion;
+        });
+        if (exists) {
+          suggestions.push({
+            value: pattern.suggestion,
+            confidence: pattern.confidence,
+            reason: pattern.reason,
+            resource
+          });
+        }
+      }
+    }
+
+    // Calculate similarity for all valid operations
+    for (const op of validOperations) {
+      const opValue = this.getOperationValue(op);
+
+      const similarity = this.calculateSimilarity(invalidOperation, opValue);
+
+      if (similarity >= OperationSimilarityService.MIN_CONFIDENCE) {
+        // Don't add if already suggested by pattern
+        if (!suggestions.some(s => s.value === opValue)) {
+          suggestions.push({
+            value: opValue,
+            confidence: similarity,
+            reason: this.getSimilarityReason(similarity, invalidOperation, opValue),
+            resource: typeof op === 'object' ? op.resource : undefined,
+            description: typeof op === 'object' ? (op.description || op.name) : undefined
+          });
+        }
+      }
+    }
+
+    // Sort by confidence and limit
+    suggestions.sort((a, b) => b.confidence - a.confidence);
+    const topSuggestions = suggestions.slice(0, maxSuggestions);
+
+    // Cache the result
+    this.suggestionCache.set(cacheKey, topSuggestions);
+
+    return topSuggestions;
+  }
+
+  /**
+   * Type-safe extraction of operation value from various formats
+   * @param op - Operation object or string
+   * @returns The operation value as a string
+   */
+  private getOperationValue(op: any): string {
+    if (typeof op === 'string') {
+      return op;
+    }
+    if (typeof op === 'object' && op !== null) {
+      return op.operation || op.value || '';
+    }
+    return '';
+  }
+
+  /**
+   * Type-safe extraction of resource value
+   * @param resource - Resource object or string
+   * @returns The resource value as a string
+   */
+  private getResourceValue(resource: any): string {
+    if (typeof resource === 'string') {
+      return resource;
+    }
+    if (typeof resource === 'object' && resource !== null) {
+      return resource.value || '';
+    }
+    return '';
+  }
+
+  /**
+   * Get operations for a node, handling resource filtering
+   */
+  private getNodeOperations(nodeType: string, resource?: string): any[] {
+    // Cleanup cache periodically
+    if (Math.random() < 0.05) { // 5% chance
+      this.cleanupExpiredEntries();
+    }
+
+    const cacheKey = `${nodeType}:${resource || 'all'}`;
+    const cached = this.operationCache.get(cacheKey);
+
+    if (cached && Date.now() - cached.timestamp < OperationSimilarityService.CACHE_DURATION_MS) {
+      return cached.operations;
+    }
+
+    const nodeInfo = this.repository.getNode(nodeType);
+    if (!nodeInfo) return [];
+
+    let operations: any[] = [];
+
+    // Parse operations from the node with safe JSON parsing
+    try {
+      const opsData = nodeInfo.operations;
+      if (typeof opsData === 'string') {
+        // Safe JSON parsing
+        try {
+          operations = JSON.parse(opsData);
+        } catch (parseError) {
+          logger.error(`JSON parse error for operations in ${nodeType}:`, parseError);
+          throw ValidationServiceError.jsonParseError(nodeType, parseError as Error);
+        }
+      } else if (Array.isArray(opsData)) {
+        operations = opsData;
+      } else if (opsData && typeof opsData === 'object') {
+        operations = Object.values(opsData).flat();
+      }
+    } catch (error) {
+      // Re-throw ValidationServiceError, log and continue for others
+      if (error instanceof ValidationServiceError) {
+        throw error;
+      }
+      logger.warn(`Failed to process operations for ${nodeType}:`, error);
+    }
+
+    // Also check properties for operation fields
+    try {
+      const properties = nodeInfo.properties || [];
+      for (const prop of properties) {
+        if (prop.name === 'operation' && prop.options) {
+          // Filter by resource if specified
+          if (prop.displayOptions?.show?.resource) {
+            const allowedResources = Array.isArray(prop.displayOptions.show.resource)
+              ? prop.displayOptions.show.resource
+              : [prop.displayOptions.show.resource];
+            // Only filter if a specific resource is requested
+            if (resource && !allowedResources.includes(resource)) {
+              continue;
+            }
+            // If no resource specified, include all operations
+          }
+
+          operations.push(...prop.options.map((opt: any) => ({
+            operation: opt.value,
+            name: opt.name,
+            description: opt.description,
+            resource
+          })));
+        }
+      }
+    } catch (error) {
+      logger.warn(`Failed to extract operations from properties for ${nodeType}:`, error);
+    }
+
+    // Cache and return
+    this.operationCache.set(cacheKey, { operations, timestamp: Date.now() });
+    return operations;
+  }
+
+  /**
+   * Get patterns for a specific node type
+   */
+  private getNodePatterns(nodeType: string): OperationPattern[] {
+    const patterns: OperationPattern[] = [];
+
+    // Add node-specific patterns
+    if (nodeType.includes('googleDrive')) {
+      patterns.push(...(this.commonPatterns.get('googleDrive') || []));
+    } else if (nodeType.includes('slack')) {
+      patterns.push(...(this.commonPatterns.get('slack') || []));
+    } else if (nodeType.includes('postgres') || nodeType.includes('mysql') || nodeType.includes('mongodb')) {
+      patterns.push(...(this.commonPatterns.get('database') || []));
+    } else if (nodeType.includes('httpRequest')) {
+      patterns.push(...(this.commonPatterns.get('httpRequest') || []));
+    }
+
+    // Always add generic patterns
+    patterns.push(...(this.commonPatterns.get('generic') || []));
+
+    return patterns;
+  }
+
+  /**
+   * Calculate similarity between two strings using Levenshtein distance
+   */
+  private calculateSimilarity(str1: string, str2: string): number {
+    const s1 = str1.toLowerCase();
+    const s2 = str2.toLowerCase();
+
+    // Exact match
+    if (s1 === s2) return 1.0;
+
+    // One is substring of the other
+    if (s1.includes(s2) || s2.includes(s1)) {
+      const ratio = Math.min(s1.length, s2.length) / Math.max(s1.length, s2.length);
+      return Math.max(OperationSimilarityService.CONFIDENCE_THRESHOLDS.MIN_SUBSTRING, ratio);
+    }
+
+    // Calculate Levenshtein distance
+    const distance = this.levenshteinDistance(s1, s2);
+    const maxLength = Math.max(s1.length, s2.length);
+
+    // Convert distance to similarity (0 to 1)
+    let similarity = 1 - (distance / maxLength);
+
+    // Boost confidence for single character typos and transpositions in short words
+    if (distance === 1 && maxLength <= 5) {
+      similarity = Math.max(similarity, 0.75);
+    } else if (distance === 2 && maxLength <= 5) {
+      // Boost for transpositions
+      similarity = Math.max(similarity, 0.72);
+    }
+
+    // Boost similarity for common patterns
+    if (this.areCommonVariations(s1, s2)) {
+      return Math.min(1.0, similarity + 0.2);
+    }
+
+    return similarity;
+  }
+
+  /**
+   * Calculate Levenshtein distance between two strings
+   */
+  private levenshteinDistance(str1: string, str2: string): number {
+    const m = str1.length;
+    const n = str2.length;
+    const dp: number[][] = Array(m + 1).fill(null).map(() => Array(n + 1).fill(0));
+
+    for (let i = 0; i <= m; i++) dp[i][0] = i;
+    for (let j = 0; j <= n; j++) dp[0][j] = j;
+
+    for (let i = 1; i <= m; i++) {
+      for (let j = 1; j <= n; j++) {
+        if (str1[i - 1] === str2[j - 1]) {
+          dp[i][j] = dp[i - 1][j - 1];
+        } else {
+          dp[i][j] = Math.min(
+            dp[i - 1][j] + 1,    // deletion
+            dp[i][j - 1] + 1,    // insertion
+            dp[i - 1][j - 1] + 1 // substitution
+          );
+        }
+      }
+    }
+
+    return dp[m][n];
+  }
+
+  /**
+   * Check if two strings are common variations
+   */
+  private areCommonVariations(str1: string, str2: string): boolean {
+    // Handle edge cases first
+    if (str1 === '' || str2 === '' || str1 === str2) {
+      return false;
+    }
+
+    // Check for common prefixes/suffixes
+    const commonPrefixes = ['get', 'set', 'create', 'delete', 'update', 'send', 'fetch'];
+    const commonSuffixes = ['data', 'item', 'record', 'message', 'file', 'folder'];
+
+    for (const prefix of commonPrefixes) {
+      if ((str1.startsWith(prefix) && !str2.startsWith(prefix)) ||
+          (!str1.startsWith(prefix) && str2.startsWith(prefix))) {
+        const s1Clean = str1.startsWith(prefix) ? str1.slice(prefix.length) : str1;
+        const s2Clean = str2.startsWith(prefix) ? str2.slice(prefix.length) : str2;
+        // Only return true if at least one string was actually cleaned (not empty after cleaning)
+        if ((str1.startsWith(prefix) && s1Clean !== str1) || (str2.startsWith(prefix) && s2Clean !== str2)) {
+          if (s1Clean === s2Clean || this.levenshteinDistance(s1Clean, s2Clean) <= 2) {
+            return true;
+          }
+        }
+      }
+    }
+
+    for (const suffix of commonSuffixes) {
+      if ((str1.endsWith(suffix) && !str2.endsWith(suffix)) ||
+          (!str1.endsWith(suffix) && str2.endsWith(suffix))) {
+        const s1Clean = str1.endsWith(suffix) ? str1.slice(0, -suffix.length) : str1;
+        const s2Clean = str2.endsWith(suffix) ? str2.slice(0, -suffix.length) : str2;
+        // Only return true if at least one string was actually cleaned (not empty after cleaning)
+        if ((str1.endsWith(suffix) && s1Clean !== str1) || (str2.endsWith(suffix) && s2Clean !== str2)) {
+          if (s1Clean === s2Clean || this.levenshteinDistance(s1Clean, s2Clean) <= 2) {
+            return true;
+          }
+        }
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Generate a human-readable reason for the similarity
+   * @param confidence - Similarity confidence score
+   * @param invalid - The invalid operation string
+   * @param valid - The valid operation string
+   * @returns Human-readable explanation of the similarity
+   */
+  private getSimilarityReason(confidence: number, invalid: string, valid: string): string {
+    const { VERY_HIGH, HIGH, MEDIUM } = OperationSimilarityService.CONFIDENCE_THRESHOLDS;
+
+    if (confidence >= VERY_HIGH) {
+      return 'Almost exact match - likely a typo';
+    } else if (confidence >= HIGH) {
+      return 'Very similar - common variation';
+    } else if (confidence >= MEDIUM) {
+      return 'Similar operation';
+    } else if (invalid.includes(valid) || valid.includes(invalid)) {
+      return 'Partial match';
+    } else {
+      return 'Possibly related operation';
+    }
+  }
+
+  /**
+   * Clear caches
+   */
+  clearCache(): void {
+    this.operationCache.clear();
+    this.suggestionCache.clear();
+  }
+}

src/services/resource-similarity-service.ts

@@ -0,0 +1,522 @@
+import { NodeRepository } from '../database/node-repository';
+import { logger } from '../utils/logger';
+import { ValidationServiceError } from '../errors/validation-service-error';
+
+export interface ResourceSuggestion {
+  value: string;
+  confidence: number;
+  reason: string;
+  availableOperations?: string[];
+}
+
+interface ResourcePattern {
+  pattern: string;
+  suggestion: string;
+  confidence: number;
+  reason: string;
+}
+
+export class ResourceSimilarityService {
+  private static readonly CACHE_DURATION_MS = 5 * 60 * 1000; // 5 minutes
+  private static readonly MIN_CONFIDENCE = 0.3; // 30% minimum confidence to suggest
+  private static readonly MAX_SUGGESTIONS = 5;
+
+  // Confidence thresholds for better code clarity
+  private static readonly CONFIDENCE_THRESHOLDS = {
+    EXACT: 1.0,
+    VERY_HIGH: 0.95,
+    HIGH: 0.8,
+    MEDIUM: 0.6,
+    MIN_SUBSTRING: 0.7
+  } as const;
+
+  private repository: NodeRepository;
+  private resourceCache: Map<string, { resources: any[], timestamp: number }> = new Map();
+  private suggestionCache: Map<string, ResourceSuggestion[]> = new Map();
+  private commonPatterns: Map<string, ResourcePattern[]>;
+
+  constructor(repository: NodeRepository) {
+    this.repository = repository;
+    this.commonPatterns = this.initializeCommonPatterns();
+  }
+
+  /**
+   * Clean up expired cache entries to prevent memory leaks
+   */
+  private cleanupExpiredEntries(): void {
+    const now = Date.now();
+
+    // Clean resource cache
+    for (const [key, value] of this.resourceCache.entries()) {
+      if (now - value.timestamp >= ResourceSimilarityService.CACHE_DURATION_MS) {
+        this.resourceCache.delete(key);
+      }
+    }
+
+    // Clean suggestion cache - these don't have timestamps, so clear if cache is too large
+    if (this.suggestionCache.size > 100) {
+      // Keep only the most recent 50 entries
+      const entries = Array.from(this.suggestionCache.entries());
+      this.suggestionCache.clear();
+      entries.slice(-50).forEach(([key, value]) => {
+        this.suggestionCache.set(key, value);
+      });
+    }
+  }
+
+  /**
+   * Initialize common resource mistake patterns
+   */
+  private initializeCommonPatterns(): Map<string, ResourcePattern[]> {
+    const patterns = new Map<string, ResourcePattern[]>();
+
+    // Google Drive patterns
+    patterns.set('googleDrive', [
+      { pattern: 'files', suggestion: 'file', confidence: 0.95, reason: 'Use singular "file" not plural' },
+      { pattern: 'folders', suggestion: 'folder', confidence: 0.95, reason: 'Use singular "folder" not plural' },
+      { pattern: 'permissions', suggestion: 'permission', confidence: 0.9, reason: 'Use singular form' },
+      { pattern: 'fileAndFolder', suggestion: 'fileFolder', confidence: 0.9, reason: 'Use "fileFolder" for combined operations' },
+      { pattern: 'driveFiles', suggestion: 'file', confidence: 0.8, reason: 'Use "file" for file operations' },
+      { pattern: 'sharedDrives', suggestion: 'drive', confidence: 0.85, reason: 'Use "drive" for shared drive operations' },
+    ]);
+
+    // Slack patterns
+    patterns.set('slack', [
+      { pattern: 'messages', suggestion: 'message', confidence: 0.95, reason: 'Use singular "message" not plural' },
+      { pattern: 'channels', suggestion: 'channel', confidence: 0.95, reason: 'Use singular "channel" not plural' },
+      { pattern: 'users', suggestion: 'user', confidence: 0.95, reason: 'Use singular "user" not plural' },
+      { pattern: 'msg', suggestion: 'message', confidence: 0.85, reason: 'Use full "message" not abbreviation' },
+      { pattern: 'dm', suggestion: 'message', confidence: 0.7, reason: 'Use "message" for direct messages' },
+      { pattern: 'conversation', suggestion: 'channel', confidence: 0.7, reason: 'Use "channel" for conversations' },
+    ]);
+
+    // Database patterns (postgres, mysql, mongodb)
+    patterns.set('database', [
+      { pattern: 'tables', suggestion: 'table', confidence: 0.95, reason: 'Use singular "table" not plural' },
+      { pattern: 'queries', suggestion: 'query', confidence: 0.95, reason: 'Use singular "query" not plural' },
+      { pattern: 'collections', suggestion: 'collection', confidence: 0.95, reason: 'Use singular "collection" not plural' },
+      { pattern: 'documents', suggestion: 'document', confidence: 0.95, reason: 'Use singular "document" not plural' },
+      { pattern: 'records', suggestion: 'record', confidence: 0.85, reason: 'Use "record" or "document"' },
+      { pattern: 'rows', suggestion: 'row', confidence: 0.9, reason: 'Use singular "row"' },
+    ]);
+
+    // Google Sheets patterns
+    patterns.set('googleSheets', [
+      { pattern: 'sheets', suggestion: 'sheet', confidence: 0.95, reason: 'Use singular "sheet" not plural' },
+      { pattern: 'spreadsheets', suggestion: 'spreadsheet', confidence: 0.95, reason: 'Use singular "spreadsheet"' },
+      { pattern: 'cells', suggestion: 'cell', confidence: 0.9, reason: 'Use singular "cell"' },
+      { pattern: 'ranges', suggestion: 'range', confidence: 0.9, reason: 'Use singular "range"' },
+      { pattern: 'worksheets', suggestion: 'sheet', confidence: 0.8, reason: 'Use "sheet" for worksheet operations' },
+    ]);
+
+    // Email patterns
+    patterns.set('email', [
+      { pattern: 'emails', suggestion: 'email', confidence: 0.95, reason: 'Use singular "email" not plural' },
+      { pattern: 'messages', suggestion: 'message', confidence: 0.9, reason: 'Use "message" for email operations' },
+      { pattern: 'mails', suggestion: 'email', confidence: 0.9, reason: 'Use "email" not "mail"' },
+      { pattern: 'attachments', suggestion: 'attachment', confidence: 0.95, reason: 'Use singular "attachment"' },
+    ]);
+
+    // Generic plural/singular patterns
+    patterns.set('generic', [
+      { pattern: 'items', suggestion: 'item', confidence: 0.9, reason: 'Use singular form' },
+      { pattern: 'objects', suggestion: 'object', confidence: 0.9, reason: 'Use singular form' },
+      { pattern: 'entities', suggestion: 'entity', confidence: 0.9, reason: 'Use singular form' },
+      { pattern: 'resources', suggestion: 'resource', confidence: 0.9, reason: 'Use singular form' },
+      { pattern: 'elements', suggestion: 'element', confidence: 0.9, reason: 'Use singular form' },
+    ]);
+
+    return patterns;
+  }
+
+  /**
+   * Find similar resources for an invalid resource using pattern matching
+   * and Levenshtein distance algorithms
+   *
+   * @param nodeType - The n8n node type (e.g., 'nodes-base.googleDrive')
+   * @param invalidResource - The invalid resource provided by the user
+   * @param maxSuggestions - Maximum number of suggestions to return (default: 5)
+   * @returns Array of resource suggestions sorted by confidence
+   *
+   * @example
+   * findSimilarResources('nodes-base.googleDrive', 'files', 3)
+   * // Returns: [{ value: 'file', confidence: 0.95, reason: 'Use singular "file" not plural' }]
+   */
+  findSimilarResources(
+    nodeType: string,
+    invalidResource: string,
+    maxSuggestions: number = ResourceSimilarityService.MAX_SUGGESTIONS
+  ): ResourceSuggestion[] {
+    // Clean up expired cache entries periodically
+    if (Math.random() < 0.1) { // 10% chance to cleanup on each call
+      this.cleanupExpiredEntries();
+    }
+    // Check cache first
+    const cacheKey = `${nodeType}:${invalidResource}`;
+    if (this.suggestionCache.has(cacheKey)) {
+      return this.suggestionCache.get(cacheKey)!;
+    }
+
+    const suggestions: ResourceSuggestion[] = [];
+
+    // Get valid resources for the node
+    const validResources = this.getNodeResources(nodeType);
+
+    // Early termination for exact match - no suggestions needed
+    for (const resource of validResources) {
+      const resourceValue = this.getResourceValue(resource);
+      if (resourceValue.toLowerCase() === invalidResource.toLowerCase()) {
+        return []; // Valid resource, no suggestions needed
+      }
+    }
+
+    // Check for exact pattern matches first
+    const nodePatterns = this.getNodePatterns(nodeType);
+    for (const pattern of nodePatterns) {
+      if (pattern.pattern.toLowerCase() === invalidResource.toLowerCase()) {
+        // Check if the suggested resource actually exists with type safety
+        const exists = validResources.some(r => {
+          const resourceValue = this.getResourceValue(r);
+          return resourceValue === pattern.suggestion;
+        });
+        if (exists) {
+          suggestions.push({
+            value: pattern.suggestion,
+            confidence: pattern.confidence,
+            reason: pattern.reason
+          });
+        }
+      }
+    }
+
+    // Handle automatic plural/singular conversion
+    const singularForm = this.toSingular(invalidResource);
+    const pluralForm = this.toPlural(invalidResource);
+
+    for (const resource of validResources) {
+      const resourceValue = this.getResourceValue(resource);
+
+      // Check for plural/singular match
+      if (resourceValue === singularForm || resourceValue === pluralForm) {
+        if (!suggestions.some(s => s.value === resourceValue)) {
+          suggestions.push({
+            value: resourceValue,
+            confidence: 0.9,
+            reason: invalidResource.endsWith('s') ?
+              'Use singular form for resources' :
+              'Incorrect plural/singular form',
+            availableOperations: typeof resource === 'object' ? resource.operations : undefined
+          });
+        }
+      }
+
+      // Calculate similarity
+      const similarity = this.calculateSimilarity(invalidResource, resourceValue);
+      if (similarity >= ResourceSimilarityService.MIN_CONFIDENCE) {
+        if (!suggestions.some(s => s.value === resourceValue)) {
+          suggestions.push({
+            value: resourceValue,
+            confidence: similarity,
+            reason: this.getSimilarityReason(similarity, invalidResource, resourceValue),
+            availableOperations: typeof resource === 'object' ? resource.operations : undefined
+          });
+        }
+      }
+    }
+
+    // Sort by confidence and limit
+    suggestions.sort((a, b) => b.confidence - a.confidence);
+    const topSuggestions = suggestions.slice(0, maxSuggestions);
+
+    // Cache the result
+    this.suggestionCache.set(cacheKey, topSuggestions);
+
+    return topSuggestions;
+  }
+
+  /**
+   * Type-safe extraction of resource value from various formats
+   * @param resource - Resource object or string
+   * @returns The resource value as a string
+   */
+  private getResourceValue(resource: any): string {
+    if (typeof resource === 'string') {
+      return resource;
+    }
+    if (typeof resource === 'object' && resource !== null) {
+      return resource.value || '';
+    }
+    return '';
+  }
+
+  /**
+   * Get resources for a node with caching
+   */
+  private getNodeResources(nodeType: string): any[] {
+    // Cleanup cache periodically
+    if (Math.random() < 0.05) { // 5% chance
+      this.cleanupExpiredEntries();
+    }
+
+    const cacheKey = nodeType;
+    const cached = this.resourceCache.get(cacheKey);
+
+    if (cached && Date.now() - cached.timestamp < ResourceSimilarityService.CACHE_DURATION_MS) {
+      return cached.resources;
+    }
+
+    const nodeInfo = this.repository.getNode(nodeType);
+    if (!nodeInfo) return [];
+
+    const resources: any[] = [];
+    const resourceMap: Map<string, string[]> = new Map();
+
+    // Parse properties for resource fields
+    try {
+      const properties = nodeInfo.properties || [];
+      for (const prop of properties) {
+        if (prop.name === 'resource' && prop.options) {
+          for (const option of prop.options) {
+            resources.push({
+              value: option.value,
+              name: option.name,
+              operations: []
+            });
+            resourceMap.set(option.value, []);
+          }
+        }
+
+        // Find operations for each resource
+        if (prop.name === 'operation' && prop.displayOptions?.show?.resource) {
+          const resourceValues = Array.isArray(prop.displayOptions.show.resource)
+            ? prop.displayOptions.show.resource
+            : [prop.displayOptions.show.resource];
+
+          for (const resourceValue of resourceValues) {
+            if (resourceMap.has(resourceValue) && prop.options) {
+              const ops = prop.options.map((op: any) => op.value);
+              resourceMap.get(resourceValue)!.push(...ops);
+            }
+          }
+        }
+      }
+
+      // Update resources with their operations
+      for (const resource of resources) {
+        if (resourceMap.has(resource.value)) {
+          resource.operations = resourceMap.get(resource.value);
+        }
+      }
+
+      // If no explicit resources, check for common patterns
+      if (resources.length === 0) {
+        // Some nodes don't have explicit resource fields
+        const implicitResources = this.extractImplicitResources(properties);
+        resources.push(...implicitResources);
+      }
+    } catch (error) {
+      logger.warn(`Failed to extract resources for ${nodeType}:`, error);
+    }
+
+    // Cache and return
+    this.resourceCache.set(cacheKey, { resources, timestamp: Date.now() });
+    return resources;
+  }
+
+  /**
+   * Extract implicit resources from node properties
+   */
+  private extractImplicitResources(properties: any[]): any[] {
+    const resources: any[] = [];
+
+    // Look for properties that suggest resources
+    for (const prop of properties) {
+      if (prop.name === 'operation' && prop.options) {
+        // If there's no explicit resource field, operations might imply resources
+        const resourceFromOps = this.inferResourceFromOperations(prop.options);
+        if (resourceFromOps) {
+          resources.push({
+            value: resourceFromOps,
+            name: resourceFromOps.charAt(0).toUpperCase() + resourceFromOps.slice(1),
+            operations: prop.options.map((op: any) => op.value)
+          });
+        }
+      }
+    }
+
+    return resources;
+  }
+
+  /**
+   * Infer resource type from operations
+   */
+  private inferResourceFromOperations(operations: any[]): string | null {
+    // Common patterns in operation names that suggest resources
+    const patterns = [
+      { keywords: ['file', 'upload', 'download'], resource: 'file' },
+      { keywords: ['folder', 'directory'], resource: 'folder' },
+      { keywords: ['message', 'send', 'reply'], resource: 'message' },
+      { keywords: ['channel', 'broadcast'], resource: 'channel' },
+      { keywords: ['user', 'member'], resource: 'user' },
+      { keywords: ['table', 'row', 'column'], resource: 'table' },
+      { keywords: ['document', 'doc'], resource: 'document' },
+    ];
+
+    for (const pattern of patterns) {
+      for (const op of operations) {
+        const opName = (op.value || op).toLowerCase();
+        if (pattern.keywords.some(keyword => opName.includes(keyword))) {
+          return pattern.resource;
+        }
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Get patterns for a specific node type
+   */
+  private getNodePatterns(nodeType: string): ResourcePattern[] {
+    const patterns: ResourcePattern[] = [];
+
+    // Add node-specific patterns
+    if (nodeType.includes('googleDrive')) {
+      patterns.push(...(this.commonPatterns.get('googleDrive') || []));
+    } else if (nodeType.includes('slack')) {
+      patterns.push(...(this.commonPatterns.get('slack') || []));
+    } else if (nodeType.includes('postgres') || nodeType.includes('mysql') || nodeType.includes('mongodb')) {
+      patterns.push(...(this.commonPatterns.get('database') || []));
+    } else if (nodeType.includes('googleSheets')) {
+      patterns.push(...(this.commonPatterns.get('googleSheets') || []));
+    } else if (nodeType.includes('gmail') || nodeType.includes('email')) {
+      patterns.push(...(this.commonPatterns.get('email') || []));
+    }
+
+    // Always add generic patterns
+    patterns.push(...(this.commonPatterns.get('generic') || []));
+
+    return patterns;
+  }
+
+  /**
+   * Convert to singular form (simple heuristic)
+   */
+  private toSingular(word: string): string {
+    if (word.endsWith('ies')) {
+      return word.slice(0, -3) + 'y';
+    } else if (word.endsWith('es')) {
+      return word.slice(0, -2);
+    } else if (word.endsWith('s') && !word.endsWith('ss')) {
+      return word.slice(0, -1);
+    }
+    return word;
+  }
+
+  /**
+   * Convert to plural form (simple heuristic)
+   */
+  private toPlural(word: string): string {
+    if (word.endsWith('y') && !['ay', 'ey', 'iy', 'oy', 'uy'].includes(word.slice(-2))) {
+      return word.slice(0, -1) + 'ies';
+    } else if (word.endsWith('s') || word.endsWith('x') || word.endsWith('z') ||
+               word.endsWith('ch') || word.endsWith('sh')) {
+      return word + 'es';
+    } else {
+      return word + 's';
+    }
+  }
+
+  /**
+   * Calculate similarity between two strings using Levenshtein distance
+   */
+  private calculateSimilarity(str1: string, str2: string): number {
+    const s1 = str1.toLowerCase();
+    const s2 = str2.toLowerCase();
+
+    // Exact match
+    if (s1 === s2) return 1.0;
+
+    // One is substring of the other
+    if (s1.includes(s2) || s2.includes(s1)) {
+      const ratio = Math.min(s1.length, s2.length) / Math.max(s1.length, s2.length);
+      return Math.max(ResourceSimilarityService.CONFIDENCE_THRESHOLDS.MIN_SUBSTRING, ratio);
+    }
+
+    // Calculate Levenshtein distance
+    const distance = this.levenshteinDistance(s1, s2);
+    const maxLength = Math.max(s1.length, s2.length);
+
+    // Convert distance to similarity
+    let similarity = 1 - (distance / maxLength);
+
+    // Boost confidence for single character typos and transpositions in short words
+    if (distance === 1 && maxLength <= 5) {
+      similarity = Math.max(similarity, 0.75);
+    } else if (distance === 2 && maxLength <= 5) {
+      // Boost for transpositions (e.g., "flie" -> "file")
+      similarity = Math.max(similarity, 0.72);
+    }
+
+    return similarity;
+  }
+
+  /**
+   * Calculate Levenshtein distance between two strings
+   */
+  private levenshteinDistance(str1: string, str2: string): number {
+    const m = str1.length;
+    const n = str2.length;
+    const dp: number[][] = Array(m + 1).fill(null).map(() => Array(n + 1).fill(0));
+
+    for (let i = 0; i <= m; i++) dp[i][0] = i;
+    for (let j = 0; j <= n; j++) dp[0][j] = j;
+
+    for (let i = 1; i <= m; i++) {
+      for (let j = 1; j <= n; j++) {
+        if (str1[i - 1] === str2[j - 1]) {
+          dp[i][j] = dp[i - 1][j - 1];
+        } else {
+          dp[i][j] = Math.min(
+            dp[i - 1][j] + 1,    // deletion
+            dp[i][j - 1] + 1,    // insertion
+            dp[i - 1][j - 1] + 1 // substitution
+          );
+        }
+      }
+    }
+
+    return dp[m][n];
+  }
+
+  /**
+   * Generate a human-readable reason for the similarity
+   * @param confidence - Similarity confidence score
+   * @param invalid - The invalid resource string
+   * @param valid - The valid resource string
+   * @returns Human-readable explanation of the similarity
+   */
+  private getSimilarityReason(confidence: number, invalid: string, valid: string): string {
+    const { VERY_HIGH, HIGH, MEDIUM } = ResourceSimilarityService.CONFIDENCE_THRESHOLDS;
+
+    if (confidence >= VERY_HIGH) {
+      return 'Almost exact match - likely a typo';
+    } else if (confidence >= HIGH) {
+      return 'Very similar - common variation';
+    } else if (confidence >= MEDIUM) {
+      return 'Similar resource name';
+    } else if (invalid.includes(valid) || valid.includes(invalid)) {
+      return 'Partial match';
+    } else {
+      return 'Possibly related resource';
+    }
+  }
+
+  /**
+   * Clear caches
+   */
+  clearCache(): void {
+    this.resourceCache.clear();
+    this.suggestionCache.clear();
+  }
+}

src/services/task-templates.ts

@@ -1,6 +1,14 @@
 /**
  * Task Templates Service
- * 
+ *
+ * @deprecated This module is deprecated as of v2.15.0 and will be removed in v2.16.0.
+ * The get_node_for_task tool has been removed in favor of template-based configuration examples.
+ *
+ * Migration:
+ * - Use `search_nodes({query: "webhook", includeExamples: true})` to find nodes with real template configs
+ * - Use `get_node_essentials({nodeType: "nodes-base.webhook", includeExamples: true})` for top 3 examples
+ * - New approach provides 2,646 real templates vs 31 hardcoded tasks
+ *
  * Provides pre-configured node settings for common tasks.
  * This helps AI agents quickly configure nodes for specific use cases.
  */