- Remove examples from get_node_essentials responses
- Remove examples from validate_node_operation when errors occur
- Update documentation to reflect removal of examples
- Keep helpful format hints in get_node_for_task (different purpose)
The auto-generated examples were misleading AI agents with incorrect
configurations (e.g., Slack "channel" vs "select" property). Tools
now focus on validation and error messages instead of examples.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Redesigned documentation to be utilitarian and AI-agent focused
- Removed all pleasantries, emojis, and conversational language
- Added concrete numbers throughout (528 nodes, 108 triggers, 264 AI tools)
- Updated all tool descriptions with practical, actionable information
- Enhanced examples with actual return structures and usage patterns
- Made Code node guides prominently featured in overview
- Verified documentation accuracy through extensive testing
- Standardized format across all 30+ tool documentation files
Documentation now optimized for token efficiency while maintaining
clarity and completeness for AI agent consumption.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Migrated all 40 MCP tools documentation to modular structure
- Created comprehensive documentation with both essentials and full details
- Organized tools by category: discovery, configuration, validation, templates, workflow_management, system, special
- Fixed all TODO placeholders with informative, precise content
- Each tool now has concise description, key tips, and full documentation
- Improved documentation quality: 30-40% more concise while maintaining usefulness
- Fixed TypeScript compilation issues and removed orphaned content
- All tools accessible via tools_documentation MCP endpoint
- Build successful with zero errors
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Fixed docker-entrypoint.sh to use NODE_DB_PATH instead of hardcoded paths
- Added log_message() helper to prevent stdio mode output corruption
- Fixed directory creation race condition with proper ownership
- Added path validation to ensure NODE_DB_PATH ends with .db
- Updated rebuild.ts to respect NODE_DB_PATH environment variable
- Added comprehensive documentation for custom database paths
- Bumped version to 2.7.16
The bug was caused by hardcoded /app/data/nodes.db paths in the Docker
entrypoint script that ignored the NODE_DB_PATH environment variable.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add intelligent URL detection supporting BASE_URL, PUBLIC_URL, and proxy headers
- Fix hardcoded localhost URLs in server console output
- Add hostname validation to prevent host header injection attacks
- Restrict URL schemes to http/https only (block javascript:, file://, etc.)
- Remove sensitive environment data from API responses
- Add GET endpoints (/, /mcp) for better API discovery
- Fix version inconsistency between server implementations
- Update HTTP bridge to use HOST/PORT environment variables
- Add comprehensive test scripts for URL configuration and security
This resolves issues #41 and #42 by making the HTTP server properly handle
deployment behind reverse proxies and adds critical security validations.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Remove default settings logic from cleanWorkflowForUpdate that was causing
"settings must NOT have additional properties" error
- The function now only removes read-only fields without adding any properties
- Add comprehensive test coverage in test-issue-45-fix.ts
- Add documentation explaining the difference between create and update functions
- Bump version to 2.7.14
This fixes the issue where n8n_update_partial_workflow would pass validation
but fail during execution when workflows didn't have settings defined.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Enhanced database adapter to support multiple WASM file resolution strategies
- Added require.resolve() for reliable package location in npm environments
- Made better-sqlite3 an optional dependency
- Improved error handling with clear messages
- Updated version to 2.7.13
- Updated CHANGELOG and README badges
- Database now contains 499 templates (was 399)
- FTS5 index properly populated with all template entries
- Fixed quote escaping in FTS5 queries to prevent syntax errors
- Verified FTS5 search returns correct results (162 for "webhook")
- Fixes template search in Docker deployments
The previous database had empty FTS5 tables causing search to fail.
This update ensures the FTS5 index is properly synchronized and
handles special characters in search queries.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add FTS5 pre-creation in fetch-templates.ts before data import
- Create prebuild-fts5.ts script to ensure FTS5 tables exist
- Improve logging in template-repository.ts for better debugging
- Add npm script 'prebuild:fts5' for manual FTS5 setup
This ensures template search works consistently in Docker mode
where runtime FTS5 table creation might fail due to permissions.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Added runtime FTS5 detection in database adapters
- Removed FTS5 from required schema to prevent "no such module" errors
- FTS5 tables/triggers created conditionally only if supported
- Template search automatically falls back to LIKE when FTS5 unavailable
- Works in ALL SQLite environments (Claude Desktop, restricted envs, etc.)
This ensures search_templates() works correctly regardless of SQLite build,
while still providing optimal performance when FTS5 is available.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Reduced average description length from 250-450 to 93-129 chars
- Documentation tools now average 129 chars per description
- Management tools average just 93 chars per description
- Moved detailed documentation to tools_documentation() system
- Only 2 tools exceed 200 chars (necessarily verbose)
Also includes search_nodes improvements:
- Fixed primary node ranking (webhook, HTTP Request now appear first)
- Fixed FUZZY mode threshold for better typo tolerance
- Removed unnecessary searchInfo messages
- Fixed HTTP node type case sensitivity issue
This significantly improves AI agent performance by reducing context usage
while preserving all essential information.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Critical fixes based on Claude Desktop feedback:
1. Fixed crypto documentation: require('crypto') IS available despite editor warnings
- Added clear examples of crypto usage
- Updated validation to guide correct require() usage
2. Clarified $helpers vs standalone functions
- $getWorkflowStaticData() is standalone, NOT $helpers.getWorkflowStaticData()
- Added validation to catch incorrect usage (prevents '$helpers is not defined' errors)
- Enhanced examples showing proper $helpers availability checks
3. Fixed JMESPath numeric literal documentation
- n8n requires backticks around numbers in filters: [?age >= `18`]
- Added multiple examples and validation to detect missing backticks
- Prevents 'JMESPath syntax error' that Claude Desktop encountered
4. Fixed webhook data access gotcha
- Webhook payload is at items[0].json.body, NOT items[0].json
- Added dedicated 'Webhook Data Access' section with clear examples
- Created process_webhook_data task template
- Added validation to detect incorrect webhook data access patterns
All fixes based on production workflows TaNqYoZNNeHC4Hne and JZ9urD7PNClDZ1bm
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Root cause: AI agents were placing error handling properties inside `parameters` instead of at node level
Major changes:
- Enhanced workflow validator to check for ALL node-level properties (expanded from 6 to 11)
- Added validation for onError property values and deprecation warnings for continueOnFail
- Updated all examples to use modern error handling (onError instead of continueOnFail)
- Added comprehensive node-level properties documentation in tools_documentation
- Enhanced MCP tool documentation for n8n_create_workflow and n8n_update_partial_workflow
- Added test script demonstrating correct node-level property usage
Node-level properties now validated:
- credentials, disabled, notes, notesInFlow, executeOnce
- onError, retryOnFail, maxTries, waitBetweenTries, alwaysOutputData
- continueOnFail (deprecated)
Validation improvements:
- Detects misplaced properties and provides clear fix examples
- Shows complete node structure when properties are incorrectly placed
- Type validation for all node-level boolean and string properties
- Smart error messages with correct placement guidance
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Added specific error reasons for auth failures: no_auth_header, invalid_auth_format, invalid_token
- Fixed AUTH_TOKEN_FILE support in Docker production stacks (issue #16)
- Added AUTH_TOKEN_FILE support to single-session HTTP server for consistency
- Enhanced security by removing token lengths from logs
- Added token trimming and empty token validation
- Updated Docker entrypoint to properly support AUTH_TOKEN_FILE
- Bumped version to 2.7.10
This improves debugging for mcp-remote authentication issues and enables
proper Docker secrets usage in production environments.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add bin configuration to package.json for npx execution
- Implement smart database path resolution for npx/global/local installs
- Create dedicated npm publish script using runtime-only dependencies
- Add .npmignore to control published package contents
- Update README with npx as primary installation method
- Add n8n version badge to README
- Sync version between package.json and package.runtime.json
- Update CHANGELOG for v2.7.8 release
This allows users to run 'npx n8n-mcp' without installing the package,
reducing friction and making it easier to get started with n8n-MCP.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add TRUST_PROXY environment variable to enable proxy header trust
- Configure Express trust proxy in both HTTP server implementations
- Fix issue #19: Docker internal IPs logged instead of real client IPs
- Update documentation with reverse proxy configuration guide
- Add examples for nginx proxy header forwarding
- Maintain backward compatibility (disabled by default)
When TRUST_PROXY=1 is set, the server will correctly log client IPs
from X-Forwarded-For headers instead of proxy/container IPs.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add AUTH_TOKEN_FILE environment variable support for reading auth tokens from files
- Support Docker secrets pattern for production deployments
- Add Known Issues section documenting Claude Desktop container duplication bug
- Update documentation with authentication options and best practices
- Fix issue #16: AUTH_TOKEN_FILE was documented but not implemented
- Add comprehensive tests for AUTH_TOKEN_FILE functionality
BREAKING CHANGE: None - AUTH_TOKEN continues to work as before
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Remove hardcoded API key and URL from debug-n8n-auth.ts
- Require environment variables with proper validation
- Add comprehensive SECURITY.md with best practices
- Address security concerns raised in issue #18
The SecureKeyGuard alert was a false positive (mistaking "validate_workflow"
for "VAULT_TOKEN"), but the review uncovered actual hardcoded credentials
that have now been removed.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fixed issue where Docker images using sql.js adapter returned boolean fields
as strings, causing is_trigger=0 to evaluate as true instead of false.
Changes:
- Added convertIntegerColumns() to sql.js adapter to convert SQLite integers
- Updated server.ts and node-repository.ts to use Number() conversion as backup
- Added test script to verify fix works with sql.js adapter
This fixes webhook, cron, interval, and emailReadImap nodes showing
isTrigger: false in Docker deployments.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Update rebuild script to automatically sanitize templates after node processing
- Update documentation to reflect GitHub push protection changes
- Add notes about template sanitization in n8n update process
- Ensures databases are always clean before push
This prevents GitHub push protection from blocking database updates
due to API tokens in workflow templates.
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
- Add TemplateSanitizer utility class for detecting and replacing API tokens
- Update template repository to automatically sanitize on save
- Add sanitize:templates command to clean existing templates
- Uses pattern matching to detect various API token formats
- Fixes GitHub push protection blocking database updates
Note: Database will be updated separately after code is deployed
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
- Removed unused empty nodes-v2.db file
- Updated NodeDocumentationService to use nodes.db as default
- Updated test file to use correct database
- Added secret scanning exclusion for database files
This prevents confusion about which database is actually used and removes
the file that GitHub's security advisor was flagging.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Updated trigger detection logic in both parsers to check if a node's group array includes 'trigger'. This fixes an issue where webhook, cron, interval, and emailReadImap nodes were not being identified as triggers despite having category='trigger'.
Note: After pulling this change, run `npm run rebuild` to update your local database.
Fixes#13🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Renamed start_here_workflow_guide to tools_documentation for clarity
- Added depth parameter to control documentation detail (essentials/full)
- Converted output from JSON to LLM-friendly plain text format
- Added per-tool documentation capability
- Created two-tier documentation system:
- Essentials: brief info with key parameters and tips
- Full: comprehensive docs with examples and best practices
- Documented 8 commonly used MCP tools
- Removed 380+ lines of unused getWorkflowGuide method
- Fixed duplicate tool definitions
- Updated all documentation references
- Added test script for tools documentation
BREAKING CHANGE: start_here_workflow_guide renamed to tools_documentation
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Added warning about experimental remote server deployment
- Clarified HTTP bridge architecture in documentation
- Added deployment scenarios section explaining local vs remote options
- Enhanced troubleshooting with bridge-specific issues
- Created http-bridge.js for local HTTP testing
- Fixed HTTP server to include management tools in tools/list
The documentation now clearly explains:
- Why "node" command is used instead of "docker" (stdio bridge requirement)
- Three deployment scenarios with pros/cons
- How to test locally with Docker
- Bridge architecture (Claude Desktop → bridge → HTTP server)
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Implement dynamic n8n API configuration checking
- Remove static config export in favor of lazy getter function
- Fix management tools not being registered when env vars set after startup
- Optimize logger performance with cached environment variables
- Clean up debug logging and remove console.error usage
- Bump version to 2.7.1
This ensures all 38 tools (22 documentation + 16 management) are properly
registered regardless of when environment variables become available.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Updated n8n from 1.99.1 to 1.100.1
- Updated n8n-core from 1.98.0 to 1.99.0
- Updated n8n-workflow from 1.96.0 to 1.97.0
- Updated @n8n/n8n-nodes-langchain from 1.98.1 to 1.99.0
- Fixed node loader path for n8n-nodes-base
- Rebuilt node database with 526 nodes
- All validation tests passing
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Updates the protocol version from '1.0' to the current MCP specification version '2024-11-05'.
This resolves compatibility issues with modern MCP clients and ensures proper protocol negotiation.
- Commented out console.log statements that were interfering with JSON-RPC communication
- Fixed Claude Desktop errors for list_nodes and list_ai_tools
- All stdout in MCP servers must be valid JSON messages
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Removed ~965MB of temporary directories (temp/, extracted-nodes/, etc)
- Deleted outdated database files and backups (.bak files)
- Removed legacy shell scripts (mcp-server-v20.sh, rebuild-v20.sh)
- Cleaned up orphan test files and debugging scripts
- Removed duplicate schema file (src/db/schema.sql)
- Deleted old Dockerfile.old and empty database files
- Updated documentation structure in README.md
- Added n8n_diagnostic tool to documentation
- Condensed version history in CLAUDE.md
- Created release notes for v2.7.0
Total impact: Removed 34 files, saving ~965MB+ of disk space
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Renamed files to remove unnecessary suffixes:
- tools-update.ts → tools.ts
- server-update.ts → server.ts
- http-server-fixed.ts → http-server.ts
- Created version utility to read from package.json as single source of truth
- Updated all imports across 21+ files
- Removed legacy files:
- src/http-server.ts (legacy HTTP server with known issues)
- src/utils/n8n-client.ts (unused legacy API client)
- Added n8n_diagnostic tool to help troubleshoot management tools visibility
- Added script to sync package.runtime.json version
- Fixed version mismatch issue (was hardcoded 2.4.1, now reads 2.7.0 from package.json)
This addresses GitHub issue #5 regarding version mismatch and provides better diagnostics for users.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
BREAKING CHANGES:
- Renamed n8n_update_workflow to n8n_update_full_workflow for clarity
NEW FEATURES:
- Added n8n_update_partial_workflow tool for diff-based workflow editing
- Implemented WorkflowDiffEngine with 13 operation types
- Added transactional updates with two-pass processing
- Maximum 5 operations per request for reliability
- Operations can be in any order - engine handles dependencies
- Added validateOnly mode for testing changes before applying
- 80-90% token savings by only sending changes
IMPROVEMENTS:
- Enhanced tool description with comprehensive parameter documentation
- Added clear examples for simple and complex use cases
- Improved error messages and validation
- Added extensive test coverage for all operations
DOCUMENTATION:
- Added workflow-diff-examples.md with usage patterns
- Added transactional-updates-example.md showing before/after
- Updated README.md with v2.7.0 features
- Updated CLAUDE.md with latest changes
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- NEW: n8n_validate_workflow tool to validate workflows from n8n instance by ID
- Fetches workflow via API and runs comprehensive validation
- Uses existing WorkflowValidator for consistency
- Supports all validation profiles and options
- Updated start_here tool with new workflow lifecycle info
- Updated README with new tool documentation
- Updated Claude Project Setup instructions
This completes the workflow lifecycle management:
discover → build → validate → deploy → execute → monitor
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add node type existence validation that catches invalid types
- Fix critical issue: now catches 'nodes-base.webhook' BEFORE database lookup
- Add smart suggestions for common mistakes (webhook → n8n-nodes-base.webhook)
- Add minimum viable workflow validation (prevents single-node workflows)
- Add empty connection detection for multi-node workflows
- Add helper functions for workflow structure examples and fix suggestions
- Prevent AI agents from creating workflows with question mark nodes
This fixes the exact issue where workflows created with 'nodes-base.webhook'
would show as broken (question marks) in the n8n UI.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Enhanced workflow validator to enforce typeVersion on versioned nodes
- Returns errors for missing typeVersion with suggested version to add
- Warns about outdated typeVersion values
- Prevents invalid typeVersion (zero, negative, or exceeding maximum)
- Added comprehensive test script for typeVersion validation
- Helps AI agents avoid common workflow creation mistakes
This ensures workflows always use compatible node versions before deployment.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Added complete workflow lifecycle documentation (Discover → Build → Validate → Deploy → Execute)
- Added new 'n8n_management' topic with comprehensive guide for all 14 management tools
- Documented API requirements, limitations, and best practices
- Added examples showing integration between documentation and management tools
- Included debug script for troubleshooting n8n API authentication
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add comprehensive AI tools guide in start_here_workflow_guide
- New 'ai_tools' topic with detailed AI workflow patterns
- Key insight: ANY node can be used as an AI tool
- $fromAI() expression examples and best practices
- AI tool connection validation guidance
- Update recommended workflow to include validate_node_minimal
- Quick required fields check before full validation
- Performance tips for validation tools
- Enhance Claude Project Setup instructions
- Clear 5-phase workflow process
- Emphasis on AI tool integration
- Validation best practices
- Better tool usage examples
- Add validation_guide section to workflow guide
- When to use each validation tool
- Performance considerations
- AI workflow validation patterns
These updates make it much clearer how to use the MCP tools effectively,
especially for AI workflows where ANY node can be connected as a tool.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Update tool descriptions to clarify ANY node can be used as AI tool
- Add get_node_as_tool_info to available tools in README
- Enhance workflow validation tool descriptions for AI connections
- Update README with v2.5.1 release notes
- Remove redundant _General__Scrape_with_HTTP_tool.json file
- Bump version to 2.5.1 in package.json
The key insight: ANY n8n node can be connected to an AI Agent's tool
port, not just those marked with usableAsTool=true. This update makes
that clear throughout the documentation and tool descriptions.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Phase 2 Professional Validation Features:
1. Validation Profiles:
- minimal: Only required fields
- runtime: Critical errors + security warnings
- ai-friendly: Balanced (default)
- strict: All checks + best practices
2. New Node Validators:
- Webhook: Path validation, response modes, auth warnings
- PostgreSQL: SQL injection detection, query safety
- MySQL: Similar to Postgres with MySQL-specific checks
3. New Tools:
- validate_node_minimal: Lightning-fast required field checking
- Updated validate_node_operation with profile support
4. SQL Safety Features:
- Detects template expressions vulnerable to injection
- Warns about DELETE/UPDATE without WHERE
- Catches dangerous operations (DROP, TRUNCATE)
- Suggests parameterized queries
5. Enhanced Coverage:
- Now supports 7+ major nodes with specific validators
- Flexible validation based on use case
- Professional-grade safety checks
This completes the major validation system overhaul from the original plan.
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
- Filter out @version and internal properties from warnings
- Deduplicate validation errors (keep most specific message)
- Add basic code syntax validation for JavaScript and Python
- Check for unbalanced braces/parentheses
- Validate Python indentation consistency
- Add n8n-specific pattern checks (return statements, input access)
- Bump version to 2.4.2
Based on comprehensive AI agent review showing 9.5/10 rating
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
- Add validate_node_operation tool with 80%+ fewer false positives
- Remove deprecated validate_node_config tool
- Add EnhancedConfigValidator with operation context filtering
- Add node-specific validators for Slack, Google Sheets, OpenAI, MongoDB
- Integrate working examples in validation responses
- Add actionable next steps and auto-fix suggestions
- Test shows Slack validation reduced from 45 errors to 1 error\!
BREAKING CHANGE: validate_node_config removed in favor of validate_node_operation
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
