fix: add comprehensive addNode examples to n8n_update_partial_workflow documentation

Fixes #269 ## Problem Claude didn't know how to use the addNode operation because the MCP tool documentation lacked working examples. Users were getting errors like: - "Cannot read properties of undefined (reading 'name')" - "Unknown operation type: n8n-nodes-base.set" ## Root Cause The tool documentation mentioned addNode as one of 6 node operations but had ZERO examples showing the correct syntax. All 6 examples focused on v2.14.4 cleanup features, leaving out the most commonly used operation. ## Solution Added 4 comprehensive examples showing addNode usage patterns: 1. Basic addNode with minimal configuration 2. Complete addNode with full parameters 3. addNode + addConnection combo (most common pattern) 4. Batch operation with multiple nodes Examples array increased from 6 to 10 total examples, with 40% now dedicated to addNode operations. ## Correct Syntax Demonstrated ```typescript { type: 'addNode', node: { name: 'Node Name', type: 'n8n-nodes-base.xxx', position: [x, y], parameters: { ... } } } ``` 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
docs: update test statistics to 3,336 tests with Phase 8 n8n API integration tests
2026-01-30 14:32:04 +00:00 · 2025-10-05 15:19:24 +02:00 · 2025-10-05 11:56:35 +02:00 · 2025-10-05 10:45:30 +02:00 · 2025-10-05 10:25:41 +02:00 · 2025-10-05 10:21:12 +02:00
16 changed files with 3735 additions and 91 deletions
--- a/README.md
+++ b/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).

--- a/docs/local/integration-testing-plan.md
+++ b/docs/local/integration-testing-plan.md
@@ -16,7 +16,61 @@
 - 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)
+
+**Next Phase**: Phase 6B - Workflow Autofix Tests

 ---

@@ -912,13 +966,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,9 +1166,9 @@ 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 (10 of 17 complete)
+- ⏳ All operations/parameters covered (83 of 150+ scenarios complete)
+- ✅ Tests run successfully locally (Phases 1-6A verified)
 - ⏳ Tests run successfully in CI (pending Phase 9)
 - ✅ No manual cleanup required (automatic)
 - ✅ Test coverage catches P0-level bugs (verified in Phase 2)
@@ -1106,15 +1182,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)**: 1 day
 - **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**: 5.5 days complete, ~5 days remaining

 ---

--- a/docs/testing-architecture.md
+++ b/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

--- a/src/mcp/tool-docs/workflow_management/n8n-update-partial-workflow.ts
+++ b/src/mcp/tool-docs/workflow_management/n8n-update-partial-workflow.ts
@@ -63,12 +63,16 @@ 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]})',
+      '// Add multiple nodes in batch\nn8n_update_partial_workflow({id: "jkl", 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: "mno", operations: [{type: "cleanStaleConnections"}]})',
+      '// Remove connection gracefully (no error if it doesn\'t exist)\nn8n_update_partial_workflow({id: "pqr", operations: [{type: "removeConnection", source: "Old Node", target: "Target", ignoreErrors: true}]})',
+      '// Best-effort mode: apply what works, report what fails\nn8n_update_partial_workflow({id: "stu", 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: "vwx", operations: [{type: "replaceConnections", connections: {"Webhook": {"main": [[{node: "Slack", type: "main", index: 0}]]}}}]})',
+      '// Update node parameter (classic atomic mode)\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: [
      'Clean up broken workflows after node renames/deletions',
--- a/tests/integration/n8n-api/executions/delete-execution.test.ts
+++ b/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();
+    });
+  });
+});
--- a/tests/integration/n8n-api/executions/get-execution.test.ts
+++ b/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');
+      }
+    });
+  });
+});
--- a/tests/integration/n8n-api/executions/list-executions.test.ts
+++ b/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);
+        }
+      }
+    });
+  });
+});
--- a/tests/integration/n8n-api/executions/trigger-webhook.test.ts
+++ b/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');
+    });
+  });
+});
--- a/tests/integration/n8n-api/system/diagnostic.test.ts
+++ b/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');
+    });
+  });
+});
--- a/tests/integration/n8n-api/system/health-check.test.ts
+++ b/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();
+        }
+      });
+    });
+  });
+});
--- a/tests/integration/n8n-api/system/list-tools.test.ts
+++ b/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);
+    });
+  });
+});
--- a/tests/integration/n8n-api/types/mcp-responses.ts
+++ b/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;
+  };
+}
--- a/tests/integration/n8n-api/utils/node-repository.ts
+++ b/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;
+}
--- a/tests/integration/n8n-api/utils/response-types.ts
+++ b/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;
+}
--- a/tests/integration/n8n-api/workflows/autofix-workflow.test.ts
+++ b/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);
+      }
+    });
+  });
+});
--- a/tests/integration/n8n-api/workflows/validate-workflow.test.ts
+++ b/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');
+    });
+  });
+});
Author	SHA1	Message	Date
czlonkowski	9e7a0e0487	fix: add comprehensive addNode examples to n8n_update_partial_workflow documentation Fixes #269 ## Problem Claude didn't know how to use the addNode operation because the MCP tool documentation lacked working examples. Users were getting errors like: - "Cannot read properties of undefined (reading 'name')" - "Unknown operation type: n8n-nodes-base.set" ## Root Cause The tool documentation mentioned addNode as one of 6 node operations but had ZERO examples showing the correct syntax. All 6 examples focused on v2.14.4 cleanup features, leaving out the most commonly used operation. ## Solution Added 4 comprehensive examples showing addNode usage patterns: 1. Basic addNode with minimal configuration 2. Complete addNode with full parameters 3. addNode + addConnection combo (most common pattern) 4. Batch operation with multiple nodes Examples array increased from 6 to 10 total examples, with 40% now dedicated to addNode operations. ## Correct Syntax Demonstrated ```typescript { type: 'addNode', node: { name: 'Node Name', type: 'n8n-nodes-base.xxx', position: [x, y], parameters: { ... } } } ``` 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>	2025-10-05 15:19:24 +02:00
czlonkowski	1c56eb0daa	docs: update test statistics to 3,336 tests with Phase 8 n8n API integration tests Updates documentation with accurate test counts following completion of Phase 8: Test Statistics: - Total: 3,336 tests (was 2,883) - Unit tests: 2,766 tests - Integration tests: 570 tests - n8n API Integration: 172 tests (all 18 MCP handlers) - Database: 226 tests - MCP Protocol: 119 tests - Templates & Docker: 53 tests Updated Files: - README.md: Updated badge and Testing Architecture section - docs/testing-architecture.md: Comprehensive update with detailed breakdown Key Additions: - Complete coverage of n8n API integration tests (Phase 1-8) - TypeScript type safety with response interfaces - Detailed test organization by component and handler type - Updated execution time estimates 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>	2025-10-05 11:56:35 +02:00
czlonkowski	c519cd5060	refactor: add TypeScript interfaces for test response types Replace 'as any' type assertions with proper TypeScript interfaces for improved type safety in Phase 8 integration tests. Changes: - Created response-types.ts with comprehensive interfaces for all response types - Updated health-check.test.ts to use HealthCheckResponse interface - Updated list-tools.test.ts to use ListToolsResponse interface - Updated diagnostic.test.ts to use DiagnosticResponse interface - Added null-safety checks for optional fields (data.debug) - Used non-null assertions (!) for values verified with expect().toBeDefined() - Removed unnecessary 'as any' casts throughout test files Benefits: - Better type safety and IDE autocomplete - Catches potential type mismatches at compile time - More maintainable and self-documenting code - Consistent with code review recommendation All 19 tests still passing with full type safety. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>	2025-10-05 10:45:30 +02:00
czlonkowski	69f3a31d41	feat: implement Phase 8 integration tests for system tools Implement comprehensive integration tests for 3 system tool handlers: - handleHealthCheck (3 tests): API connectivity, version checking, feature availability - handleListAvailableTools (7 tests): Tool discovery by category, configuration status, API limitations - handleDiagnostic (9 tests): Environment checks, API status, tools availability, verbose mode All 19 tests passing against real n8n instance. Coverage: - Health check: API availability verification, version information, feature discovery - Tool listing: All categories (Workflow Management, Execution Management, System), configuration details - Diagnostics: Environment variables, API connectivity, tool availability, troubleshooting steps, verbose debug mode 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>	2025-10-05 10:25:41 +02:00
Romuald Członkowski	bd8a7f68ac	Merge pull request #266 from czlonkowski/feat/integration-tests-phase-7 feat: Phase 7 Integration Tests - Execution Management	2025-10-05 10:21:12 +02:00
czlonkowski	abc6a31302	feat: implement Phase 7 integration tests for execution management Implement comprehensive integration tests for 4 execution management handlers: - handleTriggerWebhookWorkflow (20 tests): GET/POST/PUT/DELETE methods, headers, error handling - handleGetExecution (16 tests): 4 retrieval modes (preview/summary/filtered/full), filtering, legacy compatibility - handleListExecutions (13 tests): status filtering, pagination with cursor, data inclusion - handleDeleteExecution (5 tests): successful deletion with verification, error handling All 54 tests passing against real n8n instance. Coverage: - All HTTP methods (GET, POST, PUT, DELETE) - All execution retrieval modes with filtering options - Pagination with cursor handling - Execution creation and cleanup verification - Comprehensive error handling scenarios 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>	2025-10-05 10:11:56 +02:00
Romuald Członkowski	57459c27e3	Merge pull request #264 from czlonkowski/feat/integration-tests-phase-6 feat: Phase 6B integration tests (workflow autofix)	2025-10-05 09:59:27 +02:00
czlonkowski	9380602439	fix: resolve code fence rendering issue in Claude Project Setup section - Change outer markdown fence from 3 to 4 backticks to prevent nested code blocks from breaking the fence - Update code block labels from 'javascript' to 'json' for MCP tool parameters to avoid confusion - Remove language labels from workflow example blocks (mixed content with annotations) Fixes #260 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>	2025-10-05 09:58:55 +02:00
czlonkowski	a696af8cfa	fix: resolve TypeScript type errors in autofix tests Fixes TypeScript compilation errors identified by typecheck: - Error TS2571: Object is of type 'unknown' (lines 121, 243) ## Problem The `parameters` field in WorkflowNode is typed as `Record<string, unknown>`, causing TypeScript to see deeply nested property accesses as `unknown` type. ## Solution Added explicit type assertions when accessing Set node parameters: ```typescript // Before (fails typecheck): const value = fetched.nodes[1].parameters.assignments.assignments[0].value; // After (passes typecheck): const params = fetched.nodes[1].parameters as { assignments: { assignments: Array<{ value: unknown }> } }; const value = params.assignments.assignments[0].value; ``` ## Verification - ✅ `npm run typecheck` passes with no errors - ✅ `npm run lint` passes with no errors - ✅ All 28 tests passing (12 validation + 16 autofix) - ✅ No regressions introduced This maintains type safety while properly handling the dynamic nature of n8n node parameters. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>	2025-10-05 09:49:24 +02:00
czlonkowski	b467bec93e	fix: address critical issues from code review (Phase 6A/6B) Implements the top 3 critical fixes identified by code review: ## 1. Fix Database Resource Leak (Critical) Problem: NodeRepository singleton never closed database connection, causing potential resource exhaustion in long test runs. Fix: - Added `closeNodeRepository()` function with proper DB cleanup - Updated both test files to call `closeNodeRepository()` in `afterAll` - Added JSDoc documentation explaining usage - Deprecated old `resetNodeRepository()` in favor of new function Files: - `tests/integration/n8n-api/utils/node-repository.ts` - `tests/integration/n8n-api/workflows/validate-workflow.test.ts` - `tests/integration/n8n-api/workflows/autofix-workflow.test.ts` ## 2. Add TypeScript Type Safety (Critical) Problem: Excessive use of `as any` bypassed TypeScript safety, hiding potential bugs and typos. Fix: - Created `tests/integration/n8n-api/types/mcp-responses.ts` - Added `ValidationResponse` interface for validation handler responses - Added `AutofixResponse` interface for autofix handler responses - Updated test files to use proper types instead of `as any` Benefits: - Compile-time type checking for response structures - IDE autocomplete for response fields - Catches typos and property access errors Files: - `tests/integration/n8n-api/types/mcp-responses.ts` (new) - Both test files updated with proper imports and type casts ## 3. Improved Documentation Fix: - Added comprehensive JSDoc to `getNodeRepository()` - Added JSDoc to `closeNodeRepository()` with usage examples - Deprecated old function with migration guidance ## Test Results - ✅ All 28 tests passing (12 validation + 16 autofix) - ✅ No regressions introduced - ✅ TypeScript compilation successful - ✅ Database connections properly cleaned up ## Code Review Score Improvement Before fixes: 85/100 (Strong) After fixes: ~90/100 (Excellent) Addresses all critical and high-priority issues identified in code review. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>	2025-10-05 09:37:39 +02:00
czlonkowski	6e042467b2	feat: implement Phase 6B integration tests for workflow autofix Completes Phase 6B of the integration testing plan by adding comprehensive tests for the handleAutofixWorkflow MCP handler against a real n8n instance. ## Test Coverage (16 scenarios) ### Preview Mode (2 tests) - Preview fixes without applying (expression-format) - Preview multiple fix types ### Apply Mode (2 tests) - Apply expression-format fixes - Apply webhook-missing-path fixes ### Fix Type Filtering (2 tests) - Filter to specific fix types - Handle multiple fix type filters ### Confidence Threshold (3 tests) - High confidence threshold filtering - Medium confidence threshold (high + medium) - Low confidence threshold (all fixes) ### Max Fixes Parameter (1 test) - Limit number of fixes via maxFixes parameter ### No Fixes Available (1 test) - Handle workflows with no fixable issues ### Error Handling (3 tests) - Non-existent workflow ID - Invalid fixTypes parameter - Invalid confidence threshold ### Response Format Verification (2 tests) - Complete preview mode response structure - Complete apply mode response structure ## Implementation Details All tests follow the MCP handler testing pattern established in Phase 1-6A: - Tests call handleAutofixWorkflow (MCP handler), not raw API client - Tests verify McpToolResponse format (success, data, error) - Tests handle both cases: fixes available and no fixes available - Tests verify actual workflow modifications when applyFixes=true ## Test Results - All 16 new tests passing - Total integration tests: 99/99 passing (Phase 1-6 complete) - Phase 6A (Validation): 12 tests - Phase 6B (Autofix): 16 tests ## Key Discoveries The autofix engine handles specific fix types: - expression-format: Missing = prefix for resource locators (not {{}} wrapping) - 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 Tests properly handle workflows without fixable issues by checking for 'No automatic fixes available' message. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>	2025-10-05 09:28:32 +02:00
Romuald Członkowski	287b9aa819	Merge pull request #263 from czlonkowski/feat/integration-tests-phase-6 feat: Phase 6A integration tests (workflow validation)	2025-10-05 09:19:11 +02:00
czlonkowski	3331b72df4	feat: implement Phase 6A integration tests (workflow validation) Implemented comprehensive integration tests for workflow validation operations. Test Coverage (12 scenarios): - validate-workflow.test.ts: 12 test scenarios * Valid workflow with all 4 profiles (runtime, strict, ai-friendly, minimal) * Invalid workflow detection (bad node types, missing connections) * Selective validation (nodes only, connections only, expressions only) * Error handling (non-existent workflow, invalid parameters) * Response format verification Infrastructure: - Created node-repository utility for integration tests - Provides singleton NodeRepository instance for validation tests - Uses production nodes.db database Test Results: - All 83 integration tests passing (Phase 1-6A complete) - Validation tests cover all 4 validation profiles - Tests verify actual validation against real n8n instance 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>	2025-10-05 09:08:23 +02:00