* feat: add structural hashes and success tracking for workflow mutations
Enables cross-referencing workflow_mutations with telemetry_workflows by adding structural hashes (nodeTypes + connections) alongside existing full hashes.
**Database Changes:**
- Added workflow_structure_hash_before/after columns
- Added is_truly_successful computed column
- Created 3 analytics views: successful_mutations, mutation_training_data, mutations_with_workflow_quality
- Created 2 helper functions: get_mutation_success_rate_by_intent(), get_mutation_crossref_stats()
**Code Changes:**
- Updated mutation-tracker.ts to generate both hash types
- Updated mutation-types.ts with new fields
- Auto-converts to snake_case via existing toSnakeCase() function
**Testing:**
- Added 5 new unit tests for structural hash generation
- All 17 tests passing
**Tooling:**
- Created backfill script to populate hashes for existing 1,499 mutations
- Created comprehensive documentation (STRUCTURAL_HASHES.md)
**Impact:**
- Before: 0% cross-reference match rate
- After: Expected 60-70% match rate (post-backfill)
- Unlocks quality impact analysis, training data curation, and mutation pattern insights
Conceived by Romuald Członkowski - www.aiadvisors.pl/en
* fix: correct test operation types for structural hash tests
Fixed TypeScript errors in mutation-tracker tests by adding required
'updates' parameter to updateNode operations. Used 'as any' for test
operations to maintain backward compatibility while tests are updated.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
* chore: remove documentation files from tracking
Removed internal documentation files from version control:
- Telemetry implementation docs
- Implementation roadmap
- Disabled tools analysis docs
These files are for internal reference only.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
* chore: remove telemetry documentation files from tracking
Removed all telemetry analysis and documentation files from root directory.
These files are for internal reference only and should not be in version control.
Files removed:
- TELEMETRY_ANALYSIS*.md
- TELEMETRY_MUTATION_SPEC.md
- TELEMETRY_*_DATASET.md
- VALIDATION_ANALYSIS*.md
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
* chore: bump version to 2.22.18 and update CHANGELOG
Version 2.22.18 adds structural hash tracking for workflow mutations,
enabling cross-referencing with workflow quality data and automated
success detection.
Key changes:
- Added workflowStructureHashBefore/After fields
- Added isTrulySuccessful computed field
- Enhanced mutation tracking with structural hashes
- All tests passing (17/17)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
* chore: remove migration and documentation files from PR
Removed internal database migration files and documentation from
version control:
- docs/migrations/
- docs/telemetry/
Updated CHANGELOG to remove database migration references.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
* feat: add comprehensive telemetry for partial workflow updates
Implement telemetry infrastructure to track workflow mutations from
partial update operations. This enables data-driven improvements to
partial update tooling by capturing:
- Workflow state before and after mutations
- User intent and operation patterns
- Validation results and improvements
- Change metrics (nodes/connections modified)
- Success/failure rates and error patterns
New Components:
- Intent classifier: Categorizes mutation patterns
- Intent sanitizer: Removes PII from user instructions
- Mutation validator: Ensures data quality before tracking
- Mutation tracker: Coordinates validation and metric calculation
Extended Components:
- TelemetryManager: New trackWorkflowMutation() method
- EventTracker: Mutation queue management
- BatchProcessor: Mutation data flushing to Supabase
MCP Tool Enhancements:
- n8n_update_partial_workflow: Added optional 'intent' parameter
- n8n_update_full_workflow: Added optional 'intent' parameter
- Both tools now track mutations asynchronously
Database Schema:
- New workflow_mutations table with 20+ fields
- Comprehensive indexes for efficient querying
- Supports deduplication and data analysis
This telemetry system is:
- Privacy-focused (PII sanitization, anonymized users)
- Non-blocking (async tracking, silent failures)
- Production-ready (batching, retries, circuit breaker)
- Backward compatible (all parameters optional)
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
* fix: correct SQL syntax for expression index in workflow_mutations schema
The expression index for significant changes needs double parentheses
around the arithmetic expression to be valid PostgreSQL syntax.
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
* fix: enable RLS policies for workflow_mutations table
Enable Row-Level Security and add policies:
- Allow anonymous (anon) inserts for telemetry data collection
- Allow authenticated reads for data analysis and querying
These policies are required for the telemetry system to function
correctly with Supabase, as the MCP server uses the anon key to
insert mutation data.
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
* fix: reduce mutation auto-flush threshold from 5 to 2
Lower the auto-flush threshold for workflow mutations from 5 to 2 to ensure
more timely data persistence. Since mutations are less frequent than regular
telemetry events, a lower threshold provides:
- Faster data persistence (don't wait for 5 mutations)
- Better testing experience (easier to verify with fewer operations)
- Reduced risk of data loss if process exits before threshold
- More responsive telemetry for low-volume mutation scenarios
This complements the existing 5-second periodic flush and process exit
handlers, ensuring mutations are persisted promptly.
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
* fix: improve mutation telemetry error logging and diagnostics
Changes:
- Upgrade error logging from debug to warn level for better visibility
- Add diagnostic logging to track mutation processing
- Log telemetry disabled state explicitly
- Add context info (sessionId, intent, operationCount) to error logs
- Remove 'await' from telemetry calls to make them truly non-blocking
This will help identify why mutations aren't being persisted to the
workflow_mutations table despite successful workflow operations.
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
* feat: enhance workflow mutation telemetry for better AI responses
Improve workflow mutation tracking to capture comprehensive data that helps provide better responses when users update workflows. This enhancement collects workflow state, user intent, and operation details to enable more context-aware assistance.
Key improvements:
- Reduce auto-flush threshold from 5 to 2 for more reliable mutation tracking
- Add comprehensive workflow and credential sanitization to mutation tracker
- Document intent parameter in workflow update tools for better UX
- Fix mutation queue handling in telemetry manager (flush now handles 3 queues)
- Add extensive unit tests for mutation tracking and validation (35 new tests)
Technical changes:
- mutation-tracker.ts: Multi-layer sanitization (workflow, node, parameter levels)
- batch-processor.ts: Support mutation data flushing to Supabase
- telemetry-manager.ts: Auto-flush mutations at threshold 2, track mutations queue
- handlers-workflow-diff.ts: Track workflow mutations with sanitized data
- Tests: 13 tests for mutation-tracker, 22 tests for mutation-validator
The intent parameter messaging emphasizes user benefit ("helps to return better response") rather than technical implementation details.
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* chore: bump version to 2.22.16 with telemetry changelog
Updated package.json and package.runtime.json to version 2.22.16.
Added comprehensive CHANGELOG entry documenting workflow mutation
telemetry enhancements for better AI-powered workflow assistance.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
Co-Authored-By: Claude <noreply@anthropic.com>
* fix: resolve TypeScript lint errors in telemetry tests
Fixed type issues in mutation-tracker and mutation-validator tests:
- Import and use MutationToolName enum instead of string literals
- Fix ValidationResult.errors to use proper object structure
- Add UpdateNodeOperation type assertion for operation with nodeName
All TypeScript errors resolved, lint now passes.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
Add tests for two critical features identified by code review:
1. 10KB Safety Limit Test:
- Verify DISABLED_TOOLS environment variable is truncated at 10KB
- Test with 15KB input to ensure truncation works
- Confirm first tools are parsed, last tools are excluded
- Prevents DoS attacks from massive environment variables
2. Security Information Disclosure Test:
- Verify error messages only reveal attempted tool name
- Ensure full list of disabled tools is NOT leaked
- Critical security test to prevent configuration disclosure
- Tests defense against information leakage attacks
Test Coverage:
- Total tests: 47 (up from 45)
- Both tests passing
- Addresses critical gaps from code review
Files Modified:
- tests/unit/mcp/disabled-tools-additional.test.ts
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Performance Optimization:
- Add caching to getDisabledTools() to prevent 3x parsing per request
- Cache result as instance property disabledToolsCache
- Reduces overhead from 3x to 1x per server instance
Security Improvements:
- Fix information disclosure in error responses
- Only reveal the attempted tool name, not full list of disabled tools
- Prevents leaking security configuration details
Safety Limits:
- Add 10KB maximum length for DISABLED_TOOLS environment variable
- Add 200-tool maximum limit to prevent abuse
- Include warnings when limits are exceeded
Code Quality:
- Add clarifying comment for defense-in-depth guard in executeTool()
- Change logging level from info to debug for frequent operations
- Add comprehensive JSDoc to TestableN8NMCPServer test classes
- Document test wrapper pattern and exposed methods
Test Updates:
- Update test to verify 200-tool safety limit enforcement
- All 45 tests passing with improved coverage
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
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.
## Implementation
- Added getDisabledTools() method to parse comma-separated tool names from env var
- Modified ListToolsRequestSchema handler to filter both documentation and management tools
- Modified CallToolRequestSchema handler to reject disabled tool calls with clear error messages
- Added defense-in-depth guard in executeTool() method
## Features
- Environment variable format: DISABLED_TOOLS=tool1,tool2,tool3
- O(1) lookup performance using Set data structure
- Clear error messages with TOOL_DISABLED code
- Backward compatible (no DISABLED_TOOLS = all tools enabled)
- Comprehensive logging for observability
## Use Cases
- Multi-tenant: Hide tools that check global env vars
- Security: Disable management tools in production
- Feature flags: Gradually roll out new tools
- Deployment-specific: Different tool sets for cloud vs self-hosted
## Testing
- 45 comprehensive tests (all passing)
- 95% feature code coverage
- Unit tests + additional test scenarios
- Performance tested with 1000 tools (<100ms)
## Files Modified
- src/mcp/server.ts - Core implementation (~40 lines)
- .env.example, .env.docker - Configuration documentation
- tests/unit/mcp/disabled-tools*.test.ts - Comprehensive tests
- package.json, package.runtime.json - Version bump to 2.22.14
- CHANGELOG.md - Full documentation
Resolves#410
Conceived by Romuald Członkowski - www.aiadvisors.pl/en
Fixed critical bug where AI Agent validator never executed, missing 179 configuration errors (30% of all telemetry-identified failures).
The Bug:
- Switch case checked for '@n8n/n8n-nodes-langchain.agent' (full package format)
- But nodeType was normalized to 'nodes-langchain.agent' before reaching switch
- Result: AI Agent validator never matched, never executed
The Fix:
- Changed case to 'nodes-langchain.agent' to match normalized format
- Now correctly catches prompt configuration, maxIterations, error handling issues
Files Changed:
- src/services/enhanced-config-validator.ts:322 - Fixed nodeType format
- tests/unit/services/enhanced-config-validator.test.ts - Added validateAIAgent to mock and verification test
- CHANGELOG.md - Added bug fix section to 2.22.13 (not separate version)
Testing:
- npm test -- tests/unit/services/enhanced-config-validator.test.ts
- ✓ All 51 tests pass including new AI Agent validation test
Discovery:
Discovered by n8n-mcp-tester agent during post-deployment verification of 2.22.13 improvements. The agent attempted to validate an AI Agent node configuration and discovered the validator was never being called.
Impact:
- Without fix: 179 AI Agent configuration errors (30%) go undetected
- With fix: All AI Agent validation rules now execute correctly
Version: 2.22.13 (kept under same version as original implementation)
Concieved by Romuald Członkowski - www.aiadvisors.pl/en
Fixed TypeScript linting errors in workflow-diff-engine.test.ts by adding
typeVersion: 1 to all test nodes that were missing it.
Fixes CI linting failures in Test Suite workflow.
Conceived by Romuald Członkowski - www.aiadvisors.pl/en
After implementing workflow activation/deactivation operations, the
"Cannot activate" limitation no longer applies. Updated the test to
match the current API capabilities.
Related to #399🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Conceived by Romuald Członkowski - www.aiadvisors.pl/en
The workflow activation/deactivation implementation added two new fields
to the response details object (active and warnings). Updated test
expectations to match the new response format.
Fixes CI test failures in handlers-workflow-diff.test.ts
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Conceived by Romuald Członkowski - www.aiadvisors.pl/en
Implements workflow activation and deactivation as diff operations in
n8n_update_partial_workflow tool, following the pattern of other
configuration operations.
Changes:
- Add activateWorkflow/deactivateWorkflow API methods
- Add operation types to diff engine
- Update tool documentation
- Remove activation limitation
Resolves#399
Credits: ArtemisAI, cmj-hub for investigation and initial implementation
Conceived by Romuald Członkowski - www.aiadvisors.pl/en
Fixed critical startup crash when server falls back to sql.js adapter
due to Node.js version mismatches.
Problem:
- better-sqlite3 fails to load when Node runtime version differs from build version
- Server falls back to sql.js (pure JS, no native dependencies)
- Database health check crashed with "no such module: fts5"
- Server exits immediately, preventing Claude Desktop connection
Solution:
- Wrapped FTS5 health check in try-catch block
- Logs warning when FTS5 not available
- Server continues with fallback search (LIKE queries)
- Graceful degradation: works with any Node.js version
Impact:
- Server now starts successfully with sql.js fallback
- Works with Node v20 (Claude Desktop) even when built with Node v22
- Clear warnings about FTS5 unavailability
- Users can choose: sql.js (slower, works everywhere) or rebuild better-sqlite3 (faster)
Files Changed:
- src/mcp/server.ts: Added try-catch around FTS5 health check (lines 299-317)
Testing:
- ✅ Tested with Node v20.17.0 (Claude Desktop)
- ✅ Tested with Node v22.17.0 (build version)
- ✅ All 6 startup checkpoints pass
- ✅ Database health check passes with warning
Fixes: Claude Desktop connection failures with Node.js version mismatches
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
* chore: bump version to 2.22.9
Updated version number to trigger release workflow after n8n 1.118.1 update.
Previous version 2.22.8 was already released on 2025-10-28, so the release
workflow did not trigger when PR #393 was merged.
Changes:
- Bump package.json version from 2.22.8 to 2.22.9
- Update CHANGELOG.md with correct version and date
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* docs: update n8n update workflow with lessons learned
Added new fast workflow section based on 2025-11-04 update experience:
- CRITICAL: Check existing releases first to avoid version conflicts
- Skip local tests - CI runs them anyway (saves 2-3 min)
- Integration test failures with 'unauthorized' are infrastructure issues
- Release workflow only triggers on version CHANGE
- Updated time estimates for fast vs full workflow
This will make future n8n updates smoother and faster.
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* fix: exclude versionCounter from workflow updates for n8n 1.118.1
n8n 1.118.1 returns versionCounter in GET /workflows/{id} responses but
rejects it in PUT /workflows/{id} updates with the error:
'request/body must NOT have additional properties'
This was causing all integration tests to fail in CI with n8n 1.118.1.
Changes:
- Added versionCounter to excluded properties in cleanWorkflowForUpdate()
- Tested and verified fix works with n8n 1.118.1 test instance
Fixes CI failures in PR #395
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* chore: improve versionCounter fix with types and tests
- Add versionCounter type definition to Workflow and WorkflowExport interfaces
- Add comprehensive test coverage for versionCounter exclusion
- Update CHANGELOG with detailed bug fix documentation
Addresses code review feedback from PR #395
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
---------
Co-authored-by: Claude <noreply@anthropic.com>
- Updated n8n from 1.117.2 to 1.118.1
- Updated n8n-core from 1.116.0 to 1.117.0
- Updated n8n-workflow from 1.114.0 to 1.115.0
- Updated @n8n/n8n-nodes-langchain from 1.116.2 to 1.117.0
- Rebuilt node database with 542 nodes (439 from n8n-nodes-base, 103 from @n8n/n8n-nodes-langchain)
- Updated README badge with new n8n version
- Updated CHANGELOG with dependency changes
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude <noreply@anthropic.com>
* Update CLAUDE_CODE_SETUP.md
docs: Improve CLI setup for PowerShell and scope management
This commit introduces two improvements to the CLAUDE_CODE_SETUP.md documentation to enhance user experience, particularly for Windows users and those managing configuration scopes.
1. Add PowerShell-Compatible Commands:
The original `claude mcp add` commands use a syntax that fails in native Windows PowerShell due to its parameter parsing. This change adds dedicated code blocks for PowerShell, which correctly wrap the `-e` arguments in single quotes.
2. Clarify Configuration Scope Management:
The documentation previously lacked guidance on the default configuration scope and how to switch to a `project` scope. A new "Tips" section has been added to:
- Explain the default scope and the purpose of `--scope project`.
- Provide a clear, recommended CLI method for switching scopes.
- Offer an advanced, manual method by editing the `.claude.json` file.
* Update CLAUDE_CODE_SETUP.md again
Fixes#376
Without this environment variable, Claude Desktop shows JSON parsing errors
because debug logs contaminate the JSON-RPC stdout channel.
Added prominent warning to Quick Start section explaining:
- Why MCP_MODE=stdio is required
- What happens without it (JSON parse errors)
- How it prevents the issue (suppresses console output)
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
Co-authored-by: Claude Code Assistant <noreply@anthropic.com>
* docs: add comprehensive documentation for removing node properties with undefined
Add detailed documentation section for property removal pattern in n8n_update_partial_workflow tool:
- New "Removing Properties with undefined" section explaining the pattern
- Examples showing basic, nested, and batch property removal
- Migration guide for deprecated properties (continueOnFail → onError)
- Best practices for when to use undefined
- Pitfalls to avoid (null vs undefined, mutual exclusivity, etc.)
This addresses the documentation gap reported in issue #292 where users
were confused about how to remove properties during node updates.
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* fix: correct array property removal documentation in n8n_update_partial_workflow (Issue #292)
Fixed critical documentation error showing array index notation [0] which doesn't work.
The setNestedProperty implementation treats "headers[0]" as a literal object key, not an array index.
Changes:
- Updated nested property removal section to show entire array removal
- Corrected example rm5 to use "parameters.headers" instead of "parameters.headers[0]"
- Replaced misleading pitfall with accurate warning about array index notation not being supported
Impact:
- Prevents user confusion and non-functional code
- All examples now show correct, working patterns
- Clear warning helps users avoid this mistake
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
Resolved conflicts in:
- package.json: accepted main's version (2.22.5)
- package.runtime.json: accepted main's version (2.22.5)
- .github/workflows/release.yml: kept script-based fix over heredoc approach
The script-based approach from this branch fixes the YAML parsing issues
that the main branch's heredoc approach causes.
Concieved by Romuald Członkowski - www.aiadvisors.pl/en
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Version bump to trigger automated release workflow and verify that the
YAML syntax fix (commit 79ef853) works correctly.
Previous release attempt for 2.22.4 failed due to YAML syntax error
(emoji in heredoc). This version bump will test the complete release
pipeline end-to-end.
Concieved by Romuald Członkowski - www.aiadvisors.pl/en
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The emoji (🎉) on line 147 inside the heredoc was causing GitHub Actions
YAML parser to fail with "Invalid workflow file" error on line 149.
Root cause analysis:
- Emojis work fine in echo statements throughout workflows
- But emojis as literal content inside heredocs within YAML break the parser
- The UTF-8 bytes of the emoji confuse GitHub Actions' YAML interpreter
- Error was reported at line 149 but caused by emoji on line 147
Solution:
- Removed emoji from heredoc content in release notes generation
- Heredoc now contains plain ASCII text only
- This follows the same pattern as other heredocs in the workflow
Related: Previous similar fix in commit 952a97e which changed from quoted
multi-line strings to heredocs. This fix completes that work by ensuring
heredoc content is parser-safe.
Fixes: https://github.com/czlonkowski/n8n-mcp/actions/runs/18802795662
Concieved by Romuald Członkowski - www.aiadvisors.pl/en
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Addresses version desynchronization that caused release workflow failures.
The package.runtime.json was stuck at 2.22.0 while package.json advanced to 2.22.3,
preventing npm package publication since v2.21.1.
Changes:
- Bump package.json to 2.22.4
- Update package.runtime.json to 2.22.4 via sync script
- Ensures release workflow will properly detect version change
This fix will allow the automated release workflow to publish v2.22.4 to npm
and create the corresponding GitHub release.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Conceived by Romuald Członkowski - www.aiadvisors.pl/en
…ssue #349)
Addresses "Cannot read properties of undefined (reading 'map')" error by adding validation and fallback handling for n8n API responses.
Changes:
Add response structure validation in listWorkflows, listExecutions, listCredentials, and listTags methods
Handle edge case where API returns array directly instead of {data: [], nextCursor} wrapper object
Provide clear error messages when response format is unexpected
Add logging when using fallback format handling
This fix ensures compatibility with different n8n API versions and prevents runtime errors when the response structure varies from expected.
Fixes#349
Conceived by Romuald Członkowski - www.aiadvisors.pl/en
Addresses "Cannot read properties of undefined (reading 'map')" error
by adding validation and fallback handling for n8n API responses.
Changes:
- Add response structure validation in listWorkflows, listExecutions,
listCredentials, and listTags methods
- Handle edge case where API returns array directly instead of
{data: [], nextCursor} wrapper object
- Provide clear error messages when response format is unexpected
- Add logging when using fallback format handling
This fix ensures compatibility with different n8n API versions and
prevents runtime errors when the response structure varies from expected.
Fixes#349
Conceived by Romuald Członkowski - www.aiadvisors.pl/en
Added helpful suggestions for HTTP Request node best practices after thorough investigation of issue #361.
## What's New
1. **alwaysOutputData Suggestion**
- Suggests adding alwaysOutputData: true at node level
- Prevents silent workflow failures when HTTP requests error
- Ensures downstream error handling can process failed requests
2. **responseFormat Suggestion for API Endpoints**
- Suggests setting options.response.response.responseFormat
- Prevents JSON parsing confusion
- Triggered for URLs containing /api, /rest, supabase, firebase, googleapis, .com/v
3. **Enhanced URL Protocol Validation**
- Detects missing protocol in expression-based URLs
- Warns about patterns like =www.{{ $json.domain }}.com
- Warns about expressions without protocol
## Investigation Findings
**Key Discoveries:**
- Mixed expression syntax =literal{{ expression }} actually works in n8n (claim was incorrect)
- Real validation gaps: missing alwaysOutputData and responseFormat checks
- Compared broken vs fixed workflows to identify actual production issues
**Testing Evidence:**
- Analyzed workflow SwjKJsJhe8OsYfBk with mixed syntax - executions successful
- Compared broken workflow (mBmkyj460i5rYTG4) with fixed workflow (hQI9pby3nSFtk4TV)
- Identified that fixed workflow has alwaysOutputData: true and explicit responseFormat
## Impact
- Non-Breaking: All changes are suggestions/warnings, not errors
- Actionable: Clear guidance on how to implement best practices
- Production-Focused: Addresses real workflow reliability concerns
## Test Coverage
Added 8 new test cases covering:
- alwaysOutputData suggestion for all HTTP Request nodes
- responseFormat suggestion for API endpoint detection
- responseFormat NOT suggested when already configured
- URL protocol validation for expression-based URLs
- No false positives when protocol is correctly included
## Files Changed
- src/services/enhanced-config-validator.ts - Added enhanceHttpRequestValidation()
- tests/unit/services/enhanced-config-validator.test.ts - Added 8 test cases
- CHANGELOG.md - Documented enhancement with investigation findings
- package.json - Bump version to 2.22.2
Fixes#361
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
Fixed failing CI test by updating test expectations to match the new response
structure that includes a details.warnings field in validateOnly mode.
Changes:
- Updated test mock to include warnings: [] in applyDiff response
- Updated test expectations to include details: { warnings: [] }
Related to issue #360 fix.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
Fixed critical bug where warnings were generated by the diff engine
but not included in the MCP response, making them invisible to users.
Now warnings are properly passed through in all return paths:
- Success path (workflow updated)
- validateOnly path (dry run mode)
- Failure path (continueOnError mode)
This completes the fix for issue #360, ensuring users receive helpful
guidance when using sourceIndex instead of branch/case parameters.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implemented a warning system to guide users toward using smart parameters
(branch="true"/"false" for If nodes, case=N for Switch nodes) instead of
sourceIndex, which can lead to incorrect branch routing.
Changes:
- Added warnings property to WorkflowDiffResult interface
- Warnings generated when sourceIndex used with If/Switch nodes
- Enhanced tool documentation with CRITICAL pitfalls
- Added regression tests reproducing issue #360
- Version bump to 2.22.1
The branch parameter functionality works correctly - this fix adds helpful
warnings to prevent users from accidentally using the less intuitive
sourceIndex parameter.
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
