diff --git a/CLAUDE.md b/CLAUDE.md index 7d1934a..b35e0c3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -185,8 +185,17 @@ npm run test-nodes # Test critical node properties/operations # Template Commands: npm run fetch:templates # Fetch workflow templates from n8n.io (manual) +npm run fetch:templates:robust # Robust template fetching with retries npm run test:templates # Test template functionality +# Test Commands: +npm run test:essentials # Test new essentials tools +npm run test:enhanced-validation # Test enhanced validation +npm run test:ai-workflow-validation # Test AI workflow validation +npm run test:mcp-tools # Test MCP tool enhancements +npm run test:single-session # Test single session HTTP +npm run test:template-validation # Test template validation + # Workflow Validation Commands: npm run test:workflow-validation # Test workflow validation features @@ -196,6 +205,8 @@ npm run update:n8n # Update n8n packages to latest versions # HTTP Server Commands: npm run start:http # Start server in HTTP mode +npm run start:http:fixed # Start with fixed HTTP implementation +npm run start:http:legacy # Start with legacy HTTP server npm run http # Build and start HTTP server npm run dev:http # HTTP server with auto-reload @@ -223,7 +234,7 @@ The project includes ultra-optimized Docker support with NO n8n dependencies at ### 🚀 Key Optimization: Runtime-Only Dependencies **Important**: Since the database is always pre-built before deployment, the Docker image contains NO n8n dependencies. This results in: -- **87% smaller images** (~200MB vs ~1.5GB) +- **82% smaller images** (~280MB vs ~1.5GB) - **10x faster builds** (~1-2 minutes vs ~12 minutes) - **No n8n version conflicts** at runtime - **Minimal attack surface** for security @@ -251,7 +262,7 @@ The Docker image contains ONLY these runtime dependencies: - `dotenv` - Environment configuration ### Docker Features -- **Ultra-optimized size** (~200MB runtime-only) +- **Ultra-optimized size** (~280MB runtime-only) - **No n8n dependencies** in production image - **Pre-built database** required (nodes.db) - **BuildKit optimizations** for fast builds @@ -261,7 +272,7 @@ The Docker image contains ONLY these runtime dependencies: ### Docker Images - `ghcr.io/czlonkowski/n8n-mcp:latest` - Runtime-only production image - Multi-architecture support (amd64, arm64) -- ~200MB compressed size (87% smaller!) +- ~280MB compressed size (82% smaller!) ### Docker Development ```bash @@ -585,7 +596,7 @@ search_node_properties("nodes-base.httpRequest", "auth") # Find specific option 3. Separate `package.runtime.json` for clarity **Results**: -- **87% smaller images** (200MB vs 1.5GB) +- **82% smaller images** (280MB vs 1.5GB) - **10x faster builds** (1-2 minutes vs 12+ minutes) - **No version conflicts** - n8n updates don't affect runtime - **Better security** - minimal attack surface diff --git a/README.md b/README.md index 9e28f00..3628489 100644 --- a/README.md +++ b/README.md @@ -40,11 +40,11 @@ Get n8n-MCP running in 5 minutes: **Prerequisites:** [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed on your system ```bash -# Pull the Docker image (~200MB, no n8n dependencies!) +# Pull the Docker image (~280MB, no n8n dependencies!) docker pull ghcr.io/czlonkowski/n8n-mcp:latest ``` -> **⚡ Ultra-optimized:** Our Docker image is 87% smaller than typical n8n images because it contains NO n8n dependencies - just the runtime MCP server with a pre-built database! +> **⚡ Ultra-optimized:** Our Docker image is 82% smaller than typical n8n images because it contains NO n8n dependencies - just the runtime MCP server with a pre-built database! Add to Claude Desktop config: ```json @@ -323,27 +323,27 @@ See [HTTP Deployment Guide](./docs/HTTP_DEPLOYMENT.md) for detailed instructions ## 📚 Documentation ### Setup Guides -- [Quick Start Guide](./docs/QUICKSTART.md) - Get running in 5 minutes -- [Claude Desktop Setup](./docs/CLAUDE_DESKTOP_SETUP.md) - Detailed Claude configuration +- [Installation Guide](./docs/INSTALLATION.md) - Comprehensive installation instructions +- [Claude Desktop Setup](./docs/README_CLAUDE_SETUP.md) - Detailed Claude configuration - [Docker Guide](./docs/DOCKER_README.md) - Advanced Docker deployment options ### Usage & Best Practices - [Claude's Interview](./docs/CLAUDE_INTERVIEW.md) - Real-world impact of n8n-MCP - [Claude Project Instructions](#claude-project-setup) - Optimal system instructions for n8n workflows -- [MCP Tools Reference](./docs/TOOLS_REFERENCE.md) - Detailed tool documentation +- [MCP Tools List](#-available-mcp-tools) - Complete list of available tools ### Technical Documentation -- [Architecture Overview](./docs/ARCHITECTURE.md) - System design and components - [HTTP Deployment (Beta)](./docs/HTTP_DEPLOYMENT.md) - Remote server setup -- [Development Guide](./docs/DEVELOPMENT.md) - Contributing and local development +- [Dependency Updates](./docs/DEPENDENCY_UPDATES.md) - Managing n8n dependencies +- [Validation Improvements](./docs/validation-improvements-v2.4.2.md) - Validation system details ### Troubleshooting -- [Common Issues](./docs/TROUBLESHOOTING.md) - Solutions to frequent problems -- [FAQ](./docs/FAQ.md) - Frequently asked questions +- [Change Log](./docs/CHANGELOG.md) - Version history and updates +- [Docker Fixes](./docs/DOCKER_FIX_IMPLEMENTATION.md) - Docker-specific troubleshooting ## 📊 Metrics & Coverage -Current database coverage (n8n v1.97.1): +Current database coverage (n8n v1.99.1): - ✅ **525/525** nodes loaded (100%) - ✅ **520** nodes with properties (99%) diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index c4706f7..b4962ac 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -2,6 +2,100 @@ All notable changes to this project will be documented in this file. +## [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 diff --git a/docs/DOCKER_README.md b/docs/DOCKER_README.md index c09d3e5..7da2f8c 100644 --- a/docs/DOCKER_README.md +++ b/docs/DOCKER_README.md @@ -39,7 +39,7 @@ curl http://localhost:3000/health Pre-built images are available on GitHub Container Registry: ```bash -# Pull the latest image (~150MB optimized) +# Pull the latest image (~280MB optimized) docker pull ghcr.io/czlonkowski/n8n-mcp:latest # Run with HTTP mode @@ -434,7 +434,7 @@ secrets: ### Image Details - Base: `node:20-alpine` -- Size: ~283MB compressed +- Size: ~280MB compressed - Features: Pre-built database with all node information - Database: Complete SQLite with 525+ nodes - Architectures: `linux/amd64`, `linux/arm64` diff --git a/docs/README_CLAUDE_SETUP.md b/docs/README_CLAUDE_SETUP.md index 03499cc..4892c65 100644 --- a/docs/README_CLAUDE_SETUP.md +++ b/docs/README_CLAUDE_SETUP.md @@ -1,6 +1,6 @@ # Claude Desktop Configuration for n8n-MCP -This guide helps you connect n8n-MCP to Claude Desktop, giving Claude comprehensive knowledge about n8n's 525+ workflow automation nodes. +This guide helps you connect n8n-MCP to Claude Desktop, giving Claude comprehensive knowledge about n8n's 525 workflow automation nodes, including 263 AI-capable tools. ## 🎯 Prerequisites @@ -50,14 +50,13 @@ No installation needed - runs directly from Docker: ```json { "mcpServers": { - "n8n-docker": { + "n8n-mcp": { "command": "docker", "args": [ - "run", "--rm", "-i", + "run", "-i", "--rm", "-e", "MCP_MODE=stdio", "-e", "LOG_LEVEL=error", "-e", "DISABLE_CONSOLE_OUTPUT=true", - "-v", "n8n-mcp-data:/app/data", "ghcr.io/czlonkowski/n8n-mcp:latest" ] } @@ -113,23 +112,47 @@ After restarting Claude Desktop: 2. Try asking Claude: "What n8n nodes are available for working with Slack?" 3. Or use a tool directly: "Use the list_nodes tool to show me trigger nodes" -## 🔧 Available Tools +## 🔧 Available Tools (v2.5.1) -Once connected, you can ask Claude to: +### Essential Tool - Start Here! +- **`start_here_workflow_guide`** - Essential guide and best practices (ALWAYS use this first!) -- **List nodes**: "Show me all n8n nodes for working with databases" -- **Get node details**: "How do I use the HTTP Request node?" -- **Search documentation**: "Find n8n nodes that support OAuth" -- **Find AI tools**: "What AI-capable nodes are available?" -- **View statistics**: "Show me n8n-MCP database statistics" +### Core Tools +- **`list_nodes`** - List all n8n nodes with filtering options +- **`get_node_info`** - Get comprehensive information (now includes aiToolCapabilities) +- **`get_node_essentials`** - Get only 10-20 essential properties (95% smaller!) +- **`search_nodes`** - Full-text search across all node documentation +- **`search_node_properties`** - Find specific properties within nodes +- **`get_node_documentation`** - Get parsed documentation from n8n-docs +- **`get_database_statistics`** - View database metrics and coverage -Claude will automatically use the appropriate tools: -- `list_nodes` - Filter and list nodes -- `get_node_info` - Get detailed node information -- `search_nodes` - Full-text search -- `list_ai_tools` - Find AI-capable nodes -- `get_node_documentation` - Get official docs -- `get_database_statistics` - View coverage metrics +### AI Tools (Enhanced in v2.5.1) +- **`list_ai_tools`** - List AI-capable nodes (ANY node can be used as AI tool!) +- **`get_node_as_tool_info`** - Get guidance on using any node as an AI tool + +### Task & Template Tools +- **`get_node_for_task`** - Pre-configured node settings for common tasks +- **`list_tasks`** - Discover available task templates +- **`list_node_templates`** - Find workflow templates using specific nodes +- **`get_template`** - Get complete workflow JSON for import +- **`search_templates`** - Search templates by keywords +- **`get_templates_for_task`** - Get curated templates for common tasks + +### Validation Tools (Professional Grade) +- **`validate_node_operation`** - Smart validation with operation awareness +- **`validate_node_minimal`** - Quick validation for just required fields +- **`validate_workflow`** - Complete workflow validation (validates AI tool connections) +- **`validate_workflow_connections`** - Check workflow structure +- **`validate_workflow_expressions`** - Validate n8n expressions including $fromAI() +- **`get_property_dependencies`** - Analyze property visibility conditions + +### Example Questions to Ask Claude: +- "Show me all n8n nodes for working with databases" +- "How do I use the HTTP Request node?" +- "Get the essentials for Slack node" (uses get_node_essentials) +- "How can I use Google Sheets as an AI tool?" +- "Validate my workflow before deployment" +- "Find templates for webhook automation" ## 🔍 Troubleshooting diff --git a/package.json b/package.json index 418aa5f..d3c76c0 100644 --- a/package.json +++ b/package.json @@ -27,6 +27,10 @@ "test:templates": "node dist/scripts/test-templates.js", "test:workflow-validation": "node dist/scripts/test-workflow-validation.js", "test:template-validation": "node dist/scripts/test-template-validation.js", + "test:essentials": "node dist/scripts/test-essentials.js", + "test:enhanced-validation": "node dist/scripts/test-enhanced-validation.js", + "test:ai-workflow-validation": "node dist/scripts/test-ai-workflow-validation.js", + "test:mcp-tools": "node dist/scripts/test-mcp-tools.js", "db:rebuild": "node dist/scripts/rebuild-database.js", "db:init": "node -e \"new (require('./dist/services/sqlite-storage-service').SQLiteStorageService)(); console.log('Database initialized')\"", "docs:rebuild": "ts-node src/scripts/rebuild-database.ts" diff --git a/scripts/build-optimized.sh b/scripts/build-optimized.sh index dc610bc..cf6695f 100755 --- a/scripts/build-optimized.sh +++ b/scripts/build-optimized.sh @@ -42,8 +42,8 @@ docker run --rm n8n-mcp:latest node -e "console.log('Build OK - Runtime dependen echo "" echo "💰 Size comparison:" echo " Old approach (with n8n deps): ~1.5GB" -echo " New approach (runtime only): ~200MB" -echo " Savings: ~87% smaller!" +echo " New approach (runtime only): ~280MB" +echo " Savings: ~82% smaller!" echo "" echo "✅ Build complete!"