Merge pull request #274 from czlonkowski/fix/issue-272-connection-operations-phase0

Phase 0 + Phase 1: Connection Operations + TypeError Fixes (Issues #272, #204, #275, #136)

.env.example

@@ -132,4 +132,36 @@ ENABLE_MULTI_TENANT=false
 
 # Enable metadata generation during template fetch (default: false)
 # Set to true to automatically generate metadata when running fetch:templates
-# METADATA_GENERATION_ENABLED=false
+# METADATA_GENERATION_ENABLED=false
+
+# ========================================
+# INTEGRATION TESTING CONFIGURATION
+# ========================================
+# Configuration for integration tests that call real n8n instance API
+
+# n8n API Configuration for Integration Tests
+# For local development: Use your local n8n instance
+# For CI: These will be provided by GitHub secrets
+# N8N_API_URL=http://localhost:5678
+# N8N_API_KEY=
+
+# Pre-activated Webhook Workflows for Testing
+# These workflows must be created manually in n8n and activated
+# because n8n API doesn't support workflow activation.
+#
+# Setup Instructions:
+# 1. Create 4 workflows in n8n UI (one for each HTTP method)
+# 2. Each workflow should have a single Webhook node
+# 3. Configure webhook paths: mcp-test-get, mcp-test-post, mcp-test-put, mcp-test-delete
+# 4. ACTIVATE each workflow in n8n UI
+# 5. Copy the workflow IDs here
+#
+# N8N_TEST_WEBHOOK_GET_ID=      # Workflow ID for GET method webhook
+# N8N_TEST_WEBHOOK_POST_ID=     # Workflow ID for POST method webhook
+# N8N_TEST_WEBHOOK_PUT_ID=      # Workflow ID for PUT method webhook
+# N8N_TEST_WEBHOOK_DELETE_ID=   # Workflow ID for DELETE method webhook
+
+# Test Configuration
+N8N_TEST_CLEANUP_ENABLED=true         # Enable automatic cleanup of test workflows
+N8N_TEST_TAG=mcp-integration-test     # Tag applied to all test workflows
+N8N_TEST_NAME_PREFIX=[MCP-TEST]       # Name prefix for test workflows

.github/workflows/test.yml

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

.gitignore

@@ -89,6 +89,13 @@ docker-compose.override.yml
 temp/
 tmp/
 
+# Batch processing error files (may contain API tokens from templates)
+docs/batch_*.jsonl
+**/batch_*_error.jsonl
+
+# Local documentation and analysis files
+docs/local/
+
 # Database files
 # Database files - nodes.db is now tracked directly
 # data/*.db

CHANGELOG.md

@@ -5,6 +5,917 @@ 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).
 
+## [2.16.0] - 2025-10-06
+
+### Added
+
+- **🎉 Issue #272 Phase 1: Connection Operations UX Improvements**
+
+  **New: `rewireConnection` Operation**
+  - Intuitive operation for changing connection target from one node to another
+  - Syntax: `{type: "rewireConnection", source: "Node", from: "OldTarget", to: "NewTarget"}`
+  - Internally uses remove + add pattern but with clearer semantics
+  - Supports smart parameters (branch, case) for multi-output nodes
+  - Validates all nodes exist before making changes
+  - 8 comprehensive unit tests covering all scenarios
+
+  **New: Smart Parameters for Multi-Output Nodes**
+  - **branch parameter for IF nodes**: Use `branch: "true"` or `branch: "false"` instead of `sourceIndex: 0/1`
+  - **case parameter for Switch nodes**: Use `case: 0`, `case: 1`, etc. instead of `sourceIndex`
+  - Semantic, intuitive syntax that matches node behavior
+  - Explicit sourceIndex overrides smart parameters if both provided
+  - Works with both `addConnection` and `rewireConnection` operations
+  - 8 comprehensive unit tests + 11 integration tests against real n8n API
+
+### Changed
+
+- **⚠️ BREAKING: Removed `updateConnection` operation**
+  - Operation removed completely (type definition, implementation, validation, tests)
+  - Migration: Use `rewireConnection` or `removeConnection` + `addConnection` instead
+  - Reason: Confusing operation that was error-prone and rarely needed
+  - All tests updated (137 tests passing)
+
+### Fixed
+
+- **🐛 CRITICAL: Issue #275, #136 - TypeError in getNodeTypeAlternatives (57.4% of production errors)**
+  - **Impact**: Eliminated 323 out of 563 production errors, helping 127 users (76.5% of affected users)
+  - **Resolves Issue #136**: "Partial Workflow Updates fail with 'Cannot convert undefined or null to object'" - defensive type guards prevent these crashes
+  - **Root Cause**: `getNodeTypeAlternatives()` called string methods without validating nodeType parameter
+  - **Fix**: Added defense-in-depth protection:
+    - **Layer 1**: Type guard in `getNodeTypeAlternatives()` returns empty array for invalid inputs
+    - **Layer 2**: Enhanced `validateToolParamsBasic()` to catch empty strings
+  - **Affected Tools**: `get_node_essentials` (208 errors → 0), `get_node_info` (115 errors → 0), `get_node_documentation` (17 errors → 0)
+  - **Testing**: 21 comprehensive unit tests, verified with n8n-mcp-tester agent
+  - **Commit**: f139d38
+
+- **Critical Bug: Smart Parameter Implementation**
+  - **Bug #1**: `branch` parameter initially mapped to `sourceOutput` instead of `sourceIndex`
+  - **Impact**: IF node connections went to wrong output (expected `IF.main[0]`, got `IF.true`)
+  - **Root Cause**: Misunderstood n8n's IF node connection structure
+  - **Fix**: Changed to correctly map `branch="true"` → `sourceIndex=0`, `branch="false"` → `sourceIndex=1`
+  - **Discovered by**: n8n-mcp-tester agent testing against real n8n API
+  - **Commit**: a7bfa73
+
+- **Critical Bug: Zod Schema Stripping Parameters**
+  - **Bug #2**: `branch`, `case`, `from`, `to` parameters stripped by Zod validation
+  - **Impact**: Parameters never reached diff engine, smart parameters silently failed
+  - **Root Cause**: Parameters not defined in Zod schema in handlers-workflow-diff.ts
+  - **Fix**: Added missing parameters to schema
+  - **Discovered by**: n8n-mcp-tester agent
+  - **Commit**: aeaba3b
+
+- **🔥 CRITICAL Bug: Array Index Corruption in Multi-Output Nodes**
+  - **Bug #3**: `applyRemoveConnection()` filtered empty arrays, causing index shifting in multi-output nodes
+  - **Impact**: PRODUCTION-BREAKING for Switch, IF with multiple handlers, Merge nodes
+  - **Severity**: Connections routed to wrong outputs after rewiring
+  - **Example**: Switch with 4 outputs `[[H0], [H1], [H2], [H3]]` → remove H1 → `[[H0], [H2], [H3]]` (indices shifted!)
+  - **Root Cause**: Line 697 filtered empty arrays: `connections.filter(conns => conns.length > 0)`
+  - **Fix**: Only remove trailing empty arrays, preserve intermediate ones to maintain index integrity
+  - **Code Change**:
+    ```typescript
+    // Before (BUGGY):
+    workflow.connections[node][output] = connections.filter(conns => conns.length > 0);
+
+    // After (FIXED):
+    while (connections.length > 0 && connections[connections.length - 1].length === 0) {
+      connections.pop();
+    }
+    ```
+  - **Testing**: Added integration test verifying Switch node rewiring preserves all indices
+  - **Discovered by**: n8n-mcp-tester agent during comprehensive testing
+  - **Commit**: aeb7410
+
+- **TypeScript Compilation**: Added missing type annotations in workflow diff tests (Commit: 653f395)
+
+### Improved
+
+- **Integration Testing**: Created comprehensive integration tests against real n8n API
+  - 11 tests covering IF nodes, Switch nodes, and rewireConnection
+  - Tests validate actual n8n workflow structure, not in-memory objects
+  - Would have caught both smart parameter bugs that unit tests missed
+  - File: `tests/integration/n8n-api/workflows/smart-parameters.test.ts`
+  - **Commit**: 34bafe2
+
+- **Documentation**: Updated MCP tool documentation
+  - Removed `updateConnection` references
+  - Added `rewireConnection` with 4 examples
+  - Added smart parameters section with IF and Switch examples
+  - Updated best practices and pitfalls
+  - Removed version references (AI agents see current state)
+  - Files: `src/mcp/tool-docs/workflow_management/n8n-update-partial-workflow.ts`, `docs/workflow-diff-examples.md`
+  - **Commit**: f78f53e
+
+### Test Coverage
+
+- **Total Tests**: 178 tests passing (158 unit + 20 integration against real n8n API)
+- **Coverage**: 90.98% statements, 89.86% branches, 93.02% functions
+- **Quality**: Integration tests against real n8n API prevent regression
+- **New Tests**:
+  - 21 tests for TypeError prevention (Issue #275)
+  - 8 tests for rewireConnection operation
+  - 8 tests for smart parameters
+  - 20 integration tests against real n8n API:
+    - **Multi-output nodes (sourceIndex preservation)**:
+      - Switch node rewiring with index preservation
+      - IF node empty array preservation on removal
+      - Switch node removing first case (production-breaking bug scenario)
+      - Sequential operations on Switch node
+      - Filter node connection rewiring
+    - **Multi-input nodes (targetIndex preservation)**:
+      - Merge node removing connection to input 0
+      - Merge node removing middle connection (inputs 0, 2 preserved)
+      - Merge node replacing source connections
+      - Merge node sequential operations
+
+### Technical Details
+
+**TypeError Prevention (Issue #275):**
+```typescript
+// Layer 1: Defensive utility function
+export function getNodeTypeAlternatives(nodeType: string): string[] {
+  // Return empty array for invalid inputs instead of crashing
+  if (!nodeType || typeof nodeType !== 'string' || nodeType.trim() === '') {
+    return [];
+  }
+  // ... rest of function
+}
+
+// Layer 2: Enhanced validation
+if (param === '') {
+  errors.push(`String parameters cannot be empty. Parameter '${key}' has value: ""`);
+}
+```
+
+**Smart Parameters Resolution:**
+```typescript
+// Resolve branch parameter for IF nodes
+if (operation.branch !== undefined && operation.sourceIndex === undefined) {
+  if (sourceNode?.type === 'n8n-nodes-base.if') {
+    sourceIndex = operation.branch === 'true' ? 0 : 1;
+    // sourceOutput remains 'main'
+  }
+}
+
+// Resolve case parameter for Switch nodes
+if (operation.case !== undefined && operation.sourceIndex === undefined) {
+  sourceIndex = operation.case;
+}
+```
+
+**Real n8n IF Node Structure:**
+```json
+"IF": {
+  "main": [
+    [/* true branch connections, index 0 */],
+    [/* false branch connections, index 1 */]
+  ]
+}
+```
+
+### Migration Guide
+
+**Before (v2.15.7):**
+```typescript
+// Old way: updateConnection (REMOVED)
+{type: "updateConnection", source: "Webhook", target: "Handler", updates: {...}}
+
+// Old way: Multi-output nodes (still works)
+{type: "addConnection", source: "IF", target: "Success", sourceIndex: 0}
+```
+
+**After (v2.16.0):**
+```typescript
+// New way: rewireConnection
+{type: "rewireConnection", source: "Webhook", from: "OldHandler", to: "NewHandler"}
+
+// New way: Smart parameters (recommended)
+{type: "addConnection", source: "IF", target: "Success", branch: "true"}
+{type: "addConnection", source: "IF", target: "Error", branch: "false"}
+{type: "addConnection", source: "Switch", target: "Handler", case: 0}
+```
+
+### Impact Summary
+
+**Production Error Reduction:**
+- Issue #275 fix: -323 errors (-57.4% of total production errors)
+- Helps 127 users (76.5% of users experiencing errors)
+
+**UX Improvements:**
+- Semantic parameters make multi-output node connections intuitive
+- `rewireConnection` provides clear intent for connection changes
+- Integration tests ensure production reliability
+
+**Breaking Changes:**
+- `updateConnection` removed (use `rewireConnection` or manual remove+add)
+
+### References
+
+- **Issue #272**: Connection operations improvements (Phase 0 + Phase 1)
+- **Issue #204**: Differential update failures on Windows
+- **Issue #275**: TypeError in getNodeTypeAlternatives
+- **Issue #136**: Partial Workflow Updates fail with "Cannot convert undefined or null to object" (resolved by defensive type guards)
+- **Commits**:
+  - Phase 0: cfe3c5e, 653f395, 2a85000
+  - Phase 1: f9194ee, ee125c5, a7bfa73, aeaba3b, 34bafe2, c6e0e52, f78f53e
+  - Issue #275/#136: f139d38
+
+## [2.15.7] - 2025-10-05
+
+### Fixed
+
+- **🐛 CRITICAL: Issue #272, #204 - Connection Operations Phase 0 Fixes**
+
+  **Bug #1: Multi-Output Node Routing Broken**
+  - **Problem**: `addConnection` ignored `sourceIndex` parameter due to `||` operator treating `0` as falsy
+  - **Impact**: IF nodes, Switch nodes, and all conditional routing completely broken
+  - **Root Cause**: Used `operation.sourceIndex || 0` instead of `operation.sourceIndex ?? 0`
+  - **Fix**: Changed to nullish coalescing (`??`) operator to properly handle explicit `0` values
+  - **Added**: Defensive array validation before index access
+  - **Result**: Multi-output nodes now work reliably (rating improved 3/10 → 9/10)
+  - **Test Coverage**: 6 comprehensive tests covering IF nodes, Switch nodes, and parallel execution
+
+  **Bug #2: Server Crashes from Missing `updates` Object**
+  - **Problem**: `updateConnection` without `updates` object caused server crash with "Cannot read properties of undefined"
+  - **Impact**: Malformed requests from AI agents crashed the MCP server
+  - **Fix**: Added runtime validation with comprehensive error message
+  - **Error Message Quality**:
+    - Shows what was provided (JSON.stringify of operation)
+    - Explains what's wrong and why
+    - Provides correct format with example
+    - Suggests alternative approach (removeConnection + addConnection)
+  - **Result**: No crashes, self-service troubleshooting enabled (rating improved 2/10 → 8/10)
+  - **Test Coverage**: 2 tests for missing and invalid `updates` object
+
+### Improved
+
+- **Connection Operations Overall Experience**: 4.5/10 → 8.5/10 (+89% improvement)
+- **Error Handling**: Helpful, actionable error messages instead of cryptic crashes
+- **Documentation**: Updated tool docs with Phase 0 fix notes and new pitfall warnings
+- **Developer Experience**: Better use of nullish coalescing, defensive programming patterns
+
+### Test Coverage
+
+- Total Tests: 126/126 passing (100%)
+- New Tests: 8 comprehensive tests for Phase 0 fixes
+- Coverage: 91.16% statements, 88.14% branches, 92.85% functions
+- Test Quality: All edge cases covered, strong assertions, independent test isolation
+
+### Technical Details
+
+**Multi-Output Node Fix:**
+```typescript
+// Before (BROKEN):
+const sourceIndex = operation.sourceIndex || 0;  // 0 treated as falsy!
+
+// After (FIXED):
+const sourceIndex = operation.sourceIndex ?? 0;  // explicit 0 preserved
+```
+
+**Runtime Validation Fix:**
+```typescript
+// Added comprehensive validation:
+if (!operation.updates || typeof operation.updates !== 'object') {
+  throw new Error(/* helpful 15-line error message */);
+}
+```
+
+### References
+
+- Issue #272: Connection operations failing (Polish language issue report)
+- Issue #204: Differential update failures on Windows
+- Analysis Document: `docs/local/connection-operations-deep-dive-and-improvement-plan.md` (2176 lines)
+- Testing: Hands-on validation with n8n-mcp-tester agent
+- Code Review: Comprehensive review against improvement plan
+
+### Phase 1 Roadmap
+
+Phase 0 addressed critical bugs. Future Phase 1 improvements planned:
+- Add `rewireConnection` operation for intuitive connection rewiring
+- Add smart parameters (`branch` for IF nodes, `case` for Switch nodes)
+- Enhanced error messages with spell-checking
+- Deprecation path for `updateConnection`
+
+## [2.15.6] - 2025-10-05
+
+### Fixed
+- **Issue #269: Missing addNode Examples** - Added comprehensive examples for addNode operation in MCP tool documentation
+  - Problem: Claude AI didn't know how to use addNode operation correctly due to zero examples in documentation
+  - Solution: Added 4 progressive examples to `n8n_update_partial_workflow` tool documentation:
+    1. Basic addNode (minimal configuration)
+    2. Complete addNode (full parameters including typeVersion)
+    3. addNode + addConnection combo (most common pattern)
+    4. Batch operation (multiple nodes + connections)
+  - Impact: AI assistants can now correctly use addNode without errors or trial-and-error
+
+- **Issue #270: Apostrophes in Node Names** - Fixed workflow diff operations failing when node names contain special characters
+  - Root Cause: `findNode()` method used exact string matching without normalization, causing escaped vs unescaped character mismatches
+  - Example: Default Manual Trigger node name "When clicking 'Execute workflow'" failed when JSON-RPC sent escaped version "When clicking \\'Execute workflow\\'"
+  - Solution: Added `normalizeNodeName()` helper that unescapes special characters (quotes, backslashes) and normalizes whitespace
+  - Affected Operations: 8 operations fixed - addConnection, removeConnection, updateConnection, removeNode, updateNode, moveNode, enableNode, disableNode
+  - Error Messages: Enhanced all validation methods with `formatNodeNotFoundError()` helper showing available nodes and suggesting node IDs for special characters
+  - Duplicate Prevention: Fixed `validateAddNode()` to use normalization when checking for duplicate node names
+
+### Changed
+- **WorkflowDiffEngine String Normalization** - Enhanced to handle edge cases from code review
+  - Regex Processing Order: Fixed critical bug - now processes backslashes BEFORE quotes (prevents multiply-escaped character failures)
+  - Whitespace Handling: Comprehensive normalization of tabs, newlines, and mixed whitespace (prevents collision edge cases)
+  - Documentation: Added detailed JSDoc warnings about normalization collision risks with examples
+  - Best Practice: Documentation recommends using node IDs over names for special characters
+
+### Technical Details
+- **Normalization Algorithm**: 4-step process
+  1. Trim leading/trailing whitespace
+  2. Unescape backslashes (MUST be first!)
+  3. Unescape single and double quotes
+  4. Normalize all whitespace to single spaces
+- **Error Message Format**: Now shows node IDs (first 8 chars) and suggests using IDs for special characters
+- **Collision Prevention**: Duplicate checking uses same normalization to prevent subtle bugs
+
+### Test Coverage
+- Unit tests: 120/120 passing (up from 116)
+- New test scenarios:
+  - Tabs in node names
+  - Newlines in node names
+  - Mixed whitespace (tabs + newlines + spaces)
+  - Escaped vs unescaped matching (core Issue #270 scenario)
+- Coverage: 90.11% statements (up from 90.05%)
+
+### Code Review
+- All 6 MUST FIX and SHOULD FIX recommendations implemented:
+  - ✅ Fixed regex processing order (critical bug)
+  - ✅ Added comprehensive whitespace tests
+  - ✅ Fixed duplicate checking normalization
+  - ✅ Enhanced all 6 validation method error messages
+  - ✅ Added comprehensive JSDoc documentation
+  - ✅ Added escaped vs unescaped test case
+- Final review: APPROVED FOR MERGE (production-ready)
+
+### Impact
+- **Workflow Operations**: All 8 affected operations now handle special characters correctly
+- **User Experience**: Clear error messages with actionable suggestions
+- **Reliability**: Comprehensive normalization prevents subtle bugs
+- **Documentation**: Tool documentation updated to reflect fix (v2.15.6+)
+
+## [2.15.5] - 2025-10-04
+
+### Added
+- **Phase 5 Integration Tests** - Comprehensive workflow management tests (16 scenarios)
+  - `delete-workflow.test.ts`: 3 test scenarios
+    - Successful deletion
+    - Error handling for non-existent workflows
+    - Cleanup verification (workflow actually deleted from n8n)
+  - `list-workflows.test.ts`: 13 test scenarios
+    - No filters (all workflows)
+    - Filter by active status (true/false)
+    - Pagination (first page, cursor, last page)
+    - Limit variations (1, 50, 100)
+    - Exclude pinned data
+    - Empty results handling
+    - Sort order consistency verification
+
+### Fixed
+- **handleDeleteWorkflow** - Now returns deleted workflow data in response
+  - Before: Returned only success message
+  - After: Returns deleted workflow object per n8n API specification
+  - Impact: MCP tool consumers can access deleted workflow data for confirmation, logging, or undo operations
+
+- **handleListWorkflows Tags Filter** - Fixed tags parameter format for n8n API compliance
+  - Before: Sent tags as array `?tags[]=tag1&tags[]=tag2` (non-functional)
+  - After: Converts to comma-separated string `?tags=tag1,tag2` per n8n OpenAPI spec
+  - Impact: Tags filtering now works correctly when listing workflows
+  - Implementation: `input.tags.join(',')` conversion in handler
+
+- **N8nApiClient.deleteWorkflow** - Return type now matches n8n API specification
+  - Before: `Promise<void>`
+  - After: `Promise<Workflow>` (returns deleted workflow object)
+  - Impact: Aligns with n8n API behavior where DELETE returns the deleted resource
+
+### Changed
+- **WorkflowListParams.tags** - Type changed for API compliance
+  - Before: `tags?: string[] | null` (incorrect)
+  - After: `tags?: string | null` (comma-separated string per n8n OpenAPI spec)
+  - Impact: Type safety now matches actual API behavior
+
+### Technical Details
+- **API Compliance**: All fixes align with n8n OpenAPI specification
+- **Backward Compatibility**: Handler maintains existing MCP tool interface (array input converted internally)
+- **Type Safety**: TypeScript types now accurately reflect n8n API contracts
+
+### Test Coverage
+- Integration tests: 71/71 passing (Phase 1-5 complete)
+- Total test scenarios across all phases: 87
+- New coverage:
+  - Workflow deletion: 3 scenarios
+  - Workflow listing with filters: 13 scenarios
+
+### Impact
+- **DELETE workflows**: Now returns workflow data for verification
+- **List with tags**: Tag filtering now functional (was broken before)
+- **API alignment**: Implementation correctly matches n8n OpenAPI specification
+- **Test reliability**: All integration tests passing in CI
+
+## [2.15.4] - 2025-10-04
+
+### Fixed
+- **Workflow Settings Updates** - Enhanced `cleanWorkflowForUpdate` to enable settings updates while maintaining Issue #248 protection
+  - Changed from always overwriting settings with `{}` to filtering to whitelisted properties
+  - Filters settings to OpenAPI spec whitelisted properties: `saveExecutionProgress`, `saveManualExecutions`, `saveDataErrorExecution`, `saveDataSuccessExecution`, `executionTimeout`, `errorWorkflow`, `timezone`, `executionOrder`
+  - Removes unsafe properties like `callerPolicy` that cause "additional properties" API errors
+  - Maintains backward compatibility: empty object `{}` still used when no settings provided
+  - Resolves conflict between preventing Issue #248 errors and enabling legitimate settings updates
+
+- **Phase 4 Integration Tests** - Fixed workflow update tests to comply with n8n API requirements
+  - Updated all `handleUpdateWorkflow` tests to include required fields: `name`, `nodes`, `connections`, `settings`
+  - Tests now fetch current workflow state before updates to obtain required fields
+  - Removed invalid "Update Connections" test that attempted to set empty connections on multi-node workflow (architecturally invalid)
+  - All 42 workflow update test scenarios now passing
+
+### Changed
+- **Settings Filtering Strategy** - Updated `cleanWorkflowForUpdate()` implementation
+  - Before: Always set `settings = {}` (prevented all settings updates)
+  - After: Filter to whitelisted properties (allows valid updates, blocks problematic ones)
+  - Impact: Users can now update workflow settings via API while staying protected from validation errors
+
+### Technical Details
+- **Whitelist-based Filtering**: Implements principle of least privilege for settings properties
+- **Reference**: Properties validated against n8n OpenAPI specification `workflowSettings` schema
+- **Security**: More secure than blacklist approach (fails safe, unknown properties filtered)
+- **Performance**: Filtering adds <1ms overhead per workflow update
+
+### Test Coverage
+- Unit tests: 72/72 passing (100% coverage for n8n-validation)
+- Integration tests: 433/433 passing (Phase 4 complete)
+- Test scenarios:
+  - Settings filtering with safe/unsafe property combinations
+  - Empty settings handling
+  - Backward compatibility verification
+  - Multi-node workflow connection validation
+
+### Impact
+- **Settings Updates**: Users can now update workflow settings (timezone, executionOrder, etc.) via API
+- **Issue #248 Protection Maintained**: `callerPolicy` and other problematic properties still filtered
+- **Test Reliability**: All Phase 4 integration tests passing in CI
+- **API Compliance**: Tests correctly implement n8n API requirements for workflow updates
+
+## [2.15.3] - 2025-10-03
+
+### Added
+- **Error Message Capture in Telemetry** - Enhanced telemetry tracking to capture actual error messages for better debugging
+  - Added optional `errorMessage` parameter to `trackError()` method
+  - Comprehensive error message sanitization to protect sensitive data
+  - Updated all production and test call sites to pass error messages
+  - Error messages now stored in telemetry events table for analysis
+
+### Security
+- **Enhanced Error Message Sanitization** - Comprehensive security hardening for telemetry data
+  - **ReDoS Prevention**: Early truncation to 1500 chars before regex processing
+  - **Full URL Redaction**: Changed from `[URL]/path` to `[URL]` to prevent API structure leakage
+  - **Correct Sanitization Order**: URLs → specific credentials → emails → generic patterns
+  - **Credential Pattern Detection**: Added AWS keys, GitHub tokens, JWT, Bearer tokens
+  - **Error Handling**: Try-catch wrapper with `[SANITIZATION_FAILED]` fallback
+  - **Stack Trace Truncation**: Limited to first 3 lines to reduce attack surface
+
+### Fixed
+- **Missing Error Messages**: Resolved issue where 272+ weekly validation errors had no error messages captured
+- **Data Leakage**: Fixed URL path preservation exposing API versions and user IDs
+- **Email Exposure**: Fixed sanitization order allowing emails in URLs to leak
+- **ReDoS Vulnerability**: Removed complex capturing regex patterns that could cause performance issues
+
+### Changed
+- **Breaking Change**: `trackError()` signature updated with 4th parameter `errorMessage?: string`
+  - All internal call sites updated in single commit (atomic change)
+  - Not backwards compatible but acceptable as all code is internal
+
+### Technical Details
+- **Sanitization Patterns**:
+  - AWS Keys: `AKIA[A-Z0-9]{16}` → `[AWS_KEY]`
+  - GitHub Tokens: `ghp_[a-zA-Z0-9]{36,}` → `[GITHUB_TOKEN]`
+  - JWT: `eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+` → `[JWT]`
+  - Bearer Tokens: `Bearer [^\s]+` → `Bearer [TOKEN]`
+  - Emails: `[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}` → `[EMAIL]`
+  - Long Keys: `\b[a-zA-Z0-9_-]{32,}\b` → `[KEY]`
+  - Generic Credentials: `password/api_key/token=<value>` → `<field>=[REDACTED]`
+
+### Test Coverage
+- Added 18 new security-focused tests
+- Total telemetry tests: 269 passing
+- Coverage: 90.75% for telemetry module
+- All security patterns validated with edge cases
+
+### Performance
+- Early truncation prevents ReDoS attacks
+- Simplified regex patterns (no complex capturing groups)
+- Sanitization adds <1ms overhead per error
+- Final message truncated to 500 chars max
+
+### Impact
+- **Debugging**: Error messages now available for root cause analysis
+- **Security**: Comprehensive protection against credential leakage
+- **Performance**: Protected against ReDoS attacks
+- **Reliability**: Try-catch ensures sanitization never breaks telemetry
+
+## [2.15.2] - 2025-10-03
+
+### Fixed
+- **Template Search Performance & Reliability** - Enhanced `search_templates_by_metadata` with production-ready improvements
+  - **Ordering Stability**: Implemented CTE with VALUES clause to preserve exact Phase 1 ordering
+    - Prevents ordering discrepancies between ID selection and data fetch phases
+    - Ensures deterministic results across query phases
+  - **Defensive ID Validation**: Added type safety filters before Phase 2 query
+    - Validates only positive integers are used in the CTE
+    - Logs warnings for filtered invalid IDs
+  - **Performance Monitoring**: Added detailed timing metrics (phase1Ms, phase2Ms, totalMs)
+    - Enables quantifying optimization benefits
+    - Debug logging for all search operations
+  - **DRY Refactoring**: Extracted `buildMetadataFilterConditions` helper method
+    - Eliminates duplication between `searchTemplatesByMetadata` and `getMetadataSearchCount`
+    - Centralized filter-building logic
+
+### Added
+- **Comprehensive Test Coverage** - 31 new unit tests achieving 100% coverage for changed code
+  - `buildMetadataFilterConditions` - All filter combinations (11 tests)
+  - Performance logging validation (3 tests)
+  - ID filtering edge cases - negative, zero, non-integer, null (7 tests)
+  - `getMetadataSearchCount` - Shared helper usage (7 tests)
+  - Two-phase query optimization verification (3 tests)
+- Fixed flaky integration tests with deterministic ordering using unique view counts
+
+### Performance
+- Query optimization maintains sub-1ms Phase 1 performance
+- Two-phase approach prevents timeout on large template sets
+- CTE-based ordering adds negligible overhead (<1ms)
+
+### Test Results
+- Unit tests: 31 new tests, all passing
+- Integration tests: 36 passing, 1 skipped
+- **Coverage**: 100% for changed code (previously 36.58% patch coverage)
+
+## [2.15.0] - 2025-10-02
+
+### 🚀 Major Features
+
+#### P0-R3: Pre-extracted Template Configurations
+- **Template-Based Configuration System** - 2,646 real-world node configurations from popular templates
+  - Pre-extracted node configurations from all workflow templates
+  - Ranked by template popularity (views)
+  - Includes metadata: complexity, use cases, credentials, expressions
+  - Query performance: <1ms (vs 30-60ms with previous system)
+  - Database size increase: ~513 KB for 2,000+ configurations
+
+### Breaking Changes
+
+#### Removed: `get_node_for_task` Tool
+- **Reason**: Only 31 hardcoded tasks, 28% failure rate in production
+- **Replacement**: Template-based examples with 2,646 real configurations
+
+#### Migration Guide
+
+**Before (v2.14.7):**
+```javascript
+// Get configuration for a task
+get_node_for_task({ task: "receive_webhook" })
+```
+
+**After (v2.15.0):**
+```javascript
+// Option 1: Search nodes with examples
+search_nodes({
+  query: "webhook",
+  includeExamples: true
+})
+// Returns: Top 2 real template configs per node
+
+// Option 2: Get node essentials with examples
+get_node_essentials({
+  nodeType: "nodes-base.webhook",
+  includeExamples: true
+})
+// Returns: Top 3 real template configs with full metadata
+```
+
+### Added
+
+- **Enhanced `search_nodes` Tool**
+  - New parameter: `includeExamples` (boolean, default: false)
+  - Returns top 2 real-world configurations per node from popular templates
+  - Includes: configuration, template name, view count
+
+- **Enhanced `get_node_essentials` Tool**
+  - New parameter: `includeExamples` (boolean, default: false)
+  - Returns top 3 real-world configurations with full metadata
+  - Includes: configuration, source template, complexity, use cases, credentials info
+
+- **Database Schema**
+  - New table: `template_node_configs` - Pre-extracted node configurations
+  - New view: `ranked_node_configs` - Easy access to top 5 configs per node
+  - Optimized indexes for fast queries (<1ms)
+
+- **Template Processing**
+  - Automatic config extraction during `npm run fetch:templates`
+  - Standalone extraction mode: `npm run fetch:templates:extract`
+  - Expression detection ({{...}}, $json, $node)
+  - Complexity analysis and use case extraction
+  - Ranking by template popularity
+  - Auto-creates `template_node_configs` table if missing
+
+- **Comprehensive Test Suite**
+  - 85+ tests covering all aspects of template configuration system
+  - Integration tests for database operations and end-to-end workflows
+  - Unit tests for tool parameters, extraction logic, and ranking algorithm
+  - Fixtures for consistent test data across test suites
+  - Test documentation in P0-R3-TEST-PLAN.md
+
+### Removed
+
+- Tool: `get_node_for_task` (see Breaking Changes above)
+- Tool documentation: `get-node-for-task.ts`
+
+### Fixed
+
+- **`search_nodes` includeExamples Support**
+  - Fixed `includeExamples` parameter not working due to missing FTS5 table
+  - Added example support to `searchNodesLIKE` fallback method
+  - Now returns template-based examples in all search scenarios
+  - Affects 100% of search_nodes calls (database lacks nodes_fts table)
+
+### Deprecated
+
+- `TaskTemplates` service marked for removal in v2.16.0
+- `list_tasks` tool marked for deprecation (use template search instead)
+
+### Performance
+
+- Query time: <1ms for pre-extracted configs (vs 30-60ms for on-demand generation)
+- 30-60x faster configuration lookups
+- 85x more configuration examples (2,646 vs 31)
+
+## [2.14.7] - 2025-10-02
+
+### Fixed
+- **Issue #248: Settings Validation Error** - Fixed "settings must NOT have additional properties" API errors
+  - Added `callerPolicy` property to `workflowSettingsSchema` to support valid n8n workflow setting
+  - Implemented whitelist-based settings filtering in `cleanWorkflowForUpdate()` to prevent API errors
+  - Filter removes UI-only properties (e.g., `timeSavedPerExecution`) that cause validation failures
+  - Only whitelisted properties are sent to n8n API: `executionOrder`, `timezone`, `saveDataErrorExecution`, `saveDataSuccessExecution`, `saveManualExecutions`, `saveExecutionProgress`, `executionTimeout`, `errorWorkflow`, `callerPolicy`
+  - Resolves workflow update failures caused by workflows fetched from n8n containing non-standard properties
+  - Added 6 comprehensive unit tests covering settings filtering scenarios
+
+- **Issue #249: Misleading AddConnection Error Messages** - Enhanced parameter validation with helpful error messages
+  - Detect common parameter mistakes: using `sourceNodeId`/`targetNodeId` instead of correct `source`/`target`
+  - Improved error messages include:
+    - Identification of wrong parameter names with correction guidance
+    - Examples of correct usage
+    - List of available nodes when source/target not found
+  - Error messages now actionable instead of cryptic (was: "Source node not found: undefined")
+  - Added 8 comprehensive unit tests for parameter validation scenarios
+
+- **P0-R1: Universal Node Type Normalization** - Eliminates 80% of validation errors
+  - Implemented `NodeTypeNormalizer` utility for consistent node type handling
+  - Automatically converts short forms to full forms (e.g., `nodes-base.webhook` → `n8n-nodes-base.webhook`)
+  - Applied normalization across all workflow validation entry points
+  - Updated workflow validator, handlers, and repository for universal normalization
+  - Fixed test expectations to match normalized node type format
+  - Resolves the single largest source of validation errors in production
+
+### Added
+- `NodeTypeNormalizer` utility class for universal node type normalization
+  - `normalizeToFullForm()` - Convert any node type variation to canonical form
+  - `normalizeWithDetails()` - Get normalization result with metadata
+  - `normalizeWorkflowNodeTypes()` - Batch normalize all nodes in a workflow
+- Settings whitelist filtering in `cleanWorkflowForUpdate()` with comprehensive null-safety
+- Enhanced `validateAddConnection()` with proactive parameter validation
+- 14 new unit tests for issues #248 and #249 fixes
+
+### Changed
+- Node repository now uses `NodeTypeNormalizer` for all lookups
+- Workflow validation applies normalization before structure checks
+- Workflow diff engine validates connection parameters before processing
+- Settings filtering applied to all workflow update operations
+
+### Performance
+- No performance impact - normalization adds <1ms overhead per workflow
+- Settings filtering is O(9) - negligible impact
+
+### Test Coverage
+- n8n-validation tests: 73/73 passing (100% coverage)
+- workflow-diff-engine tests: 110/110 passing (89.72% coverage)
+- Total: 183 tests passing
+
+### Impact
+- **Issue #248**: Eliminates ALL settings validation errors for workflows with non-standard properties
+- **Issue #249**: Provides clear, actionable error messages reducing user frustration
+- **P0-R1**: Reduces validation error rate by 80% (addresses 4,800+ weekly errors)
+- Combined impact: Expected overall error rate reduction from 5-10% to <2%
+
+## [2.14.6] - 2025-10-01
+
+### Enhanced
+- **Webhook Error Messages**: Replaced generic "Please try again later or contact support" messages with actionable guidance
+  - Error messages now extract execution ID and workflow ID from failed webhook triggers
+  - Guide users to use `n8n_get_execution({id: executionId, mode: 'preview'})` for efficient debugging
+  - Format: "Workflow {workflowId} execution {executionId} failed. Use n8n_get_execution({id: '{executionId}', mode: 'preview'}) to investigate the error."
+  - When no execution ID available: "Workflow failed to execute. Use n8n_list_executions to find recent executions, then n8n_get_execution with mode='preview' to investigate."
+
+### Added
+- New error formatting functions in `n8n-errors.ts`:
+  - `formatExecutionError()` - Creates execution-specific error messages with debugging guidance
+  - `formatNoExecutionError()` - Provides guidance when execution context unavailable
+- Enhanced `McpToolResponse` type with optional `executionId` and `workflowId` fields
+- Error handling documentation in `n8n-trigger-webhook-workflow` tool docs
+- 30 new comprehensive tests for error message formatting and webhook error handling
+
+### Changed
+- `handleTriggerWebhookWorkflow` now extracts execution context from error responses
+- `getUserFriendlyErrorMessage` returns actual server error messages instead of generic text
+- Tool documentation type enhanced with optional `errorHandling` field
+
+### Fixed
+- Test expectations updated to match new error message format (handlers-workflow-diff.test.ts)
+
+### Benefits
+- **Fast debugging**: Preview mode executes in <50ms (vs seconds for full data)
+- **Efficient**: Uses ~500 tokens (vs 50K+ tokens for full execution data)
+- **Safe**: No timeout or token limit risks
+- **Actionable**: Clear next steps for users to investigate failures
+
+### Impact
+- Eliminates unhelpful "contact support" messages
+- Provides specific, actionable debugging guidance
+- Reduces debugging time by directing users to efficient tools
+- 100% backward compatible - only improves error messages
+
+## [2.14.5] - 2025-09-30
+
+### Added
+- **Intelligent Execution Data Filtering**: Major enhancement to `n8n_get_execution` tool to handle large datasets without exceeding token limits
+  - **Preview Mode**: Shows data structure, counts, and size estimates without actual data (~500 tokens)
+  - **Summary Mode**: Returns 2 sample items per node (safe default, ~2-5K tokens)
+  - **Filtered Mode**: Granular control with node filtering and custom item limits
+  - **Full Mode**: Complete data retrieval (explicit opt-in)
+  - Smart recommendations based on data size (guides optimal retrieval strategy)
+  - Structure-only mode (`itemsLimit: 0`) to see data schema without values
+  - Node-specific filtering with `nodeNames` parameter
+  - Input data inclusion option for debugging transformations
+  - Automatic size estimation and token consumption guidance
+
+### Enhanced
+- `n8n_get_execution` tool with new parameters:
+  - `mode`: 'preview' | 'summary' | 'filtered' | 'full'
+  - `nodeNames`: Filter to specific nodes
+  - `itemsLimit`: Control items per node (0=structure, -1=unlimited, default=2)
+  - `includeInputData`: Include input data for debugging
+  - Legacy `includeData` parameter mapped to new modes for backward compatibility
+- Tool documentation with comprehensive examples and best practices
+- Type system with new interfaces: `ExecutionMode`, `ExecutionPreview`, `ExecutionFilterOptions`, `FilteredExecutionResponse`
+
+### Technical Improvements
+- New `ExecutionProcessor` service with intelligent filtering logic
+- Smart data truncation with metadata (`hasMoreData`, `truncated` flags)
+- Validation for `itemsLimit` (capped at 1000, negative values default to 2)
+- Error message extraction helper for consistent error handling
+- Constants-based thresholds for easy tuning (20/50/100KB limits)
+- 33 comprehensive unit tests with 78% coverage
+- Null-safe data access throughout
+
+### Performance
+- Preview mode: <50ms (no data, just structure)
+- Summary mode: <200ms (2 items per node)
+- Filtered mode: 50-500ms (depends on filters)
+- Size estimation within 10-20% accuracy
+
+### Impact
+- Solves token limit issues when inspecting large workflow executions
+- Enables AI agents to understand execution data without overwhelming responses
+- Reduces token usage by 80-95% for large datasets (50+ items)
+- Maintains 100% backward compatibility with existing integrations
+- Recommended workflow: preview → recommendation → filtered/summary
+
+### Fixed
+- Preview mode bug: Fixed API data fetching logic to ensure preview mode retrieves execution data for structure analysis and recommendation generation
+  - Changed `fetchFullData` condition in handlers-n8n-manager.ts to include preview mode
+  - Preview mode now correctly returns structure, item counts, and size estimates
+  - Recommendations are now accurate and prevent token overflow issues
+
+### Migration Guide
+- **No breaking changes**: Existing `n8n_get_execution` calls work unchanged
+- New recommended workflow:
+  1. Call with `mode: 'preview'` to assess data size
+  2. Follow `recommendation.suggestedMode` from preview
+  3. Use `mode: 'filtered'` with `itemsLimit` for precise control
+- Legacy `includeData: true` now maps to `mode: 'summary'` (safer default)
+
+## [2.14.4] - 2025-09-30
+
+### Added
+- **Workflow Cleanup Operations**: Two new operations for `n8n_update_partial_workflow`
+  - `cleanStaleConnections`: Automatically removes connections referencing non-existent nodes
+  - `replaceConnections`: Replace entire connections object in a single operation
+- **Graceful Error Handling**: Enhanced `removeConnection` with `ignoreErrors` flag
+- **Best-Effort Mode**: New `continueOnError` mode for `WorkflowDiffRequest`
+  - Apply valid operations even if some fail
+  - Returns detailed results with `applied` and `failed` operation indices
+  - Maintains atomic mode as default for safety
+
+### Enhanced
+- Tool documentation for workflow cleanup scenarios
+- Type system with new operation interfaces
+- 15 new tests covering all new features
+
+### Impact
+- Reduces broken workflow fix time from 10-15 minutes to 30 seconds
+- Token efficiency: `cleanStaleConnections` is 1 operation vs 10+ manual operations
+- 100% backwards compatibility maintained
+
+## [2.14.3] - 2025-09-30
+
+### Added
+- Incremental template updates with `npm run fetch:templates:update`
+- Smart filtering for new templates (5-10 min vs 30-40 min full rebuild)
+- 48 new templates (2,598 → 2,646 total)
+
+### Fixed
+- Template metadata generation: Updated to `gpt-4o-mini-2025-08-07` model
+- Removed unsupported `temperature` parameter from OpenAI Batch API
+- Template sanitization: Added Airtable PAT and GitHub token detection
+- Sanitized 24 templates removing API tokens
+
+### Updated
+- n8n: 1.112.3 → 1.113.3
+- n8n-core: 1.111.0 → 1.112.1
+- n8n-workflow: 1.109.0 → 1.110.0
+- @n8n/n8n-nodes-langchain: 1.111.1 → 1.112.2
+- Node database rebuilt with 536 nodes from n8n v1.113.3
+
+## [2.14.2] - 2025-09-29
+
+### Fixed
+- Validation false positives for Google Drive nodes with 'fileFolder' resource
+  - Added node type normalization to handle both `n8n-nodes-base.` and `nodes-base.` prefixes correctly
+  - Fixed resource validation to properly recognize all valid resource types
+  - Default operations are now properly applied when not specified
+  - Property visibility is now correctly checked with defaults applied
+- Code node validation incorrectly flagging valid n8n expressions as syntax errors
+  - Removed overly aggressive regex pattern `/\)\s*\)\s*{/` that flagged valid expressions
+  - Valid patterns like `$('NodeName').first().json` are now correctly recognized
+  - Function chaining and method chaining no longer trigger false positives
+- Enhanced error handling in repository methods based on code review feedback
+  - Added try-catch blocks to `getNodePropertyDefaults` and `getDefaultOperationForResource`
+  - Validates data structures before accessing to prevent crashes with malformed node data
+  - Returns safe defaults on errors to ensure validation continues
+
+### Added
+- Comprehensive test coverage for validation fixes in `tests/unit/services/validation-fixes.test.ts`
+- New repository methods for better default value handling:
+  - `getNodePropertyDefaults()` - retrieves default values for node properties
+  - `getDefaultOperationForResource()` - gets default operation for a specific resource
+
+### Changed
+- Enhanced `filterPropertiesByMode` to return both filtered properties and config with defaults applied
+- Improved node type validation to accept both valid prefix formats
+
+## [2.14.1] - 2025-09-26
+
+### Changed
+- **BREAKING**: Refactored telemetry system with major architectural improvements
+  - Split 636-line TelemetryManager into 7 focused modules (event-tracker, batch-processor, event-validator, rate-limiter, circuit-breaker, workflow-sanitizer, config-manager)
+  - Changed TelemetryManager constructor to private, use `getInstance()` method now
+  - Implemented lazy initialization pattern to avoid early singleton creation
+
+### Added
+- Security & Privacy enhancements for telemetry:
+  - Comprehensive input validation with Zod schemas
+  - Enhanced sanitization of sensitive data (URLs, API keys, emails)
+  - Expanded sensitive key detection patterns (25+ patterns)
+  - Row Level Security on Supabase backend
+  - Data deletion contact info (romuald@n8n-mcp.com)
+- Performance & Reliability improvements:
+  - Sliding window rate limiter (100 events/minute)
+  - Circuit breaker pattern for network failures
+  - Dead letter queue for failed events
+  - Exponential backoff with jitter for retries
+  - Performance monitoring with overhead tracking (<5%)
+  - Memory-safe array limits in rate limiter
+- Comprehensive test coverage enhancements:
+  - Added 662 lines of new telemetry tests
+  - Enhanced config-manager tests with 17 new edge cases
+  - Enhanced workflow-sanitizer tests with 19 new edge cases
+  - Improved coverage from 63% to 91% for telemetry module
+  - Branch coverage improved from 69% to 87%
+
+### Fixed
+- TypeScript lint errors in telemetry test files
+  - Corrected variable name conflicts in integration tests
+  - Fixed process.exit mock implementation in batch-processor tests
+  - Fixed tuple type annotations for workflow node positions
+  - Resolved MockInstance type import issues
+- Test failures in CI pipeline
+  - Fixed test timeouts caused by improper fake timer usage
+  - Resolved Timer.unref() compatibility issues
+  - Fixed event validator filtering standalone 'key' property
+  - Corrected batch processor circuit breaker behavior
+- TypeScript error in telemetry test preventing CI build
+- Added @supabase/supabase-js to Docker builder stage and runtime dependencies
+
 ## [2.14.0] - 2025-09-26
 
 ### Added

MEMORY_TEMPLATE_UPDATE.md

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

P0-R3-TEST-PLAN.md

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

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-1728%20passing-brightgreen.svg)](https://github.com/czlonkowski/n8n-mcp/actions)
-[![n8n version](https://img.shields.io/badge/n8n-^1.112.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.113.3-orange.svg)](https://github.com/n8n-io/n8n)
 [![Docker](https://img.shields.io/badge/docker-ghcr.io%2Fczlonkowski%2Fn8n--mcp-green.svg)](https://github.com/czlonkowski/n8n-mcp/pkgs/container/n8n-mcp)
 [![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/n8n-mcp?referralCode=n8n-mcp)
 
@@ -20,6 +20,8 @@ n8n-MCP serves as a bridge between n8n's workflow automation platform and AI mod
 - ⚡ **Node operations** - 63.6% coverage of available actions
 - 📄 **Documentation** - 90% coverage from official n8n docs (including AI nodes)
 - 🤖 **AI tools** - 263 AI-capable nodes detected with full documentation
+- 💡 **Real-world examples** - 2,646 pre-extracted configurations from popular templates
+- 🎯 **Template library** - 2,500+ workflow templates with smart filtering
 
 
 ## ⚠️ Important Safety Warning
@@ -397,180 +399,260 @@ 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 Workflow Process
+## Core Principles
 
-1. **ALWAYS start new conversation with**: `tools_documentation()` to understand best practices and available tools.
+### 1. Silent Execution
+CRITICAL: Execute tools without commentary. Only respond AFTER all tools complete.
 
-2. **Template Discovery Phase** 
-   - `search_templates_by_metadata({complexity: "simple"})` - Find skill-appropriate templates
-   - `get_templates_for_task('webhook_processing')` - Get curated templates by task
-   - `search_templates('slack notification')` - Text search for specific needs. Start by quickly searching with "id" and "name" to find the template you are looking for, only then dive deeper into the template details adding "description" to your search query.
-   - `list_node_templates(['n8n-nodes-base.slack'])` - Find templates using specific nodes
-   
-   **Template filtering strategies**:
-   - **For beginners**: `complexity: "simple"` and `maxSetupMinutes: 30`
-   - **By role**: `targetAudience: "marketers"` or `"developers"` or `"analysts"`
-   - **By time**: `maxSetupMinutes: 15` for quick wins
-   - **By service**: `requiredService: "openai"` to find compatible templates
+❌ BAD: "Let me search for Slack nodes... Great! Now let me get details..."
+✅ GOOD: [Execute search_nodes and get_node_essentials in parallel, then respond]
 
-3. **Discovery Phase** - Find the right nodes (if no suitable template):
-   - Think deeply about user request and the logic you are going to build to fulfill it. Ask follow-up questions to clarify the user's intent, if something is unclear. Then, proceed with the rest of your instructions.
-   - `search_nodes({query: 'keyword'})` - Search by functionality
+### 2. Parallel Execution
+When operations are independent, execute them in parallel for maximum performance.
+
+✅ GOOD: Call search_nodes, list_nodes, and search_templates simultaneously
+❌ BAD: Sequential tool calls (await each one before the next)
+
+### 3. Templates First
+ALWAYS check templates before building from scratch (2,500+ available).
+
+### 4. Multi-Level Validation
+Use validate_node_minimal → validate_node_operation → validate_workflow pattern.
+
+### 5. Never Trust Defaults
+⚠️ CRITICAL: Default parameter values are the #1 source of runtime failures.
+ALWAYS explicitly configure ALL parameters that control node behavior.
+
+## Workflow Process
+
+1. **Start**: Call `tools_documentation()` for best practices
+
+2. **Template Discovery Phase** (FIRST - parallel when searching multiple)
+   - `search_templates_by_metadata({complexity: "simple"})` - Smart filtering
+   - `get_templates_for_task('webhook_processing')` - Curated by task
+   - `search_templates('slack notification')` - Text search
+   - `list_node_templates(['n8n-nodes-base.slack'])` - By node type
+
+   **Filtering strategies**:
+   - Beginners: `complexity: "simple"` + `maxSetupMinutes: 30`
+   - By role: `targetAudience: "marketers"` | `"developers"` | `"analysts"`
+   - By time: `maxSetupMinutes: 15` for quick wins
+   - By service: `requiredService: "openai"` for compatibility
+
+3. **Node Discovery** (if no suitable template - parallel execution)
+   - Think deeply about requirements. Ask clarifying questions if unclear.
+   - `search_nodes({query: 'keyword', includeExamples: true})` - Parallel for multiple nodes
    - `list_nodes({category: 'trigger'})` - Browse by category
-   - `list_ai_tools()` - See AI-capable nodes (remember: ANY node can be an AI tool!)
+   - `list_ai_tools()` - AI-capable nodes
 
-4. **Configuration Phase** - Get node details efficiently:
-   - `get_node_essentials(nodeType)` - Start here! Only 10-20 essential properties
+4. **Configuration Phase** (parallel for multiple nodes)
+   - `get_node_essentials(nodeType, {includeExamples: true})` - 10-20 key properties
    - `search_node_properties(nodeType, 'auth')` - Find specific properties
-   - `get_node_for_task('send_email')` - Get pre-configured templates
-   - `get_node_documentation(nodeType)` - Human-readable docs when needed
-   - It is good common practice to show a visual representation of the workflow architecture to the user and asking for opinion, before moving forward. 
+   - `get_node_documentation(nodeType)` - Human-readable docs
+   - Show workflow architecture to user for approval before proceeding
 
-5. **Pre-Validation Phase** - Validate BEFORE building:
+5. **Validation Phase** (parallel for multiple nodes)
    - `validate_node_minimal(nodeType, config)` - Quick required fields check
-   - `validate_node_operation(nodeType, config, profile)` - Full operation-aware validation
-   - Fix any validation errors before proceeding
+   - `validate_node_operation(nodeType, config, 'runtime')` - Full validation with fixes
+   - Fix ALL errors before proceeding
 
-6. **Building Phase** - Create or customize the workflow:
+6. **Building Phase**
    - If using template: `get_template(templateId, {mode: "full"})`
-   - **MANDATORY ATTRIBUTION**: When using a template, ALWAYS inform the user:
-     - "This workflow is based on a template by **[author.name]** (@[author.username])"
-     - "View the original template at: [url]"
-     - Example: "This workflow is based on a template by **David Ashby** (@cfomodz). View the original at: https://n8n.io/workflows/2414"
-   - Customize template or build from validated configurations
+   - **MANDATORY ATTRIBUTION**: "Based on template by **[author.name]** (@[username]). View at: [url]"
+   - Build from validated configurations
+   - ⚠️ EXPLICITLY set ALL parameters - never rely on defaults
    - Connect nodes with proper structure
-   - Add error handling where appropriate
-   - Use expressions like $json, $node["NodeName"].json
-   - Build the workflow in an artifact for easy editing downstream (unless the user asked to create in n8n instance)
+   - Add error handling
+   - Use n8n expressions: $json, $node["NodeName"].json
+   - Build in artifact (unless deploying to n8n instance)
 
-7. **Workflow Validation Phase** - Validate complete workflow:
-   - `validate_workflow(workflow)` - Complete validation including connections
-   - `validate_workflow_connections(workflow)` - Check structure and AI tool connections
-   - `validate_workflow_expressions(workflow)` - Validate all n8n expressions
-   - Fix any issues found before deployment
+7. **Workflow Validation** (before deployment)
+   - `validate_workflow(workflow)` - Complete validation
+   - `validate_workflow_connections(workflow)` - Structure check
+   - `validate_workflow_expressions(workflow)` - Expression validation
+   - Fix ALL issues before deployment
 
-8. **Deployment Phase** (if n8n API configured):
-   - `n8n_create_workflow(workflow)` - Deploy validated workflow
-   - `n8n_validate_workflow({id: 'workflow-id'})` - Post-deployment validation
-   - `n8n_update_partial_workflow()` - Make incremental updates using diffs
-   - `n8n_trigger_webhook_workflow()` - Test webhook workflows
+8. **Deployment** (if n8n API configured)
+   - `n8n_create_workflow(workflow)` - Deploy
+   - `n8n_validate_workflow({id})` - Post-deployment check
+   - `n8n_update_partial_workflow({id, operations: [...]})` - Batch updates
+   - `n8n_trigger_webhook_workflow()` - Test webhooks
 
-## Key Insights
+## Critical Warnings
 
-- **TEMPLATES FIRST** - Always check for existing templates before building from scratch (2,500+ available!)
-- **ATTRIBUTION REQUIRED** - Always credit template authors with name, username, and link to n8n.io
-- **SMART FILTERING** - Use metadata filters to find templates matching user skill level and time constraints
-- **USE CODE NODE ONLY WHEN IT IS NECESSARY** - always prefer to use standard nodes over code node. Use code node only when you are sure you need it.
-- **VALIDATE EARLY AND OFTEN** - Catch errors before they reach deployment
-- **USE DIFF UPDATES** - Use n8n_update_partial_workflow for 80-90% token savings
-- **ANY node can be an AI tool** - not just those with usableAsTool=true
-- **Pre-validate configurations** - Use validate_node_minimal before building
-- **Post-validate workflows** - Always validate complete workflows before deployment
-- **Incremental updates** - Use diff operations for existing workflows
-- **Test thoroughly** - Validate both locally and after deployment to n8n
+### ⚠️ Never Trust Defaults
+Default values cause runtime failures. Example:
+```json
+// ❌ FAILS at runtime
+{resource: "message", operation: "post", text: "Hello"}
+
+// ✅ WORKS - all parameters explicit
+{resource: "message", operation: "post", select: "channel", channelId: "C123", text: "Hello"}
+```
+
+### ⚠️ Example Availability
+`includeExamples: true` returns real configurations from workflow templates.
+- Coverage varies by node popularity
+- When no examples available, use `get_node_essentials` + `validate_node_minimal`
 
 ## Validation Strategy
 
-### Before Building:
-1. validate_node_minimal() - Check required fields
-2. validate_node_operation() - Full configuration validation
-3. Fix all errors before proceeding
+### Level 1 - Quick Check (before building)
+`validate_node_minimal(nodeType, config)` - Required fields only (<100ms)
 
-### After Building:
-1. validate_workflow() - Complete workflow validation
-2. validate_workflow_connections() - Structure validation
-3. validate_workflow_expressions() - Expression syntax check
+### Level 2 - Comprehensive (before building)
+`validate_node_operation(nodeType, config, 'runtime')` - Full validation with fixes
 
-### After Deployment:
-1. n8n_validate_workflow({id}) - Validate deployed workflow
-2. n8n_autofix_workflow({id}) - Auto-fix common errors (expressions, typeVersion, webhooks)
-3. n8n_list_executions() - Monitor execution status
-4. n8n_update_partial_workflow() - Fix issues using diffs
+### Level 3 - Complete (after building)
+`validate_workflow(workflow)` - Connections, expressions, AI tools
 
-## Response Structure
+### Level 4 - Post-Deployment
+1. `n8n_validate_workflow({id})` - Validate deployed workflow
+2. `n8n_autofix_workflow({id})` - Auto-fix common errors
+3. `n8n_list_executions()` - Monitor execution status
 
-1. **Discovery**: Show available nodes and options
-2. **Pre-Validation**: Validate node configurations first
-3. **Configuration**: Show only validated, working configs
-4. **Building**: Construct workflow with validated components
-5. **Workflow Validation**: Full workflow validation results
-6. **Deployment**: Deploy only after all validations pass
-7. **Post-Validation**: Verify deployment succeeded
+## Response Format
+
+### Initial Creation
+```
+[Silent tool execution in parallel]
+
+Created workflow:
+- Webhook trigger → Slack notification
+- Configured: POST /webhook → #general channel
+
+Validation: ✅ All checks passed
+```
+
+### Modifications
+```
+[Silent tool execution]
+
+Updated workflow:
+- Added error handling to HTTP node
+- Fixed required Slack parameters
+
+Changes validated successfully.
+```
+
+## Batch Operations
+
+Use `n8n_update_partial_workflow` with multiple operations in a single call:
+
+✅ GOOD - Batch multiple operations:
+```json
+n8n_update_partial_workflow({
+  id: "wf-123",
+  operations: [
+    {type: "updateNode", nodeId: "slack-1", changes: {...}},
+    {type: "updateNode", nodeId: "http-1", changes: {...}},
+    {type: "cleanStaleConnections"}
+  ]
+})
+```
+
+❌ BAD - Separate calls:
+```json
+n8n_update_partial_workflow({id: "wf-123", operations: [{...}]})
+n8n_update_partial_workflow({id: "wf-123", operations: [{...}]})
+```
 
 ## Example Workflow
 
-### Smart Template-First Approach
+### Template-First Approach
 
-#### 1. Find existing templates
-// Find simple Slack templates for marketers
-const templates = search_templates_by_metadata({
+```
+// STEP 1: Template Discovery (parallel execution)
+[Silent execution]
+search_templates_by_metadata({
   requiredService: 'slack',
   complexity: 'simple',
-  targetAudience: 'marketers',
-  maxSetupMinutes: 30
+  targetAudience: 'marketers'
 })
-
-// Or search by text
-search_templates('slack notification')
-
-// Or get curated templates
 get_templates_for_task('slack_integration')
 
-#### 2. Use and customize template
-const workflow = get_template(templates.items[0].id, {mode: 'full'})
+// STEP 2: Use template
+get_template(templateId, {mode: 'full'})
 validate_workflow(workflow)
 
-### Building from Scratch (if no suitable template)
+// Response after all tools complete:
+"Found template by **David Ashby** (@cfomodz).
+View at: https://n8n.io/workflows/2414
 
-#### 1. Discovery & Configuration
-search_nodes({query: 'slack'})
-get_node_essentials('n8n-nodes-base.slack')
+Validation: ✅ All checks passed"
+```
 
-#### 2. Pre-Validation
-validate_node_minimal('n8n-nodes-base.slack', {resource:'message', operation:'send'})
+### Building from Scratch (if no template)
+
+```
+// STEP 1: Discovery (parallel execution)
+[Silent execution]
+search_nodes({query: 'slack', includeExamples: true})
+list_nodes({category: 'communication'})
+
+// STEP 2: Configuration (parallel execution)
+[Silent execution]
+get_node_essentials('n8n-nodes-base.slack', {includeExamples: true})
+get_node_essentials('n8n-nodes-base.webhook', {includeExamples: true})
+
+// STEP 3: Validation (parallel execution)
+[Silent execution]
+validate_node_minimal('n8n-nodes-base.slack', config)
 validate_node_operation('n8n-nodes-base.slack', fullConfig, 'runtime')
 
-#### 3. Build Workflow
-// Create workflow JSON with validated configs
+// STEP 4: Build
+// Construct workflow with validated configs
+// ⚠️ Set ALL parameters explicitly
 
-#### 4. Workflow Validation
+// STEP 5: Validate
+[Silent execution]
 validate_workflow(workflowJson)
-validate_workflow_connections(workflowJson)
-validate_workflow_expressions(workflowJson)
 
-#### 5. Deploy (if configured)
-n8n_create_workflow(validatedWorkflow)
-n8n_validate_workflow({id: createdWorkflowId})
+// Response after all tools complete:
+"Created workflow: Webhook → Slack
+Validation: ✅ Passed"
+```
 
-#### 6. Update Using Diffs
+### Batch Updates
+
+```json
+// ONE call with multiple operations
 n8n_update_partial_workflow({
-  workflowId: id,
+  id: "wf-123",
   operations: [
-    {type: 'updateNode', nodeId: 'slack1', changes: {position: [100, 200]}}
+    {type: "updateNode", nodeId: "slack-1", changes: {position: [100, 200]}},
+    {type: "updateNode", nodeId: "http-1", changes: {position: [300, 200]}},
+    {type: "cleanStaleConnections"}
   ]
 })
+```
 
 ## Important Rules
 
-- ALWAYS check for existing templates before building from scratch
-- LEVERAGE metadata filters to find skill-appropriate templates
-- **ALWAYS ATTRIBUTE TEMPLATES**: When using any template, you MUST share the author's name, username, and link to the original template on n8n.io
-- VALIDATE templates before deployment (they may need updates)
-- USE diff operations for updates (80-90% token savings)
-- STATE validation results clearly
-- FIX all errors before proceeding
+### Core Behavior
+1. **Silent execution** - No commentary between tools
+2. **Parallel by default** - Execute independent operations simultaneously
+3. **Templates first** - Always check before building (2,500+ available)
+4. **Multi-level validation** - Quick check → Full validation → Workflow validation
+5. **Never trust defaults** - Explicitly configure ALL parameters
 
-## Template Discovery Tips
+### Attribution & Credits
+- **MANDATORY TEMPLATE ATTRIBUTION**: Share author name, username, and n8n.io link
+- **Template validation** - Always validate before deployment (may need updates)
 
-- **97.5% of templates have metadata** - Use smart filtering!
-- **Filter combinations work best** - Combine complexity + setup time + service
-- **Templates save 70-90% development time** - Always check first
-- **Metadata is AI-generated** - Occasionally imprecise but highly useful
-- **Use `includeMetadata: false` for fast browsing** - Add metadata only when needed
-```
+### Performance
+- **Batch operations** - Use diff operations with multiple changes in one call
+- **Parallel execution** - Search, validate, and configure simultaneously
+- **Template metadata** - Use smart filtering for faster discovery
+
+### Code Node Usage
+- **Avoid when possible** - Prefer standard nodes
+- **Only when necessary** - Use code node as last resort
+- **AI tool capability** - ANY node can be an AI tool (not just marked ones)
+````
 
 Save these instructions in your Claude Project for optimal n8n workflow assistance with intelligent template discovery.
 
@@ -588,11 +670,11 @@ This tool was created to benefit everyone in the n8n community without friction.
 ## Features
 
 - **🔍 Smart Node Search**: Find nodes by name, category, or functionality
-- **📖 Essential Properties**: Get only the 10-20 properties that matter (NEW in v2.4.0)
-- **🎯 Task Templates**: Pre-configured settings for common automation tasks
+- **📖 Essential Properties**: Get only the 10-20 properties that matter
+- **💡 Real-World Examples**: 2,646 pre-extracted configurations from popular templates
 - **✅ Config Validation**: Validate node configurations before deployment
 - **🔗 Dependency Analysis**: Understand property relationships and conditions
-- **💡 Working Examples**: Real-world examples for immediate use
+- **🎯 Template Discovery**: 2,500+ workflow templates with smart filtering
 - **⚡ Fast Response**: Average query time ~12ms with optimized SQLite
 - **🌐 Universal Compatibility**: Works with any Node.js version
 
@@ -618,8 +700,8 @@ Once connected, Claude can use these powerful tools:
 - **`tools_documentation`** - Get documentation for any MCP tool (START HERE!)
 - **`list_nodes`** - List all n8n nodes with filtering options
 - **`get_node_info`** - Get comprehensive information about a specific node
-- **`get_node_essentials`** - Get only essential properties with examples (10-20 properties instead of 200+)
-- **`search_nodes`** - Full-text search across all node documentation
+- **`get_node_essentials`** - Get only essential properties (10-20 instead of 200+). Use `includeExamples: true` to get top 3 real-world configurations from popular templates
+- **`search_nodes`** - Full-text search across all node documentation. Use `includeExamples: true` to get top 2 real-world configurations per node from templates
 - **`search_node_properties`** - Find specific properties within nodes
 - **`list_ai_tools`** - List all AI-capable nodes (ANY node can be used as AI tool!)
 - **`get_node_as_tool_info`** - Get guidance on using any node as an AI tool
@@ -633,8 +715,6 @@ Once connected, Claude can use these powerful tools:
 - **`get_templates_for_task`** - Curated templates for common automation tasks
 
 ### Advanced Tools
-- **`get_node_for_task`** - Pre-configured node settings for common tasks
-- **`list_tasks`** - Discover available task templates
 - **`validate_node_operation`** - Validate node configurations (operation-aware, profiles support)
 - **`validate_node_minimal`** - Quick validation for just required fields
 - **`validate_workflow`** - Complete workflow validation including AI tool connections
@@ -674,14 +754,17 @@ These powerful tools allow you to manage n8n workflows directly from Claude. The
 ### Example Usage
 
 ```typescript
-// Get essentials for quick configuration
-get_node_essentials("nodes-base.httpRequest")
+// Get essentials with real-world examples from templates
+get_node_essentials({
+  nodeType: "nodes-base.httpRequest",
+  includeExamples: true  // Returns top 3 configs from popular templates
+})
 
-// Find nodes for a specific task
-search_nodes({ query: "send email gmail" })
-
-// Get pre-configured settings
-get_node_for_task("send_email")
+// Search nodes with configuration examples
+search_nodes({
+  query: "send email gmail",
+  includeExamples: true  // Returns top 2 configs per node
+})
 
 // Validate before deployment
 validate_node_operation({
@@ -772,12 +855,14 @@ npm run dev:http       # HTTP dev mode
 
 ## 📊 Metrics & Coverage
 
-Current database coverage (n8n v1.106.3):
+Current database coverage (n8n v1.113.3):
 
-- ✅ **535/535** nodes loaded (100%)
+- ✅ **536/536** nodes loaded (100%)
 - ✅ **528** nodes with properties (98.7%)
 - ✅ **470** nodes with documentation (88%)
 - ✅ **267** AI-capable tools detected
+- ✅ **2,646** pre-extracted template configurations
+- ✅ **2,500+** workflow templates available
 - ✅ **AI Agent & LangChain nodes** fully documented
 - ⚡ **Average response time**: ~12ms
 - 💾 **Database size**: ~15MB (optimized)
@@ -817,7 +902,7 @@ docker run --rm ghcr.io/czlonkowski/n8n-mcp:latest --version
 
 ## 🧪 Testing
 
-The project includes a comprehensive test suite with **1,356 tests** ensuring code quality and reliability:
+The project includes a comprehensive test suite with **2,883 tests** ensuring code quality and reliability:
 
 ```bash
 # Run all tests
@@ -837,9 +922,9 @@ npm run test:bench          # Performance benchmarks
 
 ### Test Suite Overview
 
-- **Total Tests**: 1,356 (100% passing)
-  - **Unit Tests**: 1,107 tests across 44 files
-  - **Integration Tests**: 249 tests across 14 files
+- **Total Tests**: 2,883 (100% passing)
+  - **Unit Tests**: 2,526 tests across 99 files
+  - **Integration Tests**: 357 tests across 20 files
 - **Execution Time**: ~2.5 minutes in CI
 - **Test Framework**: Vitest (for speed and TypeScript support)
 - **Mocking**: MSW for API mocking, custom mocks for databases
@@ -853,22 +938,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,107 @@ 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
+- **Workflow Cleanup Operations**: Two new operations for `n8n_update_partial_workflow` to handle broken workflow recovery
+  - `cleanStaleConnections`: Automatically removes all connections referencing non-existent nodes
+    - Essential after node renames or deletions that leave dangling connection references
+    - Supports `dryRun: true` mode to preview what would be removed
+    - Removes both source and target stale connections
+  - `replaceConnections`: Replace entire connections object in a single operation
+    - Faster than crafting many individual connection operations
+    - Useful for bulk connection rewiring
+
+- **Graceful Error Handling for Connection Operations**: Enhanced `removeConnection` operation
+  - New `ignoreErrors` flag: When `true`, operation succeeds even if connection doesn't exist
+  - Perfect for cleanup scenarios where you're not sure if connections exist
+  - Maintains backwards compatibility (defaults to `false` for strict validation)
+
+- **Best-Effort Mode**: New `continueOnError` mode for `WorkflowDiffRequest`
+  - Apply valid operations even if some fail
+  - Returns detailed results with `applied` and `failed` operation indices
+  - Breaks atomic guarantees intentionally for bulk cleanup scenarios
+  - Maintains atomic mode as default for safety
+
+### Enhanced
+- **Tool Documentation**: Updated `n8n_update_partial_workflow` documentation
+  - Added examples for cleanup scenarios
+  - Documented new operation types and modes
+  - Added best practices for workflow recovery
+  - Clarified atomic vs. best-effort behavior
+
+- **Type System**: Extended workflow diff types
+  - Added `CleanStaleConnectionsOperation` interface
+  - Added `ReplaceConnectionsOperation` interface
+  - Extended `WorkflowDiffResult` with `applied`, `failed`, and `staleConnectionsRemoved` fields
+  - Updated type guards for new connection operations
+
+### Testing
+- Added comprehensive test suite for v2.14.4 features
+  - 15 new tests covering all new operations and modes
+  - Tests for cleanStaleConnections with various stale scenarios
+  - Tests for replaceConnections validation
+  - Tests for ignoreErrors flag behavior
+  - Tests for continueOnError mode with mixed success/failure
+  - Backwards compatibility verification tests
+
+### Impact
+- **Time Saved**: Reduces broken workflow fix time from 10-15 minutes to 30 seconds
+- **Token Efficiency**: `cleanStaleConnections` is 1 operation vs 10+ manual operations
+- **User Experience**: Dramatically improved workflow recovery capabilities
+- **Backwards Compatibility**: 100% - all additions are optional and default to existing behavior
+
 ## [2.13.2] - 2025-01-24
 
 ### Added

docs/local/DEEP_DIVE_ANALYSIS_README.md

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

docs/local/TEMPLATE_MINING_ANALYSIS.md

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

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

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

docs/testing-architecture.md

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

docs/workflow-diff-examples.md

@@ -116,17 +116,46 @@ The `n8n_update_partial_workflow` tool allows you to make targeted changes to wo
 }
 ```
 
-#### Update Connection (Change routing)
+#### Rewire Connection
 ```json
 {
-  "type": "updateConnection",
+  "type": "rewireConnection",
+  "source": "Webhook",
+  "from": "Old Handler",
+  "to": "New Handler",
+  "description": "Rewire connection to new handler"
+}
+```
+
+#### Smart Parameters for IF Nodes
+```json
+{
+  "type": "addConnection",
   "source": "IF",
-  "target": "Send Email",
-  "changes": {
-    "sourceOutput": "false",  // Change from 'true' to 'false' output
-    "targetInput": "main"
-  },
-  "description": "Route failed conditions to email"
+  "target": "Success Handler",
+  "branch": "true",  // Semantic parameter instead of sourceIndex
+  "description": "Route true branch to success handler"
+}
+```
+
+```json
+{
+  "type": "addConnection",
+  "source": "IF",
+  "target": "Error Handler",
+  "branch": "false",  // Routes to false branch (sourceIndex=1)
+  "description": "Route false branch to error handler"
+}
+```
+
+#### Smart Parameters for Switch Nodes
+```json
+{
+  "type": "addConnection",
+  "source": "Switch",
+  "target": "Handler A",
+  "case": 0,  // First output
+  "description": "Route case 0 to Handler A"
 }
 ```
 
@@ -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,6 +1,6 @@
 {
   "name": "n8n-mcp",
-  "version": "2.14.0",
+  "version": "2.16.0",
   "description": "Integration between n8n workflow automation and Model Context Protocol (MCP)",
   "main": "dist/index.js",
   "bin": {
@@ -31,12 +31,16 @@
     "test:watch": "vitest watch",
     "test:unit": "vitest run tests/unit",
     "test:integration": "vitest run --config vitest.config.integration.ts",
+    "test:integration:n8n": "vitest run tests/integration/n8n-api",
+    "test:cleanup:orphans": "tsx tests/integration/n8n-api/scripts/cleanup-orphans.ts",
     "test:e2e": "vitest run tests/e2e",
     "lint": "tsc --noEmit",
     "typecheck": "tsc --noEmit",
     "update:n8n": "node scripts/update-n8n-deps.js",
     "update:n8n:check": "node scripts/update-n8n-deps.js --dry-run",
     "fetch:templates": "node dist/scripts/fetch-templates.js",
+    "fetch:templates:update": "node dist/scripts/fetch-templates.js --update",
+    "fetch:templates:extract": "node dist/scripts/fetch-templates.js --extract-only",
     "fetch:templates:robust": "node dist/scripts/fetch-templates-robust.js",
     "prebuild:fts5": "npx tsx scripts/prebuild-fts5.ts",
     "test:templates": "node dist/scripts/test-templates.js",
@@ -128,14 +132,14 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.13.2",
-    "@n8n/n8n-nodes-langchain": "^1.111.1",
+    "@n8n/n8n-nodes-langchain": "^1.112.2",
     "@supabase/supabase-js": "^2.57.4",
     "dotenv": "^16.5.0",
     "express": "^5.1.0",
     "lru-cache": "^11.2.1",
-    "n8n": "^1.112.3",
-    "n8n-core": "^1.111.0",
-    "n8n-workflow": "^1.109.0",
+    "n8n": "^1.113.3",
+    "n8n-core": "^1.112.1",
+    "n8n-workflow": "^1.110.0",
     "openai": "^4.77.0",
     "sql.js": "^1.13.0",
     "uuid": "^10.0.0",

package.runtime.json

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

scripts/export-webhook-workflows.ts

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

scripts/test-error-message-tracking.ts

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

scripts/test-telemetry-integration.ts

@@ -23,7 +23,7 @@ async function testIntegration() {
 
   // Track errors
   console.log('Tracking errors...');
-  telemetry.trackError('ValidationError', 'workflow_validation', 'validate_workflow');
+  telemetry.trackError('ValidationError', 'workflow_validation', 'validate_workflow', 'Required field missing: nodes array is empty');
 
   // Track a test workflow
   console.log('Tracking workflow creation...');

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

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

src/database/node-repository.ts

@@ -1,6 +1,7 @@
 import { DatabaseAdapter } from './database-adapter';
 import { ParsedNode } from '../parsers/node-parser';
 import { SQLiteStorageService } from '../services/sqlite-storage-service';
+import { NodeTypeNormalizer } from '../utils/node-type-normalizer';
 
 export class NodeRepository {
   private db: DatabaseAdapter;
@@ -50,33 +51,30 @@ export class NodeRepository {
   
   /**
    * Get node with proper JSON deserialization
+   * Automatically normalizes node type to full form for consistent lookups
    */
   getNode(nodeType: string): any {
+    // Normalize to full form first for consistent lookups
+    const normalizedType = NodeTypeNormalizer.normalizeToFullForm(nodeType);
+
     const row = this.db.prepare(`
       SELECT * FROM nodes WHERE node_type = ?
-    `).get(nodeType) as any;
-    
+    `).get(normalizedType) as any;
+
+    // Fallback: try original type if normalization didn't help (e.g., community nodes)
+    if (!row && normalizedType !== nodeType) {
+      const originalRow = this.db.prepare(`
+        SELECT * FROM nodes WHERE node_type = ?
+      `).get(nodeType) as any;
+
+      if (originalRow) {
+        return this.parseNodeRow(originalRow);
+      }
+    }
+
     if (!row) return null;
-    
-    return {
-      nodeType: row.node_type,
-      displayName: row.display_name,
-      description: row.description,
-      category: row.category,
-      developmentStyle: row.development_style,
-      package: row.package_name,
-      isAITool: Number(row.is_ai_tool) === 1,
-      isTrigger: Number(row.is_trigger) === 1,
-      isWebhook: Number(row.is_webhook) === 1,
-      isVersioned: Number(row.is_versioned) === 1,
-      version: row.version,
-      properties: this.safeJsonParse(row.properties_schema, []),
-      operations: this.safeJsonParse(row.operations, []),
-      credentials: this.safeJsonParse(row.credentials_required, []),
-      hasDocumentation: !!row.documentation,
-      outputs: row.outputs ? this.safeJsonParse(row.outputs, null) : null,
-      outputNames: row.output_names ? this.safeJsonParse(row.output_names, null) : null
-    };
+
+    return this.parseNodeRow(row);
   }
   
   /**
@@ -377,4 +375,78 @@ export class NodeRepository {
 
     return allResources;
   }
+
+  /**
+   * Get default values for node properties
+   */
+  getNodePropertyDefaults(nodeType: string): Record<string, any> {
+    try {
+      const node = this.getNode(nodeType);
+      if (!node || !node.properties) return {};
+
+      const defaults: Record<string, any> = {};
+
+      for (const prop of node.properties) {
+        if (prop.name && prop.default !== undefined) {
+          defaults[prop.name] = prop.default;
+        }
+      }
+
+      return defaults;
+    } catch (error) {
+      // Log error and return empty defaults rather than throwing
+      console.error(`Error getting property defaults for ${nodeType}:`, error);
+      return {};
+    }
+  }
+
+  /**
+   * Get the default operation for a specific resource
+   */
+  getDefaultOperationForResource(nodeType: string, resource?: string): string | undefined {
+    try {
+      const node = this.getNode(nodeType);
+      if (!node || !node.properties) return undefined;
+
+      // Find operation property that's visible for this resource
+      for (const prop of node.properties) {
+        if (prop.name === 'operation') {
+          // If there's a resource dependency, check if it matches
+          if (resource && prop.displayOptions?.show?.resource) {
+            // Validate displayOptions structure
+            const resourceDep = prop.displayOptions.show.resource;
+            if (!Array.isArray(resourceDep) && typeof resourceDep !== 'string') {
+              continue; // Skip malformed displayOptions
+            }
+
+            const allowedResources = Array.isArray(resourceDep)
+              ? resourceDep
+              : [resourceDep];
+
+            if (!allowedResources.includes(resource)) {
+              continue; // This operation property doesn't apply to our resource
+            }
+          }
+
+          // Return the default value if it exists
+          if (prop.default !== undefined) {
+            return prop.default;
+          }
+
+          // If no default but has options, return the first option's value
+          if (prop.options && Array.isArray(prop.options) && prop.options.length > 0) {
+            const firstOption = prop.options[0];
+            return typeof firstOption === 'string' ? firstOption : firstOption.value;
+          }
+        }
+      }
+    } catch (error) {
+      // Log error and return undefined rather than throwing
+      // This ensures validation continues even with malformed node data
+      console.error(`Error getting default operation for ${nodeType}:`, error);
+      return undefined;
+    }
+
+    return undefined;
+  }
 }

src/database/schema.sql

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

src/mcp-tools-engine.ts

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

src/mcp/handlers-n8n-manager.ts

@@ -6,7 +6,9 @@ import {
   WorkflowConnection,
   ExecutionStatus,
   WebhookRequest,
-  McpToolResponse
+  McpToolResponse,
+  ExecutionFilterOptions,
+  ExecutionMode
 } from '../types/n8n-api';
 import {
   validateWorkflowStructure,
@@ -16,7 +18,9 @@ import {
 import {
   N8nApiError,
   N8nNotFoundError,
-  getUserFriendlyErrorMessage
+  getUserFriendlyErrorMessage,
+  formatExecutionError,
+  formatNoExecutionError
 } from '../utils/n8n-errors';
 import { logger } from '../utils/logger';
 import { z } from 'zod';
@@ -24,6 +28,7 @@ import { WorkflowValidator } from '../services/workflow-validator';
 import { EnhancedConfigValidator } from '../services/enhanced-config-validator';
 import { NodeRepository } from '../database/node-repository';
 import { InstanceContext, validateInstanceContext } from '../types/instance-context';
+import { NodeTypeNormalizer } from '../utils/node-type-normalizer';
 import { WorkflowAutoFixer, AutoFixConfig } from '../services/workflow-auto-fixer';
 import { ExpressionFormatValidator } from '../services/expression-format-validator';
 import { handleUpdatePartialWorkflow } from './handlers-workflow-diff';
@@ -36,6 +41,7 @@ import {
   withRetry,
   getCacheStatistics
 } from '../utils/cache-utils';
+import { processExecution } from '../services/execution-processor';
 
 // Singleton n8n API client instance (backward compatibility)
 let defaultApiClient: N8nApiClient | null = null;
@@ -277,8 +283,34 @@ export async function handleCreateWorkflow(args: unknown, context?: InstanceCont
   try {
     const client = ensureApiConfigured(context);
     const input = createWorkflowSchema.parse(args);
-    
-    // Validate workflow structure
+
+    // Proactively detect SHORT form node types (common mistake)
+    const shortFormErrors: string[] = [];
+    input.nodes?.forEach((node: any, index: number) => {
+      if (node.type?.startsWith('nodes-base.') || node.type?.startsWith('nodes-langchain.')) {
+        const fullForm = node.type.startsWith('nodes-base.')
+          ? node.type.replace('nodes-base.', 'n8n-nodes-base.')
+          : node.type.replace('nodes-langchain.', '@n8n/n8n-nodes-langchain.');
+        shortFormErrors.push(
+          `Node ${index} ("${node.name}") uses SHORT form "${node.type}". ` +
+          `The n8n API requires FULL form. Change to "${fullForm}"`
+        );
+      }
+    });
+
+    if (shortFormErrors.length > 0) {
+      telemetry.trackWorkflowCreation(input, false);
+      return {
+        success: false,
+        error: 'Node type format error: n8n API requires FULL form node types',
+        details: {
+          errors: shortFormErrors,
+          hint: 'Use n8n-nodes-base.* instead of nodes-base.* for standard nodes'
+        }
+      };
+    }
+
+    // Validate workflow structure (n8n API expects FULL form: n8n-nodes-base.*)
     const errors = validateWorkflowStructure(input);
     if (errors.length > 0) {
       // Track validation failure
@@ -291,7 +323,7 @@ export async function handleCreateWorkflow(args: unknown, context?: InstanceCont
       };
     }
 
-    // Create workflow
+    // Create workflow (n8n API expects node types in FULL form)
     const workflow = await client.createWorkflow(input);
 
     // Track successful workflow creation
@@ -517,20 +549,17 @@ export async function handleUpdateWorkflow(args: unknown, context?: InstanceCont
     const client = ensureApiConfigured(context);
     const input = updateWorkflowSchema.parse(args);
     const { id, ...updateData } = input;
-    
+
     // If nodes/connections are being updated, validate the structure
     if (updateData.nodes || updateData.connections) {
-      // Fetch current workflow if only partial update
-      let fullWorkflow = updateData as Partial<Workflow>;
-      
-      if (!updateData.nodes || !updateData.connections) {
-        const current = await client.getWorkflow(id);
-        fullWorkflow = {
-          ...current,
-          ...updateData
-        };
-      }
-      
+      // Always fetch current workflow for validation (need all fields like name)
+      const current = await client.getWorkflow(id);
+      const fullWorkflow = {
+        ...current,
+        ...updateData
+      };
+
+      // Validate workflow structure (n8n API expects FULL form: n8n-nodes-base.*)
       const errors = validateWorkflowStructure(fullWorkflow);
       if (errors.length > 0) {
         return {
@@ -578,11 +607,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) {
@@ -613,12 +643,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
     });
@@ -939,7 +974,7 @@ export async function handleTriggerWebhookWorkflow(args: unknown, context?: Inst
   try {
     const client = ensureApiConfigured(context);
     const input = triggerWebhookSchema.parse(args);
-    
+
     const webhookRequest: WebhookRequest = {
       webhookUrl: input.webhookUrl,
       httpMethod: input.httpMethod || 'POST',
@@ -947,9 +982,9 @@ export async function handleTriggerWebhookWorkflow(args: unknown, context?: Inst
       headers: input.headers,
       waitForResponse: input.waitForResponse ?? true
     };
-    
+
     const response = await client.triggerWebhook(webhookRequest);
-    
+
     return {
       success: true,
       data: response,
@@ -963,8 +998,35 @@ export async function handleTriggerWebhookWorkflow(args: unknown, context?: Inst
         details: { errors: error.errors }
       };
     }
-    
+
     if (error instanceof N8nApiError) {
+      // Try to extract execution context from error response
+      const errorData = error.details as any;
+      const executionId = errorData?.executionId || errorData?.id || errorData?.execution?.id;
+      const workflowId = errorData?.workflowId || errorData?.workflow?.id;
+
+      // If we have execution ID, provide specific guidance with n8n_get_execution
+      if (executionId) {
+        return {
+          success: false,
+          error: formatExecutionError(executionId, workflowId),
+          code: error.code,
+          executionId,
+          workflowId: workflowId || undefined
+        };
+      }
+
+      // No execution ID available - workflow likely didn't start
+      // Provide guidance to check recent executions
+      if (error.code === 'SERVER_ERROR' || error.statusCode && error.statusCode >= 500) {
+        return {
+          success: false,
+          error: formatNoExecutionError(),
+          code: error.code
+        };
+      }
+
+      // For other errors (auth, validation, etc), use standard message
       return {
         success: false,
         error: getUserFriendlyErrorMessage(error),
@@ -972,7 +1034,7 @@ export async function handleTriggerWebhookWorkflow(args: unknown, context?: Inst
         details: error.details as Record<string, unknown> | undefined
       };
     }
-    
+
     return {
       success: false,
       error: error instanceof Error ? error.message : 'Unknown error occurred'
@@ -983,16 +1045,72 @@ export async function handleTriggerWebhookWorkflow(args: unknown, context?: Inst
 export async function handleGetExecution(args: unknown, context?: InstanceContext): Promise<McpToolResponse> {
   try {
     const client = ensureApiConfigured(context);
-    const { id, includeData } = z.object({ 
+
+    // Parse and validate input with new parameters
+    const schema = z.object({
       id: z.string(),
+      // New filtering parameters
+      mode: z.enum(['preview', 'summary', 'filtered', 'full']).optional(),
+      nodeNames: z.array(z.string()).optional(),
+      itemsLimit: z.number().optional(),
+      includeInputData: z.boolean().optional(),
+      // Legacy parameter (backward compatibility)
       includeData: z.boolean().optional()
-    }).parse(args);
-    
-    const execution = await client.getExecution(id, includeData || false);
-    
+    });
+
+    const params = schema.parse(args);
+    const { id, mode, nodeNames, itemsLimit, includeInputData, includeData } = params;
+
+    /**
+     * Map legacy includeData parameter to mode for backward compatibility
+     *
+     * Legacy behavior:
+     * - includeData: undefined -> minimal execution summary (no data)
+     * - includeData: false -> minimal execution summary (no data)
+     * - includeData: true -> full execution data
+     *
+     * New behavior mapping:
+     * - includeData: undefined -> no mode (minimal)
+     * - includeData: false -> no mode (minimal)
+     * - includeData: true -> mode: 'summary' (2 items per node, not full)
+     *
+     * Note: Legacy true behavior returned ALL data, which could exceed token limits.
+     * New behavior caps at 2 items for safety. Users can use mode: 'full' for old behavior.
+     */
+    let effectiveMode = mode;
+    if (!effectiveMode && includeData !== undefined) {
+      effectiveMode = includeData ? 'summary' : undefined;
+    }
+
+    // Determine if we need to fetch full data from API
+    // We fetch full data if any mode is specified (including preview) or legacy includeData is true
+    // Preview mode needs the data to analyze structure and generate recommendations
+    const fetchFullData = effectiveMode !== undefined || includeData === true;
+
+    // Fetch execution from n8n API
+    const execution = await client.getExecution(id, fetchFullData);
+
+    // If no filtering options specified, return original execution (backward compatibility)
+    if (!effectiveMode && !nodeNames && itemsLimit === undefined) {
+      return {
+        success: true,
+        data: execution
+      };
+    }
+
+    // Apply filtering using ExecutionProcessor
+    const filterOptions: ExecutionFilterOptions = {
+      mode: effectiveMode,
+      nodeNames,
+      itemsLimit,
+      includeInputData
+    };
+
+    const processedExecution = processExecution(execution, filterOptions);
+
     return {
       success: true,
-      data: execution
+      data: processedExecution
     };
   } catch (error) {
     if (error instanceof z.ZodError) {
@@ -1002,7 +1120,7 @@ export async function handleGetExecution(args: unknown, context?: InstanceContex
         details: { errors: error.errors }
       };
     }
-    
+
     if (error instanceof N8nApiError) {
       return {
         success: false,
@@ -1010,7 +1128,7 @@ export async function handleGetExecution(args: unknown, context?: InstanceContex
         code: error.code
       };
     }
-    
+
     return {
       success: false,
       error: error instanceof Error ? error.message : 'Unknown error occurred'

src/mcp/handlers-workflow-diff.ts

@@ -27,16 +27,26 @@ 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(),
+    connections: z.any().optional(),
     // Metadata operations
     settings: z.any().optional(),
     name: z.string().optional(),
     tag: z.string().optional(),
   })),
   validateOnly: z.boolean().optional(),
+  continueOnError: z.boolean().optional(),
 });
 
 export async function handleUpdatePartialWorkflow(args: unknown, context?: InstanceContext): Promise<McpToolResponse> {
@@ -80,17 +90,28 @@ export async function handleUpdatePartialWorkflow(args: unknown, context?: Insta
     
     // Apply diff operations
     const diffEngine = new WorkflowDiffEngine();
-    const diffResult = await diffEngine.applyDiff(workflow, input as WorkflowDiffRequest);
-    
+    const diffRequest = input as WorkflowDiffRequest;
+    const diffResult = await diffEngine.applyDiff(workflow, diffRequest);
+
+    // Check if this is a complete failure or partial success in continueOnError mode
     if (!diffResult.success) {
-      return {
-        success: false,
-        error: 'Failed to apply diff operations',
-        details: {
-          errors: diffResult.errors,
-          operationsApplied: diffResult.operationsApplied
-        }
-      };
+      // In continueOnError mode, partial success is still valuable
+      if (diffRequest.continueOnError && diffResult.workflow && diffResult.operationsApplied && diffResult.operationsApplied > 0) {
+        logger.info(`continueOnError mode: Applying ${diffResult.operationsApplied} successful operations despite ${diffResult.failed?.length || 0} failures`);
+        // Continue to update workflow with partial changes
+      } else {
+        // Complete failure - return error
+        return {
+          success: false,
+          error: 'Failed to apply diff operations',
+          details: {
+            errors: diffResult.errors,
+            operationsApplied: diffResult.operationsApplied,
+            applied: diffResult.applied,
+            failed: diffResult.failed
+          }
+        };
+      }
     }
     
     // If validateOnly, return validation result
@@ -116,7 +137,10 @@ export async function handleUpdatePartialWorkflow(args: unknown, context?: Insta
         details: {
           operationsApplied: diffResult.operationsApplied,
           workflowId: updatedWorkflow.id,
-          workflowName: updatedWorkflow.name
+          workflowName: updatedWorkflow.name,
+          applied: diffResult.applied,
+          failed: diffResult.failed,
+          errors: diffResult.errors
         }
       };
     } catch (error) {

src/mcp/server.ts

@@ -27,7 +27,8 @@ import * as n8nHandlers from './handlers-n8n-manager';
 import { handleUpdatePartialWorkflow } from './handlers-workflow-diff';
 import { getToolDocumentation, getToolsOverview } from './tools-documentation';
 import { PROJECT_VERSION } from '../utils/version';
-import { normalizeNodeType, getNodeTypeAlternatives, getWorkflowNodeType } from '../utils/node-utils';
+import { getNodeTypeAlternatives, getWorkflowNodeType } from '../utils/node-utils';
+import { NodeTypeNormalizer } from '../utils/node-type-normalizer';
 import { ToolValidation, Validator, ValidationError } from '../utils/validation-schemas';
 import {
   negotiateProtocolVersion,
@@ -397,7 +398,8 @@ export class N8NDocumentationMCPServer {
         telemetry.trackError(
           error instanceof Error ? error.constructor.name : 'UnknownError',
           `tool_execution`,
-          name
+          name,
+          errorMessage
         );
 
         // Track tool sequence even for errors
@@ -597,16 +599,23 @@ export class N8NDocumentationMCPServer {
    */
   private validateToolParamsBasic(toolName: string, args: any, requiredParams: string[]): void {
     const missing: string[] = [];
-    
+    const invalid: string[] = [];
+
     for (const param of requiredParams) {
       if (!(param in args) || args[param] === undefined || args[param] === null) {
         missing.push(param);
+      } else if (typeof args[param] === 'string' && args[param].trim() === '') {
+        invalid.push(`${param} (empty string)`);
       }
     }
-    
+
     if (missing.length > 0) {
       throw new Error(`Missing required parameters for ${toolName}: ${missing.join(', ')}. Please provide the required parameters to use this tool.`);
     }
+
+    if (invalid.length > 0) {
+      throw new Error(`Invalid parameters for ${toolName}: ${invalid.join(', ')}. String parameters cannot be empty.`);
+    }
   }
 
   /**
@@ -712,7 +721,7 @@ export class N8NDocumentationMCPServer {
         this.validateToolParams(name, args, ['query']);
         // Convert limit to number if provided, otherwise use default
         const limit = args.limit !== undefined ? Number(args.limit) || 20 : 20;
-        return this.searchNodes(args.query, limit, { mode: args.mode });
+        return this.searchNodes(args.query, limit, { mode: args.mode, includeExamples: args.includeExamples });
       case 'list_ai_tools':
         // No required parameters
         return this.listAITools();
@@ -724,14 +733,11 @@ export class N8NDocumentationMCPServer {
         return this.getDatabaseStatistics();
       case 'get_node_essentials':
         this.validateToolParams(name, args, ['nodeType']);
-        return this.getNodeEssentials(args.nodeType);
+        return this.getNodeEssentials(args.nodeType, args.includeExamples);
       case 'search_node_properties':
         this.validateToolParams(name, args, ['nodeType', 'query']);
         const maxResults = args.maxResults !== undefined ? Number(args.maxResults) || 20 : 20;
         return this.searchNodeProperties(args.nodeType, args.query, maxResults);
-      case 'get_node_for_task':
-        this.validateToolParams(name, args, ['task']);
-        return this.getNodeForTask(args.task);
       case 'list_tasks':
         // No required parameters
         return this.listTasks(args.category);
@@ -966,9 +972,9 @@ export class N8NDocumentationMCPServer {
   private async getNodeInfo(nodeType: string): Promise<any> {
     await this.ensureInitialized();
     if (!this.repository) throw new Error('Repository not initialized');
-    
-    // First try with normalized type
-    const normalizedType = normalizeNodeType(nodeType);
+
+    // First try with normalized type (repository will also normalize internally)
+    const normalizedType = NodeTypeNormalizer.normalizeToFullForm(nodeType);
     let node = this.repository.getNode(normalizedType);
     
     if (!node && normalizedType !== nodeType) {
@@ -1029,11 +1035,12 @@ export class N8NDocumentationMCPServer {
   }
 
   private async searchNodes(
-    query: string, 
+    query: string,
     limit: number = 20,
-    options?: { 
+    options?: {
       mode?: 'OR' | 'AND' | 'FUZZY';
       includeSource?: boolean;
+      includeExamples?: boolean;
     }
   ): Promise<any> {
     await this.ensureInitialized();
@@ -1059,16 +1066,23 @@ export class N8NDocumentationMCPServer {
     
     if (ftsExists) {
       // Use FTS5 search with normalized query
-      return this.searchNodesFTS(normalizedQuery, limit, searchMode);
+      logger.debug(`Using FTS5 search with includeExamples=${options?.includeExamples}`);
+      return this.searchNodesFTS(normalizedQuery, limit, searchMode, options);
     } else {
       // Fallback to LIKE search with normalized query
-      return this.searchNodesLIKE(normalizedQuery, limit);
+      logger.debug('Using LIKE search (no FTS5)');
+      return this.searchNodesLIKE(normalizedQuery, limit, options);
     }
   }
-  
-  private async searchNodesFTS(query: string, limit: number, mode: 'OR' | 'AND' | 'FUZZY'): Promise<any> {
+
+  private async searchNodesFTS(
+    query: string,
+    limit: number,
+    mode: 'OR' | 'AND' | 'FUZZY',
+    options?: { includeSource?: boolean; includeExamples?: boolean; }
+  ): Promise<any> {
     if (!this.db) throw new Error('Database not initialized');
-    
+
     // Clean and prepare the query
     const cleanedQuery = query.trim();
     if (!cleanedQuery) {
@@ -1167,12 +1181,40 @@ export class N8NDocumentationMCPServer {
         })),
         totalCount: scoredNodes.length
       };
-      
+
       // Only include mode if it's not the default
       if (mode !== 'OR') {
         result.mode = mode;
       }
 
+      // Add examples if requested
+      if (options && options.includeExamples) {
+        try {
+          for (const nodeResult of result.results) {
+            const examples = this.db!.prepare(`
+              SELECT
+                parameters_json,
+                template_name,
+                template_views
+              FROM template_node_configs
+              WHERE node_type = ?
+              ORDER BY rank
+              LIMIT 2
+            `).all(nodeResult.workflowNodeType) as any[];
+
+            if (examples.length > 0) {
+              nodeResult.examples = examples.map((ex: any) => ({
+                configuration: JSON.parse(ex.parameters_json),
+                template: ex.template_name,
+                views: ex.template_views
+              }));
+            }
+          }
+        } catch (error: any) {
+          logger.error(`Failed to add examples:`, error);
+        }
+      }
+
       // Track search query telemetry
       telemetry.trackSearchQuery(query, scoredNodes.length, mode ?? 'OR');
 
@@ -1349,24 +1391,28 @@ export class N8NDocumentationMCPServer {
     return dp[m][n];
   }
   
-  private async searchNodesLIKE(query: string, limit: number): Promise<any> {
+  private async searchNodesLIKE(
+    query: string,
+    limit: number,
+    options?: { includeSource?: boolean; includeExamples?: boolean; }
+  ): Promise<any> {
     if (!this.db) throw new Error('Database not initialized');
-    
+
     // This is the existing LIKE-based implementation
     // Handle exact phrase searches with quotes
     if (query.startsWith('"') && query.endsWith('"')) {
       const exactPhrase = query.slice(1, -1);
       const nodes = this.db!.prepare(`
-        SELECT * FROM nodes 
+        SELECT * FROM nodes
         WHERE node_type LIKE ? OR display_name LIKE ? OR description LIKE ?
         LIMIT ?
       `).all(`%${exactPhrase}%`, `%${exactPhrase}%`, `%${exactPhrase}%`, limit * 3) as NodeRow[];
-      
+
       // Apply relevance ranking for exact phrase search
       const rankedNodes = this.rankSearchResults(nodes, exactPhrase, limit);
-      
-      return { 
-        query, 
+
+      const result: any = {
+        query,
         results: rankedNodes.map(node => ({
           nodeType: node.node_type,
           workflowNodeType: getWorkflowNodeType(node.package_name, node.node_type),
@@ -1374,9 +1420,39 @@ export class N8NDocumentationMCPServer {
           description: node.description,
           category: node.category,
           package: node.package_name
-        })), 
-        totalCount: rankedNodes.length 
+        })),
+        totalCount: rankedNodes.length
       };
+
+      // Add examples if requested
+      if (options?.includeExamples) {
+        for (const nodeResult of result.results) {
+          try {
+            const examples = this.db!.prepare(`
+              SELECT
+                parameters_json,
+                template_name,
+                template_views
+              FROM template_node_configs
+              WHERE node_type = ?
+              ORDER BY rank
+              LIMIT 2
+            `).all(nodeResult.workflowNodeType) as any[];
+
+            if (examples.length > 0) {
+              nodeResult.examples = examples.map((ex: any) => ({
+                configuration: JSON.parse(ex.parameters_json),
+                template: ex.template_name,
+                views: ex.template_views
+              }));
+            }
+          } catch (error: any) {
+            logger.warn(`Failed to fetch examples for ${nodeResult.nodeType}:`, error.message);
+          }
+        }
+      }
+
+      return result;
     }
     
     // Split into words for normal search
@@ -1403,8 +1479,8 @@ export class N8NDocumentationMCPServer {
     
     // Apply relevance ranking
     const rankedNodes = this.rankSearchResults(nodes, query, limit);
-    
-    return {
+
+    const result: any = {
       query,
       results: rankedNodes.map(node => ({
         nodeType: node.node_type,
@@ -1416,6 +1492,36 @@ export class N8NDocumentationMCPServer {
       })),
       totalCount: rankedNodes.length
     };
+
+    // Add examples if requested
+    if (options?.includeExamples) {
+      for (const nodeResult of result.results) {
+        try {
+          const examples = this.db!.prepare(`
+            SELECT
+              parameters_json,
+              template_name,
+              template_views
+            FROM template_node_configs
+            WHERE node_type = ?
+            ORDER BY rank
+            LIMIT 2
+          `).all(nodeResult.workflowNodeType) as any[];
+
+          if (examples.length > 0) {
+            nodeResult.examples = examples.map((ex: any) => ({
+              configuration: JSON.parse(ex.parameters_json),
+              template: ex.template_name,
+              views: ex.template_views
+            }));
+          }
+        } catch (error: any) {
+          logger.warn(`Failed to fetch examples for ${nodeResult.nodeType}:`, error.message);
+        }
+      }
+    }
+
+    return result;
   }
 
   private calculateRelevance(node: NodeRow, query: string): string {
@@ -1604,9 +1710,9 @@ export class N8NDocumentationMCPServer {
   private async getNodeDocumentation(nodeType: string): Promise<any> {
     await this.ensureInitialized();
     if (!this.db) throw new Error('Database not initialized');
-    
+
     // First try with normalized type
-    const normalizedType = normalizeNodeType(nodeType);
+    const normalizedType = NodeTypeNormalizer.normalizeToFullForm(nodeType);
     let node = this.db!.prepare(`
       SELECT node_type, display_name, documentation, description 
       FROM nodes 
@@ -1732,18 +1838,18 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
     };
   }
 
-  private async getNodeEssentials(nodeType: string): Promise<any> {
+  private async getNodeEssentials(nodeType: string, includeExamples?: boolean): Promise<any> {
     await this.ensureInitialized();
     if (!this.repository) throw new Error('Repository not initialized');
-    
-    // Check cache first
-    const cacheKey = `essentials:${nodeType}`;
+
+    // Check cache first (cache key includes includeExamples)
+    const cacheKey = `essentials:${nodeType}:${includeExamples ? 'withExamples' : 'basic'}`;
     const cached = this.cache.get(cacheKey);
     if (cached) return cached;
     
     // Get the full node information
     // First try with normalized type
-    const normalizedType = normalizeNodeType(nodeType);
+    const normalizedType = NodeTypeNormalizer.normalizeToFullForm(nodeType);
     let node = this.repository.getNode(normalizedType);
     
     if (!node && normalizedType !== nodeType) {
@@ -1804,20 +1910,66 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
         developmentStyle: node.developmentStyle ?? 'programmatic'
       }
     };
-    
+
+    // Add examples from templates if requested
+    if (includeExamples) {
+      try {
+        const fullNodeType = getWorkflowNodeType(node.package ?? 'n8n-nodes-base', node.nodeType);
+        const examples = this.db!.prepare(`
+          SELECT
+            parameters_json,
+            template_name,
+            template_views,
+            complexity,
+            use_cases,
+            has_credentials,
+            has_expressions
+          FROM template_node_configs
+          WHERE node_type = ?
+          ORDER BY rank
+          LIMIT 3
+        `).all(fullNodeType) as any[];
+
+        if (examples.length > 0) {
+          (result as any).examples = examples.map((ex: any) => ({
+            configuration: JSON.parse(ex.parameters_json),
+            source: {
+              template: ex.template_name,
+              views: ex.template_views,
+              complexity: ex.complexity
+            },
+            useCases: ex.use_cases ? JSON.parse(ex.use_cases).slice(0, 2) : [],
+            metadata: {
+              hasCredentials: ex.has_credentials === 1,
+              hasExpressions: ex.has_expressions === 1
+            }
+          }));
+
+          (result as any).examplesCount = examples.length;
+        } else {
+          (result as any).examples = [];
+          (result as any).examplesCount = 0;
+        }
+      } catch (error: any) {
+        logger.warn(`Failed to fetch examples for ${nodeType}:`, error.message);
+        (result as any).examples = [];
+        (result as any).examplesCount = 0;
+      }
+    }
+
     // Cache for 1 hour
     this.cache.set(cacheKey, result, 3600);
-    
+
     return result;
   }
 
   private async searchNodeProperties(nodeType: string, query: string, maxResults: number = 20): Promise<any> {
     await this.ensureInitialized();
     if (!this.repository) throw new Error('Repository not initialized');
-    
+
     // Get the node
     // First try with normalized type
-    const normalizedType = normalizeNodeType(nodeType);
+    const normalizedType = NodeTypeNormalizer.normalizeToFullForm(nodeType);
     let node = this.repository.getNode(normalizedType);
     
     if (!node && normalizedType !== nodeType) {
@@ -1865,43 +2017,6 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
     };
   }
 
-  private async getNodeForTask(task: string): Promise<any> {
-    const template = TaskTemplates.getTaskTemplate(task);
-    
-    if (!template) {
-      // Try to find similar tasks
-      const similar = TaskTemplates.searchTasks(task);
-      throw new Error(
-        `Unknown task: ${task}. ` +
-        (similar.length > 0 
-          ? `Did you mean: ${similar.slice(0, 3).join(', ')}?`
-          : `Use 'list_tasks' to see available tasks.`)
-      );
-    }
-    
-    return {
-      task: template.task,
-      description: template.description,
-      nodeType: template.nodeType,
-      configuration: template.configuration,
-      userMustProvide: template.userMustProvide,
-      optionalEnhancements: template.optionalEnhancements || [],
-      notes: template.notes || [],
-      example: {
-        node: {
-          type: template.nodeType,
-          parameters: template.configuration
-        },
-        userInputsNeeded: template.userMustProvide.map(p => ({
-          property: p.property,
-          currentValue: this.getPropertyValue(template.configuration, p.property),
-          description: p.description,
-          example: p.example
-        }))
-      }
-    };
-  }
-  
   private getPropertyValue(config: any, path: string): any {
     const parts = path.split('.');
     let value = config;
@@ -1972,17 +2087,17 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
   ): Promise<any> {
     await this.ensureInitialized();
     if (!this.repository) throw new Error('Repository not initialized');
-    
+
     // Get node info to access properties
     // First try with normalized type
-    const normalizedType = normalizeNodeType(nodeType);
+    const normalizedType = NodeTypeNormalizer.normalizeToFullForm(nodeType);
     let node = this.repository.getNode(normalizedType);
-    
+
     if (!node && normalizedType !== nodeType) {
       // Try original if normalization changed it
       node = this.repository.getNode(nodeType);
     }
-    
+
     if (!node) {
       // Fallback to other alternatives for edge cases
       const alternatives = getNodeTypeAlternatives(normalizedType);
@@ -2030,10 +2145,10 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
   private async getPropertyDependencies(nodeType: string, config?: Record<string, any>): Promise<any> {
     await this.ensureInitialized();
     if (!this.repository) throw new Error('Repository not initialized');
-    
+
     // Get node info to access properties
     // First try with normalized type
-    const normalizedType = normalizeNodeType(nodeType);
+    const normalizedType = NodeTypeNormalizer.normalizeToFullForm(nodeType);
     let node = this.repository.getNode(normalizedType);
     
     if (!node && normalizedType !== nodeType) {
@@ -2084,10 +2199,10 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
   private async getNodeAsToolInfo(nodeType: string): Promise<any> {
     await this.ensureInitialized();
     if (!this.repository) throw new Error('Repository not initialized');
-    
+
     // Get node info
     // First try with normalized type
-    const normalizedType = normalizeNodeType(nodeType);
+    const normalizedType = NodeTypeNormalizer.normalizeToFullForm(nodeType);
     let node = this.repository.getNode(normalizedType);
     
     if (!node && normalizedType !== nodeType) {
@@ -2307,10 +2422,10 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
   private async validateNodeMinimal(nodeType: string, config: Record<string, any>): Promise<any> {
     await this.ensureInitialized();
     if (!this.repository) throw new Error('Repository not initialized');
-    
+
     // Get node info
     // First try with normalized type
-    const normalizedType = normalizeNodeType(nodeType);
+    const normalizedType = NodeTypeNormalizer.normalizeToFullForm(nodeType);
     let node = this.repository.getNode(normalizedType);
     
     if (!node && normalizedType !== nodeType) {
@@ -2659,24 +2774,19 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
           expressionsValidated: result.statistics.expressionsValidated,
           errorCount: result.errors.length,
           warningCount: result.warnings.length
-        }
-      };
-      
-      if (result.errors.length > 0) {
-        response.errors = result.errors.map(e => ({
+        },
+        // Always include errors and warnings arrays for consistent API response
+        errors: result.errors.map(e => ({
           node: e.nodeName || 'workflow',
           message: e.message,
           details: e.details
-        }));
-      }
-      
-      if (result.warnings.length > 0) {
-        response.warnings = result.warnings.map(w => ({
+        })),
+        warnings: result.warnings.map(w => ({
           node: w.nodeName || 'workflow',
           message: w.message,
           details: w.details
-        }));
-      }
+        }))
+      };
       
       if (result.suggestions.length > 0) {
         response.suggestions = result.suggestions;

src/mcp/tool-docs/index.ts

@@ -17,14 +17,13 @@ import {
   validateWorkflowConnectionsDoc,
   validateWorkflowExpressionsDoc
 } from './validation';
-import { 
-  listTasksDoc, 
-  getNodeForTaskDoc, 
-  listNodeTemplatesDoc, 
-  getTemplateDoc, 
+import {
+  listTasksDoc,
+  listNodeTemplatesDoc,
+  getTemplateDoc,
   searchTemplatesDoc,
-  searchTemplatesByMetadataDoc, 
-  getTemplatesForTaskDoc 
+  searchTemplatesByMetadataDoc,
+  getTemplatesForTaskDoc
 } from './templates';
 import { 
   toolsDocumentationDoc,
@@ -81,7 +80,6 @@ export const toolsDocumentation: Record<string, ToolDocumentation> = {
   
   // Template tools
   list_tasks: listTasksDoc,
-  get_node_for_task: getNodeForTaskDoc,
   list_node_templates: listNodeTemplatesDoc,
   get_template: getTemplateDoc,
   search_templates: searchTemplatesDoc,

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

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

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

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

src/mcp/tool-docs/types.ts

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

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

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

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

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

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

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

src/mcp/tools-n8n-manager.ts

@@ -180,6 +180,10 @@ export const n8nManagementTools: ToolDefinition[] = [
         validateOnly: {
           type: 'boolean',
           description: 'If true, only validate operations without applying them'
+        },
+        continueOnError: {
+          type: 'boolean',
+          description: 'If true, apply valid operations even if some fail (best-effort mode). Returns applied and failed operation indices. Default: false (atomic)'
         }
       },
       required: ['id', 'operations']
@@ -340,17 +344,41 @@ export const n8nManagementTools: ToolDefinition[] = [
   },
   {
     name: 'n8n_get_execution',
-    description: `Get details of a specific execution by ID.`,
+    description: `Get execution details with smart filtering. RECOMMENDED: Use mode='preview' first to assess data size.
+Examples:
+- {id, mode:'preview'} - Structure & counts (fast, no data)
+- {id, mode:'summary'} - 2 samples per node (default)
+- {id, mode:'filtered', itemsLimit:5} - 5 items per node
+- {id, nodeNames:['HTTP Request']} - Specific node only
+- {id, mode:'full'} - Complete data (use with caution)`,
     inputSchema: {
       type: 'object',
       properties: {
-        id: { 
-          type: 'string', 
-          description: 'Execution ID' 
+        id: {
+          type: 'string',
+          description: 'Execution ID'
         },
-        includeData: { 
-          type: 'boolean', 
-          description: 'Include full execution data (default: false)' 
+        mode: {
+          type: 'string',
+          enum: ['preview', 'summary', 'filtered', 'full'],
+          description: 'Data retrieval mode: preview=structure only, summary=2 items, filtered=custom, full=all data'
+        },
+        nodeNames: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Filter to specific nodes by name (for filtered mode)'
+        },
+        itemsLimit: {
+          type: 'number',
+          description: 'Items per node: 0=structure only, 2=default, -1=unlimited (for filtered mode)'
+        },
+        includeInputData: {
+          type: 'boolean',
+          description: 'Include input data in addition to output (default: false)'
+        },
+        includeData: {
+          type: 'boolean',
+          description: 'Legacy: Include execution data. Maps to mode=summary if true (deprecated, use mode instead)'
         }
       },
       required: ['id']

src/mcp/tools.ts

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

src/scripts/fetch-templates.ts

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

src/scripts/sanitize-templates.ts

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

src/scripts/test-execution-filtering.ts

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

src/services/config-validator.ts

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

src/services/enhanced-config-validator.ts

@@ -12,6 +12,7 @@ import { OperationSimilarityService } from './operation-similarity-service';
 import { ResourceSimilarityService } from './resource-similarity-service';
 import { NodeRepository } from '../database/node-repository';
 import { DatabaseAdapter } from '../database/database-adapter';
+import { NodeTypeNormalizer } from '../utils/node-type-normalizer';
 
 export type ValidationMode = 'full' | 'operation' | 'minimal';
 export type ValidationProfile = 'strict' | 'runtime' | 'ai-friendly' | 'minimal';
@@ -76,17 +77,17 @@ export class EnhancedConfigValidator extends ConfigValidator {
     
     // Extract operation context from config
     const operationContext = this.extractOperationContext(config);
-    
-    // Filter properties based on mode and operation
-    const filteredProperties = this.filterPropertiesByMode(
+
+    // Filter properties based on mode and operation, and get config with defaults
+    const { properties: filteredProperties, configWithDefaults } = this.filterPropertiesByMode(
       properties,
       config,
       mode,
       operationContext
     );
-    
-    // Perform base validation on filtered properties
-    const baseResult = super.validate(nodeType, config, filteredProperties);
+
+    // Perform base validation on filtered properties with defaults applied
+    const baseResult = super.validate(nodeType, configWithDefaults, filteredProperties);
     
     // Enhance the result
     const enhancedResult: EnhancedValidationResult = {
@@ -136,31 +137,56 @@ export class EnhancedConfigValidator extends ConfigValidator {
   
   /**
    * Filter properties based on validation mode and operation
+   * Returns both filtered properties and config with defaults
    */
   private static filterPropertiesByMode(
     properties: any[],
     config: Record<string, any>,
     mode: ValidationMode,
     operation: OperationContext
-  ): any[] {
+  ): { properties: any[], configWithDefaults: Record<string, any> } {
+    // Apply defaults for visibility checking
+    const configWithDefaults = this.applyNodeDefaults(properties, config);
+
+    let filteredProperties: any[];
     switch (mode) {
       case 'minimal':
         // Only required properties that are visible
-        return properties.filter(prop => 
-          prop.required && this.isPropertyVisible(prop, config)
+        filteredProperties = properties.filter(prop =>
+          prop.required && this.isPropertyVisible(prop, configWithDefaults)
         );
-        
+        break;
+
       case 'operation':
         // Only properties relevant to the current operation
-        return properties.filter(prop => 
-          this.isPropertyRelevantToOperation(prop, config, operation)
+        filteredProperties = properties.filter(prop =>
+          this.isPropertyRelevantToOperation(prop, configWithDefaults, operation)
         );
-        
+        break;
+
       case 'full':
       default:
         // All properties (current behavior)
-        return properties;
+        filteredProperties = properties;
+        break;
     }
+
+    return { properties: filteredProperties, configWithDefaults };
+  }
+
+  /**
+   * Apply node defaults to configuration for accurate visibility checking
+   */
+  private static applyNodeDefaults(properties: any[], config: Record<string, any>): Record<string, any> {
+    const result = { ...config };
+
+    for (const prop of properties) {
+      if (prop.name && prop.default !== undefined && result[prop.name] === undefined) {
+        result[prop.name] = prop.default;
+      }
+    }
+
+    return result;
   }
   
   /**
@@ -675,11 +701,25 @@ export class EnhancedConfigValidator extends ConfigValidator {
       return;
     }
 
+    // Normalize the node type for repository lookups
+    const normalizedNodeType = NodeTypeNormalizer.normalizeToFullForm(nodeType);
+
+    // Apply defaults for validation
+    const configWithDefaults = { ...config };
+
+    // If operation is undefined but resource is set, get the default operation for that resource
+    if (configWithDefaults.operation === undefined && configWithDefaults.resource !== undefined) {
+      const defaultOperation = this.nodeRepository.getDefaultOperationForResource(normalizedNodeType, configWithDefaults.resource);
+      if (defaultOperation !== undefined) {
+        configWithDefaults.operation = defaultOperation;
+      }
+    }
+
     // Validate resource field if present
     if (config.resource !== undefined) {
       // Remove any existing resource error from base validator to replace with our enhanced version
       result.errors = result.errors.filter(e => e.property !== 'resource');
-      const validResources = this.nodeRepository.getNodeResources(nodeType);
+      const validResources = this.nodeRepository.getNodeResources(normalizedNodeType);
       const resourceIsValid = validResources.some(r => {
         const resourceValue = typeof r === 'string' ? r : r.value;
         return resourceValue === config.resource;
@@ -690,7 +730,7 @@ export class EnhancedConfigValidator extends ConfigValidator {
         let suggestions: any[] = [];
         try {
           suggestions = this.resourceSimilarityService.findSimilarResources(
-            nodeType,
+            normalizedNodeType,
             config.resource,
             3
           );
@@ -749,22 +789,27 @@ export class EnhancedConfigValidator extends ConfigValidator {
       }
     }
 
-    // Validate operation field if present
-    if (config.operation !== undefined) {
+    // Validate operation field - now we check configWithDefaults which has defaults applied
+    // Only validate if operation was explicitly set (not undefined) OR if we're using a default
+    if (config.operation !== undefined || configWithDefaults.operation !== undefined) {
       // Remove any existing operation error from base validator to replace with our enhanced version
       result.errors = result.errors.filter(e => e.property !== 'operation');
-      const validOperations = this.nodeRepository.getNodeOperations(nodeType, config.resource);
+
+      // Use the operation from configWithDefaults for validation (which includes the default if applied)
+      const operationToValidate = configWithDefaults.operation || config.operation;
+      const validOperations = this.nodeRepository.getNodeOperations(normalizedNodeType, config.resource);
       const operationIsValid = validOperations.some(op => {
         const opValue = op.operation || op.value || op;
-        return opValue === config.operation;
+        return opValue === operationToValidate;
       });
 
-      if (!operationIsValid && config.operation !== '') {
+      // Only report error if the explicit operation is invalid (not for defaults)
+      if (!operationIsValid && config.operation !== undefined && config.operation !== '') {
         // Find similar operations
         let suggestions: any[] = [];
         try {
           suggestions = this.operationSimilarityService.findSimilarOperations(
-            nodeType,
+            normalizedNodeType,
             config.operation,
             config.resource,
             3

src/services/execution-processor.ts

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

src/services/expression-validator.ts

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

src/services/n8n-api-client.ts

@@ -161,9 +161,10 @@ export class N8nApiClient {
     }
   }
 
-  async deleteWorkflow(id: string): Promise<void> {
+  async deleteWorkflow(id: string): Promise<Workflow> {
     try {
-      await this.client.delete(`/workflows/${id}`);
+      const response = await this.client.delete(`/workflows/${id}`);
+      return response.data;
     } catch (error) {
       throw handleN8nApiError(error);
     }

src/services/n8n-validation.ts

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

src/services/node-specific-validators.ts

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

src/services/task-templates.ts

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

src/services/workflow-diff-engine.ts

@@ -4,7 +4,7 @@
  */
 
 import { v4 as uuidv4 } from 'uuid';
-import { 
+import {
   WorkflowDiffOperation,
   WorkflowDiffRequest,
   WorkflowDiffResult,
@@ -20,11 +20,13 @@ import {
   DisableNodeOperation,
   AddConnectionOperation,
   RemoveConnectionOperation,
-  UpdateConnectionOperation,
+  RewireConnectionOperation,
   UpdateSettingsOperation,
   UpdateNameOperation,
   AddTagOperation,
-  RemoveTagOperation
+  RemoveTagOperation,
+  CleanStaleConnectionsOperation,
+  ReplaceConnectionsOperation
 } from '../types/workflow-diff';
 import { Workflow, WorkflowNode, WorkflowConnection } from '../types/n8n-api';
 import { Logger } from '../utils/logger';
@@ -37,18 +39,18 @@ export class WorkflowDiffEngine {
    * Apply diff operations to a workflow
    */
   async applyDiff(
-    workflow: Workflow, 
+    workflow: Workflow,
     request: WorkflowDiffRequest
   ): Promise<WorkflowDiffResult> {
     try {
       // Clone workflow to avoid modifying original
       const workflowCopy = JSON.parse(JSON.stringify(workflow));
-      
+
       // Group operations by type for two-pass processing
       const nodeOperationTypes = ['addNode', 'removeNode', 'updateNode', 'moveNode', 'enableNode', 'disableNode'];
       const nodeOperations: Array<{ operation: WorkflowDiffOperation; index: number }> = [];
       const otherOperations: Array<{ operation: WorkflowDiffOperation; index: number }> = [];
-      
+
       request.operations.forEach((operation, index) => {
         if (nodeOperationTypes.includes(operation.type)) {
           nodeOperations.push({ operation, index });
@@ -57,79 +59,137 @@ export class WorkflowDiffEngine {
         }
       });
 
-      // Pass 1: Validate and apply node operations first
-      for (const { operation, index } of nodeOperations) {
-        const error = this.validateOperation(workflowCopy, operation);
-        if (error) {
-          return {
-            success: false,
-            errors: [{
+      const allOperations = [...nodeOperations, ...otherOperations];
+      const errors: WorkflowDiffValidationError[] = [];
+      const appliedIndices: number[] = [];
+      const failedIndices: number[] = [];
+
+      // Process based on mode
+      if (request.continueOnError) {
+        // Best-effort mode: continue even if some operations fail
+        for (const { operation, index } of allOperations) {
+          const error = this.validateOperation(workflowCopy, operation);
+          if (error) {
+            errors.push({
               operation: index,
               message: error,
               details: operation
-            }]
-          };
-        }
-        
-        // Always apply to working copy for proper validation of subsequent operations
-        try {
-          this.applyOperation(workflowCopy, operation);
-        } catch (error) {
-          return {
-            success: false,
-            errors: [{
-              operation: index,
-              message: `Failed to apply operation: ${error instanceof Error ? error.message : 'Unknown error'}`,
-              details: operation
-            }]
-          };
-        }
-      }
+            });
+            failedIndices.push(index);
+            continue;
+          }
 
-      // Pass 2: Validate and apply other operations (connections, metadata)
-      for (const { operation, index } of otherOperations) {
-        const error = this.validateOperation(workflowCopy, operation);
-        if (error) {
-          return {
-            success: false,
-            errors: [{
+          try {
+            this.applyOperation(workflowCopy, operation);
+            appliedIndices.push(index);
+          } catch (error) {
+            const errorMsg = `Failed to apply operation: ${error instanceof Error ? error.message : 'Unknown error'}`;
+            errors.push({
               operation: index,
-              message: error,
+              message: errorMsg,
               details: operation
-            }]
-          };
+            });
+            failedIndices.push(index);
+          }
         }
-        
-        // Always apply to working copy for proper validation of subsequent operations
-        try {
-          this.applyOperation(workflowCopy, operation);
-        } catch (error) {
-          return {
-            success: false,
-            errors: [{
-              operation: index,
-              message: `Failed to apply operation: ${error instanceof Error ? error.message : 'Unknown error'}`,
-              details: operation
-            }]
-          };
-        }
-      }
 
-      // If validateOnly flag is set, return success without applying
-      if (request.validateOnly) {
+        // If validateOnly flag is set, return success without applying
+        if (request.validateOnly) {
+          return {
+            success: errors.length === 0,
+            message: errors.length === 0
+              ? 'Validation successful. All operations are valid.'
+              : `Validation completed with ${errors.length} errors.`,
+            errors: errors.length > 0 ? errors : undefined,
+            applied: appliedIndices,
+            failed: failedIndices
+          };
+        }
+
+        const success = appliedIndices.length > 0;
+        return {
+          success,
+          workflow: workflowCopy,
+          operationsApplied: appliedIndices.length,
+          message: `Applied ${appliedIndices.length} operations, ${failedIndices.length} failed (continueOnError mode)`,
+          errors: errors.length > 0 ? errors : undefined,
+          applied: appliedIndices,
+          failed: failedIndices
+        };
+      } else {
+        // Atomic mode: all operations must succeed
+        // Pass 1: Validate and apply node operations first
+        for (const { operation, index } of nodeOperations) {
+          const error = this.validateOperation(workflowCopy, operation);
+          if (error) {
+            return {
+              success: false,
+              errors: [{
+                operation: index,
+                message: error,
+                details: operation
+              }]
+            };
+          }
+
+          try {
+            this.applyOperation(workflowCopy, operation);
+          } catch (error) {
+            return {
+              success: false,
+              errors: [{
+                operation: index,
+                message: `Failed to apply operation: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                details: operation
+              }]
+            };
+          }
+        }
+
+        // Pass 2: Validate and apply other operations (connections, metadata)
+        for (const { operation, index } of otherOperations) {
+          const error = this.validateOperation(workflowCopy, operation);
+          if (error) {
+            return {
+              success: false,
+              errors: [{
+                operation: index,
+                message: error,
+                details: operation
+              }]
+            };
+          }
+
+          try {
+            this.applyOperation(workflowCopy, operation);
+          } catch (error) {
+            return {
+              success: false,
+              errors: [{
+                operation: index,
+                message: `Failed to apply operation: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                details: operation
+              }]
+            };
+          }
+        }
+
+        // If validateOnly flag is set, return success without applying
+        if (request.validateOnly) {
+          return {
+            success: true,
+            message: 'Validation successful. Operations are valid but not applied.'
+          };
+        }
+
+        const operationsApplied = request.operations.length;
         return {
           success: true,
-          message: 'Validation successful. Operations are valid but not applied.'
+          workflow: workflowCopy,
+          operationsApplied,
+          message: `Successfully applied ${operationsApplied} operations (${nodeOperations.length} node ops, ${otherOperations.length} other ops)`
         };
       }
-
-      const operationsApplied = request.operations.length;
-      return {
-        success: true,
-        workflow: workflowCopy,
-        operationsApplied,
-        message: `Successfully applied ${operationsApplied} operations (${nodeOperations.length} node ops, ${otherOperations.length} other ops)`
-      };
     } catch (error) {
       logger.error('Failed to apply diff', error);
       return {
@@ -163,13 +223,17 @@ 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':
       case 'removeTag':
         return null; // These are always valid
+      case 'cleanStaleConnections':
+        return this.validateCleanStaleConnections(workflow, operation);
+      case 'replaceConnections':
+        return this.validateReplaceConnections(workflow, operation);
       default:
         return `Unknown operation type: ${(operation as any).type}`;
     }
@@ -204,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);
@@ -219,16 +283,26 @@ export class WorkflowDiffEngine {
       case 'removeTag':
         this.applyRemoveTag(workflow, operation);
         break;
+      case 'cleanStaleConnections':
+        this.applyCleanStaleConnections(workflow, operation);
+        break;
+      case 'replaceConnections':
+        this.applyReplaceConnections(workflow, operation);
+        break;
     }
   }
 
   // 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
@@ -246,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
@@ -269,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;
   }
@@ -277,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;
   }
@@ -285,23 +359,48 @@ 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;
   }
 
   // Connection operation validators
   private validateAddConnection(workflow: Workflow, operation: AddConnectionOperation): string | null {
+    // Check for common parameter mistakes (Issue #249)
+    const operationAny = operation as any;
+    if (operationAny.sourceNodeId || operationAny.targetNodeId) {
+      const wrongParams: string[] = [];
+      if (operationAny.sourceNodeId) wrongParams.push('sourceNodeId');
+      if (operationAny.targetNodeId) wrongParams.push('targetNodeId');
+
+      return `Invalid parameter(s): ${wrongParams.join(', ')}. Use 'source' and 'target' instead. Example: {type: "addConnection", source: "Node Name", target: "Target Name"}`;
+    }
+
+    // Check for missing required parameters
+    if (!operation.source) {
+      return `Missing required parameter 'source'. The addConnection operation requires both 'source' and 'target' parameters. Check that you're using 'source' (not 'sourceNodeId').`;
+    }
+    if (!operation.target) {
+      return `Missing required parameter 'target'. The addConnection operation requires both 'source' and 'target' parameters. Check that you're using 'target' (not 'targetNodeId').`;
+    }
+
     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 (apostrophes, quotes).`;
     }
     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 (apostrophes, quotes).`;
     }
-    
+
     // Check if connection already exists
     const sourceOutput = operation.sourceOutput || 'main';
     const existing = workflow.connections[sourceNode.name]?.[sourceOutput];
@@ -313,69 +412,96 @@ export class WorkflowDiffEngine {
         return `Connection already exists from "${sourceNode.name}" to "${targetNode.name}"`;
       }
     }
-    
+
     return null;
   }
 
   private validateRemoveConnection(workflow: Workflow, operation: RemoveConnectionOperation): string | null {
+    // If ignoreErrors is true, don't validate - operation will silently succeed even if connection doesn't exist
+    if (operation.ignoreErrors) {
+      return null;
+    }
+
     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}`;
+      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';
     const connections = workflow.connections[sourceNode.name]?.[sourceOutput];
     if (!connections) {
       return `No connections found from "${sourceNode.name}"`;
     }
-    
+
     const hasConnection = connections.some(conns =>
       conns.some(c => c.node === targetNode.name)
     );
-    
+
     if (!hasConnection) {
       return `No connection exists from "${sourceNode.name}" to "${targetNode.name}"`;
     }
-    
+
     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;
   }
 
@@ -469,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
@@ -504,7 +675,13 @@ export class WorkflowDiffEngine {
   private applyRemoveConnection(workflow: Workflow, operation: RemoveConnectionOperation): void {
     const sourceNode = this.findNode(workflow, operation.source, operation.source);
     const targetNode = this.findNode(workflow, operation.target, operation.target);
-    if (!sourceNode || !targetNode) return;
+    // If ignoreErrors is true, silently succeed even if nodes don't exist
+    if (!sourceNode || !targetNode) {
+      if (operation.ignoreErrors) {
+        return; // Gracefully handle missing nodes
+      }
+      return; // Should never reach here if validation passed, but safety check
+    }
     
     const sourceOutput = operation.sourceOutput || 'main';
     const connections = workflow.connections[sourceNode.name]?.[sourceOutput];
@@ -514,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];
     }
     
@@ -528,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
     });
   }
 
@@ -579,27 +770,207 @@ export class WorkflowDiffEngine {
     }
   }
 
+  // Connection cleanup operation validators
+  private validateCleanStaleConnections(workflow: Workflow, operation: CleanStaleConnectionsOperation): string | null {
+    // This operation is always valid - it just cleans up what it finds
+    return null;
+  }
+
+  private validateReplaceConnections(workflow: Workflow, operation: ReplaceConnectionsOperation): string | null {
+    // Validate that all referenced nodes exist
+    const nodeNames = new Set(workflow.nodes.map(n => n.name));
+
+    for (const [sourceName, outputs] of Object.entries(operation.connections)) {
+      if (!nodeNames.has(sourceName)) {
+        return `Source node not found in connections: ${sourceName}`;
+      }
+
+      // outputs is the value from Object.entries, need to iterate its keys
+      for (const outputName of Object.keys(outputs)) {
+        const connections = outputs[outputName];
+        for (const conns of connections) {
+          for (const conn of conns) {
+            if (!nodeNames.has(conn.node)) {
+              return `Target node not found in connections: ${conn.node}`;
+            }
+          }
+        }
+      }
+    }
+
+    return null;
+  }
+
+  // Connection cleanup operation appliers
+  private applyCleanStaleConnections(workflow: Workflow, operation: CleanStaleConnectionsOperation): void {
+    const nodeNames = new Set(workflow.nodes.map(n => n.name));
+    const staleConnections: Array<{ from: string; to: string }> = [];
+
+    // If dryRun, only identify stale connections without removing them
+    if (operation.dryRun) {
+      for (const [sourceName, outputs] of Object.entries(workflow.connections)) {
+        if (!nodeNames.has(sourceName)) {
+          for (const [outputName, connections] of Object.entries(outputs)) {
+            for (const conns of connections) {
+              for (const conn of conns) {
+                staleConnections.push({ from: sourceName, to: conn.node });
+              }
+            }
+          }
+        } else {
+          for (const [outputName, connections] of Object.entries(outputs)) {
+            for (const conns of connections) {
+              for (const conn of conns) {
+                if (!nodeNames.has(conn.node)) {
+                  staleConnections.push({ from: sourceName, to: conn.node });
+                }
+              }
+            }
+          }
+        }
+      }
+      logger.info(`[DryRun] Would remove ${staleConnections.length} stale connections:`, staleConnections);
+      return;
+    }
+
+    // Actually remove stale connections
+    for (const [sourceName, outputs] of Object.entries(workflow.connections)) {
+      // If source node doesn't exist, mark all connections as stale
+      if (!nodeNames.has(sourceName)) {
+        for (const [outputName, connections] of Object.entries(outputs)) {
+          for (const conns of connections) {
+            for (const conn of conns) {
+              staleConnections.push({ from: sourceName, to: conn.node });
+            }
+          }
+        }
+        delete workflow.connections[sourceName];
+        continue;
+      }
+
+      // Check each connection
+      for (const [outputName, connections] of Object.entries(outputs)) {
+        const filteredConnections = connections.map(conns =>
+          conns.filter(conn => {
+            if (!nodeNames.has(conn.node)) {
+              staleConnections.push({ from: sourceName, to: conn.node });
+              return false;
+            }
+            return true;
+          })
+        ).filter(conns => conns.length > 0);
+
+        if (filteredConnections.length === 0) {
+          delete outputs[outputName];
+        } else {
+          outputs[outputName] = filteredConnections;
+        }
+      }
+
+      // Clean up empty output objects
+      if (Object.keys(outputs).length === 0) {
+        delete workflow.connections[sourceName];
+      }
+    }
+
+    logger.info(`Removed ${staleConnections.length} stale connections`);
+  }
+
+  private applyReplaceConnections(workflow: Workflow, operation: ReplaceConnectionsOperation): void {
+    workflow.connections = operation.connections;
+  }
+
   // 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

@@ -8,7 +8,7 @@ import { EnhancedConfigValidator } from './enhanced-config-validator';
 import { ExpressionValidator } from './expression-validator';
 import { ExpressionFormatValidator } from './expression-format-validator';
 import { NodeSimilarityService, NodeSuggestion } from './node-similarity-service';
-import { normalizeNodeType } from '../utils/node-type-utils';
+import { NodeTypeNormalizer } from '../utils/node-type-normalizer';
 import { Logger } from '../utils/logger';
 const logger = new Logger({ prefix: '[WorkflowValidator]' });
 
@@ -247,7 +247,7 @@ export class WorkflowValidator {
     // Check for minimum viable workflow
     if (workflow.nodes.length === 1) {
       const singleNode = workflow.nodes[0];
-      const normalizedType = normalizeNodeType(singleNode.type);
+      const normalizedType = NodeTypeNormalizer.normalizeToFullForm(singleNode.type);
       const isWebhook = normalizedType === 'nodes-base.webhook' ||
                        normalizedType === 'nodes-base.webhookTrigger';
       
@@ -304,7 +304,7 @@ export class WorkflowValidator {
 
     // Count trigger nodes - normalize type names first
     const triggerNodes = workflow.nodes.filter(n => {
-      const normalizedType = normalizeNodeType(n.type);
+      const normalizedType = NodeTypeNormalizer.normalizeToFullForm(n.type);
       return normalizedType.toLowerCase().includes('trigger') ||
              normalizedType.toLowerCase().includes('webhook') ||
              normalizedType === 'nodes-base.start' ||
@@ -364,30 +364,17 @@ export class WorkflowValidator {
             });
           }
         }
-        // FIRST: Check for common invalid patterns before database lookup
-        if (node.type.startsWith('nodes-base.')) {
-          // This is ALWAYS invalid in workflows - must use n8n-nodes-base prefix
-          const correctType = node.type.replace('nodes-base.', 'n8n-nodes-base.');
-          result.errors.push({
-            type: 'error',
-            nodeId: node.id,
-            nodeName: node.name,
-            message: `Invalid node type: "${node.type}". Use "${correctType}" instead. Node types in workflows must use the full package name.`
-          });
-          continue;
-        }
-        
-        // Get node definition - try multiple formats
-        let nodeInfo = this.nodeRepository.getNode(node.type);
+        // Normalize node type FIRST to ensure consistent lookup
+        const normalizedType = NodeTypeNormalizer.normalizeToFullForm(node.type);
 
-        // If not found, try with normalized type
-        if (!nodeInfo) {
-          const normalizedType = normalizeNodeType(node.type);
-          if (normalizedType !== node.type) {
-            nodeInfo = this.nodeRepository.getNode(normalizedType);
-          }
+        // Update node type in place if it was normalized
+        if (normalizedType !== node.type) {
+          node.type = normalizedType;
         }
-        
+
+        // Get node definition using normalized type
+        const nodeInfo = this.nodeRepository.getNode(normalizedType);
+
         if (!nodeInfo) {
           // Use NodeSimilarityService to find suggestions
           const suggestions = await this.similarityService.findSimilarNodes(node.type, 3);
@@ -610,8 +597,8 @@ export class WorkflowValidator {
     // Check for orphaned nodes (exclude sticky notes)
     for (const node of workflow.nodes) {
       if (node.disabled || this.isStickyNote(node)) continue;
-      
-      const normalizedType = normalizeNodeType(node.type);
+
+      const normalizedType = NodeTypeNormalizer.normalizeToFullForm(node.type);
       const isTrigger = normalizedType.toLowerCase().includes('trigger') ||
                        normalizedType.toLowerCase().includes('webhook') ||
                        normalizedType === 'nodes-base.start' ||
@@ -671,7 +658,7 @@ export class WorkflowValidator {
         }
 
         // Special validation for SplitInBatches node
-        if (sourceNode && sourceNode.type === 'n8n-nodes-base.splitInBatches') {
+        if (sourceNode && sourceNode.type === 'nodes-base.splitInBatches') {
           this.validateSplitInBatchesConnection(
             sourceNode,
             outputIndex,
@@ -684,7 +671,7 @@ export class WorkflowValidator {
         // Check for self-referencing connections
         if (connection.node === sourceName) {
           // This is only a warning for non-loop nodes
-          if (sourceNode && sourceNode.type !== 'n8n-nodes-base.splitInBatches') {
+          if (sourceNode && sourceNode.type !== 'nodes-base.splitInBatches') {
             result.warnings.push({
               type: 'warning',
               message: `Node "${sourceName}" has a self-referencing connection. This can cause infinite loops.`
@@ -824,14 +811,12 @@ export class WorkflowValidator {
     // The source should be an AI Agent connecting to this target node as a tool
     
     // Get target node info to check if it can be used as a tool
-    let targetNodeInfo = this.nodeRepository.getNode(targetNode.type);
-    
-    // Try normalized type if not found
-    if (!targetNodeInfo) {
-      const normalizedType = normalizeNodeType(targetNode.type);
-      if (normalizedType !== targetNode.type) {
-        targetNodeInfo = this.nodeRepository.getNode(normalizedType);
-      }
+    const normalizedType = NodeTypeNormalizer.normalizeToFullForm(targetNode.type);
+    let targetNodeInfo = this.nodeRepository.getNode(normalizedType);
+
+    // Try original type if normalization didn't help (fallback for edge cases)
+    if (!targetNodeInfo && normalizedType !== targetNode.type) {
+      targetNodeInfo = this.nodeRepository.getNode(targetNode.type);
     }
     
     if (targetNodeInfo && !targetNodeInfo.isAITool && targetNodeInfo.package !== 'n8n-nodes-base') {

src/telemetry/batch-processor.ts

@@ -0,0 +1,400 @@
+/**
+ * Batch Processor for Telemetry
+ * Handles batching, queuing, and sending telemetry data to Supabase
+ */
+
+import { SupabaseClient } from '@supabase/supabase-js';
+import { TelemetryEvent, WorkflowTelemetry, TELEMETRY_CONFIG, TelemetryMetrics } from './telemetry-types';
+import { TelemetryError, TelemetryErrorType, TelemetryCircuitBreaker } from './telemetry-error';
+import { logger } from '../utils/logger';
+
+export class TelemetryBatchProcessor {
+  private flushTimer?: NodeJS.Timeout;
+  private isFlushingEvents: boolean = false;
+  private isFlushingWorkflows: boolean = false;
+  private circuitBreaker: TelemetryCircuitBreaker;
+  private metrics: TelemetryMetrics = {
+    eventsTracked: 0,
+    eventsDropped: 0,
+    eventsFailed: 0,
+    batchesSent: 0,
+    batchesFailed: 0,
+    averageFlushTime: 0,
+    rateLimitHits: 0
+  };
+  private flushTimes: number[] = [];
+  private deadLetterQueue: (TelemetryEvent | WorkflowTelemetry)[] = [];
+  private readonly maxDeadLetterSize = 100;
+
+  constructor(
+    private supabase: SupabaseClient | null,
+    private isEnabled: () => boolean
+  ) {
+    this.circuitBreaker = new TelemetryCircuitBreaker();
+  }
+
+  /**
+   * Start the batch processor
+   */
+  start(): void {
+    if (!this.isEnabled() || !this.supabase) return;
+
+    // Set up periodic flushing
+    this.flushTimer = setInterval(() => {
+      this.flush();
+    }, TELEMETRY_CONFIG.BATCH_FLUSH_INTERVAL);
+
+    // Prevent timer from keeping process alive
+    // In tests, flushTimer might be a number instead of a Timer object
+    if (typeof this.flushTimer === 'object' && 'unref' in this.flushTimer) {
+      this.flushTimer.unref();
+    }
+
+    // Set up process exit handlers
+    process.on('beforeExit', () => this.flush());
+    process.on('SIGINT', () => {
+      this.flush();
+      process.exit(0);
+    });
+    process.on('SIGTERM', () => {
+      this.flush();
+      process.exit(0);
+    });
+
+    logger.debug('Telemetry batch processor started');
+  }
+
+  /**
+   * Stop the batch processor
+   */
+  stop(): void {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = undefined;
+    }
+    logger.debug('Telemetry batch processor stopped');
+  }
+
+  /**
+   * Flush events and workflows to Supabase
+   */
+  async flush(events?: TelemetryEvent[], workflows?: WorkflowTelemetry[]): Promise<void> {
+    if (!this.isEnabled() || !this.supabase) return;
+
+    // Check circuit breaker
+    if (!this.circuitBreaker.shouldAllow()) {
+      logger.debug('Circuit breaker open - skipping flush');
+      this.metrics.eventsDropped += (events?.length || 0) + (workflows?.length || 0);
+      return;
+    }
+
+    const startTime = Date.now();
+    let hasErrors = false;
+
+    // Flush events if provided
+    if (events && events.length > 0) {
+      hasErrors = !(await this.flushEvents(events)) || hasErrors;
+    }
+
+    // Flush workflows if provided
+    if (workflows && workflows.length > 0) {
+      hasErrors = !(await this.flushWorkflows(workflows)) || hasErrors;
+    }
+
+    // Record flush time
+    const flushTime = Date.now() - startTime;
+    this.recordFlushTime(flushTime);
+
+    // Update circuit breaker
+    if (hasErrors) {
+      this.circuitBreaker.recordFailure();
+    } else {
+      this.circuitBreaker.recordSuccess();
+    }
+
+    // Process dead letter queue if circuit is healthy
+    if (!hasErrors && this.deadLetterQueue.length > 0) {
+      await this.processDeadLetterQueue();
+    }
+  }
+
+  /**
+   * Flush events with batching
+   */
+  private async flushEvents(events: TelemetryEvent[]): Promise<boolean> {
+    if (this.isFlushingEvents || events.length === 0) return true;
+
+    this.isFlushingEvents = true;
+
+    try {
+      // Batch events
+      const batches = this.createBatches(events, TELEMETRY_CONFIG.MAX_BATCH_SIZE);
+
+      for (const batch of batches) {
+        const result = await this.executeWithRetry(async () => {
+          const { error } = await this.supabase!
+            .from('telemetry_events')
+            .insert(batch);
+
+          if (error) {
+            throw error;
+          }
+
+          logger.debug(`Flushed batch of ${batch.length} telemetry events`);
+          return true;
+        }, 'Flush telemetry events');
+
+        if (result) {
+          this.metrics.eventsTracked += batch.length;
+          this.metrics.batchesSent++;
+        } else {
+          this.metrics.eventsFailed += batch.length;
+          this.metrics.batchesFailed++;
+          this.addToDeadLetterQueue(batch);
+          return false;
+        }
+      }
+
+      return true;
+    } catch (error) {
+      logger.debug('Failed to flush events:', error);
+      throw new TelemetryError(
+        TelemetryErrorType.NETWORK_ERROR,
+        'Failed to flush events',
+        { error: error instanceof Error ? error.message : String(error) },
+        true
+      );
+    } finally {
+      this.isFlushingEvents = false;
+    }
+  }
+
+  /**
+   * Flush workflows with deduplication
+   */
+  private async flushWorkflows(workflows: WorkflowTelemetry[]): Promise<boolean> {
+    if (this.isFlushingWorkflows || workflows.length === 0) return true;
+
+    this.isFlushingWorkflows = true;
+
+    try {
+      // Deduplicate workflows by hash
+      const uniqueWorkflows = this.deduplicateWorkflows(workflows);
+      logger.debug(`Deduplicating workflows: ${workflows.length} -> ${uniqueWorkflows.length}`);
+
+      // Batch workflows
+      const batches = this.createBatches(uniqueWorkflows, TELEMETRY_CONFIG.MAX_BATCH_SIZE);
+
+      for (const batch of batches) {
+        const result = await this.executeWithRetry(async () => {
+          const { error } = await this.supabase!
+            .from('telemetry_workflows')
+            .insert(batch);
+
+          if (error) {
+            throw error;
+          }
+
+          logger.debug(`Flushed batch of ${batch.length} telemetry workflows`);
+          return true;
+        }, 'Flush telemetry workflows');
+
+        if (result) {
+          this.metrics.eventsTracked += batch.length;
+          this.metrics.batchesSent++;
+        } else {
+          this.metrics.eventsFailed += batch.length;
+          this.metrics.batchesFailed++;
+          this.addToDeadLetterQueue(batch);
+          return false;
+        }
+      }
+
+      return true;
+    } catch (error) {
+      logger.debug('Failed to flush workflows:', error);
+      throw new TelemetryError(
+        TelemetryErrorType.NETWORK_ERROR,
+        'Failed to flush workflows',
+        { error: error instanceof Error ? error.message : String(error) },
+        true
+      );
+    } finally {
+      this.isFlushingWorkflows = false;
+    }
+  }
+
+  /**
+   * Execute operation with exponential backoff retry
+   */
+  private async executeWithRetry<T>(
+    operation: () => Promise<T>,
+    operationName: string
+  ): Promise<T | null> {
+    let lastError: Error | null = null;
+    let delay = TELEMETRY_CONFIG.RETRY_DELAY;
+
+    for (let attempt = 1; attempt <= TELEMETRY_CONFIG.MAX_RETRIES; attempt++) {
+      try {
+        // In test environment, execute without timeout but still handle errors
+        if (process.env.NODE_ENV === 'test' && process.env.VITEST) {
+          const result = await operation();
+          return result;
+        }
+
+        // Create a timeout promise
+        const timeoutPromise = new Promise<never>((_, reject) => {
+          setTimeout(() => reject(new Error('Operation timed out')), TELEMETRY_CONFIG.OPERATION_TIMEOUT);
+        });
+
+        // Race between operation and timeout
+        const result = await Promise.race([operation(), timeoutPromise]) as T;
+        return result;
+      } catch (error) {
+        lastError = error as Error;
+        logger.debug(`${operationName} attempt ${attempt} failed:`, error);
+
+        if (attempt < TELEMETRY_CONFIG.MAX_RETRIES) {
+          // Skip delay in test environment when using fake timers
+          if (!(process.env.NODE_ENV === 'test' && process.env.VITEST)) {
+            // Exponential backoff with jitter
+            const jitter = Math.random() * 0.3 * delay; // 30% jitter
+            const waitTime = delay + jitter;
+            await new Promise(resolve => setTimeout(resolve, waitTime));
+            delay *= 2; // Double the delay for next attempt
+          }
+          // In test mode, continue to next retry attempt without delay
+        }
+      }
+    }
+
+    logger.debug(`${operationName} failed after ${TELEMETRY_CONFIG.MAX_RETRIES} attempts:`, lastError);
+    return null;
+  }
+
+  /**
+   * Create batches from array
+   */
+  private createBatches<T>(items: T[], batchSize: number): T[][] {
+    const batches: T[][] = [];
+
+    for (let i = 0; i < items.length; i += batchSize) {
+      batches.push(items.slice(i, i + batchSize));
+    }
+
+    return batches;
+  }
+
+  /**
+   * Deduplicate workflows by hash
+   */
+  private deduplicateWorkflows(workflows: WorkflowTelemetry[]): WorkflowTelemetry[] {
+    const seen = new Set<string>();
+    const unique: WorkflowTelemetry[] = [];
+
+    for (const workflow of workflows) {
+      if (!seen.has(workflow.workflow_hash)) {
+        seen.add(workflow.workflow_hash);
+        unique.push(workflow);
+      }
+    }
+
+    return unique;
+  }
+
+  /**
+   * Add failed items to dead letter queue
+   */
+  private addToDeadLetterQueue(items: (TelemetryEvent | WorkflowTelemetry)[]): void {
+    for (const item of items) {
+      this.deadLetterQueue.push(item);
+
+      // Maintain max size
+      if (this.deadLetterQueue.length > this.maxDeadLetterSize) {
+        const dropped = this.deadLetterQueue.shift();
+        if (dropped) {
+          this.metrics.eventsDropped++;
+        }
+      }
+    }
+
+    logger.debug(`Added ${items.length} items to dead letter queue`);
+  }
+
+  /**
+   * Process dead letter queue when circuit is healthy
+   */
+  private async processDeadLetterQueue(): Promise<void> {
+    if (this.deadLetterQueue.length === 0) return;
+
+    logger.debug(`Processing ${this.deadLetterQueue.length} items from dead letter queue`);
+
+    const events: TelemetryEvent[] = [];
+    const workflows: WorkflowTelemetry[] = [];
+
+    // Separate events and workflows
+    for (const item of this.deadLetterQueue) {
+      if ('workflow_hash' in item) {
+        workflows.push(item as WorkflowTelemetry);
+      } else {
+        events.push(item as TelemetryEvent);
+      }
+    }
+
+    // Clear dead letter queue
+    this.deadLetterQueue = [];
+
+    // Try to flush
+    if (events.length > 0) {
+      await this.flushEvents(events);
+    }
+    if (workflows.length > 0) {
+      await this.flushWorkflows(workflows);
+    }
+  }
+
+  /**
+   * Record flush time for metrics
+   */
+  private recordFlushTime(time: number): void {
+    this.flushTimes.push(time);
+
+    // Keep last 100 flush times
+    if (this.flushTimes.length > 100) {
+      this.flushTimes.shift();
+    }
+
+    // Update average
+    const sum = this.flushTimes.reduce((a, b) => a + b, 0);
+    this.metrics.averageFlushTime = Math.round(sum / this.flushTimes.length);
+    this.metrics.lastFlushTime = time;
+  }
+
+  /**
+   * Get processor metrics
+   */
+  getMetrics(): TelemetryMetrics & { circuitBreakerState: any; deadLetterQueueSize: number } {
+    return {
+      ...this.metrics,
+      circuitBreakerState: this.circuitBreaker.getState(),
+      deadLetterQueueSize: this.deadLetterQueue.length
+    };
+  }
+
+  /**
+   * Reset metrics
+   */
+  resetMetrics(): void {
+    this.metrics = {
+      eventsTracked: 0,
+      eventsDropped: 0,
+      eventsFailed: 0,
+      batchesSent: 0,
+      batchesFailed: 0,
+      averageFlushTime: 0,
+      rateLimitHits: 0
+    };
+    this.flushTimes = [];
+    this.circuitBreaker.reset();
+  }
+}

src/telemetry/config-manager.ts

@@ -257,6 +257,9 @@ For Docker: Set N8N_MCP_TELEMETRY_DISABLED=true
 ║  To opt-out at any time:                                   ║
 ║  npx n8n-mcp telemetry disable                            ║
 ║                                                             ║
+║  Data deletion requests:                                   ║
+║  Email romuald@n8n-mcp.com with your anonymous ID          ║
+║                                                             ║
 ║  Learn more:                                               ║
 ║  https://github.com/czlonkowski/n8n-mcp/blob/main/PRIVACY.md ║
 ║                                                             ║

src/telemetry/event-tracker.ts

@@ -0,0 +1,484 @@
+/**
+ * Event Tracker for Telemetry
+ * Handles all event tracking logic extracted from TelemetryManager
+ */
+
+import { TelemetryEvent, WorkflowTelemetry } from './telemetry-types';
+import { WorkflowSanitizer } from './workflow-sanitizer';
+import { TelemetryRateLimiter } from './rate-limiter';
+import { TelemetryEventValidator } from './event-validator';
+import { TelemetryError, TelemetryErrorType } from './telemetry-error';
+import { logger } from '../utils/logger';
+import { existsSync, readFileSync } from 'fs';
+import { resolve } from 'path';
+
+export class TelemetryEventTracker {
+  private rateLimiter: TelemetryRateLimiter;
+  private validator: TelemetryEventValidator;
+  private eventQueue: TelemetryEvent[] = [];
+  private workflowQueue: WorkflowTelemetry[] = [];
+  private previousTool?: string;
+  private previousToolTimestamp: number = 0;
+  private performanceMetrics: Map<string, number[]> = new Map();
+
+  constructor(
+    private getUserId: () => string,
+    private isEnabled: () => boolean
+  ) {
+    this.rateLimiter = new TelemetryRateLimiter();
+    this.validator = new TelemetryEventValidator();
+  }
+
+  /**
+   * Track a tool usage event
+   */
+  trackToolUsage(toolName: string, success: boolean, duration?: number): void {
+    if (!this.isEnabled()) return;
+
+    // Check rate limit
+    if (!this.rateLimiter.allow()) {
+      logger.debug(`Rate limited: tool_used event for ${toolName}`);
+      return;
+    }
+
+    // Track performance metrics
+    if (duration !== undefined) {
+      this.recordPerformanceMetric(toolName, duration);
+    }
+
+    const event: TelemetryEvent = {
+      user_id: this.getUserId(),
+      event: 'tool_used',
+      properties: {
+        tool: toolName.replace(/[^a-zA-Z0-9_-]/g, '_'),
+        success,
+        duration: duration || 0,
+      }
+    };
+
+    // Validate and queue
+    const validated = this.validator.validateEvent(event);
+    if (validated) {
+      this.eventQueue.push(validated);
+    }
+  }
+
+  /**
+   * Track workflow creation
+   */
+  async trackWorkflowCreation(workflow: any, validationPassed: boolean): Promise<void> {
+    if (!this.isEnabled()) return;
+
+    // Check rate limit
+    if (!this.rateLimiter.allow()) {
+      logger.debug('Rate limited: workflow creation event');
+      return;
+    }
+
+    // Only store workflows that pass validation
+    if (!validationPassed) {
+      this.trackEvent('workflow_validation_failed', {
+        nodeCount: workflow.nodes?.length || 0,
+      });
+      return;
+    }
+
+    try {
+      const sanitized = WorkflowSanitizer.sanitizeWorkflow(workflow);
+
+      const telemetryData: WorkflowTelemetry = {
+        user_id: this.getUserId(),
+        workflow_hash: sanitized.workflowHash,
+        node_count: sanitized.nodeCount,
+        node_types: sanitized.nodeTypes,
+        has_trigger: sanitized.hasTrigger,
+        has_webhook: sanitized.hasWebhook,
+        complexity: sanitized.complexity,
+        sanitized_workflow: {
+          nodes: sanitized.nodes,
+          connections: sanitized.connections,
+        },
+      };
+
+      // Validate workflow telemetry
+      const validated = this.validator.validateWorkflow(telemetryData);
+      if (validated) {
+        this.workflowQueue.push(validated);
+
+        // Also track as event
+        this.trackEvent('workflow_created', {
+          nodeCount: sanitized.nodeCount,
+          nodeTypes: sanitized.nodeTypes.length,
+          complexity: sanitized.complexity,
+          hasTrigger: sanitized.hasTrigger,
+          hasWebhook: sanitized.hasWebhook,
+        });
+      }
+    } catch (error) {
+      logger.debug('Failed to track workflow creation:', error);
+      throw new TelemetryError(
+        TelemetryErrorType.VALIDATION_ERROR,
+        'Failed to sanitize workflow',
+        { error: error instanceof Error ? error.message : String(error) }
+      );
+    }
+  }
+
+  /**
+   * Track an error event
+   */
+  trackError(errorType: string, context: string, toolName?: string, errorMessage?: string): void {
+    if (!this.isEnabled()) return;
+
+    // Don't rate limit error tracking - we want to see all errors
+    this.trackEvent('error_occurred', {
+      errorType: this.sanitizeErrorType(errorType),
+      context: this.sanitizeContext(context),
+      tool: toolName ? toolName.replace(/[^a-zA-Z0-9_-]/g, '_') : undefined,
+      error: errorMessage ? this.sanitizeErrorMessage(errorMessage) : undefined,
+    }, false); // Skip rate limiting for errors
+  }
+
+  /**
+   * Track a generic event
+   */
+  trackEvent(eventName: string, properties: Record<string, any>, checkRateLimit: boolean = true): void {
+    if (!this.isEnabled()) return;
+
+    // Check rate limit unless explicitly skipped
+    if (checkRateLimit && !this.rateLimiter.allow()) {
+      logger.debug(`Rate limited: ${eventName} event`);
+      return;
+    }
+
+    const event: TelemetryEvent = {
+      user_id: this.getUserId(),
+      event: eventName,
+      properties,
+    };
+
+    // Validate and queue
+    const validated = this.validator.validateEvent(event);
+    if (validated) {
+      this.eventQueue.push(validated);
+    }
+  }
+
+  /**
+   * Track session start
+   */
+  trackSessionStart(): void {
+    if (!this.isEnabled()) return;
+
+    this.trackEvent('session_start', {
+      version: this.getPackageVersion(),
+      platform: process.platform,
+      arch: process.arch,
+      nodeVersion: process.version,
+    });
+  }
+
+  /**
+   * Track search queries
+   */
+  trackSearchQuery(query: string, resultsFound: number, searchType: string): void {
+    if (!this.isEnabled()) return;
+
+    this.trackEvent('search_query', {
+      query: query.substring(0, 100),
+      resultsFound,
+      searchType,
+      hasResults: resultsFound > 0,
+      isZeroResults: resultsFound === 0
+    });
+  }
+
+  /**
+   * Track validation details
+   */
+  trackValidationDetails(nodeType: string, errorType: string, details: Record<string, any>): void {
+    if (!this.isEnabled()) return;
+
+    this.trackEvent('validation_details', {
+      nodeType: nodeType.replace(/[^a-zA-Z0-9_.-]/g, '_'),
+      errorType: this.sanitizeErrorType(errorType),
+      errorCategory: this.categorizeError(errorType),
+      details
+    });
+  }
+
+  /**
+   * Track tool usage sequences
+   */
+  trackToolSequence(previousTool: string, currentTool: string, timeDelta: number): void {
+    if (!this.isEnabled()) return;
+
+    this.trackEvent('tool_sequence', {
+      previousTool: previousTool.replace(/[^a-zA-Z0-9_-]/g, '_'),
+      currentTool: currentTool.replace(/[^a-zA-Z0-9_-]/g, '_'),
+      timeDelta: Math.min(timeDelta, 300000), // Cap at 5 minutes
+      isSlowTransition: timeDelta > 10000,
+      sequence: `${previousTool}->${currentTool}`
+    });
+  }
+
+  /**
+   * Track node configuration patterns
+   */
+  trackNodeConfiguration(nodeType: string, propertiesSet: number, usedDefaults: boolean): void {
+    if (!this.isEnabled()) return;
+
+    this.trackEvent('node_configuration', {
+      nodeType: nodeType.replace(/[^a-zA-Z0-9_.-]/g, '_'),
+      propertiesSet,
+      usedDefaults,
+      complexity: this.categorizeConfigComplexity(propertiesSet)
+    });
+  }
+
+  /**
+   * Track performance metrics
+   */
+  trackPerformanceMetric(operation: string, duration: number, metadata?: Record<string, any>): void {
+    if (!this.isEnabled()) return;
+
+    // Record for internal metrics
+    this.recordPerformanceMetric(operation, duration);
+
+    this.trackEvent('performance_metric', {
+      operation: operation.replace(/[^a-zA-Z0-9_-]/g, '_'),
+      duration,
+      isSlow: duration > 1000,
+      isVerySlow: duration > 5000,
+      metadata
+    });
+  }
+
+  /**
+   * Update tool sequence tracking
+   */
+  updateToolSequence(toolName: string): void {
+    if (this.previousTool) {
+      const timeDelta = Date.now() - this.previousToolTimestamp;
+      this.trackToolSequence(this.previousTool, toolName, timeDelta);
+    }
+
+    this.previousTool = toolName;
+    this.previousToolTimestamp = Date.now();
+  }
+
+  /**
+   * Get queued events
+   */
+  getEventQueue(): TelemetryEvent[] {
+    return [...this.eventQueue];
+  }
+
+  /**
+   * Get queued workflows
+   */
+  getWorkflowQueue(): WorkflowTelemetry[] {
+    return [...this.workflowQueue];
+  }
+
+  /**
+   * Clear event queue
+   */
+  clearEventQueue(): void {
+    this.eventQueue = [];
+  }
+
+  /**
+   * Clear workflow queue
+   */
+  clearWorkflowQueue(): void {
+    this.workflowQueue = [];
+  }
+
+  /**
+   * Get tracking statistics
+   */
+  getStats() {
+    return {
+      rateLimiter: this.rateLimiter.getStats(),
+      validator: this.validator.getStats(),
+      eventQueueSize: this.eventQueue.length,
+      workflowQueueSize: this.workflowQueue.length,
+      performanceMetrics: this.getPerformanceStats()
+    };
+  }
+
+  /**
+   * Record performance metric internally
+   */
+  private recordPerformanceMetric(operation: string, duration: number): void {
+    if (!this.performanceMetrics.has(operation)) {
+      this.performanceMetrics.set(operation, []);
+    }
+
+    const metrics = this.performanceMetrics.get(operation)!;
+    metrics.push(duration);
+
+    // Keep only last 100 measurements
+    if (metrics.length > 100) {
+      metrics.shift();
+    }
+  }
+
+  /**
+   * Get performance statistics
+   */
+  private getPerformanceStats() {
+    const stats: Record<string, any> = {};
+
+    for (const [operation, durations] of this.performanceMetrics.entries()) {
+      if (durations.length === 0) continue;
+
+      const sorted = [...durations].sort((a, b) => a - b);
+      const sum = sorted.reduce((a, b) => a + b, 0);
+
+      stats[operation] = {
+        count: sorted.length,
+        min: sorted[0],
+        max: sorted[sorted.length - 1],
+        avg: Math.round(sum / sorted.length),
+        p50: sorted[Math.floor(sorted.length * 0.5)],
+        p95: sorted[Math.floor(sorted.length * 0.95)],
+        p99: sorted[Math.floor(sorted.length * 0.99)]
+      };
+    }
+
+    return stats;
+  }
+
+  /**
+   * Categorize error types
+   */
+  private categorizeError(errorType: string): string {
+    const lowerError = errorType.toLowerCase();
+    if (lowerError.includes('type')) return 'type_error';
+    if (lowerError.includes('validation')) return 'validation_error';
+    if (lowerError.includes('required')) return 'required_field_error';
+    if (lowerError.includes('connection')) return 'connection_error';
+    if (lowerError.includes('expression')) return 'expression_error';
+    return 'other_error';
+  }
+
+  /**
+   * Categorize configuration complexity
+   */
+  private categorizeConfigComplexity(propertiesSet: number): string {
+    if (propertiesSet === 0) return 'defaults_only';
+    if (propertiesSet <= 3) return 'simple';
+    if (propertiesSet <= 10) return 'moderate';
+    return 'complex';
+  }
+
+  /**
+   * Get package version
+   */
+  private getPackageVersion(): string {
+    try {
+      const possiblePaths = [
+        resolve(__dirname, '..', '..', 'package.json'),
+        resolve(process.cwd(), 'package.json'),
+        resolve(__dirname, '..', '..', '..', 'package.json')
+      ];
+
+      for (const packagePath of possiblePaths) {
+        if (existsSync(packagePath)) {
+          const packageJson = JSON.parse(readFileSync(packagePath, 'utf-8'));
+          if (packageJson.version) {
+            return packageJson.version;
+          }
+        }
+      }
+
+      return 'unknown';
+    } catch (error) {
+      logger.debug('Failed to get package version:', error);
+      return 'unknown';
+    }
+  }
+
+  /**
+   * Sanitize error type
+   */
+  private sanitizeErrorType(errorType: string): string {
+    return errorType.replace(/[^a-zA-Z0-9_-]/g, '_').substring(0, 50);
+  }
+
+  /**
+   * Sanitize context
+   */
+  private sanitizeContext(context: string): string {
+    // Sanitize in a specific order to preserve some structure
+    let sanitized = context
+      // First replace emails (before URLs eat them)
+      .replace(/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g, '[EMAIL]')
+      // Then replace long keys (32+ chars to match validator)
+      .replace(/\b[a-zA-Z0-9_-]{32,}/g, '[KEY]')
+      // Finally replace URLs but keep the path structure
+      .replace(/(https?:\/\/)([^\s\/]+)(\/[^\s]*)?/gi, (match, protocol, domain, path) => {
+        return '[URL]' + (path || '');
+      });
+
+    // Then truncate if needed
+    if (sanitized.length > 100) {
+      sanitized = sanitized.substring(0, 100);
+    }
+    return sanitized;
+  }
+
+  /**
+   * Sanitize error message
+   */
+  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]';
+    }
+  }
+}

src/telemetry/event-validator.ts

@@ -0,0 +1,278 @@
+/**
+ * Event Validator for Telemetry
+ * Validates and sanitizes telemetry events using Zod schemas
+ */
+
+import { z } from 'zod';
+import { TelemetryEvent, WorkflowTelemetry } from './telemetry-types';
+import { logger } from '../utils/logger';
+
+// Base property schema that sanitizes strings
+const sanitizedString = z.string().transform(val => {
+  // Remove URLs
+  let sanitized = val.replace(/https?:\/\/[^\s]+/gi, '[URL]');
+  // Remove potential API keys
+  sanitized = sanitized.replace(/[a-zA-Z0-9_-]{32,}/g, '[KEY]');
+  // Remove emails
+  sanitized = sanitized.replace(/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g, '[EMAIL]');
+  return sanitized;
+});
+
+// Schema for generic event properties
+const eventPropertiesSchema = z.record(z.unknown()).transform(obj => {
+  const sanitized: Record<string, any> = {};
+
+  for (const [key, value] of Object.entries(obj)) {
+    // Skip sensitive keys
+    if (isSensitiveKey(key)) {
+      continue;
+    }
+
+    // Sanitize string values
+    if (typeof value === 'string') {
+      sanitized[key] = sanitizedString.parse(value);
+    } else if (typeof value === 'number' || typeof value === 'boolean') {
+      sanitized[key] = value;
+    } else if (value === null || value === undefined) {
+      sanitized[key] = null;
+    } else if (typeof value === 'object') {
+      // Recursively sanitize nested objects (limited depth)
+      sanitized[key] = sanitizeNestedObject(value, 3);
+    }
+  }
+
+  return sanitized;
+});
+
+// Schema for telemetry events
+export const telemetryEventSchema = z.object({
+  user_id: z.string().min(1).max(64),
+  event: z.string().min(1).max(100).regex(/^[a-zA-Z0-9_-]+$/),
+  properties: eventPropertiesSchema,
+  created_at: z.string().datetime().optional()
+});
+
+// Schema for workflow telemetry
+export const workflowTelemetrySchema = z.object({
+  user_id: z.string().min(1).max(64),
+  workflow_hash: z.string().min(1).max(64),
+  node_count: z.number().int().min(0).max(1000),
+  node_types: z.array(z.string()).max(100),
+  has_trigger: z.boolean(),
+  has_webhook: z.boolean(),
+  complexity: z.enum(['simple', 'medium', 'complex']),
+  sanitized_workflow: z.object({
+    nodes: z.array(z.any()).max(1000),
+    connections: z.record(z.any())
+  }),
+  created_at: z.string().datetime().optional()
+});
+
+// Specific event property schemas for common events
+const toolUsagePropertiesSchema = z.object({
+  tool: z.string().max(100),
+  success: z.boolean(),
+  duration: z.number().min(0).max(3600000), // Max 1 hour
+});
+
+const searchQueryPropertiesSchema = z.object({
+  query: z.string().max(100).transform(val => {
+    // Apply same sanitization as sanitizedString
+    let sanitized = val.replace(/https?:\/\/[^\s]+/gi, '[URL]');
+    sanitized = sanitized.replace(/[a-zA-Z0-9_-]{32,}/g, '[KEY]');
+    sanitized = sanitized.replace(/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g, '[EMAIL]');
+    return sanitized;
+  }),
+  resultsFound: z.number().int().min(0),
+  searchType: z.string().max(50),
+  hasResults: z.boolean(),
+  isZeroResults: z.boolean()
+});
+
+const validationDetailsPropertiesSchema = z.object({
+  nodeType: z.string().max(100),
+  errorType: z.string().max(100),
+  errorCategory: z.string().max(50),
+  details: z.record(z.any()).optional()
+});
+
+const performanceMetricPropertiesSchema = z.object({
+  operation: z.string().max(100),
+  duration: z.number().min(0).max(3600000),
+  isSlow: z.boolean(),
+  isVerySlow: z.boolean(),
+  metadata: z.record(z.any()).optional()
+});
+
+// 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,
+};
+
+/**
+ * Check if a key is sensitive
+ * Handles various naming conventions: camelCase, snake_case, kebab-case, and case variations
+ */
+function isSensitiveKey(key: string): boolean {
+  const sensitivePatterns = [
+    // Core sensitive terms
+    'password', 'passwd', 'pwd',
+    'token', 'jwt', 'bearer',
+    'apikey', 'api_key', 'api-key',
+    'secret', 'private',
+    'credential', 'cred', 'auth',
+
+    // Network/Connection sensitive
+    'url', 'uri', 'endpoint', 'host', 'hostname',
+    'database', 'db', 'connection', 'conn',
+
+    // Service-specific
+    'slack', 'discord', 'telegram',
+    'oauth', 'client_secret', 'client-secret', 'clientsecret',
+    'access_token', 'access-token', 'accesstoken',
+    'refresh_token', 'refresh-token', 'refreshtoken'
+  ];
+
+  const lowerKey = key.toLowerCase();
+
+  // Check for exact matches first (most efficient)
+  if (sensitivePatterns.includes(lowerKey)) {
+    return true;
+  }
+
+  // Check for compound key terms specifically
+  if (lowerKey.includes('key') && lowerKey !== 'key') {
+    // Check if it's a compound term like apikey, api_key, etc.
+    const keyPatterns = ['apikey', 'api_key', 'api-key', 'secretkey', 'secret_key', 'privatekey', 'private_key'];
+    if (keyPatterns.some(pattern => lowerKey.includes(pattern))) {
+      return true;
+    }
+  }
+
+  // Check for substring matches with word boundaries
+  return sensitivePatterns.some(pattern => {
+    // Match as whole words or with common separators
+    const regex = new RegExp(`(?:^|[_-])${pattern}(?:[_-]|$)`, 'i');
+    return regex.test(key) || lowerKey.includes(pattern);
+  });
+}
+
+/**
+ * Sanitize nested objects with depth limit
+ */
+function sanitizeNestedObject(obj: any, maxDepth: number): any {
+  if (maxDepth <= 0 || !obj || typeof obj !== 'object') {
+    return '[NESTED]';
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.slice(0, 10).map(item =>
+      typeof item === 'object' ? sanitizeNestedObject(item, maxDepth - 1) : item
+    );
+  }
+
+  const sanitized: Record<string, any> = {};
+  let keyCount = 0;
+
+  for (const [key, value] of Object.entries(obj)) {
+    if (keyCount++ >= 20) { // Limit keys per object
+      sanitized['...'] = 'truncated';
+      break;
+    }
+
+    if (isSensitiveKey(key)) {
+      continue;
+    }
+
+    if (typeof value === 'string') {
+      sanitized[key] = sanitizedString.parse(value);
+    } else if (typeof value === 'object' && value !== null) {
+      sanitized[key] = sanitizeNestedObject(value, maxDepth - 1);
+    } else {
+      sanitized[key] = value;
+    }
+  }
+
+  return sanitized;
+}
+
+export class TelemetryEventValidator {
+  private validationErrors: number = 0;
+  private validationSuccesses: number = 0;
+
+  /**
+   * Validate and sanitize a telemetry event
+   */
+  validateEvent(event: TelemetryEvent): TelemetryEvent | null {
+    try {
+      // Use specific schema if available for this event type
+      const specificSchema = EVENT_SCHEMAS[event.event];
+
+      if (specificSchema) {
+        // Validate properties with specific schema first
+        const validatedProperties = specificSchema.safeParse(event.properties);
+        if (!validatedProperties.success) {
+          logger.debug(`Event validation failed for ${event.event}:`, validatedProperties.error.errors);
+          this.validationErrors++;
+          return null;
+        }
+        event.properties = validatedProperties.data;
+      }
+
+      // Validate the complete event
+      const validated = telemetryEventSchema.parse(event);
+      this.validationSuccesses++;
+      return validated;
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        logger.debug('Event validation error:', error.errors);
+      } else {
+        logger.debug('Unexpected validation error:', error);
+      }
+      this.validationErrors++;
+      return null;
+    }
+  }
+
+  /**
+   * Validate workflow telemetry
+   */
+  validateWorkflow(workflow: WorkflowTelemetry): WorkflowTelemetry | null {
+    try {
+      const validated = workflowTelemetrySchema.parse(workflow);
+      this.validationSuccesses++;
+      return validated;
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        logger.debug('Workflow validation error:', error.errors);
+      } else {
+        logger.debug('Unexpected workflow validation error:', error);
+      }
+      this.validationErrors++;
+      return null;
+    }
+  }
+
+  /**
+   * Get validation statistics
+   */
+  getStats() {
+    return {
+      errors: this.validationErrors,
+      successes: this.validationSuccesses,
+      total: this.validationErrors + this.validationSuccesses,
+      errorRate: this.validationErrors / (this.validationErrors + this.validationSuccesses) || 0
+    };
+  }
+
+  /**
+   * Reset statistics
+   */
+  resetStats(): void {
+    this.validationErrors = 0;
+    this.validationSuccesses = 0;
+  }
+}

src/telemetry/performance-monitor.ts

@@ -0,0 +1,303 @@
+/**
+ * Performance Monitor for Telemetry
+ * Tracks telemetry overhead and provides performance insights
+ */
+
+import { logger } from '../utils/logger';
+
+interface PerformanceMetric {
+  operation: string;
+  duration: number;
+  timestamp: number;
+  memory?: {
+    heapUsed: number;
+    heapTotal: number;
+    external: number;
+  };
+}
+
+export class TelemetryPerformanceMonitor {
+  private metrics: PerformanceMetric[] = [];
+  private operationTimers: Map<string, number> = new Map();
+  private readonly maxMetrics = 1000;
+  private startupTime = Date.now();
+  private operationCounts: Map<string, number> = new Map();
+
+  /**
+   * Start timing an operation
+   */
+  startOperation(operation: string): void {
+    this.operationTimers.set(operation, performance.now());
+  }
+
+  /**
+   * End timing an operation and record metrics
+   */
+  endOperation(operation: string): number {
+    const startTime = this.operationTimers.get(operation);
+    if (!startTime) {
+      logger.debug(`No start time found for operation: ${operation}`);
+      return 0;
+    }
+
+    const duration = performance.now() - startTime;
+    this.operationTimers.delete(operation);
+
+    // Record the metric
+    const metric: PerformanceMetric = {
+      operation,
+      duration,
+      timestamp: Date.now(),
+      memory: this.captureMemoryUsage()
+    };
+
+    this.recordMetric(metric);
+
+    // Update operation count
+    const count = this.operationCounts.get(operation) || 0;
+    this.operationCounts.set(operation, count + 1);
+
+    return duration;
+  }
+
+  /**
+   * Record a performance metric
+   */
+  private recordMetric(metric: PerformanceMetric): void {
+    this.metrics.push(metric);
+
+    // Keep only recent metrics
+    if (this.metrics.length > this.maxMetrics) {
+      this.metrics.shift();
+    }
+
+    // Log slow operations
+    if (metric.duration > 100) {
+      logger.debug(`Slow telemetry operation: ${metric.operation} took ${metric.duration.toFixed(2)}ms`);
+    }
+  }
+
+  /**
+   * Capture current memory usage
+   */
+  private captureMemoryUsage() {
+    if (typeof process !== 'undefined' && process.memoryUsage) {
+      const usage = process.memoryUsage();
+      return {
+        heapUsed: Math.round(usage.heapUsed / 1024 / 1024), // MB
+        heapTotal: Math.round(usage.heapTotal / 1024 / 1024), // MB
+        external: Math.round(usage.external / 1024 / 1024) // MB
+      };
+    }
+    return undefined;
+  }
+
+  /**
+   * Get performance statistics
+   */
+  getStatistics() {
+    const now = Date.now();
+    const recentMetrics = this.metrics.filter(m => now - m.timestamp < 60000); // Last minute
+
+    if (recentMetrics.length === 0) {
+      return {
+        totalOperations: 0,
+        averageDuration: 0,
+        slowOperations: 0,
+        operationsByType: {},
+        memoryUsage: this.captureMemoryUsage(),
+        uptimeMs: now - this.startupTime,
+        overhead: {
+          percentage: 0,
+          totalMs: 0
+        }
+      };
+    }
+
+    // Calculate statistics
+    const durations = recentMetrics.map(m => m.duration);
+    const totalDuration = durations.reduce((a, b) => a + b, 0);
+    const avgDuration = totalDuration / durations.length;
+    const slowOps = durations.filter(d => d > 50).length;
+
+    // Group by operation type
+    const operationsByType: Record<string, { count: number; avgDuration: number }> = {};
+    const typeGroups = new Map<string, number[]>();
+
+    for (const metric of recentMetrics) {
+      const type = metric.operation;
+      if (!typeGroups.has(type)) {
+        typeGroups.set(type, []);
+      }
+      typeGroups.get(type)!.push(metric.duration);
+    }
+
+    for (const [type, durations] of typeGroups.entries()) {
+      const sum = durations.reduce((a, b) => a + b, 0);
+      operationsByType[type] = {
+        count: durations.length,
+        avgDuration: Math.round(sum / durations.length * 100) / 100
+      };
+    }
+
+    // Estimate overhead
+    const estimatedOverheadPercentage = Math.min(5, avgDuration / 10); // Rough estimate
+
+    return {
+      totalOperations: this.operationCounts.size,
+      operationsInLastMinute: recentMetrics.length,
+      averageDuration: Math.round(avgDuration * 100) / 100,
+      slowOperations: slowOps,
+      operationsByType,
+      memoryUsage: this.captureMemoryUsage(),
+      uptimeMs: now - this.startupTime,
+      overhead: {
+        percentage: estimatedOverheadPercentage,
+        totalMs: totalDuration
+      }
+    };
+  }
+
+  /**
+   * Get detailed performance report
+   */
+  getDetailedReport() {
+    const stats = this.getStatistics();
+    const percentiles = this.calculatePercentiles();
+
+    return {
+      summary: stats,
+      percentiles,
+      topSlowOperations: this.getTopSlowOperations(5),
+      memoryTrend: this.getMemoryTrend(),
+      recommendations: this.generateRecommendations(stats, percentiles)
+    };
+  }
+
+  /**
+   * Calculate percentiles for recent operations
+   */
+  private calculatePercentiles() {
+    const recentDurations = this.metrics
+      .filter(m => Date.now() - m.timestamp < 60000)
+      .map(m => m.duration)
+      .sort((a, b) => a - b);
+
+    if (recentDurations.length === 0) {
+      return { p50: 0, p75: 0, p90: 0, p95: 0, p99: 0 };
+    }
+
+    return {
+      p50: this.percentile(recentDurations, 0.5),
+      p75: this.percentile(recentDurations, 0.75),
+      p90: this.percentile(recentDurations, 0.9),
+      p95: this.percentile(recentDurations, 0.95),
+      p99: this.percentile(recentDurations, 0.99)
+    };
+  }
+
+  /**
+   * Calculate a specific percentile
+   */
+  private percentile(sorted: number[], p: number): number {
+    const index = Math.ceil(sorted.length * p) - 1;
+    return Math.round(sorted[Math.max(0, index)] * 100) / 100;
+  }
+
+  /**
+   * Get top slow operations
+   */
+  private getTopSlowOperations(n: number) {
+    return [...this.metrics]
+      .sort((a, b) => b.duration - a.duration)
+      .slice(0, n)
+      .map(m => ({
+        operation: m.operation,
+        duration: Math.round(m.duration * 100) / 100,
+        timestamp: m.timestamp
+      }));
+  }
+
+  /**
+   * Get memory usage trend
+   */
+  private getMemoryTrend() {
+    const metricsWithMemory = this.metrics.filter(m => m.memory);
+    if (metricsWithMemory.length < 2) {
+      return { trend: 'stable', delta: 0 };
+    }
+
+    const recent = metricsWithMemory.slice(-10);
+    const first = recent[0].memory!;
+    const last = recent[recent.length - 1].memory!;
+    const delta = last.heapUsed - first.heapUsed;
+
+    let trend: 'increasing' | 'decreasing' | 'stable';
+    if (delta > 5) trend = 'increasing';
+    else if (delta < -5) trend = 'decreasing';
+    else trend = 'stable';
+
+    return { trend, delta };
+  }
+
+  /**
+   * Generate performance recommendations
+   */
+  private generateRecommendations(stats: any, percentiles: any): string[] {
+    const recommendations: string[] = [];
+
+    // Check for high average duration
+    if (stats.averageDuration > 50) {
+      recommendations.push('Consider batching more events to reduce overhead');
+    }
+
+    // Check for slow operations
+    if (stats.slowOperations > stats.operationsInLastMinute * 0.1) {
+      recommendations.push('Many slow operations detected - investigate network latency');
+    }
+
+    // Check p99 percentile
+    if (percentiles.p99 > 200) {
+      recommendations.push('P99 latency is high - consider implementing local queue persistence');
+    }
+
+    // Check memory trend
+    const memoryTrend = this.getMemoryTrend();
+    if (memoryTrend.trend === 'increasing' && memoryTrend.delta > 10) {
+      recommendations.push('Memory usage is increasing - check for memory leaks');
+    }
+
+    // Check operation count
+    if (stats.operationsInLastMinute > 1000) {
+      recommendations.push('High telemetry volume - ensure rate limiting is effective');
+    }
+
+    return recommendations;
+  }
+
+  /**
+   * Reset all metrics
+   */
+  reset(): void {
+    this.metrics = [];
+    this.operationTimers.clear();
+    this.operationCounts.clear();
+    this.startupTime = Date.now();
+  }
+
+  /**
+   * Get telemetry overhead estimate
+   */
+  getTelemetryOverhead(): { percentage: number; impact: 'minimal' | 'low' | 'moderate' | 'high' } {
+    const stats = this.getStatistics();
+    const percentage = stats.overhead.percentage;
+
+    let impact: 'minimal' | 'low' | 'moderate' | 'high';
+    if (percentage < 1) impact = 'minimal';
+    else if (percentage < 3) impact = 'low';
+    else if (percentage < 5) impact = 'moderate';
+    else impact = 'high';
+
+    return { percentage, impact };
+  }
+}

src/telemetry/rate-limiter.ts

@@ -0,0 +1,173 @@
+/**
+ * Rate Limiter for Telemetry
+ * Implements sliding window rate limiting to prevent excessive telemetry events
+ */
+
+import { TELEMETRY_CONFIG } from './telemetry-types';
+import { logger } from '../utils/logger';
+
+export class TelemetryRateLimiter {
+  private eventTimestamps: number[] = [];
+  private windowMs: number;
+  private maxEvents: number;
+  private droppedEventsCount: number = 0;
+  private lastWarningTime: number = 0;
+  private readonly WARNING_INTERVAL = 60000; // Warn at most once per minute
+  private readonly MAX_ARRAY_SIZE = 1000; // Prevent memory leaks by limiting array size
+
+  constructor(
+    windowMs: number = TELEMETRY_CONFIG.RATE_LIMIT_WINDOW,
+    maxEvents: number = TELEMETRY_CONFIG.RATE_LIMIT_MAX_EVENTS
+  ) {
+    this.windowMs = windowMs;
+    this.maxEvents = maxEvents;
+  }
+
+  /**
+   * Check if an event can be tracked based on rate limits
+   * Returns true if event can proceed, false if rate limited
+   */
+  allow(): boolean {
+    const now = Date.now();
+
+    // Clean up old timestamps outside the window
+    this.cleanupOldTimestamps(now);
+
+    // Check if we've hit the rate limit
+    if (this.eventTimestamps.length >= this.maxEvents) {
+      this.handleRateLimitHit(now);
+      return false;
+    }
+
+    // Add current timestamp and allow event
+    this.eventTimestamps.push(now);
+    return true;
+  }
+
+  /**
+   * Check if rate limiting would occur without actually blocking
+   * Useful for pre-flight checks
+   */
+  wouldAllow(): boolean {
+    const now = Date.now();
+    this.cleanupOldTimestamps(now);
+    return this.eventTimestamps.length < this.maxEvents;
+  }
+
+  /**
+   * Get current usage statistics
+   */
+  getStats() {
+    const now = Date.now();
+    this.cleanupOldTimestamps(now);
+
+    return {
+      currentEvents: this.eventTimestamps.length,
+      maxEvents: this.maxEvents,
+      windowMs: this.windowMs,
+      droppedEvents: this.droppedEventsCount,
+      utilizationPercent: Math.round((this.eventTimestamps.length / this.maxEvents) * 100),
+      remainingCapacity: Math.max(0, this.maxEvents - this.eventTimestamps.length),
+      arraySize: this.eventTimestamps.length,
+      maxArraySize: this.MAX_ARRAY_SIZE,
+      memoryUsagePercent: Math.round((this.eventTimestamps.length / this.MAX_ARRAY_SIZE) * 100)
+    };
+  }
+
+  /**
+   * Reset the rate limiter (useful for testing)
+   */
+  reset(): void {
+    this.eventTimestamps = [];
+    this.droppedEventsCount = 0;
+    this.lastWarningTime = 0;
+  }
+
+  /**
+   * Clean up timestamps outside the current window and enforce array size limit
+   */
+  private cleanupOldTimestamps(now: number): void {
+    const windowStart = now - this.windowMs;
+
+    // Remove all timestamps before the window start
+    let i = 0;
+    while (i < this.eventTimestamps.length && this.eventTimestamps[i] < windowStart) {
+      i++;
+    }
+
+    if (i > 0) {
+      this.eventTimestamps.splice(0, i);
+    }
+
+    // Enforce maximum array size to prevent memory leaks
+    if (this.eventTimestamps.length > this.MAX_ARRAY_SIZE) {
+      const excess = this.eventTimestamps.length - this.MAX_ARRAY_SIZE;
+      this.eventTimestamps.splice(0, excess);
+
+      if (now - this.lastWarningTime > this.WARNING_INTERVAL) {
+        logger.debug(
+          `Telemetry rate limiter array trimmed: removed ${excess} oldest timestamps to prevent memory leak. ` +
+          `Array size: ${this.eventTimestamps.length}/${this.MAX_ARRAY_SIZE}`
+        );
+        this.lastWarningTime = now;
+      }
+    }
+  }
+
+  /**
+   * Handle rate limit hit
+   */
+  private handleRateLimitHit(now: number): void {
+    this.droppedEventsCount++;
+
+    // Log warning if enough time has passed since last warning
+    if (now - this.lastWarningTime > this.WARNING_INTERVAL) {
+      const stats = this.getStats();
+      logger.debug(
+        `Telemetry rate limit reached: ${stats.currentEvents}/${stats.maxEvents} events in ${stats.windowMs}ms window. ` +
+        `Total dropped: ${stats.droppedEvents}`
+      );
+      this.lastWarningTime = now;
+    }
+  }
+
+  /**
+   * Get the number of dropped events
+   */
+  getDroppedEventsCount(): number {
+    return this.droppedEventsCount;
+  }
+
+  /**
+   * Estimate time until capacity is available (in ms)
+   * Returns 0 if capacity is available now
+   */
+  getTimeUntilCapacity(): number {
+    const now = Date.now();
+    this.cleanupOldTimestamps(now);
+
+    if (this.eventTimestamps.length < this.maxEvents) {
+      return 0;
+    }
+
+    // Find the oldest timestamp that would need to expire
+    const oldestRelevant = this.eventTimestamps[this.eventTimestamps.length - this.maxEvents];
+    const timeUntilExpiry = Math.max(0, (oldestRelevant + this.windowMs) - now);
+
+    return timeUntilExpiry;
+  }
+
+  /**
+   * Update rate limit configuration dynamically
+   */
+  updateLimits(windowMs?: number, maxEvents?: number): void {
+    if (windowMs !== undefined && windowMs > 0) {
+      this.windowMs = windowMs;
+    }
+    if (maxEvents !== undefined && maxEvents > 0) {
+      this.maxEvents = maxEvents;
+    }
+
+    logger.debug(`Rate limiter updated: ${this.maxEvents} events per ${this.windowMs}ms`);
+  }
+}

src/telemetry/telemetry-error.ts

@@ -0,0 +1,244 @@
+/**
+ * Telemetry Error Classes
+ * Custom error types for telemetry system with enhanced tracking
+ */
+
+import { TelemetryErrorType, TelemetryErrorContext } from './telemetry-types';
+import { logger } from '../utils/logger';
+
+// Re-export types for convenience
+export { TelemetryErrorType, TelemetryErrorContext } from './telemetry-types';
+
+export class TelemetryError extends Error {
+  public readonly type: TelemetryErrorType;
+  public readonly context?: Record<string, any>;
+  public readonly timestamp: number;
+  public readonly retryable: boolean;
+
+  constructor(
+    type: TelemetryErrorType,
+    message: string,
+    context?: Record<string, any>,
+    retryable: boolean = false
+  ) {
+    super(message);
+    this.name = 'TelemetryError';
+    this.type = type;
+    this.context = context;
+    this.timestamp = Date.now();
+    this.retryable = retryable;
+
+    // Ensure proper prototype chain
+    Object.setPrototypeOf(this, TelemetryError.prototype);
+  }
+
+  /**
+   * Convert error to context object
+   */
+  toContext(): TelemetryErrorContext {
+    return {
+      type: this.type,
+      message: this.message,
+      context: this.context,
+      timestamp: this.timestamp,
+      retryable: this.retryable
+    };
+  }
+
+  /**
+   * Log the error with appropriate level
+   */
+  log(): void {
+    const logContext = {
+      type: this.type,
+      message: this.message,
+      ...this.context
+    };
+
+    if (this.retryable) {
+      logger.debug('Retryable telemetry error:', logContext);
+    } else {
+      logger.debug('Non-retryable telemetry error:', logContext);
+    }
+  }
+}
+
+/**
+ * Circuit Breaker for handling repeated failures
+ */
+export class TelemetryCircuitBreaker {
+  private failureCount: number = 0;
+  private lastFailureTime: number = 0;
+  private state: 'closed' | 'open' | 'half-open' = 'closed';
+
+  private readonly failureThreshold: number;
+  private readonly resetTimeout: number;
+  private readonly halfOpenRequests: number;
+  private halfOpenCount: number = 0;
+
+  constructor(
+    failureThreshold: number = 5,
+    resetTimeout: number = 60000, // 1 minute
+    halfOpenRequests: number = 3
+  ) {
+    this.failureThreshold = failureThreshold;
+    this.resetTimeout = resetTimeout;
+    this.halfOpenRequests = halfOpenRequests;
+  }
+
+  /**
+   * Check if requests should be allowed
+   */
+  shouldAllow(): boolean {
+    const now = Date.now();
+
+    switch (this.state) {
+      case 'closed':
+        return true;
+
+      case 'open':
+        // Check if enough time has passed to try half-open
+        if (now - this.lastFailureTime > this.resetTimeout) {
+          this.state = 'half-open';
+          this.halfOpenCount = 0;
+          logger.debug('Circuit breaker transitioning to half-open');
+          return true;
+        }
+        return false;
+
+      case 'half-open':
+        // Allow limited requests in half-open state
+        if (this.halfOpenCount < this.halfOpenRequests) {
+          this.halfOpenCount++;
+          return true;
+        }
+        return false;
+
+      default:
+        return false;
+    }
+  }
+
+  /**
+   * Record a success
+   */
+  recordSuccess(): void {
+    if (this.state === 'half-open') {
+      // If we've had enough successful requests, close the circuit
+      if (this.halfOpenCount >= this.halfOpenRequests) {
+        this.state = 'closed';
+        this.failureCount = 0;
+        logger.debug('Circuit breaker closed after successful recovery');
+      }
+    } else if (this.state === 'closed') {
+      // Reset failure count on success
+      this.failureCount = 0;
+    }
+  }
+
+  /**
+   * Record a failure
+   */
+  recordFailure(error?: Error): void {
+    this.failureCount++;
+    this.lastFailureTime = Date.now();
+
+    if (this.state === 'half-open') {
+      // Immediately open on failure in half-open state
+      this.state = 'open';
+      logger.debug('Circuit breaker opened from half-open state', { error: error?.message });
+    } else if (this.state === 'closed' && this.failureCount >= this.failureThreshold) {
+      // Open circuit after threshold reached
+      this.state = 'open';
+      logger.debug(
+        `Circuit breaker opened after ${this.failureCount} failures`,
+        { error: error?.message }
+      );
+    }
+  }
+
+  /**
+   * Get current state
+   */
+  getState(): { state: string; failureCount: number; canRetry: boolean } {
+    return {
+      state: this.state,
+      failureCount: this.failureCount,
+      canRetry: this.shouldAllow()
+    };
+  }
+
+  /**
+   * Force reset the circuit breaker
+   */
+  reset(): void {
+    this.state = 'closed';
+    this.failureCount = 0;
+    this.lastFailureTime = 0;
+    this.halfOpenCount = 0;
+  }
+}
+
+/**
+ * Error aggregator for tracking error patterns
+ */
+export class TelemetryErrorAggregator {
+  private errors: Map<TelemetryErrorType, number> = new Map();
+  private errorDetails: TelemetryErrorContext[] = [];
+  private readonly maxDetails: number = 100;
+
+  /**
+   * Record an error
+   */
+  record(error: TelemetryError): void {
+    // Increment counter for this error type
+    const count = this.errors.get(error.type) || 0;
+    this.errors.set(error.type, count + 1);
+
+    // Store error details (limited)
+    this.errorDetails.push(error.toContext());
+    if (this.errorDetails.length > this.maxDetails) {
+      this.errorDetails.shift();
+    }
+  }
+
+  /**
+   * Get error statistics
+   */
+  getStats(): {
+    totalErrors: number;
+    errorsByType: Record<string, number>;
+    mostCommonError?: string;
+    recentErrors: TelemetryErrorContext[];
+  } {
+    const errorsByType: Record<string, number> = {};
+    let totalErrors = 0;
+    let mostCommonError: string | undefined;
+    let maxCount = 0;
+
+    for (const [type, count] of this.errors.entries()) {
+      errorsByType[type] = count;
+      totalErrors += count;
+
+      if (count > maxCount) {
+        maxCount = count;
+        mostCommonError = type;
+      }
+    }
+
+    return {
+      totalErrors,
+      errorsByType,
+      mostCommonError,
+      recentErrors: this.errorDetails.slice(-10) // Last 10 errors
+    };
+  }
+
+  /**
+   * Clear error history
+   */
+  reset(): void {
+    this.errors.clear();
+    this.errorDetails = [];
+  }
+}

src/telemetry/telemetry-manager.ts

@@ -1,69 +1,51 @@
 /**
  * Telemetry Manager
- * Main telemetry class for anonymous usage statistics
+ * Main telemetry coordinator using modular components
  */
 
 import { createClient, SupabaseClient } from '@supabase/supabase-js';
 import { TelemetryConfigManager } from './config-manager';
-import { WorkflowSanitizer } from './workflow-sanitizer';
+import { TelemetryEventTracker } from './event-tracker';
+import { TelemetryBatchProcessor } from './batch-processor';
+import { TelemetryPerformanceMonitor } from './performance-monitor';
+import { TELEMETRY_BACKEND } from './telemetry-types';
+import { TelemetryError, TelemetryErrorType, TelemetryErrorAggregator } from './telemetry-error';
 import { logger } from '../utils/logger';
-import { resolve } from 'path';
-import { existsSync, readFileSync } from 'fs';
-
-interface TelemetryEvent {
-  user_id: string;
-  event: string;
-  properties: Record<string, any>;
-  created_at?: string;
-}
-
-interface WorkflowTelemetry {
-  user_id: string;
-  workflow_hash: string;
-  node_count: number;
-  node_types: string[];
-  has_trigger: boolean;
-  has_webhook: boolean;
-  complexity: 'simple' | 'medium' | 'complex';
-  sanitized_workflow: any;
-  created_at?: string;
-}
-
-// Configuration constants
-const TELEMETRY_CONFIG = {
-  BATCH_FLUSH_INTERVAL: 5000, // 5 seconds - reduced for multi-process
-  EVENT_QUEUE_THRESHOLD: 1, // Immediate flush for multi-process compatibility
-  WORKFLOW_QUEUE_THRESHOLD: 1, // Immediate flush for multi-process compatibility
-  MAX_RETRIES: 3,
-  RETRY_DELAY: 1000, // 1 second
-  OPERATION_TIMEOUT: 5000, // 5 seconds
-} as const;
-
-// Hardcoded telemetry backend configuration
-// IMPORTANT: This is intentionally hardcoded for zero-configuration telemetry
-// The anon key is PUBLIC and SAFE to expose because:
-// 1. It only allows INSERT operations (write-only)
-// 2. Row Level Security (RLS) policies prevent reading/updating/deleting data
-// 3. This is standard practice for anonymous telemetry collection
-// 4. No sensitive user data is ever sent
-const TELEMETRY_BACKEND = {
-  URL: 'https://ydyufsohxdfpopqbubwk.supabase.co',
-  ANON_KEY: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InlkeXVmc29oeGRmcG9wcWJ1YndrIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NTg3OTYyMDAsImV4cCI6MjA3NDM3MjIwMH0.xESphg6h5ozaDsm4Vla3QnDJGc6Nc_cpfoqTHRynkCk'
-} as const;
 
 export class TelemetryManager {
   private static instance: TelemetryManager;
   private supabase: SupabaseClient | null = null;
   private configManager: TelemetryConfigManager;
-  private eventQueue: TelemetryEvent[] = [];
-  private workflowQueue: WorkflowTelemetry[] = [];
-  private flushTimer?: NodeJS.Timeout;
+  private eventTracker: TelemetryEventTracker;
+  private batchProcessor: TelemetryBatchProcessor;
+  private performanceMonitor: TelemetryPerformanceMonitor;
+  private errorAggregator: TelemetryErrorAggregator;
   private isInitialized: boolean = false;
-  private isFlushingWorkflows: boolean = false;
 
   private constructor() {
+    // Prevent direct instantiation even when TypeScript is bypassed
+    if (TelemetryManager.instance) {
+      throw new Error('Use TelemetryManager.getInstance() instead of new TelemetryManager()');
+    }
+
     this.configManager = TelemetryConfigManager.getInstance();
-    this.initialize();
+    this.errorAggregator = new TelemetryErrorAggregator();
+    this.performanceMonitor = new TelemetryPerformanceMonitor();
+
+    // Initialize event tracker with callbacks
+    this.eventTracker = new TelemetryEventTracker(
+      () => this.configManager.getUserId(),
+      () => this.isEnabled()
+    );
+
+    // Initialize batch processor (will be configured after Supabase init)
+    this.batchProcessor = new TelemetryBatchProcessor(
+      null,
+      () => this.isEnabled()
+    );
+
+    // Delay initialization to first use, not constructor
+    // this.initialize();
   }
 
   static getInstance(): TelemetryManager {
@@ -73,6 +55,15 @@ export class TelemetryManager {
     return TelemetryManager.instance;
   }
 
+  /**
+   * Ensure telemetry is initialized before use
+   */
+  private ensureInitialized(): void {
+    if (!this.isInitialized && this.configManager.isEnabled()) {
+      this.initialize();
+    }
+  }
+
   /**
    * Initialize telemetry if enabled
    */
@@ -100,23 +91,24 @@ export class TelemetryManager {
         },
       });
 
-      this.isInitialized = true;
-      this.startBatchProcessor();
+      // Update batch processor with Supabase client
+      this.batchProcessor = new TelemetryBatchProcessor(
+        this.supabase,
+        () => this.isEnabled()
+      );
 
-      // Flush on exit
-      process.on('beforeExit', () => this.flush());
-      process.on('SIGINT', () => {
-        this.flush();
-        process.exit(0);
-      });
-      process.on('SIGTERM', () => {
-        this.flush();
-        process.exit(0);
-      });
+      this.batchProcessor.start();
+      this.isInitialized = true;
 
       logger.debug('Telemetry initialized successfully');
     } catch (error) {
-      logger.debug('Failed to initialize telemetry:', error);
+      const telemetryError = new TelemetryError(
+        TelemetryErrorType.INITIALIZATION_ERROR,
+        'Failed to initialize telemetry',
+        { error: error instanceof Error ? error.message : String(error) }
+      );
+      this.errorAggregator.record(telemetryError);
+      telemetryError.log();
       this.isInitialized = false;
     }
   }
@@ -125,395 +117,137 @@ export class TelemetryManager {
    * Track a tool usage event
    */
   trackToolUsage(toolName: string, success: boolean, duration?: number): void {
-    if (!this.isEnabled()) return;
-
-    // Sanitize tool name (remove any potential sensitive data)
-    const sanitizedToolName = toolName.replace(/[^a-zA-Z0-9_-]/g, '_');
-
-    this.trackEvent('tool_used', {
-      tool: sanitizedToolName,
-      success,
-      duration: duration || 0,
-    });
+    this.ensureInitialized();
+    this.performanceMonitor.startOperation('trackToolUsage');
+    this.eventTracker.trackToolUsage(toolName, success, duration);
+    this.eventTracker.updateToolSequence(toolName);
+    this.performanceMonitor.endOperation('trackToolUsage');
   }
 
   /**
-   * Track workflow creation (fire-and-forget)
+   * Track workflow creation
    */
-  trackWorkflowCreation(workflow: any, validationPassed: boolean): void {
-    if (!this.isEnabled()) return;
-
-    // Only store workflows that pass validation
-    if (!validationPassed) {
-      this.trackEvent('workflow_validation_failed', {
-        nodeCount: workflow.nodes?.length || 0,
-      });
-      return;
+  async trackWorkflowCreation(workflow: any, validationPassed: boolean): Promise<void> {
+    this.ensureInitialized();
+    this.performanceMonitor.startOperation('trackWorkflowCreation');
+    try {
+      await this.eventTracker.trackWorkflowCreation(workflow, validationPassed);
+      // Auto-flush workflows to prevent data loss
+      await this.flush();
+    } catch (error) {
+      const telemetryError = error instanceof TelemetryError
+        ? error
+        : new TelemetryError(
+            TelemetryErrorType.UNKNOWN_ERROR,
+            'Failed to track workflow',
+            { error: String(error) }
+          );
+      this.errorAggregator.record(telemetryError);
+    } finally {
+      this.performanceMonitor.endOperation('trackWorkflowCreation');
     }
-
-    // Process asynchronously without blocking
-    setImmediate(async () => {
-      try {
-        const sanitized = WorkflowSanitizer.sanitizeWorkflow(workflow);
-
-        const telemetryData: WorkflowTelemetry = {
-          user_id: this.configManager.getUserId(),
-          workflow_hash: sanitized.workflowHash,
-          node_count: sanitized.nodeCount,
-          node_types: sanitized.nodeTypes,
-          has_trigger: sanitized.hasTrigger,
-          has_webhook: sanitized.hasWebhook,
-          complexity: sanitized.complexity,
-          sanitized_workflow: {
-            nodes: sanitized.nodes,
-            connections: sanitized.connections,
-          },
-        };
-
-        // Add to queue synchronously to avoid race conditions
-        const queueLength = this.addToWorkflowQueue(telemetryData);
-
-        // Also track as event
-        this.trackEvent('workflow_created', {
-          nodeCount: sanitized.nodeCount,
-          nodeTypes: sanitized.nodeTypes.length,
-          complexity: sanitized.complexity,
-          hasTrigger: sanitized.hasTrigger,
-          hasWebhook: sanitized.hasWebhook,
-        });
-
-        // Flush if queue reached threshold
-        if (queueLength >= TELEMETRY_CONFIG.WORKFLOW_QUEUE_THRESHOLD) {
-          await this.flush();
-        }
-      } catch (error) {
-        logger.debug('Failed to track workflow creation:', error);
-      }
-    });
   }
 
-  /**
-   * Thread-safe method to add workflow to queue
-   * Returns the new queue length after adding
-   */
-  private addToWorkflowQueue(telemetryData: WorkflowTelemetry): number {
-    // Don't add to queue if we're currently flushing workflows
-    // This prevents race conditions where items are added during flush
-    if (this.isFlushingWorkflows) {
-      // Queue the flush for later to ensure we don't lose data
-      setImmediate(() => {
-        this.workflowQueue.push(telemetryData);
-        if (this.workflowQueue.length >= TELEMETRY_CONFIG.WORKFLOW_QUEUE_THRESHOLD) {
-          this.flush();
-        }
-      });
-      return 0; // Don't trigger immediate flush
-    }
-
-    this.workflowQueue.push(telemetryData);
-    return this.workflowQueue.length;
-  }
 
   /**
    * Track an error event
    */
-  trackError(errorType: string, context: string, toolName?: string): void {
-    if (!this.isEnabled()) return;
-
-    this.trackEvent('error_occurred', {
-      errorType: this.sanitizeErrorType(errorType),
-      context: this.sanitizeContext(context),
-      tool: toolName ? toolName.replace(/[^a-zA-Z0-9_-]/g, '_') : undefined,
-    });
+  trackError(errorType: string, context: string, toolName?: string, errorMessage?: string): void {
+    this.ensureInitialized();
+    this.eventTracker.trackError(errorType, context, toolName, errorMessage);
   }
 
   /**
    * Track a generic event
    */
   trackEvent(eventName: string, properties: Record<string, any>): void {
-    if (!this.isEnabled()) return;
-
-    const event: TelemetryEvent = {
-      user_id: this.configManager.getUserId(),
-      event: eventName,
-      properties: this.sanitizeProperties(properties),
-    };
-
-    this.eventQueue.push(event);
-
-    // Flush if queue is getting large
-    if (this.eventQueue.length >= TELEMETRY_CONFIG.EVENT_QUEUE_THRESHOLD) {
-      this.flush();
-    }
+    this.ensureInitialized();
+    this.eventTracker.trackEvent(eventName, properties);
   }
 
   /**
    * Track session start
    */
   trackSessionStart(): void {
-    if (!this.isEnabled()) return;
-
-    this.trackEvent('session_start', {
-      version: this.getPackageVersion(),
-      platform: process.platform,
-      arch: process.arch,
-      nodeVersion: process.version,
-    });
+    this.ensureInitialized();
+    this.eventTracker.trackSessionStart();
   }
 
   /**
-   * Track search queries to identify documentation gaps
+   * Track search queries
    */
   trackSearchQuery(query: string, resultsFound: number, searchType: string): void {
-    if (!this.isEnabled()) return;
-
-    this.trackEvent('search_query', {
-      query: this.sanitizeString(query).substring(0, 100),
-      resultsFound,
-      searchType,
-      hasResults: resultsFound > 0,
-      isZeroResults: resultsFound === 0
-    });
+    this.eventTracker.trackSearchQuery(query, resultsFound, searchType);
   }
 
   /**
-   * Track validation failure details for improvement insights
+   * Track validation details
    */
   trackValidationDetails(nodeType: string, errorType: string, details: Record<string, any>): void {
-    if (!this.isEnabled()) return;
-
-    this.trackEvent('validation_details', {
-      nodeType: nodeType.replace(/[^a-zA-Z0-9_.-]/g, '_'),
-      errorType: this.sanitizeErrorType(errorType),
-      errorCategory: this.categorizeError(errorType),
-      details: this.sanitizeProperties(details)
-    });
+    this.eventTracker.trackValidationDetails(nodeType, errorType, details);
   }
 
   /**
-   * Track tool usage sequences to understand workflows
+   * Track tool sequences
    */
   trackToolSequence(previousTool: string, currentTool: string, timeDelta: number): void {
-    if (!this.isEnabled()) return;
-
-    this.trackEvent('tool_sequence', {
-      previousTool: previousTool.replace(/[^a-zA-Z0-9_-]/g, '_'),
-      currentTool: currentTool.replace(/[^a-zA-Z0-9_-]/g, '_'),
-      timeDelta: Math.min(timeDelta, 300000), // Cap at 5 minutes
-      isSlowTransition: timeDelta > 10000, // More than 10 seconds
-      sequence: `${previousTool}->${currentTool}`
-    });
+    this.eventTracker.trackToolSequence(previousTool, currentTool, timeDelta);
   }
 
   /**
-   * Track node configuration patterns
+   * Track node configuration
    */
   trackNodeConfiguration(nodeType: string, propertiesSet: number, usedDefaults: boolean): void {
-    if (!this.isEnabled()) return;
-
-    this.trackEvent('node_configuration', {
-      nodeType: nodeType.replace(/[^a-zA-Z0-9_.-]/g, '_'),
-      propertiesSet,
-      usedDefaults,
-      complexity: this.categorizeConfigComplexity(propertiesSet)
-    });
+    this.eventTracker.trackNodeConfiguration(nodeType, propertiesSet, usedDefaults);
   }
 
   /**
-   * Track performance metrics for optimization
+   * Track performance metrics
    */
   trackPerformanceMetric(operation: string, duration: number, metadata?: Record<string, any>): void {
-    if (!this.isEnabled()) return;
-
-    this.trackEvent('performance_metric', {
-      operation: operation.replace(/[^a-zA-Z0-9_-]/g, '_'),
-      duration,
-      isSlow: duration > 1000,
-      isVerySlow: duration > 5000,
-      metadata: metadata ? this.sanitizeProperties(metadata) : undefined
-    });
+    this.eventTracker.trackPerformanceMetric(operation, duration, metadata);
   }
 
-  /**
-   * Categorize error types for better analysis
-   */
-  private categorizeError(errorType: string): string {
-    const lowerError = errorType.toLowerCase();
-    if (lowerError.includes('type')) return 'type_error';
-    if (lowerError.includes('validation')) return 'validation_error';
-    if (lowerError.includes('required')) return 'required_field_error';
-    if (lowerError.includes('connection')) return 'connection_error';
-    if (lowerError.includes('expression')) return 'expression_error';
-    return 'other_error';
-  }
-
-  /**
-   * Categorize configuration complexity
-   */
-  private categorizeConfigComplexity(propertiesSet: number): string {
-    if (propertiesSet === 0) return 'defaults_only';
-    if (propertiesSet <= 3) return 'simple';
-    if (propertiesSet <= 10) return 'moderate';
-    return 'complex';
-  }
-
-  /**
-   * Get package version safely
-   */
-  private getPackageVersion(): string {
-    try {
-      // Try multiple approaches to find package.json
-      const possiblePaths = [
-        resolve(__dirname, '..', '..', 'package.json'),
-        resolve(process.cwd(), 'package.json'),
-        resolve(__dirname, '..', '..', '..', 'package.json')
-      ];
-
-      for (const packagePath of possiblePaths) {
-        if (existsSync(packagePath)) {
-          const packageJson = JSON.parse(readFileSync(packagePath, 'utf-8'));
-          if (packageJson.version) {
-            return packageJson.version;
-          }
-        }
-      }
-
-      // Fallback: try require (works in some environments)
-      try {
-        const packageJson = require('../../package.json');
-        return packageJson.version || 'unknown';
-      } catch {
-        // Ignore require error
-      }
-
-      return 'unknown';
-    } catch (error) {
-      logger.debug('Failed to get package version:', error);
-      return 'unknown';
-    }
-  }
-
-  /**
-   * Execute Supabase operation with retry and timeout
-   */
-  private async executeWithRetry<T>(
-    operation: () => Promise<T>,
-    operationName: string
-  ): Promise<T | null> {
-    let lastError: Error | null = null;
-
-    for (let attempt = 1; attempt <= TELEMETRY_CONFIG.MAX_RETRIES; attempt++) {
-      try {
-        // Create a timeout promise
-        const timeoutPromise = new Promise<never>((_, reject) => {
-          setTimeout(() => reject(new Error('Operation timed out')), TELEMETRY_CONFIG.OPERATION_TIMEOUT);
-        });
-
-        // Race between operation and timeout
-        const result = await Promise.race([operation(), timeoutPromise]) as T;
-        return result;
-      } catch (error) {
-        lastError = error as Error;
-        logger.debug(`${operationName} attempt ${attempt} failed:`, error);
-
-        if (attempt < TELEMETRY_CONFIG.MAX_RETRIES) {
-          // Wait before retrying
-          await new Promise(resolve => setTimeout(resolve, TELEMETRY_CONFIG.RETRY_DELAY * attempt));
-        }
-      }
-    }
-
-    logger.debug(`${operationName} failed after ${TELEMETRY_CONFIG.MAX_RETRIES} attempts:`, lastError);
-    return null;
-  }
 
   /**
    * Flush queued events to Supabase
    */
   async flush(): Promise<void> {
+    this.ensureInitialized();
     if (!this.isEnabled() || !this.supabase) return;
 
-    // Flush events
-    if (this.eventQueue.length > 0) {
-      const events = [...this.eventQueue];
-      this.eventQueue = [];
+    this.performanceMonitor.startOperation('flush');
 
-      await this.executeWithRetry(async () => {
-        const { error } = await this.supabase!
-          .from('telemetry_events')
-          .insert(events);  // No .select() - we don't need the response
+    // Get queued data from event tracker
+    const events = this.eventTracker.getEventQueue();
+    const workflows = this.eventTracker.getWorkflowQueue();
 
-        if (error) {
-          throw error;
-        }
+    // Clear queues immediately to prevent duplicate processing
+    this.eventTracker.clearEventQueue();
+    this.eventTracker.clearWorkflowQueue();
 
-        logger.debug(`Flushed ${events.length} telemetry events`);
-        return true;
-      }, 'Flush telemetry events');
-    }
-
-    // Flush workflows
-    if (this.workflowQueue.length > 0) {
-      this.isFlushingWorkflows = true;
-
-      try {
-        const workflows = [...this.workflowQueue];
-        this.workflowQueue = [];
-
-        const result = await this.executeWithRetry(async () => {
-          // Deduplicate workflows by hash before inserting
-          const uniqueWorkflows = workflows.reduce((acc, workflow) => {
-            if (!acc.some(w => w.workflow_hash === workflow.workflow_hash)) {
-              acc.push(workflow);
-            }
-            return acc;
-          }, [] as WorkflowTelemetry[]);
-
-          logger.debug(`Deduplicating workflows: ${workflows.length} -> ${uniqueWorkflows.length} unique`);
-
-          // Use insert (same as events) - duplicates are handled by deduplication above
-          const { error } = await this.supabase!
-            .from('telemetry_workflows')
-            .insert(uniqueWorkflows);  // No .select() - we don't need the response
-
-          if (error) {
-            logger.debug('Detailed workflow flush error:', {
-              error: error,
-              workflowCount: workflows.length,
-              firstWorkflow: workflows[0] ? {
-                user_id: workflows[0].user_id,
-                workflow_hash: workflows[0].workflow_hash,
-                node_count: workflows[0].node_count
-              } : null
-            });
-            throw error;
-          }
-
-          logger.debug(`Flushed ${uniqueWorkflows.length} unique telemetry workflows (${workflows.length} total processed)`);
-          return true;
-        }, 'Flush telemetry workflows');
-
-        if (!result) {
-          logger.debug('Failed to flush workflows after retries');
-        }
-      } finally {
-        this.isFlushingWorkflows = false;
+    try {
+      // Use batch processor to flush
+      await this.batchProcessor.flush(events, workflows);
+    } catch (error) {
+      const telemetryError = error instanceof TelemetryError
+        ? error
+        : new TelemetryError(
+            TelemetryErrorType.NETWORK_ERROR,
+            'Failed to flush telemetry',
+            { error: String(error) },
+            true // Retryable
+          );
+      this.errorAggregator.record(telemetryError);
+      telemetryError.log();
+    } finally {
+      const duration = this.performanceMonitor.endOperation('flush');
+      if (duration > 100) {
+        logger.debug(`Telemetry flush took ${duration.toFixed(2)}ms`);
       }
     }
   }
 
-  /**
-   * Start batch processor for periodic flushing
-   */
-  private startBatchProcessor(): void {
-    // Flush periodically
-    this.flushTimer = setInterval(() => {
-      this.flush();
-    }, TELEMETRY_CONFIG.BATCH_FLUSH_INTERVAL);
-
-    // Prevent timer from keeping process alive
-    this.flushTimer.unref();
-  }
 
   /**
    * Check if telemetry is enabled
@@ -522,89 +256,12 @@ export class TelemetryManager {
     return this.isInitialized && this.configManager.isEnabled();
   }
 
-  /**
-   * Sanitize properties to remove sensitive data
-   */
-  private sanitizeProperties(properties: Record<string, any>): Record<string, any> {
-    const sanitized: Record<string, any> = {};
-
-    for (const [key, value] of Object.entries(properties)) {
-      // Skip sensitive keys
-      if (this.isSensitiveKey(key)) {
-        continue;
-      }
-
-      // Sanitize values
-      if (typeof value === 'string') {
-        sanitized[key] = this.sanitizeString(value);
-      } else if (typeof value === 'object' && value !== null) {
-        sanitized[key] = this.sanitizeProperties(value);
-      } else {
-        sanitized[key] = value;
-      }
-    }
-
-    return sanitized;
-  }
-
-  /**
-   * Check if a key is sensitive
-   */
-  private isSensitiveKey(key: string): boolean {
-    const sensitiveKeys = [
-      'password', 'token', 'key', 'secret', 'credential',
-      'auth', 'url', 'endpoint', 'host', 'database',
-    ];
-
-    const lowerKey = key.toLowerCase();
-    return sensitiveKeys.some(sensitive => lowerKey.includes(sensitive));
-  }
-
-  /**
-   * Sanitize string values
-   */
-  private sanitizeString(value: string): string {
-    // Remove URLs
-    let sanitized = value.replace(/https?:\/\/[^\s]+/gi, '[URL]');
-
-    // Remove potential API keys (long alphanumeric strings)
-    sanitized = sanitized.replace(/[a-zA-Z0-9_-]{32,}/g, '[KEY]');
-
-    // Remove email addresses
-    sanitized = sanitized.replace(/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g, '[EMAIL]');
-
-    return sanitized;
-  }
-
-  /**
-   * Sanitize error type
-   */
-  private sanitizeErrorType(errorType: string): string {
-    // Remove any potential sensitive data from error type
-    return errorType
-      .replace(/[^a-zA-Z0-9_-]/g, '_')
-      .substring(0, 50);
-  }
-
-  /**
-   * Sanitize context
-   */
-  private sanitizeContext(context: string): string {
-    // Remove any potential sensitive data from context
-    return context
-      .replace(/https?:\/\/[^\s]+/gi, '[URL]')
-      .replace(/[a-zA-Z0-9_-]{32,}/g, '[KEY]')
-      .substring(0, 100);
-  }
-
   /**
    * Disable telemetry
    */
   disable(): void {
     this.configManager.disable();
-    if (this.flushTimer) {
-      clearInterval(this.flushTimer);
-    }
+    this.batchProcessor.stop();
     this.isInitialized = false;
     this.supabase = null;
   }
@@ -623,6 +280,29 @@ export class TelemetryManager {
   getStatus(): string {
     return this.configManager.getStatus();
   }
+
+  /**
+   * Get comprehensive telemetry metrics
+   */
+  getMetrics() {
+    return {
+      status: this.isEnabled() ? 'enabled' : 'disabled',
+      initialized: this.isInitialized,
+      tracking: this.eventTracker.getStats(),
+      processing: this.batchProcessor.getMetrics(),
+      errors: this.errorAggregator.getStats(),
+      performance: this.performanceMonitor.getDetailedReport(),
+      overhead: this.performanceMonitor.getTelemetryOverhead()
+    };
+  }
+
+  /**
+   * Reset singleton instance (for testing purposes)
+   */
+  static resetInstance(): void {
+    TelemetryManager.instance = undefined as any;
+    (global as any).__telemetryManager = undefined;
+  }
 }
 
 // Create a global singleton to ensure only one instance across all imports

src/telemetry/telemetry-types.ts

@@ -0,0 +1,87 @@
+/**
+ * Telemetry Types and Interfaces
+ * Centralized type definitions for the telemetry system
+ */
+
+export interface TelemetryEvent {
+  user_id: string;
+  event: string;
+  properties: Record<string, any>;
+  created_at?: string;
+}
+
+export interface WorkflowTelemetry {
+  user_id: string;
+  workflow_hash: string;
+  node_count: number;
+  node_types: string[];
+  has_trigger: boolean;
+  has_webhook: boolean;
+  complexity: 'simple' | 'medium' | 'complex';
+  sanitized_workflow: any;
+  created_at?: string;
+}
+
+export interface SanitizedWorkflow {
+  nodes: any[];
+  connections: any;
+  nodeCount: number;
+  nodeTypes: string[];
+  hasTrigger: boolean;
+  hasWebhook: boolean;
+  complexity: 'simple' | 'medium' | 'complex';
+  workflowHash: string;
+}
+
+export const TELEMETRY_CONFIG = {
+  // Batch processing
+  BATCH_FLUSH_INTERVAL: 5000, // 5 seconds
+  EVENT_QUEUE_THRESHOLD: 10, // Batch events for efficiency
+  WORKFLOW_QUEUE_THRESHOLD: 5, // Batch workflows
+
+  // Retry logic
+  MAX_RETRIES: 3,
+  RETRY_DELAY: 1000, // 1 second base delay
+  OPERATION_TIMEOUT: 5000, // 5 seconds
+
+  // Rate limiting
+  RATE_LIMIT_WINDOW: 60000, // 1 minute
+  RATE_LIMIT_MAX_EVENTS: 100, // Max events per window
+
+  // Queue limits
+  MAX_QUEUE_SIZE: 1000, // Maximum events to queue
+  MAX_BATCH_SIZE: 50, // Maximum events per batch
+} as const;
+
+export const TELEMETRY_BACKEND = {
+  URL: 'https://ydyufsohxdfpopqbubwk.supabase.co',
+  ANON_KEY: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InlkeXVmc29oeGRmcG9wcWJ1YndrIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NTg3OTYyMDAsImV4cCI6MjA3NDM3MjIwMH0.xESphg6h5ozaDsm4Vla3QnDJGc6Nc_cpfoqTHRynkCk'
+} as const;
+
+export interface TelemetryMetrics {
+  eventsTracked: number;
+  eventsDropped: number;
+  eventsFailed: number;
+  batchesSent: number;
+  batchesFailed: number;
+  averageFlushTime: number;
+  lastFlushTime?: number;
+  rateLimitHits: number;
+}
+
+export enum TelemetryErrorType {
+  VALIDATION_ERROR = 'VALIDATION_ERROR',
+  NETWORK_ERROR = 'NETWORK_ERROR',
+  RATE_LIMIT_ERROR = 'RATE_LIMIT_ERROR',
+  QUEUE_OVERFLOW_ERROR = 'QUEUE_OVERFLOW_ERROR',
+  INITIALIZATION_ERROR = 'INITIALIZATION_ERROR',
+  UNKNOWN_ERROR = 'UNKNOWN_ERROR'
+}
+
+export interface TelemetryErrorContext {
+  type: TelemetryErrorType;
+  message: string;
+  context?: Record<string, any>;
+  timestamp: number;
+  retryable: boolean;
+}

src/templates/batch-processor.ts

@@ -258,85 +258,132 @@ export class BatchProcessor {
   }
   
   /**
-   * Monitor batch job with exponential backoff
+   * Monitor batch job with fixed 1-minute polling interval
    */
   private async monitorBatchJob(batchId: string): Promise<any> {
-    // Start with shorter wait times for better UX
-    const waitTimes = [30, 60, 120, 300, 600, 900, 1800]; // Progressive wait times in seconds
-    let waitIndex = 0;
+    const pollInterval = 60; // Check every 60 seconds (1 minute)
     let attempts = 0;
-    const maxAttempts = 100; // Safety limit
+    const maxAttempts = 120; // 120 minutes max (2 hours)
     const startTime = Date.now();
     let lastStatus = '';
-    
+
     while (attempts < maxAttempts) {
       const batchJob = await this.client.batches.retrieve(batchId);
-      
-      // Only log if status changed
+      const elapsedMinutes = Math.floor((Date.now() - startTime) / 60000);
+
+      // Log status on every check (not just on change)
+      const statusSymbol = batchJob.status === 'in_progress' ? '⚙️' :
+                          batchJob.status === 'finalizing' ? '📦' :
+                          batchJob.status === 'validating' ? '🔍' :
+                          batchJob.status === 'completed' ? '✅' :
+                          batchJob.status === 'failed' ? '❌' : '⏳';
+
+      console.log(`   ${statusSymbol} Batch ${batchId.slice(-8)}: ${batchJob.status} (${elapsedMinutes} min, check ${attempts + 1})`);
+
       if (batchJob.status !== lastStatus) {
-        const elapsedMinutes = Math.floor((Date.now() - startTime) / 60000);
-        const statusSymbol = batchJob.status === 'in_progress' ? '⚙️' : 
-                            batchJob.status === 'finalizing' ? '📦' :
-                            batchJob.status === 'validating' ? '🔍' : '⏳';
-        
-        console.log(`   ${statusSymbol} Batch ${batchId.slice(-8)}: ${batchJob.status} (${elapsedMinutes} min)`);
+        logger.info(`Batch ${batchId} status changed: ${lastStatus} -> ${batchJob.status}`);
         lastStatus = batchJob.status;
       }
-      
-      logger.debug(`Batch ${batchId} status: ${batchJob.status} (attempt ${attempts + 1})`);
-      
+
       if (batchJob.status === 'completed') {
-        const elapsedMinutes = Math.floor((Date.now() - startTime) / 60000);
-        console.log(`   ✅ Batch ${batchId.slice(-8)} completed in ${elapsedMinutes} minutes`);
+        console.log(`   ✅ Batch ${batchId.slice(-8)} completed successfully in ${elapsedMinutes} minutes`);
         logger.info(`Batch job ${batchId} completed successfully`);
         return batchJob;
       }
-      
+
       if (['failed', 'expired', 'cancelled'].includes(batchJob.status)) {
+        logger.error(`Batch job ${batchId} failed with status: ${batchJob.status}`);
         throw new Error(`Batch job failed with status: ${batchJob.status}`);
       }
-      
-      // Wait before next check
-      const waitTime = waitTimes[Math.min(waitIndex, waitTimes.length - 1)];
-      logger.debug(`Waiting ${waitTime} seconds before next check...`);
-      await this.sleep(waitTime * 1000);
-      
-      waitIndex = Math.min(waitIndex + 1, waitTimes.length - 1);
+
+      // Wait before next check (always 1 minute)
+      logger.debug(`Waiting ${pollInterval} seconds before next check...`);
+      await this.sleep(pollInterval * 1000);
+
       attempts++;
     }
-    
-    throw new Error(`Batch job monitoring timed out after ${maxAttempts} attempts`);
+
+    throw new Error(`Batch job monitoring timed out after ${maxAttempts} minutes`);
   }
   
   /**
    * Retrieve and parse results
    */
   private async retrieveResults(batchJob: any): Promise<MetadataResult[]> {
-    if (!batchJob.output_file_id) {
-      throw new Error('No output file available for batch job');
-    }
-    
-    // Download result file
-    const fileResponse = await this.client.files.content(batchJob.output_file_id);
-    const fileContent = await fileResponse.text();
-    
-    // Parse JSONL results
     const results: MetadataResult[] = [];
-    const lines = fileContent.trim().split('\n');
-    
-    for (const line of lines) {
-      if (!line) continue;
-      
+
+    // Check if we have an output file (successful results)
+    if (batchJob.output_file_id) {
+      const fileResponse = await this.client.files.content(batchJob.output_file_id);
+      const fileContent = await fileResponse.text();
+
+      const lines = fileContent.trim().split('\n');
+      for (const line of lines) {
+        if (!line) continue;
+        try {
+          const result = JSON.parse(line);
+          const parsed = this.generator.parseResult(result);
+          results.push(parsed);
+        } catch (error) {
+          logger.error('Error parsing result line:', error);
+        }
+      }
+      logger.info(`Retrieved ${results.length} successful results from batch job`);
+    }
+
+    // Check if we have an error file (failed results)
+    if (batchJob.error_file_id) {
+      logger.warn(`Batch job has error file: ${batchJob.error_file_id}`);
+
       try {
-        const result = JSON.parse(line);
-        const parsed = this.generator.parseResult(result);
-        results.push(parsed);
+        const errorResponse = await this.client.files.content(batchJob.error_file_id);
+        const errorContent = await errorResponse.text();
+
+        // Save error file locally for debugging
+        const errorFilePath = path.join(this.outputDir, `batch_${batchJob.id}_error.jsonl`);
+        fs.writeFileSync(errorFilePath, errorContent);
+        logger.warn(`Error file saved to: ${errorFilePath}`);
+
+        // Parse errors and create default metadata for failed templates
+        const errorLines = errorContent.trim().split('\n');
+        logger.warn(`Found ${errorLines.length} failed requests in error file`);
+
+        for (const line of errorLines) {
+          if (!line) continue;
+          try {
+            const errorResult = JSON.parse(line);
+            const templateId = parseInt(errorResult.custom_id?.replace('template-', '') || '0');
+
+            if (templateId > 0) {
+              const errorMessage = errorResult.response?.body?.error?.message ||
+                                  errorResult.error?.message ||
+                                  'Unknown error';
+
+              logger.debug(`Template ${templateId} failed: ${errorMessage}`);
+
+              // Use getDefaultMetadata() from generator (it's private but accessible via bracket notation)
+              const defaultMeta = (this.generator as any).getDefaultMetadata();
+              results.push({
+                templateId,
+                metadata: defaultMeta,
+                error: errorMessage
+              });
+            }
+          } catch (parseError) {
+            logger.error('Error parsing error line:', parseError);
+          }
+        }
       } catch (error) {
-        logger.error('Error parsing result line:', error);
+        logger.error('Failed to process error file:', error);
       }
     }
-    
-    logger.info(`Retrieved ${results.length} results from batch job`);
+
+    // If we have no results at all, something is very wrong
+    if (results.length === 0 && !batchJob.output_file_id && !batchJob.error_file_id) {
+      throw new Error('No output file or error file available for batch job');
+    }
+
+    logger.info(`Total results (successful + failed): ${results.length}`);
     return results;
   }
   

src/templates/metadata-generator.ts

@@ -34,7 +34,7 @@ export class MetadataGenerator {
   private client: OpenAI;
   private model: string;
   
-  constructor(apiKey: string, model: string = 'gpt-4o-mini') {
+  constructor(apiKey: string, model: string = 'gpt-5-mini-2025-08-07') {
     this.client = new OpenAI({ apiKey });
     this.model = model;
   }
@@ -131,8 +131,8 @@ export class MetadataGenerator {
       url: '/v1/chat/completions',
       body: {
         model: this.model,
-        temperature: 0.3,  // Lower temperature for more consistent structured outputs
-        max_completion_tokens: 1000,
+        // temperature removed - batch API only supports default (1.0) for this model
+        max_completion_tokens: 3000,
         response_format: {
           type: 'json_schema',
           json_schema: this.getJsonSchema()
@@ -288,8 +288,8 @@ export class MetadataGenerator {
     try {
       const completion = await this.client.chat.completions.create({
         model: this.model,
-        temperature: 0.3,  // Lower temperature for more consistent structured outputs
-        max_completion_tokens: 1000,
+        // temperature removed - not supported in batch API for this model
+        max_completion_tokens: 3000,
         response_format: {
           type: 'json_schema',
           json_schema: this.getJsonSchema()

src/templates/template-repository.ts

@@ -625,7 +625,65 @@ export class TemplateRepository {
     
     return { total, withMetadata, withoutMetadata, outdated };
   }
-  
+
+  /**
+   * Build WHERE conditions for metadata filtering
+   * @private
+   * @returns Object containing SQL conditions array and parameter values array
+   */
+  private buildMetadataFilterConditions(filters: {
+    category?: string;
+    complexity?: 'simple' | 'medium' | 'complex';
+    maxSetupMinutes?: number;
+    minSetupMinutes?: number;
+    requiredService?: string;
+    targetAudience?: string;
+  }): { conditions: string[], params: any[] } {
+    const conditions: string[] = ['metadata_json IS NOT NULL'];
+    const params: any[] = [];
+
+    if (filters.category !== undefined) {
+      // Use parameterized LIKE with JSON array search - safe from injection
+      conditions.push("json_extract(metadata_json, '$.categories') LIKE '%' || ? || '%'");
+      // Escape special characters and quotes for JSON string matching
+      const sanitizedCategory = JSON.stringify(filters.category).slice(1, -1);
+      params.push(sanitizedCategory);
+    }
+
+    if (filters.complexity) {
+      conditions.push("json_extract(metadata_json, '$.complexity') = ?");
+      params.push(filters.complexity);
+    }
+
+    if (filters.maxSetupMinutes !== undefined) {
+      conditions.push("CAST(json_extract(metadata_json, '$.estimated_setup_minutes') AS INTEGER) <= ?");
+      params.push(filters.maxSetupMinutes);
+    }
+
+    if (filters.minSetupMinutes !== undefined) {
+      conditions.push("CAST(json_extract(metadata_json, '$.estimated_setup_minutes') AS INTEGER) >= ?");
+      params.push(filters.minSetupMinutes);
+    }
+
+    if (filters.requiredService !== undefined) {
+      // Use parameterized LIKE with JSON array search - safe from injection
+      conditions.push("json_extract(metadata_json, '$.required_services') LIKE '%' || ? || '%'");
+      // Escape special characters and quotes for JSON string matching
+      const sanitizedService = JSON.stringify(filters.requiredService).slice(1, -1);
+      params.push(sanitizedService);
+    }
+
+    if (filters.targetAudience !== undefined) {
+      // Use parameterized LIKE with JSON array search - safe from injection
+      conditions.push("json_extract(metadata_json, '$.target_audience') LIKE '%' || ? || '%'");
+      // Escape special characters and quotes for JSON string matching
+      const sanitizedAudience = JSON.stringify(filters.targetAudience).slice(1, -1);
+      params.push(sanitizedAudience);
+    }
+
+    return { conditions, params };
+  }
+
   /**
    * Search templates by metadata fields
    */
@@ -637,60 +695,72 @@ export class TemplateRepository {
     requiredService?: string;
     targetAudience?: string;
   }, limit: number = 20, offset: number = 0): StoredTemplate[] {
-    const conditions: string[] = ['metadata_json IS NOT NULL'];
-    const params: any[] = [];
-    
-    // Build WHERE conditions based on filters with proper parameterization
-    if (filters.category !== undefined) {
-      // Use parameterized LIKE with JSON array search - safe from injection
-      conditions.push("json_extract(metadata_json, '$.categories') LIKE '%' || ? || '%'");
-      // Escape special characters and quotes for JSON string matching
-      const sanitizedCategory = JSON.stringify(filters.category).slice(1, -1);
-      params.push(sanitizedCategory);
-    }
-    
-    if (filters.complexity) {
-      conditions.push("json_extract(metadata_json, '$.complexity') = ?");
-      params.push(filters.complexity);
-    }
-    
-    if (filters.maxSetupMinutes !== undefined) {
-      conditions.push("CAST(json_extract(metadata_json, '$.estimated_setup_minutes') AS INTEGER) <= ?");
-      params.push(filters.maxSetupMinutes);
-    }
-    
-    if (filters.minSetupMinutes !== undefined) {
-      conditions.push("CAST(json_extract(metadata_json, '$.estimated_setup_minutes') AS INTEGER) >= ?");
-      params.push(filters.minSetupMinutes);
-    }
-    
-    if (filters.requiredService !== undefined) {
-      // Use parameterized LIKE with JSON array search - safe from injection
-      conditions.push("json_extract(metadata_json, '$.required_services') LIKE '%' || ? || '%'");
-      // Escape special characters and quotes for JSON string matching
-      const sanitizedService = JSON.stringify(filters.requiredService).slice(1, -1);
-      params.push(sanitizedService);
-    }
-    
-    if (filters.targetAudience !== undefined) {
-      // Use parameterized LIKE with JSON array search - safe from injection  
-      conditions.push("json_extract(metadata_json, '$.target_audience') LIKE '%' || ? || '%'");
-      // Escape special characters and quotes for JSON string matching
-      const sanitizedAudience = JSON.stringify(filters.targetAudience).slice(1, -1);
-      params.push(sanitizedAudience);
-    }
-    
-    const query = `
-      SELECT * FROM templates 
+    const startTime = Date.now();
+
+    // Build WHERE conditions using shared helper
+    const { conditions, params } = this.buildMetadataFilterConditions(filters);
+
+    // Performance optimization: Use two-phase query to avoid loading large compressed workflows
+    // during metadata filtering. This prevents timeout when no filters are provided.
+    // Phase 1: Get IDs only with metadata filtering (fast - no workflow data)
+    // Add id to ORDER BY to ensure stable ordering
+    const idsQuery = `
+      SELECT id FROM templates
       WHERE ${conditions.join(' AND ')}
-      ORDER BY views DESC, created_at DESC
+      ORDER BY views DESC, created_at DESC, id ASC
       LIMIT ? OFFSET ?
     `;
-    
+
     params.push(limit, offset);
-    const results = this.db.prepare(query).all(...params) as StoredTemplate[];
-    
-    logger.debug(`Metadata search found ${results.length} results`, { filters, count: results.length });
+    const ids = this.db.prepare(idsQuery).all(...params) as { id: number }[];
+
+    const phase1Time = Date.now() - startTime;
+
+    if (ids.length === 0) {
+      logger.debug('Metadata search found 0 results', { filters, phase1Ms: phase1Time });
+      return [];
+    }
+
+    // Defensive validation: ensure all IDs are valid positive integers
+    const idValues = ids.map(r => r.id).filter(id => typeof id === 'number' && id > 0 && Number.isInteger(id));
+
+    if (idValues.length === 0) {
+      logger.warn('No valid IDs after filtering', { filters, originalCount: ids.length });
+      return [];
+    }
+
+    if (idValues.length !== ids.length) {
+      logger.warn('Some IDs were filtered out as invalid', {
+        original: ids.length,
+        valid: idValues.length,
+        filtered: ids.length - idValues.length
+      });
+    }
+
+    // Phase 2: Fetch full records preserving exact order from Phase 1
+    // Use CTE with VALUES to maintain ordering without depending on SQLite's IN clause behavior
+    const phase2Start = Date.now();
+    const orderedQuery = `
+      WITH ordered_ids(id, sort_order) AS (
+        VALUES ${idValues.map((id, idx) => `(${id}, ${idx})`).join(', ')}
+      )
+      SELECT t.* FROM templates t
+      INNER JOIN ordered_ids o ON t.id = o.id
+      ORDER BY o.sort_order
+    `;
+
+    const results = this.db.prepare(orderedQuery).all() as StoredTemplate[];
+    const phase2Time = Date.now() - phase2Start;
+
+    logger.debug(`Metadata search found ${results.length} results`, {
+      filters,
+      count: results.length,
+      phase1Ms: phase1Time,
+      phase2Ms: phase2Time,
+      totalMs: Date.now() - startTime,
+      optimization: 'two-phase-with-ordering'
+    });
+
     return results.map(t => this.decompressWorkflow(t));
   }
   
@@ -705,48 +775,12 @@ export class TemplateRepository {
     requiredService?: string;
     targetAudience?: string;
   }): number {
-    const conditions: string[] = ['metadata_json IS NOT NULL'];
-    const params: any[] = [];
-    
-    if (filters.category !== undefined) {
-      // Use parameterized LIKE with JSON array search - safe from injection
-      conditions.push("json_extract(metadata_json, '$.categories') LIKE '%' || ? || '%'");
-      const sanitizedCategory = JSON.stringify(filters.category).slice(1, -1);
-      params.push(sanitizedCategory);
-    }
-    
-    if (filters.complexity) {
-      conditions.push("json_extract(metadata_json, '$.complexity') = ?");
-      params.push(filters.complexity);
-    }
-    
-    if (filters.maxSetupMinutes !== undefined) {
-      conditions.push("CAST(json_extract(metadata_json, '$.estimated_setup_minutes') AS INTEGER) <= ?");
-      params.push(filters.maxSetupMinutes);
-    }
-    
-    if (filters.minSetupMinutes !== undefined) {
-      conditions.push("CAST(json_extract(metadata_json, '$.estimated_setup_minutes') AS INTEGER) >= ?");
-      params.push(filters.minSetupMinutes);
-    }
-    
-    if (filters.requiredService !== undefined) {
-      // Use parameterized LIKE with JSON array search - safe from injection
-      conditions.push("json_extract(metadata_json, '$.required_services') LIKE '%' || ? || '%'");
-      const sanitizedService = JSON.stringify(filters.requiredService).slice(1, -1);
-      params.push(sanitizedService);
-    }
-    
-    if (filters.targetAudience !== undefined) {
-      // Use parameterized LIKE with JSON array search - safe from injection
-      conditions.push("json_extract(metadata_json, '$.target_audience') LIKE '%' || ? || '%'");
-      const sanitizedAudience = JSON.stringify(filters.targetAudience).slice(1, -1);
-      params.push(sanitizedAudience);
-    }
-    
+    // Build WHERE conditions using shared helper
+    const { conditions, params } = this.buildMetadataFilterConditions(filters);
+
     const query = `SELECT COUNT(*) as count FROM templates WHERE ${conditions.join(' AND ')}`;
     const result = this.db.prepare(query).get(...params) as { count: number };
-    
+
     return result.count;
   }
   

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;
@@ -290,4 +290,86 @@ export interface McpToolResponse {
   message?: string;
   code?: string;
   details?: Record<string, unknown>;
+  executionId?: string;
+  workflowId?: string;
+}
+
+// Execution Filtering Types
+export type ExecutionMode = 'preview' | 'summary' | 'filtered' | 'full';
+
+export interface ExecutionPreview {
+  totalNodes: number;
+  executedNodes: number;
+  estimatedSizeKB: number;
+  nodes: Record<string, NodePreview>;
+}
+
+export interface NodePreview {
+  status: 'success' | 'error';
+  itemCounts: {
+    input: number;
+    output: number;
+  };
+  dataStructure: Record<string, any>;
+  estimatedSizeKB: number;
+  error?: string;
+}
+
+export interface ExecutionRecommendation {
+  canFetchFull: boolean;
+  suggestedMode: ExecutionMode;
+  suggestedItemsLimit?: number;
+  reason: string;
+}
+
+export interface ExecutionFilterOptions {
+  mode?: ExecutionMode;
+  nodeNames?: string[];
+  itemsLimit?: number;
+  includeInputData?: boolean;
+  fieldsToInclude?: string[];
+}
+
+export interface FilteredExecutionResponse {
+  id: string;
+  workflowId: string;
+  status: ExecutionStatus;
+  mode: ExecutionMode;
+  startedAt: string;
+  stoppedAt?: string;
+  duration?: number;
+  finished: boolean;
+
+  // Preview-specific data
+  preview?: ExecutionPreview;
+  recommendation?: ExecutionRecommendation;
+
+  // Summary/Filtered data
+  summary?: {
+    totalNodes: number;
+    executedNodes: number;
+    totalItems: number;
+    hasMoreData: boolean;
+  };
+  nodes?: Record<string, FilteredNodeData>;
+
+  // Error information
+  error?: Record<string, unknown>;
+}
+
+export interface FilteredNodeData {
+  executionTime?: number;
+  itemsInput: number;
+  itemsOutput: number;
+  status: 'success' | 'error';
+  error?: string;
+  data?: {
+    input?: any[][];
+    output?: any[][];
+    metadata: {
+      totalItems: number;
+      itemsShown: number;
+      truncated: boolean;
+    };
+  };
 }

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 {
@@ -72,18 +75,20 @@ export interface RemoveConnectionOperation extends DiffOperation {
   target: string; // Node name or ID
   sourceOutput?: string; // Default: 'main'
   targetInput?: string; // Default: 'main'
+  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
@@ -109,6 +114,25 @@ export interface RemoveTagOperation extends DiffOperation {
   tag: string;
 }
 
+// Connection Cleanup Operations
+export interface CleanStaleConnectionsOperation extends DiffOperation {
+  type: 'cleanStaleConnections';
+  dryRun?: boolean; // If true, return what would be removed without applying changes
+}
+
+export interface ReplaceConnectionsOperation extends DiffOperation {
+  type: 'replaceConnections';
+  connections: {
+    [nodeName: string]: {
+      [outputName: string]: Array<Array<{
+        node: string;
+        type: string;
+        index: number;
+      }>>;
+    };
+  };
+}
+
 // Union type for all operations
 export type WorkflowDiffOperation =
   | AddNodeOperation
@@ -119,17 +143,20 @@ export type WorkflowDiffOperation =
   | DisableNodeOperation
   | AddConnectionOperation
   | RemoveConnectionOperation
-  | UpdateConnectionOperation
+  | RewireConnectionOperation
   | UpdateSettingsOperation
   | UpdateNameOperation
   | AddTagOperation
-  | RemoveTagOperation;
+  | RemoveTagOperation
+  | CleanStaleConnectionsOperation
+  | ReplaceConnectionsOperation;
 
 // Main diff request structure
 export interface WorkflowDiffRequest {
   id: string; // Workflow ID
   operations: WorkflowDiffOperation[];
   validateOnly?: boolean; // If true, only validate without applying
+  continueOnError?: boolean; // If true, apply valid operations even if some fail (default: false for atomic behavior)
 }
 
 // Response types
@@ -145,6 +172,9 @@ export interface WorkflowDiffResult {
   errors?: WorkflowDiffValidationError[];
   operationsApplied?: number;
   message?: string;
+  applied?: number[]; // Indices of successfully applied operations (when continueOnError is true)
+  failed?: number[]; // Indices of failed operations (when continueOnError is true)
+  staleConnectionsRemoved?: Array<{ from: string; to: string }>; // For cleanStaleConnections operation
 }
 
 // Helper type for node reference (supports both ID and name)
@@ -160,9 +190,9 @@ export function isNodeOperation(op: WorkflowDiffOperation): op is
   return ['addNode', 'removeNode', 'updateNode', 'moveNode', 'enableNode', 'disableNode'].includes(op.type);
 }
 
-export function isConnectionOperation(op: WorkflowDiffOperation): op is 
-  AddConnectionOperation | RemoveConnectionOperation | UpdateConnectionOperation {
-  return ['addConnection', 'removeConnection', 'updateConnection'].includes(op.type);
+export function isConnectionOperation(op: WorkflowDiffOperation): op is
+  AddConnectionOperation | RemoveConnectionOperation | RewireConnectionOperation | CleanStaleConnectionsOperation | ReplaceConnectionsOperation {
+  return ['addConnection', 'removeConnection', 'rewireConnection', 'cleanStaleConnections', 'replaceConnections'].includes(op.type);
 }
 
 export function isMetadataOperation(op: WorkflowDiffOperation): op is 

src/utils/n8n-errors.ts

@@ -95,6 +95,25 @@ export function handleN8nApiError(error: unknown): N8nApiError {
   return new N8nApiError('Unknown error occurred', undefined, 'UNKNOWN_ERROR', error);
 }
 
+/**
+ * Format execution error message with guidance to use n8n_get_execution
+ * @param executionId - The execution ID from the failed execution
+ * @param workflowId - Optional workflow ID
+ * @returns Formatted error message with n8n_get_execution guidance
+ */
+export function formatExecutionError(executionId: string, workflowId?: string): string {
+  const workflowPrefix = workflowId ? `Workflow ${workflowId} execution ` : 'Execution ';
+  return `${workflowPrefix}${executionId} failed. Use n8n_get_execution({id: '${executionId}', mode: 'preview'}) to investigate the error.`;
+}
+
+/**
+ * Format error message when no execution ID is available
+ * @returns Generic guidance to check executions
+ */
+export function formatNoExecutionError(): string {
+  return "Workflow failed to execute. Use n8n_list_executions to find recent executions, then n8n_get_execution with mode='preview' to investigate.";
+}
+
 // Utility to extract user-friendly error messages
 export function getUserFriendlyErrorMessage(error: N8nApiError): string {
   switch (error.code) {
@@ -109,7 +128,9 @@ export function getUserFriendlyErrorMessage(error: N8nApiError): string {
     case 'NO_RESPONSE':
       return 'Unable to connect to n8n. Please check the server URL and ensure n8n is running.';
     case 'SERVER_ERROR':
-      return 'n8n server error. Please try again later or contact support.';
+      // For server errors, we should not show generic message
+      // Callers should check for execution context and use formatExecutionError instead
+      return error.message || 'n8n server error occurred';
     default:
       return error.message || 'An unexpected error occurred';
   }

src/utils/node-type-normalizer.ts

@@ -0,0 +1,234 @@
+/**
+ * Universal Node Type Normalizer - FOR DATABASE OPERATIONS ONLY
+ *
+ * ⚠️ WARNING: Do NOT use before n8n API calls!
+ *
+ * This class converts node types to SHORT form (database format).
+ * The n8n API requires FULL form (n8n-nodes-base.*).
+ *
+ * **Use this ONLY when:**
+ * - Querying the node database
+ * - Searching for node information
+ * - Looking up node metadata
+ *
+ * **Do NOT use before:**
+ * - Creating workflows (n8n_create_workflow)
+ * - Updating workflows (n8n_update_workflow)
+ * - Any n8n API calls
+ *
+ * **IMPORTANT:** The n8n-mcp database stores nodes in SHORT form:
+ * - n8n-nodes-base → nodes-base
+ * - @n8n/n8n-nodes-langchain → nodes-langchain
+ *
+ * But the n8n API requires FULL form:
+ * - nodes-base → n8n-nodes-base
+ * - nodes-langchain → @n8n/n8n-nodes-langchain
+ *
+ * @example Database Lookup (CORRECT usage)
+ * const dbType = NodeTypeNormalizer.normalizeToFullForm('n8n-nodes-base.webhook')
+ * // → 'nodes-base.webhook'
+ * const node = await repository.getNode(dbType)
+ *
+ * @example API Call (INCORRECT - Do NOT do this!)
+ * const workflow = { nodes: [{ type: 'n8n-nodes-base.webhook' }] }
+ * const normalized = NodeTypeNormalizer.normalizeWorkflowNodeTypes(workflow)
+ * // ❌ WRONG! normalized has SHORT form, API needs FULL form
+ * await client.createWorkflow(normalized) // FAILS!
+ *
+ * @example API Call (CORRECT)
+ * const workflow = { nodes: [{ type: 'n8n-nodes-base.webhook' }] }
+ * // ✅ Send as-is to API (FULL form required)
+ * await client.createWorkflow(workflow) // WORKS!
+ */
+
+export interface NodeTypeNormalizationResult {
+  original: string;
+  normalized: string;
+  wasNormalized: boolean;
+  package: 'base' | 'langchain' | 'community' | 'unknown';
+}
+
+export class NodeTypeNormalizer {
+  /**
+   * Normalize node type to canonical SHORT form (database format)
+   *
+   * This is the PRIMARY method to use throughout the codebase.
+   * It converts any node type variation to the SHORT form that the database uses.
+   *
+   * **NOTE:** Method name says "ToFullForm" for backward compatibility,
+   * but actually normalizes TO SHORT form to match database storage.
+   *
+   * @param type - Node type in any format
+   * @returns Normalized node type in short form (database format)
+   *
+   * @example
+   * normalizeToFullForm('n8n-nodes-base.webhook')
+   * // → 'nodes-base.webhook'
+   *
+   * @example
+   * normalizeToFullForm('nodes-base.webhook')
+   * // → 'nodes-base.webhook' (unchanged)
+   *
+   * @example
+   * normalizeToFullForm('@n8n/n8n-nodes-langchain.agent')
+   * // → 'nodes-langchain.agent'
+   */
+  static normalizeToFullForm(type: string): string {
+    if (!type || typeof type !== 'string') {
+      return type;
+    }
+
+    // Normalize full forms to short form (database format)
+    if (type.startsWith('n8n-nodes-base.')) {
+      return type.replace(/^n8n-nodes-base\./, 'nodes-base.');
+    }
+    if (type.startsWith('@n8n/n8n-nodes-langchain.')) {
+      return type.replace(/^@n8n\/n8n-nodes-langchain\./, 'nodes-langchain.');
+    }
+    // Handle n8n-nodes-langchain without @n8n/ prefix
+    if (type.startsWith('n8n-nodes-langchain.')) {
+      return type.replace(/^n8n-nodes-langchain\./, 'nodes-langchain.');
+    }
+
+    // Already in short form or community node - return unchanged
+    return type;
+  }
+
+  /**
+   * Normalize with detailed result including metadata
+   *
+   * Use this when you need to know if normalization occurred
+   * or what package the node belongs to.
+   *
+   * @param type - Node type in any format
+   * @returns Detailed normalization result
+   *
+   * @example
+   * normalizeWithDetails('nodes-base.webhook')
+   * // → {
+   * //   original: 'nodes-base.webhook',
+   * //   normalized: 'n8n-nodes-base.webhook',
+   * //   wasNormalized: true,
+   * //   package: 'base'
+   * // }
+   */
+  static normalizeWithDetails(type: string): NodeTypeNormalizationResult {
+    const original = type;
+    const normalized = this.normalizeToFullForm(type);
+
+    return {
+      original,
+      normalized,
+      wasNormalized: original !== normalized,
+      package: this.detectPackage(normalized)
+    };
+  }
+
+  /**
+   * Detect package type from node type
+   *
+   * @param type - Node type (in any form)
+   * @returns Package identifier
+   */
+  private static detectPackage(type: string): 'base' | 'langchain' | 'community' | 'unknown' {
+    // Check both short and full forms
+    if (type.startsWith('nodes-base.') || type.startsWith('n8n-nodes-base.')) return 'base';
+    if (type.startsWith('nodes-langchain.') || type.startsWith('@n8n/n8n-nodes-langchain.') || type.startsWith('n8n-nodes-langchain.')) return 'langchain';
+    if (type.includes('.')) return 'community';
+    return 'unknown';
+  }
+
+  /**
+   * Batch normalize multiple node types
+   *
+   * Use this when you need to normalize multiple types at once.
+   *
+   * @param types - Array of node types
+   * @returns Map of original → normalized types
+   *
+   * @example
+   * normalizeBatch(['nodes-base.webhook', 'nodes-base.set'])
+   * // → Map {
+   * //   'nodes-base.webhook' => 'n8n-nodes-base.webhook',
+   * //   'nodes-base.set' => 'n8n-nodes-base.set'
+   * // }
+   */
+  static normalizeBatch(types: string[]): Map<string, string> {
+    const result = new Map<string, string>();
+    for (const type of types) {
+      result.set(type, this.normalizeToFullForm(type));
+    }
+    return result;
+  }
+
+  /**
+   * Normalize all node types in a workflow
+   *
+   * This is the key method for fixing workflows before validation.
+   * It normalizes all node types in place while preserving all other
+   * workflow properties.
+   *
+   * @param workflow - Workflow object with nodes array
+   * @returns Workflow with normalized node types
+   *
+   * @example
+   * const workflow = {
+   *   nodes: [
+   *     { type: 'nodes-base.webhook', id: '1', name: 'Webhook' },
+   *     { type: 'nodes-base.set', id: '2', name: 'Set' }
+   *   ],
+   *   connections: {}
+   * };
+   * const normalized = normalizeWorkflowNodeTypes(workflow);
+   * // workflow.nodes[0].type → 'n8n-nodes-base.webhook'
+   * // workflow.nodes[1].type → 'n8n-nodes-base.set'
+   */
+  static normalizeWorkflowNodeTypes(workflow: any): any {
+    if (!workflow?.nodes || !Array.isArray(workflow.nodes)) {
+      return workflow;
+    }
+
+    return {
+      ...workflow,
+      nodes: workflow.nodes.map((node: any) => ({
+        ...node,
+        type: this.normalizeToFullForm(node.type)
+      }))
+    };
+  }
+
+  /**
+   * Check if a node type is in full form (needs normalization)
+   *
+   * @param type - Node type to check
+   * @returns True if in full form (will be normalized to short)
+   */
+  static isFullForm(type: string): boolean {
+    if (!type || typeof type !== 'string') {
+      return false;
+    }
+
+    return (
+      type.startsWith('n8n-nodes-base.') ||
+      type.startsWith('@n8n/n8n-nodes-langchain.') ||
+      type.startsWith('n8n-nodes-langchain.')
+    );
+  }
+
+  /**
+   * Check if a node type is in short form (database format)
+   *
+   * @param type - Node type to check
+   * @returns True if in short form (already in database format)
+   */
+  static isShortForm(type: string): boolean {
+    if (!type || typeof type !== 'string') {
+      return false;
+    }
+
+    return (
+      type.startsWith('nodes-base.') ||
+      type.startsWith('nodes-langchain.')
+    );
+  }
+}

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/template-sanitizer.ts

@@ -19,11 +19,17 @@ export const defaultSanitizerConfig: SanitizerConfig = {
   tokenPatterns: [
     /apify_api_[A-Za-z0-9]+/g,
     /sk-[A-Za-z0-9]+/g, // OpenAI tokens
+    /pat[A-Za-z0-9_]{40,}/g, // Airtable Personal Access Tokens
+    /ghp_[A-Za-z0-9]{36,}/g, // GitHub Personal Access Tokens
+    /gho_[A-Za-z0-9]{36,}/g, // GitHub OAuth tokens
     /Bearer\s+[A-Za-z0-9\-._~+\/]+=*/g // Generic bearer tokens
   ],
   replacements: new Map([
     ['apify_api_', 'apify_api_YOUR_TOKEN_HERE'],
     ['sk-', 'sk-YOUR_OPENAI_KEY_HERE'],
+    ['pat', 'patYOUR_AIRTABLE_TOKEN_HERE'],
+    ['ghp_', 'ghp_YOUR_GITHUB_TOKEN_HERE'],
+    ['gho_', 'gho_YOUR_GITHUB_TOKEN_HERE'],
     ['Bearer ', 'Bearer YOUR_TOKEN_HERE']
   ])
 };

tests/fixtures/template-configs.ts

@@ -0,0 +1,484 @@
+/**
+ * Test fixtures for template node configurations
+ * Used across unit and integration tests for P0-R3 feature
+ */
+
+import * as zlib from 'zlib';
+
+export interface TemplateConfigFixture {
+  node_type: string;
+  template_id: number;
+  template_name: string;
+  template_views: number;
+  node_name: string;
+  parameters_json: string;
+  credentials_json: string | null;
+  has_credentials: number;
+  has_expressions: number;
+  complexity: 'simple' | 'medium' | 'complex';
+  use_cases: string;
+  rank?: number;
+}
+
+export interface WorkflowFixture {
+  id: string;
+  name: string;
+  nodes: any[];
+  connections: Record<string, any>;
+  settings?: Record<string, any>;
+}
+
+/**
+ * Sample node configurations for common use cases
+ */
+export const sampleConfigs: Record<string, TemplateConfigFixture> = {
+  simpleWebhook: {
+    node_type: 'n8n-nodes-base.webhook',
+    template_id: 1,
+    template_name: 'Simple Webhook Trigger',
+    template_views: 5000,
+    node_name: 'Webhook',
+    parameters_json: JSON.stringify({
+      httpMethod: 'POST',
+      path: 'webhook',
+      responseMode: 'lastNode',
+      alwaysOutputData: true
+    }),
+    credentials_json: null,
+    has_credentials: 0,
+    has_expressions: 0,
+    complexity: 'simple',
+    use_cases: JSON.stringify(['webhook processing', 'trigger automation']),
+    rank: 1
+  },
+
+  webhookWithAuth: {
+    node_type: 'n8n-nodes-base.webhook',
+    template_id: 2,
+    template_name: 'Authenticated Webhook',
+    template_views: 3000,
+    node_name: 'Webhook',
+    parameters_json: JSON.stringify({
+      httpMethod: 'POST',
+      path: 'secure-webhook',
+      responseMode: 'responseNode',
+      authentication: 'headerAuth'
+    }),
+    credentials_json: JSON.stringify({
+      httpHeaderAuth: {
+        id: '1',
+        name: 'Header Auth'
+      }
+    }),
+    has_credentials: 1,
+    has_expressions: 0,
+    complexity: 'medium',
+    use_cases: JSON.stringify(['secure webhook', 'authenticated triggers']),
+    rank: 2
+  },
+
+  httpRequestBasic: {
+    node_type: 'n8n-nodes-base.httpRequest',
+    template_id: 3,
+    template_name: 'Basic HTTP GET Request',
+    template_views: 10000,
+    node_name: 'HTTP Request',
+    parameters_json: JSON.stringify({
+      url: 'https://api.example.com/data',
+      method: 'GET',
+      responseFormat: 'json',
+      options: {
+        timeout: 10000,
+        redirect: {
+          followRedirects: true
+        }
+      }
+    }),
+    credentials_json: null,
+    has_credentials: 0,
+    has_expressions: 0,
+    complexity: 'simple',
+    use_cases: JSON.stringify(['API calls', 'data fetching']),
+    rank: 1
+  },
+
+  httpRequestWithExpressions: {
+    node_type: 'n8n-nodes-base.httpRequest',
+    template_id: 4,
+    template_name: 'Dynamic HTTP Request',
+    template_views: 7500,
+    node_name: 'HTTP Request',
+    parameters_json: JSON.stringify({
+      url: '={{ $json.apiUrl }}',
+      method: 'POST',
+      sendBody: true,
+      bodyParameters: {
+        values: [
+          {
+            name: 'userId',
+            value: '={{ $json.userId }}'
+          },
+          {
+            name: 'action',
+            value: '={{ $json.action }}'
+          }
+        ]
+      },
+      options: {
+        timeout: '={{ $json.timeout || 10000 }}'
+      }
+    }),
+    credentials_json: null,
+    has_credentials: 0,
+    has_expressions: 1,
+    complexity: 'complex',
+    use_cases: JSON.stringify(['dynamic API calls', 'expression-based routing']),
+    rank: 2
+  },
+
+  slackMessage: {
+    node_type: 'n8n-nodes-base.slack',
+    template_id: 5,
+    template_name: 'Send Slack Message',
+    template_views: 8000,
+    node_name: 'Slack',
+    parameters_json: JSON.stringify({
+      resource: 'message',
+      operation: 'post',
+      channel: '#general',
+      text: 'Hello from n8n!'
+    }),
+    credentials_json: JSON.stringify({
+      slackApi: {
+        id: '2',
+        name: 'Slack API'
+      }
+    }),
+    has_credentials: 1,
+    has_expressions: 0,
+    complexity: 'simple',
+    use_cases: JSON.stringify(['notifications', 'team communication']),
+    rank: 1
+  },
+
+  codeNodeTransform: {
+    node_type: 'n8n-nodes-base.code',
+    template_id: 6,
+    template_name: 'Data Transformation',
+    template_views: 6000,
+    node_name: 'Code',
+    parameters_json: JSON.stringify({
+      mode: 'runOnceForAllItems',
+      jsCode: `const items = $input.all();
+
+return items.map(item => ({
+  json: {
+    id: item.json.id,
+    name: item.json.name.toUpperCase(),
+    timestamp: new Date().toISOString()
+  }
+}));`
+    }),
+    credentials_json: null,
+    has_credentials: 0,
+    has_expressions: 0,
+    complexity: 'medium',
+    use_cases: JSON.stringify(['data transformation', 'custom logic']),
+    rank: 1
+  },
+
+  codeNodeWithExpressions: {
+    node_type: 'n8n-nodes-base.code',
+    template_id: 7,
+    template_name: 'Advanced Code with Expressions',
+    template_views: 4500,
+    node_name: 'Code',
+    parameters_json: JSON.stringify({
+      mode: 'runOnceForEachItem',
+      jsCode: `const data = $input.item.json;
+const previousNode = $('HTTP Request').first().json;
+
+return {
+  json: {
+    combined: data.value + previousNode.value,
+    nodeRef: $node
+  }
+};`
+    }),
+    credentials_json: null,
+    has_credentials: 0,
+    has_expressions: 1,
+    complexity: 'complex',
+    use_cases: JSON.stringify(['advanced transformations', 'node references']),
+    rank: 2
+  }
+};
+
+/**
+ * Sample workflows for testing extraction
+ */
+export const sampleWorkflows: Record<string, WorkflowFixture> = {
+  webhookToSlack: {
+    id: '1',
+    name: 'Webhook to Slack Notification',
+    nodes: [
+      {
+        id: 'webhook1',
+        name: 'Webhook',
+        type: 'n8n-nodes-base.webhook',
+        typeVersion: 1,
+        position: [250, 300],
+        parameters: {
+          httpMethod: 'POST',
+          path: 'alert',
+          responseMode: 'lastNode'
+        }
+      },
+      {
+        id: 'slack1',
+        name: 'Slack',
+        type: 'n8n-nodes-base.slack',
+        typeVersion: 1,
+        position: [450, 300],
+        parameters: {
+          resource: 'message',
+          operation: 'post',
+          channel: '#alerts',
+          text: '={{ $json.message }}'
+        },
+        credentials: {
+          slackApi: {
+            id: '1',
+            name: 'Slack API'
+          }
+        }
+      }
+    ],
+    connections: {
+      webhook1: {
+        main: [[{ node: 'slack1', type: 'main', index: 0 }]]
+      }
+    },
+    settings: {}
+  },
+
+  apiWorkflow: {
+    id: '2',
+    name: 'API Data Processing',
+    nodes: [
+      {
+        id: 'http1',
+        name: 'Fetch Data',
+        type: 'n8n-nodes-base.httpRequest',
+        typeVersion: 3,
+        position: [250, 300],
+        parameters: {
+          url: 'https://api.example.com/users',
+          method: 'GET',
+          responseFormat: 'json'
+        }
+      },
+      {
+        id: 'code1',
+        name: 'Transform',
+        type: 'n8n-nodes-base.code',
+        typeVersion: 2,
+        position: [450, 300],
+        parameters: {
+          mode: 'runOnceForAllItems',
+          jsCode: 'return $input.all().map(item => ({ json: { ...item.json, processed: true } }));'
+        }
+      },
+      {
+        id: 'http2',
+        name: 'Send Results',
+        type: 'n8n-nodes-base.httpRequest',
+        typeVersion: 3,
+        position: [650, 300],
+        parameters: {
+          url: '={{ $json.callbackUrl }}',
+          method: 'POST',
+          sendBody: true,
+          bodyParameters: {
+            values: [
+              { name: 'data', value: '={{ JSON.stringify($json) }}' }
+            ]
+          }
+        }
+      }
+    ],
+    connections: {
+      http1: {
+        main: [[{ node: 'code1', type: 'main', index: 0 }]]
+      },
+      code1: {
+        main: [[{ node: 'http2', type: 'main', index: 0 }]]
+      }
+    },
+    settings: {}
+  },
+
+  complexWorkflow: {
+    id: '3',
+    name: 'Complex Multi-Node Workflow',
+    nodes: [
+      {
+        id: 'webhook1',
+        name: 'Start',
+        type: 'n8n-nodes-base.webhook',
+        typeVersion: 1,
+        position: [100, 300],
+        parameters: {
+          httpMethod: 'POST',
+          path: 'start'
+        }
+      },
+      {
+        id: 'sticky1',
+        name: 'Note',
+        type: 'n8n-nodes-base.stickyNote',
+        typeVersion: 1,
+        position: [100, 200],
+        parameters: {
+          content: 'This workflow processes incoming data'
+        }
+      },
+      {
+        id: 'if1',
+        name: 'Check Type',
+        type: 'n8n-nodes-base.if',
+        typeVersion: 1,
+        position: [300, 300],
+        parameters: {
+          conditions: {
+            boolean: [
+              {
+                value1: '={{ $json.type }}',
+                value2: 'premium'
+              }
+            ]
+          }
+        }
+      },
+      {
+        id: 'http1',
+        name: 'Premium API',
+        type: 'n8n-nodes-base.httpRequest',
+        typeVersion: 3,
+        position: [500, 200],
+        parameters: {
+          url: 'https://api.example.com/premium',
+          method: 'POST'
+        }
+      },
+      {
+        id: 'http2',
+        name: 'Standard API',
+        type: 'n8n-nodes-base.httpRequest',
+        typeVersion: 3,
+        position: [500, 400],
+        parameters: {
+          url: 'https://api.example.com/standard',
+          method: 'POST'
+        }
+      }
+    ],
+    connections: {
+      webhook1: {
+        main: [[{ node: 'if1', type: 'main', index: 0 }]]
+      },
+      if1: {
+        main: [
+          [{ node: 'http1', type: 'main', index: 0 }],
+          [{ node: 'http2', type: 'main', index: 0 }]
+        ]
+      }
+    },
+    settings: {}
+  }
+};
+
+/**
+ * Compress workflow to base64 (mimics n8n template format)
+ */
+export function compressWorkflow(workflow: WorkflowFixture): string {
+  const json = JSON.stringify(workflow);
+  return zlib.gzipSync(Buffer.from(json, 'utf-8')).toString('base64');
+}
+
+/**
+ * Create template metadata
+ */
+export function createTemplateMetadata(complexity: 'simple' | 'medium' | 'complex', useCases: string[]) {
+  return {
+    complexity,
+    use_cases: useCases
+  };
+}
+
+/**
+ * Batch create configs for testing
+ */
+export function createConfigBatch(nodeType: string, count: number): TemplateConfigFixture[] {
+  return Array.from({ length: count }, (_, i) => ({
+    node_type: nodeType,
+    template_id: i + 1,
+    template_name: `Template ${i + 1}`,
+    template_views: 1000 - (i * 50),
+    node_name: `Node ${i + 1}`,
+    parameters_json: JSON.stringify({ index: i }),
+    credentials_json: null,
+    has_credentials: 0,
+    has_expressions: 0,
+    complexity: (['simple', 'medium', 'complex'] as const)[i % 3],
+    use_cases: JSON.stringify(['test use case']),
+    rank: i + 1
+  }));
+}
+
+/**
+ * Get config by complexity
+ */
+export function getConfigByComplexity(complexity: 'simple' | 'medium' | 'complex'): TemplateConfigFixture {
+  const configs = Object.values(sampleConfigs);
+  const match = configs.find(c => c.complexity === complexity);
+  return match || configs[0];
+}
+
+/**
+ * Get configs with expressions
+ */
+export function getConfigsWithExpressions(): TemplateConfigFixture[] {
+  return Object.values(sampleConfigs).filter(c => c.has_expressions === 1);
+}
+
+/**
+ * Get configs with credentials
+ */
+export function getConfigsWithCredentials(): TemplateConfigFixture[] {
+  return Object.values(sampleConfigs).filter(c => c.has_credentials === 1);
+}
+
+/**
+ * Mock database insert helper
+ */
+export function createInsertStatement(config: TemplateConfigFixture): string {
+  return `INSERT INTO template_node_configs (
+    node_type, template_id, template_name, template_views,
+    node_name, parameters_json, credentials_json,
+    has_credentials, has_expressions, complexity, use_cases, rank
+  ) VALUES (
+    '${config.node_type}',
+    ${config.template_id},
+    '${config.template_name}',
+    ${config.template_views},
+    '${config.node_name}',
+    '${config.parameters_json.replace(/'/g, "''")}',
+    ${config.credentials_json ? `'${config.credentials_json.replace(/'/g, "''")}'` : 'NULL'},
+    ${config.has_credentials},
+    ${config.has_expressions},
+    '${config.complexity}',
+    '${config.use_cases.replace(/'/g, "''")}',
+    ${config.rank || 0}
+  )`;
+}

tests/integration/database/template-node-configs.test.ts

@@ -0,0 +1,534 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import Database from 'better-sqlite3';
+import { DatabaseAdapter, createDatabaseAdapter } from '../../../src/database/database-adapter';
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Integration tests for template_node_configs table
+ * Testing database schema, migrations, and data operations
+ */
+
+describe('Template Node Configs Database Integration', () => {
+  let db: DatabaseAdapter;
+  let dbPath: string;
+
+  beforeEach(async () => {
+    // Create temporary database
+    dbPath = ':memory:';
+    db = await createDatabaseAdapter(dbPath);
+
+    // Apply schema
+    const schemaPath = path.join(__dirname, '../../../src/database/schema.sql');
+    const schema = fs.readFileSync(schemaPath, 'utf-8');
+    db.exec(schema);
+
+    // Apply migration
+    const migrationPath = path.join(__dirname, '../../../src/database/migrations/add-template-node-configs.sql');
+    const migration = fs.readFileSync(migrationPath, 'utf-8');
+    db.exec(migration);
+
+    // Insert test templates with id 1-1000 to satisfy foreign key constraints
+    // Tests insert configs with various template_id values, so we pre-create many templates
+    const stmt = db.prepare(`
+      INSERT INTO templates (
+        id, workflow_id, name, description, views,
+        nodes_used, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, datetime('now'), datetime('now'))
+    `);
+    for (let i = 1; i <= 1000; i++) {
+      stmt.run(i, i, `Test Template ${i}`, 'Test template for node configs', 100, '[]');
+    }
+  });
+
+  afterEach(() => {
+    if ('close' in db && typeof db.close === 'function') {
+      db.close();
+    }
+  });
+
+  describe('Schema Validation', () => {
+    it('should create template_node_configs table', () => {
+      const tableExists = db.prepare(`
+        SELECT name FROM sqlite_master
+        WHERE type='table' AND name='template_node_configs'
+      `).get();
+
+      expect(tableExists).toBeDefined();
+      expect(tableExists).toHaveProperty('name', 'template_node_configs');
+    });
+
+    it('should have all required columns', () => {
+      const columns = db.prepare(`PRAGMA table_info(template_node_configs)`).all() as any[];
+
+      const columnNames = columns.map(col => col.name);
+      expect(columnNames).toContain('id');
+      expect(columnNames).toContain('node_type');
+      expect(columnNames).toContain('template_id');
+      expect(columnNames).toContain('template_name');
+      expect(columnNames).toContain('template_views');
+      expect(columnNames).toContain('node_name');
+      expect(columnNames).toContain('parameters_json');
+      expect(columnNames).toContain('credentials_json');
+      expect(columnNames).toContain('has_credentials');
+      expect(columnNames).toContain('has_expressions');
+      expect(columnNames).toContain('complexity');
+      expect(columnNames).toContain('use_cases');
+      expect(columnNames).toContain('rank');
+      expect(columnNames).toContain('created_at');
+    });
+
+    it('should have correct column types and constraints', () => {
+      const columns = db.prepare(`PRAGMA table_info(template_node_configs)`).all() as any[];
+
+      const idColumn = columns.find(col => col.name === 'id');
+      expect(idColumn.pk).toBe(1); // Primary key
+
+      const nodeTypeColumn = columns.find(col => col.name === 'node_type');
+      expect(nodeTypeColumn.notnull).toBe(1); // NOT NULL
+
+      const parametersJsonColumn = columns.find(col => col.name === 'parameters_json');
+      expect(parametersJsonColumn.notnull).toBe(1); // NOT NULL
+    });
+
+    it('should have complexity CHECK constraint', () => {
+      // Try to insert invalid complexity
+      expect(() => {
+        db.prepare(`
+          INSERT INTO template_node_configs (
+            node_type, template_id, template_name, template_views,
+            node_name, parameters_json, complexity
+          ) VALUES (?, ?, ?, ?, ?, ?, ?)
+        `).run(
+          'n8n-nodes-base.test',
+          1,
+          'Test Template',
+          100,
+          'Test Node',
+          '{}',
+          'invalid' // Should fail CHECK constraint
+        );
+      }).toThrow();
+    });
+
+    it('should accept valid complexity values', () => {
+      const validComplexities = ['simple', 'medium', 'complex'];
+
+      validComplexities.forEach((complexity, index) => {
+        expect(() => {
+          db.prepare(`
+            INSERT INTO template_node_configs (
+              node_type, template_id, template_name, template_views,
+              node_name, parameters_json, complexity
+            ) VALUES (?, ?, ?, ?, ?, ?, ?)
+          `).run(
+            'n8n-nodes-base.test',
+            index + 1,
+            'Test Template',
+            100,
+            'Test Node',
+            '{}',
+            complexity
+          );
+        }).not.toThrow();
+      });
+
+      const count = db.prepare('SELECT COUNT(*) as count FROM template_node_configs').get() as any;
+      expect(count.count).toBe(3);
+    });
+  });
+
+  describe('Indexes', () => {
+    it('should create idx_config_node_type_rank index', () => {
+      const indexes = db.prepare(`
+        SELECT name FROM sqlite_master
+        WHERE type='index' AND tbl_name='template_node_configs'
+      `).all() as any[];
+
+      const indexNames = indexes.map(idx => idx.name);
+      expect(indexNames).toContain('idx_config_node_type_rank');
+    });
+
+    it('should create idx_config_complexity index', () => {
+      const indexes = db.prepare(`
+        SELECT name FROM sqlite_master
+        WHERE type='index' AND tbl_name='template_node_configs'
+      `).all() as any[];
+
+      const indexNames = indexes.map(idx => idx.name);
+      expect(indexNames).toContain('idx_config_complexity');
+    });
+
+    it('should create idx_config_auth index', () => {
+      const indexes = db.prepare(`
+        SELECT name FROM sqlite_master
+        WHERE type='index' AND tbl_name='template_node_configs'
+      `).all() as any[];
+
+      const indexNames = indexes.map(idx => idx.name);
+      expect(indexNames).toContain('idx_config_auth');
+    });
+  });
+
+  describe('View: ranked_node_configs', () => {
+    it('should create ranked_node_configs view', () => {
+      const viewExists = db.prepare(`
+        SELECT name FROM sqlite_master
+        WHERE type='view' AND name='ranked_node_configs'
+      `).get();
+
+      expect(viewExists).toBeDefined();
+      expect(viewExists).toHaveProperty('name', 'ranked_node_configs');
+    });
+
+    it('should return only top 5 ranked configs per node type', () => {
+      // Insert 10 configs for same node type with different ranks
+      for (let i = 1; i <= 10; i++) {
+        db.prepare(`
+          INSERT INTO template_node_configs (
+            node_type, template_id, template_name, template_views,
+            node_name, parameters_json, rank
+          ) VALUES (?, ?, ?, ?, ?, ?, ?)
+        `).run(
+          'n8n-nodes-base.httpRequest',
+          i,
+          `Template ${i}`,
+          1000 - (i * 50), // Decreasing views
+          'HTTP Request',
+          '{}',
+          i // Rank 1-10
+        );
+      }
+
+      const rankedConfigs = db.prepare('SELECT * FROM ranked_node_configs').all() as any[];
+
+      // Should only return rank 1-5
+      expect(rankedConfigs).toHaveLength(5);
+      expect(Math.max(...rankedConfigs.map(c => c.rank))).toBe(5);
+      expect(Math.min(...rankedConfigs.map(c => c.rank))).toBe(1);
+    });
+
+    it('should order by node_type and rank', () => {
+      // Insert configs for multiple node types
+      const configs = [
+        { nodeType: 'n8n-nodes-base.webhook', rank: 2 },
+        { nodeType: 'n8n-nodes-base.webhook', rank: 1 },
+        { nodeType: 'n8n-nodes-base.httpRequest', rank: 2 },
+        { nodeType: 'n8n-nodes-base.httpRequest', rank: 1 },
+      ];
+
+      configs.forEach((config, index) => {
+        db.prepare(`
+          INSERT INTO template_node_configs (
+            node_type, template_id, template_name, template_views,
+            node_name, parameters_json, rank
+          ) VALUES (?, ?, ?, ?, ?, ?, ?)
+        `).run(
+          config.nodeType,
+          index + 1,
+          `Template ${index}`,
+          100,
+          'Node',
+          '{}',
+          config.rank
+        );
+      });
+
+      const rankedConfigs = db.prepare('SELECT * FROM ranked_node_configs ORDER BY node_type, rank').all() as any[];
+
+      // First two should be httpRequest rank 1, 2
+      expect(rankedConfigs[0].node_type).toBe('n8n-nodes-base.httpRequest');
+      expect(rankedConfigs[0].rank).toBe(1);
+      expect(rankedConfigs[1].node_type).toBe('n8n-nodes-base.httpRequest');
+      expect(rankedConfigs[1].rank).toBe(2);
+
+      // Last two should be webhook rank 1, 2
+      expect(rankedConfigs[2].node_type).toBe('n8n-nodes-base.webhook');
+      expect(rankedConfigs[2].rank).toBe(1);
+      expect(rankedConfigs[3].node_type).toBe('n8n-nodes-base.webhook');
+      expect(rankedConfigs[3].rank).toBe(2);
+    });
+  });
+
+  describe('Foreign Key Constraints', () => {
+    beforeEach(() => {
+      // Enable foreign keys
+      db.exec('PRAGMA foreign_keys = ON');
+      // Note: Templates are already created in the main beforeEach
+    });
+
+    it('should allow inserting config with valid template_id', () => {
+      expect(() => {
+        db.prepare(`
+          INSERT INTO template_node_configs (
+            node_type, template_id, template_name, template_views,
+            node_name, parameters_json
+          ) VALUES (?, ?, ?, ?, ?, ?)
+        `).run(
+          'n8n-nodes-base.test',
+          1, // Valid template_id
+          'Test Template',
+          100,
+          'Test Node',
+          '{}'
+        );
+      }).not.toThrow();
+    });
+
+    it('should cascade delete configs when template is deleted', () => {
+      // Insert config
+      db.prepare(`
+        INSERT INTO template_node_configs (
+          node_type, template_id, template_name, template_views,
+          node_name, parameters_json
+        ) VALUES (?, ?, ?, ?, ?, ?)
+      `).run(
+        'n8n-nodes-base.test',
+        1,
+        'Test Template',
+        100,
+        'Test Node',
+        '{}'
+      );
+
+      // Verify config exists
+      let configs = db.prepare('SELECT * FROM template_node_configs WHERE template_id = ?').all(1) as any[];
+      expect(configs).toHaveLength(1);
+
+      // Delete template
+      db.prepare('DELETE FROM templates WHERE id = ?').run(1);
+
+      // Verify config is deleted (CASCADE)
+      configs = db.prepare('SELECT * FROM template_node_configs WHERE template_id = ?').all(1) as any[];
+      expect(configs).toHaveLength(0);
+    });
+  });
+
+  describe('Data Operations', () => {
+    it('should insert and retrieve config with all fields', () => {
+      const testConfig = {
+        node_type: 'n8n-nodes-base.webhook',
+        template_id: 1,
+        template_name: 'Webhook Template',
+        template_views: 2000,
+        node_name: 'Webhook Trigger',
+        parameters_json: JSON.stringify({
+          httpMethod: 'POST',
+          path: 'webhook-test',
+          responseMode: 'lastNode'
+        }),
+        credentials_json: JSON.stringify({
+          webhookAuth: { id: '1', name: 'Webhook Auth' }
+        }),
+        has_credentials: 1,
+        has_expressions: 1,
+        complexity: 'medium',
+        use_cases: JSON.stringify(['webhook processing', 'automation triggers']),
+        rank: 1
+      };
+
+      db.prepare(`
+        INSERT INTO template_node_configs (
+          node_type, template_id, template_name, template_views,
+          node_name, parameters_json, credentials_json,
+          has_credentials, has_expressions, complexity, use_cases, rank
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(...Object.values(testConfig));
+
+      const retrieved = db.prepare('SELECT * FROM template_node_configs WHERE id = 1').get() as any;
+
+      expect(retrieved.node_type).toBe(testConfig.node_type);
+      expect(retrieved.template_id).toBe(testConfig.template_id);
+      expect(retrieved.template_name).toBe(testConfig.template_name);
+      expect(retrieved.template_views).toBe(testConfig.template_views);
+      expect(retrieved.node_name).toBe(testConfig.node_name);
+      expect(retrieved.parameters_json).toBe(testConfig.parameters_json);
+      expect(retrieved.credentials_json).toBe(testConfig.credentials_json);
+      expect(retrieved.has_credentials).toBe(testConfig.has_credentials);
+      expect(retrieved.has_expressions).toBe(testConfig.has_expressions);
+      expect(retrieved.complexity).toBe(testConfig.complexity);
+      expect(retrieved.use_cases).toBe(testConfig.use_cases);
+      expect(retrieved.rank).toBe(testConfig.rank);
+      expect(retrieved.created_at).toBeDefined();
+    });
+
+    it('should handle nullable fields correctly', () => {
+      db.prepare(`
+        INSERT INTO template_node_configs (
+          node_type, template_id, template_name, template_views,
+          node_name, parameters_json
+        ) VALUES (?, ?, ?, ?, ?, ?)
+      `).run(
+        'n8n-nodes-base.test',
+        1,
+        'Test',
+        100,
+        'Node',
+        '{}'
+      );
+
+      const retrieved = db.prepare('SELECT * FROM template_node_configs WHERE id = 1').get() as any;
+
+      expect(retrieved.credentials_json).toBeNull();
+      expect(retrieved.has_credentials).toBe(0); // Default value
+      expect(retrieved.has_expressions).toBe(0); // Default value
+      expect(retrieved.rank).toBe(0); // Default value
+    });
+
+    it('should update rank values', () => {
+      // Insert multiple configs
+      for (let i = 1; i <= 3; i++) {
+        db.prepare(`
+          INSERT INTO template_node_configs (
+            node_type, template_id, template_name, template_views,
+            node_name, parameters_json, rank
+          ) VALUES (?, ?, ?, ?, ?, ?, ?)
+        `).run(
+          'n8n-nodes-base.test',
+          i,
+          'Template',
+          100,
+          'Node',
+          '{}',
+          0 // Initial rank
+        );
+      }
+
+      // Update ranks
+      db.exec(`
+        UPDATE template_node_configs
+        SET rank = (
+          SELECT COUNT(*) + 1
+          FROM template_node_configs AS t2
+          WHERE t2.node_type = template_node_configs.node_type
+            AND t2.template_views > template_node_configs.template_views
+        )
+      `);
+
+      const configs = db.prepare('SELECT * FROM template_node_configs ORDER BY rank').all() as any[];
+
+      // All should have same rank (same views)
+      expect(configs.every(c => c.rank === 1)).toBe(true);
+    });
+
+    it('should delete configs with rank > 10', () => {
+      // Insert 15 configs with different ranks
+      for (let i = 1; i <= 15; i++) {
+        db.prepare(`
+          INSERT INTO template_node_configs (
+            node_type, template_id, template_name, template_views,
+            node_name, parameters_json, rank
+          ) VALUES (?, ?, ?, ?, ?, ?, ?)
+        `).run(
+          'n8n-nodes-base.test',
+          i,
+          'Template',
+          100,
+          'Node',
+          '{}',
+          i // Rank 1-15
+        );
+      }
+
+      // Delete configs with rank > 10
+      db.exec(`
+        DELETE FROM template_node_configs
+        WHERE id NOT IN (
+          SELECT id FROM template_node_configs
+          WHERE rank <= 10
+          ORDER BY node_type, rank
+        )
+      `);
+
+      const remaining = db.prepare('SELECT * FROM template_node_configs').all() as any[];
+
+      expect(remaining).toHaveLength(10);
+      expect(Math.max(...remaining.map(c => c.rank))).toBe(10);
+    });
+  });
+
+  describe('Query Performance', () => {
+    beforeEach(() => {
+      // Insert 1000 configs for performance testing
+      const stmt = db.prepare(`
+        INSERT INTO template_node_configs (
+          node_type, template_id, template_name, template_views,
+          node_name, parameters_json, rank
+        ) VALUES (?, ?, ?, ?, ?, ?, ?)
+      `);
+
+      const nodeTypes = [
+        'n8n-nodes-base.httpRequest',
+        'n8n-nodes-base.webhook',
+        'n8n-nodes-base.slack',
+        'n8n-nodes-base.googleSheets',
+        'n8n-nodes-base.code'
+      ];
+
+      for (let i = 1; i <= 1000; i++) {
+        const nodeType = nodeTypes[i % nodeTypes.length];
+        stmt.run(
+          nodeType,
+          i,
+          `Template ${i}`,
+          Math.floor(Math.random() * 10000),
+          'Node',
+          '{}',
+          (i % 10) + 1 // Rank 1-10
+        );
+      }
+    });
+
+    it('should query by node_type and rank efficiently', () => {
+      const start = Date.now();
+      const results = db.prepare(`
+        SELECT * FROM template_node_configs
+        WHERE node_type = ?
+        ORDER BY rank
+        LIMIT 3
+      `).all('n8n-nodes-base.httpRequest') as any[];
+      const duration = Date.now() - start;
+
+      expect(results.length).toBeGreaterThan(0);
+      expect(duration).toBeLessThan(10); // Should be very fast with index
+    });
+
+    it('should filter by complexity efficiently', () => {
+      // First set some complexity values
+      db.exec(`UPDATE template_node_configs SET complexity = 'simple' WHERE id % 3 = 0`);
+      db.exec(`UPDATE template_node_configs SET complexity = 'medium' WHERE id % 3 = 1`);
+      db.exec(`UPDATE template_node_configs SET complexity = 'complex' WHERE id % 3 = 2`);
+
+      const start = Date.now();
+      const results = db.prepare(`
+        SELECT * FROM template_node_configs
+        WHERE node_type = ? AND complexity = ?
+        ORDER BY rank
+        LIMIT 5
+      `).all('n8n-nodes-base.webhook', 'simple') as any[];
+      const duration = Date.now() - start;
+
+      expect(duration).toBeLessThan(10); // Should be fast with index
+    });
+  });
+
+  describe('Migration Idempotency', () => {
+    it('should be safe to run migration multiple times', () => {
+      const migrationPath = path.join(__dirname, '../../../src/database/migrations/add-template-node-configs.sql');
+      const migration = fs.readFileSync(migrationPath, 'utf-8');
+
+      // Run migration again
+      expect(() => {
+        db.exec(migration);
+      }).not.toThrow();
+
+      // Table should still exist
+      const tableExists = db.prepare(`
+        SELECT name FROM sqlite_master
+        WHERE type='table' AND name='template_node_configs'
+      `).get();
+
+      expect(tableExists).toBeDefined();
+    });
+  });
+});

tests/integration/database/template-repository.test.ts

@@ -643,6 +643,207 @@ describe('TemplateRepository Integration Tests', () => {
       });
     });
   });
+
+  describe('searchTemplatesByMetadata - Two-Phase Optimization', () => {
+  it('should use two-phase query pattern for performance', () => {
+    // Setup: Create templates with metadata and different views for deterministic ordering
+    const templates = [
+      { id: 1, complexity: 'simple', category: 'automation', views: 200 },
+      { id: 2, complexity: 'medium', category: 'integration', views: 300 },
+      { id: 3, complexity: 'simple', category: 'automation', views: 100 },
+      { id: 4, complexity: 'complex', category: 'data-processing', views: 400 }
+    ];
+
+    templates.forEach(({ id, complexity, category, views }) => {
+      const template = createTemplateWorkflow({ id, name: `Template ${id}`, totalViews: views });
+      const detail = createTemplateDetail({
+        id,
+        views,
+        workflow: {
+          id: id.toString(),
+          name: `Template ${id}`,
+          nodes: [],
+          connections: {},
+          settings: {}
+        }
+      });
+
+      repository.saveTemplate(template, detail);
+
+      // Update views to match our test data
+      db.prepare(`UPDATE templates SET views = ? WHERE workflow_id = ?`).run(views, id);
+
+      // Add metadata
+      const metadata = {
+        categories: [category],
+        complexity,
+        use_cases: ['test'],
+        estimated_setup_minutes: 15,
+        required_services: [],
+        key_features: ['test'],
+        target_audience: ['developers']
+      };
+
+      db.prepare(`
+        UPDATE templates
+        SET metadata_json = ?,
+            metadata_generated_at = datetime('now')
+        WHERE workflow_id = ?
+      `).run(JSON.stringify(metadata), id);
+    });
+
+    // Test: Search with filter should return matching templates
+    const results = repository.searchTemplatesByMetadata({ complexity: 'simple' }, 10, 0);
+
+    // Verify results - Ordered by views DESC (200, 100), then created_at DESC, then id ASC
+    expect(results).toHaveLength(2);
+    expect(results[0].workflow_id).toBe(1); // 200 views
+    expect(results[1].workflow_id).toBe(3); // 100 views
+  });
+
+  it('should preserve exact ordering from Phase 1', () => {
+    // Setup: Create templates with different view counts
+    // Use unique views to ensure deterministic ordering
+    const templates = [
+      { id: 1, views: 100 },
+      { id: 2, views: 500 },
+      { id: 3, views: 300 },
+      { id: 4, views: 400 },
+      { id: 5, views: 200 }
+    ];
+
+    templates.forEach(({ id, views }) => {
+      const template = createTemplateWorkflow({ id, name: `Template ${id}`, totalViews: views });
+      const detail = createTemplateDetail({
+        id,
+        views,
+        workflow: {
+          id: id.toString(),
+          name: `Template ${id}`,
+          nodes: [],
+          connections: {},
+          settings: {}
+        }
+      });
+
+      repository.saveTemplate(template, detail);
+
+      // Update views in database to match our test data
+      db.prepare(`UPDATE templates SET views = ? WHERE workflow_id = ?`).run(views, id);
+
+      // Add metadata
+      const metadata = {
+        categories: ['test'],
+        complexity: 'medium',
+        use_cases: ['test'],
+        estimated_setup_minutes: 15,
+        required_services: [],
+        key_features: ['test'],
+        target_audience: ['developers']
+      };
+
+      db.prepare(`
+        UPDATE templates
+        SET metadata_json = ?,
+            metadata_generated_at = datetime('now')
+        WHERE workflow_id = ?
+      `).run(JSON.stringify(metadata), id);
+    });
+
+    // Test: Search should return templates in correct order
+    const results = repository.searchTemplatesByMetadata({ complexity: 'medium' }, 10, 0);
+
+    // Verify ordering: 500 views, 400 views, 300 views, 200 views, 100 views
+    expect(results).toHaveLength(5);
+    expect(results[0].workflow_id).toBe(2); // 500 views
+    expect(results[1].workflow_id).toBe(4); // 400 views
+    expect(results[2].workflow_id).toBe(3); // 300 views
+    expect(results[3].workflow_id).toBe(5); // 200 views
+    expect(results[4].workflow_id).toBe(1); // 100 views
+  });
+
+  it('should handle empty results efficiently', () => {
+    // Setup: Create templates without the searched complexity
+    const template = createTemplateWorkflow({ id: 1 });
+    const detail = createTemplateDetail({
+      id: 1,
+      workflow: {
+        id: '1',
+        name: 'Template 1',
+        nodes: [],
+        connections: {},
+        settings: {}
+      }
+    });
+
+    repository.saveTemplate(template, detail);
+
+    const metadata = {
+      categories: ['test'],
+      complexity: 'simple',
+      use_cases: ['test'],
+      estimated_setup_minutes: 15,
+      required_services: [],
+      key_features: ['test'],
+      target_audience: ['developers']
+    };
+
+    db.prepare(`
+      UPDATE templates
+      SET metadata_json = ?,
+          metadata_generated_at = datetime('now')
+      WHERE workflow_id = 1
+    `).run(JSON.stringify(metadata));
+
+    // Test: Search for non-existent complexity
+    const results = repository.searchTemplatesByMetadata({ complexity: 'complex' }, 10, 0);
+
+    // Verify: Should return empty array without errors
+    expect(results).toHaveLength(0);
+  });
+
+  it('should validate IDs defensively', () => {
+    // This test ensures the defensive ID validation works
+    // Setup: Create a template
+    const template = createTemplateWorkflow({ id: 1 });
+    const detail = createTemplateDetail({
+      id: 1,
+      workflow: {
+        id: '1',
+        name: 'Template 1',
+        nodes: [],
+        connections: {},
+        settings: {}
+      }
+    });
+
+    repository.saveTemplate(template, detail);
+
+    const metadata = {
+      categories: ['test'],
+      complexity: 'simple',
+      use_cases: ['test'],
+      estimated_setup_minutes: 15,
+      required_services: [],
+      key_features: ['test'],
+      target_audience: ['developers']
+    };
+
+    db.prepare(`
+      UPDATE templates
+      SET metadata_json = ?,
+          metadata_generated_at = datetime('now')
+      WHERE workflow_id = 1
+    `).run(JSON.stringify(metadata));
+
+    // Test: Normal search should work
+    const results = repository.searchTemplatesByMetadata({ complexity: 'simple' }, 10, 0);
+
+    // Verify: Should return the template
+    expect(results).toHaveLength(1);
+    expect(results[0].workflow_id).toBe(1);
+  });
+  });
 });
 
 // Helper functions

tests/integration/mcp-protocol/session-management.test.ts

@@ -483,10 +483,11 @@ describe('MCP Session Management', { timeout: 15000 }, () => {
       await client.connect(clientTransport);
 
       // Multiple error-inducing requests
+      // Note: get_node_for_task was removed in v2.15.0
       const errorPromises = [
         client.callTool({ name: 'get_node_info', arguments: { nodeType: 'invalid1' } }).catch(e => e),
         client.callTool({ name: 'get_node_info', arguments: { nodeType: 'invalid2' } }).catch(e => e),
-        client.callTool({ name: 'get_node_for_task', arguments: { task: 'invalid_task' } }).catch(e => e)
+        client.callTool({ name: 'search_nodes', arguments: { query: '' } }).catch(e => e) // Empty query should error
       ];
 
       const errors = await Promise.all(errorPromises);

tests/integration/mcp-protocol/tool-invocation.test.ts

@@ -459,30 +459,8 @@ describe('MCP Tool Invocation', () => {
   });
 
   describe('Task Templates', () => {
-    describe('get_node_for_task', () => {
-      it('should return pre-configured node for task', async () => {
-        const response = await client.callTool({ name: 'get_node_for_task', arguments: {
-          task: 'post_json_request'
-        }});
-
-        const config = JSON.parse(((response as any).content[0]).text);
-        expect(config).toHaveProperty('task');
-        expect(config).toHaveProperty('nodeType');
-        expect(config).toHaveProperty('configuration');
-        expect(config.configuration.method).toBe('POST');
-      });
-
-      it('should handle unknown tasks', async () => {
-        try {
-          await client.callTool({ name: 'get_node_for_task', arguments: {
-            task: 'unknown_task'
-          }});
-          expect.fail('Should have thrown an error');
-        } catch (error: any) {
-          expect(error.message).toContain('Unknown task');
-        }
-      });
-    });
+    // get_node_for_task was removed in v2.15.0
+    // Use search_nodes({ includeExamples: true }) instead for real-world examples
 
     describe('list_tasks', () => {
       it('should list all available tasks', async () => {

tests/integration/mcp/template-examples-e2e.test.ts

@@ -0,0 +1,452 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { createDatabaseAdapter, DatabaseAdapter } from '../../../src/database/database-adapter';
+import fs from 'fs';
+import path from 'path';
+import { sampleConfigs, compressWorkflow, sampleWorkflows } from '../../fixtures/template-configs';
+
+/**
+ * End-to-end integration tests for template-based examples feature
+ * Tests the complete flow: database -> MCP server -> examples in response
+ */
+
+describe('Template Examples E2E Integration', () => {
+  let db: DatabaseAdapter;
+
+  beforeEach(async () => {
+    // Create in-memory database
+    db = await createDatabaseAdapter(':memory:');
+
+    // Apply schema
+    const schemaPath = path.join(__dirname, '../../../src/database/schema.sql');
+    const schema = fs.readFileSync(schemaPath, 'utf-8');
+    db.exec(schema);
+
+    // Apply migration
+    const migrationPath = path.join(__dirname, '../../../src/database/migrations/add-template-node-configs.sql');
+    const migration = fs.readFileSync(migrationPath, 'utf-8');
+    db.exec(migration);
+
+    // Seed test data
+    seedTemplateConfigs();
+  });
+
+  afterEach(() => {
+    if ('close' in db && typeof db.close === 'function') {
+      db.close();
+    }
+  });
+
+  function seedTemplateConfigs() {
+    // Insert sample templates first to satisfy foreign key constraints
+    // The sampleConfigs use template_id 1-4, edge cases use 998-999
+    const templateIds = [1, 2, 3, 4, 998, 999];
+    for (const id of templateIds) {
+      db.prepare(`
+        INSERT INTO templates (
+          id, workflow_id, name, description, views,
+          nodes_used, created_at, updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, datetime('now'), datetime('now'))
+      `).run(
+        id,
+        id,
+        `Test Template ${id}`,
+        'Test Description',
+        1000,
+        JSON.stringify(['n8n-nodes-base.webhook', 'n8n-nodes-base.httpRequest'])
+      );
+    }
+
+    // Insert webhook configs
+    db.prepare(`
+      INSERT INTO template_node_configs (
+        node_type, template_id, template_name, template_views,
+        node_name, parameters_json, credentials_json,
+        has_credentials, has_expressions, complexity, use_cases, rank
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      ...Object.values(sampleConfigs.simpleWebhook)
+    );
+
+    db.prepare(`
+      INSERT INTO template_node_configs (
+        node_type, template_id, template_name, template_views,
+        node_name, parameters_json, credentials_json,
+        has_credentials, has_expressions, complexity, use_cases, rank
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      ...Object.values(sampleConfigs.webhookWithAuth)
+    );
+
+    // Insert HTTP request configs
+    db.prepare(`
+      INSERT INTO template_node_configs (
+        node_type, template_id, template_name, template_views,
+        node_name, parameters_json, credentials_json,
+        has_credentials, has_expressions, complexity, use_cases, rank
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      ...Object.values(sampleConfigs.httpRequestBasic)
+    );
+
+    db.prepare(`
+      INSERT INTO template_node_configs (
+        node_type, template_id, template_name, template_views,
+        node_name, parameters_json, credentials_json,
+        has_credentials, has_expressions, complexity, use_cases, rank
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      ...Object.values(sampleConfigs.httpRequestWithExpressions)
+    );
+  }
+
+  describe('Querying Examples Directly', () => {
+    it('should fetch top 2 examples for webhook node', () => {
+      const examples = db.prepare(`
+        SELECT
+          parameters_json,
+          template_name,
+          template_views
+        FROM template_node_configs
+        WHERE node_type = ?
+        ORDER BY rank
+        LIMIT 2
+      `).all('n8n-nodes-base.webhook') as any[];
+
+      expect(examples).toHaveLength(2);
+      expect(examples[0].template_name).toBe('Simple Webhook Trigger');
+      expect(examples[1].template_name).toBe('Authenticated Webhook');
+    });
+
+    it('should fetch top 3 examples with metadata for HTTP request node', () => {
+      const examples = db.prepare(`
+        SELECT
+          parameters_json,
+          template_name,
+          template_views,
+          complexity,
+          use_cases,
+          has_credentials,
+          has_expressions
+        FROM template_node_configs
+        WHERE node_type = ?
+        ORDER BY rank
+        LIMIT 3
+      `).all('n8n-nodes-base.httpRequest') as any[];
+
+      expect(examples).toHaveLength(2); // Only 2 inserted
+      expect(examples[0].template_name).toBe('Basic HTTP GET Request');
+      expect(examples[0].complexity).toBe('simple');
+      expect(examples[0].has_expressions).toBe(0);
+
+      expect(examples[1].template_name).toBe('Dynamic HTTP Request');
+      expect(examples[1].complexity).toBe('complex');
+      expect(examples[1].has_expressions).toBe(1);
+    });
+  });
+
+  describe('Example Data Structure Validation', () => {
+    it('should have valid JSON in parameters_json', () => {
+      const examples = db.prepare(`
+        SELECT parameters_json
+        FROM template_node_configs
+        WHERE node_type = ?
+        LIMIT 1
+      `).all('n8n-nodes-base.webhook') as any[];
+
+      expect(() => {
+        const params = JSON.parse(examples[0].parameters_json);
+        expect(params).toHaveProperty('httpMethod');
+        expect(params).toHaveProperty('path');
+      }).not.toThrow();
+    });
+
+    it('should have valid JSON in use_cases', () => {
+      const examples = db.prepare(`
+        SELECT use_cases
+        FROM template_node_configs
+        WHERE node_type = ?
+        LIMIT 1
+      `).all('n8n-nodes-base.webhook') as any[];
+
+      expect(() => {
+        const useCases = JSON.parse(examples[0].use_cases);
+        expect(Array.isArray(useCases)).toBe(true);
+      }).not.toThrow();
+    });
+
+    it('should have credentials_json when has_credentials is 1', () => {
+      const examples = db.prepare(`
+        SELECT credentials_json, has_credentials
+        FROM template_node_configs
+        WHERE has_credentials = 1
+        LIMIT 1
+      `).all() as any[];
+
+      if (examples.length > 0) {
+        expect(examples[0].credentials_json).not.toBeNull();
+        expect(() => {
+          JSON.parse(examples[0].credentials_json);
+        }).not.toThrow();
+      }
+    });
+  });
+
+  describe('Ranked View Functionality', () => {
+    it('should return only top 5 ranked configs per node type from view', () => {
+      // Insert templates first to satisfy foreign key constraints
+      // Note: seedTemplateConfigs already created templates 1-4, so start from 5
+      for (let i = 5; i <= 14; i++) {
+        db.prepare(`
+          INSERT INTO templates (
+            id, workflow_id, name, description, views,
+            nodes_used, created_at, updated_at
+          ) VALUES (?, ?, ?, ?, ?, ?, datetime('now'), datetime('now'))
+        `).run(i, i, `Template ${i}`, 'Test', 1000 - (i * 50), '[]');
+      }
+
+      // Insert 10 configs for same node type
+      for (let i = 5; i <= 14; i++) {
+        db.prepare(`
+          INSERT INTO template_node_configs (
+            node_type, template_id, template_name, template_views,
+            node_name, parameters_json, rank
+          ) VALUES (?, ?, ?, ?, ?, ?, ?)
+        `).run(
+          'n8n-nodes-base.webhook',
+          i,
+          `Template ${i}`,
+          1000 - (i * 50),
+          'Webhook',
+          '{}',
+          i
+        );
+      }
+
+      const rankedConfigs = db.prepare(`
+        SELECT * FROM ranked_node_configs
+        WHERE node_type = ?
+      `).all('n8n-nodes-base.webhook') as any[];
+
+      expect(rankedConfigs.length).toBeLessThanOrEqual(5);
+    });
+  });
+
+  describe('Performance with Real-World Data Volume', () => {
+    beforeEach(() => {
+      // Insert templates first to satisfy foreign key constraints
+      for (let i = 1; i <= 100; i++) {
+        db.prepare(`
+          INSERT INTO templates (
+            id, workflow_id, name, description, views,
+            nodes_used, created_at, updated_at
+          ) VALUES (?, ?, ?, ?, ?, ?, datetime('now'), datetime('now'))
+        `).run(i + 100, i + 100, `Template ${i}`, 'Test', Math.floor(Math.random() * 10000), '[]');
+      }
+
+      // Insert 100 configs across 10 different node types
+      const nodeTypes = [
+        'n8n-nodes-base.slack',
+        'n8n-nodes-base.googleSheets',
+        'n8n-nodes-base.code',
+        'n8n-nodes-base.if',
+        'n8n-nodes-base.switch',
+        'n8n-nodes-base.set',
+        'n8n-nodes-base.merge',
+        'n8n-nodes-base.splitInBatches',
+        'n8n-nodes-base.postgres',
+        'n8n-nodes-base.gmail'
+      ];
+
+      for (let i = 1; i <= 100; i++) {
+        const nodeType = nodeTypes[i % nodeTypes.length];
+        db.prepare(`
+          INSERT INTO template_node_configs (
+            node_type, template_id, template_name, template_views,
+            node_name, parameters_json, rank
+          ) VALUES (?, ?, ?, ?, ?, ?, ?)
+        `).run(
+          nodeType,
+          i + 100, // Offset template_id
+          `Template ${i}`,
+          Math.floor(Math.random() * 10000),
+          'Node',
+          '{}',
+          (i % 10) + 1
+        );
+      }
+    });
+
+    it('should query specific node type examples quickly', () => {
+      const start = Date.now();
+      const examples = db.prepare(`
+        SELECT * FROM template_node_configs
+        WHERE node_type = ?
+        ORDER BY rank
+        LIMIT 3
+      `).all('n8n-nodes-base.slack') as any[];
+      const duration = Date.now() - start;
+
+      expect(examples.length).toBeGreaterThan(0);
+      expect(duration).toBeLessThan(5); // Should be very fast with index
+    });
+
+    it('should filter by complexity efficiently', () => {
+      // Set complexity on configs
+      db.exec(`UPDATE template_node_configs SET complexity = 'simple' WHERE id % 3 = 0`);
+      db.exec(`UPDATE template_node_configs SET complexity = 'medium' WHERE id % 3 = 1`);
+
+      const start = Date.now();
+      const examples = db.prepare(`
+        SELECT * FROM template_node_configs
+        WHERE node_type = ? AND complexity = ?
+        ORDER BY rank
+        LIMIT 3
+      `).all('n8n-nodes-base.code', 'simple') as any[];
+      const duration = Date.now() - start;
+
+      expect(duration).toBeLessThan(5);
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('should handle node types with no configs', () => {
+      const examples = db.prepare(`
+        SELECT * FROM template_node_configs
+        WHERE node_type = ?
+        LIMIT 2
+      `).all('n8n-nodes-base.nonexistent') as any[];
+
+      expect(examples).toHaveLength(0);
+    });
+
+    it('should handle very long parameters_json', () => {
+      const longParams = JSON.stringify({
+        options: {
+          queryParameters: Array.from({ length: 100 }, (_, i) => ({
+            name: `param${i}`,
+            value: `value${i}`.repeat(10)
+          }))
+        }
+      });
+
+      db.prepare(`
+        INSERT INTO template_node_configs (
+          node_type, template_id, template_name, template_views,
+          node_name, parameters_json, rank
+        ) VALUES (?, ?, ?, ?, ?, ?, ?)
+      `).run(
+        'n8n-nodes-base.test',
+        999,
+        'Long Params Template',
+        100,
+        'Test',
+        longParams,
+        1
+      );
+
+      const example = db.prepare(`
+        SELECT parameters_json FROM template_node_configs WHERE template_id = ?
+      `).get(999) as any;
+
+      expect(() => {
+        const parsed = JSON.parse(example.parameters_json);
+        expect(parsed.options.queryParameters).toHaveLength(100);
+      }).not.toThrow();
+    });
+
+    it('should handle special characters in parameters', () => {
+      const specialParams = JSON.stringify({
+        message: "Test with 'quotes' and \"double quotes\"",
+        unicode: "特殊文字 🎉 émojis",
+        symbols: "!@#$%^&*()_+-={}[]|\\:;<>?,./"
+      });
+
+      db.prepare(`
+        INSERT INTO template_node_configs (
+          node_type, template_id, template_name, template_views,
+          node_name, parameters_json, rank
+        ) VALUES (?, ?, ?, ?, ?, ?, ?)
+      `).run(
+        'n8n-nodes-base.test',
+        998,
+        'Special Chars Template',
+        100,
+        'Test',
+        specialParams,
+        1
+      );
+
+      const example = db.prepare(`
+        SELECT parameters_json FROM template_node_configs WHERE template_id = ?
+      `).get(998) as any;
+
+      expect(() => {
+        const parsed = JSON.parse(example.parameters_json);
+        expect(parsed.message).toContain("'quotes'");
+        expect(parsed.unicode).toContain("🎉");
+      }).not.toThrow();
+    });
+  });
+
+  describe('Data Integrity', () => {
+    it('should maintain referential integrity with templates table', () => {
+      // Try to insert config with non-existent template_id (with FK enabled)
+      db.exec('PRAGMA foreign_keys = ON');
+
+      expect(() => {
+        db.prepare(`
+          INSERT INTO template_node_configs (
+            node_type, template_id, template_name, template_views,
+            node_name, parameters_json, rank
+          ) VALUES (?, ?, ?, ?, ?, ?, ?)
+        `).run(
+          'n8n-nodes-base.test',
+          999999, // Non-existent template_id
+          'Test',
+          100,
+          'Node',
+          '{}',
+          1
+        );
+      }).toThrow(); // Should fail due to FK constraint
+    });
+
+    it('should cascade delete configs when template is deleted', () => {
+      db.exec('PRAGMA foreign_keys = ON');
+
+      // Insert a new template (use id 1000 to avoid conflicts with seedTemplateConfigs)
+      db.prepare(`
+        INSERT INTO templates (
+          id, workflow_id, name, description, views,
+          nodes_used, created_at, updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, datetime('now'), datetime('now'))
+      `).run(1000, 1000, 'Test Template 1000', 'Desc', 100, '[]');
+
+      db.prepare(`
+        INSERT INTO template_node_configs (
+          node_type, template_id, template_name, template_views,
+          node_name, parameters_json, rank
+        ) VALUES (?, ?, ?, ?, ?, ?, ?)
+      `).run(
+        'n8n-nodes-base.test',
+        1000,
+        'Test',
+        100,
+        'Node',
+        '{}',
+        1
+      );
+
+      // Verify config exists
+      let config = db.prepare('SELECT * FROM template_node_configs WHERE template_id = ?').get(1000);
+      expect(config).toBeDefined();
+
+      // Delete template
+      db.prepare('DELETE FROM templates WHERE id = ?').run(1000);
+
+      // Verify config is deleted (CASCADE)
+      config = db.prepare('SELECT * FROM template_node_configs WHERE template_id = ?').get(1000);
+      expect(config).toBeUndefined();
+    });
+  });
+});

tests/integration/n8n-api/executions/delete-execution.test.ts

@@ -0,0 +1,148 @@
+/**
+ * Integration Tests: handleDeleteExecution
+ *
+ * Tests execution deletion against a real n8n instance.
+ * Covers successful deletion, error handling, and cleanup verification.
+ */
+
+import { describe, it, expect, beforeEach, beforeAll } from 'vitest';
+import { createMcpContext } from '../utils/mcp-context';
+import { InstanceContext } from '../../../../src/types/instance-context';
+import { handleDeleteExecution, handleTriggerWebhookWorkflow, handleGetExecution } from '../../../../src/mcp/handlers-n8n-manager';
+import { getN8nCredentials } from '../utils/credentials';
+
+describe('Integration: handleDeleteExecution', () => {
+  let mcpContext: InstanceContext;
+  let webhookUrl: string;
+
+  beforeEach(() => {
+    mcpContext = createMcpContext();
+  });
+
+  beforeAll(() => {
+    const creds = getN8nCredentials();
+    webhookUrl = creds.webhookUrls.get;
+  });
+
+  // ======================================================================
+  // Successful Deletion
+  // ======================================================================
+
+  describe('Successful Deletion', () => {
+    it('should delete an execution successfully', async () => {
+      // First, create an execution to delete
+      const triggerResponse = await handleTriggerWebhookWorkflow(
+        {
+          webhookUrl,
+          httpMethod: 'GET',
+          waitForResponse: true
+        },
+        mcpContext
+      );
+
+      // Try to extract execution ID
+      let executionId: string | undefined;
+      if (triggerResponse.success && triggerResponse.data) {
+        const responseData = triggerResponse.data as any;
+        executionId = responseData.executionId ||
+                      responseData.id ||
+                      responseData.execution?.id ||
+                      responseData.workflowData?.executionId;
+      }
+
+      if (!executionId) {
+        console.warn('Could not extract execution ID for deletion test');
+        return;
+      }
+
+      // Delete the execution
+      const response = await handleDeleteExecution(
+        { id: executionId },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      expect(response.data).toBeDefined();
+    }, 30000);
+
+    it('should verify execution is actually deleted', async () => {
+      // Create an execution
+      const triggerResponse = await handleTriggerWebhookWorkflow(
+        {
+          webhookUrl,
+          httpMethod: 'GET',
+          waitForResponse: true
+        },
+        mcpContext
+      );
+
+      let executionId: string | undefined;
+      if (triggerResponse.success && triggerResponse.data) {
+        const responseData = triggerResponse.data as any;
+        executionId = responseData.executionId ||
+                      responseData.id ||
+                      responseData.execution?.id ||
+                      responseData.workflowData?.executionId;
+      }
+
+      if (!executionId) {
+        console.warn('Could not extract execution ID for deletion verification test');
+        return;
+      }
+
+      // Delete it
+      const deleteResponse = await handleDeleteExecution(
+        { id: executionId },
+        mcpContext
+      );
+
+      expect(deleteResponse.success).toBe(true);
+
+      // Try to fetch the deleted execution
+      const getResponse = await handleGetExecution(
+        { id: executionId },
+        mcpContext
+      );
+
+      // Should fail to find the deleted execution
+      expect(getResponse.success).toBe(false);
+      expect(getResponse.error).toBeDefined();
+    }, 30000);
+  });
+
+  // ======================================================================
+  // Error Handling
+  // ======================================================================
+
+  describe('Error Handling', () => {
+    it('should handle non-existent execution ID', async () => {
+      const response = await handleDeleteExecution(
+        { id: '99999999' },
+        mcpContext
+      );
+
+      expect(response.success).toBe(false);
+      expect(response.error).toBeDefined();
+    });
+
+    it('should handle invalid execution ID format', async () => {
+      const response = await handleDeleteExecution(
+        { id: 'invalid-id-format' },
+        mcpContext
+      );
+
+      expect(response.success).toBe(false);
+      expect(response.error).toBeDefined();
+    });
+
+    it('should handle missing execution ID', async () => {
+      const response = await handleDeleteExecution(
+        {} as any,
+        mcpContext
+      );
+
+      expect(response.success).toBe(false);
+      expect(response.error).toBeDefined();
+    });
+  });
+});

tests/integration/n8n-api/executions/get-execution.test.ts

@@ -0,0 +1,428 @@
+/**
+ * Integration Tests: handleGetExecution
+ *
+ * Tests execution retrieval against a real n8n instance.
+ * Covers all retrieval modes, filtering options, and error handling.
+ */
+
+import { describe, it, expect, beforeAll } from 'vitest';
+import { createMcpContext } from '../utils/mcp-context';
+import { InstanceContext } from '../../../../src/types/instance-context';
+import { handleGetExecution, handleTriggerWebhookWorkflow } from '../../../../src/mcp/handlers-n8n-manager';
+import { getN8nCredentials } from '../utils/credentials';
+
+describe('Integration: handleGetExecution', () => {
+  let mcpContext: InstanceContext;
+  let executionId: string;
+  let webhookUrl: string;
+
+  beforeAll(async () => {
+    mcpContext = createMcpContext();
+    const creds = getN8nCredentials();
+    webhookUrl = creds.webhookUrls.get;
+
+    // Trigger a webhook to create an execution for testing
+    const triggerResponse = await handleTriggerWebhookWorkflow(
+      {
+        webhookUrl,
+        httpMethod: 'GET',
+        waitForResponse: true
+      },
+      mcpContext
+    );
+
+    // Extract execution ID from the response
+    if (triggerResponse.success && triggerResponse.data) {
+      const responseData = triggerResponse.data as any;
+      // Try to get execution ID from various possible locations
+      executionId = responseData.executionId ||
+                    responseData.id ||
+                    responseData.execution?.id ||
+                    responseData.workflowData?.executionId;
+
+      if (!executionId) {
+        // If no execution ID in response, we'll use error handling tests
+        console.warn('Could not extract execution ID from webhook response');
+      }
+    }
+  }, 30000);
+
+  // ======================================================================
+  // Preview Mode
+  // ======================================================================
+
+  describe('Preview Mode', () => {
+    it('should get execution in preview mode (structure only)', async () => {
+      if (!executionId) {
+        console.warn('Skipping test: No execution ID available');
+        return;
+      }
+
+      const response = await handleGetExecution(
+        {
+          id: executionId,
+          mode: 'preview'
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      // Preview mode should return structure and counts
+      expect(data).toBeDefined();
+      expect(data.id).toBe(executionId);
+
+      // Should have basic execution info
+      if (data.status) {
+        expect(['success', 'error', 'running', 'waiting']).toContain(data.status);
+      }
+    });
+  });
+
+  // ======================================================================
+  // Summary Mode (Default)
+  // ======================================================================
+
+  describe('Summary Mode', () => {
+    it('should get execution in summary mode (2 samples per node)', async () => {
+      if (!executionId) {
+        console.warn('Skipping test: No execution ID available');
+        return;
+      }
+
+      const response = await handleGetExecution(
+        {
+          id: executionId,
+          mode: 'summary'
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      expect(data).toBeDefined();
+      expect(data.id).toBe(executionId);
+    });
+
+    it('should default to summary mode when mode not specified', async () => {
+      if (!executionId) {
+        console.warn('Skipping test: No execution ID available');
+        return;
+      }
+
+      const response = await handleGetExecution(
+        {
+          id: executionId
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      expect(data).toBeDefined();
+      expect(data.id).toBe(executionId);
+    });
+  });
+
+  // ======================================================================
+  // Filtered Mode
+  // ======================================================================
+
+  describe('Filtered Mode', () => {
+    it('should get execution with custom items limit', async () => {
+      if (!executionId) {
+        console.warn('Skipping test: No execution ID available');
+        return;
+      }
+
+      const response = await handleGetExecution(
+        {
+          id: executionId,
+          mode: 'filtered',
+          itemsLimit: 5
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      expect(data).toBeDefined();
+      expect(data.id).toBe(executionId);
+    });
+
+    it('should get execution with itemsLimit 0 (structure only)', async () => {
+      if (!executionId) {
+        console.warn('Skipping test: No execution ID available');
+        return;
+      }
+
+      const response = await handleGetExecution(
+        {
+          id: executionId,
+          mode: 'filtered',
+          itemsLimit: 0
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      expect(data).toBeDefined();
+      expect(data.id).toBe(executionId);
+    });
+
+    it('should get execution with unlimited items (itemsLimit: -1)', async () => {
+      if (!executionId) {
+        console.warn('Skipping test: No execution ID available');
+        return;
+      }
+
+      const response = await handleGetExecution(
+        {
+          id: executionId,
+          mode: 'filtered',
+          itemsLimit: -1
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      expect(data).toBeDefined();
+      expect(data.id).toBe(executionId);
+    });
+
+    it('should get execution filtered by node names', async () => {
+      if (!executionId) {
+        console.warn('Skipping test: No execution ID available');
+        return;
+      }
+
+      const response = await handleGetExecution(
+        {
+          id: executionId,
+          mode: 'filtered',
+          nodeNames: ['Webhook']
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      expect(data).toBeDefined();
+      expect(data.id).toBe(executionId);
+    });
+  });
+
+  // ======================================================================
+  // Full Mode
+  // ======================================================================
+
+  describe('Full Mode', () => {
+    it('should get complete execution data', async () => {
+      if (!executionId) {
+        console.warn('Skipping test: No execution ID available');
+        return;
+      }
+
+      const response = await handleGetExecution(
+        {
+          id: executionId,
+          mode: 'full'
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      expect(data).toBeDefined();
+      expect(data.id).toBe(executionId);
+
+      // Full mode should include complete execution data
+      if (data.data) {
+        expect(typeof data.data).toBe('object');
+      }
+    });
+  });
+
+  // ======================================================================
+  // Input Data Inclusion
+  // ======================================================================
+
+  describe('Input Data Inclusion', () => {
+    it('should include input data when requested', async () => {
+      if (!executionId) {
+        console.warn('Skipping test: No execution ID available');
+        return;
+      }
+
+      const response = await handleGetExecution(
+        {
+          id: executionId,
+          mode: 'summary',
+          includeInputData: true
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      expect(data).toBeDefined();
+      expect(data.id).toBe(executionId);
+    });
+
+    it('should exclude input data by default', async () => {
+      if (!executionId) {
+        console.warn('Skipping test: No execution ID available');
+        return;
+      }
+
+      const response = await handleGetExecution(
+        {
+          id: executionId,
+          mode: 'summary',
+          includeInputData: false
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      expect(data).toBeDefined();
+      expect(data.id).toBe(executionId);
+    });
+  });
+
+  // ======================================================================
+  // Legacy Parameter Compatibility
+  // ======================================================================
+
+  describe('Legacy Parameter Compatibility', () => {
+    it('should support legacy includeData parameter', async () => {
+      if (!executionId) {
+        console.warn('Skipping test: No execution ID available');
+        return;
+      }
+
+      const response = await handleGetExecution(
+        {
+          id: executionId,
+          includeData: true
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      expect(data).toBeDefined();
+      expect(data.id).toBe(executionId);
+    });
+  });
+
+  // ======================================================================
+  // Error Handling
+  // ======================================================================
+
+  describe('Error Handling', () => {
+    it('should handle non-existent execution ID', async () => {
+      const response = await handleGetExecution(
+        {
+          id: '99999999'
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(false);
+      expect(response.error).toBeDefined();
+    });
+
+    it('should handle invalid execution ID format', async () => {
+      const response = await handleGetExecution(
+        {
+          id: 'invalid-id-format'
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(false);
+      expect(response.error).toBeDefined();
+    });
+
+    it('should handle missing execution ID', async () => {
+      const response = await handleGetExecution(
+        {} as any,
+        mcpContext
+      );
+
+      expect(response.success).toBe(false);
+      expect(response.error).toBeDefined();
+    });
+
+    it('should handle invalid mode parameter', async () => {
+      if (!executionId) {
+        console.warn('Skipping test: No execution ID available');
+        return;
+      }
+
+      const response = await handleGetExecution(
+        {
+          id: executionId,
+          mode: 'invalid-mode' as any
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(false);
+      expect(response.error).toBeDefined();
+    });
+  });
+
+  // ======================================================================
+  // Response Format Verification
+  // ======================================================================
+
+  describe('Response Format', () => {
+    it('should return complete execution response structure', async () => {
+      if (!executionId) {
+        console.warn('Skipping test: No execution ID available');
+        return;
+      }
+
+      const response = await handleGetExecution(
+        {
+          id: executionId,
+          mode: 'summary'
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      expect(response.data).toBeDefined();
+
+      const data = response.data as any;
+      expect(data.id).toBeDefined();
+
+      // Should have execution metadata
+      if (data.status) {
+        expect(typeof data.status).toBe('string');
+      }
+      if (data.mode) {
+        expect(typeof data.mode).toBe('string');
+      }
+      if (data.startedAt) {
+        expect(typeof data.startedAt).toBe('string');
+      }
+    });
+  });
+});

tests/integration/n8n-api/executions/list-executions.test.ts

@@ -0,0 +1,263 @@
+/**
+ * Integration Tests: handleListExecutions
+ *
+ * Tests execution listing against a real n8n instance.
+ * Covers filtering, pagination, and various list parameters.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { createMcpContext } from '../utils/mcp-context';
+import { InstanceContext } from '../../../../src/types/instance-context';
+import { handleListExecutions } from '../../../../src/mcp/handlers-n8n-manager';
+
+describe('Integration: handleListExecutions', () => {
+  let mcpContext: InstanceContext;
+
+  beforeEach(() => {
+    mcpContext = createMcpContext();
+  });
+
+  // ======================================================================
+  // No Filters
+  // ======================================================================
+
+  describe('No Filters', () => {
+    it('should list all executions without filters', async () => {
+      const response = await handleListExecutions({}, mcpContext);
+
+      expect(response.success).toBe(true);
+      expect(response.data).toBeDefined();
+
+      const data = response.data as any;
+      expect(Array.isArray(data.executions)).toBe(true);
+      expect(data).toHaveProperty('returned');
+    });
+  });
+
+  // ======================================================================
+  // Filter by Status
+  // ======================================================================
+
+  describe('Filter by Status', () => {
+    it('should filter executions by success status', async () => {
+      const response = await handleListExecutions(
+        { status: 'success' },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      expect(Array.isArray(data.executions)).toBe(true);
+      // All returned executions should have success status
+      if (data.executions.length > 0) {
+        data.executions.forEach((exec: any) => {
+          expect(exec.status).toBe('success');
+        });
+      }
+    });
+
+    it('should filter executions by error status', async () => {
+      const response = await handleListExecutions(
+        { status: 'error' },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      expect(Array.isArray(data.executions)).toBe(true);
+      // All returned executions should have error status
+      if (data.executions.length > 0) {
+        data.executions.forEach((exec: any) => {
+          expect(exec.status).toBe('error');
+        });
+      }
+    });
+
+    it('should filter executions by waiting status', async () => {
+      const response = await handleListExecutions(
+        { status: 'waiting' },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      expect(Array.isArray(data.executions)).toBe(true);
+    });
+  });
+
+  // ======================================================================
+  // Pagination
+  // ======================================================================
+
+  describe('Pagination', () => {
+    it('should return first page with limit', async () => {
+      const response = await handleListExecutions(
+        { limit: 10 },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      expect(Array.isArray(data.executions)).toBe(true);
+      expect(data.executions.length).toBeLessThanOrEqual(10);
+    });
+
+    it('should handle pagination with cursor', async () => {
+      // Get first page
+      const firstPage = await handleListExecutions(
+        { limit: 5 },
+        mcpContext
+      );
+
+      expect(firstPage.success).toBe(true);
+      const firstData = firstPage.data as any;
+
+      // If there's a next cursor, get second page
+      if (firstData.nextCursor) {
+        const secondPage = await handleListExecutions(
+          { limit: 5, cursor: firstData.nextCursor },
+          mcpContext
+        );
+
+        expect(secondPage.success).toBe(true);
+        const secondData = secondPage.data as any;
+
+        // Second page should have different executions
+        const firstIds = new Set(firstData.executions.map((e: any) => e.id));
+        const secondIds = secondData.executions.map((e: any) => e.id);
+
+        secondIds.forEach((id: string) => {
+          expect(firstIds.has(id)).toBe(false);
+        });
+      }
+    });
+
+    it('should respect limit=1', async () => {
+      const response = await handleListExecutions(
+        { limit: 1 },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      expect(data.executions.length).toBeLessThanOrEqual(1);
+    });
+
+    it('should respect limit=50', async () => {
+      const response = await handleListExecutions(
+        { limit: 50 },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      expect(data.executions.length).toBeLessThanOrEqual(50);
+    });
+
+    it('should respect limit=100 (max)', async () => {
+      const response = await handleListExecutions(
+        { limit: 100 },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      expect(data.executions.length).toBeLessThanOrEqual(100);
+    });
+  });
+
+  // ======================================================================
+  // Include Execution Data
+  // ======================================================================
+
+  describe('Include Execution Data', () => {
+    it('should exclude execution data by default', async () => {
+      const response = await handleListExecutions(
+        { limit: 5 },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      expect(Array.isArray(data.executions)).toBe(true);
+      // By default, should not include full execution data
+    });
+
+    it('should include execution data when requested', async () => {
+      const response = await handleListExecutions(
+        { limit: 5, includeData: true },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      expect(Array.isArray(data.executions)).toBe(true);
+    });
+  });
+
+  // ======================================================================
+  // Empty Results
+  // ======================================================================
+
+  describe('Empty Results', () => {
+    it('should return empty array when no executions match filters', async () => {
+      // Use a very restrictive workflowId that likely doesn't exist
+      const response = await handleListExecutions(
+        { workflowId: '99999999' },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      expect(Array.isArray(data.executions)).toBe(true);
+      // May or may not be empty depending on actual data
+    });
+  });
+
+  // ======================================================================
+  // Response Format Verification
+  // ======================================================================
+
+  describe('Response Format', () => {
+    it('should return complete list response structure', async () => {
+      const response = await handleListExecutions(
+        { limit: 10 },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      // Verify required fields
+      expect(data).toHaveProperty('executions');
+      expect(Array.isArray(data.executions)).toBe(true);
+      expect(data).toHaveProperty('returned');
+      expect(data).toHaveProperty('hasMore');
+
+      // Verify pagination fields when present
+      if (data.nextCursor) {
+        expect(typeof data.nextCursor).toBe('string');
+      }
+
+      // Verify execution structure if any executions returned
+      if (data.executions.length > 0) {
+        const execution = data.executions[0];
+        expect(execution).toHaveProperty('id');
+
+        if (execution.status) {
+          expect(['success', 'error', 'running', 'waiting']).toContain(execution.status);
+        }
+      }
+    });
+  });
+});

tests/integration/n8n-api/executions/trigger-webhook.test.ts

@@ -0,0 +1,375 @@
+/**
+ * Integration Tests: handleTriggerWebhookWorkflow
+ *
+ * Tests webhook triggering against a real n8n instance.
+ * Covers all HTTP methods, request data, headers, and error handling.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { createMcpContext } from '../utils/mcp-context';
+import { InstanceContext } from '../../../../src/types/instance-context';
+import { handleTriggerWebhookWorkflow } from '../../../../src/mcp/handlers-n8n-manager';
+import { getN8nCredentials } from '../utils/credentials';
+
+describe('Integration: handleTriggerWebhookWorkflow', () => {
+  let mcpContext: InstanceContext;
+  let webhookUrls: {
+    get: string;
+    post: string;
+    put: string;
+    delete: string;
+  };
+
+  beforeEach(() => {
+    mcpContext = createMcpContext();
+    const creds = getN8nCredentials();
+    webhookUrls = creds.webhookUrls;
+  });
+
+  // ======================================================================
+  // GET Method Tests
+  // ======================================================================
+
+  describe('GET Method', () => {
+    it('should trigger GET webhook without data', async () => {
+      const response = await handleTriggerWebhookWorkflow(
+        {
+          webhookUrl: webhookUrls.get,
+          httpMethod: 'GET'
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      expect(response.data).toBeDefined();
+      expect(response.message).toContain('Webhook triggered successfully');
+    });
+
+    it('should trigger GET webhook with query parameters', async () => {
+      // GET method uses query parameters in URL
+      const urlWithParams = `${webhookUrls.get}?testParam=value&number=42`;
+
+      const response = await handleTriggerWebhookWorkflow(
+        {
+          webhookUrl: urlWithParams,
+          httpMethod: 'GET'
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      expect(response.data).toBeDefined();
+    });
+
+    it('should trigger GET webhook with custom headers', async () => {
+      const response = await handleTriggerWebhookWorkflow(
+        {
+          webhookUrl: webhookUrls.get,
+          httpMethod: 'GET',
+          headers: {
+            'X-Custom-Header': 'test-value',
+            'X-Request-Id': '12345'
+          }
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      expect(response.data).toBeDefined();
+    });
+
+    it('should trigger GET webhook and wait for response', async () => {
+      const response = await handleTriggerWebhookWorkflow(
+        {
+          webhookUrl: webhookUrls.get,
+          httpMethod: 'GET',
+          waitForResponse: true
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      expect(response.data).toBeDefined();
+      // Response should contain workflow execution data
+    });
+  });
+
+  // ======================================================================
+  // POST Method Tests
+  // ======================================================================
+
+  describe('POST Method', () => {
+    it('should trigger POST webhook with JSON data', async () => {
+      const response = await handleTriggerWebhookWorkflow(
+        {
+          webhookUrl: webhookUrls.post,
+          httpMethod: 'POST',
+          data: {
+            message: 'Test webhook trigger',
+            timestamp: Date.now(),
+            nested: {
+              value: 'nested data'
+            }
+          }
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      expect(response.data).toBeDefined();
+    });
+
+    it('should trigger POST webhook without data', async () => {
+      const response = await handleTriggerWebhookWorkflow(
+        {
+          webhookUrl: webhookUrls.post,
+          httpMethod: 'POST'
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      expect(response.data).toBeDefined();
+    });
+
+    it('should trigger POST webhook with custom headers', async () => {
+      const response = await handleTriggerWebhookWorkflow(
+        {
+          webhookUrl: webhookUrls.post,
+          httpMethod: 'POST',
+          data: { test: 'data' },
+          headers: {
+            'Content-Type': 'application/json',
+            'X-Api-Key': 'test-key'
+          }
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      expect(response.data).toBeDefined();
+    });
+
+    it('should trigger POST webhook without waiting for response', async () => {
+      const response = await handleTriggerWebhookWorkflow(
+        {
+          webhookUrl: webhookUrls.post,
+          httpMethod: 'POST',
+          data: { async: true },
+          waitForResponse: false
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      // With waitForResponse: false, may return immediately
+    });
+  });
+
+  // ======================================================================
+  // PUT Method Tests
+  // ======================================================================
+
+  describe('PUT Method', () => {
+    it('should trigger PUT webhook with update data', async () => {
+      const response = await handleTriggerWebhookWorkflow(
+        {
+          webhookUrl: webhookUrls.put,
+          httpMethod: 'PUT',
+          data: {
+            id: '123',
+            updatedField: 'new value',
+            timestamp: Date.now()
+          }
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      expect(response.data).toBeDefined();
+    });
+
+    it('should trigger PUT webhook with custom headers', async () => {
+      const response = await handleTriggerWebhookWorkflow(
+        {
+          webhookUrl: webhookUrls.put,
+          httpMethod: 'PUT',
+          data: { update: true },
+          headers: {
+            'X-Update-Operation': 'modify',
+            'If-Match': 'etag-value'
+          }
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      expect(response.data).toBeDefined();
+    });
+
+    it('should trigger PUT webhook without data', async () => {
+      const response = await handleTriggerWebhookWorkflow(
+        {
+          webhookUrl: webhookUrls.put,
+          httpMethod: 'PUT'
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      expect(response.data).toBeDefined();
+    });
+  });
+
+  // ======================================================================
+  // DELETE Method Tests
+  // ======================================================================
+
+  describe('DELETE Method', () => {
+    it('should trigger DELETE webhook with query parameters', async () => {
+      const urlWithParams = `${webhookUrls.delete}?id=123&reason=test`;
+
+      const response = await handleTriggerWebhookWorkflow(
+        {
+          webhookUrl: urlWithParams,
+          httpMethod: 'DELETE'
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      expect(response.data).toBeDefined();
+    });
+
+    it('should trigger DELETE webhook with custom headers', async () => {
+      const response = await handleTriggerWebhookWorkflow(
+        {
+          webhookUrl: webhookUrls.delete,
+          httpMethod: 'DELETE',
+          headers: {
+            'X-Delete-Reason': 'cleanup',
+            'Authorization': 'Bearer token'
+          }
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      expect(response.data).toBeDefined();
+    });
+
+    it('should trigger DELETE webhook without parameters', async () => {
+      const response = await handleTriggerWebhookWorkflow(
+        {
+          webhookUrl: webhookUrls.delete,
+          httpMethod: 'DELETE'
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      expect(response.data).toBeDefined();
+    });
+  });
+
+  // ======================================================================
+  // Error Handling
+  // ======================================================================
+
+  describe('Error Handling', () => {
+    it('should handle invalid webhook URL', async () => {
+      const response = await handleTriggerWebhookWorkflow(
+        {
+          webhookUrl: 'https://invalid-url.example.com/webhook/nonexistent',
+          httpMethod: 'GET'
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(false);
+      expect(response.error).toBeDefined();
+    });
+
+    it('should handle malformed webhook URL', async () => {
+      const response = await handleTriggerWebhookWorkflow(
+        {
+          webhookUrl: 'not-a-valid-url',
+          httpMethod: 'GET'
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(false);
+      expect(response.error).toBeDefined();
+    });
+
+    it('should handle missing webhook URL', async () => {
+      const response = await handleTriggerWebhookWorkflow(
+        {
+          httpMethod: 'GET'
+        } as any,
+        mcpContext
+      );
+
+      expect(response.success).toBe(false);
+      expect(response.error).toBeDefined();
+    });
+
+    it('should handle invalid HTTP method', async () => {
+      const response = await handleTriggerWebhookWorkflow(
+        {
+          webhookUrl: webhookUrls.get,
+          httpMethod: 'INVALID' as any
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(false);
+      expect(response.error).toBeDefined();
+    });
+  });
+
+  // ======================================================================
+  // Default Method (POST)
+  // ======================================================================
+
+  describe('Default Method Behavior', () => {
+    it('should default to POST method when not specified', async () => {
+      const response = await handleTriggerWebhookWorkflow(
+        {
+          webhookUrl: webhookUrls.post,
+          data: { defaultMethod: true }
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      expect(response.data).toBeDefined();
+    });
+  });
+
+  // ======================================================================
+  // Response Format Verification
+  // ======================================================================
+
+  describe('Response Format', () => {
+    it('should return complete webhook response structure', async () => {
+      const response = await handleTriggerWebhookWorkflow(
+        {
+          webhookUrl: webhookUrls.get,
+          httpMethod: 'GET',
+          waitForResponse: true
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      expect(response.data).toBeDefined();
+      expect(response.message).toBeDefined();
+      expect(response.message).toContain('Webhook triggered successfully');
+
+      // Response data should be defined (either workflow output or execution info)
+      expect(typeof response.data).not.toBe('undefined');
+    });
+  });
+});

tests/integration/n8n-api/scripts/cleanup-orphans.ts

@@ -0,0 +1,43 @@
+#!/usr/bin/env tsx
+/**
+ * Cleanup Orphaned Test Resources
+ *
+ * Standalone script to clean up orphaned workflows and executions
+ * from failed test runs. Run this periodically in CI or manually
+ * to maintain a clean test environment.
+ *
+ * Usage:
+ *   npm run test:cleanup:orphans
+ *   tsx tests/integration/n8n-api/scripts/cleanup-orphans.ts
+ */
+
+import { cleanupAllTestResources } from '../utils/cleanup-helpers';
+import { getN8nCredentials, validateCredentials } from '../utils/credentials';
+
+async function main() {
+  console.log('Starting cleanup of orphaned test resources...\n');
+
+  try {
+    // Validate credentials
+    const creds = getN8nCredentials();
+    validateCredentials(creds);
+
+    console.log(`n8n Instance: ${creds.url}`);
+    console.log(`Cleanup Tag: ${creds.cleanup.tag}`);
+    console.log(`Cleanup Prefix: ${creds.cleanup.namePrefix}\n`);
+
+    // Run cleanup
+    const result = await cleanupAllTestResources();
+
+    console.log('\n✅ Cleanup complete!');
+    console.log(`   Workflows deleted: ${result.workflows}`);
+    console.log(`   Executions deleted: ${result.executions}`);
+
+    process.exit(0);
+  } catch (error) {
+    console.error('\n❌ Cleanup failed:', error);
+    process.exit(1);
+  }
+}
+
+main();

tests/integration/n8n-api/system/diagnostic.test.ts

@@ -0,0 +1,270 @@
+/**
+ * Integration Tests: handleDiagnostic
+ *
+ * Tests system diagnostic functionality.
+ * Covers environment checks, API status, and verbose mode.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { createMcpContext } from '../utils/mcp-context';
+import { InstanceContext } from '../../../../src/types/instance-context';
+import { handleDiagnostic } from '../../../../src/mcp/handlers-n8n-manager';
+import { DiagnosticResponse } from '../utils/response-types';
+
+describe('Integration: handleDiagnostic', () => {
+  let mcpContext: InstanceContext;
+
+  beforeEach(() => {
+    mcpContext = createMcpContext();
+  });
+
+  // ======================================================================
+  // Basic Diagnostic
+  // ======================================================================
+
+  describe('Basic Diagnostic', () => {
+    it('should run basic diagnostic check', async () => {
+      const response = await handleDiagnostic(
+        { params: { arguments: {} } },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      expect(response.data).toBeDefined();
+
+      const data = response.data as DiagnosticResponse;
+
+      // Verify core diagnostic fields
+      expect(data).toHaveProperty('timestamp');
+      expect(data).toHaveProperty('environment');
+      expect(data).toHaveProperty('apiConfiguration');
+      expect(data).toHaveProperty('toolsAvailability');
+      expect(data).toHaveProperty('troubleshooting');
+
+      // Verify timestamp format
+      expect(typeof data.timestamp).toBe('string');
+      const timestamp = new Date(data.timestamp);
+      expect(timestamp.toString()).not.toBe('Invalid Date');
+    });
+
+    it('should include environment variables', async () => {
+      const response = await handleDiagnostic(
+        { params: { arguments: {} } },
+        mcpContext
+      );
+
+      const data = response.data as DiagnosticResponse;
+
+      expect(data.environment).toBeDefined();
+      expect(data.environment).toHaveProperty('N8N_API_URL');
+      expect(data.environment).toHaveProperty('N8N_API_KEY');
+      expect(data.environment).toHaveProperty('NODE_ENV');
+      expect(data.environment).toHaveProperty('MCP_MODE');
+
+      // API key should be masked
+      if (data.environment.N8N_API_KEY) {
+        expect(data.environment.N8N_API_KEY).toBe('***configured***');
+      }
+    });
+
+    it('should check API configuration and connectivity', async () => {
+      const response = await handleDiagnostic(
+        { params: { arguments: {} } },
+        mcpContext
+      );
+
+      const data = response.data as DiagnosticResponse;
+
+      expect(data.apiConfiguration).toBeDefined();
+      expect(data.apiConfiguration).toHaveProperty('configured');
+      expect(data.apiConfiguration).toHaveProperty('status');
+
+      // In test environment, API should be configured
+      expect(data.apiConfiguration.configured).toBe(true);
+
+      // Verify API status
+      const status = data.apiConfiguration.status;
+      expect(status).toHaveProperty('configured');
+      expect(status).toHaveProperty('connected');
+
+      // Should successfully connect to n8n API
+      expect(status.connected).toBe(true);
+
+      // If connected, should have version info
+      if (status.connected) {
+        expect(status).toHaveProperty('version');
+      }
+
+      // Config details should be present when configured
+      if (data.apiConfiguration.configured) {
+        expect(data.apiConfiguration).toHaveProperty('config');
+        expect(data.apiConfiguration.config).toHaveProperty('baseUrl');
+        expect(data.apiConfiguration.config).toHaveProperty('timeout');
+        expect(data.apiConfiguration.config).toHaveProperty('maxRetries');
+      }
+    });
+
+    it('should report tools availability', async () => {
+      const response = await handleDiagnostic(
+        { params: { arguments: {} } },
+        mcpContext
+      );
+
+      const data = response.data as DiagnosticResponse;
+
+      expect(data.toolsAvailability).toBeDefined();
+      expect(data.toolsAvailability).toHaveProperty('documentationTools');
+      expect(data.toolsAvailability).toHaveProperty('managementTools');
+      expect(data.toolsAvailability).toHaveProperty('totalAvailable');
+
+      // Documentation tools should always be available
+      const docTools = data.toolsAvailability.documentationTools;
+      expect(docTools.count).toBeGreaterThan(0);
+      expect(docTools.enabled).toBe(true);
+      expect(docTools.description).toBeDefined();
+
+      // Management tools should be available when API configured
+      const mgmtTools = data.toolsAvailability.managementTools;
+      expect(mgmtTools).toHaveProperty('count');
+      expect(mgmtTools).toHaveProperty('enabled');
+      expect(mgmtTools).toHaveProperty('description');
+
+      // In test environment, management tools should be enabled
+      expect(mgmtTools.enabled).toBe(true);
+      expect(mgmtTools.count).toBeGreaterThan(0);
+
+      // Total should be sum of both
+      expect(data.toolsAvailability.totalAvailable).toBe(
+        docTools.count + mgmtTools.count
+      );
+    });
+
+    it('should include troubleshooting information', async () => {
+      const response = await handleDiagnostic(
+        { params: { arguments: {} } },
+        mcpContext
+      );
+
+      const data = response.data as DiagnosticResponse;
+
+      expect(data.troubleshooting).toBeDefined();
+      expect(data.troubleshooting).toHaveProperty('steps');
+      expect(data.troubleshooting).toHaveProperty('documentation');
+
+      // Troubleshooting steps should be an array
+      expect(Array.isArray(data.troubleshooting.steps)).toBe(true);
+      expect(data.troubleshooting.steps.length).toBeGreaterThan(0);
+
+      // Documentation link should be present
+      expect(typeof data.troubleshooting.documentation).toBe('string');
+      expect(data.troubleshooting.documentation).toContain('https://');
+    });
+  });
+
+  // ======================================================================
+  // Verbose Mode
+  // ======================================================================
+
+  describe('Verbose Mode', () => {
+    it('should include additional debug info in verbose mode', async () => {
+      const response = await handleDiagnostic(
+        { params: { arguments: { verbose: true } } },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as DiagnosticResponse;
+
+      // Verbose mode should add debug section
+      expect(data).toHaveProperty('debug');
+      expect(data.debug).toBeDefined();
+
+      // Verify debug information
+      expect(data.debug).toBeDefined();
+      expect(data.debug).toHaveProperty('processEnv');
+      expect(data.debug).toHaveProperty('nodeVersion');
+      expect(data.debug).toHaveProperty('platform');
+      expect(data.debug).toHaveProperty('workingDirectory');
+
+      // Process env should list relevant environment variables
+      expect(Array.isArray(data.debug?.processEnv)).toBe(true);
+
+      // Node version should be a string
+      expect(typeof data.debug?.nodeVersion).toBe('string');
+      expect(data.debug?.nodeVersion).toMatch(/^v\d+\.\d+\.\d+/);
+
+      // Platform should be a string (linux, darwin, win32, etc.)
+      expect(typeof data.debug?.platform).toBe('string');
+      expect(data.debug && data.debug.platform.length).toBeGreaterThan(0);
+
+      // Working directory should be a path
+      expect(typeof data.debug?.workingDirectory).toBe('string');
+      expect(data.debug && data.debug.workingDirectory.length).toBeGreaterThan(0);
+    });
+
+    it('should not include debug info when verbose is false', async () => {
+      const response = await handleDiagnostic(
+        { params: { arguments: { verbose: false } } },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as DiagnosticResponse;
+
+      // Debug section should not be present
+      expect(data.debug).toBeUndefined();
+    });
+
+    it('should not include debug info by default', async () => {
+      const response = await handleDiagnostic(
+        { params: { arguments: {} } },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as DiagnosticResponse;
+
+      // Debug section should not be present when verbose not specified
+      expect(data.debug).toBeUndefined();
+    });
+  });
+
+  // ======================================================================
+  // Response Format Verification
+  // ======================================================================
+
+  describe('Response Format', () => {
+    it('should return complete diagnostic response structure', async () => {
+      const response = await handleDiagnostic(
+        { params: { arguments: {} } },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      expect(response.data).toBeDefined();
+
+      const data = response.data as DiagnosticResponse;
+
+      // Verify all required fields
+      const requiredFields = [
+        'timestamp',
+        'environment',
+        'apiConfiguration',
+        'toolsAvailability',
+        'troubleshooting'
+      ];
+
+      requiredFields.forEach(field => {
+        expect(data).toHaveProperty(field);
+        expect(data[field]).toBeDefined();
+      });
+
+      // Verify data types
+      expect(typeof data.timestamp).toBe('string');
+      expect(typeof data.environment).toBe('object');
+      expect(typeof data.apiConfiguration).toBe('object');
+      expect(typeof data.toolsAvailability).toBe('object');
+      expect(typeof data.troubleshooting).toBe('object');
+    });
+  });
+});

tests/integration/n8n-api/system/health-check.test.ts

@@ -0,0 +1,110 @@
+/**
+ * Integration Tests: handleHealthCheck
+ *
+ * Tests API health check against a real n8n instance.
+ * Covers connectivity verification and feature availability.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { createMcpContext } from '../utils/mcp-context';
+import { InstanceContext } from '../../../../src/types/instance-context';
+import { handleHealthCheck } from '../../../../src/mcp/handlers-n8n-manager';
+import { HealthCheckResponse } from '../utils/response-types';
+
+describe('Integration: handleHealthCheck', () => {
+  let mcpContext: InstanceContext;
+
+  beforeEach(() => {
+    mcpContext = createMcpContext();
+  });
+
+  // ======================================================================
+  // Successful Health Check
+  // ======================================================================
+
+  describe('API Available', () => {
+    it('should successfully check n8n API health', async () => {
+      const response = await handleHealthCheck(mcpContext);
+
+      expect(response.success).toBe(true);
+      expect(response.data).toBeDefined();
+
+      const data = response.data as HealthCheckResponse;
+
+      // Verify required fields
+      expect(data).toHaveProperty('status');
+      expect(data).toHaveProperty('apiUrl');
+      expect(data).toHaveProperty('mcpVersion');
+
+      // Status should be a string (e.g., "ok", "healthy")
+      if (data.status) {
+        expect(typeof data.status).toBe('string');
+      }
+
+      // API URL should match configuration
+      expect(data.apiUrl).toBeDefined();
+      expect(typeof data.apiUrl).toBe('string');
+
+      // MCP version should be defined
+      expect(data.mcpVersion).toBeDefined();
+      expect(typeof data.mcpVersion).toBe('string');
+    });
+
+    it('should include feature availability information', async () => {
+      const response = await handleHealthCheck(mcpContext);
+
+      expect(response.success).toBe(true);
+      const data = response.data as HealthCheckResponse;
+
+      // Check for feature information
+      // Note: Features may vary by n8n instance configuration
+      if (data.features) {
+        expect(typeof data.features).toBe('object');
+      }
+
+      // Check for version information
+      if (data.n8nVersion) {
+        expect(typeof data.n8nVersion).toBe('string');
+      }
+
+      if (data.supportedN8nVersion) {
+        expect(typeof data.supportedN8nVersion).toBe('string');
+      }
+
+      // Should include version note for AI agents
+      if (data.versionNote) {
+        expect(typeof data.versionNote).toBe('string');
+        expect(data.versionNote).toContain('version');
+      }
+    });
+  });
+
+  // ======================================================================
+  // Response Format Verification
+  // ======================================================================
+
+  describe('Response Format', () => {
+    it('should return complete health check response structure', async () => {
+      const response = await handleHealthCheck(mcpContext);
+
+      expect(response.success).toBe(true);
+      expect(response.data).toBeDefined();
+
+      const data = response.data as HealthCheckResponse;
+
+      // Verify all expected fields are present
+      const expectedFields = ['status', 'apiUrl', 'mcpVersion'];
+      expectedFields.forEach(field => {
+        expect(data).toHaveProperty(field);
+      });
+
+      // Optional fields that may be present
+      const optionalFields = ['instanceId', 'n8nVersion', 'features', 'supportedN8nVersion', 'versionNote'];
+      optionalFields.forEach(field => {
+        if (data[field] !== undefined) {
+          expect(data[field]).not.toBeNull();
+        }
+      });
+    });
+  });
+});

tests/integration/n8n-api/system/list-tools.test.ts

@@ -0,0 +1,208 @@
+/**
+ * Integration Tests: handleListAvailableTools
+ *
+ * Tests tool listing functionality.
+ * Covers tool discovery and configuration status.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { createMcpContext } from '../utils/mcp-context';
+import { InstanceContext } from '../../../../src/types/instance-context';
+import { handleListAvailableTools } from '../../../../src/mcp/handlers-n8n-manager';
+import { ListToolsResponse } from '../utils/response-types';
+
+describe('Integration: handleListAvailableTools', () => {
+  let mcpContext: InstanceContext;
+
+  beforeEach(() => {
+    mcpContext = createMcpContext();
+  });
+
+  // ======================================================================
+  // List All Tools
+  // ======================================================================
+
+  describe('Tool Listing', () => {
+    it('should list all available tools organized by category', async () => {
+      const response = await handleListAvailableTools(mcpContext);
+
+      expect(response.success).toBe(true);
+      expect(response.data).toBeDefined();
+
+      const data = response.data as ListToolsResponse;
+
+      // Verify tools array exists
+      expect(data).toHaveProperty('tools');
+      expect(Array.isArray(data.tools)).toBe(true);
+      expect(data.tools.length).toBeGreaterThan(0);
+
+      // Verify tool categories
+      const categories = data.tools.map((cat: any) => cat.category);
+      expect(categories).toContain('Workflow Management');
+      expect(categories).toContain('Execution Management');
+      expect(categories).toContain('System');
+
+      // Verify each category has tools
+      data.tools.forEach(category => {
+        expect(category).toHaveProperty('category');
+        expect(category).toHaveProperty('tools');
+        expect(Array.isArray(category.tools)).toBe(true);
+        expect(category.tools.length).toBeGreaterThan(0);
+
+        // Verify each tool has required fields
+        category.tools.forEach(tool => {
+          expect(tool).toHaveProperty('name');
+          expect(tool).toHaveProperty('description');
+          expect(typeof tool.name).toBe('string');
+          expect(typeof tool.description).toBe('string');
+        });
+      });
+    });
+
+    it('should include API configuration status', async () => {
+      const response = await handleListAvailableTools(mcpContext);
+
+      expect(response.success).toBe(true);
+      const data = response.data as ListToolsResponse;
+
+      // Verify configuration status
+      expect(data).toHaveProperty('apiConfigured');
+      expect(typeof data.apiConfigured).toBe('boolean');
+
+      // Since tests run with API configured, should be true
+      expect(data.apiConfigured).toBe(true);
+
+      // Verify configuration details are present when configured
+      if (data.apiConfigured) {
+        expect(data).toHaveProperty('configuration');
+        expect(data.configuration).toBeDefined();
+        expect(data.configuration).toHaveProperty('apiUrl');
+        expect(data.configuration).toHaveProperty('timeout');
+        expect(data.configuration).toHaveProperty('maxRetries');
+      }
+    });
+
+    it('should include API limitations information', async () => {
+      const response = await handleListAvailableTools(mcpContext);
+
+      expect(response.success).toBe(true);
+      const data = response.data as ListToolsResponse;
+
+      // Verify limitations are documented
+      expect(data).toHaveProperty('limitations');
+      expect(Array.isArray(data.limitations)).toBe(true);
+      expect(data.limitations.length).toBeGreaterThan(0);
+
+      // Verify limitations are informative strings
+      data.limitations.forEach(limitation => {
+        expect(typeof limitation).toBe('string');
+        expect(limitation.length).toBeGreaterThan(0);
+      });
+
+      // Common known limitations
+      const limitationsText = data.limitations.join(' ');
+      expect(limitationsText).toContain('Cannot activate');
+      expect(limitationsText).toContain('Cannot execute workflows directly');
+    });
+  });
+
+  // ======================================================================
+  // Workflow Management Tools
+  // ======================================================================
+
+  describe('Workflow Management Tools', () => {
+    it('should include all workflow management tools', async () => {
+      const response = await handleListAvailableTools(mcpContext);
+      const data = response.data as ListToolsResponse;
+
+      const workflowCategory = data.tools.find(cat => cat.category === 'Workflow Management');
+      expect(workflowCategory).toBeDefined();
+
+      const toolNames = workflowCategory!.tools.map(t => t.name);
+
+      // Core workflow tools
+      expect(toolNames).toContain('n8n_create_workflow');
+      expect(toolNames).toContain('n8n_get_workflow');
+      expect(toolNames).toContain('n8n_update_workflow');
+      expect(toolNames).toContain('n8n_delete_workflow');
+      expect(toolNames).toContain('n8n_list_workflows');
+
+      // Enhanced workflow tools
+      expect(toolNames).toContain('n8n_get_workflow_details');
+      expect(toolNames).toContain('n8n_get_workflow_structure');
+      expect(toolNames).toContain('n8n_get_workflow_minimal');
+      expect(toolNames).toContain('n8n_validate_workflow');
+      expect(toolNames).toContain('n8n_autofix_workflow');
+    });
+  });
+
+  // ======================================================================
+  // Execution Management Tools
+  // ======================================================================
+
+  describe('Execution Management Tools', () => {
+    it('should include all execution management tools', async () => {
+      const response = await handleListAvailableTools(mcpContext);
+      const data = response.data as ListToolsResponse;
+
+      const executionCategory = data.tools.find(cat => cat.category === 'Execution Management');
+      expect(executionCategory).toBeDefined();
+
+      const toolNames = executionCategory!.tools.map(t => t.name);
+
+      expect(toolNames).toContain('n8n_trigger_webhook_workflow');
+      expect(toolNames).toContain('n8n_get_execution');
+      expect(toolNames).toContain('n8n_list_executions');
+      expect(toolNames).toContain('n8n_delete_execution');
+    });
+  });
+
+  // ======================================================================
+  // System Tools
+  // ======================================================================
+
+  describe('System Tools', () => {
+    it('should include system tools', async () => {
+      const response = await handleListAvailableTools(mcpContext);
+      const data = response.data as ListToolsResponse;
+
+      const systemCategory = data.tools.find(cat => cat.category === 'System');
+      expect(systemCategory).toBeDefined();
+
+      const toolNames = systemCategory!.tools.map(t => t.name);
+
+      expect(toolNames).toContain('n8n_health_check');
+      expect(toolNames).toContain('n8n_list_available_tools');
+    });
+  });
+
+  // ======================================================================
+  // Response Format Verification
+  // ======================================================================
+
+  describe('Response Format', () => {
+    it('should return complete tool list response structure', async () => {
+      const response = await handleListAvailableTools(mcpContext);
+
+      expect(response.success).toBe(true);
+      expect(response.data).toBeDefined();
+
+      const data = response.data as ListToolsResponse;
+
+      // Verify all required fields
+      expect(data).toHaveProperty('tools');
+      expect(data).toHaveProperty('apiConfigured');
+      expect(data).toHaveProperty('limitations');
+
+      // Verify optional configuration field
+      if (data.apiConfigured) {
+        expect(data).toHaveProperty('configuration');
+      }
+
+      // Verify data types
+      expect(Array.isArray(data.tools)).toBe(true);
+      expect(typeof data.apiConfigured).toBe('boolean');
+      expect(Array.isArray(data.limitations)).toBe(true);
+    });
+  });
+});

tests/integration/n8n-api/test-connection.ts

@@ -0,0 +1,34 @@
+/**
+ * Quick test script to verify n8n API connection
+ */
+
+import { getN8nCredentials } from './utils/credentials';
+import { getTestN8nClient } from './utils/n8n-client';
+
+async function testConnection() {
+  try {
+    console.log('Loading credentials...');
+    const creds = getN8nCredentials();
+    console.log('Credentials loaded:', {
+      url: creds.url,
+      hasApiKey: !!creds.apiKey,
+      apiKeyLength: creds.apiKey?.length
+    });
+
+    console.log('\nCreating n8n client...');
+    const client = getTestN8nClient();
+    console.log('Client created successfully');
+
+    console.log('\nTesting health check...');
+    const health = await client.healthCheck();
+    console.log('Health check result:', health);
+
+    console.log('\n✅ Connection test passed!');
+  } catch (error) {
+    console.error('❌ Connection test failed:');
+    console.error(error);
+    process.exit(1);
+  }
+}
+
+testConnection();

tests/integration/n8n-api/types/mcp-responses.ts

@@ -0,0 +1,72 @@
+/**
+ * TypeScript interfaces for MCP handler responses
+ *
+ * These interfaces provide type safety for integration tests,
+ * replacing unsafe `as any` casts with proper type definitions.
+ */
+
+/**
+ * Workflow validation response from handleValidateWorkflow
+ */
+export interface ValidationResponse {
+  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;
+    message: string;
+    details?: unknown;
+  }>;
+  warnings?: Array<{
+    node: string;
+    message: string;
+    details?: unknown;
+  }>;
+}
+
+/**
+ * Workflow autofix response from handleAutofixWorkflow
+ */
+export interface AutofixResponse {
+  workflowId: string;
+  workflowName: string;
+  preview?: boolean;
+  fixesAvailable?: number;
+  fixesApplied?: number;
+  fixes?: Array<{
+    type: 'expression-format' | 'typeversion-correction' | 'error-output-config' | 'node-type-correction' | 'webhook-missing-path';
+    confidence: 'high' | 'medium' | 'low';
+    description: string;
+    nodeName?: string;
+    nodeId?: string;
+    before?: unknown;
+    after?: unknown;
+  }>;
+  summary?: {
+    totalFixes: number;
+    byType: Record<string, number>;
+    byConfidence: Record<string, number>;
+  };
+  stats?: {
+    expressionFormat?: number;
+    typeVersionCorrection?: number;
+    errorOutputConfig?: number;
+    nodeTypeCorrection?: number;
+    webhookMissingPath?: number;
+  };
+  message?: string;
+  validationSummary?: {
+    errors: number;
+    warnings: number;
+  };
+}

tests/integration/n8n-api/utils/cleanup-helpers.ts

@@ -0,0 +1,308 @@
+/**
+ * Cleanup Helpers for Integration Tests
+ *
+ * Provides multi-level cleanup strategies for test resources:
+ * - Orphaned workflows (from failed test runs)
+ * - Old executions (older than 24 hours)
+ * - Bulk cleanup by tag or name prefix
+ */
+
+import { getTestN8nClient } from './n8n-client';
+import { getN8nCredentials } from './credentials';
+import { Logger } from '../../../../src/utils/logger';
+
+const logger = new Logger({ prefix: '[Cleanup]' });
+
+/**
+ * Clean up orphaned test workflows
+ *
+ * Finds and deletes all workflows tagged with the test tag or
+ * prefixed with the test name prefix. Run this periodically in CI
+ * to clean up failed test runs.
+ *
+ * @returns Array of deleted workflow IDs
+ */
+export async function cleanupOrphanedWorkflows(): Promise<string[]> {
+  const creds = getN8nCredentials();
+  const client = getTestN8nClient();
+  const deleted: string[] = [];
+
+  logger.info('Searching for orphaned test workflows...');
+
+  let allWorkflows: any[] = [];
+  let cursor: string | undefined;
+  let pageCount = 0;
+  const MAX_PAGES = 1000; // Safety limit to prevent infinite loops
+
+  // Fetch all workflows with pagination
+  try {
+    do {
+      pageCount++;
+
+      if (pageCount > MAX_PAGES) {
+        logger.error(`Exceeded maximum pages (${MAX_PAGES}). Possible infinite loop or API issue.`);
+        throw new Error('Pagination safety limit exceeded while fetching workflows');
+      }
+
+      logger.debug(`Fetching workflows page ${pageCount}...`);
+
+      const response = await client.listWorkflows({
+        cursor,
+        limit: 100,
+        excludePinnedData: true
+      });
+
+      allWorkflows.push(...response.data);
+      cursor = response.nextCursor || undefined;
+    } while (cursor);
+
+    logger.info(`Found ${allWorkflows.length} total workflows across ${pageCount} page(s)`);
+  } catch (error) {
+    logger.error('Failed to fetch workflows:', error);
+    throw error;
+  }
+
+  // Pre-activated webhook workflow that should NOT be deleted
+  // This is needed for webhook trigger integration tests
+  // Note: Single webhook accepts all HTTP methods (GET, POST, PUT, DELETE)
+  const preservedWorkflowNames = new Set([
+    '[MCP-TEST] Webhook All Methods'
+  ]);
+
+  // Find test workflows but exclude pre-activated webhook workflows
+  const testWorkflows = allWorkflows.filter(w => {
+    const isTestWorkflow = w.tags?.includes(creds.cleanup.tag) || w.name?.startsWith(creds.cleanup.namePrefix);
+    const isPreserved = preservedWorkflowNames.has(w.name);
+
+    return isTestWorkflow && !isPreserved;
+  });
+
+  logger.info(`Found ${testWorkflows.length} orphaned test workflow(s) (excluding ${preservedWorkflowNames.size} preserved webhook workflow)`);
+
+  if (testWorkflows.length === 0) {
+    return deleted;
+  }
+
+  // Delete them
+  for (const workflow of testWorkflows) {
+    try {
+      await client.deleteWorkflow(workflow.id);
+      deleted.push(workflow.id);
+      logger.debug(`Deleted orphaned workflow: ${workflow.name} (${workflow.id})`);
+    } catch (error) {
+      logger.warn(`Failed to delete workflow ${workflow.id}:`, error);
+    }
+  }
+
+  logger.info(`Successfully deleted ${deleted.length} orphaned workflow(s)`);
+  return deleted;
+}
+
+/**
+ * Clean up old executions
+ *
+ * Deletes executions older than the specified age.
+ *
+ * @param maxAgeMs - Maximum age in milliseconds (default: 24 hours)
+ * @returns Array of deleted execution IDs
+ */
+export async function cleanupOldExecutions(
+  maxAgeMs: number = 24 * 60 * 60 * 1000
+): Promise<string[]> {
+  const client = getTestN8nClient();
+  const deleted: string[] = [];
+
+  logger.info(`Searching for executions older than ${maxAgeMs}ms...`);
+
+  let allExecutions: any[] = [];
+  let cursor: string | undefined;
+  let pageCount = 0;
+  const MAX_PAGES = 1000; // Safety limit to prevent infinite loops
+
+  // Fetch all executions
+  try {
+    do {
+      pageCount++;
+
+      if (pageCount > MAX_PAGES) {
+        logger.error(`Exceeded maximum pages (${MAX_PAGES}). Possible infinite loop or API issue.`);
+        throw new Error('Pagination safety limit exceeded while fetching executions');
+      }
+
+      logger.debug(`Fetching executions page ${pageCount}...`);
+
+      const response = await client.listExecutions({
+        cursor,
+        limit: 100,
+        includeData: false
+      });
+
+      allExecutions.push(...response.data);
+      cursor = response.nextCursor || undefined;
+    } while (cursor);
+
+    logger.info(`Found ${allExecutions.length} total executions across ${pageCount} page(s)`);
+  } catch (error) {
+    logger.error('Failed to fetch executions:', error);
+    throw error;
+  }
+
+  const cutoffTime = Date.now() - maxAgeMs;
+  const oldExecutions = allExecutions.filter(e => {
+    const executionTime = new Date(e.startedAt).getTime();
+    return executionTime < cutoffTime;
+  });
+
+  logger.info(`Found ${oldExecutions.length} old execution(s)`);
+
+  if (oldExecutions.length === 0) {
+    return deleted;
+  }
+
+  for (const execution of oldExecutions) {
+    try {
+      await client.deleteExecution(execution.id);
+      deleted.push(execution.id);
+      logger.debug(`Deleted old execution: ${execution.id}`);
+    } catch (error) {
+      logger.warn(`Failed to delete execution ${execution.id}:`, error);
+    }
+  }
+
+  logger.info(`Successfully deleted ${deleted.length} old execution(s)`);
+  return deleted;
+}
+
+/**
+ * Clean up all test resources
+ *
+ * Combines cleanupOrphanedWorkflows and cleanupOldExecutions.
+ * Use this as a comprehensive cleanup in CI.
+ *
+ * @returns Object with counts of deleted resources
+ */
+export async function cleanupAllTestResources(): Promise<{
+  workflows: number;
+  executions: number;
+}> {
+  logger.info('Starting comprehensive test resource cleanup...');
+
+  const [workflowIds, executionIds] = await Promise.all([
+    cleanupOrphanedWorkflows(),
+    cleanupOldExecutions()
+  ]);
+
+  logger.info(
+    `Cleanup complete: ${workflowIds.length} workflows, ${executionIds.length} executions`
+  );
+
+  return {
+    workflows: workflowIds.length,
+    executions: executionIds.length
+  };
+}
+
+/**
+ * Delete workflows by tag
+ *
+ * Deletes all workflows with the specified tag.
+ *
+ * @param tag - Tag to match
+ * @returns Array of deleted workflow IDs
+ */
+export async function cleanupWorkflowsByTag(tag: string): Promise<string[]> {
+  const client = getTestN8nClient();
+  const deleted: string[] = [];
+
+  logger.info(`Searching for workflows with tag: ${tag}`);
+
+  try {
+    const response = await client.listWorkflows({
+      tags: tag || undefined,
+      limit: 100,
+      excludePinnedData: true
+    });
+
+    const workflows = response.data;
+    logger.info(`Found ${workflows.length} workflow(s) with tag: ${tag}`);
+
+    for (const workflow of workflows) {
+      if (!workflow.id) continue;
+
+      try {
+        await client.deleteWorkflow(workflow.id);
+        deleted.push(workflow.id);
+        logger.debug(`Deleted workflow: ${workflow.name} (${workflow.id})`);
+      } catch (error) {
+        logger.warn(`Failed to delete workflow ${workflow.id}:`, error);
+      }
+    }
+
+    logger.info(`Successfully deleted ${deleted.length} workflow(s)`);
+    return deleted;
+  } catch (error) {
+    logger.error(`Failed to cleanup workflows by tag: ${tag}`, error);
+    throw error;
+  }
+}
+
+/**
+ * Delete executions for a specific workflow
+ *
+ * @param workflowId - Workflow ID
+ * @returns Array of deleted execution IDs
+ */
+export async function cleanupExecutionsByWorkflow(
+  workflowId: string
+): Promise<string[]> {
+  const client = getTestN8nClient();
+  const deleted: string[] = [];
+
+  logger.info(`Searching for executions of workflow: ${workflowId}`);
+
+  let cursor: string | undefined;
+  let totalCount = 0;
+  let pageCount = 0;
+  const MAX_PAGES = 1000; // Safety limit to prevent infinite loops
+
+  try {
+    do {
+      pageCount++;
+
+      if (pageCount > MAX_PAGES) {
+        logger.error(`Exceeded maximum pages (${MAX_PAGES}). Possible infinite loop or API issue.`);
+        throw new Error(`Pagination safety limit exceeded while fetching executions for workflow ${workflowId}`);
+      }
+
+      const response = await client.listExecutions({
+        workflowId,
+        cursor,
+        limit: 100,
+        includeData: false
+      });
+
+      const executions = response.data;
+      totalCount += executions.length;
+
+      for (const execution of executions) {
+        try {
+          await client.deleteExecution(execution.id);
+          deleted.push(execution.id);
+          logger.debug(`Deleted execution: ${execution.id}`);
+        } catch (error) {
+          logger.warn(`Failed to delete execution ${execution.id}:`, error);
+        }
+      }
+
+      cursor = response.nextCursor || undefined;
+    } while (cursor);
+
+    logger.info(
+      `Successfully deleted ${deleted.length}/${totalCount} execution(s) for workflow ${workflowId}`
+    );
+    return deleted;
+  } catch (error) {
+    logger.error(`Failed to cleanup executions for workflow: ${workflowId}`, error);
+    throw error;
+  }
+}

tests/integration/n8n-api/utils/credentials.ts

@@ -0,0 +1,195 @@
+/**
+ * Integration Test Credentials Management
+ *
+ * Provides environment-aware credential loading for integration tests.
+ * - Local development: Reads from .env file
+ * - CI/GitHub Actions: Uses GitHub secrets from process.env
+ */
+
+import dotenv from 'dotenv';
+import path from 'path';
+
+// Load .env file for local development
+dotenv.config({ path: path.resolve(process.cwd(), '.env') });
+
+export interface N8nTestCredentials {
+  url: string;
+  apiKey: string;
+  webhookUrls: {
+    get: string;
+    post: string;
+    put: string;
+    delete: string;
+  };
+  cleanup: {
+    enabled: boolean;
+    tag: string;
+    namePrefix: string;
+  };
+}
+
+/**
+ * Get n8n credentials for integration tests
+ *
+ * Automatically detects environment (local vs CI) and loads
+ * credentials from the appropriate source.
+ *
+ * @returns N8nTestCredentials
+ * @throws Error if required credentials are missing
+ */
+export function getN8nCredentials(): N8nTestCredentials {
+  if (process.env.CI) {
+    // CI: Use GitHub secrets - validate required variables first
+    const url = process.env.N8N_API_URL;
+    const apiKey = process.env.N8N_API_KEY;
+
+    if (!url || !apiKey) {
+      throw new Error(
+        'Missing required CI credentials:\n' +
+        `  N8N_API_URL: ${url ? 'set' : 'MISSING'}\n` +
+        `  N8N_API_KEY: ${apiKey ? 'set' : 'MISSING'}\n` +
+        'Please configure GitHub secrets for integration tests.'
+      );
+    }
+
+    return {
+      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,
+        tag: 'mcp-integration-test',
+        namePrefix: '[MCP-TEST]'
+      }
+    };
+  } else {
+    // Local: Use .env file - validate required variables first
+    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,
+      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',
+        tag: process.env.N8N_TEST_TAG || 'mcp-integration-test',
+        namePrefix: process.env.N8N_TEST_NAME_PREFIX || '[MCP-TEST]'
+      }
+    };
+  }
+}
+
+/**
+ * Validate that required credentials are present
+ *
+ * @param creds - Credentials to validate
+ * @throws Error if required credentials are missing
+ */
+export function validateCredentials(creds: N8nTestCredentials): void {
+  const missing: string[] = [];
+
+  if (!creds.url) {
+    missing.push(process.env.CI ? 'N8N_URL' : 'N8N_API_URL');
+  }
+  if (!creds.apiKey) {
+    missing.push('N8N_API_KEY');
+  }
+
+  if (missing.length > 0) {
+    throw new Error(
+      `Missing required n8n credentials: ${missing.join(', ')}\n\n` +
+      `Please set the following environment variables:\n` +
+      missing.map(v => `  ${v}`).join('\n') + '\n\n' +
+      `See .env.example for configuration details.`
+    );
+  }
+}
+
+/**
+ * Validate that webhook URLs are configured
+ *
+ * @param creds - Credentials to validate
+ * @throws Error with setup instructions if webhook URLs are missing
+ */
+export function validateWebhookUrls(creds: N8nTestCredentials): void {
+  const missing: string[] = [];
+
+  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) {
+    const envVars = missing.map(m => `N8N_TEST_WEBHOOK_${m}_URL`);
+
+    throw new Error(
+      `Missing webhook URLs for HTTP methods: ${missing.join(', ')}\n\n` +
+      `Webhook testing requires pre-activated workflows in n8n.\n` +
+      `n8n API doesn't support workflow activation, so these must be created manually.\n\n` +
+      `Setup Instructions:\n` +
+      `1. Create ${missing.length} workflow(s) in your n8n instance\n` +
+      `2. Each workflow should have a single Webhook node\n` +
+      `3. Configure webhook paths:\n` +
+      missing.map(m => `   - ${m}: mcp-test-${m.toLowerCase()}`).join('\n') + '\n' +
+      `4. ACTIVATE each workflow in n8n UI\n` +
+      `5. Set the following environment variables with full webhook URLs:\n` +
+      envVars.map(v => `   ${v}=<full-webhook-url>`).join('\n') + '\n\n' +
+      `Example: N8N_TEST_WEBHOOK_GET_URL=https://n8n-test.n8n-mcp.com/webhook/mcp-test-get\n\n` +
+      `See docs/local/integration-testing-plan.md for detailed instructions.`
+    );
+  }
+}
+
+/**
+ * Check if credentials are configured (non-throwing version)
+ *
+ * @returns true if basic credentials are available
+ */
+export function hasCredentials(): boolean {
+  try {
+    const creds = getN8nCredentials();
+    return !!(creds.url && creds.apiKey);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if webhook URLs are configured (non-throwing version)
+ *
+ * @returns true if all webhook URLs are available
+ */
+export function hasWebhookUrls(): boolean {
+  try {
+    const creds = getN8nCredentials();
+    return !!(
+      creds.webhookUrls.get &&
+      creds.webhookUrls.post &&
+      creds.webhookUrls.put &&
+      creds.webhookUrls.delete
+    );
+  } catch {
+    return false;
+  }
+}

tests/integration/n8n-api/utils/factories.ts

@@ -0,0 +1,326 @@
+/**
+ * Test Data Factories
+ *
+ * Provides factory functions for generating test data dynamically.
+ * Useful for creating variations of workflows, nodes, and parameters.
+ */
+
+import { Workflow, WorkflowNode } from '../../../../src/types/n8n-api';
+import { createTestWorkflowName } from './test-context';
+
+/**
+ * Create a webhook node with custom parameters
+ *
+ * @param options - Node options
+ * @returns WorkflowNode
+ */
+export function createWebhookNode(options: {
+  id?: string;
+  name?: string;
+  httpMethod?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+  path?: string;
+  position?: [number, number];
+  responseMode?: 'onReceived' | 'lastNode';
+}): WorkflowNode {
+  return {
+    id: options.id || `webhook-${Date.now()}`,
+    name: options.name || 'Webhook',
+    type: 'n8n-nodes-base.webhook',
+    typeVersion: 2,
+    position: options.position || [250, 300],
+    parameters: {
+      httpMethod: options.httpMethod || 'GET',
+      path: options.path || `test-${Date.now()}`,
+      responseMode: options.responseMode || 'lastNode'
+    }
+  };
+}
+
+/**
+ * Create an HTTP Request node with custom parameters
+ *
+ * @param options - Node options
+ * @returns WorkflowNode
+ */
+export function createHttpRequestNode(options: {
+  id?: string;
+  name?: string;
+  url?: string;
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+  position?: [number, number];
+  authentication?: string;
+}): WorkflowNode {
+  return {
+    id: options.id || `http-${Date.now()}`,
+    name: options.name || 'HTTP Request',
+    type: 'n8n-nodes-base.httpRequest',
+    typeVersion: 4.2,
+    position: options.position || [450, 300],
+    parameters: {
+      url: options.url || 'https://httpbin.org/get',
+      method: options.method || 'GET',
+      authentication: options.authentication || 'none'
+    }
+  };
+}
+
+/**
+ * Create a Set node with custom assignments
+ *
+ * @param options - Node options
+ * @returns WorkflowNode
+ */
+export function createSetNode(options: {
+  id?: string;
+  name?: string;
+  position?: [number, number];
+  assignments?: Array<{
+    name: string;
+    value: any;
+    type?: 'string' | 'number' | 'boolean' | 'object' | 'array';
+  }>;
+}): WorkflowNode {
+  const assignments = options.assignments || [
+    { name: 'key', value: 'value', type: 'string' as const }
+  ];
+
+  return {
+    id: options.id || `set-${Date.now()}`,
+    name: options.name || 'Set',
+    type: 'n8n-nodes-base.set',
+    typeVersion: 3.4,
+    position: options.position || [450, 300],
+    parameters: {
+      assignments: {
+        assignments: assignments.map((a, idx) => ({
+          id: `assign-${idx}`,
+          name: a.name,
+          value: a.value,
+          type: a.type || 'string'
+        }))
+      },
+      options: {}
+    }
+  };
+}
+
+/**
+ * Create a Manual Trigger node
+ *
+ * @param options - Node options
+ * @returns WorkflowNode
+ */
+export function createManualTriggerNode(options: {
+  id?: string;
+  name?: string;
+  position?: [number, number];
+} = {}): WorkflowNode {
+  return {
+    id: options.id || `manual-${Date.now()}`,
+    name: options.name || 'When clicking "Test workflow"',
+    type: 'n8n-nodes-base.manualTrigger',
+    typeVersion: 1,
+    position: options.position || [250, 300],
+    parameters: {}
+  };
+}
+
+/**
+ * Create a simple connection between two nodes
+ *
+ * @param from - Source node name
+ * @param to - Target node name
+ * @param options - Connection options
+ * @returns Connection object
+ */
+export function createConnection(
+  from: string,
+  to: string,
+  options: {
+    sourceOutput?: string;
+    targetInput?: string;
+    sourceIndex?: number;
+    targetIndex?: number;
+  } = {}
+): Record<string, any> {
+  const sourceOutput = options.sourceOutput || 'main';
+  const targetInput = options.targetInput || 'main';
+  const sourceIndex = options.sourceIndex || 0;
+  const targetIndex = options.targetIndex || 0;
+
+  return {
+    [from]: {
+      [sourceOutput]: [
+        [
+          {
+            node: to,
+            type: targetInput,
+            index: targetIndex
+          }
+        ]
+      ]
+    }
+  };
+}
+
+/**
+ * Create a workflow from nodes with automatic connections
+ *
+ * Connects nodes in sequence: node1 -> node2 -> node3, etc.
+ *
+ * @param name - Workflow name
+ * @param nodes - Array of nodes
+ * @returns Partial workflow
+ */
+export function createSequentialWorkflow(
+  name: string,
+  nodes: WorkflowNode[]
+): Partial<Workflow> {
+  const connections: Record<string, any> = {};
+
+  // Create connections between sequential nodes
+  for (let i = 0; i < nodes.length - 1; i++) {
+    const currentNode = nodes[i];
+    const nextNode = nodes[i + 1];
+
+    connections[currentNode.name] = {
+      main: [[{ node: nextNode.name, type: 'main', index: 0 }]]
+    };
+  }
+
+  return {
+    name: createTestWorkflowName(name),
+    nodes,
+    connections,
+    settings: {
+      executionOrder: 'v1'
+    }
+  };
+}
+
+/**
+ * Create a workflow with parallel branches
+ *
+ * Creates a workflow with one trigger node that splits into multiple
+ * parallel execution paths.
+ *
+ * @param name - Workflow name
+ * @param trigger - Trigger node
+ * @param branches - Array of branch nodes
+ * @returns Partial workflow
+ */
+export function createParallelWorkflow(
+  name: string,
+  trigger: WorkflowNode,
+  branches: WorkflowNode[]
+): Partial<Workflow> {
+  const connections: Record<string, any> = {
+    [trigger.name]: {
+      main: [branches.map(node => ({ node: node.name, type: 'main', index: 0 }))]
+    }
+  };
+
+  return {
+    name: createTestWorkflowName(name),
+    nodes: [trigger, ...branches],
+    connections,
+    settings: {
+      executionOrder: 'v1'
+    }
+  };
+}
+
+/**
+ * Generate a random string for test data
+ *
+ * @param length - String length (default: 8)
+ * @returns Random string
+ */
+export function randomString(length: number = 8): string {
+  const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';
+  let result = '';
+  for (let i = 0; i < length; i++) {
+    result += chars.charAt(Math.floor(Math.random() * chars.length));
+  }
+  return result;
+}
+
+/**
+ * Generate a unique ID for testing
+ *
+ * @param prefix - Optional prefix
+ * @returns Unique ID
+ */
+export function uniqueId(prefix: string = 'test'): string {
+  return `${prefix}-${Date.now()}-${randomString(4)}`;
+}
+
+/**
+ * Create a workflow with error handling
+ *
+ * @param name - Workflow name
+ * @param mainNode - Main processing node
+ * @param errorNode - Error handling node
+ * @returns Partial workflow with error handling configured
+ */
+export function createErrorHandlingWorkflow(
+  name: string,
+  mainNode: WorkflowNode,
+  errorNode: WorkflowNode
+): Partial<Workflow> {
+  const trigger = createWebhookNode({
+    name: 'Trigger',
+    position: [250, 300]
+  });
+
+  // Configure main node for error handling
+  const mainNodeWithError = {
+    ...mainNode,
+    continueOnFail: true,
+    onError: 'continueErrorOutput' as const
+  };
+
+  const connections: Record<string, any> = {
+    [trigger.name]: {
+      main: [[{ node: mainNode.name, type: 'main', index: 0 }]]
+    },
+    [mainNode.name]: {
+      error: [[{ node: errorNode.name, type: 'main', index: 0 }]]
+    }
+  };
+
+  return {
+    name: createTestWorkflowName(name),
+    nodes: [trigger, mainNodeWithError, errorNode],
+    connections,
+    settings: {
+      executionOrder: 'v1'
+    }
+  };
+}
+
+/**
+ * Create test workflow tags
+ *
+ * @param additional - Additional tags to include
+ * @returns Array of tags for test workflows
+ */
+export function createTestTags(additional: string[] = []): string[] {
+  return ['mcp-integration-test', ...additional];
+}
+
+/**
+ * Create workflow settings with common test configurations
+ *
+ * @param overrides - Settings to override
+ * @returns Workflow settings object
+ */
+export function createWorkflowSettings(overrides: Record<string, any> = {}): Record<string, any> {
+  return {
+    executionOrder: 'v1',
+    saveDataErrorExecution: 'all',
+    saveDataSuccessExecution: 'all',
+    saveManualExecutions: true,
+    ...overrides
+  };
+}

tests/integration/n8n-api/utils/fixtures.ts

@@ -0,0 +1,375 @@
+/**
+ * Workflow Fixtures for Integration Tests
+ *
+ * Provides reusable workflow templates for testing.
+ * All fixtures use FULL node type format (n8n-nodes-base.*)
+ * as required by the n8n API.
+ */
+
+import { Workflow, WorkflowNode } from '../../../../src/types/n8n-api';
+
+/**
+ * Simple webhook workflow with a single Webhook node
+ *
+ * Use this for basic workflow creation tests.
+ */
+export const SIMPLE_WEBHOOK_WORKFLOW: Partial<Workflow> = {
+  nodes: [
+    {
+      id: 'webhook-1',
+      name: 'Webhook',
+      type: 'n8n-nodes-base.webhook',
+      typeVersion: 2,
+      position: [250, 300],
+      parameters: {
+        httpMethod: 'GET',
+        path: 'test-webhook'
+      }
+    }
+  ],
+  connections: {},
+  settings: {
+    executionOrder: 'v1'
+  }
+};
+
+/**
+ * Simple HTTP request workflow
+ *
+ * Contains a Webhook trigger and an HTTP Request node.
+ * Tests basic workflow connections.
+ */
+export const SIMPLE_HTTP_WORKFLOW: Partial<Workflow> = {
+  nodes: [
+    {
+      id: 'webhook-1',
+      name: 'Webhook',
+      type: 'n8n-nodes-base.webhook',
+      typeVersion: 2,
+      position: [250, 300],
+      parameters: {
+        httpMethod: 'GET',
+        path: 'trigger'
+      }
+    },
+    {
+      id: 'http-1',
+      name: 'HTTP Request',
+      type: 'n8n-nodes-base.httpRequest',
+      typeVersion: 4.2,
+      position: [450, 300],
+      parameters: {
+        url: 'https://httpbin.org/get',
+        method: 'GET'
+      }
+    }
+  ],
+  connections: {
+    Webhook: {
+      main: [[{ node: 'HTTP Request', type: 'main', index: 0 }]]
+    }
+  },
+  settings: {
+    executionOrder: 'v1'
+  }
+};
+
+/**
+ * Multi-node workflow with branching
+ *
+ * Tests complex connections and multiple execution paths.
+ */
+export const MULTI_NODE_WORKFLOW: Partial<Workflow> = {
+  nodes: [
+    {
+      id: 'webhook-1',
+      name: 'Webhook',
+      type: 'n8n-nodes-base.webhook',
+      typeVersion: 2,
+      position: [250, 300],
+      parameters: {
+        httpMethod: 'POST',
+        path: 'multi-node'
+      }
+    },
+    {
+      id: 'set-1',
+      name: 'Set 1',
+      type: 'n8n-nodes-base.set',
+      typeVersion: 3.4,
+      position: [450, 200],
+      parameters: {
+        assignments: {
+          assignments: [
+            {
+              id: 'assign-1',
+              name: 'branch',
+              value: 'top',
+              type: 'string'
+            }
+          ]
+        },
+        options: {}
+      }
+    },
+    {
+      id: 'set-2',
+      name: 'Set 2',
+      type: 'n8n-nodes-base.set',
+      typeVersion: 3.4,
+      position: [450, 400],
+      parameters: {
+        assignments: {
+          assignments: [
+            {
+              id: 'assign-2',
+              name: 'branch',
+              value: 'bottom',
+              type: 'string'
+            }
+          ]
+        },
+        options: {}
+      }
+    },
+    {
+      id: 'merge-1',
+      name: 'Merge',
+      type: 'n8n-nodes-base.merge',
+      typeVersion: 3,
+      position: [650, 300],
+      parameters: {
+        mode: 'append',
+        options: {}
+      }
+    }
+  ],
+  connections: {
+    Webhook: {
+      main: [
+        [
+          { node: 'Set 1', type: 'main', index: 0 },
+          { node: 'Set 2', type: 'main', index: 0 }
+        ]
+      ]
+    },
+    'Set 1': {
+      main: [[{ node: 'Merge', type: 'main', index: 0 }]]
+    },
+    'Set 2': {
+      main: [[{ node: 'Merge', type: 'main', index: 1 }]]
+    }
+  },
+  settings: {
+    executionOrder: 'v1'
+  }
+};
+
+/**
+ * Workflow with error handling
+ *
+ * Tests error output configuration and error workflows.
+ */
+export const ERROR_HANDLING_WORKFLOW: Partial<Workflow> = {
+  nodes: [
+    {
+      id: 'webhook-1',
+      name: 'Webhook',
+      type: 'n8n-nodes-base.webhook',
+      typeVersion: 2,
+      position: [250, 300],
+      parameters: {
+        httpMethod: 'GET',
+        path: 'error-test'
+      }
+    },
+    {
+      id: 'http-1',
+      name: 'HTTP Request',
+      type: 'n8n-nodes-base.httpRequest',
+      typeVersion: 4.2,
+      position: [450, 300],
+      parameters: {
+        url: 'https://httpbin.org/status/500',
+        method: 'GET'
+      },
+      continueOnFail: true,
+      onError: 'continueErrorOutput'
+    },
+    {
+      id: 'set-error',
+      name: 'Handle Error',
+      type: 'n8n-nodes-base.set',
+      typeVersion: 3.4,
+      position: [650, 400],
+      parameters: {
+        assignments: {
+          assignments: [
+            {
+              id: 'error-assign',
+              name: 'error_handled',
+              value: 'true',
+              type: 'boolean'
+            }
+          ]
+        },
+        options: {}
+      }
+    }
+  ],
+  connections: {
+    Webhook: {
+      main: [[{ node: 'HTTP Request', type: 'main', index: 0 }]]
+    },
+    'HTTP Request': {
+      main: [[{ node: 'Handle Error', type: 'main', index: 0 }]],
+      error: [[{ node: 'Handle Error', type: 'main', index: 0 }]]
+    }
+  },
+  settings: {
+    executionOrder: 'v1'
+  }
+};
+
+/**
+ * AI Agent workflow (langchain nodes)
+ *
+ * Tests langchain node support.
+ */
+export const AI_AGENT_WORKFLOW: Partial<Workflow> = {
+  nodes: [
+    {
+      id: 'manual-1',
+      name: 'When clicking "Test workflow"',
+      type: 'n8n-nodes-base.manualTrigger',
+      typeVersion: 1,
+      position: [250, 300],
+      parameters: {}
+    },
+    {
+      id: 'agent-1',
+      name: 'AI Agent',
+      type: '@n8n/n8n-nodes-langchain.agent',
+      typeVersion: 1.7,
+      position: [450, 300],
+      parameters: {
+        promptType: 'define',
+        text: '={{ $json.input }}',
+        options: {}
+      }
+    }
+  ],
+  connections: {
+    'When clicking "Test workflow"': {
+      main: [[{ node: 'AI Agent', type: 'main', index: 0 }]]
+    }
+  },
+  settings: {
+    executionOrder: 'v1'
+  }
+};
+
+/**
+ * Workflow with n8n expressions
+ *
+ * Tests expression validation.
+ */
+export const EXPRESSION_WORKFLOW: Partial<Workflow> = {
+  nodes: [
+    {
+      id: 'manual-1',
+      name: 'Manual Trigger',
+      type: 'n8n-nodes-base.manualTrigger',
+      typeVersion: 1,
+      position: [250, 300],
+      parameters: {}
+    },
+    {
+      id: 'set-1',
+      name: 'Set Variables',
+      type: 'n8n-nodes-base.set',
+      typeVersion: 3.4,
+      position: [450, 300],
+      parameters: {
+        assignments: {
+          assignments: [
+            {
+              id: 'expr-1',
+              name: 'timestamp',
+              value: '={{ $now }}',
+              type: 'string'
+            },
+            {
+              id: 'expr-2',
+              name: 'item_count',
+              value: '={{ $json.items.length }}',
+              type: 'number'
+            },
+            {
+              id: 'expr-3',
+              name: 'first_item',
+              value: '={{ $node["Manual Trigger"].json }}',
+              type: 'object'
+            }
+          ]
+        },
+        options: {}
+      }
+    }
+  ],
+  connections: {
+    'Manual Trigger': {
+      main: [[{ node: 'Set Variables', type: 'main', index: 0 }]]
+    }
+  },
+  settings: {
+    executionOrder: 'v1'
+  }
+};
+
+/**
+ * Get a fixture by name
+ *
+ * @param name - Fixture name
+ * @returns Workflow fixture
+ */
+export function getFixture(
+  name:
+    | 'simple-webhook'
+    | 'simple-http'
+    | 'multi-node'
+    | 'error-handling'
+    | 'ai-agent'
+    | 'expression'
+): Partial<Workflow> {
+  const fixtures = {
+    'simple-webhook': SIMPLE_WEBHOOK_WORKFLOW,
+    'simple-http': SIMPLE_HTTP_WORKFLOW,
+    'multi-node': MULTI_NODE_WORKFLOW,
+    'error-handling': ERROR_HANDLING_WORKFLOW,
+    'ai-agent': AI_AGENT_WORKFLOW,
+    expression: EXPRESSION_WORKFLOW
+  };
+
+  return JSON.parse(JSON.stringify(fixtures[name])); // Deep clone
+}
+
+/**
+ * Create a minimal workflow with custom nodes
+ *
+ * @param nodes - Array of workflow nodes
+ * @param connections - Optional connections object
+ * @returns Workflow fixture
+ */
+export function createCustomWorkflow(
+  nodes: WorkflowNode[],
+  connections: Record<string, any> = {}
+): Partial<Workflow> {
+  return {
+    nodes,
+    connections,
+    settings: {
+      executionOrder: 'v1'
+    }
+  };
+}

tests/integration/n8n-api/utils/mcp-context.ts

@@ -0,0 +1,14 @@
+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
+  };
+}

tests/integration/n8n-api/utils/n8n-client.ts

@@ -0,0 +1,65 @@
+/**
+ * Pre-configured n8n API Client for Integration Tests
+ *
+ * Provides a singleton API client instance configured with test credentials.
+ * Automatically loads credentials from .env (local) or GitHub secrets (CI).
+ */
+
+import { N8nApiClient } from '../../../../src/services/n8n-api-client';
+import { getN8nCredentials, validateCredentials } from './credentials';
+
+let client: N8nApiClient | null = null;
+
+/**
+ * Get or create the test n8n API client
+ *
+ * Creates a singleton instance configured with credentials from
+ * the environment. Validates that required credentials are present.
+ *
+ * @returns Configured N8nApiClient instance
+ * @throws Error if credentials are missing or invalid
+ *
+ * @example
+ * const client = getTestN8nClient();
+ * const workflow = await client.createWorkflow({ ... });
+ */
+export function getTestN8nClient(): N8nApiClient {
+  if (!client) {
+    const creds = getN8nCredentials();
+    validateCredentials(creds);
+    client = new N8nApiClient({
+      baseUrl: creds.url,
+      apiKey: creds.apiKey,
+      timeout: 30000,
+      maxRetries: 3
+    });
+  }
+  return client;
+}
+
+/**
+ * Reset the test client instance
+ *
+ * Forces recreation of the client on next call to getTestN8nClient().
+ * Useful for testing or when credentials change.
+ */
+export function resetTestN8nClient(): void {
+  client = null;
+}
+
+/**
+ * Check if the n8n API is accessible
+ *
+ * Performs a health check to verify API connectivity.
+ *
+ * @returns true if API is accessible, false otherwise
+ */
+export async function isN8nApiAccessible(): Promise<boolean> {
+  try {
+    const client = getTestN8nClient();
+    await client.healthCheck();
+    return true;
+  } catch {
+    return false;
+  }
+}

tests/integration/n8n-api/utils/node-repository.ts

@@ -0,0 +1,65 @@
+/**
+ * Node Repository Utility for Integration Tests
+ *
+ * Provides a singleton NodeRepository instance for integration tests
+ * that require validation or autofix functionality.
+ */
+
+import path from 'path';
+import { createDatabaseAdapter, DatabaseAdapter } from '../../../../src/database/database-adapter';
+import { NodeRepository } from '../../../../src/database/node-repository';
+
+let repositoryInstance: NodeRepository | null = null;
+let dbInstance: DatabaseAdapter | null = null;
+
+/**
+ * Get or create NodeRepository instance
+ *
+ * Uses the production nodes.db database (data/nodes.db).
+ *
+ * @returns Singleton NodeRepository instance
+ * @throws {Error} If database file cannot be found or opened
+ *
+ * @example
+ * const repository = await getNodeRepository();
+ * const nodeInfo = await repository.getNodeByType('n8n-nodes-base.webhook');
+ */
+export async function getNodeRepository(): Promise<NodeRepository> {
+  if (repositoryInstance) {
+    return repositoryInstance;
+  }
+
+  const dbPath = path.join(process.cwd(), 'data/nodes.db');
+  dbInstance = await createDatabaseAdapter(dbPath);
+  repositoryInstance = new NodeRepository(dbInstance);
+
+  return repositoryInstance;
+}
+
+/**
+ * Close database and reset repository instance
+ *
+ * Should be called in test cleanup (afterAll) to prevent resource leaks.
+ * Properly closes the database connection and resets the singleton.
+ *
+ * @example
+ * afterAll(async () => {
+ *   await closeNodeRepository();
+ * });
+ */
+export async function closeNodeRepository(): Promise<void> {
+  if (dbInstance && typeof dbInstance.close === 'function') {
+    await dbInstance.close();
+  }
+  dbInstance = null;
+  repositoryInstance = null;
+}
+
+/**
+ * Reset repository instance (useful for test cleanup)
+ *
+ * @deprecated Use closeNodeRepository() instead to properly close database connections
+ */
+export function resetNodeRepository(): void {
+  repositoryInstance = null;
+}

tests/integration/n8n-api/utils/response-types.ts

@@ -0,0 +1,202 @@
+/**
+ * TypeScript interfaces for n8n API and MCP handler responses
+ * Used in integration tests to provide type safety
+ */
+
+// ======================================================================
+// System Tool Response Types
+// ======================================================================
+
+export interface HealthCheckResponse {
+  status: string;
+  instanceId?: string;
+  n8nVersion?: string;
+  features?: Record<string, any>;
+  apiUrl: string;
+  mcpVersion: string;
+  supportedN8nVersion?: string;
+  versionNote?: string;
+  [key: string]: any; // Allow dynamic property access for optional field checks
+}
+
+export interface ToolDefinition {
+  name: string;
+  description: string;
+}
+
+export interface ToolCategory {
+  category: string;
+  tools: ToolDefinition[];
+}
+
+export interface ApiConfiguration {
+  apiUrl: string;
+  timeout: number;
+  maxRetries: number;
+}
+
+export interface ListToolsResponse {
+  tools: ToolCategory[];
+  apiConfigured: boolean;
+  configuration?: ApiConfiguration | null;
+  limitations: string[];
+}
+
+export interface ApiStatus {
+  configured: boolean;
+  connected: boolean;
+  error?: string | null;
+  version?: string | null;
+}
+
+export interface ToolsAvailability {
+  documentationTools: {
+    count: number;
+    enabled: boolean;
+    description: string;
+  };
+  managementTools: {
+    count: number;
+    enabled: boolean;
+    description: string;
+  };
+  totalAvailable: number;
+}
+
+export interface DebugInfo {
+  processEnv: string[];
+  nodeVersion: string;
+  platform: string;
+  workingDirectory: string;
+}
+
+export interface DiagnosticResponse {
+  timestamp: string;
+  environment: {
+    N8N_API_URL: string | null;
+    N8N_API_KEY: string | null;
+    NODE_ENV: string;
+    MCP_MODE: string;
+  };
+  apiConfiguration: {
+    configured: boolean;
+    status: ApiStatus;
+    config?: {
+      baseUrl: string;
+      timeout: number;
+      maxRetries: number;
+    } | null;
+  };
+  toolsAvailability: ToolsAvailability;
+  troubleshooting: {
+    steps: string[];
+    documentation: string;
+  };
+  debug?: DebugInfo;
+  [key: string]: any; // Allow dynamic property access for optional field checks
+}
+
+// ======================================================================
+// Execution Response Types
+// ======================================================================
+
+export interface ExecutionData {
+  id: string;
+  status?: 'success' | 'error' | 'running' | 'waiting';
+  mode?: string;
+  startedAt?: string;
+  stoppedAt?: string;
+  workflowId?: string;
+  data?: any;
+}
+
+export interface ListExecutionsResponse {
+  executions: ExecutionData[];
+  returned: number;
+  nextCursor?: string;
+  hasMore: boolean;
+  _note?: string;
+}
+
+// ======================================================================
+// Workflow Response Types
+// ======================================================================
+
+export interface WorkflowNode {
+  id: string;
+  name: string;
+  type: string;
+  typeVersion: number;
+  position: [number, number];
+  parameters: Record<string, any>;
+  credentials?: Record<string, any>;
+  disabled?: boolean;
+}
+
+export interface WorkflowConnections {
+  [key: string]: any;
+}
+
+export interface WorkflowData {
+  id: string;
+  name: string;
+  active: boolean;
+  nodes: WorkflowNode[];
+  connections: WorkflowConnections;
+  settings?: Record<string, any>;
+  staticData?: Record<string, any>;
+  tags?: string[];
+  versionId?: string;
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+export interface ValidationError {
+  nodeId?: string;
+  nodeName?: string;
+  field?: string;
+  message: string;
+  type?: string;
+}
+
+export interface ValidationWarning {
+  nodeId?: string;
+  nodeName?: string;
+  message: string;
+  type?: string;
+}
+
+export interface ValidateWorkflowResponse {
+  valid: boolean;
+  errors?: ValidationError[];
+  warnings?: ValidationWarning[];
+  errorCount?: number;
+  warningCount?: number;
+  summary?: string;
+}
+
+export interface AutofixChange {
+  nodeId: string;
+  nodeName: string;
+  field: string;
+  oldValue: any;
+  newValue: any;
+  reason: string;
+}
+
+export interface AutofixSuggestion {
+  fixType: string;
+  nodeId: string;
+  nodeName: string;
+  description: string;
+  confidence: 'high' | 'medium' | 'low';
+  changes: AutofixChange[];
+}
+
+export interface AutofixResponse {
+  appliedFixes?: number;
+  suggestions?: AutofixSuggestion[];
+  workflow?: WorkflowData;
+  summary?: string;
+  preview?: boolean;
+}

tests/integration/n8n-api/utils/test-context.ts

@@ -0,0 +1,177 @@
+/**
+ * Test Context for Resource Tracking and Cleanup
+ *
+ * Tracks resources created during tests (workflows, executions) and
+ * provides automatic cleanup functionality.
+ */
+
+import { getTestN8nClient } from './n8n-client';
+import { getN8nCredentials } from './credentials';
+import { Logger } from '../../../../src/utils/logger';
+
+const logger = new Logger({ prefix: '[TestContext]' });
+
+export interface TestContext {
+  /** Workflow IDs created during the test */
+  workflowIds: string[];
+
+  /** Execution IDs created during the test */
+  executionIds: string[];
+
+  /** Clean up all tracked resources */
+  cleanup: () => Promise<void>;
+
+  /** Track a workflow for cleanup */
+  trackWorkflow: (id: string) => void;
+
+  /** Track an execution for cleanup */
+  trackExecution: (id: string) => void;
+
+  /** Remove a workflow from tracking (e.g., already deleted) */
+  untrackWorkflow: (id: string) => void;
+
+  /** Remove an execution from tracking (e.g., already deleted) */
+  untrackExecution: (id: string) => void;
+}
+
+/**
+ * Create a test context for tracking and cleaning up resources
+ *
+ * Use this in test setup to create a context that tracks all
+ * workflows and executions created during the test. Call cleanup()
+ * in afterEach or afterAll to remove test resources.
+ *
+ * @returns TestContext
+ *
+ * @example
+ * describe('Workflow tests', () => {
+ *   let context: TestContext;
+ *
+ *   beforeEach(() => {
+ *     context = createTestContext();
+ *   });
+ *
+ *   afterEach(async () => {
+ *     await context.cleanup();
+ *   });
+ *
+ *   it('creates a workflow', async () => {
+ *     const workflow = await client.createWorkflow({ ... });
+ *     context.trackWorkflow(workflow.id);
+ *     // Test runs, then cleanup() automatically deletes the workflow
+ *   });
+ * });
+ */
+export function createTestContext(): TestContext {
+  const context: TestContext = {
+    workflowIds: [],
+    executionIds: [],
+
+    trackWorkflow(id: string) {
+      if (!this.workflowIds.includes(id)) {
+        this.workflowIds.push(id);
+        logger.debug(`Tracking workflow for cleanup: ${id}`);
+      }
+    },
+
+    trackExecution(id: string) {
+      if (!this.executionIds.includes(id)) {
+        this.executionIds.push(id);
+        logger.debug(`Tracking execution for cleanup: ${id}`);
+      }
+    },
+
+    untrackWorkflow(id: string) {
+      const index = this.workflowIds.indexOf(id);
+      if (index > -1) {
+        this.workflowIds.splice(index, 1);
+        logger.debug(`Untracked workflow: ${id}`);
+      }
+    },
+
+    untrackExecution(id: string) {
+      const index = this.executionIds.indexOf(id);
+      if (index > -1) {
+        this.executionIds.splice(index, 1);
+        logger.debug(`Untracked execution: ${id}`);
+      }
+    },
+
+    async cleanup() {
+      const creds = getN8nCredentials();
+
+      // Skip cleanup if disabled
+      if (!creds.cleanup.enabled) {
+        logger.info('Cleanup disabled, skipping resource cleanup');
+        return;
+      }
+
+      const client = getTestN8nClient();
+
+      // Delete executions first (they reference workflows)
+      if (this.executionIds.length > 0) {
+        logger.info(`Cleaning up ${this.executionIds.length} execution(s)`);
+
+        for (const id of this.executionIds) {
+          try {
+            await client.deleteExecution(id);
+            logger.debug(`Deleted execution: ${id}`);
+          } catch (error) {
+            // Log but don't fail - execution might already be deleted
+            logger.warn(`Failed to delete execution ${id}:`, error);
+          }
+        }
+
+        this.executionIds = [];
+      }
+
+      // Then delete workflows
+      if (this.workflowIds.length > 0) {
+        logger.info(`Cleaning up ${this.workflowIds.length} workflow(s)`);
+
+        for (const id of this.workflowIds) {
+          try {
+            await client.deleteWorkflow(id);
+            logger.debug(`Deleted workflow: ${id}`);
+          } catch (error) {
+            // Log but don't fail - workflow might already be deleted
+            logger.warn(`Failed to delete workflow ${id}:`, error);
+          }
+        }
+
+        this.workflowIds = [];
+      }
+    }
+  };
+
+  return context;
+}
+
+/**
+ * Create a test workflow name with prefix and timestamp
+ *
+ * Generates a unique workflow name for testing that follows
+ * the configured naming convention.
+ *
+ * @param baseName - Base name for the workflow
+ * @returns Prefixed workflow name with timestamp
+ *
+ * @example
+ * const name = createTestWorkflowName('Simple HTTP Request');
+ * // Returns: "[MCP-TEST] Simple HTTP Request 1704067200000"
+ */
+export function createTestWorkflowName(baseName: string): string {
+  const creds = getN8nCredentials();
+  const timestamp = Date.now();
+  return `${creds.cleanup.namePrefix} ${baseName} ${timestamp}`;
+}
+
+/**
+ * Get the configured test tag
+ *
+ * @returns Tag to apply to test workflows
+ */
+export function getTestTag(): string {
+  const creds = getN8nCredentials();
+  return creds.cleanup.tag;
+}