feat: Add MCP server icon support (SEP-973) v2.20.0 (#333)

* feat: Add MCP server icon support (SEP-973) v2.20.0

Implements custom server icons for MCP clients according to the MCP
specification SEP-973. Icons enable better visual identification of
the n8n-mcp server in MCP client interfaces.

Features:
- Added 3 icon sizes: 192x192, 128x128, 48x48 (PNG format)
- Icons served from https://www.n8n-mcp.com/logo*.png
- Added websiteUrl field pointing to https://n8n-mcp.com
- Server version now uses package.json (PROJECT_VERSION) instead of hardcoded '1.0.0'

Changes:
- Upgraded @modelcontextprotocol/sdk from ^1.13.2 to ^1.20.1
- Updated src/mcp/server.ts with icon configuration
- Bumped version to 2.20.0
- Updated CHANGELOG.md with release notes

Testing:
- All icon URLs verified accessible (HTTP 200, CORS enabled)
- Build passes, type checking passes
- No breaking changes, fully backward compatible

Icons won't display in Claude Desktop yet (pending upstream UI support),
but will appear automatically when support is added. Other MCP clients
may already support icon display.

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

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

* docs: Fix icon URLs in CHANGELOG to reflect actual implementation

The CHANGELOG incorrectly documented icon URLs as
https://api.n8n-mcp.com/public/logo-*.png when the actual
implementation uses https://www.n8n-mcp.com/logo*.png

This updates the documentation to match the code.

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

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

---------

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

.env.example

@@ -69,6 +69,40 @@ 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
 # =========================

.github/workflows/release.yml

@@ -79,6 +79,38 @@ jobs:
             echo "ℹ️ No version change detected"
           fi
 
+      - name: Validate version against npm registry
+        if: steps.check.outputs.changed == 'true'
+        run: |
+          CURRENT_VERSION="${{ steps.check.outputs.version }}"
+
+          # Get latest version from npm (handle package not found)
+          NPM_VERSION=$(npm view n8n-mcp version 2>/dev/null || echo "0.0.0")
+
+          echo "Current version: $CURRENT_VERSION"
+          echo "NPM registry version: $NPM_VERSION"
+
+          # Check if version already exists in npm
+          if [ "$CURRENT_VERSION" = "$NPM_VERSION" ]; then
+            echo "❌ Error: Version $CURRENT_VERSION already published to npm"
+            echo "Please bump the version in package.json before releasing"
+            exit 1
+          fi
+
+          # Simple semver comparison (assumes format: major.minor.patch)
+          # Compare if current version is greater than npm version
+          if [ "$NPM_VERSION" != "0.0.0" ]; then
+            # Sort versions and check if current is not the highest
+            HIGHEST=$(printf '%s\n%s' "$NPM_VERSION" "$CURRENT_VERSION" | sort -V | tail -n1)
+            if [ "$HIGHEST" != "$CURRENT_VERSION" ]; then
+              echo "❌ Error: Version $CURRENT_VERSION is not greater than npm version $NPM_VERSION"
+              echo "Please use a higher version number"
+              exit 1
+            fi
+          fi
+
+          echo "✅ Version $CURRENT_VERSION is valid (higher than npm version $NPM_VERSION)"
+
   extract-changelog:
     name: Extract Changelog
     runs-on: ubuntu-latest
@@ -206,8 +238,8 @@ jobs:
           echo "id=$RELEASE_ID" >> $GITHUB_OUTPUT
           echo "upload_url=https://uploads.github.com/repos/${{ github.repository }}/releases/$RELEASE_ID/assets{?name,label}" >> $GITHUB_OUTPUT
 
-  build-and-test:
-    name: Build and Test
+  build-and-verify:
+    name: Build and Verify
     runs-on: ubuntu-latest
     needs: detect-version-change
     if: needs.detect-version-change.outputs.version-changed == 'true'
@@ -226,22 +258,28 @@ jobs:
       
       - name: Build project
         run: npm run build
-      
-      - name: Rebuild database
-        run: npm run rebuild
-      
-      - name: Run tests
-        run: npm test
-        env:
-          CI: true
-      
+
+      # Database is already built and committed during development
+      # Rebuilding here causes segfault due to memory pressure (exit code 139)
+      - name: Verify database exists
+        run: |
+          if [ ! -f "data/nodes.db" ]; then
+            echo "❌ Error: data/nodes.db not found"
+            echo "Please run 'npm run rebuild' locally and commit the database"
+            exit 1
+          fi
+          echo "✅ Database exists ($(du -h data/nodes.db | cut -f1))"
+
+      # Skip tests - they already passed in PR before merge
+      # Running them again on the same commit adds no safety, only time (~6-7 min)
+
       - name: Run type checking
         run: npm run typecheck
 
   publish-npm:
     name: Publish to NPM
     runs-on: ubuntu-latest
-    needs: [detect-version-change, build-and-test, create-release]
+    needs: [detect-version-change, build-and-verify, create-release]
     if: needs.detect-version-change.outputs.version-changed == 'true'
     steps:
       - name: Checkout repository
@@ -259,10 +297,16 @@ jobs:
       
       - name: Build project
         run: npm run build
-      
-      - name: Rebuild database
-        run: npm run rebuild
-      
+
+      # Database is already built and committed during development
+      - name: Verify database exists
+        run: |
+          if [ ! -f "data/nodes.db" ]; then
+            echo "❌ Error: data/nodes.db not found"
+            exit 1
+          fi
+          echo "✅ Database exists ($(du -h data/nodes.db | cut -f1))"
+
       - name: Sync runtime version
         run: npm run sync:runtime-version
       
@@ -290,6 +334,15 @@ jobs:
           const pkg = require('./package.json');
           pkg.name = 'n8n-mcp';
           pkg.description = 'Integration between n8n workflow automation and Model Context Protocol (MCP)';
+          pkg.main = 'dist/index.js';
+          pkg.types = 'dist/index.d.ts';
+          pkg.exports = {
+            '.': {
+              types: './dist/index.d.ts',
+              require: './dist/index.js',
+              import: './dist/index.js'
+            }
+          };
           pkg.bin = { 'n8n-mcp': './dist/mcp/index.js' };
           pkg.repository = { type: 'git', url: 'git+https://github.com/czlonkowski/n8n-mcp.git' };
           pkg.keywords = ['n8n', 'mcp', 'model-context-protocol', 'ai', 'workflow', 'automation'];
@@ -324,7 +377,7 @@ jobs:
   build-docker:
     name: Build and Push Docker Images
     runs-on: ubuntu-latest
-    needs: [detect-version-change, build-and-test]
+    needs: [detect-version-change, build-and-verify]
     if: needs.detect-version-change.outputs.version-changed == 'true'
     permissions:
       contents: read

.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

README.md

@@ -4,8 +4,8 @@
 [![GitHub stars](https://img.shields.io/github/stars/czlonkowski/n8n-mcp?style=social)](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-2883%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)
+[![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.115.2-orange.svg)](https://github.com/n8n-io/n8n)
 [![Docker](https://img.shields.io/badge/docker-ghcr.io%2Fczlonkowski%2Fn8n--mcp-green.svg)](https://github.com/czlonkowski/n8n-mcp/pkgs/container/n8n-mcp)
 [![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/n8n-mcp?referralCode=n8n-mcp)
 
@@ -198,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).
@@ -399,7 +425,7 @@ Complete guide for integrating n8n-MCP with Codex.
 
 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 Principles
@@ -485,7 +511,7 @@ ALWAYS explicitly configure ALL parameters that control node behavior.
 
 ### ⚠️ Never Trust Defaults
 Default values cause runtime failures. Example:
-```javascript
+```json
 // ❌ FAILS at runtime
 {resource: "message", operation: "post", text: "Hello"}
 
@@ -543,7 +569,7 @@ Changes validated successfully.
 Use `n8n_update_partial_workflow` with multiple operations in a single call:
 
 ✅ GOOD - Batch multiple operations:
-```javascript
+```json
 n8n_update_partial_workflow({
   id: "wf-123",
   operations: [
@@ -555,7 +581,7 @@ n8n_update_partial_workflow({
 ```
 
 ❌ BAD - Separate calls:
-```javascript
+```json
 n8n_update_partial_workflow({id: "wf-123", operations: [{...}]})
 n8n_update_partial_workflow({id: "wf-123", operations: [{...}]})
 ```
@@ -564,7 +590,7 @@ n8n_update_partial_workflow({id: "wf-123", operations: [{...}]})
 
 ### Template-First Approach
 
-```javascript
+```
 // STEP 1: Template Discovery (parallel execution)
 [Silent execution]
 search_templates_by_metadata({
@@ -587,7 +613,7 @@ Validation: ✅ All checks passed"
 
 ### Building from Scratch (if no template)
 
-```javascript
+```
 // STEP 1: Discovery (parallel execution)
 [Silent execution]
 search_nodes({query: 'slack', includeExamples: true})
@@ -618,7 +644,7 @@ Validation: ✅ Passed"
 
 ### Batch Updates
 
-```javascript
+```json
 // ONE call with multiple operations
 n8n_update_partial_workflow({
   id: "wf-123",
@@ -652,7 +678,33 @@ n8n_update_partial_workflow({
 - **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)
-```
+
+### Most Popular n8n Nodes (for get_node_essentials):
+
+1. **n8n-nodes-base.code** - JavaScript/Python scripting
+2. **n8n-nodes-base.httpRequest** - HTTP API calls
+3. **n8n-nodes-base.webhook** - Event-driven triggers
+4. **n8n-nodes-base.set** - Data transformation
+5. **n8n-nodes-base.if** - Conditional routing
+6. **n8n-nodes-base.manualTrigger** - Manual workflow execution
+7. **n8n-nodes-base.respondToWebhook** - Webhook responses
+8. **n8n-nodes-base.scheduleTrigger** - Time-based triggers
+9. **@n8n/n8n-nodes-langchain.agent** - AI agents
+10. **n8n-nodes-base.googleSheets** - Spreadsheet integration
+11. **n8n-nodes-base.merge** - Data merging
+12. **n8n-nodes-base.switch** - Multi-branch routing
+13. **n8n-nodes-base.telegram** - Telegram bot integration
+14. **@n8n/n8n-nodes-langchain.lmChatOpenAi** - OpenAI chat models
+15. **n8n-nodes-base.splitInBatches** - Batch processing
+16. **n8n-nodes-base.openAi** - OpenAI legacy node
+17. **n8n-nodes-base.gmail** - Email automation
+18. **n8n-nodes-base.function** - Custom functions
+19. **n8n-nodes-base.stickyNote** - Workflow documentation
+20. **n8n-nodes-base.executeWorkflowTrigger** - Sub-workflow calls
+
+**Note:** LangChain nodes use the `@n8n/n8n-nodes-langchain.` prefix, core nodes use `n8n-nodes-base.`
+
+````
 
 Save these instructions in your Claude Project for optimal n8n workflow assistance with intelligent template discovery.
 
@@ -673,6 +725,11 @@ This tool was created to benefit everyone in the n8n community without friction.
 - **📖 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
+- **🤖 AI Workflow Validation**: Comprehensive validation for AI Agent workflows (NEW in v2.17.0!)
+  - Missing language model detection
+  - AI tool connection validation
+  - Streaming mode constraints
+  - Memory and output parser checks
 - **🔗 Dependency Analysis**: Understand property relationships and conditions
 - **🎯 Template Discovery**: 2,500+ workflow templates with smart filtering
 - **⚡ Fast Response**: Average query time ~12ms with optimized SQLite
@@ -714,12 +771,18 @@ Once connected, Claude can use these powerful tools:
 - **`get_template`** - Get complete workflow JSON for import
 - **`get_templates_for_task`** - Curated templates for common automation tasks
 
-### Advanced Tools
-- **`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
+### Validation Tools
+- **`validate_workflow`** - Complete workflow validation including **AI Agent validation** (NEW in v2.17.0!)
+  - Detects missing language model connections
+  - Validates AI tool connections (no false warnings)
+  - Enforces streaming mode constraints
+  - Checks memory and output parser configurations
 - **`validate_workflow_connections`** - Check workflow structure and AI tool connections
 - **`validate_workflow_expressions`** - Validate n8n expressions including $fromAI()
+- **`validate_node_operation`** - Validate node configurations (operation-aware, profiles support)
+- **`validate_node_minimal`** - Quick validation for just required fields
+
+### Advanced Tools
 - **`get_property_dependencies`** - Analyze property visibility conditions
 - **`get_node_documentation`** - Get parsed documentation from n8n-docs
 - **`get_database_statistics`** - View database metrics and coverage
@@ -938,22 +1001,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).
 

docs/CHANGELOG.md

@@ -5,6 +5,56 @@ 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] - 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

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/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/LIBRARY_USAGE.md

@@ -0,0 +1,724 @@
+# Library Usage Guide - Multi-Tenant / Hosted Deployments
+
+This guide covers using n8n-mcp as a library dependency for building multi-tenant hosted services.
+
+## Overview
+
+n8n-mcp can be used as a Node.js library to build multi-tenant backends that provide MCP services to multiple users or instances. The package exports all necessary components for integration into your existing services.
+
+## Installation
+
+```bash
+npm install n8n-mcp
+```
+
+## Core Concepts
+
+### Library Mode vs CLI Mode
+
+- **CLI Mode** (default): Single-player usage via `npx n8n-mcp` or Docker
+- **Library Mode**: Multi-tenant usage by importing and using the `N8NMCPEngine` class
+
+### Instance Context
+
+The `InstanceContext` type allows you to pass per-request configuration to the MCP engine:
+
+```typescript
+interface InstanceContext {
+  // Instance-specific n8n API configuration
+  n8nApiUrl?: string;
+  n8nApiKey?: string;
+  n8nApiTimeout?: number;
+  n8nApiMaxRetries?: number;
+
+  // Instance identification
+  instanceId?: string;
+  sessionId?: string;
+
+  // Extensible metadata
+  metadata?: Record<string, any>;
+}
+```
+
+## Basic Example
+
+```typescript
+import express from 'express';
+import { N8NMCPEngine } from 'n8n-mcp';
+
+const app = express();
+const mcpEngine = new N8NMCPEngine({
+  sessionTimeout: 3600000, // 1 hour
+  logLevel: 'info'
+});
+
+// Handle MCP requests with per-user context
+app.post('/mcp', async (req, res) => {
+  const instanceContext = {
+    n8nApiUrl: req.user.n8nUrl,
+    n8nApiKey: req.user.n8nApiKey,
+    instanceId: req.user.id
+  };
+
+  await mcpEngine.processRequest(req, res, instanceContext);
+});
+
+app.listen(3000);
+```
+
+## Multi-Tenant Backend Example
+
+This example shows a complete multi-tenant implementation with user authentication and instance management:
+
+```typescript
+import express from 'express';
+import { N8NMCPEngine, InstanceContext, validateInstanceContext } from 'n8n-mcp';
+
+const app = express();
+const mcpEngine = new N8NMCPEngine({
+  sessionTimeout: 3600000, // 1 hour
+  logLevel: 'info'
+});
+
+// Start MCP engine
+await mcpEngine.start();
+
+// Authentication middleware
+const authenticate = async (req, res, next) => {
+  const token = req.headers.authorization?.replace('Bearer ', '');
+  if (!token) {
+    return res.status(401).json({ error: 'Unauthorized' });
+  }
+
+  // Verify token and attach user to request
+  req.user = await getUserFromToken(token);
+  next();
+};
+
+// Get instance configuration from database
+const getInstanceConfig = async (instanceId: string, userId: string) => {
+  // Your database logic here
+  const instance = await db.instances.findOne({
+    where: { id: instanceId, userId }
+  });
+
+  if (!instance) {
+    throw new Error('Instance not found');
+  }
+
+  return {
+    n8nApiUrl: instance.n8nUrl,
+    n8nApiKey: await decryptApiKey(instance.encryptedApiKey),
+    instanceId: instance.id
+  };
+};
+
+// MCP endpoint with per-instance context
+app.post('/api/instances/:instanceId/mcp', authenticate, async (req, res) => {
+  try {
+    // Get instance configuration
+    const instance = await getInstanceConfig(req.params.instanceId, req.user.id);
+
+    // Create instance context
+    const context: InstanceContext = {
+      n8nApiUrl: instance.n8nApiUrl,
+      n8nApiKey: instance.n8nApiKey,
+      instanceId: instance.instanceId,
+      metadata: {
+        userId: req.user.id,
+        userAgent: req.headers['user-agent'],
+        ip: req.ip
+      }
+    };
+
+    // Validate context before processing
+    const validation = validateInstanceContext(context);
+    if (!validation.valid) {
+      return res.status(400).json({
+        error: 'Invalid instance configuration',
+        details: validation.errors
+      });
+    }
+
+    // Process request with instance context
+    await mcpEngine.processRequest(req, res, context);
+
+  } catch (error) {
+    console.error('MCP request error:', error);
+    res.status(500).json({ error: 'Internal server error' });
+  }
+});
+
+// Health endpoint
+app.get('/health', async (req, res) => {
+  const health = await mcpEngine.healthCheck();
+  res.status(health.status === 'healthy' ? 200 : 503).json(health);
+});
+
+// Graceful shutdown
+process.on('SIGTERM', async () => {
+  await mcpEngine.shutdown();
+  process.exit(0);
+});
+
+app.listen(3000);
+```
+
+## API Reference
+
+### N8NMCPEngine
+
+#### Constructor
+
+```typescript
+new N8NMCPEngine(options?: {
+  sessionTimeout?: number;  // Session TTL in ms (default: 1800000 = 30min)
+  logLevel?: 'error' | 'warn' | 'info' | 'debug';  // Default: 'info'
+})
+```
+
+#### Methods
+
+##### `async processRequest(req, res, context?)`
+
+Process a single MCP request with optional instance context.
+
+**Parameters:**
+- `req`: Express request object
+- `res`: Express response object
+- `context` (optional): InstanceContext with per-instance configuration
+
+**Example:**
+```typescript
+const context: InstanceContext = {
+  n8nApiUrl: 'https://instance1.n8n.cloud',
+  n8nApiKey: 'instance1-key',
+  instanceId: 'tenant-123'
+};
+
+await engine.processRequest(req, res, context);
+```
+
+##### `async healthCheck()`
+
+Get engine health status for monitoring.
+
+**Returns:** `EngineHealth`
+```typescript
+{
+  status: 'healthy' | 'unhealthy';
+  uptime: number;  // seconds
+  sessionActive: boolean;
+  memoryUsage: {
+    used: number;
+    total: number;
+    unit: string;
+  };
+  version: string;
+}
+```
+
+**Example:**
+```typescript
+app.get('/health', async (req, res) => {
+  const health = await engine.healthCheck();
+  res.status(health.status === 'healthy' ? 200 : 503).json(health);
+});
+```
+
+##### `getSessionInfo()`
+
+Get current session information for debugging.
+
+**Returns:**
+```typescript
+{
+  active: boolean;
+  sessionId?: string;
+  age?: number;  // milliseconds
+  sessions?: {
+    total: number;
+    active: number;
+    expired: number;
+    max: number;
+    sessionIds: string[];
+  };
+}
+```
+
+##### `async start()`
+
+Start the engine (for standalone mode). Not needed when using `processRequest()` directly.
+
+##### `async shutdown()`
+
+Graceful shutdown for service lifecycle management.
+
+**Example:**
+```typescript
+process.on('SIGTERM', async () => {
+  await engine.shutdown();
+  process.exit(0);
+});
+```
+
+### Types
+
+#### InstanceContext
+
+Configuration for a specific user instance:
+
+```typescript
+interface InstanceContext {
+  n8nApiUrl?: string;
+  n8nApiKey?: string;
+  n8nApiTimeout?: number;
+  n8nApiMaxRetries?: number;
+  instanceId?: string;
+  sessionId?: string;
+  metadata?: Record<string, any>;
+}
+```
+
+#### Validation Functions
+
+##### `validateInstanceContext(context: InstanceContext)`
+
+Validate and sanitize instance context.
+
+**Returns:**
+```typescript
+{
+  valid: boolean;
+  errors?: string[];
+}
+```
+
+**Example:**
+```typescript
+import { validateInstanceContext } from 'n8n-mcp';
+
+const validation = validateInstanceContext(context);
+if (!validation.valid) {
+  console.error('Invalid context:', validation.errors);
+}
+```
+
+##### `isInstanceContext(obj: any)`
+
+Type guard to check if an object is a valid InstanceContext.
+
+**Example:**
+```typescript
+import { isInstanceContext } from 'n8n-mcp';
+
+if (isInstanceContext(req.body.context)) {
+  // TypeScript knows this is InstanceContext
+  await engine.processRequest(req, res, req.body.context);
+}
+```
+
+## Session Management
+
+### Session Strategies
+
+The MCP engine supports flexible session ID formats:
+
+- **UUIDv4**: Internal n8n-mcp format (default)
+- **Instance-prefixed**: `instance-{userId}-{hash}-{uuid}` for multi-tenant isolation
+- **Custom formats**: Any non-empty string for mcp-remote and other proxies
+
+Session validation happens via transport lookup, not format validation. This ensures compatibility with all MCP clients.
+
+### Multi-Tenant Configuration
+
+Set these environment variables for multi-tenant mode:
+
+```bash
+# Enable multi-tenant mode
+ENABLE_MULTI_TENANT=true
+
+# Session strategy: "instance" (default) or "shared"
+MULTI_TENANT_SESSION_STRATEGY=instance
+```
+
+**Session Strategies:**
+
+- **instance** (recommended): Each tenant gets isolated sessions
+  - Session ID: `instance-{instanceId}-{configHash}-{uuid}`
+  - Better isolation and security
+  - Easier debugging per tenant
+
+- **shared**: Multiple tenants share sessions with context switching
+  - More efficient for high tenant count
+  - Requires careful context management
+
+## Security Considerations
+
+### API Key Management
+
+Always encrypt API keys server-side:
+
+```typescript
+import { createCipheriv, createDecipheriv } from 'crypto';
+
+// Encrypt before storing
+const encryptApiKey = (apiKey: string) => {
+  const cipher = createCipheriv('aes-256-gcm', encryptionKey, iv);
+  return cipher.update(apiKey, 'utf8', 'hex') + cipher.final('hex');
+};
+
+// Decrypt before using
+const decryptApiKey = (encrypted: string) => {
+  const decipher = createDecipheriv('aes-256-gcm', encryptionKey, iv);
+  return decipher.update(encrypted, 'hex', 'utf8') + decipher.final('utf8');
+};
+
+// Use decrypted key in context
+const context: InstanceContext = {
+  n8nApiKey: await decryptApiKey(instance.encryptedApiKey),
+  // ...
+};
+```
+
+### Input Validation
+
+Always validate instance context before processing:
+
+```typescript
+import { validateInstanceContext } from 'n8n-mcp';
+
+const validation = validateInstanceContext(context);
+if (!validation.valid) {
+  throw new Error(`Invalid context: ${validation.errors?.join(', ')}`);
+}
+```
+
+### Rate Limiting
+
+Implement rate limiting per tenant:
+
+```typescript
+import rateLimit from 'express-rate-limit';
+
+const limiter = rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 100, // limit each IP to 100 requests per windowMs
+  keyGenerator: (req) => req.user?.id || req.ip
+});
+
+app.post('/api/instances/:instanceId/mcp', authenticate, limiter, async (req, res) => {
+  // ...
+});
+```
+
+## Error Handling
+
+Always wrap MCP requests in try-catch blocks:
+
+```typescript
+app.post('/api/instances/:instanceId/mcp', authenticate, async (req, res) => {
+  try {
+    const context = await getInstanceConfig(req.params.instanceId, req.user.id);
+    await mcpEngine.processRequest(req, res, context);
+  } catch (error) {
+    console.error('MCP error:', error);
+
+    // Don't leak internal errors to clients
+    if (error.message.includes('not found')) {
+      return res.status(404).json({ error: 'Instance not found' });
+    }
+
+    res.status(500).json({ error: 'Internal server error' });
+  }
+});
+```
+
+## Monitoring
+
+### Health Checks
+
+Set up periodic health checks:
+
+```typescript
+setInterval(async () => {
+  const health = await mcpEngine.healthCheck();
+
+  if (health.status === 'unhealthy') {
+    console.error('MCP engine unhealthy:', health);
+    // Alert your monitoring system
+  }
+
+  // Log metrics
+  console.log('MCP engine metrics:', {
+    uptime: health.uptime,
+    memory: health.memoryUsage,
+    sessionActive: health.sessionActive
+  });
+}, 60000); // Every minute
+```
+
+### Session Monitoring
+
+Track active sessions:
+
+```typescript
+app.get('/admin/sessions', authenticate, async (req, res) => {
+  if (!req.user.isAdmin) {
+    return res.status(403).json({ error: 'Forbidden' });
+  }
+
+  const sessionInfo = mcpEngine.getSessionInfo();
+  res.json(sessionInfo);
+});
+```
+
+## Testing
+
+### Unit Testing
+
+```typescript
+import { N8NMCPEngine, InstanceContext } from 'n8n-mcp';
+
+describe('MCP Engine', () => {
+  let engine: N8NMCPEngine;
+
+  beforeEach(() => {
+    engine = new N8NMCPEngine({ logLevel: 'error' });
+  });
+
+  afterEach(async () => {
+    await engine.shutdown();
+  });
+
+  it('should process request with context', async () => {
+    const context: InstanceContext = {
+      n8nApiUrl: 'https://test.n8n.io',
+      n8nApiKey: 'test-key',
+      instanceId: 'test-instance'
+    };
+
+    const mockReq = createMockRequest();
+    const mockRes = createMockResponse();
+
+    await engine.processRequest(mockReq, mockRes, context);
+
+    expect(mockRes.status).toBe(200);
+  });
+});
+```
+
+### Integration Testing
+
+```typescript
+import request from 'supertest';
+import { createApp } from './app';
+
+describe('Multi-tenant MCP API', () => {
+  let app;
+  let authToken;
+
+  beforeAll(async () => {
+    app = await createApp();
+    authToken = await getTestAuthToken();
+  });
+
+  it('should handle MCP request for instance', async () => {
+    const response = await request(app)
+      .post('/api/instances/test-instance/mcp')
+      .set('Authorization', `Bearer ${authToken}`)
+      .send({
+        jsonrpc: '2.0',
+        method: 'initialize',
+        params: {
+          protocolVersion: '2024-11-05',
+          capabilities: {}
+        },
+        id: 1
+      });
+
+    expect(response.status).toBe(200);
+    expect(response.body.result).toBeDefined();
+  });
+});
+```
+
+## Deployment Considerations
+
+### Environment Variables
+
+```bash
+# Required for multi-tenant mode
+ENABLE_MULTI_TENANT=true
+MULTI_TENANT_SESSION_STRATEGY=instance
+
+# Optional: Logging
+LOG_LEVEL=info
+DISABLE_CONSOLE_OUTPUT=false
+
+# Optional: Session configuration
+SESSION_TIMEOUT=1800000  # 30 minutes in milliseconds
+MAX_SESSIONS=100
+
+# Optional: Performance
+NODE_ENV=production
+```
+
+### Docker Deployment
+
+```dockerfile
+FROM node:20-alpine
+
+WORKDIR /app
+
+COPY package*.json ./
+RUN npm ci --only=production
+
+COPY . .
+
+ENV NODE_ENV=production
+ENV ENABLE_MULTI_TENANT=true
+ENV LOG_LEVEL=info
+
+EXPOSE 3000
+
+CMD ["node", "dist/server.js"]
+```
+
+### Kubernetes Deployment
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: n8n-mcp-backend
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: n8n-mcp-backend
+  template:
+    metadata:
+      labels:
+        app: n8n-mcp-backend
+    spec:
+      containers:
+      - name: backend
+        image: your-registry/n8n-mcp-backend:latest
+        ports:
+        - containerPort: 3000
+        env:
+        - name: ENABLE_MULTI_TENANT
+          value: "true"
+        - name: LOG_LEVEL
+          value: "info"
+        resources:
+          requests:
+            memory: "256Mi"
+            cpu: "250m"
+          limits:
+            memory: "512Mi"
+            cpu: "500m"
+        livenessProbe:
+          httpGet:
+            path: /health
+            port: 3000
+          initialDelaySeconds: 10
+          periodSeconds: 30
+        readinessProbe:
+          httpGet:
+            path: /health
+            port: 3000
+          initialDelaySeconds: 5
+          periodSeconds: 10
+```
+
+## Examples
+
+### Complete Multi-Tenant SaaS Example
+
+For a complete implementation example, see:
+- [n8n-mcp-backend](https://github.com/czlonkowski/n8n-mcp-backend) - Full hosted service implementation
+
+### Migration from Single-Player
+
+If you're migrating from single-player (CLI/Docker) to multi-tenant:
+
+1. **Keep backward compatibility** - Use environment fallback:
+```typescript
+const context: InstanceContext = {
+  n8nApiUrl: instanceUrl || process.env.N8N_API_URL,
+  n8nApiKey: instanceKey || process.env.N8N_API_KEY,
+  instanceId: instanceId || 'default'
+};
+```
+
+2. **Gradual rollout** - Start with a feature flag:
+```typescript
+const isMultiTenant = process.env.ENABLE_MULTI_TENANT === 'true';
+
+if (isMultiTenant) {
+  const context = await getInstanceConfig(req.params.instanceId);
+  await engine.processRequest(req, res, context);
+} else {
+  // Legacy single-player mode
+  await engine.processRequest(req, res);
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### Module Resolution Errors
+
+If you see `Cannot find module 'n8n-mcp'`:
+
+```bash
+# Clear node_modules and reinstall
+rm -rf node_modules package-lock.json
+npm install
+
+# Verify package has types field
+npm info n8n-mcp
+
+# Check TypeScript can resolve it
+npx tsc --noEmit
+```
+
+#### Session ID Validation Errors
+
+If you see `Invalid session ID format` errors:
+
+- Ensure you're using n8n-mcp v2.18.9 or later
+- Session IDs can be any non-empty string
+- No need to generate UUIDs - use your own format
+
+#### Memory Leaks
+
+If memory usage grows over time:
+
+```typescript
+// Ensure proper cleanup
+process.on('SIGTERM', async () => {
+  await engine.shutdown();
+  process.exit(0);
+});
+
+// Monitor session count
+const sessionInfo = engine.getSessionInfo();
+console.log('Active sessions:', sessionInfo.sessions?.active);
+```
+
+## Further Reading
+
+- [MCP Protocol Specification](https://modelcontextprotocol.io/docs)
+- [n8n API Documentation](https://docs.n8n.io/api/)
+- [Express.js Guide](https://expressjs.com/en/guide/routing.html)
+- [n8n-mcp Main README](../README.md)
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/czlonkowski/n8n-mcp/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/czlonkowski/n8n-mcp/discussions)
+- **Security**: For security issues, see [SECURITY.md](../SECURITY.md)

docs/PR-104-test-improvements-summary.md

@@ -1,62 +0,0 @@
-# PR #104 Test Suite Improvements Summary
-
-## Overview
-Based on comprehensive review feedback from PR #104, we've significantly improved the test suite quality, organization, and coverage.
-
-## Test Results
-- **Before:** 78 failing tests
-- **After:** 0 failing tests (1,356 passed, 19 skipped)
-- **Coverage:** 85.34% statements, 85.3% branches
-
-## Key Improvements
-
-### 1. Fixed All Test Failures
-- Fixed logger test spy issues by properly handling DEBUG environment variable
-- Fixed MSW configuration test by restoring environment variables
-- Fixed workflow validator tests by adding proper node connections
-- Fixed mock setup issues in edge case tests
-
-### 2. Improved Test Organization
-- Split large config-validator.test.ts (1,075 lines) into 4 focused files:
-  - config-validator-basic.test.ts
-  - config-validator-node-specific.test.ts
-  - config-validator-security.test.ts
-  - config-validator-edge-cases.test.ts
-
-### 3. Enhanced Test Coverage
-- Added comprehensive edge case tests for all major validators
-- Added null/undefined handling tests
-- Added boundary value tests
-- Added performance tests with CI-aware timeouts
-- Added security validation tests
-
-### 4. Improved Test Quality
-- Fixed test naming conventions (100% compliance with "should X when Y" pattern)
-- Added JSDoc comments to test utilities and factories
-- Created comprehensive test documentation (tests/README.md)
-- Improved test isolation to prevent cross-test pollution
-
-### 5. New Features
-- Implemented validateBatch method for ConfigValidator
-- Added test factories for better test data management
-- Created test utilities for common scenarios
-
-## Files Modified
-- 7 existing test files fixed
-- 8 new test files created
-- 1 source file enhanced (ConfigValidator)
-- 4 debug files removed before commit
-
-## Skipped Tests
-19 tests remain skipped with documented reasons:
-- FTS5 search sync test (database corruption in CI)
-- Template clearing (not implemented)
-- Mock API configuration tests
-- Duplicate edge case tests with mocking issues (working versions exist)
-
-## Next Steps
-The only remaining task from the improvement plan is:
-- Add performance regression tests and boundaries (low priority, future sprint)
-
-## Conclusion
-The test suite is now robust, well-organized, and provides excellent coverage. All critical issues have been resolved, and the codebase is ready for merge.

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
 
@@ -284,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/TEMPLATE_METADATA.md

@@ -1,314 +0,0 @@
-# Template Metadata Generation
-
-This document describes the template metadata generation system introduced in n8n-MCP v2.10.0, which uses OpenAI's batch API to automatically analyze and categorize workflow templates.
-
-## Overview
-
-The template metadata system analyzes n8n workflow templates to extract structured information about their purpose, complexity, requirements, and target audience. This enables intelligent template discovery through advanced filtering capabilities.
-
-## Architecture
-
-### Components
-
-1. **MetadataGenerator** (`src/templates/metadata-generator.ts`)
-   - Interfaces with OpenAI API
-   - Generates structured metadata using JSON schemas
-   - Provides fallback defaults for error cases
-
-2. **BatchProcessor** (`src/templates/batch-processor.ts`)
-   - Manages OpenAI batch API operations
-   - Handles parallel batch submission
-   - Monitors batch status and retrieves results
-
-3. **Template Repository** (`src/templates/template-repository.ts`)
-   - Stores metadata in SQLite database
-   - Provides advanced search capabilities
-   - Supports JSON extraction queries
-
-## Metadata Schema
-
-Each template's metadata contains:
-
-```typescript
-{
-  categories: string[]           // Max 5 categories (e.g., "automation", "integration")
-  complexity: "simple" | "medium" | "complex"
-  use_cases: string[]           // Max 5 primary use cases
-  estimated_setup_minutes: number // 5-480 minutes
-  required_services: string[]    // External services needed
-  key_features: string[]        // Max 5 main capabilities
-  target_audience: string[]     // Max 3 target user types
-}
-```
-
-## Generation Process
-
-### 1. Initial Setup
-
-```bash
-# Set OpenAI API key in .env
-OPENAI_API_KEY=your-api-key-here
-```
-
-### 2. Generate Metadata for Existing Templates
-
-```bash
-# Generate metadata only (no template fetching)
-npm run fetch:templates -- --metadata-only
-
-# Generate metadata during update
-npm run fetch:templates -- --mode=update --generate-metadata
-```
-
-### 3. Batch Processing
-
-The system uses OpenAI's batch API for cost-effective processing:
-
-- **50% cost reduction** compared to synchronous API calls
-- **24-hour processing window** for batch completion
-- **Parallel batch submission** for faster processing
-- **Automatic retry** for failed items
-
-### Configuration Options
-
-Environment variables:
-- `OPENAI_API_KEY`: Required for metadata generation
-- `OPENAI_MODEL`: Model to use (default: "gpt-4o-mini")
-- `OPENAI_BATCH_SIZE`: Templates per batch (default: 100, max: 500)
-- `METADATA_LIMIT`: Limit templates to process (for testing)
-
-## How It Works
-
-### 1. Template Analysis
-
-For each template, the generator analyzes:
-- Template name and description
-- Node types and their frequency
-- Workflow structure and connections
-- Overall complexity
-
-### 2. Node Summarization
-
-Nodes are grouped into categories:
-- HTTP/Webhooks
-- Database operations
-- Communication (Slack, Email)
-- AI/ML operations
-- Spreadsheets
-- Service-specific nodes
-
-### 3. Metadata Generation
-
-The AI model receives:
-```
-Template: [name]
-Description: [description]
-Nodes Used (X): [summarized node list]
-Workflow has X nodes with Y connections
-```
-
-And generates structured metadata following the JSON schema.
-
-### 4. Storage and Indexing
-
-Metadata is stored as JSON in SQLite and indexed for fast querying:
-
-```sql
--- Example query for simple automation templates
-SELECT * FROM templates 
-WHERE json_extract(metadata, '$.complexity') = 'simple'
-AND json_extract(metadata, '$.categories') LIKE '%automation%'
-```
-
-## MCP Tool Integration
-
-### search_templates_by_metadata
-
-Advanced filtering tool with multiple parameters:
-
-```typescript
-search_templates_by_metadata({
-  category: "automation",           // Filter by category
-  complexity: "simple",             // Skill level
-  maxSetupMinutes: 30,             // Time constraint
-  targetAudience: "marketers",     // Role-based
-  requiredService: "slack"         // Service dependency
-})
-```
-
-### list_templates
-
-Enhanced to include metadata:
-
-```typescript
-list_templates({
-  includeMetadata: true,  // Include full metadata
-  limit: 20,
-  offset: 0
-})
-```
-
-## Usage Examples
-
-### Finding Beginner-Friendly Templates
-
-```typescript
-const templates = await search_templates_by_metadata({
-  complexity: "simple",
-  maxSetupMinutes: 15
-});
-```
-
-### Role-Specific Templates
-
-```typescript
-const marketingTemplates = await search_templates_by_metadata({
-  targetAudience: "marketers",
-  category: "communication"
-});
-```
-
-### Service Integration Templates
-
-```typescript
-const openaiTemplates = await search_templates_by_metadata({
-  requiredService: "openai",
-  complexity: "medium"
-});
-```
-
-## Performance Metrics
-
-- **Coverage**: 97.5% of templates have metadata (2,534/2,598)
-- **Generation Time**: ~2-4 hours for full database (using batch API)
-- **Query Performance**: <100ms for metadata searches
-- **Storage Overhead**: ~2MB additional database size
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Batch Processing Stuck**
-   - Check batch status: The API provides status updates
-   - Batches auto-expire after 24 hours
-   - Monitor using the batch ID in logs
-
-2. **Missing Metadata**
-   - ~2.5% of templates may fail metadata generation
-   - Fallback defaults are provided
-   - Can regenerate with `--metadata-only` flag
-
-3. **API Rate Limits**
-   - Batch API has generous limits (50,000 requests/batch)
-   - Cost is 50% of synchronous API
-   - Processing happens within 24-hour window
-
-### Monitoring Batch Status
-
-```bash
-# Check current batch status (if logged)
-curl https://api.openai.com/v1/batches/[batch-id] \
-  -H "Authorization: Bearer $OPENAI_API_KEY"
-```
-
-## Cost Analysis
-
-### Batch API Pricing (gpt-4o-mini)
-
-- Input: $0.075 per 1M tokens (50% of standard)
-- Output: $0.30 per 1M tokens (50% of standard)
-- Average template: ~300 input tokens, ~200 output tokens
-- Total cost for 2,500 templates: ~$0.50
-
-### Comparison with Synchronous API
-
-- Synchronous cost: ~$1.00 for same volume
-- Time saved: Parallel processing vs sequential
-- Reliability: Automatic retries included
-
-## Future Enhancements
-
-### Planned Improvements
-
-1. **Incremental Updates**
-   - Only generate metadata for new templates
-   - Track metadata version for updates
-
-2. **Enhanced Analysis**
-   - Workflow complexity scoring
-   - Dependency graph analysis
-   - Performance impact estimates
-
-3. **User Feedback Loop**
-   - Collect accuracy feedback
-   - Refine categorization over time
-   - Community-driven corrections
-
-4. **Alternative Models**
-   - Support for local LLMs
-   - Claude API integration
-   - Configurable model selection
-
-## Implementation Details
-
-### Database Schema
-
-```sql
--- Metadata stored as JSON column
-ALTER TABLE templates ADD COLUMN metadata TEXT;
-
--- Indexes for common queries
-CREATE INDEX idx_templates_complexity ON templates(
-  json_extract(metadata, '$.complexity')
-);
-CREATE INDEX idx_templates_setup_time ON templates(
-  json_extract(metadata, '$.estimated_setup_minutes')
-);
-```
-
-### Error Handling
-
-The system provides robust error handling:
-
-1. **API Failures**: Fallback to default metadata
-2. **Parsing Errors**: Logged with template ID
-3. **Batch Failures**: Individual item retry
-4. **Validation Errors**: Zod schema enforcement
-
-## Maintenance
-
-### Regenerating Metadata
-
-```bash
-# Full regeneration (caution: costs ~$0.50)
-npm run fetch:templates -- --mode=rebuild --generate-metadata
-
-# Partial regeneration (templates without metadata)
-npm run fetch:templates -- --metadata-only
-```
-
-### Database Backup
-
-```bash
-# Backup before regeneration
-cp data/nodes.db data/nodes.db.backup
-
-# Restore if needed
-cp data/nodes.db.backup data/nodes.db
-```
-
-## Security Considerations
-
-1. **API Key Management**
-   - Store in `.env` file (gitignored)
-   - Never commit API keys
-   - Use environment variables in CI/CD
-
-2. **Data Privacy**
-   - Only template structure is sent to API
-   - No user data or credentials included
-   - Processing happens in OpenAI's secure environment
-
-## Conclusion
-
-The template metadata system transforms template discovery from simple text search to intelligent, multi-dimensional filtering. By leveraging OpenAI's batch API, we achieve cost-effective, scalable metadata generation that significantly improves the user experience for finding relevant workflow templates.

docs/issue-90-findings.md

@@ -1,162 +0,0 @@
-# Issue #90: "propertyValues[itemName] is not iterable" Error - Research Findings
-
-## Executive Summary
-
-The error "propertyValues[itemName] is not iterable" occurs when AI agents create workflows with incorrect data structures for n8n nodes that use `fixedCollection` properties. This primarily affects Switch Node v2, If Node, and Filter Node. The error prevents workflows from loading in the n8n UI, resulting in empty canvases.
-
-## Root Cause Analysis
-
-### 1. Data Structure Mismatch
-
-The error occurs when n8n's validation engine expects an iterable array but encounters a non-iterable object. This happens with nodes using `fixedCollection` type properties.
-
-**Incorrect Structure (causes error):**
-```json
-{
-  "rules": {
-    "conditions": {
-      "values": [
-        {
-          "value1": "={{$json.status}}",
-          "operation": "equals", 
-          "value2": "active"
-        }
-      ]
-    }
-  }
-}
-```
-
-**Correct Structure:**
-```json
-{
-  "rules": {
-    "conditions": [
-      {
-        "value1": "={{$json.status}}",
-        "operation": "equals",
-        "value2": "active"
-      }
-    ]
-  }
-}
-```
-
-### 2. Affected Nodes
-
-Based on the research and issue comments, the following nodes are affected:
-
-1. **Switch Node v2** (`n8n-nodes-base.switch` with typeVersion: 2)
-   - Uses `rules` parameter with `conditions` fixedCollection
-   - v3 doesn't have this issue due to restructured schema
-
-2. **If Node** (`n8n-nodes-base.if` with typeVersion: 1)
-   - Uses `conditions` parameter with nested conditions array
-   - Similar structure to Switch v2
-
-3. **Filter Node** (`n8n-nodes-base.filter`)
-   - Uses `conditions` parameter
-   - Same fixedCollection pattern
-
-### 3. Why AI Agents Create Incorrect Structures
-
-1. **Training Data Issues**: AI models may have been trained on outdated or incorrect n8n workflow examples
-2. **Nested Object Inference**: AI tends to create unnecessarily nested structures when it sees collection-type parameters
-3. **Legacy Format Confusion**: Mixing v2 and v3 Switch node formats
-4. **Schema Misinterpretation**: The term "fixedCollection" may lead AI to create object wrappers
-
-## Current Impact
-
-From issue #90 comments:
-- Multiple users experiencing the issue
-- Workflows fail to load completely (empty canvas)
-- Users resort to using Switch Node v3 or direct API calls
-- The issue appears in "most MCPs" according to user feedback
-
-## Recommended Actions
-
-### 1. Immediate Validation Enhancement
-
-Add specific validation for fixedCollection properties in the workflow validator:
-
-```typescript
-// In workflow-validator.ts or enhanced-config-validator.ts
-function validateFixedCollectionParameters(node, result) {
-  const problematicNodes = {
-    'n8n-nodes-base.switch': { version: 2, fields: ['rules'] },
-    'n8n-nodes-base.if': { version: 1, fields: ['conditions'] },
-    'n8n-nodes-base.filter': { version: 1, fields: ['conditions'] }
-  };
-  
-  const nodeConfig = problematicNodes[node.type];
-  if (nodeConfig && node.typeVersion === nodeConfig.version) {
-    // Validate structure
-  }
-}
-```
-
-### 2. Enhanced MCP Tool Validation
-
-Update the validation tools to detect and prevent this specific error pattern:
-
-1. **In `validate_node_operation` tool**: Add checks for fixedCollection structures
-2. **In `validate_workflow` tool**: Include specific validation for Switch/If nodes
-3. **In `n8n_create_workflow` tool**: Pre-validate parameters before submission
-
-### 3. AI-Friendly Examples
-
-Update workflow examples to show correct structures:
-
-```typescript
-// In workflow-examples.ts
-export const SWITCH_NODE_EXAMPLE = {
-  name: "Switch",
-  type: "n8n-nodes-base.switch", 
-  typeVersion: 3, // Prefer v3 over v2
-  parameters: {
-    // Correct v3 structure
-  }
-};
-```
-
-### 4. Migration Strategy
-
-For existing workflows with Switch v2:
-1. Detect Switch v2 nodes in validation
-2. Suggest migration to v3
-3. Provide automatic conversion utility
-
-### 5. Documentation Updates
-
-1. Add warnings about fixedCollection structures in tool documentation
-2. Include specific examples of correct vs incorrect structures
-3. Document the Switch v2 to v3 migration path
-
-## Proposed Implementation Priority
-
-1. **High Priority**: Add validation to prevent creation of invalid structures
-2. **High Priority**: Update existing validation tools to catch this error
-3. **Medium Priority**: Add auto-fix capabilities to correct structures
-4. **Medium Priority**: Update examples and documentation
-5. **Low Priority**: Create migration utilities for v2 to v3
-
-## Testing Strategy
-
-1. Create test cases for each affected node type
-2. Test both correct and incorrect structures
-3. Verify validation catches all variants of the error
-4. Test auto-fix suggestions work correctly
-
-## Success Metrics
-
-- Zero instances of "propertyValues[itemName] is not iterable" in newly created workflows
-- Clear error messages that guide users to correct structures
-- Successful validation of all Switch/If node configurations before workflow creation
-
-## Next Steps
-
-1. Implement validation enhancements in the workflow validator
-2. Update MCP tools to include these validations
-3. Add comprehensive tests
-4. Update documentation with clear examples
-5. Consider adding a migration tool for existing workflows

docs/local/integration-testing-plan.md

@@ -1,8 +1,181 @@
 # Comprehensive Integration Testing Plan
 
+## Status
+
+**Phase 1: Foundation** ✅ **COMPLETE** (October 3, 2025)
+- All utility files created and tested
+- Webhook workflows created on `https://n8n-test.n8n-mcp.com`
+- GitHub secrets configured
+- Critical fix: Updated credentials to use webhook URLs instead of IDs
+- Environment loading fixed to support real n8n API integration tests
+
+**Phase 2: Workflow Creation Tests** ✅ **COMPLETE** (October 3, 2025)
+- 15 test scenarios implemented and passing
+- P0 bug verification confirmed (FULL node type format)
+- All test categories covered: base nodes, advanced features, error scenarios, edge cases
+- Documented actual n8n API behavior (validation at execution time, not creation time)
+- Test file: `tests/integration/n8n-api/workflows/create-workflow.test.ts` (484 lines)
+
+**Phase 3: Workflow Retrieval Tests** ✅ **COMPLETE** (October 3, 2025)
+- 11 test scenarios implemented and passing
+- All MCP retrieval handlers tested: handleGetWorkflow, handleGetWorkflowDetails, handleGetWorkflowStructure, handleGetWorkflowMinimal
+- Test files:
+  - `get-workflow.test.ts` (3 scenarios)
+  - `get-workflow-details.test.ts` (4 scenarios)
+  - `get-workflow-structure.test.ts` (2 scenarios)
+  - `get-workflow-minimal.test.ts` (2 scenarios)
+
+**Phase 4: Workflow Update Tests** ✅ **COMPLETE** (October 4, 2025)
+- 42 test scenarios implemented and passing
+- Enhanced settings filtering (whitelist approach) to enable updates while maintaining Issue #248 protection
+- All update operations tested:
+  - Full workflow updates: 7 scenarios (update-workflow.test.ts)
+  - Partial/diff-based updates: 32 scenarios covering all 15 operations (update-partial-workflow.test.ts)
+  - Validation error scenarios: 3 scenarios
+- Critical fixes:
+  - Settings filtering uses OpenAPI spec whitelist (filters callerPolicy, preserves safe properties)
+  - All tests comply with n8n API requirements (name, nodes, connections, settings fields)
+  - Removed invalid "Update Connections" test (empty connections invalid for multi-node workflows)
+- Version 2.15.4 released with comprehensive CHANGELOG entry
+
+**Phase 5: Workflow Management Tests** ✅ **COMPLETE** (October 4, 2025)
+- 16 test scenarios implemented and passing
+- All workflow management operations tested:
+  - Delete workflow: 3 scenarios (delete-workflow.test.ts)
+  - List workflows: 13 scenarios (list-workflows.test.ts)
+- Critical API compliance fixes:
+  - handleDeleteWorkflow: Now returns deleted workflow data (per n8n API spec)
+  - handleListWorkflows: Fixed tags parameter format (array → CSV string conversion)
+  - N8nApiClient.deleteWorkflow: Return type corrected (void → Workflow)
+  - WorkflowListParams.tags: Type corrected (string[] → string per n8n OpenAPI spec)
+- Unit test coverage: Added 9 unit tests for handler coverage (100% coverage achieved)
+- n8n-mcp-tester validation: All tools tested and working correctly in production
+- Version 2.15.5 released with comprehensive CHANGELOG entry
+- Test results: 71/71 integration tests passing (Phase 1-5 complete)
+
+**Phase 6A: Workflow Validation Tests** ✅ **COMPLETE** (October 5, 2025)
+- 12 test scenarios implemented and passing
+- NodeRepository utility created for tests requiring node validation
+- All validation profiles tested: strict, runtime, ai-friendly, minimal
+- Test coverage:
+  - Valid workflows across all 4 profiles (4 scenarios)
+  - Invalid workflow detection (2 scenarios - bad node types, missing connections)
+  - Selective validation (3 scenarios - nodes only, connections only, expressions only)
+  - Error handling (2 scenarios - non-existent workflow, invalid profile)
+  - Response format verification (1 scenario)
+- Critical discoveries:
+  - Response only includes errors/warnings fields when they exist (not empty arrays)
+  - Field name is errorCount, not totalErrors
+  - Tests require NodeRepository instance (added singleton utility)
+- Test file: validate-workflow.test.ts (431 lines)
+- Test results: 83/83 integration tests passing (Phase 1-5, 6A complete)
+
+**Phase 6B: Workflow Autofix Tests** ✅ **COMPLETE** (October 5, 2025)
+- 16 test scenarios implemented and passing
+- All autofix operations tested: preview mode, apply mode, fix types, confidence filtering
+- Test coverage:
+  - Preview mode (2 scenarios - expression-format, multiple fix types)
+  - Apply mode (2 scenarios - expression-format, webhook-missing-path)
+  - Fix type filtering (2 scenarios - single type, multiple types)
+  - Confidence thresholds (3 scenarios - high, medium, low)
+  - Max fixes parameter (1 scenario)
+  - No fixes available (1 scenario)
+  - Error handling (3 scenarios - non-existent workflow, invalid parameters)
+  - Response format verification (2 scenarios - preview and apply modes)
+- Fix types tested:
+  - expression-format (missing = prefix for resource locators)
+  - typeversion-correction (outdated typeVersion values)
+  - error-output-config (error output configuration issues)
+  - node-type-correction (incorrect node types)
+  - webhook-missing-path (missing webhook path parameters)
+- Code quality improvements:
+  - Fixed database resource leak in NodeRepository utility
+  - Added TypeScript interfaces (ValidationResponse, AutofixResponse)
+  - Replaced unsafe `as any` casts with proper type definitions
+  - All lint and typecheck errors resolved
+- Test file: autofix-workflow.test.ts (855 lines)
+- Test results: 99/99 integration tests passing (Phase 1-6 complete)
+
+**Phase 7: Execution Management Tests** ✅ **COMPLETE** (October 5, 2025)
+- 54 test scenarios implemented and passing
+- All 4 execution management handlers tested against real n8n instance
+- Test coverage:
+  - handleTriggerWebhookWorkflow (20 tests): All HTTP methods (GET/POST/PUT/DELETE), query params, JSON body, custom headers, error handling
+  - handleGetExecution (16 tests): All 4 retrieval modes (preview/summary/filtered/full), node filtering, item limits, input data inclusion, legacy compatibility
+  - handleListExecutions (13 tests): Status filtering (success/error/waiting), pagination with cursor, various limits (1/10/50/100), data inclusion control
+  - handleDeleteExecution (5 tests): Successful deletion, verification via fetch attempt, error handling
+- Critical fix: Corrected response structure expectations (executions/returned vs data/count)
+- Test files:
+  - trigger-webhook.test.ts (375 lines, 20 tests)
+  - get-execution.test.ts (429 lines, 16 tests)
+  - list-executions.test.ts (264 lines, 13 tests)
+  - delete-execution.test.ts (149 lines, 5 tests)
+- Code review: APPROVED (9.5/10 quality score)
+- Test results: 153/153 integration tests passing (Phase 1-7 complete)
+
+**Phase 8: System Tools Tests** ✅ **COMPLETE** (October 5, 2025)
+- 19 test scenarios implemented and passing
+- All 3 system tool handlers tested against real n8n instance
+- Test coverage:
+  - handleHealthCheck (3 tests): API connectivity verification, version information, feature availability
+  - handleListAvailableTools (7 tests): Complete tool inventory by category, configuration status, API limitations
+  - handleDiagnostic (9 tests): Environment checks, API connectivity, tools availability, verbose mode with debug info
+- TypeScript type safety improvements:
+  - Created response-types.ts with comprehensive interfaces for all response types
+  - Replaced all 'as any' casts with proper TypeScript interfaces
+  - Added null-safety checks and non-null assertions
+  - Full type safety and IDE autocomplete support
+- Test files:
+  - health-check.test.ts (117 lines, 3 tests)
+  - list-tools.test.ts (181 lines, 7 tests)
+  - diagnostic.test.ts (243 lines, 9 tests)
+  - response-types.ts (241 lines, comprehensive type definitions)
+- Code review: APPROVED
+- Test results: 172/172 integration tests passing (Phase 1-8 complete)
+
+**🎉 INTEGRATION TEST SUITE COMPLETE**: All 18 MCP handlers fully tested
+
+**Next Phase**: Update documentation and finalize integration testing plan
+
+---
+
 ## Overview
 
-Transform the test suite to test all 17 n8n API handlers against a **real n8n instance** instead of mocks. This plan ensures 100% coverage of every tool, operation, and parameter combination to prevent bugs like the P0 workflow creation issue from slipping through.
+Transform the test suite to test all 17 **MCP handlers** against a **real n8n instance** instead of mocks. This plan ensures 100% coverage of every tool, operation, and parameter combination to prevent bugs like the P0 workflow creation issue from slipping through.
+
+### What We Test: MCP Handlers (The Product Layer)
+
+**IMPORTANT**: These integration tests validate the **MCP handler layer** (the actual product that AI assistants interact with), not just the raw n8n API client.
+
+**Architecture:**
+```
+AI Assistant (Claude)
+      ↓
+  MCP Tools (What AI sees)
+      ↓
+  MCP Handlers (What we test) ← INTEGRATION TESTS TARGET THIS LAYER
+      ↓
+  N8nApiClient (Low-level HTTP)
+      ↓
+  n8n REST API
+```
+
+**Why This Matters:**
+- **MCP handlers** wrap API responses in `McpToolResponse` format: `{ success: boolean, data?: any, error?: string }`
+- **MCP handlers** transform and enrich API responses (e.g., `handleGetWorkflowDetails` adds execution stats)
+- **MCP handlers** provide the exact interface that AI assistants consume
+- Testing raw API client bypasses the product layer and misses MCP-specific logic
+
+**Test Pattern:**
+```typescript
+// ❌ WRONG: Testing raw API client (low-level service)
+const result = await client.createWorkflow(workflow);
+
+// ✅ CORRECT: Testing MCP handler (product layer)
+const response = await handleCreateWorkflow({ ...workflow }, mcpContext);
+expect(response.success).toBe(true);
+const result = response.data;
+```
 
 ## Critical Requirements
 
@@ -13,11 +186,12 @@ Transform the test suite to test all 17 n8n API handlers against a **real n8n in
 2. **Pre-activated Webhook Workflows**:
    - n8n API doesn't support workflow activation via API
    - Need pre-created, activated workflows for webhook testing
-   - Store workflow IDs in `.env`:
-     - `N8N_TEST_WEBHOOK_GET_ID` - Webhook with GET method
-     - `N8N_TEST_WEBHOOK_POST_ID` - Webhook with POST method
-     - `N8N_TEST_WEBHOOK_PUT_ID` - Webhook with PUT method
-     - `N8N_TEST_WEBHOOK_DELETE_ID` - Webhook with DELETE method
+   - Store webhook URLs (not workflow IDs) in `.env`:
+     - `N8N_TEST_WEBHOOK_GET_URL` - GET method webhook URL
+     - `N8N_TEST_WEBHOOK_POST_URL` - POST method webhook URL
+     - `N8N_TEST_WEBHOOK_PUT_URL` - PUT method webhook URL
+     - `N8N_TEST_WEBHOOK_DELETE_URL` - DELETE method webhook URL
+   - **Rationale**: Webhook URLs are what the `n8n_trigger_webhook_workflow` tool needs. Workflow IDs are only for workflow management tests (which create workflows dynamically during test execution).
 
 3. **100% Coverage Goal**: Test EVERY tool, EVERY operation, EVERY parameter combination
 
@@ -27,9 +201,9 @@ Transform the test suite to test all 17 n8n API handlers against a **real n8n in
 
 ### Total Test Scenarios: ~150+
 
-#### Workflow Management (10 handlers)
+#### Workflow Management (10 MCP handlers)
 
-**1. `handleCreateWorkflow`** - 10+ scenarios
+**1. `handleCreateWorkflow`** - 15+ scenarios (MCP handler testing)
 - Create workflow with base nodes (webhook, httpRequest, set)
 - Create workflow with langchain nodes (agent, aiChain)
 - Invalid node types (error handling)
@@ -232,13 +406,13 @@ Transform the test suite to test all 17 n8n API handlers against a **real n8n in
 N8N_API_URL=http://localhost:5678
 N8N_API_KEY=your-api-key-here
 
-# Pre-activated Webhook Workflows for Testing
+# Pre-activated Webhook URLs for Testing
 # Create these workflows manually in n8n and activate them
-# Each workflow should have a single Webhook node with the specified HTTP method
-N8N_TEST_WEBHOOK_GET_ID=     # Webhook with GET method
-N8N_TEST_WEBHOOK_POST_ID=    # Webhook with POST method
-N8N_TEST_WEBHOOK_PUT_ID=     # Webhook with PUT method
-N8N_TEST_WEBHOOK_DELETE_ID=  # Webhook with DELETE method
+# Store the full webhook URLs (not workflow IDs)
+N8N_TEST_WEBHOOK_GET_URL=https://n8n-test.n8n-mcp.com/webhook/mcp-test-get
+N8N_TEST_WEBHOOK_POST_URL=https://n8n-test.n8n-mcp.com/webhook/mcp-test-post
+N8N_TEST_WEBHOOK_PUT_URL=https://n8n-test.n8n-mcp.com/webhook/mcp-test-put
+N8N_TEST_WEBHOOK_DELETE_URL=https://n8n-test.n8n-mcp.com/webhook/mcp-test-delete
 
 # Test Configuration
 N8N_TEST_CLEANUP_ENABLED=true           # Enable automatic cleanup
@@ -247,12 +421,14 @@ N8N_TEST_NAME_PREFIX=[MCP-TEST]         # Name prefix for test workflows
 ```
 
 **GitHub Secrets (for CI):**
-- `N8N_URL`: n8n instance URL
-- `N8N_API_KEY`: n8n API key
-- `N8N_TEST_WEBHOOK_GET_ID`: Pre-activated GET webhook workflow ID
-- `N8N_TEST_WEBHOOK_POST_ID`: Pre-activated POST webhook workflow ID
-- `N8N_TEST_WEBHOOK_PUT_ID`: Pre-activated PUT webhook workflow ID
-- `N8N_TEST_WEBHOOK_DELETE_ID`: Pre-activated DELETE webhook workflow ID
+- `N8N_URL`: n8n instance URL (e.g., `https://n8n-test.n8n-mcp.com`)
+- `N8N_API_KEY`: n8n API key (JWT token from n8n Settings > API)
+- `N8N_TEST_WEBHOOK_GET_URL`: Pre-activated GET webhook URL
+- `N8N_TEST_WEBHOOK_POST_URL`: Pre-activated POST webhook URL
+- `N8N_TEST_WEBHOOK_PUT_URL`: Pre-activated PUT webhook URL
+- `N8N_TEST_WEBHOOK_DELETE_URL`: Pre-activated DELETE webhook URL
+
+**Note**: Webhook URLs can be stored as repository secrets (not environment secrets) since they don't grant API access. The real secret is `N8N_API_KEY`.
 
 #### 1.2 Directory Structure
 
@@ -291,6 +467,24 @@ tests/integration/n8n-api/
 
 #### 1.3 Core Utilities
 
+**mcp-context.ts** - MCP context configuration for handler testing:
+```typescript
+import { InstanceContext } from '../../../../src/types/instance-context';
+import { getN8nCredentials } from './credentials';
+
+/**
+ * Creates MCP context for testing MCP handlers against real n8n instance
+ * This is what gets passed to MCP handlers (handleCreateWorkflow, etc.)
+ */
+export function createMcpContext(): InstanceContext {
+  const creds = getN8nCredentials();
+  return {
+    n8nApiUrl: creds.url,
+    n8nApiKey: creds.apiKey
+  };
+}
+```
+
 **credentials.ts** - Environment-aware credential loader:
 ```typescript
 import dotenv from 'dotenv';
@@ -300,7 +494,7 @@ dotenv.config();
 export interface N8nTestCredentials {
   url: string;
   apiKey: string;
-  webhookWorkflows: {
+  webhookUrls: {
     get: string;
     post: string;
     put: string;
@@ -316,14 +510,26 @@ export interface N8nTestCredentials {
 export function getN8nCredentials(): N8nTestCredentials {
   if (process.env.CI) {
     // CI: Use GitHub secrets
+    const url = process.env.N8N_URL;
+    const apiKey = process.env.N8N_API_KEY;
+
+    if (!url || !apiKey) {
+      throw new Error(
+        'Missing required CI credentials:\n' +
+        `  N8N_URL: ${url ? 'set' : 'MISSING'}\n` +
+        `  N8N_API_KEY: ${apiKey ? 'set' : 'MISSING'}\n` +
+        'Please configure GitHub secrets for integration tests.'
+      );
+    }
+
     return {
-      url: process.env.N8N_URL!,
-      apiKey: process.env.N8N_API_KEY!,
-      webhookWorkflows: {
-        get: process.env.N8N_TEST_WEBHOOK_GET_ID!,
-        post: process.env.N8N_TEST_WEBHOOK_POST_ID!,
-        put: process.env.N8N_TEST_WEBHOOK_PUT_ID!,
-        delete: process.env.N8N_TEST_WEBHOOK_DELETE_ID!
+      url,
+      apiKey,
+      webhookUrls: {
+        get: process.env.N8N_TEST_WEBHOOK_GET_URL || '',
+        post: process.env.N8N_TEST_WEBHOOK_POST_URL || '',
+        put: process.env.N8N_TEST_WEBHOOK_PUT_URL || '',
+        delete: process.env.N8N_TEST_WEBHOOK_DELETE_URL || ''
       },
       cleanup: {
         enabled: true,
@@ -333,14 +539,27 @@ export function getN8nCredentials(): N8nTestCredentials {
     };
   } else {
     // Local: Use .env file
+    const url = process.env.N8N_API_URL;
+    const apiKey = process.env.N8N_API_KEY;
+
+    if (!url || !apiKey) {
+      throw new Error(
+        'Missing required credentials in .env:\n' +
+        `  N8N_API_URL: ${url ? 'set' : 'MISSING'}\n` +
+        `  N8N_API_KEY: ${apiKey ? 'set' : 'MISSING'}\n\n` +
+        'Please add these to your .env file.\n' +
+        'See .env.example for configuration details.'
+      );
+    }
+
     return {
-      url: process.env.N8N_API_URL!,
-      apiKey: process.env.N8N_API_KEY!,
-      webhookWorkflows: {
-        get: process.env.N8N_TEST_WEBHOOK_GET_ID || '',
-        post: process.env.N8N_TEST_WEBHOOK_POST_ID || '',
-        put: process.env.N8N_TEST_WEBHOOK_PUT_ID || '',
-        delete: process.env.N8N_TEST_WEBHOOK_DELETE_ID || ''
+      url,
+      apiKey,
+      webhookUrls: {
+        get: process.env.N8N_TEST_WEBHOOK_GET_URL || '',
+        post: process.env.N8N_TEST_WEBHOOK_POST_URL || '',
+        put: process.env.N8N_TEST_WEBHOOK_PUT_URL || '',
+        delete: process.env.N8N_TEST_WEBHOOK_DELETE_URL || ''
       },
       cleanup: {
         enabled: process.env.N8N_TEST_CLEANUP_ENABLED !== 'false',
@@ -356,28 +575,42 @@ export function validateCredentials(creds: N8nTestCredentials): void {
   if (!creds.apiKey) throw new Error('N8N_API_KEY is required');
 }
 
-export function validateWebhookWorkflows(creds: N8nTestCredentials): void {
+export function validateWebhookUrls(creds: N8nTestCredentials): void {
   const missing: string[] = [];
-  if (!creds.webhookWorkflows.get) missing.push('GET');
-  if (!creds.webhookWorkflows.post) missing.push('POST');
-  if (!creds.webhookWorkflows.put) missing.push('PUT');
-  if (!creds.webhookWorkflows.delete) missing.push('DELETE');
+  if (!creds.webhookUrls.get) missing.push('GET');
+  if (!creds.webhookUrls.post) missing.push('POST');
+  if (!creds.webhookUrls.put) missing.push('PUT');
+  if (!creds.webhookUrls.delete) missing.push('DELETE');
 
   if (missing.length > 0) {
     throw new Error(
-      `Missing webhook workflow IDs for HTTP methods: ${missing.join(', ')}\n` +
+      `Missing webhook URLs for HTTP methods: ${missing.join(', ')}\n` +
       `Please create and activate webhook workflows, then set:\n` +
-      missing.map(m => `  N8N_TEST_WEBHOOK_${m}_ID`).join('\n')
+      missing.map(m => `  N8N_TEST_WEBHOOK_${m}_URL`).join('\n')
     );
   }
 }
 ```
 
-**n8n-client.ts** - Pre-configured API client wrapper:
+**n8n-client.ts** - Pre-configured API client (for test utilities only):
 ```typescript
 import { N8nApiClient } from '../../../src/services/n8n-api-client';
 import { getN8nCredentials } from './credentials';
 
+/**
+ * IMPORTANT: This client is ONLY used for test setup/cleanup utilities.
+ * DO NOT use this in actual test cases - use MCP handlers instead!
+ *
+ * Test utilities that need direct API access:
+ * - cleanupOrphanedWorkflows() - bulk cleanup
+ * - Fixture setup/teardown
+ * - Pre-test verification
+ *
+ * Actual tests MUST use MCP handlers:
+ * - handleCreateWorkflow()
+ * - handleGetWorkflow()
+ * - etc.
+ */
 let client: N8nApiClient | null = null;
 
 export function getTestN8nClient(): N8nApiClient {
@@ -689,33 +922,92 @@ ${method} Method:
 
 ### Phase 2: Workflow Creation Tests (P0)
 
-**Branch**: `feat/integration-tests-workflow-creation`
+**Branch**: `feat/integration-tests-phase-2`
 
 **File**: `tests/integration/n8n-api/workflows/create-workflow.test.ts`
 
-**10+ Test Scenarios**:
+**Test Approach**: Tests the `handleCreateWorkflow` MCP handler against real n8n instance
+
+**MCP Handler Test Pattern:**
+```typescript
+import { handleCreateWorkflow } from '../../../../src/mcp/handlers-n8n-manager';
+import { createMcpContext } from '../utils/mcp-context';
+import { InstanceContext } from '../../../../src/types/instance-context';
+
+describe('Integration: handleCreateWorkflow', () => {
+  let mcpContext: InstanceContext;
+
+  beforeEach(() => {
+    mcpContext = createMcpContext();
+  });
+
+  it('should create workflow using MCP handler', async () => {
+    const workflow = { name: 'Test', nodes: [...], connections: {} };
+
+    // Test MCP handler (the product layer)
+    const response = await handleCreateWorkflow({ ...workflow }, mcpContext);
+
+    // Verify MCP response structure
+    expect(response.success).toBe(true);
+    expect(response.data).toBeDefined();
+
+    // Extract actual workflow from MCP response
+    const result = response.data;
+    expect(result.id).toBeTruthy();
+  });
+});
+```
+
+**15 Test Scenarios** (all testing MCP handlers):
 1. Create workflow with base webhook node (verify P0 bug fix)
 2. Create workflow with base HTTP request node
 3. Create workflow with langchain agent node
 4. Create complex multi-node workflow
 5. Create workflow with complex connections
-6. Error: Invalid node type
-7. Error: Missing required parameters
-8. Error: Duplicate node names
-9. Error: Invalid connection references
-10. Create workflow with custom settings
+6. Create workflow with custom settings
+7. Create workflow with n8n expressions
+8. Create workflow with error handling
+9. Error: Invalid node type (documents API behavior)
+10. Error: Missing required parameters (documents API behavior)
+11. Error: Duplicate node names (documents API behavior)
+12. Error: Invalid connection references (documents API behavior)
+13. Edge case: Minimal single node workflow
+14. Edge case: Empty connections object
+15. Edge case: Workflow without settings
 
 ---
 
 ### Phase 3: Workflow Retrieval Tests (P1)
 
-**Branch**: `feat/integration-tests-workflow-retrieval`
+**Branch**: `feat/integration-tests-phase-3`
+
+**Test Approach**: Tests MCP handlers (`handleGetWorkflow`, `handleGetWorkflowDetails`, `handleGetWorkflowStructure`, `handleGetWorkflowMinimal`)
+
+**MCP Handler Pattern:**
+```typescript
+import {
+  handleGetWorkflow,
+  handleGetWorkflowDetails,
+  handleGetWorkflowStructure,
+  handleGetWorkflowMinimal
+} from '../../../../src/mcp/handlers-n8n-manager';
+
+// Test MCP handler
+const response = await handleGetWorkflow({ id: workflowId }, mcpContext);
+expect(response.success).toBe(true);
+const workflow = response.data;
+
+// Note: handleGetWorkflowDetails returns nested structure
+const detailsResponse = await handleGetWorkflowDetails({ id }, mcpContext);
+const workflow = detailsResponse.data.workflow;  // Extract from nested structure
+const stats = detailsResponse.data.executionStats;
+```
 
 **Files**:
-- `get-workflow.test.ts` (3 scenarios)
-- `get-workflow-details.test.ts` (4 scenarios)
-- `get-workflow-structure.test.ts` (2 scenarios)
-- `get-workflow-minimal.test.ts` (2 scenarios)
+- `get-workflow.test.ts` (3 scenarios - tests handleGetWorkflow)
+- `get-workflow-details.test.ts` (4 scenarios - tests handleGetWorkflowDetails)
+- `get-workflow-structure.test.ts` (2 scenarios - tests handleGetWorkflowStructure)
+- `get-workflow-minimal.test.ts` (2 scenarios - tests handleGetWorkflowMinimal)
 
 ---
 
@@ -739,13 +1031,35 @@ ${method} Method:
 
 ---
 
-### Phase 6: Validation & Autofix Tests (P2)
+### Phase 6A: Workflow Validation Tests (P2) ✅ COMPLETE
 
-**Branch**: `feat/integration-tests-validation`
+**Branch**: `feat/integration-tests-phase-6`
 
 **Files**:
-- `validate-workflow.test.ts` (16 scenarios: 4 profiles × 4 validation types)
-- `autofix-workflow.test.ts` (20+ scenarios: 5 fix types × confidence levels)
+- ✅ `tests/integration/n8n-api/utils/node-repository.ts` - NodeRepository singleton for validation tests
+- ✅ `validate-workflow.test.ts` (12 scenarios: 4 profiles + invalid detection + selective validation + error handling)
+
+**Implementation Notes**:
+- Created NodeRepository utility since handleValidateWorkflow requires repository parameter
+- Tests cover all 4 validation profiles (strict, runtime, ai-friendly, minimal)
+- Invalid workflow detection tests (bad node types, missing connections)
+- Selective validation tests (nodes only, connections only, expressions only)
+- Response structure correctly handles conditional errors/warnings fields
+
+### Phase 6B: Workflow Autofix Tests (P2)
+
+**Branch**: `feat/integration-tests-phase-6b` (or continue on `feat/integration-tests-phase-6`)
+
+**Files**:
+- `autofix-workflow.test.ts` (15-20 scenarios: 5 fix types × modes × confidence levels)
+
+**Test Coverage Required**:
+- 5 fix types: expression-format, typeversion-correction, error-output-config, node-type-correction, webhook-missing-path
+- Preview mode (applyFixes: false) vs Apply mode (applyFixes: true)
+- Confidence threshold filtering (high, medium, low)
+- maxFixes parameter limiting
+- Multiple fix types in single workflow
+- No fixes available scenario
 
 ---
 
@@ -818,12 +1132,12 @@ jobs:
         env:
           N8N_URL: ${{ secrets.N8N_URL }}
           N8N_API_KEY: ${{ secrets.N8N_API_KEY }}
-          N8N_TEST_WEBHOOK_GET_ID: ${{ secrets.N8N_TEST_WEBHOOK_GET_ID }}
-          N8N_TEST_WEBHOOK_POST_ID: ${{ secrets.N8N_TEST_WEBHOOK_POST_ID }}
-          N8N_TEST_WEBHOOK_PUT_ID: ${{ secrets.N8N_TEST_WEBHOOK_PUT_ID }}
-          N8N_TEST_WEBHOOK_DELETE_ID: ${{ secrets.N8N_TEST_WEBHOOK_DELETE_ID }}
+          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 }}
           CI: true
-        run: npm run test:integration
+        run: npm run test:integration:n8n
 
       - name: Cleanup orphaned workflows
         if: always()
@@ -871,48 +1185,79 @@ jobs:
 2. ✅ Start n8n instance: `npx n8n start`
 3. ✅ Create 4 webhook workflows (GET, POST, PUT, DELETE)
 4. ✅ Activate all 4 webhook workflows in n8n UI
-5. ✅ Get workflow IDs from n8n UI
+5. ✅ Get webhook URLs from the workflow's Webhook node
 6. ✅ Copy `.env.example` to `.env`
-7. ✅ Set `N8N_API_URL=http://localhost:5678`
+7. ✅ Set `N8N_API_URL=<your-n8n-url>`
 8. ✅ Generate API key in n8n Settings > API
 9. ✅ Set `N8N_API_KEY=<your-key>`
-10. ✅ Set all 4 `N8N_TEST_WEBHOOK_*_ID` variables
+10. ✅ Set all 4 `N8N_TEST_WEBHOOK_*_URL` variables with full webhook URLs
 
-### CI/GitHub Actions
-1. ✅ Set up cloud n8n instance (or self-hosted)
+### CI/GitHub Actions (✅ COMPLETED)
+1. ✅ Set up cloud n8n instance: `https://n8n-test.n8n-mcp.com`
 2. ✅ Create 4 webhook workflows (GET, POST, PUT, DELETE)
 3. ✅ Activate all 4 webhook workflows
 4. ✅ Add GitHub secrets: `N8N_URL`, `N8N_API_KEY`
-5. ✅ Add webhook workflow ID secrets (4 total)
+5. ✅ Add webhook URL secrets:
+   - `N8N_TEST_WEBHOOK_GET_URL=https://n8n-test.n8n-mcp.com/webhook/mcp-test-get`
+   - `N8N_TEST_WEBHOOK_POST_URL=https://n8n-test.n8n-mcp.com/webhook/mcp-test-post`
+   - `N8N_TEST_WEBHOOK_PUT_URL=https://n8n-test.n8n-mcp.com/webhook/mcp-test-put`
+   - `N8N_TEST_WEBHOOK_DELETE_URL=https://n8n-test.n8n-mcp.com/webhook/mcp-test-delete`
 
 ---
 
 ## Success Criteria
 
-- ✅ All 17 handlers have integration tests
-- ✅ All operations/parameters covered (150+ scenarios)
-- ✅ Tests run successfully locally and in CI
+### Phase 1: Foundation ✅ COMPLETE
+- ✅ Environment configuration (.env, GitHub secrets)
+- ✅ All utility files created (8 files, ~1,520 lines of code)
+- ✅ Pre-activated webhook workflows created and tested
+- ✅ Cleanup helpers with pagination safety
+- ✅ Resource tracking with TestContext
+- ✅ Fixtures and factories for test data
+- ✅ Documentation updated
+- ✅ Environment loading fixed (loads .env before test defaults)
+- ✅ Vitest integration config updated (removed MSW for n8n-api tests)
+
+### Phase 2: Workflow Creation Tests ✅ COMPLETE
+- ✅ 15 test scenarios implemented (all passing)
+- ✅ Tests the `handleCreateWorkflow` MCP handler (product layer)
+- ✅ All tests use MCP handler pattern with McpToolResponse validation
+- ✅ P0 bug verification (FULL vs SHORT node type format)
+- ✅ Base node tests (webhook, HTTP, langchain, multi-node)
+- ✅ Advanced features (connections, settings, expressions, error handling)
+- ✅ Error scenarios (4 tests documenting actual API behavior)
+- ✅ Edge cases (3 tests for minimal/empty configurations)
+- ✅ Test file: 563 lines covering all handleCreateWorkflow scenarios
+- ✅ All tests passing against real n8n instance
+
+### Overall Project (In Progress)
+- ⏳ All 17 handlers have integration tests (11 of 17 complete)
+- ⏳ All operations/parameters covered (99 of 150+ scenarios complete)
+- ✅ Tests run successfully locally (Phases 1-6 verified)
+- ⏳ Tests run successfully in CI (pending Phase 9)
 - ✅ No manual cleanup required (automatic)
-- ✅ Test coverage catches P0-level bugs
-- ✅ CI runs on every PR and daily
+- ✅ Test coverage catches P0-level bugs (verified in Phase 2)
+- ⏳ CI runs on every PR and daily (pending Phase 9)
 - ✅ Clear error messages when tests fail
 - ✅ Documentation for webhook workflow setup
+- ✅ Code quality maintained (lint, typecheck, type safety)
 
 ---
 
 ## Timeline Estimate
 
-- **Phase 1 (Foundation)**: 2-3 days
-- **Phase 2 (Workflow Creation)**: 1 day
-- **Phase 3 (Retrieval)**: 1 day
-- **Phase 4 (Updates)**: 2-3 days (15 operations)
-- **Phase 5 (Management)**: 1 day
-- **Phase 6 (Validation)**: 2 days
+- **Phase 1 (Foundation)**: ✅ COMPLETE (October 3, 2025)
+- **Phase 2 (Workflow Creation)**: ✅ COMPLETE (October 3, 2025)
+- **Phase 3 (Retrieval)**: ✅ COMPLETE (October 3, 2025)
+- **Phase 4 (Updates)**: ✅ COMPLETE (October 4, 2025)
+- **Phase 5 (Management)**: ✅ COMPLETE (October 4, 2025)
+- **Phase 6A (Validation)**: ✅ COMPLETE (October 5, 2025)
+- **Phase 6B (Autofix)**: ✅ COMPLETE (October 5, 2025)
 - **Phase 7 (Executions)**: 2 days
 - **Phase 8 (System)**: 1 day
 - **Phase 9 (CI/CD)**: 1 day
 
-**Total**: ~14-18 days
+**Total**: 6 days complete, ~4 days remaining
 
 ---
 
@@ -922,3 +1267,40 @@ jobs:
 - Phases can be parallelized where dependencies allow
 - Run local tests frequently to catch issues early
 - Document any n8n API quirks discovered during testing
+
+## Key Learnings from Implementation
+
+### Critical Testing Principle: Test the Product Layer
+
+**The Mistake**: Initially, Phase 2 tests called `client.createWorkflow()` (raw API client) instead of `handleCreateWorkflow()` (MCP handler).
+
+**Why This Was Wrong**:
+- AI assistants interact with MCP handlers, not raw API client
+- MCP handlers wrap responses in `McpToolResponse` format
+- MCP handlers may transform/enrich API responses
+- Bypassing MCP layer misses product-specific logic and bugs
+
+**The Fix**: All tests updated to use MCP handlers:
+```typescript
+// ❌ BEFORE: Testing wrong layer
+const result = await client.createWorkflow(workflow);
+
+// ✅ AFTER: Testing the actual product
+const response = await handleCreateWorkflow({ ...workflow }, mcpContext);
+expect(response.success).toBe(true);
+const result = response.data;
+```
+
+**Lesson Learned**: Always test the layer closest to the user/consumer. For n8n-mcp, that's the MCP handler layer.
+
+### n8n API Behavior Discoveries
+1. **Validation Timing**: n8n API accepts workflows with invalid node types and connection references at creation time. Validation only happens at execution time.
+2. **Node Type Format**: FULL node type format (`n8n-nodes-base.*`) must be used in API requests. The P0 bug was confirmed fixed.
+3. **Missing Parameters**: n8n accepts workflows with missing required parameters. They fail during execution, not creation.
+4. **Duplicate Names**: n8n API handles duplicate node names gracefully (may auto-rename).
+
+### Technical Implementation Insights
+1. **MSW Interference**: Integration tests that need real network requests must NOT load MSW setup. Removed from vitest.config.integration.ts.
+2. **Environment Loading**: Must load `.env` file BEFORE test defaults in global setup to preserve real credentials.
+3. **Cleanup Safety**: TestContext pattern works well for tracking and cleaning up test resources.
+4. **Test Isolation**: Each test creates unique workflows with timestamps to avoid conflicts.

docs/mcp-tools-documentation.md

@@ -1,712 +0,0 @@
-# MCP Tools Documentation for LLMs
-
-This document provides comprehensive documentation for the most commonly used MCP tools in the n8n-mcp server. Each tool includes parameters, return formats, examples, and best practices.
-
-## Table of Contents
-1. [search_nodes](#search_nodes)
-2. [get_node_essentials](#get_node_essentials)
-3. [list_nodes](#list_nodes)
-4. [validate_node_minimal](#validate_node_minimal)
-5. [validate_node_operation](#validate_node_operation)
-6. [get_node_for_task](#get_node_for_task)
-7. [n8n_create_workflow](#n8n_create_workflow)
-8. [n8n_update_partial_workflow](#n8n_update_partial_workflow)
-
----
-
-## search_nodes
-
-**Brief Description**: Search for n8n nodes by keywords in names and descriptions.
-
-### Parameters
-- `query` (string, required): Search term - single word recommended for best results
-- `limit` (number, optional): Maximum results to return (default: 20)
-
-### Return Format
-```json
-{
-  "nodes": [
-    {
-      "nodeType": "nodes-base.slack",
-      "displayName": "Slack",
-      "description": "Send messages to Slack channels"
-    }
-  ],
-  "totalFound": 5
-}
-```
-
-### Common Use Cases
-1. **Finding integration nodes**: `search_nodes("slack")` to find Slack integration
-2. **Finding HTTP nodes**: `search_nodes("http")` for HTTP/webhook nodes
-3. **Finding database nodes**: `search_nodes("postgres")` for PostgreSQL nodes
-
-### Examples
-```json
-// Search for Slack-related nodes
-{
-  "query": "slack",
-  "limit": 10
-}
-
-// Search for webhook nodes
-{
-  "query": "webhook",
-  "limit": 20
-}
-```
-
-### Performance Notes
-- Fast operation (cached results)
-- Single-word queries are more precise
-- Returns results with OR logic (any word matches)
-
-### Best Practices
-- Use single words for precise results: "slack" not "send slack message"
-- Try shorter terms if no results: "sheet" instead of "spreadsheet"
-- Search is case-insensitive
-- Common searches: "http", "webhook", "email", "database", "slack"
-
-### Common Pitfalls
-- Multi-word searches return too many results (OR logic)
-- Searching for exact phrases doesn't work
-- Node types aren't searchable here (use exact type with get_node_info)
-
-### Related Tools
-- `list_nodes` - Browse nodes by category
-- `get_node_essentials` - Get node configuration after finding it
-- `list_ai_tools` - Find AI-capable nodes specifically
-
----
-
-## get_node_essentials
-
-**Brief Description**: Get only the 10-20 most important properties for a node with working examples.
-
-### Parameters
-- `nodeType` (string, required): Full node type with prefix (e.g., "nodes-base.httpRequest")
-
-### Return Format
-```json
-{
-  "nodeType": "nodes-base.httpRequest",
-  "displayName": "HTTP Request",
-  "essentialProperties": [
-    {
-      "name": "method",
-      "type": "options",
-      "default": "GET",
-      "options": ["GET", "POST", "PUT", "DELETE"],
-      "required": true
-    },
-    {
-      "name": "url",
-      "type": "string",
-      "required": true,
-      "placeholder": "https://api.example.com/endpoint"
-    }
-  ],
-  "examples": [
-    {
-      "name": "Simple GET Request",
-      "configuration": {
-        "method": "GET",
-        "url": "https://api.example.com/users"
-      }
-    }
-  ],
-  "tips": [
-    "Use expressions like {{$json.url}} to make URLs dynamic",
-    "Enable 'Split Into Items' for array responses"
-  ]
-}
-```
-
-### Common Use Cases
-1. **Quick node configuration**: Get just what you need without parsing 100KB+ of data
-2. **Learning node basics**: Understand essential properties with examples
-3. **Building workflows efficiently**: 95% smaller responses than get_node_info
-
-### Examples
-```json
-// Get essentials for HTTP Request node
-{
-  "nodeType": "nodes-base.httpRequest"
-}
-
-// Get essentials for Slack node
-{
-  "nodeType": "nodes-base.slack"
-}
-
-// Get essentials for OpenAI node
-{
-  "nodeType": "nodes-langchain.openAi"
-}
-```
-
-### Performance Notes
-- Very fast (<5KB responses vs 100KB+ for full info)
-- Curated for 20+ common nodes
-- Automatic fallback for unconfigured nodes
-
-### Best Practices
-- Always use this before get_node_info
-- Node type must include prefix: "nodes-base.slack" not "slack"
-- Check examples section for working configurations
-- Use tips section for common patterns
-
-### Common Pitfalls
-- Forgetting the prefix in node type
-- Using wrong package name (n8n-nodes-base vs @n8n/n8n-nodes-langchain)
-- Case sensitivity in node types
-
-### Related Tools
-- `get_node_info` - Full schema when essentials aren't enough
-- `search_node_properties` - Find specific properties
-- `get_node_for_task` - Pre-configured for common tasks
-
----
-
-## list_nodes
-
-**Brief Description**: List available n8n nodes with optional filtering by package, category, or capabilities.
-
-### Parameters
-- `package` (string, optional): Filter by exact package name
-- `category` (string, optional): Filter by category (trigger, transform, output, input)
-- `developmentStyle` (string, optional): Filter by implementation style
-- `isAITool` (boolean, optional): Filter for AI-capable nodes
-- `limit` (number, optional): Maximum results (default: 50, max: 500)
-
-### Return Format
-```json
-{
-  "nodes": [
-    {
-      "nodeType": "nodes-base.webhook",
-      "displayName": "Webhook",
-      "description": "Receive HTTP requests",
-      "categories": ["trigger"],
-      "version": 2
-    }
-  ],
-  "total": 104,
-  "hasMore": false
-}
-```
-
-### Common Use Cases
-1. **Browse all triggers**: `list_nodes({category: "trigger", limit: 200})`
-2. **List all nodes**: `list_nodes({limit: 500})`
-3. **Find AI nodes**: `list_nodes({isAITool: true})`
-4. **Browse core nodes**: `list_nodes({package: "n8n-nodes-base"})`
-
-### Examples
-```json
-// List all trigger nodes
-{
-  "category": "trigger",
-  "limit": 200
-}
-
-// List all AI-capable nodes
-{
-  "isAITool": true,
-  "limit": 100
-}
-
-// List nodes from core package
-{
-  "package": "n8n-nodes-base",
-  "limit": 200
-}
-```
-
-### Performance Notes
-- Fast operation (cached results)
-- Default limit of 50 may miss nodes - use 200+
-- Returns metadata only, not full schemas
-
-### Best Practices
-- Always set limit to 200+ for complete results
-- Use exact package names: "n8n-nodes-base" not "@n8n/n8n-nodes-base"
-- Categories are singular: "trigger" not "triggers"
-- Common categories: trigger (104), transform, output, input
-
-### Common Pitfalls
-- Default limit (50) misses many nodes
-- Using wrong package name format
-- Multiple filters may return empty results
-
-### Related Tools
-- `search_nodes` - Search by keywords
-- `list_ai_tools` - Specifically for AI nodes
-- `get_database_statistics` - Overview of all nodes
-
----
-
-## validate_node_minimal
-
-**Brief Description**: Quick validation checking only for missing required fields.
-
-### Parameters
-- `nodeType` (string, required): Node type to validate (e.g., "nodes-base.slack")
-- `config` (object, required): Node configuration to check
-
-### Return Format
-```json
-{
-  "valid": false,
-  "missingRequired": ["channel", "messageType"],
-  "message": "Missing 2 required fields"
-}
-```
-
-### Common Use Cases
-1. **Quick validation**: Check if all required fields are present
-2. **Pre-flight check**: Validate before creating workflow
-3. **Minimal overhead**: Fastest validation option
-
-### Examples
-```json
-// Validate Slack message configuration
-{
-  "nodeType": "nodes-base.slack",
-  "config": {
-    "resource": "message",
-    "operation": "send",
-    "text": "Hello World"
-    // Missing: channel
-  }
-}
-
-// Validate HTTP Request
-{
-  "nodeType": "nodes-base.httpRequest",
-  "config": {
-    "method": "POST"
-    // Missing: url
-  }
-}
-```
-
-### Performance Notes
-- Fastest validation option
-- No schema loading overhead
-- Returns only missing fields
-
-### Best Practices
-- Use for quick checks during workflow building
-- Follow up with validate_node_operation for complex nodes
-- Check operation-specific requirements
-
-### Common Pitfalls
-- Doesn't validate field values or types
-- Doesn't check operation-specific requirements
-- Won't catch configuration errors beyond missing fields
-
-### Related Tools
-- `validate_node_operation` - Comprehensive validation
-- `validate_workflow` - Full workflow validation
-
----
-
-## validate_node_operation
-
-**Brief Description**: Comprehensive node configuration validation with operation awareness and helpful error messages.
-
-### Parameters
-- `nodeType` (string, required): Node type to validate
-- `config` (object, required): Complete node configuration including operation fields
-- `profile` (string, optional): Validation profile (minimal, runtime, ai-friendly, strict)
-
-### Return Format
-```json
-{
-  "valid": false,
-  "errors": [
-    {
-      "field": "channel",
-      "message": "Channel is required to send Slack message",
-      "suggestion": "Add channel: '#general' or '@username'"
-    }
-  ],
-  "warnings": [
-    {
-      "field": "unfurl_links",
-      "message": "Consider setting unfurl_links: false for better performance"
-    }
-  ],
-  "examples": {
-    "minimal": {
-      "resource": "message",
-      "operation": "send",
-      "channel": "#general",
-      "text": "Hello World"
-    }
-  }
-}
-```
-
-### Common Use Cases
-1. **Complex node validation**: Slack, Google Sheets, databases
-2. **Operation-specific checks**: Different rules per operation
-3. **Getting fix suggestions**: Helpful error messages with solutions
-
-### Examples
-```json
-// Validate Slack configuration
-{
-  "nodeType": "nodes-base.slack",
-  "config": {
-    "resource": "message",
-    "operation": "send",
-    "text": "Hello team!"
-  },
-  "profile": "ai-friendly"
-}
-
-// Validate Google Sheets operation
-{
-  "nodeType": "nodes-base.googleSheets",
-  "config": {
-    "operation": "append",
-    "sheetId": "1234567890",
-    "range": "Sheet1!A:Z"
-  },
-  "profile": "runtime"
-}
-```
-
-### Performance Notes
-- Slower than minimal validation
-- Loads full node schema
-- Operation-aware validation rules
-
-### Best Practices
-- Use "ai-friendly" profile for balanced validation
-- Check examples in response for working configurations
-- Follow suggestions to fix errors
-- Essential for complex nodes (Slack, databases, APIs)
-
-### Common Pitfalls
-- Forgetting operation fields (resource, operation, action)
-- Using wrong profile (too strict or too lenient)
-- Ignoring warnings that could cause runtime issues
-
-### Related Tools
-- `validate_node_minimal` - Quick required field check
-- `get_property_dependencies` - Understand field relationships
-- `validate_workflow` - Validate entire workflow
-
----
-
-## get_node_for_task
-
-**Brief Description**: Get pre-configured node settings for common automation tasks.
-
-### Parameters
-- `task` (string, required): Task identifier (e.g., "post_json_request", "receive_webhook")
-
-### Return Format
-```json
-{
-  "task": "post_json_request",
-  "nodeType": "nodes-base.httpRequest",
-  "displayName": "HTTP Request",
-  "configuration": {
-    "method": "POST",
-    "url": "={{ $json.api_endpoint }}",
-    "responseFormat": "json",
-    "options": {
-      "bodyContentType": "json"
-    },
-    "bodyParametersJson": "={{ JSON.stringify($json) }}"
-  },
-  "userMustProvide": [
-    "url - The API endpoint URL",
-    "bodyParametersJson - The JSON data to send"
-  ],
-  "tips": [
-    "Use expressions to make values dynamic",
-    "Enable 'Split Into Items' for batch processing"
-  ]
-}
-```
-
-### Common Use Cases
-1. **Quick task setup**: Configure nodes for specific tasks instantly
-2. **Learning patterns**: See how to configure nodes properly
-3. **Common workflows**: Standard patterns like webhooks, API calls, database queries
-
-### Examples
-```json
-// Get configuration for JSON POST request
-{
-  "task": "post_json_request"
-}
-
-// Get webhook receiver configuration
-{
-  "task": "receive_webhook"
-}
-
-// Get AI chat configuration
-{
-  "task": "chat_with_ai"
-}
-```
-
-### Performance Notes
-- Instant response (pre-configured templates)
-- No database lookups required
-- Includes working examples
-
-### Best Practices
-- Use list_tasks first to see available options
-- Check userMustProvide section
-- Follow tips for best results
-- Common tasks: API calls, webhooks, database queries, AI chat
-
-### Common Pitfalls
-- Not all tasks available (use list_tasks)
-- Configuration needs customization
-- Some fields still need user input
-
-### Related Tools
-- `list_tasks` - See all available tasks
-- `get_node_essentials` - Alternative approach
-- `search_templates` - Find complete workflow templates
-
----
-
-## n8n_create_workflow
-
-**Brief Description**: Create a new workflow in n8n with nodes and connections.
-
-### Parameters
-- `name` (string, required): Workflow name
-- `nodes` (array, required): Array of node definitions
-- `connections` (object, required): Node connections mapping
-- `settings` (object, optional): Workflow settings
-
-### Return Format
-```json
-{
-  "id": "workflow-uuid",
-  "name": "My Workflow",
-  "active": false,
-  "createdAt": "2024-01-15T10:30:00Z",
-  "updatedAt": "2024-01-15T10:30:00Z",
-  "nodes": [...],
-  "connections": {...}
-}
-```
-
-### Common Use Cases
-1. **Automated workflow creation**: Build workflows programmatically
-2. **Template deployment**: Deploy pre-built workflow patterns
-3. **Multi-workflow systems**: Create interconnected workflows
-
-### Examples
-```json
-// Create simple webhook → HTTP request workflow
-{
-  "name": "Webhook to API",
-  "nodes": [
-    {
-      "id": "webhook-1",
-      "name": "Webhook",
-      "type": "n8n-nodes-base.webhook",
-      "typeVersion": 2,
-      "position": [250, 300],
-      "parameters": {
-        "path": "/my-webhook",
-        "httpMethod": "POST"
-      }
-    },
-    {
-      "id": "http-1",
-      "name": "HTTP Request",
-      "type": "n8n-nodes-base.httpRequest",
-      "typeVersion": 4.2,
-      "position": [450, 300],
-      "parameters": {
-        "method": "POST",
-        "url": "https://api.example.com/process",
-        "responseFormat": "json"
-      }
-    }
-  ],
-  "connections": {
-    "Webhook": {
-      "main": [[{"node": "HTTP Request", "type": "main", "index": 0}]]
-    }
-  }
-}
-```
-
-### Performance Notes
-- API call to n8n instance required
-- Workflow created in inactive state
-- Must be manually activated in UI
-
-### Best Practices
-- Always include typeVersion for nodes
-- Use node names (not IDs) in connections
-- Position nodes logically ([x, y] coordinates)
-- Test with validate_workflow first
-- Start simple, add complexity gradually
-
-### Common Pitfalls
-- Missing typeVersion causes errors
-- Using node IDs instead of names in connections
-- Forgetting required node properties
-- Creating cycles in connections
-- Workflow can't be activated via API
-
-### Related Tools
-- `validate_workflow` - Validate before creating
-- `n8n_update_partial_workflow` - Modify existing workflows
-- `n8n_trigger_webhook_workflow` - Execute workflows
-
----
-
-## n8n_update_partial_workflow
-
-**Brief Description**: Update workflows using diff operations for precise, incremental changes without sending the entire workflow.
-
-### Parameters
-- `id` (string, required): Workflow ID to update
-- `operations` (array, required): Array of diff operations (max 5)
-- `validateOnly` (boolean, optional): Test without applying changes
-
-### Return Format
-```json
-{
-  "success": true,
-  "workflow": {
-    "id": "workflow-uuid",
-    "name": "Updated Workflow",
-    "nodes": [...],
-    "connections": {...}
-  },
-  "appliedOperations": 3
-}
-```
-
-### Common Use Cases
-1. **Add nodes to existing workflows**: Insert new functionality
-2. **Update node configurations**: Change parameters without full replacement
-3. **Manage connections**: Add/remove node connections
-4. **Quick edits**: Rename, enable/disable nodes, update settings
-
-### Examples
-```json
-// Add a new node and connect it
-{
-  "id": "workflow-123",
-  "operations": [
-    {
-      "type": "addNode",
-      "node": {
-        "id": "set-1",
-        "name": "Set Data",
-        "type": "n8n-nodes-base.set",
-        "typeVersion": 3,
-        "position": [600, 300],
-        "parameters": {
-          "values": {
-            "string": [{
-              "name": "status",
-              "value": "processed"
-            }]
-          }
-        }
-      }
-    },
-    {
-      "type": "addConnection",
-      "source": "HTTP Request",
-      "target": "Set Data"
-    }
-  ]
-}
-
-// Update multiple properties
-{
-  "id": "workflow-123",
-  "operations": [
-    {
-      "type": "updateName",
-      "name": "Production Workflow v2"
-    },
-    {
-      "type": "updateNode",
-      "nodeName": "Webhook",
-      "changes": {
-        "parameters.path": "/v2/webhook"
-      }
-    },
-    {
-      "type": "addTag",
-      "tag": "production"
-    }
-  ]
-}
-```
-
-### Performance Notes
-- 80-90% token savings vs full updates
-- Maximum 5 operations per request
-- Two-pass processing handles dependencies
-- Transactional: all or nothing
-
-### Best Practices
-- Use validateOnly: true to test first
-- Keep operations under 5 for reliability
-- Operations can be in any order (v2.7.0+)
-- Use node names, not IDs in operations
-- For updateNode, use dot notation for nested paths
-
-### Common Pitfalls
-- Exceeding 5 operations limit
-- Using node IDs instead of names
-- Forgetting required node properties in addNode
-- Not testing with validateOnly first
-
-### Related Tools
-- `n8n_update_full_workflow` - Complete workflow replacement
-- `n8n_get_workflow` - Fetch current workflow state
-- `validate_workflow` - Validate changes before applying
-
----
-
-## Quick Reference
-
-### Workflow Building Process
-1. **Discovery**: `search_nodes` → `list_nodes`
-2. **Configuration**: `get_node_essentials` → `get_node_for_task`
-3. **Validation**: `validate_node_minimal` → `validate_node_operation`
-4. **Creation**: `validate_workflow` → `n8n_create_workflow`
-5. **Updates**: `n8n_update_partial_workflow`
-
-### Performance Tips
-- Use `get_node_essentials` instead of `get_node_info` (95% smaller)
-- Set high limits on `list_nodes` (200+)
-- Use single words in `search_nodes`
-- Validate incrementally while building
-
-### Common Node Types
-- **Triggers**: webhook, schedule, emailReadImap, slackTrigger
-- **Core**: httpRequest, code, set, if, merge, splitInBatches
-- **Integrations**: slack, gmail, googleSheets, postgres, mongodb
-- **AI**: agent, openAi, chainLlm, documentLoader
-
-### Error Prevention
-- Always include node type prefixes: "nodes-base.slack"
-- Use node names (not IDs) in connections
-- Include typeVersion in all nodes
-- Test with validateOnly before applying changes
-- Check userMustProvide sections in templates

docs/n8n-integration-implementation-plan.md

@@ -1,514 +0,0 @@
-# n8n MCP Client Tool Integration - Implementation Plan (Simplified)
-
-## Overview
-
-This document provides a **simplified** implementation plan for making n8n-mcp compatible with n8n's MCP Client Tool (v1.1). Based on expert review, we're taking a minimal approach that extends the existing single-session server rather than creating new architecture.
-
-## Key Design Principles
-
-1. **Minimal Changes**: Extend existing single-session server with n8n compatibility mode
-2. **No Overengineering**: No complex session management or multi-session architecture
-3. **Docker-Native**: Separate Docker image for n8n deployment
-4. **Remote Deployment**: Designed to run alongside n8n in production
-5. **Backward Compatible**: Existing functionality remains unchanged
-
-## Prerequisites
-
-- Docker and Docker Compose
-- n8n version 1.104.2 or higher (with MCP Client Tool v1.1)
-- Basic understanding of Docker networking
-
-## Implementation Approach
-
-Instead of creating new multi-session architecture, we'll extend the existing single-session server with an n8n compatibility mode. This approach was recommended by all three expert reviewers as simpler and more maintainable.
-
-## Architecture Changes
-
-```
-src/
-├── http-server-single-session.ts  # MODIFY: Add n8n mode flag
-└── mcp/
-    └── server.ts                  # NO CHANGES NEEDED
-
-Docker/
-├── Dockerfile.n8n                 # NEW: n8n-specific image
-├── docker-compose.n8n.yml         # NEW: Simplified stack
-└── .github/workflows/
-    └── docker-build-n8n.yml       # NEW: Build workflow
-```
-
-## Implementation Steps
-
-### Step 1: Modify Existing Single-Session Server
-
-#### 1.1 Update `src/http-server-single-session.ts`
-
-Add n8n compatibility mode to the existing server with minimal changes:
-
-```typescript
-// Add these constants at the top (after imports)
-const PROTOCOL_VERSION = "2024-11-05";
-const N8N_MODE = process.env.N8N_MODE === 'true';
-
-// In the constructor or start method, add logging
-if (N8N_MODE) {
-  logger.info('Running in n8n compatibility mode');
-}
-
-// In setupRoutes method, add the protocol version endpoint
-if (N8N_MODE) {
-  app.get('/mcp', (req, res) => {
-    res.json({
-      protocolVersion: PROTOCOL_VERSION,
-      serverInfo: {
-        name: "n8n-mcp",
-        version: PROJECT_VERSION,
-        capabilities: {
-          tools: true,
-          resources: false,
-          prompts: false,
-        },
-      },
-    });
-  });
-}
-
-// In handleMCPRequest method, add session header
-if (N8N_MODE && this.session) {
-  res.setHeader('Mcp-Session-Id', this.session.sessionId);
-}
-
-// Update error handling to use JSON-RPC format
-catch (error) {
-  logger.error('MCP request error:', error);
-  
-  if (N8N_MODE) {
-    res.status(500).json({
-      jsonrpc: '2.0',
-      error: {
-        code: -32603,
-        message: 'Internal error',
-        data: error instanceof Error ? error.message : 'Unknown error',
-      },
-      id: null,
-    });
-  } else {
-    // Keep existing error handling for backward compatibility
-    res.status(500).json({ 
-      error: 'Internal server error',
-      details: error instanceof Error ? error.message : 'Unknown error'
-    });
-  }
-}
-```
-
-That's it! No new files, no complex session management. Just a few lines of code.
-
-### Step 2: Update Package Scripts
-
-#### 2.1 Update `package.json`
-
-Add a simple script for n8n mode:
-
-```json
-{
-  "scripts": {
-    "start:n8n": "N8N_MODE=true MCP_MODE=http node dist/mcp/index.js"
-  }
-}
-```
-
-### Step 3: Create Docker Infrastructure for n8n
-
-#### 3.1 Create `Dockerfile.n8n`
-
-```dockerfile
-# Dockerfile.n8n - Optimized for n8n integration
-FROM node:22-alpine AS builder
-
-WORKDIR /app
-
-# Install build dependencies
-RUN apk add --no-cache python3 make g++
-
-# Copy package files
-COPY package*.json tsconfig*.json ./
-
-# Install ALL dependencies
-RUN npm ci --no-audit --no-fund
-
-# Copy source and build
-COPY src ./src
-RUN npm run build && npm run rebuild
-
-# Runtime stage
-FROM node:22-alpine
-
-WORKDIR /app
-
-# Install runtime dependencies
-RUN apk add --no-cache curl dumb-init
-
-# Create non-root user
-RUN addgroup -g 1001 -S nodejs && adduser -S nodejs -u 1001
-
-# Copy application from builder
-COPY --from=builder --chown=nodejs:nodejs /app/dist ./dist
-COPY --from=builder --chown=nodejs:nodejs /app/data ./data
-COPY --from=builder --chown=nodejs:nodejs /app/node_modules ./node_modules
-COPY --chown=nodejs:nodejs package.json ./
-
-USER nodejs
-
-EXPOSE 3001
-
-HEALTHCHECK CMD curl -f http://localhost:3001/health || exit 1
-
-ENTRYPOINT ["dumb-init", "--"]
-CMD ["node", "dist/mcp/index.js"]
-```
-
-#### 3.2 Create `docker-compose.n8n.yml`
-
-```yaml
-# docker-compose.n8n.yml - Simple stack for n8n + n8n-mcp
-version: '3.8'
-
-services:
-  n8n:
-    image: n8nio/n8n:latest
-    container_name: n8n
-    restart: unless-stopped
-    ports:
-      - "5678:5678"
-    environment:
-      - N8N_BASIC_AUTH_ACTIVE=${N8N_BASIC_AUTH_ACTIVE:-true}
-      - N8N_BASIC_AUTH_USER=${N8N_USER:-admin}
-      - N8N_BASIC_AUTH_PASSWORD=${N8N_PASSWORD:-changeme}
-      - N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true
-    volumes:
-      - n8n_data:/home/node/.n8n
-    networks:
-      - n8n-net
-    depends_on:
-      n8n-mcp:
-        condition: service_healthy
-
-  n8n-mcp:
-    image: ghcr.io/${GITHUB_USER:-czlonkowski}/n8n-mcp-n8n:latest
-    build:
-      context: .
-      dockerfile: Dockerfile.n8n
-    container_name: n8n-mcp
-    restart: unless-stopped
-    environment:
-      - MCP_MODE=http
-      - N8N_MODE=true
-      - AUTH_TOKEN=${MCP_AUTH_TOKEN}
-      - NODE_ENV=production
-      - HTTP_PORT=3001
-    networks:
-      - n8n-net
-    healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:3001/health"]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-
-networks:
-  n8n-net:
-    driver: bridge
-
-volumes:
-  n8n_data:
-```
-
-#### 3.3 Create `.env.n8n.example`
-
-```bash
-# .env.n8n.example - Copy to .env and configure
-
-# n8n Configuration
-N8N_USER=admin
-N8N_PASSWORD=changeme
-N8N_BASIC_AUTH_ACTIVE=true
-
-# MCP Configuration
-# Generate with: openssl rand -base64 32
-MCP_AUTH_TOKEN=your-secure-token-minimum-32-characters
-
-# GitHub username for image registry
-GITHUB_USER=czlonkowski
-```
-
-### Step 4: Create GitHub Actions Workflow
-
-#### 4.1 Create `.github/workflows/docker-build-n8n.yml`
-
-```yaml
-name: Build n8n Docker Image
-
-on:
-  push:
-    branches: [main]
-    tags: ['v*']
-    paths:
-      - 'src/**'
-      - 'package*.json'
-      - 'Dockerfile.n8n'
-  workflow_dispatch:
-
-env:
-  REGISTRY: ghcr.io
-  IMAGE_NAME: ${{ github.repository }}-n8n
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      packages: write
-      
-    steps:
-      - uses: actions/checkout@v4
-      
-      - uses: docker/setup-buildx-action@v3
-      
-      - uses: docker/login-action@v3
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-          
-      - uses: docker/metadata-action@v5
-        id: meta
-        with:
-          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
-          tags: |
-            type=ref,event=branch
-            type=semver,pattern={{version}}
-            type=raw,value=latest,enable={{is_default_branch}}
-            
-      - uses: docker/build-push-action@v5
-        with:
-          context: .
-          file: ./Dockerfile.n8n
-          push: true
-          tags: ${{ steps.meta.outputs.tags }}
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
-```
-
-### Step 5: Testing
-
-#### 5.1 Unit Tests for n8n Mode
-
-Create `tests/unit/http-server-n8n-mode.test.ts`:
-
-```typescript
-import { describe, it, expect, vi } from 'vitest';
-import request from 'supertest';
-
-describe('n8n Mode', () => {
-  it('should return protocol version on GET /mcp', async () => {
-    process.env.N8N_MODE = 'true';
-    const app = await createTestApp();
-    
-    const response = await request(app)
-      .get('/mcp')
-      .expect(200);
-    
-    expect(response.body.protocolVersion).toBe('2024-11-05');
-    expect(response.body.serverInfo.capabilities.tools).toBe(true);
-  });
-  
-  it('should include session ID in response headers', async () => {
-    process.env.N8N_MODE = 'true';
-    const app = await createTestApp();
-    
-    const response = await request(app)
-      .post('/mcp')
-      .set('Authorization', 'Bearer test-token')
-      .send({ jsonrpc: '2.0', method: 'initialize', id: 1 });
-    
-    expect(response.headers['mcp-session-id']).toBeDefined();
-  });
-  
-  it('should format errors as JSON-RPC', async () => {
-    process.env.N8N_MODE = 'true';
-    const app = await createTestApp();
-    
-    const response = await request(app)
-      .post('/mcp')
-      .send({ invalid: 'request' })
-      .expect(500);
-    
-    expect(response.body.jsonrpc).toBe('2.0');
-    expect(response.body.error.code).toBe(-32603);
-  });
-});
-```
-
-#### 5.2 Quick Deployment Script
-
-Create `deploy/quick-deploy-n8n.sh`:
-
-```bash
-#!/bin/bash
-set -e
-
-echo "🚀 Quick Deploy n8n + n8n-mcp"
-
-# Check prerequisites
-command -v docker >/dev/null 2>&1 || { echo "Docker required"; exit 1; }
-command -v docker-compose >/dev/null 2>&1 || { echo "Docker Compose required"; exit 1; }
-
-# Generate auth token if not exists
-if [ ! -f .env ]; then
-  cp .env.n8n.example .env
-  TOKEN=$(openssl rand -base64 32)
-  sed -i "s/your-secure-token-minimum-32-characters/$TOKEN/" .env
-  echo "Generated MCP_AUTH_TOKEN: $TOKEN"
-fi
-
-# Deploy
-docker-compose -f docker-compose.n8n.yml up -d
-
-echo ""
-echo "✅ Deployment complete!"
-echo ""
-echo "📋 Next steps:"
-echo "1. Access n8n at http://localhost:5678"
-echo "   Username: admin (or check .env)"
-echo "   Password: changeme (or check .env)"
-echo ""
-echo "2. Create a workflow with MCP Client Tool:"
-echo "   - Server URL: http://n8n-mcp:3001/mcp"
-echo "   - Authentication: Bearer Token"
-echo "   - Token: Check .env file for MCP_AUTH_TOKEN"
-echo ""
-echo "📊 View logs: docker-compose -f docker-compose.n8n.yml logs -f"
-echo "🛑 Stop: docker-compose -f docker-compose.n8n.yml down"
-```
-
-## Implementation Checklist (Simplified)
-
-### Code Changes
-- [ ] Add N8N_MODE flag to `http-server-single-session.ts`
-- [ ] Add protocol version endpoint (GET /mcp) when N8N_MODE=true
-- [ ] Add Mcp-Session-Id header to responses
-- [ ] Update error responses to JSON-RPC format when N8N_MODE=true
-- [ ] Add npm script `start:n8n` to package.json
-
-### Docker Infrastructure
-- [ ] Create `Dockerfile.n8n` for n8n-specific image
-- [ ] Create `docker-compose.n8n.yml` for simple deployment
-- [ ] Create `.env.n8n.example` template
-- [ ] Create GitHub Actions workflow `docker-build-n8n.yml`
-- [ ] Create `deploy/quick-deploy-n8n.sh` script
-
-### Testing
-- [ ] Write unit tests for n8n mode functionality
-- [ ] Test with actual n8n MCP Client Tool
-- [ ] Verify protocol version endpoint
-- [ ] Test authentication flow
-- [ ] Validate error formatting
-
-### Documentation
-- [ ] Update README with n8n deployment section
-- [ ] Document N8N_MODE environment variable
-- [ ] Add troubleshooting guide for common issues
-
-## Quick Start Guide
-
-### 1. One-Command Deployment
-
-```bash
-# Clone and deploy
-git clone https://github.com/czlonkowski/n8n-mcp.git
-cd n8n-mcp
-./deploy/quick-deploy-n8n.sh
-```
-
-### 2. Manual Configuration in n8n
-
-After deployment, configure the MCP Client Tool in n8n:
-
-1. Open n8n at `http://localhost:5678`
-2. Create a new workflow
-3. Add "MCP Client Tool" node (under AI category)
-4. Configure:
-   - **Server URL**: `http://n8n-mcp:3001/mcp`
-   - **Authentication**: Bearer Token
-   - **Token**: Check your `.env` file for MCP_AUTH_TOKEN
-5. Select a tool (e.g., `list_nodes`)
-6. Execute the workflow
-
-### 3. Production Deployment
-
-For production with SSL, use a reverse proxy:
-
-```nginx
-# nginx configuration
-server {
-    listen 443 ssl;
-    server_name n8n.yourdomain.com;
-    
-    location / {
-        proxy_pass http://localhost:5678;
-        proxy_http_version 1.1;
-        proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection "upgrade";
-    }
-}
-```
-
-The MCP server should remain internal only - n8n connects via Docker network.
-
-## Success Criteria
-
-The implementation is successful when:
-
-1. **Minimal Code Changes**: Only ~20 lines added to existing server
-2. **Protocol Compliance**: GET /mcp returns correct protocol version
-3. **n8n Connection**: MCP Client Tool connects successfully
-4. **Tool Execution**: Tools work without modification
-5. **Backward Compatible**: Existing Claude Desktop usage unaffected
-
-## Troubleshooting
-
-### Common Issues
-
-1. **"Protocol version mismatch"**
-   - Ensure N8N_MODE=true is set
-   - Check GET /mcp returns "2024-11-05"
-
-2. **"Authentication failed"**
-   - Verify AUTH_TOKEN matches in .env and n8n
-   - Token must be 32+ characters
-   - Use "Bearer Token" auth type in n8n
-
-3. **"Connection refused"**
-   - Check containers are on same network
-   - Use internal hostname: `http://n8n-mcp:3001/mcp`
-   - Verify health check passes
-
-4. **Testing the Setup**
-   ```bash
-   # Check protocol version
-   docker exec n8n-mcp curl http://localhost:3001/mcp
-   
-   # View logs
-   docker-compose -f docker-compose.n8n.yml logs -f n8n-mcp
-   ```
-
-## Summary
-
-This simplified approach:
-- **Extends existing code** rather than creating new architecture
-- **Adds n8n compatibility** with minimal changes
-- **Uses separate Docker image** for clean deployment
-- **Maintains backward compatibility** for existing users
-- **Avoids overengineering** with simple, practical solutions
-
-Total implementation effort: ~2-3 hours (vs. 2-3 days for multi-session approach)

docs/test-artifacts.md

@@ -1,146 +0,0 @@
-# Test Artifacts Documentation
-
-This document describes the comprehensive test result artifact storage system implemented in the n8n-mcp project.
-
-## Overview
-
-The test artifact system captures, stores, and presents test results in multiple formats to facilitate debugging, analysis, and historical tracking of test performance.
-
-## Artifact Types
-
-### 1. Test Results
-- **JUnit XML** (`test-results/junit.xml`): Standard format for CI integration
-- **JSON Results** (`test-results/results.json`): Detailed test data for analysis
-- **HTML Report** (`test-results/html/index.html`): Interactive test report
-- **Test Summary** (`test-summary.md`): Markdown summary for PR comments
-
-### 2. Coverage Reports
-- **LCOV** (`coverage/lcov.info`): Standard coverage format
-- **HTML Coverage** (`coverage/html/index.html`): Interactive coverage browser
-- **Coverage Summary** (`coverage/coverage-summary.json`): JSON coverage data
-
-### 3. Benchmark Results
-- **Benchmark JSON** (`benchmark-results.json`): Raw benchmark data
-- **Comparison Reports** (`benchmark-comparison.md`): PR benchmark comparisons
-
-### 4. Detailed Reports
-- **HTML Report** (`test-reports/report.html`): Comprehensive styled report
-- **Markdown Report** (`test-reports/report.md`): Full markdown report
-- **JSON Report** (`test-reports/report.json`): Complete test data
-
-## GitHub Actions Integration
-
-### Test Workflow (`test.yml`)
-
-The main test workflow:
-1. Runs tests with coverage using multiple reporters
-2. Generates test summaries and detailed reports
-3. Uploads artifacts with metadata
-4. Posts summaries to PRs
-5. Creates a combined artifact index
-
-### Benchmark PR Workflow (`benchmark-pr.yml`)
-
-For pull requests:
-1. Runs benchmarks on PR branch
-2. Runs benchmarks on base branch
-3. Compares results
-4. Posts comparison to PR
-5. Sets status checks for regressions
-
-## Artifact Retention
-
-- **Test Results**: 30 days
-- **Coverage Reports**: 30 days
-- **Benchmark Results**: 30 days
-- **Combined Results**: 90 days
-- **Test Metadata**: 30 days
-
-## PR Comment Integration
-
-The system automatically:
-- Posts test summaries to PR comments
-- Updates existing comments instead of creating duplicates
-- Includes links to full artifacts
-- Shows coverage and benchmark changes
-
-## Job Summary
-
-Each workflow run includes a job summary with:
-- Test results overview
-- Coverage summary
-- Benchmark results
-- Direct links to download artifacts
-
-## Local Development
-
-### Running Tests with Reports
-
-```bash
-# Run tests with all reporters
-CI=true npm run test:coverage
-
-# Generate detailed reports
-node scripts/generate-detailed-reports.js
-
-# Generate test summary
-node scripts/generate-test-summary.js
-
-# Compare benchmarks
-node scripts/compare-benchmarks.js benchmark-results.json benchmark-baseline.json
-```
-
-### Report Locations
-
-When running locally, reports are generated in:
-- `test-results/` - Vitest outputs
-- `test-reports/` - Detailed reports
-- `coverage/` - Coverage reports
-- Root directory - Summary files
-
-## Report Formats
-
-### HTML Report Features
-- Responsive design
-- Test suite breakdown
-- Failed test details with error messages
-- Coverage visualization with progress bars
-- Benchmark performance metrics
-- Sortable tables
-
-### Markdown Report Features
-- GitHub-compatible formatting
-- Summary statistics
-- Failed test listings
-- Coverage breakdown
-- Benchmark comparisons
-
-### JSON Report Features
-- Complete test data
-- Programmatic access
-- Historical comparison
-- CI/CD integration
-
-## Best Practices
-
-1. **Always Check Artifacts**: When tests fail in CI, download and review the HTML report
-2. **Monitor Coverage**: Use the coverage reports to identify untested code
-3. **Track Benchmarks**: Review benchmark comparisons on performance-critical PRs
-4. **Archive Important Runs**: Download artifacts from significant releases
-
-## Troubleshooting
-
-### Missing Artifacts
-- Check if tests ran to completion
-- Verify artifact upload steps executed
-- Check retention period hasn't expired
-
-### Report Generation Failures
-- Ensure all dependencies are installed
-- Check for valid test/coverage output files
-- Review workflow logs for errors
-
-### PR Comment Issues
-- Verify GitHub Actions permissions
-- Check bot authentication
-- Review comment posting logs

docs/testing-architecture.md

@@ -1,802 +0,0 @@
-# n8n-MCP Testing Architecture
-
-## 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.
-
-### Test Suite Statistics (from CI Run #41)
-
-- **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**: 
-  - 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)
-- **CI/CD Pipeline**: Fully automated with GitHub Actions
-- **Test Artifacts**: JUnit XML, coverage reports, benchmark results
-- **Parallel Execution**: Configurable with thread pool
-
-## Testing Framework: Vitest
-
-We use **Vitest** as our primary testing framework, chosen for its:
-- **Speed**: Native ESM support and fast execution
-- **TypeScript Integration**: First-class TypeScript support
-- **Watch Mode**: Instant feedback during development
-- **Jest Compatibility**: Easy migration from Jest
-- **Built-in Mocking**: Powerful mocking capabilities
-- **Coverage**: Integrated code coverage with v8
-
-### Configuration
-
-```typescript
-// vitest.config.ts
-export default defineConfig({
-  test: {
-    globals: true,
-    environment: 'node',
-    setupFiles: ['./tests/setup/global-setup.ts'],
-    pool: 'threads',
-    poolOptions: {
-      threads: {
-        singleThread: process.env.TEST_PARALLEL !== 'true',
-        maxThreads: parseInt(process.env.TEST_MAX_WORKERS || '4', 10)
-      }
-    },
-    coverage: {
-      provider: 'v8',
-      reporter: ['lcov', 'html', 'text-summary'],
-      exclude: ['node_modules/', 'tests/', '**/*.test.ts', 'scripts/']
-    }
-  },
-  resolve: {
-    alias: {
-      '@': path.resolve(__dirname, './src'),
-      '@tests': path.resolve(__dirname, './tests')
-    }
-  }
-});
-```
-
-## Directory Structure
-
-```
-tests/
-├── unit/                        # Unit tests with mocks (933 tests, 30 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
-│   ├── loaders/                # Node loader tests
-│   │   └── node-loader.test.ts
-│   ├── mappers/                # Data mapper tests
-│   │   └── docs-mapper.test.ts
-│   ├── mcp/                    # MCP server and tools tests
-│   │   ├── handlers-n8n-manager.test.ts
-│   │   ├── handlers-workflow-diff.test.ts
-│   │   ├── tools-documentation.test.ts
-│   │   └── tools.test.ts
-│   ├── parsers/                # Parser tests
-│   │   ├── node-parser.test.ts
-│   │   ├── property-extractor.test.ts
-│   │   └── simple-parser.test.ts
-│   ├── services/               # Service layer tests (largest test suite)
-│   │   ├── config-validator.test.ts
-│   │   ├── enhanced-config-validator.test.ts
-│   │   ├── example-generator.test.ts
-│   │   ├── expression-validator.test.ts
-│   │   ├── n8n-api-client.test.ts
-│   │   ├── n8n-validation.test.ts
-│   │   ├── node-specific-validators.test.ts
-│   │   ├── property-dependencies.test.ts
-│   │   ├── property-filter.test.ts
-│   │   ├── task-templates.test.ts
-│   │   ├── workflow-diff-engine.test.ts
-│   │   ├── workflow-validator-comprehensive.test.ts
-│   │   └── workflow-validator.test.ts
-│   └── utils/                  # Utility function tests
-│       └── database-utils.test.ts
-├── integration/                 # Integration tests (249 tests, 14 files)
-│   ├── database/               # Database integration tests
-│   │   ├── connection-management.test.ts
-│   │   ├── fts5-search.test.ts
-│   │   ├── node-repository.test.ts
-│   │   ├── performance.test.ts
-│   │   └── transactions.test.ts
-│   ├── mcp-protocol/           # MCP protocol tests
-│   │   ├── basic-connection.test.ts
-│   │   ├── error-handling.test.ts
-│   │   ├── performance.test.ts
-│   │   ├── protocol-compliance.test.ts
-│   │   ├── session-management.test.ts
-│   │   └── tool-invocation.test.ts
-│   └── setup/                  # Integration test setup
-│       ├── integration-setup.ts
-│       └── msw-test-server.ts
-├── benchmarks/                  # Performance benchmarks
-│   ├── database-queries.bench.ts
-│   └── sample.bench.ts
-├── setup/                       # Global test configuration
-│   ├── global-setup.ts         # Global test setup
-│   ├── msw-setup.ts            # Mock Service Worker setup
-│   └── test-env.ts             # Test environment configuration
-├── utils/                       # Test utilities
-│   ├── assertions.ts           # Custom assertions
-│   ├── builders/               # Test data builders
-│   │   └── workflow.builder.ts
-│   ├── data-generators.ts      # Test data generators
-│   ├── database-utils.ts       # Database test utilities
-│   └── test-helpers.ts         # General test helpers
-├── mocks/                       # Mock implementations
-│   └── n8n-api/               # n8n API mocks
-│       ├── handlers.ts        # MSW request handlers
-│       └── data/              # Mock data
-└── fixtures/                    # Test fixtures
-    ├── database/               # Database fixtures
-    ├── factories/              # Data factories
-    └── workflows/              # Workflow fixtures
-```
-
-## Mock Strategy
-
-### 1. Mock Service Worker (MSW) for API Mocking
-
-We use MSW for intercepting and mocking HTTP requests:
-
-```typescript
-// tests/mocks/n8n-api/handlers.ts
-import { http, HttpResponse } from 'msw';
-
-export const handlers = [
-  // Workflow endpoints
-  http.get('*/workflows/:id', ({ params }) => {
-    const workflow = mockWorkflows.find(w => w.id === params.id);
-    if (!workflow) {
-      return new HttpResponse(null, { status: 404 });
-    }
-    return HttpResponse.json(workflow);
-  }),
-
-  // Execution endpoints
-  http.post('*/workflows/:id/run', async ({ params, request }) => {
-    const body = await request.json();
-    return HttpResponse.json({
-      executionId: generateExecutionId(),
-      status: 'running'
-    });
-  })
-];
-```
-
-### 2. Database Mocking
-
-For unit tests, we mock the database layer:
-
-```typescript
-// tests/unit/__mocks__/better-sqlite3.ts
-import { vi } from 'vitest';
-
-export default vi.fn(() => ({
-  prepare: vi.fn(() => ({
-    all: vi.fn().mockReturnValue([]),
-    get: vi.fn().mockReturnValue(undefined),
-    run: vi.fn().mockReturnValue({ changes: 1 }),
-    finalize: vi.fn()
-  })),
-  exec: vi.fn(),
-  close: vi.fn(),
-  pragma: vi.fn()
-}));
-```
-
-### 3. MCP SDK Mocking
-
-For testing MCP protocol interactions:
-
-```typescript
-// tests/integration/mcp-protocol/test-helpers.ts
-export class TestableN8NMCPServer extends N8NMCPServer {
-  private transports = new Set<Transport>();
-  
-  async connectToTransport(transport: Transport): Promise<void> {
-    this.transports.add(transport);
-    await this.connect(transport);
-  }
-  
-  async close(): Promise<void> {
-    for (const transport of this.transports) {
-      await transport.close();
-    }
-    this.transports.clear();
-  }
-}
-```
-
-## Test Patterns and Utilities
-
-### 1. Database Test Utilities
-
-```typescript
-// tests/utils/database-utils.ts
-export class TestDatabase {
-  constructor(options: TestDatabaseOptions = {}) {
-    this.options = {
-      mode: 'memory',
-      enableFTS5: true,
-      ...options
-    };
-  }
-
-  async initialize(): Promise<Database.Database> {
-    const db = this.options.mode === 'memory' 
-      ? new Database(':memory:') 
-      : new Database(this.dbPath);
-    
-    if (this.options.enableFTS5) {
-      await this.enableFTS5(db);
-    }
-    
-    return db;
-  }
-}
-```
-
-### 2. Data Generators
-
-```typescript
-// tests/utils/data-generators.ts
-export class TestDataGenerator {
-  static generateNode(overrides: Partial<ParsedNode> = {}): ParsedNode {
-    return {
-      nodeType: `test.node${faker.number.int()}`,
-      displayName: faker.commerce.productName(),
-      description: faker.lorem.sentence(),
-      properties: this.generateProperties(5),
-      ...overrides
-    };
-  }
-
-  static generateWorkflow(nodeCount = 3): any {
-    const nodes = Array.from({ length: nodeCount }, (_, i) => ({
-      id: `node_${i}`,
-      type: 'test.node',
-      position: [i * 100, 0],
-      parameters: {}
-    }));
-    
-    return { nodes, connections: {} };
-  }
-}
-```
-
-### 3. Custom Assertions
-
-```typescript
-// tests/utils/assertions.ts
-export function expectValidMCPResponse(response: any): void {
-  expect(response).toBeDefined();
-  expect(response.content).toBeDefined();
-  expect(Array.isArray(response.content)).toBe(true);
-  expect(response.content[0]).toHaveProperty('type', 'text');
-  expect(response.content[0]).toHaveProperty('text');
-}
-
-export function expectNodeStructure(node: any): void {
-  expect(node).toHaveProperty('nodeType');
-  expect(node).toHaveProperty('displayName');
-  expect(node).toHaveProperty('properties');
-  expect(Array.isArray(node.properties)).toBe(true);
-}
-```
-
-## Unit Testing
-
-Our unit tests focus on testing individual components in isolation with mocked dependencies:
-
-### Service Layer Tests
-
-The bulk of our unit tests (400+ tests) are in the services layer:
-
-```typescript
-// tests/unit/services/workflow-validator-comprehensive.test.ts
-describe('WorkflowValidator Comprehensive Tests', () => {
-  it('should validate complex workflow with AI nodes', () => {
-    const workflow = {
-      nodes: [
-        {
-          id: 'ai_agent',
-          type: '@n8n/n8n-nodes-langchain.agent',
-          parameters: { prompt: 'Analyze data' }
-        }
-      ],
-      connections: {}
-    };
-    
-    const result = validator.validateWorkflow(workflow);
-    expect(result.valid).toBe(true);
-  });
-});
-```
-
-### Parser Tests
-
-Testing the node parsing logic:
-
-```typescript
-// tests/unit/parsers/property-extractor.test.ts
-describe('PropertyExtractor', () => {
-  it('should extract nested properties correctly', () => {
-    const node = {
-      properties: [
-        {
-          displayName: 'Options',
-          name: 'options',
-          type: 'collection',
-          options: [
-            { name: 'timeout', type: 'number' }
-          ]
-        }
-      ]
-    };
-    
-    const extracted = extractor.extractProperties(node);
-    expect(extracted).toHaveProperty('options.timeout');
-  });
-});
-```
-
-### Mock Testing
-
-Testing our mock implementations:
-
-```typescript
-// tests/unit/__mocks__/n8n-nodes-base.test.ts
-describe('n8n-nodes-base mock', () => {
-  it('should provide mocked node definitions', () => {
-    const httpNode = mockNodes['n8n-nodes-base.httpRequest'];
-    expect(httpNode).toBeDefined();
-    expect(httpNode.description.displayName).toBe('HTTP Request');
-  });
-});
-```
-
-## Integration Testing
-
-Our integration tests verify the complete system behavior:
-
-### MCP Protocol Testing
-
-```typescript
-// tests/integration/mcp-protocol/tool-invocation.test.ts
-describe('MCP Tool Invocation', () => {
-  let mcpServer: TestableN8NMCPServer;
-  let client: Client;
-
-  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 } 
-    });
-    
-    expectValidMCPResponse(response);
-    const result = JSON.parse(response.content[0].text);
-    expect(result.nodes).toHaveLength(10);
-    expect(result.nodes.every(n => n.category === 'trigger')).toBe(true);
-  });
-});
-```
-
-### Database Integration Testing
-
-```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') || 
-      n.description?.includes('http')
-    )).toBe(true);
-  });
-});
-```
-
-## Test Distribution and Coverage
-
-### Test Distribution by Component
-
-Based on our 1,182 tests:
-
-1. **Services Layer** (~450 tests)
-   - `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
-
-2. **Parsers** (~200 tests)
-   - `simple-parser.test.ts`: 80+ tests
-   - `property-extractor.test.ts`: 70+ tests
-   - `node-parser.test.ts`: 50+ tests
-
-3. **MCP Integration** (~150 tests)
-   - `tool-invocation.test.ts`: 50+ tests
-   - `error-handling.test.ts`: 40+ tests
-   - `session-management.test.ts`: 30+ tests
-
-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
-
-### Test Execution Performance
-
-From our CI runs:
-- **Fastest tests**: Unit tests with mocks (<1ms each)
-- **Slowest tests**: Integration tests with real database (100-5000ms)
-- **Average test time**: ~20ms per test
-- **Total suite execution**: Under 3 minutes in CI
-
-## CI/CD Pipeline
-
-Our GitHub Actions workflow runs all tests automatically:
-
-```yaml
-# .github/workflows/test.yml
-name: Test Suite
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          
-      - name: Install dependencies
-        run: npm ci
-      
-      - name: Run unit tests with coverage
-        run: npm run test:unit -- --coverage
-        
-      - name: Run integration tests
-        run: npm run test:integration
-        
-      - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v4
-```
-
-### Test Execution Scripts
-
-```json
-// package.json
-{
-  "scripts": {
-    "test": "vitest",
-    "test:unit": "vitest run tests/unit",
-    "test:integration": "vitest run tests/integration --config vitest.config.integration.ts",
-    "test:coverage": "vitest run --coverage",
-    "test:watch": "vitest watch",
-    "test:bench": "vitest bench --config vitest.config.benchmark.ts",
-    "benchmark:ci": "CI=true node scripts/run-benchmarks-ci.js"
-  }
-}
-```
-
-### CI Test Results Summary
-
-From our latest CI run (#41):
-
-```
-UNIT TESTS:
- Test Files  30 passed (30)
-      Tests  932 passed | 1 skipped (933)
-
-INTEGRATION TESTS:
- Test Files  14 passed (14)
-      Tests  245 passed | 4 skipped (249)
-
-TOTAL: 1,177 passed | 5 skipped | 0 failed
-```
-
-## Performance Testing
-
-We use Vitest's built-in benchmark functionality:
-
-```typescript
-// tests/benchmarks/database-queries.bench.ts
-import { bench, describe } from 'vitest';
-
-describe('Database Query Performance', () => {
-  bench('search nodes by category', async () => {
-    await nodeRepo.getNodesByCategory('trigger');
-  });
-
-  bench('FTS5 search performance', async () => {
-    await nodeRepo.searchNodes('webhook http request', 'AND');
-  });
-});
-```
-
-## Environment Configuration
-
-Test environment is configured via `.env.test`:
-
-```bash
-# Test Environment Configuration
-NODE_ENV=test
-TEST_DB_PATH=:memory:
-TEST_PARALLEL=false
-TEST_MAX_WORKERS=4
-FEATURE_TEST_COVERAGE=true
-MSW_ENABLED=true
-```
-
-## Key Patterns and Lessons Learned
-
-### 1. Response Structure Consistency
-
-All MCP responses follow a specific structure that must be handled correctly:
-
-```typescript
-// Common pattern for handling MCP responses
-const response = await client.callTool({ name: 'list_nodes', arguments: {} });
-
-// MCP responses have content array with text objects
-expect(response.content).toBeDefined();
-expect(response.content[0].type).toBe('text');
-
-// Parse the actual data
-const data = JSON.parse(response.content[0].text);
-```
-
-### 2. MSW Integration Setup
-
-Proper MSW setup is crucial for integration tests:
-
-```typescript
-// tests/integration/setup/integration-setup.ts
-import { setupServer } from 'msw/node';
-import { handlers } from '@tests/mocks/n8n-api/handlers';
-
-// Create server but don't start it globally
-const server = setupServer(...handlers);
-
-beforeAll(async () => {
-  // Only start MSW for integration tests
-  if (process.env.MSW_ENABLED === 'true') {
-    server.listen({ onUnhandledRequest: 'bypass' });
-  }
-});
-
-afterAll(async () => {
-  server.close();
-});
-```
-
-### 3. Database Isolation for Parallel Tests
-
-Each test gets its own database to enable parallel execution:
-
-```typescript
-// tests/utils/database-utils.ts
-export function createTestDatabaseAdapter(
-  db?: Database.Database,
-  options: TestDatabaseOptions = {}
-): DatabaseAdapter {
-  const database = db || new Database(':memory:');
-  
-  // Enable FTS5 if needed
-  if (options.enableFTS5) {
-    database.exec('PRAGMA main.compile_options;');
-  }
-  
-  return new DatabaseAdapter(database);
-}
-```
-
-### 4. Environment-Aware Performance Thresholds
-
-CI environments are slower, so we adjust expectations:
-
-```typescript
-// Environment-aware thresholds
-const getThreshold = (local: number, ci: number) => 
-  process.env.CI ? ci : local;
-
-it('should respond quickly', async () => {
-  const start = performance.now();
-  await someOperation();
-  const duration = performance.now() - start;
-  
-  expect(duration).toBeLessThan(getThreshold(50, 200));
-});
-```
-
-## Best Practices
-
-### 1. Test Isolation
-- Each test creates its own database instance
-- Tests clean up after themselves
-- No shared state between tests
-
-### 2. Proper Cleanup Order
-```typescript
-afterEach(async () => {
-  // Close client first to ensure no pending requests
-  await client.close();
-  
-  // Give time for client to fully close
-  await new Promise(resolve => setTimeout(resolve, 50));
-  
-  // Then close server
-  await mcpServer.close();
-  
-  // Finally cleanup database
-  await testDb.cleanup();
-});
-```
-
-### 3. Handle Async Operations Carefully
-```typescript
-// Avoid race conditions in cleanup
-it('should handle disconnection', async () => {
-  // ... test code ...
-  
-  // Ensure operations complete before cleanup
-  await transport.close();
-  await new Promise(resolve => setTimeout(resolve, 100));
-});
-```
-
-### 4. Meaningful Test Organization
-- Group related tests using `describe` blocks
-- Use descriptive test names that explain the behavior
-- Follow AAA pattern: Arrange, Act, Assert
-- Keep tests focused on single behaviors
-
-## Debugging Tests
-
-### Running Specific Tests
-```bash
-# Run a single test file
-npm test tests/integration/mcp-protocol/tool-invocation.test.ts
-
-# Run tests matching a pattern
-npm test -- --grep "should list nodes"
-
-# Run with debugging output
-DEBUG=* npm test
-```
-
-### VSCode Integration
-```json
-// .vscode/launch.json
-{
-  "configurations": [
-    {
-      "type": "node",
-      "request": "launch",
-      "name": "Debug Tests",
-      "program": "${workspaceFolder}/node_modules/vitest/vitest.mjs",
-      "args": ["run", "${file}"],
-      "console": "integratedTerminal"
-    }
-  ]
-}
-```
-
-## Test Coverage
-
-While we don't enforce strict coverage thresholds yet, the infrastructure is in place:
-- Coverage reports generated in `lcov`, `html`, and `text` formats
-- Integration with Codecov for tracking coverage over time
-- Per-file coverage visible in VSCode with extensions
-
-## Future Improvements
-
-1. **E2E Testing**: Add Playwright for testing the full MCP server interaction
-2. **Load Testing**: Implement k6 or Artillery for stress testing
-3. **Contract Testing**: Add Pact for ensuring API compatibility
-4. **Visual Regression**: For any UI components that may be added
-5. **Mutation Testing**: Use Stryker to ensure test quality
-
-## Common Issues and Solutions
-
-### 1. Tests Hanging in CI
-
-**Problem**: Tests would hang indefinitely in CI due to `process.exit()` calls.
-
-**Solution**: Remove all `process.exit()` calls from test code and use proper cleanup:
-```typescript
-// Bad
-afterAll(() => {
-  process.exit(0); // This causes Vitest to hang
-});
-
-// Good
-afterAll(async () => {
-  await cleanup();
-  // Let Vitest handle process termination
-});
-```
-
-### 2. MCP Response Structure
-
-**Problem**: Tests expecting wrong response format from MCP tools.
-
-**Solution**: Always access responses through `content[0].text`:
-```typescript
-// Wrong
-const data = response[0].text;
-
-// Correct
-const data = JSON.parse(response.content[0].text);
-```
-
-### 3. Database Not Found Errors
-
-**Problem**: Tests failing with "node not found" when database is empty.
-
-**Solution**: Check for empty databases before assertions:
-```typescript
-const stats = await server.executeTool('get_database_statistics', {});
-if (stats.totalNodes > 0) {
-  expect(result.nodes.length).toBeGreaterThan(0);
-} else {
-  expect(result.nodes).toHaveLength(0);
-}
-```
-
-### 4. MSW Loading Globally
-
-**Problem**: MSW interfering with unit tests when loaded globally.
-
-**Solution**: Only load MSW in integration test setup:
-```typescript
-// vitest.config.integration.ts
-setupFiles: [
-  './tests/setup/global-setup.ts',
-  './tests/integration/setup/integration-setup.ts' // MSW only here
-]
-```
-
-## Resources
-
-- [Vitest Documentation](https://vitest.dev/)
-- [MSW Documentation](https://mswjs.io/)
-- [Testing Best Practices](https://github.com/goldbergyoni/javascript-testing-best-practices)
-- [MCP SDK Documentation](https://modelcontextprotocol.io/)

docs/testing-checklist.md

@@ -1,276 +0,0 @@
-# n8n-MCP Testing Implementation Checklist
-
-## Test Suite Development Status
-
-### Context
-- **Situation**: Building comprehensive test suite from scratch
-- **Branch**: feat/comprehensive-testing-suite (separate from main)
-- **Main Branch Status**: Working in production without tests
-- **Goal**: Add test coverage without disrupting development
-
-## Immediate Actions (Day 1)
-
-- [x] ~~Fix failing tests (Phase 0)~~ ✅ COMPLETED
-- [x] ~~Create GitHub Actions workflow file~~ ✅ COMPLETED
-- [x] ~~Install Vitest and remove Jest~~ ✅ COMPLETED
-- [x] ~~Create vitest.config.ts~~ ✅ COMPLETED
-- [x] ~~Setup global test configuration~~ ✅ COMPLETED
-- [x] ~~Migrate existing tests to Vitest syntax~~ ✅ COMPLETED
-- [x] ~~Setup coverage reporting with Codecov~~ ✅ COMPLETED
-
-## Phase 1: Vitest Migration ✅ COMPLETED
-
-All tests have been successfully migrated from Jest to Vitest:
-- ✅ Removed Jest and installed Vitest
-- ✅ Created vitest.config.ts with path aliases
-- ✅ Set up global test configuration
-- ✅ Migrated all 6 test files (68 tests passing)
-- ✅ Updated TypeScript configuration
-- ✅ Cleaned up Jest configuration files
-
-## Week 1: Foundation
-
-### Testing Infrastructure ✅ COMPLETED (Phase 2)
-- [x] ~~Create test directory structure~~ ✅ COMPLETED
-- [x] ~~Setup mock infrastructure for better-sqlite3~~ ✅ COMPLETED
-- [x] ~~Create mock for n8n-nodes-base package~~ ✅ COMPLETED
-- [x] ~~Setup test database utilities~~ ✅ COMPLETED
-- [x] ~~Create factory pattern for nodes~~ ✅ COMPLETED
-- [x] ~~Create builder pattern for workflows~~ ✅ COMPLETED
-- [x] ~~Setup global test utilities~~ ✅ COMPLETED
-- [x] ~~Configure test environment variables~~ ✅ COMPLETED
-
-### CI/CD Pipeline ✅ COMPLETED (Phase 3.8)
-- [x] ~~GitHub Actions for test execution~~ ✅ COMPLETED & VERIFIED
-  - Successfully running with Vitest
-  - 1021 tests passing in CI
-  - Build time: ~2 minutes
-- [x] ~~Coverage reporting integration~~ ✅ COMPLETED (Codecov setup)
-- [x] ~~Performance benchmark tracking~~ ✅ COMPLETED
-- [x] ~~Test result artifacts~~ ✅ COMPLETED
-- [ ] Branch protection rules
-- [ ] Required status checks
-
-## Week 2: Mock Infrastructure
-
-### Database Mocking
-- [ ] Complete better-sqlite3 mock implementation
-- [ ] Mock prepared statements
-- [ ] Mock transactions
-- [ ] Mock FTS5 search functionality
-- [ ] Test data seeding utilities
-
-### External Dependencies
-- [ ] Mock axios for API calls
-- [ ] Mock file system operations
-- [ ] Mock MCP SDK
-- [ ] Mock Express server
-- [ ] Mock WebSocket connections
-
-## Week 3-4: Unit Tests ✅ COMPLETED (Phase 3)
-
-### Core Services (Priority 1) ✅ COMPLETED
-- [x] ~~`config-validator.ts` - 95% coverage~~ ✅ 96.9%
-- [x] ~~`enhanced-config-validator.ts` - 95% coverage~~ ✅ 94.55%
-- [x] ~~`workflow-validator.ts` - 90% coverage~~ ✅ 97.59%
-- [x] ~~`expression-validator.ts` - 90% coverage~~ ✅ 97.22%
-- [x] ~~`property-filter.ts` - 90% coverage~~ ✅ 95.25%
-- [x] ~~`example-generator.ts` - 85% coverage~~ ✅ 94.34%
-
-### Parsers (Priority 2) ✅ COMPLETED
-- [x] ~~`node-parser.ts` - 90% coverage~~ ✅ 97.42%
-- [x] ~~`property-extractor.ts` - 90% coverage~~ ✅ 95.49%
-
-### MCP Layer (Priority 3) ✅ COMPLETED
-- [x] ~~`tools.ts` - 90% coverage~~ ✅ 94.11%
-- [x] ~~`handlers-n8n-manager.ts` - 85% coverage~~ ✅ 92.71%
-- [x] ~~`handlers-workflow-diff.ts` - 85% coverage~~ ✅ 96.34%
-- [x] ~~`tools-documentation.ts` - 80% coverage~~ ✅ 94.12%
-
-### Database Layer (Priority 4) ✅ COMPLETED
-- [x] ~~`node-repository.ts` - 85% coverage~~ ✅ 91.48%
-- [x] ~~`database-adapter.ts` - 85% coverage~~ ✅ 89.29%
-- [x] ~~`template-repository.ts` - 80% coverage~~ ✅ 86.78%
-
-### Loaders and Mappers (Priority 5) ✅ COMPLETED
-- [x] ~~`node-loader.ts` - 85% coverage~~ ✅ 91.89%
-- [x] ~~`docs-mapper.ts` - 80% coverage~~ ✅ 95.45%
-
-### Additional Critical Services Tested ✅ COMPLETED (Phase 3.5)
-- [x] ~~`n8n-api-client.ts`~~ ✅ 83.87%
-- [x] ~~`workflow-diff-engine.ts`~~ ✅ 90.06%
-- [x] ~~`n8n-validation.ts`~~ ✅ 97.14%
-- [x] ~~`node-specific-validators.ts`~~ ✅ 98.7%
-
-## Week 5-6: Integration Tests 🚧 IN PROGRESS
-
-### Real Status (July 29, 2025)
-**Context**: Building test suite from scratch on testing branch. Main branch has no tests.
-
-**Overall Status**: 187/246 tests passing (76% pass rate)
-**Critical Issue**: CI shows green despite 58 failing tests due to `|| true` in workflow
-
-### MCP Protocol Tests 🔄 MIXED STATUS
-- [x] ~~Full MCP server initialization~~ ✅ COMPLETED
-- [x] ~~Tool invocation flow~~ ✅ FIXED (30 tests in tool-invocation.test.ts)
-- [ ] Error handling and recovery ⚠️ 16 FAILING (error-handling.test.ts)
-- [x] ~~Concurrent request handling~~ ✅ COMPLETED  
-- [ ] Session management ⚠️ 5 FAILING (timeout issues)
-
-### n8n API Integration 🔄 PENDING
-- [ ] Workflow CRUD operations (MSW mocks ready)
-- [ ] Webhook triggering
-- [ ] Execution monitoring
-- [ ] Authentication handling
-- [ ] Error scenarios
-
-### Database Integration ⚠️ ISSUES FOUND
-- [x] ~~SQLite operations with real DB~~ ✅ BASIC TESTS PASS
-- [ ] FTS5 search functionality ⚠️ 7 FAILING (syntax errors)
-- [ ] Transaction handling ⚠️ 1 FAILING (isolation issues)
-- [ ] Migration testing 🔄 NOT STARTED
-- [ ] Performance under load ⚠️ 4 FAILING (slower than thresholds)
-
-## Week 7-8: E2E & Performance
-
-### End-to-End Scenarios
-- [ ] Complete workflow creation flow
-- [ ] AI agent workflow setup
-- [ ] Template import and validation
-- [ ] Workflow execution monitoring
-- [ ] Error recovery scenarios
-
-### Performance Benchmarks
-- [ ] Node loading speed (< 50ms per node)
-- [ ] Search performance (< 100ms for 1000 nodes)
-- [ ] Validation speed (< 10ms simple, < 100ms complex)
-- [ ] Database query performance
-- [ ] Memory usage profiling
-- [ ] Concurrent request handling
-
-### Load Testing
-- [ ] 100 concurrent MCP requests
-- [ ] 10,000 nodes in database
-- [ ] 1,000 workflow validations/minute
-- [ ] Memory leak detection
-- [ ] Resource cleanup verification
-
-## Testing Quality Gates
-
-### Coverage Requirements
-- [ ] Overall: 80%+ (Currently: 62.67%)
-- [x] ~~Core services: 90%+~~ ✅ COMPLETED
-- [x] ~~MCP tools: 90%+~~ ✅ COMPLETED
-- [x] ~~Critical paths: 95%+~~ ✅ COMPLETED
-- [x] ~~New code: 90%+~~ ✅ COMPLETED
-
-### Performance Requirements
-- [x] ~~All unit tests < 10ms~~ ✅ COMPLETED
-- [ ] Integration tests < 1s
-- [ ] E2E tests < 10s
-- [x] ~~Full suite < 5 minutes~~ ✅ COMPLETED (~2 minutes)
-- [x] ~~No memory leaks~~ ✅ COMPLETED
-
-### Code Quality
-- [x] ~~No ESLint errors~~ ✅ COMPLETED
-- [x] ~~No TypeScript errors~~ ✅ COMPLETED
-- [x] ~~No console.log in tests~~ ✅ COMPLETED
-- [x] ~~All tests have descriptions~~ ✅ COMPLETED
-- [x] ~~No hardcoded values~~ ✅ COMPLETED
-
-## Monitoring & Maintenance
-
-### Daily
-- [ ] Check CI pipeline status
-- [ ] Review failed tests
-- [ ] Monitor flaky tests
-
-### Weekly
-- [ ] Review coverage reports
-- [ ] Update test documentation
-- [ ] Performance benchmark review
-- [ ] Team sync on testing progress
-
-### Monthly
-- [ ] Update baseline benchmarks
-- [ ] Review and refactor tests
-- [ ] Update testing strategy
-- [ ] Training/knowledge sharing
-
-## Risk Mitigation
-
-### Technical Risks
-- [ ] Mock complexity - Use simple, maintainable mocks
-- [ ] Test brittleness - Focus on behavior, not implementation
-- [ ] Performance impact - Run heavy tests in parallel
-- [ ] Flaky tests - Proper async handling and isolation
-
-### Process Risks
-- [ ] Slow adoption - Provide training and examples
-- [ ] Coverage gaming - Review test quality, not just numbers
-- [ ] Maintenance burden - Automate what's possible
-- [ ] Integration complexity - Use test containers
-
-## Success Criteria
-
-### Current Reality Check
-- **Unit Tests**: ✅ SOLID (932 passing, 87.8% coverage)
-- **Integration Tests**: ⚠️ NEEDS WORK (58 failing, 76% pass rate)
-- **E2E Tests**: 🔄 NOT STARTED
-- **CI/CD**: ⚠️ BROKEN (hiding failures with || true)
-
-### Revised Technical Metrics
-- Coverage: Currently 87.8% for unit tests ✅
-- Integration test pass rate: Target 100% (currently 76%)
-- Performance: Adjust thresholds based on reality
-- Reliability: Fix flaky tests during repair
-- Speed: CI pipeline < 5 minutes ✅ (~2 minutes)
-
-### Team Metrics
-- All developers writing tests ✅
-- Tests reviewed in PRs ✅
-- No production bugs from tested code
-- Improved development velocity ✅
-
-## Phases Completed
-
-- **Phase 0**: Immediate Fixes ✅ COMPLETED
-- **Phase 1**: Vitest Migration ✅ COMPLETED  
-- **Phase 2**: Test Infrastructure ✅ COMPLETED
-- **Phase 3**: Unit Tests (All 943 tests) ✅ COMPLETED
-- **Phase 3.5**: Critical Service Testing ✅ COMPLETED
-- **Phase 3.8**: CI/CD & Infrastructure ✅ COMPLETED
-- **Phase 4**: Integration Tests 🚧 IN PROGRESS
-  - **Status**: 58 out of 246 tests failing (23.6% failure rate)
-  - **CI Issue**: Tests appear green due to `|| true` error suppression
-  - **Categories of Failures**:
-    - Database: 9 tests (state isolation, FTS5 syntax)
-    - MCP Protocol: 16 tests (response structure in error-handling.test.ts)
-    - MSW: 6 tests (not initialized properly)
-    - FTS5 Search: 7 tests (query syntax issues)
-    - Session Management: 5 tests (async cleanup)
-    - Performance: 15 tests (threshold mismatches)
-  - **Next Steps**: 
-    1. Get team buy-in for "red" CI
-    2. Remove `|| true` from workflow
-    3. Fix tests systematically by category
-- **Phase 5**: E2E Tests 🔄 PENDING
-
-## Resources & Tools
-
-### Documentation
-- Vitest: https://vitest.dev/
-- Testing Library: https://testing-library.com/
-- MSW: https://mswjs.io/
-- Testcontainers: https://www.testcontainers.com/
-
-### Monitoring
-- Codecov: https://codecov.io/
-- GitHub Actions: https://github.com/features/actions
-- Benchmark Action: https://github.com/benchmark-action/github-action-benchmark
-
-### Team Resources
-- Testing best practices guide
-- Example test implementations
-- Mock usage patterns
-- Performance optimization tips

docs/testing-implementation-guide.md

@@ -1,472 +0,0 @@
-# n8n-MCP Testing Implementation Guide
-
-## Phase 1: Foundation Setup (Week 1-2)
-
-### 1.1 Install Vitest and Dependencies
-
-```bash
-# Remove Jest
-npm uninstall jest ts-jest @types/jest
-
-# Install Vitest and related packages
-npm install -D vitest @vitest/ui @vitest/coverage-v8
-npm install -D @testing-library/jest-dom
-npm install -D msw # For API mocking
-npm install -D @faker-js/faker # For test data
-npm install -D fishery # For factories
-```
-
-### 1.2 Update package.json Scripts
-
-```json
-{
-  "scripts": {
-    // Testing
-    "test": "vitest",
-    "test:ui": "vitest --ui",
-    "test:unit": "vitest run tests/unit",
-    "test:integration": "vitest run tests/integration",
-    "test:e2e": "vitest run tests/e2e",
-    "test:watch": "vitest watch",
-    "test:coverage": "vitest run --coverage",
-    "test:coverage:check": "vitest run --coverage --coverage.thresholdAutoUpdate=false",
-    
-    // Benchmarks
-    "bench": "vitest bench",
-    "bench:compare": "vitest bench --compare",
-    
-    // CI specific
-    "test:ci": "vitest run --reporter=junit --reporter=default",
-    "test:ci:coverage": "vitest run --coverage --reporter=junit --reporter=default"
-  }
-}
-```
-
-### 1.3 Migrate Existing Tests
-
-```typescript
-// Before (Jest)
-import { describe, test, expect } from '@jest/globals';
-
-// After (Vitest)
-import { describe, it, expect, vi } from 'vitest';
-
-// Update mock syntax
-// Jest: jest.mock('module')
-// Vitest: vi.mock('module')
-
-// Update timer mocks
-// Jest: jest.useFakeTimers()
-// Vitest: vi.useFakeTimers()
-```
-
-### 1.4 Create Test Database Setup
-
-```typescript
-// tests/setup/test-database.ts
-import Database from 'better-sqlite3';
-import { readFileSync } from 'fs';
-import { join } from 'path';
-
-export class TestDatabase {
-  private db: Database.Database;
-  
-  constructor() {
-    this.db = new Database(':memory:');
-    this.initialize();
-  }
-  
-  private initialize() {
-    const schema = readFileSync(
-      join(__dirname, '../../src/database/schema.sql'),
-      'utf8'
-    );
-    this.db.exec(schema);
-  }
-  
-  seedNodes(nodes: any[]) {
-    const stmt = this.db.prepare(`
-      INSERT INTO nodes (type, displayName, name, group, version, description, properties)
-      VALUES (?, ?, ?, ?, ?, ?, ?)
-    `);
-    
-    const insertMany = this.db.transaction((nodes) => {
-      for (const node of nodes) {
-        stmt.run(
-          node.type,
-          node.displayName,
-          node.name,
-          node.group,
-          node.version,
-          node.description,
-          JSON.stringify(node.properties)
-        );
-      }
-    });
-    
-    insertMany(nodes);
-  }
-  
-  close() {
-    this.db.close();
-  }
-  
-  getDb() {
-    return this.db;
-  }
-}
-```
-
-## Phase 2: Core Unit Tests (Week 3-4)
-
-### 2.1 Test Organization Template
-
-```typescript
-// tests/unit/services/[service-name].test.ts
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import { ServiceName } from '@/services/service-name';
-
-describe('ServiceName', () => {
-  let service: ServiceName;
-  let mockDependency: any;
-  
-  beforeEach(() => {
-    // Setup mocks
-    mockDependency = {
-      method: vi.fn()
-    };
-    
-    // Create service instance
-    service = new ServiceName(mockDependency);
-  });
-  
-  afterEach(() => {
-    vi.clearAllMocks();
-  });
-  
-  describe('methodName', () => {
-    it('should handle happy path', async () => {
-      // Arrange
-      const input = { /* test data */ };
-      mockDependency.method.mockResolvedValue({ /* mock response */ });
-      
-      // Act
-      const result = await service.methodName(input);
-      
-      // Assert
-      expect(result).toEqual(/* expected output */);
-      expect(mockDependency.method).toHaveBeenCalledWith(/* expected args */);
-    });
-    
-    it('should handle errors gracefully', async () => {
-      // Arrange
-      mockDependency.method.mockRejectedValue(new Error('Test error'));
-      
-      // Act & Assert
-      await expect(service.methodName({})).rejects.toThrow('Expected error message');
-    });
-  });
-});
-```
-
-### 2.2 Mock Strategies by Layer
-
-#### Database Layer
-```typescript
-// tests/unit/database/node-repository.test.ts
-import { vi } from 'vitest';
-
-vi.mock('better-sqlite3', () => ({
-  default: vi.fn(() => ({
-    prepare: vi.fn(() => ({
-      all: vi.fn(() => mockData),
-      get: vi.fn((id) => mockData.find(d => d.id === id)),
-      run: vi.fn(() => ({ changes: 1 }))
-    })),
-    exec: vi.fn(),
-    close: vi.fn()
-  }))
-}));
-```
-
-#### External APIs
-```typescript
-// tests/unit/services/__mocks__/axios.ts
-export default {
-  create: vi.fn(() => ({
-    get: vi.fn(() => Promise.resolve({ data: {} })),
-    post: vi.fn(() => Promise.resolve({ data: { id: '123' } })),
-    put: vi.fn(() => Promise.resolve({ data: {} })),
-    delete: vi.fn(() => Promise.resolve({ data: {} }))
-  }))
-};
-```
-
-#### File System
-```typescript
-// Use memfs for file system mocking
-import { vol } from 'memfs';
-
-vi.mock('fs', () => vol);
-
-beforeEach(() => {
-  vol.reset();
-  vol.fromJSON({
-    '/test/file.json': JSON.stringify({ test: 'data' })
-  });
-});
-```
-
-### 2.3 Critical Path Tests
-
-```typescript
-// Priority 1: Node Loading and Parsing
-// tests/unit/loaders/node-loader.test.ts
-
-// Priority 2: Configuration Validation
-// tests/unit/services/config-validator.test.ts
-
-// Priority 3: MCP Tools
-// tests/unit/mcp/tools.test.ts
-
-// Priority 4: Database Operations
-// tests/unit/database/node-repository.test.ts
-
-// Priority 5: Workflow Validation
-// tests/unit/services/workflow-validator.test.ts
-```
-
-## Phase 3: Integration Tests (Week 5-6)
-
-### 3.1 Test Container Setup
-
-```typescript
-// tests/setup/test-containers.ts
-import { GenericContainer, StartedTestContainer } from 'testcontainers';
-
-export class N8nTestContainer {
-  private container: StartedTestContainer;
-  
-  async start() {
-    this.container = await new GenericContainer('n8nio/n8n:latest')
-      .withExposedPorts(5678)
-      .withEnv('N8N_BASIC_AUTH_ACTIVE', 'false')
-      .withEnv('N8N_ENCRYPTION_KEY', 'test-key')
-      .start();
-    
-    return {
-      url: `http://localhost:${this.container.getMappedPort(5678)}`,
-      stop: () => this.container.stop()
-    };
-  }
-}
-```
-
-### 3.2 Integration Test Pattern
-
-```typescript
-// tests/integration/n8n-api/workflow-crud.test.ts
-import { N8nTestContainer } from '@tests/setup/test-containers';
-import { N8nAPIClient } from '@/services/n8n-api-client';
-
-describe('n8n API Integration', () => {
-  let container: any;
-  let apiClient: N8nAPIClient;
-  
-  beforeAll(async () => {
-    container = await new N8nTestContainer().start();
-    apiClient = new N8nAPIClient(container.url);
-  }, 30000);
-  
-  afterAll(async () => {
-    await container.stop();
-  });
-  
-  it('should create and retrieve workflow', async () => {
-    // Create workflow
-    const workflow = createTestWorkflow();
-    const created = await apiClient.createWorkflow(workflow);
-    
-    expect(created.id).toBeDefined();
-    
-    // Retrieve workflow
-    const retrieved = await apiClient.getWorkflow(created.id);
-    expect(retrieved.name).toBe(workflow.name);
-  });
-});
-```
-
-## Phase 4: E2E & Performance (Week 7-8)
-
-### 4.1 E2E Test Setup
-
-```typescript
-// tests/e2e/workflows/complete-workflow.test.ts
-import { MCPClient } from '@tests/utils/mcp-client';
-import { N8nTestContainer } from '@tests/setup/test-containers';
-
-describe('Complete Workflow E2E', () => {
-  let mcpServer: any;
-  let n8nContainer: any;
-  let mcpClient: MCPClient;
-  
-  beforeAll(async () => {
-    // Start n8n
-    n8nContainer = await new N8nTestContainer().start();
-    
-    // Start MCP server
-    mcpServer = await startMCPServer({
-      n8nUrl: n8nContainer.url
-    });
-    
-    // Create MCP client
-    mcpClient = new MCPClient(mcpServer.url);
-  }, 60000);
-  
-  it('should execute complete workflow creation flow', async () => {
-    // 1. Search for nodes
-    const searchResult = await mcpClient.call('search_nodes', {
-      query: 'webhook http slack'
-    });
-    
-    // 2. Get node details
-    const webhookInfo = await mcpClient.call('get_node_info', {
-      nodeType: 'nodes-base.webhook'
-    });
-    
-    // 3. Create workflow
-    const workflow = new WorkflowBuilder('E2E Test')
-      .addWebhookNode()
-      .addHttpRequestNode()
-      .addSlackNode()
-      .connectSequentially()
-      .build();
-    
-    // 4. Validate workflow
-    const validation = await mcpClient.call('validate_workflow', {
-      workflow
-    });
-    
-    expect(validation.isValid).toBe(true);
-    
-    // 5. Deploy to n8n
-    const deployed = await mcpClient.call('n8n_create_workflow', {
-      ...workflow
-    });
-    
-    expect(deployed.id).toBeDefined();
-    expect(deployed.active).toBe(false);
-  });
-});
-```
-
-### 4.2 Performance Benchmarks
-
-```typescript
-// vitest.benchmark.config.ts
-export default {
-  test: {
-    benchmark: {
-      // Output benchmark results
-      outputFile: './benchmark-results.json',
-      
-      // Compare with baseline
-      compare: './benchmark-baseline.json',
-      
-      // Fail if performance degrades by more than 10%
-      threshold: {
-        p95: 1.1, // 110% of baseline
-        p99: 1.2  // 120% of baseline
-      }
-    }
-  }
-};
-```
-
-## Testing Best Practices
-
-### 1. Test Naming Convention
-```typescript
-// Format: should [expected behavior] when [condition]
-it('should return user data when valid ID is provided')
-it('should throw ValidationError when email is invalid')
-it('should retry 3 times when network fails')
-```
-
-### 2. Test Data Builders
-```typescript
-// Use builders for complex test data
-const user = new UserBuilder()
-  .withEmail('test@example.com')
-  .withRole('admin')
-  .build();
-```
-
-### 3. Custom Matchers
-```typescript
-// tests/utils/matchers.ts
-export const toBeValidNode = (received: any) => {
-  const pass = 
-    received.type &&
-    received.displayName &&
-    received.properties &&
-    Array.isArray(received.properties);
-  
-  return {
-    pass,
-    message: () => `expected ${received} to be a valid node`
-  };
-};
-
-// Usage
-expect(node).toBeValidNode();
-```
-
-### 4. Snapshot Testing
-```typescript
-// For complex structures
-it('should generate correct node schema', () => {
-  const schema = generateNodeSchema(node);
-  expect(schema).toMatchSnapshot();
-});
-```
-
-### 5. Test Isolation
-```typescript
-// Always clean up after tests
-afterEach(async () => {
-  await cleanup();
-  vi.clearAllMocks();
-  vi.restoreAllMocks();
-});
-```
-
-## Coverage Goals by Module
-
-| Module | Target | Priority | Notes |
-|--------|--------|----------|-------|
-| services/config-validator | 95% | High | Critical for reliability |
-| services/workflow-validator | 90% | High | Core functionality |
-| mcp/tools | 90% | High | User-facing API |
-| database/node-repository | 85% | Medium | Well-tested DB layer |
-| loaders/node-loader | 85% | Medium | External dependencies |
-| parsers/* | 90% | High | Data transformation |
-| utils/* | 80% | Low | Helper functions |
-| scripts/* | 50% | Low | One-time scripts |
-
-## Continuous Improvement
-
-1. **Weekly Reviews**: Review test coverage and identify gaps
-2. **Performance Baselines**: Update benchmarks monthly
-3. **Flaky Test Detection**: Monitor and fix within 48 hours
-4. **Test Documentation**: Keep examples updated
-5. **Developer Training**: Pair programming on tests
-
-## Success Metrics
-
-- [ ] All tests pass in CI (0 failures)
-- [ ] Coverage > 80% overall
-- [ ] No flaky tests
-- [ ] CI runs < 5 minutes
-- [ ] Performance benchmarks stable
-- [ ] Zero production bugs from tested code

docs/token-efficiency-summary.md

@@ -1,66 +0,0 @@
-# Token Efficiency Improvements Summary
-
-## Overview
-Made all MCP tool descriptions concise and token-efficient while preserving essential information.
-
-## Key Improvements
-
-### Before vs After Examples
-
-1. **search_nodes**
-   - Before: ~350 chars with verbose explanation
-   - After: 165 chars
-   - `Search nodes by keywords. Modes: OR (any word), AND (all words), FUZZY (typos OK). Primary nodes ranked first. Examples: "webhook"→Webhook, "http call"→HTTP Request.`
-
-2. **get_node_info**
-   - Before: ~450 chars with warnings about size
-   - After: 174 chars
-   - `Get FULL node schema (100KB+). TIP: Use get_node_essentials first! Returns all properties/operations/credentials. Prefix required: "nodes-base.httpRequest" not "httpRequest".`
-
-3. **validate_node_minimal**
-   - Before: ~350 chars explaining what it doesn't do
-   - After: 102 chars
-   - `Fast check for missing required fields only. No warnings/suggestions. Returns: list of missing fields.`
-
-4. **get_property_dependencies**
-   - Before: ~400 chars with full example
-   - After: 131 chars
-   - `Shows property dependencies and visibility rules. Example: sendBody=true reveals body fields. Test visibility with optional config.`
-
-## Statistics
-
-### Documentation Tools (22 tools)
-- Average description length: **129 characters**
-- Total characters: 2,836
-- Tools over 200 chars: 1 (list_nodes at 204)
-
-### Management Tools (17 tools)
-- Average description length: **93 characters**
-- Total characters: 1,578
-- Tools over 200 chars: 1 (n8n_update_partial_workflow at 284)
-
-## Strategy Used
-
-1. **Remove redundancy**: Eliminated repeated information available in parameter descriptions
-2. **Use abbreviations**: "vs" instead of "versus", "&" instead of "and" where appropriate
-3. **Compact examples**: `"webhook"→Webhook` instead of verbose explanations
-4. **Direct language**: "Fast check" instead of "Quick validation that only checks"
-5. **Move details to documentation**: Complex tools reference `tools_documentation()` for full details
-6. **Essential info only**: Focus on what the tool does, not how it works internally
-
-## Special Cases
-
-### n8n_update_partial_workflow
-This tool's description is necessarily longer (284 chars) because:
-- Lists all 13 operation types
-- Critical for users to know available operations
-- Directs to full documentation for details
-
-### Complex Documentation Preserved
-For tools like `n8n_update_partial_workflow`, detailed documentation was moved to `tools-documentation.ts` rather than deleted, ensuring users can still access comprehensive information when needed.
-
-## Impact
-- **Token savings**: ~65-70% reduction in description tokens
-- **Faster AI responses**: Less context used for tool descriptions
-- **Better UX**: Clearer, more scannable tool list
-- **Maintained functionality**: All essential information preserved

docs/transactional-updates-example.md

@@ -1,118 +0,0 @@
-# Transactional Updates Example
-
-This example demonstrates the new transactional update capabilities in v2.7.0.
-
-## Before (v2.6.x and earlier)
-
-Previously, you had to carefully order operations to ensure nodes existed before connecting them:
-
-```json
-{
-  "id": "workflow-123",
-  "operations": [
-    // 1. First add all nodes
-    { "type": "addNode", "node": { "name": "Process", "type": "n8n-nodes-base.set", ... }},
-    { "type": "addNode", "node": { "name": "Notify", "type": "n8n-nodes-base.slack", ... }},
-    
-    // 2. Then add connections (would fail if done before nodes)
-    { "type": "addConnection", "source": "Webhook", "target": "Process" },
-    { "type": "addConnection", "source": "Process", "target": "Notify" }
-  ]
-}
-```
-
-## After (v2.7.0+)
-
-Now you can write operations in any order - the engine automatically handles dependencies:
-
-```json
-{
-  "id": "workflow-123",
-  "operations": [
-    // Connections can come first!
-    { "type": "addConnection", "source": "Webhook", "target": "Process" },
-    { "type": "addConnection", "source": "Process", "target": "Notify" },
-    
-    // Nodes added later - still works!
-    { "type": "addNode", "node": { "name": "Process", "type": "n8n-nodes-base.set", "position": [400, 300] }},
-    { "type": "addNode", "node": { "name": "Notify", "type": "n8n-nodes-base.slack", "position": [600, 300] }}
-  ]
-}
-```
-
-## How It Works
-
-1. **Two-Pass Processing**:
-   - Pass 1: All node operations (add, remove, update, move, enable, disable)
-   - Pass 2: All other operations (connections, settings, metadata)
-
-2. **Operation Limit**: Maximum 5 operations per request keeps complexity manageable
-
-3. **Atomic Updates**: All operations succeed or all fail - no partial updates
-
-## Benefits for AI Agents
-
-- **Intuitive**: Write operations in the order that makes sense logically
-- **Reliable**: No need to track dependencies manually
-- **Simple**: Focus on what to change, not how to order changes
-- **Safe**: Built-in limits prevent overly complex operations
-
-## Complete Example
-
-Here's a real-world example of adding error handling to a workflow:
-
-```json
-{
-  "id": "workflow-123",
-  "operations": [
-    // Define the flow first (makes logical sense)
-    { 
-      "type": "removeConnection", 
-      "source": "HTTP Request", 
-      "target": "Save to DB" 
-    },
-    { 
-      "type": "addConnection", 
-      "source": "HTTP Request", 
-      "target": "Error Handler" 
-    },
-    { 
-      "type": "addConnection", 
-      "source": "Error Handler", 
-      "target": "Send Alert" 
-    },
-    
-    // Then add the nodes
-    { 
-      "type": "addNode", 
-      "node": {
-        "name": "Error Handler",
-        "type": "n8n-nodes-base.if",
-        "position": [500, 400],
-        "parameters": {
-          "conditions": {
-            "boolean": [{
-              "value1": "={{$json.error}}",
-              "value2": true
-            }]
-          }
-        }
-      }
-    },
-    { 
-      "type": "addNode", 
-      "node": {
-        "name": "Send Alert",
-        "type": "n8n-nodes-base.emailSend",
-        "position": [700, 400],
-        "parameters": {
-          "to": "alerts@company.com",
-          "subject": "Workflow Error Alert"
-        }
-      }
-    }
-  ]
-}
-```
-
-All operations will be processed correctly, even though connections reference nodes that don't exist yet!

docs/validation-improvements-v2.4.2.md

@@ -1,92 +0,0 @@
-# Validation Improvements v2.4.2
-
-Based on AI agent feedback, we've implemented several improvements to the `validate_node_operation` tool:
-
-## 🎯 Issues Addressed
-
-### 1. **@version Warnings** ✅ FIXED
-- **Issue**: Showed confusing warnings about `@version` property not being used
-- **Fix**: Filter out internal properties starting with `@` or `_`
-- **Result**: No more false warnings about internal n8n properties
-
-### 2. **Duplicate Errors** ✅ FIXED
-- **Issue**: Same error shown multiple times (e.g., missing `ts` field)
-- **Fix**: Implemented deduplication that keeps the most specific error message
-- **Result**: Each error shown only once with the best description
-
-### 3. **Basic Code Validation** ✅ ADDED
-- **Issue**: No syntax validation for Code node
-- **Fix**: Added basic syntax checks for JavaScript and Python
-- **Features**:
-  - Unbalanced braces/parentheses detection
-  - Python indentation consistency check
-  - n8n-specific patterns (return statement, input access)
-  - Security warnings (eval/exec usage)
-
-## 📊 Before & After
-
-### Before (v2.4.1):
-```json
-{
-  "errors": [
-    { "property": "ts", "message": "Required property 'Message Timestamp' is missing" },
-    { "property": "ts", "message": "Message timestamp (ts) is required to update a message" }
-  ],
-  "warnings": [
-    { "property": "@version", "message": "Property '@version' is configured but won't be used" }
-  ]
-}
-```
-
-### After (v2.4.2):
-```json
-{
-  "errors": [
-    { "property": "ts", "message": "Message timestamp (ts) is required to update a message", 
-      "fix": "Provide the timestamp of the message to update" }
-  ],
-  "warnings": []  // No @version warning
-}
-```
-
-## 🆕 Code Validation Examples
-
-### JavaScript Syntax Check:
-```javascript
-// Missing closing brace
-if (true) {
-  return items;
-// Error: "Unbalanced braces detected"
-```
-
-### Python Indentation Check:
-```python
-def process():
-	if True:  # Tab
-    return items  # Spaces
-# Error: "Mixed tabs and spaces in indentation"
-```
-
-### n8n Pattern Check:
-```javascript
-const result = items.map(item => item.json);
-// Warning: "No return statement found"
-// Suggestion: "Add: return items;"
-```
-
-## 🚀 Impact
-
-- **Cleaner validation results** - No more noise from internal properties
-- **Clearer error messages** - Each issue reported once with best description
-- **Better code quality** - Basic syntax validation catches common mistakes
-- **n8n best practices** - Warns about missing return statements and input handling
-
-## 📝 Summary
-
-The `validate_node_operation` tool is now even more helpful for AI agents and developers:
-- 95% reduction in false positives (operation-aware)
-- No duplicate or confusing warnings
-- Basic code validation for common syntax errors
-- n8n-specific pattern checking
-
-**Rating improved from 9/10 to 9.5/10!** 🎉

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"
 }
 ```
 
@@ -577,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)
@@ -633,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
 
@@ -694,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,8 +1,16 @@
 {
   "name": "n8n-mcp",
-  "version": "2.15.3",
+  "version": "2.20.0",
   "description": "Integration between n8n workflow automation and Model Context Protocol (MCP)",
   "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.js"
+    }
+  },
   "bin": {
     "n8n-mcp": "./dist/mcp/index.js"
   },
@@ -131,15 +139,16 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.13.2",
-    "@n8n/n8n-nodes-langchain": "^1.112.2",
+    "@modelcontextprotocol/sdk": "^1.20.1",
+    "@n8n/n8n-nodes-langchain": "^1.114.1",
     "@supabase/supabase-js": "^2.57.4",
     "dotenv": "^16.5.0",
     "express": "^5.1.0",
+    "express-rate-limit": "^7.1.5",
     "lru-cache": "^11.2.1",
-    "n8n": "^1.113.3",
-    "n8n-core": "^1.112.1",
-    "n8n-workflow": "^1.110.0",
+    "n8n": "^1.115.2",
+    "n8n-core": "^1.114.0",
+    "n8n-workflow": "^1.112.0",
     "openai": "^4.77.0",
     "sql.js": "^1.13.0",
     "uuid": "^10.0.0",

package.runtime.json

@@ -1,12 +1,13 @@
 {
   "name": "n8n-mcp-runtime",
-  "version": "2.15.1",
+  "version": "2.19.6",
   "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",

release-notes-v2.7.0.md

@@ -1,60 +0,0 @@
-# n8n-MCP v2.7.0 Release Notes
-
-## 🎉 What's New
-
-### 🔧 File Refactoring & Version Management
-- **Renamed core MCP files** to remove unnecessary suffixes for cleaner codebase:
-  - `tools-update.ts` → `tools.ts`
-  - `server-update.ts` → `server.ts`
-  - `http-server-fixed.ts` → `http-server.ts`
-- **Fixed version management** - Now reads from package.json as single source of truth (fixes #5)
-- **Updated imports** across 21+ files to use the new file names
-
-### 🔍 New Diagnostic Tool
-- **Added `n8n_diagnostic` tool** - Helps troubleshoot why n8n management tools might not be appearing
-- Shows environment variable status, API connectivity, and tool availability
-- Provides step-by-step troubleshooting guidance
-- Includes verbose mode for additional debug information
-
-### 🧹 Code Cleanup
-- Removed legacy HTTP server implementation with known issues
-- Removed unused legacy API client
-- Added version utility for consistent version handling
-- Added script to sync runtime package version
-
-## 📦 Installation
-
-### Docker (Recommended)
-```bash
-docker pull ghcr.io/czlonkowski/n8n-mcp:2.7.0
-```
-
-### Claude Desktop
-Update your configuration to use the latest version:
-```json
-{
-  "mcpServers": {
-    "n8n-mcp": {
-      "command": "docker",
-      "args": ["run", "-i", "--rm", "ghcr.io/czlonkowski/n8n-mcp:2.7.0"]
-    }
-  }
-}
-```
-
-## 🐛 Bug Fixes
-- Fixed version mismatch where version was hardcoded as 2.4.1 instead of reading from package.json
-- Improved error messages for better debugging
-
-## 📚 Documentation Updates
-- Condensed version history in CLAUDE.md
-- Updated documentation structure in README.md
-- Removed outdated documentation files
-- Added n8n_diagnostic tool to documentation
-
-## 🙏 Acknowledgments
-Thanks to all contributors and users who reported issues!
-
----
-
-**Full Changelog**: https://github.com/czlonkowski/n8n-mcp/blob/main/CHANGELOG.md

scripts/audit-schema-coverage.ts

@@ -0,0 +1,78 @@
+/**
+ * Database Schema Coverage Audit Script
+ *
+ * Audits the database to determine how many nodes have complete schema information
+ * for resourceLocator mode validation. This helps assess the coverage of our
+ * schema-driven validation approach.
+ */
+
+import Database from 'better-sqlite3';
+import path from 'path';
+
+const dbPath = path.join(__dirname, '../data/nodes.db');
+const db = new Database(dbPath, { readonly: true });
+
+console.log('=== Schema Coverage Audit ===\n');
+
+// Query 1: How many nodes have resourceLocator properties?
+const totalResourceLocator = db.prepare(`
+  SELECT COUNT(*) as count FROM nodes
+  WHERE properties_schema LIKE '%resourceLocator%'
+`).get() as { count: number };
+
+console.log(`Nodes with resourceLocator properties: ${totalResourceLocator.count}`);
+
+// Query 2: Of those, how many have modes defined?
+const withModes = db.prepare(`
+  SELECT COUNT(*) as count FROM nodes
+  WHERE properties_schema LIKE '%resourceLocator%'
+    AND properties_schema LIKE '%modes%'
+`).get() as { count: number };
+
+console.log(`Nodes with modes defined: ${withModes.count}`);
+
+// Query 3: Which nodes have resourceLocator but NO modes?
+const withoutModes = db.prepare(`
+  SELECT node_type, display_name
+  FROM nodes
+  WHERE properties_schema LIKE '%resourceLocator%'
+    AND properties_schema NOT LIKE '%modes%'
+  LIMIT 10
+`).all() as Array<{ node_type: string; display_name: string }>;
+
+console.log(`\nSample nodes WITHOUT modes (showing 10):`);
+withoutModes.forEach(node => {
+  console.log(`  - ${node.display_name} (${node.node_type})`);
+});
+
+// Calculate coverage percentage
+const coverage = totalResourceLocator.count > 0
+  ? (withModes.count / totalResourceLocator.count) * 100
+  : 0;
+
+console.log(`\nSchema coverage: ${coverage.toFixed(1)}% of resourceLocator nodes have modes defined`);
+
+// Query 4: Get some examples of nodes WITH modes for verification
+console.log('\nSample nodes WITH modes (showing 5):');
+const withModesExamples = db.prepare(`
+  SELECT node_type, display_name
+  FROM nodes
+  WHERE properties_schema LIKE '%resourceLocator%'
+    AND properties_schema LIKE '%modes%'
+  LIMIT 5
+`).all() as Array<{ node_type: string; display_name: string }>;
+
+withModesExamples.forEach(node => {
+  console.log(`  - ${node.display_name} (${node.node_type})`);
+});
+
+// Summary
+console.log('\n=== Summary ===');
+console.log(`Total nodes in database: ${db.prepare('SELECT COUNT(*) as count FROM nodes').get() as any as { count: number }.count}`);
+console.log(`Nodes with resourceLocator: ${totalResourceLocator.count}`);
+console.log(`Nodes with complete mode schemas: ${withModes.count}`);
+console.log(`Nodes without mode schemas: ${totalResourceLocator.count - withModes.count}`);
+console.log(`\nImplication: Schema-driven validation will apply to ${withModes.count} nodes.`);
+console.log(`For the remaining ${totalResourceLocator.count - withModes.count} nodes, validation will be skipped (graceful degradation).`);
+
+db.close();

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/publish-npm.sh

@@ -11,29 +11,8 @@ NC='\033[0m' # No Color
 
 echo "🚀 Preparing n8n-mcp for npm publish..."
 
-# Run tests first to ensure quality
-echo "🧪 Running tests..."
-TEST_OUTPUT=$(npm test 2>&1)
-TEST_EXIT_CODE=$?
-
-# Check test results - look for actual test failures vs coverage issues
-if echo "$TEST_OUTPUT" | grep -q "Tests.*failed"; then
-    # Extract failed count using sed (portable)
-    FAILED_COUNT=$(echo "$TEST_OUTPUT" | sed -n 's/.*Tests.*\([0-9]*\) failed.*/\1/p' | head -1)
-    if [ "$FAILED_COUNT" != "0" ] && [ "$FAILED_COUNT" != "" ]; then
-        echo -e "${RED}❌ $FAILED_COUNT test(s) failed. Aborting publish.${NC}"
-        echo "$TEST_OUTPUT" | tail -20
-        exit 1
-    fi
-fi
-
-# If we got here, tests passed - check coverage
-if echo "$TEST_OUTPUT" | grep -q "Coverage.*does not meet global threshold"; then
-    echo -e "${YELLOW}⚠️  All tests passed but coverage is below threshold${NC}"
-    echo -e "${YELLOW}   Consider improving test coverage before next release${NC}"
-else
-    echo -e "${GREEN}✅ All tests passed with good coverage!${NC}"
-fi
+# Skip tests - they already run in CI before merge/publish
+echo "⏭️  Skipping tests (already verified in CI)"
 
 # Sync version to runtime package first
 echo "🔄 Syncing version to package.runtime.json..."
@@ -80,6 +59,15 @@ node -e "
 const pkg = require('./package.json');
 pkg.name = 'n8n-mcp';
 pkg.description = 'Integration between n8n workflow automation and Model Context Protocol (MCP)';
+pkg.main = 'dist/index.js';
+pkg.types = 'dist/index.d.ts';
+pkg.exports = {
+  '.': {
+    types: './dist/index.d.ts',
+    require: './dist/index.js',
+    import: './dist/index.js'
+  }
+};
 pkg.bin = { 'n8n-mcp': './dist/mcp/index.js' };
 pkg.repository = { type: 'git', url: 'git+https://github.com/czlonkowski/n8n-mcp.git' };
 pkg.keywords = ['n8n', 'mcp', 'model-context-protocol', 'ai', 'workflow', 'automation'];

scripts/test-ai-validation-debug.ts

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+/**
+ * Debug test for AI validation issues
+ * Reproduces the bugs found by n8n-mcp-tester
+ */
+
+import { validateAISpecificNodes, buildReverseConnectionMap } from '../src/services/ai-node-validator';
+import type { WorkflowJson } from '../src/services/ai-tool-validators';
+import { NodeTypeNormalizer } from '../src/utils/node-type-normalizer';
+
+console.log('=== AI Validation Debug Tests ===\n');
+
+// Test 1: AI Agent with NO language model connection
+console.log('Test 1: Missing Language Model Detection');
+const workflow1: WorkflowJson = {
+  name: 'Test Missing LM',
+  nodes: [
+    {
+      id: 'ai-agent-1',
+      name: 'AI Agent',
+      type: '@n8n/n8n-nodes-langchain.agent',
+      position: [500, 300],
+      parameters: {
+        promptType: 'define',
+        text: 'You are a helpful assistant'
+      },
+      typeVersion: 1.7
+    }
+  ],
+  connections: {
+    // NO connections - AI Agent is isolated
+  }
+};
+
+console.log('Workflow:', JSON.stringify(workflow1, null, 2));
+
+const reverseMap1 = buildReverseConnectionMap(workflow1);
+console.log('\nReverse connection map for AI Agent:');
+console.log('Entries:', Array.from(reverseMap1.entries()));
+console.log('AI Agent connections:', reverseMap1.get('AI Agent'));
+
+// Check node normalization
+const normalizedType1 = NodeTypeNormalizer.normalizeToFullForm(workflow1.nodes[0].type);
+console.log(`\nNode type: ${workflow1.nodes[0].type}`);
+console.log(`Normalized type: ${normalizedType1}`);
+console.log(`Match check: ${normalizedType1 === '@n8n/n8n-nodes-langchain.agent'}`);
+
+const issues1 = validateAISpecificNodes(workflow1);
+console.log('\nValidation issues:');
+console.log(JSON.stringify(issues1, null, 2));
+
+const hasMissingLMError = issues1.some(
+  i => i.severity === 'error' && i.code === 'MISSING_LANGUAGE_MODEL'
+);
+console.log(`\n✓ Has MISSING_LANGUAGE_MODEL error: ${hasMissingLMError}`);
+console.log(`✗ Expected: true, Got: ${hasMissingLMError}`);
+
+// Test 2: AI Agent WITH language model connection
+console.log('\n\n' + '='.repeat(60));
+console.log('Test 2: AI Agent WITH Language Model (Should be valid)');
+const workflow2: WorkflowJson = {
+  name: 'Test With LM',
+  nodes: [
+    {
+      id: 'openai-1',
+      name: 'OpenAI Chat Model',
+      type: '@n8n/n8n-nodes-langchain.lmChatOpenAi',
+      position: [200, 300],
+      parameters: {
+        modelName: 'gpt-4'
+      },
+      typeVersion: 1
+    },
+    {
+      id: 'ai-agent-1',
+      name: 'AI Agent',
+      type: '@n8n/n8n-nodes-langchain.agent',
+      position: [500, 300],
+      parameters: {
+        promptType: 'define',
+        text: 'You are a helpful assistant'
+      },
+      typeVersion: 1.7
+    }
+  ],
+  connections: {
+    'OpenAI Chat Model': {
+      ai_languageModel: [
+        [
+          {
+            node: 'AI Agent',
+            type: 'ai_languageModel',
+            index: 0
+          }
+        ]
+      ]
+    }
+  }
+};
+
+console.log('\nConnections:', JSON.stringify(workflow2.connections, null, 2));
+
+const reverseMap2 = buildReverseConnectionMap(workflow2);
+console.log('\nReverse connection map for AI Agent:');
+console.log('AI Agent connections:', reverseMap2.get('AI Agent'));
+
+const issues2 = validateAISpecificNodes(workflow2);
+console.log('\nValidation issues:');
+console.log(JSON.stringify(issues2, null, 2));
+
+const hasMissingLMError2 = issues2.some(
+  i => i.severity === 'error' && i.code === 'MISSING_LANGUAGE_MODEL'
+);
+console.log(`\n✓ Should NOT have MISSING_LANGUAGE_MODEL error: ${!hasMissingLMError2}`);
+console.log(`Expected: false, Got: ${hasMissingLMError2}`);
+
+// Test 3: AI Agent with tools but no language model
+console.log('\n\n' + '='.repeat(60));
+console.log('Test 3: AI Agent with Tools but NO Language Model');
+const workflow3: WorkflowJson = {
+  name: 'Test Tools No LM',
+  nodes: [
+    {
+      id: 'http-tool-1',
+      name: 'HTTP Request Tool',
+      type: '@n8n/n8n-nodes-langchain.toolHttpRequest',
+      position: [200, 300],
+      parameters: {
+        toolDescription: 'Calls an API',
+        url: 'https://api.example.com'
+      },
+      typeVersion: 1.1
+    },
+    {
+      id: 'ai-agent-1',
+      name: 'AI Agent',
+      type: '@n8n/n8n-nodes-langchain.agent',
+      position: [500, 300],
+      parameters: {
+        promptType: 'define',
+        text: 'You are a helpful assistant'
+      },
+      typeVersion: 1.7
+    }
+  ],
+  connections: {
+    'HTTP Request Tool': {
+      ai_tool: [
+        [
+          {
+            node: 'AI Agent',
+            type: 'ai_tool',
+            index: 0
+          }
+        ]
+      ]
+    }
+  }
+};
+
+console.log('\nConnections:', JSON.stringify(workflow3.connections, null, 2));
+
+const reverseMap3 = buildReverseConnectionMap(workflow3);
+console.log('\nReverse connection map for AI Agent:');
+const aiAgentConns = reverseMap3.get('AI Agent');
+console.log('AI Agent connections:', aiAgentConns);
+console.log('Connection types:', aiAgentConns?.map(c => c.type));
+
+const issues3 = validateAISpecificNodes(workflow3);
+console.log('\nValidation issues:');
+console.log(JSON.stringify(issues3, null, 2));
+
+const hasMissingLMError3 = issues3.some(
+  i => i.severity === 'error' && i.code === 'MISSING_LANGUAGE_MODEL'
+);
+const hasNoToolsInfo3 = issues3.some(
+  i => i.severity === 'info' && i.message.includes('no ai_tool connections')
+);
+
+console.log(`\n✓ Should have MISSING_LANGUAGE_MODEL error: ${hasMissingLMError3}`);
+console.log(`Expected: true, Got: ${hasMissingLMError3}`);
+console.log(`✗ Should NOT have "no tools" info: ${!hasNoToolsInfo3}`);
+console.log(`Expected: false, Got: ${hasNoToolsInfo3}`);
+
+console.log('\n' + '='.repeat(60));
+console.log('Summary:');
+console.log(`Test 1 (No LM): ${hasMissingLMError ? 'PASS ✓' : 'FAIL ✗'}`);
+console.log(`Test 2 (With LM): ${!hasMissingLMError2 ? 'PASS ✓' : 'FAIL ✗'}`);
+console.log(`Test 3 (Tools, No LM): ${hasMissingLMError3 && !hasNoToolsInfo3 ? 'PASS ✓' : 'FAIL ✗'}`);

scripts/test-docker-fingerprint.ts

@@ -0,0 +1,163 @@
+/**
+ * Test Docker Host Fingerprinting
+ * Verifies that host machine characteristics are stable across container recreations
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { platform, arch } from 'os';
+import { createHash } from 'crypto';
+
+console.log('=== Docker Host Fingerprinting Test ===\n');
+
+function generateHostFingerprint(): string {
+  try {
+    const signals: string[] = [];
+
+    console.log('Collecting host signals...\n');
+
+    // CPU info (stable across container recreations)
+    if (existsSync('/proc/cpuinfo')) {
+      const cpuinfo = readFileSync('/proc/cpuinfo', 'utf-8');
+      const modelMatch = cpuinfo.match(/model name\s*:\s*(.+)/);
+      const coresMatch = cpuinfo.match(/processor\s*:/g);
+
+      if (modelMatch) {
+        const cpuModel = modelMatch[1].trim();
+        signals.push(cpuModel);
+        console.log('✓ CPU Model:', cpuModel);
+      }
+
+      if (coresMatch) {
+        const cores = `cores:${coresMatch.length}`;
+        signals.push(cores);
+        console.log('✓ CPU Cores:', coresMatch.length);
+      }
+    } else {
+      console.log('✗ /proc/cpuinfo not available (Windows/Mac Docker)');
+    }
+
+    // Memory (stable)
+    if (existsSync('/proc/meminfo')) {
+      const meminfo = readFileSync('/proc/meminfo', 'utf-8');
+      const totalMatch = meminfo.match(/MemTotal:\s+(\d+)/);
+
+      if (totalMatch) {
+        const memory = `mem:${totalMatch[1]}`;
+        signals.push(memory);
+        console.log('✓ Total Memory:', totalMatch[1], 'kB');
+      }
+    } else {
+      console.log('✗ /proc/meminfo not available (Windows/Mac Docker)');
+    }
+
+    // Docker network subnet
+    const networkInfo = getDockerNetworkInfo();
+    if (networkInfo) {
+      signals.push(networkInfo);
+      console.log('✓ Network Info:', networkInfo);
+    } else {
+      console.log('✗ Network info not available');
+    }
+
+    // Platform basics (stable)
+    signals.push(platform(), arch());
+    console.log('✓ Platform:', platform());
+    console.log('✓ Architecture:', arch());
+
+    // Generate stable ID from all signals
+    console.log('\nCombined signals:', signals.join(' | '));
+    const fingerprint = signals.join('-');
+    const userId = createHash('sha256').update(fingerprint).digest('hex').substring(0, 16);
+
+    return userId;
+
+  } catch (error) {
+    console.error('Error generating fingerprint:', error);
+    // Fallback
+    return createHash('sha256')
+      .update(`${platform()}-${arch()}-docker`)
+      .digest('hex')
+      .substring(0, 16);
+  }
+}
+
+function getDockerNetworkInfo(): string | null {
+  try {
+    // Read routing table to get bridge network
+    if (existsSync('/proc/net/route')) {
+      const routes = readFileSync('/proc/net/route', 'utf-8');
+      const lines = routes.split('\n');
+
+      for (const line of lines) {
+        if (line.includes('eth0')) {
+          const parts = line.split(/\s+/);
+          if (parts[2]) {
+            const gateway = parseInt(parts[2], 16).toString(16);
+            return `net:${gateway}`;
+          }
+        }
+      }
+    }
+  } catch {
+    // Ignore errors
+  }
+  return null;
+}
+
+// Test environment detection
+console.log('\n=== Environment Detection ===\n');
+
+const isDocker = process.env.IS_DOCKER === 'true';
+const isCloudEnvironment = !!(
+  process.env.RAILWAY_ENVIRONMENT ||
+  process.env.RENDER ||
+  process.env.FLY_APP_NAME ||
+  process.env.HEROKU_APP_NAME ||
+  process.env.AWS_EXECUTION_ENV ||
+  process.env.KUBERNETES_SERVICE_HOST
+);
+
+console.log('IS_DOCKER env:', process.env.IS_DOCKER);
+console.log('Docker detected:', isDocker);
+console.log('Cloud environment:', isCloudEnvironment);
+
+// Generate fingerprints
+console.log('\n=== Fingerprint Generation ===\n');
+
+const fingerprint1 = generateHostFingerprint();
+const fingerprint2 = generateHostFingerprint();
+const fingerprint3 = generateHostFingerprint();
+
+console.log('\nFingerprint 1:', fingerprint1);
+console.log('Fingerprint 2:', fingerprint2);
+console.log('Fingerprint 3:', fingerprint3);
+
+const consistent = fingerprint1 === fingerprint2 && fingerprint2 === fingerprint3;
+console.log('\nConsistent:', consistent ? '✓ YES' : '✗ NO');
+
+// Test explicit ID override
+console.log('\n=== Environment Variable Override Test ===\n');
+
+if (process.env.N8N_MCP_USER_ID) {
+  console.log('Explicit user ID:', process.env.N8N_MCP_USER_ID);
+  console.log('This would override the fingerprint');
+} else {
+  console.log('No explicit user ID set');
+  console.log('To test: N8N_MCP_USER_ID=my-custom-id npx tsx ' + process.argv[1]);
+}
+
+// Stability estimate
+console.log('\n=== Stability Analysis ===\n');
+
+const hasStableSignals = existsSync('/proc/cpuinfo') || existsSync('/proc/meminfo');
+if (hasStableSignals) {
+  console.log('✓ Host-based signals available');
+  console.log('✓ Fingerprint should be stable across container recreations');
+  console.log('✓ Different fingerprints on different physical hosts');
+} else {
+  console.log('⚠️  Limited host signals (Windows/Mac Docker Desktop)');
+  console.log('⚠️  Fingerprint may not be fully stable');
+  console.log('💡 Recommendation: Use N8N_MCP_USER_ID env var for stability');
+}
+
+console.log('\n');

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-user-id-persistence.ts

@@ -0,0 +1,119 @@
+/**
+ * Test User ID Persistence
+ * Verifies that user IDs are consistent across sessions and modes
+ */
+
+import { TelemetryConfigManager } from '../src/telemetry/config-manager';
+import { hostname, platform, arch, homedir } from 'os';
+import { createHash } from 'crypto';
+
+console.log('=== User ID Persistence Test ===\n');
+
+// Test 1: Verify deterministic ID generation
+console.log('Test 1: Deterministic ID Generation');
+console.log('-----------------------------------');
+
+const machineId = `${hostname()}-${platform()}-${arch()}-${homedir()}`;
+const expectedUserId = createHash('sha256')
+  .update(machineId)
+  .digest('hex')
+  .substring(0, 16);
+
+console.log('Machine characteristics:');
+console.log('  hostname:', hostname());
+console.log('  platform:', platform());
+console.log('  arch:', arch());
+console.log('  homedir:', homedir());
+console.log('\nGenerated machine ID:', machineId);
+console.log('Expected user ID:', expectedUserId);
+
+// Test 2: Load actual config
+console.log('\n\nTest 2: Actual Config Manager');
+console.log('-----------------------------------');
+
+const configManager = TelemetryConfigManager.getInstance();
+const actualUserId = configManager.getUserId();
+const config = configManager.loadConfig();
+
+console.log('Actual user ID:', actualUserId);
+console.log('Config first run:', config.firstRun || 'Unknown');
+console.log('Config version:', config.version || 'Unknown');
+console.log('Telemetry enabled:', config.enabled);
+
+// Test 3: Verify consistency
+console.log('\n\nTest 3: Consistency Check');
+console.log('-----------------------------------');
+
+const match = actualUserId === expectedUserId;
+console.log('User IDs match:', match ? '✓ YES' : '✗ NO');
+
+if (!match) {
+  console.log('WARNING: User ID mismatch detected!');
+  console.log('This could indicate an implementation issue.');
+}
+
+// Test 4: Multiple loads (simulate multiple sessions)
+console.log('\n\nTest 4: Multiple Session Simulation');
+console.log('-----------------------------------');
+
+const userId1 = configManager.getUserId();
+const userId2 = TelemetryConfigManager.getInstance().getUserId();
+const userId3 = configManager.getUserId();
+
+console.log('Session 1 user ID:', userId1);
+console.log('Session 2 user ID:', userId2);
+console.log('Session 3 user ID:', userId3);
+
+const consistent = userId1 === userId2 && userId2 === userId3;
+console.log('All sessions consistent:', consistent ? '✓ YES' : '✗ NO');
+
+// Test 5: Docker environment simulation
+console.log('\n\nTest 5: Docker Environment Check');
+console.log('-----------------------------------');
+
+const isDocker = process.env.IS_DOCKER === 'true';
+console.log('Running in Docker:', isDocker);
+
+if (isDocker) {
+  console.log('\n⚠️  DOCKER MODE DETECTED');
+  console.log('In Docker, user IDs may change across container recreations because:');
+  console.log('  1. Container hostname changes each time');
+  console.log('  2. Config file is not persisted (no volume mount)');
+  console.log('  3. Each container gets a new ephemeral filesystem');
+  console.log('\nRecommendation: Mount ~/.n8n-mcp as a volume for persistent user IDs');
+}
+
+// Test 6: Environment variable override check
+console.log('\n\nTest 6: Environment Variable Override');
+console.log('-----------------------------------');
+
+const telemetryDisabledVars = [
+  'N8N_MCP_TELEMETRY_DISABLED',
+  'TELEMETRY_DISABLED',
+  'DISABLE_TELEMETRY'
+];
+
+telemetryDisabledVars.forEach(varName => {
+  const value = process.env[varName];
+  if (value !== undefined) {
+    console.log(`${varName}:`, value);
+  }
+});
+
+console.log('\nTelemetry status:', configManager.isEnabled() ? 'ENABLED' : 'DISABLED');
+
+// Summary
+console.log('\n\n=== SUMMARY ===');
+console.log('User ID:', actualUserId);
+console.log('Deterministic:', match ? 'YES ✓' : 'NO ✗');
+console.log('Persistent across sessions:', consistent ? 'YES ✓' : 'NO ✗');
+console.log('Telemetry enabled:', config.enabled ? 'YES' : 'NO');
+console.log('Docker mode:', isDocker ? 'YES' : 'NO');
+
+if (isDocker && !process.env.N8N_MCP_CONFIG_VOLUME) {
+  console.log('\n⚠️  WARNING: Running in Docker without persistent volume!');
+  console.log('User IDs will change on container recreation.');
+  console.log('Mount /home/nodejs/.n8n-mcp to persist telemetry config.');
+}
+
+console.log('\n');

src/data/canonical-ai-tool-examples.json

@@ -0,0 +1,310 @@
+{
+  "description": "Canonical configuration examples for critical AI tools based on FINAL_AI_VALIDATION_SPEC.md",
+  "version": "1.0.0",
+  "examples": [
+    {
+      "node_type": "@n8n/n8n-nodes-langchain.toolHttpRequest",
+      "display_name": "HTTP Request Tool",
+      "examples": [
+        {
+          "name": "Weather API Tool",
+          "use_case": "Fetch current weather data for AI Agent",
+          "complexity": "simple",
+          "parameters": {
+            "method": "GET",
+            "url": "https://api.weatherapi.com/v1/current.json?key={{$credentials.weatherApiKey}}&q={city}",
+            "toolDescription": "Get current weather conditions for a city. Provide the city name (e.g., 'London', 'New York') and receive temperature, humidity, wind speed, and conditions.",
+            "placeholderDefinitions": {
+              "values": [
+                {
+                  "name": "city",
+                  "description": "Name of the city to get weather for",
+                  "type": "string"
+                }
+              ]
+            },
+            "authentication": "predefinedCredentialType",
+            "nodeCredentialType": "weatherApiApi"
+          },
+          "credentials": {
+            "weatherApiApi": {
+              "id": "1",
+              "name": "Weather API account"
+            }
+          },
+          "notes": "Example shows proper toolDescription, URL with placeholder, and credential configuration"
+        },
+        {
+          "name": "GitHub Issues Tool",
+          "use_case": "Create GitHub issues from AI Agent conversations",
+          "complexity": "medium",
+          "parameters": {
+            "method": "POST",
+            "url": "https://api.github.com/repos/{owner}/{repo}/issues",
+            "toolDescription": "Create a new GitHub issue. Requires owner (repo owner username), repo (repository name), title, and body. Returns the created issue URL and number.",
+            "placeholderDefinitions": {
+              "values": [
+                {
+                  "name": "owner",
+                  "description": "GitHub repository owner username",
+                  "type": "string"
+                },
+                {
+                  "name": "repo",
+                  "description": "Repository name",
+                  "type": "string"
+                },
+                {
+                  "name": "title",
+                  "description": "Issue title",
+                  "type": "string"
+                },
+                {
+                  "name": "body",
+                  "description": "Issue description and details",
+                  "type": "string"
+                }
+              ]
+            },
+            "sendBody": true,
+            "specifyBody": "json",
+            "jsonBody": "={{ { \"title\": $json.title, \"body\": $json.body } }}",
+            "authentication": "predefinedCredentialType",
+            "nodeCredentialType": "githubApi"
+          },
+          "credentials": {
+            "githubApi": {
+              "id": "2",
+              "name": "GitHub credentials"
+            }
+          },
+          "notes": "Example shows POST request with JSON body, multiple placeholders, and expressions"
+        },
+        {
+          "name": "Slack Message Tool",
+          "use_case": "Send Slack messages from AI Agent",
+          "complexity": "simple",
+          "parameters": {
+            "method": "POST",
+            "url": "https://slack.com/api/chat.postMessage",
+            "toolDescription": "Send a message to a Slack channel. Provide channel ID or name (e.g., '#general', 'C1234567890') and message text.",
+            "placeholderDefinitions": {
+              "values": [
+                {
+                  "name": "channel",
+                  "description": "Channel ID or name (e.g., #general)",
+                  "type": "string"
+                },
+                {
+                  "name": "text",
+                  "description": "Message text to send",
+                  "type": "string"
+                }
+              ]
+            },
+            "sendHeaders": true,
+            "headerParameters": {
+              "parameters": [
+                {
+                  "name": "Content-Type",
+                  "value": "application/json; charset=utf-8"
+                },
+                {
+                  "name": "Authorization",
+                  "value": "=Bearer {{$credentials.slackApi.accessToken}}"
+                }
+              ]
+            },
+            "sendBody": true,
+            "specifyBody": "json",
+            "jsonBody": "={{ { \"channel\": $json.channel, \"text\": $json.text } }}",
+            "authentication": "predefinedCredentialType",
+            "nodeCredentialType": "slackApi"
+          },
+          "credentials": {
+            "slackApi": {
+              "id": "3",
+              "name": "Slack account"
+            }
+          },
+          "notes": "Example shows headers with credential expressions and JSON body construction"
+        }
+      ]
+    },
+    {
+      "node_type": "@n8n/n8n-nodes-langchain.toolCode",
+      "display_name": "Code Tool",
+      "examples": [
+        {
+          "name": "Calculate Shipping Cost",
+          "use_case": "Calculate shipping costs based on weight and distance",
+          "complexity": "simple",
+          "parameters": {
+            "name": "calculate_shipping_cost",
+            "description": "Calculate shipping cost based on package weight (in kg) and distance (in km). Returns the cost in USD.",
+            "language": "javaScript",
+            "code": "const baseRate = 5;\nconst perKgRate = 2;\nconst perKmRate = 0.1;\n\nconst weight = $input.weight || 0;\nconst distance = $input.distance || 0;\n\nconst cost = baseRate + (weight * perKgRate) + (distance * perKmRate);\n\nreturn { cost: parseFloat(cost.toFixed(2)), currency: 'USD' };",
+            "specifyInputSchema": true,
+            "schemaType": "manual",
+            "inputSchema": "{\n  \"type\": \"object\",\n  \"properties\": {\n    \"weight\": {\n      \"type\": \"number\",\n      \"description\": \"Package weight in kilograms\"\n    },\n    \"distance\": {\n      \"type\": \"number\",\n      \"description\": \"Shipping distance in kilometers\"\n    }\n  },\n  \"required\": [\"weight\", \"distance\"]\n}"
+          },
+          "notes": "Example shows proper function naming, detailed description, input schema, and return value"
+        },
+        {
+          "name": "Format Customer Data",
+          "use_case": "Transform and validate customer information",
+          "complexity": "medium",
+          "parameters": {
+            "name": "format_customer_data",
+            "description": "Format and validate customer data. Takes raw customer info (name, email, phone) and returns formatted object with validation status.",
+            "language": "javaScript",
+            "code": "const { name, email, phone } = $input;\n\n// Validation\nconst emailRegex = /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/;\nconst phoneRegex = /^\\+?[1-9]\\d{1,14}$/;\n\nconst errors = [];\nif (!emailRegex.test(email)) errors.push('Invalid email format');\nif (!phoneRegex.test(phone)) errors.push('Invalid phone format');\n\n// Formatting\nconst formatted = {\n  name: name.trim(),\n  email: email.toLowerCase().trim(),\n  phone: phone.replace(/\\s/g, ''),\n  valid: errors.length === 0,\n  errors: errors\n};\n\nreturn formatted;",
+            "specifyInputSchema": true,
+            "schemaType": "manual",
+            "inputSchema": "{\n  \"type\": \"object\",\n  \"properties\": {\n    \"name\": {\n      \"type\": \"string\",\n      \"description\": \"Customer full name\"\n    },\n    \"email\": {\n      \"type\": \"string\",\n      \"description\": \"Customer email address\"\n    },\n    \"phone\": {\n      \"type\": \"string\",\n      \"description\": \"Customer phone number\"\n    }\n  },\n  \"required\": [\"name\", \"email\", \"phone\"]\n}"
+          },
+          "notes": "Example shows data validation, formatting, and structured error handling"
+        },
+        {
+          "name": "Parse Date Range",
+          "use_case": "Convert natural language date ranges to ISO format",
+          "complexity": "medium",
+          "parameters": {
+            "name": "parse_date_range",
+            "description": "Parse natural language date ranges (e.g., 'last 7 days', 'this month', 'Q1 2024') into start and end dates in ISO format.",
+            "language": "javaScript",
+            "code": "const input = $input.dateRange || '';\nconst now = new Date();\nlet start, end;\n\nif (input.includes('last') && input.includes('days')) {\n  const days = parseInt(input.match(/\\d+/)[0]);\n  start = new Date(now.getTime() - (days * 24 * 60 * 60 * 1000));\n  end = now;\n} else if (input === 'this month') {\n  start = new Date(now.getFullYear(), now.getMonth(), 1);\n  end = new Date(now.getFullYear(), now.getMonth() + 1, 0);\n} else if (input === 'this year') {\n  start = new Date(now.getFullYear(), 0, 1);\n  end = new Date(now.getFullYear(), 11, 31);\n} else {\n  throw new Error('Unsupported date range format');\n}\n\nreturn {\n  startDate: start.toISOString().split('T')[0],\n  endDate: end.toISOString().split('T')[0],\n  daysCount: Math.ceil((end - start) / (24 * 60 * 60 * 1000))\n};",
+            "specifyInputSchema": true,
+            "schemaType": "manual",
+            "inputSchema": "{\n  \"type\": \"object\",\n  \"properties\": {\n    \"dateRange\": {\n      \"type\": \"string\",\n      \"description\": \"Natural language date range (e.g., 'last 7 days', 'this month')\"\n    }\n  },\n  \"required\": [\"dateRange\"]\n}"
+          },
+          "notes": "Example shows complex logic, error handling, and date manipulation"
+        }
+      ]
+    },
+    {
+      "node_type": "@n8n/n8n-nodes-langchain.agentTool",
+      "display_name": "AI Agent Tool",
+      "examples": [
+        {
+          "name": "Research Specialist Agent",
+          "use_case": "Specialized sub-agent for in-depth research tasks",
+          "complexity": "medium",
+          "parameters": {
+            "name": "research_specialist",
+            "description": "Expert research agent that can search multiple sources, synthesize information, and provide comprehensive analysis on any topic. Use this when you need detailed, well-researched information.",
+            "promptType": "define",
+            "text": "You are a research specialist. Your role is to:\n1. Search for relevant information from multiple sources\n2. Synthesize findings into a coherent analysis\n3. Cite your sources\n4. Highlight key insights and patterns\n\nProvide thorough, well-structured research that answers the user's question comprehensively.",
+            "systemMessage": "You are a meticulous researcher focused on accuracy and completeness. Always cite sources and acknowledge limitations in available information."
+          },
+          "connections": {
+            "ai_languageModel": [
+              {
+                "node": "OpenAI GPT-4",
+                "type": "ai_languageModel",
+                "index": 0
+              }
+            ],
+            "ai_tool": [
+              {
+                "node": "SerpApi Tool",
+                "type": "ai_tool",
+                "index": 0
+              },
+              {
+                "node": "Wikipedia Tool",
+                "type": "ai_tool",
+                "index": 0
+              }
+            ]
+          },
+          "notes": "Example shows specialized sub-agent with custom prompt, specific system message, and multiple search tools"
+        },
+        {
+          "name": "Data Analysis Agent",
+          "use_case": "Sub-agent for analyzing and visualizing data",
+          "complexity": "complex",
+          "parameters": {
+            "name": "data_analyst",
+            "description": "Data analysis specialist that can process datasets, calculate statistics, identify trends, and generate insights. Use for any data analysis or statistical questions.",
+            "promptType": "auto",
+            "systemMessage": "You are a data analyst with expertise in statistics and data interpretation. Break down complex datasets into understandable insights. Use the Code Tool to perform calculations when needed.",
+            "maxIterations": 10
+          },
+          "connections": {
+            "ai_languageModel": [
+              {
+                "node": "Anthropic Claude",
+                "type": "ai_languageModel",
+                "index": 0
+              }
+            ],
+            "ai_tool": [
+              {
+                "node": "Code Tool - Stats",
+                "type": "ai_tool",
+                "index": 0
+              },
+              {
+                "node": "HTTP Request Tool - Data API",
+                "type": "ai_tool",
+                "index": 0
+              }
+            ]
+          },
+          "notes": "Example shows auto prompt type with specialized system message and analytical tools"
+        }
+      ]
+    },
+    {
+      "node_type": "@n8n/n8n-nodes-langchain.mcpClientTool",
+      "display_name": "MCP Client Tool",
+      "examples": [
+        {
+          "name": "Filesystem MCP Tool",
+          "use_case": "Access filesystem operations via MCP protocol",
+          "complexity": "medium",
+          "parameters": {
+            "description": "Access file system operations through MCP. Can read files, list directories, create files, and search for content.",
+            "mcpServer": {
+              "transport": "stdio",
+              "command": "npx",
+              "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"]
+            },
+            "tool": "read_file"
+          },
+          "notes": "Example shows stdio transport MCP server with filesystem access tool"
+        },
+        {
+          "name": "Puppeteer MCP Tool",
+          "use_case": "Browser automation via MCP for AI Agents",
+          "complexity": "complex",
+          "parameters": {
+            "description": "Control a web browser to navigate pages, take screenshots, and extract content. Useful for web scraping and automated testing.",
+            "mcpServer": {
+              "transport": "stdio",
+              "command": "npx",
+              "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
+            },
+            "tool": "puppeteer_navigate"
+          },
+          "notes": "Example shows Puppeteer MCP server for browser automation"
+        },
+        {
+          "name": "Database MCP Tool",
+          "use_case": "Query databases via MCP protocol",
+          "complexity": "complex",
+          "parameters": {
+            "description": "Execute SQL queries and retrieve data from PostgreSQL databases. Supports SELECT, INSERT, UPDATE operations with proper escaping.",
+            "mcpServer": {
+              "transport": "sse",
+              "url": "https://mcp-server.example.com/database"
+            },
+            "tool": "execute_query"
+          },
+          "notes": "Example shows SSE transport MCP server for remote database access"
+        }
+      ]
+    }
+  ]
+}

src/database/node-repository.ts

@@ -7,11 +7,12 @@ export class NodeRepository {
   private db: DatabaseAdapter;
   
   constructor(dbOrService: DatabaseAdapter | SQLiteStorageService) {
-    if ('db' in dbOrService) {
+    if (dbOrService instanceof SQLiteStorageService) {
       this.db = dbOrService.db;
-    } else {
-      this.db = dbOrService;
+      return;
     }
+
+    this.db = dbOrService;
   }
   
   /**
@@ -122,10 +123,22 @@ export class NodeRepository {
     return rows.map(row => this.parseNodeRow(row));
   }
 
+  /**
+   * Legacy LIKE-based search method for direct repository usage.
+   *
+   * NOTE: MCP tools do NOT use this method. They use MCPServer.searchNodes()
+   * which automatically detects and uses FTS5 full-text search when available.
+   * See src/mcp/server.ts:1135-1148 for FTS5 implementation.
+   *
+   * This method remains for:
+   * - Direct repository access in scripts/benchmarks
+   * - Fallback when FTS5 table doesn't exist
+   * - Legacy compatibility
+   */
   searchNodes(query: string, mode: 'OR' | 'AND' | 'FUZZY' = 'OR', limit: number = 20): any[] {
     let sql = '';
     const params: any[] = [];
-    
+
     if (mode === 'FUZZY') {
       // Simple fuzzy search
       sql = `

src/database/schema.sql

@@ -25,6 +25,40 @@ CREATE INDEX IF NOT EXISTS idx_package ON nodes(package_name);
 CREATE INDEX IF NOT EXISTS idx_ai_tool ON nodes(is_ai_tool);
 CREATE INDEX IF NOT EXISTS idx_category ON nodes(category);
 
+-- FTS5 full-text search index for nodes
+CREATE VIRTUAL TABLE IF NOT EXISTS nodes_fts USING fts5(
+  node_type,
+  display_name,
+  description,
+  documentation,
+  operations,
+  content=nodes,
+  content_rowid=rowid
+);
+
+-- Triggers to keep FTS5 in sync with nodes table
+CREATE TRIGGER IF NOT EXISTS nodes_fts_insert AFTER INSERT ON nodes
+BEGIN
+  INSERT INTO nodes_fts(rowid, node_type, display_name, description, documentation, operations)
+  VALUES (new.rowid, new.node_type, new.display_name, new.description, new.documentation, new.operations);
+END;
+
+CREATE TRIGGER IF NOT EXISTS nodes_fts_update AFTER UPDATE ON nodes
+BEGIN
+  UPDATE nodes_fts
+  SET node_type = new.node_type,
+      display_name = new.display_name,
+      description = new.description,
+      documentation = new.documentation,
+      operations = new.operations
+  WHERE rowid = new.rowid;
+END;
+
+CREATE TRIGGER IF NOT EXISTS nodes_fts_delete AFTER DELETE ON nodes
+BEGIN
+  DELETE FROM nodes_fts WHERE rowid = old.rowid;
+END;
+
 -- Templates table for n8n workflow templates
 CREATE TABLE IF NOT EXISTS templates (
   id INTEGER PRIMARY KEY,
@@ -108,5 +142,6 @@ 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
+-- Note: Template FTS5 tables are created conditionally at runtime if FTS5 is supported
+-- See template-repository.ts initializeFTS5() method
+-- Node FTS5 table (nodes_fts) is created above during schema initialization

src/http-server-single-session.ts

@@ -5,11 +5,13 @@
  * 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';
@@ -186,11 +188,22 @@ export class SingleSessionHTTPServer {
   
   /**
    * Validate session ID format
+   *
+   * Accepts any non-empty string to support various MCP clients:
+   * - UUIDv4 (internal n8n-mcp format)
+   * - instance-{userId}-{hash}-{uuid} (multi-tenant format)
+   * - Custom formats from mcp-remote and other proxies
+   *
+   * Security: Session validation happens via lookup in this.transports,
+   * not format validation. This ensures compatibility with all MCP clients.
+   *
+   * @param sessionId - Session identifier from MCP client
+   * @returns true if valid, false otherwise
    */
   private isValidSessionId(sessionId: string): boolean {
-    // UUID v4 format validation
-    const uuidv4Regex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-    return uuidv4Regex.test(sessionId);
+    // Accept any non-empty string as session ID
+    // This ensures compatibility with all MCP clients and proxies
+    return Boolean(sessionId && sessionId.length > 0);
   }
   
   /**
@@ -988,8 +1001,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,
@@ -1080,15 +1126,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,

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/index.ts

@@ -10,6 +10,22 @@ export { SingleSessionHTTPServer } from './http-server-single-session';
 export { ConsoleManager } from './utils/console-manager';
 export { N8NDocumentationMCPServer } from './mcp/server';
 
+// Type exports for multi-tenant and library usage
+export type {
+  InstanceContext
+} from './types/instance-context';
+export {
+  validateInstanceContext,
+  isInstanceContext
+} from './types/instance-context';
+
+// Re-export MCP SDK types for convenience
+export type {
+  Tool,
+  CallToolResult,
+  ListToolsResult
+} from '@modelcontextprotocol/sdk/types.js';
+
 // Default export for convenience
 import N8NMCPEngine from './mcp-engine';
 export default N8NMCPEngine;

src/mcp-tools-engine.ts

@@ -62,8 +62,12 @@ export class MCPEngine {
         hiddenProperties: []
       };
     }
-    
-    return ConfigValidator.validate(args.nodeType, args.config, node.properties || []);
+
+    // CRITICAL FIX: Extract user-provided keys before validation
+    // This prevents false warnings about default values
+    const userProvidedKeys = new Set(Object.keys(args.config || {}));
+
+    return ConfigValidator.validate(args.nodeType, args.config, node.properties || [], userProvidedKeys);
   }
 
   async validateNodeMinimal(args: any) {

src/mcp/handlers-n8n-manager.ts

@@ -30,7 +30,7 @@ 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 { ExpressionFormatValidator, ExpressionFormatIssue } from '../services/expression-format-validator';
 import { handleUpdatePartialWorkflow } from './handlers-workflow-diff';
 import { telemetry } from '../telemetry';
 import {
@@ -42,7 +42,145 @@ import {
   getCacheStatistics
 } from '../utils/cache-utils';
 import { processExecution } from '../services/execution-processor';
+import { checkNpmVersion, formatVersionMessage } from '../utils/npm-version-checker';
 
+// ========================================================================
+// TypeScript Interfaces for Type Safety
+// ========================================================================
+
+/**
+ * Health Check Response Data Structure
+ */
+interface HealthCheckResponseData {
+  status: string;
+  instanceId?: string;
+  n8nVersion?: string;
+  features?: Record<string, unknown>;
+  apiUrl?: string;
+  mcpVersion: string;
+  supportedN8nVersion?: string;
+  versionCheck: {
+    current: string;
+    latest: string | null;
+    upToDate: boolean;
+    message: string;
+    updateCommand?: string;
+  };
+  performance: {
+    responseTimeMs: number;
+    cacheHitRate: string;
+    cachedInstances: number;
+  };
+  nextSteps?: string[];
+  updateWarning?: string;
+}
+
+/**
+ * Cloud Platform Guide Structure
+ */
+interface CloudPlatformGuide {
+  name: string;
+  troubleshooting: string[];
+}
+
+/**
+ * Workflow Validation Response Data
+ */
+interface WorkflowValidationResponse {
+  valid: boolean;
+  workflowId?: string;
+  workflowName?: string;
+  summary: {
+    totalNodes: number;
+    enabledNodes: number;
+    triggerNodes: number;
+    validConnections: number;
+    invalidConnections: number;
+    expressionsValidated: number;
+    errorCount: number;
+    warningCount: number;
+  };
+  errors?: Array<{
+    node: string;
+    nodeName?: string;
+    message: string;
+    details?: Record<string, unknown>;
+  }>;
+  warnings?: Array<{
+    node: string;
+    nodeName?: string;
+    message: string;
+    details?: Record<string, unknown>;
+  }>;
+  suggestions?: unknown[];
+}
+
+/**
+ * Diagnostic Response Data Structure
+ */
+interface DiagnosticResponseData {
+  timestamp: string;
+  environment: {
+    N8N_API_URL: string | null;
+    N8N_API_KEY: string | null;
+    NODE_ENV: string;
+    MCP_MODE: string;
+    isDocker: boolean;
+    cloudPlatform: string | null;
+    nodeVersion: string;
+    platform: string;
+  };
+  apiConfiguration: {
+    configured: boolean;
+    status: {
+      configured: boolean;
+      connected: boolean;
+      error: string | null;
+      version: string | null;
+    };
+    config: {
+      baseUrl: string;
+      timeout: number;
+      maxRetries: number;
+    } | null;
+  };
+  versionInfo: {
+    current: string;
+    latest: string | null;
+    upToDate: boolean;
+    message: string;
+    updateCommand?: string;
+  };
+  toolsAvailability: {
+    documentationTools: {
+      count: number;
+      enabled: boolean;
+      description: string;
+    };
+    managementTools: {
+      count: number;
+      enabled: boolean;
+      description: string;
+    };
+    totalAvailable: number;
+  };
+  performance: {
+    diagnosticResponseTimeMs: number;
+    cacheHitRate: string;
+    cachedInstances: number;
+  };
+  modeSpecificDebug: Record<string, unknown>;
+  dockerDebug?: Record<string, unknown>;
+  cloudPlatformDebug?: CloudPlatformGuide;
+  nextSteps?: Record<string, unknown>;
+  troubleshooting?: Record<string, unknown>;
+  setupGuide?: Record<string, unknown>;
+  updateWarning?: Record<string, unknown>;
+  debug?: Record<string, unknown>;
+  [key: string]: unknown; // Allow dynamic property access for optional fields
+}
+
+// ========================================================================
 // Singleton n8n API client instance (backward compatibility)
 let defaultApiClient: N8nApiClient | null = null;
 let lastDefaultConfigUrl: string | null = null;
@@ -552,16 +690,12 @@ export async function handleUpdateWorkflow(args: unknown, context?: InstanceCont
 
     // 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);
@@ -611,11 +745,12 @@ export async function handleDeleteWorkflow(args: unknown, context?: InstanceCont
   try {
     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) {
@@ -646,12 +781,17 @@ export async function handleListWorkflows(args: unknown, context?: InstanceConte
   try {
     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
     });
@@ -729,7 +869,7 @@ export async function handleValidateWorkflow(
     const validationResult = await validator.validateWorkflow(workflow, input.options);
     
     // Format the response (same format as the regular validate_workflow tool)
-    const response: any = {
+    const response: WorkflowValidationResponse = {
       valid: validationResult.valid,
       workflowId: workflow.id,
       workflowName: workflow.name,
@@ -748,14 +888,16 @@ export async function handleValidateWorkflow(
     if (validationResult.errors.length > 0) {
       response.errors = validationResult.errors.map(e => ({
         node: e.nodeName || 'workflow',
+        nodeName: e.nodeName, // Also set nodeName for compatibility
         message: e.message,
         details: e.details
       }));
     }
-    
+
     if (validationResult.warnings.length > 0) {
       response.warnings = validationResult.warnings.map(w => ({
         node: w.nodeName || 'workflow',
+        nodeName: w.nodeName, // Also set nodeName for compatibility
         message: w.message,
         details: w.details
       }));
@@ -828,7 +970,7 @@ export async function handleAutofixWorkflow(
     });
 
     // Check for expression format issues
-    const allFormatIssues: any[] = [];
+    const allFormatIssues: ExpressionFormatIssue[] = [];
     for (const node of workflow.nodes) {
       const formatContext = {
         nodeType: node.type,
@@ -1222,29 +1364,86 @@ export async function handleDeleteExecution(args: unknown, context?: InstanceCon
 // System Tools Handlers
 
 export async function handleHealthCheck(context?: InstanceContext): Promise<McpToolResponse> {
+  const startTime = Date.now();
+
   try {
     const client = ensureApiConfigured(context);
     const health = await client.healthCheck();
-    
+
     // Get MCP version from package.json
     const packageJson = require('../../package.json');
     const mcpVersion = packageJson.version;
     const supportedN8nVersion = packageJson.dependencies?.n8n?.replace(/[^0-9.]/g, '');
-    
-    return {
-      success: true,
-      data: {
-        status: health.status,
-        instanceId: health.instanceId,
-        n8nVersion: health.n8nVersion,
-        features: health.features,
-        apiUrl: getN8nApiConfig()?.baseUrl,
-        mcpVersion,
-        supportedN8nVersion,
-        versionNote: 'AI Agent: Please inform the user to verify their n8n instance version matches or is compatible with the supported version listed above. The n8n API currently does not expose version information, so manual verification is required.'
+
+    // Check npm for latest version (async, non-blocking)
+    const versionCheck = await checkNpmVersion();
+
+    // Get cache metrics for performance monitoring
+    const cacheMetricsData = getInstanceCacheMetrics();
+
+    // Calculate response time
+    const responseTime = Date.now() - startTime;
+
+    // Build response data
+    const responseData: HealthCheckResponseData = {
+      status: health.status,
+      instanceId: health.instanceId,
+      n8nVersion: health.n8nVersion,
+      features: health.features,
+      apiUrl: getN8nApiConfig()?.baseUrl,
+      mcpVersion,
+      supportedN8nVersion,
+      versionCheck: {
+        current: versionCheck.currentVersion,
+        latest: versionCheck.latestVersion,
+        upToDate: !versionCheck.isOutdated,
+        message: formatVersionMessage(versionCheck),
+        ...(versionCheck.updateCommand ? { updateCommand: versionCheck.updateCommand } : {})
+      },
+      performance: {
+        responseTimeMs: responseTime,
+        cacheHitRate: (cacheMetricsData.hits + cacheMetricsData.misses) > 0
+          ? ((cacheMetricsData.hits / (cacheMetricsData.hits + cacheMetricsData.misses)) * 100).toFixed(2) + '%'
+          : 'N/A',
+        cachedInstances: cacheMetricsData.size
       }
     };
+
+    // Add next steps guidance based on telemetry insights
+    responseData.nextSteps = [
+      '• Create workflow: n8n_create_workflow',
+      '• List workflows: n8n_list_workflows',
+      '• Search nodes: search_nodes',
+      '• Browse templates: search_templates'
+    ];
+
+    // Add update warning if outdated
+    if (versionCheck.isOutdated && versionCheck.latestVersion) {
+      responseData.updateWarning = `⚠️  n8n-mcp v${versionCheck.latestVersion} is available (you have v${versionCheck.currentVersion}). Update recommended.`;
+    }
+
+    // Track result in telemetry
+    telemetry.trackEvent('health_check_completed', {
+      success: true,
+      responseTimeMs: responseTime,
+      upToDate: !versionCheck.isOutdated,
+      apiConnected: true
+    });
+
+    return {
+      success: true,
+      data: responseData
+    };
   } catch (error) {
+    const responseTime = Date.now() - startTime;
+
+    // Track failure in telemetry
+    telemetry.trackEvent('health_check_failed', {
+      success: false,
+      responseTimeMs: responseTime,
+      errorType: error instanceof N8nApiError ? error.code : 'unknown'
+    });
+
     if (error instanceof N8nApiError) {
       return {
         success: false,
@@ -1252,11 +1451,17 @@ export async function handleHealthCheck(context?: InstanceContext): Promise<McpT
         code: error.code,
         details: {
           apiUrl: getN8nApiConfig()?.baseUrl,
-          hint: 'Check if n8n is running and API is enabled'
+          hint: 'Check if n8n is running and API is enabled',
+          troubleshooting: [
+            '1. Verify n8n instance is running',
+            '2. Check N8N_API_URL is correct',
+            '3. Verify N8N_API_KEY has proper permissions',
+            '4. Run n8n_diagnostic for detailed analysis'
+          ]
         }
       };
     }
-    
+
     return {
       success: false,
       error: error instanceof Error ? error.message : 'Unknown error occurred'
@@ -1322,23 +1527,208 @@ export async function handleListAvailableTools(context?: InstanceContext): Promi
   };
 }
 
+// Environment-aware debugging helpers
+
+/**
+ * Detect cloud platform from environment variables
+ * Returns platform name or null if not in cloud
+ */
+function detectCloudPlatform(): string | null {
+  if (process.env.RAILWAY_ENVIRONMENT) return 'railway';
+  if (process.env.RENDER) return 'render';
+  if (process.env.FLY_APP_NAME) return 'fly';
+  if (process.env.HEROKU_APP_NAME) return 'heroku';
+  if (process.env.AWS_EXECUTION_ENV) return 'aws';
+  if (process.env.KUBERNETES_SERVICE_HOST) return 'kubernetes';
+  if (process.env.GOOGLE_CLOUD_PROJECT) return 'gcp';
+  if (process.env.AZURE_FUNCTIONS_ENVIRONMENT) return 'azure';
+  return null;
+}
+
+/**
+ * Get mode-specific debugging suggestions
+ */
+function getModeSpecificDebug(mcpMode: string) {
+  if (mcpMode === 'http') {
+    const port = process.env.MCP_PORT || process.env.PORT || 3000;
+    return {
+      mode: 'HTTP Server',
+      port,
+      authTokenConfigured: !!(process.env.MCP_AUTH_TOKEN || process.env.AUTH_TOKEN),
+      corsEnabled: true,
+      serverUrl: `http://localhost:${port}`,
+      healthCheckUrl: `http://localhost:${port}/health`,
+      troubleshooting: [
+        `1. Test server health: curl http://localhost:${port}/health`,
+        '2. Check browser console for CORS errors',
+        '3. Verify MCP_AUTH_TOKEN or AUTH_TOKEN if authentication enabled',
+        `4. Ensure port ${port} is not in use: lsof -i :${port} (macOS/Linux) or netstat -ano | findstr :${port} (Windows)`,
+        '5. Check firewall settings for port access',
+        '6. Review server logs for connection errors'
+      ],
+      commonIssues: [
+        'CORS policy blocking browser requests',
+        'Port already in use by another application',
+        'Authentication token mismatch',
+        'Network firewall blocking connections'
+      ]
+    };
+  } else {
+    // stdio mode
+    const configLocation = process.platform === 'darwin'
+      ? '~/Library/Application Support/Claude/claude_desktop_config.json'
+      : process.platform === 'win32'
+      ? '%APPDATA%\\Claude\\claude_desktop_config.json'
+      : '~/.config/Claude/claude_desktop_config.json';
+
+    return {
+      mode: 'Standard I/O (Claude Desktop)',
+      configLocation,
+      troubleshooting: [
+        '1. Verify Claude Desktop config file exists and is valid JSON',
+        '2. Check MCP server entry: {"mcpServers": {"n8n": {"command": "npx", "args": ["-y", "n8n-mcp"]}}}',
+        '3. Restart Claude Desktop after config changes',
+        '4. Check Claude Desktop logs for startup errors',
+        '5. Test npx can run: npx -y n8n-mcp --version',
+        '6. Verify executable permissions if using local installation'
+      ],
+      commonIssues: [
+        'Invalid JSON in claude_desktop_config.json',
+        'Incorrect command or args in MCP server config',
+        'Claude Desktop not restarted after config changes',
+        'npx unable to download or run package',
+        'Missing execute permissions on local binary'
+      ]
+    };
+  }
+}
+
+/**
+ * Get Docker-specific debugging suggestions
+ */
+function getDockerDebug(isDocker: boolean) {
+  if (!isDocker) return null;
+
+  return {
+    containerDetected: true,
+    troubleshooting: [
+      '1. Verify volume mounts for data/nodes.db',
+      '2. Check network connectivity to n8n instance',
+      '3. Ensure ports are correctly mapped',
+      '4. Review container logs: docker logs <container-name>',
+      '5. Verify environment variables passed to container',
+      '6. Check IS_DOCKER=true is set correctly'
+    ],
+    commonIssues: [
+      'Volume mount not persisting database',
+      'Network isolation preventing n8n API access',
+      'Port mapping conflicts',
+      'Missing environment variables in container'
+    ]
+  };
+}
+
+/**
+ * Get cloud platform-specific suggestions
+ */
+function getCloudPlatformDebug(cloudPlatform: string | null) {
+  if (!cloudPlatform) return null;
+
+  const platformGuides: Record<string, CloudPlatformGuide> = {
+    railway: {
+      name: 'Railway',
+      troubleshooting: [
+        '1. Check Railway environment variables are set',
+        '2. Verify deployment logs in Railway dashboard',
+        '3. Ensure PORT matches Railway assigned port (automatic)',
+        '4. Check networking configuration for external access'
+      ]
+    },
+    render: {
+      name: 'Render',
+      troubleshooting: [
+        '1. Verify Render environment variables',
+        '2. Check Render logs for startup errors',
+        '3. Ensure health check endpoint is responding',
+        '4. Verify instance type has sufficient resources'
+      ]
+    },
+    fly: {
+      name: 'Fly.io',
+      troubleshooting: [
+        '1. Check Fly.io logs: flyctl logs',
+        '2. Verify fly.toml configuration',
+        '3. Ensure volumes are properly mounted',
+        '4. Check app status: flyctl status'
+      ]
+    },
+    heroku: {
+      name: 'Heroku',
+      troubleshooting: [
+        '1. Check Heroku logs: heroku logs --tail',
+        '2. Verify Procfile configuration',
+        '3. Ensure dynos are running: heroku ps',
+        '4. Check environment variables: heroku config'
+      ]
+    },
+    kubernetes: {
+      name: 'Kubernetes',
+      troubleshooting: [
+        '1. Check pod logs: kubectl logs <pod-name>',
+        '2. Verify service and ingress configuration',
+        '3. Check persistent volume claims',
+        '4. Verify resource limits and requests'
+      ]
+    },
+    aws: {
+      name: 'AWS',
+      troubleshooting: [
+        '1. Check CloudWatch logs',
+        '2. Verify IAM roles and permissions',
+        '3. Check security groups and networking',
+        '4. Verify environment variables in service config'
+      ]
+    }
+  };
+
+  return platformGuides[cloudPlatform] || {
+    name: cloudPlatform.toUpperCase(),
+    troubleshooting: [
+      '1. Check cloud platform logs',
+      '2. Verify environment variables are set',
+      '3. Check networking and port configuration',
+      '4. Review platform-specific documentation'
+    ]
+  };
+}
+
 // Handler: n8n_diagnostic
 export async function handleDiagnostic(request: any, context?: InstanceContext): Promise<McpToolResponse> {
+  const startTime = Date.now();
   const verbose = request.params?.arguments?.verbose || false;
-  
+
+  // Detect environment for targeted debugging
+  const mcpMode = process.env.MCP_MODE || 'stdio';
+  const isDocker = process.env.IS_DOCKER === 'true';
+  const cloudPlatform = detectCloudPlatform();
+
   // Check environment variables
   const envVars = {
     N8N_API_URL: process.env.N8N_API_URL || null,
     N8N_API_KEY: process.env.N8N_API_KEY ? '***configured***' : null,
     NODE_ENV: process.env.NODE_ENV || 'production',
-    MCP_MODE: process.env.MCP_MODE || 'stdio'
+    MCP_MODE: mcpMode,
+    isDocker,
+    cloudPlatform,
+    nodeVersion: process.version,
+    platform: process.platform
   };
-  
+
   // Check API configuration
   const apiConfig = getN8nApiConfig();
   const apiConfigured = apiConfig !== null;
   const apiClient = getN8nApiClient(context);
-  
+
   // Test API connectivity if configured
   let apiStatus = {
     configured: apiConfigured,
@@ -1346,7 +1736,7 @@ export async function handleDiagnostic(request: any, context?: InstanceContext):
     error: null as string | null,
     version: null as string | null
   };
-  
+
   if (apiClient) {
     try {
       const health = await apiClient.healthCheck();
@@ -1356,14 +1746,21 @@ export async function handleDiagnostic(request: any, context?: InstanceContext):
       apiStatus.error = error instanceof Error ? error.message : 'Unknown error';
     }
   }
-  
+
   // Check which tools are available
   const documentationTools = 22; // Base documentation tools
   const managementTools = apiConfigured ? 16 : 0;
   const totalTools = documentationTools + managementTools;
-  
+
+  // Check npm version
+  const versionCheck = await checkNpmVersion();
+
+  // Get performance metrics
+  const cacheMetricsData = getInstanceCacheMetrics();
+  const responseTime = Date.now() - startTime;
+
   // Build diagnostic report
-  const diagnostic: any = {
+  const diagnostic: DiagnosticResponseData = {
     timestamp: new Date().toISOString(),
     environment: envVars,
     apiConfiguration: {
@@ -1375,6 +1772,13 @@ export async function handleDiagnostic(request: any, context?: InstanceContext):
         maxRetries: apiConfig.maxRetries
       } : null
     },
+    versionInfo: {
+      current: versionCheck.currentVersion,
+      latest: versionCheck.latestVersion,
+      upToDate: !versionCheck.isOutdated,
+      message: formatVersionMessage(versionCheck),
+      ...(versionCheck.updateCommand ? { updateCommand: versionCheck.updateCommand } : {})
+    },
     toolsAvailability: {
       documentationTools: {
         count: documentationTools,
@@ -1384,43 +1788,175 @@ export async function handleDiagnostic(request: any, context?: InstanceContext):
       managementTools: {
         count: managementTools,
         enabled: apiConfigured,
-        description: apiConfigured ? 
-          'Management tools are ENABLED - create, update, execute workflows' : 
+        description: apiConfigured ?
+          'Management tools are ENABLED - create, update, execute workflows' :
           'Management tools are DISABLED - configure N8N_API_URL and N8N_API_KEY to enable'
       },
       totalAvailable: totalTools
     },
-    troubleshooting: {
-      steps: apiConfigured ? [
-        'API is configured and should work',
-        'If tools are not showing in Claude Desktop:',
-        '1. Restart Claude Desktop completely',
-        '2. Check if using latest Docker image',
-        '3. Verify environment variables are passed correctly',
-        '4. Try running n8n_health_check to test connectivity'
-      ] : [
-        'To enable management tools:',
-        '1. Set N8N_API_URL environment variable (e.g., https://your-n8n-instance.com)',
-        '2. Set N8N_API_KEY environment variable (get from n8n API settings)',
-        '3. Restart the MCP server',
-        '4. Management tools will automatically appear'
-      ],
-      documentation: 'For detailed setup instructions, see: https://github.com/czlonkowski/n8n-mcp?tab=readme-ov-file#n8n-management-tools-optional---requires-api-configuration'
-    }
+    performance: {
+      diagnosticResponseTimeMs: responseTime,
+      cacheHitRate: (cacheMetricsData.hits + cacheMetricsData.misses) > 0
+        ? ((cacheMetricsData.hits / (cacheMetricsData.hits + cacheMetricsData.misses)) * 100).toFixed(2) + '%'
+        : 'N/A',
+      cachedInstances: cacheMetricsData.size
+    },
+    modeSpecificDebug: getModeSpecificDebug(mcpMode)
   };
-  
+
+  // Enhanced guidance based on telemetry insights
+  if (apiConfigured && apiStatus.connected) {
+    // API is working - provide next steps
+    diagnostic.nextSteps = {
+      message: '✓ API connected! Here\'s what you can do:',
+      recommended: [
+        {
+          action: 'n8n_list_workflows',
+          description: 'See your existing workflows',
+          timing: 'Fast (6 seconds median)'
+        },
+        {
+          action: 'n8n_create_workflow',
+          description: 'Create a new workflow',
+          timing: 'Typically 6-14 minutes to build'
+        },
+        {
+          action: 'search_nodes',
+          description: 'Discover available nodes',
+          timing: 'Fast - explore 500+ nodes'
+        },
+        {
+          action: 'search_templates',
+          description: 'Browse pre-built workflows',
+          timing: 'Find examples quickly'
+        }
+      ],
+      tips: [
+        '82% of users start creating workflows after diagnostics - you\'re ready to go!',
+        'Most common first action: n8n_update_partial_workflow (managing existing workflows)',
+        'Use n8n_validate_workflow before deploying to catch issues early'
+      ]
+    };
+  } else if (apiConfigured && !apiStatus.connected) {
+    // API configured but not connecting - troubleshooting
+    diagnostic.troubleshooting = {
+      issue: '⚠️ API configured but connection failed',
+      error: apiStatus.error,
+      steps: [
+        '1. Verify n8n instance is running and accessible',
+        '2. Check N8N_API_URL is correct (currently: ' + apiConfig?.baseUrl + ')',
+        '3. Test URL in browser: ' + apiConfig?.baseUrl + '/healthz',
+        '4. Verify N8N_API_KEY has proper permissions',
+        '5. Check firewall/network settings if using remote n8n',
+        '6. Try running n8n_health_check again after fixes'
+      ],
+      commonIssues: [
+        'Wrong port number in N8N_API_URL',
+        'API key doesn\'t have sufficient permissions',
+        'n8n instance not running or crashed',
+        'Network firewall blocking connection'
+      ],
+      documentation: 'https://github.com/czlonkowski/n8n-mcp?tab=readme-ov-file#n8n-management-tools-optional---requires-api-configuration'
+    };
+  } else {
+    // API not configured - setup guidance
+    diagnostic.setupGuide = {
+      message: 'n8n API not configured. You can still use documentation tools!',
+      whatYouCanDoNow: {
+        documentation: [
+          {
+            tool: 'search_nodes',
+            description: 'Search 500+ n8n nodes',
+            example: 'search_nodes({query: "slack"})'
+          },
+          {
+            tool: 'get_node_essentials',
+            description: 'Get node configuration details',
+            example: 'get_node_essentials({nodeType: "nodes-base.httpRequest"})'
+          },
+          {
+            tool: 'search_templates',
+            description: 'Browse workflow templates',
+            example: 'search_templates({query: "chatbot"})'
+          },
+          {
+            tool: 'validate_workflow',
+            description: 'Validate workflow JSON',
+            example: 'validate_workflow({workflow: {...}})'
+          }
+        ],
+        note: '22 documentation tools available without API configuration'
+      },
+      whatYouCannotDo: [
+        '✗ Create/update workflows in n8n instance',
+        '✗ List your workflows',
+        '✗ Execute workflows',
+        '✗ View execution results'
+      ],
+      howToEnable: {
+        steps: [
+          '1. Get your n8n API key: [Your n8n instance]/settings/api',
+          '2. Set environment variables:',
+          '   N8N_API_URL=https://your-n8n-instance.com',
+          '   N8N_API_KEY=your_api_key_here',
+          '3. Restart the MCP server',
+          '4. Run n8n_diagnostic again to verify',
+          '5. All 38 tools will be available!'
+        ],
+        documentation: 'https://github.com/czlonkowski/n8n-mcp?tab=readme-ov-file#n8n-management-tools-optional---requires-api-configuration'
+      }
+    };
+  }
+
+  // Add version warning if outdated
+  if (versionCheck.isOutdated && versionCheck.latestVersion) {
+    diagnostic.updateWarning = {
+      message: `⚠️ Update available: v${versionCheck.currentVersion} → v${versionCheck.latestVersion}`,
+      command: versionCheck.updateCommand,
+      benefits: [
+        'Latest bug fixes and improvements',
+        'New features and tools',
+        'Better performance and reliability'
+      ]
+    };
+  }
+
+  // Add Docker-specific debugging if in container
+  const dockerDebug = getDockerDebug(isDocker);
+  if (dockerDebug) {
+    diagnostic.dockerDebug = dockerDebug;
+  }
+
+  // Add cloud platform-specific debugging if detected
+  const cloudDebug = getCloudPlatformDebug(cloudPlatform);
+  if (cloudDebug) {
+    diagnostic.cloudPlatformDebug = cloudDebug;
+  }
+
   // Add verbose debug info if requested
   if (verbose) {
-    diagnostic['debug'] = {
-      processEnv: Object.keys(process.env).filter(key => 
+    diagnostic.debug = {
+      processEnv: Object.keys(process.env).filter(key =>
         key.startsWith('N8N_') || key.startsWith('MCP_')
       ),
       nodeVersion: process.version,
       platform: process.platform,
-      workingDirectory: process.cwd()
+      workingDirectory: process.cwd(),
+      cacheMetrics: cacheMetricsData
     };
   }
-  
+
+  // Track diagnostic usage with result data
+  telemetry.trackEvent('diagnostic_completed', {
+    success: true,
+    apiConfigured,
+    apiConnected: apiStatus.connected,
+    toolsAvailable: totalTools,
+    responseTimeMs: responseTime,
+    upToDate: !versionCheck.isOutdated,
+    verbose
+  });
+
   return {
     success: true,
     data: diagnostic

src/mcp/handlers-workflow-diff.ts

@@ -27,10 +27,15 @@ const workflowDiffSchema = z.object({
     // 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(),

src/mcp/index.ts

@@ -3,6 +3,9 @@
 import { N8NDocumentationMCPServer } from './server';
 import { logger } from '../utils/logger';
 import { TelemetryConfigManager } from '../telemetry/config-manager';
+import { EarlyErrorLogger } from '../telemetry/early-error-logger';
+import { STARTUP_CHECKPOINTS, findFailedCheckpoint, StartupCheckpoint } from '../telemetry/startup-checkpoints';
+import { existsSync } from 'fs';
 
 // Add error details to stderr for Claude Desktop debugging
 process.on('uncaughtException', (error) => {
@@ -21,9 +24,50 @@ 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);
+  // Initialize early error logger for pre-handshake error capture (v2.18.3)
+  // Now using singleton pattern with defensive initialization
+  const startTime = Date.now();
+  const earlyLogger = EarlyErrorLogger.getInstance();
+  const checkpoints: StartupCheckpoint[] = [];
+
+  try {
+    // Checkpoint: Process started (fire-and-forget, no await)
+    earlyLogger.logCheckpoint(STARTUP_CHECKPOINTS.PROCESS_STARTED);
+    checkpoints.push(STARTUP_CHECKPOINTS.PROCESS_STARTED);
+
+    // 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];
@@ -58,6 +102,15 @@ Learn more: https://github.com/czlonkowski/n8n-mcp/blob/main/PRIVACY.md
 
   const mode = process.env.MCP_MODE || 'stdio';
 
+    // Checkpoint: Telemetry initializing (fire-and-forget, no await)
+    earlyLogger.logCheckpoint(STARTUP_CHECKPOINTS.TELEMETRY_INITIALIZING);
+    checkpoints.push(STARTUP_CHECKPOINTS.TELEMETRY_INITIALIZING);
+
+    // Telemetry is already initialized by TelemetryConfigManager in imports
+    // Mark as ready (fire-and-forget, no await)
+    earlyLogger.logCheckpoint(STARTUP_CHECKPOINTS.TELEMETRY_READY);
+    checkpoints.push(STARTUP_CHECKPOINTS.TELEMETRY_READY);
+
   try {
     // Only show debug messages in HTTP mode to avoid corrupting stdio communication
     if (mode === 'http') {
@@ -65,6 +118,10 @@ Learn more: https://github.com/czlonkowski/n8n-mcp/blob/main/PRIVACY.md
       console.error('Current directory:', process.cwd());
       console.error('Node version:', process.version);
     }
+
+    // Checkpoint: MCP handshake starting (fire-and-forget, no await)
+    earlyLogger.logCheckpoint(STARTUP_CHECKPOINTS.MCP_HANDSHAKE_STARTING);
+    checkpoints.push(STARTUP_CHECKPOINTS.MCP_HANDSHAKE_STARTING);
     
     if (mode === 'http') {
       // Check if we should use the fixed implementation
@@ -90,15 +147,95 @@ Learn more: https://github.com/czlonkowski/n8n-mcp/blob/main/PRIVACY.md
       }
     } else {
       // Stdio mode - for local Claude Desktop
-      const server = new N8NDocumentationMCPServer();
+      const server = new N8NDocumentationMCPServer(undefined, earlyLogger);
+
+      // 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();
     }
+
+    // Checkpoint: MCP handshake complete (fire-and-forget, no await)
+    earlyLogger.logCheckpoint(STARTUP_CHECKPOINTS.MCP_HANDSHAKE_COMPLETE);
+    checkpoints.push(STARTUP_CHECKPOINTS.MCP_HANDSHAKE_COMPLETE);
+
+    // Checkpoint: Server ready (fire-and-forget, no await)
+    earlyLogger.logCheckpoint(STARTUP_CHECKPOINTS.SERVER_READY);
+    checkpoints.push(STARTUP_CHECKPOINTS.SERVER_READY);
+
+    // Log successful startup (fire-and-forget, no await)
+    const startupDuration = Date.now() - startTime;
+    earlyLogger.logStartupSuccess(checkpoints, startupDuration);
+
+    logger.info(`Server startup completed in ${startupDuration}ms (${checkpoints.length} checkpoints passed)`);
+
   } catch (error) {
+    // Log startup error with checkpoint context (fire-and-forget, no await)
+    const failedCheckpoint = findFailedCheckpoint(checkpoints);
+    earlyLogger.logStartupError(failedCheckpoint, error);
+
     // In stdio mode, we cannot output to console at all
     if (mode !== 'stdio') {
       console.error('Failed to start MCP server:', error);
       logger.error('Failed to start MCP server', error);
-      
+
       // Provide helpful error messages
       if (error instanceof Error && error.message.includes('nodes.db not found')) {
         console.error('\nTo fix this issue:');
@@ -112,7 +249,12 @@ Learn more: https://github.com/czlonkowski/n8n-mcp/blob/main/PRIVACY.md
         console.error('3. If that doesn\'t work, try: rm -rf node_modules && npm install');
       }
     }
-    
+
+    process.exit(1);
+  }
+  } catch (outerError) {
+    // Outer error catch for early initialization failures
+    logger.error('Critical startup error:', outerError);
     process.exit(1);
   }
 }

src/mcp/server.ts

@@ -37,6 +37,8 @@ import {
 } from '../utils/protocol-version';
 import { InstanceContext } from '../types/instance-context';
 import { telemetry } from '../telemetry';
+import { EarlyErrorLogger } from '../telemetry/early-error-logger';
+import { STARTUP_CHECKPOINTS } from '../telemetry/startup-checkpoints';
 
 interface NodeRow {
   node_type: string;
@@ -67,9 +69,11 @@ export class N8NDocumentationMCPServer {
   private instanceContext?: InstanceContext;
   private previousTool: string | null = null;
   private previousToolTimestamp: number = Date.now();
+  private earlyLogger: EarlyErrorLogger | null = null;
 
-  constructor(instanceContext?: InstanceContext) {
+  constructor(instanceContext?: InstanceContext, earlyLogger?: EarlyErrorLogger) {
     this.instanceContext = instanceContext;
+    this.earlyLogger = earlyLogger || null;
     // Check for test environment first
     const envDbPath = process.env.NODE_DB_PATH;
     let dbPath: string | null = null;
@@ -100,22 +104,49 @@ export class N8NDocumentationMCPServer {
     }
     
     // Initialize database asynchronously
-    this.initialized = this.initializeDatabase(dbPath);
-    
+    this.initialized = this.initializeDatabase(dbPath).then(() => {
+      // After database is ready, check n8n API configuration (v2.18.3)
+      if (this.earlyLogger) {
+        this.earlyLogger.logCheckpoint(STARTUP_CHECKPOINTS.N8N_API_CHECKING);
+      }
+
+      // Log n8n API configuration status at startup
+      const apiConfigured = isN8nApiConfigured();
+      const totalTools = apiConfigured ?
+        n8nDocumentationToolsFinal.length + n8nManagementTools.length :
+        n8nDocumentationToolsFinal.length;
+
+      logger.info(`MCP server initialized with ${totalTools} tools (n8n API: ${apiConfigured ? 'configured' : 'not configured'})`);
+
+      if (this.earlyLogger) {
+        this.earlyLogger.logCheckpoint(STARTUP_CHECKPOINTS.N8N_API_READY);
+      }
+    });
+
     logger.info('Initializing n8n Documentation MCP server');
     
-    // Log n8n API configuration status at startup
-    const apiConfigured = isN8nApiConfigured();
-    const totalTools = apiConfigured ? 
-      n8nDocumentationToolsFinal.length + n8nManagementTools.length : 
-      n8nDocumentationToolsFinal.length;
-    
-    logger.info(`MCP server initialized with ${totalTools} tools (n8n API: ${apiConfigured ? 'configured' : 'not configured'})`);
-    
     this.server = new Server(
       {
         name: 'n8n-documentation-mcp',
-        version: '1.0.0',
+        version: PROJECT_VERSION,
+        icons: [
+          {
+            src: "https://www.n8n-mcp.com/logo.png",
+            mimeType: "image/png",
+            sizes: ["192x192"]
+          },
+          {
+            src: "https://www.n8n-mcp.com/logo-128.png",
+            mimeType: "image/png",
+            sizes: ["128x128"]
+          },
+          {
+            src: "https://www.n8n-mcp.com/logo-48.png",
+            mimeType: "image/png",
+            sizes: ["48x48"]
+          }
+        ],
+        websiteUrl: "https://n8n-mcp.com"
       },
       {
         capabilities: {
@@ -129,20 +160,38 @@ export class N8NDocumentationMCPServer {
   
   private async initializeDatabase(dbPath: string): Promise<void> {
     try {
+      // Checkpoint: Database connecting (v2.18.3)
+      if (this.earlyLogger) {
+        this.earlyLogger.logCheckpoint(STARTUP_CHECKPOINTS.DATABASE_CONNECTING);
+      }
+
+      logger.debug('Database initialization starting...', { dbPath });
+
       this.db = await createDatabaseAdapter(dbPath);
-      
+      logger.debug('Database adapter created');
+
       // If using in-memory database for tests, initialize schema
       if (dbPath === ':memory:') {
         await this.initializeInMemorySchema();
+        logger.debug('In-memory schema initialized');
       }
-      
+
       this.repository = new NodeRepository(this.db);
+      logger.debug('Node repository initialized');
+
       this.templateService = new TemplateService(this.db);
+      logger.debug('Template service initialized');
 
       // Initialize similarity services for enhanced validation
       EnhancedConfigValidator.initializeSimilarityServices(this.repository);
+      logger.debug('Similarity services initialized');
 
-      logger.info(`Initialized database from: ${dbPath}`);
+      // Checkpoint: Database connected (v2.18.3)
+      if (this.earlyLogger) {
+        this.earlyLogger.logCheckpoint(STARTUP_CHECKPOINTS.DATABASE_CONNECTED);
+      }
+
+      logger.info(`Database initialized successfully from: ${dbPath}`);
     } catch (error) {
       logger.error('Failed to initialize database:', error);
       throw new Error(`Failed to open database: ${error instanceof Error ? error.message : 'Unknown error'}`);
@@ -151,25 +200,122 @@ export class N8NDocumentationMCPServer {
   
   private async initializeInMemorySchema(): Promise<void> {
     if (!this.db) return;
-    
+
     // Read and execute schema
     const schemaPath = path.join(__dirname, '../../src/database/schema.sql');
     const schema = await fs.readFile(schemaPath, 'utf-8');
-    
-    // Execute schema statements
-    const statements = schema.split(';').filter(stmt => stmt.trim());
+
+    // Parse SQL statements properly (handles BEGIN...END blocks in triggers)
+    const statements = this.parseSQLStatements(schema);
+
     for (const statement of statements) {
       if (statement.trim()) {
-        this.db.exec(statement);
+        try {
+          this.db.exec(statement);
+        } catch (error) {
+          logger.error(`Failed to execute SQL statement: ${statement.substring(0, 100)}...`, error);
+          throw error;
+        }
       }
     }
   }
+
+  /**
+   * Parse SQL statements from schema file, properly handling multi-line statements
+   * including triggers with BEGIN...END blocks
+   */
+  private parseSQLStatements(sql: string): string[] {
+    const statements: string[] = [];
+    let current = '';
+    let inBlock = false;
+
+    const lines = sql.split('\n');
+
+    for (const line of lines) {
+      const trimmed = line.trim().toUpperCase();
+
+      // Skip comments and empty lines
+      if (trimmed.startsWith('--') || trimmed === '') {
+        continue;
+      }
+
+      // Track BEGIN...END blocks (triggers, procedures)
+      if (trimmed.includes('BEGIN')) {
+        inBlock = true;
+      }
+
+      current += line + '\n';
+
+      // End of block (trigger/procedure)
+      if (inBlock && trimmed === 'END;') {
+        statements.push(current.trim());
+        current = '';
+        inBlock = false;
+        continue;
+      }
+
+      // Regular statement end (not in block)
+      if (!inBlock && trimmed.endsWith(';')) {
+        statements.push(current.trim());
+        current = '';
+      }
+    }
+
+    // Add any remaining content
+    if (current.trim()) {
+      statements.push(current.trim());
+    }
+
+    return statements.filter(s => s.length > 0);
+  }
   
   private async ensureInitialized(): Promise<void> {
     await this.initialized;
     if (!this.db || !this.repository) {
       throw new Error('Database not initialized');
     }
+
+    // Validate database health on first access
+    if (!this.dbHealthChecked) {
+      await this.validateDatabaseHealth();
+      this.dbHealthChecked = true;
+    }
+  }
+
+  private dbHealthChecked: boolean = false;
+
+  private async validateDatabaseHealth(): Promise<void> {
+    if (!this.db) return;
+
+    try {
+      // Check if nodes table has data
+      const nodeCount = this.db.prepare('SELECT COUNT(*) as count FROM nodes').get() as { count: number };
+
+      if (nodeCount.count === 0) {
+        logger.error('CRITICAL: Database is empty - no nodes found! Please run: npm run rebuild');
+        throw new Error('Database is empty. Run "npm run rebuild" to populate node data.');
+      }
+
+      // Check if FTS5 table exists
+      const ftsExists = this.db.prepare(`
+        SELECT name FROM sqlite_master
+        WHERE type='table' AND name='nodes_fts'
+      `).get();
+
+      if (!ftsExists) {
+        logger.warn('FTS5 table missing - search performance will be degraded. Please run: npm run rebuild');
+      } else {
+        const ftsCount = this.db.prepare('SELECT COUNT(*) as count FROM nodes_fts').get() as { count: number };
+        if (ftsCount.count === 0) {
+          logger.warn('FTS5 index is empty - search will not work properly. Please run: npm run rebuild');
+        }
+      }
+
+      logger.info(`Database health check passed: ${nodeCount.count} nodes loaded`);
+    } catch (error) {
+      logger.error('Database health check failed:', error);
+      throw error;
+    }
   }
 
   private setupHandlers(): void {
@@ -599,16 +745,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.`);
+    }
   }
 
   /**
@@ -1027,6 +1180,15 @@ export class N8NDocumentationMCPServer {
     };
   }
 
+  /**
+   * Primary search method used by ALL MCP search tools.
+   *
+   * This method automatically detects and uses FTS5 full-text search when available
+   * (lines 1189-1203), falling back to LIKE queries only if FTS5 table doesn't exist.
+   *
+   * NOTE: This is separate from NodeRepository.searchNodes() which is legacy LIKE-based.
+   * All MCP tool invocations route through this method to leverage FTS5 performance.
+   */
   private async searchNodes(
     query: string,
     limit: number = 20,
@@ -1038,7 +1200,7 @@ export class N8NDocumentationMCPServer {
   ): Promise<any> {
     await this.ensureInitialized();
     if (!this.db) throw new Error('Database not initialized');
-    
+
     // Normalize the query if it looks like a full node type
     let normalizedQuery = query;
     
@@ -1907,7 +2069,8 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
     // Add examples from templates if requested
     if (includeExamples) {
       try {
-        const fullNodeType = getWorkflowNodeType(node.package ?? 'n8n-nodes-base', node.nodeType);
+        // Use the already-computed workflowNodeType from result (line 1888)
+        // This ensures consistency with search_nodes behavior (line 1203)
         const examples = this.db!.prepare(`
           SELECT
             parameters_json,
@@ -1921,7 +2084,7 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
           WHERE node_type = ?
           ORDER BY rank
           LIMIT 3
-        `).all(fullNodeType) as any[];
+        `).all(result.workflowNodeType) as any[];
 
         if (examples.length > 0) {
           (result as any).examples = examples.map((ex: any) => ({

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

@@ -4,26 +4,30 @@ export const listAiToolsDoc: ToolDocumentation = {
   name: 'list_ai_tools',
   category: 'discovery',
   essentials: {
-    description: 'Returns 263 nodes with built-in AI features. CRITICAL: Any of the 525 n8n nodes can be used as an AI tool by connecting it to an AI Agent node\'s tool port. This list only shows nodes with AI-specific features, not all usable nodes.',
+    description: 'DEPRECATED: Basic list of 263 AI nodes. For comprehensive AI Agent guidance, use tools_documentation({topic: "ai_agents_guide"}). That guide covers architecture, connections, tools, validation, and best practices. Use search_nodes({query: "AI", includeExamples: true}) for AI nodes with working examples.',
     keyParameters: [],
-    example: 'list_ai_tools()',
+    example: 'tools_documentation({topic: "ai_agents_guide"}) // Recommended alternative',
     performance: 'Instant (cached)',
     tips: [
-      'ANY node can be an AI tool - not limited to this list',
-      'Connect Slack, Database, HTTP Request, etc. to AI Agent tool port',
+      'NEW: Use ai_agents_guide for comprehensive AI workflow documentation',
+      'Use search_nodes({includeExamples: true}) for AI nodes with real-world examples',
+      'ANY node can be an AI tool - not limited to AI-specific nodes',
       'Use get_node_as_tool_info for guidance on any node'
     ]
   },
   full: {
-    description: 'Lists 263 nodes that have built-in AI capabilities or are optimized for AI workflows. IMPORTANT: This is NOT a complete list of nodes usable as AI tools. Any of the 525 n8n nodes can be connected to an AI Agent node\'s tool port to function as an AI tool. This includes Slack, Google Sheets, databases, HTTP requests, and more.',
+    description: '**DEPRECATED in favor of ai_agents_guide**. Lists 263 nodes with built-in AI capabilities. For comprehensive documentation on building AI Agent workflows, use tools_documentation({topic: "ai_agents_guide"}) which covers architecture, the 8 AI connection types, validation, and best practices with real examples. IMPORTANT: This basic list is NOT a complete guide - use the full AI Agents guide instead.',
     parameters: {},
-    returns: 'Array of 263 AI-optimized nodes including: OpenAI (GPT-3/4), Anthropic (Claude), Google AI (Gemini/PaLM), Cohere, HuggingFace, Pinecone, Qdrant, Supabase Vector Store, LangChain nodes, embeddings processors, vector stores, chat models, and AI-specific utilities. Each entry includes nodeType, displayName, and AI-specific capabilities.',
+    returns: 'Array of 263 AI-optimized nodes. RECOMMENDED: Use ai_agents_guide for comprehensive guidance, or search_nodes({query: "AI", includeExamples: true}) for AI nodes with working configuration examples.',
     examples: [
-      'list_ai_tools() - Returns all 263 AI-optimized nodes',
-      '// To use ANY node as AI tool:',
-      '// 1. Add any node (e.g., Slack, MySQL, HTTP Request)',  
-      '// 2. Connect it to AI Agent node\'s "Tool" input port',
-      '// 3. The AI agent can now use that node\'s functionality'
+      '// RECOMMENDED: Use the comprehensive AI Agents guide',
+      'tools_documentation({topic: "ai_agents_guide"})',
+      '',
+      '// Or search for AI nodes with real-world examples',
+      'search_nodes({query: "AI Agent", includeExamples: true})',
+      '',
+      '// Basic list (deprecated)',
+      'list_ai_tools() - Returns 263 AI-optimized nodes'
     ],
     useCases: [
       'Discover AI model integrations (OpenAI, Anthropic, Google AI)',

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

@@ -0,0 +1,738 @@
+import { ToolDocumentation } from '../types';
+
+export const aiAgentsGuide: ToolDocumentation = {
+  name: 'ai_agents_guide',
+  category: 'guides',
+  essentials: {
+    description: 'Comprehensive guide to building AI Agent workflows in n8n. Covers architecture, connections, tools, validation, and best practices for production AI systems.',
+    keyParameters: [],
+    example: 'Use tools_documentation({topic: "ai_agents_guide"}) to access this guide',
+    performance: 'N/A - Documentation only',
+    tips: [
+      'Start with Chat Trigger → AI Agent → Language Model pattern',
+      'Always connect language model BEFORE enabling AI Agent',
+      'Use proper toolDescription for all AI tools (15+ characters)',
+      'Validate workflows with n8n_validate_workflow before deployment',
+      'Use includeExamples=true when searching for AI nodes',
+      'Check FINAL_AI_VALIDATION_SPEC.md for detailed requirements'
+    ]
+  },
+  full: {
+    description: `# Complete Guide to AI Agents in n8n
+
+This comprehensive guide covers everything you need to build production-ready AI Agent workflows in n8n.
+
+## Table of Contents
+1. [AI Agent Architecture](#architecture)
+2. [Essential Connection Types](#connections)
+3. [Building Your First AI Agent](#first-agent)
+4. [AI Tools Deep Dive](#tools)
+5. [Advanced Patterns](#advanced)
+6. [Validation & Best Practices](#validation)
+7. [Troubleshooting](#troubleshooting)
+
+---
+
+## 1. AI Agent Architecture {#architecture}
+
+### Core Components
+
+An n8n AI Agent workflow typically consists of:
+
+1. **Chat Trigger**: Entry point for user interactions
+   - Webhook-based or manual trigger
+   - Supports streaming responses (responseMode)
+   - Passes user message to AI Agent
+
+2. **AI Agent**: The orchestrator
+   - Manages conversation flow
+   - Decides when to use tools
+   - Iterates until task is complete
+   - Supports fallback models (v2.1+)
+
+3. **Language Model**: The AI brain
+   - OpenAI GPT-4, Claude, Gemini, etc.
+   - Connected via ai_languageModel port
+   - Can have primary + fallback for reliability
+
+4. **Tools**: AI Agent's capabilities
+   - HTTP Request, Code, Vector Store, etc.
+   - Connected via ai_tool port
+   - Each tool needs clear toolDescription
+
+5. **Optional Components**:
+   - Memory (conversation history)
+   - Output Parser (structured responses)
+   - Vector Store (knowledge retrieval)
+
+### Connection Flow
+
+**CRITICAL**: AI connections flow TO the consumer (reversed from standard n8n):
+
+\`\`\`
+Standard n8n:  [Source] --main--> [Target]
+AI pattern:    [Language Model] --ai_languageModel--> [AI Agent]
+               [HTTP Tool] --ai_tool--> [AI Agent]
+\`\`\`
+
+This is why you use \`sourceOutput: "ai_languageModel"\` when connecting components.
+
+---
+
+## 2. Essential Connection Types {#connections}
+
+### The 8 AI Connection Types
+
+1. **ai_languageModel**
+   - FROM: OpenAI Chat Model, Anthropic, Google Gemini, etc.
+   - TO: AI Agent, Basic LLM Chain
+   - REQUIRED: Every AI Agent needs 1-2 language models
+   - Example: \`{type: "addConnection", source: "OpenAI", target: "AI Agent", sourceOutput: "ai_languageModel"}\`
+
+2. **ai_tool**
+   - FROM: Any tool node (HTTP Request Tool, Code Tool, etc.)
+   - TO: AI Agent
+   - REQUIRED: At least 1 tool recommended
+   - Example: \`{type: "addConnection", source: "HTTP Request Tool", target: "AI Agent", sourceOutput: "ai_tool"}\`
+
+3. **ai_memory**
+   - FROM: Window Buffer Memory, Conversation Summary, etc.
+   - TO: AI Agent
+   - OPTIONAL: 0-1 memory system
+   - Enables conversation history tracking
+
+4. **ai_outputParser**
+   - FROM: Structured Output Parser, JSON Parser, etc.
+   - TO: AI Agent
+   - OPTIONAL: For structured responses
+   - Must set hasOutputParser=true on AI Agent
+
+5. **ai_embedding**
+   - FROM: Embeddings OpenAI, Embeddings Google, etc.
+   - TO: Vector Store (Pinecone, In-Memory, etc.)
+   - REQUIRED: For vector-based retrieval
+
+6. **ai_vectorStore**
+   - FROM: Vector Store node
+   - TO: Vector Store Tool
+   - REQUIRED: For retrieval-augmented generation (RAG)
+
+7. **ai_document**
+   - FROM: Document Loader, Default Data Loader
+   - TO: Vector Store
+   - REQUIRED: Provides data for vector storage
+
+8. **ai_textSplitter**
+   - FROM: Text Splitter nodes
+   - TO: Document processing chains
+   - OPTIONAL: Chunk large documents
+
+### Connection Examples
+
+\`\`\`typescript
+// Basic AI Agent setup
+n8n_update_partial_workflow({
+  id: "workflow_id",
+  operations: [
+    // Connect language model (REQUIRED)
+    {
+      type: "addConnection",
+      source: "OpenAI Chat Model",
+      target: "AI Agent",
+      sourceOutput: "ai_languageModel"
+    },
+    // Connect tools
+    {
+      type: "addConnection",
+      source: "HTTP Request Tool",
+      target: "AI Agent",
+      sourceOutput: "ai_tool"
+    },
+    {
+      type: "addConnection",
+      source: "Code Tool",
+      target: "AI Agent",
+      sourceOutput: "ai_tool"
+    },
+    // Add memory (optional)
+    {
+      type: "addConnection",
+      source: "Window Buffer Memory",
+      target: "AI Agent",
+      sourceOutput: "ai_memory"
+    }
+  ]
+})
+\`\`\`
+
+---
+
+## 3. Building Your First AI Agent {#first-agent}
+
+### Step-by-Step Tutorial
+
+#### Step 1: Create Chat Trigger
+
+Use \`n8n_create_workflow\` or manually create a workflow with:
+
+\`\`\`typescript
+{
+  name: "My First AI Agent",
+  nodes: [
+    {
+      id: "chat_trigger",
+      name: "Chat Trigger",
+      type: "@n8n/n8n-nodes-langchain.chatTrigger",
+      position: [100, 100],
+      parameters: {
+        options: {
+          responseMode: "lastNode"  // or "streaming" for real-time
+        }
+      }
+    }
+  ],
+  connections: {}
+}
+\`\`\`
+
+#### Step 2: Add Language Model
+
+\`\`\`typescript
+n8n_update_partial_workflow({
+  id: "workflow_id",
+  operations: [
+    {
+      type: "addNode",
+      node: {
+        name: "OpenAI Chat Model",
+        type: "@n8n/n8n-nodes-langchain.lmChatOpenAi",
+        position: [300, 50],
+        parameters: {
+          model: "gpt-4",
+          temperature: 0.7
+        }
+      }
+    }
+  ]
+})
+\`\`\`
+
+#### Step 3: Add AI Agent
+
+\`\`\`typescript
+n8n_update_partial_workflow({
+  id: "workflow_id",
+  operations: [
+    {
+      type: "addNode",
+      node: {
+        name: "AI Agent",
+        type: "@n8n/n8n-nodes-langchain.agent",
+        position: [300, 150],
+        parameters: {
+          promptType: "auto",
+          systemMessage: "You are a helpful assistant. Be concise and accurate."
+        }
+      }
+    }
+  ]
+})
+\`\`\`
+
+#### Step 4: Connect Components
+
+\`\`\`typescript
+n8n_update_partial_workflow({
+  id: "workflow_id",
+  operations: [
+    // Chat Trigger → AI Agent (main connection)
+    {
+      type: "addConnection",
+      source: "Chat Trigger",
+      target: "AI Agent"
+    },
+    // Language Model → AI Agent (AI connection)
+    {
+      type: "addConnection",
+      source: "OpenAI Chat Model",
+      target: "AI Agent",
+      sourceOutput: "ai_languageModel"
+    }
+  ]
+})
+\`\`\`
+
+#### Step 5: Validate
+
+\`\`\`typescript
+n8n_validate_workflow({id: "workflow_id"})
+\`\`\`
+
+---
+
+## 4. AI Tools Deep Dive {#tools}
+
+### Tool Types and When to Use Them
+
+#### 1. HTTP Request Tool
+**Use when**: AI needs to call external APIs
+
+**Critical Requirements**:
+- \`toolDescription\`: Clear, 15+ character description
+- \`url\`: API endpoint (can include placeholders)
+- \`placeholderDefinitions\`: Define all {placeholders}
+- Proper authentication if needed
+
+**Example**:
+\`\`\`typescript
+{
+  type: "addNode",
+  node: {
+    name: "GitHub Issues Tool",
+    type: "@n8n/n8n-nodes-langchain.toolHttpRequest",
+    position: [500, 100],
+    parameters: {
+      method: "POST",
+      url: "https://api.github.com/repos/{owner}/{repo}/issues",
+      toolDescription: "Create GitHub issues. Requires owner (username), repo (repository name), title, and body.",
+      placeholderDefinitions: {
+        values: [
+          {name: "owner", description: "Repository owner username"},
+          {name: "repo", description: "Repository name"},
+          {name: "title", description: "Issue title"},
+          {name: "body", description: "Issue description"}
+        ]
+      },
+      sendBody: true,
+      jsonBody: "={{ { title: $json.title, body: $json.body } }}"
+    }
+  }
+}
+\`\`\`
+
+#### 2. Code Tool
+**Use when**: AI needs to run custom logic
+
+**Critical Requirements**:
+- \`name\`: Function name (alphanumeric + underscore)
+- \`description\`: 10+ character explanation
+- \`code\`: JavaScript or Python code
+- \`inputSchema\`: Define expected inputs (recommended)
+
+**Example**:
+\`\`\`typescript
+{
+  type: "addNode",
+  node: {
+    name: "Calculate Shipping",
+    type: "@n8n/n8n-nodes-langchain.toolCode",
+    position: [500, 200],
+    parameters: {
+      name: "calculate_shipping",
+      description: "Calculate shipping cost based on weight (kg) and distance (km)",
+      language: "javaScript",
+      code: "const cost = 5 + ($input.weight * 2) + ($input.distance * 0.1); return { cost };",
+      specifyInputSchema: true,
+      inputSchema: "{ \\"type\\": \\"object\\", \\"properties\\": { \\"weight\\": { \\"type\\": \\"number\\" }, \\"distance\\": { \\"type\\": \\"number\\" } } }"
+    }
+  }
+}
+\`\`\`
+
+#### 3. Vector Store Tool
+**Use when**: AI needs to search knowledge base
+
+**Setup**: Requires Vector Store + Embeddings + Documents
+
+**Example**:
+\`\`\`typescript
+// Step 1: Create Vector Store with embeddings and documents
+n8n_update_partial_workflow({
+  operations: [
+    {type: "addConnection", source: "Embeddings OpenAI", target: "Pinecone", sourceOutput: "ai_embedding"},
+    {type: "addConnection", source: "Document Loader", target: "Pinecone", sourceOutput: "ai_document"}
+  ]
+})
+
+// Step 2: Connect Vector Store to Vector Store Tool
+n8n_update_partial_workflow({
+  operations: [
+    {type: "addConnection", source: "Pinecone", target: "Vector Store Tool", sourceOutput: "ai_vectorStore"}
+  ]
+})
+
+// Step 3: Connect tool to AI Agent
+n8n_update_partial_workflow({
+  operations: [
+    {type: "addConnection", source: "Vector Store Tool", target: "AI Agent", sourceOutput: "ai_tool"}
+  ]
+})
+\`\`\`
+
+#### 4. AI Agent Tool (Sub-Agents)
+**Use when**: Need specialized expertise
+
+**Example**: Research specialist sub-agent
+\`\`\`typescript
+{
+  type: "addNode",
+  node: {
+    name: "Research Specialist",
+    type: "@n8n/n8n-nodes-langchain.agentTool",
+    position: [500, 300],
+    parameters: {
+      name: "research_specialist",
+      description: "Expert researcher that searches multiple sources and synthesizes information. Use for detailed research tasks.",
+      systemMessage: "You are a research specialist. Search thoroughly, cite sources, and provide comprehensive analysis."
+    }
+  }
+}
+\`\`\`
+
+#### 5. MCP Client Tool
+**Use when**: Need to use Model Context Protocol servers
+
+**Example**: Filesystem access
+\`\`\`typescript
+{
+  type: "addNode",
+  node: {
+    name: "Filesystem Tool",
+    type: "@n8n/n8n-nodes-langchain.mcpClientTool",
+    position: [500, 400],
+    parameters: {
+      description: "Access file system to read files, list directories, and search content",
+      mcpServer: {
+        transport: "stdio",
+        command: "npx",
+        args: ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"]
+      },
+      tool: "read_file"
+    }
+  }
+}
+\`\`\`
+
+---
+
+## 5. Advanced Patterns {#advanced}
+
+### Pattern 1: Streaming Responses
+
+For real-time user experience:
+
+\`\`\`typescript
+// Set Chat Trigger to streaming mode
+{
+  parameters: {
+    options: {
+      responseMode: "streaming"
+    }
+  }
+}
+
+// CRITICAL: AI Agent must NOT have main output connections in streaming mode
+// Responses stream back through Chat Trigger automatically
+\`\`\`
+
+**Validation will fail if**:
+- Chat Trigger has streaming but target is not AI Agent
+- AI Agent in streaming mode has main output connections
+
+### Pattern 2: Fallback Language Models
+
+For production reliability (requires AI Agent v2.1+):
+
+\`\`\`typescript
+n8n_update_partial_workflow({
+  operations: [
+    // Primary model
+    {
+      type: "addConnection",
+      source: "OpenAI GPT-4",
+      target: "AI Agent",
+      sourceOutput: "ai_languageModel",
+      targetIndex: 0
+    },
+    // Fallback model
+    {
+      type: "addConnection",
+      source: "Anthropic Claude",
+      target: "AI Agent",
+      sourceOutput: "ai_languageModel",
+      targetIndex: 1
+    }
+  ]
+})
+
+// Enable fallback on AI Agent
+{
+  type: "updateNode",
+  nodeName: "AI Agent",
+  updates: {
+    "parameters.needsFallback": true
+  }
+}
+\`\`\`
+
+### Pattern 3: RAG (Retrieval-Augmented Generation)
+
+Complete knowledge base setup:
+
+\`\`\`typescript
+// 1. Load documents
+{type: "addConnection", source: "PDF Loader", target: "Text Splitter", sourceOutput: "ai_document"}
+
+// 2. Split and embed
+{type: "addConnection", source: "Text Splitter", target: "Vector Store"}
+{type: "addConnection", source: "Embeddings", target: "Vector Store", sourceOutput: "ai_embedding"}
+
+// 3. Create search tool
+{type: "addConnection", source: "Vector Store", target: "Vector Store Tool", sourceOutput: "ai_vectorStore"}
+
+// 4. Give tool to agent
+{type: "addConnection", source: "Vector Store Tool", target: "AI Agent", sourceOutput: "ai_tool"}
+\`\`\`
+
+### Pattern 4: Multi-Agent Systems
+
+Specialized sub-agents for complex tasks:
+
+\`\`\`typescript
+// Create sub-agents with specific expertise
+[
+  {name: "research_agent", description: "Deep research specialist"},
+  {name: "data_analyst", description: "Data analysis expert"},
+  {name: "writer_agent", description: "Content writing specialist"}
+].forEach(agent => {
+  // Add as AI Agent Tool to main coordinator agent
+  {
+    type: "addConnection",
+    source: agent.name,
+    target: "Coordinator Agent",
+    sourceOutput: "ai_tool"
+  }
+})
+\`\`\`
+
+---
+
+## 6. Validation & Best Practices {#validation}
+
+### Always Validate Before Deployment
+
+\`\`\`typescript
+const result = n8n_validate_workflow({id: "workflow_id"})
+
+if (!result.valid) {
+  console.log("Errors:", result.errors)
+  console.log("Warnings:", result.warnings)
+  console.log("Suggestions:", result.suggestions)
+}
+\`\`\`
+
+### Common Validation Errors
+
+1. **MISSING_LANGUAGE_MODEL**
+   - Problem: AI Agent has no ai_languageModel connection
+   - Fix: Connect a language model before creating AI Agent
+
+2. **MISSING_TOOL_DESCRIPTION**
+   - Problem: HTTP Request Tool has no toolDescription
+   - Fix: Add clear description (15+ characters)
+
+3. **STREAMING_WITH_MAIN_OUTPUT**
+   - Problem: AI Agent in streaming mode has outgoing main connections
+   - Fix: Remove main connections when using streaming
+
+4. **FALLBACK_MISSING_SECOND_MODEL**
+   - Problem: needsFallback=true but only 1 language model
+   - Fix: Add second language model or disable needsFallback
+
+### Best Practices Checklist
+
+✅ **Before Creating AI Agent**:
+- [ ] Language model is connected first
+- [ ] At least one tool is prepared (or will be added)
+- [ ] System message is thoughtful and specific
+
+✅ **For Each Tool**:
+- [ ] Has toolDescription/description (15+ characters)
+- [ ] toolDescription explains WHEN to use the tool
+- [ ] All required parameters are configured
+- [ ] Credentials are set up if needed
+
+✅ **For Production**:
+- [ ] Workflow validated with n8n_validate_workflow
+- [ ] Tested with real user queries
+- [ ] Fallback model configured for reliability
+- [ ] Error handling in place
+- [ ] maxIterations set appropriately (default 10, max 50)
+
+---
+
+## 7. Troubleshooting {#troubleshooting}
+
+### Problem: "AI Agent has no language model"
+
+**Cause**: Connection created AFTER AI Agent or using wrong sourceOutput
+
+**Solution**:
+\`\`\`typescript
+n8n_update_partial_workflow({
+  operations: [
+    {
+      type: "addConnection",
+      source: "OpenAI Chat Model",
+      target: "AI Agent",
+      sourceOutput: "ai_languageModel"  // ← CRITICAL
+    }
+  ]
+})
+\`\`\`
+
+### Problem: "Tool has no description"
+
+**Cause**: HTTP Request Tool or Code Tool missing toolDescription/description
+
+**Solution**:
+\`\`\`typescript
+{
+  type: "updateNode",
+  nodeName: "HTTP Request Tool",
+  updates: {
+    "parameters.toolDescription": "Call weather API to get current conditions for a city"
+  }
+}
+\`\`\`
+
+### Problem: "Streaming mode not working"
+
+**Causes**:
+1. Chat Trigger not set to streaming
+2. AI Agent has main output connections
+3. Target of Chat Trigger is not AI Agent
+
+**Solution**:
+\`\`\`typescript
+// 1. Set Chat Trigger to streaming
+{
+  type: "updateNode",
+  nodeName: "Chat Trigger",
+  updates: {
+    "parameters.options.responseMode": "streaming"
+  }
+}
+
+// 2. Remove AI Agent main outputs
+{
+  type: "removeConnection",
+  source: "AI Agent",
+  target: "Any Output Node"
+}
+\`\`\`
+
+### Problem: "Agent keeps looping"
+
+**Cause**: Tool not returning proper response or agent stuck in reasoning loop
+
+**Solutions**:
+1. Set maxIterations lower: \`"parameters.maxIterations": 5\`
+2. Improve tool descriptions to be more specific
+3. Add system message guidance: "Use tools efficiently, don't repeat actions"
+
+---
+
+## Quick Reference
+
+### Essential Tools
+
+| Tool | Purpose | Key Parameters |
+|------|---------|----------------|
+| HTTP Request Tool | API calls | toolDescription, url, placeholders |
+| Code Tool | Custom logic | name, description, code, inputSchema |
+| Vector Store Tool | Knowledge search | description, topK |
+| AI Agent Tool | Sub-agents | name, description, systemMessage |
+| MCP Client Tool | MCP protocol | description, mcpServer, tool |
+
+### Connection Quick Codes
+
+\`\`\`typescript
+// Language Model → AI Agent
+sourceOutput: "ai_languageModel"
+
+// Tool → AI Agent
+sourceOutput: "ai_tool"
+
+// Memory → AI Agent
+sourceOutput: "ai_memory"
+
+// Parser → AI Agent
+sourceOutput: "ai_outputParser"
+
+// Embeddings → Vector Store
+sourceOutput: "ai_embedding"
+
+// Vector Store → Vector Store Tool
+sourceOutput: "ai_vectorStore"
+\`\`\`
+
+### Validation Command
+
+\`\`\`typescript
+n8n_validate_workflow({id: "workflow_id"})
+\`\`\`
+
+---
+
+## Related Resources
+
+- **FINAL_AI_VALIDATION_SPEC.md**: Complete validation rules
+- **n8n_update_partial_workflow**: Workflow modification tool
+- **search_nodes({query: "AI", includeExamples: true})**: Find AI nodes with examples
+- **get_node_essentials({nodeType: "...", includeExamples: true})**: Node details with examples
+
+---
+
+*This guide is part of the n8n-mcp documentation system. For questions or issues, refer to the validation spec or use tools_documentation() for specific topics.*`,
+    parameters: {},
+    returns: 'Complete AI Agents guide with architecture, patterns, validation, and troubleshooting',
+    examples: [
+      'tools_documentation({topic: "ai_agents_guide"}) - Full guide',
+      'tools_documentation({topic: "ai_agents_guide", depth: "essentials"}) - Quick reference',
+      'When user asks about AI Agents, Chat Trigger, or building AI workflows → Point to this guide'
+    ],
+    useCases: [
+      'Learning AI Agent architecture in n8n',
+      'Understanding AI connection types and patterns',
+      'Building first AI Agent workflow step-by-step',
+      'Implementing advanced patterns (streaming, fallback, RAG, multi-agent)',
+      'Troubleshooting AI workflow issues',
+      'Validating AI workflows before deployment',
+      'Quick reference for connection types and tools'
+    ],
+    performance: 'N/A - Static documentation',
+    bestPractices: [
+      'Reference this guide when users ask about AI Agents',
+      'Point to specific sections based on user needs',
+      'Combine with search_nodes(includeExamples=true) for working examples',
+      'Validate workflows after following guide instructions',
+      'Use FINAL_AI_VALIDATION_SPEC.md for detailed requirements'
+    ],
+    pitfalls: [
+      'This is a guide, not an executable tool',
+      'Always validate workflows after making changes',
+      'AI connections require sourceOutput parameter',
+      'Streaming mode has specific constraints',
+      'Some features require specific AI Agent versions (v2.1+ for fallback)'
+    ],
+    relatedTools: [
+      'n8n_create_workflow',
+      'n8n_update_partial_workflow',
+      'n8n_validate_workflow',
+      'search_nodes',
+      'get_node_essentials',
+      'list_ai_tools'
+    ]
+  }
+};

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

@@ -0,0 +1,2 @@
+// Export all guides
+export { aiAgentsGuide } from './ai-agents-guide';

src/mcp/tool-docs/index.ts

@@ -25,12 +25,15 @@ import {
   searchTemplatesByMetadataDoc,
   getTemplatesForTaskDoc
 } from './templates';
-import { 
+import {
   toolsDocumentationDoc,
   n8nDiagnosticDoc,
   n8nHealthCheckDoc,
   n8nListAvailableToolsDoc
 } from './system';
+import {
+  aiAgentsGuide
+} from './guides';
 import {
   n8nCreateWorkflowDoc,
   n8nGetWorkflowDoc,
@@ -56,7 +59,10 @@ export const toolsDocumentation: Record<string, ToolDocumentation> = {
   n8n_diagnostic: n8nDiagnosticDoc,
   n8n_health_check: n8nHealthCheckDoc,
   n8n_list_available_tools: n8nListAvailableToolsDoc,
-  
+
+  // Guides
+  ai_agents_guide: aiAgentsGuide,
+
   // Discovery tools
   search_nodes: searchNodesDoc,
   list_nodes: listNodesDoc,

src/mcp/tool-docs/system/n8n-diagnostic.ts

@@ -4,14 +4,16 @@ export const n8nDiagnosticDoc: ToolDocumentation = {
   name: 'n8n_diagnostic',
   category: 'system',
   essentials: {
-    description: 'Diagnose n8n API configuration and troubleshoot why n8n management tools might not be working',
+    description: 'Comprehensive diagnostic with environment-aware debugging, version checks, performance metrics, and mode-specific troubleshooting',
     keyParameters: ['verbose'],
     example: 'n8n_diagnostic({verbose: true})',
-    performance: 'Instant - checks environment and configuration only',
+    performance: 'Fast - checks environment, API, and npm version (~180ms median)',
     tips: [
-      'Run first when n8n tools are missing or failing - shows exact configuration issues',
-      'Use verbose=true for detailed debugging info including environment variables',
-      'If tools are missing, check that N8N_API_URL and N8N_API_KEY are configured'
+      'Now includes environment-aware debugging based on MCP_MODE (http/stdio)',
+      'Provides mode-specific troubleshooting (HTTP server vs Claude Desktop)',
+      'Detects Docker and cloud platforms for targeted guidance',
+      'Shows performance metrics: response time and cache statistics',
+      'Includes data-driven tips based on 82% user success rate'
     ]
   },
   full: {
@@ -35,15 +37,31 @@ The diagnostic is essential when:
         default: false
       }
     },
-    returns: `Diagnostic report object containing:
-- status: Overall health status ('ok', 'error', 'not_configured')
-- apiUrl: Detected API URL (or null if not configured)
-- apiKeyStatus: Status of API key ('configured', 'missing', 'invalid')
-- toolsAvailable: Number of n8n management tools available
-- connectivity: API connectivity test results
-- errors: Array of specific error messages
-- suggestions: Array of actionable fix suggestions
-- verbose: Additional debug information (if verbose=true)`,
+    returns: `Comprehensive diagnostic report containing:
+- timestamp: ISO timestamp of diagnostic run
+- environment: Enhanced environment variables
+  - N8N_API_URL, N8N_API_KEY (masked), NODE_ENV, MCP_MODE
+  - isDocker: Boolean indicating if running in Docker
+  - cloudPlatform: Detected cloud platform (railway/render/fly/etc.) or null
+  - nodeVersion: Node.js version
+  - platform: OS platform (darwin/win32/linux)
+- apiConfiguration: API configuration and connectivity status
+  - configured, status (connected/error/version), config details
+- versionInfo: Version check results (current, latest, upToDate, message, updateCommand)
+- toolsAvailability: Tool availability breakdown (doc tools + management tools)
+- performance: Performance metrics (responseTimeMs, cacheHitRate, cachedInstances)
+- modeSpecificDebug: Mode-specific debugging (ALWAYS PRESENT)
+  - HTTP mode: port, authTokenConfigured, serverUrl, healthCheckUrl, troubleshooting steps, commonIssues
+  - stdio mode: configLocation, troubleshooting steps, commonIssues
+- dockerDebug: Docker-specific guidance (if IS_DOCKER=true)
+  - containerDetected, troubleshooting steps, commonIssues
+- cloudPlatformDebug: Cloud platform-specific tips (if platform detected)
+  - name, troubleshooting steps tailored to platform (Railway/Render/Fly/K8s/AWS/etc.)
+- nextSteps: Context-specific guidance (if API connected)
+- troubleshooting: Troubleshooting guidance (if API not connecting)
+- setupGuide: Setup guidance (if API not configured)
+- updateWarning: Update recommendation (if version outdated)
+- debug: Verbose debug information (if verbose=true)`,
     examples: [
       'n8n_diagnostic({}) - Quick diagnostic check',
       'n8n_diagnostic({verbose: true}) - Detailed diagnostic with environment info',

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

@@ -4,14 +4,15 @@ export const n8nHealthCheckDoc: ToolDocumentation = {
   name: 'n8n_health_check',
   category: 'system',
   essentials: {
-    description: 'Check n8n instance health, API connectivity, and available features',
+    description: 'Check n8n instance health, API connectivity, version status, and performance metrics',
     keyParameters: [],
     example: 'n8n_health_check({})',
-    performance: 'Fast - single API call to health endpoint',
+    performance: 'Fast - single API call (~150-200ms median)',
     tips: [
       'Use before starting workflow operations to ensure n8n is responsive',
-      'Check regularly in production environments for monitoring',
-      'Returns version info and feature availability for compatibility checks'
+      'Automatically checks if n8n-mcp version is outdated',
+      'Returns version info, performance metrics, and next-step recommendations',
+      'New: Shows cache hit rate and response time for performance monitoring'
     ]
   },
   full: {
@@ -33,17 +34,27 @@ Health checks are crucial for:
     parameters: {},
     returns: `Health status object containing:
 - status: Overall health status ('healthy', 'degraded', 'error')
-- version: n8n instance version information
+- n8nVersion: n8n instance version information
 - instanceId: Unique identifier for the n8n instance
 - features: Object listing available features and their status
-- apiVersion: API version for compatibility checking
-- responseTime: API response time in milliseconds
-- timestamp: Check timestamp
-- details: Additional health metrics from n8n`,
+- mcpVersion: Current n8n-mcp version
+- supportedN8nVersion: Recommended n8n version for compatibility
+- versionCheck: Version status information
+  - current: Current n8n-mcp version
+  - latest: Latest available version from npm
+  - upToDate: Boolean indicating if version is current
+  - message: Formatted version status message
+  - updateCommand: Command to update (if outdated)
+- performance: Performance metrics
+  - responseTimeMs: API response time in milliseconds
+  - cacheHitRate: Cache efficiency percentage
+  - cachedInstances: Number of cached API instances
+- nextSteps: Recommended actions after health check
+- updateWarning: Warning if version is outdated (if applicable)`,
     examples: [
-      'n8n_health_check({}) - Standard health check',
-      '// Use in monitoring scripts\nconst health = await n8n_health_check({});\nif (health.status !== "healthy") alert("n8n is down!");',
-      '// Check before critical operations\nconst health = await n8n_health_check({});\nif (health.responseTime > 1000) console.warn("n8n is slow");'
+      'n8n_health_check({}) - Complete health check with version and performance data',
+      '// Use in monitoring scripts\nconst health = await n8n_health_check({});\nif (health.status !== "ok") alert("n8n is down!");\nif (!health.versionCheck.upToDate) console.log("Update available:", health.versionCheck.updateCommand);',
+      '// Check before critical operations\nconst health = await n8n_health_check({});\nif (health.performance.responseTimeMs > 1000) console.warn("n8n is slow");\nif (health.versionCheck.isOutdated) console.log(health.updateWarning);'
     ],
     useCases: [
       'Pre-flight checks before workflow deployments',

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

@@ -4,19 +4,24 @@ export const n8nUpdatePartialWorkflowDoc: ToolDocumentation = {
   name: 'n8n_update_partial_workflow',
   category: 'workflow_management',
   essentials: {
-    description: 'Update workflow incrementally with diff operations. Types: addNode, removeNode, updateNode, moveNode, enable/disableNode, addConnection, removeConnection, cleanStaleConnections, replaceConnections, updateSettings, updateName, add/removeTag.',
+    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. Full support for AI connections (ai_languageModel, ai_tool, ai_memory, ai_embedding, ai_vectorStore, ai_document, ai_textSplitter, ai_outputParser).',
     keyParameters: ['id', 'operations', 'continueOnError'],
-    example: 'n8n_update_partial_workflow({id: "wf_123", operations: [{type: "cleanStaleConnections"}]})',
+    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 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'
+      'Validate with validateOnly first',
+      'For AI connections, specify sourceOutput type (ai_languageModel, ai_tool, etc.)',
+      'Batch AI component connections for atomic updates'
     ]
   },
   full: {
-    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. v2.14.4 adds cleanup operations and best-effort mode for workflow recovery scenarios.
+    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:
 
@@ -29,11 +34,11 @@ export const n8nUpdatePartialWorkflowDoc: ToolDocumentation = {
 - **disableNode**: Disable an active node
 
 ### Connection Operations (5 types):
-- **addConnection**: Connect nodes (source→target)
+- **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)
-- **updateConnection**: Modify connection properties
-- **cleanStaleConnections**: Auto-remove all connections referencing non-existent nodes (NEW in v2.14.4)
-- **replaceConnections**: Replace entire connections object (NEW in v2.14.4)
+- **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
@@ -41,7 +46,46 @@ export const n8nUpdatePartialWorkflowDoc: ToolDocumentation = {
 - **addTag**: Add a workflow tag
 - **removeTag**: Remove a workflow tag
 
-## New in v2.14.4: Cleanup & Recovery Features
+## 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.
+
+## AI Connection Support
+
+Full support for all 8 AI connection types used in n8n AI workflows:
+
+**Connection Types**:
+- **ai_languageModel**: Connect language models (OpenAI, Anthropic, Google Gemini) to AI Agents
+- **ai_tool**: Connect tools (HTTP Request Tool, Code Tool, etc.) to AI Agents
+- **ai_memory**: Connect memory systems (Window Buffer, Conversation Summary) to AI Agents
+- **ai_outputParser**: Connect output parsers (Structured, JSON) to AI Agents
+- **ai_embedding**: Connect embedding models to Vector Stores
+- **ai_vectorStore**: Connect vector stores to Vector Store Tools
+- **ai_document**: Connect document loaders to Vector Stores
+- **ai_textSplitter**: Connect text splitters to document processing chains
+
+**AI Connection Examples**:
+- Single connection: \`{type: "addConnection", source: "OpenAI", target: "AI Agent", sourceOutput: "ai_languageModel"}\`
+- Fallback model: Use targetIndex (0=primary, 1=fallback) for dual language model setup
+- Multiple tools: Batch multiple \`sourceOutput: "ai_tool"\` connections to one AI Agent
+- Vector retrieval: Chain ai_embedding → ai_vectorStore → ai_tool → AI Agent
+
+**Best Practices**:
+- Always specify \`sourceOutput\` for AI connections (defaults to "main" if omitted)
+- Connect language model BEFORE creating/enabling AI Agent (validation requirement)
+- Use atomic mode (default) when setting up AI workflows to ensure complete configuration
+- Validate AI workflows after changes with \`n8n_validate_workflow\` tool
+
+## Cleanup & Recovery Features
 
 ### Automatic Cleanup
 The **cleanStaleConnections** operation automatically removes broken connection references after node renames/deletions. Essential for workflow recovery.
@@ -63,14 +107,35 @@ Add **ignoreErrors: true** to removeConnection operations to prevent failures wh
     },
     returns: 'Updated workflow object or validation results if validateOnly=true',
     examples: [
-      '// Clean up stale connections after node renames/deletions\nn8n_update_partial_workflow({id: "abc", operations: [{type: "cleanStaleConnections"}]})',
-      '// Remove connection gracefully (no error if it doesn\'t exist)\nn8n_update_partial_workflow({id: "xyz", operations: [{type: "removeConnection", source: "Old Node", target: "Target", ignoreErrors: true}]})',
-      '// Best-effort mode: apply what works, report what fails\nn8n_update_partial_workflow({id: "123", operations: [\n  {type: "updateName", name: "Fixed Workflow"},\n  {type: "removeConnection", source: "Broken", target: "Node"},\n  {type: "cleanStaleConnections"}\n], continueOnError: true})',
-      '// Replace entire connections object\nn8n_update_partial_workflow({id: "456", operations: [{type: "replaceConnections", connections: {"Webhook": {"main": [[{node: "Slack", type: "main", index: 0}]]}}}]})',
-      '// Update node parameter (classic atomic mode)\nn8n_update_partial_workflow({id: "789", operations: [{type: "updateNode", nodeName: "HTTP Request", updates: {"parameters.url": "https://api.example.com"}}]})',
-      '// Validate before applying\nn8n_update_partial_workflow({id: "012", 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})',
+      '\n// ============ AI CONNECTION EXAMPLES ============',
+      '// Connect language model to AI Agent\nn8n_update_partial_workflow({id: "ai1", operations: [{type: "addConnection", source: "OpenAI Chat Model", target: "AI Agent", sourceOutput: "ai_languageModel"}]})',
+      '// Connect tool to AI Agent\nn8n_update_partial_workflow({id: "ai2", operations: [{type: "addConnection", source: "HTTP Request Tool", target: "AI Agent", sourceOutput: "ai_tool"}]})',
+      '// Connect memory to AI Agent\nn8n_update_partial_workflow({id: "ai3", operations: [{type: "addConnection", source: "Window Buffer Memory", target: "AI Agent", sourceOutput: "ai_memory"}]})',
+      '// Connect output parser to AI Agent\nn8n_update_partial_workflow({id: "ai4", operations: [{type: "addConnection", source: "Structured Output Parser", target: "AI Agent", sourceOutput: "ai_outputParser"}]})',
+      '// Complete AI Agent setup: Add language model, tools, and memory\nn8n_update_partial_workflow({id: "ai5", operations: [\n  {type: "addConnection", source: "OpenAI Chat Model", target: "AI Agent", sourceOutput: "ai_languageModel"},\n  {type: "addConnection", source: "HTTP Request Tool", target: "AI Agent", sourceOutput: "ai_tool"},\n  {type: "addConnection", source: "Code Tool", target: "AI Agent", sourceOutput: "ai_tool"},\n  {type: "addConnection", source: "Window Buffer Memory", target: "AI Agent", sourceOutput: "ai_memory"}\n]})',
+      '// Add fallback model to AI Agent (requires v2.1+)\nn8n_update_partial_workflow({id: "ai6", operations: [\n  {type: "addConnection", source: "OpenAI Chat Model", target: "AI Agent", sourceOutput: "ai_languageModel", targetIndex: 0},\n  {type: "addConnection", source: "Anthropic Chat Model", target: "AI Agent", sourceOutput: "ai_languageModel", targetIndex: 1}\n]})',
+      '// Vector Store setup: Connect embeddings and documents\nn8n_update_partial_workflow({id: "ai7", operations: [\n  {type: "addConnection", source: "Embeddings OpenAI", target: "Pinecone Vector Store", sourceOutput: "ai_embedding"},\n  {type: "addConnection", source: "Default Data Loader", target: "Pinecone Vector Store", sourceOutput: "ai_document"}\n]})',
+      '// Connect Vector Store Tool to AI Agent (retrieval setup)\nn8n_update_partial_workflow({id: "ai8", operations: [\n  {type: "addConnection", source: "Pinecone Vector Store", target: "Vector Store Tool", sourceOutput: "ai_vectorStore"},\n  {type: "addConnection", source: "Vector Store Tool", target: "AI Agent", sourceOutput: "ai_tool"}\n]})',
+      '// Rewire AI Agent to use different language model\nn8n_update_partial_workflow({id: "ai9", operations: [{type: "rewireConnection", source: "AI Agent", from: "OpenAI Chat Model", to: "Anthropic Chat Model", sourceOutput: "ai_languageModel"}]})',
+      '// Replace all AI tools for an agent\nn8n_update_partial_workflow({id: "ai10", operations: [\n  {type: "removeConnection", source: "Old Tool 1", target: "AI Agent", sourceOutput: "ai_tool"},\n  {type: "removeConnection", source: "Old Tool 2", target: "AI Agent", sourceOutput: "ai_tool"},\n  {type: "addConnection", source: "New HTTP Tool", target: "AI Agent", sourceOutput: "ai_tool"},\n  {type: "addConnection", source: "New Code Tool", target: "AI Agent", sourceOutput: "ai_tool"}\n]})'
     ],
     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',
@@ -78,17 +143,31 @@ Add **ignoreErrors: true** to removeConnection operations to prevent failures wh
       'Graceful cleanup operations that don\'t fail',
       'Enable/disable nodes',
       'Rename workflows or nodes',
-      'Manage tags efficiently'
+      'Manage tags efficiently',
+      'Connect AI components (language models, tools, memory, parsers)',
+      'Set up AI Agent workflows with multiple tools',
+      'Add fallback language models to AI Agents',
+      'Configure Vector Store retrieval systems',
+      'Swap language models in existing AI workflows',
+      'Batch-update AI tool connections'
     ],
     performance: 'Very fast - typically 50-200ms. Much faster than full updates as only changes are processed.',
     bestPractices: [
+      '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',
       'Check operation order for dependencies',
-      'Use atomic mode (default) for critical updates'
+      'Use atomic mode (default) for critical updates',
+      'For AI connections, always specify sourceOutput (ai_languageModel, ai_tool, ai_memory, etc.)',
+      'Connect language model BEFORE adding AI Agent to ensure validation passes',
+      'Use targetIndex for fallback models (primary=0, fallback=1)',
+      'Batch AI component connections in a single operation for atomicity',
+      'Validate AI workflows after connection changes to catch configuration errors'
     ],
     pitfalls: [
       '**REQUIRES N8N_API_URL and N8N_API_KEY environment variables** - will not work without n8n API access',
@@ -96,7 +175,11 @@ Add **ignoreErrors: true** to removeConnection operations to prevent failures wh
       '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',
+      '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'
     ],

src/parsers/node-parser.ts

@@ -1,4 +1,14 @@
 import { PropertyExtractor } from './property-extractor';
+import type {
+  NodeClass,
+  VersionedNodeInstance
+} from '../types/node-types';
+import {
+  isVersionedNodeInstance,
+  isVersionedNodeClass,
+  getNodeDescription as getNodeDescriptionHelper
+} from '../types/node-types';
+import type { INodeTypeBaseDescription, INodeTypeDescription } from 'n8n-workflow';
 
 export interface ParsedNode {
   style: 'declarative' | 'programmatic';
@@ -22,9 +32,9 @@ export interface ParsedNode {
 
 export class NodeParser {
   private propertyExtractor = new PropertyExtractor();
-  private currentNodeClass: any = null;
-  
-  parse(nodeClass: any, packageName: string): ParsedNode {
+  private currentNodeClass: NodeClass | null = null;
+
+  parse(nodeClass: NodeClass, packageName: string): ParsedNode {
     this.currentNodeClass = nodeClass;
     // Get base description (handles versioned nodes)
     const description = this.getNodeDescription(nodeClass);
@@ -50,46 +60,64 @@ export class NodeParser {
     };
   }
   
-  private getNodeDescription(nodeClass: any): any {
+  private getNodeDescription(nodeClass: NodeClass): INodeTypeBaseDescription | INodeTypeDescription {
     // Try to get description from the class first
-    let description: any;
-    
-    // Check if it's a versioned node (has baseDescription and nodeVersions)
-    if (typeof nodeClass === 'function' && nodeClass.prototype && 
-        nodeClass.prototype.constructor && 
-        nodeClass.prototype.constructor.name === 'VersionedNodeType') {
+    let description: INodeTypeBaseDescription | INodeTypeDescription | undefined;
+
+    // Check if it's a versioned node using type guard
+    if (isVersionedNodeClass(nodeClass)) {
       // This is a VersionedNodeType class - instantiate it
-      const instance = new nodeClass();
-      description = instance.baseDescription || {};
+      try {
+        const instance = new (nodeClass as new () => VersionedNodeInstance)();
+        // Strategic any assertion for accessing both description and baseDescription
+        const inst = instance as any;
+        // Try description first (real VersionedNodeType with getter)
+        // Only fallback to baseDescription if nodeVersions exists (complete VersionedNodeType mock)
+        // This prevents using baseDescription for incomplete mocks that test edge cases
+        description = inst.description || (inst.nodeVersions ? inst.baseDescription : undefined);
+
+        // If still undefined (incomplete mock), leave as undefined to use catch block fallback
+      } catch (e) {
+        // Some nodes might require parameters to instantiate
+      }
     } else if (typeof nodeClass === 'function') {
       // Try to instantiate to get description
       try {
         const instance = new nodeClass();
-        description = instance.description || {};
-        
-        // For versioned nodes, we might need to look deeper
-        if (!description.name && instance.baseDescription) {
-          description = instance.baseDescription;
+        description = instance.description;
+        // If description is empty or missing name, check for baseDescription fallback
+        if (!description || !description.name) {
+          const inst = instance as any;
+          if (inst.baseDescription?.name) {
+            description = inst.baseDescription;
+          }
         }
       } catch (e) {
         // Some nodes might require parameters to instantiate
         // Try to access static properties
-        description = nodeClass.description || {};
+        description = (nodeClass as any).description;
       }
     } else {
       // Maybe it's already an instance
-      description = nodeClass.description || {};
+      description = nodeClass.description;
+      // If description is empty or missing name, check for baseDescription fallback
+      if (!description || !description.name) {
+        const inst = nodeClass as any;
+        if (inst.baseDescription?.name) {
+          description = inst.baseDescription;
+        }
+      }
     }
-    
-    return description;
+
+    return description || ({} as any);
   }
   
-  private detectStyle(nodeClass: any): 'declarative' | 'programmatic' {
+  private detectStyle(nodeClass: NodeClass): 'declarative' | 'programmatic' {
     const desc = this.getNodeDescription(nodeClass);
-    return desc.routing ? 'declarative' : 'programmatic';
+    return (desc as any).routing ? 'declarative' : 'programmatic';
   }
-  
-  private extractNodeType(description: any, packageName: string): string {
+
+  private extractNodeType(description: INodeTypeBaseDescription | INodeTypeDescription, packageName: string): string {
     // Ensure we have the full node type including package prefix
     const name = description.name;
     
@@ -106,57 +134,97 @@ export class NodeParser {
     return `${packagePrefix}.${name}`;
   }
   
-  private extractCategory(description: any): string {
-    return description.group?.[0] || 
-           description.categories?.[0] || 
-           description.category || 
+  private extractCategory(description: INodeTypeBaseDescription | INodeTypeDescription): string {
+    return description.group?.[0] ||
+           (description as any).categories?.[0] ||
+           (description as any).category ||
            'misc';
   }
-  
-  private detectTrigger(description: any): boolean {
+
+  private detectTrigger(description: INodeTypeBaseDescription | INodeTypeDescription): boolean {
+    // Strategic any assertion for properties that only exist on INodeTypeDescription
+    const desc = description as any;
+
     // Primary check: group includes 'trigger'
     if (description.group && Array.isArray(description.group)) {
       if (description.group.includes('trigger')) {
         return true;
       }
     }
-    
+
     // Fallback checks for edge cases
-    return description.polling === true || 
-           description.trigger === true ||
-           description.eventTrigger === true ||
+    return desc.polling === true ||
+           desc.trigger === true ||
+           desc.eventTrigger === true ||
            description.name?.toLowerCase().includes('trigger');
   }
   
-  private detectWebhook(description: any): boolean {
-    return (description.webhooks?.length > 0) ||
-           description.webhook === true ||
+  private detectWebhook(description: INodeTypeBaseDescription | INodeTypeDescription): boolean {
+    const desc = description as any; // INodeTypeDescription has webhooks, but INodeTypeBaseDescription doesn't
+    return (desc.webhooks?.length > 0) ||
+           desc.webhook === true ||
            description.name?.toLowerCase().includes('webhook');
   }
   
-  private extractVersion(nodeClass: any): string {
-    // Check instance for baseDescription first
+  /**
+   * Extracts the version from a node class.
+   *
+   * Priority Chain:
+   * 1. Instance currentVersion (VersionedNodeType's computed property)
+   * 2. Instance description.defaultVersion (explicit default)
+   * 3. Instance nodeVersions (fallback to max available version)
+   * 4. Description version array (legacy nodes)
+   * 5. Description version scalar (simple versioning)
+   * 6. Class-level properties (if instantiation fails)
+   * 7. Default to "1"
+   *
+   * Critical Fix (v2.17.4): Removed check for non-existent instance.baseDescription.defaultVersion
+   * which caused AI Agent to incorrectly return version "3" instead of "2.2"
+   *
+   * @param nodeClass - The node class or instance to extract version from
+   * @returns The version as a string
+   */
+  private extractVersion(nodeClass: NodeClass): string {
+    // Check instance properties first
     try {
       const instance = typeof nodeClass === 'function' ? new nodeClass() : nodeClass;
-      
-      // Handle instance-level baseDescription
-      if (instance?.baseDescription?.defaultVersion) {
-        return instance.baseDescription.defaultVersion.toString();
+      // Strategic any assertion - instance could be INodeType or IVersionedNodeType
+      const inst = instance as any;
+
+      // PRIORITY 1: Check currentVersion (what VersionedNodeType actually uses)
+      // For VersionedNodeType, currentVersion = defaultVersion ?? max(nodeVersions)
+      if (inst?.currentVersion !== undefined) {
+        return inst.currentVersion.toString();
       }
-      
-      // Handle instance-level nodeVersions
-      if (instance?.nodeVersions) {
-        const versions = Object.keys(instance.nodeVersions);
-        return Math.max(...versions.map(Number)).toString();
+
+      // PRIORITY 2: Handle instance-level description.defaultVersion
+      // VersionedNodeType stores baseDescription as 'description', not 'baseDescription'
+      if (inst?.description?.defaultVersion) {
+        return inst.description.defaultVersion.toString();
       }
-      
+
+      // PRIORITY 3: Handle instance-level nodeVersions (fallback to max)
+      if (inst?.nodeVersions) {
+        const versions = Object.keys(inst.nodeVersions).map(Number);
+        if (versions.length > 0) {
+          const maxVersion = Math.max(...versions);
+          if (!isNaN(maxVersion)) {
+            return maxVersion.toString();
+          }
+        }
+      }
+
       // Handle version array in description (e.g., [1, 1.1, 1.2])
-      if (instance?.description?.version) {
-        const version = instance.description.version;
+      if (inst?.description?.version) {
+        const version = inst.description.version;
         if (Array.isArray(version)) {
-          // Find the maximum version from the array
-          const maxVersion = Math.max(...version.map((v: any) => parseFloat(v.toString())));
-          return maxVersion.toString();
+          const numericVersions = version.map((v: any) => parseFloat(v.toString()));
+          if (numericVersions.length > 0) {
+            const maxVersion = Math.max(...numericVersions);
+            if (!isNaN(maxVersion)) {
+              return maxVersion.toString();
+            }
+          }
         } else if (typeof version === 'number' || typeof version === 'string') {
           return version.toString();
         }
@@ -165,94 +233,119 @@ export class NodeParser {
       // Some nodes might require parameters to instantiate
       // Try class-level properties
     }
-    
+
     // Handle class-level VersionedNodeType with defaultVersion
-    if (nodeClass.baseDescription?.defaultVersion) {
-      return nodeClass.baseDescription.defaultVersion.toString();
+    // Note: Most VersionedNodeType classes don't have static properties
+    // Strategic any assertion for class-level property access
+    const nodeClassAny = nodeClass as any;
+    if (nodeClassAny.description?.defaultVersion) {
+      return nodeClassAny.description.defaultVersion.toString();
     }
-    
+
     // Handle class-level VersionedNodeType with nodeVersions
-    if (nodeClass.nodeVersions) {
-      const versions = Object.keys(nodeClass.nodeVersions);
-      return Math.max(...versions.map(Number)).toString();
-    }
-    
-    // Also check class-level description for version array
-    const description = this.getNodeDescription(nodeClass);
-    if (description?.version) {
-      if (Array.isArray(description.version)) {
-        const maxVersion = Math.max(...description.version.map((v: any) => parseFloat(v.toString())));
-        return maxVersion.toString();
-      } else if (typeof description.version === 'number' || typeof description.version === 'string') {
-        return description.version.toString();
+    if (nodeClassAny.nodeVersions) {
+      const versions = Object.keys(nodeClassAny.nodeVersions).map(Number);
+      if (versions.length > 0) {
+        const maxVersion = Math.max(...versions);
+        if (!isNaN(maxVersion)) {
+          return maxVersion.toString();
+        }
       }
     }
-    
+
+    // Also check class-level description for version array
+    const description = this.getNodeDescription(nodeClass);
+    const desc = description as any; // Strategic assertion for version property
+    if (desc?.version) {
+      if (Array.isArray(desc.version)) {
+        const numericVersions = desc.version.map((v: any) => parseFloat(v.toString()));
+        if (numericVersions.length > 0) {
+          const maxVersion = Math.max(...numericVersions);
+          if (!isNaN(maxVersion)) {
+            return maxVersion.toString();
+          }
+        }
+      } else if (typeof desc.version === 'number' || typeof desc.version === 'string') {
+        return desc.version.toString();
+      }
+    }
+
     // Default to version 1
     return '1';
   }
   
-  private detectVersioned(nodeClass: any): boolean {
+  private detectVersioned(nodeClass: NodeClass): boolean {
     // Check instance-level properties first
     try {
       const instance = typeof nodeClass === 'function' ? new nodeClass() : nodeClass;
-      
+      // Strategic any assertion - instance could be INodeType or IVersionedNodeType
+      const inst = instance as any;
+
       // Check for instance baseDescription with defaultVersion
-      if (instance?.baseDescription?.defaultVersion) {
+      if (inst?.baseDescription?.defaultVersion) {
         return true;
       }
-      
+
       // Check for nodeVersions
-      if (instance?.nodeVersions) {
+      if (inst?.nodeVersions) {
         return true;
       }
-      
+
       // Check for version array in description
-      if (instance?.description?.version && Array.isArray(instance.description.version)) {
+      if (inst?.description?.version && Array.isArray(inst.description.version)) {
         return true;
       }
     } catch (e) {
       // Some nodes might require parameters to instantiate
       // Try class-level checks
     }
-    
+
     // Check class-level nodeVersions
-    if (nodeClass.nodeVersions || nodeClass.baseDescription?.defaultVersion) {
+    // Strategic any assertion for class-level property access
+    const nodeClassAny = nodeClass as any;
+    if (nodeClassAny.nodeVersions || nodeClassAny.baseDescription?.defaultVersion) {
       return true;
     }
-    
+
     // Also check class-level description for version array
     const description = this.getNodeDescription(nodeClass);
-    if (description?.version && Array.isArray(description.version)) {
+    const desc = description as any; // Strategic assertion for version property
+    if (desc?.version && Array.isArray(desc.version)) {
       return true;
     }
     
     return false;
   }
 
-  private extractOutputs(description: any): { outputs?: any[], outputNames?: string[] } {
+  private extractOutputs(description: INodeTypeBaseDescription | INodeTypeDescription): { outputs?: any[], outputNames?: string[] } {
     const result: { outputs?: any[], outputNames?: string[] } = {};
-    
+    // Strategic any assertion for outputs/outputNames properties
+    const desc = description as any;
+
     // First check the base description
-    if (description.outputs) {
-      result.outputs = Array.isArray(description.outputs) ? description.outputs : [description.outputs];
+    if (desc.outputs) {
+      result.outputs = Array.isArray(desc.outputs) ? desc.outputs : [desc.outputs];
     }
-    
-    if (description.outputNames) {
-      result.outputNames = Array.isArray(description.outputNames) ? description.outputNames : [description.outputNames];
+
+    if (desc.outputNames) {
+      result.outputNames = Array.isArray(desc.outputNames) ? desc.outputNames : [desc.outputNames];
     }
-    
+
     // If no outputs found and this is a versioned node, check the latest version
     if (!result.outputs && !result.outputNames) {
       const nodeClass = this.currentNodeClass; // We'll need to track this
       if (nodeClass) {
         try {
-          const instance = new nodeClass();
-          if (instance.nodeVersions) {
+          const instance = typeof nodeClass === 'function' ? new nodeClass() : nodeClass;
+          // Strategic any assertion for instance properties
+          const inst = instance as any;
+          if (inst.nodeVersions) {
             // Get the latest version
-            const versions = Object.keys(instance.nodeVersions).map(Number);
-            const latestVersion = Math.max(...versions);
-            const versionedDescription = instance.nodeVersions[latestVersion]?.description;
+            const versions = Object.keys(inst.nodeVersions).map(Number);
+            if (versions.length > 0) {
+              const latestVersion = Math.max(...versions);
+              if (!isNaN(latestVersion)) {
+                const versionedDescription = inst.nodeVersions[latestVersion]?.description;
             
             if (versionedDescription) {
               if (versionedDescription.outputs) {
@@ -262,11 +355,13 @@ export class NodeParser {
               }
               
               if (versionedDescription.outputNames) {
-                result.outputNames = Array.isArray(versionedDescription.outputNames) 
-                  ? versionedDescription.outputNames 
+                result.outputNames = Array.isArray(versionedDescription.outputNames)
+                  ? versionedDescription.outputNames
                   : [versionedDescription.outputNames];
               }
             }
+              }
+            }
           }
         } catch (e) {
           // Ignore errors from instantiating node

src/parsers/property-extractor.ts

@@ -1,8 +1,10 @@
+import type { NodeClass } from '../types/node-types';
+
 export class PropertyExtractor {
   /**
    * Extract properties with proper handling of n8n's complex structures
    */
-  extractProperties(nodeClass: any): any[] {
+  extractProperties(nodeClass: NodeClass): any[] {
     const properties: any[] = [];
     
     // First try to get instance-level properties
@@ -15,12 +17,16 @@ export class PropertyExtractor {
     
     // Handle versioned nodes - check instance for nodeVersions
     if (instance?.nodeVersions) {
-      const versions = Object.keys(instance.nodeVersions);
-      const latestVersion = Math.max(...versions.map(Number));
-      const versionedNode = instance.nodeVersions[latestVersion];
-      
-      if (versionedNode?.description?.properties) {
-        return this.normalizeProperties(versionedNode.description.properties);
+      const versions = Object.keys(instance.nodeVersions).map(Number);
+      if (versions.length > 0) {
+        const latestVersion = Math.max(...versions);
+        if (!isNaN(latestVersion)) {
+          const versionedNode = instance.nodeVersions[latestVersion];
+
+          if (versionedNode?.description?.properties) {
+            return this.normalizeProperties(versionedNode.description.properties);
+          }
+        }
       }
     }
     
@@ -35,30 +41,36 @@ export class PropertyExtractor {
     return properties;
   }
   
-  private getNodeDescription(nodeClass: any): any {
+  private getNodeDescription(nodeClass: NodeClass): any {
     // Try to get description from the class first
     let description: any;
-    
+
     if (typeof nodeClass === 'function') {
       // Try to instantiate to get description
       try {
         const instance = new nodeClass();
-        description = instance.description || instance.baseDescription || {};
+        // Strategic any assertion for instance properties
+        const inst = instance as any;
+        description = inst.description || inst.baseDescription || {};
       } catch (e) {
         // Some nodes might require parameters to instantiate
-        description = nodeClass.description || {};
+        // Strategic any assertion for class-level properties
+        const nodeClassAny = nodeClass as any;
+        description = nodeClassAny.description || {};
       }
     } else {
-      description = nodeClass.description || {};
+      // Strategic any assertion for instance properties
+      const inst = nodeClass as any;
+      description = inst.description || {};
     }
-    
+
     return description;
   }
   
   /**
    * Extract operations from both declarative and programmatic nodes
    */
-  extractOperations(nodeClass: any): any[] {
+  extractOperations(nodeClass: NodeClass): any[] {
     const operations: any[] = [];
     
     // First try to get instance-level data
@@ -71,12 +83,16 @@ export class PropertyExtractor {
     
     // Handle versioned nodes
     if (instance?.nodeVersions) {
-      const versions = Object.keys(instance.nodeVersions);
-      const latestVersion = Math.max(...versions.map(Number));
-      const versionedNode = instance.nodeVersions[latestVersion];
-      
-      if (versionedNode?.description) {
-        return this.extractOperationsFromDescription(versionedNode.description);
+      const versions = Object.keys(instance.nodeVersions).map(Number);
+      if (versions.length > 0) {
+        const latestVersion = Math.max(...versions);
+        if (!isNaN(latestVersion)) {
+          const versionedNode = instance.nodeVersions[latestVersion];
+
+          if (versionedNode?.description) {
+            return this.extractOperationsFromDescription(versionedNode.description);
+          }
+        }
       }
     }
     
@@ -138,33 +154,35 @@ export class PropertyExtractor {
   /**
    * Deep search for AI tool capability
    */
-  detectAIToolCapability(nodeClass: any): boolean {
+  detectAIToolCapability(nodeClass: NodeClass): boolean {
     const description = this.getNodeDescription(nodeClass);
-    
+
     // Direct property check
     if (description?.usableAsTool === true) return true;
-    
+
     // Check in actions for declarative nodes
     if (description?.actions?.some((a: any) => a.usableAsTool === true)) return true;
-    
+
     // Check versioned nodes
-    if (nodeClass.nodeVersions) {
-      for (const version of Object.values(nodeClass.nodeVersions)) {
+    // Strategic any assertion for nodeVersions property
+    const nodeClassAny = nodeClass as any;
+    if (nodeClassAny.nodeVersions) {
+      for (const version of Object.values(nodeClassAny.nodeVersions)) {
         if ((version as any).description?.usableAsTool === true) return true;
       }
     }
-    
+
     // Check for specific AI-related properties
     const aiIndicators = ['openai', 'anthropic', 'huggingface', 'cohere', 'ai'];
     const nodeName = description?.name?.toLowerCase() || '';
-    
+
     return aiIndicators.some(indicator => nodeName.includes(indicator));
   }
   
   /**
    * Extract credential requirements with proper structure
    */
-  extractCredentials(nodeClass: any): any[] {
+  extractCredentials(nodeClass: NodeClass): any[] {
     const credentials: any[] = [];
     
     // First try to get instance-level data
@@ -177,12 +195,16 @@ export class PropertyExtractor {
     
     // Handle versioned nodes
     if (instance?.nodeVersions) {
-      const versions = Object.keys(instance.nodeVersions);
-      const latestVersion = Math.max(...versions.map(Number));
-      const versionedNode = instance.nodeVersions[latestVersion];
-      
-      if (versionedNode?.description?.credentials) {
-        return versionedNode.description.credentials;
+      const versions = Object.keys(instance.nodeVersions).map(Number);
+      if (versions.length > 0) {
+        const latestVersion = Math.max(...versions);
+        if (!isNaN(latestVersion)) {
+          const versionedNode = instance.nodeVersions[latestVersion];
+
+          if (versionedNode?.description?.credentials) {
+            return versionedNode.description.credentials;
+          }
+        }
       }
     }
     
@@ -209,6 +231,7 @@ export class PropertyExtractor {
       required: prop.required,
       displayOptions: prop.displayOptions,
       typeOptions: prop.typeOptions,
+      modes: prop.modes, // For resourceLocator type properties - modes are at top level
       noDataExpression: prop.noDataExpression
     }));
   }

src/parsers/simple-parser.ts

@@ -1,3 +1,13 @@
+import type {
+  NodeClass,
+  VersionedNodeInstance
+} from '../types/node-types';
+import {
+  isVersionedNodeInstance,
+  isVersionedNodeClass
+} from '../types/node-types';
+import type { INodeTypeBaseDescription, INodeTypeDescription } from 'n8n-workflow';
+
 export interface ParsedNode {
   style: 'declarative' | 'programmatic';
   nodeType: string;
@@ -15,24 +25,32 @@ export interface ParsedNode {
 }
 
 export class SimpleParser {
-  parse(nodeClass: any): ParsedNode {
-    let description: any;
+  parse(nodeClass: NodeClass): ParsedNode {
+    let description: INodeTypeBaseDescription | INodeTypeDescription;
     let isVersioned = false;
-    
+
     // Try to get description from the class
     try {
-      // Check if it's a versioned node (has baseDescription and nodeVersions)
-      if (typeof nodeClass === 'function' && nodeClass.prototype && 
-          nodeClass.prototype.constructor && 
-          nodeClass.prototype.constructor.name === 'VersionedNodeType') {
+      // Check if it's a versioned node using type guard
+      if (isVersionedNodeClass(nodeClass)) {
         // This is a VersionedNodeType class - instantiate it
-        const instance = new nodeClass();
-        description = instance.baseDescription || {};
+        const instance = new (nodeClass as new () => VersionedNodeInstance)();
+        // Strategic any assertion for accessing both description and baseDescription
+        const inst = instance as any;
+        // Try description first (real VersionedNodeType with getter)
+        // Only fallback to baseDescription if nodeVersions exists (complete VersionedNodeType mock)
+        // This prevents using baseDescription for incomplete mocks that test edge cases
+        description = inst.description || (inst.nodeVersions ? inst.baseDescription : undefined);
+
+        // If still undefined (incomplete mock), use empty object to allow graceful failure later
+        if (!description) {
+          description = {} as any;
+        }
         isVersioned = true;
-        
+
         // For versioned nodes, try to get properties from the current version
-        if (instance.nodeVersions && instance.currentVersion) {
-          const currentVersionNode = instance.nodeVersions[instance.currentVersion];
+        if (inst.nodeVersions && inst.currentVersion) {
+          const currentVersionNode = inst.nodeVersions[inst.currentVersion];
           if (currentVersionNode && currentVersionNode.description) {
             // Merge baseDescription with version-specific description
             description = { ...description, ...currentVersionNode.description };
@@ -42,63 +60,76 @@ export class SimpleParser {
         // Try to instantiate to get description
         try {
           const instance = new nodeClass();
-          description = instance.description || {};
-          
-          // For versioned nodes, we might need to look deeper
-          if (!description.name && instance.baseDescription) {
-            description = instance.baseDescription;
-            isVersioned = true;
+          description = instance.description;
+          // If description is empty or missing name, check for baseDescription fallback
+          if (!description || !description.name) {
+            const inst = instance as any;
+            if (inst.baseDescription?.name) {
+              description = inst.baseDescription;
+            }
           }
         } catch (e) {
           // Some nodes might require parameters to instantiate
           // Try to access static properties or look for common patterns
-          description = {};
+          description = {} as any;
         }
       } else {
         // Maybe it's already an instance
-        description = nodeClass.description || {};
+        description = nodeClass.description;
+        // If description is empty or missing name, check for baseDescription fallback
+        if (!description || !description.name) {
+          const inst = nodeClass as any;
+          if (inst.baseDescription?.name) {
+            description = inst.baseDescription;
+          }
+        }
       }
     } catch (error) {
       // If instantiation fails, try to get static description
-      description = nodeClass.description || {};
+      description = (nodeClass as any).description || ({} as any);
     }
-    
-    const isDeclarative = !!description.routing;
-    
+
+    // Strategic any assertion for properties that don't exist on both union sides
+    const desc = description as any;
+    const isDeclarative = !!desc.routing;
+
     // Ensure we have a valid nodeType
     if (!description.name) {
       throw new Error('Node is missing name property');
     }
-    
+
     return {
       style: isDeclarative ? 'declarative' : 'programmatic',
       nodeType: description.name,
       displayName: description.displayName || description.name,
       description: description.description,
-      category: description.group?.[0] || description.categories?.[0],
-      properties: description.properties || [],
-      credentials: description.credentials || [],
-      isAITool: description.usableAsTool === true,
+      category: description.group?.[0] || desc.categories?.[0],
+      properties: desc.properties || [],
+      credentials: desc.credentials || [],
+      isAITool: desc.usableAsTool === true,
       isTrigger: this.detectTrigger(description),
-      isWebhook: description.webhooks?.length > 0,
-      operations: isDeclarative ? this.extractOperations(description.routing) : this.extractProgrammaticOperations(description),
+      isWebhook: desc.webhooks?.length > 0,
+      operations: isDeclarative ? this.extractOperations(desc.routing) : this.extractProgrammaticOperations(desc),
       version: this.extractVersion(nodeClass),
-      isVersioned: isVersioned || this.isVersionedNode(nodeClass) || Array.isArray(description.version) || description.defaultVersion !== undefined
+      isVersioned: isVersioned || this.isVersionedNode(nodeClass) || Array.isArray(desc.version) || desc.defaultVersion !== undefined
     };
   }
   
-  private detectTrigger(description: any): boolean {
+  private detectTrigger(description: INodeTypeBaseDescription | INodeTypeDescription): boolean {
     // Primary check: group includes 'trigger'
     if (description.group && Array.isArray(description.group)) {
       if (description.group.includes('trigger')) {
         return true;
       }
     }
-    
+
+    // Strategic any assertion for properties that only exist on INodeTypeDescription
+    const desc = description as any;
+
     // Fallback checks for edge cases
-    return description.polling === true || 
-           description.trigger === true ||
-           description.eventTrigger === true ||
+    return desc.polling === true ||
+           desc.trigger === true ||
+           desc.eventTrigger === true ||
            description.name?.toLowerCase().includes('trigger');
   }
 
@@ -186,48 +217,109 @@ export class SimpleParser {
     return operations;
   }
 
-  private extractVersion(nodeClass: any): string {
+  /**
+   * Extracts the version from a node class.
+   *
+   * Priority Chain (same as node-parser.ts):
+   * 1. Instance currentVersion (VersionedNodeType's computed property)
+   * 2. Instance description.defaultVersion (explicit default)
+   * 3. Instance nodeVersions (fallback to max available version)
+   * 4. Instance description.version (simple versioning)
+   * 5. Class-level properties (if instantiation fails)
+   * 6. Default to "1"
+   *
+   * Critical Fix (v2.17.4): Removed check for non-existent instance.baseDescription.defaultVersion
+   * which caused AI Agent and other VersionedNodeType nodes to return wrong versions.
+   *
+   * @param nodeClass - The node class or instance to extract version from
+   * @returns The version as a string
+   */
+  private extractVersion(nodeClass: NodeClass): string {
     // Try to get version from instance first
     try {
       const instance = typeof nodeClass === 'function' ? new nodeClass() : nodeClass;
-      
-      // Check instance baseDescription
-      if (instance?.baseDescription?.defaultVersion) {
-        return instance.baseDescription.defaultVersion.toString();
+      // Strategic any assertion for instance properties
+      const inst = instance as any;
+
+      // PRIORITY 1: Check currentVersion (what VersionedNodeType actually uses)
+      // For VersionedNodeType, currentVersion = defaultVersion ?? max(nodeVersions)
+      if (inst?.currentVersion !== undefined) {
+        return inst.currentVersion.toString();
       }
-      
-      // Check instance description version
-      if (instance?.description?.version) {
-        return instance.description.version.toString();
+
+      // PRIORITY 2: Handle instance-level description.defaultVersion
+      // VersionedNodeType stores baseDescription as 'description', not 'baseDescription'
+      if (inst?.description?.defaultVersion) {
+        return inst.description.defaultVersion.toString();
+      }
+
+      // PRIORITY 3: Handle instance-level nodeVersions (fallback to max)
+      if (inst?.nodeVersions) {
+        const versions = Object.keys(inst.nodeVersions).map(Number);
+        if (versions.length > 0) {
+          const maxVersion = Math.max(...versions);
+          if (!isNaN(maxVersion)) {
+            return maxVersion.toString();
+          }
+        }
+      }
+
+      // PRIORITY 4: Check instance description version
+      if (inst?.description?.version) {
+        return inst.description.version.toString();
       }
     } catch (e) {
       // Ignore instantiation errors
     }
-    
-    // Check class-level properties
-    if (nodeClass.baseDescription?.defaultVersion) {
-      return nodeClass.baseDescription.defaultVersion.toString();
+
+    // PRIORITY 5: Check class-level properties (if instantiation failed)
+    // Strategic any assertion for class-level properties
+    const nodeClassAny = nodeClass as any;
+    if (nodeClassAny.description?.defaultVersion) {
+      return nodeClassAny.description.defaultVersion.toString();
     }
-    
-    return nodeClass.description?.version || '1';
+
+    if (nodeClassAny.nodeVersions) {
+      const versions = Object.keys(nodeClassAny.nodeVersions).map(Number);
+      if (versions.length > 0) {
+        const maxVersion = Math.max(...versions);
+        if (!isNaN(maxVersion)) {
+          return maxVersion.toString();
+        }
+      }
+    }
+
+    // PRIORITY 6: Default to version 1
+    return nodeClassAny.description?.version || '1';
   }
 
-  private isVersionedNode(nodeClass: any): boolean {
-    // Check for VersionedNodeType pattern
-    if (nodeClass.baseDescription && nodeClass.nodeVersions) {
+  private isVersionedNode(nodeClass: NodeClass): boolean {
+    // Strategic any assertion for class-level properties
+    const nodeClassAny = nodeClass as any;
+
+    // Check for VersionedNodeType pattern at class level
+    if (nodeClassAny.baseDescription && nodeClassAny.nodeVersions) {
       return true;
     }
-    
+
     // Check for inline versioning pattern (like Code node)
     try {
       const instance = typeof nodeClass === 'function' ? new nodeClass() : nodeClass;
-      const description = instance.description || {};
-      
+      // Strategic any assertion for instance properties
+      const inst = instance as any;
+
+      // Check for VersionedNodeType pattern at instance level
+      if (inst.baseDescription && inst.nodeVersions) {
+        return true;
+      }
+
+      const description = inst.description || {};
+
       // If version is an array, it's versioned
       if (Array.isArray(description.version)) {
         return true;
       }
-      
+
       // If it has defaultVersion, it's likely versioned
       if (description.defaultVersion !== undefined) {
         return true;
@@ -235,7 +327,7 @@ export class SimpleParser {
     } catch (e) {
       // Ignore instantiation errors
     }
-    
+
     return false;
   }
 }

src/scripts/fetch-templates.ts

@@ -417,12 +417,28 @@ async function generateTemplateMetadata(db: any, service: TemplateService) {
       } catch (error) {
         console.warn(`Failed to parse workflow for template ${t.id}:`, error);
       }
-      
+
+      // Parse nodes_used safely
+      let nodes: string[] = [];
+      try {
+        if (t.nodes_used) {
+          nodes = JSON.parse(t.nodes_used);
+          // Ensure it's an array
+          if (!Array.isArray(nodes)) {
+            console.warn(`Template ${t.id} has invalid nodes_used (not an array), using empty array`);
+            nodes = [];
+          }
+        }
+      } catch (error) {
+        console.warn(`Failed to parse nodes_used for template ${t.id}:`, error);
+        nodes = [];
+      }
+
       return {
         templateId: t.id,
         name: t.name,
         description: t.description,
-        nodes: JSON.parse(t.nodes_used),
+        nodes: nodes,
         workflow
       };
     });

src/scripts/rebuild.ts

@@ -167,29 +167,81 @@ async function rebuild() {
 
 function validateDatabase(repository: NodeRepository): { passed: boolean; issues: string[] } {
   const issues = [];
-  
-  // Check critical nodes
-  const criticalNodes = ['nodes-base.httpRequest', 'nodes-base.code', 'nodes-base.webhook', 'nodes-base.slack'];
-  
-  for (const nodeType of criticalNodes) {
-    const node = repository.getNode(nodeType);
-    
-    if (!node) {
-      issues.push(`Critical node ${nodeType} not found`);
-      continue;
+
+  try {
+    const db = (repository as any).db;
+
+    // CRITICAL: Check if database has any nodes at all
+    const nodeCount = db.prepare('SELECT COUNT(*) as count FROM nodes').get() as { count: number };
+    if (nodeCount.count === 0) {
+      issues.push('CRITICAL: Database is empty - no nodes found! Rebuild failed or was interrupted.');
+      return { passed: false, issues };
     }
-    
-    if (node.properties.length === 0) {
-      issues.push(`Node ${nodeType} has no properties`);
+
+    // Check minimum expected node count (should have at least 500 nodes from both packages)
+    if (nodeCount.count < 500) {
+      issues.push(`WARNING: Only ${nodeCount.count} nodes found - expected at least 500 (both n8n packages)`);
     }
+
+    // Check critical nodes
+    const criticalNodes = ['nodes-base.httpRequest', 'nodes-base.code', 'nodes-base.webhook', 'nodes-base.slack'];
+
+    for (const nodeType of criticalNodes) {
+      const node = repository.getNode(nodeType);
+
+      if (!node) {
+        issues.push(`Critical node ${nodeType} not found`);
+        continue;
+      }
+
+      if (node.properties.length === 0) {
+        issues.push(`Node ${nodeType} has no properties`);
+      }
+    }
+
+    // Check AI tools
+    const aiTools = repository.getAITools();
+    if (aiTools.length === 0) {
+      issues.push('No AI tools found - check detection logic');
+    }
+
+    // Check FTS5 table existence and population
+    const ftsTableCheck = db.prepare(`
+      SELECT name FROM sqlite_master
+      WHERE type='table' AND name='nodes_fts'
+    `).get();
+
+    if (!ftsTableCheck) {
+      issues.push('CRITICAL: FTS5 table (nodes_fts) does not exist - searches will fail or be very slow');
+    } else {
+      // Check if FTS5 table is properly populated
+      const ftsCount = db.prepare('SELECT COUNT(*) as count FROM nodes_fts').get() as { count: number };
+
+      if (ftsCount.count === 0) {
+        issues.push('CRITICAL: FTS5 index is empty - searches will return zero results');
+      } else if (nodeCount.count !== ftsCount.count) {
+        issues.push(`FTS5 index out of sync: ${nodeCount.count} nodes but ${ftsCount.count} FTS5 entries`);
+      }
+
+      // Verify critical nodes are searchable via FTS5
+      const searchableNodes = ['webhook', 'merge', 'split'];
+      for (const searchTerm of searchableNodes) {
+        const searchResult = db.prepare(`
+          SELECT COUNT(*) as count FROM nodes_fts
+          WHERE nodes_fts MATCH ?
+        `).get(searchTerm);
+
+        if (searchResult.count === 0) {
+          issues.push(`CRITICAL: Search for "${searchTerm}" returns zero results in FTS5 index`);
+        }
+      }
+    }
+  } catch (error) {
+    // Catch any validation errors
+    const errorMessage = (error as Error).message;
+    issues.push(`Validation error: ${errorMessage}`);
   }
-  
-  // Check AI tools
-  const aiTools = repository.getAITools();
-  if (aiTools.length === 0) {
-    issues.push('No AI tools found - check detection logic');
-  }
-  
+
   return {
     passed: issues.length === 0,
     issues

src/scripts/seed-canonical-ai-examples.ts

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+/**
+ * Seed canonical AI tool examples into the database
+ *
+ * These hand-crafted examples demonstrate best practices for critical AI tools
+ * that are missing from the template database.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { createDatabaseAdapter } from '../database/database-adapter';
+import { logger } from '../utils/logger';
+
+interface CanonicalExample {
+  name: string;
+  use_case: string;
+  complexity: 'simple' | 'medium' | 'complex';
+  parameters: Record<string, any>;
+  credentials?: Record<string, any>;
+  connections?: Record<string, any>;
+  notes: string;
+}
+
+interface CanonicalToolExamples {
+  node_type: string;
+  display_name: string;
+  examples: CanonicalExample[];
+}
+
+interface CanonicalExamplesFile {
+  description: string;
+  version: string;
+  examples: CanonicalToolExamples[];
+}
+
+async function seedCanonicalExamples() {
+  try {
+    // Load canonical examples file
+    const examplesPath = path.join(__dirname, '../data/canonical-ai-tool-examples.json');
+    const examplesData = fs.readFileSync(examplesPath, 'utf-8');
+    const canonicalExamples: CanonicalExamplesFile = JSON.parse(examplesData);
+
+    logger.info('Loading canonical AI tool examples', {
+      version: canonicalExamples.version,
+      tools: canonicalExamples.examples.length
+    });
+
+    // Initialize database
+    const db = await createDatabaseAdapter('./data/nodes.db');
+
+    // First, ensure we have placeholder templates for canonical examples
+    const templateStmt = db.prepare(`
+      INSERT OR IGNORE INTO templates (
+        id,
+        workflow_id,
+        name,
+        description,
+        views,
+        created_at,
+        updated_at
+      ) VALUES (?, ?, ?, ?, ?, datetime('now'), datetime('now'))
+    `);
+
+    // Create one placeholder template for canonical examples
+    const canonicalTemplateId = -1000;
+    templateStmt.run(
+      canonicalTemplateId,
+      canonicalTemplateId, // workflow_id must be unique
+      'Canonical AI Tool Examples',
+      'Hand-crafted examples demonstrating best practices for AI tools',
+      99999 // High view count
+    );
+
+    // Prepare insert statement for node configs
+    const stmt = db.prepare(`
+      INSERT OR REPLACE 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 (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+
+    let totalInserted = 0;
+
+    // Seed each tool's examples
+    for (const toolExamples of canonicalExamples.examples) {
+      const { node_type, display_name, examples } = toolExamples;
+
+      logger.info(`Seeding examples for ${display_name}`, {
+        nodeType: node_type,
+        exampleCount: examples.length
+      });
+
+      for (let i = 0; i < examples.length; i++) {
+        const example = examples[i];
+
+        // All canonical examples use the same template ID
+        const templateId = canonicalTemplateId;
+        const templateName = `Canonical: ${display_name} - ${example.name}`;
+
+        // Check for expressions in parameters
+        const paramsStr = JSON.stringify(example.parameters);
+        const hasExpressions = paramsStr.includes('={{') || paramsStr.includes('$json') || paramsStr.includes('$node') ? 1 : 0;
+
+        // Insert into database
+        stmt.run(
+          node_type,
+          templateId,
+          templateName,
+          99999, // High view count for canonical examples
+          example.name,
+          JSON.stringify(example.parameters),
+          example.credentials ? JSON.stringify(example.credentials) : null,
+          example.credentials ? 1 : 0,
+          hasExpressions,
+          example.complexity,
+          example.use_case
+        );
+
+        totalInserted++;
+        logger.info(`  ✓ Seeded: ${example.name}`, {
+          complexity: example.complexity,
+          hasCredentials: !!example.credentials,
+          hasExpressions: hasExpressions === 1
+        });
+      }
+    }
+
+    db.close();
+
+    logger.info('Canonical examples seeding complete', {
+      totalExamples: totalInserted,
+      tools: canonicalExamples.examples.length
+    });
+
+    console.log('\n✅ Successfully seeded', totalInserted, 'canonical AI tool examples');
+    console.log('\nExamples are now available via:');
+    console.log('  • search_nodes({query: "HTTP Request Tool", includeExamples: true})');
+    console.log('  • get_node_essentials({nodeType: "nodes-langchain.toolCode", includeExamples: true})');
+
+  } catch (error) {
+    logger.error('Failed to seed canonical examples', { error });
+    console.error('❌ Error:', error);
+    process.exit(1);
+  }
+}
+
+// Run if called directly
+if (require.main === module) {
+  seedCanonicalExamples().catch(console.error);
+}
+
+export { seedCanonicalExamples };

src/services/ai-node-validator.ts

@@ -0,0 +1,634 @@
+/**
+ * AI Node Validator
+ *
+ * Implements validation logic for AI Agent, Chat Trigger, and Basic LLM Chain nodes
+ * from docs/FINAL_AI_VALIDATION_SPEC.md
+ *
+ * Key Features:
+ * - Reverse connection mapping (AI connections flow TO the consumer)
+ * - AI Agent comprehensive validation (prompt types, fallback models, streaming mode)
+ * - Chat Trigger validation (streaming mode constraints)
+ * - Integration with AI tool validators
+ */
+
+import { NodeTypeNormalizer } from '../utils/node-type-normalizer';
+import {
+  WorkflowNode,
+  WorkflowJson,
+  ReverseConnection,
+  ValidationIssue,
+  isAIToolSubNode,
+  validateAIToolSubNode
+} from './ai-tool-validators';
+
+// Re-export types for test files
+export type {
+  WorkflowNode,
+  WorkflowJson,
+  ReverseConnection,
+  ValidationIssue
+} from './ai-tool-validators';
+
+// Validation constants
+const MIN_SYSTEM_MESSAGE_LENGTH = 20;
+const MAX_ITERATIONS_WARNING_THRESHOLD = 50;
+
+/**
+ * AI Connection Types
+ * From spec lines 551-596
+ */
+export const AI_CONNECTION_TYPES = [
+  'ai_languageModel',
+  'ai_memory',
+  'ai_tool',
+  'ai_embedding',
+  'ai_vectorStore',
+  'ai_document',
+  'ai_textSplitter',
+  'ai_outputParser'
+] as const;
+
+/**
+ * Build Reverse Connection Map
+ *
+ * CRITICAL: AI connections flow TO the consumer node (reversed from standard n8n pattern)
+ * This utility maps which nodes connect TO each node, essential for AI validation.
+ *
+ * From spec lines 551-596
+ *
+ * @example
+ * Standard n8n: [Source] --main--> [Target]
+ * workflow.connections["Source"]["main"] = [[{node: "Target", ...}]]
+ *
+ * AI pattern: [Language Model] --ai_languageModel--> [AI Agent]
+ * workflow.connections["Language Model"]["ai_languageModel"] = [[{node: "AI Agent", ...}]]
+ *
+ * Reverse map: reverseMap.get("AI Agent") = [{sourceName: "Language Model", type: "ai_languageModel", ...}]
+ */
+export function buildReverseConnectionMap(
+  workflow: WorkflowJson
+): Map<string, ReverseConnection[]> {
+  const map = new Map<string, ReverseConnection[]>();
+
+  // Iterate through all connections
+  for (const [sourceName, outputs] of Object.entries(workflow.connections)) {
+    // Validate source name is not empty
+    if (!sourceName || typeof sourceName !== 'string' || sourceName.trim() === '') {
+      continue;
+    }
+
+    if (!outputs || typeof outputs !== 'object') continue;
+
+    // Iterate through all output types (main, error, ai_tool, ai_languageModel, etc.)
+    for (const [outputType, connections] of Object.entries(outputs)) {
+      if (!Array.isArray(connections)) continue;
+
+      // Flatten nested arrays and process each connection
+      const connArray = connections.flat().filter(c => c);
+
+      for (const conn of connArray) {
+        if (!conn || !conn.node) continue;
+
+        // Validate target node name is not empty
+        if (typeof conn.node !== 'string' || conn.node.trim() === '') {
+          continue;
+        }
+
+        // Initialize array for target node if not exists
+        if (!map.has(conn.node)) {
+          map.set(conn.node, []);
+        }
+
+        // Add reverse connection entry
+        map.get(conn.node)!.push({
+          sourceName: sourceName,
+          sourceType: outputType,
+          type: outputType,
+          index: conn.index ?? 0
+        });
+      }
+    }
+  }
+
+  return map;
+}
+
+/**
+ * Get AI connections TO a specific node
+ */
+export function getAIConnections(
+  nodeName: string,
+  reverseConnections: Map<string, ReverseConnection[]>,
+  connectionType?: string
+): ReverseConnection[] {
+  const incoming = reverseConnections.get(nodeName) || [];
+
+  if (connectionType) {
+    return incoming.filter(c => c.type === connectionType);
+  }
+
+  return incoming.filter(c => AI_CONNECTION_TYPES.includes(c.type as any));
+}
+
+/**
+ * Validate AI Agent Node
+ * From spec lines 3-549
+ *
+ * Validates:
+ * - Language model connections (1 or 2 if fallback)
+ * - Output parser connection + hasOutputParser flag
+ * - Prompt type configuration (auto vs define)
+ * - System message recommendations
+ * - Streaming mode constraints (CRITICAL)
+ * - Memory connections (0-1)
+ * - Tool connections
+ * - maxIterations validation
+ */
+export function validateAIAgent(
+  node: WorkflowNode,
+  reverseConnections: Map<string, ReverseConnection[]>,
+  workflow: WorkflowJson
+): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+  const incoming = reverseConnections.get(node.name) || [];
+
+  // 1. Validate language model connections (REQUIRED: 1 or 2 if fallback)
+  const languageModelConnections = incoming.filter(c => c.type === 'ai_languageModel');
+
+  if (languageModelConnections.length === 0) {
+    issues.push({
+      severity: 'error',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `AI Agent "${node.name}" requires an ai_languageModel connection. Connect a language model node (e.g., OpenAI Chat Model, Anthropic Chat Model).`,
+      code: 'MISSING_LANGUAGE_MODEL'
+    });
+  } else if (languageModelConnections.length > 2) {
+    issues.push({
+      severity: 'error',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `AI Agent "${node.name}" has ${languageModelConnections.length} ai_languageModel connections. Maximum is 2 (for fallback model support).`,
+      code: 'TOO_MANY_LANGUAGE_MODELS'
+    });
+  } else if (languageModelConnections.length === 2) {
+    // Check if fallback is enabled
+    if (!node.parameters.needsFallback) {
+      issues.push({
+        severity: 'warning',
+        nodeId: node.id,
+        nodeName: node.name,
+        message: `AI Agent "${node.name}" has 2 language models but needsFallback is not enabled. Set needsFallback=true or remove the second model.`
+      });
+    }
+  } else if (languageModelConnections.length === 1 && node.parameters.needsFallback === true) {
+    issues.push({
+      severity: 'error',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `AI Agent "${node.name}" has needsFallback=true but only 1 language model connected. Connect a second model for fallback or disable needsFallback.`,
+      code: 'FALLBACK_MISSING_SECOND_MODEL'
+    });
+  }
+
+  // 2. Validate output parser configuration
+  const outputParserConnections = incoming.filter(c => c.type === 'ai_outputParser');
+
+  if (node.parameters.hasOutputParser === true) {
+    if (outputParserConnections.length === 0) {
+      issues.push({
+        severity: 'error',
+        nodeId: node.id,
+        nodeName: node.name,
+        message: `AI Agent "${node.name}" has hasOutputParser=true but no ai_outputParser connection. Connect an output parser or set hasOutputParser=false.`,
+        code: 'MISSING_OUTPUT_PARSER'
+      });
+    }
+  } else if (outputParserConnections.length > 0) {
+    issues.push({
+      severity: 'warning',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `AI Agent "${node.name}" has an output parser connected but hasOutputParser is not true. Set hasOutputParser=true to enable output parsing.`
+    });
+  }
+
+  if (outputParserConnections.length > 1) {
+    issues.push({
+      severity: 'error',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `AI Agent "${node.name}" has ${outputParserConnections.length} output parsers. Only 1 is allowed.`,
+      code: 'MULTIPLE_OUTPUT_PARSERS'
+    });
+  }
+
+  // 3. Validate prompt type configuration
+  if (node.parameters.promptType === 'define') {
+    if (!node.parameters.text || node.parameters.text.trim() === '') {
+      issues.push({
+        severity: 'error',
+        nodeId: node.id,
+        nodeName: node.name,
+        message: `AI Agent "${node.name}" has promptType="define" but the text field is empty. Provide a custom prompt or switch to promptType="auto".`,
+        code: 'MISSING_PROMPT_TEXT'
+      });
+    }
+  }
+
+  // 4. Check system message (RECOMMENDED)
+  if (!node.parameters.systemMessage) {
+    issues.push({
+      severity: 'info',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `AI Agent "${node.name}" has no systemMessage. Consider adding one to define the agent's role, capabilities, and constraints.`
+    });
+  } else if (node.parameters.systemMessage.trim().length < MIN_SYSTEM_MESSAGE_LENGTH) {
+    issues.push({
+      severity: 'info',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `AI Agent "${node.name}" systemMessage is very short (minimum ${MIN_SYSTEM_MESSAGE_LENGTH} characters recommended). Provide more detail about the agent's role and capabilities.`
+    });
+  }
+
+  // 5. Validate streaming mode constraints (CRITICAL)
+  // From spec lines 753-879: AI Agent with streaming MUST NOT have main output connections
+  const isStreamingTarget = checkIfStreamingTarget(node, workflow, reverseConnections);
+  const hasOwnStreamingEnabled = node.parameters?.options?.streamResponse === true;
+
+  if (isStreamingTarget || hasOwnStreamingEnabled) {
+    // Check if AI Agent has any main output connections
+    const agentMainOutput = workflow.connections[node.name]?.main;
+    if (agentMainOutput && agentMainOutput.flat().some((c: any) => c)) {
+      const streamSource = isStreamingTarget
+        ? 'connected from Chat Trigger with responseMode="streaming"'
+        : 'has streamResponse=true in options';
+      issues.push({
+        severity: 'error',
+        nodeId: node.id,
+        nodeName: node.name,
+        message: `AI Agent "${node.name}" is in streaming mode (${streamSource}) but has outgoing main connections. Remove all main output connections - streaming responses flow back through the Chat Trigger.`,
+        code: 'STREAMING_WITH_MAIN_OUTPUT'
+      });
+    }
+  }
+
+  // 6. Validate memory connections (0-1 allowed)
+  const memoryConnections = incoming.filter(c => c.type === 'ai_memory');
+
+  if (memoryConnections.length > 1) {
+    issues.push({
+      severity: 'error',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `AI Agent "${node.name}" has ${memoryConnections.length} ai_memory connections. Only 1 memory is allowed.`,
+      code: 'MULTIPLE_MEMORY_CONNECTIONS'
+    });
+  }
+
+  // 7. Validate tool connections
+  const toolConnections = incoming.filter(c => c.type === 'ai_tool');
+
+  if (toolConnections.length === 0) {
+    issues.push({
+      severity: 'info',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `AI Agent "${node.name}" has no ai_tool connections. Consider adding tools to enhance the agent's capabilities.`
+    });
+  }
+
+  // 8. Validate maxIterations if specified
+  if (node.parameters.maxIterations !== undefined) {
+    if (typeof node.parameters.maxIterations !== 'number') {
+      issues.push({
+        severity: 'error',
+        nodeId: node.id,
+        nodeName: node.name,
+        message: `AI Agent "${node.name}" has invalid maxIterations type. Must be a number.`,
+        code: 'INVALID_MAX_ITERATIONS_TYPE'
+      });
+    } else if (node.parameters.maxIterations < 1) {
+      issues.push({
+        severity: 'error',
+        nodeId: node.id,
+        nodeName: node.name,
+        message: `AI Agent "${node.name}" has maxIterations=${node.parameters.maxIterations}. Must be at least 1.`,
+        code: 'MAX_ITERATIONS_TOO_LOW'
+      });
+    } else if (node.parameters.maxIterations > MAX_ITERATIONS_WARNING_THRESHOLD) {
+      issues.push({
+        severity: 'warning',
+        nodeId: node.id,
+        nodeName: node.name,
+        message: `AI Agent "${node.name}" has maxIterations=${node.parameters.maxIterations}. Very high iteration counts (>${MAX_ITERATIONS_WARNING_THRESHOLD}) may cause long execution times and high costs.`
+      });
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * Check if AI Agent is a streaming target
+ * Helper function to determine if an AI Agent is receiving streaming input from Chat Trigger
+ */
+function checkIfStreamingTarget(
+  node: WorkflowNode,
+  workflow: WorkflowJson,
+  reverseConnections: Map<string, ReverseConnection[]>
+): boolean {
+  const incoming = reverseConnections.get(node.name) || [];
+
+  // Check if any incoming main connection is from a Chat Trigger with streaming enabled
+  const mainConnections = incoming.filter(c => c.type === 'main');
+
+  for (const conn of mainConnections) {
+    const sourceNode = workflow.nodes.find(n => n.name === conn.sourceName);
+    if (!sourceNode) continue;
+
+    const normalizedType = NodeTypeNormalizer.normalizeToFullForm(sourceNode.type);
+    if (normalizedType === 'nodes-langchain.chatTrigger') {
+      const responseMode = sourceNode.parameters?.options?.responseMode || 'lastNode';
+      if (responseMode === 'streaming') {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Validate Chat Trigger Node
+ * From spec lines 753-879
+ *
+ * Critical validations:
+ * - responseMode="streaming" requires AI Agent target
+ * - AI Agent with streaming MUST NOT have main output connections
+ * - responseMode="lastNode" validation
+ */
+export function validateChatTrigger(
+  node: WorkflowNode,
+  workflow: WorkflowJson,
+  reverseConnections: Map<string, ReverseConnection[]>
+): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  const responseMode = node.parameters?.options?.responseMode || 'lastNode';
+
+  // Get outgoing main connections from Chat Trigger
+  const outgoingMain = workflow.connections[node.name]?.main;
+  if (!outgoingMain || outgoingMain.length === 0 || !outgoingMain[0] || outgoingMain[0].length === 0) {
+    issues.push({
+      severity: 'error',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `Chat Trigger "${node.name}" has no outgoing connections. Connect it to an AI Agent or workflow.`,
+      code: 'MISSING_CONNECTIONS'
+    });
+    return issues;
+  }
+
+  const firstConnection = outgoingMain[0][0];
+  if (!firstConnection) {
+    return issues;
+  }
+
+  const targetNode = workflow.nodes.find(n => n.name === firstConnection.node);
+  if (!targetNode) {
+    issues.push({
+      severity: 'error',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `Chat Trigger "${node.name}" connects to non-existent node "${firstConnection.node}".`,
+      code: 'INVALID_TARGET_NODE'
+    });
+    return issues;
+  }
+
+  const targetType = NodeTypeNormalizer.normalizeToFullForm(targetNode.type);
+
+  // Validate streaming mode
+  if (responseMode === 'streaming') {
+    // CRITICAL: Streaming mode only works with AI Agent
+    if (targetType !== 'nodes-langchain.agent') {
+      issues.push({
+        severity: 'error',
+        nodeId: node.id,
+        nodeName: node.name,
+        message: `Chat Trigger "${node.name}" has responseMode="streaming" but connects to "${targetNode.name}" (${targetType}). Streaming mode only works with AI Agent. Change responseMode to "lastNode" or connect to an AI Agent.`,
+        code: 'STREAMING_WRONG_TARGET'
+      });
+    } else {
+      // CRITICAL: Check AI Agent has NO main output connections
+      const agentMainOutput = workflow.connections[targetNode.name]?.main;
+      if (agentMainOutput && agentMainOutput.flat().some((c: any) => c)) {
+        issues.push({
+          severity: 'error',
+          nodeId: targetNode.id,
+          nodeName: targetNode.name,
+          message: `AI Agent "${targetNode.name}" is in streaming mode but has outgoing main connections. In streaming mode, the AI Agent must NOT have main output connections - responses stream back through the Chat Trigger.`,
+          code: 'STREAMING_AGENT_HAS_OUTPUT'
+        });
+      }
+    }
+  }
+
+  // Validate lastNode mode
+  if (responseMode === 'lastNode') {
+    // lastNode mode requires a workflow that ends somewhere
+    // Just informational - this is the default and works with any workflow
+    if (targetType === 'nodes-langchain.agent') {
+      issues.push({
+        severity: 'info',
+        nodeId: node.id,
+        nodeName: node.name,
+        message: `Chat Trigger "${node.name}" uses responseMode="lastNode" with AI Agent. Consider using responseMode="streaming" for better user experience with real-time responses.`
+      });
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * Validate Basic LLM Chain Node
+ * From spec - simplified AI chain without agent loop
+ *
+ * Similar to AI Agent but simpler:
+ * - Requires exactly 1 language model
+ * - Can have 0-1 memory
+ * - No tools (not an agent)
+ * - No fallback model support
+ */
+export function validateBasicLLMChain(
+  node: WorkflowNode,
+  reverseConnections: Map<string, ReverseConnection[]>
+): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+  const incoming = reverseConnections.get(node.name) || [];
+
+  // 1. Validate language model connection (REQUIRED: exactly 1)
+  const languageModelConnections = incoming.filter(c => c.type === 'ai_languageModel');
+
+  if (languageModelConnections.length === 0) {
+    issues.push({
+      severity: 'error',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `Basic LLM Chain "${node.name}" requires an ai_languageModel connection. Connect a language model node.`,
+      code: 'MISSING_LANGUAGE_MODEL'
+    });
+  } else if (languageModelConnections.length > 1) {
+    issues.push({
+      severity: 'error',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `Basic LLM Chain "${node.name}" has ${languageModelConnections.length} ai_languageModel connections. Basic LLM Chain only supports 1 language model (no fallback).`,
+      code: 'MULTIPLE_LANGUAGE_MODELS'
+    });
+  }
+
+  // 2. Validate memory connections (0-1 allowed)
+  const memoryConnections = incoming.filter(c => c.type === 'ai_memory');
+
+  if (memoryConnections.length > 1) {
+    issues.push({
+      severity: 'error',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `Basic LLM Chain "${node.name}" has ${memoryConnections.length} ai_memory connections. Only 1 memory is allowed.`,
+      code: 'MULTIPLE_MEMORY_CONNECTIONS'
+    });
+  }
+
+  // 3. Check for tool connections (not supported)
+  const toolConnections = incoming.filter(c => c.type === 'ai_tool');
+
+  if (toolConnections.length > 0) {
+    issues.push({
+      severity: 'error',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `Basic LLM Chain "${node.name}" has ai_tool connections. Basic LLM Chain does not support tools. Use AI Agent if you need tool support.`,
+      code: 'TOOLS_NOT_SUPPORTED'
+    });
+  }
+
+  // 4. Validate prompt configuration
+  if (node.parameters.promptType === 'define') {
+    if (!node.parameters.text || node.parameters.text.trim() === '') {
+      issues.push({
+        severity: 'error',
+        nodeId: node.id,
+        nodeName: node.name,
+        message: `Basic LLM Chain "${node.name}" has promptType="define" but the text field is empty.`,
+        code: 'MISSING_PROMPT_TEXT'
+      });
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * Validate all AI-specific nodes in a workflow
+ *
+ * This is the main entry point called by WorkflowValidator
+ */
+export function validateAISpecificNodes(
+  workflow: WorkflowJson
+): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  // Build reverse connection map (critical for AI validation)
+  const reverseConnectionMap = buildReverseConnectionMap(workflow);
+
+  for (const node of workflow.nodes) {
+    if (node.disabled) continue;
+
+    const normalizedType = NodeTypeNormalizer.normalizeToFullForm(node.type);
+
+    // Validate AI Agent nodes
+    if (normalizedType === 'nodes-langchain.agent') {
+      const nodeIssues = validateAIAgent(node, reverseConnectionMap, workflow);
+      issues.push(...nodeIssues);
+    }
+
+    // Validate Chat Trigger nodes
+    if (normalizedType === 'nodes-langchain.chatTrigger') {
+      const nodeIssues = validateChatTrigger(node, workflow, reverseConnectionMap);
+      issues.push(...nodeIssues);
+    }
+
+    // Validate Basic LLM Chain nodes
+    if (normalizedType === 'nodes-langchain.chainLlm') {
+      const nodeIssues = validateBasicLLMChain(node, reverseConnectionMap);
+      issues.push(...nodeIssues);
+    }
+
+    // Validate AI tool sub-nodes (13 types)
+    if (isAIToolSubNode(normalizedType)) {
+      const nodeIssues = validateAIToolSubNode(
+        node,
+        normalizedType,
+        reverseConnectionMap,
+        workflow
+      );
+      issues.push(...nodeIssues);
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * Check if a workflow contains any AI nodes
+ * Useful for skipping AI validation when not needed
+ */
+export function hasAINodes(workflow: WorkflowJson): boolean {
+  const aiNodeTypes = [
+    'nodes-langchain.agent',
+    'nodes-langchain.chatTrigger',
+    'nodes-langchain.chainLlm',
+  ];
+
+  return workflow.nodes.some(node => {
+    const normalized = NodeTypeNormalizer.normalizeToFullForm(node.type);
+    return aiNodeTypes.includes(normalized) || isAIToolSubNode(normalized);
+  });
+}
+
+/**
+ * Helper: Get AI node type category
+ */
+export function getAINodeCategory(nodeType: string): string | null {
+  const normalized = NodeTypeNormalizer.normalizeToFullForm(nodeType);
+
+  if (normalized === 'nodes-langchain.agent') return 'AI Agent';
+  if (normalized === 'nodes-langchain.chatTrigger') return 'Chat Trigger';
+  if (normalized === 'nodes-langchain.chainLlm') return 'Basic LLM Chain';
+  if (isAIToolSubNode(normalized)) return 'AI Tool';
+
+  // Check for AI component nodes
+  if (normalized.startsWith('nodes-langchain.')) {
+    if (normalized.includes('openAi') || normalized.includes('anthropic') || normalized.includes('googleGemini')) {
+      return 'Language Model';
+    }
+    if (normalized.includes('memory') || normalized.includes('buffer')) {
+      return 'Memory';
+    }
+    if (normalized.includes('vectorStore') || normalized.includes('pinecone') || normalized.includes('qdrant')) {
+      return 'Vector Store';
+    }
+    if (normalized.includes('embedding')) {
+      return 'Embeddings';
+    }
+    return 'AI Component';
+  }
+
+  return null;
+}

src/services/ai-tool-validators.ts

@@ -0,0 +1,607 @@
+/**
+ * AI Tool Sub-Node Validators
+ *
+ * Implements validation logic for all 13 AI tool sub-nodes from
+ * docs/FINAL_AI_VALIDATION_SPEC.md
+ *
+ * Each validator checks configuration requirements, connections, and
+ * parameters specific to that tool type.
+ */
+
+import { NodeTypeNormalizer } from '../utils/node-type-normalizer';
+
+// Validation constants
+const MIN_DESCRIPTION_LENGTH_SHORT = 10;
+const MIN_DESCRIPTION_LENGTH_MEDIUM = 15;
+const MIN_DESCRIPTION_LENGTH_LONG = 20;
+const MAX_ITERATIONS_WARNING_THRESHOLD = 50;
+const MAX_TOPK_WARNING_THRESHOLD = 20;
+
+export interface WorkflowNode {
+  id: string;
+  name: string;
+  type: string;
+  position: [number, number];
+  parameters: any;
+  credentials?: any;
+  disabled?: boolean;
+  typeVersion?: number;
+}
+
+export interface WorkflowJson {
+  name?: string;
+  nodes: WorkflowNode[];
+  connections: Record<string, any>;
+  settings?: any;
+}
+
+export interface ReverseConnection {
+  sourceName: string;
+  sourceType: string;
+  type: string;  // main, ai_tool, ai_languageModel, etc.
+  index: number;
+}
+
+export interface ValidationIssue {
+  severity: 'error' | 'warning' | 'info';
+  nodeId?: string;
+  nodeName?: string;
+  message: string;
+  code?: string;
+}
+
+/**
+ * 1. HTTP Request Tool Validator
+ * From spec lines 883-1123
+ */
+export function validateHTTPRequestTool(node: WorkflowNode): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  // 1. Check toolDescription (REQUIRED)
+  if (!node.parameters.toolDescription) {
+    issues.push({
+      severity: 'error',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `HTTP Request Tool "${node.name}" has no toolDescription. Add a clear description to help the LLM know when to use this API.`,
+      code: 'MISSING_TOOL_DESCRIPTION'
+    });
+  } else if (node.parameters.toolDescription.trim().length < MIN_DESCRIPTION_LENGTH_MEDIUM) {
+    issues.push({
+      severity: 'warning',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `HTTP Request Tool "${node.name}" toolDescription is too short (minimum ${MIN_DESCRIPTION_LENGTH_MEDIUM} characters). Explain what API this calls and when to use it.`
+    });
+  }
+
+  // 2. Check URL (REQUIRED)
+  if (!node.parameters.url) {
+    issues.push({
+      severity: 'error',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `HTTP Request Tool "${node.name}" has no URL. Add the API endpoint URL.`,
+      code: 'MISSING_URL'
+    });
+  } else {
+    // Validate URL protocol (must be http or https)
+    try {
+      const urlObj = new URL(node.parameters.url);
+      if (urlObj.protocol !== 'http:' && urlObj.protocol !== 'https:') {
+        issues.push({
+          severity: 'error',
+          nodeId: node.id,
+          nodeName: node.name,
+          message: `HTTP Request Tool "${node.name}" has invalid URL protocol "${urlObj.protocol}". Use http:// or https:// only.`,
+          code: 'INVALID_URL_PROTOCOL'
+        });
+      }
+    } catch (e) {
+      // URL parsing failed - invalid format
+      // Only warn if it's not an n8n expression
+      if (!node.parameters.url.includes('{{')) {
+        issues.push({
+          severity: 'warning',
+          nodeId: node.id,
+          nodeName: node.name,
+          message: `HTTP Request Tool "${node.name}" has potentially invalid URL format. Ensure it's a valid URL or n8n expression.`
+        });
+      }
+    }
+  }
+
+  // 3. Validate placeholders match definitions
+  if (node.parameters.url || node.parameters.body || node.parameters.headers) {
+    const placeholderRegex = /\{([^}]+)\}/g;
+    const placeholders = new Set<string>();
+
+    // Extract placeholders from URL, body, headers
+    [node.parameters.url, node.parameters.body, JSON.stringify(node.parameters.headers || {})].forEach(text => {
+      if (text) {
+        let match;
+        while ((match = placeholderRegex.exec(text)) !== null) {
+          placeholders.add(match[1]);
+        }
+      }
+    });
+
+    // If placeholders exist in URL/body/headers
+    if (placeholders.size > 0) {
+      const definitions = node.parameters.placeholderDefinitions?.values || [];
+      const definedNames = new Set(definitions.map((d: any) => d.name));
+
+      // If no placeholderDefinitions at all, warn
+      if (!node.parameters.placeholderDefinitions) {
+        issues.push({
+          severity: 'warning',
+          nodeId: node.id,
+          nodeName: node.name,
+          message: `HTTP Request Tool "${node.name}" uses placeholders but has no placeholderDefinitions. Add definitions to describe the expected inputs.`
+        });
+      } else {
+        // Has placeholderDefinitions, check each placeholder
+        for (const placeholder of placeholders) {
+          if (!definedNames.has(placeholder)) {
+            issues.push({
+              severity: 'error',
+              nodeId: node.id,
+              nodeName: node.name,
+              message: `HTTP Request Tool "${node.name}" Placeholder "${placeholder}" in URL but it's not defined in placeholderDefinitions.`,
+              code: 'UNDEFINED_PLACEHOLDER'
+            });
+          }
+        }
+
+        // Check for defined but unused placeholders
+        for (const def of definitions) {
+          if (!placeholders.has(def.name)) {
+            issues.push({
+              severity: 'warning',
+              nodeId: node.id,
+              nodeName: node.name,
+              message: `HTTP Request Tool "${node.name}" defines placeholder "${def.name}" but doesn't use it.`
+            });
+          }
+        }
+      }
+    }
+  }
+
+  // 4. Validate authentication
+  if (node.parameters.authentication === 'predefinedCredentialType' &&
+      (!node.credentials || Object.keys(node.credentials).length === 0)) {
+    issues.push({
+      severity: 'error',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `HTTP Request Tool "${node.name}" requires credentials but none are configured.`,
+      code: 'MISSING_CREDENTIALS'
+    });
+  }
+
+  // 5. Validate HTTP method
+  const validMethods = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS'];
+  if (node.parameters.method && !validMethods.includes(node.parameters.method.toUpperCase())) {
+    issues.push({
+      severity: 'error',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `HTTP Request Tool "${node.name}" has invalid HTTP method "${node.parameters.method}". Use one of: ${validMethods.join(', ')}.`,
+      code: 'INVALID_HTTP_METHOD'
+    });
+  }
+
+  // 6. Validate body for POST/PUT/PATCH
+  if (['POST', 'PUT', 'PATCH'].includes(node.parameters.method?.toUpperCase())) {
+    if (!node.parameters.body && !node.parameters.jsonBody) {
+      issues.push({
+        severity: 'warning',
+        nodeId: node.id,
+        nodeName: node.name,
+        message: `HTTP Request Tool "${node.name}" uses ${node.parameters.method} but has no body. Consider adding a body or using GET instead.`
+      });
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * 2. Code Tool Validator
+ * From spec lines 1125-1393
+ */
+export function validateCodeTool(node: WorkflowNode): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  // 1. Check toolDescription (REQUIRED)
+  if (!node.parameters.toolDescription) {
+    issues.push({
+      severity: 'error',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `Code Tool "${node.name}" has no toolDescription. Add one to help the LLM understand the tool's purpose.`,
+      code: 'MISSING_TOOL_DESCRIPTION'
+    });
+  }
+
+  // 2. Check jsCode exists (REQUIRED)
+  if (!node.parameters.jsCode || node.parameters.jsCode.trim().length === 0) {
+    issues.push({
+      severity: 'error',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `Code Tool "${node.name}" code is empty. Add the JavaScript code to execute.`,
+      code: 'MISSING_CODE'
+    });
+  }
+
+  // 3. Recommend input/output schema
+  if (!node.parameters.inputSchema && !node.parameters.specifyInputSchema) {
+    issues.push({
+      severity: 'warning',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `Code Tool "${node.name}" has no input schema. Consider adding one to validate LLM inputs.`
+    });
+  }
+
+  return issues;
+}
+
+/**
+ * 3. Vector Store Tool Validator
+ * From spec lines 1395-1620
+ */
+export function validateVectorStoreTool(
+  node: WorkflowNode,
+  reverseConnections: Map<string, ReverseConnection[]>,
+  workflow: WorkflowJson
+): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  // 1. Check toolDescription (REQUIRED)
+  if (!node.parameters.toolDescription) {
+    issues.push({
+      severity: 'error',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `Vector Store Tool "${node.name}" has no toolDescription. Add one to explain what data it searches.`,
+      code: 'MISSING_TOOL_DESCRIPTION'
+    });
+  }
+
+  // 2. Validate topK parameter if specified
+  if (node.parameters.topK !== undefined) {
+    if (typeof node.parameters.topK !== 'number' || node.parameters.topK < 1) {
+      issues.push({
+        severity: 'error',
+        nodeId: node.id,
+        nodeName: node.name,
+        message: `Vector Store Tool "${node.name}" has invalid topK value. Must be a positive number.`,
+        code: 'INVALID_TOPK'
+      });
+    } else if (node.parameters.topK > MAX_TOPK_WARNING_THRESHOLD) {
+      issues.push({
+        severity: 'warning',
+        nodeId: node.id,
+        nodeName: node.name,
+        message: `Vector Store Tool "${node.name}" has topK=${node.parameters.topK}. Large values (>${MAX_TOPK_WARNING_THRESHOLD}) may overwhelm the LLM context. Consider reducing to 10 or less.`
+      });
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * 4. Workflow Tool Validator
+ * From spec lines 1622-1831 (already complete in spec)
+ */
+export function validateWorkflowTool(node: WorkflowNode, reverseConnections?: Map<string, ReverseConnection[]>): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  // 1. Check toolDescription (REQUIRED)
+  if (!node.parameters.toolDescription) {
+    issues.push({
+      severity: 'error',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `Workflow Tool "${node.name}" has no toolDescription. Add one to help the LLM know when to use this tool.`,
+      code: 'MISSING_TOOL_DESCRIPTION'
+    });
+  }
+
+  // 2. Check workflowId (REQUIRED)
+  if (!node.parameters.workflowId) {
+    issues.push({
+      severity: 'error',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `Workflow Tool "${node.name}" has no workflowId. Select a workflow to execute.`,
+      code: 'MISSING_WORKFLOW_ID'
+    });
+  }
+
+  return issues;
+}
+
+/**
+ * 5. AI Agent Tool Validator
+ * From spec lines 1882-2122
+ */
+export function validateAIAgentTool(
+  node: WorkflowNode,
+  reverseConnections: Map<string, ReverseConnection[]>
+): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  // 1. Check toolDescription (REQUIRED)
+  if (!node.parameters.toolDescription) {
+    issues.push({
+      severity: 'error',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `AI Agent Tool "${node.name}" has no toolDescription. Add one to help the LLM know when to use this tool.`,
+      code: 'MISSING_TOOL_DESCRIPTION'
+    });
+  }
+
+  // 2. Validate maxIterations if specified
+  if (node.parameters.maxIterations !== undefined) {
+    if (typeof node.parameters.maxIterations !== 'number' || node.parameters.maxIterations < 1) {
+      issues.push({
+        severity: 'error',
+        nodeId: node.id,
+        nodeName: node.name,
+        message: `AI Agent Tool "${node.name}" has invalid maxIterations. Must be a positive number.`,
+        code: 'INVALID_MAX_ITERATIONS'
+      });
+    } else if (node.parameters.maxIterations > MAX_ITERATIONS_WARNING_THRESHOLD) {
+      issues.push({
+        severity: 'warning',
+        nodeId: node.id,
+        nodeName: node.name,
+        message: `AI Agent Tool "${node.name}" has maxIterations=${node.parameters.maxIterations}. Large values (>${MAX_ITERATIONS_WARNING_THRESHOLD}) may lead to long execution times.`
+      });
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * 6. MCP Client Tool Validator
+ * From spec lines 2124-2534 (already complete in spec)
+ */
+export function validateMCPClientTool(node: WorkflowNode): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  // 1. Check toolDescription (REQUIRED)
+  if (!node.parameters.toolDescription) {
+    issues.push({
+      severity: 'error',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `MCP Client Tool "${node.name}" has no toolDescription. Add one to help the LLM know when to use this tool.`,
+      code: 'MISSING_TOOL_DESCRIPTION'
+    });
+  }
+
+  // 2. Check serverUrl (REQUIRED)
+  if (!node.parameters.serverUrl) {
+    issues.push({
+      severity: 'error',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `MCP Client Tool "${node.name}" has no serverUrl. Configure the MCP server URL.`,
+      code: 'MISSING_SERVER_URL'
+    });
+  }
+
+  return issues;
+}
+
+/**
+ * 7-8. Simple Tools (Calculator, Think) Validators
+ * From spec lines 1868-2009
+ */
+export function validateCalculatorTool(node: WorkflowNode): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  // Calculator Tool has a built-in description and is self-explanatory
+  // toolDescription is optional - no validation needed
+  return issues;
+}
+
+export function validateThinkTool(node: WorkflowNode): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  // Think Tool has a built-in description and is self-explanatory
+  // toolDescription is optional - no validation needed
+  return issues;
+}
+
+/**
+ * 9-12. Search Tools Validators
+ * From spec lines 1833-2139
+ */
+export function validateSerpApiTool(node: WorkflowNode): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  // 1. Check toolDescription (REQUIRED)
+  if (!node.parameters.toolDescription) {
+    issues.push({
+      severity: 'error',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `SerpApi Tool "${node.name}" has no toolDescription. Add one to explain when to use Google search.`,
+      code: 'MISSING_TOOL_DESCRIPTION'
+    });
+  }
+
+  // 2. Check credentials (RECOMMENDED)
+  if (!node.credentials || !node.credentials.serpApiApi) {
+    issues.push({
+      severity: 'warning',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `SerpApi Tool "${node.name}" requires SerpApi credentials. Configure your API key.`
+    });
+  }
+
+  return issues;
+}
+
+export function validateWikipediaTool(node: WorkflowNode): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  // 1. Check toolDescription (REQUIRED)
+  if (!node.parameters.toolDescription) {
+    issues.push({
+      severity: 'error',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `Wikipedia Tool "${node.name}" has no toolDescription. Add one to explain when to use Wikipedia.`,
+      code: 'MISSING_TOOL_DESCRIPTION'
+    });
+  }
+
+  // 2. Validate language if specified
+  if (node.parameters.language) {
+    const validLanguageCodes = /^[a-z]{2,3}$/;  // ISO 639 codes
+    if (!validLanguageCodes.test(node.parameters.language)) {
+      issues.push({
+        severity: 'warning',
+        nodeId: node.id,
+        nodeName: node.name,
+        message: `Wikipedia Tool "${node.name}" has potentially invalid language code "${node.parameters.language}". Use ISO 639 codes (e.g., "en", "es", "fr").`
+      });
+    }
+  }
+
+  return issues;
+}
+
+export function validateSearXngTool(node: WorkflowNode): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  // 1. Check toolDescription (REQUIRED)
+  if (!node.parameters.toolDescription) {
+    issues.push({
+      severity: 'error',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `SearXNG Tool "${node.name}" has no toolDescription. Add one to explain when to use SearXNG.`,
+      code: 'MISSING_TOOL_DESCRIPTION'
+    });
+  }
+
+  // 2. Check baseUrl (REQUIRED)
+  if (!node.parameters.baseUrl) {
+    issues.push({
+      severity: 'error',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `SearXNG Tool "${node.name}" has no baseUrl. Configure your SearXNG instance URL.`,
+      code: 'MISSING_BASE_URL'
+    });
+  }
+
+  return issues;
+}
+
+export function validateWolframAlphaTool(node: WorkflowNode): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  // 1. Check credentials (REQUIRED)
+  if (!node.credentials || (!node.credentials.wolframAlpha && !node.credentials.wolframAlphaApi)) {
+    issues.push({
+      severity: 'error',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `WolframAlpha Tool "${node.name}" requires Wolfram|Alpha API credentials. Configure your App ID.`,
+      code: 'MISSING_CREDENTIALS'
+    });
+  }
+
+  // 2. Check description (INFO)
+  if (!node.parameters.description && !node.parameters.toolDescription) {
+    issues.push({
+      severity: 'info',
+      nodeId: node.id,
+      nodeName: node.name,
+      message: `WolframAlpha Tool "${node.name}" has no custom description. Add one to explain when to use Wolfram|Alpha for computational queries.`
+    });
+  }
+
+  return issues;
+}
+
+/**
+ * Helper: Map node types to validator functions
+ */
+export const AI_TOOL_VALIDATORS = {
+  'nodes-langchain.toolHttpRequest': validateHTTPRequestTool,
+  'nodes-langchain.toolCode': validateCodeTool,
+  'nodes-langchain.toolVectorStore': validateVectorStoreTool,
+  'nodes-langchain.toolWorkflow': validateWorkflowTool,
+  'nodes-langchain.agentTool': validateAIAgentTool,
+  'nodes-langchain.mcpClientTool': validateMCPClientTool,
+  'nodes-langchain.toolCalculator': validateCalculatorTool,
+  'nodes-langchain.toolThink': validateThinkTool,
+  'nodes-langchain.toolSerpApi': validateSerpApiTool,
+  'nodes-langchain.toolWikipedia': validateWikipediaTool,
+  'nodes-langchain.toolSearXng': validateSearXngTool,
+  'nodes-langchain.toolWolframAlpha': validateWolframAlphaTool,
+} as const;
+
+/**
+ * Check if a node type is an AI tool sub-node
+ */
+export function isAIToolSubNode(nodeType: string): boolean {
+  const normalized = NodeTypeNormalizer.normalizeToFullForm(nodeType);
+  return normalized in AI_TOOL_VALIDATORS;
+}
+
+/**
+ * Validate an AI tool sub-node with the appropriate validator
+ */
+export function validateAIToolSubNode(
+  node: WorkflowNode,
+  nodeType: string,
+  reverseConnections: Map<string, ReverseConnection[]>,
+  workflow: WorkflowJson
+): ValidationIssue[] {
+  const normalized = NodeTypeNormalizer.normalizeToFullForm(nodeType);
+
+  // Route to appropriate validator based on node type
+  switch (normalized) {
+    case 'nodes-langchain.toolHttpRequest':
+      return validateHTTPRequestTool(node);
+    case 'nodes-langchain.toolCode':
+      return validateCodeTool(node);
+    case 'nodes-langchain.toolVectorStore':
+      return validateVectorStoreTool(node, reverseConnections, workflow);
+    case 'nodes-langchain.toolWorkflow':
+      return validateWorkflowTool(node);
+    case 'nodes-langchain.agentTool':
+      return validateAIAgentTool(node, reverseConnections);
+    case 'nodes-langchain.mcpClientTool':
+      return validateMCPClientTool(node);
+    case 'nodes-langchain.toolCalculator':
+      return validateCalculatorTool(node);
+    case 'nodes-langchain.toolThink':
+      return validateThinkTool(node);
+    case 'nodes-langchain.toolSerpApi':
+      return validateSerpApiTool(node);
+    case 'nodes-langchain.toolWikipedia':
+      return validateWikipediaTool(node);
+    case 'nodes-langchain.toolSearXng':
+      return validateSearXngTool(node);
+    case 'nodes-langchain.toolWolframAlpha':
+      return validateWolframAlphaTool(node);
+    default:
+      return [];
+  }
+}

src/services/config-validator.ts

@@ -31,13 +31,19 @@ export interface ValidationWarning {
 }
 
 export class ConfigValidator {
+  /**
+   * UI-only property types that should not be validated as configuration
+   */
+  private static readonly UI_ONLY_TYPES = ['notice', 'callout', 'infoBox', 'info'];
+
   /**
    * Validate a node configuration
    */
   static validate(
-    nodeType: string, 
-    config: Record<string, any>, 
-    properties: any[]
+    nodeType: string,
+    config: Record<string, any>,
+    properties: any[],
+    userProvidedKeys?: Set<string> // NEW: Track user-provided properties to avoid warning about defaults
   ): ValidationResult {
     // Input validation
     if (!config || typeof config !== 'object') {
@@ -46,7 +52,7 @@ export class ConfigValidator {
     if (!properties || !Array.isArray(properties)) {
       throw new TypeError('Properties must be a non-null array');
     }
-    
+
     const errors: ValidationError[] = [];
     const warnings: ValidationWarning[] = [];
     const suggestions: string[] = [];
@@ -69,8 +75,8 @@ export class ConfigValidator {
     this.performNodeSpecificValidation(nodeType, config, errors, warnings, suggestions, autofix);
     
     // Check for common issues
-    this.checkCommonIssues(nodeType, config, properties, warnings, suggestions);
-    
+    this.checkCommonIssues(nodeType, config, properties, warnings, suggestions, userProvidedKeys);
+
     // Security checks
     this.performSecurityChecks(nodeType, config, warnings);
     
@@ -234,8 +240,86 @@ export class ConfigValidator {
           message: `Property '${key}' must be a boolean, got ${typeof value}`,
           fix: `Change ${key} to true or false`
         });
+      } else if (prop.type === 'resourceLocator') {
+        // resourceLocator validation: Used by AI model nodes (OpenAI, Anthropic, etc.)
+        // Must be an object with required properties:
+        //   - mode: string ('list' | 'id' | 'url')
+        //   - value: any (the actual model/resource identifier)
+        // Common mistake: passing string directly instead of object structure
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+          const fixValue = typeof value === 'string' ? value : JSON.stringify(value);
+          errors.push({
+            type: 'invalid_type',
+            property: key,
+            message: `Property '${key}' is a resourceLocator and must be an object with 'mode' and 'value' properties, got ${typeof value}`,
+            fix: `Change ${key} to { mode: "list", value: ${JSON.stringify(fixValue)} } or { mode: "id", value: ${JSON.stringify(fixValue)} }`
+          });
+        } else {
+          // Check required properties
+          if (!value.mode) {
+            errors.push({
+              type: 'missing_required',
+              property: `${key}.mode`,
+              message: `resourceLocator '${key}' is missing required property 'mode'`,
+              fix: `Add mode property: { mode: "list", value: ${JSON.stringify(value.value || '')} }`
+            });
+          } else if (typeof value.mode !== 'string') {
+            errors.push({
+              type: 'invalid_type',
+              property: `${key}.mode`,
+              message: `resourceLocator '${key}.mode' must be a string, got ${typeof value.mode}`,
+              fix: `Set mode to a valid string value`
+            });
+          } else if (prop.modes) {
+            // Schema-based validation: Check if mode exists in the modes definition
+            // In n8n, modes are defined at the top level of resourceLocator properties
+            // Modes can be defined in different ways:
+            // 1. Array of mode objects: [{name: 'list', ...}, {name: 'id', ...}, {name: 'name', ...}]
+            // 2. Object with mode keys: { list: {...}, id: {...}, url: {...}, name: {...} }
+            const modes = prop.modes;
+
+            // Validate modes structure before processing to prevent crashes
+            if (!modes || typeof modes !== 'object') {
+              // Invalid schema structure - skip validation to prevent false positives
+              continue;
+            }
+
+            let allowedModes: string[] = [];
+
+            if (Array.isArray(modes)) {
+              // Array format (most common in n8n): extract name property from each mode object
+              allowedModes = modes
+                .map(m => (typeof m === 'object' && m !== null) ? m.name : m)
+                .filter(m => typeof m === 'string' && m.length > 0);
+            } else {
+              // Object format: extract keys as mode names
+              allowedModes = Object.keys(modes).filter(k => k.length > 0);
+            }
+
+            // Only validate if we successfully extracted modes
+            if (allowedModes.length > 0 && !allowedModes.includes(value.mode)) {
+              errors.push({
+                type: 'invalid_value',
+                property: `${key}.mode`,
+                message: `resourceLocator '${key}.mode' must be one of [${allowedModes.join(', ')}], got '${value.mode}'`,
+                fix: `Change mode to one of: ${allowedModes.join(', ')}`
+              });
+            }
+          }
+          // If no modes defined at property level, skip mode validation
+          // This prevents false positives for nodes with dynamic/runtime-determined modes
+
+          if (value.value === undefined) {
+            errors.push({
+              type: 'missing_required',
+              property: `${key}.value`,
+              message: `resourceLocator '${key}' is missing required property 'value'`,
+              fix: `Add value property to specify the ${prop.displayName || key}`
+            });
+          }
+        }
       }
-      
+
       // Options validation
       if (prop.type === 'options' && prop.options) {
         const validValues = prop.options.map((opt: any) => 
@@ -445,30 +529,48 @@ export class ConfigValidator {
     config: Record<string, any>,
     properties: any[],
     warnings: ValidationWarning[],
-    suggestions: string[]
+    suggestions: string[],
+    userProvidedKeys?: Set<string> // NEW: Only warn about user-provided properties
   ): void {
     // Skip visibility checks for Code nodes as they have simple property structure
     if (nodeType === 'nodes-base.code') {
       // Code nodes don't have complex displayOptions, so skip visibility warnings
       return;
     }
-    
+
     // Check for properties that won't be used
     const visibleProps = properties.filter(p => this.isPropertyVisible(p, config));
     const configuredKeys = Object.keys(config);
-    
+
     for (const key of configuredKeys) {
       // Skip internal properties that are always present
       if (key === '@version' || key.startsWith('_')) {
         continue;
       }
-      
+
+      // CRITICAL FIX: Only warn about properties the user actually provided, not defaults
+      if (userProvidedKeys && !userProvidedKeys.has(key)) {
+        continue; // Skip properties that were added as defaults
+      }
+
+      // Find the property definition
+      const prop = properties.find(p => p.name === key);
+
+      // Skip UI-only properties (notice, callout, etc.) - they're not configuration
+      if (prop && this.UI_ONLY_TYPES.includes(prop.type)) {
+        continue;
+      }
+
+      // Check if property is visible with current settings
       if (!visibleProps.find(p => p.name === key)) {
+        // Get visibility requirements for better error message
+        const visibilityReq = this.getVisibilityRequirement(prop, config);
+
         warnings.push({
           type: 'inefficient',
           property: key,
-          message: `Property '${key}' is configured but won't be used due to current settings`,
-          suggestion: 'Remove this property or adjust other settings to make it visible'
+          message: `Property '${prop?.displayName || key}' won't be used - not visible with current settings`,
+          suggestion: visibilityReq || 'Remove this property or adjust other settings to make it visible'
         });
       }
     }
@@ -517,6 +619,36 @@ export class ConfigValidator {
     }
   }
   
+  /**
+   * Get visibility requirement for a property
+   * Explains what needs to be set for the property to be visible
+   */
+  private static getVisibilityRequirement(prop: any, config: Record<string, any>): string | undefined {
+    if (!prop || !prop.displayOptions?.show) {
+      return undefined;
+    }
+
+    const requirements: string[] = [];
+    for (const [field, values] of Object.entries(prop.displayOptions.show)) {
+      const expectedValues = Array.isArray(values) ? values : [values];
+      const currentValue = config[field];
+
+      // Only include if the current value doesn't match
+      if (!expectedValues.includes(currentValue)) {
+        const valueStr = expectedValues.length === 1
+          ? `"${expectedValues[0]}"`
+          : expectedValues.map(v => `"${v}"`).join(' or ');
+        requirements.push(`${field}=${valueStr}`);
+      }
+    }
+
+    if (requirements.length === 0) {
+      return undefined;
+    }
+
+    return `Requires: ${requirements.join(', ')}`;
+  }
+
   /**
    * Basic JavaScript syntax validation
    */

src/services/enhanced-config-validator.ts

@@ -78,6 +78,9 @@ export class EnhancedConfigValidator extends ConfigValidator {
     // Extract operation context from config
     const operationContext = this.extractOperationContext(config);
 
+    // Extract user-provided keys before applying defaults (CRITICAL FIX for warning system)
+    const userProvidedKeys = new Set(Object.keys(config));
+
     // Filter properties based on mode and operation, and get config with defaults
     const { properties: filteredProperties, configWithDefaults } = this.filterPropertiesByMode(
       properties,
@@ -87,7 +90,8 @@ export class EnhancedConfigValidator extends ConfigValidator {
     );
 
     // Perform base validation on filtered properties with defaults applied
-    const baseResult = super.validate(nodeType, configWithDefaults, filteredProperties);
+    // Pass userProvidedKeys to prevent warnings about default values
+    const baseResult = super.validate(nodeType, configWithDefaults, filteredProperties, userProvidedKeys);
     
     // Enhance the result
     const enhancedResult: EnhancedValidationResult = {
@@ -314,7 +318,11 @@ export class EnhancedConfigValidator extends ConfigValidator {
       case 'nodes-base.mysql':
         NodeSpecificValidators.validateMySQL(context);
         break;
-        
+
+      case 'nodes-base.set':
+        NodeSpecificValidators.validateSet(context);
+        break;
+
       case 'nodes-base.switch':
         this.validateSwitchNodeStructure(config, result);
         break;
@@ -469,22 +477,32 @@ export class EnhancedConfigValidator extends ConfigValidator {
       case 'minimal':
         // Only keep missing required errors
         result.errors = result.errors.filter(e => e.type === 'missing_required');
-        result.warnings = [];
+        // Keep ONLY critical warnings (security and deprecated)
+        result.warnings = result.warnings.filter(w =>
+          w.type === 'security' || w.type === 'deprecated'
+        );
         result.suggestions = [];
         break;
-        
+
       case 'runtime':
         // Keep critical runtime errors only
-        result.errors = result.errors.filter(e => 
-          e.type === 'missing_required' || 
+        result.errors = result.errors.filter(e =>
+          e.type === 'missing_required' ||
           e.type === 'invalid_value' ||
           (e.type === 'invalid_type' && e.message.includes('undefined'))
         );
-        // Keep only security warnings
-        result.warnings = result.warnings.filter(w => w.type === 'security');
+        // Keep security and deprecated warnings, REMOVE property visibility warnings
+        result.warnings = result.warnings.filter(w => {
+          if (w.type === 'security' || w.type === 'deprecated') return true;
+          // FILTER OUT property visibility warnings (too noisy)
+          if (w.type === 'inefficient' && w.message && w.message.includes('not visible')) {
+            return false;
+          }
+          return false;
+        });
         result.suggestions = [];
         break;
-        
+
       case 'strict':
         // Keep everything, add more suggestions
         if (result.warnings.length === 0 && result.errors.length === 0) {
@@ -494,14 +512,28 @@ export class EnhancedConfigValidator extends ConfigValidator {
         // Require error handling for external service nodes
         this.enforceErrorHandlingForProfile(result, profile);
         break;
-        
+
       case 'ai-friendly':
       default:
         // Current behavior - balanced for AI agents
         // Filter out noise but keep helpful warnings
-        result.warnings = result.warnings.filter(w => 
-          w.type !== 'inefficient' || !w.property?.startsWith('_')
-        );
+        result.warnings = result.warnings.filter(w => {
+          // Keep security and deprecated warnings
+          if (w.type === 'security' || w.type === 'deprecated') return true;
+          // Keep missing common properties
+          if (w.type === 'missing_common') return true;
+          // Keep best practice warnings
+          if (w.type === 'best_practice') return true;
+          // FILTER OUT inefficient warnings about property visibility (now fixed at source)
+          if (w.type === 'inefficient' && w.message && w.message.includes('not visible')) {
+            return false; // These are now rare due to userProvidedKeys fix
+          }
+          // Filter out internal property warnings
+          if (w.type === 'inefficient' && w.property?.startsWith('_')) {
+            return false;
+          }
+          return true;
+        });
         // Add error handling suggestions for AI-friendly profile
         this.addErrorHandlingSuggestions(result);
         break;

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

@@ -139,18 +139,44 @@ export function cleanWorkflowForUpdate(workflow: Workflow): Partial<Workflow> {
   // PROBLEM:
   // - Some versions reject updates with settings properties (community forum reports)
   // - Cloud versions REQUIRE settings property to be present (n8n.estyl.team)
-  // - Properties like callerPolicy and executionOrder cause "additional properties" errors
+  // - Properties like callerPolicy cause "additional properties" errors
   //
   // SOLUTION:
-  // - ALWAYS set settings to empty object {}, regardless of whether it exists
+  // - 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)
-  // - Empty object has no "additional properties" to trigger errors (self-hosted)
-  // - n8n API interprets empty settings as "no changes" and preserves existing settings
+  // - 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)
-  cleanedWorkflow.settings = {};
+
+  // 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-specific-validators.ts

@@ -269,13 +269,15 @@ export class NodeSpecificValidators {
   
   private static validateGoogleSheetsAppend(context: NodeValidationContext): void {
     const { config, errors, warnings, autofix } = context;
-    
-    if (!config.range) {
+
+    // In Google Sheets v4+, range is only required if NOT using the columns resourceMapper
+    // The columns parameter is a resourceMapper introduced in v4 that handles range automatically
+    if (!config.range && !config.columns) {
       errors.push({
         type: 'missing_required',
         property: 'range',
-        message: 'Range is required for append operation',
-        fix: 'Specify range like "Sheet1!A:B" or "Sheet1!A1:B10"'
+        message: 'Range or columns mapping is required for append operation',
+        fix: 'Specify range like "Sheet1!A:B" OR use columns with mappingMode'
       });
     }
     
@@ -1556,4 +1558,59 @@ export class NodeSpecificValidators {
       });
     }
   }
+
+  /**
+   * Validate Set node configuration
+   */
+  static validateSet(context: NodeValidationContext): void {
+    const { config, errors, warnings } = context;
+
+    // Validate jsonOutput when present (used in JSON mode or when directly setting JSON)
+    if (config.jsonOutput !== undefined && config.jsonOutput !== null && config.jsonOutput !== '') {
+      try {
+        const parsed = JSON.parse(config.jsonOutput);
+
+        // Set node with JSON input expects an OBJECT {}, not an ARRAY []
+        // This is a common mistake that n8n UI catches but our validator should too
+        if (Array.isArray(parsed)) {
+          errors.push({
+            type: 'invalid_value',
+            property: 'jsonOutput',
+            message: 'Set node expects a JSON object {}, not an array []',
+            fix: 'Either wrap array items as object properties: {"items": [...]}, OR use a different approach for multiple items'
+          });
+        }
+
+        // Warn about empty objects
+        if (typeof parsed === 'object' && !Array.isArray(parsed) && Object.keys(parsed).length === 0) {
+          warnings.push({
+            type: 'inefficient',
+            property: 'jsonOutput',
+            message: 'jsonOutput is an empty object - this node will output no data',
+            suggestion: 'Add properties to the object or remove this node if not needed'
+          });
+        }
+      } catch (e) {
+        errors.push({
+          type: 'syntax_error',
+          property: 'jsonOutput',
+          message: `Invalid JSON in jsonOutput: ${e instanceof Error ? e.message : 'Syntax error'}`,
+          fix: 'Ensure jsonOutput contains valid JSON syntax'
+        });
+      }
+    }
+
+    // Validate mode-specific requirements
+    if (config.mode === 'manual') {
+      // In manual mode, at least one field should be defined
+      const hasFields = config.values && Object.keys(config.values).length > 0;
+      if (!hasFields && !config.jsonOutput) {
+        warnings.push({
+          type: 'missing_common',
+          message: 'Set node has no fields configured - will output empty items',
+          suggestion: 'Add fields in the Values section or use JSON mode'
+        });
+      }
+    }
+  }
 }

src/services/universal-expression-validator.ts

@@ -21,8 +21,18 @@ export class UniversalExpressionValidator {
   private static readonly EXPRESSION_PREFIX = '=';
 
   /**
-   * Universal Rule 1: Any field containing {{ }} MUST have = prefix
-   * This is an absolute rule in n8n - no exceptions
+   * Universal Rule 1: Any field containing {{ }} MUST have = prefix to be evaluated
+   * This applies to BOTH pure expressions and mixed content
+   *
+   * Examples:
+   * - "{{ $json.value }}" -> literal text (NOT evaluated)
+   * - "={{ $json.value }}" -> evaluated expression
+   * - "Hello {{ $json.name }}!" -> literal text (NOT evaluated)
+   * - "=Hello {{ $json.name }}!" -> evaluated (expression in mixed content)
+   * - "=https://api.com/{{ $json.id }}/data" -> evaluated (real example from n8n)
+   *
+   * EXCEPTION: Some langchain node fields auto-evaluate without = prefix
+   * (validated separately by AI-specific validators)
    */
   static validateExpressionPrefix(value: any): UniversalValidationResult {
     // Only validate strings
@@ -53,6 +63,10 @@ export class UniversalExpressionValidator {
     const hasPrefix = value.startsWith(this.EXPRESSION_PREFIX);
     const isMixedContent = this.hasMixedContent(value);
 
+    // For langchain nodes, we don't validate expression prefixes
+    // They have AI-specific validators that handle their expression rules
+    // This is checked at the node level, not here
+
     if (!hasPrefix) {
       return {
         isValid: false,

src/services/workflow-diff-engine.ts

@@ -20,7 +20,7 @@ import {
   DisableNodeOperation,
   AddConnectionOperation,
   RemoveConnectionOperation,
-  UpdateConnectionOperation,
+  RewireConnectionOperation,
   UpdateSettingsOperation,
   UpdateNameOperation,
   AddTagOperation,
@@ -223,8 +223,8 @@ export class WorkflowDiffEngine {
         return this.validateAddConnection(workflow, operation);
       case 'removeConnection':
         return this.validateRemoveConnection(workflow, operation);
-      case 'updateConnection':
-        return this.validateUpdateConnection(workflow, operation);
+      case 'rewireConnection':
+        return this.validateRewireConnection(workflow, operation as RewireConnectionOperation);
       case 'updateSettings':
       case 'updateName':
       case 'addTag':
@@ -268,8 +268,8 @@ export class WorkflowDiffEngine {
       case 'removeConnection':
         this.applyRemoveConnection(workflow, operation);
         break;
-      case 'updateConnection':
-        this.applyUpdateConnection(workflow, operation);
+      case 'rewireConnection':
+        this.applyRewireConnection(workflow, operation as RewireConnectionOperation);
         break;
       case 'updateSettings':
         this.applyUpdateSettings(workflow, operation);
@@ -295,10 +295,14 @@ export class WorkflowDiffEngine {
   // Node operation validators
   private validateAddNode(workflow: Workflow, operation: AddNodeOperation): string | null {
     const { node } = operation;
-    
-    // Check if node with same name already exists
-    if (workflow.nodes.some(n => n.name === node.name)) {
-      return `Node with name "${node.name}" already exists`;
+
+    // Check if node with same name already exists (use normalization to prevent collisions)
+    const normalizedNewName = this.normalizeNodeName(node.name);
+    const duplicate = workflow.nodes.find(n =>
+      this.normalizeNodeName(n.name) === normalizedNewName
+    );
+    if (duplicate) {
+      return `Node with name "${node.name}" already exists (normalized name matches existing node "${duplicate.name}")`;
     }
     
     // Validate node type format
@@ -316,7 +320,7 @@ export class WorkflowDiffEngine {
   private validateRemoveNode(workflow: Workflow, operation: RemoveNodeOperation): string | null {
     const node = this.findNode(workflow, operation.nodeId, operation.nodeName);
     if (!node) {
-      return `Node not found: ${operation.nodeId || operation.nodeName}`;
+      return this.formatNodeNotFoundError(workflow, operation.nodeId || operation.nodeName || '', 'removeNode');
     }
     
     // Check if node has connections that would be broken
@@ -339,7 +343,7 @@ export class WorkflowDiffEngine {
   private validateUpdateNode(workflow: Workflow, operation: UpdateNodeOperation): string | null {
     const node = this.findNode(workflow, operation.nodeId, operation.nodeName);
     if (!node) {
-      return `Node not found: ${operation.nodeId || operation.nodeName}`;
+      return this.formatNodeNotFoundError(workflow, operation.nodeId || operation.nodeName || '', 'updateNode');
     }
     return null;
   }
@@ -347,7 +351,7 @@ export class WorkflowDiffEngine {
   private validateMoveNode(workflow: Workflow, operation: MoveNodeOperation): string | null {
     const node = this.findNode(workflow, operation.nodeId, operation.nodeName);
     if (!node) {
-      return `Node not found: ${operation.nodeId || operation.nodeName}`;
+      return this.formatNodeNotFoundError(workflow, operation.nodeId || operation.nodeName || '', 'moveNode');
     }
     return null;
   }
@@ -355,7 +359,8 @@ export class WorkflowDiffEngine {
   private validateToggleNode(workflow: Workflow, operation: EnableNodeOperation | DisableNodeOperation): string | null {
     const node = this.findNode(workflow, operation.nodeId, operation.nodeName);
     if (!node) {
-      return `Node not found: ${operation.nodeId || operation.nodeName}`;
+      const operationType = operation.type === 'enableNode' ? 'enableNode' : 'disableNode';
+      return this.formatNodeNotFoundError(workflow, operation.nodeId || operation.nodeName || '', operationType);
     }
     return null;
   }
@@ -384,12 +389,16 @@ export class WorkflowDiffEngine {
     const targetNode = this.findNode(workflow, operation.target, operation.target);
 
     if (!sourceNode) {
-      const availableNodes = workflow.nodes.map(n => n.name).join(', ');
-      return `Source node not found: "${operation.source}". Available nodes: ${availableNodes}`;
+      const availableNodes = workflow.nodes
+        .map(n => `"${n.name}" (id: ${n.id.substring(0, 8)}...)`)
+        .join(', ');
+      return `Source node not found: "${operation.source}". Available nodes: ${availableNodes}. Tip: Use node ID for names with special characters (apostrophes, quotes).`;
     }
     if (!targetNode) {
-      const availableNodes = workflow.nodes.map(n => n.name).join(', ');
-      return `Target node not found: "${operation.target}". Available nodes: ${availableNodes}`;
+      const availableNodes = workflow.nodes
+        .map(n => `"${n.name}" (id: ${n.id.substring(0, 8)}...)`)
+        .join(', ');
+      return `Target node not found: "${operation.target}". Available nodes: ${availableNodes}. Tip: Use node ID for names with special characters (apostrophes, quotes).`;
     }
 
     // Check if connection already exists
@@ -417,10 +426,16 @@ export class WorkflowDiffEngine {
     const targetNode = this.findNode(workflow, operation.target, operation.target);
 
     if (!sourceNode) {
-      return `Source node not found: ${operation.source}`;
+      const availableNodes = workflow.nodes
+        .map(n => `"${n.name}" (id: ${n.id.substring(0, 8)}...)`)
+        .join(', ');
+      return `Source node not found: "${operation.source}". Available nodes: ${availableNodes}. Tip: Use node ID for names with special characters.`;
     }
     if (!targetNode) {
-      return `Target node not found: ${operation.target}`;
+      const availableNodes = workflow.nodes
+        .map(n => `"${n.name}" (id: ${n.id.substring(0, 8)}...)`)
+        .join(', ');
+      return `Target node not found: "${operation.target}". Available nodes: ${availableNodes}. Tip: Use node ID for names with special characters.`;
     }
 
     const sourceOutput = operation.sourceOutput || 'main';
@@ -440,37 +455,53 @@ export class WorkflowDiffEngine {
     return null;
   }
 
-  private validateUpdateConnection(workflow: Workflow, operation: UpdateConnectionOperation): string | null {
+  private validateRewireConnection(workflow: Workflow, operation: RewireConnectionOperation): string | null {
+    // Validate source node exists
     const sourceNode = this.findNode(workflow, operation.source, operation.source);
-    const targetNode = this.findNode(workflow, operation.target, operation.target);
-    
     if (!sourceNode) {
-      return `Source node not found: ${operation.source}`;
+      const availableNodes = workflow.nodes
+        .map(n => `"${n.name}" (id: ${n.id.substring(0, 8)}...)`)
+        .join(', ');
+      return `Source node not found: "${operation.source}". Available nodes: ${availableNodes}. Tip: Use node ID for names with special characters.`;
     }
-    if (!targetNode) {
-      return `Target node not found: ${operation.target}`;
+
+    // Validate "from" node exists (current target)
+    const fromNode = this.findNode(workflow, operation.from, operation.from);
+    if (!fromNode) {
+      const availableNodes = workflow.nodes
+        .map(n => `"${n.name}" (id: ${n.id.substring(0, 8)}...)`)
+        .join(', ');
+      return `"From" node not found: "${operation.from}". Available nodes: ${availableNodes}. Tip: Use node ID for names with special characters.`;
     }
-    
-    // Check if connection exists to update
-    const existingConnections = workflow.connections[sourceNode.name];
-    if (!existingConnections) {
-      return `No connections found from "${sourceNode.name}"`;
+
+    // Validate "to" node exists (new target)
+    const toNode = this.findNode(workflow, operation.to, operation.to);
+    if (!toNode) {
+      const availableNodes = workflow.nodes
+        .map(n => `"${n.name}" (id: ${n.id.substring(0, 8)}...)`)
+        .join(', ');
+      return `"To" node not found: "${operation.to}". Available nodes: ${availableNodes}. Tip: Use node ID for names with special characters.`;
     }
-    
-    // Check if any connection to target exists
-    let hasConnection = false;
-    Object.values(existingConnections).forEach(outputs => {
-      outputs.forEach(connections => {
-        if (connections.some(c => c.node === targetNode.name)) {
-          hasConnection = true;
-        }
-      });
-    });
-    
+
+    // Resolve smart parameters (branch, case) before validating connections
+    const { sourceOutput, sourceIndex } = this.resolveSmartParameters(workflow, operation);
+
+    // Validate that connection from source to "from" exists at the specific index
+    const connections = workflow.connections[sourceNode.name]?.[sourceOutput];
+    if (!connections) {
+      return `No connections found from "${sourceNode.name}" on output "${sourceOutput}"`;
+    }
+
+    if (!connections[sourceIndex]) {
+      return `No connections found from "${sourceNode.name}" on output "${sourceOutput}" at index ${sourceIndex}`;
+    }
+
+    const hasConnection = connections[sourceIndex].some(c => c.node === fromNode.name);
+
     if (!hasConnection) {
-      return `No connection exists from "${sourceNode.name}" to "${targetNode.name}"`;
+      return `No connection exists from "${sourceNode.name}" to "${fromNode.name}" on output "${sourceOutput}" at index ${sourceIndex}"`;
     }
-    
+
     return null;
   }
 
@@ -564,32 +595,77 @@ export class WorkflowDiffEngine {
     node.disabled = true;
   }
 
+  /**
+   * Resolve smart parameters (branch, case) to technical parameters
+   * Phase 1 UX improvement: Semantic parameters for multi-output nodes
+   */
+  private resolveSmartParameters(
+    workflow: Workflow,
+    operation: AddConnectionOperation | RewireConnectionOperation
+  ): { sourceOutput: string; sourceIndex: number } {
+    const sourceNode = this.findNode(workflow, operation.source, operation.source);
+
+    // Start with explicit values or defaults
+    let sourceOutput = operation.sourceOutput ?? 'main';
+    let sourceIndex = operation.sourceIndex ?? 0;
+
+    // Smart parameter: branch (for IF nodes)
+    // IF nodes use 'main' output with index 0 (true) or 1 (false)
+    if (operation.branch !== undefined && operation.sourceIndex === undefined) {
+      // Only apply if sourceIndex not explicitly set
+      if (sourceNode?.type === 'n8n-nodes-base.if') {
+        sourceIndex = operation.branch === 'true' ? 0 : 1;
+        // sourceOutput remains 'main' (do not change it)
+      }
+    }
+
+    // Smart parameter: case (for Switch nodes)
+    if (operation.case !== undefined && operation.sourceIndex === undefined) {
+      // Only apply if sourceIndex not explicitly set
+      sourceIndex = operation.case;
+    }
+
+    return { sourceOutput, sourceIndex };
+  }
+
   // Connection operation appliers
   private applyAddConnection(workflow: Workflow, operation: AddConnectionOperation): void {
     const sourceNode = this.findNode(workflow, operation.source, operation.source);
     const targetNode = this.findNode(workflow, operation.target, operation.target);
     if (!sourceNode || !targetNode) return;
-    
-    const sourceOutput = operation.sourceOutput || 'main';
-    const targetInput = operation.targetInput || 'main';
-    const sourceIndex = operation.sourceIndex || 0;
-    const targetIndex = operation.targetIndex || 0;
-    
-    // Initialize connections structure if needed
+
+    // Resolve smart parameters (branch, case) to technical parameters
+    const { sourceOutput, sourceIndex } = this.resolveSmartParameters(workflow, operation);
+
+    // Use nullish coalescing to properly handle explicit 0 values
+    const targetInput = operation.targetInput ?? 'main';
+    const targetIndex = operation.targetIndex ?? 0;
+
+    // Initialize source node connections object
     if (!workflow.connections[sourceNode.name]) {
       workflow.connections[sourceNode.name] = {};
     }
+
+    // Initialize output type array
     if (!workflow.connections[sourceNode.name][sourceOutput]) {
       workflow.connections[sourceNode.name][sourceOutput] = [];
     }
-    
-    // Ensure we have array at the source index
-    while (workflow.connections[sourceNode.name][sourceOutput].length <= sourceIndex) {
-      workflow.connections[sourceNode.name][sourceOutput].push([]);
+
+    // Get reference to output array for clarity
+    const outputArray = workflow.connections[sourceNode.name][sourceOutput];
+
+    // Ensure we have connection arrays up to and including the target sourceIndex
+    while (outputArray.length <= sourceIndex) {
+      outputArray.push([]);
     }
-    
-    // Add connection
-    workflow.connections[sourceNode.name][sourceOutput][sourceIndex].push({
+
+    // Defensive: Verify the slot is an array (should always be true after while loop)
+    if (!Array.isArray(outputArray[sourceIndex])) {
+      outputArray[sourceIndex] = [];
+    }
+
+    // Add connection to the correct sourceIndex
+    outputArray[sourceIndex].push({
       node: targetNode.name,
       type: targetInput,
       index: targetIndex
@@ -615,12 +691,14 @@ export class WorkflowDiffEngine {
     workflow.connections[sourceNode.name][sourceOutput] = connections.map(conns =>
       conns.filter(conn => conn.node !== targetNode.name)
     );
-    
-    // Clean up empty arrays
-    workflow.connections[sourceNode.name][sourceOutput] = 
-      workflow.connections[sourceNode.name][sourceOutput].filter(conns => conns.length > 0);
-    
-    if (workflow.connections[sourceNode.name][sourceOutput].length === 0) {
+
+    // Remove trailing empty arrays only (preserve intermediate empty arrays to maintain indices)
+    const outputConnections = workflow.connections[sourceNode.name][sourceOutput];
+    while (outputConnections.length > 0 && outputConnections[outputConnections.length - 1].length === 0) {
+      outputConnections.pop();
+    }
+
+    if (outputConnections.length === 0) {
       delete workflow.connections[sourceNode.name][sourceOutput];
     }
     
@@ -629,24 +707,36 @@ export class WorkflowDiffEngine {
     }
   }
 
-  private applyUpdateConnection(workflow: Workflow, operation: UpdateConnectionOperation): void {
-    // For now, implement as remove + add
+  /**
+   * Rewire a connection from one target to another
+   * This is a semantic wrapper around removeConnection + addConnection
+   * that provides clear intent: "rewire connection from X to Y"
+   *
+   * @param workflow - Workflow to modify
+   * @param operation - Rewire operation specifying source, from, and to
+   */
+  private applyRewireConnection(workflow: Workflow, operation: RewireConnectionOperation): void {
+    // Resolve smart parameters (branch, case) to technical parameters
+    const { sourceOutput, sourceIndex } = this.resolveSmartParameters(workflow, operation);
+
+    // First, remove the old connection (source → from)
     this.applyRemoveConnection(workflow, {
       type: 'removeConnection',
       source: operation.source,
-      target: operation.target,
-      sourceOutput: operation.updates.sourceOutput,
-      targetInput: operation.updates.targetInput
+      target: operation.from,
+      sourceOutput: sourceOutput,
+      targetInput: operation.targetInput
     });
-    
+
+    // Then, add the new connection (source → to)
     this.applyAddConnection(workflow, {
       type: 'addConnection',
       source: operation.source,
-      target: operation.target,
-      sourceOutput: operation.updates.sourceOutput,
-      targetInput: operation.updates.targetInput,
-      sourceIndex: operation.updates.sourceIndex,
-      targetIndex: operation.updates.targetIndex
+      target: operation.to,
+      sourceOutput: sourceOutput,
+      targetInput: operation.targetInput,
+      sourceIndex: sourceIndex,
+      targetIndex: 0 // Default target index for new connection
     });
   }
 
@@ -791,26 +881,96 @@ export class WorkflowDiffEngine {
   }
 
   // Helper methods
+
+  /**
+   * Normalize node names to handle special characters and escaping differences.
+   * Fixes issue #270: apostrophes and other special characters in node names.
+   *
+   * ⚠️ WARNING: Normalization can cause collisions between names that differ only in:
+   * - Leading/trailing whitespace
+   * - Multiple consecutive spaces vs single spaces
+   * - Escaped vs unescaped quotes/backslashes
+   * - Different types of whitespace (tabs, newlines, spaces)
+   *
+   * Examples of names that normalize to the SAME value:
+   * - "Node 'test'" === "Node  'test'" (multiple spaces)
+   * - "Node 'test'" === "Node\t'test'" (tab vs space)
+   * - "Node 'test'" === "Node \\'test\\'" (escaped quotes)
+   * - "Path\\to\\file" === "Path\\\\to\\\\file" (escaped backslashes)
+   *
+   * Best Practice: For node names with special characters, prefer using node IDs
+   * to avoid ambiguity. Use n8n_get_workflow_structure() to get node IDs.
+   *
+   * @param name - The node name to normalize
+   * @returns Normalized node name for safe comparison
+   */
+  private normalizeNodeName(name: string): string {
+    return name
+      .trim()                    // Remove leading/trailing whitespace
+      .replace(/\\\\/g, '\\')    // FIRST: Unescape backslashes: \\ -> \ (must be first to handle multiply-escaped chars)
+      .replace(/\\'/g, "'")      // THEN: Unescape single quotes: \' -> '
+      .replace(/\\"/g, '"')      // THEN: Unescape double quotes: \" -> "
+      .replace(/\s+/g, ' ');     // FINALLY: Normalize all whitespace (spaces, tabs, newlines) to single space
+  }
+
+  /**
+   * Find a node by ID or name in the workflow.
+   * Uses string normalization to handle special characters (Issue #270).
+   *
+   * @param workflow - The workflow to search in
+   * @param nodeId - Optional node ID to search for
+   * @param nodeName - Optional node name to search for
+   * @returns The found node or null
+   */
   private findNode(workflow: Workflow, nodeId?: string, nodeName?: string): WorkflowNode | null {
+    // Try to find by ID first (exact match, no normalization needed for UUIDs)
     if (nodeId) {
       const nodeById = workflow.nodes.find(n => n.id === nodeId);
       if (nodeById) return nodeById;
     }
-    
+
+    // Try to find by name with normalization (handles special characters)
     if (nodeName) {
-      const nodeByName = workflow.nodes.find(n => n.name === nodeName);
+      const normalizedSearch = this.normalizeNodeName(nodeName);
+      const nodeByName = workflow.nodes.find(n =>
+        this.normalizeNodeName(n.name) === normalizedSearch
+      );
       if (nodeByName) return nodeByName;
     }
-    
-    // If nodeId is provided but not found, try treating it as a name
+
+    // Fallback: If nodeId provided but not found, try treating it as a name
+    // This allows operations to work with either IDs or names flexibly
     if (nodeId && !nodeName) {
-      const nodeByName = workflow.nodes.find(n => n.name === nodeId);
+      const normalizedSearch = this.normalizeNodeName(nodeId);
+      const nodeByName = workflow.nodes.find(n =>
+        this.normalizeNodeName(n.name) === normalizedSearch
+      );
       if (nodeByName) return nodeByName;
     }
-    
+
     return null;
   }
 
+  /**
+   * Format a consistent "node not found" error message with helpful context.
+   * Shows available nodes with IDs and tips about using node IDs for special characters.
+   *
+   * @param workflow - The workflow being validated
+   * @param nodeIdentifier - The node ID or name that wasn't found
+   * @param operationType - The operation being performed (e.g., "removeNode", "updateNode")
+   * @returns Formatted error message with available nodes and helpful tips
+   */
+  private formatNodeNotFoundError(
+    workflow: Workflow,
+    nodeIdentifier: string,
+    operationType: string
+  ): string {
+    const availableNodes = workflow.nodes
+      .map(n => `"${n.name}" (id: ${n.id.substring(0, 8)}...)`)
+      .join(', ');
+    return `Node not found for ${operationType}: "${nodeIdentifier}". Available nodes: ${availableNodes}. Tip: Use node ID for names with special characters (apostrophes, quotes).`;
+  }
+
   private setNestedProperty(obj: any, path: string, value: any): void {
     const keys = path.split('.');
     let current = obj;

src/services/workflow-validator.ts

@@ -10,6 +10,7 @@ import { ExpressionFormatValidator } from './expression-format-validator';
 import { NodeSimilarityService, NodeSuggestion } from './node-similarity-service';
 import { NodeTypeNormalizer } from '../utils/node-type-normalizer';
 import { Logger } from '../utils/logger';
+import { validateAISpecificNodes, hasAINodes } from './ai-node-validator';
 const logger = new Logger({ prefix: '[WorkflowValidator]' });
 
 interface WorkflowNode {
@@ -174,9 +175,30 @@ export class WorkflowValidator {
           this.checkWorkflowPatterns(workflow, result, profile);
         }
 
+        // Validate AI-specific nodes (AI Agent, Chat Trigger, AI tools)
+        if (workflow.nodes.length > 0 && hasAINodes(workflow)) {
+          const aiIssues = validateAISpecificNodes(workflow);
+          // Convert AI validation issues to workflow validation format
+          for (const issue of aiIssues) {
+            const validationIssue: ValidationIssue = {
+              type: issue.severity === 'error' ? 'error' : 'warning',
+              nodeId: issue.nodeId,
+              nodeName: issue.nodeName,
+              message: issue.message,
+              details: issue.code ? { code: issue.code } : undefined
+            };
+
+            if (issue.severity === 'error') {
+              result.errors.push(validationIssue);
+            } else {
+              result.warnings.push(validationIssue);
+            }
+          }
+        }
+
         // Add suggestions based on findings
         this.generateSuggestions(workflow, result);
-        
+
         // Add AI-specific recovery suggestions if there are errors
         if (result.errors.length > 0) {
           this.addErrorRecoverySuggestions(result);
@@ -250,13 +272,15 @@ export class WorkflowValidator {
       const normalizedType = NodeTypeNormalizer.normalizeToFullForm(singleNode.type);
       const isWebhook = normalizedType === 'nodes-base.webhook' ||
                        normalizedType === 'nodes-base.webhookTrigger';
-      
-      if (!isWebhook) {
+      const isLangchainNode = normalizedType.startsWith('nodes-langchain.');
+
+      // Langchain nodes can be validated standalone for AI tool purposes
+      if (!isWebhook && !isLangchainNode) {
         result.errors.push({
           type: 'error',
           message: 'Single-node workflows are only valid for webhook endpoints. Add at least one more connected node to create a functional workflow.'
         });
-      } else if (Object.keys(workflow.connections).length === 0) {
+      } else if (isWebhook && Object.keys(workflow.connections).length === 0) {
         result.warnings.push({
           type: 'warning',
           message: 'Webhook node has no connections. Consider adding nodes to process the webhook data.'
@@ -305,8 +329,9 @@ export class WorkflowValidator {
     // Count trigger nodes - normalize type names first
     const triggerNodes = workflow.nodes.filter(n => {
       const normalizedType = NodeTypeNormalizer.normalizeToFullForm(n.type);
-      return normalizedType.toLowerCase().includes('trigger') ||
-             normalizedType.toLowerCase().includes('webhook') ||
+      const lowerType = normalizedType.toLowerCase();
+      return lowerType.includes('trigger') ||
+             (lowerType.includes('webhook') && !lowerType.includes('respond')) ||
              normalizedType === 'nodes-base.start' ||
              normalizedType === 'nodes-base.manualTrigger' ||
              normalizedType === 'nodes-base.formTrigger';
@@ -372,10 +397,11 @@ export class WorkflowValidator {
           node.type = normalizedType;
         }
 
-        // Get node definition using normalized type
+        // Get node definition using normalized type (needed for typeVersion validation)
         const nodeInfo = this.nodeRepository.getNode(normalizedType);
 
         if (!nodeInfo) {
+
           // Use NodeSimilarityService to find suggestions
           const suggestions = await this.similarityService.findSimilarNodes(node.type, 3);
 
@@ -418,7 +444,10 @@ export class WorkflowValidator {
           continue;
         }
 
-        // Validate typeVersion for versioned nodes
+        // Validate typeVersion for ALL versioned nodes (including langchain nodes)
+        // CRITICAL: This MUST run BEFORE the langchain skip below!
+        // Otherwise, langchain nodes with invalid typeVersion (e.g., 99999) would pass validation
+        // but fail at runtime in n8n. This was the bug fixed in v2.17.4.
         if (nodeInfo.isVersioned) {
           // Check if typeVersion is missing
           if (!node.typeVersion) {
@@ -428,14 +457,14 @@ export class WorkflowValidator {
               nodeName: node.name,
               message: `Missing required property 'typeVersion'. Add typeVersion: ${nodeInfo.version || 1}`
             });
-          } 
-          // Check if typeVersion is invalid
-          else if (typeof node.typeVersion !== 'number' || node.typeVersion < 1) {
+          }
+          // Check if typeVersion is invalid (must be non-negative number, version 0 is valid)
+          else if (typeof node.typeVersion !== 'number' || node.typeVersion < 0) {
             result.errors.push({
               type: 'error',
               nodeId: node.id,
               nodeName: node.name,
-              message: `Invalid typeVersion: ${node.typeVersion}. Must be a positive number`
+              message: `Invalid typeVersion: ${node.typeVersion}. Must be a non-negative number`
             });
           }
           // Check if typeVersion is outdated (less than latest)
@@ -458,6 +487,13 @@ export class WorkflowValidator {
           }
         }
 
+        // Skip PARAMETER validation for langchain nodes (but NOT typeVersion validation above!)
+        // Langchain nodes have dedicated AI-specific validators in validateAISpecificNodes()
+        // which handle their unique parameter structures (AI connections, tool ports, etc.)
+        if (normalizedType.startsWith('nodes-langchain.')) {
+          continue;
+        }
+
         // Validate node configuration
         const nodeValidation = this.nodeValidator.validateWithMode(
           node.type,
@@ -930,6 +966,13 @@ export class WorkflowValidator {
     for (const node of workflow.nodes) {
       if (node.disabled || this.isStickyNote(node)) continue;
 
+      // Skip expression validation for langchain nodes
+      // They have AI-specific validators and different expression rules
+      const normalizedType = NodeTypeNormalizer.normalizeToFullForm(node.type);
+      if (normalizedType.startsWith('nodes-langchain.')) {
+        continue;
+      }
+
       // Create expression context
       const context = {
         availableNodes: nodeNames.filter(n => n !== node.name),

src/telemetry/config-manager.ts

@@ -37,12 +37,135 @@ export class TelemetryConfigManager {
 
   /**
    * Generate a deterministic anonymous user ID based on machine characteristics
+   * Uses Docker/cloud-specific method for containerized environments
    */
   private generateUserId(): string {
+    // Use boot_id for all Docker/cloud environments (stable across container updates)
+    if (process.env.IS_DOCKER === 'true' || this.isCloudEnvironment()) {
+      return this.generateDockerStableId();
+    }
+
+    // Local installations use file-based method with hostname
     const machineId = `${hostname()}-${platform()}-${arch()}-${homedir()}`;
     return createHash('sha256').update(machineId).digest('hex').substring(0, 16);
   }
 
+  /**
+   * Generate stable user ID for Docker/cloud environments
+   * Priority: boot_id → combined signals → generic fallback
+   */
+  private generateDockerStableId(): string {
+    // Priority 1: Try boot_id (stable across container recreations)
+    const bootId = this.readBootId();
+    if (bootId) {
+      const fingerprint = `${bootId}-${platform()}-${arch()}`;
+      return createHash('sha256').update(fingerprint).digest('hex').substring(0, 16);
+    }
+
+    // Priority 2: Try combined host signals
+    const combinedFingerprint = this.generateCombinedFingerprint();
+    if (combinedFingerprint) {
+      return combinedFingerprint;
+    }
+
+    // Priority 3: Generic Docker ID (allows aggregate statistics)
+    const genericId = `docker-${platform()}-${arch()}`;
+    return createHash('sha256').update(genericId).digest('hex').substring(0, 16);
+  }
+
+  /**
+   * Read host boot_id from /proc (available in Linux containers)
+   * Returns null if not available or invalid format
+   */
+  private readBootId(): string | null {
+    try {
+      const bootIdPath = '/proc/sys/kernel/random/boot_id';
+
+      if (!existsSync(bootIdPath)) {
+        return null;
+      }
+
+      const bootId = readFileSync(bootIdPath, 'utf-8').trim();
+
+      // Validate UUID format (8-4-4-4-12 hex digits)
+      const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+      if (!uuidRegex.test(bootId)) {
+        return null;
+      }
+
+      return bootId;
+    } catch (error) {
+      // File not readable or other error
+      return null;
+    }
+  }
+
+  /**
+   * Generate fingerprint from combined host signals
+   * Fallback for environments where boot_id is not available
+   */
+  private generateCombinedFingerprint(): string | null {
+    try {
+      const signals: string[] = [];
+
+      // CPU cores (stable)
+      if (existsSync('/proc/cpuinfo')) {
+        const cpuinfo = readFileSync('/proc/cpuinfo', 'utf-8');
+        const cores = (cpuinfo.match(/processor\s*:/g) || []).length;
+        if (cores > 0) {
+          signals.push(`cores:${cores}`);
+        }
+      }
+
+      // Memory (stable)
+      if (existsSync('/proc/meminfo')) {
+        const meminfo = readFileSync('/proc/meminfo', 'utf-8');
+        const totalMatch = meminfo.match(/MemTotal:\s+(\d+)/);
+        if (totalMatch) {
+          signals.push(`mem:${totalMatch[1]}`);
+        }
+      }
+
+      // Kernel version (stable)
+      if (existsSync('/proc/version')) {
+        const version = readFileSync('/proc/version', 'utf-8');
+        const kernelMatch = version.match(/Linux version ([\d.]+)/);
+        if (kernelMatch) {
+          signals.push(`kernel:${kernelMatch[1]}`);
+        }
+      }
+
+      // Platform and arch
+      signals.push(platform(), arch());
+
+      // Need at least 3 signals for reasonable uniqueness
+      if (signals.length < 3) {
+        return null;
+      }
+
+      const fingerprint = signals.join('-');
+      return createHash('sha256').update(fingerprint).digest('hex').substring(0, 16);
+    } catch (error) {
+      return null;
+    }
+  }
+
+  /**
+   * Check if running in a cloud environment
+   */
+  private isCloudEnvironment(): boolean {
+    return !!(
+      process.env.RAILWAY_ENVIRONMENT ||
+      process.env.RENDER ||
+      process.env.FLY_APP_NAME ||
+      process.env.HEROKU_APP_NAME ||
+      process.env.AWS_EXECUTION_ENV ||
+      process.env.KUBERNETES_SERVICE_HOST ||
+      process.env.GOOGLE_CLOUD_PROJECT ||
+      process.env.AZURE_FUNCTIONS_ENVIRONMENT
+    );
+  }
+
   /**
    * Load configuration from disk or create default
    */

src/telemetry/early-error-logger.ts

@@ -0,0 +1,298 @@
+/**
+ * Early Error Logger (v2.18.3)
+ * Captures errors that occur BEFORE the main telemetry system is ready
+ * Uses direct Supabase insert to bypass batching and ensure immediate persistence
+ *
+ * CRITICAL FIXES:
+ * - Singleton pattern to prevent multiple instances
+ * - Defensive initialization (safe defaults before any throwing operation)
+ * - Timeout wrapper for Supabase operations (5s max)
+ * - Shared sanitization utilities (DRY principle)
+ */
+
+import { createClient, SupabaseClient } from '@supabase/supabase-js';
+import { TelemetryConfigManager } from './config-manager';
+import { TELEMETRY_BACKEND } from './telemetry-types';
+import { StartupCheckpoint, isValidCheckpoint, getCheckpointDescription } from './startup-checkpoints';
+import { sanitizeErrorMessageCore } from './error-sanitization-utils';
+import { logger } from '../utils/logger';
+
+/**
+ * Timeout wrapper for async operations
+ * Prevents hanging if Supabase is unreachable
+ */
+async function withTimeout<T>(promise: Promise<T>, timeoutMs: number, operation: string): Promise<T | null> {
+  try {
+    const timeoutPromise = new Promise<T>((_, reject) => {
+      setTimeout(() => reject(new Error(`${operation} timeout after ${timeoutMs}ms`)), timeoutMs);
+    });
+
+    return await Promise.race([promise, timeoutPromise]);
+  } catch (error) {
+    logger.debug(`${operation} failed or timed out:`, error);
+    return null;
+  }
+}
+
+export class EarlyErrorLogger {
+  // Singleton instance
+  private static instance: EarlyErrorLogger | null = null;
+
+  // DEFENSIVE INITIALIZATION: Initialize all fields to safe defaults FIRST
+  // This ensures the object is in a valid state even if initialization fails
+  private enabled: boolean = false;  // Safe default: disabled
+  private supabase: SupabaseClient | null = null;  // Safe default: null
+  private userId: string | null = null;  // Safe default: null
+  private checkpoints: StartupCheckpoint[] = [];
+  private startTime: number = Date.now();
+  private initPromise: Promise<void>;
+
+  /**
+   * Private constructor - use getInstance() instead
+   * Ensures only one instance exists per process
+   */
+  private constructor() {
+    // Kick off async initialization without blocking
+    this.initPromise = this.initialize();
+  }
+
+  /**
+   * Get singleton instance
+   * Safe to call from anywhere - initialization errors won't crash caller
+   */
+  static getInstance(): EarlyErrorLogger {
+    if (!EarlyErrorLogger.instance) {
+      EarlyErrorLogger.instance = new EarlyErrorLogger();
+    }
+    return EarlyErrorLogger.instance;
+  }
+
+  /**
+   * Async initialization logic
+   * Separated from constructor to prevent throwing before safe defaults are set
+   */
+  private async initialize(): Promise<void> {
+    try {
+      // Validate backend configuration before using
+      if (!TELEMETRY_BACKEND.URL || !TELEMETRY_BACKEND.ANON_KEY) {
+        logger.debug('Telemetry backend not configured, early error logger disabled');
+        this.enabled = false;
+        return;
+      }
+
+      // Check if telemetry is disabled by user
+      const configManager = TelemetryConfigManager.getInstance();
+      const isEnabled = configManager.isEnabled();
+
+      if (!isEnabled) {
+        logger.debug('Telemetry disabled by user, early error logger will not send events');
+        this.enabled = false;
+        return;
+      }
+
+      // Initialize Supabase client for direct inserts
+      this.supabase = createClient(
+        TELEMETRY_BACKEND.URL,
+        TELEMETRY_BACKEND.ANON_KEY,
+        {
+          auth: {
+            persistSession: false,
+            autoRefreshToken: false,
+          },
+        }
+      );
+
+      // Get user ID from config manager
+      this.userId = configManager.getUserId();
+
+      // Mark as enabled only after successful initialization
+      this.enabled = true;
+
+      logger.debug('Early error logger initialized successfully');
+    } catch (error) {
+      // Initialization failed - ensure safe state
+      logger.debug('Early error logger initialization failed:', error);
+      this.enabled = false;
+      this.supabase = null;
+      this.userId = null;
+    }
+  }
+
+  /**
+   * Wait for initialization to complete (for testing)
+   * Not needed in production - all methods handle uninitialized state gracefully
+   */
+  async waitForInit(): Promise<void> {
+    await this.initPromise;
+  }
+
+  /**
+   * Log a checkpoint as the server progresses through startup
+   * FIRE-AND-FORGET: Does not block caller (no await needed)
+   */
+  logCheckpoint(checkpoint: StartupCheckpoint): void {
+    if (!this.enabled) {
+      return;
+    }
+
+    try {
+      // Validate checkpoint
+      if (!isValidCheckpoint(checkpoint)) {
+        logger.warn(`Invalid checkpoint: ${checkpoint}`);
+        return;
+      }
+
+      // Add to internal checkpoint list
+      this.checkpoints.push(checkpoint);
+
+      logger.debug(`Checkpoint passed: ${checkpoint} (${getCheckpointDescription(checkpoint)})`);
+    } catch (error) {
+      // Don't throw - we don't want checkpoint logging to crash the server
+      logger.debug('Failed to log checkpoint:', error);
+    }
+  }
+
+  /**
+   * Log a startup error with checkpoint context
+   * This is the main error capture mechanism
+   * FIRE-AND-FORGET: Does not block caller
+   */
+  logStartupError(checkpoint: StartupCheckpoint, error: unknown): void {
+    if (!this.enabled || !this.supabase || !this.userId) {
+      return;
+    }
+
+    // Run async operation without blocking caller
+    this.logStartupErrorAsync(checkpoint, error).catch((logError) => {
+      // Swallow errors - telemetry must never crash the server
+      logger.debug('Failed to log startup error:', logError);
+    });
+  }
+
+  /**
+   * Internal async implementation with timeout wrapper
+   */
+  private async logStartupErrorAsync(checkpoint: StartupCheckpoint, error: unknown): Promise<void> {
+    try {
+      // Sanitize error message using shared utilities (v2.18.3)
+      let errorMessage = 'Unknown error';
+      if (error instanceof Error) {
+        errorMessage = error.message;
+        if (error.stack) {
+          errorMessage = error.stack;
+        }
+      } else if (typeof error === 'string') {
+        errorMessage = error;
+      } else {
+        errorMessage = String(error);
+      }
+
+      const sanitizedError = sanitizeErrorMessageCore(errorMessage);
+
+      // Extract error type if it's an Error object
+      let errorType = 'unknown';
+      if (error instanceof Error) {
+        errorType = error.name || 'Error';
+      } else if (typeof error === 'string') {
+        errorType = 'string_error';
+      }
+
+      // Create startup_error event
+      const event = {
+        user_id: this.userId!,
+        event: 'startup_error',
+        properties: {
+          checkpoint,
+          errorMessage: sanitizedError,
+          errorType,
+          checkpointsPassed: this.checkpoints,
+          checkpointsPassedCount: this.checkpoints.length,
+          startupDuration: Date.now() - this.startTime,
+          platform: process.platform,
+          arch: process.arch,
+          nodeVersion: process.version,
+          isDocker: process.env.IS_DOCKER === 'true',
+        },
+        created_at: new Date().toISOString(),
+      };
+
+      // Direct insert to Supabase with timeout (5s max)
+      const insertOperation = async () => {
+        return await this.supabase!
+          .from('events')
+          .insert(event)
+          .select()
+          .single();
+      };
+
+      const result = await withTimeout(insertOperation(), 5000, 'Startup error insert');
+
+      if (result && 'error' in result && result.error) {
+        logger.debug('Failed to insert startup error event:', result.error);
+      } else if (result) {
+        logger.debug(`Startup error logged for checkpoint: ${checkpoint}`);
+      }
+    } catch (logError) {
+      // Don't throw - telemetry failures should never crash the server
+      logger.debug('Failed to log startup error:', logError);
+    }
+  }
+
+  /**
+   * Log successful startup completion
+   * Called when all checkpoints have been passed
+   * FIRE-AND-FORGET: Does not block caller
+   */
+  logStartupSuccess(checkpoints: StartupCheckpoint[], durationMs: number): void {
+    if (!this.enabled) {
+      return;
+    }
+
+    try {
+      // Store checkpoints for potential session_start enhancement
+      this.checkpoints = checkpoints;
+
+      logger.debug(`Startup successful: ${checkpoints.length} checkpoints passed in ${durationMs}ms`);
+
+      // We don't send a separate event here - this data will be included
+      // in the session_start event sent by the main telemetry system
+    } catch (error) {
+      logger.debug('Failed to log startup success:', error);
+    }
+  }
+
+  /**
+   * Get the list of checkpoints passed so far
+   */
+  getCheckpoints(): StartupCheckpoint[] {
+    return [...this.checkpoints];
+  }
+
+  /**
+   * Get startup duration in milliseconds
+   */
+  getStartupDuration(): number {
+    return Date.now() - this.startTime;
+  }
+
+  /**
+   * Get startup data for inclusion in session_start event
+   */
+  getStartupData(): { durationMs: number; checkpoints: StartupCheckpoint[] } | null {
+    if (!this.enabled) {
+      return null;
+    }
+
+    return {
+      durationMs: this.getStartupDuration(),
+      checkpoints: this.getCheckpoints(),
+    };
+  }
+
+  /**
+   * Check if early logger is enabled
+   */
+  isEnabled(): boolean {
+    return this.enabled && this.supabase !== null && this.userId !== null;
+  }
+}

src/telemetry/error-sanitization-utils.ts

@@ -0,0 +1,75 @@
+/**
+ * Shared Error Sanitization Utilities
+ * Used by both error-sanitizer.ts and event-tracker.ts to avoid code duplication
+ *
+ * Security patterns from v2.15.3 with ReDoS fix from v2.18.3
+ */
+
+import { logger } from '../utils/logger';
+
+/**
+ * Core error message sanitization with security-focused patterns
+ *
+ * Sanitization order (critical for preventing leakage):
+ * 1. Early truncation (ReDoS prevention)
+ * 2. Stack trace limitation
+ * 3. URLs (most encompassing) - fully redact
+ * 4. Specific credentials (AWS, GitHub, JWT, Bearer)
+ * 5. Emails (after URLs)
+ * 6. Long keys and tokens
+ * 7. Generic credential patterns
+ * 8. Final truncation
+ *
+ * @param errorMessage - Raw error message to sanitize
+ * @returns Sanitized error message safe for telemetry
+ */
+export function sanitizeErrorMessageCore(errorMessage: string): string {
+  try {
+    // Early truncate to prevent ReDoS and performance issues
+    const maxLength = 1500;
+    const trimmed = errorMessage.length > maxLength
+      ? errorMessage.substring(0, maxLength)
+      : errorMessage;
+
+    // Handle stack traces - keep only first 3 lines (message + top stack frames)
+    const lines = trimmed.split('\n');
+    let sanitized = lines.slice(0, 3).join('\n');
+
+    // Sanitize sensitive data in correct order to prevent leakage
+
+    // 1. URLs first (most encompassing) - fully redact to prevent path leakage
+    sanitized = sanitized.replace(/https?:\/\/\S+/gi, '[URL]');
+
+    // 2. Specific credential patterns (before generic patterns)
+    sanitized = sanitized
+      .replace(/AKIA[A-Z0-9]{16}/g, '[AWS_KEY]')
+      .replace(/ghp_[a-zA-Z0-9]{36,}/g, '[GITHUB_TOKEN]')
+      .replace(/eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+/g, '[JWT]')
+      .replace(/Bearer\s+[^\s]+/gi, 'Bearer [TOKEN]');
+
+    // 3. Emails (after URLs to avoid partial matches)
+    sanitized = sanitized.replace(/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g, '[EMAIL]');
+
+    // 4. Long keys and quoted tokens
+    sanitized = sanitized
+      .replace(/\b[a-zA-Z0-9_-]{32,}\b/g, '[KEY]')
+      .replace(/(['"])[a-zA-Z0-9_-]{16,}\1/g, '$1[TOKEN]$1');
+
+    // 5. Generic credential patterns (after specific ones to avoid conflicts)
+    // FIX (v2.18.3): Replaced negative lookbehind with simpler regex to prevent ReDoS
+    sanitized = sanitized
+      .replace(/password\s*[=:]\s*\S+/gi, 'password=[REDACTED]')
+      .replace(/api[_-]?key\s*[=:]\s*\S+/gi, 'api_key=[REDACTED]')
+      .replace(/\btoken\s*[=:]\s*[^\s;,)]+/gi, 'token=[REDACTED]'); // Simplified regex (no negative lookbehind)
+
+    // Final truncate to 500 chars
+    if (sanitized.length > 500) {
+      sanitized = sanitized.substring(0, 500) + '...';
+    }
+
+    return sanitized;
+  } catch (error) {
+    logger.debug('Error message sanitization failed:', error);
+    return '[SANITIZATION_FAILED]';
+  }
+}

src/telemetry/error-sanitizer.ts

@@ -0,0 +1,65 @@
+/**
+ * Error Sanitizer for Startup Errors (v2.18.3)
+ * Extracts and sanitizes error messages with security-focused patterns
+ * Now uses shared sanitization utilities to avoid code duplication
+ */
+
+import { logger } from '../utils/logger';
+import { sanitizeErrorMessageCore } from './error-sanitization-utils';
+
+/**
+ * Extract error message from unknown error type
+ * Safely handles Error objects, strings, and other types
+ */
+export function extractErrorMessage(error: unknown): string {
+  try {
+    if (error instanceof Error) {
+      // Include stack trace if available (will be truncated later)
+      return error.stack || error.message || 'Unknown error';
+    }
+
+    if (typeof error === 'string') {
+      return error;
+    }
+
+    if (error && typeof error === 'object') {
+      // Try to extract message from object
+      const errorObj = error as any;
+      if (errorObj.message) {
+        return String(errorObj.message);
+      }
+      if (errorObj.error) {
+        return String(errorObj.error);
+      }
+      // Fall back to JSON stringify with truncation
+      try {
+        return JSON.stringify(error).substring(0, 500);
+      } catch {
+        return 'Error object (unstringifiable)';
+      }
+    }
+
+    return String(error);
+  } catch (extractError) {
+    logger.debug('Error during message extraction:', extractError);
+    return 'Error message extraction failed';
+  }
+}
+
+/**
+ * Sanitize startup error message to remove sensitive data
+ * Now uses shared sanitization core from error-sanitization-utils.ts (v2.18.3)
+ * This eliminates code duplication and the ReDoS vulnerability
+ */
+export function sanitizeStartupError(errorMessage: string): string {
+  return sanitizeErrorMessageCore(errorMessage);
+}
+
+/**
+ * Combined operation: Extract and sanitize error message
+ * This is the main entry point for startup error processing
+ */
+export function processStartupError(error: unknown): string {
+  const message = extractErrorMessage(error);
+  return sanitizeStartupError(message);
+}

src/telemetry/event-tracker.ts

@@ -1,6 +1,7 @@
 /**
- * Event Tracker for Telemetry
+ * Event Tracker for Telemetry (v2.18.3)
  * Handles all event tracking logic extracted from TelemetryManager
+ * Now uses shared sanitization utilities to avoid code duplication
  */
 
 import { TelemetryEvent, WorkflowTelemetry } from './telemetry-types';
@@ -11,6 +12,7 @@ import { TelemetryError, TelemetryErrorType } from './telemetry-error';
 import { logger } from '../utils/logger';
 import { existsSync, readFileSync } from 'fs';
 import { resolve } from 'path';
+import { sanitizeErrorMessageCore } from './error-sanitization-utils';
 
 export class TelemetryEventTracker {
   private rateLimiter: TelemetryRateLimiter;
@@ -136,6 +138,9 @@ export class TelemetryEventTracker {
       context: this.sanitizeContext(context),
       tool: toolName ? toolName.replace(/[^a-zA-Z0-9_-]/g, '_') : undefined,
       error: errorMessage ? this.sanitizeErrorMessage(errorMessage) : undefined,
+      // Add environment context for better error analysis
+      mcpMode: process.env.MCP_MODE || 'stdio',
+      platform: process.platform
     }, false); // Skip rate limiting for errors
   }
 
@@ -165,9 +170,13 @@ export class TelemetryEventTracker {
   }
 
   /**
-   * Track session start
+   * Track session start with optional startup tracking data (v2.18.2)
    */
-  trackSessionStart(): void {
+  trackSessionStart(startupData?: {
+    durationMs?: number;
+    checkpoints?: string[];
+    errorCount?: number;
+  }): void {
     if (!this.isEnabled()) return;
 
     this.trackEvent('session_start', {
@@ -175,9 +184,44 @@ export class TelemetryEventTracker {
       platform: process.platform,
       arch: process.arch,
       nodeVersion: process.version,
+      isDocker: process.env.IS_DOCKER === 'true',
+      cloudPlatform: this.detectCloudPlatform(),
+      mcpMode: process.env.MCP_MODE || 'stdio',
+      // NEW: Startup tracking fields (v2.18.2)
+      startupDurationMs: startupData?.durationMs,
+      checkpointsPassed: startupData?.checkpoints,
+      startupErrorCount: startupData?.errorCount || 0,
     });
   }
 
+  /**
+   * Track startup completion (v2.18.2)
+   * Called after first successful tool call to confirm server is functional
+   */
+  trackStartupComplete(): void {
+    if (!this.isEnabled()) return;
+
+    this.trackEvent('startup_completed', {
+      version: this.getPackageVersion(),
+    });
+  }
+
+  /**
+   * Detect cloud platform from environment variables
+   * Returns platform name or null if not in cloud
+   */
+  private detectCloudPlatform(): string | null {
+    if (process.env.RAILWAY_ENVIRONMENT) return 'railway';
+    if (process.env.RENDER) return 'render';
+    if (process.env.FLY_APP_NAME) return 'fly';
+    if (process.env.HEROKU_APP_NAME) return 'heroku';
+    if (process.env.AWS_EXECUTION_ENV) return 'aws';
+    if (process.env.KUBERNETES_SERVICE_HOST) return 'kubernetes';
+    if (process.env.GOOGLE_CLOUD_PROJECT) return 'gcp';
+    if (process.env.AZURE_FUNCTIONS_ENVIRONMENT) return 'azure';
+    return null;
+  }
+
   /**
    * Track search queries
    */
@@ -432,53 +476,10 @@ export class TelemetryEventTracker {
 
   /**
    * Sanitize error message
+   * Now uses shared sanitization core from error-sanitization-utils.ts (v2.18.3)
+   * This eliminates code duplication and the ReDoS vulnerability
    */
   private sanitizeErrorMessage(errorMessage: string): string {
-    try {
-      // Early truncate to prevent ReDoS and performance issues
-      const maxLength = 1500;
-      const trimmed = errorMessage.length > maxLength
-        ? errorMessage.substring(0, maxLength)
-        : errorMessage;
-
-      // Handle stack traces - keep only first 3 lines (message + top stack frames)
-      const lines = trimmed.split('\n');
-      let sanitized = lines.slice(0, 3).join('\n');
-
-      // Sanitize sensitive data in correct order to prevent leakage
-      // 1. URLs first (most encompassing) - fully redact to prevent path leakage
-      sanitized = sanitized.replace(/https?:\/\/\S+/gi, '[URL]');
-
-      // 2. Specific credential patterns (before generic patterns)
-      sanitized = sanitized
-        .replace(/AKIA[A-Z0-9]{16}/g, '[AWS_KEY]')
-        .replace(/ghp_[a-zA-Z0-9]{36,}/g, '[GITHUB_TOKEN]')
-        .replace(/eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+/g, '[JWT]')
-        .replace(/Bearer\s+[^\s]+/gi, 'Bearer [TOKEN]');
-
-      // 3. Emails (after URLs to avoid partial matches)
-      sanitized = sanitized.replace(/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g, '[EMAIL]');
-
-      // 4. Long keys and quoted tokens
-      sanitized = sanitized
-        .replace(/\b[a-zA-Z0-9_-]{32,}\b/g, '[KEY]')
-        .replace(/(['"])[a-zA-Z0-9_-]{16,}\1/g, '$1[TOKEN]$1');
-
-      // 5. Generic credential patterns (after specific ones to avoid conflicts)
-      sanitized = sanitized
-        .replace(/password\s*[=:]\s*\S+/gi, 'password=[REDACTED]')
-        .replace(/api[_-]?key\s*[=:]\s*\S+/gi, 'api_key=[REDACTED]')
-        .replace(/(?<!Bearer\s)token\s*[=:]\s*\S+/gi, 'token=[REDACTED]');  // Negative lookbehind to avoid Bearer tokens
-
-      // Final truncate to 500 chars
-      if (sanitized.length > 500) {
-        sanitized = sanitized.substring(0, 500) + '...';
-      }
-
-      return sanitized;
-    } catch (error) {
-      logger.debug('Error message sanitization failed:', error);
-      return '[SANITIZATION_FAILED]';
-    }
+    return sanitizeErrorMessageCore(errorMessage);
   }
 }

src/telemetry/event-validator.ts

@@ -104,12 +104,33 @@ const performanceMetricPropertiesSchema = z.object({
   metadata: z.record(z.any()).optional()
 });
 
+// Schema for startup_error event properties (v2.18.2)
+const startupErrorPropertiesSchema = z.object({
+  checkpoint: z.string().max(100),
+  errorMessage: z.string().max(500),
+  errorType: z.string().max(100),
+  checkpointsPassed: z.array(z.string()).max(20),
+  checkpointsPassedCount: z.number().int().min(0).max(20),
+  startupDuration: z.number().min(0).max(300000), // Max 5 minutes
+  platform: z.string().max(50),
+  arch: z.string().max(50),
+  nodeVersion: z.string().max(50),
+  isDocker: z.boolean()
+});
+
+// Schema for startup_completed event properties (v2.18.2)
+const startupCompletedPropertiesSchema = z.object({
+  version: z.string().max(50)
+});
+
 // Map of event names to their specific schemas
 const EVENT_SCHEMAS: Record<string, z.ZodSchema<any>> = {
   'tool_used': toolUsagePropertiesSchema,
   'search_query': searchQueryPropertiesSchema,
   'validation_details': validationDetailsPropertiesSchema,
   'performance_metric': performanceMetricPropertiesSchema,
+  'startup_error': startupErrorPropertiesSchema,
+  'startup_completed': startupCompletedPropertiesSchema,
 };
 
 /**

src/telemetry/startup-checkpoints.ts

@@ -0,0 +1,133 @@
+/**
+ * Startup Checkpoint System
+ * Defines checkpoints throughout the server initialization process
+ * to identify where failures occur
+ */
+
+/**
+ * Startup checkpoint constants
+ * These checkpoints mark key stages in the server initialization process
+ */
+export const STARTUP_CHECKPOINTS = {
+  /** Process has started, very first checkpoint */
+  PROCESS_STARTED: 'process_started',
+
+  /** About to connect to database */
+  DATABASE_CONNECTING: 'database_connecting',
+
+  /** Database connection successful */
+  DATABASE_CONNECTED: 'database_connected',
+
+  /** About to check n8n API configuration (if applicable) */
+  N8N_API_CHECKING: 'n8n_api_checking',
+
+  /** n8n API is configured and ready (if applicable) */
+  N8N_API_READY: 'n8n_api_ready',
+
+  /** About to initialize telemetry system */
+  TELEMETRY_INITIALIZING: 'telemetry_initializing',
+
+  /** Telemetry system is ready */
+  TELEMETRY_READY: 'telemetry_ready',
+
+  /** About to start MCP handshake */
+  MCP_HANDSHAKE_STARTING: 'mcp_handshake_starting',
+
+  /** MCP handshake completed successfully */
+  MCP_HANDSHAKE_COMPLETE: 'mcp_handshake_complete',
+
+  /** Server is fully ready to handle requests */
+  SERVER_READY: 'server_ready',
+} as const;
+
+/**
+ * Type for checkpoint names
+ */
+export type StartupCheckpoint = typeof STARTUP_CHECKPOINTS[keyof typeof STARTUP_CHECKPOINTS];
+
+/**
+ * Checkpoint data structure
+ */
+export interface CheckpointData {
+  name: StartupCheckpoint;
+  timestamp: number;
+  success: boolean;
+  error?: string;
+}
+
+/**
+ * Get all checkpoint names in order
+ */
+export function getAllCheckpoints(): StartupCheckpoint[] {
+  return Object.values(STARTUP_CHECKPOINTS);
+}
+
+/**
+ * Find which checkpoint failed based on the list of passed checkpoints
+ * Returns the first checkpoint that was not passed
+ */
+export function findFailedCheckpoint(passedCheckpoints: string[]): StartupCheckpoint {
+  const allCheckpoints = getAllCheckpoints();
+
+  for (const checkpoint of allCheckpoints) {
+    if (!passedCheckpoints.includes(checkpoint)) {
+      return checkpoint;
+    }
+  }
+
+  // If all checkpoints were passed, the failure must have occurred after SERVER_READY
+  // This would be an unexpected post-initialization failure
+  return STARTUP_CHECKPOINTS.SERVER_READY;
+}
+
+/**
+ * Validate if a string is a valid checkpoint
+ */
+export function isValidCheckpoint(checkpoint: string): checkpoint is StartupCheckpoint {
+  return getAllCheckpoints().includes(checkpoint as StartupCheckpoint);
+}
+
+/**
+ * Get human-readable description for a checkpoint
+ */
+export function getCheckpointDescription(checkpoint: StartupCheckpoint): string {
+  const descriptions: Record<StartupCheckpoint, string> = {
+    [STARTUP_CHECKPOINTS.PROCESS_STARTED]: 'Process initialization started',
+    [STARTUP_CHECKPOINTS.DATABASE_CONNECTING]: 'Connecting to database',
+    [STARTUP_CHECKPOINTS.DATABASE_CONNECTED]: 'Database connection established',
+    [STARTUP_CHECKPOINTS.N8N_API_CHECKING]: 'Checking n8n API configuration',
+    [STARTUP_CHECKPOINTS.N8N_API_READY]: 'n8n API ready',
+    [STARTUP_CHECKPOINTS.TELEMETRY_INITIALIZING]: 'Initializing telemetry system',
+    [STARTUP_CHECKPOINTS.TELEMETRY_READY]: 'Telemetry system ready',
+    [STARTUP_CHECKPOINTS.MCP_HANDSHAKE_STARTING]: 'Starting MCP protocol handshake',
+    [STARTUP_CHECKPOINTS.MCP_HANDSHAKE_COMPLETE]: 'MCP handshake completed',
+    [STARTUP_CHECKPOINTS.SERVER_READY]: 'Server fully initialized and ready',
+  };
+
+  return descriptions[checkpoint] || 'Unknown checkpoint';
+}
+
+/**
+ * Get the next expected checkpoint after the given one
+ * Returns null if this is the last checkpoint
+ */
+export function getNextCheckpoint(current: StartupCheckpoint): StartupCheckpoint | null {
+  const allCheckpoints = getAllCheckpoints();
+  const currentIndex = allCheckpoints.indexOf(current);
+
+  if (currentIndex === -1 || currentIndex === allCheckpoints.length - 1) {
+    return null;
+  }
+
+  return allCheckpoints[currentIndex + 1];
+}
+
+/**
+ * Calculate completion percentage based on checkpoints passed
+ */
+export function getCompletionPercentage(passedCheckpoints: string[]): number {
+  const totalCheckpoints = getAllCheckpoints().length;
+  const passedCount = passedCheckpoints.length;
+
+  return Math.round((passedCount / totalCheckpoints) * 100);
+}

src/telemetry/telemetry-types.ts

@@ -3,6 +3,8 @@
  * Centralized type definitions for the telemetry system
  */
 
+import { StartupCheckpoint } from './startup-checkpoints';
+
 export interface TelemetryEvent {
   user_id: string;
   event: string;
@@ -10,6 +12,51 @@ export interface TelemetryEvent {
   created_at?: string;
 }
 
+/**
+ * Startup error event - captures pre-handshake failures
+ */
+export interface StartupErrorEvent extends TelemetryEvent {
+  event: 'startup_error';
+  properties: {
+    checkpoint: StartupCheckpoint;
+    errorMessage: string;
+    errorType: string;
+    checkpointsPassed: StartupCheckpoint[];
+    checkpointsPassedCount: number;
+    startupDuration: number;
+    platform: string;
+    arch: string;
+    nodeVersion: string;
+    isDocker: boolean;
+  };
+}
+
+/**
+ * Startup completed event - confirms server is functional
+ */
+export interface StartupCompletedEvent extends TelemetryEvent {
+  event: 'startup_completed';
+  properties: {
+    version: string;
+  };
+}
+
+/**
+ * Enhanced session start properties with startup tracking
+ */
+export interface SessionStartProperties {
+  version: string;
+  platform: string;
+  arch: string;
+  nodeVersion: string;
+  isDocker: boolean;
+  cloudPlatform: string | null;
+  // NEW: Startup tracking fields (v2.18.2)
+  startupDurationMs?: number;
+  checkpointsPassed?: StartupCheckpoint[];
+  startupErrorCount?: number;
+}
+
 export interface WorkflowTelemetry {
   user_id: string;
   workflow_hash: string;

src/templates/template-fetcher.ts

@@ -45,19 +45,22 @@ export class TemplateFetcher {
    * Fetch all templates and filter to last 12 months
    * This fetches ALL pages first, then applies date filter locally
    */
-  async fetchTemplates(progressCallback?: (current: number, total: number) => void): Promise<TemplateWorkflow[]> {
+  async fetchTemplates(progressCallback?: (current: number, total: number) => void, sinceDate?: Date): Promise<TemplateWorkflow[]> {
     const allTemplates = await this.fetchAllTemplates(progressCallback);
-    
-    // Apply date filter locally after fetching all
-    const oneYearAgo = new Date();
-    oneYearAgo.setMonth(oneYearAgo.getMonth() - 12);
-    
+
+    // Use provided date or default to 12 months ago
+    const cutoffDate = sinceDate || (() => {
+      const oneYearAgo = new Date();
+      oneYearAgo.setMonth(oneYearAgo.getMonth() - 12);
+      return oneYearAgo;
+    })();
+
     const recentTemplates = allTemplates.filter((w: TemplateWorkflow) => {
       const createdDate = new Date(w.createdAt);
-      return createdDate >= oneYearAgo;
+      return createdDate >= cutoffDate;
     });
-    
-    logger.info(`Filtered to ${recentTemplates.length} templates from last 12 months (out of ${allTemplates.length} total)`);
+
+    logger.info(`Filtered to ${recentTemplates.length} templates since ${cutoffDate.toISOString().split('T')[0]} (out of ${allTemplates.length} total)`);
     return recentTemplates;
   }
   

src/templates/template-repository.ts

@@ -442,7 +442,19 @@ export class TemplateRepository {
     const rows = this.db.prepare('SELECT id FROM templates').all() as { id: number }[];
     return new Set(rows.map(r => r.id));
   }
-  
+
+  /**
+   * Get the most recent template creation date
+   * Used in update mode to fetch only newer templates
+   */
+  getMostRecentTemplateDate(): Date | null {
+    const result = this.db.prepare('SELECT MAX(created_at) as max_date FROM templates').get() as { max_date: string | null } | undefined;
+    if (!result || !result.max_date) {
+      return null;
+    }
+    return new Date(result.max_date);
+  }
+
   /**
    * Check if a template exists in the database
    */

src/templates/template-service.ts

@@ -319,22 +319,38 @@ export class TemplateService {
       
       // Get existing template IDs if in update mode
       let existingIds: Set<number> = new Set();
+      let sinceDate: Date | undefined;
+
       if (mode === 'update') {
         existingIds = this.repository.getExistingTemplateIds();
         logger.info(`Update mode: Found ${existingIds.size} existing templates in database`);
+
+        // Get most recent template date and fetch only templates from last 2 weeks
+        const mostRecentDate = this.repository.getMostRecentTemplateDate();
+        if (mostRecentDate) {
+          // Fetch templates from 2 weeks before the most recent template
+          sinceDate = new Date(mostRecentDate);
+          sinceDate.setDate(sinceDate.getDate() - 14);
+          logger.info(`Update mode: Fetching templates since ${sinceDate.toISOString().split('T')[0]} (2 weeks before most recent)`);
+        } else {
+          // No templates yet, fetch from last 2 weeks
+          sinceDate = new Date();
+          sinceDate.setDate(sinceDate.getDate() - 14);
+          logger.info(`Update mode: No existing templates, fetching from last 2 weeks`);
+        }
       } else {
         // Clear existing templates in rebuild mode
         this.repository.clearTemplates();
         logger.info('Rebuild mode: Cleared existing templates');
       }
-      
+
       // Fetch template list
       logger.info(`Fetching template list from n8n.io (mode: ${mode})`);
       const templates = await fetcher.fetchTemplates((current, total) => {
         progressCallback?.('Fetching template list', current, total);
-      });
+      }, sinceDate);
       
-      logger.info(`Found ${templates.length} templates from last 12 months`);
+      logger.info(`Found ${templates.length} templates matching date criteria`);
       
       // Filter to only new templates if in update mode
       let templatesToFetch = templates;

src/types/index.ts

@@ -1,3 +1,6 @@
+// Export n8n node type definitions and utilities
+export * from './node-types';
+
 export interface MCPServerConfig {
   port: number;
   host: string;

src/types/n8n-api.ts

@@ -226,7 +226,7 @@ export interface WorkflowListParams {
   limit?: number;
   cursor?: string;
   active?: boolean;
-  tags?: string[] | null;
+  tags?: string | null;  // Comma-separated string per n8n API spec
   projectId?: string;
   excludePinnedData?: boolean;
   instance?: string;

src/types/node-types.ts

@@ -0,0 +1,220 @@
+/**
+ * TypeScript type definitions for n8n node parsing
+ *
+ * This file provides strong typing for node classes and instances,
+ * preventing bugs like the v2.17.4 baseDescription issue where
+ * TypeScript couldn't catch property name mistakes due to `any` types.
+ *
+ * @module types/node-types
+ * @since 2.17.5
+ */
+
+// Import n8n's official interfaces
+import type {
+  IVersionedNodeType,
+  INodeType,
+  INodeTypeBaseDescription,
+  INodeTypeDescription
+} from 'n8n-workflow';
+
+/**
+ * Represents a node class that can be either:
+ * - A constructor function that returns INodeType
+ * - A constructor function that returns IVersionedNodeType
+ * - An already-instantiated node instance
+ *
+ * This covers all patterns we encounter when loading nodes from n8n packages.
+ */
+export type NodeClass =
+  | (new () => INodeType)
+  | (new () => IVersionedNodeType)
+  | INodeType
+  | IVersionedNodeType;
+
+/**
+ * Instance of a versioned node type with all properties accessible.
+ *
+ * This represents nodes that use n8n's VersionedNodeType pattern,
+ * such as AI Agent, HTTP Request, Slack, etc.
+ *
+ * @property currentVersion - The computed current version (defaultVersion ?? max(nodeVersions))
+ * @property description - Base description stored as 'description' (NOT 'baseDescription')
+ * @property nodeVersions - Map of version numbers to INodeType implementations
+ *
+ * @example
+ * ```typescript
+ * const aiAgent = new AIAgentNode() as VersionedNodeInstance;
+ * console.log(aiAgent.currentVersion); // 2.2
+ * console.log(aiAgent.description.defaultVersion); // 2.2
+ * console.log(aiAgent.nodeVersions[1]); // INodeType for version 1
+ * ```
+ */
+export interface VersionedNodeInstance extends IVersionedNodeType {
+  currentVersion: number;
+  description: INodeTypeBaseDescription;
+  nodeVersions: {
+    [version: number]: INodeType;
+  };
+}
+
+/**
+ * Instance of a regular (non-versioned) node type.
+ *
+ * This represents simple nodes that don't use versioning,
+ * such as Edit Fields, Set, Code (v1), etc.
+ */
+export interface RegularNodeInstance extends INodeType {
+  description: INodeTypeDescription;
+}
+
+/**
+ * Union type for any node instance (versioned or regular).
+ *
+ * Use this when you need to handle both types of nodes.
+ */
+export type NodeInstance = VersionedNodeInstance | RegularNodeInstance;
+
+/**
+ * Type guard to check if a node is a VersionedNodeType instance.
+ *
+ * This provides runtime type safety and enables TypeScript to narrow
+ * the type within conditional blocks.
+ *
+ * @param node - The node instance to check
+ * @returns True if node is a VersionedNodeInstance
+ *
+ * @example
+ * ```typescript
+ * const instance = new nodeClass();
+ * if (isVersionedNodeInstance(instance)) {
+ *   // TypeScript knows instance is VersionedNodeInstance here
+ *   console.log(instance.currentVersion);
+ *   console.log(instance.nodeVersions);
+ * }
+ * ```
+ */
+export function isVersionedNodeInstance(node: any): node is VersionedNodeInstance {
+  return (
+    node !== null &&
+    typeof node === 'object' &&
+    'nodeVersions' in node &&
+    'currentVersion' in node &&
+    'description' in node &&
+    typeof node.currentVersion === 'number'
+  );
+}
+
+/**
+ * Type guard to check if a value is a VersionedNodeType class.
+ *
+ * This checks the constructor name pattern used by n8n's VersionedNodeType.
+ *
+ * @param nodeClass - The class or value to check
+ * @returns True if nodeClass is a VersionedNodeType constructor
+ *
+ * @example
+ * ```typescript
+ * if (isVersionedNodeClass(nodeClass)) {
+ *   // It's a VersionedNodeType class
+ *   const instance = new nodeClass() as VersionedNodeInstance;
+ * }
+ * ```
+ */
+export function isVersionedNodeClass(nodeClass: any): boolean {
+  return (
+    typeof nodeClass === 'function' &&
+    nodeClass.prototype?.constructor?.name === 'VersionedNodeType'
+  );
+}
+
+/**
+ * Safely instantiate a node class with proper error handling.
+ *
+ * Some nodes require specific parameters or environment setup to instantiate.
+ * This helper provides safe instantiation with fallback to null on error.
+ *
+ * @param nodeClass - The node class or instance to instantiate
+ * @returns The instantiated node or null if instantiation fails
+ *
+ * @example
+ * ```typescript
+ * const instance = instantiateNode(nodeClass);
+ * if (instance) {
+ *   // Successfully instantiated
+ *   const version = isVersionedNodeInstance(instance)
+ *     ? instance.currentVersion
+ *     : instance.description.version;
+ * }
+ * ```
+ */
+export function instantiateNode(nodeClass: NodeClass): NodeInstance | null {
+  try {
+    if (typeof nodeClass === 'function') {
+      return new nodeClass();
+    }
+    // Already an instance
+    return nodeClass;
+  } catch (e) {
+    // Some nodes require parameters to instantiate
+    return null;
+  }
+}
+
+/**
+ * Safely get a node instance, handling both classes and instances.
+ *
+ * This is a non-throwing version that returns undefined on failure.
+ *
+ * @param nodeClass - The node class or instance
+ * @returns The node instance or undefined
+ */
+export function getNodeInstance(nodeClass: NodeClass): NodeInstance | undefined {
+  const instance = instantiateNode(nodeClass);
+  return instance ?? undefined;
+}
+
+/**
+ * Extract description from a node class or instance.
+ *
+ * Handles both versioned and regular nodes, with fallback logic.
+ *
+ * @param nodeClass - The node class or instance
+ * @returns The node description or empty object on failure
+ */
+export function getNodeDescription(
+  nodeClass: NodeClass
+): INodeTypeBaseDescription | INodeTypeDescription {
+  // Try to get description from instance first
+  try {
+    const instance = instantiateNode(nodeClass);
+
+    if (instance) {
+      // For VersionedNodeType, description is the baseDescription
+      if (isVersionedNodeInstance(instance)) {
+        return instance.description;
+      }
+      // For regular nodes, description is the full INodeTypeDescription
+      return instance.description;
+    }
+  } catch (e) {
+    // Ignore instantiation errors
+  }
+
+  // Fallback to static properties
+  if (typeof nodeClass === 'object' && 'description' in nodeClass) {
+    return nodeClass.description;
+  }
+
+  // Last resort: empty description
+  return {
+    displayName: '',
+    name: '',
+    group: [],
+    description: '',
+    version: 1,
+    defaults: { name: '', color: '' },
+    inputs: [],
+    outputs: [],
+    properties: []
+  } as any; // Type assertion needed for fallback case
+}

src/types/workflow-diff.ts

@@ -64,6 +64,9 @@ export interface AddConnectionOperation extends DiffOperation {
   targetInput?: string; // Default: 'main'
   sourceIndex?: number; // Default: 0
   targetIndex?: number; // Default: 0
+  // Smart parameters for multi-output nodes (Phase 1 UX improvement)
+  branch?: 'true' | 'false'; // For IF nodes: maps to sourceIndex (0=true, 1=false)
+  case?: number; // For Switch/multi-output nodes: maps to sourceIndex
 }
 
 export interface RemoveConnectionOperation extends DiffOperation {
@@ -75,16 +78,17 @@ export interface RemoveConnectionOperation extends DiffOperation {
   ignoreErrors?: boolean; // If true, don't fail when connection doesn't exist (useful for cleanup)
 }
 
-export interface UpdateConnectionOperation extends DiffOperation {
-  type: 'updateConnection';
-  source: string;
-  target: string;
-  updates: {
-    sourceOutput?: string;
-    targetInput?: string;
-    sourceIndex?: number;
-    targetIndex?: number;
-  };
+export interface RewireConnectionOperation extends DiffOperation {
+  type: 'rewireConnection';
+  source: string;      // Source node name or ID
+  from: string;        // Current target to rewire FROM
+  to: string;          // New target to rewire TO
+  sourceOutput?: string;  // Optional: which output to rewire (default: 'main')
+  targetInput?: string;   // Optional: which input type (default: 'main')
+  sourceIndex?: number;   // Optional: which source index (default: 0)
+  // Smart parameters for multi-output nodes (Phase 1 UX improvement)
+  branch?: 'true' | 'false'; // For IF nodes: maps to sourceIndex (0=true, 1=false)
+  case?: number; // For Switch/multi-output nodes: maps to sourceIndex
 }
 
 // Workflow Metadata Operations
@@ -139,7 +143,7 @@ export type WorkflowDiffOperation =
   | DisableNodeOperation
   | AddConnectionOperation
   | RemoveConnectionOperation
-  | UpdateConnectionOperation
+  | RewireConnectionOperation
   | UpdateSettingsOperation
   | UpdateNameOperation
   | AddTagOperation
@@ -187,8 +191,8 @@ export function isNodeOperation(op: WorkflowDiffOperation): op is
 }
 
 export function isConnectionOperation(op: WorkflowDiffOperation): op is
-  AddConnectionOperation | RemoveConnectionOperation | UpdateConnectionOperation | CleanStaleConnectionsOperation | ReplaceConnectionsOperation {
-  return ['addConnection', 'removeConnection', 'updateConnection', 'cleanStaleConnections', 'replaceConnections'].includes(op.type);
+  AddConnectionOperation | RemoveConnectionOperation | RewireConnectionOperation | CleanStaleConnectionsOperation | ReplaceConnectionsOperation {
+  return ['addConnection', 'removeConnection', 'rewireConnection', 'cleanStaleConnections', 'replaceConnections'].includes(op.type);
 }
 
 export function isMetadataOperation(op: WorkflowDiffOperation): op is 

src/utils/auth.ts

@@ -22,8 +22,9 @@ export class AuthManager {
       return false;
     }
 
-    // Check static token
-    if (token === expectedToken) {
+    // SECURITY: Use timing-safe comparison for static token
+    // See: https://github.com/czlonkowski/n8n-mcp/issues/265 (CRITICAL-02)
+    if (AuthManager.timingSafeCompare(token, expectedToken)) {
       return true;
     }
 
@@ -97,4 +98,47 @@ export class AuthManager {
       Buffer.from(hashedToken)
     );
   }
+
+  /**
+   * Compare two tokens using constant-time algorithm to prevent timing attacks
+   *
+   * @param plainToken - Token from request
+   * @param expectedToken - Expected token value
+   * @returns true if tokens match, false otherwise
+   *
+   * @security This uses crypto.timingSafeEqual to prevent timing attack vulnerabilities.
+   * Never use === or !== for token comparison as it allows attackers to discover
+   * tokens character-by-character through timing analysis.
+   *
+   * @example
+   * const isValid = AuthManager.timingSafeCompare(requestToken, serverToken);
+   * if (!isValid) {
+   *   return res.status(401).json({ error: 'Unauthorized' });
+   * }
+   *
+   * @see https://github.com/czlonkowski/n8n-mcp/issues/265 (CRITICAL-02)
+   */
+  static timingSafeCompare(plainToken: string, expectedToken: string): boolean {
+    try {
+      // Tokens must be non-empty
+      if (!plainToken || !expectedToken) {
+        return false;
+      }
+
+      // Convert to buffers
+      const plainBuffer = Buffer.from(plainToken, 'utf8');
+      const expectedBuffer = Buffer.from(expectedToken, 'utf8');
+
+      // Check length first (constant time not needed for length comparison)
+      if (plainBuffer.length !== expectedBuffer.length) {
+        return false;
+      }
+
+      // Constant-time comparison
+      return crypto.timingSafeEqual(plainBuffer, expectedBuffer);
+    } catch (error) {
+      // Buffer conversion or comparison failed
+      return false;
+    }
+  }
 }

src/utils/enhanced-documentation-fetcher.ts

@@ -1,7 +1,7 @@
 import { promises as fs } from 'fs';
 import path from 'path';
 import { logger } from './logger';
-import { execSync } from 'child_process';
+import { spawnSync } from 'child_process';
 
 // Enhanced documentation structure with rich content
 export interface EnhancedNodeDocumentation {
@@ -61,36 +61,136 @@ export interface DocumentationMetadata {
 
 export class EnhancedDocumentationFetcher {
   private docsPath: string;
-  private docsRepoUrl = 'https://github.com/n8n-io/n8n-docs.git';
+  private readonly docsRepoUrl = 'https://github.com/n8n-io/n8n-docs.git';
   private cloned = false;
 
   constructor(docsPath?: string) {
-    this.docsPath = docsPath || path.join(__dirname, '../../temp', 'n8n-docs');
+    // SECURITY: Validate and sanitize docsPath to prevent command injection
+    // See: https://github.com/czlonkowski/n8n-mcp/issues/265 (CRITICAL-01 Part 2)
+    const defaultPath = path.join(__dirname, '../../temp', 'n8n-docs');
+
+    if (!docsPath) {
+      this.docsPath = defaultPath;
+    } else {
+      // SECURITY: Block directory traversal and malicious paths
+      const sanitized = this.sanitizePath(docsPath);
+
+      if (!sanitized) {
+        logger.error('Invalid docsPath rejected in constructor', { docsPath });
+        throw new Error('Invalid docsPath: path contains disallowed characters or patterns');
+      }
+
+      // SECURITY: Verify path is absolute and within allowed boundaries
+      const absolutePath = path.resolve(sanitized);
+
+      // Block paths that could escape to sensitive directories
+      if (absolutePath.startsWith('/etc') ||
+          absolutePath.startsWith('/sys') ||
+          absolutePath.startsWith('/proc') ||
+          absolutePath.startsWith('/var/log')) {
+        logger.error('docsPath points to system directory - blocked', { docsPath, absolutePath });
+        throw new Error('Invalid docsPath: cannot use system directories');
+      }
+
+      this.docsPath = absolutePath;
+      logger.info('docsPath validated and set', { docsPath: this.docsPath });
+    }
+
+    // SECURITY: Validate repository URL is HTTPS
+    if (!this.docsRepoUrl.startsWith('https://')) {
+      logger.error('docsRepoUrl must use HTTPS protocol', { url: this.docsRepoUrl });
+      throw new Error('Invalid repository URL: must use HTTPS protocol');
+    }
+  }
+
+  /**
+   * Sanitize path input to prevent command injection and directory traversal
+   * SECURITY: Part of fix for command injection vulnerability
+   */
+  private sanitizePath(inputPath: string): string | null {
+    // SECURITY: Reject paths containing any shell metacharacters or control characters
+    // This prevents command injection even before attempting to sanitize
+    const dangerousChars = /[;&|`$(){}[\]<>'"\\#\n\r\t]/;
+    if (dangerousChars.test(inputPath)) {
+      logger.warn('Path contains shell metacharacters - rejected', { path: inputPath });
+      return null;
+    }
+
+    // Block directory traversal attempts
+    if (inputPath.includes('..') || inputPath.startsWith('.')) {
+      logger.warn('Path traversal attempt blocked', { path: inputPath });
+      return null;
+    }
+
+    return inputPath;
   }
 
   /**
    * Clone or update the n8n-docs repository
+   * SECURITY: Uses spawnSync with argument arrays to prevent command injection
+   * See: https://github.com/czlonkowski/n8n-mcp/issues/265 (CRITICAL-01 Part 2)
    */
   async ensureDocsRepository(): Promise<void> {
     try {
       const exists = await fs.access(this.docsPath).then(() => true).catch(() => false);
-      
+
       if (!exists) {
-        logger.info('Cloning n8n-docs repository...');
-        await fs.mkdir(path.dirname(this.docsPath), { recursive: true });
-        execSync(`git clone --depth 1 ${this.docsRepoUrl} ${this.docsPath}`, {
-          stdio: 'pipe'
+        logger.info('Cloning n8n-docs repository...', {
+          url: this.docsRepoUrl,
+          path: this.docsPath
         });
+        await fs.mkdir(path.dirname(this.docsPath), { recursive: true });
+
+        // SECURITY: Use spawnSync with argument array instead of string interpolation
+        // This prevents command injection even if docsPath or docsRepoUrl are compromised
+        const cloneResult = spawnSync('git', [
+          'clone',
+          '--depth', '1',
+          this.docsRepoUrl,
+          this.docsPath
+        ], {
+          stdio: 'pipe',
+          encoding: 'utf-8'
+        });
+
+        if (cloneResult.status !== 0) {
+          const error = cloneResult.stderr || cloneResult.error?.message || 'Unknown error';
+          logger.error('Git clone failed', {
+            status: cloneResult.status,
+            stderr: error,
+            url: this.docsRepoUrl,
+            path: this.docsPath
+          });
+          throw new Error(`Git clone failed: ${error}`);
+        }
+
         logger.info('n8n-docs repository cloned successfully');
       } else {
-        logger.info('Updating n8n-docs repository...');
-        execSync('git pull --ff-only', {
+        logger.info('Updating n8n-docs repository...', { path: this.docsPath });
+
+        // SECURITY: Use spawnSync with argument array and cwd option
+        const pullResult = spawnSync('git', [
+          'pull',
+          '--ff-only'
+        ], {
           cwd: this.docsPath,
-          stdio: 'pipe'
+          stdio: 'pipe',
+          encoding: 'utf-8'
         });
+
+        if (pullResult.status !== 0) {
+          const error = pullResult.stderr || pullResult.error?.message || 'Unknown error';
+          logger.error('Git pull failed', {
+            status: pullResult.status,
+            stderr: error,
+            cwd: this.docsPath
+          });
+          throw new Error(`Git pull failed: ${error}`);
+        }
+
         logger.info('n8n-docs repository updated');
       }
-      
+
       this.cloned = true;
     } catch (error) {
       logger.error('Failed to clone/update n8n-docs repository:', error);
@@ -560,35 +660,113 @@ export class EnhancedDocumentationFetcher {
 
   /**
    * Search for node documentation file
+   * SECURITY: Uses Node.js fs APIs instead of shell commands to prevent command injection
+   * See: https://github.com/czlonkowski/n8n-mcp/issues/265 (CRITICAL-01)
    */
   private async searchForNodeDoc(nodeType: string): Promise<string | null> {
     try {
-      // First try exact match with nodeType
-      let result = execSync(
-        `find ${this.docsPath}/docs/integrations/builtin -name "${nodeType}.md" -type f | grep -v credentials | head -1`,
-        { encoding: 'utf-8', stdio: 'pipe' }
-      ).trim();
-      
-      if (result) return result;
-      
-      // Try lowercase nodeType
-      const lowerNodeType = nodeType.toLowerCase();
-      result = execSync(
-        `find ${this.docsPath}/docs/integrations/builtin -name "${lowerNodeType}.md" -type f | grep -v credentials | head -1`,
-        { encoding: 'utf-8', stdio: 'pipe' }
-      ).trim();
-      
-      if (result) return result;
-      
-      // Try node name pattern but exclude trigger nodes
-      const nodeName = this.extractNodeName(nodeType);
-      result = execSync(
-        `find ${this.docsPath}/docs/integrations/builtin -name "*${nodeName}.md" -type f | grep -v credentials | grep -v trigger | head -1`,
-        { encoding: 'utf-8', stdio: 'pipe' }
-      ).trim();
-      
-      return result || null;
+      // SECURITY: Sanitize input to prevent command injection and directory traversal
+      const sanitized = nodeType.replace(/[^a-zA-Z0-9._-]/g, '');
+
+      if (!sanitized) {
+        logger.warn('Invalid nodeType after sanitization', { nodeType });
+        return null;
+      }
+
+      // SECURITY: Block directory traversal attacks
+      if (sanitized.includes('..') || sanitized.startsWith('.') || sanitized.startsWith('/')) {
+        logger.warn('Path traversal attempt blocked', { nodeType, sanitized });
+        return null;
+      }
+
+      // Log sanitization if it occurred
+      if (sanitized !== nodeType) {
+        logger.warn('nodeType was sanitized (potential injection attempt)', {
+          original: nodeType,
+          sanitized,
+        });
+      }
+
+      // SECURITY: Use path.basename to strip any path components
+      const safeName = path.basename(sanitized);
+      const searchPath = path.join(this.docsPath, 'docs', 'integrations', 'builtin');
+
+      // SECURITY: Read directory recursively using Node.js fs API (no shell execution!)
+      const files = await fs.readdir(searchPath, {
+        recursive: true,
+        encoding: 'utf-8'
+      }) as string[];
+
+      // Try exact match first
+      let match = files.find(f =>
+        f.endsWith(`${safeName}.md`) &&
+        !f.includes('credentials') &&
+        !f.includes('trigger')
+      );
+
+      if (match) {
+        const fullPath = path.join(searchPath, match);
+
+        // SECURITY: Verify final path is within expected directory
+        if (!fullPath.startsWith(searchPath)) {
+          logger.error('Path traversal blocked in final path', { fullPath, searchPath });
+          return null;
+        }
+
+        logger.info('Found documentation (exact match)', { path: fullPath });
+        return fullPath;
+      }
+
+      // Try lowercase match
+      const lowerSafeName = safeName.toLowerCase();
+      match = files.find(f =>
+        f.endsWith(`${lowerSafeName}.md`) &&
+        !f.includes('credentials') &&
+        !f.includes('trigger')
+      );
+
+      if (match) {
+        const fullPath = path.join(searchPath, match);
+
+        // SECURITY: Verify final path is within expected directory
+        if (!fullPath.startsWith(searchPath)) {
+          logger.error('Path traversal blocked in final path', { fullPath, searchPath });
+          return null;
+        }
+
+        logger.info('Found documentation (lowercase match)', { path: fullPath });
+        return fullPath;
+      }
+
+      // Try partial match with node name
+      const nodeName = this.extractNodeName(safeName);
+      match = files.find(f =>
+        f.toLowerCase().includes(nodeName.toLowerCase()) &&
+        f.endsWith('.md') &&
+        !f.includes('credentials') &&
+        !f.includes('trigger')
+      );
+
+      if (match) {
+        const fullPath = path.join(searchPath, match);
+
+        // SECURITY: Verify final path is within expected directory
+        if (!fullPath.startsWith(searchPath)) {
+          logger.error('Path traversal blocked in final path', { fullPath, searchPath });
+          return null;
+        }
+
+        logger.info('Found documentation (partial match)', { path: fullPath });
+        return fullPath;
+      }
+
+      logger.debug('No documentation found', { nodeType: safeName });
+      return null;
     } catch (error) {
+      logger.error('Error searching for node documentation:', {
+        error: error instanceof Error ? error.message : String(error),
+        nodeType,
+      });
       return null;
     }
   }

src/utils/node-utils.ts

@@ -32,13 +32,18 @@ export function normalizeNodeType(nodeType: string): string {
 
 /**
  * Gets alternative node type formats to try for lookups
- * 
+ *
  * @param nodeType The original node type
  * @returns Array of alternative formats to try
  */
 export function getNodeTypeAlternatives(nodeType: string): string[] {
+  // Defensive: validate input to prevent TypeError when nodeType is undefined/null/empty
+  if (!nodeType || typeof nodeType !== 'string' || nodeType.trim() === '') {
+    return [];
+  }
+
   const alternatives: string[] = [];
-  
+
   // Add lowercase version
   alternatives.push(nodeType.toLowerCase());
   

src/utils/npm-version-checker.ts

@@ -0,0 +1,208 @@
+/**
+ * NPM Version Checker Utility
+ *
+ * Checks if the current n8n-mcp version is outdated by comparing
+ * against the latest version published on npm.
+ */
+
+import { logger } from './logger';
+
+/**
+ * NPM Registry Response structure
+ * Based on npm registry JSON format for package metadata
+ */
+interface NpmRegistryResponse {
+  version: string;
+  [key: string]: unknown;
+}
+
+export interface VersionCheckResult {
+  currentVersion: string;
+  latestVersion: string | null;
+  isOutdated: boolean;
+  updateAvailable: boolean;
+  error: string | null;
+  checkedAt: Date;
+  updateCommand?: string;
+}
+
+// Cache for version check to avoid excessive npm requests
+let versionCheckCache: VersionCheckResult | null = null;
+let lastCheckTime: number = 0;
+const CACHE_TTL_MS = 1 * 60 * 60 * 1000; // 1 hour cache
+
+/**
+ * Check if current version is outdated compared to npm registry
+ * Uses caching to avoid excessive npm API calls
+ *
+ * @param forceRefresh - Force a fresh check, bypassing cache
+ * @returns Version check result
+ */
+export async function checkNpmVersion(forceRefresh: boolean = false): Promise<VersionCheckResult> {
+  const now = Date.now();
+
+  // Return cached result if available and not expired
+  if (!forceRefresh && versionCheckCache && (now - lastCheckTime) < CACHE_TTL_MS) {
+    logger.debug('Returning cached npm version check result');
+    return versionCheckCache;
+  }
+
+  // Get current version from package.json
+  const packageJson = require('../../package.json');
+  const currentVersion = packageJson.version;
+
+  try {
+    // Fetch latest version from npm registry
+    const response = await fetch('https://registry.npmjs.org/n8n-mcp/latest', {
+      headers: {
+        'Accept': 'application/json',
+      },
+      signal: AbortSignal.timeout(5000) // 5 second timeout
+    });
+
+    if (!response.ok) {
+      logger.warn('Failed to fetch npm version info', {
+        status: response.status,
+        statusText: response.statusText
+      });
+
+      const result: VersionCheckResult = {
+        currentVersion,
+        latestVersion: null,
+        isOutdated: false,
+        updateAvailable: false,
+        error: `npm registry returned ${response.status}`,
+        checkedAt: new Date()
+      };
+
+      versionCheckCache = result;
+      lastCheckTime = now;
+      return result;
+    }
+
+    // Parse and validate JSON response
+    let data: unknown;
+    try {
+      data = await response.json();
+    } catch (error) {
+      throw new Error('Failed to parse npm registry response as JSON');
+    }
+
+    // Validate response structure
+    if (!data || typeof data !== 'object' || !('version' in data)) {
+      throw new Error('Invalid response format from npm registry');
+    }
+
+    const registryData = data as NpmRegistryResponse;
+    const latestVersion = registryData.version;
+
+    // Validate version format (semver: x.y.z or x.y.z-prerelease)
+    if (!latestVersion || !/^\d+\.\d+\.\d+/.test(latestVersion)) {
+      throw new Error(`Invalid version format from npm registry: ${latestVersion}`);
+    }
+
+    // Compare versions
+    const isOutdated = compareVersions(currentVersion, latestVersion) < 0;
+
+    const result: VersionCheckResult = {
+      currentVersion,
+      latestVersion,
+      isOutdated,
+      updateAvailable: isOutdated,
+      error: null,
+      checkedAt: new Date(),
+      updateCommand: isOutdated ? `npm install -g n8n-mcp@${latestVersion}` : undefined
+    };
+
+    // Cache the result
+    versionCheckCache = result;
+    lastCheckTime = now;
+
+    logger.debug('npm version check completed', {
+      current: currentVersion,
+      latest: latestVersion,
+      outdated: isOutdated
+    });
+
+    return result;
+
+  } catch (error) {
+    logger.warn('Error checking npm version', {
+      error: error instanceof Error ? error.message : String(error)
+    });
+
+    const result: VersionCheckResult = {
+      currentVersion,
+      latestVersion: null,
+      isOutdated: false,
+      updateAvailable: false,
+      error: error instanceof Error ? error.message : 'Unknown error',
+      checkedAt: new Date()
+    };
+
+    // Cache error result to avoid rapid retry
+    versionCheckCache = result;
+    lastCheckTime = now;
+
+    return result;
+  }
+}
+
+/**
+ * Compare two semantic version strings
+ * Returns: -1 if v1 < v2, 0 if v1 === v2, 1 if v1 > v2
+ *
+ * @param v1 - First version (e.g., "1.2.3")
+ * @param v2 - Second version (e.g., "1.3.0")
+ * @returns Comparison result
+ */
+export function compareVersions(v1: string, v2: string): number {
+  // Remove 'v' prefix if present
+  const clean1 = v1.replace(/^v/, '');
+  const clean2 = v2.replace(/^v/, '');
+
+  // Split into parts and convert to numbers
+  const parts1 = clean1.split('.').map(n => parseInt(n, 10) || 0);
+  const parts2 = clean2.split('.').map(n => parseInt(n, 10) || 0);
+
+  // Compare each part
+  for (let i = 0; i < Math.max(parts1.length, parts2.length); i++) {
+    const p1 = parts1[i] || 0;
+    const p2 = parts2[i] || 0;
+
+    if (p1 < p2) return -1;
+    if (p1 > p2) return 1;
+  }
+
+  return 0; // Versions are equal
+}
+
+/**
+ * Clear the version check cache (useful for testing)
+ */
+export function clearVersionCheckCache(): void {
+  versionCheckCache = null;
+  lastCheckTime = 0;
+}
+
+/**
+ * Format version check result as a user-friendly message
+ *
+ * @param result - Version check result
+ * @returns Formatted message
+ */
+export function formatVersionMessage(result: VersionCheckResult): string {
+  if (result.error) {
+    return `Version check failed: ${result.error}. Current version: ${result.currentVersion}`;
+  }
+
+  if (!result.latestVersion) {
+    return `Current version: ${result.currentVersion} (latest version unknown)`;
+  }
+
+  if (result.isOutdated) {
+    return `⚠️ Update available! Current: ${result.currentVersion} → Latest: ${result.latestVersion}`;
+  }
+
+  return `✓ You're up to date! Current version: ${result.currentVersion}`;
+}

src/utils/ssrf-protection.ts

@@ -0,0 +1,187 @@
+import { URL } from 'url';
+import { lookup } from 'dns/promises';
+import { logger } from './logger';
+
+/**
+ * SSRF Protection Utility with Configurable Security Modes
+ *
+ * Validates URLs to prevent Server-Side Request Forgery attacks including DNS rebinding
+ * See: https://github.com/czlonkowski/n8n-mcp/issues/265 (HIGH-03)
+ *
+ * Security Modes:
+ * - strict (default): Block localhost + private IPs + cloud metadata (production)
+ * - moderate: Allow localhost, block private IPs + cloud metadata (local dev)
+ * - permissive: Allow localhost + private IPs, block cloud metadata (testing only)
+ */
+
+// Security mode type
+type SecurityMode = 'strict' | 'moderate' | 'permissive';
+
+// Cloud metadata endpoints (ALWAYS blocked in all modes)
+const CLOUD_METADATA = new Set([
+  // AWS/Azure
+  '169.254.169.254', // AWS/Azure metadata
+  '169.254.170.2',   // AWS ECS metadata
+  // Google Cloud
+  'metadata.google.internal', // GCP metadata
+  'metadata',
+  // Alibaba Cloud
+  '100.100.100.200', // Alibaba Cloud metadata
+  // Oracle Cloud
+  '192.0.0.192',     // Oracle Cloud metadata
+]);
+
+// Localhost patterns
+const LOCALHOST_PATTERNS = new Set([
+  'localhost',
+  '127.0.0.1',
+  '::1',
+  '0.0.0.0',
+  'localhost.localdomain',
+]);
+
+// Private IP ranges (regex for IPv4)
+const PRIVATE_IP_RANGES = [
+  /^10\./,                          // 10.0.0.0/8
+  /^192\.168\./,                    // 192.168.0.0/16
+  /^172\.(1[6-9]|2[0-9]|3[0-1])\./, // 172.16.0.0/12
+  /^169\.254\./,                    // 169.254.0.0/16 (Link-local)
+  /^127\./,                         // 127.0.0.0/8 (Loopback)
+  /^0\./,                           // 0.0.0.0/8 (Invalid)
+];
+
+export class SSRFProtection {
+  /**
+   * Validate webhook URL for SSRF protection with configurable security modes
+   *
+   * @param urlString - URL to validate
+   * @returns Promise with validation result
+   *
+   * @security Uses DNS resolution to prevent DNS rebinding attacks
+   *
+   * @example
+   * // Production (default strict mode)
+   * const result = await SSRFProtection.validateWebhookUrl('http://localhost:5678');
+   * // { valid: false, reason: 'Localhost not allowed' }
+   *
+   * @example
+   * // Local development (moderate mode)
+   * process.env.WEBHOOK_SECURITY_MODE = 'moderate';
+   * const result = await SSRFProtection.validateWebhookUrl('http://localhost:5678');
+   * // { valid: true }
+   */
+  static async validateWebhookUrl(urlString: string): Promise<{
+    valid: boolean;
+    reason?: string
+  }> {
+    try {
+      const url = new URL(urlString);
+      const mode: SecurityMode = (process.env.WEBHOOK_SECURITY_MODE || 'strict') as SecurityMode;
+
+      // Step 1: Must be HTTP/HTTPS (all modes)
+      if (!['http:', 'https:'].includes(url.protocol)) {
+        return { valid: false, reason: 'Invalid protocol. Only HTTP/HTTPS allowed.' };
+      }
+
+      // Get hostname and strip IPv6 brackets if present
+      let hostname = url.hostname.toLowerCase();
+      // Remove IPv6 brackets for consistent comparison
+      if (hostname.startsWith('[') && hostname.endsWith(']')) {
+        hostname = hostname.slice(1, -1);
+      }
+
+      // Step 2: ALWAYS block cloud metadata endpoints (all modes)
+      if (CLOUD_METADATA.has(hostname)) {
+        logger.warn('SSRF blocked: Cloud metadata endpoint', { hostname, mode });
+        return { valid: false, reason: 'Cloud metadata endpoint blocked' };
+      }
+
+      // Step 3: Resolve DNS to get actual IP address
+      // This prevents DNS rebinding attacks where hostname resolves to different IPs
+      let resolvedIP: string;
+      try {
+        const { address } = await lookup(hostname);
+        resolvedIP = address;
+
+        logger.debug('DNS resolved for SSRF check', { hostname, resolvedIP, mode });
+      } catch (error) {
+        logger.warn('DNS resolution failed for webhook URL', {
+          hostname,
+          error: error instanceof Error ? error.message : String(error)
+        });
+        return { valid: false, reason: 'DNS resolution failed' };
+      }
+
+      // Step 4: ALWAYS block cloud metadata IPs (all modes)
+      if (CLOUD_METADATA.has(resolvedIP)) {
+        logger.warn('SSRF blocked: Hostname resolves to cloud metadata IP', {
+          hostname,
+          resolvedIP,
+          mode
+        });
+        return { valid: false, reason: 'Hostname resolves to cloud metadata endpoint' };
+      }
+
+      // Step 5: Mode-specific validation
+
+      // MODE: permissive - Allow everything except cloud metadata
+      if (mode === 'permissive') {
+        logger.warn('SSRF protection in permissive mode (localhost and private IPs allowed)', {
+          hostname,
+          resolvedIP
+        });
+        return { valid: true };
+      }
+
+      // Check if target is localhost
+      const isLocalhost = LOCALHOST_PATTERNS.has(hostname) ||
+                        resolvedIP === '::1' ||
+                        resolvedIP.startsWith('127.');
+
+      // MODE: strict - Block localhost and private IPs
+      if (mode === 'strict' && isLocalhost) {
+        logger.warn('SSRF blocked: Localhost not allowed in strict mode', {
+          hostname,
+          resolvedIP
+        });
+        return { valid: false, reason: 'Localhost access is blocked in strict mode' };
+      }
+
+      // MODE: moderate - Allow localhost, block private IPs
+      if (mode === 'moderate' && isLocalhost) {
+        logger.info('Localhost webhook allowed (moderate mode)', { hostname, resolvedIP });
+        return { valid: true };
+      }
+
+      // Step 6: Check private IPv4 ranges (strict & moderate modes)
+      if (PRIVATE_IP_RANGES.some(regex => regex.test(resolvedIP))) {
+        logger.warn('SSRF blocked: Private IP address', { hostname, resolvedIP, mode });
+        return {
+          valid: false,
+          reason: mode === 'strict'
+            ? 'Private IP addresses not allowed'
+            : 'Private IP addresses not allowed (use WEBHOOK_SECURITY_MODE=permissive if needed)'
+        };
+      }
+
+      // Step 7: IPv6 private address check (strict & moderate modes)
+      if (resolvedIP === '::1' ||         // Loopback
+          resolvedIP === '::' ||          // Unspecified address
+          resolvedIP.startsWith('fe80:') || // Link-local
+          resolvedIP.startsWith('fc00:') || // Unique local (fc00::/7)
+          resolvedIP.startsWith('fd00:') || // Unique local (fd00::/8)
+          resolvedIP.startsWith('::ffff:')) { // IPv4-mapped IPv6
+        logger.warn('SSRF blocked: IPv6 private address', {
+          hostname,
+          resolvedIP,
+          mode
+        });
+        return { valid: false, reason: 'IPv6 private address not allowed' };
+      }
+
+      return { valid: true };
+    } catch (error) {
+      return { valid: false, reason: 'Invalid URL format' };
+    }
+  }
+}

tests/benchmarks/database-queries.bench.ts

@@ -4,6 +4,17 @@ import { SQLiteStorageService } from '../../src/services/sqlite-storage-service'
 import { NodeFactory } from '../factories/node-factory';
 import { PropertyDefinitionFactory } from '../factories/property-definition-factory';
 
+/**
+ * Database Query Performance Benchmarks
+ *
+ * NOTE: These benchmarks use MOCK DATA (500 artificial test nodes)
+ * created with factories, not the real production database.
+ *
+ * This is useful for tracking database layer performance in isolation,
+ * but may not reflect real-world performance characteristics.
+ *
+ * For end-to-end MCP tool performance with real data, see mcp-tools.bench.ts
+ */
 describe('Database Query Performance', () => {
   let repository: NodeRepository;
   let storage: SQLiteStorageService;

tests/benchmarks/index.ts

@@ -1,7 +1,3 @@
 // Export all benchmark suites
-// Note: Some benchmarks are temporarily disabled due to API changes
-// export * from './node-loading.bench';
 export * from './database-queries.bench';
-// export * from './search-operations.bench';
-// export * from './validation-performance.bench';
-// export * from './mcp-tools.bench';
+export * from './mcp-tools.bench';

tests/benchmarks/mcp-tools.bench.ts

@@ -0,0 +1,169 @@
+import { bench, describe } from 'vitest';
+import { NodeRepository } from '../../src/database/node-repository';
+import { createDatabaseAdapter } from '../../src/database/database-adapter';
+import { EnhancedConfigValidator } from '../../src/services/enhanced-config-validator';
+import { PropertyFilter } from '../../src/services/property-filter';
+import path from 'path';
+
+/**
+ * MCP Tool Performance Benchmarks
+ *
+ * These benchmarks measure end-to-end performance of actual MCP tool operations
+ * using the REAL production database (data/nodes.db with 525+ nodes).
+ *
+ * Unlike database-queries.bench.ts which uses mock data, these benchmarks
+ * reflect what AI assistants actually experience when calling MCP tools,
+ * making this the most meaningful performance metric for the system.
+ */
+describe('MCP Tool Performance (Production Database)', () => {
+  let repository: NodeRepository;
+
+  beforeAll(async () => {
+    // Use REAL production database
+    const dbPath = path.join(__dirname, '../../data/nodes.db');
+    const db = await createDatabaseAdapter(dbPath);
+    repository = new NodeRepository(db);
+    // Initialize similarity services for validation
+    EnhancedConfigValidator.initializeSimilarityServices(repository);
+  });
+
+  /**
+   * search_nodes - Most frequently used tool for node discovery
+   *
+   * This measures:
+   * - Database FTS5 full-text search
+   * - Result filtering and ranking
+   * - Response serialization
+   *
+   * Target: <20ms for common queries
+   */
+  bench('search_nodes - common query (http)', async () => {
+    await repository.searchNodes('http', 'OR', 20);
+  }, {
+    iterations: 100,
+    warmupIterations: 10,
+    warmupTime: 500,
+    time: 3000
+  });
+
+  bench('search_nodes - AI agent query (slack message)', async () => {
+    await repository.searchNodes('slack send message', 'AND', 10);
+  }, {
+    iterations: 100,
+    warmupIterations: 10,
+    warmupTime: 500,
+    time: 3000
+  });
+
+  /**
+   * get_node_essentials - Fast retrieval of node configuration
+   *
+   * This measures:
+   * - Database node lookup
+   * - Property filtering (essentials only)
+   * - Response formatting
+   *
+   * Target: <10ms for most nodes
+   */
+  bench('get_node_essentials - HTTP Request node', async () => {
+    const node = await repository.getNodeByType('n8n-nodes-base.httpRequest');
+    if (node && node.properties) {
+      PropertyFilter.getEssentials(node.properties, node.nodeType);
+    }
+  }, {
+    iterations: 200,
+    warmupIterations: 20,
+    warmupTime: 500,
+    time: 3000
+  });
+
+  bench('get_node_essentials - Slack node', async () => {
+    const node = await repository.getNodeByType('n8n-nodes-base.slack');
+    if (node && node.properties) {
+      PropertyFilter.getEssentials(node.properties, node.nodeType);
+    }
+  }, {
+    iterations: 200,
+    warmupIterations: 20,
+    warmupTime: 500,
+    time: 3000
+  });
+
+  /**
+   * list_nodes - Initial exploration/listing
+   *
+   * This measures:
+   * - Database query with pagination
+   * - Result serialization
+   * - Category filtering
+   *
+   * Target: <15ms for first page
+   */
+  bench('list_nodes - first 50 nodes', async () => {
+    await repository.getAllNodes(50);
+  }, {
+    iterations: 100,
+    warmupIterations: 10,
+    warmupTime: 500,
+    time: 3000
+  });
+
+  bench('list_nodes - AI tools only', async () => {
+    await repository.getAIToolNodes();
+  }, {
+    iterations: 100,
+    warmupIterations: 10,
+    warmupTime: 500,
+    time: 3000
+  });
+
+  /**
+   * validate_node_operation - Configuration validation
+   *
+   * This measures:
+   * - Schema lookup
+   * - Validation logic execution
+   * - Error message formatting
+   *
+   * Target: <15ms for simple validations
+   */
+  bench('validate_node_operation - HTTP Request (minimal)', async () => {
+    const node = await repository.getNodeByType('n8n-nodes-base.httpRequest');
+    if (node && node.properties) {
+      EnhancedConfigValidator.validateWithMode(
+        'n8n-nodes-base.httpRequest',
+        {},
+        node.properties,
+        'operation',
+        'ai-friendly'
+      );
+    }
+  }, {
+    iterations: 100,
+    warmupIterations: 10,
+    warmupTime: 500,
+    time: 3000
+  });
+
+  bench('validate_node_operation - HTTP Request (with params)', async () => {
+    const node = await repository.getNodeByType('n8n-nodes-base.httpRequest');
+    if (node && node.properties) {
+      EnhancedConfigValidator.validateWithMode(
+        'n8n-nodes-base.httpRequest',
+        {
+          requestMethod: 'GET',
+          url: 'https://api.example.com',
+          authentication: 'none'
+        },
+        node.properties,
+        'operation',
+        'ai-friendly'
+      );
+    }
+  }, {
+    iterations: 100,
+    warmupIterations: 10,
+    warmupTime: 500,
+    time: 3000
+  });
+});

tests/benchmarks/sample.bench.ts

@@ -1,47 +0,0 @@
-import { bench, describe } from 'vitest';
-
-/**
- * Sample benchmark to verify the setup works correctly
- */
-describe('Sample Benchmarks', () => {
-  bench('array sorting - small', () => {
-    const arr = Array.from({ length: 100 }, () => Math.random());
-    arr.sort((a, b) => a - b);
-  }, {
-    iterations: 1000,
-    warmupIterations: 100
-  });
-
-  bench('array sorting - large', () => {
-    const arr = Array.from({ length: 10000 }, () => Math.random());
-    arr.sort((a, b) => a - b);
-  }, {
-    iterations: 100,
-    warmupIterations: 10
-  });
-
-  bench('string concatenation', () => {
-    let str = '';
-    for (let i = 0; i < 1000; i++) {
-      str += 'a';
-    }
-  }, {
-    iterations: 1000,
-    warmupIterations: 100
-  });
-
-  bench('object creation', () => {
-    const objects = [];
-    for (let i = 0; i < 1000; i++) {
-      objects.push({
-        id: i,
-        name: `Object ${i}`,
-        value: Math.random(),
-        timestamp: Date.now()
-      });
-    }
-  }, {
-    iterations: 1000,
-    warmupIterations: 100
-  });
-});