diff --git a/CLAUDE.md b/CLAUDE.md index 3c15989..64cf656 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,118 +6,6 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co n8n-mcp is a comprehensive documentation and knowledge server that provides AI assistants with complete access to n8n node information through the Model Context Protocol (MCP). It serves as a bridge between n8n's workflow automation platform and AI models, enabling them to understand and work with n8n nodes effectively. -## ✅ Latest Updates (v2.7.6) - -### Update (v2.7.6) - Trust Proxy Support for Correct IP Logging: -- ✅ **NEW: TRUST_PROXY support** - Log real client IPs when behind reverse proxy -- ✅ **FIXED: Issue #19** - Docker internal IPs no longer logged when proxy configured -- ✅ **ENHANCED: HTTP deployment** - Better nginx/proxy configuration documentation -- ✅ **FLEXIBLE: Proxy hop configuration** - Support for single or multiple proxy layers -- ✅ **BACKWARD COMPATIBLE**: Defaults to current behavior when not configured - -### Update (v2.7.5) - AUTH_TOKEN_FILE Support & Known Issues: -- ✅ **NEW: AUTH_TOKEN_FILE support** - Read authentication token from file (Docker secrets compatible) -- ✅ **ADDED: Known Issues section** - Documented Claude Desktop container duplication bug -- ✅ **ENHANCED: Authentication flexibility** - Support both AUTH_TOKEN and AUTH_TOKEN_FILE variables -- ✅ **FIXED: Issue #16** - AUTH_TOKEN_FILE now properly implemented as documented -- ✅ **DOCKER SECRETS**: Seamlessly integrate with Docker secrets management -- ✅ **BACKWARD COMPATIBLE**: AUTH_TOKEN continues to work as before - -### Update (v2.7.4) - Self-Documenting MCP Tools: -- ✅ **RENAMED: start_here_workflow_guide → tools_documentation** - More descriptive name -- ✅ **NEW: Depth parameter** - Control documentation detail level with "essentials" or "full" -- ✅ **NEW: Per-tool documentation** - Get help for any specific tool by name -- ✅ **Concise by default** - Essential info only, unless full depth requested -- ✅ **LLM-friendly format** - Plain text, not JSON for better readability -- ✅ **Two-tier documentation**: - - **Essentials**: Brief description, key parameters, example, performance, 2-3 tips - - **Full**: Complete documentation with all parameters, examples, use cases, best practices, pitfalls -- ✅ **Quick reference** - Call without parameters for immediate help -- ✅ **8 documented tools** - Comprehensive docs for most commonly used tools -- ✅ **Performance guidance** - Clear indication of which tools are fast vs slow -- ✅ **Error prevention** - Common pitfalls documented upfront - -### Update (v2.7.0) - Diff-Based Workflow Editing with Transactional Updates: -- ✅ **NEW: n8n_update_partial_workflow tool** - Update workflows using diff operations for precise, incremental changes -- ✅ **RENAMED: n8n_update_workflow → n8n_update_full_workflow** - Clarifies that it replaces the entire workflow -- ✅ **NEW: WorkflowDiffEngine** - Applies targeted edits without sending full workflow JSON -- ✅ **80-90% token savings** - Only send the changes, not the entire workflow -- ✅ **13 diff operations** - addNode, removeNode, updateNode, moveNode, enableNode, disableNode, addConnection, removeConnection, updateConnection, updateSettings, updateName, addTag, removeTag -- ✅ **Smart node references** - Use either node ID or name for operations -- ✅ **Transaction safety** - Validates all operations before applying any changes -- ✅ **Validation-only mode** - Test your diff operations without applying them -- ✅ **Comprehensive test coverage** - All operations and edge cases tested -- ✅ **Example guide** - See [workflow-diff-examples.md](./docs/workflow-diff-examples.md) for usage patterns -- ✅ **FIXED: MCP validation error** - Simplified schema to fix "additional properties" error in Claude Desktop -- ✅ **FIXED: n8n API validation** - Updated cleanWorkflowForUpdate to remove all read-only fields -- ✅ **FIXED: Claude Desktop compatibility** - Added additionalProperties: true to handle extra metadata from Claude Desktop -- ✅ **NEW: Transactional Updates** - Two-pass processing allows adding nodes and connections in any order -- ✅ **Operation Limit** - Maximum 5 operations per request ensures reliability -- ✅ **Order Independence** - Add connections before nodes - engine handles dependencies automatically - -### Update (v2.6.3) - n8n Instance Workflow Validation: -- ✅ **NEW: n8n_validate_workflow tool** - Validate workflows directly from n8n instance by ID -- ✅ **Fetches and validates** - Retrieves workflow from n8n API and runs comprehensive validation -- ✅ **Same validation logic** - Uses existing WorkflowValidator for consistency -- ✅ **Full validation options** - Supports all validation profiles and options -- ✅ **Integrated workflow** - Part of complete lifecycle: discover → build → validate → deploy → execute -- ✅ **No JSON needed** - AI agents can validate by just providing workflow ID - -### Update (v2.6.2) - Enhanced Workflow Creation Validation: -- ✅ **NEW: Node type validation** - Verifies node types actually exist in n8n -- ✅ **FIXED: nodes-base prefix detection** - Now catches `nodes-base.webhook` BEFORE database lookup -- ✅ **NEW: Smart suggestions** - Detects `nodes-base.webhook` and suggests `n8n-nodes-base.webhook` -- ✅ **NEW: Common mistake detection** - Catches missing package prefixes (e.g., `webhook` → `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 -- ✅ **Enhanced error messages** - Clear guidance on proper workflow structure -- ✅ **Connection examples** - Shows correct format: `connections: { "Node Name": { "main": [[{ "node": "Target", "type": "main", "index": 0 }]] } }` -- ✅ **Helper functions** - `getWorkflowStructureExample()` and `getWorkflowFixSuggestions()` -- ✅ **Prevents broken workflows** - Like single webhook nodes with empty connections that show as question marks -- ✅ **Reinforces best practices** - Use node NAMES (not IDs) in connections - -### Update (v2.6.1) - Enhanced typeVersion Validation: -- ✅ **NEW: typeVersion validation** - Workflow validator now enforces typeVersion on all versioned nodes -- ✅ **Catches missing typeVersion** - Returns error with correct version to use -- ✅ **Warns on outdated versions** - Alerts when using older node versions -- ✅ **Prevents invalid versions** - Errors on versions that exceed maximum supported -- ✅ Helps AI agents avoid common workflow creation mistakes -- ✅ Ensures workflows use compatible node versions before deployment - -### Update (v2.6.0) - n8n Management Tools Integration: -- ✅ **NEW: 14 n8n management tools** - Create, update, execute workflows via API -- ✅ **NEW: n8n_create_workflow** - Create workflows programmatically -- ✅ **NEW: n8n_update_workflow** - Update existing workflows -- ✅ **NEW: n8n_trigger_webhook_workflow** - Execute workflows via webhooks -- ✅ **NEW: n8n_list_executions** - Monitor workflow executions -- ✅ **NEW: n8n_health_check** - Check n8n instance connectivity -- ✅ 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 - -## ✅ Previous Updates - -For a complete history of all updates from v2.0.0 to v2.5.1, please see [CHANGELOG.md](./CHANGELOG.md). - -Key highlights from recent versions: -- **v2.5.x**: AI tool support enhancements, workflow validation, expression validation -- **v2.4.x**: AI-optimized tools, workflow templates, enhanced validation profiles -- **v2.3.x**: Universal Node.js compatibility, HTTP server fixes, dependency management -- ✅ Maintains full functionality with either adapter - -## ✅ Previous Achievements (v2.2) - -**The major refactor has been successfully completed based on IMPLEMENTATION_PLAN.md v2.2** - -### Achieved Goals: -- ✅ Fixed property/operation extraction (452/458 nodes have properties) -- ✅ Added AI tool detection (35 AI tools detected) -- ✅ Full support for @n8n/n8n-nodes-langchain package -- ✅ Proper VersionedNodeType handling -- ✅ Fixed documentation mapping issues - ### Current Architecture: ``` src/