n8n-mcp/CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[2.14.6] - 2025-10-01

Enhanced

• Webhook Error Messages: Replaced generic "Please try again later or contact support" messages with actionable guidance
  • Error messages now extract execution ID and workflow ID from failed webhook triggers
  • Guide users to use n8n_get_execution({id: executionId, mode: 'preview'}) for efficient debugging
  • Format: "Workflow {workflowId} execution {executionId} failed. Use n8n_get_execution({id: '{executionId}', mode: 'preview'}) to investigate the error."
  • When no execution ID available: "Workflow failed to execute. Use n8n_list_executions to find recent executions, then n8n_get_execution with mode='preview' to investigate."

Added

• New error formatting functions in n8n-errors.ts:
  • formatExecutionError() - Creates execution-specific error messages with debugging guidance
  • formatNoExecutionError() - Provides guidance when execution context unavailable
• Enhanced McpToolResponse type with optional executionId and workflowId fields
• Error handling documentation in n8n-trigger-webhook-workflow tool docs
• 30 new comprehensive tests for error message formatting and webhook error handling

Changed

• handleTriggerWebhookWorkflow now extracts execution context from error responses
• getUserFriendlyErrorMessage returns actual server error messages instead of generic text
• Tool documentation type enhanced with optional errorHandling field

Fixed

• Test expectations updated to match new error message format (handlers-workflow-diff.test.ts)

Benefits

• Fast debugging: Preview mode executes in <50ms (vs seconds for full data)
• Efficient: Uses ~500 tokens (vs 50K+ tokens for full execution data)
• Safe: No timeout or token limit risks
• Actionable: Clear next steps for users to investigate failures

Impact

• Eliminates unhelpful "contact support" messages
• Provides specific, actionable debugging guidance
• Reduces debugging time by directing users to efficient tools
• 100% backward compatible - only improves error messages

[2.14.5] - 2025-09-30

Added

• Intelligent Execution Data Filtering: Major enhancement to n8n_get_execution tool to handle large datasets without exceeding token limits
  • Preview Mode: Shows data structure, counts, and size estimates without actual data (~500 tokens)
  • Summary Mode: Returns 2 sample items per node (safe default, ~2-5K tokens)
  • Filtered Mode: Granular control with node filtering and custom item limits
  • Full Mode: Complete data retrieval (explicit opt-in)
  • Smart recommendations based on data size (guides optimal retrieval strategy)
  • Structure-only mode (itemsLimit: 0) to see data schema without values
  • Node-specific filtering with nodeNames parameter
  • Input data inclusion option for debugging transformations
  • Automatic size estimation and token consumption guidance

Enhanced

• n8n_get_execution tool with new parameters:
  • mode: 'preview' | 'summary' | 'filtered' | 'full'
  • nodeNames: Filter to specific nodes
  • itemsLimit: Control items per node (0=structure, -1=unlimited, default=2)
  • includeInputData: Include input data for debugging
  • Legacy includeData parameter mapped to new modes for backward compatibility
• Tool documentation with comprehensive examples and best practices
• Type system with new interfaces: ExecutionMode, ExecutionPreview, ExecutionFilterOptions, FilteredExecutionResponse

Technical Improvements

• New ExecutionProcessor service with intelligent filtering logic
• Smart data truncation with metadata (hasMoreData, truncated flags)
• Validation for itemsLimit (capped at 1000, negative values default to 2)
• Error message extraction helper for consistent error handling
• Constants-based thresholds for easy tuning (20/50/100KB limits)
• 33 comprehensive unit tests with 78% coverage
• Null-safe data access throughout

Performance

• Preview mode: <50ms (no data, just structure)
• Summary mode: <200ms (2 items per node)
• Filtered mode: 50-500ms (depends on filters)
• Size estimation within 10-20% accuracy

Impact

• Solves token limit issues when inspecting large workflow executions
• Enables AI agents to understand execution data without overwhelming responses
• Reduces token usage by 80-95% for large datasets (50+ items)
• Maintains 100% backward compatibility with existing integrations
• Recommended workflow: preview → recommendation → filtered/summary

Fixed

• Preview mode bug: Fixed API data fetching logic to ensure preview mode retrieves execution data for structure analysis and recommendation generation
  • Changed fetchFullData condition in handlers-n8n-manager.ts to include preview mode
  • Preview mode now correctly returns structure, item counts, and size estimates
  • Recommendations are now accurate and prevent token overflow issues

Migration Guide

• No breaking changes: Existing n8n_get_execution calls work unchanged
• New recommended workflow:
  1. Call with mode: 'preview' to assess data size
  2. Follow recommendation.suggestedMode from preview
  3. Use mode: 'filtered' with itemsLimit for precise control
• Legacy includeData: true now maps to mode: 'summary' (safer default)

[2.14.4] - 2025-09-30

Added

• Workflow Cleanup Operations: Two new operations for n8n_update_partial_workflow
  • cleanStaleConnections: Automatically removes connections referencing non-existent nodes
  • replaceConnections: Replace entire connections object in a single operation
• Graceful Error Handling: Enhanced removeConnection with ignoreErrors flag
• Best-Effort Mode: New continueOnError mode for WorkflowDiffRequest
  • Apply valid operations even if some fail
  • Returns detailed results with applied and failed operation indices
  • Maintains atomic mode as default for safety

Enhanced

• Tool documentation for workflow cleanup scenarios
• Type system with new operation interfaces
• 15 new tests covering all new features

Impact

• Reduces broken workflow fix time from 10-15 minutes to 30 seconds
• Token efficiency: cleanStaleConnections is 1 operation vs 10+ manual operations
• 100% backwards compatibility maintained

[2.14.3] - 2025-09-30

Added

• Incremental template updates with npm run fetch:templates:update
• Smart filtering for new templates (5-10 min vs 30-40 min full rebuild)
• 48 new templates (2,598 → 2,646 total)

Fixed

• Template metadata generation: Updated to gpt-4o-mini-2025-08-07 model
• Removed unsupported temperature parameter from OpenAI Batch API
• Template sanitization: Added Airtable PAT and GitHub token detection
• Sanitized 24 templates removing API tokens

Updated

• n8n: 1.112.3 → 1.113.3
• n8n-core: 1.111.0 → 1.112.1
• n8n-workflow: 1.109.0 → 1.110.0
• @n8n/n8n-nodes-langchain: 1.111.1 → 1.112.2
• Node database rebuilt with 536 nodes from n8n v1.113.3

[2.14.2] - 2025-09-29

Fixed

• Validation false positives for Google Drive nodes with 'fileFolder' resource
  • Added node type normalization to handle both n8n-nodes-base. and nodes-base. prefixes correctly
  • Fixed resource validation to properly recognize all valid resource types
  • Default operations are now properly applied when not specified
  • Property visibility is now correctly checked with defaults applied
• Code node validation incorrectly flagging valid n8n expressions as syntax errors
  • Removed overly aggressive regex pattern /\)\s*\)\s*{/ that flagged valid expressions
  • Valid patterns like $('NodeName').first().json are now correctly recognized
  • Function chaining and method chaining no longer trigger false positives
• Enhanced error handling in repository methods based on code review feedback
  • Added try-catch blocks to getNodePropertyDefaults and getDefaultOperationForResource
  • Validates data structures before accessing to prevent crashes with malformed node data
  • Returns safe defaults on errors to ensure validation continues

Added

• Comprehensive test coverage for validation fixes in tests/unit/services/validation-fixes.test.ts
• New repository methods for better default value handling:
  • getNodePropertyDefaults() - retrieves default values for node properties
  • getDefaultOperationForResource() - gets default operation for a specific resource

Changed

• Enhanced filterPropertiesByMode to return both filtered properties and config with defaults applied
• Improved node type validation to accept both valid prefix formats

[2.14.1] - 2025-09-26

Changed

• BREAKING: Refactored telemetry system with major architectural improvements
  • Split 636-line TelemetryManager into 7 focused modules (event-tracker, batch-processor, event-validator, rate-limiter, circuit-breaker, workflow-sanitizer, config-manager)
  • Changed TelemetryManager constructor to private, use getInstance() method now
  • Implemented lazy initialization pattern to avoid early singleton creation

Added

• Security & Privacy enhancements for telemetry:
  • Comprehensive input validation with Zod schemas
  • Enhanced sanitization of sensitive data (URLs, API keys, emails)
  • Expanded sensitive key detection patterns (25+ patterns)
  • Row Level Security on Supabase backend
  • Data deletion contact info (romuald@n8n-mcp.com)
• Performance & Reliability improvements:
  • Sliding window rate limiter (100 events/minute)
  • Circuit breaker pattern for network failures
  • Dead letter queue for failed events
  • Exponential backoff with jitter for retries
  • Performance monitoring with overhead tracking (<5%)
  • Memory-safe array limits in rate limiter
• Comprehensive test coverage enhancements:
  • Added 662 lines of new telemetry tests
  • Enhanced config-manager tests with 17 new edge cases
  • Enhanced workflow-sanitizer tests with 19 new edge cases
  • Improved coverage from 63% to 91% for telemetry module
  • Branch coverage improved from 69% to 87%

Fixed

• TypeScript lint errors in telemetry test files
  • Corrected variable name conflicts in integration tests
  • Fixed process.exit mock implementation in batch-processor tests
  • Fixed tuple type annotations for workflow node positions
  • Resolved MockInstance type import issues
• Test failures in CI pipeline
  • Fixed test timeouts caused by improper fake timer usage
  • Resolved Timer.unref() compatibility issues
  • Fixed event validator filtering standalone 'key' property
  • Corrected batch processor circuit breaker behavior
• TypeScript error in telemetry test preventing CI build
• Added @supabase/supabase-js to Docker builder stage and runtime dependencies

[2.14.0] - 2025-09-26

Added

• Anonymous telemetry system with Supabase integration to understand usage patterns

  • Tracks active users with deterministic anonymous IDs
  • Records MCP tool usage frequency and error rates
  • Captures sanitized workflow structures on successful validation
  • Monitors common error patterns for improvement insights
  • Zero-configuration design with opt-out support via N8N_MCP_TELEMETRY_DISABLED environment variable

• Enhanced telemetry tracking methods:

  • trackSearchQuery - Records search patterns and result counts
  • trackValidationDetails - Captures validation errors and warnings
  • trackToolSequence - Tracks AI agent tool usage sequences
  • trackNodeConfiguration - Records common node configuration patterns
  • trackPerformanceMetric - Monitors operation performance

• Privacy-focused workflow sanitization:

  • Removes all sensitive data (URLs, API keys, credentials)
  • Generates workflow hashes for deduplication
  • Preserves only structural information

• Comprehensive test coverage for telemetry components (91%+ coverage)

Fixed

• Fixed TypeErrors in get_node_info, get_node_essentials, and get_node_documentation tools that were affecting 50% of calls
• Added null safety checks for undefined node properties
• Fixed multi-process telemetry issues with immediate flush strategy
• Resolved RLS policy and permission issues with Supabase

Changed

• Updated Docker configuration to include Supabase client for telemetry support
• Enhanced workflow validation tools to track validated workflows
• Improved error handling with proper null coalescing operators

Documentation

• Added PRIVACY.md with comprehensive privacy policy
• Added telemetry configuration instructions to README
• Updated CLAUDE.md with telemetry system architecture

Previous Versions

For changes in previous versions, please refer to the git history and release notes.