n8n-mcp/docs/CHANGELOG.md

# Changelog

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

## [2.7.0] - 2025-06-28

### Added
- **Diff-Based Workflow Editing**: Revolutionary token-efficient workflow updates
  - **NEW**: `n8n_update_partial_workflow` tool - Update workflows using diff operations for precise, incremental changes
  - **NEW**: WorkflowDiffEngine - Applies targeted edits without sending full workflow JSON
  - **NEW**: 13 diff operations - addNode, removeNode, updateNode, moveNode, enableNode, disableNode, addConnection, removeConnection, updateConnection, updateSettings, updateName, addTag, removeTag
  - **NEW**: Transaction safety - Validates all operations before applying any changes
  - **NEW**: Validation-only mode - Test your diff operations without applying them
  - **NEW**: Transactional Updates - Two-pass processing allows adding nodes and connections in any order
  - Smart node references - Use either node ID or name for operations
  - Order independence - Add connections before nodes, engine handles dependencies automatically
  - Operation limit - Maximum 5 operations per request ensures reliability
  - 80-90% token savings - Only send the changes, not the entire workflow
  - Comprehensive test coverage - All operations and edge cases tested
  - Example guide - See [workflow-diff-examples.md](./workflow-diff-examples.md) for usage patterns

### Changed
- **RENAMED**: `n8n_update_workflow` → `n8n_update_full_workflow` - Clarifies that it replaces the entire workflow

### Fixed
- **Docker Runtime Dependencies**: Added missing `uuid` package to runtime dependencies
  - Fixed MODULE_NOT_FOUND error in Docker containers
  - Updated both package.json and package.runtime.json
  - Aligned package versions between main and runtime configurations

## [2.6.2] - 2025-06-26

### Added
- **Enhanced Workflow Creation Validation**: Major improvements to prevent broken workflows
  - **NEW**: Node type existence validation - Verifies node types actually exist in n8n
  - **NEW**: Smart suggestions for common mistakes - Detects `webhook` and suggests `n8n-nodes-base.webhook`
  - **NEW**: Minimum viable workflow validation - Prevents single-node workflows (except webhooks)
  - **NEW**: Empty connection detection - Catches multi-node workflows with no connections
  - **NEW**: Helper functions - `getWorkflowStructureExample()` and `getWorkflowFixSuggestions()`
  - Enhanced error messages with clear guidance and connection examples
  - Prevents broken workflows that show as question marks in n8n UI

### Fixed
- **Critical**: `nodes-base.webhook` validation - Now caught BEFORE database lookup
  - Previously, `nodes-base.webhook` would pass validation because it existed in the normalized database
  - Now explicitly checks for and rejects `nodes-base.` prefix before any database operations
  - This fixes the exact issue causing workflows to appear broken in n8n UI

### Changed
- Workflow validator now checks node types in order: invalid patterns → database lookup → suggestions
- Connection validation messages now include proper format examples
- Error messages are more actionable with specific fix instructions

## [2.6.1] - 2025-06-26

### Added
- **Enhanced typeVersion Validation**: Comprehensive validation for versioned nodes
  - **NEW**: typeVersion validation enforced on all versioned nodes
  - Catches missing typeVersion and provides correct version to use
  - Warns on outdated versions when newer versions are available
  - Prevents invalid versions that exceed maximum supported
  - Helps AI agents avoid common workflow creation mistakes
  - Test coverage for all typeVersion scenarios

### Changed
- WorkflowValidator now includes typeVersion in its validation pipeline
- Enhanced error messages for typeVersion issues with actionable suggestions

## [2.6.0] - 2025-06-26

### Added
- **n8n Management Tools Integration**: Complete workflow lifecycle management via API
  - **NEW**: 14 n8n management tools for creating, updating, and executing workflows
  - **NEW**: `n8n_create_workflow` - Create workflows programmatically with validation
  - **NEW**: `n8n_update_workflow` - Update existing workflows with safety checks
  - **NEW**: `n8n_trigger_webhook_workflow` - Execute workflows via webhooks
  - **NEW**: `n8n_list_executions` - Monitor workflow executions with filtering
  - **NEW**: `n8n_health_check` - Check n8n instance connectivity and features
  - **NEW**: Workflow management tools with smart error handling
  - **NEW**: Execution management tools for monitoring and debugging
  - Integrated n8n-manager-for-ai-agents functionality
  - Optional feature - only enabled when N8N_API_URL and N8N_API_KEY configured
  - Complete workflow lifecycle: discover → build → validate → deploy → execute
  - Smart error handling for API limitations (activation, direct execution)
  - Conditional tool registration based on configuration

### Changed
- Updated `start_here_workflow_guide` to include n8n management tools documentation
- Enhanced MCP server to conditionally register management tools
- Added comprehensive integration tests for all management features

## [2.5.1] - 2025-01-25

### Added
- **AI Tool Support Enhancement**: Major improvements to AI tool integration
  - **NEW**: `get_node_as_tool_info` tool - Get specific information about using ANY node as an AI tool
  - **ENHANCED**: `get_node_info` now includes `aiToolCapabilities` section for all nodes
  - **ENHANCED**: `list_ai_tools` - Added usage guidance explaining ANY node can be used as a tool
  - **ENHANCED**: `WorkflowValidator` - Now validates `ai_tool` connections in workflows
  - AI workflow pattern detection - Warns when AI Agents have no tools connected
  - Community node detection - Reminds about N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE environment variable
  - **NEW**: AI Tool TaskTemplates - Added use_google_sheets_as_tool, use_slack_as_tool, multi_tool_ai_agent
  - Comprehensive examples showing how to connect regular nodes as AI tools
  - Tool usage documentation with $fromAI() expression examples

### Changed
- Clarified that ANY node can be used as an AI tool, not just nodes with usableAsTool property
- Enhanced workflow validation to understand and validate ai_tool connections
- Improved expression validation to support $fromAI() dynamic AI parameters

## [2.5.0] - 2025-01-20

### Added
- **Complete Workflow Validation**: Professional-grade workflow validation system
  - **NEW**: `validate_workflow` tool - Validate entire workflows before deployment
  - **NEW**: `validate_workflow_connections` tool - Check workflow structure and connections
  - **NEW**: `validate_workflow_expressions` tool - Validate all n8n expressions in a workflow
  - **NEW**: `ExpressionValidator` - Comprehensive n8n expression syntax validation
  - **NEW**: `WorkflowValidator` - Complete workflow structure and logic validation
  - Detects cycles (infinite loops) in workflows
  - Validates node references in expressions ($node["Node Name"])
  - Checks for orphaned nodes and missing connections
  - Expression syntax validation with common mistake detection
  - Workflow best practices analysis with suggestions
  - Supports partial validation (nodes only, connections only, expressions only)
  - Test coverage for all validation scenarios

## [2.4.2] - 2025-01-15

### Added
- **Enhanced Node Configuration Validation**: Operation-aware validation with dramatic accuracy improvements
  - **NEW**: `validate_node_operation` tool - Operation-aware validation with 80%+ fewer false positives
  - **NEW**: `validate_node_minimal` tool - Lightning-fast validation for just required fields
  - **NEW**: Validation profiles - Choose between minimal, runtime, ai-friendly, or strict validation
  - **NEW**: `EnhancedConfigValidator` - Smart validation that only checks relevant properties
  - **NEW**: Node-specific validators - Custom logic for Slack, Google Sheets, OpenAI, MongoDB, Webhook, Postgres, MySQL
  - **NEW**: SQL safety features - Detects SQL injection risks, unsafe DELETE/UPDATE queries
  - Added operation context filtering (only validates properties for selected operation)
  - Integrated working examples in validation responses when errors found
  - Added actionable next steps and auto-fix suggestions
  - Basic code syntax validation for JavaScript/Python in Code node
  - Dramatic improvement for complex multi-operation nodes
  - Test results: Slack validation reduced from 45 errors to 1 error!

### Removed
- Deprecated `validate_node_config` tool in favor of new operation-aware validators

## [2.4.1] - 2025-01-10

### Added
- **n8n Workflow Templates**: Integration with n8n.io template library
  - **NEW**: `list_node_templates` tool - Find workflow templates using specific nodes
  - **NEW**: `get_template` tool - Get complete workflow JSON for import
  - **NEW**: `search_templates` tool - Search templates by keywords
  - **NEW**: `get_templates_for_task` tool - Get curated templates for common tasks
  - Added Templates system with n8n.io API integration
  - Templates filtered to last 6 months only (freshness guarantee)
  - Manual fetch system - not part of regular rebuild
  - Full workflow JSON available for immediate use
  - 10 task categories: AI automation, data sync, webhooks, etc.

## [2.4.0] - 2025-01-05

### Added
- **AI-Optimized MCP Tools**: Dramatically improved AI agent experience
  - **NEW**: `get_node_essentials` tool - Returns only 10-20 essential properties (95% size reduction)
  - **NEW**: `search_node_properties` tool - Search for specific properties within nodes
  - **NEW**: `get_node_for_task` tool - Pre-configured settings for 14 common tasks
  - **NEW**: `list_tasks` tool - Discover available task templates
  - **NEW**: `validate_node_config` tool - Validate configurations before use
  - **NEW**: `get_property_dependencies` tool - Analyze property visibility dependencies
  - Added PropertyFilter service with curated essential properties for 20+ nodes
  - Added ExampleGenerator with working examples for common use cases
  - Added TaskTemplates service with 14 pre-configured tasks
  - Added ConfigValidator service for comprehensive validation
  - Added PropertyDependencies service for dependency analysis
  - Enhanced all property descriptions - 100% coverage
  - Added version information to essentials response
  - Response sizes reduced from 100KB+ to <5KB for common nodes

### Changed
- **License Change**: Changed from Apache 2.0 to MIT License for wider adoption
- Fixed missing AI and LangChain node documentation
- Improved documentation mapping for better coverage

## [2.3.3] - 2025-06-16

### Added
- **Automated Dependency Update System**: Comprehensive solution for keeping n8n packages in sync
  - Custom update script (`scripts/update-n8n-deps.js`) that respects n8n's interdependencies
  - GitHub Actions workflow for weekly automated updates
  - Renovate configuration as an alternative solution
  - Dependency update documentation guide
- Support for automatic n8n package version synchronization
- Documentation updates reflecting current metrics

### Fixed
- **Validation Script Node Type References**: Fixed node type format issues
  - Changed from short names (e.g., 'httpRequest') to full names (e.g., 'nodes-base.httpRequest')
  - Removed versioned check for Code node as it's not consistently detected
  - All validation tests now pass after dependency updates

### Changed
- Updated n8n dependencies to latest versions:
  - n8n: 1.14.1 → 1.97.1
  - n8n-core: 1.14.1 → 1.96.0
  - n8n-workflow: 1.82.0 → 1.94.0
  - @n8n/n8n-nodes-langchain: 1.97.0 → 1.96.1
- Significant increase in detected nodes and capabilities:
  - Total nodes: 458 → 525
  - AI-capable tools: 35 → 263 (major increase due to updated detection)
  - Nodes with properties: 98.7% → 99%
  - Nodes with operations: 57.9% → 63.6%

### Technical Details
- Dependency update script now checks n8n's required dependency versions
- Validation script uses correct database column names
- All critical nodes (httpRequest, code, slack, agent) validate successfully

## [2.3.2] - 2025-06-14

### Fixed
- **HTTP Server Stream Error**: Complete fix for "stream is not readable" error
  - Removed Express body parsing middleware that was consuming request streams
  - Fixed "Server not initialized" error with direct JSON-RPC implementation
  - Added `USE_FIXED_HTTP=true` environment variable for stable HTTP mode
  - Bypassed problematic StreamableHTTPServerTransport implementation
- HTTP server now works reliably with average response time of ~12ms
- Updated all HTTP server implementations to preserve raw streams

### Added
- `http-server-fixed.ts` - Direct JSON-RPC implementation
- `ConsoleManager` utility for stream isolation
- `MCP Engine` interface for service integration
- Comprehensive documentation for HTTP server fixes

### Changed
- Default HTTP mode now uses fixed implementation when `USE_FIXED_HTTP=true`
- Updated Docker configuration to use fixed implementation by default
- Improved error handling and logging in HTTP mode

## [2.3.1] - 2025-06-14

### Added
- **Single-Session Architecture**: Initial attempt to fix HTTP server issues
  - Implemented session reuse across requests
  - Added console output isolation
  - Created engine interface for service integration

### Fixed
- Partial fix for "stream is not readable" error (completed in v2.3.2)

## [2.3.0] - 2024-12-06

### Added
- **HTTP Remote Deployment**: Single-user HTTP server for remote access
  - Stateless architecture for simple deployments
  - Bearer token authentication
  - Compatible with mcp-remote adapter for Claude Desktop
  - New HTTP mode scripts and deployment helper
- **Universal Node.js Compatibility**: Automatic database adapter fallback system
  - Primary adapter: `better-sqlite3` for optimal performance
  - Fallback adapter: `sql.js` (pure JavaScript) for version mismatches
  - Automatic detection and switching between adapters
  - No manual configuration required
- Database adapter abstraction layer (`src/database/database-adapter.ts`)
- Version detection and logging for troubleshooting
- sql.js dependency for pure JavaScript SQLite implementation
- HTTP server implementation (`src/http-server.ts`)
- Deployment documentation and scripts

### Changed
- Updated all database operations to use the adapter interface
- Removed Node.js v20.17.0 requirement - now works with ANY version
- Simplified Claude Desktop setup - no wrapper scripts needed
- Enhanced error messages for database initialization
- Made all MCP tool handlers async for proper initialization

### Fixed
- NODE_MODULE_VERSION mismatch errors with Claude Desktop
- Native module compilation issues in restricted environments
- Compatibility issues when running with different Node.js versions
- Database initialization race conditions in HTTP mode

### Technical Details
- Better-sqlite3: ~10-50x faster (when compatible)
- sql.js: ~2-5x slower but universally compatible
- Both adapters maintain identical API and functionality
- Automatic persistence for sql.js with 100ms debounced saves
- HTTP server uses StreamableHTTPServerTransport for MCP compatibility

## [2.2.0] - 2024-12-06

### Added
- PropertyExtractor class for dedicated property/operation extraction
- NodeRepository for proper JSON serialization/deserialization  
- Support for @n8n/n8n-nodes-langchain package (59 AI nodes)
- AI tool detection (35 tools with usableAsTool property)
- Test suite for critical node validation
- Comprehensive documentation (README, SETUP, CHANGELOG)
- Example configuration files for Claude Desktop
- Node.js v20.17.0 wrapper scripts for compatibility

### Fixed
- Empty properties/operations arrays (now 98.7% nodes have properties)
- Versioned node detection (HTTPRequest, Code properly identified)
- Documentation mapping for nodes with directory-based docs
- Critical node validation (httpRequest, slack, code all pass)

### Changed
- Refactored parser to handle instance-level properties
- Updated MCP server to use NodeRepository
- Improved rebuild script with validation
- Enhanced database schema with proper typing

### Metrics
- 458 total nodes (100% success rate)
- 452 nodes with properties (98.7%)
- 265 nodes with operations (57.9%) 
- 406 nodes with documentation (88.6%)
- 35 AI-capable tools detected
- All critical nodes validated

## [2.1.0] - 2025-01-08

### Added
- Remote deployment capabilities via HTTP/JSON-RPC transport
- Domain configuration through environment variables (`MCP_DOMAIN`)
- Bearer token authentication for remote access
- Comprehensive remote deployment documentation
- PM2 and Nginx configuration examples
- HTTP server mode (`npm run start:http`)

### Enhanced
- Support for both local (stdio) and remote (HTTP) deployment modes
- Production deployment guide for VM/cloud environments
- Claude Desktop configuration for remote servers

## [2.0.0] - 2025-01-08

### Major Refactoring
- **BREAKING CHANGE**: Refocused project to serve only n8n node documentation
- Removed all workflow execution and management features
- Removed bidirectional n8n-MCP integration
- Simplified to be a read-only documentation server

### Added
- SQLite database with full-text search (FTS5) for node documentation
- Integration with n8n-docs repository for official documentation
- Automatic example workflow generation for each node type
- Comprehensive node information including:
  - Source code
  - Official documentation
  - Usage examples
  - Properties schema
  - Credential definitions

### New MCP Tools
- `list_nodes` - List available nodes with filtering
- `get_node_info` - Get complete node information
- `search_nodes` - Full-text search across nodes
- `get_node_example` - Get example workflow for a node
- `get_node_source_code` - Get only source code
- `get_node_documentation` - Get only documentation
- `rebuild_database` - Rebuild entire node database
- `get_database_statistics` - Database statistics

### Infrastructure
- New database schema optimized for documentation storage
- `DocumentationFetcher` for n8n-docs repository integration
- `ExampleGenerator` for creating node usage examples
- `NodeDocumentationService` for database management

## [1.1.0] - 2024-01-07

### Added
- Node source code extraction capability via `get_node_source_code` tool
- List available nodes functionality with `list_available_nodes` tool
- `NodeSourceExtractor` utility for file system access to n8n nodes
- Resource endpoint `nodes://source/{nodeType}` for accessing node source code
- Docker test environment with mounted n8n node_modules
- Comprehensive test suite for AI Agent node extraction
- Test documentation in `docs/AI_AGENT_EXTRACTION_TEST.md`

### Enhanced
- MCP server can now access and extract n8n node implementations
- Support for extracting credential definitions alongside node code
- Package metadata included in extraction results

## [1.0.0] - 2024-01-07

### Initial Release
- Complete n8n-MCP integration implementation
- MCP server exposing n8n workflows as tools, resources, and prompts
- Custom n8n node for connecting to MCP servers
- Bidirectional data format conversion bridge
- Token-based authentication system
- Comprehensive error handling and logging
- Full test coverage for core components
- Docker support with production and development configurations
- Installation scripts for n8n custom node deployment

### MCP Tools
- `execute_workflow` - Execute n8n workflows
- `list_workflows` - List available workflows
- `get_workflow` - Get workflow details
- `create_workflow` - Create new workflows
- `update_workflow` - Update existing workflows
- `delete_workflow` - Delete workflows
- `get_executions` - Get execution history
- `get_execution_data` - Get execution details

### MCP Resources
- `workflow://active` - Active workflows
- `workflow://all` - All workflows
- `execution://recent` - Recent executions
- `credentials://types` - Credential types
- `nodes://available` - Available nodes

### MCP Prompts
- `create_workflow_prompt` - Workflow creation
- `debug_workflow_prompt` - Workflow debugging
- `optimize_workflow_prompt` - Workflow optimization
- `explain_workflow_prompt` - Workflow explanation