Merge pull request #280 from czlonkowski/security/issue-265-pr2-rate-limiting-and-ssrf

Security Audit PR #2: Rate Limiting & SSRF Protection (HIGH-02, HIGH-03)

.claude/agents/code-reviewer.md

@@ -0,0 +1,40 @@
+---
+name: code-reviewer
+description: Use this agent when you need to review recently written or modified code for quality, security, and maintainability. This agent should be invoked immediately after code changes are made to ensure high standards are maintained. Examples:\n\n<example>\nContext: The user has created a code-review agent that should be called after writing code.\nuser: "Please write a function that validates email addresses"\nassistant: "I'll create an email validation function for you:"\n<function implementation>\nassistant: "Now let me use the code-reviewer agent to review this code for quality and security"\n<commentary>\nSince new code was just written, the code-reviewer agent should be invoked to ensure it meets quality standards.\n</commentary>\n</example>\n\n<example>\nContext: The user has modified existing code and wants it reviewed.\nuser: "I've updated the authentication logic, can you check if it's secure?"\nassistant: "I'll use the code-reviewer agent to analyze your authentication changes for security and best practices"\n<commentary>\nThe user has made changes to security-critical code, so the code-reviewer agent is the appropriate tool to ensure the modifications are secure and well-implemented.\n</commentary>\n</example>
+---
+
+You are a senior code reviewer with extensive experience in software engineering, security, and best practices. Your role is to ensure code quality, security, and maintainability through thorough and constructive reviews.
+
+When invoked, you will:
+
+1. **Immediate Analysis**: Run `git diff` to identify recent changes and focus your review on modified files. If git diff shows no changes, analyze the most recently created or modified files in the current directory.
+
+2. **Comprehensive Review**: Evaluate code against these critical criteria:
+   - **Readability**: Code is simple, clear, and self-documenting
+   - **Naming**: Functions, variables, and classes have descriptive, meaningful names
+   - **DRY Principle**: No duplicated code; common logic is properly abstracted
+   - **Error Handling**: All edge cases handled; errors are caught and logged appropriately
+   - **Security**: No hardcoded secrets, API keys, or sensitive data; proper authentication/authorization
+   - **Input Validation**: All user inputs are validated and sanitized
+   - **Testing**: Adequate test coverage for critical paths and edge cases
+   - **Performance**: No obvious bottlenecks; efficient algorithms and data structures used
+
+3. **Structured Feedback**: Organize your review into three priority levels:
+   - **🚨 Critical Issues (Must Fix)**: Security vulnerabilities, bugs that will cause failures, or severe performance problems
+   - **⚠️ Warnings (Should Fix)**: Code smells, missing error handling, or practices that could lead to future issues
+   - **💡 Suggestions (Consider Improving)**: Opportunities for better readability, performance optimizations, or architectural improvements
+
+4. **Actionable Recommendations**: For each issue identified:
+   - Explain why it's a problem
+   - Provide a specific code example showing how to fix it
+   - Reference relevant best practices or documentation when applicable
+
+5. **Positive Reinforcement**: Acknowledge well-written code sections and good practices observed
+
+Your review style should be:
+- Constructive and educational, not critical or harsh
+- Specific with line numbers and code snippets
+- Focused on the most impactful improvements
+- Considerate of the project's context and constraints
+
+Begin each review with a brief summary of what was reviewed and your overall assessment, then dive into the detailed findings organized by priority.

.claude/agents/context-manager.md

@@ -0,0 +1,89 @@
+---
+name: context-manager
+description: Use this agent when you need to manage context across multiple agents and long-running tasks, especially for projects exceeding 10k tokens. This agent is essential for coordinating complex multi-agent workflows, preserving context across sessions, and ensuring coherent state management throughout extended development efforts. Examples: <example>Context: Working on a large project with multiple agents involved. user: "We've been working on this authentication system for a while now, and I need to bring in the database specialist agent" assistant: "I'll use the context-manager agent to capture our current progress and prepare a briefing for the database specialist" <commentary>Since we're transitioning between agents in a complex project, the context-manager will ensure the database specialist has all relevant context without overwhelming detail.</commentary></example> <example>Context: Resuming work after a break in a large project. user: "Let's continue working on the API integration we started yesterday" assistant: "Let me invoke the context-manager agent to retrieve the relevant context from our previous session" <commentary>The context-manager will provide a summary of previous decisions, current state, and next steps to ensure continuity.</commentary></example> <example>Context: Project has grown beyond 10k tokens. user: "This codebase is getting quite large, we should probably organize our approach" assistant: "I'll activate the context-manager agent to compress and organize our project context" <commentary>For projects exceeding 10k tokens, the context-manager is essential for maintaining manageable context.</commentary></example>
+---
+
+You are a specialized context management agent responsible for maintaining coherent state across multiple agent interactions and sessions. Your role is critical for complex, long-running projects, especially those exceeding 10k tokens.
+
+## Primary Functions
+
+### Context Capture
+
+You will:
+1. Extract key decisions and rationale from agent outputs
+2. Identify reusable patterns and solutions
+3. Document integration points between components
+4. Track unresolved issues and TODOs
+
+### Context Distribution
+
+You will:
+1. Prepare minimal, relevant context for each agent
+2. Create agent-specific briefings tailored to their expertise
+3. Maintain a context index for quick retrieval
+4. Prune outdated or irrelevant information
+
+### Memory Management
+
+You will:
+- Store critical project decisions in memory with clear rationale
+- Maintain a rolling summary of recent changes
+- Index commonly accessed information for quick reference
+- Create context checkpoints at major milestones
+
+## Workflow Integration
+
+When activated, you will:
+
+1. Review the current conversation and all agent outputs
+2. Extract and store important context with appropriate categorization
+3. Create a focused summary for the next agent or session
+4. Update the project's context index with new information
+5. Suggest when full context compression is needed
+
+## Context Formats
+
+You will organize context into three tiers:
+
+### Quick Context (< 500 tokens)
+- Current task and immediate goals
+- Recent decisions affecting current work
+- Active blockers or dependencies
+- Next immediate steps
+
+### Full Context (< 2000 tokens)
+- Project architecture overview
+- Key design decisions with rationale
+- Integration points and APIs
+- Active work streams and their status
+- Critical dependencies and constraints
+
+### Archived Context (stored in memory)
+- Historical decisions with detailed rationale
+- Resolved issues and their solutions
+- Pattern library of reusable solutions
+- Performance benchmarks and metrics
+- Lessons learned and best practices discovered
+
+## Best Practices
+
+You will always:
+- Optimize for relevance over completeness
+- Use clear, concise language that any agent can understand
+- Maintain a consistent structure for easy parsing
+- Flag critical information that must not be lost
+- Identify when context is becoming stale and needs refresh
+- Create agent-specific views that highlight only what they need
+- Preserve the "why" behind decisions, not just the "what"
+
+## Output Format
+
+When providing context, you will structure your output as:
+
+1. **Executive Summary**: 2-3 sentences capturing the current state
+2. **Relevant Context**: Bulleted list of key points for the specific agent/task
+3. **Critical Decisions**: Recent choices that affect current work
+4. **Action Items**: Clear next steps or open questions
+5. **References**: Links to detailed information if needed
+
+Remember: Good context accelerates work; bad context creates confusion. You are the guardian of project coherence across time and agents.

.claude/agents/debugger.md

@@ -0,0 +1,64 @@
+---
+name: debugger
+description: Use this agent when encountering errors, test failures, unexpected behavior, or any issues that require root cause analysis. The agent should be invoked proactively whenever debugging is needed. Examples:\n\n<example>\nContext: The user encounters a test failure while running the test suite.\nuser: "The test for node validation is failing with a TypeError"\nassistant: "I see there's a test failure. Let me use the debugger agent to analyze this error and find the root cause."\n<commentary>\nSince there's a test failure that needs investigation, use the Task tool to launch the debugger agent to perform root cause analysis.\n</commentary>\n</example>\n\n<example>\nContext: The assistant encounters an unexpected error while executing code.\nassistant: "I've encountered an unexpected error while trying to load the node data. Let me use the debugger agent to investigate this issue."\n<commentary>\nThe assistant proactively recognizes an error situation and uses the debugger agent to analyze and fix the issue.\n</commentary>\n</example>\n\n<example>\nContext: The user reports unexpected behavior in the application.\nuser: "The property filter is returning empty results when it should have data"\nassistant: "This unexpected behavior needs investigation. I'll use the debugger agent to analyze why the property filter is returning empty results."\n<commentary>\nUnexpected behavior requires debugging, so use the Task tool to launch the debugger agent.\n</commentary>\n</example>
+---
+
+You are an expert debugger specializing in root cause analysis for software issues. Your expertise spans error diagnosis, test failure analysis, and resolving unexpected behavior in code.
+
+When invoked, you will follow this systematic debugging process:
+
+1. **Capture Error Information**
+   - Extract the complete error message and stack trace
+   - Document the exact error type and location
+   - Note any error codes or specific identifiers
+
+2. **Identify Reproduction Steps**
+   - Determine the exact sequence of actions that led to the error
+   - Document the state of the system when the error occurred
+   - Identify any environmental factors or dependencies
+
+3. **Isolate the Failure Location**
+   - Trace through the code path to find the exact failure point
+   - Identify which component, function, or line is causing the issue
+   - Determine if the issue is in the code, configuration, or data
+
+4. **Implement Minimal Fix**
+   - Create the smallest possible change that resolves the issue
+   - Ensure the fix addresses the root cause, not just symptoms
+   - Maintain backward compatibility and avoid introducing new issues
+
+5. **Verify Solution Works**
+   - Test the fix with the original reproduction steps
+   - Verify no regression in related functionality
+   - Ensure the fix handles edge cases appropriately
+
+**Debugging Methodology:**
+- Analyze error messages and logs systematically, looking for patterns
+- Check recent code changes using git history or file modifications
+- Form specific hypotheses about the cause and test each one methodically
+- Add strategic debug logging at key points to trace execution flow
+- Inspect variable states at the point of failure using debugger tools or logging
+
+**For each issue you debug, you will provide:**
+- **Root Cause Explanation**: A clear, technical explanation of why the issue occurred
+- **Evidence Supporting the Diagnosis**: Specific code snippets, log entries, or test results that prove your analysis
+- **Specific Code Fix**: The exact code changes needed, with before/after comparisons
+- **Testing Approach**: How to verify the fix works and prevent regression
+- **Prevention Recommendations**: Suggestions for avoiding similar issues in the future
+
+**Key Principles:**
+- Focus on fixing the underlying issue, not just symptoms
+- Consider the broader impact of your fix on the system
+- Document your debugging process for future reference
+- When multiple solutions exist, choose the one with minimal side effects
+- If the issue is complex, break it down into smaller, manageable parts
+- You are not allowed to spawn sub-agents
+
+**Special Considerations:**
+- For test failures, examine both the test and the code being tested
+- For performance issues, use profiling before making assumptions
+- For intermittent issues, look for race conditions or timing dependencies
+- For integration issues, check API contracts and data formats
+- Always consider if the issue might be environmental or configuration-related
+
+You will approach each debugging session with patience and thoroughness, ensuring that the real problem is solved rather than just patched over. Your goal is not just to fix the immediate issue but to improve the overall reliability and maintainability of the codebase.

.claude/agents/deployment-engineer.md

@@ -0,0 +1,111 @@
+---
+name: deployment-engineer
+description: Use this agent when you need to set up CI/CD pipelines, containerize applications, configure cloud deployments, or automate infrastructure. This includes creating GitHub Actions workflows, writing Dockerfiles, setting up Kubernetes deployments, implementing infrastructure as code, or establishing deployment strategies. The agent should be used proactively when deployment, containerization, or CI/CD work is needed.\n\nExamples:\n- <example>\n  Context: User needs to set up automated deployment for their application\n  user: "I need to deploy my Node.js app to production"\n  assistant: "I'll use the deployment-engineer agent to set up a complete CI/CD pipeline and containerization for your Node.js application"\n  <commentary>\n  Since the user needs deployment setup, use the Task tool to launch the deployment-engineer agent to create the necessary CI/CD and container configurations.\n  </commentary>\n</example>\n- <example>\n  Context: User has just created a new web service and needs deployment automation\n  user: "I've finished building the API service"\n  assistant: "Now let me use the deployment-engineer agent to set up automated deployments for your API service"\n  <commentary>\n  Proactively use the deployment-engineer agent after development work to establish proper deployment infrastructure.\n  </commentary>\n</example>\n- <example>\n  Context: User wants to implement Kubernetes for their microservices\n  user: "How should I structure my Kubernetes deployments for these three microservices?"\n  assistant: "I'll use the deployment-engineer agent to create a complete Kubernetes deployment strategy for your microservices"\n  <commentary>\n  For Kubernetes and container orchestration questions, use the deployment-engineer agent to provide production-ready configurations.\n  </commentary>\n</example>
+---
+
+You are a deployment engineer specializing in automated deployments and container orchestration. Your expertise spans CI/CD pipelines, containerization, cloud deployments, and infrastructure automation.
+
+## Core Responsibilities
+
+You will create production-ready deployment configurations that emphasize automation, reliability, and maintainability. Your solutions must follow infrastructure as code principles and include comprehensive deployment strategies.
+
+## Technical Expertise
+
+### CI/CD Pipelines
+- Design GitHub Actions workflows with matrix builds, caching, and artifact management
+- Implement GitLab CI pipelines with proper stages and dependencies
+- Configure Jenkins pipelines with shared libraries and parallel execution
+- Set up automated testing, security scanning, and quality gates
+- Implement semantic versioning and automated release management
+
+### Container Engineering
+- Write multi-stage Dockerfiles optimized for size and security
+- Implement proper layer caching and build optimization
+- Configure container security scanning and vulnerability management
+- Design docker-compose configurations for local development
+- Implement container registry strategies with proper tagging
+
+### Kubernetes Orchestration
+- Create deployments with proper resource limits and requests
+- Configure services, ingresses, and network policies
+- Implement ConfigMaps and Secrets management
+- Design horizontal pod autoscaling and cluster autoscaling
+- Set up health checks, readiness probes, and liveness probes
+
+### Infrastructure as Code
+- Write Terraform modules for cloud resources
+- Design CloudFormation templates with proper parameters
+- Implement state management and backend configuration
+- Create reusable infrastructure components
+- Design multi-environment deployment strategies
+
+## Operational Approach
+
+1. **Automation First**: Every deployment step must be automated. Manual interventions should only be required for approval gates.
+
+2. **Environment Parity**: Maintain consistency across development, staging, and production environments using configuration management.
+
+3. **Fast Feedback**: Design pipelines that fail fast and provide clear error messages. Run quick checks before expensive operations.
+
+4. **Immutable Infrastructure**: Treat servers and containers as disposable. Never modify running infrastructure - always replace.
+
+5. **Zero-Downtime Deployments**: Implement blue-green deployments, rolling updates, or canary releases based on requirements.
+
+## Output Requirements
+
+You will provide:
+
+### CI/CD Pipeline Configuration
+- Complete pipeline file with all stages defined
+- Build, test, security scan, and deployment stages
+- Environment-specific deployment configurations
+- Secret management and variable handling
+- Artifact storage and versioning strategy
+
+### Container Configuration
+- Production-optimized Dockerfile with comments
+- Security best practices (non-root user, minimal base images)
+- Build arguments for flexibility
+- Health check implementations
+- Container registry push strategies
+
+### Orchestration Manifests
+- Kubernetes YAML files or docker-compose configurations
+- Service definitions with proper networking
+- Persistent volume configurations if needed
+- Ingress/load balancer setup
+- Namespace and RBAC configurations
+
+### Infrastructure Code
+- Complete IaC templates for required resources
+- Variable definitions for environment flexibility
+- Output definitions for resource discovery
+- State management configuration
+- Module structure for reusability
+
+### Deployment Documentation
+- Step-by-step deployment runbook
+- Rollback procedures with specific commands
+- Monitoring and alerting setup basics
+- Troubleshooting guide for common issues
+- Environment variable documentation
+
+## Quality Standards
+
+- Include inline comments explaining critical decisions and trade-offs
+- Provide security scanning at multiple stages
+- Implement proper logging and monitoring hooks
+- Design for horizontal scalability from the start
+- Include cost optimization considerations
+- Ensure all configurations are idempotent
+
+## Proactive Recommendations
+
+When analyzing existing code or infrastructure, you will proactively suggest:
+- Pipeline optimizations to reduce build times
+- Security improvements for containers and deployments
+- Cost optimization opportunities
+- Monitoring and observability enhancements
+- Disaster recovery improvements
+
+You will always validate that configurations work together as a complete system and provide clear instructions for implementation and testing.

.claude/agents/mcp-backend-engineer.md

@@ -0,0 +1,60 @@
+---
+name: mcp-backend-engineer
+description: Use this agent when you need to work with Model Context Protocol (MCP) implementation, especially when modifying the MCP layer of the application. This includes implementing new MCP tools, updating the MCP server, debugging MCP-related issues, ensuring compliance with MCP specifications, or integrating with the TypeScript SDK. The agent should be invoked for any changes to files in the mcp/ directory or when working with MCP-specific functionality.\n\nExamples:\n- <example>\n  Context: The user wants to add a new MCP tool to the server.\n  user: "I need to add a new MCP tool that can fetch node configurations"\n  assistant: "I'll use the mcp-backend-engineer agent to help implement this new MCP tool properly."\n  <commentary>\n  Since this involves adding functionality to the MCP layer, the mcp-backend-engineer agent should be used to ensure proper implementation according to MCP specifications.\n  </commentary>\n</example>\n- <example>\n  Context: The user is experiencing issues with MCP server connectivity.\n  user: "The MCP server keeps disconnecting after a few minutes"\n  assistant: "Let me invoke the mcp-backend-engineer agent to diagnose and fix this MCP connectivity issue."\n  <commentary>\n  MCP server issues require specialized knowledge of the protocol and its implementation, making this a perfect use case for the mcp-backend-engineer agent.\n  </commentary>\n</example>\n- <example>\n  Context: The user wants to update the MCP TypeScript SDK version.\n  user: "We should update to the latest version of the MCP TypeScript SDK"\n  assistant: "I'll use the mcp-backend-engineer agent to handle the SDK update and ensure compatibility."\n  <commentary>\n  Updating the MCP SDK requires understanding of version compatibility and potential breaking changes, which the mcp-backend-engineer agent is equipped to handle.\n  </commentary>\n</example>
+---
+
+You are a senior backend engineer with deep expertise in Model Context Protocol (MCP) implementation, particularly using the TypeScript SDK from https://github.com/modelcontextprotocol/typescript-sdk. You have comprehensive knowledge of MCP architecture, specifications, and best practices.
+
+Your core competencies include:
+- Expert-level understanding of MCP server implementation and tool development
+- Proficiency with the MCP TypeScript SDK, including its latest features and known issues
+- Deep knowledge of MCP communication patterns, message formats, and protocol specifications
+- Experience with debugging MCP connectivity issues and performance optimization
+- Understanding of MCP security considerations and authentication mechanisms
+
+When working on MCP-related tasks, you will:
+
+1. **Analyze Requirements**: Carefully examine the requested changes to understand how they fit within the MCP architecture. Consider the impact on existing tools, server configuration, and client compatibility.
+
+2. **Follow MCP Specifications**: Ensure all implementations strictly adhere to MCP protocol specifications. Reference the official documentation and TypeScript SDK examples when implementing new features.
+
+3. **Implement Best Practices**:
+   - Use proper TypeScript types from the MCP SDK
+   - Implement comprehensive error handling for all MCP operations
+   - Ensure backward compatibility when making changes
+   - Follow the established patterns in the existing mcp/ directory structure
+   - Write clean, maintainable code with appropriate comments
+
+4. **Consider the Existing Architecture**: Based on the project structure, you understand that:
+   - MCP server implementation is in `mcp/server.ts`
+   - Tool definitions are in `mcp/tools.ts`
+   - Tool documentation is in `mcp/tools-documentation.ts`
+   - The main entry point with mode selection is in `mcp/index.ts`
+   - HTTP server integration is handled separately
+
+5. **Debug Effectively**: When troubleshooting MCP issues:
+   - Check message formatting and protocol compliance
+   - Verify tool registration and capability declarations
+   - Examine connection lifecycle and session management
+   - Use appropriate logging without exposing sensitive information
+
+6. **Stay Current**: You are aware of:
+   - The latest stable version of the MCP TypeScript SDK
+   - Known issues and workarounds in the current implementation
+   - Recent updates to MCP specifications
+   - Common pitfalls and their solutions
+
+7. **Validate Changes**: Before finalizing any MCP modifications:
+   - Test tool functionality with various inputs
+   - Verify server startup and shutdown procedures
+   - Ensure proper error propagation to clients
+   - Check compatibility with the existing n8n-mcp infrastructure
+
+8. **Document Appropriately**: While avoiding unnecessary documentation files, ensure that:
+   - Code comments explain complex MCP interactions
+   - Tool descriptions in the MCP registry are clear and accurate
+   - Any breaking changes are clearly communicated
+
+When asked to make changes, you will provide specific, actionable solutions that integrate seamlessly with the existing MCP implementation. You understand that the MCP layer is critical for AI assistant integration and must maintain high reliability and performance standards.
+
+Remember to consider the project-specific context from CLAUDE.md, especially regarding the MCP server's role in providing n8n node information to AI assistants. Your implementations should support this core functionality while maintaining clean separation of concerns.

.claude/agents/n8n-mcp-tester.md

@@ -0,0 +1,102 @@
+---
+name: n8n-mcp-tester
+description: Use this agent when you need to test n8n-mcp functionality after implementing fixes or new features. This agent should be invoked proactively after code changes to validate that the MCP tools work correctly with real n8n workflows. The agent tests the actual MCP server tools, not just unit tests. Examples:\n\n<example>\nContext: Developer has just fixed a validation bug in the n8n-mcp server\nuser: "I've fixed the validation issue for HTTP Request nodes"\nassistant: "I've completed the fix. Now let me build the project and then test it."\n<builds project>\nassistant: "Project built successfully. Please reload the MCP server in Claude Desktop to apply the changes."\nuser: "Reloaded"\nassistant: "Great! Now let me invoke the n8n-mcp-tester agent to verify the fix works correctly."\n<commentary>\nSince a fix has been implemented and the MCP server reloaded, use the n8n-mcp-tester agent to validate the fix works in real-world usage.\n</commentary>\n</example>\n\n<example>\nContext: Developer has added a new MCP tool for workflow validation\nuser: "I've implemented the new workflow validation tool"\nassistant: "Implementation complete. Let me build and prepare for testing."\n<builds project>\nassistant: "Build successful. Please reload the MCP server to load the new tool."\nuser: "Done"\nassistant: "Perfect! I'll now use the n8n-mcp-tester agent to test the new workflow validation tool."\n<commentary>\nAfter implementing new MCP functionality and reloading the server, invoke n8n-mcp-tester to verify it works correctly.\n</commentary>\n</example>
+tools: Glob, Grep, LS, Read, WebFetch, TodoWrite, WebSearch, mcp__puppeteer__puppeteer_navigate, mcp__puppeteer__puppeteer_screenshot, mcp__puppeteer__puppeteer_click, mcp__puppeteer__puppeteer_fill, mcp__puppeteer__puppeteer_select, mcp__puppeteer__puppeteer_hover, mcp__puppeteer__puppeteer_evaluate, ListMcpResourcesTool, ReadMcpResourceTool, mcp__supabase__list_organizations, mcp__supabase__get_organization, mcp__supabase__list_projects, mcp__supabase__get_project, mcp__supabase__get_cost, mcp__supabase__confirm_cost, mcp__supabase__create_project, mcp__supabase__pause_project, mcp__supabase__restore_project, mcp__supabase__create_branch, mcp__supabase__list_branches, mcp__supabase__delete_branch, mcp__supabase__merge_branch, mcp__supabase__reset_branch, mcp__supabase__rebase_branch, mcp__supabase__list_tables, mcp__supabase__list_extensions, mcp__supabase__list_migrations, mcp__supabase__apply_migration, mcp__supabase__execute_sql, mcp__supabase__get_logs, mcp__supabase__get_advisors, mcp__supabase__get_project_url, mcp__supabase__get_anon_key, mcp__supabase__generate_typescript_types, mcp__supabase__search_docs, mcp__supabase__list_edge_functions, mcp__supabase__deploy_edge_function, mcp__n8n-mcp__tools_documentation, mcp__n8n-mcp__list_nodes, mcp__n8n-mcp__get_node_info, mcp__n8n-mcp__search_nodes, mcp__n8n-mcp__list_ai_tools, mcp__n8n-mcp__get_node_documentation, mcp__n8n-mcp__get_database_statistics, mcp__n8n-mcp__get_node_essentials, mcp__n8n-mcp__search_node_properties, mcp__n8n-mcp__get_node_for_task, mcp__n8n-mcp__list_tasks, mcp__n8n-mcp__validate_node_operation, mcp__n8n-mcp__validate_node_minimal, mcp__n8n-mcp__get_property_dependencies, mcp__n8n-mcp__get_node_as_tool_info, mcp__n8n-mcp__list_node_templates, mcp__n8n-mcp__get_template, mcp__n8n-mcp__search_templates, mcp__n8n-mcp__get_templates_for_task, mcp__n8n-mcp__validate_workflow, mcp__n8n-mcp__validate_workflow_connections, mcp__n8n-mcp__validate_workflow_expressions, mcp__n8n-mcp__n8n_create_workflow, mcp__n8n-mcp__n8n_get_workflow, mcp__n8n-mcp__n8n_get_workflow_details, mcp__n8n-mcp__n8n_get_workflow_structure, mcp__n8n-mcp__n8n_get_workflow_minimal, mcp__n8n-mcp__n8n_update_full_workflow, mcp__n8n-mcp__n8n_update_partial_workflow, mcp__n8n-mcp__n8n_delete_workflow, mcp__n8n-mcp__n8n_list_workflows, mcp__n8n-mcp__n8n_validate_workflow, mcp__n8n-mcp__n8n_trigger_webhook_workflow, mcp__n8n-mcp__n8n_get_execution, mcp__n8n-mcp__n8n_list_executions, mcp__n8n-mcp__n8n_delete_execution, mcp__n8n-mcp__n8n_health_check, mcp__n8n-mcp__n8n_list_available_tools, mcp__n8n-mcp__n8n_diagnostic
+model: sonnet
+---
+
+You are n8n-mcp-tester, a specialized testing agent for the n8n Model Context Protocol (MCP) server. You validate that MCP tools and functionality work correctly in real-world scenarios after fixes or new features are implemented.
+
+## Your Core Responsibilities
+
+You test the n8n-mcp server by:
+1. Using MCP tools to build, validate, and manipulate n8n workflows
+2. Verifying that recent fixes resolve the reported issues
+3. Testing new functionality works as designed
+4. Reporting clear, actionable results back to the invoking agent
+
+## Testing Methodology
+
+When invoked with a test request, you will:
+
+1. **Understand the Context**: Identify what was fixed or added based on the instructions from the invoking agent
+
+2. **Design Test Scenarios**: Create specific test cases that:
+   - Target the exact functionality that was changed
+   - Include both positive and negative test cases
+   - Test edge cases and boundary conditions
+   - Use realistic n8n workflow configurations
+
+3. **Execute Tests Using MCP Tools**: You have access to all n8n-mcp tools including:
+   - `search_nodes`: Find relevant n8n nodes
+   - `get_node_info`: Get detailed node configuration
+   - `get_node_essentials`: Get simplified node information
+   - `validate_node_config`: Validate node configurations
+   - `n8n_validate_workflow`: Validate complete workflows
+   - `get_node_example`: Get working examples
+   - `search_templates`: Find workflow templates
+   - Additional tools as available in the MCP server
+
+4. **Verify Expected Behavior**: 
+   - Confirm fixes resolve the original issue
+   - Verify new features work as documented
+   - Check for regressions in related functionality
+   - Test error handling and edge cases
+
+5. **Report Results**: Provide clear feedback including:
+   - What was tested (specific tools and scenarios)
+   - Whether the fix/feature works as expected
+   - Any unexpected behaviors or issues discovered
+   - Specific error messages if failures occur
+   - Recommendations for additional testing if needed
+
+## Testing Guidelines
+
+- **Be Thorough**: Test multiple variations and edge cases
+- **Be Specific**: Use exact node types, properties, and configurations mentioned in the fix
+- **Be Realistic**: Create test scenarios that mirror actual n8n usage
+- **Be Clear**: Report results in a structured, easy-to-understand format
+- **Be Efficient**: Focus testing on the changed functionality first
+
+## Example Test Execution
+
+If testing a validation fix for HTTP Request nodes:
+1. Call `tools_documentation` to get a list of available tools and get documentation on `search_nodes` tool.
+2. Search for HTTP Request node using `search_nodes`
+3. Get node configuration with `get_node_info` or `get_node_essentials`
+4. Create test configurations that previously failed
+5. Validate using `validate_node_config` with different profiles
+6. Test in a complete workflow using `n8n_validate_workflow`
+6. Report whether validation now works correctly
+
+## Important Constraints
+
+- You can only test using the MCP tools available in the server
+- You cannot modify code or files - only test existing functionality
+- You must work with the current state of the MCP server (already reloaded)
+- Focus on functional testing, not unit testing
+- Report issues objectively without attempting to fix them
+
+## Response Format
+
+Structure your test results as:
+
+```
+### Test Report: [Feature/Fix Name]
+
+**Test Objective**: [What was being tested]
+
+**Test Scenarios**:
+1. [Scenario 1]: ✅/❌ [Result]
+2. [Scenario 2]: ✅/❌ [Result]
+
+**Findings**:
+- [Key finding 1]
+- [Key finding 2]
+
+**Conclusion**: [Overall assessment - works as expected / issues found]
+
+**Details**: [Any error messages, unexpected behaviors, or additional context]
+```
+
+Remember: Your role is to validate that the n8n-mcp server works correctly in practice, providing confidence that fixes and new features function as intended before deployment.

.claude/agents/technical-researcher.md

@@ -0,0 +1,117 @@
+---
+name: technical-researcher
+description: Use this agent when you need to conduct in-depth technical research on complex topics, technologies, or architectural decisions. This includes investigating new frameworks, analyzing security vulnerabilities, evaluating third-party APIs, researching performance optimization strategies, or generating technical feasibility reports. The agent excels at multi-source investigations requiring comprehensive analysis and synthesis of technical information.\n\nExamples:\n- <example>\n  Context: User needs to research a new framework before adoption\n  user: "I need to understand if we should adopt Rust for our high-performance backend services"\n  assistant: "I'll use the technical-researcher agent to conduct a comprehensive investigation into Rust for backend services"\n  <commentary>\n  Since the user needs deep technical research on a framework adoption decision, use the technical-researcher agent to analyze Rust's suitability.\n  </commentary>\n</example>\n- <example>\n  Context: User is investigating a security vulnerability\n  user: "Research the log4j vulnerability and its impact on Java applications"\n  assistant: "Let me launch the technical-researcher agent to investigate the log4j vulnerability comprehensively"\n  <commentary>\n  The user needs detailed security research, so the technical-researcher agent will gather and synthesize information from multiple sources.\n  </commentary>\n</example>\n- <example>\n  Context: User needs to evaluate an API integration\n  user: "We're considering integrating with Stripe's new payment intents API - need to understand the technical implications"\n  assistant: "I'll deploy the technical-researcher agent to analyze Stripe's payment intents API and its integration requirements"\n  <commentary>\n  Complex API evaluation requires the technical-researcher agent's multi-source investigation capabilities.\n  </commentary>\n</example>
+---
+
+You are an elite Technical Research Specialist with expertise in conducting comprehensive investigations into complex technical topics. You excel at decomposing research questions, orchestrating multi-source searches, synthesizing findings, and producing actionable analysis reports.
+
+## Core Capabilities
+
+You specialize in:
+- Query decomposition and search strategy optimization
+- Parallel information gathering from diverse sources
+- Cross-reference validation and fact verification
+- Source credibility assessment and relevance scoring
+- Synthesis of technical findings into coherent narratives
+- Citation management and proper attribution
+
+## Research Methodology
+
+### 1. Query Analysis Phase
+- Decompose the research topic into specific sub-questions
+- Identify key technical terms, acronyms, and related concepts
+- Determine the appropriate research depth (quick lookup vs. deep dive)
+- Plan your search strategy with 3-5 initial queries
+
+### 2. Information Gathering Phase
+- Execute searches across multiple sources (web, documentation, forums)
+- Prioritize authoritative sources (official docs, peer-reviewed content)
+- Capture both mainstream perspectives and edge cases
+- Track source URLs, publication dates, and author credentials
+- Aim for 5-10 diverse sources for standard research, 15-20 for deep dives
+
+### 3. Validation Phase
+- Cross-reference findings across multiple sources
+- Identify contradictions or outdated information
+- Verify technical claims against official documentation
+- Flag areas of uncertainty or debate
+
+### 4. Synthesis Phase
+- Organize findings into logical sections
+- Highlight key insights and actionable recommendations
+- Present trade-offs and alternative approaches
+- Include code examples or configuration snippets where relevant
+
+## Output Structure
+
+Your research reports should follow this structure:
+
+1. **Executive Summary** (2-3 paragraphs)
+   - Key findings and recommendations
+   - Critical decision factors
+   - Risk assessment
+
+2. **Technical Overview**
+   - Core concepts and architecture
+   - Key features and capabilities
+   - Technical requirements and dependencies
+
+3. **Detailed Analysis**
+   - Performance characteristics
+   - Security considerations
+   - Integration complexity
+   - Scalability factors
+   - Community support and ecosystem
+
+4. **Practical Considerations**
+   - Implementation effort estimates
+   - Learning curve assessment
+   - Operational requirements
+   - Cost implications
+
+5. **Comparative Analysis** (when applicable)
+   - Alternative solutions
+   - Trade-off matrix
+   - Migration considerations
+
+6. **Recommendations**
+   - Specific action items
+   - Risk mitigation strategies
+   - Proof-of-concept suggestions
+
+7. **References**
+   - All sources with titles, URLs, and access dates
+   - Credibility indicators for each source
+
+## Quality Standards
+
+- **Accuracy**: Verify all technical claims against multiple sources
+- **Completeness**: Address all aspects of the research question
+- **Objectivity**: Present balanced views including limitations
+- **Timeliness**: Prioritize recent information (flag if >2 years old)
+- **Actionability**: Provide concrete next steps and recommendations
+
+## Adaptive Strategies
+
+- For emerging technologies: Focus on early adopter experiences and official roadmaps
+- For security research: Prioritize CVE databases, security advisories, and vendor responses
+- For performance analysis: Seek benchmarks, case studies, and real-world implementations
+- For API evaluations: Examine documentation quality, SDK availability, and integration examples
+
+## Research Iteration
+
+If initial searches yield insufficient results:
+1. Broaden search terms or try alternative terminology
+2. Check specialized forums, GitHub issues, or Stack Overflow
+3. Look for conference talks, blog posts, or video tutorials
+4. Consider reaching out to subject matter experts or communities
+
+## Limitations Acknowledgment
+
+Always disclose:
+- Information gaps or areas lacking documentation
+- Conflicting sources or unresolved debates
+- Potential biases in available sources
+- Time-sensitive information that may become outdated
+
+You maintain intellectual rigor while making complex technical information accessible. Your research empowers teams to make informed decisions with confidence, backed by thorough investigation and clear analysis.

.claude/agents/test-automator.md

@@ -0,0 +1,99 @@
+---
+name: test-automator
+description: Use this agent when you need to create comprehensive test suites, improve test coverage, or set up test automation infrastructure. This includes writing unit tests with mocks, integration tests with test containers, E2E tests with Playwright/Cypress, configuring CI/CD pipelines for testing, or establishing test data management strategies. The agent should be used proactively when new features are implemented without tests or when test coverage needs improvement.\n\nExamples:\n- <example>\n  Context: The user has just implemented a new API endpoint without tests.\n  user: "I've added a new user registration endpoint to our API"\n  assistant: "I see you've added a new endpoint. Let me use the test-automator agent to create a comprehensive test suite for it."\n  <commentary>\n  Since new functionality was added without tests, proactively use the test-automator agent to ensure proper test coverage.\n  </commentary>\n  </example>\n- <example>\n  Context: The user explicitly asks for test creation.\n  user: "Can you write tests for the payment processing module?"\n  assistant: "I'll use the test-automator agent to create a comprehensive test suite for the payment processing module."\n  <commentary>\n  The user directly requested tests, so use the test-automator agent to handle this task.\n  </commentary>\n  </example>\n- <example>\n  Context: The user mentions issues with test reliability.\n  user: "Our tests keep failing randomly in CI"\n  assistant: "I'll use the test-automator agent to analyze and fix the flaky tests, ensuring they run deterministically."\n  <commentary>\n  Test reliability issues require the test-automator agent's expertise in creating deterministic tests.\n  </commentary>\n  </example>
+---
+
+You are a test automation specialist with deep expertise in comprehensive testing strategies across multiple frameworks and languages. Your mission is to create robust, maintainable test suites that provide confidence in code quality while enabling rapid development cycles.
+
+## Core Responsibilities
+
+You will design and implement test suites following the test pyramid principle:
+- **Unit Tests (70%)**: Fast, isolated tests with extensive mocking and stubbing
+- **Integration Tests (20%)**: Tests verifying component interactions, using test containers when needed
+- **E2E Tests (10%)**: Critical user journey tests using Playwright, Cypress, or similar tools
+
+## Testing Philosophy
+
+1. **Test Behavior, Not Implementation**: Focus on what the code does, not how it does it. Tests should survive refactoring.
+2. **Arrange-Act-Assert Pattern**: Structure every test clearly with setup, execution, and verification phases.
+3. **Deterministic Execution**: Eliminate flakiness through proper async handling, explicit waits, and controlled test data.
+4. **Fast Feedback**: Optimize for quick test execution through parallelization and efficient test design.
+5. **Meaningful Test Names**: Use descriptive names that explain what is being tested and expected behavior.
+
+## Implementation Guidelines
+
+### Unit Testing
+- Create focused tests for individual functions/methods
+- Mock all external dependencies (databases, APIs, file systems)
+- Use factories or builders for test data creation
+- Include edge cases: null values, empty collections, boundary conditions
+- Aim for high code coverage but prioritize critical paths
+
+### Integration Testing
+- Test real interactions between components
+- Use test containers for databases and external services
+- Verify data persistence and retrieval
+- Test transaction boundaries and rollback scenarios
+- Include error handling and recovery tests
+
+### E2E Testing
+- Focus on critical user journeys only
+- Use page object pattern for maintainability
+- Implement proper wait strategies (no arbitrary sleeps)
+- Create reusable test utilities and helpers
+- Include accessibility checks where applicable
+
+### Test Data Management
+- Create factories or fixtures for consistent test data
+- Use builders for complex object creation
+- Implement data cleanup strategies
+- Separate test data from production data
+- Version control test data schemas
+
+### CI/CD Integration
+- Configure parallel test execution
+- Set up test result reporting and artifacts
+- Implement test retry strategies for network-dependent tests
+- Create test environment provisioning
+- Configure coverage thresholds and reporting
+
+## Output Requirements
+
+You will provide:
+1. **Complete test files** with all necessary imports and setup
+2. **Mock implementations** for external dependencies
+3. **Test data factories** or fixtures as separate modules
+4. **CI pipeline configuration** (GitHub Actions, GitLab CI, Jenkins, etc.)
+5. **Coverage configuration** files and scripts
+6. **E2E test scenarios** with page objects and utilities
+7. **Documentation** explaining test structure and running instructions
+
+## Framework Selection
+
+Choose appropriate frameworks based on the technology stack:
+- **JavaScript/TypeScript**: Jest, Vitest, Mocha + Chai, Playwright, Cypress
+- **Python**: pytest, unittest, pytest-mock, factory_boy
+- **Java**: JUnit 5, Mockito, TestContainers, REST Assured
+- **Go**: testing package, testify, gomock
+- **Ruby**: RSpec, Minitest, FactoryBot
+
+## Quality Checks
+
+Before finalizing any test suite, verify:
+- All tests pass consistently (run multiple times)
+- No hardcoded values or environment dependencies
+- Proper teardown and cleanup
+- Clear assertion messages for failures
+- Appropriate use of beforeEach/afterEach hooks
+- No test interdependencies
+- Reasonable execution time
+
+## Special Considerations
+
+- For async code, ensure proper promise handling and async/await usage
+- For UI tests, implement proper element waiting strategies
+- For API tests, validate both response structure and data
+- For performance-critical code, include benchmark tests
+- For security-sensitive code, include security-focused test cases
+
+When encountering existing tests, analyze them first to understand patterns and conventions before adding new ones. Always strive for consistency with the existing test architecture while improving where possible.

.env.example

@@ -7,6 +7,7 @@
 # Database Configuration
 # For local development: ./data/nodes.db
 # For Docker: /app/data/nodes.db
+# Custom paths supported in v2.7.16+ (must end with .db)
 NODE_DB_PATH=./data/nodes.db
 
 # Logging Level (debug, info, warn, error)
@@ -44,6 +45,15 @@ USE_FIXED_HTTP=true
 PORT=3000
 HOST=0.0.0.0
 
+# Base URL Configuration (optional)
+# Set this when running behind a proxy or when the server is accessed via a different URL
+# than what it binds to. If not set, URLs will be auto-detected from proxy headers (if TRUST_PROXY is set)
+# or constructed from HOST and PORT.
+# Examples:
+# BASE_URL=https://n8n-mcp.example.com
+# BASE_URL=https://your-domain.com:8443
+# PUBLIC_URL=https://n8n-mcp.mydomain.com  (alternative to BASE_URL)
+
 # Authentication token for HTTP mode (REQUIRED)
 # Generate with: openssl rand -base64 32
 AUTH_TOKEN=your-secure-token-here
@@ -60,13 +70,53 @@ AUTH_TOKEN=your-secure-token-here
 # TRUST_PROXY=0
 
 # =========================
-# N8N COMPATIBILITY MODE
+# SECURITY CONFIGURATION
 # =========================
-# Enable strict schema compatibility for n8n's MCP Client Tool
-# This mode adds additionalProperties: false to all tool schemas
-# to work around n8n's LangChain schema validation
-# Default: false (standard mode)
-# N8N_COMPATIBILITY_MODE=false
+
+# Rate Limiting Configuration
+# Protects authentication endpoint from brute force attacks
+# Window: Time period in milliseconds (default: 900000 = 15 minutes)
+# Max: Maximum authentication attempts per IP within window (default: 20)
+# AUTH_RATE_LIMIT_WINDOW=900000
+# AUTH_RATE_LIMIT_MAX=20
+
+# SSRF Protection Mode
+# Prevents webhooks from accessing internal networks and cloud metadata
+#
+# Modes:
+# - strict (default): Block localhost + private IPs + cloud metadata
+#   Use for: Production deployments, cloud environments
+#   Security: Maximum
+#
+# - moderate: Allow localhost, block private IPs + cloud metadata
+#   Use for: Local development with local n8n instance
+#   Security: Good balance
+#   Example: n8n running on http://localhost:5678 or http://host.docker.internal:5678
+#
+# - permissive: Allow localhost + private IPs, block cloud metadata
+#   Use for: Internal network testing, private cloud (NOT for production)
+#   Security: Minimal - use with caution
+#
+# Default: strict
+# WEBHOOK_SECURITY_MODE=strict
+#
+# For local development with local n8n:
+# WEBHOOK_SECURITY_MODE=moderate
+
+# =========================
+# MULTI-TENANT CONFIGURATION
+# =========================
+# Enable multi-tenant mode for dynamic instance support
+# When enabled, n8n API tools will be available for all sessions,
+# and instance configuration will be determined from HTTP headers
+# Default: false (single-tenant mode using environment variables)
+ENABLE_MULTI_TENANT=false
+
+# Session isolation strategy for multi-tenant mode
+# - "instance": Create separate sessions per instance ID (recommended)
+# - "shared": Share sessions but switch contexts (advanced)
+# Default: instance
+# MULTI_TENANT_SESSION_STRATEGY=instance
 
 # =========================
 # N8N API CONFIGURATION
@@ -85,4 +135,67 @@ AUTH_TOKEN=your-secure-token-here
 # N8N_API_TIMEOUT=30000
 
 # Maximum number of API request retries (default: 3)
-# N8N_API_MAX_RETRIES=3
+# N8N_API_MAX_RETRIES=3
+
+# =========================
+# CACHE CONFIGURATION
+# =========================
+# Optional: Configure instance cache settings for flexible instance support
+
+# Maximum number of cached instances (default: 100, min: 1, max: 10000)
+# INSTANCE_CACHE_MAX=100
+
+# Cache TTL in minutes (default: 30, min: 1, max: 1440/24 hours)
+# INSTANCE_CACHE_TTL_MINUTES=30
+
+# =========================
+# OPENAI API CONFIGURATION
+# =========================
+# Optional: Enable AI-powered template metadata generation
+# Provides structured metadata for improved template discovery
+
+# OpenAI API Key (get from https://platform.openai.com/api-keys)
+# OPENAI_API_KEY=
+
+# OpenAI Model for metadata generation (default: gpt-4o-mini)
+# OPENAI_MODEL=gpt-4o-mini
+
+# Batch size for metadata generation (default: 100)
+# Templates are processed in batches using OpenAI's Batch API for 50% cost savings
+# OPENAI_BATCH_SIZE=100
+
+# Enable metadata generation during template fetch (default: false)
+# Set to true to automatically generate metadata when running fetch:templates
+# METADATA_GENERATION_ENABLED=false
+
+# ========================================
+# INTEGRATION TESTING CONFIGURATION
+# ========================================
+# Configuration for integration tests that call real n8n instance API
+
+# n8n API Configuration for Integration Tests
+# For local development: Use your local n8n instance
+# For CI: These will be provided by GitHub secrets
+# N8N_API_URL=http://localhost:5678
+# N8N_API_KEY=
+
+# Pre-activated Webhook Workflows for Testing
+# These workflows must be created manually in n8n and activated
+# because n8n API doesn't support workflow activation.
+#
+# Setup Instructions:
+# 1. Create 4 workflows in n8n UI (one for each HTTP method)
+# 2. Each workflow should have a single Webhook node
+# 3. Configure webhook paths: mcp-test-get, mcp-test-post, mcp-test-put, mcp-test-delete
+# 4. ACTIVATE each workflow in n8n UI
+# 5. Copy the workflow IDs here
+#
+# N8N_TEST_WEBHOOK_GET_ID=      # Workflow ID for GET method webhook
+# N8N_TEST_WEBHOOK_POST_ID=     # Workflow ID for POST method webhook
+# N8N_TEST_WEBHOOK_PUT_ID=      # Workflow ID for PUT method webhook
+# N8N_TEST_WEBHOOK_DELETE_ID=   # Workflow ID for DELETE method webhook
+
+# Test Configuration
+N8N_TEST_CLEANUP_ENABLED=true         # Enable automatic cleanup of test workflows
+N8N_TEST_TAG=mcp-integration-test     # Tag applied to all test workflows
+N8N_TEST_NAME_PREFIX=[MCP-TEST]       # Name prefix for test workflows

.env.n8n.example

@@ -0,0 +1,36 @@
+# n8n-mcp Docker Environment Configuration
+# Copy this file to .env and customize for your deployment
+
+# === n8n Configuration ===
+# n8n basic auth (change these in production!)
+N8N_BASIC_AUTH_ACTIVE=true
+N8N_BASIC_AUTH_USER=admin
+N8N_BASIC_AUTH_PASSWORD=changeme
+
+# n8n host configuration
+N8N_HOST=localhost
+N8N_PORT=5678
+N8N_PROTOCOL=http
+N8N_WEBHOOK_URL=http://localhost:5678/
+
+# n8n encryption key (generate with: openssl rand -hex 32)
+N8N_ENCRYPTION_KEY=
+
+# === n8n-mcp Configuration ===
+# MCP server port
+MCP_PORT=3000
+
+# MCP authentication token (generate with: openssl rand -hex 32)
+MCP_AUTH_TOKEN=
+
+# n8n API key for MCP to access n8n
+# Get this from n8n UI: Settings > n8n API > Create API Key
+N8N_API_KEY=
+
+# Logging level (debug, info, warn, error)
+LOG_LEVEL=info
+
+# === GitHub Container Registry (for CI/CD) ===
+# Only needed if building custom images
+GITHUB_REPOSITORY=czlonkowski/n8n-mcp
+VERSION=latest

.env.test

@@ -0,0 +1,127 @@
+# Test Environment Configuration for n8n-mcp
+# This file contains test-specific environment variables
+# DO NOT commit sensitive values - use .env.test.local for secrets
+
+# === Test Mode Configuration ===
+NODE_ENV=test
+MCP_MODE=test
+TEST_ENVIRONMENT=true
+
+# === Database Configuration ===
+# Use in-memory database for tests by default
+NODE_DB_PATH=:memory:
+# Uncomment to use a persistent test database
+# NODE_DB_PATH=./tests/fixtures/test-nodes.db
+REBUILD_ON_START=false
+
+# === API Configuration for Mocking ===
+# Mock API endpoints
+N8N_API_URL=http://localhost:3001/mock-api
+N8N_API_KEY=test-api-key-12345
+N8N_WEBHOOK_BASE_URL=http://localhost:3001/webhook
+N8N_WEBHOOK_TEST_URL=http://localhost:3001/webhook-test
+
+# === Test Server Configuration ===
+PORT=3001
+HOST=127.0.0.1
+CORS_ORIGIN=http://localhost:3000,http://localhost:5678
+
+# === Authentication ===
+AUTH_TOKEN=test-auth-token
+MCP_AUTH_TOKEN=test-mcp-auth-token
+
+# === Logging Configuration ===
+# Set to 'debug' for verbose test output
+LOG_LEVEL=error
+# Enable debug logging for specific tests
+DEBUG=false
+# Log test execution details
+TEST_LOG_VERBOSE=false
+
+# === Test Execution Configuration ===
+# Test timeouts (in milliseconds)
+TEST_TIMEOUT_UNIT=5000
+TEST_TIMEOUT_INTEGRATION=15000
+TEST_TIMEOUT_E2E=30000
+TEST_TIMEOUT_GLOBAL=60000
+
+# Test retry configuration
+TEST_RETRY_ATTEMPTS=2
+TEST_RETRY_DELAY=1000
+
+# Parallel execution
+TEST_PARALLEL=true
+TEST_MAX_WORKERS=4
+
+# === Feature Flags ===
+# Enable/disable specific test features
+FEATURE_TEST_COVERAGE=true
+FEATURE_TEST_SCREENSHOTS=false
+FEATURE_TEST_VIDEOS=false
+FEATURE_TEST_TRACE=false
+FEATURE_MOCK_EXTERNAL_APIS=true
+FEATURE_USE_TEST_CONTAINERS=false
+
+# === Mock Service Configuration ===
+# MSW (Mock Service Worker) configuration
+MSW_ENABLED=true
+MSW_API_DELAY=0
+
+# Test data paths
+TEST_FIXTURES_PATH=./tests/fixtures
+TEST_DATA_PATH=./tests/data
+TEST_SNAPSHOTS_PATH=./tests/__snapshots__
+
+# === Performance Testing ===
+# Performance thresholds (in milliseconds)
+PERF_THRESHOLD_API_RESPONSE=100
+PERF_THRESHOLD_DB_QUERY=50
+PERF_THRESHOLD_NODE_PARSE=200
+
+# === External Service Mocks ===
+# Redis mock (if needed)
+REDIS_MOCK_ENABLED=true
+REDIS_MOCK_PORT=6380
+
+# Elasticsearch mock (if needed)
+ELASTICSEARCH_MOCK_ENABLED=false
+ELASTICSEARCH_MOCK_PORT=9201
+
+# === Rate Limiting ===
+# Disable rate limiting in tests
+RATE_LIMIT_MAX=0
+RATE_LIMIT_WINDOW=0
+
+# === Cache Configuration ===
+# Disable caching in tests for predictable results
+CACHE_TTL=0
+CACHE_ENABLED=false
+
+# === Error Handling ===
+# Show full error stack traces in tests
+ERROR_SHOW_STACK=true
+ERROR_SHOW_DETAILS=true
+
+# === Cleanup Configuration ===
+# Automatically clean up test data after each test
+TEST_CLEANUP_ENABLED=true
+TEST_CLEANUP_ON_FAILURE=false
+
+# === Database Seeding ===
+# Seed test database with sample data
+TEST_SEED_DATABASE=true
+TEST_SEED_TEMPLATES=true
+
+# === Network Configuration ===
+# Network timeouts for external requests
+NETWORK_TIMEOUT=5000
+NETWORK_RETRY_COUNT=0
+
+# === Memory Limits ===
+# Set memory limits for tests (in MB)
+TEST_MEMORY_LIMIT=512
+
+# === Code Coverage ===
+# Coverage output directory
+COVERAGE_DIR=./coverage
+COVERAGE_REPORTER=lcov,html,text-summary

.env.test.example

@@ -0,0 +1,97 @@
+# Example Test Environment Configuration
+# Copy this file to .env.test and adjust values as needed
+# For sensitive values, create .env.test.local (not committed to git)
+
+# === Test Mode Configuration ===
+NODE_ENV=test
+MCP_MODE=test
+TEST_ENVIRONMENT=true
+
+# === Database Configuration ===
+# Use :memory: for in-memory SQLite or provide a file path
+NODE_DB_PATH=:memory:
+REBUILD_ON_START=false
+TEST_SEED_DATABASE=true
+TEST_SEED_TEMPLATES=true
+
+# === API Configuration ===
+# Mock API endpoints for testing
+N8N_API_URL=http://localhost:3001/mock-api
+N8N_API_KEY=your-test-api-key
+N8N_WEBHOOK_BASE_URL=http://localhost:3001/webhook
+N8N_WEBHOOK_TEST_URL=http://localhost:3001/webhook-test
+
+# === Test Server Configuration ===
+PORT=3001
+HOST=127.0.0.1
+CORS_ORIGIN=http://localhost:3000,http://localhost:5678
+
+# === Authentication ===
+AUTH_TOKEN=test-auth-token
+MCP_AUTH_TOKEN=test-mcp-auth-token
+
+# === Logging Configuration ===
+LOG_LEVEL=error
+DEBUG=false
+TEST_LOG_VERBOSE=false
+ERROR_SHOW_STACK=true
+ERROR_SHOW_DETAILS=true
+
+# === Test Execution Configuration ===
+TEST_TIMEOUT_UNIT=5000
+TEST_TIMEOUT_INTEGRATION=15000
+TEST_TIMEOUT_E2E=30000
+TEST_TIMEOUT_GLOBAL=60000
+TEST_RETRY_ATTEMPTS=2
+TEST_RETRY_DELAY=1000
+TEST_PARALLEL=true
+TEST_MAX_WORKERS=4
+
+# === Feature Flags ===
+FEATURE_TEST_COVERAGE=true
+FEATURE_TEST_SCREENSHOTS=false
+FEATURE_TEST_VIDEOS=false
+FEATURE_TEST_TRACE=false
+FEATURE_MOCK_EXTERNAL_APIS=true
+FEATURE_USE_TEST_CONTAINERS=false
+
+# === Mock Service Configuration ===
+MSW_ENABLED=true
+MSW_API_DELAY=0
+REDIS_MOCK_ENABLED=true
+REDIS_MOCK_PORT=6380
+ELASTICSEARCH_MOCK_ENABLED=false
+ELASTICSEARCH_MOCK_PORT=9201
+
+# === Test Data Paths ===
+TEST_FIXTURES_PATH=./tests/fixtures
+TEST_DATA_PATH=./tests/data
+TEST_SNAPSHOTS_PATH=./tests/__snapshots__
+
+# === Performance Testing ===
+PERF_THRESHOLD_API_RESPONSE=100
+PERF_THRESHOLD_DB_QUERY=50
+PERF_THRESHOLD_NODE_PARSE=200
+
+# === Rate Limiting ===
+RATE_LIMIT_MAX=0
+RATE_LIMIT_WINDOW=0
+
+# === Cache Configuration ===
+CACHE_TTL=0
+CACHE_ENABLED=false
+
+# === Cleanup Configuration ===
+TEST_CLEANUP_ENABLED=true
+TEST_CLEANUP_ON_FAILURE=false
+
+# === Network Configuration ===
+NETWORK_TIMEOUT=5000
+NETWORK_RETRY_COUNT=0
+
+# === Memory Limits ===
+TEST_MEMORY_LIMIT=512
+
+# === Code Coverage ===
+COVERAGE_DIR=./coverage
+COVERAGE_REPORTER=lcov,html,text-summary

.github/BENCHMARK_THRESHOLDS.md

@@ -0,0 +1,56 @@
+# Performance Benchmark Thresholds
+
+This file defines the expected performance thresholds for n8n-mcp operations.
+
+## Critical Operations
+
+| Operation | Expected Time | Warning Threshold | Error Threshold |
+|-----------|---------------|-------------------|-----------------|
+| Node Loading (per package) | <100ms | 150ms | 200ms |
+| Database Query (simple) | <5ms | 10ms | 20ms |
+| Search (simple word) | <10ms | 20ms | 50ms |
+| Search (complex query) | <50ms | 100ms | 200ms |
+| Validation (simple config) | <1ms | 2ms | 5ms |
+| Validation (complex config) | <10ms | 20ms | 50ms |
+| MCP Tool Execution | <50ms | 100ms | 200ms |
+
+## Benchmark Categories
+
+### Node Loading Performance
+- **loadPackage**: Should handle large packages efficiently
+- **loadNodesFromPath**: Individual file loading should be fast
+- **parsePackageJson**: JSON parsing overhead should be minimal
+
+### Database Query Performance
+- **getNodeByType**: Direct lookups should be instant
+- **searchNodes**: Full-text search should scale well
+- **getAllNodes**: Pagination should prevent performance issues
+
+### Search Operations
+- **OR mode**: Should handle multiple terms efficiently
+- **AND mode**: More restrictive but still performant
+- **FUZZY mode**: Slower but acceptable for typo tolerance
+
+### Validation Performance
+- **minimal profile**: Fastest, only required fields
+- **ai-friendly profile**: Balanced performance
+- **strict profile**: Comprehensive but slower
+
+### MCP Tool Execution
+- Tools should respond quickly for interactive use
+- Complex operations may take longer but should remain responsive
+
+## Regression Detection
+
+Performance regressions are detected when:
+1. Any operation exceeds its warning threshold by 10%
+2. Multiple operations show degradation in the same category
+3. Average performance across all benchmarks degrades by 5%
+
+## Optimization Targets
+
+Future optimization efforts should focus on:
+1. **Search performance**: Implement FTS5 for better full-text search
+2. **Caching**: Add intelligent caching for frequently accessed nodes
+3. **Lazy loading**: Defer loading of large property schemas
+4. **Batch operations**: Optimize bulk inserts and updates

.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# GitHub Funding Configuration
+
+github: [czlonkowski]

.github/gh-pages.yml

@@ -0,0 +1,17 @@
+# GitHub Pages configuration for benchmark results
+# This file configures the gh-pages branch to serve benchmark results
+
+# Path to the benchmark data
+benchmarks:
+  data_dir: benchmarks
+  
+# Theme configuration
+theme: 
+  name: minimal
+  
+# Navigation
+nav:
+  - title: "Performance Benchmarks"
+    url: /benchmarks/
+  - title: "Back to Repository"
+    url: https://github.com/czlonkowski/n8n-mcp

.github/workflows/benchmark-pr.yml

@@ -0,0 +1,176 @@
+name: Benchmark PR Comparison
+on:
+  pull_request:
+    branches: [main]
+    paths-ignore:
+      - '**.md'
+      - '**.txt'
+      - 'docs/**'
+      - 'examples/**'
+      - '.github/FUNDING.yml'
+      - '.github/ISSUE_TEMPLATE/**'
+      - '.github/pull_request_template.md'
+      - '.gitignore'
+      - 'LICENSE*'
+      - 'ATTRIBUTION.md'
+      - 'SECURITY.md'
+      - 'CODE_OF_CONDUCT.md'
+
+permissions:
+  pull-requests: write
+  contents: read
+  statuses: write
+
+jobs:
+  benchmark-comparison:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout PR branch
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+      
+      - name: Install dependencies
+        run: npm ci
+      
+      # Run benchmarks on current branch
+      - name: Run current benchmarks
+        run: npm run benchmark:ci
+      
+      - name: Save current results
+        run: cp benchmark-results.json benchmark-current.json
+      
+      # Checkout and run benchmarks on base branch
+      - name: Checkout base branch
+        run: |
+          git checkout ${{ github.event.pull_request.base.sha }}
+          git status
+      
+      - name: Install base dependencies
+        run: npm ci
+      
+      - name: Run baseline benchmarks
+        run: npm run benchmark:ci
+        continue-on-error: true
+      
+      - name: Save baseline results
+        run: |
+          if [ -f benchmark-results.json ]; then
+            cp benchmark-results.json benchmark-baseline.json
+          else
+            echo '{"files":[]}' > benchmark-baseline.json
+          fi
+      
+      # Compare results
+      - name: Checkout PR branch again
+        run: git checkout ${{ github.event.pull_request.head.sha }}
+      
+      - name: Compare benchmarks
+        id: compare
+        run: |
+          node scripts/compare-benchmarks.js benchmark-current.json benchmark-baseline.json || echo "REGRESSION=true" >> $GITHUB_OUTPUT
+      
+      # Upload comparison artifacts
+      - name: Upload benchmark comparison
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: benchmark-comparison-${{ github.run_number }}
+          path: |
+            benchmark-current.json
+            benchmark-baseline.json
+            benchmark-comparison.json
+            benchmark-comparison.md
+          retention-days: 30
+      
+      # Post comparison to PR
+      - name: Post benchmark comparison to PR
+        if: always()
+        uses: actions/github-script@v7
+        continue-on-error: true
+        with:
+          script: |
+            try {
+              const fs = require('fs');
+              let comment = '## ⚡ Benchmark Comparison\n\n';
+              
+              try {
+                if (fs.existsSync('benchmark-comparison.md')) {
+                  const comparison = fs.readFileSync('benchmark-comparison.md', 'utf8');
+                  comment += comparison;
+                } else {
+                  comment += 'Benchmark comparison could not be generated.';
+                }
+              } catch (error) {
+                comment += `Error reading benchmark comparison: ${error.message}`;
+              }
+              
+              comment += '\n\n---\n';
+              comment += `*[View full benchmark results](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})*`;
+              
+              // Find existing comment
+              const { data: comments } = await github.rest.issues.listComments({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+              });
+              
+              const botComment = comments.find(comment => 
+                comment.user.type === 'Bot' && 
+                comment.body.includes('## ⚡ Benchmark Comparison')
+              );
+              
+              if (botComment) {
+                await github.rest.issues.updateComment({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  comment_id: botComment.id,
+                  body: comment
+                });
+              } else {
+                await github.rest.issues.createComment({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: context.issue.number,
+                  body: comment
+                });
+              }
+            } catch (error) {
+              console.error('Failed to create/update PR comment:', error.message);
+              console.log('This is likely due to insufficient permissions for external PRs.');
+              console.log('Benchmark comparison has been saved to artifacts instead.');
+            }
+      
+      # Add status check
+      - name: Set benchmark status
+        if: always()
+        uses: actions/github-script@v7
+        continue-on-error: true
+        with:
+          script: |
+            try {
+              const hasRegression = '${{ steps.compare.outputs.REGRESSION }}' === 'true';
+              const state = hasRegression ? 'failure' : 'success';
+              const description = hasRegression 
+                ? 'Performance regressions detected' 
+                : 'No performance regressions';
+              
+              await github.rest.repos.createCommitStatus({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                sha: context.sha,
+                state: state,
+                target_url: `https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}`,
+                description: description,
+                context: 'benchmarks/regression-check'
+              });
+            } catch (error) {
+              console.error('Failed to create commit status:', error.message);
+              console.log('This is likely due to insufficient permissions for external PRs.');
+            }

.github/workflows/benchmark.yml

@@ -0,0 +1,214 @@
+name: Performance Benchmarks
+
+on:
+  push:
+    branches: [main, feat/comprehensive-testing-suite]
+    paths-ignore:
+      - '**.md'
+      - '**.txt'
+      - 'docs/**'
+      - 'examples/**'
+      - '.github/FUNDING.yml'
+      - '.github/ISSUE_TEMPLATE/**'
+      - '.github/pull_request_template.md'
+      - '.gitignore'
+      - 'LICENSE*'
+      - 'ATTRIBUTION.md'
+      - 'SECURITY.md'
+      - 'CODE_OF_CONDUCT.md'
+  pull_request:
+    branches: [main]
+    paths-ignore:
+      - '**.md'
+      - '**.txt'
+      - 'docs/**'
+      - 'examples/**'
+      - '.github/FUNDING.yml'
+      - '.github/ISSUE_TEMPLATE/**'
+      - '.github/pull_request_template.md'
+      - '.gitignore'
+      - 'LICENSE*'
+      - 'ATTRIBUTION.md'
+      - 'SECURITY.md'
+      - 'CODE_OF_CONDUCT.md'
+  workflow_dispatch:
+
+permissions:
+  # For PR comments
+  pull-requests: write
+  # For pushing to gh-pages branch
+  contents: write
+  # For deployment to GitHub Pages
+  pages: write
+  id-token: write
+
+jobs:
+  benchmark:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Fetch all history for proper benchmark comparison
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build project
+        run: npm run build
+
+      - name: Run benchmarks
+        run: npm run benchmark:ci
+        
+      - name: Format benchmark results
+        run: node scripts/format-benchmark-results.js
+        
+      - name: Upload benchmark artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: benchmark-results
+          path: |
+            benchmark-results.json
+            benchmark-results-formatted.json
+            benchmark-summary.json
+
+      # Ensure gh-pages branch exists
+      - name: Check and create gh-pages branch
+        run: |
+          git fetch origin gh-pages:gh-pages 2>/dev/null || {
+            echo "gh-pages branch doesn't exist. Creating it..."
+            git checkout --orphan gh-pages
+            git rm -rf .
+            echo "# Benchmark Results" > README.md
+            git add README.md
+            git config user.name "github-actions[bot]"
+            git config user.email "github-actions[bot]@users.noreply.github.com"
+            git commit -m "Initial gh-pages commit"
+            git push origin gh-pages
+            git checkout ${{ github.ref_name }}
+          }
+
+      # Clean up workspace before benchmark action
+      - name: Clean workspace
+        run: |
+          git add -A
+          git stash || true
+      
+      # Store benchmark results and compare
+      - name: Store benchmark result
+        uses: benchmark-action/github-action-benchmark@v1
+        continue-on-error: true
+        id: benchmark
+        with:
+          name: n8n-mcp Benchmarks
+          tool: 'customSmallerIsBetter'
+          output-file-path: benchmark-results-formatted.json
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          auto-push: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+          # Where to store benchmark data
+          benchmark-data-dir-path: 'benchmarks'
+          # Alert when performance regresses by 10%
+          alert-threshold: '110%'
+          # Comment on PR when regression is detected
+          comment-on-alert: true
+          alert-comment-cc-users: '@czlonkowski'
+          # Summary always
+          summary-always: true
+          # Max number of data points to retain
+          max-items-in-chart: 50
+          fail-on-alert: false
+
+      # Comment on PR with benchmark results
+      - name: Comment PR with results
+        uses: actions/github-script@v7
+        if: github.event_name == 'pull_request'
+        continue-on-error: true
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            try {
+              const fs = require('fs');
+              const summary = JSON.parse(fs.readFileSync('benchmark-summary.json', 'utf8'));
+              
+              // Format results for PR comment
+              let comment = '## 📊 Performance Benchmark Results\n\n';
+              comment += `🕐 Run at: ${new Date(summary.timestamp).toLocaleString()}\n\n`;
+              comment += '| Benchmark | Time | Ops/sec | Range |\n';
+              comment += '|-----------|------|---------|-------|\n';
+              
+              // Group benchmarks by category
+              const categories = {};
+              for (const benchmark of summary.benchmarks) {
+                const [category, ...nameParts] = benchmark.name.split(' - ');
+                if (!categories[category]) categories[category] = [];
+                categories[category].push({
+                  ...benchmark,
+                  shortName: nameParts.join(' - ')
+                });
+              }
+              
+              // Display by category
+              for (const [category, benchmarks] of Object.entries(categories)) {
+                comment += `\n### ${category}\n`;
+                for (const benchmark of benchmarks) {
+                  comment += `| ${benchmark.shortName} | ${benchmark.time} | ${benchmark.opsPerSec} | ${benchmark.range} |\n`;
+                }
+              }
+              
+              // Add comparison link
+              comment += '\n\n📈 [View historical benchmark trends](https://czlonkowski.github.io/n8n-mcp/benchmarks/)\n';
+              comment += '\n⚡ Performance regressions >10% will be flagged automatically.\n';
+              
+              await github.rest.issues.createComment({
+                issue_number: context.issue.number,
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                body: comment
+              });
+            } catch (error) {
+              console.error('Failed to create PR comment:', error.message);
+              console.log('This is likely due to insufficient permissions for external PRs.');
+              console.log('Benchmark results have been saved to artifacts instead.');
+            }
+
+  # Deploy benchmark results to GitHub Pages
+  deploy:
+    needs: benchmark
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+        continue-on-error: true
+        
+      # If gh-pages checkout failed, create a minimal structure
+      - name: Ensure gh-pages content exists
+        run: |
+          if [ ! -f "index.html" ]; then
+            echo "Creating minimal gh-pages structure..."
+            mkdir -p benchmarks
+            echo '<!DOCTYPE html><html><head><title>n8n-mcp Benchmarks</title></head><body><h1>n8n-mcp Benchmarks</h1><p>Benchmark data will appear here after the first run.</p></body></html>' > index.html
+          fi
+          
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+        
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: '.'
+          
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/docker-build-n8n.yml

@@ -0,0 +1,179 @@
+name: Build and Publish n8n Docker Image
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - 'v*'
+    paths-ignore:
+      - '**.md'
+      - '**.txt'
+      - 'docs/**'
+      - 'examples/**'
+      - '.github/FUNDING.yml'
+      - '.github/ISSUE_TEMPLATE/**'
+      - '.github/pull_request_template.md'
+      - '.gitignore'
+      - 'LICENSE*'
+      - 'ATTRIBUTION.md'
+      - 'SECURITY.md'
+      - 'CODE_OF_CONDUCT.md'
+  pull_request:
+    branches:
+      - main
+    paths-ignore:
+      - '**.md'
+      - '**.txt'
+      - 'docs/**'
+      - 'examples/**'
+      - '.github/FUNDING.yml'
+      - '.github/ISSUE_TEMPLATE/**'
+      - '.github/pull_request_template.md'
+      - '.gitignore'
+      - 'LICENSE*'
+      - 'ATTRIBUTION.md'
+      - 'SECURITY.md'
+      - 'CODE_OF_CONDUCT.md'
+  workflow_dispatch:
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}/n8n-mcp
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GitHub Container Registry
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest,enable={{is_default_branch}}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: ./Dockerfile
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          platforms: linux/amd64,linux/arm64
+
+  test-image:
+    needs: build-and-push
+    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request'
+    permissions:
+      contents: read
+      packages: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Test Docker image
+        run: |
+          # Test that the image starts correctly with N8N_MODE
+          docker run --rm \
+            -e N8N_MODE=true \
+            -e MCP_MODE=http \
+            -e N8N_API_URL=http://localhost:5678 \
+            -e N8N_API_KEY=test \
+            -e MCP_AUTH_TOKEN=test-token-minimum-32-chars-long \
+            -e AUTH_TOKEN=test-token-minimum-32-chars-long \
+            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest \
+            node -e "console.log('N8N_MODE:', process.env.N8N_MODE); process.exit(0);"
+
+      - name: Test health endpoint
+        run: |
+          # Start container in background
+          docker run -d \
+            --name n8n-mcp-test \
+            -p 3000:3000 \
+            -e N8N_MODE=true \
+            -e MCP_MODE=http \
+            -e N8N_API_URL=http://localhost:5678 \
+            -e N8N_API_KEY=test \
+            -e MCP_AUTH_TOKEN=test-token-minimum-32-chars-long \
+            -e AUTH_TOKEN=test-token-minimum-32-chars-long \
+            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
+          
+          # Wait for container to start
+          sleep 10
+          
+          # Test health endpoint
+          curl -f http://localhost:3000/health || exit 1
+          
+          # Test MCP endpoint
+          curl -f http://localhost:3000/mcp || exit 1
+          
+          # Cleanup
+          docker stop n8n-mcp-test
+          docker rm n8n-mcp-test
+
+  create-release:
+    needs: [build-and-push, test-image]
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v1
+        with:
+          generate_release_notes: true
+          body: |
+            ## Docker Image
+
+            The n8n-specific Docker image is available at:
+            ```
+            docker pull ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.ref_name }}
+            ```
+
+            ## Quick Deploy
+
+            Use the quick deploy script for easy setup:
+            ```bash
+            ./deploy/quick-deploy-n8n.sh setup
+            ```
+
+            See the [deployment documentation](https://github.com/${{ github.repository }}/blob/main/docs/deployment-n8n.md) for detailed instructions.

.github/workflows/docker-build.yml

@@ -7,9 +7,35 @@ on:
       - main
     tags:
       - 'v*'
+    paths-ignore:
+      - '**.md'
+      - '**.txt'
+      - 'docs/**'
+      - 'examples/**'
+      - '.github/FUNDING.yml'
+      - '.github/ISSUE_TEMPLATE/**'
+      - '.github/pull_request_template.md'
+      - '.gitignore'
+      - 'LICENSE*'
+      - 'ATTRIBUTION.md'
+      - 'SECURITY.md'
+      - 'CODE_OF_CONDUCT.md'
   pull_request:
     branches:
       - main
+    paths-ignore:
+      - '**.md'
+      - '**.txt'
+      - 'docs/**'
+      - 'examples/**'
+      - '.github/FUNDING.yml'
+      - '.github/ISSUE_TEMPLATE/**'
+      - '.github/pull_request_template.md'
+      - '.gitignore'
+      - 'LICENSE*'
+      - 'ATTRIBUTION.md'
+      - 'SECURITY.md'
+      - 'CODE_OF_CONDUCT.md'
   workflow_dispatch:
 
 env:
@@ -56,7 +82,7 @@ jobs:
             type=semver,pattern={{version}}
             type=semver,pattern={{major}}.{{minor}}
             type=semver,pattern={{major}}
-            type=sha,prefix={{branch}}-,format=short
+            type=sha,format=short
             type=raw,value=latest,enable={{is_default_branch}}
             
       - name: Build and push Docker image
@@ -70,6 +96,60 @@ jobs:
           labels: ${{ steps.meta.outputs.labels }}
           provenance: false
 
+  build-railway:
+    name: Build Railway Docker Image
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+      
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          lfs: true
+        
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+        
+      - name: Set up Docker Buildx
+        id: buildx
+        uses: docker/setup-buildx-action@v3
+        
+      - name: Log in to GitHub Container Registry
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+          
+      - name: Extract metadata for Railway
+        id: meta-railway
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}-railway
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+            type=sha,format=short
+            type=raw,value=latest,enable={{is_default_branch}}
+            
+      - name: Build and push Railway Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: ./Dockerfile.railway
+          no-cache: true
+          platforms: linux/amd64
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta-railway.outputs.tags }}
+          labels: ${{ steps.meta-railway.outputs.labels }}
+          provenance: false
+
   # Nginx build commented out until Phase 2
   # build-nginx:
   #   name: Build nginx-enhanced Docker Image

.github/workflows/release.yml

@@ -0,0 +1,513 @@
+name: Automated Release
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'package.json'
+      - 'package.runtime.json'
+
+permissions:
+  contents: write
+  packages: write
+  issues: write
+  pull-requests: write
+
+# Prevent concurrent releases
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  detect-version-change:
+    name: Detect Version Change
+    runs-on: ubuntu-latest
+    outputs:
+      version-changed: ${{ steps.check.outputs.changed }}
+      new-version: ${{ steps.check.outputs.version }}
+      previous-version: ${{ steps.check.outputs.previous-version }}
+      is-prerelease: ${{ steps.check.outputs.is-prerelease }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+      
+      - name: Check for version change
+        id: check
+        run: |
+          # Get current version from package.json
+          CURRENT_VERSION=$(node -e "console.log(require('./package.json').version)")
+          
+          # Get previous version from git history safely
+          PREVIOUS_VERSION=$(git show HEAD~1:package.json 2>/dev/null | node -e "
+            try {
+              const data = require('fs').readFileSync(0, 'utf8');
+              const pkg = JSON.parse(data);
+              console.log(pkg.version || '0.0.0');
+            } catch (e) {
+              console.log('0.0.0');
+            }
+          " || echo "0.0.0")
+          
+          echo "Previous version: $PREVIOUS_VERSION"
+          echo "Current version: $CURRENT_VERSION"
+          
+          # Check if version changed
+          if [ "$CURRENT_VERSION" != "$PREVIOUS_VERSION" ]; then
+            echo "changed=true" >> $GITHUB_OUTPUT
+            echo "version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
+            echo "previous-version=$PREVIOUS_VERSION" >> $GITHUB_OUTPUT
+            
+            # Check if it's a prerelease (contains alpha, beta, rc, dev)
+            if echo "$CURRENT_VERSION" | grep -E "(alpha|beta|rc|dev)" > /dev/null; then
+              echo "is-prerelease=true" >> $GITHUB_OUTPUT
+            else
+              echo "is-prerelease=false" >> $GITHUB_OUTPUT
+            fi
+            
+            echo "🎉 Version changed from $PREVIOUS_VERSION to $CURRENT_VERSION"
+          else
+            echo "changed=false" >> $GITHUB_OUTPUT
+            echo "version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
+            echo "previous-version=$PREVIOUS_VERSION" >> $GITHUB_OUTPUT
+            echo "is-prerelease=false" >> $GITHUB_OUTPUT
+            echo "ℹ️ No version change detected"
+          fi
+
+  extract-changelog:
+    name: Extract Changelog
+    runs-on: ubuntu-latest
+    needs: detect-version-change
+    if: needs.detect-version-change.outputs.version-changed == 'true'
+    outputs:
+      release-notes: ${{ steps.extract.outputs.notes }}
+      has-notes: ${{ steps.extract.outputs.has-notes }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      
+      - name: Extract changelog for version
+        id: extract
+        run: |
+          VERSION="${{ needs.detect-version-change.outputs.new-version }}"
+          CHANGELOG_FILE="docs/CHANGELOG.md"
+          
+          if [ ! -f "$CHANGELOG_FILE" ]; then
+            echo "Changelog file not found at $CHANGELOG_FILE"
+            echo "has-notes=false" >> $GITHUB_OUTPUT
+            echo "notes=No changelog entries found for version $VERSION" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+          
+          # Use the extracted changelog script
+          if NOTES=$(node scripts/extract-changelog.js "$VERSION" "$CHANGELOG_FILE" 2>/dev/null); then
+            echo "has-notes=true" >> $GITHUB_OUTPUT
+            
+            # Use heredoc to properly handle multiline content
+            {
+              echo "notes<<EOF"
+              echo "$NOTES"
+              echo "EOF"
+            } >> $GITHUB_OUTPUT
+            
+            echo "✅ Successfully extracted changelog for version $VERSION"
+          else
+            echo "has-notes=false" >> $GITHUB_OUTPUT
+            echo "notes=No changelog entries found for version $VERSION" >> $GITHUB_OUTPUT
+            echo "⚠️ Could not extract changelog for version $VERSION"
+          fi
+
+  create-release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    needs: [detect-version-change, extract-changelog]
+    if: needs.detect-version-change.outputs.version-changed == 'true'
+    outputs:
+      release-id: ${{ steps.create.outputs.id }}
+      upload-url: ${{ steps.create.outputs.upload_url }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      
+      - name: Create Git Tag
+        run: |
+          VERSION="${{ needs.detect-version-change.outputs.new-version }}"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          
+          # Create annotated tag
+          git tag -a "v$VERSION" -m "Release v$VERSION"
+          git push origin "v$VERSION"
+      
+      - name: Create GitHub Release
+        id: create
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          VERSION="${{ needs.detect-version-change.outputs.new-version }}"
+          IS_PRERELEASE="${{ needs.detect-version-change.outputs.is-prerelease }}"
+          
+          # Create release body
+          cat > release_body.md << 'EOF'
+          # Release v${{ needs.detect-version-change.outputs.new-version }}
+          
+          ${{ needs.extract-changelog.outputs.release-notes }}
+          
+          ---
+          
+          ## Installation
+          
+          ### NPM Package
+          ```bash
+          # Install globally
+          npm install -g n8n-mcp
+          
+          # Or run directly
+          npx n8n-mcp
+          ```
+          
+          ### Docker
+          ```bash
+          # Standard image
+          docker run -p 3000:3000 ghcr.io/czlonkowski/n8n-mcp:v${{ needs.detect-version-change.outputs.new-version }}
+          
+          # Railway optimized
+          docker run -p 3000:3000 ghcr.io/czlonkowski/n8n-mcp-railway:v${{ needs.detect-version-change.outputs.new-version }}
+          ```
+          
+          ## Documentation
+          - [Installation Guide](https://github.com/czlonkowski/n8n-mcp#installation)
+          - [Docker Deployment](https://github.com/czlonkowski/n8n-mcp/blob/main/docs/DOCKER_README.md)
+          - [n8n Integration](https://github.com/czlonkowski/n8n-mcp/blob/main/docs/N8N_DEPLOYMENT.md)
+          - [Complete Changelog](https://github.com/czlonkowski/n8n-mcp/blob/main/docs/CHANGELOG.md)
+          
+          🤖 *Generated with [Claude Code](https://claude.ai/code)*
+          EOF
+          
+          # Create release using gh CLI
+          if [ "$IS_PRERELEASE" = "true" ]; then
+            PRERELEASE_FLAG="--prerelease"
+          else
+            PRERELEASE_FLAG=""
+          fi
+          
+          gh release create "v$VERSION" \
+            --title "Release v$VERSION" \
+            --notes-file release_body.md \
+            $PRERELEASE_FLAG
+          
+          # Output release info for next jobs
+          RELEASE_ID=$(gh release view "v$VERSION" --json id --jq '.id')
+          echo "id=$RELEASE_ID" >> $GITHUB_OUTPUT
+          echo "upload_url=https://uploads.github.com/repos/${{ github.repository }}/releases/$RELEASE_ID/assets{?name,label}" >> $GITHUB_OUTPUT
+
+  build-and-test:
+    name: Build and Test
+    runs-on: ubuntu-latest
+    needs: detect-version-change
+    if: needs.detect-version-change.outputs.version-changed == 'true'
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+      
+      - name: Install dependencies
+        run: npm ci
+      
+      - name: Build project
+        run: npm run build
+      
+      - name: Rebuild database
+        run: npm run rebuild
+      
+      - name: Run tests
+        run: npm test
+        env:
+          CI: true
+      
+      - name: Run type checking
+        run: npm run typecheck
+
+  publish-npm:
+    name: Publish to NPM
+    runs-on: ubuntu-latest
+    needs: [detect-version-change, build-and-test, create-release]
+    if: needs.detect-version-change.outputs.version-changed == 'true'
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+          registry-url: 'https://registry.npmjs.org'
+      
+      - name: Install dependencies
+        run: npm ci
+      
+      - name: Build project
+        run: npm run build
+      
+      - name: Rebuild database
+        run: npm run rebuild
+      
+      - name: Sync runtime version
+        run: npm run sync:runtime-version
+      
+      - name: Prepare package for publishing
+        run: |
+          # Create publish directory
+          PUBLISH_DIR="npm-publish-temp"
+          rm -rf $PUBLISH_DIR
+          mkdir -p $PUBLISH_DIR
+          
+          # Copy necessary files
+          cp -r dist $PUBLISH_DIR/
+          cp -r data $PUBLISH_DIR/
+          cp README.md $PUBLISH_DIR/
+          cp LICENSE $PUBLISH_DIR/
+          cp .env.example $PUBLISH_DIR/
+          
+          # Use runtime package.json as base
+          cp package.runtime.json $PUBLISH_DIR/package.json
+          
+          cd $PUBLISH_DIR
+          
+          # Update package.json with complete metadata
+          node -e "
+          const pkg = require('./package.json');
+          pkg.name = 'n8n-mcp';
+          pkg.description = 'Integration between n8n workflow automation and Model Context Protocol (MCP)';
+          pkg.bin = { 'n8n-mcp': './dist/mcp/index.js' };
+          pkg.repository = { type: 'git', url: 'git+https://github.com/czlonkowski/n8n-mcp.git' };
+          pkg.keywords = ['n8n', 'mcp', 'model-context-protocol', 'ai', 'workflow', 'automation'];
+          pkg.author = 'Romuald Czlonkowski @ www.aiadvisors.pl/en';
+          pkg.license = 'MIT';
+          pkg.bugs = { url: 'https://github.com/czlonkowski/n8n-mcp/issues' };
+          pkg.homepage = 'https://github.com/czlonkowski/n8n-mcp#readme';
+          pkg.files = ['dist/**/*', 'data/nodes.db', '.env.example', 'README.md', 'LICENSE'];
+          delete pkg.private;
+          require('fs').writeFileSync('./package.json', JSON.stringify(pkg, null, 2));
+          "
+          
+          echo "Package prepared for publishing:"
+          echo "Name: $(node -e "console.log(require('./package.json').name)")"
+          echo "Version: $(node -e "console.log(require('./package.json').version)")"
+      
+      - name: Publish to NPM with retry
+        uses: nick-invision/retry@v2
+        with:
+          timeout_minutes: 5
+          max_attempts: 3
+          command: |
+            cd npm-publish-temp
+            npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      
+      - name: Clean up
+        if: always()
+        run: rm -rf npm-publish-temp
+
+  build-docker:
+    name: Build and Push Docker Images
+    runs-on: ubuntu-latest
+    needs: [detect-version-change, build-and-test]
+    if: needs.detect-version-change.outputs.version-changed == 'true'
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          lfs: true
+      
+      - name: Check disk space
+        run: |
+          echo "Disk usage before Docker build:"
+          df -h
+          
+          # Check available space (require at least 2GB)
+          AVAILABLE_GB=$(df / --output=avail --block-size=1G | tail -1)
+          if [ "$AVAILABLE_GB" -lt 2 ]; then
+            echo "❌ Insufficient disk space: ${AVAILABLE_GB}GB available, 2GB required"
+            exit 1
+          fi
+          echo "✅ Sufficient disk space: ${AVAILABLE_GB}GB available"
+      
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+      
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      
+      - name: Extract metadata for standard image
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=semver,pattern={{version}},value=v${{ needs.detect-version-change.outputs.new-version }}
+            type=semver,pattern={{major}}.{{minor}},value=v${{ needs.detect-version-change.outputs.new-version }}
+            type=semver,pattern={{major}},value=v${{ needs.detect-version-change.outputs.new-version }}
+            type=raw,value=latest,enable={{is_default_branch}}
+      
+      - name: Build and push standard Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+      
+      - name: Extract metadata for Railway image
+        id: meta-railway
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}-railway
+          tags: |
+            type=semver,pattern={{version}},value=v${{ needs.detect-version-change.outputs.new-version }}
+            type=semver,pattern={{major}}.{{minor}},value=v${{ needs.detect-version-change.outputs.new-version }}
+            type=semver,pattern={{major}},value=v${{ needs.detect-version-change.outputs.new-version }}
+            type=raw,value=latest,enable={{is_default_branch}}
+      
+      - name: Build and push Railway Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: ./Dockerfile.railway
+          platforms: linux/amd64
+          push: true
+          tags: ${{ steps.meta-railway.outputs.tags }}
+          labels: ${{ steps.meta-railway.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  update-documentation:
+    name: Update Documentation
+    runs-on: ubuntu-latest
+    needs: [detect-version-change, create-release, publish-npm, build-docker]
+    if: needs.detect-version-change.outputs.version-changed == 'true' && !failure()
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      
+      - name: Update version badges in README
+        run: |
+          VERSION="${{ needs.detect-version-change.outputs.new-version }}"
+          
+          # Update README version badges
+          if [ -f "README.md" ]; then
+            # Update npm version badge
+            sed -i.bak "s|npm/v/n8n-mcp/[^)]*|npm/v/n8n-mcp/$VERSION|g" README.md
+            
+            # Update any other version references
+            sed -i.bak "s|version-[0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*|version-$VERSION|g" README.md
+            
+            # Clean up backup file
+            rm -f README.md.bak
+            
+            echo "✅ Updated version badges in README.md to $VERSION"
+          fi
+      
+      - name: Commit documentation updates
+        env:
+          VERSION: ${{ needs.detect-version-change.outputs.new-version }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          
+          if git diff --quiet; then
+            echo "No documentation changes to commit"
+          else
+            git add README.md
+            git commit -m "docs: update version badges to v${VERSION}"
+            git push
+            echo "✅ Committed documentation updates"
+          fi
+
+  notify-completion:
+    name: Notify Release Completion
+    runs-on: ubuntu-latest
+    needs: [detect-version-change, create-release, publish-npm, build-docker, update-documentation]
+    if: always() && needs.detect-version-change.outputs.version-changed == 'true'
+    steps:
+      - name: Create release summary
+        run: |
+          VERSION="${{ needs.detect-version-change.outputs.new-version }}"
+          RELEASE_URL="https://github.com/${{ github.repository }}/releases/tag/v$VERSION"
+          
+          echo "## 🎉 Release v$VERSION Published Successfully!" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### ✅ Completed Tasks:" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          
+          # Check job statuses
+          if [ "${{ needs.create-release.result }}" = "success" ]; then
+            echo "- ✅ GitHub Release created: [$RELEASE_URL]($RELEASE_URL)" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "- ❌ GitHub Release creation failed" >> $GITHUB_STEP_SUMMARY
+          fi
+          
+          if [ "${{ needs.publish-npm.result }}" = "success" ]; then
+            echo "- ✅ NPM package published: [npmjs.com/package/n8n-mcp](https://www.npmjs.com/package/n8n-mcp)" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "- ❌ NPM publishing failed" >> $GITHUB_STEP_SUMMARY
+          fi
+          
+          if [ "${{ needs.build-docker.result }}" = "success" ]; then
+            echo "- ✅ Docker images built and pushed" >> $GITHUB_STEP_SUMMARY
+            echo "  - Standard: \`ghcr.io/czlonkowski/n8n-mcp:v$VERSION\`" >> $GITHUB_STEP_SUMMARY
+            echo "  - Railway: \`ghcr.io/czlonkowski/n8n-mcp-railway:v$VERSION\`" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "- ❌ Docker image building failed" >> $GITHUB_STEP_SUMMARY
+          fi
+          
+          if [ "${{ needs.update-documentation.result }}" = "success" ]; then
+            echo "- ✅ Documentation updated" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "- ⚠️ Documentation update skipped or failed" >> $GITHUB_STEP_SUMMARY
+          fi
+          
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### 📦 Installation:" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`bash" >> $GITHUB_STEP_SUMMARY
+          echo "# NPM" >> $GITHUB_STEP_SUMMARY
+          echo "npx n8n-mcp" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "# Docker" >> $GITHUB_STEP_SUMMARY
+          echo "docker run -p 3000:3000 ghcr.io/czlonkowski/n8n-mcp:v$VERSION" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+          
+          echo "🎉 Release automation completed for v$VERSION!"

.github/workflows/test.yml

@@ -0,0 +1,353 @@
+name: Test Suite
+on:
+  push:
+    branches: [main, feat/comprehensive-testing-suite]
+    paths-ignore:
+      - '**.md'
+      - '**.txt'
+      - 'docs/**'
+      - 'examples/**'
+      - '.github/FUNDING.yml'
+      - '.github/ISSUE_TEMPLATE/**'
+      - '.github/pull_request_template.md'
+      - '.gitignore'
+      - 'LICENSE*'
+      - 'ATTRIBUTION.md'
+      - 'SECURITY.md'
+      - 'CODE_OF_CONDUCT.md'
+  pull_request:
+    branches: [main]
+    paths-ignore:
+      - '**.md'
+      - '**.txt'
+      - 'docs/**'
+      - 'examples/**'
+      - '.github/FUNDING.yml'
+      - '.github/ISSUE_TEMPLATE/**'
+      - '.github/pull_request_template.md'
+      - '.gitignore'
+      - 'LICENSE*'
+      - 'ATTRIBUTION.md'
+      - 'SECURITY.md'
+      - 'CODE_OF_CONDUCT.md'
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+  checks: write
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10  # Add a 10-minute timeout to prevent hanging
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+      
+      - name: Install dependencies
+        run: npm ci
+      
+      # Verify test environment setup
+      - name: Verify test environment
+        run: |
+          echo "Current directory: $(pwd)"
+          echo "Checking for .env.test file:"
+          ls -la .env.test || echo ".env.test not found!"
+          echo "First few lines of .env.test:"
+          head -5 .env.test || echo "Cannot read .env.test"
+      
+      # Run unit tests first (without MSW)
+      - name: Run unit tests with coverage
+        run: npm run test:unit -- --coverage --coverage.thresholds.lines=0 --coverage.thresholds.functions=0 --coverage.thresholds.branches=0 --coverage.thresholds.statements=0 --reporter=default --reporter=junit
+        env:
+          CI: true
+      
+      # Run integration tests separately (with MSW setup)
+      - name: Run integration tests
+        run: npm run test:integration -- --reporter=default --reporter=junit
+        env:
+          CI: true
+          N8N_API_URL: ${{ secrets.N8N_API_URL }}
+          N8N_API_KEY: ${{ secrets.N8N_API_KEY }}
+          N8N_TEST_WEBHOOK_GET_URL: ${{ secrets.N8N_TEST_WEBHOOK_GET_URL }}
+          N8N_TEST_WEBHOOK_POST_URL: ${{ secrets.N8N_TEST_WEBHOOK_POST_URL }}
+          N8N_TEST_WEBHOOK_PUT_URL: ${{ secrets.N8N_TEST_WEBHOOK_PUT_URL }}
+          N8N_TEST_WEBHOOK_DELETE_URL: ${{ secrets.N8N_TEST_WEBHOOK_DELETE_URL }}
+      
+      # Generate test summary
+      - name: Generate test summary
+        if: always()
+        run: node scripts/generate-test-summary.js
+      
+      # Generate detailed reports
+      - name: Generate detailed reports
+        if: always()
+        run: node scripts/generate-detailed-reports.js
+      
+      # Upload test results artifacts
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-${{ github.run_number }}-${{ github.run_attempt }}
+          path: |
+            test-results/
+            test-summary.md
+            test-reports/
+          retention-days: 30
+          if-no-files-found: warn
+      
+      # Upload coverage artifacts
+      - name: Upload coverage reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-${{ github.run_number }}-${{ github.run_attempt }}
+          path: |
+            coverage/
+          retention-days: 30
+          if-no-files-found: warn
+      
+      # Upload coverage to Codecov
+      - name: Upload coverage to Codecov
+        if: always()
+        uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./coverage/lcov.info
+          flags: unittests
+          name: codecov-umbrella
+          fail_ci_if_error: false
+          verbose: true
+      
+      # Run linting
+      - name: Run linting
+        run: npm run lint
+      
+      # Run type checking
+      - name: Run type checking
+        run: npm run typecheck
+      
+      # Run benchmarks
+      - name: Run benchmarks
+        id: benchmarks
+        run: npm run benchmark:ci
+        continue-on-error: true
+      
+      # Upload benchmark results
+      - name: Upload benchmark results
+        if: always() && steps.benchmarks.outcome != 'skipped'
+        uses: actions/upload-artifact@v4
+        with:
+          name: benchmark-results-${{ github.run_number }}-${{ github.run_attempt }}
+          path: |
+            benchmark-results.json
+          retention-days: 30
+          if-no-files-found: warn
+      
+      # Create test report comment for PRs
+      - name: Create test report comment
+        if: github.event_name == 'pull_request' && always()
+        uses: actions/github-script@v7
+        continue-on-error: true
+        with:
+          script: |
+            const fs = require('fs');
+            let summary = '## Test Results\n\nTest summary generation failed.';
+            
+            try {
+              if (fs.existsSync('test-summary.md')) {
+                summary = fs.readFileSync('test-summary.md', 'utf8');
+              }
+            } catch (error) {
+              console.error('Error reading test summary:', error);
+            }
+            
+            try {
+              // Find existing comment
+              const { data: comments } = await github.rest.issues.listComments({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+              });
+              
+              const botComment = comments.find(comment => 
+                comment.user.type === 'Bot' && 
+                comment.body.includes('## Test Results')
+              );
+              
+              if (botComment) {
+                // Update existing comment
+                await github.rest.issues.updateComment({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  comment_id: botComment.id,
+                  body: summary
+                });
+              } else {
+                // Create new comment
+                await github.rest.issues.createComment({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: context.issue.number,
+                  body: summary
+                });
+              }
+            } catch (error) {
+              console.error('Failed to create/update PR comment:', error.message);
+              console.log('This is likely due to insufficient permissions for external PRs.');
+              console.log('Test results have been saved to the job summary instead.');
+            }
+      
+      # Generate job summary
+      - name: Generate job summary
+        if: always()
+        run: |
+          echo "# Test Run Summary" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          
+          if [ -f test-summary.md ]; then
+            cat test-summary.md >> $GITHUB_STEP_SUMMARY
+          else
+            echo "Test summary generation failed." >> $GITHUB_STEP_SUMMARY
+          fi
+          
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "## 📥 Download Artifacts" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "- [Test Results](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})" >> $GITHUB_STEP_SUMMARY
+          echo "- [Coverage Report](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})" >> $GITHUB_STEP_SUMMARY
+          echo "- [Benchmark Results](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})" >> $GITHUB_STEP_SUMMARY
+      
+      # Store test metadata
+      - name: Store test metadata
+        if: always()
+        run: |
+          cat > test-metadata.json << EOF
+          {
+            "run_id": "${{ github.run_id }}",
+            "run_number": "${{ github.run_number }}",
+            "run_attempt": "${{ github.run_attempt }}",
+            "sha": "${{ github.sha }}",
+            "ref": "${{ github.ref }}",
+            "event_name": "${{ github.event_name }}",
+            "repository": "${{ github.repository }}",
+            "actor": "${{ github.actor }}",
+            "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+            "node_version": "$(node --version)",
+            "npm_version": "$(npm --version)"
+          }
+          EOF
+      
+      - name: Upload test metadata
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-metadata-${{ github.run_number }}-${{ github.run_attempt }}
+          path: test-metadata.json
+          retention-days: 30
+
+  # Separate job to process and publish test results
+  publish-results:
+    needs: test
+    runs-on: ubuntu-latest
+    if: always()
+    permissions:
+      checks: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+      
+      # Download all artifacts
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+      
+      # Publish test results as checks
+      - name: Publish test results
+        uses: dorny/test-reporter@v1
+        if: always()
+        continue-on-error: true
+        with:
+          name: Test Results
+          path: 'artifacts/test-results-*/test-results/junit.xml'
+          reporter: java-junit
+          fail-on-error: false
+          fail-on-empty: false
+      
+      # Create a combined artifact with all results
+      - name: Create combined results artifact
+        if: always()
+        run: |
+          mkdir -p combined-results
+          cp -r artifacts/* combined-results/ 2>/dev/null || true
+          
+          # Create index file
+          cat > combined-results/index.html << 'EOF'
+          <!DOCTYPE html>
+          <html>
+          <head>
+              <title>n8n-mcp Test Results</title>
+              <style>
+                  body { font-family: Arial, sans-serif; margin: 40px; }
+                  h1 { color: #333; }
+                  .section { margin: 20px 0; padding: 20px; border: 1px solid #ddd; border-radius: 5px; }
+                  a { color: #0066cc; text-decoration: none; }
+                  a:hover { text-decoration: underline; }
+              </style>
+          </head>
+          <body>
+              <h1>n8n-mcp Test Results</h1>
+              <div class="section">
+                  <h2>Test Reports</h2>
+                  <ul>
+                      <li><a href="test-results-${{ github.run_number }}-${{ github.run_attempt }}/test-reports/report.html">📊 Detailed HTML Report</a></li>
+                      <li><a href="test-results-${{ github.run_number }}-${{ github.run_attempt }}/test-results/html/index.html">📈 Vitest HTML Report</a></li>
+                      <li><a href="test-results-${{ github.run_number }}-${{ github.run_attempt }}/test-reports/report.md">📄 Markdown Report</a></li>
+                      <li><a href="test-results-${{ github.run_number }}-${{ github.run_attempt }}/test-summary.md">📝 PR Summary</a></li>
+                      <li><a href="test-results-${{ github.run_number }}-${{ github.run_attempt }}/test-results/junit.xml">🔧 JUnit XML</a></li>
+                      <li><a href="test-results-${{ github.run_number }}-${{ github.run_attempt }}/test-results/results.json">🔢 JSON Results</a></li>
+                      <li><a href="test-results-${{ github.run_number }}-${{ github.run_attempt }}/test-reports/report.json">📊 Full JSON Report</a></li>
+                  </ul>
+              </div>
+              <div class="section">
+                  <h2>Coverage Reports</h2>
+                  <ul>
+                      <li><a href="coverage-${{ github.run_number }}-${{ github.run_attempt }}/html/index.html">HTML Coverage Report</a></li>
+                      <li><a href="coverage-${{ github.run_number }}-${{ github.run_attempt }}/lcov.info">LCOV Report</a></li>
+                      <li><a href="coverage-${{ github.run_number }}-${{ github.run_attempt }}/coverage-summary.json">Coverage Summary JSON</a></li>
+                  </ul>
+              </div>
+              <div class="section">
+                  <h2>Benchmark Results</h2>
+                  <ul>
+                      <li><a href="benchmark-results-${{ github.run_number }}-${{ github.run_attempt }}/benchmark-results.json">Benchmark Results JSON</a></li>
+                  </ul>
+              </div>
+              <div class="section">
+                  <h2>Metadata</h2>
+                  <ul>
+                      <li><a href="test-metadata-${{ github.run_number }}-${{ github.run_attempt }}/test-metadata.json">Test Run Metadata</a></li>
+                  </ul>
+              </div>
+              <div class="section">
+                  <p><em>Generated at $(date -u +%Y-%m-%dT%H:%M:%SZ)</em></p>
+                  <p><em>Run: #${{ github.run_number }} | SHA: ${{ github.sha }}</em></p>
+              </div>
+          </body>
+          </html>
+          EOF
+      
+      - name: Upload combined results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: all-test-results-${{ github.run_number }}
+          path: combined-results/
+          retention-days: 90

.gitignore

@@ -39,6 +39,26 @@ logs/
 # Testing
 coverage/
 .nyc_output/
+test-results/
+test-reports/
+test-summary.md
+test-metadata.json
+benchmark-results.json
+benchmark-results*.json
+benchmark-summary.json
+coverage-report.json
+benchmark-comparison.md
+benchmark-comparison.json
+benchmark-current.json
+benchmark-baseline.json
+tests/data/*.db
+tests/fixtures/*.tmp
+tests/test-results/
+.test-dbs/
+junit.xml
+*.test.db
+test-*.db
+.vitest/
 
 # TypeScript
 *.tsbuildinfo
@@ -69,11 +89,19 @@ docker-compose.override.yml
 temp/
 tmp/
 
+# Batch processing error files (may contain API tokens from templates)
+docs/batch_*.jsonl
+**/batch_*_error.jsonl
+
+# Local documentation and analysis files
+docs/local/
+
 # Database files
 # Database files - nodes.db is now tracked directly
 # data/*.db
 data/*.db-journal
 data/*.db.bak
+data/*.db.backup
 !data/.gitkeep
 !data/nodes.db
 
@@ -106,3 +134,9 @@ n8n-mcp-wrapper.sh
 
 # Package tarballs
 *.tgz
+
+# MCP configuration files
+.mcp.json
+
+# Telemetry configuration (user-specific)
+~/.n8n-mcp/

CLAUDE.md

@@ -6,137 +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.8.1)
-
-### Update (v2.8.1) - n8n Compatibility Mode for Strict Schema Validation:
-- ✅ **NEW: N8N_COMPATIBILITY_MODE** - Enable strict schema validation for n8n's MCP Client Tool
-- ✅ **FIXED: Schema validation errors** - "Received tool input did not match expected schema" error in n8n
-- ✅ **ENHANCED: Schema strictness** - All tools have `additionalProperties: false` in compatibility mode
-- ✅ **SEPARATE TOOL FILES** - Clean architecture with separate n8n-compatible tool definitions
-- ✅ **ENVIRONMENT TOGGLE** - Set `N8N_COMPATIBILITY_MODE=true` to enable strict schemas
-- ✅ **BACKWARD COMPATIBLE**: Defaults to standard mode when not configured
-
-### Update (v2.8.0) - SSE (Server-Sent Events) Support for n8n Integration:
-- ✅ **NEW: SSE mode** - Full Server-Sent Events implementation for n8n MCP Server Trigger
-- ✅ **NEW: Real-time streaming** - Push-based event streaming from server to n8n workflows
-- ✅ **NEW: Async tool execution** - Better support for long-running operations
-- ✅ **NEW: Session management** - Handle multiple concurrent n8n connections
-- ✅ **NEW: Keep-alive mechanism** - Automatic connection maintenance with 30s pings
-- ✅ **ADDED: SSE endpoints** - `/sse` for event stream, `/mcp/message` for requests
-- ✅ **BACKWARD COMPATIBLE** - Legacy `/mcp` endpoint continues to work
-- ✅ **Docker support** - New `docker-compose.sse.yml` for easy deployment
-- ✅ **Complete documentation** - See [SSE_IMPLEMENTATION.md](./docs/SSE_IMPLEMENTATION.md)
-
-### 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/
@@ -193,641 +62,134 @@ src/
 └── index.ts                   # Library exports
 ```
 
-### Key Metrics:
-- 525 nodes successfully loaded (100%) - Updated to n8n v1.97.1
-- 520 nodes with properties (99%)
-- 334 nodes with operations (63.6%)
-- 457 nodes with documentation (87%)
-- 263 AI-capable tools detected (major increase)
-- All critical nodes pass validation
-
-## Key Commands
+## Common Development Commands
 
 ```bash
-# Development
-npm install          # Install dependencies
-npm run build        # Build TypeScript (required before running)
-npm run dev          # Run in development mode with auto-reload
-npm test             # Run Jest tests
-npm run typecheck    # TypeScript type checking
-npm run lint         # Check TypeScript types (alias for typecheck)
+# Build and Setup
+npm run build          # Build TypeScript (always run after changes)
+npm run rebuild        # Rebuild node database from n8n packages
+npm run validate       # Validate all node data in database
 
-# Core Commands:
-npm run rebuild      # Rebuild node database
-npm run rebuild:optimized  # Build database with embedded source code
-npm run validate     # Validate critical nodes
-npm run test-nodes   # Test critical node properties/operations
+# Testing
+npm test               # Run all tests
+npm run test:unit      # Run unit tests only
+npm run test:integration # Run integration tests
+npm run test:coverage  # Run tests with coverage report
+npm run test:watch     # Run tests in watch mode
 
-# 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
+# Run a single test file
+npm test -- tests/unit/services/property-filter.test.ts
 
-# 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
-npm run test:n8n-manager   # Test n8n management tools integration
-npm run test:n8n-validate-workflow  # Test n8n_validate_workflow tool
-npm run test:typeversion-validation  # Test typeVersion validation
-npm run test:workflow-diff  # Test workflow diff engine
-npm run test:tools-documentation  # Test MCP tools documentation system
+# Linting and Type Checking
+npm run lint           # Check TypeScript types (alias for typecheck)
+npm run typecheck      # Check TypeScript types
 
-# Workflow Validation Commands:
-npm run test:workflow-validation   # Test workflow validation features
+# Running the Server
+npm start              # Start MCP server in stdio mode
+npm run start:http     # Start MCP server in HTTP mode
+npm run dev            # Build, rebuild database, and validate
+npm run dev:http       # Run HTTP server with auto-reload
 
-# Dependency Update Commands:
+# Update n8n Dependencies
 npm run update:n8n:check  # Check for n8n updates (dry run)
-npm run update:n8n        # Update n8n packages to latest versions
+npm run update:n8n        # Update n8n packages to latest
 
-# 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
-
-# Legacy Commands (deprecated):
-npm run db:rebuild   # Old rebuild command
-npm run db:init      # Initialize empty database
-npm run docs:rebuild # Rebuild documentation from TypeScript source
-
-# Production
-npm start            # Run built application (stdio mode)
-npm run start:http   # Run in HTTP mode for remote access
-
-# Docker Commands:
-docker compose up -d        # Start with Docker Compose
-docker compose logs -f      # View logs
-docker compose down         # Stop containers
-docker compose down -v      # Stop and remove volumes
-./scripts/test-docker.sh    # Test Docker deployment
+# Database Management
+npm run db:rebuild     # Rebuild database from scratch
+npm run migrate:fts5   # Migrate to FTS5 search (if needed)
 
+# Template Management
+npm run fetch:templates  # Fetch latest workflow templates from n8n.io
+npm run test:templates   # Test template functionality
 ```
 
-## Docker Deployment
-
-The project includes ultra-optimized Docker support with NO n8n dependencies at runtime:
-
-### 🚀 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:
-- **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
-
-### Quick Start with Docker
-```bash
-# IMPORTANT: Rebuild database first (requires n8n locally)
-npm run rebuild
-
-# Create .env file with auth token
-echo "AUTH_TOKEN=$(openssl rand -base64 32)" > .env
-
-# Start the server
-docker compose up -d
-
-# Check health
-curl http://localhost:3000/health
-```
-
-### Docker Architecture
-The Docker image contains ONLY these runtime dependencies:
-- `@modelcontextprotocol/sdk` - MCP protocol implementation
-- `better-sqlite3` / `sql.js` - SQLite database access
-- `express` - HTTP server mode
-- `dotenv` - Environment configuration
-
-### Docker Features
-- **Ultra-optimized size** (~280MB runtime-only)
-- **No n8n dependencies** in production image
-- **Pre-built database** required (nodes.db)
-- **BuildKit optimizations** for fast builds
-- **Non-root user** execution for security
-- **Health checks** built into the image
-
-### Docker Images
-- `ghcr.io/czlonkowski/n8n-mcp:latest` - Runtime-only production image
-- Multi-architecture support (amd64, arm64)
-- ~280MB compressed size (82% smaller!)
-
-### Docker Development
-```bash
-# Use BuildKit compose for development
-COMPOSE_DOCKER_CLI_BUILD=1 docker-compose -f docker-compose.buildkit.yml up
-
-# Build with optimizations
-./scripts/build-optimized.sh
-
-# Run tests
-./scripts/test-docker.sh
-```
-
-For detailed Docker documentation, see [DOCKER_README.md](./DOCKER_README.md).
-
 ## High-Level Architecture
 
-The project implements MCP (Model Context Protocol) to expose n8n node documentation, source code, and examples to AI assistants. Key architectural components:
-
-### Core Services
-- **NodeDocumentationService** (`src/services/node-documentation-service.ts`): Main database service using SQLite with FTS5 for fast searching
-- **MCP Server** (`src/mcp/server.ts`): Implements MCP protocol with tools for querying n8n nodes
-- **Node Source Extractor** (`src/utils/node-source-extractor.ts`): Extracts node implementations from n8n packages
-- **Enhanced Documentation Fetcher** (`src/utils/enhanced-documentation-fetcher.ts`): Fetches and parses official n8n documentation
-
-### MCP Tools Available
-- `list_nodes` - List all available n8n nodes with filtering
-- `get_node_info` - Get comprehensive information about a specific node (now includes aiToolCapabilities)
-- `get_node_essentials` - **NEW** Get only essential properties (10-20) with examples (95% smaller)
-- `get_node_as_tool_info` - **NEW v2.5.1** Get specific information about using ANY node as an AI tool
-- `search_nodes` - Full-text search across all node documentation
-- `search_node_properties` - **NEW** Search for specific properties within a node
-- `get_node_for_task` - **NEW** Get pre-configured node settings for common tasks
-- `list_tasks` - **NEW** List all available task templates
-- `validate_node_operation` - **NEW v2.4.2** Verify node configuration with operation awareness and profiles
-- `validate_node_minimal` - **NEW v2.4.2** Quick validation for just required fields
-- `validate_workflow` - **NEW v2.5.0** Validate entire workflows before deployment (now validates ai_tool connections)
-- `validate_workflow_connections` - **NEW v2.5.0** Check workflow structure and connections
-- `validate_workflow_expressions` - **NEW v2.5.0** Validate all n8n expressions in a workflow
-- `get_property_dependencies` - **NEW** Analyze property dependencies and visibility conditions
-- `list_ai_tools` - List all AI-capable nodes (now includes usage guidance)
-- `get_node_documentation` - Get parsed documentation from n8n-docs
-- `get_database_statistics` - Get database usage statistics and metrics
-- `list_node_templates` - **NEW** Find workflow templates using specific nodes
-- `get_template` - **NEW** Get complete workflow JSON for import
-- `search_templates` - **NEW** Search templates by keywords
-- `get_templates_for_task` - **NEW** Get curated templates for common tasks
-- `tools_documentation` - **NEW v2.7.3** Get comprehensive documentation for MCP tools
-
-### n8n Management Tools (NEW v2.6.0 - Requires API Configuration)
-These tools are only available when N8N_API_URL and N8N_API_KEY are configured:
-
-#### Workflow Management
-- `n8n_create_workflow` - Create new workflows with nodes and connections
-- `n8n_get_workflow` - Get complete workflow by ID
-- `n8n_get_workflow_details` - Get workflow with execution statistics
-- `n8n_get_workflow_structure` - Get simplified workflow structure
-- `n8n_get_workflow_minimal` - Get minimal workflow info
-- `n8n_update_full_workflow` - Update existing workflows (complete replacement)
-- `n8n_update_partial_workflow` - **NEW v2.7.0** Update workflows using diff operations
-- `n8n_delete_workflow` - Delete workflows permanently
-- `n8n_list_workflows` - List workflows with filtering
-- `n8n_validate_workflow` - **NEW v2.6.3** Validate workflow from n8n instance by ID
-
-#### Execution Management
-- `n8n_trigger_webhook_workflow` - Trigger workflows via webhook URL
-- `n8n_get_execution` - Get execution details by ID
-- `n8n_list_executions` - List executions with status filtering
-- `n8n_delete_execution` - Delete execution records
-
-#### System Tools
-- `n8n_health_check` - Check n8n API connectivity and features
-- `n8n_list_available_tools` - List all available management tools
-
-### Database Structure
-Uses SQLite with enhanced schema:
-- **nodes** table: Core node information with FTS5 indexing
-- **node_documentation**: Parsed markdown documentation
-- **node_examples**: Generated workflow examples
-- **node_source_code**: Complete TypeScript/JavaScript implementations
-
-## Important Development Notes
-
-### Initial Setup Requirements
-
-1. **Clone n8n-docs**: `git clone https://github.com/n8n-io/n8n-docs.git ../n8n-docs`
-2. **Install Dependencies**: `npm install`
-3. **Build**: `npm run build`
-4. **Rebuild Database**: `npm run rebuild`
-5. **Validate**: `npm run test-nodes`
-
-### Key Technical Decisions (v2.3)
-
-1. **Database Adapter Implementation**:
-   - Created `DatabaseAdapter` interface to abstract database operations
-   - Implemented `BetterSQLiteAdapter` and `SQLJSAdapter` classes
-   - Used factory pattern in `createDatabaseAdapter()` for automatic selection
-   - Added persistence layer for sql.js with debounced saves (100ms)
-
-2. **Compatibility Strategy**:
-   - Primary: Try better-sqlite3 first for performance
-   - Fallback: Catch native module errors and switch to sql.js
-   - Detection: Check for NODE_MODULE_VERSION errors specifically
-   - Logging: Clear messages about which adapter is active
-
-3. **Performance Considerations**:
-   - better-sqlite3: ~10-50x faster for most operations
-   - sql.js: ~2-5x slower but acceptable for this use case
-   - Auto-save: 100ms debounce prevents excessive disk writes with sql.js
-   - Memory: sql.js uses more memory but manageable for our dataset size
-
-### Node.js Version Compatibility
-
-The project now features automatic database adapter fallback for universal Node.js compatibility:
-
-1. **Primary adapter**: Uses `better-sqlite3` for optimal performance when available
-2. **Fallback adapter**: Automatically switches to `sql.js` (pure JavaScript) if:
-   - Native modules fail to load
-   - Node.js version mismatch detected
-   - Running in Claude Desktop or other restricted environments
-
-This means the project works with ANY Node.js version without manual intervention. The adapter selection is automatic and transparent.
-
-### Implementation Status
-- ✅ Property/operation extraction for 98.7% of nodes
-- ✅ Support for both n8n-nodes-base and @n8n/n8n-nodes-langchain
-- ✅ AI tool detection (35 tools with usableAsTool property)
-- ✅ Versioned node support (HTTPRequest, Code, etc.)
-- ✅ Documentation coverage for 88.6% of nodes
-- ⏳ Version history tracking (deferred - only current version)
-- ⏳ Workflow examples (deferred - using documentation)
-
-### Testing Workflow
-```bash
-npm run build        # Always build first
-npm test             # Run all tests
-npm run typecheck    # Verify TypeScript types
-```
-
-### Docker Development
-```bash
-# Local development with stdio
-docker-compose -f docker-compose.local.yml up
-
-# HTTP server mode
-docker-compose -f docker-compose.http.yml up
-```
-
-### Authentication (HTTP mode)
-When running in HTTP mode, use Bearer token authentication:
-```
-Authorization: Bearer your-auth-token
-```
-
-## Architecture Patterns
-
-### Service Layer Pattern
-All major functionality is implemented as services in `src/services/`. When adding new features:
-1. Create a service class with clear responsibilities
-2. Use dependency injection where appropriate
-3. Implement proper error handling with custom error types
-4. Add comprehensive logging using the logger utility
-
-### MCP Tool Implementation
-When adding new MCP tools:
-1. Define the tool in `src/mcp/tools.ts`
-2. Implement handler in `src/mcp/server.ts`
-3. Add proper input validation
-4. Return structured responses matching MCP expectations
-
-### Database Access Pattern
-- Use prepared statements for all queries
-- Implement proper transaction handling
-- Use FTS5 for text searching
-- Cache frequently accessed data in memory
-
-### Database Adapter Pattern (NEW in v2.3)
-The project uses a database adapter pattern for universal compatibility:
-- **Primary adapter**: `better-sqlite3` - Native SQLite bindings for optimal performance
-- **Fallback adapter**: `sql.js` - Pure JavaScript implementation for compatibility
-- **Automatic selection**: The system detects and handles version mismatches automatically
-- **Unified interface**: Both adapters implement the same `DatabaseAdapter` interface
-- **Transparent operation**: Application code doesn't need to know which adapter is active
-
-## Environment Configuration
-
-Required environment variables (see `.env.example`):
-```
-# Server Configuration
-NODE_ENV=development
-PORT=3000
-AUTH_TOKEN=your-secure-token
-
-# Trust proxy for correct IP logging (optional)
-# Set to 1 when behind a reverse proxy (Nginx, etc.)
-TRUST_PROXY=0
-
-# n8n Compatibility Mode (optional)
-# Enable strict schema validation for n8n's MCP Client Tool
-N8N_COMPATIBILITY_MODE=false
-
-# MCP Configuration  
-MCP_SERVER_NAME=n8n-documentation-mcp
-MCP_SERVER_VERSION=1.0.0
-
-# Logging
-LOG_LEVEL=info
-```
-
-## License
-
-This project is licensed under the MIT License. Created by Romuald Czlonkowski @ www.aiadvisors.pl/en.
-- ✅ Free for any use (personal, commercial, etc.)
-- ✅ Modifications and distribution allowed
-- ✅ Can be included in commercial products
-- ✅ Can be hosted as a service
-
-Attribution is appreciated but not required. See [LICENSE](LICENSE) and [ATTRIBUTION.md](ATTRIBUTION.md) for details.
-
-## HTTP Remote Deployment (v2.3.0)
-
-### ✅ HTTP Server Implementation Complete
-
-The project now includes a simplified HTTP server mode for remote deployments:
-- **Single-user design**: Stateless architecture for private deployments
-- **Simple token auth**: Bearer token authentication
-- **MCP-compatible**: Works with mcp-remote adapter for Claude Desktop
-- **Easy deployment**: Minimal configuration required
-
-### Quick Start
-```bash
-# Server setup
-export MCP_MODE=http
-export AUTH_TOKEN=$(openssl rand -base64 32)
-npm run start:http
-
-# Client setup (Claude Desktop config)
-{
-  "mcpServers": {
-    "n8n-remote": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@modelcontextprotocol/mcp-remote@latest",
-        "connect",
-        "https://your-server.com/mcp"
-      ],
-      "env": {
-        "MCP_AUTH_TOKEN": "your-auth-token"
-      }
-    }
-  }
-}
-```
-
-### Available Scripts
-- `npm run start:http` - Start in HTTP mode
-- `npm run http` - Build and start HTTP server
-- `npm run dev:http` - Development mode with auto-reload
-- `./scripts/deploy-http.sh` - Deployment helper script
-
-For detailed deployment instructions, see [HTTP Deployment Guide](./docs/HTTP_DEPLOYMENT.md).
-
-## Recent Problem Solutions
-
-### MCP HTTP Server Errors (Solved in v2.3.2)
-**Problem**: Two critical errors prevented the HTTP server from working:
-1. "stream is not readable" - Express.json() middleware consumed the request stream
-2. "Server not initialized" - StreamableHTTPServerTransport initialization issues
-
-**Solution**: Two-phase fix:
-1. Removed body parsing middleware to preserve raw stream
-2. Created direct JSON-RPC implementation bypassing StreamableHTTPServerTransport
-
-**Technical Details**:
-- `src/http-server-single-session.ts` - Single-session implementation (partial fix)
-- `src/http-server.ts` - Direct JSON-RPC implementation (complete fix)
-- `src/utils/console-manager.ts` - Console output isolation
-- Use `USE_FIXED_HTTP=true` to enable the fixed implementation
-
-### SQLite Version Mismatch (Solved in v2.3)
-**Problem**: Claude Desktop bundles Node.js v16.19.1, causing NODE_MODULE_VERSION errors with better-sqlite3 compiled for different versions.
-
-**Solution**: Implemented dual-adapter system:
-1. Database adapter abstraction layer
-2. Automatic fallback from better-sqlite3 to sql.js
-3. Transparent operation regardless of Node.js version
-4. No manual configuration required
-
-**Technical Details**:
-- `src/database/database-adapter.ts` - Adapter interface and implementations
-- `createDatabaseAdapter()` - Factory function with automatic selection
-- Modified all database operations to use adapter interface
-- Added sql.js with persistence support
-
-### Property Extraction Issues (Solved in v2.2)
-**Problem**: Many nodes had empty properties/operations arrays.
-
-**Solution**: Created dedicated `PropertyExtractor` class that handles:
-1. Instance-level property extraction
-2. Versioned node support
-3. Both programmatic and declarative styles
-4. Complex nested property structures
-
-### Dependency Update Issues (Solved in v2.3.3)
-**Problem**: n8n packages have interdependent version requirements. Updating them independently causes version mismatches.
-
-**Solution**: Implemented smart dependency update system:
-1. Check n8n's required dependency versions
-2. Update all packages to match n8n's requirements
-3. Validate database after updates
-4. Fix node type references in validation script
-
-**Technical Details**:
-- `scripts/update-n8n-deps.js` - Smart dependency updater
-- `.github/workflows/update-n8n-deps.yml` - GitHub Actions automation
-- `renovate.json` - Alternative Renovate configuration
-- Fixed validation to use 'nodes-base.httpRequest' format instead of 'httpRequest'
-
-### AI-Optimized Tools (NEW in v2.4.0)
-**Problem**: get_node_info returns 100KB+ of JSON with 200+ properties, making it nearly impossible for AI agents to efficiently configure nodes.
-
-**Solution**: Created new tools that provide progressive disclosure of information:
-1. `get_node_essentials` - Returns only the 10-20 most important properties
-2. `search_node_properties` - Find specific properties without downloading everything
-
-**Results**:
-- 95% reduction in response size (100KB → 5KB)
-- Only essential and commonly-used properties returned
-- Includes working examples for immediate use
-- AI agents can now configure nodes in seconds instead of minutes
-
-**Technical Implementation**:
-- `src/services/property-filter.ts` - Curated essential properties for 20+ nodes
-- `src/services/example-generator.ts` - Working examples for common use cases
-- Smart property search with relevance scoring
-- Automatic fallback for unconfigured nodes
-
-**Usage Recommendation**:
-```bash
-# OLD approach (avoid):
-get_node_info("nodes-base.httpRequest")  # 100KB+ response
-
-# NEW approach (prefer):
-get_node_essentials("nodes-base.httpRequest")  # 5KB response with examples
-```
-
-### Task-Based Configuration (NEW in v2.4.0)
-**Problem**: AI agents need to know exactly how to configure nodes for common tasks like "send email", "fetch API", or "update database".
-
-**Solution**: Created task template system:
-1. Pre-configured node settings for common tasks
-2. Working examples with proper credentials structure
-3. Task discovery via `list_tasks` tool
-
-**Results**:
-- Instant node configuration for common tasks
-- No guessing about property values
-- Production-ready configurations
-- Covers 30+ common automation tasks
-
-### Workflow Template Support (NEW in v2.4.1)
-**Problem**: AI agents needed complete workflow examples to understand how nodes work together.
-
-**Solution**: Integrated n8n.io workflow templates:
-1. **10,000+ templates** available via MCP tools
-2. Search by keywords or node usage
-3. Get complete workflow JSON for import
-4. Task-based template suggestions
-
-**Technical Details**:
-- Templates fetched from official n8n.io API
-- Stored in SQLite with FTS5 search
-- Includes metadata: categories, node counts, user ratings
-- Smart caching to prevent API overload
-
-### Enhanced Validation with Profiles (NEW in v2.4.2)
-**Problem**: Different validation needs - quick checks during editing vs thorough validation before deployment.
-
-**Solution**: Validation profiles with operation awareness:
-1. **strict** - Full validation (deployment)
-2. **standard** - Common issues only (default)
-3. **minimal** - Just required fields
-4. **quick** - Fast essential checks
-
-**Results**:
-- 90% faster validation for editing workflows
-- Operation-specific validation rules
-- Better error messages with fix suggestions
-- Node-specific validators for complex nodes
-
-### Complete Workflow Validation (NEW in v2.5.0)
-**Problem**: Node validation wasn't enough - needed to validate entire workflows including connections, expressions, and dependencies.
-
-**Solution**: Three-layer workflow validation:
-1. **Structure validation** - Nodes, connections, dependencies
-2. **Configuration validation** - All node configs with operation awareness  
-3. **Expression validation** - n8n expression syntax checking
-
-**Results**:
-- Catch workflow errors before deployment
-- Validate complex multi-node workflows
-- Check all n8n expressions for syntax errors
-- Ensure proper node connections and data flow
-
-### AI Tool Support Enhancement (NEW in v2.5.1)
-**Problem**: AI agents needed better guidance on using n8n nodes as AI tools and understanding tool connections.
-
-**Solution**: Enhanced AI tool support:
-1. New `get_node_as_tool_info` - Explains how ANY node can be used as an AI tool
-2. Enhanced workflow validation for ai_tool node connections
-3. Better documentation for AI tool usage patterns
-4. Validation ensures proper tool node connections
-
-**Results**:
-- AI agents can now properly configure AI tool workflows
-- Clear guidance on credential requirements for tools
-- Validation catches common AI workflow mistakes
-- Supports both native AI nodes and regular nodes as tools
-
-### n8n Management Integration (NEW in v2.6.0)
-**Problem**: AI agents could discover and validate workflows but couldn't deploy or execute them.
-
-**Solution**: Integrated n8n-manager-for-ai-agents functionality:
-1. **14 new management tools** when API configured
-2. Complete workflow lifecycle support
-3. Smart error handling for API limitations
-4. Optional feature - only loads when configured
-
-**Results**:
-- Full workflow automation: discover → build → validate → deploy → execute
-- Webhook-based workflow triggering
-- Execution monitoring and management
-- Backwards compatible - doesn't affect existing functionality
-
-### Workflow Diff Engine (NEW in v2.7.0)
-**Problem**: Updating workflows required sending the entire JSON (often 50KB+), wasting tokens and making it hard to see what changed.
-
-**Solution**: Diff-based workflow updates:
-1. **13 targeted operations** - Add, remove, update, move nodes/connections
-2. **80-90% token savings** - Only send the changes
-3. **Transactional updates** - All changes validated before applying
-4. **Order independence** - Add connections before nodes exist
-
-**Results**:
-- Update a single node property without sending entire workflow
-- Clear audit trail of what changed
-- Safer updates with validation
-- Works with any workflow size
-
-## Known Issues
-
-### Claude Desktop - Duplicate Container Bug
-When adding n8n-mcp to Claude Desktop, you might see "Container with name '/n8n-mcp-container' already exists" error. This is a Claude Desktop bug where it doesn't properly clean up containers between sessions.
-
-**Workaround**: Add this to your Claude Desktop config to use a unique container name each time:
-```json
-{
-  "command": "docker",
-  "args": [
-    "run", 
-    "--rm", 
-    "--name", "n8n-mcp-{{timestamp}}",
-    "-e", "AUTH_TOKEN=your-token",
-    "ghcr.io/czlonkowski/n8n-mcp:latest"
-  ]
-}
-```
-
-Note: `{{timestamp}}` is not actually supported by Claude Desktop. The real workaround is to manually remove the container when this happens:
-```bash
-docker rm n8n-mcp-container
-```
-
-See [Issue #13](https://github.com/czlonkowski/n8n-mcp/issues/13) for more details.
-
-## npm Publishing
-
-To publish a new version to npm:
-
-```bash
-# 1. Update version in package.json
-npm version patch  # or minor/major
-
-# 2. Prepare the publish directory
-npm run prepare:publish
-
-# 3. Publish to npm (requires OTP)
-cd npm-publish-temp
-npm publish --otp=YOUR_OTP_CODE
-
-# 4. Clean up
-cd ..
-rm -rf npm-publish-temp
-```
-
-The published package can then be used with npx:
-```bash
-npx n8n-mcp
-```
-
-## Future Enhancements
-
-### Planned Features
-- Historical version tracking for nodes
-- Workflow template generation from examples
-- Performance metrics and optimization suggestions
-- Integration with n8n Cloud API for live data
-- WebSocket support for real-time updates
-
-### Contributing
-Contributions are welcome! Please:
-1. Follow the existing code patterns
-2. Add tests for new functionality
-3. Update documentation as needed
-4. Run all tests before submitting PRs
-
-For questions or support, please open an issue on GitHub.
+### Core Components
+
+1. **MCP Server** (`mcp/server.ts`)
+   - Implements Model Context Protocol for AI assistants
+   - Provides tools for searching, validating, and managing n8n nodes
+   - Supports both stdio (Claude Desktop) and HTTP modes
+
+2. **Database Layer** (`database/`)
+   - SQLite database storing all n8n node information
+   - Universal adapter pattern supporting both better-sqlite3 and sql.js
+   - Full-text search capabilities with FTS5
+
+3. **Node Processing Pipeline**
+   - **Loader** (`loaders/node-loader.ts`): Loads nodes from n8n packages
+   - **Parser** (`parsers/node-parser.ts`): Extracts node metadata and structure
+   - **Property Extractor** (`parsers/property-extractor.ts`): Deep property analysis
+   - **Docs Mapper** (`mappers/docs-mapper.ts`): Maps external documentation
+
+4. **Service Layer** (`services/`)
+   - **Property Filter**: Reduces node properties to AI-friendly essentials
+   - **Config Validator**: Multi-profile validation system
+   - **Expression Validator**: Validates n8n expression syntax
+   - **Workflow Validator**: Complete workflow structure validation
+
+5. **Template System** (`templates/`)
+   - Fetches and stores workflow templates from n8n.io
+   - Provides pre-built workflow examples
+   - Supports template search and validation
+
+### Key Design Patterns
+
+1. **Repository Pattern**: All database operations go through repository classes
+2. **Service Layer**: Business logic separated from data access
+3. **Validation Profiles**: Different validation strictness levels (minimal, runtime, ai-friendly, strict)
+4. **Diff-Based Updates**: Efficient workflow updates using operation diffs
+
+### MCP Tools Architecture
+
+The MCP server exposes tools in several categories:
+
+1. **Discovery Tools**: Finding and exploring nodes
+2. **Configuration Tools**: Getting node details and examples
+3. **Validation Tools**: Validating configurations before deployment
+4. **Workflow Tools**: Complete workflow validation
+5. **Management Tools**: Creating and updating workflows (requires API config)
+
+## Memories and Notes for Development
+
+### Development Workflow Reminders
+- When you make changes to MCP server, you need to ask the user to reload it before you test
+- When the user asks to review issues, you should use GH CLI to get the issue and all the comments
+- When the task can be divided into separated subtasks, you should spawn separate sub-agents to handle them in parallel
+- Use the best sub-agent for the task as per their descriptions
+
+### Testing Best Practices
+- Always run `npm run build` before testing changes
+- Use `npm run dev` to rebuild database after package updates
+- Check coverage with `npm run test:coverage`
+- Integration tests require a clean database state
+
+### Common Pitfalls
+- The MCP server needs to be reloaded in Claude Desktop after changes
+- HTTP mode requires proper CORS and auth token configuration
+- Database rebuilds can take 2-3 minutes due to n8n package size
+- Always validate workflows before deployment to n8n
+
+### Performance Considerations
+- Use `get_node_essentials()` instead of `get_node_info()` for faster responses
+- Batch validation operations when possible
+- The diff-based update system saves 80-90% tokens on workflow updates
+
+### Agent Interaction Guidelines
+- Sub-agents are not allowed to spawn further sub-agents
+- When you use sub-agents, do not allow them to commit and push. That should be done by you
+
+### Development Best Practices
+- Run typecheck and lint after every code change
+
+# important-instruction-reminders
+Do what has been asked; nothing more, nothing less.
+NEVER create files unless they're absolutely necessary for achieving your goal.
+ALWAYS prefer editing an existing file to creating a new one.
+NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
+- When you make changes to MCP server, you need to ask the user to reload it before you test
+- When the user asks to review issues, you should use GH CLI to get the issue and all the comments
+- When the task can be divided into separated subtasks, you should spawn separate sub-agents to handle them in paralel
+- Use the best sub-agent for the task as per their descriptions
+- Do not use hyperbolic or dramatic language in comments and documentation

Dockerfile

@@ -2,31 +2,33 @@
 # Ultra-optimized Dockerfile - minimal runtime dependencies (no n8n packages)
 
 # Stage 1: Builder (TypeScript compilation only)
-FROM node:20-alpine AS builder
+FROM node:22-alpine AS builder
 WORKDIR /app
 
-# Copy tsconfig for TypeScript compilation
-COPY tsconfig.json ./
+# Copy tsconfig files for TypeScript compilation
+COPY tsconfig*.json ./
 
 # Create minimal package.json and install ONLY build dependencies
+# Note: openai and zod are needed for TypeScript compilation of template metadata modules
 RUN --mount=type=cache,target=/root/.npm \
     echo '{}' > package.json && \
     npm install --no-save typescript@^5.8.3 @types/node@^22.15.30 @types/express@^5.0.3 \
         @modelcontextprotocol/sdk@^1.12.1 dotenv@^16.5.0 express@^5.1.0 axios@^1.10.0 \
-        n8n-workflow@^1.96.0 uuid@^11.0.5 @types/uuid@^10.0.0
+        n8n-workflow@^1.96.0 uuid@^11.0.5 @types/uuid@^10.0.0 \
+        openai@^4.77.0 zod@^3.24.1 lru-cache@^11.2.1 @supabase/supabase-js@^2.57.4
 
 # Copy source and build
 COPY src ./src
 # Note: src/n8n contains TypeScript types needed for compilation
 # These will be compiled but not included in runtime
-RUN npx tsc
+RUN npx tsc -p tsconfig.build.json
 
 # Stage 2: Runtime (minimal dependencies)
-FROM node:20-alpine AS runtime
+FROM node:22-alpine AS runtime
 WORKDIR /app
 
 # Install only essential runtime tools
-RUN apk add --no-cache curl && \
+RUN apk add --no-cache curl su-exec && \
     rm -rf /var/cache/apk/*
 
 # Copy runtime-only package.json
@@ -45,9 +47,11 @@ COPY data/nodes.db ./data/
 COPY src/database/schema-optimized.sql ./src/database/
 COPY .env.example ./
 
-# Copy entrypoint script
+# Copy entrypoint script, config parser, and n8n-mcp command
 COPY docker/docker-entrypoint.sh /usr/local/bin/
-RUN chmod +x /usr/local/bin/docker-entrypoint.sh
+COPY docker/parse-config.js /app/docker/
+COPY docker/n8n-mcp /usr/local/bin/
+RUN chmod +x /usr/local/bin/docker-entrypoint.sh /usr/local/bin/n8n-mcp
 
 # Add container labels
 LABEL org.opencontainers.image.source="https://github.com/czlonkowski/n8n-mcp"
@@ -55,9 +59,13 @@ LABEL org.opencontainers.image.description="n8n MCP Server - Runtime Only"
 LABEL org.opencontainers.image.licenses="MIT"
 LABEL org.opencontainers.image.title="n8n-mcp"
 
-# Create non-root user
-RUN addgroup -g 1001 -S nodejs && \
-    adduser -S nodejs -u 1001 && \
+# Create non-root user with unpredictable UID/GID
+# Using a hash of the build time to generate unpredictable IDs
+RUN BUILD_HASH=$(date +%s | sha256sum | head -c 8) && \
+    UID=$((10000 + 0x${BUILD_HASH} % 50000)) && \
+    GID=$((10000 + 0x${BUILD_HASH} % 50000)) && \
+    addgroup -g ${GID} -S nodejs && \
+    adduser -S nodejs -u ${UID} -G nodejs && \
     chown -R nodejs:nodejs /app
 
 # Switch to non-root user
@@ -66,13 +74,20 @@ USER nodejs
 # Set Docker environment flag
 ENV IS_DOCKER=true
 
+# Telemetry: Anonymous usage statistics are ENABLED by default
+# To opt-out, uncomment the following line:
+# ENV N8N_MCP_TELEMETRY_DISABLED=true
+
 # Expose HTTP port
 EXPOSE 3000
 
+# Set stop signal to SIGTERM (default, but explicit is better)
+STOPSIGNAL SIGTERM
+
 # Health check
 HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
   CMD curl -f http://127.0.0.1:3000/health || exit 1
 
 # Optimized entrypoint
 ENTRYPOINT ["/usr/local/bin/docker-entrypoint.sh"]
-CMD ["node", "dist/mcp/index.js"]
+CMD ["node", "dist/mcp/index.js"]

Dockerfile.railway

@@ -0,0 +1,88 @@
+# syntax=docker/dockerfile:1.7
+# Railway-compatible Dockerfile for n8n-mcp
+
+# --- Stage 1: Builder ---
+FROM node:22-alpine AS builder
+WORKDIR /app
+
+# Install system dependencies for native modules
+RUN apk add --no-cache python3 make g++ && \
+    rm -rf /var/cache/apk/*
+
+# Copy package files and tsconfig files
+COPY package*.json tsconfig*.json ./
+
+# Install all dependencies (including devDependencies for build)
+RUN npm ci --no-audit --no-fund
+
+# Copy source code
+COPY src ./src
+
+# Build the application
+RUN npm run build
+
+# --- Stage 2: Runtime ---
+FROM node:22-alpine AS runtime
+WORKDIR /app
+
+# Install system dependencies
+RUN apk add --no-cache curl python3 make g++ && \
+    rm -rf /var/cache/apk/*
+
+# Copy runtime-only package.json
+COPY package.runtime.json package.json
+
+# Install only production dependencies
+RUN npm install --production --no-audit --no-fund && \
+    npm cache clean --force
+
+# Copy built application from builder stage
+COPY --from=builder /app/dist ./dist
+
+# Copy necessary data and configuration files
+COPY data/ ./data/
+COPY src/database/schema-optimized.sql ./src/database/schema-optimized.sql
+COPY .env.example ./
+
+# Copy entrypoint script
+COPY docker/docker-entrypoint.sh /usr/local/bin/
+RUN chmod +x /usr/local/bin/docker-entrypoint.sh
+
+# Create data directory if it doesn't exist and set permissions
+RUN mkdir -p ./data && \
+    chmod 755 ./data
+
+# Add metadata labels
+LABEL org.opencontainers.image.source="https://github.com/czlonkowski/n8n-mcp"
+LABEL org.opencontainers.image.description="n8n MCP Server - Integration between n8n workflow automation and Model Context Protocol"
+LABEL org.opencontainers.image.licenses="MIT"
+LABEL org.opencontainers.image.title="n8n-mcp"
+LABEL org.opencontainers.image.version="2.7.13"
+
+# Create non-root user for security
+RUN addgroup -g 1001 -S nodejs && \
+    adduser -S nodejs -u 1001 && \
+    chown -R nodejs:nodejs /app
+USER nodejs
+
+# Set Railway-optimized environment variables
+ENV AUTH_TOKEN="REPLACE_THIS_AUTH_TOKEN_32_CHARS_MIN_abcdefgh"
+ENV NODE_ENV=production
+ENV IS_DOCKER=true
+ENV MCP_MODE=http
+ENV USE_FIXED_HTTP=true
+ENV LOG_LEVEL=info
+ENV TRUST_PROXY=1
+ENV HOST=0.0.0.0
+ENV CORS_ORIGIN="*"
+
+# Expose port (Railway will set PORT automatically)
+EXPOSE 3000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+  CMD curl -f http://127.0.0.1:${PORT:-3000}/health || exit 1
+
+# Optimized entrypoint (identical to main Dockerfile)
+ENTRYPOINT ["/usr/local/bin/docker-entrypoint.sh"]
+CMD ["node", "dist/mcp/index.js", "--http"]

Dockerfile.test

@@ -1,5 +1,5 @@
 # Quick test Dockerfile using pre-built files
-FROM node:20-alpine
+FROM node:22-alpine
 
 WORKDIR /app
 

MEMORY_N8N_UPDATE.md

@@ -1,17 +1,49 @@
 # n8n Update Process - Quick Reference
 
-## Quick Steps to Update n8n
+## Quick One-Command Update
 
-When there's a new n8n version available, follow these steps:
+For a complete update with tests and publish preparation:
+
+```bash
+npm run update:all
+```
+
+This single command will:
+1. ✅ Check for n8n updates and ask for confirmation
+2. ✅ Update all n8n dependencies to latest compatible versions
+3. ✅ Run all 1,182 tests (933 unit + 249 integration)
+4. ✅ Validate critical nodes
+5. ✅ Build the project
+6. ✅ Bump the version
+7. ✅ Update README badges
+8. ✅ Prepare everything for npm publish
+9. ✅ Create a comprehensive commit
+
+## Manual Steps (if needed)
+
+### Quick Steps to Update n8n
 
 ```bash
 # 1. Update n8n dependencies automatically
 npm run update:n8n
 
-# 2. Validate the update
+# 2. Run tests
+npm test
+
+# 3. Validate the update
 npm run validate
 
-# 3. Commit and push
+# 4. Build
+npm run build
+
+# 5. Bump version
+npm version patch
+
+# 6. Update README badges manually
+# - Update version badge
+# - Update n8n version badge
+
+# 7. Commit and push
 git add -A
 git commit -m "chore: update n8n to vX.X.X
 
@@ -21,6 +53,7 @@ git commit -m "chore: update n8n to vX.X.X
 - Updated @n8n/n8n-nodes-langchain from X.X.X to X.X.X
 - Rebuilt node database with XXX nodes
 - Sanitized XXX workflow templates (if present)
+- All 1,182 tests passing (933 unit, 249 integration)
 - All validation tests passing
 
 🤖 Generated with [Claude Code](https://claude.ai/code)
@@ -31,8 +64,21 @@ git push origin main
 
 ## What the Commands Do
 
+### `npm run update:all`
+This comprehensive command:
+1. Checks current branch and git status
+2. Shows current versions and checks for updates
+3. Updates all n8n dependencies to compatible versions
+4. **Runs the complete test suite** (NEW!)
+5. Validates critical nodes
+6. Builds the project
+7. Bumps the patch version
+8. Updates version badges in README
+9. Creates a detailed commit with all changes
+10. Provides next steps for GitHub release and npm publish
+
 ### `npm run update:n8n`
-This single command:
+This command:
 1. Checks for the latest n8n version
 2. Updates n8n and all its required dependencies (n8n-core, n8n-workflow, @n8n/n8n-nodes-langchain)
 3. Runs `npm install` to update package-lock.json
@@ -45,13 +91,20 @@ This single command:
 - Shows database statistics
 - Confirms everything is working correctly
 
+### `npm test`
+- Runs all 1,182 tests
+- Unit tests: 933 tests across 30 files
+- Integration tests: 249 tests across 14 files
+- Must pass before publishing!
+
 ## Important Notes
 
 1. **Always run on main branch** - Make sure you're on main and it's clean
 2. **The update script is smart** - It automatically syncs all n8n dependencies to compatible versions
-3. **Database rebuild is automatic** - The update script handles this for you
-4. **Template sanitization is automatic** - Any API tokens in workflow templates are replaced with placeholders
-5. **Docker image builds automatically** - Pushing to GitHub triggers the workflow
+3. **Tests are required** - The publish script now runs tests automatically
+4. **Database rebuild is automatic** - The update script handles this for you
+5. **Template sanitization is automatic** - Any API tokens in workflow templates are replaced with placeholders
+6. **Docker image builds automatically** - Pushing to GitHub triggers the workflow
 
 ## GitHub Push Protection
 
@@ -62,12 +115,18 @@ As of July 2025, GitHub's push protection may block database pushes if they cont
 3. If push is still blocked, use the GitHub web interface to review and allow the push
 
 ## Time Estimate
-- Total time: ~3-5 minutes
-- Most time is spent on `npm install` and database rebuild
-- The actual commands take seconds to run
+- Total time: ~5-7 minutes
+- Test suite: ~2.5 minutes
+- npm install and database rebuild: ~2-3 minutes
+- The rest: seconds
 
 ## Troubleshooting
 
+If tests fail:
+1. Check the test output for specific failures
+2. Run `npm run test:unit` or `npm run test:integration` separately
+3. Fix any issues before proceeding with the update
+
 If validation fails:
 1. Check the error message - usually it's a node type reference issue
 2. The update script handles most compatibility issues automatically
@@ -79,4 +138,23 @@ To see what would be updated without making changes:
 npm run update:n8n:check
 ```
 
-This shows you the available updates without modifying anything.
+This shows you the available updates without modifying anything.
+
+## Publishing to npm
+
+After updating:
+```bash
+# Prepare for publish (runs tests automatically)
+npm run prepare:publish
+
+# Follow the instructions to publish with OTP
+cd npm-publish-temp
+npm publish --otp=YOUR_OTP_CODE
+```
+
+## Creating a GitHub Release
+
+After pushing:
+```bash
+gh release create vX.X.X --title "vX.X.X" --notes "Updated n8n to vX.X.X"
+```

MEMORY_TEMPLATE_UPDATE.md

@@ -0,0 +1,336 @@
+# Template Update Process - Quick Reference
+
+## Overview
+
+The n8n-mcp project maintains a database of workflow templates from n8n.io. This guide explains how to update the template database incrementally without rebuilding from scratch.
+
+## Current Database State
+
+As of the last update:
+- **2,598 templates** in database
+- Templates from the last 12 months
+- Latest template: September 12, 2025
+
+## Quick Commands
+
+### Incremental Update (Recommended)
+```bash
+# Build if needed
+npm run build
+
+# Fetch only NEW templates (5-10 minutes)
+npm run fetch:templates:update
+```
+
+### Full Rebuild (Rare)
+```bash
+# Rebuild entire database from scratch (30-40 minutes)
+npm run fetch:templates
+```
+
+## How It Works
+
+### Incremental Update Mode (`--update`)
+
+The incremental update is **smart and efficient**:
+
+1. **Loads existing template IDs** from database (~2,598 templates)
+2. **Fetches template list** from n8n.io API (all templates from last 12 months)
+3. **Filters** to find only NEW templates not in database
+4. **Fetches details** for new templates only (saves time and API calls)
+5. **Saves** new templates to database (existing ones untouched)
+6. **Rebuilds FTS5** search index for new templates
+
+### Key Benefits
+
+✅ **Non-destructive**: All existing templates preserved
+✅ **Fast**: Only fetches new templates (5-10 min vs 30-40 min)
+✅ **API friendly**: Reduces load on n8n.io API
+✅ **Safe**: Preserves AI-generated metadata
+✅ **Smart**: Automatically skips duplicates
+
+## Performance Comparison
+
+| Mode | Templates Fetched | Time | Use Case |
+|------|------------------|------|----------|
+| **Update** | Only new (~50-200) | 5-10 min | Regular updates |
+| **Rebuild** | All (~8000+) | 30-40 min | Initial setup or corruption |
+
+## Command Options
+
+### Basic Update
+```bash
+npm run fetch:templates:update
+```
+
+### Full Rebuild
+```bash
+npm run fetch:templates
+```
+
+### With Metadata Generation
+```bash
+# Update templates and generate AI metadata
+npm run fetch:templates -- --update --generate-metadata
+
+# Or just generate metadata for existing templates
+npm run fetch:templates -- --metadata-only
+```
+
+### Help
+```bash
+npm run fetch:templates -- --help
+```
+
+## Update Frequency
+
+Recommended update schedule:
+- **Weekly**: Run incremental update to get latest templates
+- **Monthly**: Review database statistics
+- **As needed**: Rebuild only if database corruption suspected
+
+## Template Filtering
+
+The fetcher automatically filters templates:
+- ✅ **Includes**: Templates from last 12 months
+- ✅ **Includes**: Templates with >10 views
+- ❌ **Excludes**: Templates with ≤10 views (too niche)
+- ❌ **Excludes**: Templates older than 12 months
+
+## Workflow
+
+### Regular Update Workflow
+
+```bash
+# 1. Check current state
+sqlite3 data/nodes.db "SELECT COUNT(*) FROM templates"
+
+# 2. Build project (if code changed)
+npm run build
+
+# 3. Run incremental update
+npm run fetch:templates:update
+
+# 4. Verify new templates added
+sqlite3 data/nodes.db "SELECT COUNT(*) FROM templates"
+```
+
+### After n8n Dependency Update
+
+When you update n8n dependencies, templates remain compatible:
+```bash
+# 1. Update n8n (from MEMORY_N8N_UPDATE.md)
+npm run update:all
+
+# 2. Fetch new templates incrementally
+npm run fetch:templates:update
+
+# 3. Check how many templates were added
+sqlite3 data/nodes.db "SELECT COUNT(*) FROM templates"
+
+# 4. Generate AI metadata for new templates (optional, requires OPENAI_API_KEY)
+npm run fetch:templates -- --metadata-only
+
+# 5. IMPORTANT: Sanitize templates before pushing database
+npm run build
+npm run sanitize:templates
+```
+
+Templates are independent of n8n version - they're just workflow JSON data.
+
+**CRITICAL**: Always run `npm run sanitize:templates` before pushing the database to remove API tokens from template workflows.
+
+**Note**: New templates fetched via `--update` mode will NOT have AI-generated metadata by default. You need to run `--metadata-only` separately to generate metadata for templates that don't have it yet.
+
+## Troubleshooting
+
+### No New Templates Found
+
+This is normal! It means:
+- All recent templates are already in your database
+- n8n.io hasn't published many new templates recently
+- Your database is up to date
+
+```bash
+📊 Update mode: 0 new templates to fetch (skipping 2598 existing)
+✅ All templates already have metadata
+```
+
+### API Rate Limiting
+
+If you hit rate limits:
+- The fetcher includes built-in delays (150ms between requests)
+- Wait a few minutes and try again
+- Use `--update` mode instead of full rebuild
+
+### Database Corruption
+
+If you suspect corruption:
+```bash
+# Full rebuild from scratch
+npm run fetch:templates
+
+# This will:
+# - Drop and recreate templates table
+# - Fetch all templates fresh
+# - Rebuild search indexes
+```
+
+## Database Schema
+
+Templates are stored with:
+- Basic info (id, name, description, author, views, created_at)
+- Node types used (JSON array)
+- Complete workflow (gzip compressed, base64 encoded)
+- AI-generated metadata (optional, requires OpenAI API key)
+- FTS5 search index for fast text search
+
+## Metadata Generation
+
+Generate AI metadata for templates:
+```bash
+# Requires OPENAI_API_KEY in .env
+export OPENAI_API_KEY="sk-..."
+
+# Generate for templates without metadata (recommended after incremental update)
+npm run fetch:templates -- --metadata-only
+
+# Generate during template fetch (slower, but automatic)
+npm run fetch:templates:update -- --generate-metadata
+```
+
+**Important**: Incremental updates (`--update`) do NOT generate metadata by default. After running `npm run fetch:templates:update`, you'll have new templates without metadata. Run `--metadata-only` separately to generate metadata for them.
+
+### Check Metadata Coverage
+
+```bash
+# See how many templates have metadata
+sqlite3 data/nodes.db "SELECT
+  COUNT(*) as total,
+  SUM(CASE WHEN metadata_json IS NOT NULL THEN 1 ELSE 0 END) as with_metadata,
+  SUM(CASE WHEN metadata_json IS NULL THEN 1 ELSE 0 END) as without_metadata
+FROM templates"
+
+# See recent templates without metadata
+sqlite3 data/nodes.db "SELECT id, name, created_at
+FROM templates
+WHERE metadata_json IS NULL
+ORDER BY created_at DESC
+LIMIT 10"
+```
+
+Metadata includes:
+- Categories
+- Complexity level (simple/medium/complex)
+- Use cases
+- Estimated setup time
+- Required services
+- Key features
+- Target audience
+
+### Metadata Generation Troubleshooting
+
+If metadata generation fails:
+
+1. **Check error file**: Errors are saved to `temp/batch/batch_*_error.jsonl`
+2. **Common issues**:
+   - `"Unsupported value: 'temperature'"` - Model doesn't support custom temperature
+   - `"Invalid request"` - Check OPENAI_API_KEY is valid
+   - Model availability issues
+3. **Model**: Uses `gpt-5-mini-2025-08-07` by default
+4. **Token limit**: 3000 tokens per request for detailed metadata
+
+The system will automatically:
+- Process error files and assign default metadata to failed templates
+- Save error details for debugging
+- Continue processing even if some templates fail
+
+**Example error handling**:
+```bash
+# If you see: "No output file available for batch job"
+# Check: temp/batch/batch_*_error.jsonl for error details
+# The system now automatically processes errors and generates default metadata
+```
+
+## Environment Variables
+
+Optional configuration:
+```bash
+# OpenAI for metadata generation
+OPENAI_API_KEY=sk-...
+OPENAI_MODEL=gpt-4o-mini  # Default model
+OPENAI_BATCH_SIZE=50      # Batch size for metadata generation
+
+# Metadata generation limits
+METADATA_LIMIT=100        # Max templates to process (0 = all)
+```
+
+## Statistics
+
+After update, check stats:
+```bash
+# Template count
+sqlite3 data/nodes.db "SELECT COUNT(*) FROM templates"
+
+# Most recent template
+sqlite3 data/nodes.db "SELECT MAX(created_at) FROM templates"
+
+# Templates by view count
+sqlite3 data/nodes.db "SELECT COUNT(*),
+  CASE
+    WHEN views < 50 THEN '<50'
+    WHEN views < 100 THEN '50-100'
+    WHEN views < 500 THEN '100-500'
+    ELSE '500+'
+  END as view_range
+  FROM templates GROUP BY view_range"
+```
+
+## Integration with n8n-mcp
+
+Templates are available through MCP tools:
+- `list_templates`: List all templates
+- `get_template`: Get specific template with workflow
+- `search_templates`: Search by keyword
+- `list_node_templates`: Templates using specific nodes
+- `get_templates_for_task`: Templates for common tasks
+- `search_templates_by_metadata`: Advanced filtering
+
+See `npm run test:templates` for usage examples.
+
+## Time Estimates
+
+Typical incremental update:
+- Loading existing IDs: 1-2 seconds
+- Fetching template list: 2-3 minutes
+- Filtering new templates: instant
+- Fetching details for 100 new templates: ~15 seconds (0.15s each)
+- Saving and indexing: 5-10 seconds
+- **Total: 3-5 minutes**
+
+Full rebuild:
+- Fetching 8000+ templates: 25-30 minutes
+- Saving and indexing: 5-10 minutes
+- **Total: 30-40 minutes**
+
+## Best Practices
+
+1. **Use incremental updates** for regular maintenance
+2. **Rebuild only when necessary** (corruption, major changes)
+3. **Generate metadata incrementally** to avoid OpenAI costs
+4. **Monitor template count** to verify updates working
+5. **Keep database backed up** before major operations
+
+## Next Steps
+
+After updating templates:
+1. Test template search: `npm run test:templates`
+2. Verify MCP tools work: Test in Claude Desktop
+3. Check statistics in database
+4. Commit changes if desired (database changes)
+
+## Related Documentation
+
+- `MEMORY_N8N_UPDATE.md` - Updating n8n dependencies
+- `CLAUDE.md` - Project overview and architecture
+- `README.md` - User documentation

P0-R3-TEST-PLAN.md

@@ -0,0 +1,484 @@
+# P0-R3 Feature Test Coverage Plan
+
+## Executive Summary
+
+This document outlines comprehensive test coverage for the P0-R3 feature (Template-based Configuration Examples). The feature adds real-world configuration examples from popular templates to node search and essentials tools.
+
+**Feature Overview:**
+- New database table: `template_node_configs` (197 pre-extracted configurations)
+- Enhanced tools: `search_nodes({includeExamples: true})` and `get_node_essentials({includeExamples: true})`
+- Breaking changes: Removed `get_node_for_task` tool
+
+## Test Files Created
+
+### Unit Tests
+
+#### 1. `/tests/unit/scripts/fetch-templates-extraction.test.ts` ✅
+**Purpose:** Test template extraction logic from `fetch-templates.ts`
+
+**Coverage:**
+- `extractNodeConfigs()` - 90%+ coverage
+  - Valid workflows with multiple nodes
+  - Empty workflows
+  - Malformed compressed data
+  - Invalid JSON
+  - Nodes without parameters
+  - Sticky note filtering
+  - Credential handling
+  - Expression detection
+  - Special characters
+  - Large workflows (100 nodes)
+
+- `detectExpressions()` - 100% coverage
+  - `={{...}}` syntax detection
+  - `$json` references
+  - `$node` references
+  - Nested objects
+  - Arrays
+  - Null/undefined handling
+  - Multiple expression types
+
+**Test Count:** 27 tests
+**Expected Coverage:** 92%+
+
+---
+
+#### 2. `/tests/unit/mcp/search-nodes-examples.test.ts` ✅
+**Purpose:** Test `search_nodes` tool with includeExamples parameter
+
+**Coverage:**
+- includeExamples parameter behavior
+  - false: no examples returned
+  - undefined: no examples returned (default)
+  - true: examples returned
+- Example data structure validation
+- Top 2 limit enforcement
+- Backward compatibility
+- Performance (<100ms)
+- Error handling (malformed JSON, database errors)
+- searchNodesLIKE integration
+- searchNodesFTS integration
+
+**Test Count:** 12 tests
+**Expected Coverage:** 85%+
+
+---
+
+#### 3. `/tests/unit/mcp/get-node-essentials-examples.test.ts` ✅
+**Purpose:** Test `get_node_essentials` tool with includeExamples parameter
+
+**Coverage:**
+- includeExamples parameter behavior
+- Full metadata structure
+  - configuration object
+  - source (template, views, complexity)
+  - useCases (limited to 2)
+  - metadata (hasCredentials, hasExpressions)
+- Cache key differentiation
+- Backward compatibility
+- Performance (<100ms)
+- Error handling
+- Top 3 limit enforcement
+
+**Test Count:** 13 tests
+**Expected Coverage:** 88%+
+
+---
+
+### Integration Tests
+
+#### 4. `/tests/integration/database/template-node-configs.test.ts` ✅
+**Purpose:** Test database schema, migrations, and operations
+
+**Coverage:**
+- Schema validation
+  - Table creation
+  - All columns present
+  - Correct types and constraints
+  - CHECK constraint on complexity
+- Indexes
+  - idx_config_node_type_rank
+  - idx_config_complexity
+  - idx_config_auth
+- View: ranked_node_configs
+  - Top 5 per node_type
+  - Correct ordering
+- Foreign key constraints
+  - CASCADE delete
+  - Referential integrity
+- Data operations
+  - INSERT with all fields
+  - Nullable fields
+  - Rank updates
+  - Delete rank > 10
+- Performance
+  - 1000 records < 10ms queries
+- Migration idempotency
+
+**Test Count:** 19 tests
+**Expected Coverage:** 95%+
+
+---
+
+#### 5. `/tests/integration/mcp/template-examples-e2e.test.ts` ✅
+**Purpose:** End-to-end integration testing
+
+**Coverage:**
+- Direct SQL queries
+  - Top 2 examples for search_nodes
+  - Top 3 examples with metadata for get_node_essentials
+- Data structure validation
+  - Valid JSON in all fields
+  - Credentials when has_credentials=1
+- Ranked view functionality
+- Performance with 100+ configs
+  - Query performance < 5ms
+  - Complexity filtering
+- Edge cases
+  - Non-existent node types
+  - Long parameters_json (100 params)
+  - Special characters (Unicode, emojis, symbols)
+- Data integrity
+  - Foreign key constraints
+  - Cascade deletes
+
+**Test Count:** 14 tests
+**Expected Coverage:** 90%+
+
+---
+
+### Test Fixtures
+
+#### 6. `/tests/fixtures/template-configs.ts` ✅
+**Purpose:** Reusable test data
+
+**Provides:**
+- `sampleConfigs`: 7 realistic node configurations
+  - simpleWebhook
+  - webhookWithAuth
+  - httpRequestBasic
+  - httpRequestWithExpressions
+  - slackMessage
+  - codeNodeTransform
+  - codeNodeWithExpressions
+
+- `sampleWorkflows`: 3 complete workflows
+  - webhookToSlack
+  - apiWorkflow
+  - complexWorkflow
+
+- **Helper Functions:**
+  - `compressWorkflow()` - Compress to base64
+  - `createTemplateMetadata()` - Generate metadata
+  - `createConfigBatch()` - Batch create configs
+  - `getConfigByComplexity()` - Filter by complexity
+  - `getConfigsWithExpressions()` - Filter with expressions
+  - `getConfigsWithCredentials()` - Filter with credentials
+  - `createInsertStatement()` - SQL insert helper
+
+---
+
+## Existing Tests Requiring Updates
+
+### High Priority
+
+#### 1. `tests/unit/mcp/parameter-validation.test.ts`
+**Line 480:** Remove `get_node_for_task` from legacyValidationTools array
+
+```typescript
+// REMOVE THIS:
+{ name: 'get_node_for_task', args: {}, expected: 'Missing required parameters for get_node_for_task: task' },
+```
+
+**Status:** ⚠️ BREAKING CHANGE - Tool removed
+
+---
+
+#### 2. `tests/unit/mcp/tools.test.ts`
+**Update:** Remove `get_node_for_task` from templates category
+
+```typescript
+// BEFORE:
+templates: ['list_tasks', 'get_node_for_task', 'search_templates', ...]
+
+// AFTER:
+templates: ['list_tasks', 'search_templates', ...]
+```
+
+**Add:** Tests for new includeExamples parameter in tool definitions
+
+```typescript
+it('should have includeExamples parameter in search_nodes', () => {
+  const searchNodesTool = tools.find(t => t.name === 'search_nodes');
+  expect(searchNodesTool.inputSchema.properties.includeExamples).toBeDefined();
+  expect(searchNodesTool.inputSchema.properties.includeExamples.type).toBe('boolean');
+  expect(searchNodesTool.inputSchema.properties.includeExamples.default).toBe(false);
+});
+
+it('should have includeExamples parameter in get_node_essentials', () => {
+  const essentialsTool = tools.find(t => t.name === 'get_node_essentials');
+  expect(essentialsTool.inputSchema.properties.includeExamples).toBeDefined();
+});
+```
+
+**Status:** ⚠️ REQUIRED UPDATE
+
+---
+
+#### 3. `tests/integration/mcp-protocol/session-management.test.ts`
+**Remove:** Test case calling `get_node_for_task` with invalid task
+
+```typescript
+// REMOVE THIS TEST:
+client.callTool({ name: 'get_node_for_task', arguments: { task: 'invalid_task' } }).catch(e => e)
+```
+
+**Status:** ⚠️ BREAKING CHANGE
+
+---
+
+#### 4. `tests/integration/mcp-protocol/tool-invocation.test.ts`
+**Remove:** Entire `get_node_for_task` describe block
+
+**Add:** Tests for new includeExamples functionality
+
+```typescript
+describe('search_nodes with includeExamples', () => {
+  it('should return examples when includeExamples is true', async () => {
+    const response = await client.callTool({
+      name: 'search_nodes',
+      arguments: { query: 'webhook', includeExamples: true }
+    });
+
+    expect(response.results).toBeDefined();
+    // Examples may or may not be present depending on database
+  });
+
+  it('should not return examples when includeExamples is false', async () => {
+    const response = await client.callTool({
+      name: 'search_nodes',
+      arguments: { query: 'webhook', includeExamples: false }
+    });
+
+    expect(response.results).toBeDefined();
+    response.results.forEach(node => {
+      expect(node.examples).toBeUndefined();
+    });
+  });
+});
+
+describe('get_node_essentials with includeExamples', () => {
+  it('should return examples with metadata when includeExamples is true', async () => {
+    const response = await client.callTool({
+      name: 'get_node_essentials',
+      arguments: { nodeType: 'nodes-base.webhook', includeExamples: true }
+    });
+
+    expect(response.nodeType).toBeDefined();
+    // Examples may or may not be present depending on database
+  });
+});
+```
+
+**Status:** ⚠️ REQUIRED UPDATE
+
+---
+
+### Medium Priority
+
+#### 5. `tests/unit/services/task-templates.test.ts`
+**Status:** ✅ No changes needed (TaskTemplates marked as deprecated but not removed)
+
+**Note:** TaskTemplates remains for backward compatibility. Tests should continue to pass.
+
+---
+
+## Test Execution Plan
+
+### Phase 1: Unit Tests
+```bash
+# Run new unit tests
+npm test tests/unit/scripts/fetch-templates-extraction.test.ts
+npm test tests/unit/mcp/search-nodes-examples.test.ts
+npm test tests/unit/mcp/get-node-essentials-examples.test.ts
+
+# Expected: All pass, 52 tests
+```
+
+### Phase 2: Integration Tests
+```bash
+# Run new integration tests
+npm test tests/integration/database/template-node-configs.test.ts
+npm test tests/integration/mcp/template-examples-e2e.test.ts
+
+# Expected: All pass, 33 tests
+```
+
+### Phase 3: Update Existing Tests
+```bash
+# Update files as outlined above, then run:
+npm test tests/unit/mcp/parameter-validation.test.ts
+npm test tests/unit/mcp/tools.test.ts
+npm test tests/integration/mcp-protocol/session-management.test.ts
+npm test tests/integration/mcp-protocol/tool-invocation.test.ts
+
+# Expected: All pass after updates
+```
+
+### Phase 4: Full Test Suite
+```bash
+# Run all tests
+npm test
+
+# Run with coverage
+npm run test:coverage
+
+# Expected coverage improvements:
+# - src/scripts/fetch-templates.ts: +20% (60% → 80%)
+# - src/mcp/server.ts: +5% (75% → 80%)
+# - Overall project: +2% (current → current+2%)
+```
+
+---
+
+## Coverage Expectations
+
+### New Code Coverage
+
+| File | Function | Target | Tests |
+|------|----------|--------|-------|
+| fetch-templates.ts | extractNodeConfigs | 95% | 15 tests |
+| fetch-templates.ts | detectExpressions | 100% | 12 tests |
+| server.ts | searchNodes (with examples) | 90% | 8 tests |
+| server.ts | getNodeEssentials (with examples) | 90% | 10 tests |
+| Database migration | template_node_configs | 100% | 19 tests |
+
+### Overall Coverage Goals
+
+- **Unit Tests:** 90%+ coverage for new code
+- **Integration Tests:** All happy paths + critical error paths
+- **E2E Tests:** Complete feature workflows
+- **Performance:** All queries <10ms (database), <100ms (MCP)
+
+---
+
+## Test Infrastructure
+
+### Dependencies Required
+All dependencies already present in `package.json`:
+- vitest (test runner)
+- better-sqlite3 (database)
+- @vitest/coverage-v8 (coverage)
+
+### Test Utilities Used
+- TestDatabase helper (from existing test utils)
+- createTestDatabaseAdapter (from existing test utils)
+- Standard vitest matchers
+
+### No New Dependencies Required ✅
+
+---
+
+## Regression Prevention
+
+### Critical Paths Protected
+
+1. **Backward Compatibility**
+   - Tools work without includeExamples parameter
+   - Existing workflows unchanged
+   - Cache keys differentiated
+
+2. **Performance**
+   - No degradation when includeExamples=false
+   - Indexed queries <10ms
+   - Example fetch errors don't break responses
+
+3. **Data Integrity**
+   - Foreign key constraints enforced
+   - JSON validation in all fields
+   - Rank calculations correct
+
+---
+
+## CI/CD Integration
+
+### GitHub Actions Updates
+No changes required. Existing test commands will run new tests:
+
+```yaml
+- run: npm test
+- run: npm run test:coverage
+```
+
+### Coverage Thresholds
+Current thresholds maintained. Expected improvements:
+- Lines: +2%
+- Functions: +3%
+- Branches: +2%
+
+---
+
+## Manual Testing Checklist
+
+### Pre-Deployment Verification
+
+- [ ] Run `npm run rebuild` - Verify migration applies cleanly
+- [ ] Run `npm run fetch:templates --extract-only` - Verify extraction works
+- [ ] Check database: `SELECT COUNT(*) FROM template_node_configs` - Should be ~197
+- [ ] Test MCP tool: `search_nodes({query: "webhook", includeExamples: true})`
+- [ ] Test MCP tool: `get_node_essentials({nodeType: "nodes-base.webhook", includeExamples: true})`
+- [ ] Verify backward compatibility: Tools work without includeExamples parameter
+- [ ] Performance test: Query 100 nodes with examples < 200ms
+
+---
+
+## Rollback Plan
+
+If issues are detected:
+
+1. **Database Rollback:**
+   ```sql
+   DROP TABLE IF EXISTS template_node_configs;
+   DROP VIEW IF EXISTS ranked_node_configs;
+   ```
+
+2. **Code Rollback:**
+   - Revert server.ts changes
+   - Revert tools.ts changes
+   - Restore get_node_for_task tool (if critical)
+
+3. **Test Rollback:**
+   - Revert parameter-validation.test.ts
+   - Revert tools.test.ts
+   - Revert tool-invocation.test.ts
+
+---
+
+## Success Metrics
+
+### Test Metrics
+- ✅ 85+ new tests added
+- ✅ 0 tests failing after updates
+- ✅ Coverage increase 2%+
+- ✅ All performance tests pass
+
+### Feature Metrics
+- ✅ 197 template configs extracted
+- ✅ Top 2/3 examples returned correctly
+- ✅ Query performance <10ms
+- ✅ No backward compatibility breaks
+
+---
+
+## Conclusion
+
+This test plan provides **comprehensive coverage** for the P0-R3 feature with:
+- **85+ new tests** across unit, integration, and E2E levels
+- **Complete coverage** of extraction, storage, and retrieval
+- **Backward compatibility** protection
+- **Performance validation** (<10ms queries)
+- **Clear migration path** for existing tests
+
+**All test files are ready for execution.** Update the 4 existing test files as outlined, then run the full test suite.
+
+**Estimated Total Implementation Time:** 2-3 hours for updating existing tests + validation

PRIVACY.md

@@ -0,0 +1,69 @@
+# Privacy Policy for n8n-mcp Telemetry
+
+## Overview
+n8n-mcp collects anonymous usage statistics to help improve the tool. This data collection is designed to respect user privacy while providing valuable insights into how the tool is used.
+
+## What We Collect
+- **Anonymous User ID**: A hashed identifier derived from your machine characteristics (no personal information)
+- **Tool Usage**: Which MCP tools are used and their performance metrics
+- **Workflow Patterns**: Sanitized workflow structures (all sensitive data removed)
+- **Error Types**: Categories of errors encountered (no error messages with user data)
+- **System Information**: Platform, architecture, Node.js version, and n8n-mcp version
+
+## What We DON'T Collect
+- Personal information or usernames
+- API keys, tokens, or credentials
+- URLs, endpoints, or hostnames
+- Email addresses or contact information
+- File paths or directory structures
+- Actual workflow data or parameters
+- Database connection strings
+- Any authentication information
+
+## Data Sanitization
+All collected data undergoes automatic sanitization:
+- URLs are replaced with `[URL]` or `[REDACTED]`
+- Long alphanumeric strings (potential keys) are replaced with `[KEY]`
+- Email addresses are replaced with `[EMAIL]`
+- Authentication-related fields are completely removed
+
+## Data Storage
+- Data is stored securely using Supabase
+- Anonymous users have write-only access (cannot read data back)
+- Row Level Security (RLS) policies prevent data access by anonymous users
+
+## Opt-Out
+You can disable telemetry at any time:
+```bash
+npx n8n-mcp telemetry disable
+```
+
+To re-enable:
+```bash
+npx n8n-mcp telemetry enable
+```
+
+To check status:
+```bash
+npx n8n-mcp telemetry status
+```
+
+## Data Usage
+Collected data is used solely to:
+- Understand which features are most used
+- Identify common error patterns
+- Improve tool performance and reliability
+- Guide development priorities
+
+## Data Retention
+- Data is retained for analysis purposes
+- No personal identification is possible from the collected data
+
+## Changes to This Policy
+We may update this privacy policy from time to time. Updates will be reflected in this document.
+
+## Contact
+For questions about telemetry or privacy, please open an issue on GitHub:
+https://github.com/czlonkowski/n8n-mcp/issues
+
+Last updated: 2025-09-25

README.md

@@ -2,10 +2,12 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![GitHub stars](https://img.shields.io/github/stars/czlonkowski/n8n-mcp?style=social)](https://github.com/czlonkowski/n8n-mcp)
-[![Version](https://img.shields.io/badge/version-2.7.8-blue.svg)](https://github.com/czlonkowski/n8n-mcp)
 [![npm version](https://img.shields.io/npm/v/n8n-mcp.svg)](https://www.npmjs.com/package/n8n-mcp)
-[![n8n version](https://img.shields.io/badge/n8n-v1.100.1-orange.svg)](https://github.com/n8n-io/n8n)
+[![codecov](https://codecov.io/gh/czlonkowski/n8n-mcp/graph/badge.svg?token=YOUR_TOKEN)](https://codecov.io/gh/czlonkowski/n8n-mcp)
+[![Tests](https://img.shields.io/badge/tests-3336%20passing-brightgreen.svg)](https://github.com/czlonkowski/n8n-mcp/actions)
+[![n8n version](https://img.shields.io/badge/n8n-^1.113.3-orange.svg)](https://github.com/n8n-io/n8n)
 [![Docker](https://img.shields.io/badge/docker-ghcr.io%2Fczlonkowski%2Fn8n--mcp-green.svg)](https://github.com/czlonkowski/n8n-mcp/pkgs/container/n8n-mcp)
+[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/n8n-mcp?referralCode=n8n-mcp)
 
 A Model Context Protocol (MCP) server that provides AI assistants with comprehensive access to n8n node documentation, properties, and operations. Deploy in minutes to give Claude and other AI assistants deep knowledge about n8n's 525+ workflow automation nodes.
 
@@ -13,17 +15,31 @@ A Model Context Protocol (MCP) server that provides AI assistants with comprehen
 
 n8n-MCP serves as a bridge between n8n's workflow automation platform and AI models, enabling them to understand and work with n8n nodes effectively. It provides structured access to:
 
-- 📚 **525 n8n nodes** from both n8n-nodes-base and @n8n/n8n-nodes-langchain
+- 📚 **536 n8n nodes** from both n8n-nodes-base and @n8n/n8n-nodes-langchain
 - 🔧 **Node properties** - 99% coverage with detailed schemas
 - ⚡ **Node operations** - 63.6% coverage of available actions
 - 📄 **Documentation** - 90% coverage from official n8n docs (including AI nodes)
 - 🤖 **AI tools** - 263 AI-capable nodes detected with full documentation
+- 💡 **Real-world examples** - 2,646 pre-extracted configurations from popular templates
+- 🎯 **Template library** - 2,500+ workflow templates with smart filtering
 
 
+## ⚠️ Important Safety Warning
+
+**NEVER edit your production workflows directly with AI!** Always:
+- 🔄 **Make a copy** of your workflow before using AI tools
+- 🧪 **Test in development** environment first
+- 💾 **Export backups** of important workflows
+- ⚡ **Validate changes** before deploying to production
+
+AI results can be unpredictable. Protect your work!
+
 ## 🚀 Quick Start
 
 Get n8n-MCP running in 5 minutes:
 
+[![n8n-mcp Video Quickstart Guide](./thumbnail.png)](https://youtu.be/5CccjiLLyaY?si=Z62SBGlw9G34IQnQ&t=343)
+
 ### Option 1: npx (Fastest - No Installation!) 🚀
 
 **Prerequisites:** [Node.js](https://nodejs.org/) installed on your system
@@ -148,6 +164,7 @@ Add to Claude Desktop config:
         "run",
         "-i",
         "--rm",
+        "--init",
         "-e", "MCP_MODE=stdio",
         "-e", "LOG_LEVEL=error",
         "-e", "DISABLE_CONSOLE_OUTPUT=true",
@@ -168,6 +185,7 @@ Add to Claude Desktop config:
         "run",
         "-i",
         "--rm",
+        "--init",
         "-e", "MCP_MODE=stdio",
         "-e", "LOG_LEVEL=error",
         "-e", "DISABLE_CONSOLE_OUTPUT=true",
@@ -180,12 +198,40 @@ Add to Claude Desktop config:
 }
 ```
 
->💡 Tip: If you’re running n8n locally on the same machine (e.g., via Docker), use http://host.docker.internal:5678 as the N8N_API_URL.
+>💡 Tip: If you're running n8n locally on the same machine (e.g., via Docker), use http://host.docker.internal:5678 as the N8N_API_URL.
 
 > **Note**: The n8n API credentials are optional. Without them, you'll have access to all documentation and validation tools. With them, you'll additionally get workflow management capabilities (create, update, execute workflows).
 
+### 🏠 Local n8n Instance Configuration
+
+If you're running n8n locally (e.g., `http://localhost:5678` or Docker), you need to allow localhost webhooks:
+
+```json
+{
+  "mcpServers": {
+    "n8n-mcp": {
+      "command": "docker",
+      "args": [
+        "run", "-i", "--rm", "--init",
+        "-e", "MCP_MODE=stdio",
+        "-e", "LOG_LEVEL=error",
+        "-e", "DISABLE_CONSOLE_OUTPUT=true",
+        "-e", "N8N_API_URL=http://host.docker.internal:5678",
+        "-e", "N8N_API_KEY=your-api-key",
+        "-e", "WEBHOOK_SECURITY_MODE=moderate",
+        "ghcr.io/czlonkowski/n8n-mcp:latest"
+      ]
+    }
+  }
+}
+```
+
+> ⚠️ **Important:** Set `WEBHOOK_SECURITY_MODE=moderate` to allow webhooks to your local n8n instance. This is safe for local development while still blocking private networks and cloud metadata.
+
 **Important:** The `-i` flag is required for MCP stdio communication.
 
+> 🔧 If you encounter any issues with Docker, check our [Docker Troubleshooting Guide](./docs/DOCKER_TROUBLESHOOTING.md).
+
 **Configuration file locations:**
 - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
 - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
@@ -193,6 +239,71 @@ Add to Claude Desktop config:
 
 **Restart Claude Desktop after updating configuration** - That's it! 🎉
 
+## 🔐 Privacy & Telemetry
+
+n8n-mcp collects anonymous usage statistics to improve the tool. [View our privacy policy](./PRIVACY.md).
+
+### Opting Out
+
+**For npx users:**
+```bash
+npx n8n-mcp telemetry disable
+```
+
+**For Docker users:**
+Add the following environment variable to your Docker configuration:
+```json
+"-e", "N8N_MCP_TELEMETRY_DISABLED=true"
+```
+
+Example in Claude Desktop config:
+```json
+{
+  "mcpServers": {
+    "n8n-mcp": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "--init",
+        "-e", "MCP_MODE=stdio",
+        "-e", "LOG_LEVEL=error",
+        "-e", "N8N_MCP_TELEMETRY_DISABLED=true",
+        "ghcr.io/czlonkowski/n8n-mcp:latest"
+      ]
+    }
+  }
+}
+```
+
+**For docker-compose users:**
+Set in your environment file or docker-compose.yml:
+```yaml
+environment:
+  N8N_MCP_TELEMETRY_DISABLED: "true"
+```
+
+## 💖 Support This Project
+
+<div align="center">
+  <a href="https://github.com/sponsors/czlonkowski">
+    <img src="https://img.shields.io/badge/Sponsor-❤️-db61a2?style=for-the-badge&logo=github-sponsors" alt="Sponsor n8n-mcp" />
+  </a>
+</div>
+
+**n8n-mcp** started as a personal tool but now helps tens of thousands of developers automate their workflows efficiently. Maintaining and developing this project competes with my paid work.
+
+Your sponsorship helps me:
+- 🚀 Dedicate focused time to new features
+- 🐛 Respond quickly to issues
+- 📚 Keep documentation up-to-date
+- 🔄 Ensure compatibility with latest n8n releases
+
+Every sponsorship directly translates to hours invested in making n8n-mcp better for everyone. **[Become a sponsor →](https://github.com/sponsors/czlonkowski)**
+
+---
+
 ### Option 3: Local Installation (For Development)
 
 **Prerequisites:** [Node.js](https://nodejs.org/) installed on your system
@@ -251,139 +362,345 @@ Add to Claude Desktop config:
 
 > 💡 Tip: If you’re running n8n locally on the same machine (e.g., via Docker), use http://host.docker.internal:5678 as the N8N_API_URL.
 
+### Option 4: Railway Cloud Deployment (One-Click Deploy) ☁️
+
+**Prerequisites:** Railway account (free tier available)
+
+Deploy n8n-MCP to Railway's cloud platform with zero configuration:
+
+[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/n8n-mcp?referralCode=n8n-mcp)
+
+**Benefits:**
+- ☁️ **Instant cloud hosting** - No server setup required
+- 🔒 **Secure by default** - HTTPS included, auth token warnings
+- 🌐 **Global access** - Connect from any Claude Desktop
+- ⚡ **Auto-scaling** - Railway handles the infrastructure
+- 📊 **Built-in monitoring** - Logs and metrics included
+
+**Quick Setup:**
+1. Click the "Deploy on Railway" button above
+2. Sign in to Railway (or create a free account)
+3. Configure your deployment (project name, region)
+4. Click "Deploy" and wait ~2-3 minutes
+5. Copy your deployment URL and auth token
+6. Add to Claude Desktop config using the HTTPS URL
+
+> 📚 **For detailed setup instructions, troubleshooting, and configuration examples, see our [Railway Deployment Guide](./docs/RAILWAY_DEPLOYMENT.md)**
+
+**Configuration file locations:**
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+**Restart Claude Desktop after updating configuration** - That's it! 🎉
+
+## 🔧 n8n Integration
+
+Want to use n8n-MCP with your n8n instance? Check out our comprehensive [n8n Deployment Guide](./docs/N8N_DEPLOYMENT.md) for:
+- Local testing with the MCP Client Tool node
+- Production deployment with Docker Compose
+- Cloud deployment on Hetzner, AWS, and other providers
+- Troubleshooting and security best practices
+
+## 💻 Connect your IDE
+
+n8n-MCP works with multiple AI-powered IDEs and tools. Choose your preferred development environment:
+
+### [Claude Code](./docs/CLAUDE_CODE_SETUP.md)
+Quick setup for Claude Code CLI - just type "add this mcp server" and paste the config.
+
+### [Visual Studio Code](./docs/VS_CODE_PROJECT_SETUP.md)
+Full setup guide for VS Code with GitHub Copilot integration and MCP support.
+
+### [Cursor](./docs/CURSOR_SETUP.md)
+Step-by-step tutorial for connecting n8n-MCP to Cursor IDE with custom rules.
+
+### [Windsurf](./docs/WINDSURF_SETUP.md)
+Complete guide for integrating n8n-MCP with Windsurf using project rules.
+
+### [Codex](./docs/CODEX_SETUP.md)
+Complete guide for integrating n8n-MCP with Codex.
+
 ## 🤖 Claude Project Setup
 
 For the best results when using n8n-MCP with Claude Projects, use these enhanced system instructions:
 
-```markdown
+````markdown
 You are an expert in n8n automation software using n8n-MCP tools. Your role is to design, build, and validate n8n workflows with maximum accuracy and efficiency.
 
-## Core Workflow Process
+## Core Principles
 
-1. **ALWAYS start with**: `tools_documentation()` to understand best practices and available tools.
+### 1. Silent Execution
+CRITICAL: Execute tools without commentary. Only respond AFTER all tools complete.
 
-2. **Discovery Phase** - Find the right nodes:
-   - `search_nodes({query: 'keyword'})` - Search by functionality
+❌ BAD: "Let me search for Slack nodes... Great! Now let me get details..."
+✅ GOOD: [Execute search_nodes and get_node_essentials in parallel, then respond]
+
+### 2. Parallel Execution
+When operations are independent, execute them in parallel for maximum performance.
+
+✅ GOOD: Call search_nodes, list_nodes, and search_templates simultaneously
+❌ BAD: Sequential tool calls (await each one before the next)
+
+### 3. Templates First
+ALWAYS check templates before building from scratch (2,500+ available).
+
+### 4. Multi-Level Validation
+Use validate_node_minimal → validate_node_operation → validate_workflow pattern.
+
+### 5. Never Trust Defaults
+⚠️ CRITICAL: Default parameter values are the #1 source of runtime failures.
+ALWAYS explicitly configure ALL parameters that control node behavior.
+
+## Workflow Process
+
+1. **Start**: Call `tools_documentation()` for best practices
+
+2. **Template Discovery Phase** (FIRST - parallel when searching multiple)
+   - `search_templates_by_metadata({complexity: "simple"})` - Smart filtering
+   - `get_templates_for_task('webhook_processing')` - Curated by task
+   - `search_templates('slack notification')` - Text search
+   - `list_node_templates(['n8n-nodes-base.slack'])` - By node type
+
+   **Filtering strategies**:
+   - Beginners: `complexity: "simple"` + `maxSetupMinutes: 30`
+   - By role: `targetAudience: "marketers"` | `"developers"` | `"analysts"`
+   - By time: `maxSetupMinutes: 15` for quick wins
+   - By service: `requiredService: "openai"` for compatibility
+
+3. **Node Discovery** (if no suitable template - parallel execution)
+   - Think deeply about requirements. Ask clarifying questions if unclear.
+   - `search_nodes({query: 'keyword', includeExamples: true})` - Parallel for multiple nodes
    - `list_nodes({category: 'trigger'})` - Browse by category
-   - `list_ai_tools()` - See AI-capable nodes (remember: ANY node can be an AI tool!)
+   - `list_ai_tools()` - AI-capable nodes
 
-3. **Configuration Phase** - Get node details efficiently:
-   - `get_node_essentials(nodeType)` - Start here! Only 10-20 essential properties
+4. **Configuration Phase** (parallel for multiple nodes)
+   - `get_node_essentials(nodeType, {includeExamples: true})` - 10-20 key properties
    - `search_node_properties(nodeType, 'auth')` - Find specific properties
-   - `get_node_for_task('send_email')` - Get pre-configured templates
-   - `get_node_documentation(nodeType)` - Human-readable docs when needed
+   - `get_node_documentation(nodeType)` - Human-readable docs
+   - Show workflow architecture to user for approval before proceeding
 
-4. **Pre-Validation Phase** - Validate BEFORE building:
+5. **Validation Phase** (parallel for multiple nodes)
    - `validate_node_minimal(nodeType, config)` - Quick required fields check
-   - `validate_node_operation(nodeType, config, profile)` - Full operation-aware validation
-   - Fix any validation errors before proceeding
+   - `validate_node_operation(nodeType, config, 'runtime')` - Full validation with fixes
+   - Fix ALL errors before proceeding
 
-5. **Building Phase** - Create the workflow:
-   - Use validated configurations from step 4
+6. **Building Phase**
+   - If using template: `get_template(templateId, {mode: "full"})`
+   - **MANDATORY ATTRIBUTION**: "Based on template by **[author.name]** (@[username]). View at: [url]"
+   - Build from validated configurations
+   - ⚠️ EXPLICITLY set ALL parameters - never rely on defaults
    - Connect nodes with proper structure
-   - Add error handling where appropriate
-   - Use expressions like $json, $node["NodeName"].json
-   - Build the workflow in an artifact (unless the user asked to create in n8n instance)
+   - Add error handling
+   - Use n8n expressions: $json, $node["NodeName"].json
+   - Build in artifact (unless deploying to n8n instance)
 
-6. **Workflow Validation Phase** - Validate complete workflow:
-   - `validate_workflow(workflow)` - Complete validation including connections
-   - `validate_workflow_connections(workflow)` - Check structure and AI tool connections
-   - `validate_workflow_expressions(workflow)` - Validate all n8n expressions
-   - Fix any issues found before deployment
+7. **Workflow Validation** (before deployment)
+   - `validate_workflow(workflow)` - Complete validation
+   - `validate_workflow_connections(workflow)` - Structure check
+   - `validate_workflow_expressions(workflow)` - Expression validation
+   - Fix ALL issues before deployment
 
-7. **Deployment Phase** (if n8n API configured):
-   - `n8n_create_workflow(workflow)` - Deploy validated workflow
-   - `n8n_validate_workflow({id: 'workflow-id'})` - Post-deployment validation
-   - `n8n_update_partial_workflow()` - Make incremental updates using diffs
-   - `n8n_trigger_webhook_workflow()` - Test webhook workflows
+8. **Deployment** (if n8n API configured)
+   - `n8n_create_workflow(workflow)` - Deploy
+   - `n8n_validate_workflow({id})` - Post-deployment check
+   - `n8n_update_partial_workflow({id, operations: [...]})` - Batch updates
+   - `n8n_trigger_webhook_workflow()` - Test webhooks
 
-## Key Insights
+## Critical Warnings
 
-- **VALIDATE EARLY AND OFTEN** - Catch errors before they reach production
-- **USE DIFF UPDATES** - Use n8n_update_partial_workflow for 80-90% token savings
-- **ANY node can be an AI tool** - not just those with usableAsTool=true
-- **Pre-validate configurations** - Use validate_node_minimal before building
-- **Post-validate workflows** - Always validate complete workflows before deployment
-- **Incremental updates** - Use diff operations for existing workflows
-- **Test thoroughly** - Validate both locally and after deployment to n8n
+### ⚠️ Never Trust Defaults
+Default values cause runtime failures. Example:
+```json
+// ❌ FAILS at runtime
+{resource: "message", operation: "post", text: "Hello"}
+
+// ✅ WORKS - all parameters explicit
+{resource: "message", operation: "post", select: "channel", channelId: "C123", text: "Hello"}
+```
+
+### ⚠️ Example Availability
+`includeExamples: true` returns real configurations from workflow templates.
+- Coverage varies by node popularity
+- When no examples available, use `get_node_essentials` + `validate_node_minimal`
 
 ## Validation Strategy
 
-### Before Building:
-1. validate_node_minimal() - Check required fields
-2. validate_node_operation() - Full configuration validation
-3. Fix all errors before proceeding
+### Level 1 - Quick Check (before building)
+`validate_node_minimal(nodeType, config)` - Required fields only (<100ms)
 
-### After Building:
-1. validate_workflow() - Complete workflow validation
-2. validate_workflow_connections() - Structure validation
-3. validate_workflow_expressions() - Expression syntax check
+### Level 2 - Comprehensive (before building)
+`validate_node_operation(nodeType, config, 'runtime')` - Full validation with fixes
 
-### After Deployment:
-1. n8n_validate_workflow({id}) - Validate deployed workflow
-2. n8n_list_executions() - Monitor execution status
-3. n8n_update_partial_workflow() - Fix issues using diffs
+### Level 3 - Complete (after building)
+`validate_workflow(workflow)` - Connections, expressions, AI tools
 
-## Response Structure
+### Level 4 - Post-Deployment
+1. `n8n_validate_workflow({id})` - Validate deployed workflow
+2. `n8n_autofix_workflow({id})` - Auto-fix common errors
+3. `n8n_list_executions()` - Monitor execution status
 
-1. **Discovery**: Show available nodes and options
-2. **Pre-Validation**: Validate node configurations first
-3. **Configuration**: Show only validated, working configs
-4. **Building**: Construct workflow with validated components
-5. **Workflow Validation**: Full workflow validation results
-6. **Deployment**: Deploy only after all validations pass
-7. **Post-Validation**: Verify deployment succeeded
+## Response Format
+
+### Initial Creation
+```
+[Silent tool execution in parallel]
+
+Created workflow:
+- Webhook trigger → Slack notification
+- Configured: POST /webhook → #general channel
+
+Validation: ✅ All checks passed
+```
+
+### Modifications
+```
+[Silent tool execution]
+
+Updated workflow:
+- Added error handling to HTTP node
+- Fixed required Slack parameters
+
+Changes validated successfully.
+```
+
+## Batch Operations
+
+Use `n8n_update_partial_workflow` with multiple operations in a single call:
+
+✅ GOOD - Batch multiple operations:
+```json
+n8n_update_partial_workflow({
+  id: "wf-123",
+  operations: [
+    {type: "updateNode", nodeId: "slack-1", changes: {...}},
+    {type: "updateNode", nodeId: "http-1", changes: {...}},
+    {type: "cleanStaleConnections"}
+  ]
+})
+```
+
+❌ BAD - Separate calls:
+```json
+n8n_update_partial_workflow({id: "wf-123", operations: [{...}]})
+n8n_update_partial_workflow({id: "wf-123", operations: [{...}]})
+```
 
 ## Example Workflow
 
-### 1. Discovery & Configuration
-search_nodes({query: 'slack'})
-get_node_essentials('n8n-nodes-base.slack')
+### Template-First Approach
 
-### 2. Pre-Validation
-validate_node_minimal('n8n-nodes-base.slack', {resource:'message', operation:'send'})
+```
+// STEP 1: Template Discovery (parallel execution)
+[Silent execution]
+search_templates_by_metadata({
+  requiredService: 'slack',
+  complexity: 'simple',
+  targetAudience: 'marketers'
+})
+get_templates_for_task('slack_integration')
+
+// STEP 2: Use template
+get_template(templateId, {mode: 'full'})
+validate_workflow(workflow)
+
+// Response after all tools complete:
+"Found template by **David Ashby** (@cfomodz).
+View at: https://n8n.io/workflows/2414
+
+Validation: ✅ All checks passed"
+```
+
+### Building from Scratch (if no template)
+
+```
+// STEP 1: Discovery (parallel execution)
+[Silent execution]
+search_nodes({query: 'slack', includeExamples: true})
+list_nodes({category: 'communication'})
+
+// STEP 2: Configuration (parallel execution)
+[Silent execution]
+get_node_essentials('n8n-nodes-base.slack', {includeExamples: true})
+get_node_essentials('n8n-nodes-base.webhook', {includeExamples: true})
+
+// STEP 3: Validation (parallel execution)
+[Silent execution]
+validate_node_minimal('n8n-nodes-base.slack', config)
 validate_node_operation('n8n-nodes-base.slack', fullConfig, 'runtime')
 
-### 3. Build Workflow
-// Create workflow JSON with validated configs
+// STEP 4: Build
+// Construct workflow with validated configs
+// ⚠️ Set ALL parameters explicitly
 
-### 4. Workflow Validation
+// STEP 5: Validate
+[Silent execution]
 validate_workflow(workflowJson)
-validate_workflow_connections(workflowJson)
-validate_workflow_expressions(workflowJson)
 
-### 5. Deploy (if configured)
-n8n_create_workflow(validatedWorkflow)
-n8n_validate_workflow({id: createdWorkflowId})
+// Response after all tools complete:
+"Created workflow: Webhook → Slack
+Validation: ✅ Passed"
+```
 
-### 6. Update Using Diffs
+### Batch Updates
+
+```json
+// ONE call with multiple operations
 n8n_update_partial_workflow({
-  workflowId: id,
+  id: "wf-123",
   operations: [
-    {type: 'updateNode', nodeId: 'slack1', changes: {position: [100, 200]}}
+    {type: "updateNode", nodeId: "slack-1", changes: {position: [100, 200]}},
+    {type: "updateNode", nodeId: "http-1", changes: {position: [300, 200]}},
+    {type: "cleanStaleConnections"}
   ]
 })
+```
 
 ## Important Rules
 
-- ALWAYS validate before building
-- ALWAYS validate after building
-- NEVER deploy unvalidated workflows
-- USE diff operations for updates (80-90% token savings)
-- STATE validation results clearly
-- FIX all errors before proceeding
-```
+### Core Behavior
+1. **Silent execution** - No commentary between tools
+2. **Parallel by default** - Execute independent operations simultaneously
+3. **Templates first** - Always check before building (2,500+ available)
+4. **Multi-level validation** - Quick check → Full validation → Workflow validation
+5. **Never trust defaults** - Explicitly configure ALL parameters
 
-Save these instructions in your Claude Project for optimal n8n workflow assistance with comprehensive validation.
+### Attribution & Credits
+- **MANDATORY TEMPLATE ATTRIBUTION**: Share author name, username, and n8n.io link
+- **Template validation** - Always validate before deployment (may need updates)
+
+### Performance
+- **Batch operations** - Use diff operations with multiple changes in one call
+- **Parallel execution** - Search, validate, and configure simultaneously
+- **Template metadata** - Use smart filtering for faster discovery
+
+### Code Node Usage
+- **Avoid when possible** - Prefer standard nodes
+- **Only when necessary** - Use code node as last resort
+- **AI tool capability** - ANY node can be an AI tool (not just marked ones)
+````
+
+Save these instructions in your Claude Project for optimal n8n workflow assistance with intelligent template discovery.
+
+## 🚨 Important: Sharing Guidelines
+
+This project is MIT licensed and free for everyone to use. However:
+
+- **✅ DO**: Share this repository freely with proper attribution
+- **✅ DO**: Include a direct link to https://github.com/czlonkowski/n8n-mcp in your first post/video
+- **❌ DON'T**: Gate this free tool behind engagement requirements (likes, follows, comments)
+- **❌ DON'T**: Use this project for engagement farming on social media
+
+This tool was created to benefit everyone in the n8n community without friction. Please respect the MIT license spirit by keeping it accessible to all.
 
 ## Features
 
 - **🔍 Smart Node Search**: Find nodes by name, category, or functionality
-- **📖 Essential Properties**: Get only the 10-20 properties that matter (NEW in v2.4.0)
-- **🎯 Task Templates**: Pre-configured settings for common automation tasks
+- **📖 Essential Properties**: Get only the 10-20 properties that matter
+- **💡 Real-World Examples**: 2,646 pre-extracted configurations from popular templates
 - **✅ Config Validation**: Validate node configurations before deployment
 - **🔗 Dependency Analysis**: Understand property relationships and conditions
-- **💡 Working Examples**: Real-world examples for immediate use
+- **🎯 Template Discovery**: 2,500+ workflow templates with smart filtering
 - **⚡ Fast Response**: Average query time ~12ms with optimized SQLite
 - **🌐 Universal Compatibility**: Works with any Node.js version
 
@@ -409,15 +726,21 @@ Once connected, Claude can use these powerful tools:
 - **`tools_documentation`** - Get documentation for any MCP tool (START HERE!)
 - **`list_nodes`** - List all n8n nodes with filtering options
 - **`get_node_info`** - Get comprehensive information about a specific node
-- **`get_node_essentials`** - Get only essential properties with examples (10-20 properties instead of 200+)
-- **`search_nodes`** - Full-text search across all node documentation
+- **`get_node_essentials`** - Get only essential properties (10-20 instead of 200+). Use `includeExamples: true` to get top 3 real-world configurations from popular templates
+- **`search_nodes`** - Full-text search across all node documentation. Use `includeExamples: true` to get top 2 real-world configurations per node from templates
 - **`search_node_properties`** - Find specific properties within nodes
 - **`list_ai_tools`** - List all 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
 
+### Template Tools
+- **`list_templates`** - Browse all templates with descriptions and optional metadata (2,500+ templates)
+- **`search_templates`** - Text search across template names and descriptions
+- **`search_templates_by_metadata`** - Advanced filtering by complexity, setup time, services, audience
+- **`list_node_templates`** - Find templates using specific nodes
+- **`get_template`** - Get complete workflow JSON for import
+- **`get_templates_for_task`** - Curated templates for common automation tasks
+
 ### Advanced Tools
-- **`get_node_for_task`** - Pre-configured node settings for common tasks
-- **`list_tasks`** - Discover available task templates
 - **`validate_node_operation`** - Validate node configurations (operation-aware, profiles support)
 - **`validate_node_minimal`** - Quick validation for just required fields
 - **`validate_workflow`** - Complete workflow validation including AI tool connections
@@ -441,6 +764,7 @@ These powerful tools allow you to manage n8n workflows directly from Claude. The
 - **`n8n_delete_workflow`** - Delete workflows permanently
 - **`n8n_list_workflows`** - List workflows with filtering and pagination
 - **`n8n_validate_workflow`** - Validate workflows already in n8n by ID (NEW in v2.6.3)
+- **`n8n_autofix_workflow`** - Automatically fix common workflow errors (NEW in v2.13.0!)
 
 #### Execution Management
 - **`n8n_trigger_webhook_workflow`** - Trigger workflows via webhook URL
@@ -456,14 +780,17 @@ These powerful tools allow you to manage n8n workflows directly from Claude. The
 ### Example Usage
 
 ```typescript
-// Get essentials for quick configuration
-get_node_essentials("nodes-base.httpRequest")
+// Get essentials with real-world examples from templates
+get_node_essentials({
+  nodeType: "nodes-base.httpRequest",
+  includeExamples: true  // Returns top 3 configs from popular templates
+})
 
-// Find nodes for a specific task
-search_nodes({ query: "send email gmail" })
-
-// Get pre-configured settings
-get_node_for_task("send_email")
+// Search nodes with configuration examples
+search_nodes({
+  query: "send email gmail",
+  includeExamples: true  // Returns top 2 configs per node
+})
 
 // Validate before deployment
 validate_node_operation({
@@ -506,7 +833,6 @@ npm run rebuild
 # 5. Start the server
 npm start          # stdio mode for Claude Desktop
 npm run start:http # HTTP mode for remote access
-npm run start:sse  # SSE mode for n8n MCP Server Trigger
 ```
 
 ### Development Commands
@@ -526,7 +852,6 @@ npm run update:n8n        # Update n8n packages
 # Run Server
 npm run dev            # Development with auto-reload
 npm run dev:http       # HTTP dev mode
-npm run dev:sse        # SSE dev mode
 ```
 
 ## 📚 Documentation
@@ -544,8 +869,8 @@ npm run dev:sse        # SSE dev mode
 - [Validation System](./docs/validation-improvements-v2.4.2.md) - Smart validation profiles
 
 ### Development & Deployment
+- [Railway Deployment](./docs/RAILWAY_DEPLOYMENT.md) - One-click cloud deployment guide
 - [HTTP Deployment](./docs/HTTP_DEPLOYMENT.md) - Remote server setup guide
-- [SSE Implementation](./docs/SSE_IMPLEMENTATION.md) - Server-Sent Events for n8n triggers
 - [Dependency Management](./docs/DEPENDENCY_UPDATES.md) - Keeping n8n packages in sync
 - [Claude's Interview](./docs/CLAUDE_INTERVIEW.md) - Real-world impact of n8n-MCP
 
@@ -556,76 +881,38 @@ npm run dev:sse        # SSE dev mode
 
 ## 📊 Metrics & Coverage
 
-Current database coverage (n8n v1.100.1):
+Current database coverage (n8n v1.113.3):
 
-- ✅ **525/525** nodes loaded (100%)
-- ✅ **520** nodes with properties (99%)
-- ✅ **470** nodes with documentation (90%)
-- ✅ **263** AI-capable tools detected
+- ✅ **536/536** nodes loaded (100%)
+- ✅ **528** nodes with properties (98.7%)
+- ✅ **470** nodes with documentation (88%)
+- ✅ **267** AI-capable tools detected
+- ✅ **2,646** pre-extracted template configurations
+- ✅ **2,500+** workflow templates available
 - ✅ **AI Agent & LangChain nodes** fully documented
 - ⚡ **Average response time**: ~12ms
 - 💾 **Database size**: ~15MB (optimized)
 
 ## 🔄 Recent Updates
 
-### v2.7.4 - Self-Documenting MCP Tools
-- ✅ **RENAMED**: `start_here_workflow_guide` → `tools_documentation` for clarity
-- ✅ **NEW**: Depth parameter - Control documentation detail with "essentials" or "full"
-- ✅ **NEW**: Per-tool documentation - Get help for any specific MCP tool by name
-- ✅ **CONCISE**: Essential info by default, comprehensive docs on demand
-- ✅ **LLM-FRIENDLY**: Plain text format instead of JSON for better readability
-- ✅ **QUICK HELP**: Call without parameters for immediate quick reference
-- ✅ **8 TOOLS DOCUMENTED**: Complete documentation for most commonly used tools
-
-### v2.7.0 - Diff-Based Workflow Editing with Transactional Updates
-- ✅ **NEW**: `n8n_update_partial_workflow` tool - Update workflows using diff operations
-- ✅ **RENAMED**: `n8n_update_workflow` → `n8n_update_full_workflow` for clarity
-- ✅ **80-90% TOKEN SAVINGS**: Only send changes, not entire workflow JSON
-- ✅ **13 OPERATIONS**: addNode, removeNode, updateNode, moveNode, enable/disable, connections, settings, tags
-- ✅ **TRANSACTIONAL**: Two-pass processing allows adding nodes and connections in any order
-- ✅ **5 OPERATION LIMIT**: Ensures reliability and atomic updates
-- ✅ **VALIDATION MODE**: Test changes with `validateOnly: true` before applying
-- ✅ **IMPROVED DOCS**: Comprehensive parameter documentation and examples
-
-### v2.6.3 - n8n Instance Workflow Validation
-- ✅ **NEW**: `n8n_validate_workflow` tool - Validate workflows directly from n8n instance by ID
-- ✅ **FETCHES**: Retrieves workflow from n8n API and runs comprehensive validation
-- ✅ **CONSISTENT**: Uses same WorkflowValidator for reliability
-- ✅ **FLEXIBLE**: Supports all validation profiles and options
-- ✅ **INTEGRATED**: Part of complete workflow lifecycle management
-- ✅ **SIMPLE**: AI agents need only workflow ID, no JSON required
-
-### v2.6.2 - Enhanced Workflow Creation Validation
-- ✅ **NEW**: Node type validation - Verifies node types actually exist in n8n
-- ✅ **FIXED**: Critical issue with `nodes-base.webhook` validation - now caught before database lookup
-- ✅ **NEW**: Smart suggestions for common mistakes (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 with clear guidance and examples
-- ✅ **PREVENTS**: Broken workflows that show as question marks in n8n UI
-
-
-See [CHANGELOG.md](./docs/CHANGELOG.md) for full version history.
+See [CHANGELOG.md](./docs/CHANGELOG.md) for full version history and recent changes.
 
 ## ⚠️ Known Issues
 
-### Claude Desktop Container Duplication
-When using n8n-MCP with Claude Desktop in Docker mode, Claude Desktop may start the container twice during initialization. This is a known Claude Desktop bug ([modelcontextprotocol/servers#812](https://github.com/modelcontextprotocol/servers/issues/812)).
+### Claude Desktop Container Management
 
-**Symptoms:**
-- Two identical containers running for the same MCP server
-- Container name conflicts if using `--name` parameter
-- Doubled resource usage
+#### Container Accumulation (Fixed in v2.7.20+)
+Previous versions had an issue where containers would not properly clean up when Claude Desktop sessions ended. This has been fixed in v2.7.20+ with proper signal handling.
 
-**Workarounds:**
-1. **Avoid using --name parameter** - Let Docker assign random names:
+**For best container lifecycle management:**
+1. **Use the --init flag** (recommended) - Docker's init system ensures proper signal handling:
 ```json
 {
   "mcpServers": {
     "n8n-mcp": {
       "command": "docker",
       "args": [
-        "run", "-i", "--rm",
+        "run", "-i", "--rm", "--init",
         "ghcr.io/czlonkowski/n8n-mcp:latest"
       ]
     }
@@ -633,15 +920,70 @@ When using n8n-MCP with Claude Desktop in Docker mode, Claude Desktop may start
 }
 ```
 
-2. **Use HTTP mode instead** - Deploy n8n-mcp as a standalone HTTP server:
+2. **Ensure you're using v2.7.20 or later** - Check your version:
 ```bash
-docker compose up -d  # Start HTTP server
+docker run --rm ghcr.io/czlonkowski/n8n-mcp:latest --version
 ```
-Then connect via mcp-remote (see [HTTP Deployment Guide](./docs/HTTP_DEPLOYMENT.md))
 
-3. **Use Docker MCP Toolkit** - Better container management through Docker Desktop
 
-This issue does not affect the functionality of n8n-MCP itself, only the container management in Claude Desktop.
+## 🧪 Testing
+
+The project includes a comprehensive test suite with **2,883 tests** ensuring code quality and reliability:
+
+```bash
+# Run all tests
+npm test
+
+# Run tests with coverage report
+npm run test:coverage
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run specific test suites
+npm run test:unit           # 933 unit tests
+npm run test:integration    # 249 integration tests
+npm run test:bench          # Performance benchmarks
+```
+
+### Test Suite Overview
+
+- **Total Tests**: 2,883 (100% passing)
+  - **Unit Tests**: 2,526 tests across 99 files
+  - **Integration Tests**: 357 tests across 20 files
+- **Execution Time**: ~2.5 minutes in CI
+- **Test Framework**: Vitest (for speed and TypeScript support)
+- **Mocking**: MSW for API mocking, custom mocks for databases
+
+### Coverage & Quality
+
+- **Coverage Reports**: Generated in `./coverage` directory
+- **CI/CD**: Automated testing on all PRs with GitHub Actions
+- **Performance**: Environment-aware thresholds for CI vs local
+- **Parallel Execution**: Configurable thread pool for faster runs
+
+### Testing Architecture
+
+**Total: 3,336 tests** across unit and integration test suites
+
+- **Unit Tests** (2,766 tests): Isolated component testing with mocks
+  - Services layer: Enhanced validation, property filtering, workflow validation
+  - Parsers: Node parsing, property extraction, documentation mapping
+  - Database: Repositories, adapters, migrations, FTS5 search
+  - MCP tools: Tool definitions, documentation system
+  - HTTP server: Multi-tenant support, security, configuration
+
+- **Integration Tests** (570 tests): Full system behavior validation
+  - **n8n API Integration** (172 tests): All 18 MCP handler tools tested against real n8n instance
+    - Workflow management: Create, read, update, delete, list, validate, autofix
+    - Execution management: Trigger, retrieve, list, delete
+    - System tools: Health check, tool listing, diagnostics
+  - **MCP Protocol** (119 tests): Protocol compliance, session management, error handling
+  - **Database** (226 tests): Repository operations, transactions, performance, FTS5 search
+  - **Templates** (35 tests): Template fetching, storage, metadata operations
+  - **Docker** (18 tests): Configuration, entrypoint, security validation
+
+For detailed testing documentation, see [Testing Architecture](./docs/testing-architecture.md).
 
 ## 📦 License
 
@@ -661,12 +1003,49 @@ Contributions are welcome! Please:
 3. Run tests (`npm test`)
 4. Submit a pull request
 
+### 🚀 For Maintainers: Automated Releases
+
+This project uses automated releases triggered by version changes:
+
+```bash
+# Guided release preparation
+npm run prepare:release
+
+# Test release automation
+npm run test:release-automation
+```
+
+The system automatically handles:
+- 🏷️ GitHub releases with changelog content
+- 📦 NPM package publishing
+- 🐳 Multi-platform Docker images
+- 📚 Documentation updates
+
+See [Automated Release Guide](./docs/AUTOMATED_RELEASES.md) for complete details.
+
 ## 👏 Acknowledgments
 
 - [n8n](https://n8n.io) team for the workflow automation platform
 - [Anthropic](https://anthropic.com) for the Model Context Protocol
 - All contributors and users of this project
 
+### Template Attribution
+
+All workflow templates in this project are fetched from n8n's public template gallery at [n8n.io/workflows](https://n8n.io/workflows). Each template includes:
+- Full attribution to the original creator (name and username)
+- Direct link to the source template on n8n.io
+- Original workflow ID for reference
+
+The AI agent instructions in this project contain mandatory attribution requirements. When using any template, the AI will automatically:
+- Share the template author's name and username
+- Provide a direct link to the original template on n8n.io
+- Display attribution in the format: "This workflow is based on a template by **[author]** (@[username]). View the original at: [url]"
+
+Template creators retain all rights to their workflows. This project indexes templates to improve discoverability through AI assistants. If you're a template creator and have concerns about your template being indexed, please open an issue.
+
+Special thanks to the prolific template contributors whose work helps thousands of users automate their workflows, including:
+**David Ashby** (@cfomodz), **Yaron Been** (@yaron-nofluff), **Jimleuk** (@jimleuk), **Davide** (@n3witalia), **David Olusola** (@dae221), **Ranjan Dailata** (@ranjancse), **Airtop** (@cesar-at-airtop), **Joseph LePage** (@joe), **Don Jayamaha Jr** (@don-the-gem-dealer), **Angel Menendez** (@djangelic), and the entire n8n community of creators!
+
 ---
 
 <div align="center">

_config.yml

@@ -0,0 +1,41 @@
+# Jekyll configuration for GitHub Pages
+# This is only used for serving benchmark results
+
+# Only process benchmark-related files
+include:
+  - index.html
+  - benchmarks/
+
+# Exclude everything else to prevent Liquid syntax errors
+exclude:
+  - "*.md"
+  - "*.json"
+  - "*.ts"
+  - "*.js"
+  - "*.yml"
+  - src/
+  - tests/
+  - docs/
+  - scripts/
+  - dist/
+  - node_modules/
+  - package.json
+  - package-lock.json
+  - tsconfig.json
+  - README.md
+  - CHANGELOG.md
+  - LICENSE
+  - Dockerfile*
+  - docker-compose*
+  - .github/
+  - .vscode/
+  - .claude/
+  - deploy/
+  - examples/
+  - data/
+
+# Disable Jekyll processing for files we don't want processed
+plugins: []
+
+# Use simple theme
+theme: null

codecov.yml

@@ -0,0 +1,53 @@
+codecov:
+  require_ci_to_pass: yes
+
+coverage:
+  precision: 2
+  round: down
+  range: "70...100"
+
+  status:
+    project:
+      default:
+        target: 80%
+        threshold: 1%
+        base: auto
+        if_not_found: success
+        if_ci_failed: error
+        informational: false
+        only_pulls: false
+    patch:
+      default:
+        target: 80%
+        threshold: 1%
+        base: auto
+        if_not_found: success
+        if_ci_failed: error
+        informational: true
+        only_pulls: false
+
+parsers:
+  gcov:
+    branch_detection:
+      conditional: yes
+      loop: yes
+      method: no
+      macro: no
+
+comment:
+  layout: "reach,diff,flags,files,footer"
+  behavior: default
+  require_changes: false
+  require_base: false
+  require_head: true
+
+ignore:
+  - "node_modules/**/*"
+  - "dist/**/*"
+  - "tests/**/*"
+  - "scripts/**/*"
+  - "**/*.test.ts"
+  - "**/*.spec.ts"
+  - "src/mcp/index.ts"
+  - "src/http-server.ts"
+  - "src/http-server-single-session.ts"

deploy/quick-deploy-n8n.sh

@@ -0,0 +1,232 @@
+#!/bin/bash
+# Quick deployment script for n8n + n8n-mcp stack
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Default values
+COMPOSE_FILE="docker-compose.n8n.yml"
+ENV_FILE=".env"
+ENV_EXAMPLE=".env.n8n.example"
+
+# Function to print colored output
+print_info() {
+    echo -e "${GREEN}[INFO]${NC} $1"
+}
+
+print_warn() {
+    echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+print_error() {
+    echo -e "${RED}[ERROR]${NC} $1"
+}
+
+# Function to generate random token
+generate_token() {
+    openssl rand -hex 32
+}
+
+# Function to check prerequisites
+check_prerequisites() {
+    print_info "Checking prerequisites..."
+    
+    # Check Docker
+    if ! command -v docker &> /dev/null; then
+        print_error "Docker is not installed. Please install Docker first."
+        exit 1
+    fi
+    
+    # Check Docker Compose
+    if ! command -v docker-compose &> /dev/null && ! docker compose version &> /dev/null; then
+        print_error "Docker Compose is not installed. Please install Docker Compose first."
+        exit 1
+    fi
+    
+    # Check openssl for token generation
+    if ! command -v openssl &> /dev/null; then
+        print_error "OpenSSL is not installed. Please install OpenSSL first."
+        exit 1
+    fi
+    
+    print_info "All prerequisites are installed."
+}
+
+# Function to setup environment
+setup_environment() {
+    print_info "Setting up environment..."
+    
+    # Check if .env exists
+    if [ -f "$ENV_FILE" ]; then
+        print_warn ".env file already exists. Backing up to .env.backup"
+        cp "$ENV_FILE" ".env.backup"
+    fi
+    
+    # Copy example env file
+    if [ -f "$ENV_EXAMPLE" ]; then
+        cp "$ENV_EXAMPLE" "$ENV_FILE"
+        print_info "Created .env file from example"
+    else
+        print_error ".env.n8n.example file not found!"
+        exit 1
+    fi
+    
+    # Generate encryption key
+    ENCRYPTION_KEY=$(generate_token)
+    if [[ "$OSTYPE" == "darwin"* ]]; then
+        sed -i '' "s/N8N_ENCRYPTION_KEY=/N8N_ENCRYPTION_KEY=$ENCRYPTION_KEY/" "$ENV_FILE"
+    else
+        sed -i "s/N8N_ENCRYPTION_KEY=/N8N_ENCRYPTION_KEY=$ENCRYPTION_KEY/" "$ENV_FILE"
+    fi
+    print_info "Generated n8n encryption key"
+    
+    # Generate MCP auth token
+    MCP_TOKEN=$(generate_token)
+    if [[ "$OSTYPE" == "darwin"* ]]; then
+        sed -i '' "s/MCP_AUTH_TOKEN=/MCP_AUTH_TOKEN=$MCP_TOKEN/" "$ENV_FILE"
+    else
+        sed -i "s/MCP_AUTH_TOKEN=/MCP_AUTH_TOKEN=$MCP_TOKEN/" "$ENV_FILE"
+    fi
+    print_info "Generated MCP authentication token"
+    
+    print_warn "Please update the following in .env file:"
+    print_warn "  - N8N_BASIC_AUTH_PASSWORD (current: changeme)"
+    print_warn "  - N8N_API_KEY (get from n8n UI after first start)"
+}
+
+# Function to build images
+build_images() {
+    print_info "Building n8n-mcp image..."
+    
+    if docker compose version &> /dev/null; then
+        docker compose -f "$COMPOSE_FILE" build
+    else
+        docker-compose -f "$COMPOSE_FILE" build
+    fi
+    
+    print_info "Image built successfully"
+}
+
+# Function to start services
+start_services() {
+    print_info "Starting services..."
+    
+    if docker compose version &> /dev/null; then
+        docker compose -f "$COMPOSE_FILE" up -d
+    else
+        docker-compose -f "$COMPOSE_FILE" up -d
+    fi
+    
+    print_info "Services started"
+}
+
+# Function to show status
+show_status() {
+    print_info "Checking service status..."
+    
+    if docker compose version &> /dev/null; then
+        docker compose -f "$COMPOSE_FILE" ps
+    else
+        docker-compose -f "$COMPOSE_FILE" ps
+    fi
+    
+    echo ""
+    print_info "Services are starting up. This may take a minute..."
+    print_info "n8n will be available at: http://localhost:5678"
+    print_info "n8n-mcp will be available at: http://localhost:3000"
+    echo ""
+    print_warn "Next steps:"
+    print_warn "1. Access n8n at http://localhost:5678"
+    print_warn "2. Log in with admin/changeme (or your custom password)"
+    print_warn "3. Go to Settings > n8n API > Create API Key"
+    print_warn "4. Update N8N_API_KEY in .env file"
+    print_warn "5. Restart n8n-mcp: docker-compose -f $COMPOSE_FILE restart n8n-mcp"
+}
+
+# Function to stop services
+stop_services() {
+    print_info "Stopping services..."
+    
+    if docker compose version &> /dev/null; then
+        docker compose -f "$COMPOSE_FILE" down
+    else
+        docker-compose -f "$COMPOSE_FILE" down
+    fi
+    
+    print_info "Services stopped"
+}
+
+# Function to view logs
+view_logs() {
+    SERVICE=$1
+    
+    if [ -z "$SERVICE" ]; then
+        if docker compose version &> /dev/null; then
+            docker compose -f "$COMPOSE_FILE" logs -f
+        else
+            docker-compose -f "$COMPOSE_FILE" logs -f
+        fi
+    else
+        if docker compose version &> /dev/null; then
+            docker compose -f "$COMPOSE_FILE" logs -f "$SERVICE"
+        else
+            docker-compose -f "$COMPOSE_FILE" logs -f "$SERVICE"
+        fi
+    fi
+}
+
+# Main script
+case "${1:-help}" in
+    setup)
+        check_prerequisites
+        setup_environment
+        build_images
+        start_services
+        show_status
+        ;;
+    start)
+        start_services
+        show_status
+        ;;
+    stop)
+        stop_services
+        ;;
+    restart)
+        stop_services
+        start_services
+        show_status
+        ;;
+    status)
+        show_status
+        ;;
+    logs)
+        view_logs "${2}"
+        ;;
+    build)
+        build_images
+        ;;
+    *)
+        echo "n8n-mcp Quick Deploy Script"
+        echo ""
+        echo "Usage: $0 {setup|start|stop|restart|status|logs|build}"
+        echo ""
+        echo "Commands:"
+        echo "  setup    - Initial setup: create .env, build images, and start services"
+        echo "  start    - Start all services"
+        echo "  stop     - Stop all services"
+        echo "  restart  - Restart all services"
+        echo "  status   - Show service status"
+        echo "  logs     - View logs (optionally specify service: logs n8n-mcp)"
+        echo "  build    - Build/rebuild images"
+        echo ""
+        echo "Examples:"
+        echo "  $0 setup          # First time setup"
+        echo "  $0 logs n8n-mcp   # View n8n-mcp logs"
+        echo "  $0 restart        # Restart all services"
+        ;;
+esac

docker-compose.extract.yml

@@ -24,7 +24,7 @@ services:
 
   # Extractor service that will read from the mounted volumes
   node-extractor:
-    image: node:18-alpine
+    image: node:22-alpine
     container_name: n8n-node-extractor
     working_dir: /app
     depends_on:

docker-compose.n8n.yml

@@ -0,0 +1,73 @@
+version: '3.8'
+
+services:
+  # n8n workflow automation
+  n8n:
+    image: n8nio/n8n:latest
+    container_name: n8n
+    restart: unless-stopped
+    ports:
+      - "${N8N_PORT:-5678}:5678"
+    environment:
+      - N8N_BASIC_AUTH_ACTIVE=${N8N_BASIC_AUTH_ACTIVE:-true}
+      - N8N_BASIC_AUTH_USER=${N8N_BASIC_AUTH_USER:-admin}
+      - N8N_BASIC_AUTH_PASSWORD=${N8N_BASIC_AUTH_PASSWORD:-password}
+      - N8N_HOST=${N8N_HOST:-localhost}
+      - N8N_PORT=5678
+      - N8N_PROTOCOL=${N8N_PROTOCOL:-http}
+      - WEBHOOK_URL=${N8N_WEBHOOK_URL:-http://localhost:5678/}
+      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
+    volumes:
+      - n8n_data:/home/node/.n8n
+    networks:
+      - n8n-network
+    healthcheck:
+      test: ["CMD", "sh", "-c", "wget --quiet --spider --tries=1 --timeout=10 http://localhost:5678/healthz || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 30s
+
+  # n8n-mcp server for AI assistance
+  n8n-mcp:
+    build:
+      context: .
+      dockerfile: Dockerfile  # Uses standard Dockerfile with N8N_MODE=true env var
+    image: ghcr.io/${GITHUB_REPOSITORY:-czlonkowski/n8n-mcp}/n8n-mcp:${VERSION:-latest}
+    container_name: n8n-mcp
+    restart: unless-stopped
+    ports:
+      - "${MCP_PORT:-3000}:3000"
+    environment:
+      - NODE_ENV=production
+      - N8N_MODE=true
+      - MCP_MODE=http
+      - N8N_API_URL=http://n8n:5678
+      - N8N_API_KEY=${N8N_API_KEY}
+      - MCP_AUTH_TOKEN=${MCP_AUTH_TOKEN}
+      - AUTH_TOKEN=${MCP_AUTH_TOKEN}
+      - LOG_LEVEL=${LOG_LEVEL:-info}
+    volumes:
+      - ./data:/app/data:ro
+      - mcp_logs:/app/logs
+    networks:
+      - n8n-network
+    depends_on:
+      n8n:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+
+volumes:
+  n8n_data:
+    driver: local
+  mcp_logs:
+    driver: local
+
+networks:
+  n8n-network:
+    driver: bridge

docker-compose.sse.yml

@@ -1,56 +0,0 @@
-version: '3.8'
-
-services:
-  n8n-mcp-sse:
-    image: ghcr.io/czlonkowski/n8n-mcp:latest
-    container_name: n8n-mcp-sse
-    command: npm run start:sse
-    ports:
-      - "3000:3000"
-    environment:
-      - AUTH_TOKEN=${AUTH_TOKEN:-test-secure-token-123456789}
-      - PORT=3000
-      - HOST=0.0.0.0
-      - NODE_ENV=production
-      - LOG_LEVEL=info
-      - CORS_ORIGIN=*
-      - TRUST_PROXY=0
-    volumes:
-      - ./data:/app/data:ro
-    restart: unless-stopped
-    healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 40s
-    networks:
-      - n8n-network
-
-  # Optional: n8n instance for testing
-  n8n:
-    image: n8nio/n8n:latest
-    container_name: n8n
-    ports:
-      - "5678:5678"
-    environment:
-      - N8N_BASIC_AUTH_ACTIVE=true
-      - N8N_BASIC_AUTH_USER=admin
-      - N8N_BASIC_AUTH_PASSWORD=password
-      - N8N_HOST=0.0.0.0
-      - N8N_PORT=5678
-      - N8N_PROTOCOL=http
-      - N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true
-      - WEBHOOK_URL=http://n8n:5678/
-    volumes:
-      - n8n_data:/home/node/.n8n
-    restart: unless-stopped
-    networks:
-      - n8n-network
-
-networks:
-  n8n-network:
-    driver: bridge
-
-volumes:
-  n8n_data:

docker-compose.test-n8n.yml

@@ -0,0 +1,24 @@
+# docker-compose.test-n8n.yml - Simple test setup for n8n integration
+# Run n8n in Docker, n8n-mcp locally for faster testing
+
+version: '3.8'
+
+services:
+  n8n:
+    image: n8nio/n8n:latest
+    container_name: n8n-test
+    ports:
+      - "5678:5678"
+    environment:
+      - N8N_BASIC_AUTH_ACTIVE=false
+      - N8N_HOST=localhost
+      - N8N_PORT=5678
+      - N8N_PROTOCOL=http
+      - NODE_ENV=development
+      - N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true
+    volumes:
+      - n8n_test_data:/home/node/.n8n
+    network_mode: "host"  # Use host network for easy local testing
+
+volumes:
+  n8n_test_data:

docker-compose.yml

@@ -23,7 +23,11 @@ services:
       # Database
       NODE_DB_PATH: ${NODE_DB_PATH:-/app/data/nodes.db}
       REBUILD_ON_START: ${REBUILD_ON_START:-false}
-      
+
+      # Telemetry: Anonymous usage statistics are ENABLED by default
+      # To opt-out, uncomment and set to 'true':
+      # N8N_MCP_TELEMETRY_DISABLED: ${N8N_MCP_TELEMETRY_DISABLED:-true}
+
       # Optional: n8n API configuration (enables 16 additional management tools)
       # Uncomment and configure to enable n8n workflow management
       # N8N_API_URL: ${N8N_API_URL}

docker/README.md

@@ -0,0 +1,87 @@
+# Docker Usage Guide for n8n-mcp
+
+## Running in HTTP Mode
+
+The n8n-mcp Docker container can be run in HTTP mode using several methods:
+
+### Method 1: Using Environment Variables (Recommended)
+
+```bash
+docker run -d -p 3000:3000 \
+  --name n8n-mcp-server \
+  -e MCP_MODE=http \
+  -e AUTH_TOKEN=your-secure-token-here \
+  ghcr.io/czlonkowski/n8n-mcp:latest
+```
+
+### Method 2: Using docker-compose
+
+```bash
+# Create a .env file
+cat > .env << EOF
+MCP_MODE=http
+AUTH_TOKEN=your-secure-token-here
+PORT=3000
+EOF
+
+# Run with docker-compose
+docker-compose up -d
+```
+
+### Method 3: Using a Configuration File
+
+Create a `config.json` file:
+```json
+{
+  "MCP_MODE": "http",
+  "AUTH_TOKEN": "your-secure-token-here",
+  "PORT": "3000",
+  "LOG_LEVEL": "info"
+}
+```
+
+Run with the config file:
+```bash
+docker run -d -p 3000:3000 \
+  --name n8n-mcp-server \
+  -v $(pwd)/config.json:/app/config.json:ro \
+  ghcr.io/czlonkowski/n8n-mcp:latest
+```
+
+### Method 4: Using the n8n-mcp serve Command
+
+```bash
+docker run -d -p 3000:3000 \
+  --name n8n-mcp-server \
+  -e AUTH_TOKEN=your-secure-token-here \
+  ghcr.io/czlonkowski/n8n-mcp:latest \
+  n8n-mcp serve
+```
+
+## Important Notes
+
+1. **AUTH_TOKEN is required** for HTTP mode. Generate a secure token:
+   ```bash
+   openssl rand -base64 32
+   ```
+
+2. **Environment variables take precedence** over config file values
+
+3. **Default mode is stdio** if MCP_MODE is not specified
+
+4. **Health check endpoint** is available at `http://localhost:3000/health`
+
+## Troubleshooting
+
+### Container exits immediately
+- Check logs: `docker logs n8n-mcp-server`
+- Ensure AUTH_TOKEN is set for HTTP mode
+
+### "n8n-mcp: not found" error
+- This has been fixed in the latest version
+- Use the full command: `node /app/dist/mcp/index.js` as a workaround
+
+### Config file not working
+- Ensure the file is valid JSON
+- Mount as read-only: `-v $(pwd)/config.json:/app/config.json:ro`
+- Check that the config parser is present: `docker exec n8n-mcp-server ls -la /app/docker/`

docker/docker-entrypoint.sh

@@ -1,55 +1,166 @@
 #!/bin/sh
 set -e
 
+# Load configuration from JSON file if it exists
+if [ -f "/app/config.json" ] && [ -f "/app/docker/parse-config.js" ]; then
+    # Use Node.js to generate shell-safe export commands
+    eval $(node /app/docker/parse-config.js /app/config.json)
+fi
+
+# Helper function for safe logging (prevents stdio mode corruption)
+log_message() {
+    [ "$MCP_MODE" != "stdio" ] && echo "$@"
+}
+
 # Environment variable validation
 if [ "$MCP_MODE" = "http" ] && [ -z "$AUTH_TOKEN" ] && [ -z "$AUTH_TOKEN_FILE" ]; then
-    echo "ERROR: AUTH_TOKEN or AUTH_TOKEN_FILE is required for HTTP mode"
+    log_message "ERROR: AUTH_TOKEN or AUTH_TOKEN_FILE is required for HTTP mode" >&2
     exit 1
 fi
 
 # Validate AUTH_TOKEN_FILE if provided
 if [ -n "$AUTH_TOKEN_FILE" ] && [ ! -f "$AUTH_TOKEN_FILE" ]; then
-    echo "ERROR: AUTH_TOKEN_FILE specified but file not found: $AUTH_TOKEN_FILE"
+    log_message "ERROR: AUTH_TOKEN_FILE specified but file not found: $AUTH_TOKEN_FILE" >&2
     exit 1
 fi
 
+# Database path configuration - respect NODE_DB_PATH if set
+if [ -n "$NODE_DB_PATH" ]; then
+    # Basic validation - must end with .db
+    case "$NODE_DB_PATH" in
+        *.db) ;;
+        *) log_message "ERROR: NODE_DB_PATH must end with .db" >&2; exit 1 ;;
+    esac
+    
+    # Use the path as-is (Docker paths should be absolute anyway)
+    DB_PATH="$NODE_DB_PATH"
+else
+    DB_PATH="/app/data/nodes.db"
+fi
+
+DB_DIR=$(dirname "$DB_PATH")
+
+# Ensure database directory exists with correct ownership
+if [ ! -d "$DB_DIR" ]; then
+    log_message "Creating database directory: $DB_DIR"
+    if [ "$(id -u)" = "0" ]; then
+        # Create as root but immediately fix ownership
+        mkdir -p "$DB_DIR" && chown nodejs:nodejs "$DB_DIR"
+    else
+        mkdir -p "$DB_DIR"
+    fi
+fi
+
 # Database initialization with file locking to prevent race conditions
-if [ ! -f "/app/data/nodes.db" ]; then
-    echo "Database not found. Initializing..."
-    # Use a lock file to prevent multiple containers from initializing simultaneously
-    (
-        flock -x 200
-        # Double-check inside the lock
-        if [ ! -f "/app/data/nodes.db" ]; then
-            echo "Initializing database..."
-            cd /app && node dist/scripts/rebuild.js || {
-                echo "ERROR: Database initialization failed"
+if [ ! -f "$DB_PATH" ]; then
+    log_message "Database not found at $DB_PATH. Initializing..."
+    
+    # Ensure lock directory exists before attempting to create lock
+    mkdir -p "$DB_DIR"
+    
+    # Check if flock is available
+    if command -v flock >/dev/null 2>&1; then
+        # Use a lock file to prevent multiple containers from initializing simultaneously
+        # Try to create lock file, handle permission errors gracefully
+        LOCK_FILE="$DB_DIR/.db.lock"
+        
+        # Ensure we can create the lock file - fix permissions if running as root
+        if [ "$(id -u)" = "0" ] && [ ! -w "$DB_DIR" ]; then
+            chown nodejs:nodejs "$DB_DIR" 2>/dev/null || true
+            chmod 755 "$DB_DIR" 2>/dev/null || true
+        fi
+        
+        # Try to create lock file with proper error handling
+        if touch "$LOCK_FILE" 2>/dev/null; then
+            (
+                flock -x 200
+                # Double-check inside the lock
+                if [ ! -f "$DB_PATH" ]; then
+                    log_message "Initializing database at $DB_PATH..."
+                    cd /app && NODE_DB_PATH="$DB_PATH" node dist/scripts/rebuild.js || {
+                        log_message "ERROR: Database initialization failed" >&2
+                        exit 1
+                    }
+                fi
+            ) 200>"$LOCK_FILE"
+        else
+            log_message "WARNING: Cannot create lock file at $LOCK_FILE, proceeding without file locking"
+            # Fallback without locking if we can't create the lock file
+            if [ ! -f "$DB_PATH" ]; then
+                log_message "Initializing database at $DB_PATH..."
+                cd /app && NODE_DB_PATH="$DB_PATH" node dist/scripts/rebuild.js || {
+                    log_message "ERROR: Database initialization failed" >&2
+                    exit 1
+                }
+            fi
+        fi
+    else
+        # Fallback without locking (log warning)
+        log_message "WARNING: flock not available, database initialization may have race conditions"
+        if [ ! -f "$DB_PATH" ]; then
+            log_message "Initializing database at $DB_PATH..."
+            cd /app && NODE_DB_PATH="$DB_PATH" node dist/scripts/rebuild.js || {
+                log_message "ERROR: Database initialization failed" >&2
                 exit 1
             }
         fi
-    ) 200>/app/data/.db.lock
+    fi
 fi
 
 # Fix permissions if running as root (for development)
 if [ "$(id -u)" = "0" ]; then
-    echo "Running as root, fixing permissions..."
-    chown -R nodejs:nodejs /app/data
-    # Switch to nodejs user (using Alpine's native su)
-    exec su nodejs -c "$*"
+    log_message "Running as root, fixing permissions..."
+    chown -R nodejs:nodejs "$DB_DIR"
+    # Also ensure /app/data exists for backward compatibility
+    if [ -d "/app/data" ]; then
+        chown -R nodejs:nodejs /app/data
+    fi
+    # Switch to nodejs user with proper exec chain for signal propagation
+    # Build the command to execute
+    if [ $# -eq 0 ]; then
+        # No arguments provided, use default CMD from Dockerfile
+        set -- node /app/dist/mcp/index.js
+    fi
+    # Export all needed environment variables
+    export MCP_MODE="$MCP_MODE"
+    export NODE_DB_PATH="$NODE_DB_PATH"
+    export AUTH_TOKEN="$AUTH_TOKEN"
+    export AUTH_TOKEN_FILE="$AUTH_TOKEN_FILE"
+    
+    # Ensure AUTH_TOKEN_FILE has restricted permissions for security
+    if [ -n "$AUTH_TOKEN_FILE" ] && [ -f "$AUTH_TOKEN_FILE" ]; then
+        chmod 600 "$AUTH_TOKEN_FILE" 2>/dev/null || true
+        chown nodejs:nodejs "$AUTH_TOKEN_FILE" 2>/dev/null || true
+    fi
+    # Use exec with su-exec for proper signal handling (Alpine Linux)
+    # su-exec advantages:
+    # - Proper signal forwarding (critical for container shutdown)
+    # - No intermediate shell process
+    # - Designed for privilege dropping in containers
+    if command -v su-exec >/dev/null 2>&1; then
+        exec su-exec nodejs "$@"
+    else
+        # Fallback to su with preserved environment
+        # Use safer approach to prevent command injection
+        exec su -p nodejs -s /bin/sh -c 'exec "$0" "$@"' -- sh -c 'exec "$@"' -- "$@"
+    fi
 fi
 
-# Trap signals for graceful shutdown
-# In stdio mode, don't output anything to stdout as it breaks JSON-RPC
-if [ "$MCP_MODE" = "stdio" ]; then
-    # Silent trap - no output at all
-    trap 'kill -TERM $PID 2>/dev/null || true' TERM INT EXIT
-else
-    # In HTTP mode, output to stderr
-    trap 'echo "Shutting down..." >&2; kill -TERM $PID 2>/dev/null' TERM INT EXIT
+# Handle special commands
+if [ "$1" = "n8n-mcp" ] && [ "$2" = "serve" ]; then
+    # Set HTTP mode for "n8n-mcp serve" command
+    export MCP_MODE="http"
+    shift 2  # Remove "n8n-mcp serve" from arguments
+    set -- node /app/dist/mcp/index.js "$@"
 fi
 
-# Execute the main command in background
-# In stdio mode, use the wrapper for clean output
+# Export NODE_DB_PATH so it's visible to child processes
+if [ -n "$DB_PATH" ]; then
+    export NODE_DB_PATH="$DB_PATH"
+fi
+
+# Execute the main command directly with exec
+# This ensures our Node.js process becomes PID 1 and receives signals directly
 if [ "$MCP_MODE" = "stdio" ]; then
     # Debug: Log to stderr to check if wrapper exists
     if [ "$DEBUG_DOCKER" = "true" ]; then
@@ -59,6 +170,7 @@ if [ "$MCP_MODE" = "stdio" ]; then
     
     if [ -f "/app/dist/mcp/stdio-wrapper.js" ]; then
         # Use the stdio wrapper for clean JSON-RPC output
+        # exec replaces the shell with node process as PID 1
         exec node /app/dist/mcp/stdio-wrapper.js
     else
         # Fallback: run with explicit environment
@@ -66,5 +178,10 @@ if [ "$MCP_MODE" = "stdio" ]; then
     fi
 else
     # HTTP mode or other
-    exec "$@"
+    if [ $# -eq 0 ]; then
+        # No arguments provided, use default
+        exec node /app/dist/mcp/index.js
+    else
+        exec "$@"
+    fi
 fi

docker/n8n-mcp

@@ -0,0 +1,45 @@
+#!/bin/sh
+# n8n-mcp wrapper script for Docker
+# Transforms "n8n-mcp serve" to proper start command
+
+# Validate arguments to prevent command injection
+validate_args() {
+    for arg in "$@"; do
+        case "$arg" in
+            # Allowed arguments - extend this list as needed
+            --port=*|--host=*|--verbose|--quiet|--help|-h|--version|-v)
+                # Valid arguments
+                ;;
+            *)
+                # Allow empty arguments
+                if [ -z "$arg" ]; then
+                    continue
+                fi
+                # Reject any other arguments for security
+                echo "Error: Invalid argument: $arg" >&2
+                echo "Allowed arguments: --port=<port>, --host=<host>, --verbose, --quiet, --help, --version" >&2
+                exit 1
+                ;;
+        esac
+    done
+}
+
+if [ "$1" = "serve" ]; then
+    # Transform serve command to start with HTTP mode
+    export MCP_MODE="http"
+    shift  # Remove "serve" from arguments
+    
+    # Validate remaining arguments
+    validate_args "$@"
+    
+    # For testing purposes, output the environment variable if requested
+    if [ "$DEBUG_ENV" = "true" ]; then
+        echo "MCP_MODE=$MCP_MODE" >&2
+    fi
+    
+    exec node /app/dist/mcp/index.js "$@"
+else
+    # For non-serve commands, pass through without validation
+    # This allows flexibility for other subcommands
+    exec node /app/dist/mcp/index.js "$@"
+fi

docker/parse-config.js

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+/**
+ * Parse JSON config file and output shell-safe export commands
+ * Only outputs variables that aren't already set in environment
+ * 
+ * Security: Uses safe quoting without any shell execution
+ */
+
+const fs = require('fs');
+
+// Debug logging support
+const DEBUG = process.env.DEBUG_CONFIG === 'true';
+
+function debugLog(message) {
+  if (DEBUG) {
+    process.stderr.write(`[parse-config] ${message}\n`);
+  }
+}
+
+const configPath = process.argv[2] || '/app/config.json';
+debugLog(`Using config path: ${configPath}`);
+
+// Dangerous environment variables that should never be set
+const DANGEROUS_VARS = new Set([
+  'PATH', 'LD_PRELOAD', 'LD_LIBRARY_PATH', 'LD_AUDIT',
+  'BASH_ENV', 'ENV', 'CDPATH', 'IFS', 'PS1', 'PS2', 'PS3', 'PS4',
+  'SHELL', 'BASH_FUNC', 'SHELLOPTS', 'GLOBIGNORE',
+  'PERL5LIB', 'PYTHONPATH', 'NODE_PATH', 'RUBYLIB'
+]);
+
+/**
+ * Sanitize a key name for use as environment variable
+ * Converts to uppercase and replaces invalid chars with underscore
+ */
+function sanitizeKey(key) {
+  // Convert to string and handle edge cases
+  const keyStr = String(key || '').trim();
+  
+  if (!keyStr) {
+    return 'EMPTY_KEY';
+  }
+  
+  // Special handling for NODE_DB_PATH to preserve exact casing
+  if (keyStr === 'NODE_DB_PATH') {
+    return 'NODE_DB_PATH';
+  }
+  
+  const sanitized = keyStr
+    .toUpperCase()
+    .replace(/[^A-Z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '') // Trim underscores
+    .replace(/^(\d)/, '_$1'); // Prefix with _ if starts with number
+  
+  // If sanitization results in empty string, use a default
+  return sanitized || 'EMPTY_KEY';
+}
+
+/**
+ * Safely quote a string for shell use
+ * This follows POSIX shell quoting rules
+ */
+function shellQuote(str) {
+  // Remove null bytes which are not allowed in environment variables
+  str = str.replace(/\x00/g, '');
+  
+  // Always use single quotes for consistency and safety
+  // Single quotes protect everything except other single quotes
+  return "'" + str.replace(/'/g, "'\"'\"'") + "'";
+}
+
+try {
+  if (!fs.existsSync(configPath)) {
+    debugLog(`Config file not found at: ${configPath}`);
+    process.exit(0); // Silent exit if no config file
+  }
+
+  let configContent;
+  let config;
+  
+  try {
+    configContent = fs.readFileSync(configPath, 'utf8');
+    debugLog(`Read config file, size: ${configContent.length} bytes`);
+  } catch (readError) {
+    // Silent exit on read errors
+    debugLog(`Error reading config: ${readError.message}`);
+    process.exit(0);
+  }
+  
+  try {
+    config = JSON.parse(configContent);
+    debugLog(`Parsed config with ${Object.keys(config).length} top-level keys`);
+  } catch (parseError) {
+    // Silent exit on invalid JSON
+    debugLog(`Error parsing JSON: ${parseError.message}`);
+    process.exit(0);
+  }
+  
+  // Validate config is an object
+  if (typeof config !== 'object' || config === null || Array.isArray(config)) {
+    // Silent exit on invalid config structure
+    process.exit(0);
+  }
+  
+  // Convert nested objects to flat environment variables
+  const flattenConfig = (obj, prefix = '', depth = 0) => {
+    const result = {};
+    
+    // Prevent infinite recursion
+    if (depth > 10) {
+      return result;
+    }
+    
+    for (const [key, value] of Object.entries(obj)) {
+      const sanitizedKey = sanitizeKey(key);
+      
+      // Skip if sanitization resulted in EMPTY_KEY (indicating invalid key)
+      if (sanitizedKey === 'EMPTY_KEY') {
+        debugLog(`Skipping key '${key}': invalid key name`);
+        continue;
+      }
+      
+      const envKey = prefix ? `${prefix}_${sanitizedKey}` : sanitizedKey;
+      
+      // Skip if key is too long
+      if (envKey.length > 255) {
+        debugLog(`Skipping key '${envKey}': too long (${envKey.length} chars)`);
+        continue;
+      }
+      
+      if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        // Recursively flatten nested objects
+        Object.assign(result, flattenConfig(value, envKey, depth + 1));
+      } else if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+        // Only include if not already set in environment
+        if (!process.env[envKey]) {
+          let stringValue = String(value);
+          
+          // Handle special JavaScript number values
+          if (typeof value === 'number') {
+            if (!isFinite(value)) {
+              if (value === Infinity) {
+                stringValue = 'Infinity';
+              } else if (value === -Infinity) {
+                stringValue = '-Infinity';
+              } else if (isNaN(value)) {
+                stringValue = 'NaN';
+              }
+            }
+          }
+          
+          // Skip if value is too long
+          if (stringValue.length <= 32768) {
+            result[envKey] = stringValue;
+          }
+        }
+      }
+    }
+    
+    return result;
+  };
+  
+  // Output shell-safe export commands
+  const flattened = flattenConfig(config);
+  const exports = [];
+  
+  for (const [key, value] of Object.entries(flattened)) {
+    // Validate key name (alphanumeric and underscore only)
+    if (!/^[A-Z_][A-Z0-9_]*$/.test(key)) {
+      continue; // Skip invalid variable names
+    }
+    
+    // Skip dangerous variables
+    if (DANGEROUS_VARS.has(key) || key.startsWith('BASH_FUNC_')) {
+      debugLog(`Warning: Ignoring dangerous variable: ${key}`);
+      process.stderr.write(`Warning: Ignoring dangerous variable: ${key}\n`);
+      continue;
+    }
+    
+    // Safely quote the value
+    const quotedValue = shellQuote(value);
+    exports.push(`export ${key}=${quotedValue}`);
+  }
+  
+  // Use process.stdout.write to ensure output goes to stdout
+  if (exports.length > 0) {
+    process.stdout.write(exports.join('\n') + '\n');
+  }
+  
+} catch (error) {
+  // Silent fail - don't break the container startup
+  process.exit(0);
+}

docs/AUTOMATED_RELEASES.md

@@ -0,0 +1,384 @@
+# Automated Release Process
+
+This document describes the automated release system for n8n-mcp, which handles version detection, changelog parsing, and multi-artifact publishing.
+
+## Overview
+
+The automated release system is triggered when the version in `package.json` is updated and pushed to the main branch. It handles:
+
+- 🏷️ **GitHub Releases**: Creates releases with changelog content
+- 📦 **NPM Publishing**: Publishes optimized runtime package
+- 🐳 **Docker Images**: Builds and pushes multi-platform images
+- 📚 **Documentation**: Updates version badges automatically
+
+## Quick Start
+
+### For Maintainers
+
+Use the prepared release script for a guided experience:
+
+```bash
+npm run prepare:release
+```
+
+This script will:
+1. Prompt for the new version
+2. Update `package.json` and `package.runtime.json`
+3. Update the changelog
+4. Run tests and build
+5. Create a git commit
+6. Optionally push to trigger the release
+
+### Manual Process
+
+1. **Update the version**:
+   ```bash
+   # Edit package.json version field
+   vim package.json
+   
+   # Sync to runtime package
+   npm run sync:runtime-version
+   ```
+
+2. **Update the changelog**:
+   ```bash
+   # Edit docs/CHANGELOG.md
+   vim docs/CHANGELOG.md
+   ```
+
+3. **Test and commit**:
+   ```bash
+   # Ensure everything works
+   npm test
+   npm run build
+   npm run rebuild
+   
+   # Commit changes
+   git add package.json package.runtime.json docs/CHANGELOG.md
+   git commit -m "chore: release vX.Y.Z"
+   git push
+   ```
+
+## Workflow Details
+
+### Version Detection
+
+The workflow monitors pushes to the main branch and detects when `package.json` version changes:
+
+```yaml
+paths:
+  - 'package.json'
+  - 'package.runtime.json'
+```
+
+### Changelog Parsing
+
+Automatically extracts release notes from `docs/CHANGELOG.md` using the version header format:
+
+```markdown
+## [2.10.0] - 2025-08-02
+
+### Added
+- New feature descriptions
+
+### Changed
+- Changed feature descriptions
+
+### Fixed
+- Bug fix descriptions
+```
+
+### Release Artifacts
+
+#### GitHub Release
+- Created with extracted changelog content
+- Tagged with `vX.Y.Z` format
+- Includes installation instructions
+- Links to documentation
+
+#### NPM Package
+- Published as `n8n-mcp` on npmjs.com
+- Uses runtime-only dependencies (8 packages vs 50+ dev deps)
+- Optimized for `npx` usage
+- ~50MB vs 1GB+ with dev dependencies
+
+#### Docker Images
+- **Standard**: `ghcr.io/czlonkowski/n8n-mcp:vX.Y.Z`
+- **Railway**: `ghcr.io/czlonkowski/n8n-mcp-railway:vX.Y.Z`
+- Multi-platform: linux/amd64, linux/arm64
+- Semantic version tags: `vX.Y.Z`, `vX.Y`, `vX`, `latest`
+
+## Configuration
+
+### Required Secrets
+
+Set these in GitHub repository settings → Secrets:
+
+| Secret | Description | Required |
+|--------|-------------|----------|
+| `NPM_TOKEN` | NPM authentication token for publishing | ✅ Yes |
+| `GITHUB_TOKEN` | Automatically provided by GitHub Actions | ✅ Auto |
+
+### NPM Token Setup
+
+1. Login to [npmjs.com](https://www.npmjs.com)
+2. Go to Account Settings → Access Tokens
+3. Create a new **Automation** token
+4. Add as `NPM_TOKEN` secret in GitHub
+
+## Testing
+
+### Test Release Automation
+
+Validate the release system without triggering a release:
+
+```bash
+npm run test:release-automation
+```
+
+This checks:
+- ✅ File existence and structure
+- ✅ Version detection logic
+- ✅ Changelog parsing
+- ✅ Build process
+- ✅ NPM package preparation
+- ✅ Docker configuration
+- ✅ Workflow syntax
+- ✅ Environment setup
+
+### Local Testing
+
+Test individual components:
+
+```bash
+# Test version detection
+node -e "console.log(require('./package.json').version)"
+
+# Test changelog parsing
+node scripts/test-release-automation.js
+
+# Test npm package preparation
+npm run prepare:publish
+
+# Test Docker build
+docker build -t test-image .
+```
+
+## Workflow Jobs
+
+### 1. Version Detection
+- Compares current vs previous version in git history
+- Determines if it's a prerelease (alpha, beta, rc, dev)
+- Outputs version information for other jobs
+
+### 2. Changelog Extraction
+- Parses `docs/CHANGELOG.md` for the current version
+- Extracts content between version headers
+- Provides formatted release notes
+
+### 3. GitHub Release Creation
+- Creates annotated git tag
+- Creates GitHub release with changelog content
+- Handles prerelease flag for alpha/beta versions
+
+### 4. Build and Test
+- Installs dependencies
+- Runs full test suite
+- Builds TypeScript
+- Rebuilds node database
+- Type checking
+
+### 5. NPM Publishing
+- Prepares optimized package structure
+- Uses `package.runtime.json` for dependencies
+- Publishes to npmjs.com registry
+- Automatic cleanup
+
+### 6. Docker Building
+- Multi-platform builds (amd64, arm64)
+- Two image variants (standard, railway)
+- Semantic versioning tags
+- GitHub Container Registry
+
+### 7. Documentation Updates
+- Updates version badges in README
+- Commits documentation changes
+- Automatic push back to repository
+
+## Monitoring
+
+### GitHub Actions
+Monitor releases at: https://github.com/czlonkowski/n8n-mcp/actions
+
+### Release Status
+- **GitHub Releases**: https://github.com/czlonkowski/n8n-mcp/releases
+- **NPM Package**: https://www.npmjs.com/package/n8n-mcp
+- **Docker Images**: https://github.com/czlonkowski/n8n-mcp/pkgs/container/n8n-mcp
+
+### Notifications
+
+The workflow provides comprehensive summaries:
+- ✅ Success notifications with links
+- ❌ Failure notifications with error details
+- 📊 Artifact information and installation commands
+
+## Troubleshooting
+
+### Common Issues
+
+#### NPM Publishing Fails
+```
+Error: 401 Unauthorized
+```
+**Solution**: Check NPM_TOKEN secret is valid and has publishing permissions.
+
+#### Docker Build Fails
+```
+Error: failed to solve: could not read from registry
+```
+**Solution**: Check GitHub Container Registry permissions and GITHUB_TOKEN.
+
+#### Changelog Parsing Fails
+```
+No changelog entries found for version X.Y.Z
+```
+**Solution**: Ensure changelog follows the correct format:
+```markdown
+## [X.Y.Z] - YYYY-MM-DD
+```
+
+#### Version Detection Fails
+```
+Version not incremented
+```
+**Solution**: Ensure new version is greater than the previous version.
+
+### Recovery Steps
+
+#### Failed NPM Publish
+1. Check if version was already published
+2. If not, manually publish:
+   ```bash
+   npm run prepare:publish
+   cd npm-publish-temp
+   npm publish
+   ```
+
+#### Failed Docker Build
+1. Build locally to test:
+   ```bash
+   docker build -t test-build .
+   ```
+2. Re-trigger workflow or push a fix
+
+#### Incomplete Release
+1. Delete the created tag if needed:
+   ```bash
+   git tag -d vX.Y.Z
+   git push --delete origin vX.Y.Z
+   ```
+2. Fix issues and push again
+
+## Security
+
+### Secrets Management
+- NPM_TOKEN has limited scope (publish only)
+- GITHUB_TOKEN has automatic scoping
+- No secrets are logged or exposed
+
+### Package Security
+- Runtime package excludes development dependencies
+- No build tools or test frameworks in published package
+- Minimal attack surface (~50MB vs 1GB+)
+
+### Docker Security
+- Multi-stage builds
+- Non-root user execution
+- Minimal base images
+- Security scanning enabled
+
+## Changelog Format
+
+The automated system expects changelog entries in [Keep a Changelog](https://keepachangelog.com/) format:
+
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+### Added
+- New features for next release
+
+## [2.10.0] - 2025-08-02
+
+### Added
+- Automated release system
+- Multi-platform Docker builds
+
+### Changed
+- Improved version detection
+- Enhanced error handling
+
+### Fixed
+- Fixed changelog parsing edge cases
+- Fixed Docker build optimization
+
+## [2.9.1] - 2025-08-01
+
+...
+```
+
+## Version Strategy
+
+### Semantic Versioning
+- **MAJOR** (X.0.0): Breaking changes
+- **MINOR** (X.Y.0): New features, backward compatible
+- **PATCH** (X.Y.Z): Bug fixes, backward compatible
+
+### Prerelease Versions
+- **Alpha**: `X.Y.Z-alpha.N` - Early development
+- **Beta**: `X.Y.Z-beta.N` - Feature complete, testing
+- **RC**: `X.Y.Z-rc.N` - Release candidate
+
+Prerelease versions are automatically detected and marked appropriately.
+
+## Best Practices
+
+### Before Releasing
+1. ✅ Run `npm run test:release-automation`
+2. ✅ Update changelog with meaningful descriptions
+3. ✅ Test locally with `npm test && npm run build`
+4. ✅ Review breaking changes
+5. ✅ Consider impact on users
+
+### Version Bumping
+- Use `npm run prepare:release` for guided process
+- Follow semantic versioning strictly
+- Document breaking changes clearly
+- Consider backward compatibility
+
+### Changelog Writing
+- Be specific about changes
+- Include migration notes for breaking changes
+- Credit contributors
+- Use consistent formatting
+
+## Contributing
+
+### For Maintainers
+1. Use automated tools: `npm run prepare:release`
+2. Follow semantic versioning
+3. Update changelog thoroughly
+4. Test before releasing
+
+### For Contributors
+- Breaking changes require MAJOR version bump
+- New features require MINOR version bump
+- Bug fixes require PATCH version bump
+- Update changelog in PR descriptions
+
+---
+
+🤖 *This automated release system was designed with [Claude Code](https://claude.ai/code)*

docs/BENCHMARKS.md

@@ -0,0 +1,185 @@
+# n8n-mcp Performance Benchmarks
+
+## Overview
+
+The n8n-mcp project includes comprehensive performance benchmarks to ensure optimal performance across all critical operations. These benchmarks help identify performance regressions and guide optimization efforts.
+
+## Running Benchmarks
+
+### Local Development
+
+```bash
+# Run all benchmarks
+npm run benchmark
+
+# Run in watch mode
+npm run benchmark:watch
+
+# Run with UI
+npm run benchmark:ui
+
+# Run specific benchmark suite
+npm run benchmark tests/benchmarks/node-loading.bench.ts
+```
+
+### Continuous Integration
+
+Benchmarks run automatically on:
+- Every push to `main` branch
+- Every pull request
+- Manual workflow dispatch
+
+Results are:
+- Tracked over time using GitHub Actions
+- Displayed in PR comments
+- Available at: https://czlonkowski.github.io/n8n-mcp/benchmarks/
+
+## Benchmark Suites
+
+### 1. Node Loading Performance
+Tests the performance of loading n8n node packages and parsing their metadata.
+
+**Key Metrics:**
+- Package loading time (< 100ms target)
+- Individual node file loading (< 5ms target)
+- Package.json parsing (< 1ms target)
+
+### 2. Database Query Performance
+Measures database operation performance including queries, inserts, and updates.
+
+**Key Metrics:**
+- Node retrieval by type (< 5ms target)
+- Search operations (< 50ms target)
+- Bulk operations (< 100ms target)
+
+### 3. Search Operations
+Tests various search modes and their performance characteristics.
+
+**Key Metrics:**
+- Simple word search (< 10ms target)
+- Multi-word OR search (< 20ms target)
+- Fuzzy search (< 50ms target)
+
+### 4. Validation Performance
+Measures configuration and workflow validation speed.
+
+**Key Metrics:**
+- Simple config validation (< 1ms target)
+- Complex config validation (< 10ms target)
+- Workflow validation (< 50ms target)
+
+### 5. MCP Tool Execution
+Tests the overhead of MCP tool execution.
+
+**Key Metrics:**
+- Tool invocation overhead (< 5ms target)
+- Complex tool operations (< 50ms target)
+
+## Performance Targets
+
+| Operation Category | Target | Warning | Critical |
+|-------------------|--------|---------|----------|
+| Node Loading | < 100ms | > 150ms | > 200ms |
+| Database Query | < 5ms | > 10ms | > 20ms |
+| Search (simple) | < 10ms | > 20ms | > 50ms |
+| Search (complex) | < 50ms | > 100ms | > 200ms |
+| Validation | < 10ms | > 20ms | > 50ms |
+| MCP Tools | < 50ms | > 100ms | > 200ms |
+
+## Optimization Guidelines
+
+### Current Optimizations
+
+1. **In-memory caching**: Frequently accessed nodes are cached
+2. **Indexed database**: Key fields are indexed for fast lookups
+3. **Lazy loading**: Large properties are loaded on demand
+4. **Batch operations**: Multiple operations are batched when possible
+
+### Future Optimizations
+
+1. **FTS5 Search**: Implement SQLite FTS5 for faster full-text search
+2. **Connection pooling**: Reuse database connections
+3. **Query optimization**: Analyze and optimize slow queries
+4. **Parallel loading**: Load multiple packages concurrently
+
+## Benchmark Implementation
+
+### Writing New Benchmarks
+
+```typescript
+import { bench, describe } from 'vitest';
+
+describe('My Performance Suite', () => {
+  bench('operation name', async () => {
+    // Code to benchmark
+  }, {
+    iterations: 100,
+    warmupIterations: 10,
+    warmupTime: 500,
+    time: 3000
+  });
+});
+```
+
+### Best Practices
+
+1. **Isolate operations**: Benchmark specific operations, not entire workflows
+2. **Use realistic data**: Load actual n8n nodes for accurate measurements
+3. **Include warmup**: Allow JIT compilation to stabilize
+4. **Consider memory**: Monitor memory usage for memory-intensive operations
+5. **Statistical significance**: Run enough iterations for reliable results
+
+## Interpreting Results
+
+### Key Metrics
+
+- **hz**: Operations per second (higher is better)
+- **mean**: Average time per operation (lower is better)
+- **p99**: 99th percentile (worst-case performance)
+- **rme**: Relative margin of error (lower is more reliable)
+
+### Performance Regression Detection
+
+A performance regression is flagged when:
+1. Operation time increases by >10% from baseline
+2. Multiple related operations show degradation
+3. P99 latency exceeds critical thresholds
+
+### Analyzing Trends
+
+1. **Gradual degradation**: Often indicates growing technical debt
+2. **Sudden spikes**: Usually from specific code changes
+3. **Seasonal patterns**: May indicate cache effectiveness
+4. **Outliers**: Check p99 vs mean for consistency
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Inconsistent results**: Increase warmup iterations
+2. **High variance**: Check for background processes
+3. **Memory issues**: Reduce iteration count
+4. **CI failures**: Verify runner resources
+
+### Performance Debugging
+
+1. Use `--reporter=verbose` for detailed output
+2. Profile with `node --inspect` for bottlenecks
+3. Check database query plans
+4. Monitor memory allocation patterns
+
+## Contributing
+
+When submitting performance improvements:
+
+1. Run benchmarks before and after changes
+2. Include benchmark results in PR description
+3. Explain optimization approach
+4. Consider trade-offs (memory vs speed)
+5. Add new benchmarks for new features
+
+## References
+
+- [Vitest Benchmark Documentation](https://vitest.dev/guide/features.html#benchmarking)
+- [GitHub Action Benchmark](https://github.com/benchmark-action/github-action-benchmark)
+- [SQLite Performance Tuning](https://www.sqlite.org/optoverview.html)

docs/CLAUDE_CODE_SETUP.md

@@ -0,0 +1,94 @@
+# Claude Code Setup
+
+Connect n8n-MCP to Claude Code CLI for enhanced n8n workflow development from the command line.
+
+## Quick Setup via CLI
+
+### Basic configuration (documentation tools only):
+```bash
+claude mcp add n8n-mcp \
+  -e MCP_MODE=stdio \
+  -e LOG_LEVEL=error \
+  -e DISABLE_CONSOLE_OUTPUT=true \
+  -- npx n8n-mcp
+```
+
+![Adding n8n-MCP server in Claude Code](./img/cc_command.png)
+
+### Full configuration (with n8n management tools):
+```bash
+claude mcp add n8n-mcp \
+  -e MCP_MODE=stdio \
+  -e LOG_LEVEL=error \
+  -e DISABLE_CONSOLE_OUTPUT=true \
+  -e N8N_API_URL=https://your-n8n-instance.com \
+  -e N8N_API_KEY=your-api-key \
+  -- npx n8n-mcp
+```
+
+Make sure to replace `https://your-n8n-instance.com` with your actual n8n URL and `your-api-key` with your n8n API key.
+
+## Alternative Setup Methods
+
+### Option 1: Import from Claude Desktop
+
+If you already have n8n-MCP configured in Claude Desktop:
+```bash
+claude mcp add-from-claude-desktop
+```
+
+### Option 2: Project Configuration
+
+For team sharing, add to `.mcp.json` in your project root:
+```json
+{
+  "mcpServers": {
+    "n8n-mcp": {
+      "command": "npx",
+      "args": ["n8n-mcp"],
+      "env": {
+        "MCP_MODE": "stdio",
+        "LOG_LEVEL": "error",
+        "DISABLE_CONSOLE_OUTPUT": "true",
+        "N8N_API_URL": "https://your-n8n-instance.com",
+        "N8N_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+Then use with scope flag:
+```bash
+claude mcp add n8n-mcp --scope project
+```
+
+## Managing Your MCP Server
+
+Check server status:
+```bash
+claude mcp list
+claude mcp get n8n-mcp
+```
+
+During a conversation, use the `/mcp` command to see server status and available tools.
+
+![n8n-MCP connected and showing 39 tools available](./img/cc_connected.png)
+
+Remove the server:
+```bash
+claude mcp remove n8n-mcp
+```
+
+## Project Instructions
+
+For optimal results, create a `CLAUDE.md` file in your project root with the instructions from the [main README's Claude Project Setup section](../README.md#-claude-project-setup).
+
+## Tips
+
+- If you're running n8n locally, use `http://localhost:5678` as the N8N_API_URL
+- The n8n API credentials are optional - without them, you'll have documentation and validation tools only
+- With API credentials, you'll get full workflow management capabilities
+- Use `--scope local` (default) to keep your API credentials private
+- Use `--scope project` to share configuration with your team (put credentials in environment variables)
+- Claude Code will automatically start the MCP server when you begin a conversation

docs/CODECOV_SETUP.md

@@ -0,0 +1,113 @@
+# Codecov Setup Guide
+
+This guide explains how to set up and configure Codecov for the n8n-MCP project.
+
+## Prerequisites
+
+1. A Codecov account (sign up at https://codecov.io)
+2. Repository admin access to add the CODECOV_TOKEN secret
+
+## Setup Steps
+
+### 1. Get Your Codecov Token
+
+1. Sign in to [Codecov](https://codecov.io)
+2. Add your repository: `czlonkowski/n8n-mcp`
+3. Copy the upload token from the repository settings
+
+### 2. Add Token to GitHub Secrets
+
+1. Go to your GitHub repository settings
+2. Navigate to `Settings` → `Secrets and variables` → `Actions`
+3. Click "New repository secret"
+4. Name: `CODECOV_TOKEN`
+5. Value: Paste your Codecov token
+6. Click "Add secret"
+
+### 3. Update the Badge Token
+
+Edit the README.md file and replace `YOUR_TOKEN` in the Codecov badge with your actual token:
+
+```markdown
+[![codecov](https://codecov.io/gh/czlonkowski/n8n-mcp/graph/badge.svg?token=YOUR_ACTUAL_TOKEN)](https://codecov.io/gh/czlonkowski/n8n-mcp)
+```
+
+Note: The token in the badge URL is a read-only token and safe to commit.
+
+## Configuration Details
+
+### codecov.yml
+
+The configuration file sets:
+- **Target coverage**: 80% for both project and patch
+- **Coverage precision**: 2 decimal places
+- **Comment behavior**: Comments on all PRs with coverage changes
+- **Ignored files**: Test files, scripts, node_modules, and build outputs
+
+### GitHub Actions
+
+The workflow:
+1. Runs tests with coverage using `npm run test:coverage`
+2. Generates LCOV format coverage report
+3. Uploads to Codecov using the official action
+4. Fails the build if upload fails
+
+### Vitest Configuration
+
+Coverage settings in `vitest.config.ts`:
+- **Provider**: V8 (fast and accurate)
+- **Reporters**: text, json, html, and lcov
+- **Thresholds**: 80% lines, 80% functions, 75% branches, 80% statements
+
+## Viewing Coverage
+
+### Local Coverage
+
+```bash
+# Generate coverage report
+npm run test:coverage
+
+# View HTML report
+open coverage/index.html
+```
+
+### Online Coverage
+
+1. Visit https://codecov.io/gh/czlonkowski/n8n-mcp
+2. View detailed reports, graphs, and file-by-file coverage
+3. Check PR comments for coverage changes
+
+## Troubleshooting
+
+### Coverage Not Uploading
+
+1. Verify CODECOV_TOKEN is set in GitHub secrets
+2. Check GitHub Actions logs for errors
+3. Ensure coverage/lcov.info is generated
+
+### Badge Not Showing
+
+1. Wait a few minutes after first upload
+2. Verify the token in the badge URL is correct
+3. Check if the repository is public/private settings match
+
+### Low Coverage Areas
+
+Current areas with lower coverage that could be improved:
+- HTTP server implementations
+- MCP index files
+- Some edge cases in validators
+
+## Best Practices
+
+1. **Write tests first**: Aim for TDD when adding features
+2. **Focus on critical paths**: Prioritize testing core functionality
+3. **Mock external dependencies**: Use MSW for HTTP, mock for databases
+4. **Keep coverage realistic**: 80% is good, 100% isn't always practical
+5. **Monitor trends**: Watch coverage over time, not just absolute numbers
+
+## Resources
+
+- [Codecov Documentation](https://docs.codecov.io/)
+- [Vitest Coverage](https://vitest.dev/guide/coverage.html)
+- [GitHub Actions + Codecov](https://github.com/codecov/codecov-action)

docs/CODEX_SETUP.md

@@ -0,0 +1,34 @@
+# Codex Setup
+
+Connect n8n-MCP to Codex for enhanced n8n workflow development.
+
+## Update your Codex configuration
+
+Go to your Codex settings at `~/.codex/config.toml` and add the following configuration:
+
+### Basic configuration (documentation tools only):
+```toml
+[mcp_servers.n8n]
+command = "npx"
+args = ["n8n-mcp"]
+env = { "MCP_MODE" = "stdio", "LOG_LEVEL" = "error", "DISABLE_CONSOLE_OUTPUT" = "true" }
+```
+
+### Full configuration (with n8n management tools):
+```toml
+[mcp_servers.n8n]
+command = "npx"
+args = ["n8n-mcp"]
+env = { "MCP_MODE" = "stdio", "LOG_LEVEL" = "error", "DISABLE_CONSOLE_OUTPUT" = "true", "N8N_API_URL" = "https://your-n8n-instance.com", "N8N_API_KEY" = "your-api-key" }
+```
+
+Make sure to replace `https://your-n8n-instance.com` with your actual n8n URL and `your-api-key` with your n8n API key.
+
+## Managing Your MCP Server
+Enter the Codex CLI and use the `/mcp` command to see server status and available tools.
+
+![n8n-MCP connected and showing 39 tools available](./img/codex_connected.png)
+
+## Project Instructions
+
+For optimal results, create a `AGENTS.md` file in your project root with the instructions same with [main README's Claude Project Setup section](../README.md#-claude-project-setup).

docs/CURSOR_SETUP.md

@@ -0,0 +1,73 @@
+# Cursor Setup
+
+Connect n8n-MCP to Cursor IDE for enhanced n8n workflow development with AI assistance.
+
+[![n8n-mcp Cursor Setup Tutorial](./img/cursor_tut.png)](https://www.youtube.com/watch?v=hRmVxzLGJWI)
+
+## Video Tutorial
+
+Watch the complete setup process: [n8n-MCP Cursor Setup Tutorial](https://www.youtube.com/watch?v=hRmVxzLGJWI)
+
+## Setup Process
+
+### 1. Create MCP Configuration
+
+1. Create a `.cursor` folder in your project root
+2. Create `mcp.json` file inside the `.cursor` folder
+3. Copy the configuration from this repository
+
+**Basic configuration (documentation tools only):**
+```json
+{
+  "mcpServers": {
+    "n8n-mcp": {
+      "command": "npx",
+      "args": ["n8n-mcp"],
+      "env": {
+        "MCP_MODE": "stdio",
+        "LOG_LEVEL": "error",
+        "DISABLE_CONSOLE_OUTPUT": "true"
+      }
+    }
+  }
+}
+```
+
+**Full configuration (with n8n management tools):**
+```json
+{
+  "mcpServers": {
+    "n8n-mcp": {
+      "command": "npx",
+      "args": ["n8n-mcp"],
+      "env": {
+        "MCP_MODE": "stdio",
+        "LOG_LEVEL": "error",
+        "DISABLE_CONSOLE_OUTPUT": "true",
+        "N8N_API_URL": "https://your-n8n-instance.com",
+        "N8N_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+### 2. Configure n8n Connection
+
+1. Replace `https://your-n8n-instance.com` with your actual n8n URL
+2. Replace `your-api-key` with your n8n API key
+
+### 3. Enable MCP Server
+
+1. Click "Enable MCP Server" button in Cursor
+2. Go to Cursor Settings
+3. Search for "mcp"
+4. Confirm MCP is working
+
+### 4. Set Up Project Instructions
+
+1. In your Cursor chat, invoke "create rule" and hit Tab
+2. Name the rule (e.g., "n8n-mcp")
+3. Set rule type to "always"
+4. Copy the Claude Project instructions from the [main README's Claude Project Setup section](../README.md#-claude-project-setup)
+

docs/DOCKER_README.md

@@ -64,9 +64,44 @@ docker run -d \
 | `PORT` | HTTP server port | `3000` | No |
 | `NODE_ENV` | Environment: `development` or `production` | `production` | No |
 | `LOG_LEVEL` | Logging level: `debug`, `info`, `warn`, `error` | `info` | No |
+| `NODE_DB_PATH` | Custom database path (v2.7.16+) | `/app/data/nodes.db` | No |
+| `AUTH_RATE_LIMIT_WINDOW` | Rate limit window in ms (v2.16.3+) | `900000` (15 min) | No |
+| `AUTH_RATE_LIMIT_MAX` | Max auth attempts per window (v2.16.3+) | `20` | No |
+| `WEBHOOK_SECURITY_MODE` | SSRF protection: `strict`/`moderate`/`permissive` (v2.16.3+) | `strict` | No |
 
 *Either `AUTH_TOKEN` or `AUTH_TOKEN_FILE` must be set for HTTP mode. If both are set, `AUTH_TOKEN` takes precedence.
 
+### Configuration File Support (v2.8.2+)
+
+You can mount a JSON configuration file to set environment variables:
+
+```bash
+# Create config file
+cat > config.json << EOF
+{
+  "MCP_MODE": "http",
+  "AUTH_TOKEN": "your-secure-token",
+  "LOG_LEVEL": "info",
+  "N8N_API_URL": "https://your-n8n-instance.com",
+  "N8N_API_KEY": "your-api-key"
+}
+EOF
+
+# Run with config file
+docker run -d \
+  --name n8n-mcp \
+  -v $(pwd)/config.json:/app/config.json:ro \
+  -p 3000:3000 \
+  ghcr.io/czlonkowski/n8n-mcp:latest
+```
+
+The config file supports:
+- All standard environment variables
+- Nested objects (flattened with underscore separators)
+- Arrays, booleans, numbers, and strings
+- Secure handling with command injection prevention
+- Dangerous variable blocking for security
+
 ### Docker Compose Configuration
 
 The default `docker-compose.yml` provides:
@@ -135,12 +170,25 @@ For local Claude Desktop integration without HTTP:
 
 ```bash
 # Run in stdio mode (interactive)
-docker run --rm -i \
+docker run --rm -i --init \
   -e MCP_MODE=stdio \
   -v n8n-mcp-data:/app/data \
   ghcr.io/czlonkowski/n8n-mcp:latest
 ```
 
+### Server Mode (Command Line)
+
+You can also use the `serve` command to start in HTTP mode:
+
+```bash
+# Using the serve command (v2.8.2+)
+docker run -d \
+  --name n8n-mcp \
+  -e AUTH_TOKEN=your-secure-token \
+  -p 3000:3000 \
+  ghcr.io/czlonkowski/n8n-mcp:latest serve
+```
+
 Configure Claude Desktop:
 ```json
 {
@@ -151,6 +199,7 @@ Configure Claude Desktop:
         "run",
         "--rm",
         "-i",
+        "--init",
         "-e", "MCP_MODE=stdio",
         "-v", "n8n-mcp-data:/app/data",
         "ghcr.io/czlonkowski/n8n-mcp:latest"
@@ -237,7 +286,36 @@ docker ps --format "table {{.Names}}\t{{.Status}}"
 docker inspect n8n-mcp | jq '.[0].State.Health'
 ```
 
-## 🔒 Security Considerations
+## 🔒 Security Features (v2.16.3+)
+
+### Rate Limiting
+
+Protects against brute force authentication attacks:
+
+```bash
+# Configure in .env or docker-compose.yml
+AUTH_RATE_LIMIT_WINDOW=900000  # 15 minutes in milliseconds
+AUTH_RATE_LIMIT_MAX=20         # 20 attempts per IP per window
+```
+
+### SSRF Protection
+
+Prevents Server-Side Request Forgery when using webhook triggers:
+
+```bash
+# For production (blocks localhost + private IPs + cloud metadata)
+WEBHOOK_SECURITY_MODE=strict
+
+# For local development with local n8n instance
+WEBHOOK_SECURITY_MODE=moderate
+
+# For internal testing only (allows private IPs)
+WEBHOOK_SECURITY_MODE=permissive
+```
+
+**Note:** Cloud metadata endpoints (169.254.169.254, metadata.google.internal, etc.) are ALWAYS blocked in all modes.
+
+## 🔒 Authentication
 
 ### Authentication
 
@@ -342,6 +420,28 @@ docker run --rm \
   alpine tar xzf /backup/n8n-mcp-backup.tar.gz -C /target
 ```
 
+### Custom Database Path (v2.7.16+)
+
+You can specify a custom database location using `NODE_DB_PATH`:
+
+```bash
+# Use custom path within mounted volume
+docker run -d \
+  --name n8n-mcp \
+  -e MCP_MODE=http \
+  -e AUTH_TOKEN=your-token \
+  -e NODE_DB_PATH=/app/data/custom/my-nodes.db \
+  -v n8n-mcp-data:/app/data \
+  -p 3000:3000 \
+  ghcr.io/czlonkowski/n8n-mcp:latest
+```
+
+**Important Notes:**
+- The path must end with `.db`
+- For data persistence, ensure the path is within a mounted volume
+- Paths outside mounted volumes will be lost on container restart
+- The directory will be created automatically if it doesn't exist
+
 ## 🐛 Troubleshooting
 
 ### Common Issues
@@ -458,7 +558,7 @@ secrets:
 
 ### Image Details
 
-- Base: `node:20-alpine`
+- Base: `node:22-alpine`
 - Size: ~280MB compressed
 - Features: Pre-built database with all node information
 - Database: Complete SQLite with 525+ nodes
@@ -506,4 +606,4 @@ services:
 
 ---
 
-*Last updated: June 2025 - Docker implementation v1.0*
+*Last updated: July 2025 - Docker implementation v1.1*

docs/DOCKER_TROUBLESHOOTING.md

@@ -0,0 +1,422 @@
+# Docker Troubleshooting Guide
+
+This guide helps resolve common issues when running n8n-mcp with Docker, especially when connecting to n8n instances.
+
+## Table of Contents
+- [Common Issues](#common-issues)
+  - [502 Bad Gateway Errors](#502-bad-gateway-errors)
+  - [Custom Database Path Not Working](#custom-database-path-not-working-v27160)
+  - [Container Name Conflicts](#container-name-conflicts)
+  - [n8n API Connection Issues](#n8n-api-connection-issues)
+- [Docker Networking](#docker-networking)
+- [Quick Solutions](#quick-solutions)
+- [Debugging Steps](#debugging-steps)
+
+## Common Issues
+
+### Docker Configuration File Not Working (v2.8.2+)
+
+**Symptoms:**
+- Config file mounted but environment variables not set
+- Container starts but ignores configuration
+- Getting "permission denied" errors
+
+**Solutions:**
+
+1. **Ensure file is mounted correctly:**
+```bash
+# Correct - mount as read-only
+docker run -v $(pwd)/config.json:/app/config.json:ro ...
+
+# Check if file is accessible
+docker exec n8n-mcp cat /app/config.json
+```
+
+2. **Verify JSON syntax:**
+```bash
+# Validate JSON file
+cat config.json | jq .
+```
+
+3. **Check Docker logs for parsing errors:**
+```bash
+docker logs n8n-mcp | grep -i config
+```
+
+4. **Common issues:**
+- Invalid JSON syntax (use a JSON validator)
+- File permissions (should be readable)
+- Wrong mount path (must be `/app/config.json`)
+- Dangerous variables blocked (PATH, LD_PRELOAD, etc.)
+
+### Custom Database Path Not Working (v2.7.16+)
+
+**Symptoms:**
+- `NODE_DB_PATH` environment variable is set but ignored
+- Database always created at `/app/data/nodes.db`
+- Custom path setting has no effect
+
+**Root Cause:** Fixed in v2.7.16. Earlier versions had hardcoded paths in docker-entrypoint.sh.
+
+**Solutions:**
+
+1. **Update to v2.7.16 or later:**
+```bash
+docker pull ghcr.io/czlonkowski/n8n-mcp:latest
+```
+
+2. **Ensure path ends with .db:**
+```bash
+# Correct
+NODE_DB_PATH=/app/data/custom/my-nodes.db
+
+# Incorrect (will be rejected)
+NODE_DB_PATH=/app/data/custom/my-nodes
+```
+
+3. **Use path within mounted volume for persistence:**
+```yaml
+services:
+  n8n-mcp:
+    environment:
+      NODE_DB_PATH: /app/data/custom/nodes.db
+    volumes:
+      - n8n-mcp-data:/app/data  # Ensure parent directory is mounted
+```
+
+### 502 Bad Gateway Errors
+
+**Symptoms:**
+- `n8n_health_check` returns 502 error
+- All n8n management API calls fail
+- n8n web UI is accessible but API is not
+
+**Root Cause:** Network connectivity issues between n8n-mcp container and n8n instance.
+
+**Solutions:**
+
+#### 1. When n8n runs in Docker on same machine
+
+Use Docker's special hostnames instead of `localhost`:
+
+```json
+{
+  "mcpServers": {
+    "n8n-mcp": {
+      "command": "docker",
+      "args": [
+        "run", "-i", "--rm",
+        "-e", "N8N_API_URL=http://host.docker.internal:5678",
+        "-e", "N8N_API_KEY=your-api-key",
+        "ghcr.io/czlonkowski/n8n-mcp:latest"
+      ]
+    }
+  }
+}
+```
+
+**Alternative hostnames to try:**
+- `host.docker.internal` (Docker Desktop on macOS/Windows)
+- `172.17.0.1` (Default Docker bridge IP on Linux)
+- Your machine's actual IP address (e.g., `192.168.1.100`)
+
+#### 2. When both containers are in same Docker network
+
+```bash
+# Create a shared network
+docker network create n8n-network
+
+# Run n8n in the network
+docker run -d --name n8n --network n8n-network -p 5678:5678 n8nio/n8n
+
+# Configure n8n-mcp to use container name
+```
+
+```json
+{
+  "N8N_API_URL": "http://n8n:5678"
+}
+```
+
+#### 3. For Docker Compose setups
+
+```yaml
+# docker-compose.yml
+services:
+  n8n:
+    image: n8nio/n8n
+    container_name: n8n
+    networks:
+      - n8n-net
+    ports:
+      - "5678:5678"
+  
+  n8n-mcp:
+    image: ghcr.io/czlonkowski/n8n-mcp:latest
+    environment:
+      N8N_API_URL: http://n8n:5678
+      N8N_API_KEY: ${N8N_API_KEY}
+    networks:
+      - n8n-net
+
+networks:
+  n8n-net:
+    driver: bridge
+```
+
+### Container Cleanup Issues (Fixed in v2.7.20+)
+
+**Symptoms:**
+- Containers accumulate after Claude Desktop restarts
+- Containers show as "unhealthy" but don't clean up
+- `--rm` flag doesn't work as expected
+
+**Root Cause:** Fixed in v2.7.20 - containers weren't handling termination signals properly.
+
+**Solutions:**
+
+1. **Update to v2.7.20+ and use --init flag (Recommended):**
+```json
+{
+  "command": "docker",
+  "args": [
+    "run", "-i", "--rm", "--init",
+    "ghcr.io/czlonkowski/n8n-mcp:latest"
+  ]
+}
+```
+
+2. **Manual cleanup of old containers:**
+```bash
+# Remove all stopped n8n-mcp containers
+docker ps -a | grep n8n-mcp | grep Exited | awk '{print $1}' | xargs -r docker rm
+```
+
+3. **For versions before 2.7.20:**
+- Manually clean up containers periodically
+- Consider using HTTP mode instead
+
+### Webhooks to Local n8n Fail (v2.16.3+)
+
+**Symptoms:**
+- `n8n_trigger_webhook_workflow` fails with "SSRF protection" error
+- Error message: "SSRF protection: Localhost access is blocked"
+- Webhooks work from n8n UI but not from n8n-MCP
+
+**Root Cause:** Default strict SSRF protection blocks localhost access to prevent attacks.
+
+**Solution:** Use moderate security mode for local development
+
+```bash
+# For Docker run
+docker run -d \
+  --name n8n-mcp \
+  -e MCP_MODE=http \
+  -e AUTH_TOKEN=your-token \
+  -e WEBHOOK_SECURITY_MODE=moderate \
+  -p 3000:3000 \
+  ghcr.io/czlonkowski/n8n-mcp:latest
+
+# For Docker Compose - add to environment:
+services:
+  n8n-mcp:
+    environment:
+      WEBHOOK_SECURITY_MODE: moderate
+```
+
+**Security Modes Explained:**
+- `strict` (default): Blocks localhost + private IPs + cloud metadata (production)
+- `moderate`: Allows localhost, blocks private IPs + cloud metadata (local development)
+- `permissive`: Allows localhost + private IPs, blocks cloud metadata (testing only)
+
+**Important:** Always use `strict` mode in production. Cloud metadata is blocked in all modes.
+
+### n8n API Connection Issues
+
+**Symptoms:**
+- API calls fail but n8n web UI works
+- Authentication errors
+- API endpoints return 404
+
+**Solutions:**
+
+1. **Verify n8n API is enabled:**
+   - Check n8n settings → REST API is enabled
+   - Ensure API key is valid and not expired
+
+2. **Test API directly:**
+```bash
+# From host machine
+curl -H "X-N8N-API-KEY: your-key" http://localhost:5678/api/v1/workflows
+
+# From inside Docker container
+docker run --rm curlimages/curl \
+  -H "X-N8N-API-KEY: your-key" \
+  http://host.docker.internal:5678/api/v1/workflows
+```
+
+3. **Check n8n environment variables:**
+```yaml
+environment:
+  - N8N_BASIC_AUTH_ACTIVE=true
+  - N8N_BASIC_AUTH_USER=user
+  - N8N_BASIC_AUTH_PASSWORD=password
+```
+
+## Docker Networking
+
+### Understanding Docker Network Modes
+
+| Scenario | Use This URL | Why |
+|----------|--------------|-----|
+| n8n on host, n8n-mcp in Docker | `http://host.docker.internal:5678` | Docker can't reach host's localhost |
+| Both in same Docker network | `http://container-name:5678` | Direct container-to-container |
+| n8n behind reverse proxy | `http://your-domain.com` | Use public URL |
+| Local development | `http://YOUR_LOCAL_IP:5678` | Use machine's IP address |
+
+### Finding Your Configuration
+
+```bash
+# Check if n8n is running in Docker
+docker ps | grep n8n
+
+# Find Docker network
+docker network ls
+
+# Get container details
+docker inspect n8n | grep NetworkMode
+
+# Find your local IP
+# macOS/Linux
+ifconfig | grep "inet " | grep -v 127.0.0.1
+
+# Windows
+ipconfig | findstr IPv4
+```
+
+## Quick Solutions
+
+### Solution 1: Use Host Network (Linux only)
+```json
+{
+  "command": "docker",
+  "args": [
+    "run", "-i", "--rm",
+    "--network", "host",
+    "-e", "N8N_API_URL=http://localhost:5678",
+    "ghcr.io/czlonkowski/n8n-mcp:latest"
+  ]
+}
+```
+
+### Solution 2: Use Your Machine's IP
+```json
+{
+  "N8N_API_URL": "http://192.168.1.100:5678"  // Replace with your IP
+}
+```
+
+### Solution 3: HTTP Mode Deployment
+Deploy n8n-mcp as HTTP server to avoid stdio/Docker issues:
+
+```bash
+# Start HTTP server
+docker run -d \
+  -p 3000:3000 \
+  -e MCP_MODE=http \
+  -e AUTH_TOKEN=your-token \
+  -e N8N_API_URL=http://host.docker.internal:5678 \
+  -e N8N_API_KEY=your-n8n-key \
+  ghcr.io/czlonkowski/n8n-mcp:latest
+
+# Configure Claude with mcp-remote
+```
+
+## Debugging Steps
+
+### 1. Enable Debug Logging
+```json
+{
+  "env": {
+    "LOG_LEVEL": "debug",
+    "DEBUG_MCP": "true"
+  }
+}
+```
+
+### 2. Test Connectivity
+```bash
+# Test from n8n-mcp container
+docker run --rm ghcr.io/czlonkowski/n8n-mcp:latest \
+  sh -c "apk add curl && curl -v http://host.docker.internal:5678/api/v1/workflows"
+```
+
+### 3. Check Docker Logs
+```bash
+# View n8n-mcp logs
+docker logs $(docker ps -q -f ancestor=ghcr.io/czlonkowski/n8n-mcp:latest)
+
+# View n8n logs
+docker logs n8n
+```
+
+### 4. Validate Environment
+```bash
+# Check what n8n-mcp sees
+docker run --rm ghcr.io/czlonkowski/n8n-mcp:latest \
+  sh -c "env | grep N8N"
+```
+
+### 5. Network Diagnostics
+```bash
+# Check Docker networks
+docker network inspect bridge
+
+# Test DNS resolution
+docker run --rm busybox nslookup host.docker.internal
+```
+
+## Platform-Specific Notes
+
+### Docker Desktop (macOS/Windows)
+- `host.docker.internal` works out of the box
+- Ensure Docker Desktop is running
+- Check Docker Desktop settings → Resources → Network
+
+### Linux
+- `host.docker.internal` requires Docker 20.10+
+- Alternative: Use `--add-host=host.docker.internal:host-gateway`
+- Or use the Docker bridge IP: `172.17.0.1`
+
+### Windows with WSL2
+- Use `host.docker.internal` or WSL2 IP
+- Check firewall rules for port 5678
+- Ensure n8n binds to `0.0.0.0` not `127.0.0.1`
+
+## Still Having Issues?
+
+1. **Check n8n logs** for API-related errors
+2. **Verify firewall/security** isn't blocking connections
+3. **Try simpler setup** - Run n8n-mcp on host instead of Docker
+4. **Report issue** with debug logs at [GitHub Issues](https://github.com/czlonkowski/n8n-mcp/issues)
+
+## Useful Commands
+
+```bash
+# Remove all n8n-mcp containers
+docker rm -f $(docker ps -aq -f ancestor=ghcr.io/czlonkowski/n8n-mcp:latest)
+
+# Test n8n API with curl
+curl -H "X-N8N-API-KEY: your-key" http://localhost:5678/api/v1/workflows
+
+# Run interactive debug session
+docker run -it --rm \
+  -e LOG_LEVEL=debug \
+  -e N8N_API_URL=http://host.docker.internal:5678 \
+  -e N8N_API_KEY=your-key \
+  ghcr.io/czlonkowski/n8n-mcp:latest \
+  sh
+
+# Check container networking
+docker run --rm alpine ping -c 4 host.docker.internal
+```

docs/FLEXIBLE_INSTANCE_CONFIGURATION.md

@@ -0,0 +1,371 @@
+# Flexible Instance Configuration
+
+## Overview
+
+The Flexible Instance Configuration feature enables n8n-mcp to serve multiple users with different n8n instances dynamically, without requiring separate deployments for each user. This feature is designed for scenarios where n8n-mcp is hosted centrally and needs to connect to different n8n instances based on runtime context.
+
+## Architecture
+
+### Core Components
+
+1. **InstanceContext Interface** (`src/types/instance-context.ts`)
+   - Runtime configuration container for instance-specific settings
+   - Optional fields for backward compatibility
+   - Comprehensive validation with security checks
+
+2. **Dual-Mode API Client**
+   - **Singleton Mode**: Uses environment variables (backward compatible)
+   - **Instance Mode**: Uses runtime context for multi-instance support
+   - Automatic fallback between modes
+
+3. **LRU Cache with Security**
+   - SHA-256 hashed cache keys for security
+   - 30-minute TTL with automatic cleanup
+   - Maximum 100 concurrent instances
+   - Secure dispose callbacks without logging sensitive data
+
+4. **Session Management**
+   - HTTP server tracks session context
+   - Each session can have different instance configuration
+   - Automatic cleanup on session end
+
+## Configuration
+
+### Environment Variables
+
+New environment variables for cache configuration:
+
+- `INSTANCE_CACHE_MAX` - Maximum number of cached instances (default: 100, min: 1, max: 10000)
+- `INSTANCE_CACHE_TTL_MINUTES` - Cache TTL in minutes (default: 30, min: 1, max: 1440/24 hours)
+
+Example:
+```bash
+# Increase cache size for high-volume deployments
+export INSTANCE_CACHE_MAX=500
+export INSTANCE_CACHE_TTL_MINUTES=60
+```
+
+### InstanceContext Structure
+
+```typescript
+interface InstanceContext {
+  n8nApiUrl?: string;        // n8n instance URL
+  n8nApiKey?: string;        // API key for authentication
+  n8nApiTimeout?: number;    // Request timeout in ms (default: 30000)
+  n8nApiMaxRetries?: number; // Max retry attempts (default: 3)
+  instanceId?: string;       // Unique instance identifier
+  sessionId?: string;        // Session identifier
+  metadata?: Record<string, any>; // Additional metadata
+}
+```
+
+### Validation Rules
+
+1. **URL Validation**:
+   - Must be valid HTTP/HTTPS URL
+   - No file://, javascript:, or other dangerous protocols
+   - Proper URL format with protocol and host
+
+2. **API Key Validation**:
+   - Non-empty string required when provided
+   - No placeholder values (e.g., "YOUR_API_KEY")
+   - Case-insensitive placeholder detection
+
+3. **Numeric Validation**:
+   - Timeout must be positive number (>0)
+   - Max retries must be non-negative (≥0)
+   - No Infinity or NaN values
+
+## Usage Examples
+
+### Basic Usage
+
+```typescript
+import { getN8nApiClient } from './mcp/handlers-n8n-manager';
+import { InstanceContext } from './types/instance-context';
+
+// Create context for a specific instance
+const context: InstanceContext = {
+  n8nApiUrl: 'https://customer1.n8n.cloud',
+  n8nApiKey: 'customer1-api-key',
+  instanceId: 'customer1'
+};
+
+// Get client for this instance
+const client = getN8nApiClient(context);
+if (client) {
+  // Use client for API operations
+  const workflows = await client.getWorkflows();
+}
+```
+
+### HTTP Headers for Multi-Tenant Support
+
+When using the HTTP server mode, clients can pass instance-specific configuration via HTTP headers:
+
+```bash
+# Example curl request with instance headers
+curl -X POST http://localhost:3000/mcp \
+  -H "Authorization: Bearer your-auth-token" \
+  -H "Content-Type: application/json" \
+  -H "X-N8n-Url: https://instance1.n8n.cloud" \
+  -H "X-N8n-Key: instance1-api-key" \
+  -H "X-Instance-Id: instance-1" \
+  -H "X-Session-Id: session-123" \
+  -d '{"method": "n8n_list_workflows", "params": {}, "id": 1}'
+```
+
+#### Supported Headers
+
+- **X-N8n-Url**: The n8n instance URL (e.g., `https://instance.n8n.cloud`)
+- **X-N8n-Key**: The API key for authentication with the n8n instance
+- **X-Instance-Id**: A unique identifier for the instance (optional, for tracking)
+- **X-Session-Id**: A session identifier (optional, for session tracking)
+
+#### Header Extraction Logic
+
+1. If either `X-N8n-Url` or `X-N8n-Key` header is present, an instance context is created
+2. All headers are extracted and passed to the MCP server
+3. The server uses the instance-specific configuration instead of environment variables
+4. If no headers are present, the server falls back to environment variables (backward compatible)
+
+#### Example: JavaScript Client
+
+```javascript
+const headers = {
+  'Authorization': 'Bearer your-auth-token',
+  'Content-Type': 'application/json',
+  'X-N8n-Url': 'https://customer1.n8n.cloud',
+  'X-N8n-Key': 'customer1-api-key',
+  'X-Instance-Id': 'customer-1',
+  'X-Session-Id': 'session-456'
+};
+
+const response = await fetch('http://localhost:3000/mcp', {
+  method: 'POST',
+  headers: headers,
+  body: JSON.stringify({
+    method: 'n8n_list_workflows',
+    params: {},
+    id: 1
+  })
+});
+
+const result = await response.json();
+```
+
+### HTTP Server Integration
+
+```typescript
+// In HTTP request handler
+app.post('/mcp', (req, res) => {
+  const context: InstanceContext = {
+    n8nApiUrl: req.headers['x-n8n-url'],
+    n8nApiKey: req.headers['x-n8n-key'],
+    sessionId: req.sessionID
+  };
+
+  // Context passed to handlers
+  const result = await handleRequest(req.body, context);
+  res.json(result);
+});
+```
+
+### Validation Example
+
+```typescript
+import { validateInstanceContext } from './types/instance-context';
+
+const context: InstanceContext = {
+  n8nApiUrl: 'https://api.n8n.cloud',
+  n8nApiKey: 'valid-key'
+};
+
+const validation = validateInstanceContext(context);
+if (!validation.valid) {
+  console.error('Validation errors:', validation.errors);
+} else {
+  // Context is valid, proceed
+  const client = getN8nApiClient(context);
+}
+```
+
+## Security Features
+
+### 1. Cache Key Hashing
+- All cache keys use SHA-256 hashing with memoization
+- Prevents sensitive data exposure in logs
+- Example: `sha256(url:key:instance)` → 64-char hex string
+- Memoization cache limited to 1000 entries
+
+### 2. Enhanced Input Validation
+- Field-specific error messages with detailed reasons
+- URL protocol restrictions (HTTP/HTTPS only)
+- API key placeholder detection (case-insensitive)
+- Numeric range validation with specific error messages
+- Example: "Invalid n8nApiUrl: ftp://example.com - URL must use HTTP or HTTPS protocol"
+
+### 3. Secure Logging
+- Only first 8 characters of cache keys logged
+- No sensitive data in debug logs
+- URL sanitization (domain only, no paths)
+- Configuration fallback logging for debugging
+
+### 4. Memory Management
+- Configurable LRU cache with automatic eviction
+- TTL-based expiration (configurable, default 30 minutes)
+- Dispose callbacks for cleanup
+- Maximum cache size limits with bounds checking
+
+### 5. Concurrency Protection
+- Mutex-based locking for cache operations
+- Prevents duplicate client creation
+- Simple lock checking with timeout
+- Thread-safe cache operations
+
+## Performance Optimization
+
+### Cache Strategy
+- **Max Size**: Configurable via `INSTANCE_CACHE_MAX` (default: 100)
+- **TTL**: Configurable via `INSTANCE_CACHE_TTL_MINUTES` (default: 30)
+- **Update on Access**: Age refreshed on each use
+- **Eviction**: Least Recently Used (LRU) policy
+- **Memoization**: Hash creation uses memoization for frequently used keys
+
+### Cache Metrics
+The system tracks comprehensive metrics:
+- Cache hits and misses
+- Hit rate percentage
+- Eviction count
+- Current size vs maximum size
+- Operation timing
+
+Retrieve metrics using:
+```typescript
+import { getInstanceCacheStatistics } from './mcp/handlers-n8n-manager';
+console.log(getInstanceCacheStatistics());
+```
+
+### Benefits
+- **Performance**: ~12ms average response time
+- **Memory Efficient**: Minimal footprint per instance
+- **Thread Safe**: Mutex protection for concurrent operations
+- **Auto Cleanup**: Unused instances automatically evicted
+- **No Memory Leaks**: Proper disposal callbacks
+
+## Backward Compatibility
+
+The feature maintains 100% backward compatibility:
+
+1. **Environment Variables Still Work**:
+   - If no context provided, falls back to env vars
+   - Existing deployments continue working unchanged
+
+2. **Optional Parameters**:
+   - All context fields are optional
+   - Missing fields use defaults or env vars
+
+3. **API Unchanged**:
+   - Same handler signatures with optional context
+   - No breaking changes to existing code
+
+## Testing
+
+Comprehensive test coverage ensures reliability:
+
+```bash
+# Run all flexible instance tests
+npm test -- tests/unit/flexible-instance-security-advanced.test.ts
+npm test -- tests/unit/mcp/lru-cache-behavior.test.ts
+npm test -- tests/unit/types/instance-context-coverage.test.ts
+npm test -- tests/unit/mcp/handlers-n8n-manager-simple.test.ts
+```
+
+### Test Coverage Areas
+- Input validation edge cases
+- Cache behavior and eviction
+- Security (hashing, sanitization)
+- Session management
+- Memory leak prevention
+- Concurrent access patterns
+
+## Migration Guide
+
+### For Existing Deployments
+No changes required - environment variables continue to work.
+
+### For Multi-Instance Support
+
+1. **Update HTTP Server** (if using HTTP mode):
+```typescript
+// Add context extraction from headers
+const context = extractInstanceContext(req);
+```
+
+2. **Pass Context to Handlers**:
+```typescript
+// Old way (still works)
+await handleListWorkflows(params);
+
+// New way (with instance context)
+await handleListWorkflows(params, context);
+```
+
+3. **Configure Clients** to send instance information:
+```typescript
+// Client sends instance info in headers
+headers: {
+  'X-N8n-Url': 'https://instance.n8n.cloud',
+  'X-N8n-Key': 'api-key',
+  'X-Instance-Id': 'customer-123'
+}
+```
+
+## Monitoring
+
+### Metrics to Track
+- Cache hit/miss ratio
+- Instance count in cache
+- Average TTL utilization
+- Memory usage per instance
+- API client creation rate
+
+### Debug Logging
+Enable debug logs to monitor cache behavior:
+```bash
+LOG_LEVEL=debug npm start
+```
+
+## Limitations
+
+1. **Maximum Instances**: 100 concurrent instances (configurable)
+2. **TTL**: 30-minute cache lifetime (configurable)
+3. **Memory**: ~1MB per cached instance (estimated)
+4. **Validation**: Strict validation may reject edge cases
+
+## Security Considerations
+
+1. **Never Log Sensitive Data**: API keys are never logged
+2. **Hash All Identifiers**: Use SHA-256 for cache keys
+3. **Validate All Input**: Comprehensive validation before use
+4. **Limit Resources**: Cache size and TTL limits
+5. **Clean Up Properly**: Dispose callbacks for resource cleanup
+
+## Future Enhancements
+
+Potential improvements for future versions:
+
+1. **Configurable Cache Settings**: Runtime cache size/TTL configuration
+2. **Instance Metrics**: Per-instance usage tracking
+3. **Rate Limiting**: Per-instance rate limits
+4. **Instance Groups**: Logical grouping of instances
+5. **Persistent Cache**: Optional Redis/database backing
+6. **Instance Discovery**: Automatic instance detection
+
+## Support
+
+For issues or questions about flexible instance configuration:
+1. Check validation errors for specific problems
+2. Enable debug logging for detailed diagnostics
+3. Review test files for usage examples
+4. Open an issue on GitHub with details

docs/HTTP_DEPLOYMENT.md

@@ -1,18 +1,16 @@
 # HTTP Deployment Guide for n8n-MCP
 
-Deploy n8n-MCP as a remote HTTP server to provide n8n knowledge to Claude from anywhere.
-
-📌 **Latest Version**: v2.7.6 (includes trust proxy support for correct IP logging behind reverse proxies)
+Deploy n8n-MCP as a remote HTTP server to provide n8n knowledge to compatible MCP Client from anywhere.
 
 ## 🎯 Overview
 
 n8n-MCP HTTP mode enables:
 - ☁️ Cloud deployment (VPS, Docker, Kubernetes)
-- 🌐 Remote access from any Claude Desktop client
+- 🌐 Remote access from any Claude Desktop /Windsurf / other MCP Client 
 - 🔒 Token-based authentication
 - ⚡ Production-ready performance (~12ms response time)
-- 🔧 Fixed implementation (v2.3.2) for stability
 - 🚀 Optional n8n management tools (16 additional tools when configured)
+- ❌ Does not work with n8n MCP Tool
 
 ## 📐 Deployment Scenarios
 
@@ -45,8 +43,8 @@ Claude Desktop → mcp-remote → https://your-server.com
 - ✅ Team collaboration
 - ✅ Production-ready
 - ❌ Requires server setup
+- Deploy to your VPS - if you just want remote acces, consider deploying to Railway -> [Railway Deployment Guide](./RAILWAY_DEPLOYMENT.md)
 
-⚠️ **Experimental Feature**: Remote server deployment has not been thoroughly tested. If you encounter any issues, please [open an issue](https://github.com/czlonkowski/n8n-mcp/issues) on GitHub.
 
 ## 📋 Prerequisites
 
@@ -75,6 +73,13 @@ PORT=3000
 # Optional: Enable n8n management tools
 # N8N_API_URL=https://your-n8n-instance.com
 # N8N_API_KEY=your-api-key-here
+# Security Configuration (v2.16.3+)
+# Rate limiting (default: 20 attempts per 15 minutes)
+AUTH_RATE_LIMIT_WINDOW=900000
+AUTH_RATE_LIMIT_MAX=20
+# SSRF protection mode (default: strict)
+# Use 'moderate' for local n8n, 'strict' for production
+WEBHOOK_SECURITY_MODE=strict
 EOF
 
 # 2. Deploy with Docker
@@ -139,18 +144,22 @@ Skip HTTP entirely and use stdio mode directly:
 | Variable | Description | Example |
 |----------|-------------|------|
 | `MCP_MODE` | Must be set to `http` | `http` |
-| `USE_FIXED_HTTP` | **Important**: Set to `true` for v2.3.2 fixes | `true` |
-| `AUTH_TOKEN` | Secure token (32+ characters) | `generated-token` |
+| `USE_FIXED_HTTP` | **Important**: Set to `true` for stable implementation | `true` |
+| `AUTH_TOKEN` or `AUTH_TOKEN_FILE` | Authentication method | See security section |
 
 ### Optional Settings
 
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `PORT` | Server port | `3000` |
-| `HOST` | Bind address | `0.0.0.0` |
-| `LOG_LEVEL` | Log verbosity | `info` |
-| `NODE_ENV` | Environment | `production` |
-| `TRUST_PROXY` | Trust proxy headers for correct IP logging | `0` |
+| Variable | Description | Default | Since |
+|----------|-------------|---------|-------|
+| `PORT` | Server port | `3000` | v1.0 |
+| `HOST` | Bind address | `0.0.0.0` | v1.0 |
+| `LOG_LEVEL` | Log verbosity (error/warn/info/debug) | `info` | v1.0 |
+| `NODE_ENV` | Environment | `production` | v1.0 |
+| `TRUST_PROXY` | Trust proxy headers (0=off, 1+=hops) | `0` | v2.7.6 |
+| `BASE_URL` | Explicit public URL | Auto-detected | v2.7.14 |
+| `PUBLIC_URL` | Alternative to BASE_URL | Auto-detected | v2.7.14 |
+| `CORS_ORIGIN` | CORS allowed origins | `*` | v2.7.8 |
+| `AUTH_TOKEN_FILE` | Path to token file | - | v2.7.10 |
 
 ### n8n Management Tools (Optional)
 
@@ -167,7 +176,7 @@ Enable 16 additional tools for managing n8n workflows by configuring API access:
 
 #### What This Enables
 
-When configured, you get **16 additional tools** (total: 38 tools):
+When configured, you get **16 additional tools** (total: 39 tools):
 
 **Workflow Management (11 tools):**
 - `n8n_create_workflow` - Create new workflows
@@ -198,8 +207,64 @@ When configured, you get **16 additional tools** (total: 38 tools):
 
 ⚠️ **Security Note**: Store API keys securely and never commit them to version control.
 
+## 🏗️ Architecture
+
+### How HTTP Mode Works
+
+```
+┌─────────────────┐        ┌─────────────┐        ┌──────────────┐
+│ Claude Desktop  │ stdio  │ mcp-remote  │  HTTP  │  n8n-MCP     │
+│ (stdio only)    ├───────►│ (bridge)    ├───────►│  HTTP Server │
+└─────────────────┘        └─────────────┘        └──────────────┘
+                                                           │
+                                                           ▼
+                                                   ┌──────────────┐
+                                                   │ Your n8n     │
+                                                   │ Instance     │
+                                                   └──────────────┘
+```
+
+**Key Points:**
+- Claude Desktop **only supports stdio** communication
+- `mcp-remote` acts as a bridge, converting stdio ↔ HTTP
+- n8n-MCP server connects to **one n8n instance** (configured server-side)
+- All clients share the same n8n instance (single-tenant design)
+
 ## 🌐 Reverse Proxy Configuration
 
+### URL Configuration (v2.7.14+)
+
+n8n-MCP intelligently detects your public URL:
+
+#### Priority Order:
+1. **Explicit Configuration** (highest priority):
+   ```bash
+   BASE_URL=https://n8n-mcp.example.com  # Full public URL
+   # or
+   PUBLIC_URL=https://api.company.com:8443/mcp
+   ```
+
+2. **Auto-Detection** (when TRUST_PROXY is enabled):
+   ```bash
+   TRUST_PROXY=1  # Required for proxy header detection
+   # Server reads X-Forwarded-Proto and X-Forwarded-Host
+   ```
+
+3. **Fallback** (local binding):
+   ```bash
+   # No configuration needed
+   # Shows: http://localhost:3000 (or configured HOST:PORT)
+   ```
+
+#### What You'll See in Logs:
+```
+[INFO] Starting n8n-MCP HTTP Server v2.7.17...
+[INFO] Server running at https://n8n-mcp.example.com
+[INFO] Endpoints:
+[INFO]   Health: https://n8n-mcp.example.com/health
+[INFO]   MCP:    https://n8n-mcp.example.com/mcp
+```
+
 ### Trust Proxy for Correct IP Logging
 
 When running n8n-MCP behind a reverse proxy (Nginx, Traefik, etc.), enable trust proxy to log real client IPs instead of proxy IPs:
@@ -272,22 +337,10 @@ your-domain.com {
 
 ## 💻 Client Configuration
 
-### Understanding the Architecture
-
-Claude Desktop only supports stdio (standard input/output) communication, but our HTTP server requires HTTP requests. We bridge this gap using one of two methods:
-
-```
-Method 1: Using mcp-remote (npm package)
-Claude Desktop (stdio) → mcp-remote → HTTP Server
-
-Method 2: Using custom bridge script
-Claude Desktop (stdio) → http-bridge.js → HTTP Server
-```
+⚠️ **Requirements**: Node.js 18+ must be installed on the client machine for `mcp-remote`
 
 ### Method 1: Using mcp-remote (Recommended)
 
-**Requirements**: Node.js 18+ installed locally
-
 ```json
 {
   "mcpServers": {
@@ -298,16 +351,15 @@ Claude Desktop (stdio) → http-bridge.js → HTTP Server
         "mcp-remote",
         "https://your-server.com/mcp",
         "--header",
-        "Authorization: Bearer ${AUTH_TOKEN}"
-      ],
-      "env": {
-        "AUTH_TOKEN": "your-auth-token-here"
-      }
+        "Authorization: Bearer YOUR_AUTH_TOKEN_HERE"
+      ]
     }
   }
 }
 ```
 
+**Note**: Replace `YOUR_AUTH_TOKEN_HERE` with your actual token. Do NOT use `${AUTH_TOKEN}` syntax - Claude Desktop doesn't support environment variable substitution in args.
+
 ### Method 2: Using Custom Bridge Script
 
 For local testing or when mcp-remote isn't available:
@@ -350,18 +402,9 @@ When testing locally with Docker:
 }
 ```
 
-### For Claude Pro/Team Users
-
-Use native remote MCP support:
-1. Go to Settings > Integrations
-2. Add your MCP server URL
-3. Complete OAuth flow (if implemented)
-
-⚠️ **Note**: Direct config file entries won't work for remote servers in Pro/Team.
-
 ## 🌐 Production Deployment
 
-### Docker Compose Setup
+### Docker Compose (Complete Example)
 
 ```yaml
 version: '3.8'
@@ -372,66 +415,153 @@ services:
     container_name: n8n-mcp
     restart: unless-stopped
     environment:
+      # Core configuration
       MCP_MODE: http
       USE_FIXED_HTTP: true
-      AUTH_TOKEN: ${AUTH_TOKEN:?AUTH_TOKEN required}
       NODE_ENV: production
+      
+      # Security - Using file-based secret
+      AUTH_TOKEN_FILE: /run/secrets/auth_token
+      
+      # Networking
+      HOST: 0.0.0.0
+      PORT: 3000
+      TRUST_PROXY: 1  # Behind Nginx/Traefik
+      CORS_ORIGIN: https://app.example.com  # Restrict in production
+      
+      # URL Configuration
+      BASE_URL: https://n8n-mcp.example.com
+      
+      # Logging
       LOG_LEVEL: info
-      TRUST_PROXY: 1  # Enable if behind reverse proxy
-      # Optional: Enable n8n management tools
-      # N8N_API_URL: ${N8N_API_URL}
-      # N8N_API_KEY: ${N8N_API_KEY}
+      
+      # Optional: n8n API Integration
+      N8N_API_URL: ${N8N_API_URL}
+      N8N_API_KEY_FILE: /run/secrets/n8n_api_key
+      
+    secrets:
+      - auth_token
+      - n8n_api_key
+      
     ports:
-      - "127.0.0.1:3000:3000"  # Bind to localhost only
+      - "127.0.0.1:3000:3000"  # Only expose to localhost
+      
     volumes:
-      - n8n-mcp-data:/app/data
+      - n8n-mcp-data:/app/data:ro  # Read-only database
+      
     healthcheck:
       test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
       interval: 30s
       timeout: 10s
       retries: 3
+      start_period: 10s
+      
     deploy:
       resources:
         limits:
           memory: 512M
+          cpus: '0.5'
         reservations:
-          memory: 256M
+          memory: 128M
+          cpus: '0.1'
+    
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
+
+secrets:
+  auth_token:
+    file: ./secrets/auth_token.txt
+  n8n_api_key:
+    file: ./secrets/n8n_api_key.txt
 
 volumes:
   n8n-mcp-data:
 ```
 
-### Systemd Service (Linux)
-
-Create `/etc/systemd/system/n8n-mcp.service`:
+### Systemd Service (Production Linux)
 
 ```ini
+# /etc/systemd/system/n8n-mcp.service
 [Unit]
 Description=n8n-MCP HTTP Server
+Documentation=https://github.com/czlonkowski/n8n-mcp
 After=network.target
+Requires=network.target
 
 [Service]
 Type=simple
 User=n8n-mcp
+Group=n8n-mcp
 WorkingDirectory=/opt/n8n-mcp
-ExecStart=/usr/bin/node dist/mcp/index.js
-Restart=always
-RestartSec=10
 
-# Environment
+# Use file-based secret
+Environment="AUTH_TOKEN_FILE=/etc/n8n-mcp/auth_token"
 Environment="MCP_MODE=http"
 Environment="USE_FIXED_HTTP=true"
 Environment="NODE_ENV=production"
-EnvironmentFile=/opt/n8n-mcp/.env
+Environment="TRUST_PROXY=1"
+Environment="BASE_URL=https://n8n-mcp.example.com"
 
-# Security
+# Additional config from file
+EnvironmentFile=-/etc/n8n-mcp/config.env
+
+ExecStartPre=/usr/bin/test -f /etc/n8n-mcp/auth_token
+ExecStart=/usr/bin/node dist/mcp/index.js --http
+
+# Restart configuration
+Restart=always
+RestartSec=10
+StartLimitBurst=5
+StartLimitInterval=60s
+
+# Security hardening
 NoNewPrivileges=true
 PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=/opt/n8n-mcp/data
+ProtectKernelTunables=true
+ProtectControlGroups=true
+RestrictSUIDSGID=true
+LockPersonality=true
+
+# Resource limits
+LimitNOFILE=65536
+MemoryLimit=512M
+CPUQuota=50%
 
 [Install]
 WantedBy=multi-user.target
 ```
 
+**Setup:**
+```bash
+# Create user and directories
+sudo useradd -r -s /bin/false n8n-mcp
+sudo mkdir -p /opt/n8n-mcp /etc/n8n-mcp
+sudo chown n8n-mcp:n8n-mcp /opt/n8n-mcp
+
+# Create secure token
+sudo sh -c 'openssl rand -base64 32 > /etc/n8n-mcp/auth_token'
+sudo chmod 600 /etc/n8n-mcp/auth_token
+sudo chown n8n-mcp:n8n-mcp /etc/n8n-mcp/auth_token
+
+# Deploy application
+sudo -u n8n-mcp git clone https://github.com/czlonkowski/n8n-mcp.git /opt/n8n-mcp
+cd /opt/n8n-mcp
+sudo -u n8n-mcp npm install --production
+sudo -u n8n-mcp npm run build
+sudo -u n8n-mcp npm run rebuild
+
+# Start service
+sudo systemctl daemon-reload
+sudo systemctl enable n8n-mcp
+sudo systemctl start n8n-mcp
+```
+
 Enable:
 ```bash
 sudo systemctl enable n8n-mcp
@@ -440,66 +570,127 @@ sudo systemctl start n8n-mcp
 
 ## 📡 Monitoring & Maintenance
 
-### Health Checks
+### Health Endpoint Details
 
 ```bash
 # Basic health check
-curl https://your-server.com/health
+curl -H "Authorization: Bearer $AUTH_TOKEN" \
+     https://your-server.com/health
 
 # Response:
 {
   "status": "ok",
   "mode": "http-fixed",
-  "version": "2.3.2",
+  "version": "2.7.17",
   "uptime": 3600,
   "memory": {
-    "used": 45,
+    "used": 95,
     "total": 512,
-    "unit": "MB"
+    "percentage": 18.5
+  },
+  "node": {
+    "version": "v20.11.0",
+    "platform": "linux"
+  },
+  "features": {
+    "n8nApi": true,  // If N8N_API_URL configured
+    "authFile": true  // If using AUTH_TOKEN_FILE
   }
 }
 ```
 
-### Monitoring with Prometheus
+## 🔒 Security Features (v2.16.3+)
 
-```yaml
-# prometheus.yml
-scrape_configs:
-  - job_name: 'n8n-mcp'
-    static_configs:
-      - targets: ['localhost:3000']
-    metrics_path: '/health'
-    bearer_token: 'your-auth-token'
-```
+### Rate Limiting
 
-### Log Management
+Built-in rate limiting protects authentication endpoints from brute force attacks:
 
+**Configuration:**
 ```bash
-# Docker logs
-docker logs -f n8n-mcp --tail 100
-
-# Systemd logs
-journalctl -u n8n-mcp -f
-
-# Log rotation (Docker)
-docker run -d \
-  --log-driver json-file \
-  --log-opt max-size=10m \
-  --log-opt max-file=3 \
-  n8n-mcp
+# Defaults (15 minutes window, 20 attempts per IP)
+AUTH_RATE_LIMIT_WINDOW=900000  # milliseconds
+AUTH_RATE_LIMIT_MAX=20
 ```
 
+**Features:**
+- Per-IP rate limiting with configurable window and max attempts
+- Standard rate limit headers (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset)
+- JSON-RPC formatted error responses
+- Automatic IP tracking behind reverse proxies (requires TRUST_PROXY=1)
+
+**Behavior:**
+- First 20 attempts: Return 401 Unauthorized for invalid credentials
+- Attempts 21+: Return 429 Too Many Requests with Retry-After header
+- Counter resets after 15 minutes (configurable)
+
+### SSRF Protection
+
+Prevents Server-Side Request Forgery attacks when using webhook triggers:
+
+**Three Security Modes:**
+
+1. **Strict Mode (default)** - Production deployments
+   ```bash
+   WEBHOOK_SECURITY_MODE=strict
+   ```
+   - ✅ Block localhost (127.0.0.1, ::1)
+   - ✅ Block private IPs (10.x, 192.168.x, 172.16-31.x)
+   - ✅ Block cloud metadata (169.254.169.254, metadata.google.internal)
+   - ✅ DNS rebinding prevention
+   - 🎯 **Use for**: Cloud deployments, production environments
+
+2. **Moderate Mode** - Local development with local n8n
+   ```bash
+   WEBHOOK_SECURITY_MODE=moderate
+   ```
+   - ✅ Allow localhost (for local n8n instances)
+   - ✅ Block private IPs
+   - ✅ Block cloud metadata
+   - ✅ DNS rebinding prevention
+   - 🎯 **Use for**: Development with n8n on localhost:5678
+
+3. **Permissive Mode** - Internal networks only
+   ```bash
+   WEBHOOK_SECURITY_MODE=permissive
+   ```
+   - ✅ Allow localhost and private IPs
+   - ✅ Block cloud metadata (always blocked)
+   - ✅ DNS rebinding prevention
+   - 🎯 **Use for**: Internal testing (NOT for production)
+
+**Important:** Cloud metadata endpoints are ALWAYS blocked in all modes for security.
+
 ## 🔒 Security Best Practices
 
 ### 1. Token Management
 
+**DO:**
+- ✅ Use tokens with 32+ characters
+- ✅ Store tokens in secure files or secrets management
+- ✅ Rotate tokens regularly (monthly minimum)
+- ✅ Use different tokens for each environment
+- ✅ Monitor logs for authentication failures
+
+**DON'T:**
+- ❌ Use default or example tokens
+- ❌ Commit tokens to version control
+- ❌ Share tokens between environments
+- ❌ Log tokens in plain text
+
 ```bash
-# Generate strong tokens
+# Generate strong token
 openssl rand -base64 32
 
-# Rotate tokens regularly
-AUTH_TOKEN_NEW=$(openssl rand -base64 32)
-docker exec n8n-mcp env AUTH_TOKEN=$AUTH_TOKEN_NEW
+# Secure storage options:
+# 1. Docker secrets (recommended)
+echo $(openssl rand -base64 32) | docker secret create auth_token -
+
+# 2. Kubernetes secrets
+kubectl create secret generic n8n-mcp-auth \
+  --from-literal=token=$(openssl rand -base64 32)
+
+# 3. HashiCorp Vault
+vault kv put secret/n8n-mcp token=$(openssl rand -base64 32)
 ```
 
 ### 2. Network Security
@@ -525,20 +716,64 @@ docker scan ghcr.io/czlonkowski/n8n-mcp:latest
 
 ## 🔍 Troubleshooting
 
-### Common Issues
+### Common Issues & Solutions
 
-**"Stream is not readable" error:**
-- ✅ Solution: Ensure `USE_FIXED_HTTP=true` is set
-- This is fixed in v2.3.2
+#### Authentication Issues
 
-**"TransformStream is not defined" (client-side):**
-- 🔄 Update Node.js to v18+ on client machine
-- Or use Docker stdio mode instead
+**"Unauthorized" error:**
+```bash
+# Check token is set correctly
+docker exec n8n-mcp env | grep AUTH
 
-**"Why is command 'node' instead of 'docker'?"**
-- Claude Desktop only supports stdio communication
-- The bridge script (http-bridge.js or mcp-remote) translates between stdio and HTTP
-- Docker containers running HTTP servers need this bridge
+# Test with curl
+curl -v -H "Authorization: Bearer YOUR_TOKEN" \
+     https://your-server.com/health
+
+# Common causes:
+# - Extra spaces in token
+# - Missing "Bearer " prefix
+# - Token file has newline at end
+# - Wrong quotes in JSON config
+```
+
+**Default token warning:**
+```
+⚠️ SECURITY WARNING: Using default AUTH_TOKEN
+```
+- Change token immediately via environment variable
+- Server shows this warning every 5 minutes
+
+#### Connection Issues
+
+**"TransformStream is not defined":**
+```bash
+# Check Node.js version on CLIENT machine
+node --version  # Must be 18+
+
+# Update Node.js
+# macOS: brew upgrade node
+# Linux: Use NodeSource repository
+# Windows: Download from nodejs.org
+```
+
+**"Cannot connect to server":**
+```bash
+# 1. Check server is running
+docker ps | grep n8n-mcp
+
+# 2. Check logs for errors
+docker logs n8n-mcp --tail 50
+
+# 3. Test locally first
+curl http://localhost:3000/health
+
+# 4. Check firewall
+sudo ufw status  # Linux
+```
+
+**"Stream is not readable":**
+- Ensure `USE_FIXED_HTTP=true` is set
+- Fixed in v2.3.2+
 
 **Bridge script not working:**
 ```bash
@@ -566,60 +801,51 @@ sudo ufw status
 - Check for extra spaces or quotes
 - Test with curl first
 
+#### Bridge Configuration Issues
+
+**"Why use 'node' instead of 'docker' in Claude config?"**
+
+Claude Desktop only supports stdio. The architecture is:
+```
+Claude → stdio → mcp-remote → HTTP → Docker container
+```
+
+The `node` command runs mcp-remote (the bridge), not the server directly.
+
+**"Command not found: npx":**
+```bash
+# Install Node.js 18+ which includes npx
+# Or use full path:
+which npx  # Find npx location
+# Use that path in Claude config
+```
+
 ### Debug Mode
 
 ```bash
-# Enable debug logging
-LOG_LEVEL=debug docker run ...
+# 1. Enable debug logging
+docker run -e LOG_LEVEL=debug ...
 
-# Test MCP endpoint directly
+# 2. Test MCP endpoint
 curl -X POST https://your-server.com/mcp \
   -H "Authorization: Bearer $AUTH_TOKEN" \
   -H "Content-Type: application/json" \
-  -d '{"jsonrpc":"2.0","method":"list_nodes","params":{"limit":5},"id":1}'
+  -d '{
+    "jsonrpc": "2.0",
+    "method": "tools/list",
+    "id": 1
+  }'
+
+# 3. Test with mcp-remote directly
+MCP_URL=https://your-server.com/mcp \
+AUTH_TOKEN=your-token \
+echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | \
+  npx mcp-remote $MCP_URL --header "Authorization: Bearer $AUTH_TOKEN"
 ```
 
-## 🚀 Scaling & Performance
+### Cloud Platform Deployments
 
-### Performance Metrics
-
-- Average response time: **~12ms**
-- Memory usage: **~50-100MB**
-- Concurrent connections: **100+**
-- Database queries: **<5ms** with FTS5
-
-### Horizontal Scaling
-
-The server is stateless - scale easily:
-
-```yaml
-# Docker Swarm example
-deploy:
-  replicas: 3
-  update_config:
-    parallelism: 1
-    delay: 10s
-  restart_policy:
-    condition: on-failure
-```
-
-### Optimization Tips
-
-1. **Use Docker** for consistent performance
-2. **Enable HTTP/2** in your reverse proxy
-3. **Set up CDN** for static assets
-4. **Monitor memory** usage over time
-
-## 👥 Multi-User Service Considerations
-
-While n8n-MCP is designed for single-user deployments, you can build a multi-user service:
-
-1. **Use this as a core engine** with your own auth layer
-2. **Deploy multiple instances** with different tokens
-3. **Add user management** in your proxy layer
-4. **Implement rate limiting** per user
-
-See [Architecture Guide](./ARCHITECTURE.md) for building multi-user services.
+**Railway:** See our [Railway Deployment Guide](./RAILWAY_DEPLOYMENT.md)
 
 ## 🔧 Using n8n Management Tools
 
@@ -658,21 +884,43 @@ curl -X POST https://your-server.com/mcp \
 
 ## 📦 Updates & Maintenance
 
+### Version Updates
+
 ```bash
-# Update to latest version
+# Check current version
+docker exec n8n-mcp node -e "console.log(require('./package.json').version)"
+
+# Update to latest
 docker pull ghcr.io/czlonkowski/n8n-mcp:latest
-docker compose up -d
+docker stop n8n-mcp
+docker rm n8n-mcp
+# Re-run with same environment
 
-# Backup database
-docker cp n8n-mcp:/app/data/nodes.db ./backup-$(date +%Y%m%d).db
+# Update to specific version
+docker pull ghcr.io/czlonkowski/n8n-mcp:v2.7.17
+```
 
-# Restore database
-docker cp ./backup.db n8n-mcp:/app/data/nodes.db
-docker restart n8n-mcp
+### Database Management
+
+```bash
+# The database is read-only and pre-built
+# No backups needed for the node database
+# Updates include new database versions
+
+# Check database stats
+curl -X POST https://your-server.com/mcp \
+  -H "Authorization: Bearer $AUTH_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "method": "get_database_statistics",
+    "id": 1
+  }'
 ```
 
 ## 🆘 Getting Help
 
 - 📚 [Full Documentation](https://github.com/czlonkowski/n8n-mcp)
+- 🚂 [Railway Deployment Guide](./RAILWAY_DEPLOYMENT.md) - Easiest deployment option
 - 🐛 [Report Issues](https://github.com/czlonkowski/n8n-mcp/issues)
-- 💬 [Discussions](https://github.com/czlonkowski/n8n-mcp/discussions)
+- 💬 [Community Discussions](https://github.com/czlonkowski/n8n-mcp/discussions)

docs/N8N_DEPLOYMENT.md

@@ -0,0 +1,758 @@
+# n8n-MCP Deployment Guide
+
+This guide covers how to deploy n8n-MCP and connect it to your n8n instance. Whether you're testing locally or deploying to production, we'll show you how to set up n8n-MCP for use with n8n's MCP Client Tool node.
+
+## Table of Contents
+- [Overview](#overview)
+- [Local Testing](#local-testing)
+- [Production Deployment](#production-deployment)
+  - [Same Server as n8n](#same-server-as-n8n)
+  - [Different Server (Cloud Deployment)](#different-server-cloud-deployment)
+- [Connecting n8n to n8n-MCP](#connecting-n8n-to-n8n-mcp)
+- [Security & Best Practices](#security--best-practices)
+- [Troubleshooting](#troubleshooting)
+
+## Overview
+
+n8n-MCP is a Model Context Protocol server that provides AI assistants with comprehensive access to n8n node documentation and management capabilities. When connected to n8n via the MCP Client Tool node, it enables:
+- AI-powered workflow creation and validation
+- Access to documentation for 500+ n8n nodes
+- Workflow management through the n8n API
+- Real-time configuration validation
+
+## Local Testing
+
+### Quick Test Script
+
+Test n8n-MCP locally with the provided test script:
+
+```bash
+# Clone the repository
+git clone https://github.com/czlonkowski/n8n-mcp.git
+cd n8n-mcp
+
+# Build the project
+npm install
+npm run build
+
+# Run the integration test script
+./scripts/test-n8n-integration.sh
+```
+
+This script will:
+1. Start a real n8n instance in Docker
+2. Start n8n-MCP server configured for n8n
+3. Guide you through API key setup for workflow management
+4. Test the complete integration between n8n and n8n-MCP
+
+### Manual Local Setup
+
+For development or custom testing:
+
+1. **Prerequisites**:
+   - n8n instance running (local or remote)
+   - n8n API key (from n8n Settings → API)
+
+2. **Start n8n-MCP**:
+```bash
+# Set environment variables
+export N8N_MODE=true
+export MCP_MODE=http                       # Required for HTTP mode
+export N8N_API_URL=http://localhost:5678  # Your n8n instance URL
+export N8N_API_KEY=your-api-key-here       # Your n8n API key
+export MCP_AUTH_TOKEN=test-token-minimum-32-chars-long
+export AUTH_TOKEN=test-token-minimum-32-chars-long  # Same value as MCP_AUTH_TOKEN
+export PORT=3001
+
+# Start the server
+npm start
+```
+
+3. **Verify it's running**:
+```bash
+# Check health
+curl http://localhost:3001/health
+
+# Check MCP protocol endpoint (this is the endpoint n8n connects to)
+curl http://localhost:3001/mcp
+# Should return: {"protocolVersion":"2024-11-05"} for n8n compatibility
+```
+
+## Environment Variables Reference
+
+| Variable | Required | Description | Example Value |
+|----------|----------|-------------|---------------|
+| `N8N_MODE` | Yes | Enables n8n integration mode | `true` |
+| `MCP_MODE` | Yes | Enables HTTP mode for n8n MCP Client | `http` |
+| `N8N_API_URL` | Yes* | URL of your n8n instance | `http://localhost:5678` |
+| `N8N_API_KEY` | Yes* | n8n API key for workflow management | `n8n_api_xxx...` |
+| `MCP_AUTH_TOKEN` | Yes | Authentication token for MCP requests (min 32 chars) | `secure-random-32-char-token` |
+| `AUTH_TOKEN` | Yes | **MUST match MCP_AUTH_TOKEN exactly** | `secure-random-32-char-token` |
+| `PORT` | No | Port for the HTTP server | `3000` (default) |
+| `LOG_LEVEL` | No | Logging verbosity | `info`, `debug`, `error` |
+
+*Required only for workflow management features. Documentation tools work without these.
+
+## Docker Build Changes (v2.9.2+)
+
+Starting with version 2.9.2, we use a single optimized Dockerfile for all deployments:
+- The previous `Dockerfile.n8n` has been removed as redundant
+- N8N_MODE functionality is enabled via the `N8N_MODE=true` environment variable
+- This reduces image size by 500MB+ and improves build times from 8+ minutes to 1-2 minutes
+- All examples now use the standard `Dockerfile`
+
+## Production Deployment
+
+> **⚠️ Critical**: Docker caches images locally. Always run `docker pull ghcr.io/czlonkowski/n8n-mcp:latest` before deploying to ensure you have the latest version. This simple step prevents most deployment issues.
+
+### Same Server as n8n
+
+If you're running n8n-MCP on the same server as your n8n instance:
+
+### Using Pre-built Image (Recommended)
+
+The pre-built images are automatically updated with each release and are the easiest way to get started.
+
+**IMPORTANT**: Always pull the latest image to avoid using cached versions:
+
+```bash
+# ALWAYS pull the latest image first
+docker pull ghcr.io/czlonkowski/n8n-mcp:latest
+
+# Generate a secure token (save this!)
+AUTH_TOKEN=$(openssl rand -hex 32)
+echo "Your AUTH_TOKEN: $AUTH_TOKEN"
+
+# Create a Docker network if n8n uses one
+docker network create n8n-net
+
+# Run n8n-MCP container
+docker run -d \
+  --name n8n-mcp \
+  --network n8n-net \
+  -p 3000:3000 \
+  -e N8N_MODE=true \
+  -e MCP_MODE=http \
+  -e N8N_API_URL=http://n8n:5678 \
+  -e N8N_API_KEY=your-n8n-api-key \
+  -e MCP_AUTH_TOKEN=$AUTH_TOKEN \
+  -e AUTH_TOKEN=$AUTH_TOKEN \
+  -e LOG_LEVEL=info \
+  --restart unless-stopped \
+  ghcr.io/czlonkowski/n8n-mcp:latest
+```
+
+### Building from Source (Advanced Users)
+
+Only build from source if you need custom modifications or are contributing to development:
+
+```bash
+# Clone and build
+git clone https://github.com/czlonkowski/n8n-mcp.git
+cd n8n-mcp
+
+# Build Docker image
+docker build -t n8n-mcp:latest .
+
+# Run using your local image
+docker run -d \
+  --name n8n-mcp \
+  -p 3000:3000 \
+  -e N8N_MODE=true \
+  -e MCP_MODE=http \
+  -e MCP_AUTH_TOKEN=$(openssl rand -hex 32) \
+  -e AUTH_TOKEN=$(openssl rand -hex 32) \
+  # ... other settings
+  n8n-mcp:latest
+```
+
+### Using systemd (for native installation)
+
+```bash
+# Create service file
+sudo cat > /etc/systemd/system/n8n-mcp.service << EOF
+[Unit]
+Description=n8n-MCP Server
+After=network.target
+
+[Service]
+Type=simple
+User=nodejs
+WorkingDirectory=/opt/n8n-mcp
+Environment="N8N_MODE=true"
+Environment="MCP_MODE=http"
+Environment="N8N_API_URL=http://localhost:5678"
+Environment="N8N_API_KEY=your-n8n-api-key"
+Environment="MCP_AUTH_TOKEN=your-secure-token-32-chars-min"
+Environment="AUTH_TOKEN=your-secure-token-32-chars-min"
+Environment="PORT=3000"
+ExecStart=/usr/bin/node /opt/n8n-mcp/dist/mcp/index.js
+Restart=on-failure
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+# Enable and start
+sudo systemctl enable n8n-mcp
+sudo systemctl start n8n-mcp
+```
+
+### Different Server (Cloud Deployment)
+
+Deploy n8n-MCP on a separate server from your n8n instance:
+
+#### Quick Docker Deployment (Recommended)
+
+**Always pull the latest image to ensure you have the current version:**
+
+```bash
+# On your cloud server (Hetzner, AWS, DigitalOcean, etc.)
+# ALWAYS pull the latest image first
+docker pull ghcr.io/czlonkowski/n8n-mcp:latest
+
+# Generate auth tokens
+AUTH_TOKEN=$(openssl rand -hex 32)
+echo "Save this AUTH_TOKEN: $AUTH_TOKEN"
+
+# Run the container
+docker run -d \
+  --name n8n-mcp \
+  -p 3000:3000 \
+  -e N8N_MODE=true \
+  -e MCP_MODE=http \
+  -e N8N_API_URL=https://your-n8n-instance.com \
+  -e N8N_API_KEY=your-n8n-api-key \
+  -e MCP_AUTH_TOKEN=$AUTH_TOKEN \
+  -e AUTH_TOKEN=$AUTH_TOKEN \
+  -e LOG_LEVEL=info \
+  --restart unless-stopped \
+  ghcr.io/czlonkowski/n8n-mcp:latest
+```
+
+#### Building from Source (Advanced)
+
+Only needed if you're modifying the code:
+
+```bash
+# Clone and build
+git clone https://github.com/czlonkowski/n8n-mcp.git
+cd n8n-mcp
+docker build -t n8n-mcp:latest .
+
+# Run using local image
+docker run -d \
+  --name n8n-mcp \
+  -p 3000:3000 \
+  # ... same environment variables as above
+  n8n-mcp:latest
+```
+
+#### Full Production Setup (Hetzner/AWS/DigitalOcean)
+
+1. **Server Requirements**:
+   - **Minimal**: 1 vCPU, 1GB RAM (CX11 on Hetzner)
+   - **Recommended**: 2 vCPU, 2GB RAM
+   - **OS**: Ubuntu 22.04 LTS
+
+2. **Initial Setup**:
+```bash
+# SSH into your server
+ssh root@your-server-ip
+
+# Update and install Docker
+apt update && apt upgrade -y
+curl -fsSL https://get.docker.com | sh
+```
+
+3. **Deploy n8n-MCP with SSL** (using Caddy for automatic HTTPS):
+
+**Using Docker Compose (Recommended)**
+```bash
+# Create docker-compose.yml
+cat > docker-compose.yml << 'EOF'
+version: '3.8'
+
+services:
+  n8n-mcp:
+    image: ghcr.io/czlonkowski/n8n-mcp:latest
+    pull_policy: always  # Always pull latest image
+    container_name: n8n-mcp
+    restart: unless-stopped
+    environment:
+      - N8N_MODE=true
+      - MCP_MODE=http
+      - N8N_API_URL=${N8N_API_URL}
+      - N8N_API_KEY=${N8N_API_KEY}
+      - MCP_AUTH_TOKEN=${MCP_AUTH_TOKEN}
+      - AUTH_TOKEN=${AUTH_TOKEN}
+      - PORT=3000
+      - LOG_LEVEL=info
+    networks:
+      - web
+
+  caddy:
+    image: caddy:2-alpine
+    container_name: caddy
+    restart: unless-stopped
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile
+      - caddy_data:/data
+      - caddy_config:/config
+    networks:
+      - web
+
+networks:
+  web:
+    driver: bridge
+
+volumes:
+  caddy_data:
+  caddy_config:
+EOF
+```
+
+**Note**: The `pull_policy: always` ensures you always get the latest version.
+
+**Building from Source (if needed)**
+```bash
+# Only if you need custom modifications
+git clone https://github.com/czlonkowski/n8n-mcp.git
+cd n8n-mcp
+docker build -t n8n-mcp:local .
+
+# Then update docker-compose.yml to use:
+# image: n8n-mcp:local
+    container_name: n8n-mcp
+    restart: unless-stopped
+    environment:
+      - N8N_MODE=true
+      - MCP_MODE=http
+      - N8N_API_URL=${N8N_API_URL}
+      - N8N_API_KEY=${N8N_API_KEY}
+      - MCP_AUTH_TOKEN=${MCP_AUTH_TOKEN}
+      - AUTH_TOKEN=${AUTH_TOKEN}
+      - PORT=3000
+      - LOG_LEVEL=info
+    networks:
+      - web
+
+  caddy:
+    image: caddy:2-alpine
+    container_name: caddy
+    restart: unless-stopped
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile
+      - caddy_data:/data
+      - caddy_config:/config
+    networks:
+      - web
+
+networks:
+  web:
+    driver: bridge
+
+volumes:
+  caddy_data:
+  caddy_config:
+EOF
+```
+
+**Complete the Setup**
+```bash
+# Create Caddyfile
+cat > Caddyfile << 'EOF'
+mcp.yourdomain.com {
+    reverse_proxy n8n-mcp:3000
+}
+EOF
+
+# Create .env file
+AUTH_TOKEN=$(openssl rand -hex 32)
+cat > .env << EOF
+N8N_API_URL=https://your-n8n-instance.com
+N8N_API_KEY=your-n8n-api-key-here
+MCP_AUTH_TOKEN=$AUTH_TOKEN
+AUTH_TOKEN=$AUTH_TOKEN
+EOF
+
+# Save the AUTH_TOKEN!
+echo "Your AUTH_TOKEN is: $AUTH_TOKEN"
+echo "Save this token - you'll need it in n8n MCP Client Tool configuration"
+
+# Start services
+docker compose up -d
+```
+
+#### Cloud Provider Tips
+
+**AWS EC2**:
+- Security Group: Open port 3000 (or 443 with HTTPS)
+- Instance Type: t3.micro is sufficient
+- Use Elastic IP for stable addressing
+
+**DigitalOcean**:
+- Droplet: Basic ($6/month) is enough
+- Enable backups for production use
+
+**Google Cloud**:
+- Machine Type: e2-micro (free tier eligible)
+- Use Cloud Load Balancer for SSL
+
+## Connecting n8n to n8n-MCP
+
+### Configure n8n MCP Client Tool
+
+1. **In your n8n workflow**, add the **MCP Client Tool** node
+
+2. **Configure the connection**:
+   ```
+   Server URL (MUST include /mcp endpoint): 
+   - Same server: http://localhost:3000/mcp
+   - Docker network: http://n8n-mcp:3000/mcp
+   - Different server: https://mcp.yourdomain.com/mcp
+   
+   Auth Token: [Your MCP_AUTH_TOKEN/AUTH_TOKEN value]
+   
+   Transport: HTTP Streamable (SSE)
+   ```
+   
+   ⚠️ **Critical**: The Server URL must include the `/mcp` endpoint path. Without this, the connection will fail.
+
+3. **Test the connection** by selecting a simple tool like `list_nodes`
+
+### Available Tools
+
+Once connected, you can use these MCP tools in n8n:
+
+**Documentation Tools** (No API key required):
+- `list_nodes` - List all n8n nodes with filtering
+- `search_nodes` - Search nodes by keyword
+- `get_node_info` - Get detailed node information
+- `get_node_essentials` - Get only essential properties
+- `validate_workflow` - Validate workflow configurations
+- `get_node_documentation` - Get human-readable docs
+
+**Management Tools** (Requires n8n API key):
+- `n8n_create_workflow` - Create new workflows
+- `n8n_update_workflow` - Update existing workflows
+- `n8n_get_workflow` - Retrieve workflow details
+- `n8n_list_workflows` - List all workflows
+- `n8n_trigger_webhook_workflow` - Trigger webhook workflows
+
+### Using with AI Agents
+
+Connect n8n-MCP to AI Agent nodes for intelligent automation:
+
+1. **Add an AI Agent node** (e.g., OpenAI, Anthropic)
+2. **Connect MCP Client Tool** to the Agent's tool input
+3. **Configure prompts** for workflow creation:
+
+```
+You are an n8n workflow expert. Use the MCP tools to:
+1. Search for appropriate nodes using search_nodes
+2. Get configuration details with get_node_essentials
+3. Validate configurations with validate_workflow
+4. Create the workflow if all validations pass
+```
+
+## Security & Best Practices
+
+### Authentication
+- **MCP_AUTH_TOKEN**: Always use a strong, random token (32+ characters)
+- **N8N_API_KEY**: Only required for workflow management features
+- Store tokens in environment variables or secure vaults
+
+### Network Security
+- **Use HTTPS** in production (Caddy/Nginx/Traefik)
+- **Firewall**: Only expose necessary ports (3000 or 443)
+- **IP Whitelisting**: Consider restricting access to known n8n instances
+
+### Docker Security
+- **Always pull latest images**: Docker caches images locally, so run `docker pull` before deployment
+- Run containers with `--read-only` flag if possible
+- Use specific image versions instead of `:latest` in production
+- Regular updates: `docker pull ghcr.io/czlonkowski/n8n-mcp:latest`
+
+## Troubleshooting
+
+### Docker Image Issues
+
+**Using Outdated Cached Images**
+- **Symptom**: Missing features, old bugs reappearing, features not working as documented
+- **Cause**: Docker uses locally cached images instead of pulling the latest version
+- **Solution**: Always run `docker pull ghcr.io/czlonkowski/n8n-mcp:latest` before deployment
+- **Verification**: Check image age with `docker images | grep n8n-mcp`
+
+### Common Configuration Issues
+
+**Missing `MCP_MODE=http` Environment Variable**
+- **Symptom**: n8n MCP Client Tool cannot connect, server doesn't respond on `/mcp` endpoint
+- **Solution**: Add `MCP_MODE=http` to your environment variables
+- **Why**: Without this, the server runs in stdio mode which is incompatible with n8n
+
+**Server URL Missing `/mcp` Endpoint**
+- **Symptom**: "Connection refused" or "Invalid response" in n8n MCP Client Tool
+- **Solution**: Ensure your Server URL includes `/mcp` (e.g., `http://localhost:3000/mcp`)
+- **Why**: n8n connects to the `/mcp` endpoint specifically, not the root URL
+
+**Mismatched Auth Tokens**
+- **Symptom**: "Authentication failed" or "Invalid auth token"
+- **Solution**: Ensure both `MCP_AUTH_TOKEN` and `AUTH_TOKEN` have the same value
+- **Why**: Both variables must match for proper authentication
+
+### Connection Issues
+
+**"Connection refused" in n8n MCP Client Tool**
+1. **Check n8n-MCP is running**:
+   ```bash
+   # Docker
+   docker ps | grep n8n-mcp
+   docker logs n8n-mcp --tail 20
+   
+   # Systemd
+   systemctl status n8n-mcp
+   journalctl -u n8n-mcp --tail 20
+   ```
+
+2. **Verify endpoints are accessible**:
+   ```bash
+   # Health check (should return status info)
+   curl http://your-server:3000/health
+   
+   # MCP endpoint (should return protocol version)
+   curl http://your-server:3000/mcp
+   ```
+
+3. **Check firewall and networking**:
+   ```bash
+   # Test port accessibility from n8n server
+   telnet your-mcp-server 3000
+   
+   # Check firewall rules (Ubuntu/Debian)
+   sudo ufw status
+   
+   # Check if port is bound correctly
+   netstat -tlnp | grep :3000
+   ```
+
+**"Invalid auth token" or "Authentication failed"**
+1. **Verify token format**:
+   ```bash
+   # Check token length (should be 64 chars for hex-32)
+   echo $MCP_AUTH_TOKEN | wc -c
+   
+   # Verify both tokens match
+   echo "MCP_AUTH_TOKEN: $MCP_AUTH_TOKEN"
+   echo "AUTH_TOKEN: $AUTH_TOKEN"
+   ```
+
+2. **Common token issues**:
+   - Token too short (minimum 32 characters)
+   - Extra whitespace or newlines in token
+   - Different values for `MCP_AUTH_TOKEN` and `AUTH_TOKEN`
+   - Special characters not properly escaped in environment files
+
+**"Cannot connect to n8n API"**
+1. **Verify n8n configuration**:
+   ```bash
+   # Test n8n API accessibility
+   curl -H "X-N8N-API-KEY: your-api-key" \
+        https://your-n8n-instance.com/api/v1/workflows
+   ```
+
+2. **Common n8n API issues**:
+   - `N8N_API_URL` missing protocol (http:// or https://)
+   - n8n API key expired or invalid
+   - n8n instance not accessible from n8n-MCP server
+   - n8n API disabled in settings
+
+### Version Compatibility Issues
+
+**"Features Not Working as Expected"**
+- **Symptom**: Missing features, old bugs, or compatibility issues
+- **Solution**: Pull the latest image: `docker pull ghcr.io/czlonkowski/n8n-mcp:latest`
+- **Check**: Verify image date with `docker inspect ghcr.io/czlonkowski/n8n-mcp:latest | grep Created`
+
+**"Protocol version mismatch"**
+- n8n-MCP automatically uses version 2024-11-05 for n8n compatibility
+- Update to latest n8n-MCP version if issues persist
+- Verify `/mcp` endpoint returns correct version
+
+### Environment Variable Issues
+
+**Complete Environment Variable Checklist**:
+```bash
+# Required for all deployments
+export N8N_MODE=true                                    # Enables n8n integration
+export MCP_MODE=http                                   # Enables HTTP mode for n8n
+export MCP_AUTH_TOKEN=your-secure-32-char-token       # Auth token
+export AUTH_TOKEN=your-secure-32-char-token           # Same value as MCP_AUTH_TOKEN
+
+# Required for workflow management features
+export N8N_API_URL=https://your-n8n-instance.com      # Your n8n URL
+export N8N_API_KEY=your-n8n-api-key                   # Your n8n API key
+
+# Optional
+export PORT=3000                                       # HTTP port (default: 3000)
+export LOG_LEVEL=info                                  # Logging level
+```
+
+### Docker-Specific Issues
+
+**Container Build Failures**
+```bash
+# Clear Docker cache and rebuild
+docker system prune -f
+docker build --no-cache -t n8n-mcp:latest .
+```
+
+**Container Runtime Issues**
+```bash
+# Check container logs for detailed errors
+docker logs n8n-mcp -f --timestamps
+
+# Inspect container environment
+docker exec n8n-mcp env | grep -E "(N8N|MCP|AUTH)"
+
+# Test container connectivity
+docker exec n8n-mcp curl -f http://localhost:3000/health
+```
+
+### Network and SSL Issues
+
+**HTTPS/SSL Problems**
+```bash
+# Test SSL certificate
+openssl s_client -connect mcp.yourdomain.com:443
+
+# Check Caddy logs
+docker logs caddy -f --tail 50
+```
+
+**Docker Network Issues**
+```bash
+# Check if containers can communicate
+docker network ls
+docker network inspect bridge
+
+# Test inter-container connectivity
+docker exec n8n curl http://n8n-mcp:3000/health
+```
+
+### Debugging Steps
+
+1. **Enable comprehensive logging**:
+```bash
+# For Docker
+docker run -d \
+  --name n8n-mcp \
+  -e DEBUG_MCP=true \
+  -e LOG_LEVEL=debug \
+  -e N8N_MODE=true \
+  -e MCP_MODE=http \
+  # ... other settings
+
+# For systemd, add to service file:
+Environment="DEBUG_MCP=true"
+Environment="LOG_LEVEL=debug"
+```
+
+2. **Test all endpoints systematically**:
+```bash
+# 1. Health check (basic server functionality)
+curl -v http://localhost:3000/health
+
+# 2. MCP protocol endpoint (what n8n connects to)
+curl -v http://localhost:3000/mcp
+
+# 3. Test authentication (if working, returns tools list)
+curl -X POST http://localhost:3000/mcp \
+  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+
+# 4. Test a simple tool (documentation only, no n8n API needed)
+curl -X POST http://localhost:3000/mcp \
+  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_database_statistics","arguments":{}},"id":2}'
+```
+
+3. **Common log patterns to look for**:
+```bash
+# Success patterns
+grep "Server started" /var/log/n8n-mcp.log
+grep "Protocol version" /var/log/n8n-mcp.log
+
+# Error patterns
+grep -i "error\|failed\|invalid" /var/log/n8n-mcp.log
+grep -i "auth\|token" /var/log/n8n-mcp.log
+grep -i "connection\|network" /var/log/n8n-mcp.log
+```
+
+### Getting Help
+
+If you're still experiencing issues:
+
+1. **Gather diagnostic information**:
+```bash
+# System info
+docker --version
+docker-compose --version
+uname -a
+
+# n8n-MCP version
+docker exec n8n-mcp node dist/index.js --version
+
+# Environment check
+docker exec n8n-mcp env | grep -E "(N8N|MCP|AUTH)" | sort
+
+# Container status
+docker ps | grep n8n-mcp
+docker stats n8n-mcp --no-stream
+```
+
+2. **Create a minimal test setup**:
+```bash
+# Test with minimal configuration
+docker run -d \
+  --name n8n-mcp-test \
+  -p 3001:3000 \
+  -e N8N_MODE=true \
+  -e MCP_MODE=http \
+  -e MCP_AUTH_TOKEN=test-token-minimum-32-chars-long \
+  -e AUTH_TOKEN=test-token-minimum-32-chars-long \
+  -e LOG_LEVEL=debug \
+  n8n-mcp:latest
+
+# Test basic functionality
+curl http://localhost:3001/health
+curl http://localhost:3001/mcp
+```
+
+3. **Report issues**: Include the diagnostic information when opening an issue on [GitHub](https://github.com/czlonkowski/n8n-mcp/issues)
+
+## Performance Tips
+
+- **Minimal deployment**: 1 vCPU, 1GB RAM is sufficient
+- **Database**: Pre-built SQLite database (~15MB) loads quickly
+- **Response time**: Average 12ms for queries
+- **Caching**: Built-in 15-minute cache for repeated queries
+
+## Next Steps
+
+- Test your setup with the [MCP Client Tool in n8n](https://docs.n8n.io/integrations/builtin/app-nodes/n8n-nodes-langchain.mcpclienttool/)
+- Explore [available MCP tools](../README.md#-available-mcp-tools)
+- Build AI-powered workflows with [AI Agent nodes](https://docs.n8n.io/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.lmagent/)
+- Join the [n8n Community](https://community.n8n.io) for ideas and support
+
+---
+
+Need help? Open an issue on [GitHub](https://github.com/czlonkowski/n8n-mcp/issues) or check the [n8n forums](https://community.n8n.io)

docs/PR-104-test-improvements-summary.md

@@ -0,0 +1,62 @@
+# PR #104 Test Suite Improvements Summary
+
+## Overview
+Based on comprehensive review feedback from PR #104, we've significantly improved the test suite quality, organization, and coverage.
+
+## Test Results
+- **Before:** 78 failing tests
+- **After:** 0 failing tests (1,356 passed, 19 skipped)
+- **Coverage:** 85.34% statements, 85.3% branches
+
+## Key Improvements
+
+### 1. Fixed All Test Failures
+- Fixed logger test spy issues by properly handling DEBUG environment variable
+- Fixed MSW configuration test by restoring environment variables
+- Fixed workflow validator tests by adding proper node connections
+- Fixed mock setup issues in edge case tests
+
+### 2. Improved Test Organization
+- Split large config-validator.test.ts (1,075 lines) into 4 focused files:
+  - config-validator-basic.test.ts
+  - config-validator-node-specific.test.ts
+  - config-validator-security.test.ts
+  - config-validator-edge-cases.test.ts
+
+### 3. Enhanced Test Coverage
+- Added comprehensive edge case tests for all major validators
+- Added null/undefined handling tests
+- Added boundary value tests
+- Added performance tests with CI-aware timeouts
+- Added security validation tests
+
+### 4. Improved Test Quality
+- Fixed test naming conventions (100% compliance with "should X when Y" pattern)
+- Added JSDoc comments to test utilities and factories
+- Created comprehensive test documentation (tests/README.md)
+- Improved test isolation to prevent cross-test pollution
+
+### 5. New Features
+- Implemented validateBatch method for ConfigValidator
+- Added test factories for better test data management
+- Created test utilities for common scenarios
+
+## Files Modified
+- 7 existing test files fixed
+- 8 new test files created
+- 1 source file enhanced (ConfigValidator)
+- 4 debug files removed before commit
+
+## Skipped Tests
+19 tests remain skipped with documented reasons:
+- FTS5 search sync test (database corruption in CI)
+- Template clearing (not implemented)
+- Mock API configuration tests
+- Duplicate edge case tests with mocking issues (working versions exist)
+
+## Next Steps
+The only remaining task from the improvement plan is:
+- Add performance regression tests and boundaries (low priority, future sprint)
+
+## Conclusion
+The test suite is now robust, well-organized, and provides excellent coverage. All critical issues have been resolved, and the codebase is ready for merge.

docs/RAILWAY_DEPLOYMENT.md

@@ -0,0 +1,339 @@
+# Railway Deployment Guide for n8n-MCP
+
+Deploy n8n-MCP to Railway's cloud platform with zero configuration and connect it to Claude Desktop from anywhere.
+
+## 🚀 Quick Deploy
+
+Deploy n8n-MCP with one click:
+
+[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/VY6UOG?referralCode=n8n-mcp)
+
+## 📋 Overview
+
+Railway deployment provides:
+- ☁️ **Instant cloud hosting** - No server setup required
+- 🔒 **Secure by default** - HTTPS included, auth token warnings
+- 🌐 **Global access** - Connect from any Claude Desktop
+- ⚡ **Auto-scaling** - Railway handles the infrastructure
+- 📊 **Built-in monitoring** - Logs and metrics included
+
+## 🎯 Step-by-Step Deployment
+
+### 1. Deploy to Railway
+
+1. **Click the Deploy button** above
+2. **Sign in to Railway** (or create account)
+3. **Configure your deployment**:
+   - Project name (optional)
+   - Environment (leave as "production")
+   - Region (choose closest to you)
+4. **Click "Deploy"** and wait ~2-3 minutes
+
+### 2. Configure Security
+
+**IMPORTANT**: The deployment includes a default AUTH_TOKEN for instant functionality, but you MUST change it:
+
+![Railway Dashboard - Variables Tab](./img/railway-variables.png)
+
+1. **Go to your Railway dashboard**
+2. **Click on your n8n-mcp service**
+3. **Navigate to "Variables" tab**
+4. **Find `AUTH_TOKEN`** 
+5. **Replace with secure token**:
+   ```bash
+   # Generate secure token locally:
+   openssl rand -base64 32
+   ```
+6. **Railway will automatically redeploy** with the new token
+
+> ⚠️ **Security Warning**: The server displays warnings every 5 minutes until you change the default token!
+
+### 3. Get Your Service URL
+
+![Railway Dashboard - Domain Settings](./img/railway-domain.png)
+
+1. In Railway dashboard, click on your service
+2. Go to **"Settings"** tab
+3. Under **"Domains"**, you'll see your URL:
+   ```
+   https://your-app-name.up.railway.app
+   ```
+4. Copy this URL for Claude Desktop configuration and add /mcp at the end
+
+### 4. Connect Claude Desktop
+
+Add to your Claude Desktop configuration:
+
+```json
+{
+  "mcpServers": {
+    "n8n-railway": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-remote",
+        "https://your-app-name.up.railway.app/mcp",
+        "--header",
+        "Authorization: Bearer YOUR_SECURE_TOKEN_HERE"
+      ]
+    }
+  }
+}
+```
+
+**Configuration file locations:**
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+**Restart Claude Desktop** after saving the configuration.
+
+## 🔧 Environment Variables
+
+### Default Variables (Pre-configured)
+
+These are automatically set by the Railway template:
+
+| Variable | Default Value | Description |
+|----------|--------------|-------------|
+| `AUTH_TOKEN` | `REPLACE_THIS...` | **⚠️ CHANGE IMMEDIATELY** |
+| `MCP_MODE` | `http` | Required for cloud deployment |
+| `USE_FIXED_HTTP` | `true` | Stable HTTP implementation |
+| `NODE_ENV` | `production` | Production optimizations |
+| `LOG_LEVEL` | `info` | Balanced logging |
+| `TRUST_PROXY` | `1` | Railway runs behind proxy |
+| `CORS_ORIGIN` | `*` | Allow any origin |
+| `HOST` | `0.0.0.0` | Listen on all interfaces |
+| `PORT` | (Railway provides) | Don't set manually |
+| `AUTH_RATE_LIMIT_WINDOW` | `900000` (15 min) | Rate limit window (v2.16.3+) |
+| `AUTH_RATE_LIMIT_MAX` | `20` | Max auth attempts (v2.16.3+) |
+| `WEBHOOK_SECURITY_MODE` | `strict` | SSRF protection mode (v2.16.3+) |
+
+### Optional Variables
+
+| Variable | Default Value | Description |
+|----------|--------------|-------------|
+| `N8N_MODE` | `false` | Enable n8n integration mode for MCP Client Tool |
+| `N8N_API_URL` | - | URL of your n8n instance (for workflow management) |
+| `N8N_API_KEY` | - | API key from n8n Settings → API |
+
+### Optional: n8n Integration
+
+#### For n8n MCP Client Tool Integration
+
+To use n8n-MCP with n8n's MCP Client Tool node:
+
+1. **Go to Railway dashboard** → Your service → **Variables**
+2. **Add this variable**:
+   - `N8N_MODE`: Set to `true` to enable n8n integration mode
+3. **Save changes** - Railway will redeploy automatically
+
+#### For n8n API Integration (Workflow Management)
+
+To enable workflow management features:
+
+1. **Go to Railway dashboard** → Your service → **Variables**
+2. **Add these variables**:
+   - `N8N_API_URL`: Your n8n instance URL (e.g., `https://n8n.example.com`)
+   - `N8N_API_KEY`: API key from n8n Settings → API
+3. **Save changes** - Railway will redeploy automatically
+
+## 🏗️ Architecture Details
+
+### How It Works
+
+```
+Claude Desktop → mcp-remote → Railway (HTTPS) → n8n-MCP Server
+```
+
+1. **Claude Desktop** uses `mcp-remote` as a bridge
+2. **mcp-remote** converts stdio to HTTP requests
+3. **Railway** provides HTTPS endpoint and infrastructure
+4. **n8n-MCP** runs in HTTP mode on Railway
+
+### Single-Instance Design
+
+**Important**: The n8n-MCP HTTP server is designed for single n8n instance deployment:
+- n8n API credentials are configured server-side via environment variables
+- All clients connecting to the server share the same n8n instance
+- For multi-tenant usage, deploy separate Railway instances
+
+### Security Model
+
+- **Bearer Token Authentication**: All requests require the AUTH_TOKEN
+- **HTTPS by Default**: Railway provides SSL certificates
+- **Environment Isolation**: Each deployment is isolated
+- **No State Storage**: Server is stateless (database is read-only)
+
+## 🚨 Troubleshooting
+
+### Connection Issues
+
+**"Invalid URL" error in Claude Desktop:**
+- Ensure you're using the exact configuration format shown above
+- Don't add "connect" or other arguments before the URL
+- The URL should end with `/mcp`
+
+**"Unauthorized" error:**
+- Check that your AUTH_TOKEN matches exactly (no extra spaces)
+- Ensure the Authorization header format is correct: `Authorization: Bearer TOKEN`
+
+**"Cannot connect to server":**
+- Verify your Railway deployment is running (check Railway dashboard)
+- Ensure the URL is correct and includes `https://`
+- Check Railway logs for any errors
+
+**Windows: "The filename, directory name, or volume label syntax is incorrect" or npx command not found:**
+
+This is a common Windows issue with spaces in Node.js installation paths. The error occurs because Claude Desktop can't properly execute npx.
+
+**Solution 1: Use node directly (Recommended)**
+```json
+{
+  "mcpServers": {
+    "n8n-railway": {
+      "command": "node",
+      "args": [
+        "C:\\Program Files\\nodejs\\node_modules\\npm\\bin\\npx-cli.js",
+        "-y",
+        "mcp-remote",
+        "https://your-app-name.up.railway.app/mcp",
+        "--header",
+        "Authorization: Bearer YOUR_SECURE_TOKEN_HERE"
+      ]
+    }
+  }
+}
+```
+
+**Solution 2: Use cmd wrapper**
+```json
+{
+  "mcpServers": {
+    "n8n-railway": {
+      "command": "cmd",
+      "args": [
+        "/C",
+        "\"C:\\Program Files\\nodejs\\npx\" -y mcp-remote https://your-app-name.up.railway.app/mcp --header \"Authorization: Bearer YOUR_SECURE_TOKEN_HERE\""
+      ]
+    }
+  }
+}
+```
+
+To find your exact npx path, open Command Prompt and run: `where npx`
+
+### Railway-Specific Issues
+
+**Build failures:**
+- Railway uses AMD64 architecture - the template is configured for this
+- Check build logs in Railway dashboard for specific errors
+
+**Environment variable issues:**
+- Variables are case-sensitive
+- Don't include quotes in the Railway dashboard (only in JSON config)
+- Railway automatically restarts when you change variables
+
+**Domain not working:**
+- It may take 1-2 minutes for the domain to become active
+- Check the "Deployments" tab to ensure the latest deployment succeeded
+
+## 📊 Monitoring & Logs
+
+### View Logs
+
+1. Go to Railway dashboard
+2. Click on your n8n-mcp service
+3. Click on **"Logs"** tab
+4. You'll see real-time logs including:
+   - Server startup messages
+   - Authentication attempts
+   - API requests (without sensitive data)
+   - Any errors or warnings
+
+### Monitor Usage
+
+Railway provides metrics for:
+- **Memory usage** (typically ~100-200MB)
+- **CPU usage** (minimal when idle)
+- **Network traffic**
+- **Response times**
+
+## 💰 Pricing & Limits
+
+### Railway Free Tier
+- **$5 free credit** monthly
+- **500 hours** of runtime
+- **Sufficient for personal use** of n8n-MCP
+
+### Estimated Costs
+- **n8n-MCP typically uses**: ~0.1 GB RAM
+- **Monthly cost**: ~$2-3 for 24/7 operation
+- **Well within free tier** for most users
+
+## 🔄 Updates & Maintenance
+
+### Manual Updates
+
+Since the Railway template uses a specific Docker image tag, updates are manual:
+
+1. **Check for updates** on [GitHub](https://github.com/czlonkowski/n8n-mcp)
+2. **Update image tag** in Railway:
+   - Go to Settings → Deploy → Docker Image
+   - Change tag from current to new version
+   - Click "Redeploy"
+
+### Automatic Updates (Not Recommended)
+
+You could use the `latest` tag, but this may cause unexpected breaking changes.
+
+## 🔒 Security Features (v2.16.3+)
+
+Railway deployments include enhanced security features:
+
+### Rate Limiting
+- **Automatic brute force protection** - 20 attempts per 15 minutes per IP
+- **Configurable limits** via `AUTH_RATE_LIMIT_WINDOW` and `AUTH_RATE_LIMIT_MAX`
+- **Standard rate limit headers** for client awareness
+
+### SSRF Protection
+- **Default strict mode** blocks localhost, private IPs, and cloud metadata
+- **Cloud metadata always blocked** (169.254.169.254, metadata.google.internal, etc.)
+- **Use `moderate` mode only if** connecting to local n8n instance
+
+**Security Configuration:**
+```bash
+# In Railway Variables tab:
+WEBHOOK_SECURITY_MODE=strict          # Production (recommended)
+# or
+WEBHOOK_SECURITY_MODE=moderate        # If using local n8n with port forwarding
+
+# Rate limiting (defaults are good for most use cases)
+AUTH_RATE_LIMIT_WINDOW=900000         # 15 minutes
+AUTH_RATE_LIMIT_MAX=20                # 20 attempts per IP
+```
+
+## 📝 Best Practices
+
+1. **Always change the default AUTH_TOKEN immediately**
+2. **Use strong, unique tokens** (32+ characters)
+3. **Monitor logs** for unauthorized access attempts
+4. **Keep credentials secure** - never commit them to git
+5. **Use environment variables** for all sensitive data
+6. **Regular updates** - check for new versions monthly
+
+## 🆘 Getting Help
+
+- **Railway Documentation**: [docs.railway.app](https://docs.railway.app)
+- **n8n-MCP Issues**: [GitHub Issues](https://github.com/czlonkowski/n8n-mcp/issues)
+- **Railway Community**: [Discord](https://discord.gg/railway)
+
+## 🎉 Success!
+
+Once connected, you can use all n8n-MCP features from Claude Desktop:
+- Search and explore 500+ n8n nodes
+- Get node configurations and examples
+- Validate workflows before deployment
+- Manage n8n workflows (if API configured)
+
+The cloud deployment means you can access your n8n knowledge base from any computer with Claude Desktop installed!

docs/SSE_IMPLEMENTATION.md

@@ -1,221 +0,0 @@
-# SSE (Server-Sent Events) Implementation for n8n MCP
-
-## Overview
-
-This document describes the SSE implementation that enables n8n's MCP Server Trigger to connect to n8n-mcp server using Server-Sent Events protocol.
-
-## Architecture
-
-### Components
-
-1. **SSE Server** (`src/sse-server.ts`)
-   - Main Express server with SSE endpoints
-   - Handles authentication and CORS
-   - Manages both SSE connections and message processing
-
-2. **SSE Session Manager** (`src/utils/sse-session-manager.ts`)
-   - Manages active SSE client connections
-   - Handles session lifecycle and cleanup
-   - Sends events to connected clients
-
-3. **Type Definitions** (`src/types/sse.ts`)
-   - TypeScript interfaces for SSE messages
-   - MCP protocol message types
-
-## Endpoints
-
-### GET /sse, GET /mcp, and GET /mcp/:path/sse
-- **Purpose**: SSE connection endpoint for n8n MCP Server Trigger
-- **Authentication**: Multiple methods supported (see Authentication section)
-- **Query Parameters** (optional):
-  - `workflowId`: n8n workflow ID
-  - `executionId`: n8n execution ID
-  - `nodeId`: n8n node ID
-  - `nodeName`: n8n node name
-  - `runId`: n8n run ID
-  - `token`: Authentication token (for SSE connections)
-- **Headers** (optional):
-  - `X-Workflow-ID`: n8n workflow ID
-  - `X-Execution-ID`: n8n execution ID
-  - `X-Node-ID`: n8n node ID
-  - `X-Node-Name`: n8n node name
-  - `X-Run-ID`: n8n run ID
-- **Response**: Event stream with MCP protocol messages
-- **Events**:
-  - `connected`: Initial connection confirmation with client ID
-  - `mcp-response`: MCP protocol responses
-  - `mcp-error`: Error messages
-  - `ping`: Keep-alive messages (every 30 seconds)
-
-### POST /mcp/message and POST /mcp/:path/message
-- **Purpose**: Receive MCP requests from n8n
-- **Authentication**: Multiple methods supported (see Authentication section)
-- **Headers**: 
-  - `X-Client-ID`: SSE session client ID (required)
-- **Request Body**: JSON-RPC 2.0 format
-- **Response**: Acknowledgment with message ID
-
-### POST /mcp and POST /mcp/:path (Legacy)
-- **Purpose**: Backward compatibility with HTTP POST mode
-- **Authentication**: Multiple methods supported (see Authentication section)
-- **Request/Response**: Standard JSON-RPC 2.0
-
-### GET /health
-- **Purpose**: Health check endpoint
-- **Response**: Server status including active SSE sessions
-
-## Protocol Flow
-
-1. **Connection**:
-   ```
-   n8n → GET /mcp/workflow-123/sse?workflowId=123&nodeId=456 (with auth)
-   ← SSE connection established
-   ← Event: connected {clientId: "uuid"}
-   ← Event: mcp-response {method: "mcp/ready"}
-   ```
-
-2. **Tool Discovery**:
-   ```
-   n8n → POST /mcp/workflow-123/message {method: "tools/list"}
-   ← Response: {status: "ok"}
-   ← Event: mcp-response {result: {tools: [...]}}
-   ```
-
-3. **Tool Execution**:
-   ```
-   n8n → POST /mcp/workflow-123/message {method: "tools/call", params: {name, arguments}}
-   ← Response: {status: "ok"}
-   ← Event: mcp-response {result: {content: [...]}}
-   ```
-
-4. **Resources and Prompts** (empty implementations):
-   ```
-   n8n → POST /mcp/message {method: "resources/list"}
-   ← Event: mcp-response {result: {resources: []}}
-   
-   n8n → POST /mcp/message {method: "prompts/list"}
-   ← Event: mcp-response {result: {prompts: []}}
-   ```
-
-## Configuration
-
-### Environment Variables
-- `AUTH_TOKEN` or `AUTH_TOKEN_FILE`: Authentication token (required)
-- `AUTH_HEADER_NAME`: Custom authentication header name (default: x-auth-token)
-- `PORT`: Server port (default: 3000)
-- `HOST`: Server host (default: 0.0.0.0)
-- `CORS_ORIGIN`: Allowed CORS origin (default: *)
-- `TRUST_PROXY`: Number of proxy hops for correct IP logging
-
-## Usage
-
-### Starting the SSE Server
-
-```bash
-# Build and start
-npm run sse
-
-# Development mode with auto-reload
-npm run dev:sse
-
-# With environment variables
-AUTH_TOKEN=your-secure-token npm run sse
-```
-
-### Testing the Implementation
-
-```bash
-# Run SSE tests
-npm run test:sse
-
-# Manual test with curl
-# 1. Connect to SSE endpoint
-curl -N -H "Authorization: Bearer your-token" http://localhost:3000/sse
-
-# 2. Send a message (in another terminal)
-curl -X POST http://localhost:3000/mcp/message \
-  -H "Authorization: Bearer your-token" \
-  -H "X-Client-ID: <client-id-from-sse>" \
-  -H "Content-Type: application/json" \
-  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
-```
-
-## n8n Configuration
-
-### MCP Client Tool Node
-
-1. **SSE Endpoint**: `http://your-server:3000/mcp/your-path/sse`
-2. **Authentication**: Choose from supported methods
-3. **Token**: Your AUTH_TOKEN value
-4. **Optional Headers**: Add workflow context headers for better tracking
-
-## Security Considerations
-
-### Authentication Methods
-The SSE server supports multiple authentication methods:
-
-1. **Bearer Token** (recommended):
-   - Header: `Authorization: Bearer <token>`
-   
-2. **Custom Header**:
-   - Header: `X-Auth-Token: <token>` (or custom via AUTH_HEADER_NAME env var)
-   
-3. **Query Parameter** (for SSE connections):
-   - URL: `/sse?token=<token>`
-   
-4. **API Key Header**:
-   - Header: `X-API-Key: <token>`
-
-### Additional Security Features
-- **CORS**: Configure CORS_ORIGIN for production deployments
-- **HTTPS**: Use reverse proxy with SSL in production
-- **Session Timeout**: Sessions expire after 5 minutes of inactivity
-- **Workflow Context**: Track requests by workflow/node for auditing
-
-## Performance
-
-- Keep-alive pings every 30 seconds prevent connection timeouts
-- Session cleanup runs every 30 seconds
-- Supports up to 1000 concurrent SSE connections (configurable)
-- Minimal memory footprint per connection
-- Enhanced debug logging available with LOG_LEVEL=debug
-
-## Troubleshooting
-
-### Connection Issues
-- Check AUTH_TOKEN is set correctly
-- Verify firewall allows SSE connections
-- Check proxy configuration if behind reverse proxy
-- **n8n Connection Failed**: If you see "Could not connect to your MCP server" in n8n logs, this is likely due to gzip compression breaking SSE. The server now explicitly disables compression with `Content-Encoding: identity` header
-
-### Message Delivery
-- Ensure X-Client-ID header matches active session
-- Check server logs for session expiration
-- Verify JSON-RPC format is correct
-
-### Nginx Configuration
-If behind Nginx, add these directives:
-```nginx
-proxy_set_header Connection '';
-proxy_http_version 1.1;
-proxy_buffering off;
-proxy_cache off;
-proxy_read_timeout 86400s;
-gzip off;  # Important: Disable gzip for SSE endpoints
-```
-
-**Note**: n8n has known issues with gzip compression on SSE connections. Always disable compression for SSE endpoints.
-
-## Integration with n8n
-
-The SSE implementation enables n8n workflows to:
-1. Receive real-time MCP events
-2. Execute long-running tool operations
-3. Handle asynchronous responses
-4. Support multiple concurrent workflows
-
-This provides a more robust integration compared to simple HTTP polling, especially for:
-- Long-running operations
-- Real-time notifications
-- Event-driven workflows
-- Scalable deployments

docs/TEMPLATE_METADATA.md

@@ -0,0 +1,314 @@
+# Template Metadata Generation
+
+This document describes the template metadata generation system introduced in n8n-MCP v2.10.0, which uses OpenAI's batch API to automatically analyze and categorize workflow templates.
+
+## Overview
+
+The template metadata system analyzes n8n workflow templates to extract structured information about their purpose, complexity, requirements, and target audience. This enables intelligent template discovery through advanced filtering capabilities.
+
+## Architecture
+
+### Components
+
+1. **MetadataGenerator** (`src/templates/metadata-generator.ts`)
+   - Interfaces with OpenAI API
+   - Generates structured metadata using JSON schemas
+   - Provides fallback defaults for error cases
+
+2. **BatchProcessor** (`src/templates/batch-processor.ts`)
+   - Manages OpenAI batch API operations
+   - Handles parallel batch submission
+   - Monitors batch status and retrieves results
+
+3. **Template Repository** (`src/templates/template-repository.ts`)
+   - Stores metadata in SQLite database
+   - Provides advanced search capabilities
+   - Supports JSON extraction queries
+
+## Metadata Schema
+
+Each template's metadata contains:
+
+```typescript
+{
+  categories: string[]           // Max 5 categories (e.g., "automation", "integration")
+  complexity: "simple" | "medium" | "complex"
+  use_cases: string[]           // Max 5 primary use cases
+  estimated_setup_minutes: number // 5-480 minutes
+  required_services: string[]    // External services needed
+  key_features: string[]        // Max 5 main capabilities
+  target_audience: string[]     // Max 3 target user types
+}
+```
+
+## Generation Process
+
+### 1. Initial Setup
+
+```bash
+# Set OpenAI API key in .env
+OPENAI_API_KEY=your-api-key-here
+```
+
+### 2. Generate Metadata for Existing Templates
+
+```bash
+# Generate metadata only (no template fetching)
+npm run fetch:templates -- --metadata-only
+
+# Generate metadata during update
+npm run fetch:templates -- --mode=update --generate-metadata
+```
+
+### 3. Batch Processing
+
+The system uses OpenAI's batch API for cost-effective processing:
+
+- **50% cost reduction** compared to synchronous API calls
+- **24-hour processing window** for batch completion
+- **Parallel batch submission** for faster processing
+- **Automatic retry** for failed items
+
+### Configuration Options
+
+Environment variables:
+- `OPENAI_API_KEY`: Required for metadata generation
+- `OPENAI_MODEL`: Model to use (default: "gpt-4o-mini")
+- `OPENAI_BATCH_SIZE`: Templates per batch (default: 100, max: 500)
+- `METADATA_LIMIT`: Limit templates to process (for testing)
+
+## How It Works
+
+### 1. Template Analysis
+
+For each template, the generator analyzes:
+- Template name and description
+- Node types and their frequency
+- Workflow structure and connections
+- Overall complexity
+
+### 2. Node Summarization
+
+Nodes are grouped into categories:
+- HTTP/Webhooks
+- Database operations
+- Communication (Slack, Email)
+- AI/ML operations
+- Spreadsheets
+- Service-specific nodes
+
+### 3. Metadata Generation
+
+The AI model receives:
+```
+Template: [name]
+Description: [description]
+Nodes Used (X): [summarized node list]
+Workflow has X nodes with Y connections
+```
+
+And generates structured metadata following the JSON schema.
+
+### 4. Storage and Indexing
+
+Metadata is stored as JSON in SQLite and indexed for fast querying:
+
+```sql
+-- Example query for simple automation templates
+SELECT * FROM templates 
+WHERE json_extract(metadata, '$.complexity') = 'simple'
+AND json_extract(metadata, '$.categories') LIKE '%automation%'
+```
+
+## MCP Tool Integration
+
+### search_templates_by_metadata
+
+Advanced filtering tool with multiple parameters:
+
+```typescript
+search_templates_by_metadata({
+  category: "automation",           // Filter by category
+  complexity: "simple",             // Skill level
+  maxSetupMinutes: 30,             // Time constraint
+  targetAudience: "marketers",     // Role-based
+  requiredService: "slack"         // Service dependency
+})
+```
+
+### list_templates
+
+Enhanced to include metadata:
+
+```typescript
+list_templates({
+  includeMetadata: true,  // Include full metadata
+  limit: 20,
+  offset: 0
+})
+```
+
+## Usage Examples
+
+### Finding Beginner-Friendly Templates
+
+```typescript
+const templates = await search_templates_by_metadata({
+  complexity: "simple",
+  maxSetupMinutes: 15
+});
+```
+
+### Role-Specific Templates
+
+```typescript
+const marketingTemplates = await search_templates_by_metadata({
+  targetAudience: "marketers",
+  category: "communication"
+});
+```
+
+### Service Integration Templates
+
+```typescript
+const openaiTemplates = await search_templates_by_metadata({
+  requiredService: "openai",
+  complexity: "medium"
+});
+```
+
+## Performance Metrics
+
+- **Coverage**: 97.5% of templates have metadata (2,534/2,598)
+- **Generation Time**: ~2-4 hours for full database (using batch API)
+- **Query Performance**: <100ms for metadata searches
+- **Storage Overhead**: ~2MB additional database size
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Batch Processing Stuck**
+   - Check batch status: The API provides status updates
+   - Batches auto-expire after 24 hours
+   - Monitor using the batch ID in logs
+
+2. **Missing Metadata**
+   - ~2.5% of templates may fail metadata generation
+   - Fallback defaults are provided
+   - Can regenerate with `--metadata-only` flag
+
+3. **API Rate Limits**
+   - Batch API has generous limits (50,000 requests/batch)
+   - Cost is 50% of synchronous API
+   - Processing happens within 24-hour window
+
+### Monitoring Batch Status
+
+```bash
+# Check current batch status (if logged)
+curl https://api.openai.com/v1/batches/[batch-id] \
+  -H "Authorization: Bearer $OPENAI_API_KEY"
+```
+
+## Cost Analysis
+
+### Batch API Pricing (gpt-4o-mini)
+
+- Input: $0.075 per 1M tokens (50% of standard)
+- Output: $0.30 per 1M tokens (50% of standard)
+- Average template: ~300 input tokens, ~200 output tokens
+- Total cost for 2,500 templates: ~$0.50
+
+### Comparison with Synchronous API
+
+- Synchronous cost: ~$1.00 for same volume
+- Time saved: Parallel processing vs sequential
+- Reliability: Automatic retries included
+
+## Future Enhancements
+
+### Planned Improvements
+
+1. **Incremental Updates**
+   - Only generate metadata for new templates
+   - Track metadata version for updates
+
+2. **Enhanced Analysis**
+   - Workflow complexity scoring
+   - Dependency graph analysis
+   - Performance impact estimates
+
+3. **User Feedback Loop**
+   - Collect accuracy feedback
+   - Refine categorization over time
+   - Community-driven corrections
+
+4. **Alternative Models**
+   - Support for local LLMs
+   - Claude API integration
+   - Configurable model selection
+
+## Implementation Details
+
+### Database Schema
+
+```sql
+-- Metadata stored as JSON column
+ALTER TABLE templates ADD COLUMN metadata TEXT;
+
+-- Indexes for common queries
+CREATE INDEX idx_templates_complexity ON templates(
+  json_extract(metadata, '$.complexity')
+);
+CREATE INDEX idx_templates_setup_time ON templates(
+  json_extract(metadata, '$.estimated_setup_minutes')
+);
+```
+
+### Error Handling
+
+The system provides robust error handling:
+
+1. **API Failures**: Fallback to default metadata
+2. **Parsing Errors**: Logged with template ID
+3. **Batch Failures**: Individual item retry
+4. **Validation Errors**: Zod schema enforcement
+
+## Maintenance
+
+### Regenerating Metadata
+
+```bash
+# Full regeneration (caution: costs ~$0.50)
+npm run fetch:templates -- --mode=rebuild --generate-metadata
+
+# Partial regeneration (templates without metadata)
+npm run fetch:templates -- --metadata-only
+```
+
+### Database Backup
+
+```bash
+# Backup before regeneration
+cp data/nodes.db data/nodes.db.backup
+
+# Restore if needed
+cp data/nodes.db.backup data/nodes.db
+```
+
+## Security Considerations
+
+1. **API Key Management**
+   - Store in `.env` file (gitignored)
+   - Never commit API keys
+   - Use environment variables in CI/CD
+
+2. **Data Privacy**
+   - Only template structure is sent to API
+   - No user data or credentials included
+   - Processing happens in OpenAI's secure environment
+
+## Conclusion
+
+The template metadata system transforms template discovery from simple text search to intelligent, multi-dimensional filtering. By leveraging OpenAI's batch API, we achieve cost-effective, scalable metadata generation that significantly improves the user experience for finding relevant workflow templates.

docs/VS_CODE_PROJECT_SETUP.md

@@ -0,0 +1,201 @@
+# Visual Studio Code Setup
+
+:white_check_mark: This n8n MCP server is compatible with VS Code + GitHub Copilot (Chat in IDE).
+
+## Preconditions
+
+Assuming you've already deployed the n8n MCP server and connected it to the n8n API, and it's available at:
+`https://n8n.your.production.url/`
+
+💡 The deployment process is documented in the [HTTP Deployment Guide](./HTTP_DEPLOYMENT.md).
+
+## Step 1
+
+Start by creating a new VS Code project folder.
+
+## Step 2
+
+Create a file: `.vscode/mcp.json`
+```json
+{
+    "inputs": [
+        {
+            "type": "promptString",
+            "id": "n8n-mcp-token",
+            "description": "Your n8n-MCP AUTH_TOKEN",
+            "password": true
+        }
+    ],
+    "servers": {
+        "n8n-mcp": {
+            "type": "http",
+            "url": "https://n8n.your.production.url/mcp",
+            "headers": {
+                "Authorization": "Bearer ${input:n8n-mcp-token}"
+            }
+        }
+    }
+}
+```
+
+💡 The `inputs` block ensures the token is requested interactively — no need to hardcode secrets.
+
+## Step 3
+
+GitHub Copilot does not provide access to "thinking models" for unpaid users. To improve results, install the official [Sequential Thinking MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking) referenced in the [VS Code docs](https://code.visualstudio.com/mcp#:~:text=Install%20Linear-,Sequential%20Thinking,-Model%20Context%20Protocol). This lightweight add-on can turn any LLM into a thinking model by enabling step-by-step reasoning. It's highly recommended to use the n8n-mcp server in combination with a sequential thinking model to generate more accurate outputs.
+
+🔧 Alternatively, you can try enabling this setting in Copilot to unlock "thinking mode" behavior:
+
+![VS Code Settings > GitHub > Copilot > Chat > Agent: Thinking Tool](./img/vsc_ghcp_chat_thinking_tool.png)
+
+_(Note: I haven’t tested this setting myself, as I use the Sequential Thinking MCP instead)_
+
+## Step 4
+
+For the best results when using n8n-MCP with VS Code, use these enhanced system instructions (copy to your project’s `.github/copilot-instructions.md`):
+
+```markdown
+You are an expert in n8n automation software using n8n-MCP tools. Your role is to design, build, and validate n8n workflows with maximum accuracy and efficiency.
+
+## Core Workflow Process
+
+1. **ALWAYS start new conversation with**: `tools_documentation()` to understand best practices and available tools.
+
+2. **Discovery Phase** - Find the right nodes:
+   - Think deeply about user request and the logic you are going to build to fulfill it. Ask follow-up questions to clarify the user's intent, if something is unclear. Then, proceed with the rest of your instructions.
+   - `search_nodes({query: 'keyword'})` - Search by functionality
+   - `list_nodes({category: 'trigger'})` - Browse by category
+   - `list_ai_tools()` - See AI-capable nodes (remember: ANY node can be an AI tool!)
+
+3. **Configuration Phase** - Get node details efficiently:
+   - `get_node_essentials(nodeType)` - Start here! Only 10-20 essential properties
+   - `search_node_properties(nodeType, 'auth')` - Find specific properties
+   - `get_node_for_task('send_email')` - Get pre-configured templates
+   - `get_node_documentation(nodeType)` - Human-readable docs when needed
+   - It is good common practice to show a visual representation of the workflow architecture to the user and asking for opinion, before moving forward. 
+
+4. **Pre-Validation Phase** - Validate BEFORE building:
+   - `validate_node_minimal(nodeType, config)` - Quick required fields check
+   - `validate_node_operation(nodeType, config, profile)` - Full operation-aware validation
+   - Fix any validation errors before proceeding
+
+5. **Building Phase** - Create the workflow:
+   - Use validated configurations from step 4
+   - Connect nodes with proper structure
+   - Add error handling where appropriate
+   - Use expressions like $json, $node["NodeName"].json
+   - Build the workflow in an artifact for easy editing downstream (unless the user asked to create in n8n instance)
+
+6. **Workflow Validation Phase** - Validate complete workflow:
+   - `validate_workflow(workflow)` - Complete validation including connections
+   - `validate_workflow_connections(workflow)` - Check structure and AI tool connections
+   - `validate_workflow_expressions(workflow)` - Validate all n8n expressions
+   - Fix any issues found before deployment
+
+7. **Deployment Phase** (if n8n API configured):
+   - `n8n_create_workflow(workflow)` - Deploy validated workflow
+   - `n8n_validate_workflow({id: 'workflow-id'})` - Post-deployment validation
+   - `n8n_update_partial_workflow()` - Make incremental updates using diffs
+   - `n8n_trigger_webhook_workflow()` - Test webhook workflows
+
+## Key Insights
+
+- **USE CODE NODE ONLY WHEN IT IS NECESSARY** - always prefer to use standard nodes over code node. Use code node only when you are sure you need it.
+- **VALIDATE EARLY AND OFTEN** - Catch errors before they reach deployment
+- **USE DIFF UPDATES** - Use n8n_update_partial_workflow for 80-90% token savings
+- **ANY node can be an AI tool** - not just those with usableAsTool=true
+- **Pre-validate configurations** - Use validate_node_minimal before building
+- **Post-validate workflows** - Always validate complete workflows before deployment
+- **Incremental updates** - Use diff operations for existing workflows
+- **Test thoroughly** - Validate both locally and after deployment to n8n
+
+## Validation Strategy
+
+### Before Building:
+1. validate_node_minimal() - Check required fields
+2. validate_node_operation() - Full configuration validation
+3. Fix all errors before proceeding
+
+### After Building:
+1. validate_workflow() - Complete workflow validation
+2. validate_workflow_connections() - Structure validation
+3. validate_workflow_expressions() - Expression syntax check
+
+### After Deployment:
+1. n8n_validate_workflow({id}) - Validate deployed workflow
+2. n8n_list_executions() - Monitor execution status
+3. n8n_update_partial_workflow() - Fix issues using diffs
+
+## Response Structure
+
+1. **Discovery**: Show available nodes and options
+2. **Pre-Validation**: Validate node configurations first
+3. **Configuration**: Show only validated, working configs
+4. **Building**: Construct workflow with validated components
+5. **Workflow Validation**: Full workflow validation results
+6. **Deployment**: Deploy only after all validations pass
+7. **Post-Validation**: Verify deployment succeeded
+
+## Example Workflow
+
+### 1. Discovery & Configuration
+search_nodes({query: 'slack'})
+get_node_essentials('n8n-nodes-base.slack')
+
+### 2. Pre-Validation
+validate_node_minimal('n8n-nodes-base.slack', {resource:'message', operation:'send'})
+validate_node_operation('n8n-nodes-base.slack', fullConfig, 'runtime')
+
+### 3. Build Workflow
+// Create workflow JSON with validated configs
+
+### 4. Workflow Validation
+validate_workflow(workflowJson)
+validate_workflow_connections(workflowJson)
+validate_workflow_expressions(workflowJson)
+
+### 5. Deploy (if configured)
+n8n_create_workflow(validatedWorkflow)
+n8n_validate_workflow({id: createdWorkflowId})
+
+### 6. Update Using Diffs
+n8n_update_partial_workflow({
+  workflowId: id,
+  operations: [
+    {type: 'updateNode', nodeId: 'slack1', changes: {position: [100, 200]}}
+  ]
+})
+
+## Important Rules
+
+- ALWAYS validate before building
+- ALWAYS validate after building
+- NEVER deploy unvalidated workflows
+- USE diff operations for updates (80-90% token savings)
+- STATE validation results clearly
+- FIX all errors before proceeding
+```
+
+This helps the agent produce higher-quality, well-structured n8n workflows.
+
+🔧 Important: To ensure the instructions are always included, make sure this checkbox is enabled in your Copilot settings:
+
+![VS Code Settings > GitHub > Copilot > Chat > Code Generation: Use Instruction Files](./img/vsc_ghcp_chat_instruction_files.png)
+
+## Step 5
+
+Switch GitHub Copilot to Agent mode:
+
+![VS Code > GitHub Copilot Chat > Edit files in your workspace in agent mode](./img/vsc_ghcp_chat_agent_mode.png)
+
+## Step 6 - Try it!
+
+Here’s an example prompt I used:
+```
+#fetch https://blog.n8n.io/rag-chatbot/
+
+use #sequentialthinking and #n8n-mcp tools to build a new n8n workflow step-by-step following the guidelines in the blog.
+In the end, please deploy a fully-functional n8n workflow.
+```
+
+🧪 My result wasn’t perfect (a bit messy workflow), but I'm genuinely happy that it created anything autonomously 😄 Stay tuned for updates!

docs/WINDSURF_SETUP.md

@@ -0,0 +1,69 @@
+# Windsurf Setup
+
+Connect n8n-MCP to Windsurf IDE for enhanced n8n workflow development with AI assistance.
+
+[![n8n-mcp Windsurf Setup Tutorial](./img/windsurf_tut.png)](https://www.youtube.com/watch?v=klxxT1__izg)
+
+## Video Tutorial
+
+Watch the complete setup process: [n8n-MCP Windsurf Setup Tutorial](https://www.youtube.com/watch?v=klxxT1__izg)
+
+## Setup Process
+
+### 1. Access MCP Configuration
+
+1. Go to Settings in Windsurf
+2. Navigate to Windsurf Settings
+3. Go to MCP Servers > Manage Plugins
+4. Click "View Raw Config"
+
+### 2. Add n8n-MCP Configuration
+
+Copy the configuration from this repository and add it to your MCP config:
+
+**Basic configuration (documentation tools only):**
+```json
+{
+  "mcpServers": {
+    "n8n-mcp": {
+      "command": "npx",
+      "args": ["n8n-mcp"],
+      "env": {
+        "MCP_MODE": "stdio",
+        "LOG_LEVEL": "error",
+        "DISABLE_CONSOLE_OUTPUT": "true"
+      }
+    }
+  }
+}
+```
+
+**Full configuration (with n8n management tools):**
+```json
+{
+  "mcpServers": {
+    "n8n-mcp": {
+      "command": "npx",
+      "args": ["n8n-mcp"],
+      "env": {
+        "MCP_MODE": "stdio",
+        "LOG_LEVEL": "error",
+        "DISABLE_CONSOLE_OUTPUT": "true",
+        "N8N_API_URL": "https://your-n8n-instance.com",
+        "N8N_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+### 3. Configure n8n Connection
+
+1. Replace `https://your-n8n-instance.com` with your actual n8n URL
+2. Replace `your-api-key` with your n8n API key
+3. Click refresh to apply the changes
+
+### 4. Set Up Project Instructions
+
+1. Create a `.windsurfrules` file in your project root
+2. Copy the Claude Project instructions from the [main README's Claude Project Setup section](../README.md#-claude-project-setup)

docs/issue-90-findings.md

@@ -0,0 +1,162 @@
+# Issue #90: "propertyValues[itemName] is not iterable" Error - Research Findings
+
+## Executive Summary
+
+The error "propertyValues[itemName] is not iterable" occurs when AI agents create workflows with incorrect data structures for n8n nodes that use `fixedCollection` properties. This primarily affects Switch Node v2, If Node, and Filter Node. The error prevents workflows from loading in the n8n UI, resulting in empty canvases.
+
+## Root Cause Analysis
+
+### 1. Data Structure Mismatch
+
+The error occurs when n8n's validation engine expects an iterable array but encounters a non-iterable object. This happens with nodes using `fixedCollection` type properties.
+
+**Incorrect Structure (causes error):**
+```json
+{
+  "rules": {
+    "conditions": {
+      "values": [
+        {
+          "value1": "={{$json.status}}",
+          "operation": "equals", 
+          "value2": "active"
+        }
+      ]
+    }
+  }
+}
+```
+
+**Correct Structure:**
+```json
+{
+  "rules": {
+    "conditions": [
+      {
+        "value1": "={{$json.status}}",
+        "operation": "equals",
+        "value2": "active"
+      }
+    ]
+  }
+}
+```
+
+### 2. Affected Nodes
+
+Based on the research and issue comments, the following nodes are affected:
+
+1. **Switch Node v2** (`n8n-nodes-base.switch` with typeVersion: 2)
+   - Uses `rules` parameter with `conditions` fixedCollection
+   - v3 doesn't have this issue due to restructured schema
+
+2. **If Node** (`n8n-nodes-base.if` with typeVersion: 1)
+   - Uses `conditions` parameter with nested conditions array
+   - Similar structure to Switch v2
+
+3. **Filter Node** (`n8n-nodes-base.filter`)
+   - Uses `conditions` parameter
+   - Same fixedCollection pattern
+
+### 3. Why AI Agents Create Incorrect Structures
+
+1. **Training Data Issues**: AI models may have been trained on outdated or incorrect n8n workflow examples
+2. **Nested Object Inference**: AI tends to create unnecessarily nested structures when it sees collection-type parameters
+3. **Legacy Format Confusion**: Mixing v2 and v3 Switch node formats
+4. **Schema Misinterpretation**: The term "fixedCollection" may lead AI to create object wrappers
+
+## Current Impact
+
+From issue #90 comments:
+- Multiple users experiencing the issue
+- Workflows fail to load completely (empty canvas)
+- Users resort to using Switch Node v3 or direct API calls
+- The issue appears in "most MCPs" according to user feedback
+
+## Recommended Actions
+
+### 1. Immediate Validation Enhancement
+
+Add specific validation for fixedCollection properties in the workflow validator:
+
+```typescript
+// In workflow-validator.ts or enhanced-config-validator.ts
+function validateFixedCollectionParameters(node, result) {
+  const problematicNodes = {
+    'n8n-nodes-base.switch': { version: 2, fields: ['rules'] },
+    'n8n-nodes-base.if': { version: 1, fields: ['conditions'] },
+    'n8n-nodes-base.filter': { version: 1, fields: ['conditions'] }
+  };
+  
+  const nodeConfig = problematicNodes[node.type];
+  if (nodeConfig && node.typeVersion === nodeConfig.version) {
+    // Validate structure
+  }
+}
+```
+
+### 2. Enhanced MCP Tool Validation
+
+Update the validation tools to detect and prevent this specific error pattern:
+
+1. **In `validate_node_operation` tool**: Add checks for fixedCollection structures
+2. **In `validate_workflow` tool**: Include specific validation for Switch/If nodes
+3. **In `n8n_create_workflow` tool**: Pre-validate parameters before submission
+
+### 3. AI-Friendly Examples
+
+Update workflow examples to show correct structures:
+
+```typescript
+// In workflow-examples.ts
+export const SWITCH_NODE_EXAMPLE = {
+  name: "Switch",
+  type: "n8n-nodes-base.switch", 
+  typeVersion: 3, // Prefer v3 over v2
+  parameters: {
+    // Correct v3 structure
+  }
+};
+```
+
+### 4. Migration Strategy
+
+For existing workflows with Switch v2:
+1. Detect Switch v2 nodes in validation
+2. Suggest migration to v3
+3. Provide automatic conversion utility
+
+### 5. Documentation Updates
+
+1. Add warnings about fixedCollection structures in tool documentation
+2. Include specific examples of correct vs incorrect structures
+3. Document the Switch v2 to v3 migration path
+
+## Proposed Implementation Priority
+
+1. **High Priority**: Add validation to prevent creation of invalid structures
+2. **High Priority**: Update existing validation tools to catch this error
+3. **Medium Priority**: Add auto-fix capabilities to correct structures
+4. **Medium Priority**: Update examples and documentation
+5. **Low Priority**: Create migration utilities for v2 to v3
+
+## Testing Strategy
+
+1. Create test cases for each affected node type
+2. Test both correct and incorrect structures
+3. Verify validation catches all variants of the error
+4. Test auto-fix suggestions work correctly
+
+## Success Metrics
+
+- Zero instances of "propertyValues[itemName] is not iterable" in newly created workflows
+- Clear error messages that guide users to correct structures
+- Successful validation of all Switch/If node configurations before workflow creation
+
+## Next Steps
+
+1. Implement validation enhancements in the workflow validator
+2. Update MCP tools to include these validations
+3. Add comprehensive tests
+4. Update documentation with clear examples
+5. Consider adding a migration tool for existing workflows

docs/local/DEEP_DIVE_ANALYSIS_README.md

@@ -0,0 +1,225 @@
+# N8N-MCP Deep Dive Analysis - October 2, 2025
+
+## Overview
+
+This directory contains a comprehensive deep-dive analysis of n8n-mcp usage data from September 26 - October 2, 2025.
+
+**Data Volume Analyzed:**
+- 212,375 telemetry events
+- 5,751 workflow creations
+- 2,119 unique users
+- 6 days of usage data
+
+## Report Structure
+
+
+###: `DEEP_DIVE_ANALYSIS_2025-10-02.md` (Main Report)
+
+**Sections Covered:**
+1. **Executive Summary** - Key findings and recommendations
+2. **Tool Performance Analysis** - Success rates, performance metrics, critical findings
+3. **Validation Catastrophe** - The node type prefix disaster analysis
+4. **Usage Patterns & User Segmentation** - User distribution, daily trends
+5. **Tool Sequence Analysis** - How AI agents use tools together
+6. **Workflow Creation Patterns** - Complexity distribution, popular nodes
+7. **Platform & Version Distribution** - OS, architecture, version adoption
+8. **Error Patterns & Root Causes** - TypeErrors, validation errors, discovery failures
+9. **P0-P1 Refactoring Recommendations** - Detailed implementation guides
+
+**Sections Covered:**
+- Remaining P1 and P2 recommendations
+- Architectural refactoring suggestions
+- Telemetry enhancements
+- CHANGELOG integration
+- Final recommendations summary
+
+## Key Findings Summary
+
+### Critical Issues (P0 - Fix Immediately)
+
+1. **Node Type Prefix Validation Catastrophe**
+   - 5,000+ validation errors from single root cause
+   - `nodes-base.X` vs `n8n-nodes-base.X` confusion
+   - **Solution**: Auto-normalize prefixes (2-4 hours effort)
+
+2. **TypeError in Node Information Tools**
+   - 10-18% failure rate in get_node_essentials/info
+   - 1,000+ failures affecting hundreds of users
+   - **Solution**: Complete null-safety audit (1 day effort)
+
+3. **Task Discovery Failures**
+   - `get_node_for_task` failing 28% of the time
+   - Worst-performing tool in entire system
+   - **Solution**: Expand task library + fuzzy matching (3 days effort)
+
+### Performance Metrics
+
+**Excellent Reliability (96-100% success):**
+- n8n_update_partial_workflow: 98.7%
+- search_nodes: 99.8%
+- n8n_create_workflow: 96.1%
+- All workflow management tools: 100%
+
+**User Distribution:**
+- Power Users (12): 2,112 events/user, 33 workflows
+- Heavy Users (47): 673 events/user, 18 workflows
+- Regular Users (516): 199 events/user, 7 workflows (CORE AUDIENCE)
+- Active Users (919): 52 events/user, 2 workflows
+- Casual Users (625): 8 events/user, 1 workflow
+
+### Usage Insights
+
+**Most Used Tools:**
+1. n8n_update_partial_workflow: 10,177 calls (iterative refinement)
+2. search_nodes: 8,839 calls (node discovery)
+3. n8n_create_workflow: 6,046 calls (workflow creation)
+
+**Most Common Tool Sequences:**
+1. update → update → update (549x) - Iterative refinement pattern
+2. create → update (297x) - Create then refine
+3. update → get_workflow (265x) - Update then verify
+
+**Most Popular Nodes:**
+1. code (53% of workflows) - AI agents love programmatic control
+2. httpRequest (47%) - Integration-heavy usage
+3. webhook (32%) - Event-driven automation
+
+## SQL Analytical Views Created
+
+15 comprehensive views were created in Supabase for ongoing analysis:
+
+1. `vw_tool_performance` - Performance metrics per tool
+2. `vw_error_analysis` - Error patterns and frequencies
+3. `vw_validation_analysis` - Validation failure details
+4. `vw_tool_sequences` - Tool-to-tool transition patterns
+5. `vw_workflow_creation_patterns` - Workflow characteristics
+6. `vw_node_usage_analysis` - Node popularity and complexity
+7. `vw_node_cooccurrence` - Which nodes are used together
+8. `vw_user_activity` - Per-user activity metrics
+9. `vw_session_analysis` - Platform/version distribution
+10. `vw_workflow_validation_failures` - Workflow validation issues
+11. `vw_temporal_patterns` - Time-based usage patterns
+12. `vw_tool_funnel` - User progression through tools
+13. `vw_search_analysis` - Search behavior
+14. `vw_tool_success_summary` - Success/failure rates
+15. `vw_user_journeys` - Complete user session reconstruction
+
+## Priority Recommendations
+
+### Immediate Actions (This Week)
+
+✅ **P0-R1**: Auto-normalize node type prefixes → Eliminate 4,800 errors
+✅ **P0-R2**: Complete null-safety audit → Fix 10-18% TypeError failures
+✅ **P0-R3**: Expand get_node_for_task library → 72% → 95% success rate
+
+**Expected Impact**: Reduce error rate from 5-10% to <2% overall
+
+### Next Release (2-3 Weeks)
+
+✅ **P1-R4**: Batch workflow operations → Save 30-50% tokens
+✅ **P1-R5**: Proactive node suggestions → Reduce search iterations
+✅ **P1-R6**: Auto-fix suggestions in errors → Self-service recovery
+
+**Expected Impact**: 40% faster workflow creation, better UX
+
+### Future Roadmap (1-3 Months)
+
+✅ **A1**: Service layer consolidation → Cleaner architecture
+✅ **A2**: Repository caching → 50% faster node operations
+✅ **R10**: Workflow template library from usage → 80% coverage
+✅ **T1-T3**: Enhanced telemetry → Better observability
+
+**Expected Impact**: Scalable foundation for 10x growth
+
+## Methodology
+
+### Data Sources
+
+1. **Supabase Telemetry Database**
+   - `telemetry_events` table: 212,375 rows
+   - `telemetry_workflows` table: 5,751 rows
+
+2. **Analytical Views**
+   - Created 15 SQL views for multi-dimensional analysis
+   - Enabled complex queries and pattern recognition
+
+3. **CHANGELOG Review**
+   - Analyzed recent changes (v2.14.0 - v2.14.6)
+   - Correlated fixes with error patterns
+
+### Analysis Approach
+
+1. **Quantitative Analysis**
+   - Success/failure rates per tool
+   - Performance metrics (avg, median, p95, p99)
+   - User segmentation and cohort analysis
+   - Temporal trends and growth patterns
+
+2. **Pattern Recognition**
+   - Tool sequence analysis (Markov chains)
+   - Node co-occurrence patterns
+   - Workflow complexity distribution
+   - Error clustering and root cause analysis
+
+3. **Qualitative Insights**
+   - CHANGELOG integration
+   - Error message analysis
+   - User journey reconstruction
+   - Best practice identification
+
+## How to Use This Analysis
+
+### For Development Priorities
+
+1. Review **P0 Critical Recommendations** (Section 8)
+2. Check estimated effort and impact
+3. Prioritize based on ROI (impact/effort ratio)
+4. Follow implementation guides with code examples
+
+### For Architecture Decisions
+
+1. Review **Architectural Recommendations** (Section 9)
+2. Consider service layer consolidation
+3. Evaluate repository caching opportunities
+4. Plan for 10x scale
+
+### For Product Strategy
+
+1. Review **Usage Patterns** (Section 3 & 5)
+2. Understand user segments (power vs casual)
+3. Identify high-value features (most-used tools)
+4. Focus on reliability over features (96% success rate target)
+
+### For Telemetry Enhancement
+
+1. Review **Telemetry Enhancements** (Section 10)
+2. Add fine-grained timing metrics
+3. Track workflow creation funnels
+4. Monitor node-level analytics
+
+## Contact & Feedback
+
+For questions about this analysis or to request additional insights:
+- Data Analyst: Claude Code with Supabase MCP
+- Analysis Date: October 2, 2025
+- Data Period: September 26 - October 2, 2025
+
+## Change Log
+
+- **2025-10-02**: Initial comprehensive analysis completed
+  - 15 SQL analytical views created
+  - 13 sections of detailed findings
+  - P0/P1/P2 recommendations with implementation guides
+  - Code examples and effort estimates provided
+
+## Next Steps
+
+1. ✅ Review findings with development team
+2. ✅ Prioritize P0 recommendations for immediate implementation
+3. ✅ Plan P1 features for next release cycle
+4. ✅ Set up monitoring for key metrics
+5. ✅ Schedule follow-up analysis (weekly recommended)
+
+---
+
+*This analysis represents a snapshot of n8n-mcp usage during early adoption phase. Patterns may evolve as the user base grows and matures.*

docs/local/TEMPLATE_MINING_ANALYSIS.md

@@ -0,0 +1,369 @@
+# Template Mining Analysis - Alternative to P0-R3
+
+**Date**: 2025-10-02
+**Context**: Analyzing whether to fix `get_node_for_task` (28% failure rate) or replace it with template-based configuration extraction
+
+## Executive Summary
+
+**RECOMMENDATION**: Replace `get_node_for_task` with template-based configuration extraction. The template database contains 2,646 real-world workflows with rich node configurations that far exceed the 31 hardcoded task templates.
+
+## Key Findings
+
+### 1. Template Database Coverage
+
+- **Total Templates**: 2,646 production workflows from n8n.io
+- **Unique Node Types**: 543 (covers 103% of our 525 core nodes)
+- **Metadata Coverage**: 100% (AI-generated structured metadata)
+
+### 2. Node Type Coverage in Templates
+
+Top node types by template usage:
+```
+3,820 templates: n8n-nodes-base.httpRequest      (144% of total templates!)
+3,678 templates: n8n-nodes-base.set
+2,445 templates: n8n-nodes-base.code
+1,700 templates: n8n-nodes-base.googleSheets
+1,471 templates: @n8n/n8n-nodes-langchain.agent
+1,269 templates: @n8n/n8n-nodes-langchain.lmChatOpenAi
+  792 templates: n8n-nodes-base.telegram
+  702 templates: n8n-nodes-base.httpRequestTool
+  596 templates: n8n-nodes-base.gmail
+  466 templates: n8n-nodes-base.webhook
+```
+
+**Comparison**:
+- Hardcoded task templates: 31 tasks covering 5.9% of nodes
+- Real templates: 2,646 templates with 2-3k examples for common nodes
+
+### 3. Database Structure
+
+```sql
+CREATE TABLE templates (
+  id INTEGER PRIMARY KEY,
+  workflow_id INTEGER UNIQUE NOT NULL,
+  name TEXT NOT NULL,
+  description TEXT,
+  -- Node information
+  nodes_used TEXT,              -- JSON array: ["n8n-nodes-base.httpRequest", ...]
+  workflow_json_compressed TEXT, -- Base64 encoded gzip of full workflow
+  -- Metadata (100% coverage)
+  metadata_json TEXT,           -- AI-generated structured metadata
+  -- Stats
+  views INTEGER DEFAULT 0,
+  created_at DATETIME,
+  -- ...
+);
+```
+
+### 4. Real Configuration Examples
+
+#### HTTP Request Node Configurations
+
+**Simple URL fetch**:
+```json
+{
+  "url": "https://api.example.com/data",
+  "options": {}
+}
+```
+
+**With authentication**:
+```json
+{
+  "url": "=https://api.wavespeed.ai/api/v3/predictions/{{ $json.data.id }}/result",
+  "options": {},
+  "authentication": "genericCredentialType",
+  "genericAuthType": "httpHeaderAuth"
+}
+```
+
+**Complex expressions**:
+```json
+{
+  "url": "=https://image.pollinations.ai/prompt/{{$('Social Media Content Factory').item.json.output.description.replaceAll(' ','-').replaceAll(',','').replaceAll('.','') }}",
+  "options": {}
+}
+```
+
+#### Webhook Node Configurations
+
+**Basic webhook**:
+```json
+{
+  "path": "ytube",
+  "options": {},
+  "httpMethod": "POST",
+  "responseMode": "responseNode"
+}
+```
+
+**With binary data**:
+```json
+{
+  "path": "your-endpoint",
+  "options": {
+    "binaryPropertyName": "data"
+  },
+  "httpMethod": "POST"
+}
+```
+
+### 5. AI-Generated Metadata
+
+Each template has structured metadata including:
+
+```json
+{
+  "categories": ["automation", "integration", "data processing"],
+  "complexity": "medium",
+  "use_cases": [
+    "Extract transaction data from Gmail",
+    "Automate bookkeeping",
+    "Expense tracking"
+  ],
+  "estimated_setup_minutes": 30,
+  "required_services": ["Gmail", "Google Sheets", "Google Gemini"],
+  "key_features": [
+    "Fetch emails by label",
+    "Extract transaction data",
+    "Use LLM for structured output"
+  ],
+  "target_audience": ["Accountants", "Small business owners"]
+}
+```
+
+## Comparison: Task Templates vs Real Templates
+
+### Current Approach (get_node_for_task)
+
+**Pros**:
+- Curated configurations with best practices
+- Predictable, stable responses
+- Fast lookup (no decompression needed)
+
+**Cons**:
+- Only 31 tasks (5.9% node coverage)
+- 28% failure rate (users can't find what they need)
+- Requires manual maintenance
+- Static configurations without real-world context
+- Usage ratio 22.5:1 (search_nodes is preferred)
+
+### Template-Based Approach
+
+**Pros**:
+- 2,646 real workflows with 2-3k examples for common nodes
+- 100% metadata coverage for semantic matching
+- Real-world patterns and best practices
+- Covers 543 node types (103% coverage)
+- Self-updating (templates fetched from n8n.io)
+- Rich context (use cases, complexity, setup time)
+
+**Cons**:
+- Requires decompression for full workflow access
+- May contain template-specific context (but can be filtered)
+- Need ranking/filtering logic for best matches
+
+## Proposed Implementation Strategy
+
+### Phase 1: Extract Node Configurations from Templates
+
+Create a new service: `TemplateConfigExtractor`
+
+```typescript
+interface ExtractedNodeConfig {
+  nodeType: string;
+  configuration: Record<string, any>;
+  source: {
+    templateId: number;
+    templateName: string;
+    templateViews: number;
+    useCases: string[];
+    complexity: 'simple' | 'medium' | 'complex';
+  };
+  patterns: {
+    hasAuthentication: boolean;
+    hasExpressions: boolean;
+    hasOptionalFields: boolean;
+  };
+}
+
+class TemplateConfigExtractor {
+  async extractConfigsForNode(
+    nodeType: string,
+    options?: {
+      complexity?: 'simple' | 'medium' | 'complex';
+      requiresAuth?: boolean;
+      limit?: number;
+    }
+  ): Promise<ExtractedNodeConfig[]> {
+    // 1. Query templates containing nodeType
+    // 2. Decompress workflow_json_compressed
+    // 3. Extract node configurations
+    // 4. Rank by popularity + complexity match
+    // 5. Return top N configurations
+  }
+}
+```
+
+### Phase 2: Integrate with Existing Tools
+
+**Option A**: Enhance `get_node_essentials`
+- Add `includeExamples: boolean` parameter
+- Return 2-3 real configurations from templates
+- Preserve existing compact format
+
+**Option B**: Enhance `get_node_info`
+- Add `examples` section with template-sourced configs
+- Include source attribution (template name, views)
+
+**Option C**: New tool `get_node_examples`
+- Dedicated tool for retrieving configuration examples
+- Query by node type, complexity, use case
+- Returns ranked list of real configurations
+
+### Phase 3: Deprecate get_node_for_task
+
+- Mark as deprecated in tool documentation
+- Redirect to enhanced tools
+- Remove after 2-3 version cycles
+
+## Performance Considerations
+
+### Decompression Cost
+
+- Average compressed size: 6-12 KB
+- Decompression time: ~5-10ms per template
+- Caching strategy needed for frequently accessed templates
+
+### Query Strategy
+
+```sql
+-- Fast: Get templates for a node type (no decompression)
+SELECT id, name, views, metadata_json
+FROM templates
+WHERE nodes_used LIKE '%n8n-nodes-base.httpRequest%'
+ORDER BY views DESC
+LIMIT 10;
+
+-- Then decompress only top matches
+```
+
+### Caching
+
+- Cache decompressed workflows for popular templates (top 100)
+- TTL: 1 hour
+- Estimated memory: 100 * 50KB = 5MB
+
+## Impact on P0-R3
+
+**Original P0-R3 Plan**: Expand task library from 31 to 100+ tasks using fuzzy matching
+
+**New Approach**: Mine 2,646 templates for real configurations
+
+**Impact Assessment**:
+
+| Metric | Original Plan | Template Mining |
+|--------|--------------|-----------------|
+| Configuration examples | 100 (estimated) | 2,646+ actual |
+| Node coverage | ~20% | 103% |
+| Maintenance | High (manual) | Low (auto-fetch) |
+| Accuracy | Curated | Production-tested |
+| Context richness | Limited | Rich metadata |
+| Development time | 2-3 weeks | 1 week |
+
+**Recommendation**: PIVOT to template mining approach for P0-R3
+
+## Implementation Estimate
+
+### Week 1: Core Infrastructure
+- Day 1-2: Create `TemplateConfigExtractor` service
+- Day 3: Implement caching layer
+- Day 4-5: Testing and optimization
+
+### Week 2: Integration
+- Day 1-2: Enhance `get_node_essentials` with examples
+- Day 3: Update tool documentation
+- Day 4-5: Integration testing
+
+**Total**: 2 weeks vs 3 weeks for original plan
+
+## Validation Tests
+
+```typescript
+// Test: Extract HTTP Request configs
+const configs = await extractor.extractConfigsForNode(
+  'n8n-nodes-base.httpRequest',
+  { complexity: 'simple', limit: 5 }
+);
+
+// Expected: 5 configs from top templates
+// - Simple URL fetch
+// - With authentication
+// - With custom headers
+// - With expressions
+// - With error handling
+
+// Test: Extract webhook configs
+const webhookConfigs = await extractor.extractConfigsForNode(
+  'n8n-nodes-base.webhook',
+  { limit: 3 }
+);
+
+// Expected: 3 configs showing different patterns
+// - Basic POST webhook
+// - With response node
+// - With binary data handling
+```
+
+## Risks and Mitigation
+
+### Risk 1: Template Quality Varies
+- **Mitigation**: Filter by views (popularity) and metadata complexity rating
+- Only use templates with >1000 views for examples
+
+### Risk 2: Decompression Performance
+- **Mitigation**: Cache decompressed popular templates
+- Implement lazy loading (decompress on demand)
+
+### Risk 3: Template-Specific Context
+- **Mitigation**: Extract only node configuration, strip workflow-specific context
+- Provide source attribution for context
+
+### Risk 4: Breaking Changes in Template Structure
+- **Mitigation**: Robust error handling in decompression
+- Fallback to cached configs if template fetch fails
+
+## Success Metrics
+
+**Before** (get_node_for_task):
+- 392 calls, 72% success rate
+- 28% failure rate
+- 31 task templates
+- 5.9% node coverage
+
+**Target** (template-based):
+- 90%+ success rate for configuration discovery
+- 100%+ node coverage
+- 2,646+ real-world examples
+- Self-updating from n8n.io
+
+## Next Steps
+
+1. ✅ Complete template database analysis
+2. ⏳ Create `TemplateConfigExtractor` service
+3. ⏳ Implement caching layer
+4. ⏳ Enhance `get_node_essentials` with examples
+5. ⏳ Update P0 implementation plan
+6. ⏳ Begin implementation
+
+## Conclusion
+
+The template database provides a vastly superior alternative to hardcoded task templates:
+
+- **2,646 templates** vs 31 tasks (85x more examples)
+- **103% node coverage** vs 5.9% coverage (17x improvement)
+- **Real-world configurations** vs synthetic examples
+- **Self-updating** vs manual maintenance
+- **Rich metadata** for semantic matching
+
+**Recommendation**: Pivot P0-R3 from "expand task library" to "mine template configurations"

docs/local/integration-tests-phase1-summary.md

@@ -0,0 +1,260 @@
+# Integration Tests Phase 1: Foundation - COMPLETED
+
+## Overview
+Phase 1 establishes the foundation for n8n API integration testing. All core utilities, fixtures, and infrastructure are now in place.
+
+## Branch
+`feat/integration-tests-foundation`
+
+## Completed Tasks
+
+### 1. Environment Configuration
+- ✅ Updated `.env.example` with integration testing configuration
+- ✅ Added environment variables for:
+  - n8n API credentials (`N8N_API_URL`, `N8N_API_KEY`)
+  - Webhook workflow IDs (4 workflows for GET/POST/PUT/DELETE)
+  - Test configuration (cleanup, tags, naming)
+- ✅ Included detailed setup instructions in comments
+
+### 2. Directory Structure
+```
+tests/integration/n8n-api/
+├── workflows/        (empty - for Phase 2+)
+├── executions/       (empty - for Phase 2+)
+├── system/           (empty - for Phase 2+)
+├── scripts/
+│   └── cleanup-orphans.ts
+└── utils/
+    ├── credentials.ts
+    ├── n8n-client.ts
+    ├── test-context.ts
+    ├── cleanup-helpers.ts
+    ├── fixtures.ts
+    ├── factories.ts
+    └── webhook-workflows.ts
+```
+
+### 3. Core Utilities
+
+#### `credentials.ts` (200 lines)
+- Environment-aware credential loading
+- Detects CI vs local environment automatically
+- Validation functions with helpful error messages
+- Non-throwing credential check functions
+
+**Key Functions:**
+- `getN8nCredentials()` - Load credentials from .env or GitHub secrets
+- `validateCredentials()` - Ensure required credentials are present
+- `validateWebhookWorkflows()` - Check webhook workflow IDs with setup instructions
+- `hasCredentials()` - Non-throwing credential check
+- `hasWebhookWorkflows()` - Non-throwing webhook check
+
+#### `n8n-client.ts` (45 lines)
+- Singleton n8n API client wrapper
+- Pre-configured with test credentials
+- Health check functionality
+
+**Key Functions:**
+- `getTestN8nClient()` - Get/create configured API client
+- `resetTestN8nClient()` - Reset client instance
+- `isN8nApiAccessible()` - Check API connectivity
+
+#### `test-context.ts` (120 lines)
+- Resource tracking for automatic cleanup
+- Test workflow naming utilities
+- Tag management
+
+**Key Functions:**
+- `createTestContext()` - Create context for tracking resources
+- `TestContext.trackWorkflow()` - Track workflow for cleanup
+- `TestContext.trackExecution()` - Track execution for cleanup
+- `TestContext.cleanup()` - Delete all tracked resources
+- `createTestWorkflowName()` - Generate unique workflow names
+- `getTestTag()` - Get configured test tag
+
+#### `cleanup-helpers.ts` (275 lines)
+- Multi-level cleanup strategies
+- Orphaned resource detection
+- Age-based execution cleanup
+- Tag-based workflow cleanup
+
+**Key Functions:**
+- `cleanupOrphanedWorkflows()` - Find and delete test workflows
+- `cleanupOldExecutions()` - Delete executions older than X hours
+- `cleanupAllTestResources()` - Comprehensive cleanup
+- `cleanupWorkflowsByTag()` - Delete workflows by tag
+- `cleanupExecutionsByWorkflow()` - Delete workflow's executions
+
+#### `fixtures.ts` (310 lines)
+- Pre-built workflow templates
+- All using FULL node type format (n8n-nodes-base.*)
+
+**Available Fixtures:**
+- `SIMPLE_WEBHOOK_WORKFLOW` - Single webhook node
+- `SIMPLE_HTTP_WORKFLOW` - Webhook + HTTP Request
+- `MULTI_NODE_WORKFLOW` - Complex branching workflow
+- `ERROR_HANDLING_WORKFLOW` - Error output configuration
+- `AI_AGENT_WORKFLOW` - Langchain agent node
+- `EXPRESSION_WORKFLOW` - n8n expressions testing
+
+**Helper Functions:**
+- `getFixture()` - Get fixture by name (with deep clone)
+- `createCustomWorkflow()` - Build custom workflow from nodes
+
+#### `factories.ts` (315 lines)
+- Dynamic test data generation
+- Node builders with sensible defaults
+- Workflow composition helpers
+
+**Node Factories:**
+- `createWebhookNode()` - Webhook node with customization
+- `createHttpRequestNode()` - HTTP Request node
+- `createSetNode()` - Set node with assignments
+- `createManualTriggerNode()` - Manual trigger node
+
+**Connection Factories:**
+- `createConnection()` - Simple node connection
+- `createSequentialWorkflow()` - Auto-connected sequential nodes
+- `createParallelWorkflow()` - Trigger with parallel branches
+- `createErrorHandlingWorkflow()` - Workflow with error handling
+
+**Utilities:**
+- `randomString()` - Generate random test data
+- `uniqueId()` - Unique IDs for testing
+- `createTestTags()` - Test workflow tags
+- `createWorkflowSettings()` - Common settings
+
+#### `webhook-workflows.ts` (215 lines)
+- Webhook workflow configuration templates
+- Setup instructions generator
+- URL generation utilities
+
+**Key Features:**
+- `WEBHOOK_WORKFLOW_CONFIGS` - Configurations for all 4 HTTP methods
+- `printSetupInstructions()` - Print detailed setup guide
+- `generateWebhookWorkflowJson()` - Generate workflow JSON
+- `exportAllWebhookWorkflows()` - Export all 4 configs
+- `getWebhookUrl()` - Get webhook URL for testing
+- `isValidWebhookWorkflow()` - Validate workflow structure
+
+### 4. Scripts
+
+#### `cleanup-orphans.ts` (40 lines)
+- Standalone cleanup script
+- Can be run manually or in CI
+- Comprehensive output logging
+
+**Usage:**
+```bash
+npm run test:cleanup:orphans
+```
+
+### 5. npm Scripts
+Added to `package.json`:
+```json
+{
+  "test:integration:n8n": "vitest run tests/integration/n8n-api",
+  "test:cleanup:orphans": "tsx tests/integration/n8n-api/scripts/cleanup-orphans.ts"
+}
+```
+
+## Code Quality
+
+### TypeScript
+- ✅ All code passes `npm run typecheck`
+- ✅ All code compiles with `npm run build`
+- ✅ No TypeScript errors
+- ✅ Proper type annotations throughout
+
+### Error Handling
+- ✅ Comprehensive error messages
+- ✅ Helpful setup instructions in error messages
+- ✅ Non-throwing validation functions where appropriate
+- ✅ Graceful handling of missing credentials
+
+### Documentation
+- ✅ All functions have JSDoc comments
+- ✅ Usage examples in comments
+- ✅ Clear parameter descriptions
+- ✅ Return type documentation
+
+## Files Created
+
+### Documentation
+1. `docs/local/integration-testing-plan.md` (550 lines)
+2. `docs/local/integration-tests-phase1-summary.md` (this file)
+
+### Code
+1. `.env.example` - Updated with test configuration (32 new lines)
+2. `package.json` - Added 2 npm scripts
+3. `tests/integration/n8n-api/utils/credentials.ts` (200 lines)
+4. `tests/integration/n8n-api/utils/n8n-client.ts` (45 lines)
+5. `tests/integration/n8n-api/utils/test-context.ts` (120 lines)
+6. `tests/integration/n8n-api/utils/cleanup-helpers.ts` (275 lines)
+7. `tests/integration/n8n-api/utils/fixtures.ts` (310 lines)
+8. `tests/integration/n8n-api/utils/factories.ts` (315 lines)
+9. `tests/integration/n8n-api/utils/webhook-workflows.ts` (215 lines)
+10. `tests/integration/n8n-api/scripts/cleanup-orphans.ts` (40 lines)
+
+**Total New Code:** ~1,520 lines of production-ready TypeScript
+
+## Next Steps (Phase 2)
+
+Phase 2 will implement the first actual integration tests:
+- Create workflow creation tests (10+ scenarios)
+- Test P0 bug fix (SHORT vs FULL node types)
+- Test workflow retrieval
+- Test workflow deletion
+
+**Branch:** `feat/integration-tests-workflow-creation`
+
+## Prerequisites for Running Tests
+
+Before running integration tests, you need to:
+
+1. **Set up n8n instance:**
+   - Local: `npx n8n start`
+   - Or use cloud/self-hosted n8n
+
+2. **Configure credentials in `.env`:**
+   ```bash
+   N8N_API_URL=http://localhost:5678
+   N8N_API_KEY=<your-api-key>
+   ```
+
+3. **Create 4 webhook workflows manually:**
+   - One for each HTTP method (GET, POST, PUT, DELETE)
+   - Activate each workflow in n8n UI
+   - Set workflow IDs in `.env`:
+     ```bash
+     N8N_TEST_WEBHOOK_GET_ID=<workflow-id>
+     N8N_TEST_WEBHOOK_POST_ID=<workflow-id>
+     N8N_TEST_WEBHOOK_PUT_ID=<workflow-id>
+     N8N_TEST_WEBHOOK_DELETE_ID=<workflow-id>
+     ```
+
+See `docs/local/integration-testing-plan.md` for detailed setup instructions.
+
+## Success Metrics
+
+Phase 1 Success Criteria - ALL MET:
+- ✅ All utilities implemented and tested
+- ✅ TypeScript compiles without errors
+- ✅ Code follows project conventions
+- ✅ Comprehensive documentation
+- ✅ Environment configuration complete
+- ✅ Cleanup infrastructure in place
+- ✅ Ready for Phase 2 test implementation
+
+## Lessons Learned
+
+1. **N8nApiClient Constructor:** Uses config object, not separate parameters
+2. **Cursor Handling:** n8n API returns `null` for no more pages, need to convert to `undefined`
+3. **Workflow ID Validation:** Some workflows might have undefined IDs, need null checks
+4. **Connection Types:** Error connections need explicit typing to avoid TypeScript errors
+5. **Webhook Activation:** Cannot be done via API, must be manual - hence pre-activated workflow requirement
+
+## Time Invested
+
+Phase 1 actual time: ~2 hours (estimated 2-3 days in plan)
+- Faster than expected due to clear architecture and reusable patterns

docs/n8n-integration-implementation-plan.md

@@ -0,0 +1,514 @@
+# n8n MCP Client Tool Integration - Implementation Plan (Simplified)
+
+## Overview
+
+This document provides a **simplified** implementation plan for making n8n-mcp compatible with n8n's MCP Client Tool (v1.1). Based on expert review, we're taking a minimal approach that extends the existing single-session server rather than creating new architecture.
+
+## Key Design Principles
+
+1. **Minimal Changes**: Extend existing single-session server with n8n compatibility mode
+2. **No Overengineering**: No complex session management or multi-session architecture
+3. **Docker-Native**: Separate Docker image for n8n deployment
+4. **Remote Deployment**: Designed to run alongside n8n in production
+5. **Backward Compatible**: Existing functionality remains unchanged
+
+## Prerequisites
+
+- Docker and Docker Compose
+- n8n version 1.104.2 or higher (with MCP Client Tool v1.1)
+- Basic understanding of Docker networking
+
+## Implementation Approach
+
+Instead of creating new multi-session architecture, we'll extend the existing single-session server with an n8n compatibility mode. This approach was recommended by all three expert reviewers as simpler and more maintainable.
+
+## Architecture Changes
+
+```
+src/
+├── http-server-single-session.ts  # MODIFY: Add n8n mode flag
+└── mcp/
+    └── server.ts                  # NO CHANGES NEEDED
+
+Docker/
+├── Dockerfile.n8n                 # NEW: n8n-specific image
+├── docker-compose.n8n.yml         # NEW: Simplified stack
+└── .github/workflows/
+    └── docker-build-n8n.yml       # NEW: Build workflow
+```
+
+## Implementation Steps
+
+### Step 1: Modify Existing Single-Session Server
+
+#### 1.1 Update `src/http-server-single-session.ts`
+
+Add n8n compatibility mode to the existing server with minimal changes:
+
+```typescript
+// Add these constants at the top (after imports)
+const PROTOCOL_VERSION = "2024-11-05";
+const N8N_MODE = process.env.N8N_MODE === 'true';
+
+// In the constructor or start method, add logging
+if (N8N_MODE) {
+  logger.info('Running in n8n compatibility mode');
+}
+
+// In setupRoutes method, add the protocol version endpoint
+if (N8N_MODE) {
+  app.get('/mcp', (req, res) => {
+    res.json({
+      protocolVersion: PROTOCOL_VERSION,
+      serverInfo: {
+        name: "n8n-mcp",
+        version: PROJECT_VERSION,
+        capabilities: {
+          tools: true,
+          resources: false,
+          prompts: false,
+        },
+      },
+    });
+  });
+}
+
+// In handleMCPRequest method, add session header
+if (N8N_MODE && this.session) {
+  res.setHeader('Mcp-Session-Id', this.session.sessionId);
+}
+
+// Update error handling to use JSON-RPC format
+catch (error) {
+  logger.error('MCP request error:', error);
+  
+  if (N8N_MODE) {
+    res.status(500).json({
+      jsonrpc: '2.0',
+      error: {
+        code: -32603,
+        message: 'Internal error',
+        data: error instanceof Error ? error.message : 'Unknown error',
+      },
+      id: null,
+    });
+  } else {
+    // Keep existing error handling for backward compatibility
+    res.status(500).json({ 
+      error: 'Internal server error',
+      details: error instanceof Error ? error.message : 'Unknown error'
+    });
+  }
+}
+```
+
+That's it! No new files, no complex session management. Just a few lines of code.
+
+### Step 2: Update Package Scripts
+
+#### 2.1 Update `package.json`
+
+Add a simple script for n8n mode:
+
+```json
+{
+  "scripts": {
+    "start:n8n": "N8N_MODE=true MCP_MODE=http node dist/mcp/index.js"
+  }
+}
+```
+
+### Step 3: Create Docker Infrastructure for n8n
+
+#### 3.1 Create `Dockerfile.n8n`
+
+```dockerfile
+# Dockerfile.n8n - Optimized for n8n integration
+FROM node:22-alpine AS builder
+
+WORKDIR /app
+
+# Install build dependencies
+RUN apk add --no-cache python3 make g++
+
+# Copy package files
+COPY package*.json tsconfig*.json ./
+
+# Install ALL dependencies
+RUN npm ci --no-audit --no-fund
+
+# Copy source and build
+COPY src ./src
+RUN npm run build && npm run rebuild
+
+# Runtime stage
+FROM node:22-alpine
+
+WORKDIR /app
+
+# Install runtime dependencies
+RUN apk add --no-cache curl dumb-init
+
+# Create non-root user
+RUN addgroup -g 1001 -S nodejs && adduser -S nodejs -u 1001
+
+# Copy application from builder
+COPY --from=builder --chown=nodejs:nodejs /app/dist ./dist
+COPY --from=builder --chown=nodejs:nodejs /app/data ./data
+COPY --from=builder --chown=nodejs:nodejs /app/node_modules ./node_modules
+COPY --chown=nodejs:nodejs package.json ./
+
+USER nodejs
+
+EXPOSE 3001
+
+HEALTHCHECK CMD curl -f http://localhost:3001/health || exit 1
+
+ENTRYPOINT ["dumb-init", "--"]
+CMD ["node", "dist/mcp/index.js"]
+```
+
+#### 3.2 Create `docker-compose.n8n.yml`
+
+```yaml
+# docker-compose.n8n.yml - Simple stack for n8n + n8n-mcp
+version: '3.8'
+
+services:
+  n8n:
+    image: n8nio/n8n:latest
+    container_name: n8n
+    restart: unless-stopped
+    ports:
+      - "5678:5678"
+    environment:
+      - N8N_BASIC_AUTH_ACTIVE=${N8N_BASIC_AUTH_ACTIVE:-true}
+      - N8N_BASIC_AUTH_USER=${N8N_USER:-admin}
+      - N8N_BASIC_AUTH_PASSWORD=${N8N_PASSWORD:-changeme}
+      - N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true
+    volumes:
+      - n8n_data:/home/node/.n8n
+    networks:
+      - n8n-net
+    depends_on:
+      n8n-mcp:
+        condition: service_healthy
+
+  n8n-mcp:
+    image: ghcr.io/${GITHUB_USER:-czlonkowski}/n8n-mcp-n8n:latest
+    build:
+      context: .
+      dockerfile: Dockerfile.n8n
+    container_name: n8n-mcp
+    restart: unless-stopped
+    environment:
+      - MCP_MODE=http
+      - N8N_MODE=true
+      - AUTH_TOKEN=${MCP_AUTH_TOKEN}
+      - NODE_ENV=production
+      - HTTP_PORT=3001
+    networks:
+      - n8n-net
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3001/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+
+networks:
+  n8n-net:
+    driver: bridge
+
+volumes:
+  n8n_data:
+```
+
+#### 3.3 Create `.env.n8n.example`
+
+```bash
+# .env.n8n.example - Copy to .env and configure
+
+# n8n Configuration
+N8N_USER=admin
+N8N_PASSWORD=changeme
+N8N_BASIC_AUTH_ACTIVE=true
+
+# MCP Configuration
+# Generate with: openssl rand -base64 32
+MCP_AUTH_TOKEN=your-secure-token-minimum-32-characters
+
+# GitHub username for image registry
+GITHUB_USER=czlonkowski
+```
+
+### Step 4: Create GitHub Actions Workflow
+
+#### 4.1 Create `.github/workflows/docker-build-n8n.yml`
+
+```yaml
+name: Build n8n Docker Image
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+    paths:
+      - 'src/**'
+      - 'package*.json'
+      - 'Dockerfile.n8n'
+  workflow_dispatch:
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}-n8n
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+      
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: docker/setup-buildx-action@v3
+      
+      - uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+          
+      - uses: docker/metadata-action@v5
+        id: meta
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=branch
+            type=semver,pattern={{version}}
+            type=raw,value=latest,enable={{is_default_branch}}
+            
+      - uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: ./Dockerfile.n8n
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+```
+
+### Step 5: Testing
+
+#### 5.1 Unit Tests for n8n Mode
+
+Create `tests/unit/http-server-n8n-mode.test.ts`:
+
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+import request from 'supertest';
+
+describe('n8n Mode', () => {
+  it('should return protocol version on GET /mcp', async () => {
+    process.env.N8N_MODE = 'true';
+    const app = await createTestApp();
+    
+    const response = await request(app)
+      .get('/mcp')
+      .expect(200);
+    
+    expect(response.body.protocolVersion).toBe('2024-11-05');
+    expect(response.body.serverInfo.capabilities.tools).toBe(true);
+  });
+  
+  it('should include session ID in response headers', async () => {
+    process.env.N8N_MODE = 'true';
+    const app = await createTestApp();
+    
+    const response = await request(app)
+      .post('/mcp')
+      .set('Authorization', 'Bearer test-token')
+      .send({ jsonrpc: '2.0', method: 'initialize', id: 1 });
+    
+    expect(response.headers['mcp-session-id']).toBeDefined();
+  });
+  
+  it('should format errors as JSON-RPC', async () => {
+    process.env.N8N_MODE = 'true';
+    const app = await createTestApp();
+    
+    const response = await request(app)
+      .post('/mcp')
+      .send({ invalid: 'request' })
+      .expect(500);
+    
+    expect(response.body.jsonrpc).toBe('2.0');
+    expect(response.body.error.code).toBe(-32603);
+  });
+});
+```
+
+#### 5.2 Quick Deployment Script
+
+Create `deploy/quick-deploy-n8n.sh`:
+
+```bash
+#!/bin/bash
+set -e
+
+echo "🚀 Quick Deploy n8n + n8n-mcp"
+
+# Check prerequisites
+command -v docker >/dev/null 2>&1 || { echo "Docker required"; exit 1; }
+command -v docker-compose >/dev/null 2>&1 || { echo "Docker Compose required"; exit 1; }
+
+# Generate auth token if not exists
+if [ ! -f .env ]; then
+  cp .env.n8n.example .env
+  TOKEN=$(openssl rand -base64 32)
+  sed -i "s/your-secure-token-minimum-32-characters/$TOKEN/" .env
+  echo "Generated MCP_AUTH_TOKEN: $TOKEN"
+fi
+
+# Deploy
+docker-compose -f docker-compose.n8n.yml up -d
+
+echo ""
+echo "✅ Deployment complete!"
+echo ""
+echo "📋 Next steps:"
+echo "1. Access n8n at http://localhost:5678"
+echo "   Username: admin (or check .env)"
+echo "   Password: changeme (or check .env)"
+echo ""
+echo "2. Create a workflow with MCP Client Tool:"
+echo "   - Server URL: http://n8n-mcp:3001/mcp"
+echo "   - Authentication: Bearer Token"
+echo "   - Token: Check .env file for MCP_AUTH_TOKEN"
+echo ""
+echo "📊 View logs: docker-compose -f docker-compose.n8n.yml logs -f"
+echo "🛑 Stop: docker-compose -f docker-compose.n8n.yml down"
+```
+
+## Implementation Checklist (Simplified)
+
+### Code Changes
+- [ ] Add N8N_MODE flag to `http-server-single-session.ts`
+- [ ] Add protocol version endpoint (GET /mcp) when N8N_MODE=true
+- [ ] Add Mcp-Session-Id header to responses
+- [ ] Update error responses to JSON-RPC format when N8N_MODE=true
+- [ ] Add npm script `start:n8n` to package.json
+
+### Docker Infrastructure
+- [ ] Create `Dockerfile.n8n` for n8n-specific image
+- [ ] Create `docker-compose.n8n.yml` for simple deployment
+- [ ] Create `.env.n8n.example` template
+- [ ] Create GitHub Actions workflow `docker-build-n8n.yml`
+- [ ] Create `deploy/quick-deploy-n8n.sh` script
+
+### Testing
+- [ ] Write unit tests for n8n mode functionality
+- [ ] Test with actual n8n MCP Client Tool
+- [ ] Verify protocol version endpoint
+- [ ] Test authentication flow
+- [ ] Validate error formatting
+
+### Documentation
+- [ ] Update README with n8n deployment section
+- [ ] Document N8N_MODE environment variable
+- [ ] Add troubleshooting guide for common issues
+
+## Quick Start Guide
+
+### 1. One-Command Deployment
+
+```bash
+# Clone and deploy
+git clone https://github.com/czlonkowski/n8n-mcp.git
+cd n8n-mcp
+./deploy/quick-deploy-n8n.sh
+```
+
+### 2. Manual Configuration in n8n
+
+After deployment, configure the MCP Client Tool in n8n:
+
+1. Open n8n at `http://localhost:5678`
+2. Create a new workflow
+3. Add "MCP Client Tool" node (under AI category)
+4. Configure:
+   - **Server URL**: `http://n8n-mcp:3001/mcp`
+   - **Authentication**: Bearer Token
+   - **Token**: Check your `.env` file for MCP_AUTH_TOKEN
+5. Select a tool (e.g., `list_nodes`)
+6. Execute the workflow
+
+### 3. Production Deployment
+
+For production with SSL, use a reverse proxy:
+
+```nginx
+# nginx configuration
+server {
+    listen 443 ssl;
+    server_name n8n.yourdomain.com;
+    
+    location / {
+        proxy_pass http://localhost:5678;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+    }
+}
+```
+
+The MCP server should remain internal only - n8n connects via Docker network.
+
+## Success Criteria
+
+The implementation is successful when:
+
+1. **Minimal Code Changes**: Only ~20 lines added to existing server
+2. **Protocol Compliance**: GET /mcp returns correct protocol version
+3. **n8n Connection**: MCP Client Tool connects successfully
+4. **Tool Execution**: Tools work without modification
+5. **Backward Compatible**: Existing Claude Desktop usage unaffected
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"Protocol version mismatch"**
+   - Ensure N8N_MODE=true is set
+   - Check GET /mcp returns "2024-11-05"
+
+2. **"Authentication failed"**
+   - Verify AUTH_TOKEN matches in .env and n8n
+   - Token must be 32+ characters
+   - Use "Bearer Token" auth type in n8n
+
+3. **"Connection refused"**
+   - Check containers are on same network
+   - Use internal hostname: `http://n8n-mcp:3001/mcp`
+   - Verify health check passes
+
+4. **Testing the Setup**
+   ```bash
+   # Check protocol version
+   docker exec n8n-mcp curl http://localhost:3001/mcp
+   
+   # View logs
+   docker-compose -f docker-compose.n8n.yml logs -f n8n-mcp
+   ```
+
+## Summary
+
+This simplified approach:
+- **Extends existing code** rather than creating new architecture
+- **Adds n8n compatibility** with minimal changes
+- **Uses separate Docker image** for clean deployment
+- **Maintains backward compatibility** for existing users
+- **Avoids overengineering** with simple, practical solutions
+
+Total implementation effort: ~2-3 hours (vs. 2-3 days for multi-session approach)

docs/test-artifacts.md

@@ -0,0 +1,146 @@
+# Test Artifacts Documentation
+
+This document describes the comprehensive test result artifact storage system implemented in the n8n-mcp project.
+
+## Overview
+
+The test artifact system captures, stores, and presents test results in multiple formats to facilitate debugging, analysis, and historical tracking of test performance.
+
+## Artifact Types
+
+### 1. Test Results
+- **JUnit XML** (`test-results/junit.xml`): Standard format for CI integration
+- **JSON Results** (`test-results/results.json`): Detailed test data for analysis
+- **HTML Report** (`test-results/html/index.html`): Interactive test report
+- **Test Summary** (`test-summary.md`): Markdown summary for PR comments
+
+### 2. Coverage Reports
+- **LCOV** (`coverage/lcov.info`): Standard coverage format
+- **HTML Coverage** (`coverage/html/index.html`): Interactive coverage browser
+- **Coverage Summary** (`coverage/coverage-summary.json`): JSON coverage data
+
+### 3. Benchmark Results
+- **Benchmark JSON** (`benchmark-results.json`): Raw benchmark data
+- **Comparison Reports** (`benchmark-comparison.md`): PR benchmark comparisons
+
+### 4. Detailed Reports
+- **HTML Report** (`test-reports/report.html`): Comprehensive styled report
+- **Markdown Report** (`test-reports/report.md`): Full markdown report
+- **JSON Report** (`test-reports/report.json`): Complete test data
+
+## GitHub Actions Integration
+
+### Test Workflow (`test.yml`)
+
+The main test workflow:
+1. Runs tests with coverage using multiple reporters
+2. Generates test summaries and detailed reports
+3. Uploads artifacts with metadata
+4. Posts summaries to PRs
+5. Creates a combined artifact index
+
+### Benchmark PR Workflow (`benchmark-pr.yml`)
+
+For pull requests:
+1. Runs benchmarks on PR branch
+2. Runs benchmarks on base branch
+3. Compares results
+4. Posts comparison to PR
+5. Sets status checks for regressions
+
+## Artifact Retention
+
+- **Test Results**: 30 days
+- **Coverage Reports**: 30 days
+- **Benchmark Results**: 30 days
+- **Combined Results**: 90 days
+- **Test Metadata**: 30 days
+
+## PR Comment Integration
+
+The system automatically:
+- Posts test summaries to PR comments
+- Updates existing comments instead of creating duplicates
+- Includes links to full artifacts
+- Shows coverage and benchmark changes
+
+## Job Summary
+
+Each workflow run includes a job summary with:
+- Test results overview
+- Coverage summary
+- Benchmark results
+- Direct links to download artifacts
+
+## Local Development
+
+### Running Tests with Reports
+
+```bash
+# Run tests with all reporters
+CI=true npm run test:coverage
+
+# Generate detailed reports
+node scripts/generate-detailed-reports.js
+
+# Generate test summary
+node scripts/generate-test-summary.js
+
+# Compare benchmarks
+node scripts/compare-benchmarks.js benchmark-results.json benchmark-baseline.json
+```
+
+### Report Locations
+
+When running locally, reports are generated in:
+- `test-results/` - Vitest outputs
+- `test-reports/` - Detailed reports
+- `coverage/` - Coverage reports
+- Root directory - Summary files
+
+## Report Formats
+
+### HTML Report Features
+- Responsive design
+- Test suite breakdown
+- Failed test details with error messages
+- Coverage visualization with progress bars
+- Benchmark performance metrics
+- Sortable tables
+
+### Markdown Report Features
+- GitHub-compatible formatting
+- Summary statistics
+- Failed test listings
+- Coverage breakdown
+- Benchmark comparisons
+
+### JSON Report Features
+- Complete test data
+- Programmatic access
+- Historical comparison
+- CI/CD integration
+
+## Best Practices
+
+1. **Always Check Artifacts**: When tests fail in CI, download and review the HTML report
+2. **Monitor Coverage**: Use the coverage reports to identify untested code
+3. **Track Benchmarks**: Review benchmark comparisons on performance-critical PRs
+4. **Archive Important Runs**: Download artifacts from significant releases
+
+## Troubleshooting
+
+### Missing Artifacts
+- Check if tests ran to completion
+- Verify artifact upload steps executed
+- Check retention period hasn't expired
+
+### Report Generation Failures
+- Ensure all dependencies are installed
+- Check for valid test/coverage output files
+- Review workflow logs for errors
+
+### PR Comment Issues
+- Verify GitHub Actions permissions
+- Check bot authentication
+- Review comment posting logs

docs/testing-architecture.md

@@ -0,0 +1,935 @@
+# n8n-MCP Testing Architecture
+
+## Overview
+
+This document describes the comprehensive testing infrastructure implemented for the n8n-MCP project. The testing suite includes 3,336 tests split between unit and integration tests, benchmarks, and a complete CI/CD pipeline ensuring code quality and reliability.
+
+### Test Suite Statistics (October 2025)
+
+- **Total Tests**: 3,336 tests
+  - **Unit Tests**: 2,766 tests - Isolated component testing with mocks
+  - **Integration Tests**: 570 tests - Full system behavior validation
+    - n8n API Integration: 172 tests (all 18 MCP handler tools)
+    - MCP Protocol: 119 tests (protocol compliance, session management)
+    - Database: 226 tests (repository operations, transactions, FTS5)
+    - Templates: 35 tests (fetching, storage, metadata)
+    - Docker: 18 tests (configuration, security)
+- **Test Files**:
+  - 106 unit test files
+  - 41 integration test files
+  - Total: 147 test files
+- **Test Execution Time**:
+  - Unit tests: ~2 minutes with coverage
+  - Integration tests: ~30 seconds
+  - Total CI time: ~3 minutes
+- **Success Rate**: 100% (all tests passing in CI)
+- **CI/CD Pipeline**: Fully automated with GitHub Actions
+- **Test Artifacts**: JUnit XML, coverage reports, benchmark results
+- **Parallel Execution**: Configurable with thread pool
+
+## Testing Framework: Vitest
+
+We use **Vitest** as our primary testing framework, chosen for its:
+- **Speed**: Native ESM support and fast execution
+- **TypeScript Integration**: First-class TypeScript support
+- **Watch Mode**: Instant feedback during development
+- **Jest Compatibility**: Easy migration from Jest
+- **Built-in Mocking**: Powerful mocking capabilities
+- **Coverage**: Integrated code coverage with v8
+
+### Configuration
+
+```typescript
+// vitest.config.ts
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    setupFiles: ['./tests/setup/global-setup.ts'],
+    pool: 'threads',
+    poolOptions: {
+      threads: {
+        singleThread: process.env.TEST_PARALLEL !== 'true',
+        maxThreads: parseInt(process.env.TEST_MAX_WORKERS || '4', 10)
+      }
+    },
+    coverage: {
+      provider: 'v8',
+      reporter: ['lcov', 'html', 'text-summary'],
+      exclude: ['node_modules/', 'tests/', '**/*.test.ts', 'scripts/']
+    }
+  },
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+      '@tests': path.resolve(__dirname, './tests')
+    }
+  }
+});
+```
+
+## Directory Structure
+
+```
+tests/
+├── unit/                        # Unit tests with mocks (2,766 tests, 106 files)
+│   ├── __mocks__/              # Mock implementations
+│   │   └── n8n-nodes-base.test.ts
+│   ├── database/               # Database layer tests
+│   │   ├── database-adapter-unit.test.ts
+│   │   ├── node-repository-core.test.ts
+│   │   └── template-repository-core.test.ts
+│   ├── docker/                 # Docker configuration tests
+│   │   ├── config-security.test.ts
+│   │   ├── edge-cases.test.ts
+│   │   ├── parse-config.test.ts
+│   │   └── serve-command.test.ts
+│   ├── http-server/            # HTTP server tests
+│   │   └── multi-tenant-support.test.ts
+│   ├── loaders/                # Node loader tests
+│   │   └── node-loader.test.ts
+│   ├── mappers/                # Data mapper tests
+│   │   └── docs-mapper.test.ts
+│   ├── mcp/                    # MCP server and tools tests
+│   │   ├── handlers-n8n-manager.test.ts
+│   │   ├── handlers-workflow-diff.test.ts
+│   │   ├── tools-documentation.test.ts
+│   │   └── tools.test.ts
+│   ├── parsers/                # Parser tests
+│   │   ├── node-parser.test.ts
+│   │   ├── property-extractor.test.ts
+│   │   └── simple-parser.test.ts
+│   ├── scripts/                # Script tests
+│   │   └── fetch-templates-extraction.test.ts
+│   ├── services/               # Service layer tests (largest test suite)
+│   │   ├── config-validator.test.ts
+│   │   ├── enhanced-config-validator.test.ts
+│   │   ├── example-generator.test.ts
+│   │   ├── expression-validator.test.ts
+│   │   ├── n8n-api-client.test.ts
+│   │   ├── n8n-validation.test.ts
+│   │   ├── node-specific-validators.test.ts
+│   │   ├── property-dependencies.test.ts
+│   │   ├── property-filter.test.ts
+│   │   ├── task-templates.test.ts
+│   │   ├── workflow-diff-engine.test.ts
+│   │   ├── workflow-validator-comprehensive.test.ts
+│   │   └── workflow-validator.test.ts
+│   ├── telemetry/              # Telemetry tests
+│   │   └── telemetry-manager.test.ts
+│   └── utils/                  # Utility function tests
+│       ├── cache-utils.test.ts
+│       └── database-utils.test.ts
+├── integration/                 # Integration tests (570 tests, 41 files)
+│   ├── n8n-api/                # n8n API integration tests (172 tests, 18 files)
+│   │   ├── executions/         # Execution management tests
+│   │   │   ├── get-execution.test.ts
+│   │   │   └── list-executions.test.ts
+│   │   ├── system/             # System tool tests
+│   │   │   ├── diagnostic.test.ts
+│   │   │   ├── health-check.test.ts
+│   │   │   └── list-tools.test.ts
+│   │   ├── utils/              # Test utilities
+│   │   │   ├── mcp-context.ts
+│   │   │   └── response-types.ts
+│   │   └── workflows/          # Workflow management tests
+│   │       ├── autofix-workflow.test.ts
+│   │       ├── create-workflow.test.ts
+│   │       ├── delete-workflow.test.ts
+│   │       ├── get-workflow-details.test.ts
+│   │       ├── get-workflow-minimal.test.ts
+│   │       ├── get-workflow-structure.test.ts
+│   │       ├── get-workflow.test.ts
+│   │       ├── list-workflows.test.ts
+│   │       ├── update-full-workflow.test.ts
+│   │       ├── update-partial-workflow.test.ts
+│   │       └── validate-workflow.test.ts
+│   ├── database/               # Database integration tests (226 tests)
+│   │   ├── connection-management.test.ts
+│   │   ├── fts5-search.test.ts
+│   │   ├── node-repository.test.ts
+│   │   ├── performance.test.ts
+│   │   ├── template-node-configs.test.ts
+│   │   ├── template-repository.test.ts
+│   │   └── transactions.test.ts
+│   ├── docker/                 # Docker integration tests (18 tests)
+│   │   ├── docker-config.test.ts
+│   │   └── docker-entrypoint.test.ts
+│   ├── mcp-protocol/           # MCP protocol tests (119 tests)
+│   │   ├── basic-connection.test.ts
+│   │   ├── error-handling.test.ts
+│   │   ├── performance.test.ts
+│   │   ├── protocol-compliance.test.ts
+│   │   ├── session-management.test.ts
+│   │   ├── tool-invocation.test.ts
+│   │   └── workflow-error-validation.test.ts
+│   ├── templates/              # Template tests (35 tests)
+│   │   └── metadata-operations.test.ts
+│   └── setup/                  # Integration test setup
+│       ├── integration-setup.ts
+│       └── msw-test-server.ts
+├── benchmarks/                  # Performance benchmarks
+│   ├── database-queries.bench.ts
+│   └── sample.bench.ts
+├── setup/                       # Global test configuration
+│   ├── global-setup.ts         # Global test setup
+│   ├── msw-setup.ts            # Mock Service Worker setup
+│   └── test-env.ts             # Test environment configuration
+├── utils/                       # Test utilities
+│   ├── assertions.ts           # Custom assertions
+│   ├── builders/               # Test data builders
+│   │   └── workflow.builder.ts
+│   ├── data-generators.ts      # Test data generators
+│   ├── database-utils.ts       # Database test utilities
+│   └── test-helpers.ts         # General test helpers
+├── mocks/                       # Mock implementations
+│   └── n8n-api/               # n8n API mocks
+│       ├── handlers.ts        # MSW request handlers
+│       └── data/              # Mock data
+└── fixtures/                    # Test fixtures
+    ├── database/               # Database fixtures
+    ├── factories/              # Data factories
+    └── workflows/              # Workflow fixtures
+```
+
+## Mock Strategy
+
+### 1. Mock Service Worker (MSW) for API Mocking
+
+We use MSW for intercepting and mocking HTTP requests:
+
+```typescript
+// tests/mocks/n8n-api/handlers.ts
+import { http, HttpResponse } from 'msw';
+
+export const handlers = [
+  // Workflow endpoints
+  http.get('*/workflows/:id', ({ params }) => {
+    const workflow = mockWorkflows.find(w => w.id === params.id);
+    if (!workflow) {
+      return new HttpResponse(null, { status: 404 });
+    }
+    return HttpResponse.json(workflow);
+  }),
+
+  // Execution endpoints
+  http.post('*/workflows/:id/run', async ({ params, request }) => {
+    const body = await request.json();
+    return HttpResponse.json({
+      executionId: generateExecutionId(),
+      status: 'running'
+    });
+  })
+];
+```
+
+### 2. Database Mocking
+
+For unit tests, we mock the database layer:
+
+```typescript
+// tests/unit/__mocks__/better-sqlite3.ts
+import { vi } from 'vitest';
+
+export default vi.fn(() => ({
+  prepare: vi.fn(() => ({
+    all: vi.fn().mockReturnValue([]),
+    get: vi.fn().mockReturnValue(undefined),
+    run: vi.fn().mockReturnValue({ changes: 1 }),
+    finalize: vi.fn()
+  })),
+  exec: vi.fn(),
+  close: vi.fn(),
+  pragma: vi.fn()
+}));
+```
+
+### 3. MCP SDK Mocking
+
+For testing MCP protocol interactions:
+
+```typescript
+// tests/integration/mcp-protocol/test-helpers.ts
+export class TestableN8NMCPServer extends N8NMCPServer {
+  private transports = new Set<Transport>();
+  
+  async connectToTransport(transport: Transport): Promise<void> {
+    this.transports.add(transport);
+    await this.connect(transport);
+  }
+  
+  async close(): Promise<void> {
+    for (const transport of this.transports) {
+      await transport.close();
+    }
+    this.transports.clear();
+  }
+}
+```
+
+## Test Patterns and Utilities
+
+### 1. Database Test Utilities
+
+```typescript
+// tests/utils/database-utils.ts
+export class TestDatabase {
+  constructor(options: TestDatabaseOptions = {}) {
+    this.options = {
+      mode: 'memory',
+      enableFTS5: true,
+      ...options
+    };
+  }
+
+  async initialize(): Promise<Database.Database> {
+    const db = this.options.mode === 'memory' 
+      ? new Database(':memory:') 
+      : new Database(this.dbPath);
+    
+    if (this.options.enableFTS5) {
+      await this.enableFTS5(db);
+    }
+    
+    return db;
+  }
+}
+```
+
+### 2. Data Generators
+
+```typescript
+// tests/utils/data-generators.ts
+export class TestDataGenerator {
+  static generateNode(overrides: Partial<ParsedNode> = {}): ParsedNode {
+    return {
+      nodeType: `test.node${faker.number.int()}`,
+      displayName: faker.commerce.productName(),
+      description: faker.lorem.sentence(),
+      properties: this.generateProperties(5),
+      ...overrides
+    };
+  }
+
+  static generateWorkflow(nodeCount = 3): any {
+    const nodes = Array.from({ length: nodeCount }, (_, i) => ({
+      id: `node_${i}`,
+      type: 'test.node',
+      position: [i * 100, 0],
+      parameters: {}
+    }));
+    
+    return { nodes, connections: {} };
+  }
+}
+```
+
+### 3. Custom Assertions
+
+```typescript
+// tests/utils/assertions.ts
+export function expectValidMCPResponse(response: any): void {
+  expect(response).toBeDefined();
+  expect(response.content).toBeDefined();
+  expect(Array.isArray(response.content)).toBe(true);
+  expect(response.content[0]).toHaveProperty('type', 'text');
+  expect(response.content[0]).toHaveProperty('text');
+}
+
+export function expectNodeStructure(node: any): void {
+  expect(node).toHaveProperty('nodeType');
+  expect(node).toHaveProperty('displayName');
+  expect(node).toHaveProperty('properties');
+  expect(Array.isArray(node.properties)).toBe(true);
+}
+```
+
+## Unit Testing
+
+Our unit tests focus on testing individual components in isolation with mocked dependencies:
+
+### Service Layer Tests
+
+The bulk of our unit tests (400+ tests) are in the services layer:
+
+```typescript
+// tests/unit/services/workflow-validator-comprehensive.test.ts
+describe('WorkflowValidator Comprehensive Tests', () => {
+  it('should validate complex workflow with AI nodes', () => {
+    const workflow = {
+      nodes: [
+        {
+          id: 'ai_agent',
+          type: '@n8n/n8n-nodes-langchain.agent',
+          parameters: { prompt: 'Analyze data' }
+        }
+      ],
+      connections: {}
+    };
+    
+    const result = validator.validateWorkflow(workflow);
+    expect(result.valid).toBe(true);
+  });
+});
+```
+
+### Parser Tests
+
+Testing the node parsing logic:
+
+```typescript
+// tests/unit/parsers/property-extractor.test.ts
+describe('PropertyExtractor', () => {
+  it('should extract nested properties correctly', () => {
+    const node = {
+      properties: [
+        {
+          displayName: 'Options',
+          name: 'options',
+          type: 'collection',
+          options: [
+            { name: 'timeout', type: 'number' }
+          ]
+        }
+      ]
+    };
+    
+    const extracted = extractor.extractProperties(node);
+    expect(extracted).toHaveProperty('options.timeout');
+  });
+});
+```
+
+### Mock Testing
+
+Testing our mock implementations:
+
+```typescript
+// tests/unit/__mocks__/n8n-nodes-base.test.ts
+describe('n8n-nodes-base mock', () => {
+  it('should provide mocked node definitions', () => {
+    const httpNode = mockNodes['n8n-nodes-base.httpRequest'];
+    expect(httpNode).toBeDefined();
+    expect(httpNode.description.displayName).toBe('HTTP Request');
+  });
+});
+```
+
+## Integration Testing
+
+Our integration tests verify the complete system behavior across 570 tests in four major categories:
+
+### n8n API Integration Testing (172 tests)
+
+The n8n API integration tests verify all 18 MCP handler tools against a real n8n instance. These tests ensure our product layer (MCP handlers) work correctly end-to-end, not just the raw API client.
+
+**Test Organization:**
+- **Workflows** (11 handlers): Create, read, update (full/partial), delete, list, validate, autofix
+- **Executions** (2 handlers): Get execution details, list executions
+- **System** (3 handlers): Health check, list available tools, diagnostics
+
+**Example:**
+```typescript
+// tests/integration/n8n-api/workflows/create-workflow.test.ts
+describe('Integration: handleCreateWorkflow', () => {
+  it('should create a simple two-node workflow', async () => {
+    const response = await handleCreateWorkflow(
+      {
+        params: {
+          arguments: {
+            name: 'Test Workflow',
+            nodes: [webhook, setNode],
+            connections: { Webhook: { main: [[{ node: 'Set', type: 'main', index: 0 }]] } }
+          }
+        }
+      },
+      mcpContext
+    );
+
+    expect(response.success).toBe(true);
+    const workflow = response.data as WorkflowData;
+    expect(workflow.id).toBeDefined();
+    expect(workflow.nodes).toHaveLength(2);
+
+    // Cleanup
+    await handleDeleteWorkflow({ params: { arguments: { id: workflow.id } } }, mcpContext);
+  });
+});
+```
+
+**Key Features Tested:**
+- Real workflow creation, modification, deletion with cleanup
+- TypeScript type safety with response interfaces
+- Complete coverage of all 18 n8n API tools
+- Proper error handling and edge cases
+- Response format validation
+
+### MCP Protocol Testing (119 tests)
+
+```typescript
+// tests/integration/mcp-protocol/tool-invocation.test.ts
+describe('MCP Tool Invocation', () => {
+  let mcpServer: TestableN8NMCPServer;
+  let client: Client;
+
+  beforeEach(async () => {
+    mcpServer = new TestableN8NMCPServer();
+    await mcpServer.initialize();
+
+    const [serverTransport, clientTransport] = InMemoryTransport.createLinkedPair();
+    await mcpServer.connectToTransport(serverTransport);
+
+    client = new Client({ name: 'test-client', version: '1.0.0' }, {});
+    await client.connect(clientTransport);
+  });
+
+  it('should list nodes with filtering', async () => {
+    const response = await client.callTool({
+      name: 'list_nodes',
+      arguments: { category: 'trigger', limit: 10 }
+    });
+
+    expectValidMCPResponse(response);
+    const result = JSON.parse(response.content[0].text);
+    expect(result.nodes).toHaveLength(10);
+    expect(result.nodes.every(n => n.category === 'trigger')).toBe(true);
+  });
+});
+```
+
+### Database Integration Testing (226 tests)
+
+```typescript
+// tests/integration/database/fts5-search.test.ts
+describe('FTS5 Search Integration', () => {
+  it('should perform fuzzy search', async () => {
+    const results = await nodeRepo.searchNodes('HTT', 'FUZZY');
+
+    expect(results.some(n => n.nodeType.includes('httpRequest'))).toBe(true);
+    expect(results.some(n => n.displayName.includes('HTTP'))).toBe(true);
+  });
+
+  it('should handle complex boolean queries', async () => {
+    const results = await nodeRepo.searchNodes('webhook OR http', 'OR');
+
+    expect(results.length).toBeGreaterThan(0);
+    expect(results.some(n =>
+      n.description?.includes('webhook') ||
+      n.description?.includes('http')
+    )).toBe(true);
+  });
+});
+```
+
+### Template Integration Testing (35 tests)
+
+Tests template fetching, storage, and metadata operations against the n8n.io API and local database.
+
+### Docker Integration Testing (18 tests)
+
+Tests Docker configuration parsing, entrypoint script, and security validation.
+
+## Test Distribution and Coverage
+
+### Test Distribution by Component
+
+Based on our 3,336 tests:
+
+**Integration Tests (570 tests):**
+1. **n8n API Integration** (172 tests)
+   - Workflow management handlers: 11 tools with comprehensive scenarios
+   - Execution management handlers: 2 tools
+   - System tool handlers: 3 tools
+   - TypeScript type safety with response interfaces
+
+2. **Database Integration** (226 tests)
+   - Repository operations and transactions
+   - FTS5 full-text search with fuzzy matching
+   - Performance and concurrent access tests
+   - Template node configurations
+
+3. **MCP Protocol** (119 tests)
+   - Protocol compliance and session management
+   - Tool invocation and error handling
+   - Performance and stress testing
+   - Workflow error validation
+
+4. **Templates & Docker** (53 tests)
+   - Template fetching and metadata operations
+   - Docker configuration and security validation
+
+**Unit Tests (2,766 tests):**
+1. **Services Layer** (largest suite)
+   - `workflow-validator-comprehensive.test.ts`: 150+ tests
+   - `enhanced-config-validator.test.ts`: 120+ tests
+   - `node-specific-validators.test.ts`: 100+ tests
+   - `n8n-api-client.test.ts`: 80+ tests
+   - Config validation, property filtering, workflow diff engine
+
+2. **Parsers** (~200 tests)
+   - Node parsing with version support
+   - Property extraction and documentation mapping
+   - Simple parser for basic node information
+
+3. **Database Layer** (~150 tests)
+   - Repository core functionality with mocks
+   - Database adapter unit tests
+   - Template repository operations
+
+4. **MCP Tools & HTTP Server** (~300 tests)
+   - Tool definitions and documentation system
+   - Multi-tenant support and security
+   - Configuration validation
+
+5. **Utils, Docker, Scripts, Telemetry** (remaining tests)
+   - Cache utilities, database helpers
+   - Docker config security and parsing
+   - Template extraction scripts
+   - Telemetry tracking
+
+### Test Execution Performance
+
+From our CI runs:
+- **Fastest tests**: Unit tests with mocks (<1ms each)
+- **Slowest tests**: Integration tests with real database and n8n API (100-5000ms)
+- **Average test time**: ~20ms per test
+- **Total suite execution**: ~3 minutes in CI (with coverage)
+- **Parallel execution**: Configurable thread pool for optimal performance
+
+## CI/CD Pipeline
+
+Our GitHub Actions workflow runs all tests automatically:
+
+```yaml
+# .github/workflows/test.yml
+name: Test Suite
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          
+      - name: Install dependencies
+        run: npm ci
+      
+      - name: Run unit tests with coverage
+        run: npm run test:unit -- --coverage
+        
+      - name: Run integration tests
+        run: npm run test:integration
+        
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+```
+
+### Test Execution Scripts
+
+```json
+// package.json
+{
+  "scripts": {
+    "test": "vitest",
+    "test:unit": "vitest run tests/unit",
+    "test:integration": "vitest run tests/integration --config vitest.config.integration.ts",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest watch",
+    "test:bench": "vitest bench --config vitest.config.benchmark.ts",
+    "benchmark:ci": "CI=true node scripts/run-benchmarks-ci.js"
+  }
+}
+```
+
+### CI Test Results Summary
+
+From our latest CI run (#41):
+
+```
+UNIT TESTS:
+ Test Files  30 passed (30)
+      Tests  932 passed | 1 skipped (933)
+
+INTEGRATION TESTS:
+ Test Files  14 passed (14)
+      Tests  245 passed | 4 skipped (249)
+
+TOTAL: 1,177 passed | 5 skipped | 0 failed
+```
+
+## Performance Testing
+
+We use Vitest's built-in benchmark functionality:
+
+```typescript
+// tests/benchmarks/database-queries.bench.ts
+import { bench, describe } from 'vitest';
+
+describe('Database Query Performance', () => {
+  bench('search nodes by category', async () => {
+    await nodeRepo.getNodesByCategory('trigger');
+  });
+
+  bench('FTS5 search performance', async () => {
+    await nodeRepo.searchNodes('webhook http request', 'AND');
+  });
+});
+```
+
+## Environment Configuration
+
+Test environment is configured via `.env.test`:
+
+```bash
+# Test Environment Configuration
+NODE_ENV=test
+TEST_DB_PATH=:memory:
+TEST_PARALLEL=false
+TEST_MAX_WORKERS=4
+FEATURE_TEST_COVERAGE=true
+MSW_ENABLED=true
+```
+
+## Key Patterns and Lessons Learned
+
+### 1. Response Structure Consistency
+
+All MCP responses follow a specific structure that must be handled correctly:
+
+```typescript
+// Common pattern for handling MCP responses
+const response = await client.callTool({ name: 'list_nodes', arguments: {} });
+
+// MCP responses have content array with text objects
+expect(response.content).toBeDefined();
+expect(response.content[0].type).toBe('text');
+
+// Parse the actual data
+const data = JSON.parse(response.content[0].text);
+```
+
+### 2. MSW Integration Setup
+
+Proper MSW setup is crucial for integration tests:
+
+```typescript
+// tests/integration/setup/integration-setup.ts
+import { setupServer } from 'msw/node';
+import { handlers } from '@tests/mocks/n8n-api/handlers';
+
+// Create server but don't start it globally
+const server = setupServer(...handlers);
+
+beforeAll(async () => {
+  // Only start MSW for integration tests
+  if (process.env.MSW_ENABLED === 'true') {
+    server.listen({ onUnhandledRequest: 'bypass' });
+  }
+});
+
+afterAll(async () => {
+  server.close();
+});
+```
+
+### 3. Database Isolation for Parallel Tests
+
+Each test gets its own database to enable parallel execution:
+
+```typescript
+// tests/utils/database-utils.ts
+export function createTestDatabaseAdapter(
+  db?: Database.Database,
+  options: TestDatabaseOptions = {}
+): DatabaseAdapter {
+  const database = db || new Database(':memory:');
+  
+  // Enable FTS5 if needed
+  if (options.enableFTS5) {
+    database.exec('PRAGMA main.compile_options;');
+  }
+  
+  return new DatabaseAdapter(database);
+}
+```
+
+### 4. Environment-Aware Performance Thresholds
+
+CI environments are slower, so we adjust expectations:
+
+```typescript
+// Environment-aware thresholds
+const getThreshold = (local: number, ci: number) => 
+  process.env.CI ? ci : local;
+
+it('should respond quickly', async () => {
+  const start = performance.now();
+  await someOperation();
+  const duration = performance.now() - start;
+  
+  expect(duration).toBeLessThan(getThreshold(50, 200));
+});
+```
+
+## Best Practices
+
+### 1. Test Isolation
+- Each test creates its own database instance
+- Tests clean up after themselves
+- No shared state between tests
+
+### 2. Proper Cleanup Order
+```typescript
+afterEach(async () => {
+  // Close client first to ensure no pending requests
+  await client.close();
+  
+  // Give time for client to fully close
+  await new Promise(resolve => setTimeout(resolve, 50));
+  
+  // Then close server
+  await mcpServer.close();
+  
+  // Finally cleanup database
+  await testDb.cleanup();
+});
+```
+
+### 3. Handle Async Operations Carefully
+```typescript
+// Avoid race conditions in cleanup
+it('should handle disconnection', async () => {
+  // ... test code ...
+  
+  // Ensure operations complete before cleanup
+  await transport.close();
+  await new Promise(resolve => setTimeout(resolve, 100));
+});
+```
+
+### 4. Meaningful Test Organization
+- Group related tests using `describe` blocks
+- Use descriptive test names that explain the behavior
+- Follow AAA pattern: Arrange, Act, Assert
+- Keep tests focused on single behaviors
+
+## Debugging Tests
+
+### Running Specific Tests
+```bash
+# Run a single test file
+npm test tests/integration/mcp-protocol/tool-invocation.test.ts
+
+# Run tests matching a pattern
+npm test -- --grep "should list nodes"
+
+# Run with debugging output
+DEBUG=* npm test
+```
+
+### VSCode Integration
+```json
+// .vscode/launch.json
+{
+  "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Debug Tests",
+      "program": "${workspaceFolder}/node_modules/vitest/vitest.mjs",
+      "args": ["run", "${file}"],
+      "console": "integratedTerminal"
+    }
+  ]
+}
+```
+
+## Test Coverage
+
+While we don't enforce strict coverage thresholds yet, the infrastructure is in place:
+- Coverage reports generated in `lcov`, `html`, and `text` formats
+- Integration with Codecov for tracking coverage over time
+- Per-file coverage visible in VSCode with extensions
+
+## Future Improvements
+
+1. **E2E Testing**: Add Playwright for testing the full MCP server interaction
+2. **Load Testing**: Implement k6 or Artillery for stress testing
+3. **Contract Testing**: Add Pact for ensuring API compatibility
+4. **Visual Regression**: For any UI components that may be added
+5. **Mutation Testing**: Use Stryker to ensure test quality
+
+## Common Issues and Solutions
+
+### 1. Tests Hanging in CI
+
+**Problem**: Tests would hang indefinitely in CI due to `process.exit()` calls.
+
+**Solution**: Remove all `process.exit()` calls from test code and use proper cleanup:
+```typescript
+// Bad
+afterAll(() => {
+  process.exit(0); // This causes Vitest to hang
+});
+
+// Good
+afterAll(async () => {
+  await cleanup();
+  // Let Vitest handle process termination
+});
+```
+
+### 2. MCP Response Structure
+
+**Problem**: Tests expecting wrong response format from MCP tools.
+
+**Solution**: Always access responses through `content[0].text`:
+```typescript
+// Wrong
+const data = response[0].text;
+
+// Correct
+const data = JSON.parse(response.content[0].text);
+```
+
+### 3. Database Not Found Errors
+
+**Problem**: Tests failing with "node not found" when database is empty.
+
+**Solution**: Check for empty databases before assertions:
+```typescript
+const stats = await server.executeTool('get_database_statistics', {});
+if (stats.totalNodes > 0) {
+  expect(result.nodes.length).toBeGreaterThan(0);
+} else {
+  expect(result.nodes).toHaveLength(0);
+}
+```
+
+### 4. MSW Loading Globally
+
+**Problem**: MSW interfering with unit tests when loaded globally.
+
+**Solution**: Only load MSW in integration test setup:
+```typescript
+// vitest.config.integration.ts
+setupFiles: [
+  './tests/setup/global-setup.ts',
+  './tests/integration/setup/integration-setup.ts' // MSW only here
+]
+```
+
+## Resources
+
+- [Vitest Documentation](https://vitest.dev/)
+- [MSW Documentation](https://mswjs.io/)
+- [Testing Best Practices](https://github.com/goldbergyoni/javascript-testing-best-practices)
+- [MCP SDK Documentation](https://modelcontextprotocol.io/)

docs/testing-checklist.md

@@ -0,0 +1,276 @@
+# n8n-MCP Testing Implementation Checklist
+
+## Test Suite Development Status
+
+### Context
+- **Situation**: Building comprehensive test suite from scratch
+- **Branch**: feat/comprehensive-testing-suite (separate from main)
+- **Main Branch Status**: Working in production without tests
+- **Goal**: Add test coverage without disrupting development
+
+## Immediate Actions (Day 1)
+
+- [x] ~~Fix failing tests (Phase 0)~~ ✅ COMPLETED
+- [x] ~~Create GitHub Actions workflow file~~ ✅ COMPLETED
+- [x] ~~Install Vitest and remove Jest~~ ✅ COMPLETED
+- [x] ~~Create vitest.config.ts~~ ✅ COMPLETED
+- [x] ~~Setup global test configuration~~ ✅ COMPLETED
+- [x] ~~Migrate existing tests to Vitest syntax~~ ✅ COMPLETED
+- [x] ~~Setup coverage reporting with Codecov~~ ✅ COMPLETED
+
+## Phase 1: Vitest Migration ✅ COMPLETED
+
+All tests have been successfully migrated from Jest to Vitest:
+- ✅ Removed Jest and installed Vitest
+- ✅ Created vitest.config.ts with path aliases
+- ✅ Set up global test configuration
+- ✅ Migrated all 6 test files (68 tests passing)
+- ✅ Updated TypeScript configuration
+- ✅ Cleaned up Jest configuration files
+
+## Week 1: Foundation
+
+### Testing Infrastructure ✅ COMPLETED (Phase 2)
+- [x] ~~Create test directory structure~~ ✅ COMPLETED
+- [x] ~~Setup mock infrastructure for better-sqlite3~~ ✅ COMPLETED
+- [x] ~~Create mock for n8n-nodes-base package~~ ✅ COMPLETED
+- [x] ~~Setup test database utilities~~ ✅ COMPLETED
+- [x] ~~Create factory pattern for nodes~~ ✅ COMPLETED
+- [x] ~~Create builder pattern for workflows~~ ✅ COMPLETED
+- [x] ~~Setup global test utilities~~ ✅ COMPLETED
+- [x] ~~Configure test environment variables~~ ✅ COMPLETED
+
+### CI/CD Pipeline ✅ COMPLETED (Phase 3.8)
+- [x] ~~GitHub Actions for test execution~~ ✅ COMPLETED & VERIFIED
+  - Successfully running with Vitest
+  - 1021 tests passing in CI
+  - Build time: ~2 minutes
+- [x] ~~Coverage reporting integration~~ ✅ COMPLETED (Codecov setup)
+- [x] ~~Performance benchmark tracking~~ ✅ COMPLETED
+- [x] ~~Test result artifacts~~ ✅ COMPLETED
+- [ ] Branch protection rules
+- [ ] Required status checks
+
+## Week 2: Mock Infrastructure
+
+### Database Mocking
+- [ ] Complete better-sqlite3 mock implementation
+- [ ] Mock prepared statements
+- [ ] Mock transactions
+- [ ] Mock FTS5 search functionality
+- [ ] Test data seeding utilities
+
+### External Dependencies
+- [ ] Mock axios for API calls
+- [ ] Mock file system operations
+- [ ] Mock MCP SDK
+- [ ] Mock Express server
+- [ ] Mock WebSocket connections
+
+## Week 3-4: Unit Tests ✅ COMPLETED (Phase 3)
+
+### Core Services (Priority 1) ✅ COMPLETED
+- [x] ~~`config-validator.ts` - 95% coverage~~ ✅ 96.9%
+- [x] ~~`enhanced-config-validator.ts` - 95% coverage~~ ✅ 94.55%
+- [x] ~~`workflow-validator.ts` - 90% coverage~~ ✅ 97.59%
+- [x] ~~`expression-validator.ts` - 90% coverage~~ ✅ 97.22%
+- [x] ~~`property-filter.ts` - 90% coverage~~ ✅ 95.25%
+- [x] ~~`example-generator.ts` - 85% coverage~~ ✅ 94.34%
+
+### Parsers (Priority 2) ✅ COMPLETED
+- [x] ~~`node-parser.ts` - 90% coverage~~ ✅ 97.42%
+- [x] ~~`property-extractor.ts` - 90% coverage~~ ✅ 95.49%
+
+### MCP Layer (Priority 3) ✅ COMPLETED
+- [x] ~~`tools.ts` - 90% coverage~~ ✅ 94.11%
+- [x] ~~`handlers-n8n-manager.ts` - 85% coverage~~ ✅ 92.71%
+- [x] ~~`handlers-workflow-diff.ts` - 85% coverage~~ ✅ 96.34%
+- [x] ~~`tools-documentation.ts` - 80% coverage~~ ✅ 94.12%
+
+### Database Layer (Priority 4) ✅ COMPLETED
+- [x] ~~`node-repository.ts` - 85% coverage~~ ✅ 91.48%
+- [x] ~~`database-adapter.ts` - 85% coverage~~ ✅ 89.29%
+- [x] ~~`template-repository.ts` - 80% coverage~~ ✅ 86.78%
+
+### Loaders and Mappers (Priority 5) ✅ COMPLETED
+- [x] ~~`node-loader.ts` - 85% coverage~~ ✅ 91.89%
+- [x] ~~`docs-mapper.ts` - 80% coverage~~ ✅ 95.45%
+
+### Additional Critical Services Tested ✅ COMPLETED (Phase 3.5)
+- [x] ~~`n8n-api-client.ts`~~ ✅ 83.87%
+- [x] ~~`workflow-diff-engine.ts`~~ ✅ 90.06%
+- [x] ~~`n8n-validation.ts`~~ ✅ 97.14%
+- [x] ~~`node-specific-validators.ts`~~ ✅ 98.7%
+
+## Week 5-6: Integration Tests 🚧 IN PROGRESS
+
+### Real Status (July 29, 2025)
+**Context**: Building test suite from scratch on testing branch. Main branch has no tests.
+
+**Overall Status**: 187/246 tests passing (76% pass rate)
+**Critical Issue**: CI shows green despite 58 failing tests due to `|| true` in workflow
+
+### MCP Protocol Tests 🔄 MIXED STATUS
+- [x] ~~Full MCP server initialization~~ ✅ COMPLETED
+- [x] ~~Tool invocation flow~~ ✅ FIXED (30 tests in tool-invocation.test.ts)
+- [ ] Error handling and recovery ⚠️ 16 FAILING (error-handling.test.ts)
+- [x] ~~Concurrent request handling~~ ✅ COMPLETED  
+- [ ] Session management ⚠️ 5 FAILING (timeout issues)
+
+### n8n API Integration 🔄 PENDING
+- [ ] Workflow CRUD operations (MSW mocks ready)
+- [ ] Webhook triggering
+- [ ] Execution monitoring
+- [ ] Authentication handling
+- [ ] Error scenarios
+
+### Database Integration ⚠️ ISSUES FOUND
+- [x] ~~SQLite operations with real DB~~ ✅ BASIC TESTS PASS
+- [ ] FTS5 search functionality ⚠️ 7 FAILING (syntax errors)
+- [ ] Transaction handling ⚠️ 1 FAILING (isolation issues)
+- [ ] Migration testing 🔄 NOT STARTED
+- [ ] Performance under load ⚠️ 4 FAILING (slower than thresholds)
+
+## Week 7-8: E2E & Performance
+
+### End-to-End Scenarios
+- [ ] Complete workflow creation flow
+- [ ] AI agent workflow setup
+- [ ] Template import and validation
+- [ ] Workflow execution monitoring
+- [ ] Error recovery scenarios
+
+### Performance Benchmarks
+- [ ] Node loading speed (< 50ms per node)
+- [ ] Search performance (< 100ms for 1000 nodes)
+- [ ] Validation speed (< 10ms simple, < 100ms complex)
+- [ ] Database query performance
+- [ ] Memory usage profiling
+- [ ] Concurrent request handling
+
+### Load Testing
+- [ ] 100 concurrent MCP requests
+- [ ] 10,000 nodes in database
+- [ ] 1,000 workflow validations/minute
+- [ ] Memory leak detection
+- [ ] Resource cleanup verification
+
+## Testing Quality Gates
+
+### Coverage Requirements
+- [ ] Overall: 80%+ (Currently: 62.67%)
+- [x] ~~Core services: 90%+~~ ✅ COMPLETED
+- [x] ~~MCP tools: 90%+~~ ✅ COMPLETED
+- [x] ~~Critical paths: 95%+~~ ✅ COMPLETED
+- [x] ~~New code: 90%+~~ ✅ COMPLETED
+
+### Performance Requirements
+- [x] ~~All unit tests < 10ms~~ ✅ COMPLETED
+- [ ] Integration tests < 1s
+- [ ] E2E tests < 10s
+- [x] ~~Full suite < 5 minutes~~ ✅ COMPLETED (~2 minutes)
+- [x] ~~No memory leaks~~ ✅ COMPLETED
+
+### Code Quality
+- [x] ~~No ESLint errors~~ ✅ COMPLETED
+- [x] ~~No TypeScript errors~~ ✅ COMPLETED
+- [x] ~~No console.log in tests~~ ✅ COMPLETED
+- [x] ~~All tests have descriptions~~ ✅ COMPLETED
+- [x] ~~No hardcoded values~~ ✅ COMPLETED
+
+## Monitoring & Maintenance
+
+### Daily
+- [ ] Check CI pipeline status
+- [ ] Review failed tests
+- [ ] Monitor flaky tests
+
+### Weekly
+- [ ] Review coverage reports
+- [ ] Update test documentation
+- [ ] Performance benchmark review
+- [ ] Team sync on testing progress
+
+### Monthly
+- [ ] Update baseline benchmarks
+- [ ] Review and refactor tests
+- [ ] Update testing strategy
+- [ ] Training/knowledge sharing
+
+## Risk Mitigation
+
+### Technical Risks
+- [ ] Mock complexity - Use simple, maintainable mocks
+- [ ] Test brittleness - Focus on behavior, not implementation
+- [ ] Performance impact - Run heavy tests in parallel
+- [ ] Flaky tests - Proper async handling and isolation
+
+### Process Risks
+- [ ] Slow adoption - Provide training and examples
+- [ ] Coverage gaming - Review test quality, not just numbers
+- [ ] Maintenance burden - Automate what's possible
+- [ ] Integration complexity - Use test containers
+
+## Success Criteria
+
+### Current Reality Check
+- **Unit Tests**: ✅ SOLID (932 passing, 87.8% coverage)
+- **Integration Tests**: ⚠️ NEEDS WORK (58 failing, 76% pass rate)
+- **E2E Tests**: 🔄 NOT STARTED
+- **CI/CD**: ⚠️ BROKEN (hiding failures with || true)
+
+### Revised Technical Metrics
+- Coverage: Currently 87.8% for unit tests ✅
+- Integration test pass rate: Target 100% (currently 76%)
+- Performance: Adjust thresholds based on reality
+- Reliability: Fix flaky tests during repair
+- Speed: CI pipeline < 5 minutes ✅ (~2 minutes)
+
+### Team Metrics
+- All developers writing tests ✅
+- Tests reviewed in PRs ✅
+- No production bugs from tested code
+- Improved development velocity ✅
+
+## Phases Completed
+
+- **Phase 0**: Immediate Fixes ✅ COMPLETED
+- **Phase 1**: Vitest Migration ✅ COMPLETED  
+- **Phase 2**: Test Infrastructure ✅ COMPLETED
+- **Phase 3**: Unit Tests (All 943 tests) ✅ COMPLETED
+- **Phase 3.5**: Critical Service Testing ✅ COMPLETED
+- **Phase 3.8**: CI/CD & Infrastructure ✅ COMPLETED
+- **Phase 4**: Integration Tests 🚧 IN PROGRESS
+  - **Status**: 58 out of 246 tests failing (23.6% failure rate)
+  - **CI Issue**: Tests appear green due to `|| true` error suppression
+  - **Categories of Failures**:
+    - Database: 9 tests (state isolation, FTS5 syntax)
+    - MCP Protocol: 16 tests (response structure in error-handling.test.ts)
+    - MSW: 6 tests (not initialized properly)
+    - FTS5 Search: 7 tests (query syntax issues)
+    - Session Management: 5 tests (async cleanup)
+    - Performance: 15 tests (threshold mismatches)
+  - **Next Steps**: 
+    1. Get team buy-in for "red" CI
+    2. Remove `|| true` from workflow
+    3. Fix tests systematically by category
+- **Phase 5**: E2E Tests 🔄 PENDING
+
+## Resources & Tools
+
+### Documentation
+- Vitest: https://vitest.dev/
+- Testing Library: https://testing-library.com/
+- MSW: https://mswjs.io/
+- Testcontainers: https://www.testcontainers.com/
+
+### Monitoring
+- Codecov: https://codecov.io/
+- GitHub Actions: https://github.com/features/actions
+- Benchmark Action: https://github.com/benchmark-action/github-action-benchmark
+
+### Team Resources
+- Testing best practices guide
+- Example test implementations
+- Mock usage patterns
+- Performance optimization tips

docs/testing-implementation-guide.md

@@ -0,0 +1,472 @@
+# n8n-MCP Testing Implementation Guide
+
+## Phase 1: Foundation Setup (Week 1-2)
+
+### 1.1 Install Vitest and Dependencies
+
+```bash
+# Remove Jest
+npm uninstall jest ts-jest @types/jest
+
+# Install Vitest and related packages
+npm install -D vitest @vitest/ui @vitest/coverage-v8
+npm install -D @testing-library/jest-dom
+npm install -D msw # For API mocking
+npm install -D @faker-js/faker # For test data
+npm install -D fishery # For factories
+```
+
+### 1.2 Update package.json Scripts
+
+```json
+{
+  "scripts": {
+    // Testing
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:unit": "vitest run tests/unit",
+    "test:integration": "vitest run tests/integration",
+    "test:e2e": "vitest run tests/e2e",
+    "test:watch": "vitest watch",
+    "test:coverage": "vitest run --coverage",
+    "test:coverage:check": "vitest run --coverage --coverage.thresholdAutoUpdate=false",
+    
+    // Benchmarks
+    "bench": "vitest bench",
+    "bench:compare": "vitest bench --compare",
+    
+    // CI specific
+    "test:ci": "vitest run --reporter=junit --reporter=default",
+    "test:ci:coverage": "vitest run --coverage --reporter=junit --reporter=default"
+  }
+}
+```
+
+### 1.3 Migrate Existing Tests
+
+```typescript
+// Before (Jest)
+import { describe, test, expect } from '@jest/globals';
+
+// After (Vitest)
+import { describe, it, expect, vi } from 'vitest';
+
+// Update mock syntax
+// Jest: jest.mock('module')
+// Vitest: vi.mock('module')
+
+// Update timer mocks
+// Jest: jest.useFakeTimers()
+// Vitest: vi.useFakeTimers()
+```
+
+### 1.4 Create Test Database Setup
+
+```typescript
+// tests/setup/test-database.ts
+import Database from 'better-sqlite3';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+export class TestDatabase {
+  private db: Database.Database;
+  
+  constructor() {
+    this.db = new Database(':memory:');
+    this.initialize();
+  }
+  
+  private initialize() {
+    const schema = readFileSync(
+      join(__dirname, '../../src/database/schema.sql'),
+      'utf8'
+    );
+    this.db.exec(schema);
+  }
+  
+  seedNodes(nodes: any[]) {
+    const stmt = this.db.prepare(`
+      INSERT INTO nodes (type, displayName, name, group, version, description, properties)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `);
+    
+    const insertMany = this.db.transaction((nodes) => {
+      for (const node of nodes) {
+        stmt.run(
+          node.type,
+          node.displayName,
+          node.name,
+          node.group,
+          node.version,
+          node.description,
+          JSON.stringify(node.properties)
+        );
+      }
+    });
+    
+    insertMany(nodes);
+  }
+  
+  close() {
+    this.db.close();
+  }
+  
+  getDb() {
+    return this.db;
+  }
+}
+```
+
+## Phase 2: Core Unit Tests (Week 3-4)
+
+### 2.1 Test Organization Template
+
+```typescript
+// tests/unit/services/[service-name].test.ts
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { ServiceName } from '@/services/service-name';
+
+describe('ServiceName', () => {
+  let service: ServiceName;
+  let mockDependency: any;
+  
+  beforeEach(() => {
+    // Setup mocks
+    mockDependency = {
+      method: vi.fn()
+    };
+    
+    // Create service instance
+    service = new ServiceName(mockDependency);
+  });
+  
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+  
+  describe('methodName', () => {
+    it('should handle happy path', async () => {
+      // Arrange
+      const input = { /* test data */ };
+      mockDependency.method.mockResolvedValue({ /* mock response */ });
+      
+      // Act
+      const result = await service.methodName(input);
+      
+      // Assert
+      expect(result).toEqual(/* expected output */);
+      expect(mockDependency.method).toHaveBeenCalledWith(/* expected args */);
+    });
+    
+    it('should handle errors gracefully', async () => {
+      // Arrange
+      mockDependency.method.mockRejectedValue(new Error('Test error'));
+      
+      // Act & Assert
+      await expect(service.methodName({})).rejects.toThrow('Expected error message');
+    });
+  });
+});
+```
+
+### 2.2 Mock Strategies by Layer
+
+#### Database Layer
+```typescript
+// tests/unit/database/node-repository.test.ts
+import { vi } from 'vitest';
+
+vi.mock('better-sqlite3', () => ({
+  default: vi.fn(() => ({
+    prepare: vi.fn(() => ({
+      all: vi.fn(() => mockData),
+      get: vi.fn((id) => mockData.find(d => d.id === id)),
+      run: vi.fn(() => ({ changes: 1 }))
+    })),
+    exec: vi.fn(),
+    close: vi.fn()
+  }))
+}));
+```
+
+#### External APIs
+```typescript
+// tests/unit/services/__mocks__/axios.ts
+export default {
+  create: vi.fn(() => ({
+    get: vi.fn(() => Promise.resolve({ data: {} })),
+    post: vi.fn(() => Promise.resolve({ data: { id: '123' } })),
+    put: vi.fn(() => Promise.resolve({ data: {} })),
+    delete: vi.fn(() => Promise.resolve({ data: {} }))
+  }))
+};
+```
+
+#### File System
+```typescript
+// Use memfs for file system mocking
+import { vol } from 'memfs';
+
+vi.mock('fs', () => vol);
+
+beforeEach(() => {
+  vol.reset();
+  vol.fromJSON({
+    '/test/file.json': JSON.stringify({ test: 'data' })
+  });
+});
+```
+
+### 2.3 Critical Path Tests
+
+```typescript
+// Priority 1: Node Loading and Parsing
+// tests/unit/loaders/node-loader.test.ts
+
+// Priority 2: Configuration Validation
+// tests/unit/services/config-validator.test.ts
+
+// Priority 3: MCP Tools
+// tests/unit/mcp/tools.test.ts
+
+// Priority 4: Database Operations
+// tests/unit/database/node-repository.test.ts
+
+// Priority 5: Workflow Validation
+// tests/unit/services/workflow-validator.test.ts
+```
+
+## Phase 3: Integration Tests (Week 5-6)
+
+### 3.1 Test Container Setup
+
+```typescript
+// tests/setup/test-containers.ts
+import { GenericContainer, StartedTestContainer } from 'testcontainers';
+
+export class N8nTestContainer {
+  private container: StartedTestContainer;
+  
+  async start() {
+    this.container = await new GenericContainer('n8nio/n8n:latest')
+      .withExposedPorts(5678)
+      .withEnv('N8N_BASIC_AUTH_ACTIVE', 'false')
+      .withEnv('N8N_ENCRYPTION_KEY', 'test-key')
+      .start();
+    
+    return {
+      url: `http://localhost:${this.container.getMappedPort(5678)}`,
+      stop: () => this.container.stop()
+    };
+  }
+}
+```
+
+### 3.2 Integration Test Pattern
+
+```typescript
+// tests/integration/n8n-api/workflow-crud.test.ts
+import { N8nTestContainer } from '@tests/setup/test-containers';
+import { N8nAPIClient } from '@/services/n8n-api-client';
+
+describe('n8n API Integration', () => {
+  let container: any;
+  let apiClient: N8nAPIClient;
+  
+  beforeAll(async () => {
+    container = await new N8nTestContainer().start();
+    apiClient = new N8nAPIClient(container.url);
+  }, 30000);
+  
+  afterAll(async () => {
+    await container.stop();
+  });
+  
+  it('should create and retrieve workflow', async () => {
+    // Create workflow
+    const workflow = createTestWorkflow();
+    const created = await apiClient.createWorkflow(workflow);
+    
+    expect(created.id).toBeDefined();
+    
+    // Retrieve workflow
+    const retrieved = await apiClient.getWorkflow(created.id);
+    expect(retrieved.name).toBe(workflow.name);
+  });
+});
+```
+
+## Phase 4: E2E & Performance (Week 7-8)
+
+### 4.1 E2E Test Setup
+
+```typescript
+// tests/e2e/workflows/complete-workflow.test.ts
+import { MCPClient } from '@tests/utils/mcp-client';
+import { N8nTestContainer } from '@tests/setup/test-containers';
+
+describe('Complete Workflow E2E', () => {
+  let mcpServer: any;
+  let n8nContainer: any;
+  let mcpClient: MCPClient;
+  
+  beforeAll(async () => {
+    // Start n8n
+    n8nContainer = await new N8nTestContainer().start();
+    
+    // Start MCP server
+    mcpServer = await startMCPServer({
+      n8nUrl: n8nContainer.url
+    });
+    
+    // Create MCP client
+    mcpClient = new MCPClient(mcpServer.url);
+  }, 60000);
+  
+  it('should execute complete workflow creation flow', async () => {
+    // 1. Search for nodes
+    const searchResult = await mcpClient.call('search_nodes', {
+      query: 'webhook http slack'
+    });
+    
+    // 2. Get node details
+    const webhookInfo = await mcpClient.call('get_node_info', {
+      nodeType: 'nodes-base.webhook'
+    });
+    
+    // 3. Create workflow
+    const workflow = new WorkflowBuilder('E2E Test')
+      .addWebhookNode()
+      .addHttpRequestNode()
+      .addSlackNode()
+      .connectSequentially()
+      .build();
+    
+    // 4. Validate workflow
+    const validation = await mcpClient.call('validate_workflow', {
+      workflow
+    });
+    
+    expect(validation.isValid).toBe(true);
+    
+    // 5. Deploy to n8n
+    const deployed = await mcpClient.call('n8n_create_workflow', {
+      ...workflow
+    });
+    
+    expect(deployed.id).toBeDefined();
+    expect(deployed.active).toBe(false);
+  });
+});
+```
+
+### 4.2 Performance Benchmarks
+
+```typescript
+// vitest.benchmark.config.ts
+export default {
+  test: {
+    benchmark: {
+      // Output benchmark results
+      outputFile: './benchmark-results.json',
+      
+      // Compare with baseline
+      compare: './benchmark-baseline.json',
+      
+      // Fail if performance degrades by more than 10%
+      threshold: {
+        p95: 1.1, // 110% of baseline
+        p99: 1.2  // 120% of baseline
+      }
+    }
+  }
+};
+```
+
+## Testing Best Practices
+
+### 1. Test Naming Convention
+```typescript
+// Format: should [expected behavior] when [condition]
+it('should return user data when valid ID is provided')
+it('should throw ValidationError when email is invalid')
+it('should retry 3 times when network fails')
+```
+
+### 2. Test Data Builders
+```typescript
+// Use builders for complex test data
+const user = new UserBuilder()
+  .withEmail('test@example.com')
+  .withRole('admin')
+  .build();
+```
+
+### 3. Custom Matchers
+```typescript
+// tests/utils/matchers.ts
+export const toBeValidNode = (received: any) => {
+  const pass = 
+    received.type &&
+    received.displayName &&
+    received.properties &&
+    Array.isArray(received.properties);
+  
+  return {
+    pass,
+    message: () => `expected ${received} to be a valid node`
+  };
+};
+
+// Usage
+expect(node).toBeValidNode();
+```
+
+### 4. Snapshot Testing
+```typescript
+// For complex structures
+it('should generate correct node schema', () => {
+  const schema = generateNodeSchema(node);
+  expect(schema).toMatchSnapshot();
+});
+```
+
+### 5. Test Isolation
+```typescript
+// Always clean up after tests
+afterEach(async () => {
+  await cleanup();
+  vi.clearAllMocks();
+  vi.restoreAllMocks();
+});
+```
+
+## Coverage Goals by Module
+
+| Module | Target | Priority | Notes |
+|--------|--------|----------|-------|
+| services/config-validator | 95% | High | Critical for reliability |
+| services/workflow-validator | 90% | High | Core functionality |
+| mcp/tools | 90% | High | User-facing API |
+| database/node-repository | 85% | Medium | Well-tested DB layer |
+| loaders/node-loader | 85% | Medium | External dependencies |
+| parsers/* | 90% | High | Data transformation |
+| utils/* | 80% | Low | Helper functions |
+| scripts/* | 50% | Low | One-time scripts |
+
+## Continuous Improvement
+
+1. **Weekly Reviews**: Review test coverage and identify gaps
+2. **Performance Baselines**: Update benchmarks monthly
+3. **Flaky Test Detection**: Monitor and fix within 48 hours
+4. **Test Documentation**: Keep examples updated
+5. **Developer Training**: Pair programming on tests
+
+## Success Metrics
+
+- [ ] All tests pass in CI (0 failures)
+- [ ] Coverage > 80% overall
+- [ ] No flaky tests
+- [ ] CI runs < 5 minutes
+- [ ] Performance benchmarks stable
+- [ ] Zero production bugs from tested code

docs/token-efficiency-summary.md

@@ -0,0 +1,66 @@
+# Token Efficiency Improvements Summary
+
+## Overview
+Made all MCP tool descriptions concise and token-efficient while preserving essential information.
+
+## Key Improvements
+
+### Before vs After Examples
+
+1. **search_nodes**
+   - Before: ~350 chars with verbose explanation
+   - After: 165 chars
+   - `Search nodes by keywords. Modes: OR (any word), AND (all words), FUZZY (typos OK). Primary nodes ranked first. Examples: "webhook"→Webhook, "http call"→HTTP Request.`
+
+2. **get_node_info**
+   - Before: ~450 chars with warnings about size
+   - After: 174 chars
+   - `Get FULL node schema (100KB+). TIP: Use get_node_essentials first! Returns all properties/operations/credentials. Prefix required: "nodes-base.httpRequest" not "httpRequest".`
+
+3. **validate_node_minimal**
+   - Before: ~350 chars explaining what it doesn't do
+   - After: 102 chars
+   - `Fast check for missing required fields only. No warnings/suggestions. Returns: list of missing fields.`
+
+4. **get_property_dependencies**
+   - Before: ~400 chars with full example
+   - After: 131 chars
+   - `Shows property dependencies and visibility rules. Example: sendBody=true reveals body fields. Test visibility with optional config.`
+
+## Statistics
+
+### Documentation Tools (22 tools)
+- Average description length: **129 characters**
+- Total characters: 2,836
+- Tools over 200 chars: 1 (list_nodes at 204)
+
+### Management Tools (17 tools)
+- Average description length: **93 characters**
+- Total characters: 1,578
+- Tools over 200 chars: 1 (n8n_update_partial_workflow at 284)
+
+## Strategy Used
+
+1. **Remove redundancy**: Eliminated repeated information available in parameter descriptions
+2. **Use abbreviations**: "vs" instead of "versus", "&" instead of "and" where appropriate
+3. **Compact examples**: `"webhook"→Webhook` instead of verbose explanations
+4. **Direct language**: "Fast check" instead of "Quick validation that only checks"
+5. **Move details to documentation**: Complex tools reference `tools_documentation()` for full details
+6. **Essential info only**: Focus on what the tool does, not how it works internally
+
+## Special Cases
+
+### n8n_update_partial_workflow
+This tool's description is necessarily longer (284 chars) because:
+- Lists all 13 operation types
+- Critical for users to know available operations
+- Directs to full documentation for details
+
+### Complex Documentation Preserved
+For tools like `n8n_update_partial_workflow`, detailed documentation was moved to `tools-documentation.ts` rather than deleted, ensuring users can still access comprehensive information when needed.
+
+## Impact
+- **Token savings**: ~65-70% reduction in description tokens
+- **Faster AI responses**: Less context used for tool descriptions
+- **Better UX**: Clearer, more scannable tool list
+- **Maintained functionality**: All essential information preserved

docs/transactional-updates-implementation.md

@@ -1,72 +0,0 @@
-# Transactional Updates Implementation Summary
-
-## Overview
-
-We successfully implemented a simple transactional update system for the `n8n_update_partial_workflow` tool that allows AI agents to add nodes and connect them in a single request, regardless of operation order.
-
-## Key Changes
-
-### 1. WorkflowDiffEngine (`src/services/workflow-diff-engine.ts`)
-
-- Added **5 operation limit** to keep complexity manageable
-- Implemented **two-pass processing**:
-  - Pass 1: Node operations (add, remove, update, move, enable, disable)
-  - Pass 2: Other operations (connections, settings, metadata)
-- Operations are always applied to working copy for proper validation
-
-### 2. Benefits
-
-- **Order Independence**: AI agents can write operations in any logical order
-- **Atomic Updates**: All operations succeed or all fail
-- **Simple Implementation**: ~50 lines of code change
-- **Backward Compatible**: Existing usage still works
-
-### 3. Example Usage
-
-```json
-{
-  "id": "workflow-id",
-  "operations": [
-    // Connections first (would fail before)
-    { "type": "addConnection", "source": "Start", "target": "Process" },
-    { "type": "addConnection", "source": "Process", "target": "End" },
-    
-    // Nodes added later (processed first internally)
-    { "type": "addNode", "node": { "name": "Process", ... }},
-    { "type": "addNode", "node": { "name": "End", ... }}
-  ]
-}
-```
-
-## Testing
-
-Created comprehensive test suite (`src/scripts/test-transactional-diff.ts`) that validates:
-- Mixed operations with connections before nodes
-- Operation limit enforcement (max 5)
-- Validate-only mode
-- Complex mixed operations
-
-All tests pass successfully!
-
-## Documentation Updates
-
-1. **CLAUDE.md** - Added transactional updates to v2.7.0 release notes
-2. **workflow-diff-examples.md** - Added new section explaining transactional updates
-3. **Tool description** - Updated to highlight order independence
-4. **transactional-updates-example.md** - Before/after comparison
-
-## Why This Approach?
-
-1. **Simplicity**: No complex dependency graphs or topological sorting
-2. **Predictability**: Clear two-pass rule is easy to understand
-3. **Reliability**: 5 operation limit prevents edge cases
-4. **Performance**: Minimal overhead, same validation logic
-
-## Future Enhancements (Not Implemented)
-
-If needed in the future, we could add:
-- Automatic operation reordering based on dependencies
-- Larger operation limits with smarter batching
-- Dependency hints in error messages
-
-But the current simple approach covers 90%+ of use cases effectively!

docs/workflow-diff-examples.md

@@ -116,17 +116,46 @@ The `n8n_update_partial_workflow` tool allows you to make targeted changes to wo
 }
 ```
 
-#### Update Connection (Change routing)
+#### Rewire Connection
 ```json
 {
-  "type": "updateConnection",
+  "type": "rewireConnection",
+  "source": "Webhook",
+  "from": "Old Handler",
+  "to": "New Handler",
+  "description": "Rewire connection to new handler"
+}
+```
+
+#### Smart Parameters for IF Nodes
+```json
+{
+  "type": "addConnection",
   "source": "IF",
-  "target": "Send Email",
-  "changes": {
-    "sourceOutput": "false",  // Change from 'true' to 'false' output
-    "targetInput": "main"
-  },
-  "description": "Route failed conditions to email"
+  "target": "Success Handler",
+  "branch": "true",  // Semantic parameter instead of sourceIndex
+  "description": "Route true branch to success handler"
+}
+```
+
+```json
+{
+  "type": "addConnection",
+  "source": "IF",
+  "target": "Error Handler",
+  "branch": "false",  // Routes to false branch (sourceIndex=1)
+  "description": "Route false branch to error handler"
+}
+```
+
+#### Smart Parameters for Switch Nodes
+```json
+{
+  "type": "addConnection",
+  "source": "Switch",
+  "target": "Handler A",
+  "case": 0,  // First output
+  "description": "Route case 0 to Handler A"
 }
 ```
 
@@ -296,6 +325,193 @@ The `n8n_update_partial_workflow` tool allows you to make targeted changes to wo
 }
 ```
 
+### Example 5: Large Batch Workflow Refactoring
+Demonstrates handling many operations in a single request - no longer limited to 5 operations!
+
+```json
+{
+  "id": "workflow-batch",
+  "operations": [
+    // Add 10 processing nodes
+    {
+      "type": "addNode",
+      "node": {
+        "name": "Filter Active Users",
+        "type": "n8n-nodes-base.filter",
+        "position": [400, 200],
+        "parameters": { "conditions": { "boolean": [{ "value1": "={{$json.active}}", "value2": true }] } }
+      }
+    },
+    {
+      "type": "addNode",
+      "node": {
+        "name": "Transform User Data",
+        "type": "n8n-nodes-base.set",
+        "position": [600, 200],
+        "parameters": { "values": { "string": [{ "name": "formatted_name", "value": "={{$json.firstName}} {{$json.lastName}}" }] } }
+      }
+    },
+    {
+      "type": "addNode",
+      "node": {
+        "name": "Validate Email",
+        "type": "n8n-nodes-base.if",
+        "position": [800, 200],
+        "parameters": { "conditions": { "string": [{ "value1": "={{$json.email}}", "operation": "contains", "value2": "@" }] } }
+      }
+    },
+    {
+      "type": "addNode",
+      "node": {
+        "name": "Enrich with API",
+        "type": "n8n-nodes-base.httpRequest",
+        "position": [1000, 150],
+        "parameters": { "url": "https://api.example.com/enrich", "method": "POST" }
+      }
+    },
+    {
+      "type": "addNode",
+      "node": {
+        "name": "Log Invalid Emails",
+        "type": "n8n-nodes-base.code",
+        "position": [1000, 350],
+        "parameters": { "jsCode": "console.log('Invalid email:', $json.email);\nreturn $json;" }
+      }
+    },
+    {
+      "type": "addNode",
+      "node": {
+        "name": "Merge Results",
+        "type": "n8n-nodes-base.merge",
+        "position": [1200, 250]
+      }
+    },
+    {
+      "type": "addNode",
+      "node": {
+        "name": "Deduplicate",
+        "type": "n8n-nodes-base.removeDuplicates",
+        "position": [1400, 250],
+        "parameters": { "propertyName": "id" }
+      }
+    },
+    {
+      "type": "addNode",
+      "node": {
+        "name": "Sort by Date",
+        "type": "n8n-nodes-base.sort",
+        "position": [1600, 250],
+        "parameters": { "sortFieldsUi": { "sortField": [{ "fieldName": "created_at", "order": "descending" }] } }
+      }
+    },
+    {
+      "type": "addNode",
+      "node": {
+        "name": "Batch for DB",
+        "type": "n8n-nodes-base.splitInBatches",
+        "position": [1800, 250],
+        "parameters": { "batchSize": 100 }
+      }
+    },
+    {
+      "type": "addNode",
+      "node": {
+        "name": "Save to Database",
+        "type": "n8n-nodes-base.postgres",
+        "position": [2000, 250],
+        "parameters": { "operation": "insert", "table": "processed_users" }
+      }
+    },
+    // Connect all the nodes
+    {
+      "type": "addConnection",
+      "source": "Get Users",
+      "target": "Filter Active Users"
+    },
+    {
+      "type": "addConnection",
+      "source": "Filter Active Users",
+      "target": "Transform User Data"
+    },
+    {
+      "type": "addConnection",
+      "source": "Transform User Data",
+      "target": "Validate Email"
+    },
+    {
+      "type": "addConnection",
+      "source": "Validate Email",
+      "sourceOutput": "true",
+      "target": "Enrich with API"
+    },
+    {
+      "type": "addConnection",
+      "source": "Validate Email",
+      "sourceOutput": "false",
+      "target": "Log Invalid Emails"
+    },
+    {
+      "type": "addConnection",
+      "source": "Enrich with API",
+      "target": "Merge Results"
+    },
+    {
+      "type": "addConnection",
+      "source": "Log Invalid Emails",
+      "target": "Merge Results",
+      "targetInput": "input2"
+    },
+    {
+      "type": "addConnection",
+      "source": "Merge Results",
+      "target": "Deduplicate"
+    },
+    {
+      "type": "addConnection",
+      "source": "Deduplicate",
+      "target": "Sort by Date"
+    },
+    {
+      "type": "addConnection",
+      "source": "Sort by Date",
+      "target": "Batch for DB"
+    },
+    {
+      "type": "addConnection",
+      "source": "Batch for DB",
+      "target": "Save to Database"
+    },
+    // Update workflow metadata
+    {
+      "type": "updateName",
+      "name": "User Processing Pipeline v2"
+    },
+    {
+      "type": "updateSettings",
+      "settings": {
+        "executionOrder": "v1",
+        "timezone": "UTC",
+        "saveDataSuccessExecution": "all"
+      }
+    },
+    {
+      "type": "addTag",
+      "tag": "production"
+    },
+    {
+      "type": "addTag",
+      "tag": "user-processing"
+    },
+    {
+      "type": "addTag",
+      "tag": "v2"
+    }
+  ]
+}
+```
+
+This example shows 26 operations in a single request, creating a complete data processing pipeline with proper error handling, validation, and batch processing.
+
 ## Best Practices
 
 1. **Use Descriptive Names**: Always provide clear node names and descriptions for operations
@@ -390,13 +606,13 @@ The tool validates all operations before applying any changes. Common errors inc
 
 Always check the response for validation errors and adjust your operations accordingly.
 
-## Transactional Updates (v2.7.0+)
+## Transactional Updates
 
 The diff engine now supports transactional updates using a **two-pass processing** approach:
 
 ### How It Works
 
-1. **Operation Limit**: Maximum 5 operations per request to ensure reliability
+1. **No Operation Limit**: Process unlimited operations in a single request
 2. **Two-Pass Processing**:
    - **Pass 1**: All node operations (add, remove, update, move, enable, disable)
    - **Pass 2**: All other operations (connections, settings, metadata)
@@ -446,9 +662,9 @@ This allows you to add nodes and connect them in the same request:
 ### Benefits
 
 - **Order Independence**: You don't need to worry about operation order
-- **Atomic Updates**: All operations succeed or all fail
+- **Atomic Updates**: All operations succeed or all fail (unless continueOnError is enabled)
 - **Intuitive Usage**: Add complex workflow structures in one call
-- **Clear Limits**: 5 operations max keeps things simple and reliable
+- **No Hard Limits**: Process unlimited operations efficiently
 
 ### Example: Complete Workflow Addition
 
@@ -507,4 +723,4 @@ This allows you to add nodes and connect them in the same request:
 }
 ```
 
-All 5 operations will be processed correctly regardless of order!
+All operations will be processed correctly regardless of order!

examples/n8n-mcp-sse-workflow.json

@@ -1,95 +0,0 @@
-{
-  "name": "MCP Server Trigger with SSE Example",
-  "nodes": [
-    {
-      "parameters": {
-        "eventSourceUrl": "http://localhost:3000/sse",
-        "messageEndpoint": "http://localhost:3000/mcp/message",
-        "authentication": "bearerToken",
-        "options": {
-          "reconnect": true,
-          "reconnectInterval": 5000
-        }
-      },
-      "id": "mcp-server-trigger",
-      "name": "MCP Server Trigger",
-      "type": "n8n-nodes-base.mcpServerTrigger",
-      "typeVersion": 1,
-      "position": [250, 300],
-      "credentials": {
-        "mcpApi": {
-          "id": "1",
-          "name": "MCP API"
-        }
-      }
-    },
-    {
-      "parameters": {
-        "operation": "callTool",
-        "toolName": "={{ $json.toolName }}",
-        "toolArguments": "={{ JSON.stringify($json.arguments) }}"
-      },
-      "id": "mcp-client",
-      "name": "MCP Client",
-      "type": "n8n-nodes-base.mcp",
-      "typeVersion": 1,
-      "position": [450, 300],
-      "credentials": {
-        "mcpApi": {
-          "id": "1",
-          "name": "MCP API"
-        }
-      }
-    },
-    {
-      "parameters": {
-        "values": {
-          "string": [
-            {
-              "name": "response",
-              "value": "={{ JSON.stringify($json) }}"
-            }
-          ]
-        },
-        "options": {}
-      },
-      "id": "set-response",
-      "name": "Format Response",
-      "type": "n8n-nodes-base.set",
-      "typeVersion": 1,
-      "position": [650, 300]
-    }
-  ],
-  "connections": {
-    "MCP Server Trigger": {
-      "main": [
-        [
-          {
-            "node": "MCP Client",
-            "type": "main",
-            "index": 0
-          }
-        ]
-      ]
-    },
-    "MCP Client": {
-      "main": [
-        [
-          {
-            "node": "Format Response",
-            "type": "main",
-            "index": 0
-          }
-        ]
-      ]
-    }
-  },
-  "settings": {
-    "executionOrder": "v1"
-  },
-  "staticData": null,
-  "pinData": {},
-  "versionId": "sse-example-v1",
-  "triggerCount": 0,
-  "tags": []
-}

jest.config.js

@@ -1,16 +0,0 @@
-module.exports = {
-  preset: 'ts-jest',
-  testEnvironment: 'node',
-  roots: ['<rootDir>/src', '<rootDir>/tests'],
-  testMatch: ['**/__tests__/**/*.ts', '**/?(*.)+(spec|test).ts'],
-  transform: {
-    '^.+\\.ts$': 'ts-jest',
-  },
-  collectCoverageFrom: [
-    'src/**/*.ts',
-    '!src/**/*.d.ts',
-    '!src/**/*.test.ts',
-  ],
-  coverageDirectory: 'coverage',
-  coverageReporters: ['text', 'lcov', 'html'],
-};

monitor_fetch.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+
+echo "Monitoring template fetch progress..."
+echo "=================================="
+
+while true; do
+    # Check if process is still running
+    if ! pgrep -f "fetch-templates" > /dev/null; then
+        echo "Fetch process completed!"
+        break
+    fi
+    
+    # Get database size
+    DB_SIZE=$(ls -lh data/nodes.db 2>/dev/null | awk '{print $5}')
+    
+    # Get template count
+    TEMPLATE_COUNT=$(sqlite3 data/nodes.db "SELECT COUNT(*) FROM templates" 2>/dev/null || echo "0")
+    
+    # Get last log entry
+    LAST_LOG=$(tail -n 1 fetch_log.txt 2>/dev/null | grep "Fetching template details" | tail -1)
+    
+    # Display status
+    echo -ne "\rDB Size: $DB_SIZE | Templates: $TEMPLATE_COUNT | $LAST_LOG"
+    
+    sleep 5
+done
+
+echo ""
+echo "Final statistics:"
+echo "-----------------"
+ls -lh data/nodes.db
+sqlite3 data/nodes.db "SELECT COUNT(*) as count, printf('%.1f MB', SUM(LENGTH(workflow_json_compressed))/1024.0/1024.0) as compressed_size FROM templates"

package.json

@@ -1,13 +1,13 @@
 {
   "name": "n8n-mcp",
-  "version": "2.8.0",
+  "version": "2.16.3",
   "description": "Integration between n8n workflow automation and Model Context Protocol (MCP)",
   "main": "dist/index.js",
   "bin": {
     "n8n-mcp": "./dist/mcp/index.js"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc -p tsconfig.build.json",
     "rebuild": "node dist/scripts/rebuild.js",
     "rebuild:optimized": "node dist/scripts/rebuild-optimized.js",
     "validate": "node dist/scripts/validate.js",
@@ -15,21 +15,36 @@
     "start": "node dist/mcp/index.js",
     "start:http": "MCP_MODE=http node dist/mcp/index.js",
     "start:http:fixed": "MCP_MODE=http USE_FIXED_HTTP=true node dist/mcp/index.js",
-    "start:sse": "MCP_MODE=sse node dist/mcp/index.js",
+    "start:n8n": "N8N_MODE=true MCP_MODE=http node dist/mcp/index.js",
     "http": "npm run build && npm run start:http:fixed",
-    "sse": "npm run build && npm run start:sse",
     "dev": "npm run build && npm run rebuild && npm run validate",
     "dev:http": "MCP_MODE=http nodemon --watch src --ext ts --exec 'npm run build && npm run start:http'",
-    "dev:sse": "MCP_MODE=sse nodemon --watch src --ext ts --exec 'npm run build && node dist/mcp/index.js'",
     "test:single-session": "./scripts/test-single-session.sh",
-    "test": "jest",
+    "test:mcp-endpoint": "node scripts/test-mcp-endpoint.js",
+    "test:mcp-endpoint:curl": "./scripts/test-mcp-endpoint.sh",
+    "test:mcp-stdio": "npm run build && node scripts/test-mcp-stdio.js",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:ci": "vitest run --coverage --coverage.thresholds.lines=0 --coverage.thresholds.functions=0 --coverage.thresholds.branches=0 --coverage.thresholds.statements=0 --reporter=default --reporter=junit",
+    "test:watch": "vitest watch",
+    "test:unit": "vitest run tests/unit",
+    "test:integration": "vitest run --config vitest.config.integration.ts",
+    "test:integration:n8n": "vitest run tests/integration/n8n-api",
+    "test:cleanup:orphans": "tsx tests/integration/n8n-api/scripts/cleanup-orphans.ts",
+    "test:e2e": "vitest run tests/e2e",
     "lint": "tsc --noEmit",
     "typecheck": "tsc --noEmit",
     "update:n8n": "node scripts/update-n8n-deps.js",
     "update:n8n:check": "node scripts/update-n8n-deps.js --dry-run",
     "fetch:templates": "node dist/scripts/fetch-templates.js",
+    "fetch:templates:update": "node dist/scripts/fetch-templates.js --update",
+    "fetch:templates:extract": "node dist/scripts/fetch-templates.js --extract-only",
     "fetch:templates:robust": "node dist/scripts/fetch-templates-robust.js",
+    "prebuild:fts5": "npx tsx scripts/prebuild-fts5.ts",
     "test:templates": "node dist/scripts/test-templates.js",
+    "test:protocol-negotiation": "npx tsx src/scripts/test-protocol-negotiation.ts",
     "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",
@@ -39,22 +54,36 @@
     "test:n8n-manager": "node dist/scripts/test-n8n-manager-integration.js",
     "test:n8n-validate-workflow": "node dist/scripts/test-n8n-validate-workflow.js",
     "test:typeversion-validation": "node dist/scripts/test-typeversion-validation.js",
+    "test:error-handling": "node dist/scripts/test-error-handling-validation.js",
     "test:workflow-diff": "node dist/scripts/test-workflow-diff.js",
     "test:transactional-diff": "node dist/scripts/test-transactional-diff.js",
     "test:tools-documentation": "node dist/scripts/test-tools-documentation.js",
+    "test:url-configuration": "npm run build && ts-node scripts/test-url-configuration.ts",
+    "test:search-improvements": "node dist/scripts/test-search-improvements.js",
+    "test:fts5-search": "node dist/scripts/test-fts5-search.js",
+    "migrate:fts5": "node dist/scripts/migrate-nodes-fts.js",
     "test:mcp:update-partial": "node dist/scripts/test-mcp-n8n-update-partial.js",
     "test:update-partial:debug": "node dist/scripts/test-update-partial-debug.js",
+    "test:issue-45-fix": "node dist/scripts/test-issue-45-fix.js",
     "test:auth-logging": "tsx scripts/test-auth-logging.ts",
-    "test:sse": "npm run build && jest tests/sse-*.test.ts --passWithNoTests",
-    "test:sse:manual": "npm run build && npx ts-node tests/test-sse-endpoints.ts",
-    "test:sse:integration": "npm run build && jest tests/sse-integration.test.ts --passWithNoTests",
-    "test:sse:unit": "npm run build && jest tests/sse-session-manager.test.ts --passWithNoTests",
+    "test:docker": "./scripts/test-docker-config.sh all",
+    "test:docker:unit": "./scripts/test-docker-config.sh unit",
+    "test:docker:integration": "./scripts/test-docker-config.sh integration",
+    "test:docker:security": "./scripts/test-docker-config.sh security",
     "sanitize:templates": "node dist/scripts/sanitize-templates.js",
     "db:rebuild": "node dist/scripts/rebuild-database.js",
+    "benchmark": "vitest bench --config vitest.config.benchmark.ts",
+    "benchmark:watch": "vitest bench --watch --config vitest.config.benchmark.ts",
+    "benchmark:ui": "vitest bench --ui --config vitest.config.benchmark.ts",
+    "benchmark:ci": "CI=true node scripts/run-benchmarks-ci.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",
     "sync:runtime-version": "node scripts/sync-runtime-version.js",
-    "prepare:publish": "./scripts/publish-npm.sh"
+    "update:readme-version": "node scripts/update-readme-version.js",
+    "prepare:publish": "./scripts/publish-npm.sh",
+    "update:all": "./scripts/update-and-publish-prep.sh",
+    "test:release-automation": "node scripts/test-release-automation.js",
+    "prepare:release": "node scripts/prepare-release.js"
   },
   "repository": {
     "type": "git",
@@ -83,27 +112,46 @@
     "package.runtime.json"
   ],
   "devDependencies": {
+    "@faker-js/faker": "^9.9.0",
+    "@testing-library/jest-dom": "^6.6.4",
+    "@types/better-sqlite3": "^7.6.13",
     "@types/express": "^5.0.3",
-    "@types/jest": "^29.5.14",
     "@types/node": "^22.15.30",
     "@types/ws": "^8.18.1",
-    "jest": "^29.7.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/runner": "^3.2.4",
+    "@vitest/ui": "^3.2.4",
+    "axios": "^1.11.0",
+    "axios-mock-adapter": "^2.1.0",
+    "fishery": "^2.3.1",
+    "msw": "^2.10.4",
     "nodemon": "^3.1.10",
-    "ts-jest": "^29.3.4",
     "ts-node": "^10.9.2",
-    "typescript": "^5.8.3"
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.13.2",
-    "@n8n/n8n-nodes-langchain": "^1.99.0",
-    "axios": "^1.10.0",
-    "better-sqlite3": "^11.10.0",
+    "@n8n/n8n-nodes-langchain": "^1.112.2",
+    "@supabase/supabase-js": "^2.57.4",
     "dotenv": "^16.5.0",
     "express": "^5.1.0",
-    "n8n": "^1.100.1",
-    "n8n-core": "^1.99.0",
-    "n8n-workflow": "^1.97.0",
+    "express-rate-limit": "^7.1.5",
+    "lru-cache": "^11.2.1",
+    "n8n": "^1.113.3",
+    "n8n-core": "^1.112.1",
+    "n8n-workflow": "^1.110.0",
+    "openai": "^4.77.0",
     "sql.js": "^1.13.0",
-    "uuid": "^10.0.0"
+    "uuid": "^10.0.0",
+    "zod": "^3.24.1"
+  },
+  "optionalDependencies": {
+    "@rollup/rollup-darwin-arm64": "^4.50.0",
+    "@rollup/rollup-linux-x64-gnu": "^4.50.0",
+    "better-sqlite3": "^11.10.0"
+  },
+  "overrides": {
+    "pyodide": "0.26.4"
   }
 }