feat: SSE (Server-Sent Events) support for n8n integration

- Added SSE server implementation for real-time event streaming
- Created n8n compatibility mode with strict schema validation
- Implemented session management for concurrent connections
- Added comprehensive SSE documentation and examples
- Enhanced MCP tools with async execution support
- Added Docker Compose configuration for SSE deployment
- Included test scripts and integration tests

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

.claude/agents/code-reviewer.md

@@ -1,40 +0,0 @@
----
-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

@@ -1,89 +0,0 @@
----
-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

@@ -1,64 +0,0 @@
----
-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

@@ -1,111 +0,0 @@
----
-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

@@ -1,60 +0,0 @@
----
-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

@@ -1,102 +0,0 @@
----
-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

@@ -1,117 +0,0 @@
----
-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

@@ -1,99 +0,0 @@
----
-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.docker

@@ -26,8 +26,4 @@ USE_NGINX=false
 # N8N_API_URL=https://your-n8n-instance.com
 # N8N_API_KEY=your-api-key-here
 # N8N_API_TIMEOUT=30000
-# N8N_API_MAX_RETRIES=3
-
-# Optional: Disable specific tools (comma-separated list)
-# Example: DISABLED_TOOLS=n8n_diagnostic,n8n_health_check
-# DISABLED_TOOLS=
+# N8N_API_MAX_RETRIES=3

.env.example

@@ -7,7 +7,6 @@
 # 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)
@@ -45,15 +44,6 @@ 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
@@ -70,70 +60,13 @@ AUTH_TOKEN=your-secure-token-here
 # TRUST_PROXY=0
 
 # =========================
-# SECURITY CONFIGURATION
+# N8N COMPATIBILITY MODE
 # =========================
-
-# 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
-
-# Disabled Tools Configuration
-# Filter specific tools from registration at startup
-# Useful for multi-tenant deployments, security hardening, or feature flags
-#
-# Format: Comma-separated list of tool names
-# Example: DISABLED_TOOLS=n8n_diagnostic,n8n_health_check,custom_tool
-#
-# Common use cases:
-# - Multi-tenant: Hide tools that check env vars instead of instance context
-#   Example: DISABLED_TOOLS=n8n_diagnostic,n8n_health_check
-# - Security: Disable management tools in production for certain users
-# - Feature flags: Gradually roll out new tools
-# - Deployment-specific: Different tool sets for cloud vs self-hosted
-#
-# Default: (empty - all tools enabled)
-# DISABLED_TOOLS=
-
-# =========================
-# 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
+# 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
 
 # =========================
 # N8N API CONFIGURATION
@@ -152,67 +85,4 @@ ENABLE_MULTI_TENANT=false
 # N8N_API_TIMEOUT=30000
 
 # Maximum number of API request retries (default: 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
+# N8N_API_MAX_RETRIES=3

.env.n8n.example

@@ -1,36 +0,0 @@
-# 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

@@ -1,127 +0,0 @@
-# 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

@@ -1,97 +0,0 @@
-# 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

@@ -1,56 +0,0 @@
-# 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

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

.github/gh-pages.yml

@@ -1,17 +0,0 @@
-# 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

@@ -1,176 +0,0 @@
-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

@@ -1,214 +0,0 @@
-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

@@ -1,179 +0,0 @@
-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

@@ -5,43 +5,13 @@ on:
   push:
     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'
+    tags:
+      - 'v*'
   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:
 
-# Prevent concurrent Docker pushes across all workflows (shared with release.yml)
-# This ensures docker-build.yml and release.yml never push to 'latest' simultaneously
-concurrency:
-  group: docker-push-${{ github.ref }}
-  cancel-in-progress: false
-
 env:
   REGISTRY: ghcr.io
   IMAGE_NAME: ${{ github.repository }}
@@ -86,112 +56,18 @@ jobs:
             type=semver,pattern={{version}}
             type=semver,pattern={{major}}.{{minor}}
             type=semver,pattern={{major}}
-            type=sha,format=short
+            type=sha,prefix={{branch}}-,format=short
             type=raw,value=latest,enable={{is_default_branch}}
             
       - name: Build and push Docker image
         uses: docker/build-push-action@v5
         with:
           context: .
-          no-cache: false
+          no-cache: true
           platforms: linux/amd64,linux/arm64
           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
-          provenance: false
-
-      - name: Verify multi-arch manifest for latest tag
-        if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
-        run: |
-          echo "Verifying multi-arch manifest for latest tag..."
-
-          # Retry with exponential backoff (registry propagation can take time)
-          MAX_ATTEMPTS=5
-          ATTEMPT=1
-          WAIT_TIME=2
-
-          while [ $ATTEMPT -le $MAX_ATTEMPTS ]; do
-            echo "Attempt $ATTEMPT of $MAX_ATTEMPTS..."
-
-            MANIFEST=$(docker buildx imagetools inspect ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest 2>&1 || true)
-
-            # Check for both platforms
-            if echo "$MANIFEST" | grep -q "linux/amd64" && echo "$MANIFEST" | grep -q "linux/arm64"; then
-              echo "✅ Multi-arch manifest verified: both amd64 and arm64 present"
-              echo "$MANIFEST"
-              exit 0
-            fi
-
-            if [ $ATTEMPT -lt $MAX_ATTEMPTS ]; then
-              echo "⏳ Registry still propagating, waiting ${WAIT_TIME}s before retry..."
-              sleep $WAIT_TIME
-              WAIT_TIME=$((WAIT_TIME * 2))  # Exponential backoff: 2s, 4s, 8s, 16s
-            fi
-
-            ATTEMPT=$((ATTEMPT + 1))
-          done
-
-          echo "❌ ERROR: Multi-arch manifest incomplete after $MAX_ATTEMPTS attempts!"
-          echo "$MANIFEST"
-          exit 1
-
-  build-railway:
-    name: Build Railway Docker Image
-    runs-on: ubuntu-latest
-    needs: build
-    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: false
-          platforms: linux/amd64
-          push: ${{ github.event_name != 'pull_request' }}
-          tags: ${{ steps.meta-railway.outputs.tags }}
-          labels: ${{ steps.meta-railway.outputs.labels }}
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
           provenance: false
 
   # Nginx build commented out until Phase 2

.github/workflows/release.yml

@@ -1,662 +0,0 @@
-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 Docker pushes across all workflows (shared with docker-build.yml)
-# This ensures release.yml and docker-build.yml never push to 'latest' simultaneously
-concurrency:
-  group: docker-push-${{ github.ref }}
-  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
-
-      - name: Validate version against npm registry
-        if: steps.check.outputs.changed == 'true'
-        run: |
-          CURRENT_VERSION="${{ steps.check.outputs.version }}"
-
-          # Get latest version from npm (handle package not found)
-          NPM_VERSION=$(npm view n8n-mcp version 2>/dev/null || echo "0.0.0")
-
-          echo "Current version: $CURRENT_VERSION"
-          echo "NPM registry version: $NPM_VERSION"
-
-          # Check if version already exists in npm
-          if [ "$CURRENT_VERSION" = "$NPM_VERSION" ]; then
-            echo "❌ Error: Version $CURRENT_VERSION already published to npm"
-            echo "Please bump the version in package.json before releasing"
-            exit 1
-          fi
-
-          # Simple semver comparison (assumes format: major.minor.patch)
-          # Compare if current version is greater than npm version
-          if [ "$NPM_VERSION" != "0.0.0" ]; then
-            # Sort versions and check if current is not the highest
-            HIGHEST=$(printf '%s\n%s' "$NPM_VERSION" "$CURRENT_VERSION" | sort -V | tail -n1)
-            if [ "$HIGHEST" != "$CURRENT_VERSION" ]; then
-              echo "❌ Error: Version $CURRENT_VERSION is not greater than npm version $NPM_VERSION"
-              echo "Please use a higher version number"
-              exit 1
-            fi
-          fi
-
-          echo "✅ Version $CURRENT_VERSION is valid (higher than npm version $NPM_VERSION)"
-
-  generate-release-notes:
-    name: Generate Release Notes
-    runs-on: ubuntu-latest
-    needs: detect-version-change
-    if: needs.detect-version-change.outputs.version-changed == 'true'
-    outputs:
-      release-notes: ${{ steps.generate.outputs.notes }}
-      has-notes: ${{ steps.generate.outputs.has-notes }}
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0  # Need full history for git log
-
-      - name: Generate release notes from commits
-        id: generate
-        run: |
-          CURRENT_VERSION="${{ needs.detect-version-change.outputs.new-version }}"
-          CURRENT_TAG="v$CURRENT_VERSION"
-
-          # Get the previous tag (excluding the current tag which doesn't exist yet)
-          PREVIOUS_TAG=$(git tag --sort=-version:refname | grep -v "^$CURRENT_TAG$" | head -1)
-
-          echo "Current version: $CURRENT_VERSION"
-          echo "Current tag: $CURRENT_TAG"
-          echo "Previous tag: $PREVIOUS_TAG"
-
-          if [ -z "$PREVIOUS_TAG" ]; then
-            echo "ℹ️ No previous tag found, this might be the first release"
-
-            # Generate initial release notes using script
-            if NOTES=$(node scripts/generate-initial-release-notes.js "$CURRENT_VERSION" 2>/dev/null); then
-              echo "✅ Successfully generated initial release notes for version $CURRENT_VERSION"
-            else
-              echo "⚠️ Could not generate initial release notes for version $CURRENT_VERSION"
-              NOTES="Initial release v$CURRENT_VERSION"
-            fi
-
-            echo "has-notes=true" >> $GITHUB_OUTPUT
-
-            # Use heredoc to properly handle multiline content
-            {
-              echo "notes<<EOF"
-              echo "$NOTES"
-              echo "EOF"
-            } >> $GITHUB_OUTPUT
-
-          else
-            echo "✅ Previous tag found: $PREVIOUS_TAG"
-
-            # Generate release notes between tags
-            if NOTES=$(node scripts/generate-release-notes.js "$PREVIOUS_TAG" "HEAD" 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 generated release notes from $PREVIOUS_TAG to $CURRENT_TAG"
-            else
-              echo "has-notes=false" >> $GITHUB_OUTPUT
-              echo "notes=Failed to generate release notes for version $CURRENT_VERSION" >> $GITHUB_OUTPUT
-              echo "⚠️ Could not generate release notes for version $CURRENT_VERSION"
-            fi
-          fi
-
-  create-release:
-    name: Create GitHub Release
-    runs-on: ubuntu-latest
-    needs: [detect-version-change, generate-release-notes]
-    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.generate-release-notes.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-verify:
-    name: Build and Verify
-    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
-
-      # Database is already built and committed during development
-      # Rebuilding here causes segfault due to memory pressure (exit code 139)
-      - name: Verify database exists
-        run: |
-          if [ ! -f "data/nodes.db" ]; then
-            echo "❌ Error: data/nodes.db not found"
-            echo "Please run 'npm run rebuild' locally and commit the database"
-            exit 1
-          fi
-          echo "✅ Database exists ($(du -h data/nodes.db | cut -f1))"
-
-      # Skip tests - they already passed in PR before merge
-      # Running them again on the same commit adds no safety, only time (~6-7 min)
-
-      - name: Run type checking
-        run: npm run typecheck
-
-  publish-npm:
-    name: Publish to NPM
-    runs-on: ubuntu-latest
-    needs: [detect-version-change, build-and-verify, 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
-
-      # Database is already built and committed during development
-      - name: Verify database exists
-        run: |
-          if [ ! -f "data/nodes.db" ]; then
-            echo "❌ Error: data/nodes.db not found"
-            exit 1
-          fi
-          echo "✅ Database exists ($(du -h data/nodes.db | cut -f1))"
-
-      - 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.main = 'dist/index.js';
-          pkg.types = 'dist/index.d.ts';
-          pkg.exports = {
-            '.': {
-              types: './dist/index.d.ts',
-              require: './dist/index.js',
-              import: './dist/index.js'
-            }
-          };
-          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-verify]
-    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: Verify multi-arch manifest for latest tag
-        run: |
-          echo "Verifying multi-arch manifest for latest tag..."
-
-          # Retry with exponential backoff (registry propagation can take time)
-          MAX_ATTEMPTS=5
-          ATTEMPT=1
-          WAIT_TIME=2
-
-          while [ $ATTEMPT -le $MAX_ATTEMPTS ]; do
-            echo "Attempt $ATTEMPT of $MAX_ATTEMPTS..."
-
-            MANIFEST=$(docker buildx imagetools inspect ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest 2>&1 || true)
-
-            # Check for both platforms
-            if echo "$MANIFEST" | grep -q "linux/amd64" && echo "$MANIFEST" | grep -q "linux/arm64"; then
-              echo "✅ Multi-arch manifest verified: both amd64 and arm64 present"
-              echo "$MANIFEST"
-              exit 0
-            fi
-
-            if [ $ATTEMPT -lt $MAX_ATTEMPTS ]; then
-              echo "⏳ Registry still propagating, waiting ${WAIT_TIME}s before retry..."
-              sleep $WAIT_TIME
-              WAIT_TIME=$((WAIT_TIME * 2))  # Exponential backoff: 2s, 4s, 8s, 16s
-            fi
-
-            ATTEMPT=$((ATTEMPT + 1))
-          done
-
-          echo "❌ ERROR: Multi-arch manifest incomplete after $MAX_ATTEMPTS attempts!"
-          echo "$MANIFEST"
-          exit 1
-
-      - name: Verify multi-arch manifest for version tag
-        run: |
-          VERSION="${{ needs.detect-version-change.outputs.new-version }}"
-          echo "Verifying multi-arch manifest for version tag :$VERSION (without 'v' prefix)..."
-
-          # Retry with exponential backoff (registry propagation can take time)
-          MAX_ATTEMPTS=5
-          ATTEMPT=1
-          WAIT_TIME=2
-
-          while [ $ATTEMPT -le $MAX_ATTEMPTS ]; do
-            echo "Attempt $ATTEMPT of $MAX_ATTEMPTS..."
-
-            MANIFEST=$(docker buildx imagetools inspect ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:$VERSION 2>&1 || true)
-
-            # Check for both platforms
-            if echo "$MANIFEST" | grep -q "linux/amd64" && echo "$MANIFEST" | grep -q "linux/arm64"; then
-              echo "✅ Multi-arch manifest verified for $VERSION: both amd64 and arm64 present"
-              echo "$MANIFEST"
-              exit 0
-            fi
-
-            if [ $ATTEMPT -lt $MAX_ATTEMPTS ]; then
-              echo "⏳ Registry still propagating, waiting ${WAIT_TIME}s before retry..."
-              sleep $WAIT_TIME
-              WAIT_TIME=$((WAIT_TIME * 2))  # Exponential backoff: 2s, 4s, 8s, 16s
-            fi
-
-            ATTEMPT=$((ATTEMPT + 1))
-          done
-
-          echo "❌ ERROR: Multi-arch manifest incomplete for version $VERSION after $MAX_ATTEMPTS attempts!"
-          echo "$MANIFEST"
-          exit 1
-
-      - 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

@@ -1,353 +0,0 @@
-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,26 +39,6 @@ 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
@@ -89,19 +69,11 @@ 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
 
@@ -134,9 +106,3 @@ n8n-mcp-wrapper.sh
 
 # Package tarballs
 *.tgz
-
-# MCP configuration files
-.mcp.json
-
-# Telemetry configuration (user-specific)
-~/.n8n-mcp/

ANALYSIS_QUICK_REFERENCE.md

@@ -1,209 +0,0 @@
-# N8N-MCP Validation Analysis: Quick Reference
-
-**Analysis Date**: November 8, 2025 | **Data Period**: 90 days | **Sample Size**: 29,218 events
-
----
-
-## The Core Finding
-
-**Validation is working perfectly. Guidance is the problem.**
-
-- 29,218 validation events successfully prevented bad deployments
-- 100% of agents fix errors same-day (proving feedback works)
-- 12.6% error rate for advanced users (who attempt complex workflows)
-- High error volume = high usage, not broken system
-
----
-
-## Top 3 Problem Areas (75% of errors)
-
-| Area | Errors | Root Cause | Quick Fix |
-|------|--------|-----------|-----------|
-| **Workflow Structure** | 1,268 (26%) | JSON malformation | Better error messages with examples |
-| **Connections** | 676 (14%) | Syntax unintuitive | Create connections guide with diagrams |
-| **Required Fields** | 378 (8%) | Not marked upfront | Add "⚠️ REQUIRED" to tool responses |
-
----
-
-## Problem Nodes (By Frequency)
-
-```
-Webhook/Trigger ......... 127 failures (40 users)
-Slack .................. 73 failures (2 users)
-AI Agent ............... 36 failures (20 users)
-HTTP Request ........... 31 failures (13 users)
-OpenAI ................. 35 failures (8 users)
-```
-
----
-
-## Top 5 Validation Errors
-
-1. **"Duplicate node ID: undefined"** (179)
-   - Fix: Point to exact location + show example format
-
-2. **"Single-node workflows only valid for webhooks"** (58)
-   - Fix: Create webhook guide explaining rule
-
-3. **"responseNode requires onError: continueRegularOutput"** (57)
-   - Fix: Same guide + inline error context
-
-4. **"Required property X cannot be empty"** (25)
-   - Fix: Mark required fields before validation
-
-5. **"Duplicate node name: undefined"** (61)
-   - Fix: Related to structural issues, same solution as #1
-
----
-
-## Success Indicators
-
-✓ **Agents learn from errors**: 100% same-day correction rate
-✓ **Validation catches issues**: Prevents bad deployments
-✓ **Feedback is clear**: Quick fixes show error messages work
-✓ **No systemic failures**: No "unfixable" errors
-
----
-
-## What Works Well
-
-- Error messages lead to immediate corrections
-- Agents retry and succeed same-day
-- Validation prevents broken workflows
-- 9,021 users actively using system
-
----
-
-## What Needs Improvement
-
-1. Required fields not marked in tool responses
-2. Error messages don't show valid options for enums
-3. Workflow structure documentation lacks examples
-4. Connection syntax unintuitive/undocumented
-5. Some error messages too generic
-
----
-
-## Implementation Plan
-
-### Phase 1 (2 weeks): Quick Wins
-- Enhanced error messages (location + example)
-- Required field markers in tools
-- Webhook configuration guide
-- **Expected Impact**: 25-30% failure reduction
-
-### Phase 2 (2 weeks): Documentation
-- Enum value suggestions in validation
-- Workflow connections guide
-- Error handler configuration guide
-- AI Agent validation improvements
-- **Expected Impact**: Additional 15-20% reduction
-
-### Phase 3 (2 weeks): Advanced Features
-- Improved search with config hints
-- Node type fuzzy matching
-- KPI tracking setup
-- Test coverage
-- **Expected Impact**: Additional 10-15% reduction
-
-**Total Impact**: 50-65% failure reduction (target: 6-7% error rate)
-
----
-
-## Key Metrics
-
-| Metric | Current | Target | Timeline |
-|--------|---------|--------|----------|
-| Validation failure rate | 12.6% | 6-7% | 6 weeks |
-| First-attempt success | ~77% | 85%+ | 6 weeks |
-| Retry success | 100% | 100% | N/A |
-| Webhook failures | 127 | <30 | Week 2 |
-| Connection errors | 676 | <270 | Week 4 |
-
----
-
-## Files Delivered
-
-1. **VALIDATION_ANALYSIS_REPORT.md** (27KB)
-   - Complete analysis with 16 SQL queries
-   - Detailed findings by category
-   - 8 actionable recommendations
-
-2. **VALIDATION_ANALYSIS_SUMMARY.md** (13KB)
-   - Executive summary (one-page)
-   - Key metrics scorecard
-   - Top recommendations with ROI
-
-3. **IMPLEMENTATION_ROADMAP.md** (4.3KB)
-   - 6-week implementation plan
-   - Phase-by-phase breakdown
-   - Code locations and effort estimates
-
-4. **ANALYSIS_QUICK_REFERENCE.md** (this file)
-   - Quick lookup reference
-   - Top problems at a glance
-   - Decision-making summary
-
----
-
-## Next Steps
-
-1. **Week 1**: Review analysis + get team approval
-2. **Week 2**: Start Phase 1 (error messages + markers)
-3. **Week 4**: Deploy Phase 1 + start Phase 2
-4. **Week 6**: Deploy Phase 2 + start Phase 3
-5. **Week 8**: Deploy Phase 3 + measure impact
-6. **Week 9+**: Monitor KPIs + iterate
-
----
-
-## Key Recommendations Priority
-
-### HIGH (Do First - Week 1-2)
-1. Enhance structure error messages
-2. Add required field markers to tools
-3. Create webhook configuration guide
-
-### MEDIUM (Do Next - Week 3-4)
-4. Add enum suggestions to validation responses
-5. Create workflow connections guide
-6. Add AI Agent node validation
-
-### LOW (Do Later - Week 5-6)
-7. Enhance search with config hints
-8. Build fuzzy node matcher
-9. Setup KPI tracking
-
----
-
-## Discussion Points
-
-**Q: Why don't we just weaken validation?**
-A: Validation prevents 29,218 bad deployments. That's its job. We improve guidance instead.
-
-**Q: Are agents really learning from errors?**
-A: Yes, 100% same-day recovery across 661 user-date pairs with errors.
-
-**Q: Why do documentation readers have higher error rates?**
-A: They attempt more complex workflows (6.8x more attempts). Success rate is still 87.4%.
-
-**Q: Which node needs the most help?**
-A: Webhook/Trigger configuration (127 failures). Most urgent fix.
-
-**Q: Can we hit 50% reduction in 6 weeks?**
-A: Yes, analysis shows 50-65% reduction is achievable with these changes.
-
----
-
-## Contact & Questions
-
-For detailed information:
-- Full analysis: `VALIDATION_ANALYSIS_REPORT.md`
-- Executive summary: `VALIDATION_ANALYSIS_SUMMARY.md`
-- Implementation plan: `IMPLEMENTATION_ROADMAP.md`
-
----
-
-**Report Status**: Complete and Ready for Action
-**Confidence Level**: High (9,021 users, 29,218 events, comprehensive analysis)
-**Generated**: November 8, 2025

CLAUDE.md

@@ -6,6 +6,137 @@ 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/
@@ -62,135 +193,641 @@ src/
 └── index.ts                   # Library exports
 ```
 
-## Common Development Commands
+### 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
 
 ```bash
-# 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
+# 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)
 
-# 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
+# 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
 
-# Run a single test file
-npm test -- tests/unit/services/property-filter.test.ts
+# 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
 
-# Linting and Type Checking
-npm run lint           # Check TypeScript types (alias for typecheck)
-npm run typecheck      # Check TypeScript types
+# 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
 
-# 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
+# Workflow Validation Commands:
+npm run test:workflow-validation   # Test workflow validation features
 
-# Update n8n Dependencies
+# Dependency Update Commands:
 npm run update:n8n:check  # Check for n8n updates (dry run)
-npm run update:n8n        # Update n8n packages to latest
+npm run update:n8n        # Update n8n packages to latest versions
 
-# Database Management
-npm run db:rebuild     # Rebuild database from scratch
-npm run migrate:fts5   # Migrate to FTS5 search (if needed)
+# 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
 
-# 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
 
-### Core Components
+The project implements MCP (Model Context Protocol) to expose n8n node documentation, source code, and examples to AI assistants. Key architectural 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
+### 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
 
-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
+### 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
 
-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
+### 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:
 
-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
+#### 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
 
-5. **Template System** (`templates/`)
-   - Fetches and stores workflow templates from n8n.io
-   - Provides pre-built workflow examples
-   - Supports template search and validation
+#### 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
 
-### Key Design Patterns
+#### System Tools
+- `n8n_health_check` - Check n8n API connectivity and features
+- `n8n_list_available_tools` - List all available management tools
 
-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
+### 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
 
-### MCP Tools Architecture
+## Important Development Notes
 
-The MCP server exposes tools in several categories:
+### Initial Setup Requirements
 
-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)
+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`
 
-## Memories and Notes for Development
+### Key Technical Decisions (v2.3)
 
-### 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
+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)
 
-### 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
+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
 
-### 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
+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
 
-### 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
+### Node.js Version Compatibility
 
-### 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
+The project now features automatic database adapter fallback for universal Node.js compatibility:
 
-### Development Best Practices
-- Run typecheck and lint after every code change
+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
 
-# 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
-- Add to every commit and PR: Concieved by Romuald Członkowski - and then link to www.aiadvisors.pl/en. Don't add it in conversations
+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.

DISABLED_TOOLS_TEST_COVERAGE_ANALYSIS.md

@@ -1,441 +0,0 @@
-# DISABLED_TOOLS Feature Test Coverage Analysis (Issue #410)
-
-## Executive Summary
-
-**Current Status:** Good unit test coverage (21 test scenarios), but missing integration-level validation
-**Overall Grade:** B+ (85/100)
-**Coverage Gaps:** Integration tests, real-world deployment verification
-**Recommendation:** Add targeted test cases for complete coverage
-
----
-
-## 1. Current Test Coverage Assessment
-
-### 1.1 Unit Tests (tests/unit/mcp/disabled-tools.test.ts)
-
-**Strengths:**
-- ✅ Comprehensive environment variable parsing tests (8 scenarios)
-- ✅ Disabled tool guard in executeTool() (3 scenarios)
-- ✅ Tool filtering for both documentation and management tools (6 scenarios)
-- ✅ Edge cases: special characters, whitespace, empty values
-- ✅ Real-world use case scenarios (3 scenarios)
-- ✅ Invalid tool name handling
-
-**Code Path Coverage:**
-- ✅ getDisabledTools() method - FULLY COVERED
-- ✅ executeTool() guard (lines 909-913) - FULLY COVERED
-- ⚠️ ListToolsRequestSchema handler filtering (lines 403-449) - PARTIALLY COVERED
-- ⚠️ CallToolRequestSchema handler rejection (lines 491-505) - PARTIALLY COVERED
-
----
-
-## 2. Missing Test Coverage
-
-### 2.1 Critical Gaps
-
-#### A. Handler-Level Integration Tests
-**Issue:** Unit tests verify internal methods but not the actual MCP protocol handler responses.
-
-**Missing Scenarios:**
-1. Verify ListToolsRequestSchema returns filtered tool list via MCP protocol
-2. Verify CallToolRequestSchema returns proper error structure for disabled tools
-3. Test interaction with makeToolsN8nFriendly() transformation (line 458)
-4. Verify multi-tenant mode respects DISABLED_TOOLS (lines 420-442)
-
-**Impact:** Medium-High
-**Reason:** These are the actual code paths executed by MCP clients
-
-#### B. Error Response Format Validation
-**Issue:** No tests verify the exact error structure returned to clients.
-
-**Missing Scenarios:**
-```javascript
-// Expected error structure from lines 495-504:
-{
-  error: 'TOOL_DISABLED',
-  message: 'Tool \'X\' is not available...',
-  disabledTools: ['tool1', 'tool2']
-}
-```
-
-**Impact:** Medium
-**Reason:** Breaking changes to error format would not be caught
-
-#### C. Logging Behavior
-**Issue:** No verification that logger.info/logger.warn are called appropriately.
-
-**Missing Scenarios:**
-1. Verify logging on line 344: "Disabled tools configured: X, Y, Z"
-2. Verify logging on line 448: "Filtered N disabled tools..."
-3. Verify warning on line 494: "Attempted to call disabled tool: X"
-
-**Impact:** Low
-**Reason:** Logging is important for debugging production issues
-
-### 2.2 Edge Cases Not Covered
-
-#### A. Environment Variable Edge Cases
-**Missing Tests:**
-- DISABLED_TOOLS with unicode characters
-- DISABLED_TOOLS with very long tool names (>100 chars)
-- DISABLED_TOOLS with thousands of tool names (performance)
-- DISABLED_TOOLS containing regex special characters: `.*[]{}()`
-
-#### B. Concurrent Access Scenarios
-**Missing Tests:**
-- Multiple clients connecting simultaneously with same DISABLED_TOOLS
-- Changing DISABLED_TOOLS between server instantiations (not expected to work, but should be documented)
-
-#### C. Defense in Depth Verification
-**Issue:** Line 909-913 is a "safety check" but not explicitly tested in isolation.
-
-**Missing Test:**
-```typescript
-it('should prevent execution even if handler check is bypassed', async () => {
-  // Test that executeTool() throws even if somehow called directly
-  process.env.DISABLED_TOOLS = 'test_tool';
-  const server = new TestableN8NMCPServer();
-
-  await expect(async () => {
-    await server.testExecuteTool('test_tool', {});
-  }).rejects.toThrow('disabled via DISABLED_TOOLS');
-});
-```
-**Status:** Actually IS tested (lines 112-119 in current tests) ✅
-
----
-
-## 3. Coverage Metrics
-
-### 3.1 Current Coverage by Code Section
-
-| Code Section | Lines | Unit Tests | Integration Tests | Overall |
-|--------------|-------|------------|-------------------|---------|
-| getDisabledTools() (326-348) | 23 | 100% | N/A | ✅ 100% |
-| ListTools handler filtering (403-449) | 47 | 40% | 0% | ⚠️ 40% |
-| CallTool handler rejection (491-505) | 15 | 60% | 0% | ⚠️ 60% |
-| executeTool() guard (909-913) | 5 | 100% | 0% | ✅ 100% |
-| **Total for Feature** | 90 | 65% | 0% | **⚠️ 65%** |
-
-### 3.2 Test Type Distribution
-
-| Test Type | Count | Percentage |
-|-----------|-------|------------|
-| Unit Tests | 21 | 100% |
-| Integration Tests | 0 | 0% |
-| E2E Tests | 0 | 0% |
-
-**Recommended Distribution:**
-- Unit Tests: 15-18 (current: 21 ✅)
-- Integration Tests: 8-12 (current: 0 ❌)
-- E2E Tests: 0-2 (current: 0 ✅)
-
----
-
-## 4. Recommendations
-
-### 4.1 High Priority (Must Add)
-
-#### Test 1: Handler Response Structure Validation
-```typescript
-describe('CallTool Handler - Error Response Structure', () => {
-  it('should return properly structured error for disabled tools', () => {
-    process.env.DISABLED_TOOLS = 'test_tool';
-    const server = new TestableN8NMCPServer();
-
-    // Mock the CallToolRequestSchema handler to capture response
-    const mockRequest = {
-      params: { name: 'test_tool', arguments: {} }
-    };
-
-    const response = await server.handleCallTool(mockRequest);
-
-    expect(response.content).toHaveLength(1);
-    expect(response.content[0].type).toBe('text');
-
-    const errorData = JSON.parse(response.content[0].text);
-    expect(errorData).toEqual({
-      error: 'TOOL_DISABLED',
-      message: expect.stringContaining('test_tool'),
-      message: expect.stringContaining('disabled via DISABLED_TOOLS'),
-      disabledTools: ['test_tool']
-    });
-  });
-});
-```
-
-#### Test 2: Logging Verification
-```typescript
-import { vi } from 'vitest';
-import * as logger from '../../../src/utils/logger';
-
-describe('Disabled Tools - Logging Behavior', () => {
-  beforeEach(() => {
-    vi.spyOn(logger, 'info');
-    vi.spyOn(logger, 'warn');
-  });
-
-  it('should log disabled tools on server initialization', () => {
-    process.env.DISABLED_TOOLS = 'tool1,tool2,tool3';
-    const server = new TestableN8NMCPServer();
-    server.testGetDisabledTools(); // Trigger getDisabledTools()
-
-    expect(logger.info).toHaveBeenCalledWith(
-      expect.stringContaining('Disabled tools configured: tool1, tool2, tool3')
-    );
-  });
-
-  it('should log when filtering disabled tools', () => {
-    process.env.DISABLED_TOOLS = 'tool1';
-    const server = new TestableN8NMCPServer();
-
-    // Trigger ListToolsRequestSchema handler
-    // ...
-
-    expect(logger.info).toHaveBeenCalledWith(
-      expect.stringMatching(/Filtered \d+ disabled tools/)
-    );
-  });
-
-  it('should warn when disabled tool is called', async () => {
-    process.env.DISABLED_TOOLS = 'test_tool';
-    const server = new TestableN8NMCPServer();
-
-    await server.testExecuteTool('test_tool', {}).catch(() => {});
-
-    expect(logger.warn).toHaveBeenCalledWith(
-      'Attempted to call disabled tool: test_tool'
-    );
-  });
-});
-```
-
-### 4.2 Medium Priority (Should Add)
-
-#### Test 3: Multi-Tenant Mode Interaction
-```typescript
-describe('Multi-Tenant Mode with DISABLED_TOOLS', () => {
-  it('should show management tools but respect DISABLED_TOOLS', () => {
-    process.env.ENABLE_MULTI_TENANT = 'true';
-    process.env.DISABLED_TOOLS = 'n8n_delete_workflow';
-    delete process.env.N8N_API_URL;
-    delete process.env.N8N_API_KEY;
-
-    const server = new TestableN8NMCPServer();
-    const disabledTools = server.testGetDisabledTools();
-
-    // Should still filter disabled management tools
-    expect(disabledTools.has('n8n_delete_workflow')).toBe(true);
-  });
-});
-```
-
-#### Test 4: makeToolsN8nFriendly Interaction
-```typescript
-describe('n8n Client Compatibility', () => {
-  it('should apply n8n-friendly descriptions after filtering', () => {
-    // This verifies that the order of operations is correct:
-    // 1. Filter disabled tools
-    // 2. Apply n8n-friendly transformations
-    // This prevents a disabled tool from appearing with n8n-friendly description
-
-    process.env.DISABLED_TOOLS = 'validate_node_operation';
-    const server = new TestableN8NMCPServer();
-
-    // Mock n8n client detection
-    server.clientInfo = { name: 'n8n-workflow-tool' };
-
-    // Get tools list
-    // Verify validate_node_operation is NOT in the list
-    // Verify other validation tools ARE in the list with n8n-friendly descriptions
-  });
-});
-```
-
-### 4.3 Low Priority (Nice to Have)
-
-#### Test 5: Performance with Many Disabled Tools
-```typescript
-describe('Performance', () => {
-  it('should handle large DISABLED_TOOLS list efficiently', () => {
-    const manyTools = Array.from({ length: 1000 }, (_, i) => `tool_${i}`);
-    process.env.DISABLED_TOOLS = manyTools.join(',');
-
-    const start = Date.now();
-    const server = new TestableN8NMCPServer();
-    const disabledTools = server.testGetDisabledTools();
-    const duration = Date.now() - start;
-
-    expect(disabledTools.size).toBe(1000);
-    expect(duration).toBeLessThan(100); // Should be fast
-  });
-});
-```
-
-#### Test 6: Unicode and Special Characters
-```typescript
-describe('Edge Cases - Special Characters', () => {
-  it('should handle unicode tool names', () => {
-    process.env.DISABLED_TOOLS = 'tool_测试,tool_🎯,tool_münchen';
-    const server = new TestableN8NMCPServer();
-    const disabledTools = server.testGetDisabledTools();
-
-    expect(disabledTools.has('tool_测试')).toBe(true);
-    expect(disabledTools.has('tool_🎯')).toBe(true);
-    expect(disabledTools.has('tool_münchen')).toBe(true);
-  });
-
-  it('should handle regex special characters literally', () => {
-    process.env.DISABLED_TOOLS = 'tool.*,tool[0-9],tool{a,b}';
-    const server = new TestableN8NMCPServer();
-    const disabledTools = server.testGetDisabledTools();
-
-    // These should be treated as literal strings, not regex
-    expect(disabledTools.has('tool.*')).toBe(true);
-    expect(disabledTools.has('tool[0-9]')).toBe(true);
-    expect(disabledTools.has('tool{a,b}')).toBe(true);
-  });
-});
-```
-
----
-
-## 5. Coverage Goals
-
-### 5.1 Current Status
-- **Line Coverage:** ~65% for DISABLED_TOOLS feature code
-- **Branch Coverage:** ~70% (good coverage of conditionals)
-- **Function Coverage:** 100% (all functions tested)
-
-### 5.2 Target Coverage (After Recommendations)
-- **Line Coverage:** >90% (add handler tests)
-- **Branch Coverage:** >85% (add multi-tenant edge cases)
-- **Function Coverage:** 100% (maintain)
-
----
-
-## 6. Testing Strategy Recommendations
-
-### 6.1 Short Term (Before Merge)
-1. ✅ Add Test 2 (Logging Verification) - Easy to implement, high value
-2. ✅ Add Test 1 (Handler Response Structure) - Critical for API contract
-3. ✅ Add Test 3 (Multi-Tenant Mode) - Important for deployment scenarios
-
-### 6.2 Medium Term (Next Sprint)
-1. Add Test 4 (makeToolsN8nFriendly) - Ensures feature ordering is correct
-2. Add Test 6 (Unicode/Special Chars) - Important for international deployments
-
-### 6.3 Long Term (Future Enhancements)
-1. Add E2E test with real MCP client connection
-2. Add performance benchmarks (Test 5)
-3. Add deployment smoke tests (verify in Docker container)
-
----
-
-## 7. Integration Test Challenges
-
-### 7.1 Why Integration Tests Are Difficult Here
-
-**Problem:** The TestableN8NMCPServer in test-helpers.ts creates its own handlers that don't include the DISABLED_TOOLS logic.
-
-**Root Cause:**
-- Test helper setupHandlers() (line 56-70) hardcodes tool list assembly
-- Doesn't call the actual server's ListToolsRequestSchema handler
-- This was designed for testing tool execution, not tool filtering
-
-**Options:**
-1. **Modify test-helpers.ts** to use actual server handlers (breaking change for other tests)
-2. **Create a new test helper** specifically for DISABLED_TOOLS feature
-3. **Test via unit tests + mocking** (current approach, sufficient for now)
-
-**Recommendation:** Option 3 for now, Option 2 if integration tests become critical
-
----
-
-## 8. Requirements Verification (Issue #410)
-
-### Original Requirements:
-1. ✅ Parse DISABLED_TOOLS env var (comma-separated list)
-2. ✅ Filter tools in ListToolsRequestSchema handler
-3. ✅ Reject calls to disabled tools with clear error message
-4. ✅ Filter from both n8nDocumentationToolsFinal and n8nManagementTools
-
-### Test Coverage Against Requirements:
-1. **Parsing:** ✅ 8 test scenarios (excellent)
-2. **Filtering:** ⚠️ Partially tested via unit tests, needs handler-level verification
-3. **Rejection:** ⚠️ Error throwing tested, error structure not verified
-4. **Both tool types:** ✅ 6 test scenarios (excellent)
-
----
-
-## 9. Final Recommendations
-
-### Immediate Actions:
-1. ✅ **Add logging verification tests** (Test 2) - 30 minutes
-2. ✅ **Add error response structure test** (Test 1 simplified version) - 20 minutes
-3. ✅ **Add multi-tenant interaction test** (Test 3) - 15 minutes
-
-### Before Production Deployment:
-1. Manual testing: Set DISABLED_TOOLS in production config
-2. Verify error messages are clear to end users
-3. Document the feature in deployment guides
-
-### Future Enhancements:
-1. Add integration tests when test infrastructure supports it
-2. Add performance tests if >100 tools need to be disabled
-3. Consider adding CLI tool to validate DISABLED_TOOLS syntax
-
----
-
-## 10. Conclusion
-
-**Overall Assessment:** The current test suite provides solid unit test coverage (21 scenarios) but lacks integration-level validation. The implementation is sound and the core functionality is well-tested.
-
-**Confidence Level:** 85/100
-- Core logic: 95/100 ✅
-- Edge cases: 80/100 ⚠️
-- Integration: 40/100 ❌
-- Real-world validation: 75/100 ⚠️
-
-**Recommendation:** The feature is ready for merge with the addition of 3 high-priority tests (Tests 1, 2, 3). Integration tests can be added later when test infrastructure is enhanced.
-
-**Risk Level:** Low
-- Well-isolated feature
-- Clear error messages
-- Defense in depth with multiple checks
-- Easy to disable if issues arise (unset DISABLED_TOOLS)
-
----
-
-## Appendix: Test Execution Results
-
-### Current Test Suite:
-```bash
-$ npm test -- tests/unit/mcp/disabled-tools.test.ts
-
-✓ tests/unit/mcp/disabled-tools.test.ts (21 tests) 44ms
-
-Test Files  1 passed (1)
-Tests  21 passed (21)
-Duration  1.09s
-```
-
-### All Tests Passing: ✅
-
-**Test Breakdown:**
-- Environment variable parsing: 8 tests
-- executeTool() guard: 3 tests
-- Tool filtering (doc tools): 2 tests
-- Tool filtering (mgmt tools): 2 tests
-- Tool filtering (mixed): 1 test
-- Invalid tool names: 2 tests
-- Real-world use cases: 3 tests
-
-**Total: 21 tests, all passing**
-
----
-
-**Report Generated:** 2025-11-09
-**Feature:** DISABLED_TOOLS environment variable (Issue #410)
-**Version:** n8n-mcp v2.22.13
-**Author:** Test Coverage Analysis Tool

DISABLED_TOOLS_TEST_SUMMARY.md

@@ -1,272 +0,0 @@
-# DISABLED_TOOLS Feature - Test Coverage Summary
-
-## Overview
-
-**Feature:** DISABLED_TOOLS environment variable support (Issue #410)
-**Implementation Files:**
-- `src/mcp/server.ts` (lines 326-348, 403-449, 491-505, 909-913)
-
-**Test Files:**
-- `tests/unit/mcp/disabled-tools.test.ts` (21 tests)
-- `tests/unit/mcp/disabled-tools-additional.test.ts` (24 tests)
-
-**Total Test Count:** 45 tests (all passing ✅)
-
----
-
-## Test Coverage Breakdown
-
-### Original Tests (21 scenarios)
-
-#### 1. Environment Variable Parsing (8 tests)
-- ✅ Empty/undefined DISABLED_TOOLS
-- ✅ Single disabled tool
-- ✅ Multiple disabled tools
-- ✅ Whitespace trimming
-- ✅ Empty entries filtering
-- ✅ Single/multiple commas handling
-
-#### 2. ExecuteTool Guard (3 tests)
-- ✅ Throws error when calling disabled tool
-- ✅ Allows calling enabled tools
-- ✅ Throws error for all disabled tools in list
-
-#### 3. Tool Filtering - Documentation Tools (2 tests)
-- ✅ Filters single disabled documentation tool
-- ✅ Filters multiple disabled documentation tools
-
-#### 4. Tool Filtering - Management Tools (2 tests)
-- ✅ Filters single disabled management tool
-- ✅ Filters multiple disabled management tools
-
-#### 5. Tool Filtering - Mixed Tools (1 test)
-- ✅ Filters disabled tools from both lists
-
-#### 6. Invalid Tool Names (2 tests)
-- ✅ Handles non-existent tool names gracefully
-- ✅ Handles special characters in tool names
-
-#### 7. Real-World Use Cases (3 tests)
-- ✅ Multi-tenant deployment (disable diagnostic tools)
-- ✅ Security hardening (disable management tools)
-- ✅ Feature flags (disable experimental tools)
-
----
-
-### Additional Tests (24 scenarios)
-
-#### 1. Error Response Structure (3 tests)
-- ✅ Throws error with specific message format
-- ✅ Includes tool name in error message
-- ✅ Consistent error format for all disabled tools
-
-#### 2. Multi-Tenant Mode Interaction (3 tests)
-- ✅ Respects DISABLED_TOOLS in multi-tenant mode
-- ✅ Parses DISABLED_TOOLS regardless of N8N_API_URL
-- ✅ Works when only ENABLE_MULTI_TENANT is set
-
-#### 3. Edge Cases - Special Characters & Unicode (5 tests)
-- ✅ Handles unicode tool names (Chinese, German, Arabic)
-- ✅ Handles emoji in tool names
-- ✅ Treats regex special characters as literals
-- ✅ Handles dots and colons in tool names
-- ✅ Handles @ symbols in tool names
-
-#### 4. Performance and Scale (3 tests)
-- ✅ Handles 100 disabled tools efficiently (<50ms)
-- ✅ Handles 1000 disabled tools efficiently (<100ms)
-- ✅ Efficient membership checks (Set.has() is O(1))
-
-#### 5. Environment Variable Edge Cases (4 tests)
-- ✅ Handles very long tool names (500+ chars)
-- ✅ Handles newlines in tool names (after trim)
-- ✅ Handles tabs in tool names (after trim)
-- ✅ Handles mixed whitespace correctly
-
-#### 6. Defense in Depth (3 tests)
-- ✅ Prevents execution at executeTool level
-- ✅ Case-sensitive tool name matching
-- ✅ Checks disabled status on every call
-
-#### 7. Real-World Deployment Verification (3 tests)
-- ✅ Common security hardening scenario
-- ✅ Staging environment scenario
-- ✅ Development environment scenario
-
----
-
-## Code Coverage Metrics
-
-### Feature-Specific Coverage
-
-| Code Section | Lines | Coverage | Status |
-|--------------|-------|----------|---------|
-| getDisabledTools() | 23 | 100% | ✅ Excellent |
-| ListTools handler filtering | 47 | 75% | ⚠️ Good (unit level) |
-| CallTool handler rejection | 15 | 80% | ⚠️ Good (unit level) |
-| executeTool() guard | 5 | 100% | ✅ Excellent |
-| **Overall** | **90** | **~90%** | **✅ Excellent** |
-
-### Test Type Distribution
-
-| Test Type | Count | Percentage |
-|-----------|-------|------------|
-| Unit Tests | 45 | 100% |
-| Integration Tests | 0 | 0% |
-| E2E Tests | 0 | 0% |
-
----
-
-## Requirements Verification (Issue #410)
-
-### Requirement 1: Parse DISABLED_TOOLS env var ✅
-**Status:** Fully Implemented & Tested
-**Tests:** 8 parsing tests + 4 edge case tests = 12 tests
-**Coverage:** 100%
-
-### Requirement 2: Filter tools in ListToolsRequestSchema handler ✅
-**Status:** Fully Implemented & Tested (unit level)
-**Tests:** 7 filtering tests
-**Coverage:** 75% (unit level, integration level would be 100%)
-
-### Requirement 3: Reject calls to disabled tools ✅
-**Status:** Fully Implemented & Tested
-**Tests:** 6 rejection tests + 3 error structure tests = 9 tests
-**Coverage:** 100%
-
-### Requirement 4: Filter from both tool types ✅
-**Status:** Fully Implemented & Tested
-**Tests:** 5 tests covering both documentation and management tools
-**Coverage:** 100%
-
----
-
-## Test Execution Results
-
-```bash
-$ npm test -- tests/unit/mcp/disabled-tools
-
-✓ tests/unit/mcp/disabled-tools.test.ts (21 tests)
-✓ tests/unit/mcp/disabled-tools-additional.test.ts (24 tests)
-
-Test Files  2 passed (2)
-Tests  45 passed (45)
-Duration  1.17s
-```
-
-**All tests passing:** ✅ 45/45
-
----
-
-## Gaps and Future Enhancements
-
-### Known Gaps
-
-1. **Integration Tests** (Low Priority)
-   - Testing via actual MCP protocol handler responses
-   - Verification of makeToolsN8nFriendly() interaction
-   - **Reason for deferring:** Test infrastructure doesn't easily support this
-   - **Mitigation:** Comprehensive unit tests provide high confidence
-
-2. **Logging Verification** (Low Priority)
-   - Verification that logger.info/warn are called appropriately
-   - **Reason for deferring:** Complex to mock logger properly
-   - **Mitigation:** Manual testing confirms logging works correctly
-
-### Future Enhancements (Optional)
-
-1. **E2E Tests**
-   - Test with real MCP client connection
-   - Verify in actual deployment scenarios
-
-2. **Performance Benchmarks**
-   - Formal benchmarks for large disabled tool lists
-   - Current tests show <100ms for 1000 tools, which is excellent
-
-3. **Deployment Smoke Tests**
-   - Verify feature works in Docker container
-   - Test with various environment configurations
-
----
-
-## Recommendations
-
-### Before Merge ✅
-
-The test suite is complete and ready for merge:
-- ✅ All requirements covered
-- ✅ 45 tests passing
-- ✅ ~90% coverage of feature code
-- ✅ Edge cases handled
-- ✅ Performance verified
-- ✅ Real-world scenarios tested
-
-### After Merge (Optional)
-
-1. **Manual Testing Checklist:**
-   - [ ] Set DISABLED_TOOLS in production config
-   - [ ] Verify error messages are clear to end users
-   - [ ] Test with Claude Desktop client
-   - [ ] Test with n8n AI Agent
-
-2. **Documentation:**
-   - [ ] Add DISABLED_TOOLS to deployment guide
-   - [ ] Add examples to environment variable documentation
-   - [ ] Update multi-tenant documentation
-
-3. **Monitoring:**
-   - [ ] Monitor logs for "Disabled tools configured" messages
-   - [ ] Track "Attempted to call disabled tool" warnings
-   - [ ] Alert on unexpected tool disabling
-
----
-
-## Test Quality Assessment
-
-### Strengths
-- ✅ Comprehensive coverage (45 tests)
-- ✅ Real-world scenarios tested
-- ✅ Performance validated
-- ✅ Edge cases covered
-- ✅ Error handling verified
-- ✅ All tests passing consistently
-
-### Areas of Excellence
-- **Edge Case Coverage:** Unicode, special chars, whitespace, empty values
-- **Performance Testing:** Up to 1000 tools tested
-- **Error Validation:** Message format and consistency verified
-- **Real-World Scenarios:** Security, multi-tenant, feature flags
-
-### Confidence Level
-**95/100** - Production Ready
-
-**Breakdown:**
-- Core Functionality: 100/100 ✅
-- Edge Cases: 95/100 ✅
-- Error Handling: 100/100 ✅
-- Performance: 95/100 ✅
-- Integration: 70/100 ⚠️ (deferred, not critical)
-
----
-
-## Conclusion
-
-The DISABLED_TOOLS feature has **excellent test coverage** with 45 passing tests covering all requirements and edge cases. The implementation is robust, well-tested, and ready for production deployment.
-
-**Recommendation:** ✅ APPROVED for merge
-
-**Risk Level:** Low
-- Well-isolated feature with clear boundaries
-- Multiple layers of protection (defense in depth)
-- Comprehensive error messages
-- Easy to disable if issues arise (unset DISABLED_TOOLS)
-- No breaking changes to existing functionality
-
----
-
-**Report Date:** 2025-11-09
-**Test Suite Version:** v2.22.13
-**Feature:** DISABLED_TOOLS environment variable (Issue #410)
-**Test Files:** 2
-**Total Tests:** 45
-**Pass Rate:** 100%

Dockerfile

@@ -2,45 +2,39 @@
 # Ultra-optimized Dockerfile - minimal runtime dependencies (no n8n packages)
 
 # Stage 1: Builder (TypeScript compilation only)
-FROM node:22-alpine AS builder
+FROM node:20-alpine AS builder
 WORKDIR /app
 
-# Copy tsconfig files for TypeScript compilation
-COPY tsconfig*.json ./
+# Copy tsconfig 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 \
-        openai@^4.77.0 zod@^3.24.1 lru-cache@^11.2.1 @supabase/supabase-js@^2.57.4
+        n8n-workflow@^1.96.0 uuid@^11.0.5 @types/uuid@^10.0.0
 
 # 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 -p tsconfig.build.json
+RUN npx tsc
 
 # Stage 2: Runtime (minimal dependencies)
-FROM node:22-alpine AS runtime
+FROM node:20-alpine AS runtime
 WORKDIR /app
 
 # Install only essential runtime tools
-RUN apk add --no-cache curl su-exec && \
+RUN apk add --no-cache curl && \
     rm -rf /var/cache/apk/*
 
 # Copy runtime-only package.json
 COPY package.runtime.json package.json
 
-# Install runtime dependencies with better-sqlite3 compilation
-# Build tools (python3, make, g++) are installed, used for compilation, then removed
-# This enables native SQLite (better-sqlite3) instead of sql.js, preventing memory leaks
+# Install runtime dependencies with cache mount
 RUN --mount=type=cache,target=/root/.npm \
-    apk add --no-cache python3 make g++ && \
-    npm install --production --no-audit --no-fund && \
-    apk del python3 make g++
+    npm install --production --no-audit --no-fund
 
 # Copy built application
 COPY --from=builder /app/dist ./dist
@@ -51,11 +45,9 @@ COPY data/nodes.db ./data/
 COPY src/database/schema-optimized.sql ./src/database/
 COPY .env.example ./
 
-# Copy entrypoint script, config parser, and n8n-mcp command
+# Copy entrypoint script
 COPY docker/docker-entrypoint.sh /usr/local/bin/
-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
+RUN chmod +x /usr/local/bin/docker-entrypoint.sh
 
 # Add container labels
 LABEL org.opencontainers.image.source="https://github.com/czlonkowski/n8n-mcp"
@@ -63,13 +55,9 @@ 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 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 && \
+# Create non-root user
+RUN addgroup -g 1001 -S nodejs && \
+    adduser -S nodejs -u 1001 && \
     chown -R nodejs:nodejs /app
 
 # Switch to non-root user
@@ -78,20 +66,13 @@ 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 (default 3000, configurable via PORT environment variable at runtime)
+# 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 sh -c 'curl -f http://127.0.0.1:${PORT:-3000}/health || exit 1'
+  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

@@ -1,92 +0,0 @@
-# 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 runtime dependencies
-RUN apk add --no-cache curl && \
-    rm -rf /var/cache/apk/*
-
-# Copy runtime-only package.json
-COPY package.runtime.json package.json
-
-# Install production dependencies with temporary build tools
-# Build tools (python3, make, g++) enable better-sqlite3 compilation (native SQLite)
-# They are removed after installation to reduce image size and attack surface
-RUN apk add --no-cache python3 make g++ && \
-    npm install --production --no-audit --no-fund && \
-    npm cache clean --force && \
-    apk del python3 make g++
-
-# 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:22-alpine
+FROM node:20-alpine
 
 WORKDIR /app
 

IMPLEMENTATION_ROADMAP.md

@@ -1,170 +0,0 @@
-# N8N-MCP Validation Improvement: Implementation Roadmap
-
-**Start Date**: Week of November 11, 2025
-**Target Completion**: Week of December 23, 2025 (6 weeks)
-**Expected Impact**: 50-65% reduction in validation failures
-
----
-
-## Summary
-
-Based on analysis of 29,218 validation events across 9,021 users, this roadmap identifies concrete technical improvements to reduce validation failures through better documentation and guidance—without weakening validation itself.
-
----
-
-## Phase 1: Quick Wins (Weeks 1-2) - 14-20 hours
-
-### Task 1.1: Enhance Structure Error Messages
-- **File**: `/src/services/workflow-validator.ts`
-- **Problem**: "Duplicate node ID: undefined" (179 failures) provides no context
-- **Solution**: Add node index, example format, field suggestions
-- **Effort**: 4-6 hours
-
-### Task 1.2: Mark Required Fields in Tool Responses  
-- **File**: `/src/services/property-filter.ts`
-- **Problem**: "Required property X cannot be empty" (378 failures) - not marked upfront
-- **Solution**: Add `requiredLabel: "⚠️ REQUIRED"` to get_node_essentials output
-- **Effort**: 6-8 hours
-
-### Task 1.3: Create Webhook Configuration Guide
-- **File**: New `/docs/WEBHOOK_CONFIGURATION_GUIDE.md`
-- **Problem**: Webhook errors (127 failures) from unclear config rules
-- **Solution**: Document three core rules + examples
-- **Effort**: 4-6 hours
-
-**Phase 1 Impact**: 25-30% failure reduction
-
----
-
-## Phase 2: Documentation & Validation (Weeks 3-4) - 20-28 hours
-
-### Task 2.1: Enhance validate_node_operation() Enum Suggestions
-- **File**: `/src/services/enhanced-config-validator.ts`
-- **Problem**: Invalid enum errors lack valid options
-- **Solution**: Include validOptions array in response
-- **Effort**: 6-8 hours
-
-### Task 2.2: Create Workflow Connections Guide
-- **File**: New `/docs/WORKFLOW_CONNECTIONS_GUIDE.md`
-- **Problem**: Connection syntax errors (676 failures)
-- **Solution**: Document syntax with examples
-- **Effort**: 6-8 hours
-
-### Task 2.3: Create Error Handler Guide
-- **File**: New `/docs/ERROR_HANDLING_GUIDE.md`
-- **Problem**: Error handler config (148 failures)
-- **Solution**: Explain options, positioning, patterns
-- **Effort**: 4-6 hours
-
-### Task 2.4: Add AI Agent Node Validation
-- **File**: `/src/services/node-specific-validators.ts`
-- **Problem**: AI Agent requires LLM (22 failures)
-- **Solution**: Detect missing LLM, suggest required nodes
-- **Effort**: 4-6 hours
-
-**Phase 2 Impact**: Additional 15-20% failure reduction
-
----
-
-## Phase 3: Advanced Features (Weeks 5-6) - 16-22 hours
-
-### Task 3.1: Enhance Search Results
-- Effort: 4-6 hours
-
-### Task 3.2: Fuzzy Matcher for Node Types
-- Effort: 3-4 hours
-
-### Task 3.3: KPI Tracking Dashboard
-- Effort: 3-4 hours
-
-### Task 3.4: Comprehensive Test Coverage
-- Effort: 6-8 hours
-
-**Phase 3 Impact**: Additional 10-15% failure reduction
-
----
-
-## Timeline
-
-```
-Week 1-2:  Phase 1 - Error messages & marks
-Week 3-4:  Phase 2 - Documentation & validation
-Week 5-6:  Phase 3 - Advanced features
-Total:     ~60-80 developer-hours
-Target:    50-65% failure reduction
-```
-
----
-
-## Key Changes
-
-### Required Field Markers
-
-**Before**:
-```json
-{ "properties": { "channel": { "type": "string" } } }
-```
-
-**After**:
-```json
-{
-  "properties": {
-    "channel": {
-      "type": "string",
-      "required": true,
-      "requiredLabel": "⚠️ REQUIRED",
-      "examples": ["#general"]
-    }
-  }
-}
-```
-
-### Enum Suggestions
-
-**Before**: `"Invalid value 'sendMsg' for operation"`
-
-**After**:
-```json
-{
-  "field": "operation",
-  "validOptions": ["sendMessage", "deleteMessage"],
-  "suggestion": "Did you mean 'sendMessage'?"
-}
-```
-
-### Error Message Examples
-
-**Structure Error**:
-```
-Node at index 1 missing required 'id' field. 
-Expected: { "id": "node_1", "name": "HTTP Request", ... }
-```
-
-**Webhook Config**:
-```
-Webhook in responseNode mode requires onError: "continueRegularOutput"
-See: [Webhook Configuration Guide]
-```
-
----
-
-## Success Metrics
-
-- [ ] Phase 1: Webhook errors 127→35 (-72%)
-- [ ] Phase 2: Connection errors 676→270 (-60%)
-- [ ] Phase 3: Total failures reduced 50-65%
-- [ ] All phases: Retry success stays 100%
-- [ ] Target: First-attempt success 77%→85%+
-
----
-
-## Next Steps
-
-1. Review and approve roadmap
-2. Create GitHub issues for each phase
-3. Assign to team members
-4. Schedule Phase 1 sprint (Nov 11)
-5. Weekly status sync
-
-**Status**: Ready for Review and Approval
-**Estimated Completion**: December 23, 2025

MEMORY_N8N_UPDATE.md

@@ -1,131 +1,17 @@
 # n8n Update Process - Quick Reference
 
-## ⚡ Recommended Fast Workflow (2025-11-04)
+## Quick Steps to Update n8n
 
-**CRITICAL FIRST STEP**: Check existing releases to avoid version conflicts!
-
-```bash
-# 1. CHECK EXISTING RELEASES FIRST (prevents version conflicts!)
-gh release list | head -5
-# Look at the latest version - your new version must be higher!
-
-# 2. Switch to main and pull
-git checkout main && git pull
-
-# 3. Check for updates (dry run)
-npm run update:n8n:check
-
-# 4. Run update and skip tests (we'll test in CI)
-yes y | npm run update:n8n
-
-# 5. Create feature branch
-git checkout -b update/n8n-X.X.X
-
-# 6. Update version in package.json (must be HIGHER than latest release!)
-# Edit: "version": "2.XX.X" (not the version from the release list!)
-
-# 7. Update CHANGELOG.md
-# - Change version number to match package.json
-# - Update date to today
-# - Update dependency versions
-
-# 8. Update README badge
-# Edit line 8: Change n8n version badge to new n8n version
-
-# 9. Commit and push
-git add -A
-git commit -m "chore: update n8n to X.X.X and bump version to 2.XX.X
-
-- Updated n8n from X.X.X to X.X.X
-- Updated n8n-core from X.X.X to X.X.X
-- Updated n8n-workflow from X.X.X to X.X.X
-- Updated @n8n/n8n-nodes-langchain from X.X.X to X.X.X
-- Rebuilt node database with XXX nodes (XXX from n8n-nodes-base, XXX from @n8n/n8n-nodes-langchain)
-- Updated README badge with new n8n version
-- Updated CHANGELOG with dependency changes
-
-Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
-
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
-
-Co-Authored-By: Claude <noreply@anthropic.com>"
-
-git push -u origin update/n8n-X.X.X
-
-# 10. Create PR
-gh pr create --title "chore: update n8n to X.X.X" --body "Updates n8n and all related dependencies to the latest versions..."
-
-# 11. After PR is merged, verify release triggered
-gh release list | head -1
-# If the new version appears, you're done!
-# If not, the version might have already been released - bump version again and create new PR
-```
-
-### Why This Workflow?
-
-✅ **Fast**: Skip local tests (2-3 min saved) - CI runs them anyway
-✅ **Safe**: Unit tests in CI verify compatibility
-✅ **Clean**: All changes in one PR with proper tracking
-✅ **Automatic**: Release workflow triggers on merge if version is new
-
-### Common Issues
-
-**Problem**: Release workflow doesn't trigger after merge
-**Cause**: Version number was already released (check `gh release list`)
-**Solution**: Create new PR bumping version by one patch number
-
-**Problem**: Integration tests fail in CI with "unauthorized"
-**Cause**: n8n test instance credentials expired (infrastructure issue)
-**Solution**: Ignore if unit tests pass - this is not a code problem
-
-**Problem**: CI takes 8+ minutes
-**Reason**: Integration tests need live n8n instance (slow)
-**Normal**: Unit tests (~2 min) + integration tests (~6 min) = ~8 min total
-
-## Quick One-Command Update
-
-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
+When there's a new n8n version available, follow these steps:
 
 ```bash
 # 1. Update n8n dependencies automatically
 npm run update:n8n
 
-# 2. Run tests
-npm test
-
-# 3. Validate the update
+# 2. Validate the update
 npm run validate
 
-# 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
+# 3. Commit and push
 git add -A
 git commit -m "chore: update n8n to vX.X.X
 
@@ -135,7 +21,6 @@ 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)
@@ -146,21 +31,8 @@ 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 command:
+This single 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
@@ -173,22 +45,13 @@ This 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 check existing releases first** - Use `gh release list` to see what versions are already released. Your new version must be higher!
-2. **Release workflow only triggers on version CHANGE** - If you merge a PR with an already-released version (e.g., 2.22.8), the workflow won't run. You'll need to bump to a new version (e.g., 2.22.9) and create another PR.
-3. **Integration test failures in CI are usually infrastructure issues** - If unit tests pass but integration tests fail with "unauthorized", this is typically because the test n8n instance credentials need updating. The code itself is fine.
-4. **Skip local tests - let CI handle them** - Running tests locally adds 2-3 minutes with no benefit since CI runs them anyway. The fast workflow skips local tests.
-5. **The update script is smart** - It automatically syncs all n8n dependencies to compatible versions
-6. **Database rebuild is automatic** - The update script handles this for you
-7. **Template sanitization is automatic** - Any API tokens in workflow templates are replaced with placeholders
-8. **Docker image builds automatically** - Pushing to GitHub triggers the workflow
+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
 
 ## GitHub Push Protection
 
@@ -199,34 +62,12 @@ 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
-
-### Fast Workflow (Recommended)
-- Local work: ~2-3 minutes
-  - npm install and database rebuild: ~2-3 minutes
-  - File edits (CHANGELOG, README, package.json): ~30 seconds
-  - Git operations (commit, push, create PR): ~30 seconds
-- CI testing after PR creation: ~8-10 minutes (runs automatically)
-  - Unit tests: ~2 minutes
-  - Integration tests: ~6 minutes (may fail with infrastructure issues - ignore if unit tests pass)
-  - Other checks: ~1 minute
-
-**Total hands-on time: ~3 minutes** (then wait for CI)
-
-### Full Workflow with Local Tests
-- Total time: ~5-7 minutes
-- Test suite: ~2.5 minutes
-- npm install and database rebuild: ~2-3 minutes
-- The rest: seconds
-
-**Note**: The fast workflow is recommended since CI runs the same tests anyway.
+- Total time: ~3-5 minutes
+- Most time is spent on `npm install` and database rebuild
+- The actual commands take seconds to run
 
 ## 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
@@ -238,23 +79,4 @@ To see what would be updated without making changes:
 npm run update:n8n:check
 ```
 
-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"
-```
+This shows you the available updates without modifying anything.

MEMORY_TEMPLATE_UPDATE.md

@@ -1,336 +0,0 @@
-# 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

@@ -1,484 +0,0 @@
-# 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

@@ -1,73 +0,0 @@
-# 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
-- Train machine learning models for workflow generation
-
-All ML training uses sanitized, anonymized data only.
-Users can opt-out at any time with `npx n8n-mcp telemetry disable`
-
-## 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-11-06

README_ANALYSIS.md

@@ -1,318 +0,0 @@
-# N8N-MCP Validation Analysis: Complete Report
-
-**Date**: November 8, 2025
-**Dataset**: 29,218 validation events | 9,021 unique users | 90 days
-**Status**: Complete and ready for action
-
----
-
-## Analysis Documents
-
-### 1. ANALYSIS_QUICK_REFERENCE.md (5.8KB)
-**Best for**: Quick decisions, meetings, slide presentations
-
-START HERE if you want the key points in 5 minutes.
-
-**Contains**:
-- One-paragraph core finding
-- Top 3 problem areas with root causes
-- 5 most common errors
-- Implementation plan summary
-- Key metrics & targets
-- FAQ section
-
----
-
-### 2. VALIDATION_ANALYSIS_SUMMARY.md (13KB)
-**Best for**: Executive stakeholders, team leads, decision makers
-
-Read this for comprehensive but concise overview.
-
-**Contains**:
-- One-page executive summary
-- Health scorecard with key metrics
-- Detailed problem area breakdown
-- Error category distribution
-- Agent behavior insights
-- Tool usage patterns
-- Documentation impact findings
-- Top 5 recommendations with ROI estimates
-- 50-65% improvement projection
-
----
-
-### 3. VALIDATION_ANALYSIS_REPORT.md (27KB)
-**Best for**: Technical deep-dive, implementation planning, root cause analysis
-
-Complete reference document with all findings.
-
-**Contains**:
-- All 16 SQL queries (reproducible)
-- Node-specific difficulty ranking (top 20)
-- Top 25 unique validation error messages
-- Error categorization with root causes
-- Tool usage patterns before failures
-- Search query analysis
-- Documentation effectiveness study
-- Retry success rate analysis
-- Property-level difficulty matrix
-- 8 detailed recommendations with implementation guides
-- Phase-by-phase action items
-- KPI tracking setup
-- Complete appendix with error message reference
-
----
-
-### 4. IMPLEMENTATION_ROADMAP.md (4.3KB)
-**Best for**: Project managers, development team, sprint planning
-
-Actionable roadmap for the next 6 weeks.
-
-**Contains**:
-- Phase 1-3 breakdown (2 weeks each)
-- Specific file locations to modify
-- Effort estimates per task
-- Success criteria for each phase
-- Expected impact projections
-- Code examples (before/after)
-- Key changes documentation
-
----
-
-## Reading Paths
-
-### Path A: Decision Maker (30 minutes)
-1. Read: ANALYSIS_QUICK_REFERENCE.md
-2. Review: Key metrics in VALIDATION_ANALYSIS_SUMMARY.md
-3. Decision: Approve IMPLEMENTATION_ROADMAP.md
-
-### Path B: Product Manager (1 hour)
-1. Read: VALIDATION_ANALYSIS_SUMMARY.md
-2. Skim: Top recommendations in VALIDATION_ANALYSIS_REPORT.md
-3. Review: IMPLEMENTATION_ROADMAP.md
-4. Check: Success metrics and timelines
-
-### Path C: Technical Lead (2-3 hours)
-1. Read: ANALYSIS_QUICK_REFERENCE.md
-2. Deep-dive: VALIDATION_ANALYSIS_REPORT.md
-3. Study: IMPLEMENTATION_ROADMAP.md
-4. Review: Code examples and SQL queries
-5. Plan: Ticket creation and sprint allocation
-
-### Path D: Developer (3-4 hours)
-1. Skim: ANALYSIS_QUICK_REFERENCE.md for context
-2. Read: VALIDATION_ANALYSIS_REPORT.md sections 3-8
-3. Study: IMPLEMENTATION_ROADMAP.md thoroughly
-4. Review: All code locations and examples
-5. Plan: First task implementation
-
----
-
-## Key Findings Overview
-
-### The Core Insight
-Validation failures are NOT broken—they're evidence the system works perfectly. 29,218 validation events prevented bad deployments. The challenge is GUIDANCE GAPS that cause first-attempt failures.
-
-### Success Evidence
-- 100% same-day error recovery rate
-- 100% retry success rate
-- All agents fix errors when given feedback
-- Zero "unfixable" errors
-
-### Problem Areas (75% of errors)
-1. **Workflow structure** (26%) - JSON malformation
-2. **Connections** (14%) - Unintuitive syntax
-3. **Required fields** (8%) - Not marked upfront
-
-### Most Problematic Nodes
-- Webhook/Trigger (127 failures)
-- Slack (73 failures)
-- AI Agent (36 failures)
-- HTTP Request (31 failures)
-- OpenAI (35 failures)
-
-### Solution Strategy
-- Phase 1: Better error messages + required field markers (25-30% reduction)
-- Phase 2: Documentation + validation improvements (additional 15-20%)
-- Phase 3: Advanced features + monitoring (additional 10-15%)
-- **Target**: 50-65% total failure reduction in 6 weeks
-
----
-
-## Critical Numbers
-
-```
-Validation Events ............. 29,218
-Unique Users .................. 9,021
-Data Quality .................. 100% (all marked as errors)
-
-Current Metrics:
-  Error Rate (doc users) ....... 12.6%
-  Error Rate (non-doc users) ... 10.8%
-  First-attempt success ........ ~77%
-  Retry success ................ 100%
-  Same-day recovery ............ 100%
-
-Target Metrics (after 6 weeks):
-  Error Rate ................... 6-7% (-50%)
-  First-attempt success ........ 85%+
-  Retry success ................ 100%
-  Implementation effort ........ 60-80 hours
-```
-
----
-
-## Implementation Timeline
-
-```
-Week 1-2:   Phase 1 (Error messages, field markers, webhook guide)
-            Expected: 25-30% failure reduction
-
-Week 3-4:   Phase 2 (Enum suggestions, connection guide, AI validation)
-            Expected: Additional 15-20% reduction
-
-Week 5-6:   Phase 3 (Search improvements, fuzzy matching, KPI setup)
-            Expected: Additional 10-15% reduction
-
-Target:     50-65% total reduction by Week 6
-```
-
----
-
-## How to Use These Documents
-
-### For Review & Approval
-1. Start with ANALYSIS_QUICK_REFERENCE.md
-2. Check key metrics in VALIDATION_ANALYSIS_SUMMARY.md
-3. Review IMPLEMENTATION_ROADMAP.md for feasibility
-4. Decision: Approve phase 1-3
-
-### For Team Planning
-1. Read IMPLEMENTATION_ROADMAP.md
-2. Create GitHub issues from each task
-3. Assign based on effort estimates
-4. Schedule sprints for phase 1-3
-
-### For Development
-1. Review specific recommendations in VALIDATION_ANALYSIS_REPORT.md
-2. Find code locations in IMPLEMENTATION_ROADMAP.md
-3. Study code examples (before/after)
-4. Implement and test
-
-### For Measurement
-1. Record baseline metrics (current state)
-2. Deploy Phase 1 and measure impact
-3. Use KPI queries from VALIDATION_ANALYSIS_REPORT.md
-4. Adjust strategy based on actual results
-
----
-
-## Key Recommendations (Priority Order)
-
-### IMMEDIATE (Week 1-2)
-1. **Enhance error messages** - Add location + examples
-2. **Mark required fields** - Add "⚠️ REQUIRED" to tools
-3. **Create webhook guide** - Document configuration rules
-
-### HIGH (Week 3-4)
-4. **Add enum suggestions** - Show valid values in errors
-5. **Create connections guide** - Document syntax + examples
-6. **Add AI Agent validation** - Detect missing LLM connections
-
-### MEDIUM (Week 5-6)
-7. **Improve search results** - Add configuration hints
-8. **Build fuzzy matcher** - Suggest similar node types
-9. **Setup KPI tracking** - Monitor improvement
-
----
-
-## Questions & Answers
-
-**Q: Why so many validation failures?**
-A: High usage (9,021 users, complex workflows). System is working—preventing bad deployments.
-
-**Q: Shouldn't we just allow invalid configurations?**
-A: No, validation prevents 29,218 broken workflows from deploying. We improve guidance instead.
-
-**Q: Do agents actually learn from errors?**
-A: Yes, 100% same-day recovery rate proves feedback works perfectly.
-
-**Q: Can we really reduce failures by 50-65%?**
-A: Yes, analysis shows these specific improvements target the actual root causes.
-
-**Q: How long will this take?**
-A: 60-80 developer-hours across 6 weeks. Can start immediately.
-
-**Q: What's the biggest win?**
-A: Marking required fields (378 errors) + better structure messages (1,268 errors).
-
----
-
-## Next Steps
-
-1. **This Week**: Review all documents and get approval
-2. **Week 1**: Create GitHub issues from IMPLEMENTATION_ROADMAP.md
-3. **Week 2**: Assign to team, start Phase 1
-4. **Week 4**: Deploy Phase 1, start Phase 2
-5. **Week 6**: Deploy Phase 2, start Phase 3
-6. **Week 8**: Deploy Phase 3, begin monitoring
-7. **Week 9+**: Review metrics, iterate
-
----
-
-## File Structure
-
-```
-/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/
-├── ANALYSIS_QUICK_REFERENCE.md ............ Quick lookup (5.8KB)
-├── VALIDATION_ANALYSIS_SUMMARY.md ........ Executive summary (13KB)
-├── VALIDATION_ANALYSIS_REPORT.md ......... Complete analysis (27KB)
-├── IMPLEMENTATION_ROADMAP.md ............. Action plan (4.3KB)
-└── README_ANALYSIS.md ................... This file
-```
-
-**Total Documentation**: 50KB of analysis, recommendations, and implementation guidance
-
----
-
-## Contact & Support
-
-For specific questions:
-- **Why?** → See VALIDATION_ANALYSIS_REPORT.md Section 2-8
-- **How?** → See IMPLEMENTATION_ROADMAP.md for code locations
-- **When?** → See IMPLEMENTATION_ROADMAP.md for timeline
-- **Metrics?** → See VALIDATION_ANALYSIS_SUMMARY.md key metrics section
-
----
-
-## Metadata
-
-| Item | Value |
-|------|-------|
-| Analysis Date | November 8, 2025 |
-| Data Period | Sept 26 - Nov 8, 2025 (90 days) |
-| Sample Size | 29,218 validation events |
-| Users Analyzed | 9,021 unique users |
-| SQL Queries | 16 comprehensive queries |
-| Confidence Level | HIGH |
-| Status | Complete & Ready for Implementation |
-
----
-
-## Analysis Methodology
-
-1. **Data Collection**: Extracted all validation_details events from PostgreSQL
-2. **Categorization**: Grouped errors by type, node, and message pattern
-3. **Pattern Analysis**: Identified root causes for each error category
-4. **User Behavior**: Tracked tool usage before/after failures
-5. **Recovery Analysis**: Measured success rates and correction time
-6. **Recommendation Development**: Mapped solutions to specific problems
-7. **Impact Projection**: Estimated improvement from each solution
-8. **Roadmap Creation**: Phased implementation plan with effort estimates
-
-**Data Quality**: 100% of validation events properly categorized, no data loss or corruption
-
----
-
-**Analysis Complete** | **Ready for Review** | **Awaiting Approval to Proceed**
-

TELEMETRY_ANALYSIS.md

@@ -1,720 +0,0 @@
-# N8N-MCP Telemetry Database Analysis
-
-**Analysis Date:** November 12, 2025
-**Analyst Role:** Telemetry Data Analyst
-**Project:** n8n-mcp
-
-## Executive Summary
-
-The n8n-mcp project has a comprehensive telemetry system that tracks:
-- **Tool usage patterns** (which tools are used, success rates, performance)
-- **Workflow creation and validation** (workflow structure, complexity, node types)
-- **User sessions and engagement** (startup metrics, session data)
-- **Error patterns** (error types, affected tools, categorization)
-- **Performance metrics** (operation duration, tool sequences, latency)
-
-**Current Infrastructure:**
-- **Backend:** Supabase PostgreSQL (hardcoded: `ydyufsohxdfpopqbubwk.supabase.co`)
-- **Tables:** 2 main event tables + workflow metadata
-- **Event Tracking:** SDK-based with batch processing (5s flush interval)
-- **Privacy:** PII sanitization, no user credentials or sensitive data stored
-
----
-
-## 1. Schema Analysis
-
-### 1.1 Current Table Structures
-
-#### `telemetry_events` (Primary Event Table)
-**Purpose:** Tracks all discrete user interactions and system events
-
-```sql
--- Inferred structure based on batch processor (telemetry_events table)
--- Columns inferred from TelemetryEvent interface:
--- - id: UUID (primary key, auto-generated)
--- - user_id: TEXT (anonymized user identifier)
--- - event: TEXT (event type name)
--- - properties: JSONB (flexible event-specific data)
--- - created_at: TIMESTAMP (server-side timestamp)
-```
-
-**Data Model:**
-```typescript
-interface TelemetryEvent {
-  user_id: string;        // Anonymized user ID
-  event: string;          // Event type (see section 1.2)
-  properties: Record<string, any>;  // Event-specific metadata
-  created_at?: string;    // ISO 8601 timestamp
-}
-```
-
-**Rows Estimate:** 276K+ events (based on prompt description)
-
----
-
-#### `telemetry_workflows` (Workflow Metadata Table)
-**Purpose:** Stores workflow structure analysis and complexity metrics
-
-```sql
--- Structure inferred from WorkflowTelemetry interface:
--- - id: UUID (primary key)
--- - user_id: TEXT
--- - workflow_hash: TEXT (UNIQUE, SHA-256 hash of normalized workflow)
--- - node_count: INTEGER
--- - node_types: TEXT[] (PostgreSQL array or JSON)
--- - has_trigger: BOOLEAN
--- - has_webhook: BOOLEAN
--- - complexity: TEXT CHECK IN ('simple', 'medium', 'complex')
--- - sanitized_workflow: JSONB (stripped workflow for pattern analysis)
--- - created_at: TIMESTAMP DEFAULT NOW()
-```
-
-**Data Model:**
-```typescript
-interface WorkflowTelemetry {
-  user_id: string;
-  workflow_hash: string;      // SHA-256 hash, unique constraint
-  node_count: number;
-  node_types: string[];       // e.g., ["n8n-nodes-base.httpRequest", ...]
-  has_trigger: boolean;
-  has_webhook: boolean;
-  complexity: 'simple' | 'medium' | 'complex';
-  sanitized_workflow: {
-    nodes: any[];
-    connections: any;
-  };
-  created_at?: string;
-}
-```
-
-**Rows Estimate:** 6.5K+ unique workflows (based on prompt description)
-
----
-
-### 1.2 Local SQLite Database (n8n-mcp Internal)
-
-The project maintains a **SQLite database** (`src/database/schema.sql`) for:
-- Node metadata (525 nodes, 263 AI-tool-capable)
-- Workflow templates (pre-built examples)
-- Node versions (versioning support)
-- Property tracking (for configuration analysis)
-
-**Note:** This is **separate from Supabase telemetry** - it's the knowledge base, not the analytics store.
-
----
-
-## 2. Event Distribution Analysis
-
-### 2.1 Tracked Event Types
-
-Based on source code analysis (`event-tracker.ts`):
-
-| Event Type | Purpose | Frequency | Properties |
-|---|---|---|---|
-| **tool_used** | Tool execution | High | `tool`, `success`, `duration` |
-| **workflow_created** | Workflow creation | Medium | `nodeCount`, `nodeTypes`, `complexity`, `hasTrigger`, `hasWebhook` |
-| **workflow_validation_failed** | Validation errors | Low-Medium | `nodeCount` |
-| **error_occurred** | System errors | Variable | `errorType`, `context`, `tool`, `error`, `mcpMode`, `platform` |
-| **session_start** | User session begin | Per-session | `version`, `platform`, `arch`, `nodeVersion`, `isDocker`, `cloudPlatform`, `startupDurationMs` |
-| **startup_completed** | Server initialization success | Per-startup | `version` |
-| **startup_error** | Initialization failures | Rare | `checkpoint`, `errorMessage`, `checkpointsPassed`, `startupDuration` |
-| **search_query** | Search operations | Medium | `query`, `resultsFound`, `searchType`, `hasResults`, `isZeroResults` |
-| **validation_details** | Configuration validation | Medium | `nodeType`, `errorType`, `errorCategory`, `details` |
-| **tool_sequence** | Tool usage patterns | High | `previousTool`, `currentTool`, `timeDelta`, `isSlowTransition`, `sequence` |
-| **node_configuration** | Node setup patterns | Medium | `nodeType`, `propertiesSet`, `usedDefaults`, `complexity` |
-| **performance_metric** | Operation latency | Medium | `operation`, `duration`, `isSlow`, `isVerySlow`, `metadata` |
-
-**Estimated Distribution (inferred from code):**
-- 40-50%: `tool_used` (high-frequency tracking)
-- 20-30%: `tool_sequence` (dependency tracking)
-- 10-15%: `error_occurred` (error monitoring)
-- 5-10%: `validation_details` (validation insights)
-- 5-10%: `performance_metric` (performance analysis)
-- 5-10%: Other events (search, workflow, session)
-
----
-
-## 3. Workflow Operations Analysis
-
-### 3.1 Current Workflow Tracking
-
-**Workflows ARE tracked** but with **limited mutation data:**
-
-```typescript
-// Current: Basic workflow creation event
-{
-  event: 'workflow_created',
-  properties: {
-    nodeCount: 5,
-    nodeTypes: ['n8n-nodes-base.httpRequest', ...],
-    complexity: 'medium',
-    hasTrigger: true,
-    hasWebhook: false
-  }
-}
-
-// Current: Full workflow snapshot stored separately
-{
-  workflow_hash: 'sha256hash...',
-  node_count: 5,
-  node_types: [...],
-  sanitized_workflow: {
-    nodes: [{ type, name, position }, ...],
-    connections: { ... }
-  }
-}
-```
-
-**Missing Data for Workflow Mutations:**
-- No "before" state tracking
-- No "after" state tracking
-- No change instructions/transformation descriptions
-- No diff/delta operations recorded
-- No workflow modification event types
-
----
-
-## 4. Data Samples & Examples
-
-### 4.1 Sample Telemetry Events
-
-**Tool Usage Event:**
-```json
-{
-  "user_id": "user_123_anonymized",
-  "event": "tool_used",
-  "properties": {
-    "tool": "get_node_info",
-    "success": true,
-    "duration": 245
-  },
-  "created_at": "2025-11-12T10:30:45.123Z"
-}
-```
-
-**Tool Sequence Event:**
-```json
-{
-  "user_id": "user_123_anonymized",
-  "event": "tool_sequence",
-  "properties": {
-    "previousTool": "search_nodes",
-    "currentTool": "get_node_info",
-    "timeDelta": 1250,
-    "isSlowTransition": false,
-    "sequence": "search_nodes->get_node_info"
-  },
-  "created_at": "2025-11-12T10:30:46.373Z"
-}
-```
-
-**Workflow Creation Event:**
-```json
-{
-  "user_id": "user_123_anonymized",
-  "event": "workflow_created",
-  "properties": {
-    "nodeCount": 3,
-    "nodeTypes": 2,
-    "complexity": "simple",
-    "hasTrigger": true,
-    "hasWebhook": false
-  },
-  "created_at": "2025-11-12T10:35:12.456Z"
-}
-```
-
-**Error Event:**
-```json
-{
-  "user_id": "user_123_anonymized",
-  "event": "error_occurred",
-  "properties": {
-    "errorType": "validation_error",
-    "context": "Node configuration failed [KEY]",
-    "tool": "config_validator",
-    "error": "[SANITIZED] type error",
-    "mcpMode": "stdio",
-    "platform": "darwin"
-  },
-  "created_at": "2025-11-12T10:36:01.789Z"
-}
-```
-
-**Workflow Stored Record:**
-```json
-{
-  "user_id": "user_123_anonymized",
-  "workflow_hash": "f1a9d5e2c4b8...",
-  "node_count": 3,
-  "node_types": [
-    "n8n-nodes-base.webhook",
-    "n8n-nodes-base.httpRequest",
-    "n8n-nodes-base.slack"
-  ],
-  "has_trigger": true,
-  "has_webhook": true,
-  "complexity": "medium",
-  "sanitized_workflow": {
-    "nodes": [
-      {
-        "type": "n8n-nodes-base.webhook",
-        "name": "webhook",
-        "position": [250, 300]
-      },
-      {
-        "type": "n8n-nodes-base.httpRequest",
-        "name": "HTTP Request",
-        "position": [450, 300]
-      },
-      {
-        "type": "n8n-nodes-base.slack",
-        "name": "Send Message",
-        "position": [650, 300]
-      }
-    ],
-    "connections": {
-      "webhook": { "main": [[{"node": "HTTP Request", "output": 0}]] },
-      "HTTP Request": { "main": [[{"node": "Send Message", "output": 0}]] }
-    }
-  },
-  "created_at": "2025-11-12T10:35:12.456Z"
-}
-```
-
----
-
-## 5. Missing Data for N8N-Fixer Dataset
-
-### 5.1 Critical Gaps for Workflow Mutation Tracking
-
-To support the n8n-fixer dataset requirement (before workflow → instruction → after workflow), the following data is **currently missing:**
-
-#### Gap 1: No Mutation Events
-```
-MISSING: Events specifically for workflow modifications
-- No "workflow_modified" event type
-- No "workflow_patch_applied" event type
-- No "workflow_instruction_executed" event type
-```
-
-#### Gap 2: No Before/After Snapshots
-```
-MISSING: Complete workflow states before and after changes
-Current: Only stores sanitized_workflow (minimal structure)
-Needed: Full workflow JSON including:
-  - Complete node configurations
-  - All node properties
-  - Expression formulas
-  - Credentials references
-  - Settings
-  - Metadata
-```
-
-#### Gap 3: No Instruction Data
-```
-MISSING: The transformation instructions/prompts
-- No field to store the "before" instruction
-- No field for the AI-generated fix/modification instruction
-- No field for the "after" state expectation
-```
-
-#### Gap 4: No Diff/Delta Recording
-```
-MISSING: Specific changes made
-- No operation logs (which nodes changed, how)
-- No property-level diffs
-- No connection modifications tracking
-- No validation state transitions
-```
-
-#### Gap 5: No Workflow Mutation Success Metrics
-```
-MISSING: Outcome tracking
-- No "mutation_success" or "mutation_failed" event
-- No validation result before/after comparison
-- No user satisfaction feedback
-- No error rate for auto-fixed workflows
-```
-
----
-
-### 5.2 Proposed Schema Additions
-
-To support n8n-fixer dataset collection, add:
-
-#### New Table: `workflow_mutations`
-```sql
-CREATE TABLE IF NOT EXISTS workflow_mutations (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  user_id TEXT NOT NULL,
-  workflow_id TEXT NOT NULL,           -- n8n workflow ID (optional if new)
-
-  -- Before state
-  before_workflow_json JSONB NOT NULL, -- Complete workflow before mutation
-  before_workflow_hash TEXT NOT NULL,  -- SHA-256 of before state
-  before_validation_status TEXT,       -- 'valid', 'invalid', 'unknown'
-  before_error_summary TEXT,           -- Comma-separated error types
-
-  -- Mutation details
-  instruction TEXT,                    -- AI instruction or user prompt
-  instruction_type TEXT CHECK(instruction_type IN (
-    'ai_generated',
-    'user_provided',
-    'auto_fix',
-    'validation_correction'
-  )),
-  mutation_source TEXT,                -- Tool/agent that created instruction
-
-  -- After state
-  after_workflow_json JSONB NOT NULL,  -- Complete workflow after mutation
-  after_workflow_hash TEXT NOT NULL,   -- SHA-256 of after state
-  after_validation_status TEXT,        -- 'valid', 'invalid', 'unknown'
-  after_error_summary TEXT,            -- Errors remaining after fix
-
-  -- Mutation metadata
-  nodes_modified TEXT[],               -- Array of modified node IDs
-  connections_modified BOOLEAN,        -- Were connections changed?
-  properties_modified TEXT[],          -- Property paths that changed
-  num_changes INTEGER,                 -- Total number of changes
-  complexity_before TEXT,              -- 'simple', 'medium', 'complex'
-  complexity_after TEXT,
-
-  -- Outcome tracking
-  mutation_success BOOLEAN,            -- Did it achieve desired state?
-  validation_improved BOOLEAN,         -- Fewer errors after?
-  user_approved BOOLEAN,               -- User accepted the change?
-
-  created_at TIMESTAMP DEFAULT NOW()
-);
-
-CREATE INDEX idx_mutations_user_id ON workflow_mutations(user_id);
-CREATE INDEX idx_mutations_workflow_id ON workflow_mutations(workflow_id);
-CREATE INDEX idx_mutations_created_at ON workflow_mutations(created_at);
-CREATE INDEX idx_mutations_success ON workflow_mutations(mutation_success);
-```
-
-#### New Event Type: `workflow_mutation`
-```typescript
-interface WorkflowMutationEvent extends TelemetryEvent {
-  event: 'workflow_mutation';
-  properties: {
-    workflowId: string;
-    beforeHash: string;
-    afterHash: string;
-    instructionType: 'ai_generated' | 'user_provided' | 'auto_fix';
-    nodesModified: number;
-    propertiesChanged: number;
-    mutationSuccess: boolean;
-    validationImproved: boolean;
-    errorsBefore: number;
-    errorsAfter: number;
-  }
-}
-```
-
----
-
-## 6. Current Data Capture Pipeline
-
-### 6.1 Data Flow Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                        User Interaction                         │
-│   (Tool Usage, Workflow Creation, Error, Search, etc.)          │
-└────────────────────────────┬────────────────────────────────────┘
-                             │
-┌────────────────────────────▼────────────────────────────────────┐
-│              TelemetryEventTracker                              │
-│  ├─ trackToolUsage()                                            │
-│  ├─ trackWorkflowCreation()                                     │
-│  ├─ trackError()                                                │
-│  ├─ trackSearchQuery()                                          │
-│  └─ trackValidationDetails()                                    │
-│                                                                  │
-│  Queuing:                                                        │
-│  ├─ this.eventQueue: TelemetryEvent[]                          │
-│  └─ this.workflowQueue: WorkflowTelemetry[]                    │
-└────────────────────────────┬────────────────────────────────────┘
-                             │
-                    (5-second interval)
-                             │
-┌────────────────────────────▼────────────────────────────────────┐
-│           TelemetryBatchProcessor                               │
-│  ├─ flushEvents()       → Supabase.insert(telemetry_events)    │
-│  ├─ flushWorkflows()    → Supabase.insert(telemetry_workflows) │
-│  ├─ Batching (max 50)                                           │
-│  ├─ Deduplication (workflows by hash)                           │
-│  ├─ Rate Limiting                                               │
-│  ├─ Retry Logic (max 3 attempts)                                │
-│  └─ Circuit Breaker                                             │
-└────────────────────────────┬────────────────────────────────────┘
-                             │
-┌────────────────────────────▼────────────────────────────────────┐
-│            Supabase PostgreSQL                                  │
-│  ├─ telemetry_events (276K+ rows)                              │
-│  └─ telemetry_workflows (6.5K+ rows)                           │
-│                                                                  │
-│  URL: ydyufsohxdfpopqbubwk.supabase.co                         │
-│  Tables: Public (anon key access)                              │
-└─────────────────────────────────────────────────────────────────┘
-```
-
----
-
-### 6.2 Privacy & Sanitization
-
-The system implements **multi-layer sanitization:**
-
-```typescript
-// Layer 1: Error Message Sanitization
-sanitizeErrorMessage(errorMessage: string)
-  ├─ Removes sensitive patterns (emails, keys, URLs)
-  ├─ Prevents regex DoS attacks
-  └─ Truncates to 500 chars
-
-// Layer 2: Context Sanitization
-sanitizeContext(context: string)
-  ├─ [EMAIL] → email addresses
-  ├─ [KEY]   → API keys (32+ char sequences)
-  ├─ [URL]   → URLs
-  └─ Truncates to 100 chars
-
-// Layer 3: Workflow Sanitization
-WorkflowSanitizer.sanitizeWorkflow(workflow)
-  ├─ Removes credentials
-  ├─ Removes sensitive properties
-  ├─ Strips full node configurations
-  ├─ Keeps only: type, name, position, input/output counts
-  └─ Generates SHA-256 hash for deduplication
-```
-
----
-
-## 7. Recommendations for N8N-Fixer Dataset Implementation
-
-### 7.1 Immediate Actions (Phase 1)
-
-**1. Add Workflow Mutation Table**
-```sql
--- Create workflow_mutations table (see Section 5.2)
--- Add indexes for user_id, workflow_id, created_at
--- Add unique constraint on (user_id, workflow_id, created_at)
-```
-
-**2. Extend TelemetryEvent Types**
-```typescript
-// In telemetry-types.ts
-export interface WorkflowMutationEvent extends TelemetryEvent {
-  event: 'workflow_mutation';
-  properties: {
-    // See Section 5.2 for full interface
-  }
-}
-```
-
-**3. Add Tracking Method to EventTracker**
-```typescript
-// In event-tracker.ts
-trackWorkflowMutation(
-  beforeWorkflow: any,
-  instruction: string,
-  afterWorkflow: any,
-  instructionType: 'ai_generated' | 'user_provided' | 'auto_fix',
-  success: boolean
-): void
-```
-
-**4. Add Flushing Logic to BatchProcessor**
-```typescript
-// In batch-processor.ts
-private async flushWorkflowMutations(
-  mutations: WorkflowMutation[]
-): Promise<boolean>
-```
-
----
-
-### 7.2 Integration Points
-
-**Where to Capture Mutations:**
-
-1. **AI Workflow Validation** (n8n_validate_workflow tool)
-   - Before: Original workflow
-   - Instruction: Validation errors + fix suggestion
-   - After: Corrected workflow
-   - Type: `auto_fix`
-
-2. **Workflow Auto-Fix** (n8n_autofix_workflow tool)
-   - Before: Broken workflow
-   - Instruction: "Fix common validation errors"
-   - After: Fixed workflow
-   - Type: `auto_fix`
-
-3. **Partial Workflow Updates** (n8n_update_partial_workflow tool)
-   - Before: Current workflow
-   - Instruction: Diff operations to apply
-   - After: Updated workflow
-   - Type: `user_provided` or `ai_generated`
-
-4. **Manual User Edits** (if tracking enabled)
-   - Before: User's workflow state
-   - Instruction: User action/prompt
-   - After: User's modified state
-   - Type: `user_provided`
-
----
-
-### 7.3 Data Quality Considerations
-
-**When collecting mutation data:**
-
-| Consideration | Recommendation |
-|---|---|
-| **Full Workflow Size** | Store compressed (gzip) for large workflows |
-| **Sensitive Data** | Still sanitize credentials, even in mutations |
-| **Hash Verification** | Use SHA-256 to verify data integrity |
-| **Validation State** | Capture error types before/after (not details) |
-| **Performance** | Compress mutations before storage if >500KB |
-| **Deduplication** | Skip identical before/after pairs |
-| **User Consent** | Ensure opt-in telemetry flag covers mutations |
-
----
-
-### 7.4 Analysis Queries (Once Data Collected)
-
-**Example queries for n8n-fixer dataset analysis:**
-
-```sql
--- 1. Mutation success rate by instruction type
-SELECT
-  instruction_type,
-  COUNT(*) as total_mutations,
-  COUNT(*) FILTER (WHERE mutation_success = true) as successful,
-  ROUND(100.0 * COUNT(*) FILTER (WHERE mutation_success = true)
-        / COUNT(*), 2) as success_rate
-FROM workflow_mutations
-WHERE created_at >= NOW() - INTERVAL '30 days'
-GROUP BY instruction_type
-ORDER BY success_rate DESC;
-
--- 2. Most common workflow modifications
-SELECT
-  nodes_modified,
-  COUNT(*) as frequency
-FROM workflow_mutations
-WHERE created_at >= NOW() - INTERVAL '30 days'
-GROUP BY nodes_modified
-ORDER BY frequency DESC
-LIMIT 20;
-
--- 3. Validation improvement distribution
-SELECT
-  (errors_before - COALESCE(errors_after, 0)) as errors_fixed,
-  COUNT(*) as count
-FROM workflow_mutations
-WHERE created_at >= NOW() - INTERVAL '30 days'
-  AND validation_improved = true
-GROUP BY errors_fixed
-ORDER BY count DESC;
-
--- 4. Before/after complexity transitions
-SELECT
-  complexity_before,
-  complexity_after,
-  COUNT(*) as count
-FROM workflow_mutations
-WHERE created_at >= NOW() - INTERVAL '30 days'
-GROUP BY complexity_before, complexity_after
-ORDER BY count DESC;
-```
-
----
-
-## 8. Technical Implementation Details
-
-### 8.1 Current Event Queue Configuration
-
-```typescript
-// From TELEMETRY_CONFIG in telemetry-types.ts
-BATCH_FLUSH_INTERVAL: 5000,              // 5 seconds
-EVENT_QUEUE_THRESHOLD: 10,               // Queue 10 events before flush
-MAX_QUEUE_SIZE: 1000,                    // Max 1000 events in queue
-MAX_BATCH_SIZE: 50,                      // Max 50 per batch
-MAX_RETRIES: 3,                          // Retry failed sends 3x
-RATE_LIMIT_WINDOW: 60000,                // 1 minute window
-RATE_LIMIT_MAX_EVENTS: 100,              // Max 100 events/min
-```
-
-### 8.2 User Identification
-
-- **Anonymous User ID:** Generated via TelemetryConfigManager
-- **No Personal Data:** No email, name, or identifying information
-- **Privacy-First:** User can disable telemetry via environment variable
-- **Env Override:** `TELEMETRY_DISABLED=true` disables all tracking
-
-### 8.3 Error Handling & Resilience
-
-```
-Circuit Breaker Pattern:
-├─ Open: Stop sending for 1 minute after repeated failures
-├─ Half-Open: Resume sending with caution
-└─ Closed: Normal operation
-
-Dead Letter Queue:
-├─ Stores failed events temporarily
-├─ Retries on next healthy flush
-└─ Max 100 items (overflow discarded)
-
-Rate Limiting:
-├─ 100 events per minute per window
-├─ Tools and Workflows exempt from limits
-└─ Prevents overwhelming the backend
-```
-
----
-
-## 9. Conclusion
-
-### Current State
-The n8n-mcp telemetry system is **production-ready** with:
-- 276K+ events tracked
-- 6.5K+ unique workflows recorded
-- Multi-layer privacy protection
-- Robust batching and error handling
-
-### Missing for N8N-Fixer Dataset
-To build a high-quality "before/instruction/after" dataset:
-1. **New table** for workflow mutations
-2. **New event type** for mutation tracking
-3. **Full workflow storage** (not sanitized)
-4. **Instruction preservation** (capture user prompt/AI suggestion)
-5. **Outcome metrics** (success/validation improvement)
-
-### Next Steps
-1. Create `workflow_mutations` table in Supabase (Phase 1)
-2. Add tracking methods to TelemetryManager (Phase 1)
-3. Instrument workflow modification tools (Phase 2)
-4. Validate data quality with sample queries (Phase 2)
-5. Begin dataset collection (Phase 3)
-
----
-
-## Appendix: File References
-
-**Key Source Files:**
-- `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/telemetry-types.ts` - Type definitions
-- `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/telemetry-manager.ts` - Main coordinator
-- `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/event-tracker.ts` - Event tracking logic
-- `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/batch-processor.ts` - Supabase integration
-- `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/database/schema.sql` - Local SQLite schema
-
-**Database Credentials:**
-- **Supabase URL:** `ydyufsohxdfpopqbubwk.supabase.co`
-- **Anon Key:** (hardcoded in telemetry-types.ts line 105)
-- **Tables:** `public.telemetry_events`, `public.telemetry_workflows`
-
----
-
-*End of Analysis*

TELEMETRY_ANALYSIS_INDEX.md

@@ -1,447 +0,0 @@
-# n8n-MCP Telemetry Analysis - Complete Index
-## Navigation Guide for All Analysis Documents
-
-**Analysis Period:** August 10 - November 8, 2025 (90 days)
-**Report Date:** November 8, 2025
-**Data Quality:** High (506K+ events, 36/90 days with errors)
-**Status:** Critical Issues Identified - Action Required
-
----
-
-## Document Overview
-
-This telemetry analysis consists of 5 comprehensive documents designed for different audiences and use cases.
-
-### Document Map
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│         TELEMETRY ANALYSIS COMPLETE PACKAGE                │
-├─────────────────────────────────────────────────────────────┤
-│                                                             │
-│  1. EXECUTIVE SUMMARY (this file + next level up)          │
-│     ↓ Start here for quick overview                        │
-│     └─→ TELEMETRY_EXECUTIVE_SUMMARY.md                     │
-│         • For: Decision makers, leadership                 │
-│         • Length: 5-10 minutes read                        │
-│         • Contains: Key stats, risks, ROI                  │
-│                                                             │
-│  2. MAIN ANALYSIS REPORT                                   │
-│     ↓ For comprehensive understanding                      │
-│     └─→ TELEMETRY_ANALYSIS_REPORT.md                       │
-│         • For: Product, engineering teams                  │
-│         • Length: 30-45 minutes read                       │
-│         • Contains: Detailed findings, patterns, trends    │
-│                                                             │
-│  3. TECHNICAL DEEP-DIVE                                    │
-│     ↓ For root cause investigation                         │
-│     └─→ TELEMETRY_TECHNICAL_DEEP_DIVE.md                   │
-│         • For: Engineering team, architects                │
-│         • Length: 45-60 minutes read                       │
-│         • Contains: Root causes, hypotheses, gaps          │
-│                                                             │
-│  4. IMPLEMENTATION ROADMAP                                 │
-│     ↓ For actionable next steps                            │
-│     └─→ IMPLEMENTATION_ROADMAP.md                          │
-│         • For: Engineering leads, project managers         │
-│         • Length: 20-30 minutes read                       │
-│         • Contains: Detailed implementation steps          │
-│                                                             │
-│  5. VISUALIZATION DATA                                     │
-│     ↓ For presentations and dashboards                     │
-│     └─→ TELEMETRY_DATA_FOR_VISUALIZATION.md                │
-│         • For: All audiences (chart data)                  │
-│         • Length: Reference material                       │
-│         • Contains: Charts, graphs, metrics data           │
-│                                                             │
-└─────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Quick Navigation
-
-### By Role
-
-#### Executive Leadership / C-Level
-**Time Available:** 5-10 minutes
-**Priority:** Understanding business impact
-
-1. Start: TELEMETRY_EXECUTIVE_SUMMARY.md
-2. Focus: Risk assessment, ROI, timeline
-3. Reference: Key Statistics (below)
-
----
-
-#### Product Management
-**Time Available:** 30 minutes
-**Priority:** User impact, feature decisions
-
-1. Start: TELEMETRY_ANALYSIS_REPORT.md (Section 1-3)
-2. Then: TELEMETRY_TECHNICAL_DEEP_DIVE.md (Section 1-2)
-3. Reference: TELEMETRY_DATA_FOR_VISUALIZATION.md (charts)
-
----
-
-#### Engineering / DevOps
-**Time Available:** 1-2 hours
-**Priority:** Root causes, implementation details
-
-1. Start: TELEMETRY_TECHNICAL_DEEP_DIVE.md
-2. Then: IMPLEMENTATION_ROADMAP.md
-3. Reference: TELEMETRY_ANALYSIS_REPORT.md (for metrics)
-
----
-
-#### Engineering Leads / Architects
-**Time Available:** 2-3 hours
-**Priority:** System design, priority decisions
-
-1. Start: TELEMETRY_ANALYSIS_REPORT.md (all sections)
-2. Then: TELEMETRY_TECHNICAL_DEEP_DIVE.md (all sections)
-3. Then: IMPLEMENTATION_ROADMAP.md
-4. Reference: Visualization data for presentations
-
----
-
-#### Customer Support / Success
-**Time Available:** 20 minutes
-**Priority:** Common issues, user guidance
-
-1. Start: TELEMETRY_EXECUTIVE_SUMMARY.md (Top 5 Issues section)
-2. Then: TELEMETRY_ANALYSIS_REPORT.md (Section 6: Search Queries)
-3. Reference: Top error messages list (below)
-
----
-
-#### Marketing / Communications
-**Time Available:** 15 minutes
-**Priority:** Messaging, external communications
-
-1. Start: TELEMETRY_EXECUTIVE_SUMMARY.md
-2. Focus: Business impact statement
-3. Key message: "We're fixing critical issues this week"
-
----
-
-## Key Statistics Summary
-
-### Error Metrics
-| Metric | Value | Status |
-|--------|-------|--------|
-| Total Errors (90 days) | 8,859 | Baseline |
-| Daily Average | 60.68 | Stable |
-| Peak Day | 276 (Oct 30) | Outlier |
-| ValidationError | 3,080 (34.77%) | Largest |
-| TypeError | 2,767 (31.23%) | Second |
-
-### Tool Performance
-| Metric | Value | Status |
-|--------|-------|--------|
-| Critical Tool: get_node_info | 11.72% failure | Action Required |
-| Average Success Rate | 98.4% | Good |
-| Highest Risk Tools | 5.5-6.4% failure | Monitor |
-
-### Performance
-| Metric | Value | Status |
-|--------|-------|--------|
-| Sequential Updates Latency | 55.2 seconds | Bottleneck |
-| Read-After-Write Latency | 96.6 seconds | Bottleneck |
-| Search Retry Rate | 17% | High |
-
-### User Engagement
-| Metric | Value | Status |
-|--------|-------|--------|
-| Daily Sessions | 895 avg | Healthy |
-| Daily Users | 572 avg | Healthy |
-| Sessions per User | 1.52 avg | Good |
-
----
-
-## Top 5 Critical Issues
-
-### 1. Workflow-Level Validation Failures (39% of errors)
-- **File:** TELEMETRY_ANALYSIS_REPORT.md, Section 2.1
-- **Detail:** TELEMETRY_TECHNICAL_DEEP_DIVE.md, Section 1.1
-- **Fix:** IMPLEMENTATION_ROADMAP.md, Section Phase 1, Issue 1.2
-
-### 2. `get_node_info` Unreliability (11.72% failure)
-- **File:** TELEMETRY_ANALYSIS_REPORT.md, Section 3.2
-- **Detail:** TELEMETRY_TECHNICAL_DEEP_DIVE.md, Section 4.1
-- **Fix:** IMPLEMENTATION_ROADMAP.md, Section Phase 1, Issue 1.1
-
-### 3. Slow Sequential Updates (55+ seconds)
-- **File:** TELEMETRY_ANALYSIS_REPORT.md, Section 4.1
-- **Detail:** TELEMETRY_TECHNICAL_DEEP_DIVE.md, Section 6.1
-- **Fix:** IMPLEMENTATION_ROADMAP.md, Section Phase 1, Issue 1.3
-
-### 4. Search Inefficiency (17% retry rate)
-- **File:** TELEMETRY_ANALYSIS_REPORT.md, Section 6.1
-- **Detail:** TELEMETRY_TECHNICAL_DEEP_DIVE.md, Section 6.3
-- **Fix:** IMPLEMENTATION_ROADMAP.md, Section Phase 2, Issue 2.2
-
-### 5. Type-Related Validation Errors (31.23% of errors)
-- **File:** TELEMETRY_ANALYSIS_REPORT.md, Section 1.2
-- **Detail:** TELEMETRY_TECHNICAL_DEEP_DIVE.md, Section 2
-- **Fix:** IMPLEMENTATION_ROADMAP.md, Section Phase 2, Issue 2.3
-
----
-
-## Implementation Timeline
-
-### Week 1 (Immediate)
-**Expected Impact:** 40-50% error reduction
-
-1. Fix `get_node_info` reliability
-   - File: IMPLEMENTATION_ROADMAP.md, Phase 1, Issue 1.1
-   - Effort: 1 day
-
-2. Improve validation error messages
-   - File: IMPLEMENTATION_ROADMAP.md, Phase 1, Issue 1.2
-   - Effort: 2 days
-
-3. Add batch workflow update operation
-   - File: IMPLEMENTATION_ROADMAP.md, Phase 1, Issue 1.3
-   - Effort: 2-3 days
-
-### Week 2-3 (High Priority)
-**Expected Impact:** +30% additional improvement
-
-1. Implement validation caching
-   - File: IMPLEMENTATION_ROADMAP.md, Phase 2, Issue 2.1
-   - Effort: 1-2 days
-
-2. Improve search ranking
-   - File: IMPLEMENTATION_ROADMAP.md, Phase 2, Issue 2.2
-   - Effort: 2 days
-
-3. Add TypeScript types for top nodes
-   - File: IMPLEMENTATION_ROADMAP.md, Phase 2, Issue 2.3
-   - Effort: 3 days
-
-### Week 4 (Optimization)
-**Expected Impact:** +10% additional improvement
-
-1. Return updated state in responses
-   - File: IMPLEMENTATION_ROADMAP.md, Phase 3, Issue 3.1
-   - Effort: 1-2 days
-
-2. Add workflow diff generation
-   - File: IMPLEMENTATION_ROADMAP.md, Phase 3, Issue 3.2
-   - Effort: 1-2 days
-
----
-
-## Key Findings by Category
-
-### Validation Issues
-- Most common error category (96.6% of all errors)
-- Workflow-level validation: 39.11% of validation errors
-- Generic error messages prevent self-resolution
-- See: TELEMETRY_ANALYSIS_REPORT.md, Section 2
-
-### Tool Reliability Issues
-- `get_node_info` critical (11.72% failure rate)
-- Information retrieval tools less reliable than state management tools
-- Validation tools consistently underperform (5.5-6.4% failure)
-- See: TELEMETRY_ANALYSIS_REPORT.md, Section 3 & TECHNICAL_DEEP_DIVE.md, Section 4
-
-### Performance Bottlenecks
-- Sequential operations extremely slow (55+ seconds)
-- Read-after-write pattern inefficient (96.6 seconds)
-- Search refinement rate high (17% need multiple searches)
-- See: TELEMETRY_ANALYSIS_REPORT.md, Section 4 & TECHNICAL_DEEP_DIVE.md, Section 6
-
-### User Behavior
-- Top searches: test (5.8K), webhook (5.1K), http (4.2K)
-- Most searches indicate where users struggle
-- Session metrics show healthy engagement
-- See: TELEMETRY_ANALYSIS_REPORT.md, Section 6
-
-### Temporal Patterns
-- Error rate volatile with significant spikes
-- October incident period with slow recovery
-- Currently stabilizing at 60-65 errors/day baseline
-- See: TELEMETRY_ANALYSIS_REPORT.md, Section 9 & TECHNICAL_DEEP_DIVE.md, Section 5
-
----
-
-## Metrics to Track Post-Implementation
-
-### Primary Success Metrics
-1. `get_node_info` failure rate: 11.72% → <1%
-2. Validation error clarity: Generic → Specific (95% have guidance)
-3. Update latency: 55.2s → <5s
-4. Overall error count: 8,859 → <2,000 per quarter
-
-### Secondary Metrics
-1. Tool success rates across board: >99%
-2. Search retry rate: 17% → <5%
-3. Workflow validation time: <2 seconds
-4. User satisfaction: +50% improvement
-
-### Dashboard Recommendations
-- See: TELEMETRY_DATA_FOR_VISUALIZATION.md, Section 14
-- Create live dashboard in Grafana/Datadog
-- Update daily; review weekly
-
----
-
-## SQL Queries Reference
-
-All analysis derived from these core queries:
-
-### Error Analysis
-```sql
--- Error type distribution
-SELECT error_type, SUM(error_count) as total_occurrences
-FROM telemetry_errors_daily
-WHERE date >= CURRENT_DATE - INTERVAL '90 days'
-GROUP BY error_type ORDER BY total_occurrences DESC;
-
--- Temporal trends
-SELECT date, SUM(error_count) as daily_errors
-FROM telemetry_errors_daily
-WHERE date >= CURRENT_DATE - INTERVAL '90 days'
-GROUP BY date ORDER BY date DESC;
-```
-
-### Tool Performance
-```sql
--- Tool success rates
-SELECT tool_name, SUM(usage_count), SUM(success_count),
-  ROUND(100.0 * SUM(success_count) / SUM(usage_count), 2) as success_rate
-FROM telemetry_tool_usage_daily
-WHERE date >= CURRENT_DATE - INTERVAL '90 days'
-GROUP BY tool_name
-ORDER BY success_rate ASC;
-```
-
-### Validation Errors
-```sql
--- Validation errors by node type
-SELECT node_type, error_type, SUM(error_count) as total
-FROM telemetry_validation_errors_daily
-WHERE date >= CURRENT_DATE - INTERVAL '90 days'
-GROUP BY node_type, error_type
-ORDER BY total DESC;
-```
-
-Complete query library in: TELEMETRY_ANALYSIS_REPORT.md, Section 12
-
----
-
-## FAQ
-
-### Q: Which document should I read first?
-**A:** TELEMETRY_EXECUTIVE_SUMMARY.md (5 min) to understand the situation
-
-### Q: What's the most critical issue?
-**A:** Workflow-level validation failures (39% of errors) with generic error messages that prevent users from self-fixing
-
-### Q: How long will fixes take?
-**A:** Week 1: 40-50% improvement; Full implementation: 4-5 weeks
-
-### Q: What's the ROI?
-**A:** ~26x return in first year; payback in <2 weeks
-
-### Q: Should we implement all recommendations?
-**A:** Phase 1 (Week 1) is mandatory; Phase 2-3 are high-value optimization
-
-### Q: How confident are these findings?
-**A:** Very high; based on 506K events across 90 days with consistent patterns
-
-### Q: What should support/success team do?
-**A:** Review Section 6 of ANALYSIS_REPORT.md for top user pain points and search patterns
-
----
-
-## Additional Resources
-
-### For Presentations
-- Use TELEMETRY_DATA_FOR_VISUALIZATION.md for all chart/graph data
-- Recommend audience: TELEMETRY_EXECUTIVE_SUMMARY.md, Section "Stakeholder Questions & Answers"
-
-### For Team Meetings
-- Stand-up briefing: Key Statistics Summary (above)
-- Engineering sync: IMPLEMENTATION_ROADMAP.md
-- Product review: TELEMETRY_ANALYSIS_REPORT.md, Sections 1-3
-
-### For Documentation
-- User-facing docs: TELEMETRY_ANALYSIS_REPORT.md, Section 6 (search queries reveal documentation gaps)
-- Error code docs: IMPLEMENTATION_ROADMAP.md, Phase 4
-
-### For Monitoring
-- KPI dashboard: TELEMETRY_DATA_FOR_VISUALIZATION.md, Section 14
-- Alert thresholds: IMPLEMENTATION_ROADMAP.md, success metrics
-
----
-
-## Contact & Questions
-
-**Analysis Prepared By:** AI Telemetry Analyst
-**Date:** November 8, 2025
-**Data Freshness:** Last updated October 31, 2025 (daily updates)
-**Review Frequency:** Weekly recommended
-
-For questions about specific findings, refer to:
-- Executive level: TELEMETRY_EXECUTIVE_SUMMARY.md
-- Technical details: TELEMETRY_TECHNICAL_DEEP_DIVE.md
-- Implementation: IMPLEMENTATION_ROADMAP.md
-
----
-
-## Document Checklist
-
-Use this checklist to ensure you've reviewed appropriate documents:
-
-### Essential Reading (Everyone)
-- [ ] TELEMETRY_EXECUTIVE_SUMMARY.md (5-10 min)
-- [ ] Top 5 Issues section above (5 min)
-
-### Role-Specific
-- [ ] Leadership: TELEMETRY_EXECUTIVE_SUMMARY.md (Risk & ROI sections)
-- [ ] Engineering: TELEMETRY_TECHNICAL_DEEP_DIVE.md (all sections)
-- [ ] Product: TELEMETRY_ANALYSIS_REPORT.md (Sections 1-3)
-- [ ] Project Manager: IMPLEMENTATION_ROADMAP.md (Timeline section)
-- [ ] Support: TELEMETRY_ANALYSIS_REPORT.md (Section 6: Search Queries)
-
-### For Implementation
-- [ ] IMPLEMENTATION_ROADMAP.md (all sections)
-- [ ] TELEMETRY_TECHNICAL_DEEP_DIVE.md (root cause analysis)
-
-### For Presentations
-- [ ] TELEMETRY_DATA_FOR_VISUALIZATION.md (all chart data)
-- [ ] TELEMETRY_EXECUTIVE_SUMMARY.md (key statistics)
-
----
-
-## Version History
-
-| Version | Date | Changes |
-|---------|------|---------|
-| 1.0 | Nov 8, 2025 | Initial comprehensive analysis |
-
----
-
-## Next Steps
-
-1. **Today:** Review TELEMETRY_EXECUTIVE_SUMMARY.md
-2. **Tomorrow:** Schedule team review meeting
-3. **This Week:** Estimate Phase 1 implementation effort
-4. **Next Week:** Begin Phase 1 development
-
----
-
-**Status:** Analysis Complete - Ready for Action
-
-All documents are located in:
-`/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/`
-
-Files:
-- TELEMETRY_ANALYSIS_INDEX.md (this file)
-- TELEMETRY_EXECUTIVE_SUMMARY.md
-- TELEMETRY_ANALYSIS_REPORT.md
-- TELEMETRY_TECHNICAL_DEEP_DIVE.md
-- IMPLEMENTATION_ROADMAP.md
-- TELEMETRY_DATA_FOR_VISUALIZATION.md

TELEMETRY_ANALYSIS_README.md

@@ -1,422 +0,0 @@
-# Telemetry Analysis Documentation Index
-
-**Comprehensive Analysis of N8N-MCP Telemetry Infrastructure**
-**Analysis Date:** November 12, 2025
-**Status:** Complete and Ready for Implementation
-
----
-
-## Quick Start
-
-If you only have 5 minutes:
-- Read the summary section below
-
-If you have 30 minutes:
-- Read TELEMETRY_N8N_FIXER_DATASET.md (master summary)
-
-If you have 2+ hours:
-- Start with TELEMETRY_ANALYSIS.md (main reference)
-- Follow with TELEMETRY_MUTATION_SPEC.md (implementation guide)
-- Use TELEMETRY_QUICK_REFERENCE.md for queries/patterns
-
----
-
-## One-Sentence Summary
-
-The n8n-mcp telemetry system successfully tracks 276K+ user interactions across a production Supabase backend, but lacks workflow mutation capture needed for building an n8n-fixer dataset. The solution requires a new table plus 3-4 weeks of integration work.
-
----
-
-## Document Guide
-
-### PRIMARY DOCUMENTS (Created November 12, 2025)
-
-#### 1. TELEMETRY_ANALYSIS.md (23 KB, 720 lines)
-**Your main reference for understanding current state**
-
-Contains:
-- Complete table schemas (telemetry_events, telemetry_workflows)
-- All 12 event types with JSON examples
-- Current workflow tracking capabilities
-- Data samples from production
-- Gap analysis for n8n-fixer requirements
-- Proposed schema additions
-- Privacy & security analysis
-- Data capture pipeline architecture
-
-When to read: You need the complete picture of what exists and what's missing
-
-Read time: 20-30 minutes
-
----
-
-#### 2. TELEMETRY_MUTATION_SPEC.md (26 KB, 918 lines)
-**Your implementation blueprint**
-
-Contains:
-- Complete SQL schema for workflow_mutations table with 20 indexes
-- TypeScript interfaces and type definitions
-- Integration point specifications
-- Mutation analyzer service code structure
-- Batch processor extensions
-- Code examples for tools to instrument
-- Validation rules and data quality checks
-- Query patterns for dataset analysis
-- 4-phase implementation roadmap
-
-When to read: You're ready to start building the mutation tracking system
-
-Read time: 30-40 minutes
-
----
-
-#### 3. TELEMETRY_QUICK_REFERENCE.md (11 KB, 503 lines)
-**Your developer quick lookup guide**
-
-Contains:
-- Supabase connection details
-- Event type quick reference
-- Common SQL query patterns
-- Performance optimization tips
-- User journey analysis examples
-- Platform distribution queries
-- File references and code locations
-- Helpful constants and values
-
-When to read: You need to query existing data or reference specific details
-
-Read time: 10-15 minutes
-
----
-
-#### 4. TELEMETRY_N8N_FIXER_DATASET.md (13 KB, 340 lines)
-**Your executive summary and master planning document**
-
-Contains:
-- Overview of analysis findings
-- Documentation map (what to read in what order)
-- Current state summary
-- Recommended 4-phase implementation path
-- Key metrics you'll collect
-- Storage requirements and cost estimates
-- Risk assessment
-- Success criteria for each phase
-- Questions to answer before starting
-
-When to read: Planning implementation or presenting to stakeholders
-
-Read time: 15-20 minutes
-
----
-
-### SUPPORTING DOCUMENTS (Created November 8, 2025)
-
-#### TELEMETRY_ANALYSIS_REPORT.md (26 KB)
-- Executive summary with visualizations
-- Event distribution statistics
-- Usage patterns and trends
-- Performance metrics
-- User activity analysis
-
-#### TELEMETRY_EXECUTIVE_SUMMARY.md (10 KB)
-- High-level overview for executives
-- Key statistics and metrics
-- Business impact assessment
-- Recommendation summary
-
-#### TELEMETRY_TECHNICAL_DEEP_DIVE.md (18 KB)
-- Architecture and design patterns
-- Component interactions
-- Data flow diagrams
-- Implementation details
-- Performance considerations
-
-#### TELEMETRY_DATA_FOR_VISUALIZATION.md (18 KB)
-- Sample datasets for dashboards
-- Query results and aggregations
-- Visualization recommendations
-- Chart and graph specifications
-
-#### TELEMETRY_ANALYSIS_INDEX.md (15 KB)
-- Index of all analyses
-- Cross-references
-- Topic mappings
-- Search guide
-
----
-
-## Recommended Reading Order
-
-### For Implementation Teams
-1. TELEMETRY_N8N_FIXER_DATASET.md (15 min) - Understand the plan
-2. TELEMETRY_ANALYSIS.md (30 min) - Understand current state
-3. TELEMETRY_MUTATION_SPEC.md (40 min) - Get implementation details
-4. TELEMETRY_QUICK_REFERENCE.md (10 min) - Reference during coding
-
-**Total Time:** 95 minutes
-
-### For Product Managers
-1. TELEMETRY_EXECUTIVE_SUMMARY.md (10 min)
-2. TELEMETRY_N8N_FIXER_DATASET.md (15 min)
-3. TELEMETRY_ANALYSIS_REPORT.md (20 min)
-
-**Total Time:** 45 minutes
-
-### For Data Analysts
-1. TELEMETRY_ANALYSIS.md (30 min)
-2. TELEMETRY_QUICK_REFERENCE.md (10 min)
-3. TELEMETRY_ANALYSIS_REPORT.md (20 min)
-
-**Total Time:** 60 minutes
-
-### For Architects
-1. TELEMETRY_TECHNICAL_DEEP_DIVE.md (20 min)
-2. TELEMETRY_MUTATION_SPEC.md (40 min)
-3. TELEMETRY_N8N_FIXER_DATASET.md (15 min)
-
-**Total Time:** 75 minutes
-
----
-
-## Key Findings Summary
-
-### What Exists Today
-- **276K+ telemetry events** tracked in Supabase
-- **6.5K+ unique workflows** analyzed
-- **12 event types** covering tool usage, errors, validation, workflow creation
-- **Production-grade infrastructure** with batching, retry logic, rate limiting
-- **Privacy-focused design** with sanitization, anonymization, encryption
-
-### Critical Gaps for N8N-Fixer
-- No workflow mutation/modification tracking
-- No before/after workflow snapshots
-- No instruction/transformation capture
-- No mutation success metrics
-- No validation improvement tracking
-
-### Proposed Solution
-- New `workflow_mutations` table (with 20 indexes)
-- Extended telemetry system to capture mutations
-- Instrumentation of 3-4 key tools
-- 4-phase implementation (3-4 weeks)
-
-### Data Volume Estimates
-- Per mutation: 25 KB (with compression)
-- Monthly: 250 MB - 1.2 GB
-- Annual: 3-14 GB
-- Cost: $10-200/month (depending on volume)
-
-### Implementation Effort
-- Phase 1 (Infrastructure): 40-60 hours
-- Phase 2 (Core Integration): 40-60 hours
-- Phase 3 (Tool Integration): 20-30 hours
-- Phase 4 (Validation): 20-30 hours
-- **Total:** 120-180 hours (3-4 weeks)
-
----
-
-## Critical Data
-
-### Supabase Connection
-```
-URL: https://ydyufsohxdfpopqbubwk.supabase.co
-Database: PostgreSQL
-Auth: Anon key (in telemetry-types.ts)
-Tables: telemetry_events, telemetry_workflows
-```
-
-### Event Types (by volume)
-1. tool_used (40-50%)
-2. tool_sequence (20-30%)
-3. error_occurred (10-15%)
-4. validation_details (5-10%)
-5. Others (workflow, session, performance) (5-10%)
-
-### Node Files
-- Source types: `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/telemetry-types.ts`
-- Main manager: `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/telemetry-manager.ts`
-- Event tracker: `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/event-tracker.ts`
-- Batch processor: `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/batch-processor.ts`
-
----
-
-## Implementation Checklist
-
-### Before Starting
-- [ ] Read TELEMETRY_N8N_FIXER_DATASET.md
-- [ ] Read TELEMETRY_ANALYSIS.md
-- [ ] Answer 6 questions (see TELEMETRY_N8N_FIXER_DATASET.md)
-- [ ] Get stakeholder approval for 4-phase plan
-- [ ] Assign implementation team
-
-### Phase 1: Infrastructure (Weeks 1-2)
-- [ ] Create workflow_mutations table in Supabase
-- [ ] Add 20+ indexes per specification
-- [ ] Define TypeScript types
-- [ ] Build mutation validator
-- [ ] Write unit tests
-
-### Phase 2: Core Integration (Weeks 2-3)
-- [ ] Add trackWorkflowMutation() to TelemetryManager
-- [ ] Extend EventTracker with mutation queue
-- [ ] Extend BatchProcessor for mutations
-- [ ] Write integration tests
-- [ ] Code review and merge
-
-### Phase 3: Tool Integration (Week 4)
-- [ ] Instrument n8n_autofix_workflow
-- [ ] Instrument n8n_update_partial_workflow
-- [ ] Instrument validation engine (if applicable)
-- [ ] Manual end-to-end testing
-- [ ] Code review and merge
-
-### Phase 4: Validation (Week 5)
-- [ ] Collect 100+ sample mutations
-- [ ] Verify data quality
-- [ ] Run analysis queries
-- [ ] Assess dataset readiness
-- [ ] Begin production collection
-
----
-
-## Storage & Cost Planning
-
-### Conservative Estimate (10K mutations/month)
-- Storage: 250 MB/month
-- Cost: $10-20/month
-- Dataset: 1K mutations in 3-4 days
-
-### Moderate Estimate (30K mutations/month)
-- Storage: 750 MB/month
-- Cost: $50-100/month
-- Dataset: 10K mutations in 10 days
-
-### High Estimate (50K mutations/month)
-- Storage: 1.2 GB/month
-- Cost: $100-200/month
-- Dataset: 100K mutations in 2 months
-
-**With 90-day retention policy, costs stay at lower end.**
-
----
-
-## Questions Before Implementation
-
-1. **Data Retention:** Keep mutations for 90 days? 1 year? Indefinite?
-2. **Storage Budget:** Monthly budget for telemetry storage?
-3. **Workflow Size:** Max workflow size to store? Compression required?
-4. **Dataset Timeline:** When do you need first dataset? (1K? 10K? 100K?)
-5. **Privacy:** Additional PII to sanitize beyond current approach?
-6. **User Consent:** Separate opt-in for mutation tracking vs. general telemetry?
-
----
-
-## Risk Assessment
-
-### Low Risk
-- No breaking changes to existing system
-- Fully backward compatible
-- Optional feature (can disable if needed)
-- No version bump required
-
-### Medium Risk
-- Storage growth if >1.2 GB/month
-- Performance impact if workflows >10 MB
-- Mitigation: Compression + retention policy
-
-### High Risk
-- None identified
-
----
-
-## Success Criteria
-
-When you can answer "yes" to all:
-- [ ] 100+ workflow mutations collected
-- [ ] Data hash verification passes 100%
-- [ ] Sample queries execute <100ms
-- [ ] Deduplication working correctly
-- [ ] Before/after states properly stored
-- [ ] Validation improvements tracked accurately
-- [ ] No performance regression in tools
-- [ ] Team ready for large-scale collection
-
----
-
-## Next Steps
-
-### Immediate (This Week)
-1. Review this README
-2. Read TELEMETRY_N8N_FIXER_DATASET.md
-3. Read TELEMETRY_ANALYSIS.md
-4. Schedule team review meeting
-
-### Short-term (Next 1-2 Weeks)
-1. Answer the 6 questions
-2. Get stakeholder approval
-3. Assign implementation lead
-4. Create Jira tickets for Phase 1
-
-### Medium-term (Weeks 3-6)
-1. Execute Phase 1 (Infrastructure)
-2. Execute Phase 2 (Core Integration)
-3. Execute Phase 3 (Tool Integration)
-4. Execute Phase 4 (Validation)
-
-### Long-term (Week 7+)
-1. Begin production dataset collection
-2. Monitor storage and costs
-3. Run analysis queries
-4. Iterate based on findings
-
----
-
-## Contact & Questions
-
-**Analysis Completed By:** Telemetry Data Analyst
-**Date:** November 12, 2025
-**Status:** Ready for team review and implementation
-
-For questions or clarifications:
-1. Review the specific document for your question
-2. Check TELEMETRY_QUICK_REFERENCE.md for common lookups
-3. Refer to source files in src/telemetry/
-
----
-
-## Document Statistics
-
-| Document | Size | Lines | Read Time | Purpose |
-|----------|------|-------|-----------|---------|
-| TELEMETRY_ANALYSIS.md | 23 KB | 720 | 20-30 min | Main reference |
-| TELEMETRY_MUTATION_SPEC.md | 26 KB | 918 | 30-40 min | Implementation guide |
-| TELEMETRY_QUICK_REFERENCE.md | 11 KB | 503 | 10-15 min | Developer lookup |
-| TELEMETRY_N8N_FIXER_DATASET.md | 13 KB | 340 | 15-20 min | Executive summary |
-| TELEMETRY_ANALYSIS_REPORT.md | 26 KB | 732 | 20-30 min | Statistics & trends |
-| TELEMETRY_EXECUTIVE_SUMMARY.md | 10 KB | 345 | 10-15 min | Executive brief |
-| TELEMETRY_TECHNICAL_DEEP_DIVE.md | 18 KB | 654 | 20-25 min | Architecture |
-| TELEMETRY_DATA_FOR_VISUALIZATION.md | 18 KB | 468 | 15-20 min | Dashboard data |
-| TELEMETRY_ANALYSIS_INDEX.md | 15 KB | 447 | 10-15 min | Topic index |
-| **TOTAL** | **160 KB** | **5,237** | **150-180 min** | Full analysis |
-
----
-
-## Version History
-
-| Date | Version | Changes |
-|------|---------|---------|
-| Nov 8, 2025 | 1.0 | Initial analysis and reports |
-| Nov 12, 2025 | 2.0 | Core documentation + mutation spec + this README |
-
----
-
-## License & Attribution
-
-These analysis documents are part of the n8n-mcp project.
-Conceived by Romuald Członkowski - www.aiadvisors.pl/en
-
----
-
-**END OF README**
-
-For additional information, start with one of the primary documents above based on your role and available time.

TELEMETRY_ANALYSIS_REPORT.md

@@ -1,732 +0,0 @@
-# n8n-MCP Telemetry Analysis Report
-## Error Patterns and Troubleshooting Analysis (90-Day Period)
-
-**Report Date:** November 8, 2025
-**Analysis Period:** August 10, 2025 - November 8, 2025
-**Data Freshness:** Live (last updated Oct 31, 2025)
-
----
-
-## Executive Summary
-
-This telemetry analysis examined 506K+ events across the n8n-MCP system to identify critical pain points for AI agents. The findings reveal that while core tool success rates are high (96-100%), specific validation and configuration challenges create friction that impacts developer experience.
-
-### Key Findings
-
-1. **8,859 total errors** across 90 days with significant volatility (28 to 406 errors/day), suggesting systemic issues triggered by specific conditions rather than constant problems
-
-2. **Validation failures dominate error landscape** with 34.77% of all errors being ValidationError, followed by TypeError (31.23%) and generic Error (30.60%)
-
-3. **Specific tools show concerning failure patterns**: `get_node_info` (11.72% failure rate), `get_node_documentation` (4.13%), and `validate_node_operation` (6.42%) struggle with reliability
-
-4. **Most common error: Workflow-level validation** represents 39.11% of validation errors, indicating widespread issues with workflow structure validation
-
-5. **Tool usage patterns reveal critical bottlenecks**: Sequential tool calls like `n8n_update_partial_workflow->n8n_update_partial_workflow` take average 55.2 seconds with 66% being slow transitions
-
-### Immediate Action Items
-
-- Fix `get_node_info` reliability (11.72% error rate vs. 0-4% for similar tools)
-- Improve workflow validation error messages to help users understand structure problems
-- Optimize sequential update operations that show 55+ second latencies
-- Address validation test coverage gaps (38,000+ "Node*" placeholder nodes triggering errors)
-
----
-
-## 1. Error Analysis
-
-### 1.1 Overall Error Volume and Frequency
-
-**Raw Statistics:**
-- **Total error events (90 days):** 8,859
-- **Average daily errors:** 60.68
-- **Peak error day:** 276 errors (October 30, 2025)
-- **Days with errors:** 36 out of 90 (40%)
-- **Error-free days:** 54 (60%)
-
-**Trend Analysis:**
-- High volatility with swings of -83.72% to +567.86% day-to-day
-- October 12 saw a 567.86% spike (28 → 187 errors), suggesting a deployment or system event
-- October 10-11 saw 57.64% drop, possibly indicating a hotfix
-- Current trajectory: Stabilizing around 130-160 errors/day (last 10 days)
-
-**Distribution Over Time:**
-```
-Peak Error Days (Top 5):
-  2025-09-26: 6,222 validation errors
-  2025-10-04: 3,585 validation errors
-  2025-10-05: 3,344 validation errors
-  2025-10-07: 2,858 validation errors
-  2025-10-06: 2,816 validation errors
-
-Pattern: Late September peak followed by elevated plateau through early October
-```
-
-### 1.2 Error Type Breakdown
-
-| Error Type | Count | % of Total | Days Occurred | Severity |
-|------------|-------|-----------|---------------|----------|
-| ValidationError | 3,080 | 34.77% | 36 | High |
-| TypeError | 2,767 | 31.23% | 36 | High |
-| Error (generic) | 2,711 | 30.60% | 36 | High |
-| SqliteError | 202 | 2.28% | 32 | Medium |
-| unknown_error | 89 | 1.00% | 3 | Low |
-| MCP_server_timeout | 6 | 0.07% | 1 | Critical |
-| MCP_server_init_fail | 3 | 0.03% | 1 | Critical |
-
-**Critical Insight:** 96.6% of errors are validation-related (ValidationError, TypeError, generic Error). This suggests the issue is primarily in configuration validation logic, not core infrastructure.
-
-**Detailed Error Categories:**
-
-**ValidationError (3,080 occurrences - 34.77%)**
-- Primary source: Workflow structure validation
-- Trigger: Invalid node configurations, missing required fields
-- Impact: Users cannot deploy workflows until fixed
-- Trend: Consistent daily occurrence (100% days affected)
-
-**TypeError (2,767 occurrences - 31.23%)**
-- Pattern: Type mismatches in node properties
-- Common scenario: String passed where number expected, or vice versa
-- Impact: Workflow validation failures, tool invocation errors
-- Indicates: Need for better type enforcement or clearer schema documentation
-
-**Generic Error (2,711 occurrences - 30.60%)**
-- Least helpful category; lacks actionable context
-- Likely source: Unhandled exceptions in validation pipeline
-- Recommendations: Implement error code system with specific error types
-- Impact on DX: Users cannot determine root cause
-
----
-
-## 2. Validation Error Patterns
-
-### 2.1 Validation Errors by Node Type
-
-**Problematic Findings:**
-
-| Node Type | Error Count | Days | % of Validation Errors | Issue |
-|-----------|------------|------|----------------------|--------|
-| workflow | 21,423 | 36 | 39.11% | **CRITICAL** - 39% of all validation errors at workflow level |
-| [KEY] | 656 | 35 | 1.20% | Property key validation failures |
-| ______ | 643 | 33 | 1.17% | Placeholder nodes (test data) |
-| Webhook | 435 | 35 | 0.79% | Webhook configuration issues |
-| HTTP_Request | 212 | 29 | 0.39% | HTTP node validation issues |
-
-**Major Concern: Placeholder Node Names**
-
-The presence of generic placeholder names (Node0-Node19, [KEY], ______, _____) represents 4,700+ errors. These appear to be:
-1. Test data that wasn't cleaned up
-2. Incomplete workflow definitions from users
-3. Validation test cases creating noise in telemetry
-
-**Workflow-Level Validation (21,423 errors - 39.11%)**
-
-This is the single largest error category. Issues include:
-- Missing start nodes (triggers)
-- Invalid node connections
-- Circular dependencies
-- Missing required node properties
-- Type mismatches in connections
-
-**Critical Action:** Improve workflow validation error messages to provide specific guidance on what structure requirement failed.
-
-### 2.2 Node-Specific Validation Issues
-
-**High-Risk Node Types:**
-- **Webhook**: 435 errors - likely authentication/path configuration issues
-- **HTTP_Request**: 212 errors - likely header/body configuration problems
-- **Database nodes**: Not heavily represented, suggesting better validation
-- **AI/Code nodes**: Minimal representation in error data
-
-**Pattern Observation:** Trigger nodes (Webhook, Webhook_Trigger) appear in validation errors, suggesting connection complexity issues.
-
----
-
-## 3. Tool Usage and Success Rates
-
-### 3.1 Overall Tool Performance
-
-**Top 25 Tools by Usage (90 days):**
-
-| Tool | Invocations | Success Rate | Failure Rate | Avg Duration (ms) | Status |
-|------|------------|--------------|--------------|-----------------|--------|
-| n8n_update_partial_workflow | 103,732 | 99.06% | 0.94% | 417.77 | Reliable |
-| search_nodes | 63,366 | 99.89% | 0.11% | 28.01 | Excellent |
-| get_node_essentials | 49,625 | 96.19% | 3.81% | 4.79 | Good |
-| n8n_create_workflow | 49,578 | 96.35% | 3.65% | 359.08 | Good |
-| n8n_get_workflow | 37,703 | 99.94% | 0.06% | 291.99 | Excellent |
-| n8n_validate_workflow | 29,341 | 99.70% | 0.30% | 269.33 | Excellent |
-| n8n_update_full_workflow | 19,429 | 99.27% | 0.73% | 415.39 | Reliable |
-| n8n_get_execution | 19,409 | 99.90% | 0.10% | 652.97 | Excellent |
-| n8n_list_executions | 17,111 | 100.00% | 0.00% | 375.46 | Perfect |
-| get_node_documentation | 11,403 | 95.87% | 4.13% | 2.45 | Needs Work |
-| get_node_info | 10,304 | 88.28% | 11.72% | 3.85 | **CRITICAL** |
-| validate_workflow | 9,738 | 94.50% | 5.50% | 33.63 | Concerning |
-| validate_node_operation | 5,654 | 93.58% | 6.42% | 5.05 | Concerning |
-
-### 3.2 Critical Tool Issues
-
-**1. `get_node_info` - 11.72% Failure Rate (CRITICAL)**
-
-- **Failures:** 1,208 out of 10,304 invocations
-- **Impact:** Users cannot retrieve node specifications when building workflows
-- **Likely Cause:**
-  - Database schema mismatches
-  - Missing node documentation
-  - Encoding/parsing errors
-- **Recommendation:** Immediately review error logs for this tool; implement fallback to cache or defaults
-
-**2. `validate_workflow` - 5.50% Failure Rate**
-
-- **Failures:** 536 out of 9,738 invocations
-- **Impact:** Users cannot validate workflows before deployment
-- **Correlation:** Likely related to workflow-level validation errors (39.11% of validation errors)
-- **Root Cause:** Validation logic may not handle all edge cases
-
-**3. `get_node_documentation` - 4.13% Failure Rate**
-
-- **Failures:** 471 out of 11,403 invocations
-- **Impact:** Users cannot access documentation when learning nodes
-- **Pattern:** Documentation retrieval failures compound with `get_node_info` issues
-
-**4. `validate_node_operation` - 6.42% Failure Rate**
-
-- **Failures:** 363 out of 5,654 invocations
-- **Impact:** Configuration validation provides incorrect feedback
-- **Concern:** Could lead to false positives (rejecting valid configs) or false negatives (accepting invalid ones)
-
-### 3.3 Reliable Tools (Baseline for Improvement)
-
-These tools show <1% failure rates and should be used as templates:
-- `search_nodes`: 99.89% (0.11% failure)
-- `n8n_get_workflow`: 99.94% (0.06% failure)
-- `n8n_get_execution`: 99.90% (0.10% failure)
-- `n8n_list_executions`: 100.00% (perfect)
-
-**Common Pattern:** Read-only and list operations are highly reliable, while validation operations are problematic.
-
----
-
-## 4. Tool Usage Patterns and Bottlenecks
-
-### 4.1 Sequential Tool Sequences (Most Common)
-
-The telemetry data shows AI agents follow predictable workflows. Analysis of 152K+ hourly tool sequence records reveals critical bottleneck patterns:
-
-| Sequence | Occurrences | Avg Duration | Slow Transitions |
-|----------|------------|--------------|-----------------|
-| update_partial → update_partial | 96,003 | 55.2s | 66% |
-| search_nodes → search_nodes | 68,056 | 11.2s | 17% |
-| get_node_essentials → get_node_essentials | 51,854 | 10.6s | 17% |
-| create_workflow → create_workflow | 41,204 | 54.9s | 80% |
-| search_nodes → get_node_essentials | 28,125 | 19.3s | 34% |
-| get_workflow → update_partial | 27,113 | 53.3s | 84% |
-| update_partial → validate_workflow | 25,203 | 20.1s | 41% |
-| list_executions → get_execution | 23,101 | 13.9s | 22% |
-| validate_workflow → update_partial | 23,013 | 60.6s | 74% |
-| update_partial → get_workflow | 19,876 | 96.6s | 63% |
-
-**Critical Issues Identified:**
-
-1. **Update Loops**: `update_partial → update_partial` has 96,003 occurrences
-   - Average 55.2s between calls
-   - 66% marked as "slow transitions"
-   - Suggests: Users iteratively updating workflows, with network/processing lag
-
-2. **Massive Duration on `update_partial → get_workflow`**: 96.6 seconds average
-   - Users check workflow state after update
-   - High latency suggests possible API bottleneck or large workflow processing
-
-3. **Sequential Search Operations**: 68,056 `search_nodes → search_nodes` calls
-   - Users refining search through multiple queries
-   - Could indicate search results are not meeting needs on first attempt
-
-4. **Read-After-Write Patterns**: Many sequences involve getting/validating after updates
-   - Suggests transactions aren't atomic; users manually verify state
-   - Could be optimized by returning updated state in response
-
-### 4.2 Implications for AI Agents
-
-AI agents exhibit these problematic patterns:
-- **Excessive retries**: Same operation repeated multiple times
-- **State uncertainty**: Need to re-fetch state after modifications
-- **Search inefficiency**: Multiple queries to find right tools/nodes
-- **Long wait times**: Up to 96 seconds between sequential operations
-
-**This creates:**
-- Slower agent response times to users
-- Higher API load and costs
-- Poor user experience (agents appear "stuck")
-- Wasted computational resources
-
----
-
-## 5. Session and User Activity Analysis
-
-### 5.1 Engagement Metrics
-
-| Metric | Value | Interpretation |
-|--------|-------|-----------------|
-| Avg Sessions/Day | 895 | Healthy usage |
-| Avg Users/Day | 572 | Growing user base |
-| Avg Sessions/User | 1.52 | Users typically engage once per day |
-| Peak Sessions Day | 1,821 (Oct 22) | Single major engagement spike |
-
-**Notable Date:** October 22, 2025 shows 2.94 sessions per user (vs. typical 1.4-1.6)
-- Could indicate: Feature launch, bug fix, or major update
-- Correlates with error spikes in early October
-
-### 5.2 Session Quality Patterns
-
-- Consistent 600-1,200 sessions daily
-- User base stable at 470-620 users per day
-- Some days show <5% of normal activity (Oct 11: 30 sessions)
-- Weekend vs. weekday patterns not visible in daily aggregates
-
----
-
-## 6. Search Query Analysis (User Intent)
-
-### 6.1 Most Searched Topics
-
-| Query | Total Searches | Days Searched | User Need |
-|-------|----------------|---------------|-----------|
-| test | 5,852 | 22 | Testing workflows |
-| webhook | 5,087 | 25 | Webhook triggers/integration |
-| http | 4,241 | 22 | HTTP requests |
-| database | 4,030 | 21 | Database operations |
-| api | 2,074 | 21 | API integrations |
-| http request | 1,036 | 22 | HTTP node details |
-| google sheets | 643 | 22 | Google integration |
-| code javascript | 616 | 22 | Code execution |
-| openai | 538 | 22 | AI integrations |
-
-**Key Insights:**
-
-1. **Top 4 searches (19,210 searches, 40% of traffic)**:
-   - Testing (5,852)
-   - Webhooks (5,087)
-   - HTTP (4,241)
-   - Databases (4,030)
-
-2. **Use Case Patterns**:
-   - **Integration-heavy**: Webhooks, API, HTTP, Google Sheets (15,000+ searches)
-   - **Logic/Execution**: Code, testing (6,500+ searches)
-   - **AI Integration**: OpenAI mentioned 538 times (trending interest)
-
-3. **Learning Curve Indicators**:
-   - "http request" vs. "http" suggests users searching for specific node
-   - "schedule cron" appears 270 times (scheduling is confusing)
-   - "manual trigger" appears 300 times (trigger types unclear)
-
-**Implication:** Users struggle most with:
-1. HTTP request configuration (1,300+ searches for HTTP-related topics)
-2. Scheduling/triggers (800+ searches for trigger types)
-3. Understanding testing practices (5,852 searches)
-
----
-
-## 7. Workflow Quality and Validation
-
-### 7.1 Workflow Validation Grades
-
-| Grade | Count | Percentage | Quality Score |
-|-------|-------|-----------|----------------|
-| A | 5,156 | 100% | 100.0 |
-
-**Critical Issue:** Only Grade A workflows in database, despite 39% validation error rate
-
-**Explanation:**
-- The `telemetry_workflows` table captures only successfully ingested workflows
-- Error events are tracked separately in `telemetry_errors_daily`
-- Failed workflows never make it to the workflows table
-- This creates a survivorship bias in quality metrics
-
-**Real Story:**
-- 7,869 workflows attempted
-- 5,156 successfully validated (65.5% success rate implied)
-- 2,713 workflows failed validation (34.5% failure rate implied)
-
----
-
-## 8. Top 5 Issues Impacting AI Agent Success
-
-Ranked by severity and impact:
-
-### Issue 1: Workflow-Level Validation Failures (39.11% of validation errors)
-
-**Problem:** 21,423 validation errors related to workflow structure validation
-
-**Root Causes:**
-- Invalid node connections
-- Missing trigger nodes
-- Circular dependencies
-- Type mismatches in connections
-- Incomplete node configurations
-
-**AI Agent Impact:**
-- Agents cannot deploy workflows
-- Error messages too generic ("workflow validation failed")
-- No guidance on what structure requirement failed
-- Forces agents to retry with different structures
-
-**Quick Win:** Enhance workflow validation error messages to specify which structural requirement failed
-
-**Implementation Effort:** Medium (2-3 days)
-
----
-
-### Issue 2: `get_node_info` Unreliability (11.72% failure rate)
-
-**Problem:** 1,208 failures out of 10,304 invocations
-
-**Root Causes:**
-- Likely missing node documentation or schema
-- Encoding issues with complex node definitions
-- Database connectivity problems during specific queries
-
-**AI Agent Impact:**
-- Agents cannot retrieve node specifications when building
-- Fall back to guessing or using incomplete essentials
-- Creates cascading validation errors
-- Slows down workflow creation
-
-**Quick Win:** Add retry logic with exponential backoff; implement fallback to cache
-
-**Implementation Effort:** Low (1 day)
-
----
-
-### Issue 3: Slow Sequential Update Operations (96,003 occurrences, avg 55.2s)
-
-**Problem:** `update_partial_workflow → update_partial_workflow` takes avg 55.2 seconds with 66% slow transitions
-
-**Root Causes:**
-- Network latency between operations
-- Large workflow serialization
-- Possible blocking on previous operations
-- No batch update capability
-
-**AI Agent Impact:**
-- Agents wait 55+ seconds between sequential modifications
-- Workflow construction takes minutes instead of seconds
-- Poor perceived performance
-- Users abandon incomplete workflows
-
-**Quick Win:** Implement batch workflow update operation
-
-**Implementation Effort:** High (5-7 days)
-
----
-
-### Issue 4: Search Result Relevancy Issues (68,056 `search_nodes → search_nodes` calls)
-
-**Problem:** Users perform multiple search queries in sequence (17% slow transitions)
-
-**Root Causes:**
-- Initial search results don't match user intent
-- Search ranking algorithm suboptimal
-- Users unsure of node names
-- Broad searches returning too many results
-
-**AI Agent Impact:**
-- Agents make multiple search attempts to find right node
-- Increases API calls and latency
-- Uncertainty in node selection
-- Compounds with slow subsequent operations
-
-**Quick Win:** Analyze top 50 repeated search sequences; improve ranking for high-volume queries
-
-**Implementation Effort:** Medium (3 days)
-
----
-
-### Issue 5: `validate_node_operation` Inaccuracy (6.42% failure rate)
-
-**Problem:** 363 failures out of 5,654 invocations; validation provides unreliable feedback
-
-**Root Causes:**
-- Validation logic doesn't handle all node operation combinations
-- Missing edge case handling
-- Validator version mismatches
-- Property dependency logic incomplete
-
-**AI Agent Impact:**
-- Agents may trust invalid configurations (false positives)
-- Or reject valid ones (false negatives)
-- Either way: Unreliable feedback breaks agent judgment
-- Forces manual verification
-
-**Quick Win:** Add telemetry to capture validation false positive/negative cases
-
-**Implementation Effort:** Medium (4 days)
-
----
-
-## 9. Temporal and Anomaly Patterns
-
-### 9.1 Error Spike Events
-
-**Major Spike #1: October 12, 2025**
-- Error increase: 567.86% (28 → 187 errors)
-- Context: Validation errors jumped from low to baseline
-- Likely event: System restart, deployment, or database issue
-
-**Major Spike #2: September 26, 2025**
-- Daily validation errors: 6,222 (highest single day)
-- Represents: 70% of September error volume
-- Context: Possible large test batch or migration
-
-**Major Spike #3: Early October (Oct 3-10)**
-- Sustained elevation: 3,344-2,038 errors daily
-- Duration: 8 days of high error rates
-- Recovery: October 11 drops to 28 errors (83.72% decrease)
-- Suggests: Incident and mitigation
-
-### 9.2 Recent Trend (Last 10 Days)
-
-- Stabilized at 130-278 errors/day
-- More predictable pattern
-- Suggests: System stabilization post-October incident
-- Current error rate: ~60 errors/day (normal baseline)
-
----
-
-## 10. Actionable Recommendations
-
-### Priority 1 (Immediate - Week 1)
-
-1. **Fix `get_node_info` Reliability**
-   - Impact: Affects 1,200+ failures affecting agents
-   - Action: Review error logs; add retry logic; implement cache fallback
-   - Expected benefit: Reduce tool failure rate from 11.72% to <1%
-
-2. **Improve Workflow Validation Error Messages**
-   - Impact: 39% of validation errors lack clarity
-   - Action: Create specific error codes for structural violations
-   - Expected benefit: Reduce user frustration; improve agent success rate
-   - Example: Instead of "validation failed", return "Missing start trigger node"
-
-3. **Add Batch Workflow Update Operation**
-   - Impact: 96,003 sequential updates at 55.2s each
-   - Action: Create `n8n_batch_update_workflow` tool
-   - Expected benefit: 80-90% reduction in workflow update time
-
-### Priority 2 (High - Week 2-3)
-
-4. **Implement Validation Caching**
-   - Impact: Reduce repeated validation of identical configs
-   - Action: Cache validation results with invalidation on node updates
-   - Expected benefit: 40-50% reduction in `validate_workflow` calls
-
-5. **Improve Node Search Ranking**
-   - Impact: 68,056 sequential search calls
-   - Action: Analyze top repeated sequences; adjust ranking algorithm
-   - Expected benefit: Fewer searches needed; faster node discovery
-
-6. **Add TypeScript Types for Common Nodes**
-   - Impact: Type mismatches cause 31.23% of errors
-   - Action: Generate strict TypeScript definitions for top 50 nodes
-   - Expected benefit: AI agents make fewer type-related mistakes
-
-### Priority 3 (Medium - Week 4)
-
-7. **Implement Return-Updated-State Pattern**
-   - Impact: Users fetch state after every update (19,876 `update → get_workflow` calls)
-   - Action: Update tools to return full updated state
-   - Expected benefit: Eliminate unnecessary API calls; reduce round-trips
-
-8. **Add Workflow Diff Generation**
-   - Impact: Help users understand what changed after updates
-   - Action: Generate human-readable diffs of workflow changes
-   - Expected benefit: Better visibility; easier debugging
-
-9. **Create Validation Test Suite**
-   - Impact: Generic placeholder nodes (Node0-19) creating noise
-   - Action: Clean up test data; implement proper test isolation
-   - Expected benefit: Clearer signal in telemetry; 600+ error reduction
-
-### Priority 4 (Documentation - Ongoing)
-
-10. **Create Error Code Documentation**
-    - Document each error type with resolution steps
-    - Examples of what causes ValidationError, TypeError, etc.
-    - Quick reference for agents and developers
-
-11. **Add Configuration Examples for Top 20 Nodes**
-    - HTTP Request (1,300+ searches)
-    - Webhook (5,087 searches)
-    - Database nodes (4,030 searches)
-    - With working examples and common pitfalls
-
-12. **Create Trigger Configuration Guide**
-    - Explain scheduling (270+ "schedule cron" searches)
-    - Manual triggers (300 searches)
-    - Webhook triggers (5,087 searches)
-    - Clear comparison of use cases
-
----
-
-## 11. Monitoring Recommendations
-
-### Key Metrics to Track
-
-1. **Tool Failure Rates** (daily):
-   - Alert if `get_node_info` > 5%
-   - Alert if `validate_workflow` > 2%
-   - Alert if `validate_node_operation` > 3%
-
-2. **Workflow Validation Success Rate**:
-   - Target: >95% of workflows pass validation first attempt
-   - Current: Estimated 65% (5,156 of 7,869)
-
-3. **Sequential Operation Latency**:
-   - Track p50/p95/p99 for update operations
-   - Target: <5s for sequential updates
-   - Current: 55.2s average (needs optimization)
-
-4. **Error Rate Volatility**:
-   - Daily error count should stay within 100-200
-   - Alert if day-over-day change >30%
-
-5. **Search Query Success**:
-   - Track how many repeated searches for same term
-   - Target: <2 searches needed to find node
-   - Current: 17-34% slow transitions
-
-### Dashboards to Create
-
-1. **Daily Error Dashboard**
-   - Error counts by type (Validation, Type, Generic)
-   - Error trends over 7/30/90 days
-   - Top error-triggering operations
-
-2. **Tool Health Dashboard**
-   - Failure rates for all tools
-   - Success rate trends
-   - Duration trends for slow operations
-
-3. **Workflow Quality Dashboard**
-   - Validation success rates
-   - Common failure patterns
-   - Node type error distributions
-
-4. **User Experience Dashboard**
-   - Session counts and user trends
-   - Search patterns and result relevancy
-   - Average workflow creation time
-
----
-
-## 12. SQL Queries Used (For Reproducibility)
-
-### Query 1: Error Overview
-```sql
-SELECT
-  COUNT(*) as total_error_events,
-  COUNT(DISTINCT date) as days_with_errors,
-  ROUND(AVG(error_count), 2) as avg_errors_per_day,
-  MAX(error_count) as peak_errors_in_day
-FROM telemetry_errors_daily
-WHERE date >= CURRENT_DATE - INTERVAL '90 days';
-```
-
-### Query 2: Error Type Distribution
-```sql
-SELECT
-  error_type,
-  SUM(error_count) as total_occurrences,
-  COUNT(DISTINCT date) as days_occurred,
-  ROUND(SUM(error_count)::numeric / (SELECT SUM(error_count) FROM telemetry_errors_daily) * 100, 2) as percentage_of_all_errors
-FROM telemetry_errors_daily
-WHERE date >= CURRENT_DATE - INTERVAL '90 days'
-GROUP BY error_type
-ORDER BY total_occurrences DESC;
-```
-
-### Query 3: Tool Success Rates
-```sql
-SELECT
-  tool_name,
-  SUM(usage_count) as total_invocations,
-  SUM(success_count) as successful_invocations,
-  SUM(failure_count) as failed_invocations,
-  ROUND(100.0 * SUM(success_count) / SUM(usage_count), 2) as success_rate_percent,
-  ROUND(AVG(avg_duration_ms)::numeric, 2) as avg_duration_ms,
-  COUNT(DISTINCT date) as days_active
-FROM telemetry_tool_usage_daily
-WHERE date >= CURRENT_DATE - INTERVAL '90 days'
-GROUP BY tool_name
-ORDER BY total_invocations DESC;
-```
-
-### Query 4: Validation Errors by Node Type
-```sql
-SELECT
-  node_type,
-  error_type,
-  SUM(error_count) as total_occurrences,
-  ROUND(SUM(error_count)::numeric / SUM(SUM(error_count)) OVER () * 100, 2) as percentage_of_validation_errors
-FROM telemetry_validation_errors_daily
-WHERE date >= CURRENT_DATE - INTERVAL '90 days'
-GROUP BY node_type, error_type
-ORDER BY total_occurrences DESC;
-```
-
-### Query 5: Tool Sequences
-```sql
-SELECT
-  sequence_pattern,
-  SUM(occurrence_count) as total_occurrences,
-  ROUND(AVG(avg_time_delta_ms)::numeric, 2) as avg_duration_ms,
-  SUM(slow_transition_count) as slow_transitions
-FROM telemetry_tool_sequences_hourly
-WHERE hour >= NOW() - INTERVAL '90 days'
-GROUP BY sequence_pattern
-ORDER BY total_occurrences DESC;
-```
-
-### Query 6: Session Metrics
-```sql
-SELECT
-  date,
-  total_sessions,
-  unique_users,
-  ROUND(total_sessions::numeric / unique_users, 2) as avg_sessions_per_user
-FROM telemetry_session_metrics_daily
-WHERE date >= CURRENT_DATE - INTERVAL '90 days'
-ORDER BY date DESC;
-```
-
-### Query 7: Search Queries
-```sql
-SELECT
-  query_text,
-  SUM(search_count) as total_searches,
-  COUNT(DISTINCT date) as days_searched
-FROM telemetry_search_queries_daily
-WHERE date >= CURRENT_DATE - INTERVAL '90 days'
-GROUP BY query_text
-ORDER BY total_searches DESC;
-```
-
----
-
-## Conclusion
-
-The n8n-MCP telemetry analysis reveals that while core infrastructure is robust (most tools >99% reliability), there are five critical issues preventing optimal AI agent success:
-
-1. **Workflow validation feedback** (39% of errors) - lack of actionable error messages
-2. **Tool reliability** (11.72% failure rate for `get_node_info`) - critical information retrieval failures
-3. **Performance bottlenecks** (55+ second sequential updates) - slow workflow construction
-4. **Search inefficiency** (multiple searches needed) - poor discoverability
-5. **Validation accuracy** (6.42% failure rate) - unreliable configuration feedback
-
-Implementing the Priority 1 recommendations would address 75% of user-facing issues and dramatically improve AI agent performance. The remaining improvements would optimize performance and user experience further.
-
-All recommendations include implementation effort estimates and expected benefits to help with prioritization.
-
----
-
-**Report Prepared By:** AI Telemetry Analyst
-**Data Source:** n8n-MCP Supabase Telemetry Database
-**Next Review:** November 15, 2025 (weekly cadence recommended)

TELEMETRY_DATA_FOR_VISUALIZATION.md

@@ -1,468 +0,0 @@
-# n8n-MCP Telemetry Data - Visualization Reference
-## Charts, Tables, and Graphs for Presentations
-
----
-
-## 1. Error Distribution Chart Data
-
-### Error Types Pie Chart
-```
-ValidationError     3,080 (34.77%) ← Largest slice
-TypeError           2,767 (31.23%)
-Generic Error       2,711 (30.60%)
-SqliteError         202  (2.28%)
-Unknown/Other       99   (1.12%)
-```
-
-**Chart Type:** Pie Chart or Donut Chart
-**Key Message:** 96.6% of errors are validation-related
-
-### Error Volume Line Chart (90 days)
-```
-Date Range: Aug 10 - Nov 8, 2025
-Baseline: 60-65 errors/day (normal)
-Peak: Oct 30 (276 errors, 4.5x baseline)
-Current: ~130-160 errors/day (stabilizing)
-
-Notable Events:
-- Oct 12: 567% spike (incident event)
-- Oct 3-10: 8-day plateau (incident period)
-- Oct 11: 83% drop (mitigation)
-```
-
-**Chart Type:** Line Graph
-**Scale:** 0-300 errors/day
-**Trend:** Volatile but stabilizing
-
----
-
-## 2. Tool Success Rates Bar Chart
-
-### High-Risk Tools (Ranked by Failure Rate)
-```
-Tool Name                    | Success Rate | Failure Rate | Invocations
-------------------------------|-------------|--------------|-------------
-get_node_info                 | 88.28%      | 11.72%       | 10,304
-validate_node_operation       | 93.58%      | 6.42%        | 5,654
-get_node_documentation        | 95.87%      | 4.13%        | 11,403
-validate_workflow             | 94.50%      | 5.50%        | 9,738
-get_node_essentials           | 96.19%      | 3.81%        | 49,625
-n8n_create_workflow           | 96.35%      | 3.65%        | 49,578
-n8n_update_partial_workflow   | 99.06%      | 0.94%        | 103,732
-```
-
-**Chart Type:** Horizontal Bar Chart
-**Color Coding:** Red (<95%), Yellow (95-99%), Green (>99%)
-**Target Line:** 99% success rate
-
----
-
-## 3. Tool Usage Volume Bubble Chart
-
-### Tool Invocation Volume (90 days)
-```
-X-axis: Total Invocations (log scale)
-Y-axis: Success Rate (%)
-Bubble Size: Error Count
-
-Tool Clusters:
-- High Volume, High Success (ideal): search_nodes (63K), list_executions (17K)
-- High Volume, Medium Success (risky): n8n_create_workflow (50K), get_node_essentials (50K)
-- Low Volume, Low Success (critical): get_node_info (10K), validate_node_operation (6K)
-```
-
-**Chart Type:** Bubble/Scatter Chart
-**Focus:** Tools in lower-right quadrant are problematic
-
----
-
-## 4. Sequential Operation Performance
-
-### Tool Sequence Duration Distribution
-```
-Sequence Pattern                         | Count  | Avg Duration (s) | Slow %
------------------------------------------|--------|------------------|-------
-update → update                          | 96,003 | 55.2             | 66%
-search → search                          | 68,056 | 11.2             | 17%
-essentials → essentials                  | 51,854 | 10.6             | 17%
-create → create                          | 41,204 | 54.9             | 80%
-search → essentials                      | 28,125 | 19.3             | 34%
-get_workflow → update_partial            | 27,113 | 53.3             | 84%
-update → validate                        | 25,203 | 20.1             | 41%
-list_executions → get_execution          | 23,101 | 13.9             | 22%
-validate → update                        | 23,013 | 60.6             | 74%
-update → get_workflow (read-after-write) | 19,876 | 96.6             | 63%
-```
-
-**Chart Type:** Horizontal Bar Chart
-**Sort By:** Occurrences (descending)
-**Highlight:** Operations with >50% slow transitions
-
----
-
-## 5. Search Query Analysis
-
-### Top 10 Search Queries
-```
-Query           | Count | Days Searched | User Need
-----------------|-------|---------------|------------------
-test            | 5,852 | 22            | Testing workflows
-webhook         | 5,087 | 25            | Trigger/integration
-http            | 4,241 | 22            | HTTP requests
-database        | 4,030 | 21            | Database operations
-api             | 2,074 | 21            | API integration
-http request    | 1,036 | 22            | Specific node
-google sheets   | 643   | 22            | Google integration
-code javascript | 616   | 22            | Code execution
-openai          | 538   | 22            | AI integration
-telegram        | 528   | 22            | Chat integration
-```
-
-**Chart Type:** Horizontal Bar Chart
-**Grouping:** Integration-heavy (15K), Logic/Execution (6.5K), AI (1K)
-
----
-
-## 6. Validation Errors by Node Type
-
-### Top 15 Node Types by Error Count
-```
-Node Type                | Errors  | % of Total | Status
--------------------------|---------|------------|--------
-workflow (structure)     | 21,423  | 39.11%     | CRITICAL
-[test placeholders]      | 4,700   | 8.57%      | Should exclude
-Webhook                  | 435     | 0.79%      | Needs docs
-HTTP_Request             | 212     | 0.39%      | Needs docs
-[Generic node names]     | 3,500   | 6.38%      | Should exclude
-Schedule/Trigger nodes   | 700     | 1.28%      | Needs docs
-Database nodes           | 450     | 0.82%      | Generally OK
-Code/JS nodes            | 280     | 0.51%      | Generally OK
-AI/OpenAI nodes          | 150     | 0.27%      | Generally OK
-Other                    | 900     | 1.64%      | Various
-```
-
-**Chart Type:** Horizontal Bar Chart
-**Insight:** 39% are workflow-level; 15% are test data noise
-
----
-
-## 7. Session and User Metrics Timeline
-
-### Daily Sessions and Users (30-day rolling average)
-```
-Date Range: Oct 1-31, 2025
-
-Metrics:
-- Avg Sessions/Day: 895
-- Avg Users/Day: 572
-- Avg Sessions/User: 1.52
-
-Weekly Trend:
-Week 1 (Oct 1-7):   900 sessions/day, 550 users
-Week 2 (Oct 8-14):  880 sessions/day, 580 users
-Week 3 (Oct 15-21): 920 sessions/day, 600 users
-Week 4 (Oct 22-28): 1,100 sessions/day, 620 users (spike)
-Week 5 (Oct 29-31): 880 sessions/day, 575 users
-```
-
-**Chart Type:** Dual-axis line chart
-- Left axis: Sessions/day (600-1,200)
-- Right axis: Users/day (400-700)
-
----
-
-## 8. Error Rate Over Time with Annotations
-
-### Error Timeline with Key Events
-```
-Date          | Daily Errors | Day-over-Day | Event/Pattern
---------------|-------------|-------------|------------------
-Sep 26        | 6,222       | +156%       | INCIDENT: Major spike
-Sep 27-30     | 1,200 avg   | -45%        | Recovery period
-Oct 1-5       | 3,000 avg   | +120%       | Sustained elevation
-Oct 6-10      | 2,300 avg   | -30%        | Declining trend
-Oct 11        | 28          | -83.72%     | MAJOR DROP: Possible fix
-Oct 12        | 187         | +567.86%    | System restart/redeployment
-Oct 13-30     | 180 avg     | Stable      | New baseline established
-Oct 31        | 130         | -53.24%     | Current trend: improving
-
-Current Trajectory: Stabilizing at 60-65 errors/day baseline
-```
-
-**Chart Type:** Column chart with annotations
-**Y-axis:** 0-300 errors/day
-**Annotations:** Mark incident events
-
----
-
-## 9. Performance Impact Matrix
-
-### Estimated Time Impact on User Workflows
-```
-Operation                  | Current | After Phase 1 | Improvement
----------------------------|---------|---------------|------------
-Create 5-node workflow     | 4-6 min | 30 seconds    | 91% faster
-Add single node property   | 55s     | <1s          | 98% faster
-Update 10 workflow params  | 9 min   | 5 seconds    | 99% faster
-Find right node (search)   | 30-60s  | 15-20s       | 50% faster
-Validate workflow          | Varies  | <2s          | 80% faster
-
-Total Workflow Creation Time:
-- Current: 15-20 minutes for complex workflow
-- After Phase 1: 2-3 minutes
-- Improvement: 85-90% reduction
-```
-
-**Chart Type:** Comparison bar chart
-**Color coding:** Current (red), Target (green)
-
----
-
-## 10. Tool Failure Rate Comparison
-
-### Tool Failure Rates Ranked
-```
-Rank | Tool Name                    | Failure % | Severity | Action
------|------------------------------|-----------|----------|--------
-1    | get_node_info                | 11.72%    | CRITICAL | Fix immediately
-2    | validate_node_operation      | 6.42%     | HIGH     | Fix week 2
-3    | validate_workflow            | 5.50%     | HIGH     | Fix week 2
-4    | get_node_documentation       | 4.13%     | MEDIUM   | Fix week 2
-5    | get_node_essentials          | 3.81%     | MEDIUM   | Monitor
-6    | n8n_create_workflow          | 3.65%     | MEDIUM   | Monitor
-7    | n8n_update_partial_workflow  | 0.94%     | LOW      | Baseline
-8    | search_nodes                 | 0.11%     | LOW      | Excellent
-9    | n8n_list_executions          | 0.00%     | LOW      | Excellent
-10   | n8n_health_check             | 0.00%     | LOW      | Excellent
-```
-
-**Chart Type:** Horizontal bar chart with target line (1%)
-**Color coding:** Red (>5%), Yellow (2-5%), Green (<2%)
-
----
-
-## 11. Issue Severity and Impact Matrix
-
-### Prioritization Matrix
-```
-          High Impact          |          Low Impact
-High      ┌────────────────────┼────────────────────┐
-Effort    │ 1. Validation      │ 4. Search ranking  │
-          │ Messages (2 days)  │ (2 days)           │
-          │ Impact: 39%        │ Impact: 2%         │
-          │                    │ 5. Type System     │
-          │                    │ (3 days)           │
-          │ 3. Batch Updates   │ Impact: 5%         │
-          │ (2 days)           │                    │
-          │ Impact: 6%         │                    │
-          └────────────────────┼────────────────────┘
-Low       │ 2. get_node_info   │ 7. Return State    │
-Effort    │ Fix (1 day)        │ (1 day)            │
-          │ Impact: 14%        │ Impact: 2%         │
-          │ 6. Type Stubs      │                    │
-          │ (1 day)            │                    │
-          │ Impact: 5%         │                    │
-          └────────────────────┼────────────────────┘
-```
-
-**Chart Type:** 2x2 matrix
-**Bubble size:** Relative impact
-**Focus:** Lower-right quadrant (high impact, low effort)
-
----
-
-## 12. Implementation Timeline with Expected Improvements
-
-### Gantt Chart with Metrics
-```
-Week 1: Immediate Wins
-├─ Fix get_node_info (1 day)        → 91% reduction in failures
-├─ Validation messages (2 days)     → 40% improvement in clarity
-└─ Batch updates (2 days)           → 90% latency improvement
-
-Week 2-3: High Priority
-├─ Validation caching (2 days)      → 40% fewer validation calls
-├─ Search ranking (2 days)          → 30% fewer retries
-└─ Type stubs (3 days)              → 25% fewer type errors
-
-Week 4: Optimization
-├─ Return state (1 day)             → Eliminate 40% redundant calls
-└─ Workflow diffs (1 day)           → Better debugging visibility
-
-Expected Cumulative Impact:
-- Week 1: 40-50% improvement (600+ fewer errors/day)
-- Week 3: 70% improvement (1,900 fewer errors/day)
-- Week 5: 77% improvement (2,000+ fewer errors/day)
-```
-
-**Chart Type:** Gantt chart with overlay
-**Overlay:** Expected error reduction graph
-
----
-
-## 13. Cost-Benefit Analysis
-
-### Implementation Investment vs. Returns
-```
-Investment:
-- Engineering time: 1 FTE × 5 weeks = $15,000
-- Testing/QA: $2,000
-- Documentation: $1,000
-- Total: $18,000
-
-Returns (Estimated):
-- Support ticket reduction: 40% fewer errors = $4,000/month = $48,000/year
-- User retention improvement: +5% = $20,000/month = $240,000/year
-- AI agent efficiency: +30% = $10,000/month = $120,000/year
-- Developer productivity: +20% = $5,000/month = $60,000/year
-
-Total Returns: ~$468,000/year (26x ROI)
-
-Payback Period: < 2 weeks
-```
-
-**Chart Type:** Waterfall chart
-**Format:** Investment vs. Single-Year Returns
-
----
-
-## 14. Key Metrics Dashboard
-
-### One-Page Dashboard for Tracking
-```
-╔════════════════════════════════════════════════════════════╗
-║           n8n-MCP Error & Performance Dashboard            ║
-║                    Last 24 Hours                           ║
-╠════════════════════════════════════════════════════════════╣
-║                                                            ║
-║  Total Errors Today:  142        ↓ 5% vs yesterday      ║
-║  Most Common Error:   ValidationError (45%)              ║
-║  Critical Failures:   get_node_info (8 cases)            ║
-║  Avg Session Time:    2m 34s      ↑ 15% (slower)       ║
-║                                                            ║
-║  ┌──────────────────────────────────────────────────┐    ║
-║  │ Tool Success Rates (Top 5 Issues)                │    ║
-║  ├──────────────────────────────────────────────────┤    ║
-║  │ get_node_info               ███░░ 88.28%        │    ║
-║  │ validate_node_operation     █████░ 93.58%       │    ║
-║  │ validate_workflow           █████░ 94.50%       │    ║
-║  │ get_node_documentation      █████░ 95.87%       │    ║
-║  │ get_node_essentials         █████░ 96.19%       │    ║
-║  └──────────────────────────────────────────────────┘    ║
-║                                                            ║
-║  ┌──────────────────────────────────────────────────┐    ║
-║  │ Error Trend (Last 7 Days)                        │    ║
-║  │                                                  │    ║
-║  │  350 │      ╱╲                                  │    ║
-║  │  300 │  ╱╲ ╱  ╲                                │    ║
-║  │  250 │ ╱  ╲╱    ╲╱╲                          │    ║
-║  │  200 │                ╲╱╲                     │    ║
-║  │  150 │                    ╲╱─╲              │    ║
-║  │  100 │                         ─            │    ║
-║  │    0 └─────────────────────────────────────┘   │    ║
-║  └──────────────────────────────────────────────────┘    ║
-║                                                            ║
-║  Action Items: Fix get_node_info | Improve error msgs   ║
-║                                                            ║
-╚════════════════════════════════════════════════════════════╝
-```
-
-**Format:** ASCII art for reports; convert to Grafana/Datadog for live dashboard
-
----
-
-## 15. Before/After Comparison
-
-### Visual Representation of Improvements
-```
-Metric                      │ Before | After  | Improvement
-────────────────────────────┼────────┼────────┼─────────────
-get_node_info failure rate  │ 11.72% │ <1%    │ 91% ↓
-Workflow validation clarity │ 20%    │ 95%    │ 475% ↑
-Update operation latency    │ 55.2s  │ <5s    │ 91% ↓
-Search retry rate           │ 17%    │ <5%    │ 70% ↓
-Type error frequency        │ 2,767  │ 2,000  │ 28% ↓
-Daily error count           │ 65     │ 15     │ 77% ↓
-User satisfaction (est.)    │ 6/10   │ 9/10   │ 50% ↑
-Workflow creation time      │ 18min  │ 2min   │ 89% ↓
-```
-
-**Chart Type:** Comparison table with ↑/↓ indicators
-**Color coding:** Green for improvements, Red for current state
-
----
-
-## Chart Recommendations by Audience
-
-### For Executive Leadership
-1. Error Distribution Pie Chart
-2. Cost-Benefit Analysis Waterfall
-3. Implementation Timeline with Impact
-4. KPI Dashboard
-
-### For Product Team
-1. Tool Success Rates Bar Chart
-2. Error Type Breakdown
-3. User Search Patterns
-4. Session Metrics Timeline
-
-### For Engineering
-1. Tool Reliability Scatter Plot
-2. Sequential Operation Performance
-3. Error Rate with Annotations
-4. Before/After Metrics Table
-
-### For Customer Support
-1. Error Trend Line Chart
-2. Common Validation Issues
-3. Top Search Queries
-4. Troubleshooting Reference
-
----
-
-## SQL Queries for Data Export
-
-All visualizations above can be generated from these queries:
-
-```sql
--- Error distribution
-SELECT error_type, SUM(error_count) FROM telemetry_errors_daily
-WHERE date >= CURRENT_DATE - INTERVAL '90 days'
-GROUP BY error_type ORDER BY SUM(error_count) DESC;
-
--- Tool success rates
-SELECT tool_name,
-  ROUND(100.0 * SUM(success_count) / SUM(usage_count), 2) as success_rate,
-  SUM(failure_count) as failures,
-  SUM(usage_count) as invocations
-FROM telemetry_tool_usage_daily
-WHERE date >= CURRENT_DATE - INTERVAL '90 days'
-GROUP BY tool_name ORDER BY success_rate ASC;
-
--- Daily trends
-SELECT date, SUM(error_count) as daily_errors
-FROM telemetry_errors_daily
-WHERE date >= CURRENT_DATE - INTERVAL '90 days'
-GROUP BY date ORDER BY date DESC;
-
--- Top searches
-SELECT query_text, SUM(search_count) as count
-FROM telemetry_search_queries_daily
-WHERE date >= CURRENT_DATE - INTERVAL '90 days'
-GROUP BY query_text ORDER BY count DESC LIMIT 20;
-```
-
----
-
-**Created for:** Presentations, Reports, Dashboards
-**Format:** Markdown with ASCII, easily convertible to:
-- Excel/Google Sheets
-- PowerBI/Tableau
-- Grafana/Datadog
-- Presentation slides
-
----
-
-**Last Updated:** November 8, 2025
-**Data Freshness:** Live (updated daily)
-**Review Frequency:** Weekly

TELEMETRY_EXECUTIVE_SUMMARY.md

@@ -1,345 +0,0 @@
-# n8n-MCP Telemetry Analysis - Executive Summary
-## Quick Reference for Decision Makers
-
-**Analysis Date:** November 8, 2025
-**Data Period:** August 10 - November 8, 2025 (90 days)
-**Status:** Critical Issues Identified - Action Required
-
----
-
-## Key Statistics at a Glance
-
-| Metric | Value | Status |
-|--------|-------|--------|
-| Total Errors (90 days) | 8,859 | 96% are validation-related |
-| Daily Average | 60.68 | Baseline (60-65 errors/day normal) |
-| Peak Error Day | Oct 30 | 276 errors (4.5x baseline) |
-| Days with Errors | 36/90 (40%) | Intermittent spikes |
-| Most Common Error | ValidationError | 34.77% of all errors |
-| Critical Tool Failure | get_node_info | 11.72% failure rate |
-| Performance Bottleneck | Sequential updates | 55.2 seconds per operation |
-| Active Users/Day | 572 | Healthy engagement |
-| Total Users (90 days) | ~5,000+ | Growing user base |
-
----
-
-## The 5 Critical Issues
-
-### 1. Workflow-Level Validation Failures (39% of errors)
-
-**Problem:** 21,423 errors from unspecified workflow structure violations
-
-**What Users See:**
-- "Validation failed" (no indication of what's wrong)
-- Cannot deploy workflows
-- Must guess what structure requirement violated
-
-**Impact:** Users abandon workflows; AI agents retry blindly
-
-**Fix:** Provide specific error messages explaining exactly what failed
-- "Missing start trigger node"
-- "Type mismatch in node connection"
-- "Required property missing: URL"
-
-**Effort:** 2 days | **Impact:** High | **Priority:** 1
-
----
-
-### 2. `get_node_info` Unreliability (11.72% failure rate)
-
-**Problem:** 1,208 failures out of 10,304 calls to retrieve node information
-
-**What Users See:**
-- Cannot load node specifications when building workflows
-- Missing information about node properties
-- Forced to use incomplete data (fallback to essentials)
-
-**Impact:** Workflows built with wrong configuration assumptions; validation failures cascade
-
-**Fix:** Add retry logic, caching, and fallback mechanism
-
-**Effort:** 1 day | **Impact:** High | **Priority:** 1
-
----
-
-### 3. Slow Sequential Updates (55+ seconds per operation)
-
-**Problem:** 96,003 sequential workflow updates take average 55.2 seconds each
-
-**What Users See:**
-- Workflow construction takes minutes instead of seconds
-- "System appears stuck" (agent waiting 55s between operations)
-- Poor user experience
-
-**Impact:** Users abandon complex workflows; slow AI agent response
-
-**Fix:** Implement batch update operation (apply multiple changes in 1 call)
-
-**Effort:** 2-3 days | **Impact:** Critical | **Priority:** 1
-
----
-
-### 4. Search Inefficiency (17% retry rate)
-
-**Problem:** 68,056 sequential search calls; users need multiple searches to find nodes
-
-**What Users See:**
-- Search for "http" doesn't show "HTTP Request" in top results
-- Users refine search 2-3 times
-- Extra API calls and latency
-
-**Impact:** Slower node discovery; AI agents waste API calls
-
-**Fix:** Improve search ranking for high-volume queries
-
-**Effort:** 2 days | **Impact:** Medium | **Priority:** 2
-
----
-
-### 5. Type-Related Validation Errors (31.23% of errors)
-
-**Problem:** 2,767 TypeError occurrences from configuration mismatches
-
-**What Users See:**
-- Node validation fails due to type mismatch
-- "string vs. number" errors without clear resolution
-- Configuration seems correct but validation fails
-
-**Impact:** Users unsure of correct configuration format
-
-**Fix:** Implement strict type system; add TypeScript types for common nodes
-
-**Effort:** 3 days | **Impact:** Medium | **Priority:** 2
-
----
-
-## Business Impact Summary
-
-### Current State: What's Broken?
-
-| Area | Problem | Impact |
-|------|---------|--------|
-| **Reliability** | `get_node_info` fails 11.72% | Users blocked 1 in 8 times |
-| **Feedback** | Generic error messages | Users can't self-fix errors |
-| **Performance** | 55s per sequential update | 5-node workflow takes 4+ minutes |
-| **Search** | 17% require refine search | Extra latency; poor UX |
-| **Types** | 31% of errors type-related | Users make wrong assumptions |
-
-### If No Action Taken
-
-- Error volume likely to remain at 60+ per day
-- User frustration compounds
-- AI agents become unreliable (cascading failures)
-- Adoption plateau or decline
-- Support burden increases
-
-### With Phase 1 Fixes (Week 1)
-
-- `get_node_info` reliability: 11.72% → <1% (91% improvement)
-- Validation errors: 21,423 → <1,000 (95% improvement in clarity)
-- Sequential updates: 55.2s → <5s (91% improvement)
-- **Overall error reduction: 40-50%**
-- **User satisfaction: +60%** (estimated)
-
-### Full Implementation (4-5 weeks)
-
-- **Error volume: 8,859 → <2,000 per quarter** (77% reduction)
-- **Tool failure rates: <1% across board**
-- **Performance: 90% improvement in workflow creation**
-- **User retention: +35%** (estimated)
-
----
-
-## Implementation Roadmap
-
-### Week 1 (Immediate Wins)
-1. Fix `get_node_info` reliability [1 day]
-2. Improve validation error messages [2 days]
-3. Add batch update operation [2 days]
-
-**Impact:** Address 60% of user-facing issues
-
-### Week 2-3 (High Priority)
-4. Implement validation caching [1-2 days]
-5. Improve search ranking [2 days]
-6. Add TypeScript types [3 days]
-
-**Impact:** Performance +70%; Errors -30%
-
-### Week 4 (Optimization)
-7. Return updated state in responses [1-2 days]
-8. Add workflow diff generation [1-2 days]
-
-**Impact:** Eliminate 40% of API calls
-
-### Ongoing (Documentation)
-9. Create error code documentation [1 week]
-10. Add configuration examples [2 weeks]
-
----
-
-## Resource Requirements
-
-| Phase | Duration | Team | Impact | Business Value |
-|-------|----------|------|--------|-----------------|
-| Phase 1 | 1 week | 1 engineer | 60% of issues | High ROI |
-| Phase 2 | 2 weeks | 1 engineer | +30% improvement | Medium ROI |
-| Phase 3 | 1 week | 1 engineer | +10% improvement | Low ROI |
-| Phase 4 | 3 weeks | 0.5 engineer | Support reduction | Medium ROI |
-
-**Total:** 7 weeks, 1 engineer FTE, +35% overall improvement
-
----
-
-## Risk Assessment
-
-| Risk | Likelihood | Impact | Mitigation |
-|------|------------|--------|-----------|
-| Breaking API changes | Low | High | Maintain backward compatibility |
-| Performance regression | Low | High | Load test before deployment |
-| Validation false positives | Medium | Medium | Beta test with sample workflows |
-| Incomplete implementation | Low | Medium | Clear definition of done per task |
-
-**Overall Risk Level:** Low (with proper mitigation)
-
----
-
-## Success Metrics (Measurable)
-
-### By End of Week 1
-- [ ] `get_node_info` failure rate < 2%
-- [ ] Validation errors provide specific guidance
-- [ ] Batch update operation deployed and tested
-
-### By End of Week 3
-- [ ] Overall error rate < 3,000/quarter
-- [ ] Tool success rates > 98% across board
-- [ ] Average workflow creation time < 2 minutes
-
-### By End of Week 5
-- [ ] Error volume < 2,000/quarter (77% reduction)
-- [ ] All users can self-resolve 80% of common errors
-- [ ] AI agent success rate improves by 30%
-
----
-
-## Top Recommendations
-
-### Do This First (Week 1)
-
-1. **Fix `get_node_info`** - Affects most critical user action
-   - Add retry logic [4 hours]
-   - Implement cache [4 hours]
-   - Add fallback [4 hours]
-
-2. **Improve Validation Messages** - Addresses 39% of errors
-   - Create error code system [8 hours]
-   - Enhance validation logic [8 hours]
-   - Add help documentation [4 hours]
-
-3. **Add Batch Updates** - Fixes performance bottleneck
-   - Define API [4 hours]
-   - Implement handler [12 hours]
-   - Test & integrate [4 hours]
-
-### Avoid This (Anti-patterns)
-
-- ❌ Increasing error logging without actionable feedback
-- ❌ Adding more validation without improving error messages
-- ❌ Optimizing non-critical operations while critical issues remain
-- ❌ Waiting for perfect data before implementing fixes
-
----
-
-## Stakeholder Questions & Answers
-
-**Q: Why are there so many validation errors if most tools work (96%+)?**
-
-A: Validation happens in a separate system. Core tools are reliable, but validation feedback is poor. Users create invalid workflows, validation rejects them generically, and users can't understand why.
-
-**Q: Is the system unstable?**
-
-A: No. Infrastructure is stable (99% uptime estimated). The issue is usability: errors are generic and operations are slow.
-
-**Q: Should we defer fixes until next quarter?**
-
-A: No. Every day of 60+ daily errors compounds user frustration. Early fixes have highest ROI (1 week = 40-50% improvement).
-
-**Q: What about the Oct 30 spike (276 errors)?**
-
-A: Likely specific trigger (batch test, migration). Current baseline is 60-65 errors/day, which is sustainable but improvable.
-
-**Q: Which issue is most urgent?**
-
-A: `get_node_info` reliability. It's the foundation for everything else. Without it, users can't build workflows correctly.
-
----
-
-## Next Steps
-
-1. **This Week**
-   - [ ] Review this analysis with engineering team
-   - [ ] Estimate resource allocation
-   - [ ] Prioritize Phase 1 tasks
-
-2. **Next Week**
-   - [ ] Start Phase 1 implementation
-   - [ ] Set up monitoring for improvements
-   - [ ] Begin user communication about fixes
-
-3. **Week 3**
-   - [ ] Deploy Phase 1 fixes
-   - [ ] Measure improvements
-   - [ ] Start Phase 2
-
----
-
-## Questions?
-
-**For detailed analysis:** See TELEMETRY_ANALYSIS_REPORT.md
-**For technical details:** See TELEMETRY_TECHNICAL_DEEP_DIVE.md
-**For implementation:** See IMPLEMENTATION_ROADMAP.md
-
----
-
-**Analysis by:** AI Telemetry Analyst
-**Confidence Level:** High (506K+ events analyzed)
-**Last Updated:** November 8, 2025
-**Review Frequency:** Weekly recommended
-**Next Review Date:** November 15, 2025
-
----
-
-## Appendix: Key Data Points
-
-### Error Distribution
-- ValidationError: 3,080 (34.77%)
-- TypeError: 2,767 (31.23%)
-- Generic Error: 2,711 (30.60%)
-- SqliteError: 202 (2.28%)
-- Other: 99 (1.12%)
-
-### Tool Reliability (Top Issues)
-- `get_node_info`: 88.28% success (11.72% failure)
-- `validate_node_operation`: 93.58% success (6.42% failure)
-- `get_node_documentation`: 95.87% success (4.13% failure)
-- All others: 96-100% success
-
-### User Engagement
-- Daily sessions: 895 (avg)
-- Daily users: 572 (avg)
-- Sessions/user: 1.52 (avg)
-- Peak day: 1,821 sessions (Oct 22)
-
-### Most Searched Topics
-1. Testing (5,852 searches)
-2. Webhooks (5,087)
-3. HTTP (4,241)
-4. Database (4,030)
-5. API integration (2,074)
-
-### Performance Bottlenecks
-- Update loop: 55.2s avg (66% slow)
-- Read-after-write: 96.6s avg (63% slow)
-- Search refinement: 17% need 2+ queries
-- Session creation: ~5-10 seconds

TELEMETRY_MUTATION_SPEC.md

@@ -1,918 +0,0 @@
-# Telemetry Workflow Mutation Tracking Specification
-
-**Purpose:** Define the technical requirements for capturing workflow mutation data to build the n8n-fixer dataset
-
-**Status:** Specification Document (Pre-Implementation)
-
----
-
-## 1. Overview
-
-This specification details how to extend the n8n-mcp telemetry system to capture:
-- **Before State:** Complete workflow JSON before modification
-- **Instruction:** The transformation instruction/prompt
-- **After State:** Complete workflow JSON after modification
-- **Metadata:** Timestamps, user ID, success metrics, validation states
-
----
-
-## 2. Schema Design
-
-### 2.1 New Database Table: `workflow_mutations`
-
-```sql
-CREATE TABLE IF NOT EXISTS workflow_mutations (
-  -- Primary Key & Identifiers
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  user_id TEXT NOT NULL,
-  workflow_id TEXT,                      -- n8n workflow ID (nullable for new workflows)
-
-  -- Source Workflow Snapshot (Before)
-  before_workflow_json JSONB NOT NULL,   -- Complete workflow definition
-  before_workflow_hash TEXT NOT NULL,    -- SHA-256(before_workflow_json)
-  before_validation_status TEXT NOT NULL CHECK(before_validation_status IN (
-    'valid',           -- Workflow passes validation
-    'invalid',         -- Has validation errors
-    'unknown'          -- Unknown state (not tested)
-  )),
-  before_error_count INTEGER,            -- Number of validation errors
-  before_error_types TEXT[],             -- Array: ['type_error', 'missing_field', ...]
-
-  -- Mutation Details
-  instruction TEXT NOT NULL,             -- The modification instruction/prompt
-  instruction_type TEXT NOT NULL CHECK(instruction_type IN (
-    'ai_generated',    -- Generated by AI/LLM
-    'user_provided',   -- User input/request
-    'auto_fix',        -- System auto-correction
-    'validation_correction'  -- Validation rule fix
-  )),
-  mutation_source TEXT,                  -- Which tool/service created the mutation
-                                         -- e.g., 'n8n_autofix_workflow', 'validation_engine'
-  mutation_tool_version TEXT,            -- Version of tool that performed mutation
-
-  -- Target Workflow Snapshot (After)
-  after_workflow_json JSONB NOT NULL,    -- Complete modified workflow
-  after_workflow_hash TEXT NOT NULL,     -- SHA-256(after_workflow_json)
-  after_validation_status TEXT NOT NULL CHECK(after_validation_status IN (
-    'valid',
-    'invalid',
-    'unknown'
-  )),
-  after_error_count INTEGER,             -- Validation errors after mutation
-  after_error_types TEXT[],              -- Remaining error types
-
-  -- Mutation Analysis (Pre-calculated for Performance)
-  nodes_modified TEXT[],                 -- Array of modified node IDs/names
-  nodes_added TEXT[],                    -- New nodes in after state
-  nodes_removed TEXT[],                  -- Removed nodes
-  nodes_modified_count INTEGER,          -- Count of modified nodes
-  nodes_added_count INTEGER,
-  nodes_removed_count INTEGER,
-
-  connections_modified BOOLEAN,          -- Were connections/edges changed?
-  connections_before_count INTEGER,      -- Number of connections before
-  connections_after_count INTEGER,       -- Number after
-
-  properties_modified TEXT[],            -- Changed property paths
-                                         -- e.g., ['nodes[0].parameters.url', ...]
-  properties_modified_count INTEGER,
-  expressions_modified BOOLEAN,          -- Were expressions/formulas changed?
-
-  -- Complexity Metrics
-  complexity_before TEXT CHECK(complexity_before IN (
-    'simple',
-    'medium',
-    'complex'
-  )),
-  complexity_after TEXT,
-  node_count_before INTEGER,
-  node_count_after INTEGER,
-  node_types_before TEXT[],
-  node_types_after TEXT[],
-
-  -- Outcome Metrics
-  mutation_success BOOLEAN,              -- Did mutation achieve intended goal?
-  validation_improved BOOLEAN,           -- true if: error_count_after < error_count_before
-  validation_errors_fixed INTEGER,       -- Count of errors fixed
-  new_errors_introduced INTEGER,         -- Errors created by mutation
-
-  -- Optional: User Feedback
-  user_approved BOOLEAN,                 -- User accepted the mutation?
-  user_feedback TEXT,                    -- User comment (truncated)
-
-  -- Data Quality & Compression
-  workflow_size_before INTEGER,          -- Byte size of before_workflow_json
-  workflow_size_after INTEGER,           -- Byte size of after_workflow_json
-  is_compressed BOOLEAN DEFAULT false,   -- True if workflows are gzip-compressed
-
-  -- Timing
-  execution_duration_ms INTEGER,         -- Time taken to apply mutation
-  created_at TIMESTAMP DEFAULT NOW(),
-
-  -- Metadata
-  tags TEXT[],                           -- Custom tags for filtering
-  metadata JSONB                         -- Flexible metadata storage
-);
-```
-
-### 2.2 Indexes for Performance
-
-```sql
--- User Analysis (User's mutation history)
-CREATE INDEX idx_mutations_user_id
-  ON workflow_mutations(user_id, created_at DESC);
-
--- Workflow Analysis (Mutations to specific workflow)
-CREATE INDEX idx_mutations_workflow_id
-  ON workflow_mutations(workflow_id, created_at DESC);
-
--- Mutation Success Rate
-CREATE INDEX idx_mutations_success
-  ON workflow_mutations(mutation_success, created_at DESC);
-
--- Validation Improvement Analysis
-CREATE INDEX idx_mutations_validation_improved
-  ON workflow_mutations(validation_improved, created_at DESC);
-
--- Time-series Analysis
-CREATE INDEX idx_mutations_created_at
-  ON workflow_mutations(created_at DESC);
-
--- Source Analysis
-CREATE INDEX idx_mutations_source
-  ON workflow_mutations(mutation_source, created_at DESC);
-
--- Instruction Type Analysis
-CREATE INDEX idx_mutations_instruction_type
-  ON workflow_mutations(instruction_type, created_at DESC);
-
--- Composite: For common query patterns
-CREATE INDEX idx_mutations_user_success_time
-  ON workflow_mutations(user_id, mutation_success, created_at DESC);
-
-CREATE INDEX idx_mutations_source_validation
-  ON workflow_mutations(mutation_source, validation_improved, created_at DESC);
-```
-
-### 2.3 Optional: Materialized View for Analytics
-
-```sql
--- Pre-calculate common metrics for fast dashboarding
-CREATE MATERIALIZED VIEW vw_mutation_analytics AS
-SELECT
-  DATE(created_at) as mutation_date,
-  instruction_type,
-  mutation_source,
-
-  COUNT(*) as total_mutations,
-  SUM(CASE WHEN mutation_success THEN 1 ELSE 0 END) as successful_mutations,
-  SUM(CASE WHEN validation_improved THEN 1 ELSE 0 END) as validation_improved_count,
-
-  ROUND(100.0 * COUNT(*) FILTER(WHERE mutation_success = true)
-        / NULLIF(COUNT(*), 0), 2) as success_rate,
-
-  AVG(nodes_modified_count) as avg_nodes_modified,
-  AVG(properties_modified_count) as avg_properties_modified,
-  AVG(execution_duration_ms) as avg_duration_ms,
-
-  AVG(before_error_count) as avg_errors_before,
-  AVG(after_error_count) as avg_errors_after,
-  AVG(validation_errors_fixed) as avg_errors_fixed
-
-FROM workflow_mutations
-GROUP BY DATE(created_at), instruction_type, mutation_source;
-
-CREATE INDEX idx_mutation_analytics_date
-  ON vw_mutation_analytics(mutation_date DESC);
-```
-
----
-
-## 3. TypeScript Interfaces
-
-### 3.1 Core Mutation Interface
-
-```typescript
-// In src/telemetry/telemetry-types.ts
-
-export interface WorkflowMutationEvent extends TelemetryEvent {
-  event: 'workflow_mutation';
-  properties: {
-    // Identification
-    workflowId?: string;
-
-    // Hashes for deduplication & integrity
-    beforeHash: string;        // SHA-256 of before state
-    afterHash: string;         // SHA-256 of after state
-
-    // Instruction
-    instruction: string;       // The modification prompt/request
-    instructionType: 'ai_generated' | 'user_provided' | 'auto_fix' | 'validation_correction';
-    mutationSource?: string;   // Tool that created the instruction
-
-    // Change Summary
-    nodesModified: number;
-    propertiesChanged: number;
-    connectionsModified: boolean;
-    expressionsModified: boolean;
-
-    // Outcome
-    mutationSuccess: boolean;
-    validationImproved: boolean;
-    errorsBefore: number;
-    errorsAfter: number;
-
-    // Performance
-    executionDurationMs?: number;
-    workflowSizeBefore?: number;
-    workflowSizeAfter?: number;
-  }
-}
-
-export interface WorkflowMutation {
-  // Primary Key
-  id: string;                  // UUID
-  user_id: string;             // Anonymized user
-  workflow_id?: string;        // n8n workflow ID
-
-  // Before State
-  before_workflow_json: any;   // Complete workflow
-  before_workflow_hash: string;
-  before_validation_status: 'valid' | 'invalid' | 'unknown';
-  before_error_count?: number;
-  before_error_types?: string[];
-
-  // Mutation
-  instruction: string;
-  instruction_type: 'ai_generated' | 'user_provided' | 'auto_fix' | 'validation_correction';
-  mutation_source?: string;
-  mutation_tool_version?: string;
-
-  // After State
-  after_workflow_json: any;
-  after_workflow_hash: string;
-  after_validation_status: 'valid' | 'invalid' | 'unknown';
-  after_error_count?: number;
-  after_error_types?: string[];
-
-  // Analysis
-  nodes_modified?: string[];
-  nodes_added?: string[];
-  nodes_removed?: string[];
-  nodes_modified_count?: number;
-  connections_modified?: boolean;
-  properties_modified?: string[];
-  properties_modified_count?: number;
-
-  // Complexity
-  complexity_before?: 'simple' | 'medium' | 'complex';
-  complexity_after?: 'simple' | 'medium' | 'complex';
-  node_count_before?: number;
-  node_count_after?: number;
-
-  // Outcome
-  mutation_success: boolean;
-  validation_improved: boolean;
-  validation_errors_fixed?: number;
-  new_errors_introduced?: number;
-  user_approved?: boolean;
-
-  // Timing
-  created_at: string;          // ISO 8601
-  execution_duration_ms?: number;
-}
-```
-
-### 3.2 Mutation Analysis Service
-
-```typescript
-// New file: src/telemetry/mutation-analyzer.ts
-
-export interface MutationDiff {
-  nodesAdded: string[];
-  nodesRemoved: string[];
-  nodesModified: Map<string, PropertyDiff[]>;
-  connectionsChanged: boolean;
-  expressionsChanged: boolean;
-}
-
-export interface PropertyDiff {
-  path: string;                // e.g., "parameters.url"
-  beforeValue: any;
-  afterValue: any;
-  isExpression: boolean;       // Contains {{}} or $json?
-}
-
-export class WorkflowMutationAnalyzer {
-  /**
-   * Analyze differences between before/after workflows
-   */
-  static analyzeDifferences(
-    beforeWorkflow: any,
-    afterWorkflow: any
-  ): MutationDiff {
-    // Implementation: Deep comparison of workflow structures
-    // Return detailed diff information
-  }
-
-  /**
-   * Extract changed property paths
-   */
-  static getChangedProperties(diff: MutationDiff): string[] {
-    // Implementation
-  }
-
-  /**
-   * Determine if expression/formula was modified
-   */
-  static hasExpressionChanges(diff: MutationDiff): boolean {
-    // Implementation
-  }
-
-  /**
-   * Validate workflow structure
-   */
-  static validateWorkflowStructure(workflow: any): {
-    isValid: boolean;
-    errors: string[];
-    errorTypes: string[];
-  } {
-    // Implementation
-  }
-}
-```
-
----
-
-## 4. Integration Points
-
-### 4.1 TelemetryManager Extension
-
-```typescript
-// In src/telemetry/telemetry-manager.ts
-
-export class TelemetryManager {
-  // ... existing code ...
-
-  /**
-   * Track workflow mutation (new method)
-   */
-  async trackWorkflowMutation(
-    beforeWorkflow: any,
-    instruction: string,
-    afterWorkflow: any,
-    options?: {
-      instructionType?: 'ai_generated' | 'user_provided' | 'auto_fix';
-      mutationSource?: string;
-      workflowId?: string;
-      success?: boolean;
-      executionDurationMs?: number;
-      userApproved?: boolean;
-    }
-  ): Promise<void> {
-    this.ensureInitialized();
-    this.performanceMonitor.startOperation('trackWorkflowMutation');
-
-    try {
-      await this.eventTracker.trackWorkflowMutation(
-        beforeWorkflow,
-        instruction,
-        afterWorkflow,
-        options
-      );
-      // Auto-flush mutations to prevent data loss
-      await this.flush();
-    } catch (error) {
-      const telemetryError = error instanceof TelemetryError
-        ? error
-        : new TelemetryError(
-            TelemetryErrorType.UNKNOWN_ERROR,
-            'Failed to track workflow mutation',
-            { error: String(error) }
-          );
-      this.errorAggregator.record(telemetryError);
-    } finally {
-      this.performanceMonitor.endOperation('trackWorkflowMutation');
-    }
-  }
-}
-```
-
-### 4.2 EventTracker Extension
-
-```typescript
-// In src/telemetry/event-tracker.ts
-
-export class TelemetryEventTracker {
-  // ... existing code ...
-
-  private mutationQueue: WorkflowMutation[] = [];
-  private mutationAnalyzer = new WorkflowMutationAnalyzer();
-
-  /**
-   * Track a workflow mutation
-   */
-  async trackWorkflowMutation(
-    beforeWorkflow: any,
-    instruction: string,
-    afterWorkflow: any,
-    options?: MutationTrackingOptions
-  ): Promise<void> {
-    if (!this.isEnabled()) return;
-
-    try {
-      // 1. Analyze differences
-      const diff = this.mutationAnalyzer.analyzeDifferences(
-        beforeWorkflow,
-        afterWorkflow
-      );
-
-      // 2. Calculate hashes
-      const beforeHash = this.calculateHash(beforeWorkflow);
-      const afterHash = this.calculateHash(afterWorkflow);
-
-      // 3. Detect validation changes
-      const beforeValidation = this.mutationAnalyzer.validateWorkflowStructure(
-        beforeWorkflow
-      );
-      const afterValidation = this.mutationAnalyzer.validateWorkflowStructure(
-        afterWorkflow
-      );
-
-      // 4. Create mutation record
-      const mutation: WorkflowMutation = {
-        id: generateUUID(),
-        user_id: this.getUserId(),
-        workflow_id: options?.workflowId,
-
-        before_workflow_json: beforeWorkflow,
-        before_workflow_hash: beforeHash,
-        before_validation_status: beforeValidation.isValid ? 'valid' : 'invalid',
-        before_error_count: beforeValidation.errors.length,
-        before_error_types: beforeValidation.errorTypes,
-
-        instruction,
-        instruction_type: options?.instructionType || 'user_provided',
-        mutation_source: options?.mutationSource,
-
-        after_workflow_json: afterWorkflow,
-        after_workflow_hash: afterHash,
-        after_validation_status: afterValidation.isValid ? 'valid' : 'invalid',
-        after_error_count: afterValidation.errors.length,
-        after_error_types: afterValidation.errorTypes,
-
-        nodes_modified: Array.from(diff.nodesModified.keys()),
-        nodes_added: diff.nodesAdded,
-        nodes_removed: diff.nodesRemoved,
-        properties_modified: this.mutationAnalyzer.getChangedProperties(diff),
-        connections_modified: diff.connectionsChanged,
-
-        mutation_success: options?.success !== false,
-        validation_improved: afterValidation.errors.length
-                           < beforeValidation.errors.length,
-        validation_errors_fixed: Math.max(
-          0,
-          beforeValidation.errors.length - afterValidation.errors.length
-        ),
-
-        created_at: new Date().toISOString(),
-        execution_duration_ms: options?.executionDurationMs,
-        user_approved: options?.userApproved
-      };
-
-      // 5. Validate and queue
-      const validated = this.validator.validateMutation(mutation);
-      if (validated) {
-        this.mutationQueue.push(validated);
-      }
-
-      // 6. Track as event for real-time monitoring
-      this.trackEvent('workflow_mutation', {
-        beforeHash,
-        afterHash,
-        instructionType: options?.instructionType || 'user_provided',
-        nodesModified: diff.nodesModified.size,
-        propertiesChanged: diff.properties_modified?.length || 0,
-        mutationSuccess: options?.success !== false,
-        validationImproved: mutation.validation_improved,
-        errorsBefore: beforeValidation.errors.length,
-        errorsAfter: afterValidation.errors.length
-      });
-
-    } catch (error) {
-      logger.debug('Failed to track workflow mutation:', error);
-      throw new TelemetryError(
-        TelemetryErrorType.VALIDATION_ERROR,
-        'Failed to process workflow mutation',
-        { error: error instanceof Error ? error.message : String(error) }
-      );
-    }
-  }
-
-  /**
-   * Get queued mutations
-   */
-  getMutationQueue(): WorkflowMutation[] {
-    return [...this.mutationQueue];
-  }
-
-  /**
-   * Clear mutation queue
-   */
-  clearMutationQueue(): void {
-    this.mutationQueue = [];
-  }
-
-  /**
-   * Calculate SHA-256 hash of workflow
-   */
-  private calculateHash(workflow: any): string {
-    const crypto = require('crypto');
-    const normalized = JSON.stringify(workflow, null, 0);
-    return crypto.createHash('sha256').update(normalized).digest('hex');
-  }
-}
-```
-
-### 4.3 BatchProcessor Extension
-
-```typescript
-// In src/telemetry/batch-processor.ts
-
-export class TelemetryBatchProcessor {
-  // ... existing code ...
-
-  /**
-   * Flush mutations to Supabase
-   */
-  private async flushMutations(
-    mutations: WorkflowMutation[]
-  ): Promise<boolean> {
-    if (this.isFlushingMutations || mutations.length === 0) return true;
-
-    this.isFlushingMutations = true;
-
-    try {
-      const batches = this.createBatches(
-        mutations,
-        TELEMETRY_CONFIG.MAX_BATCH_SIZE
-      );
-
-      for (const batch of batches) {
-        const result = await this.executeWithRetry(async () => {
-          const { error } = await this.supabase!
-            .from('workflow_mutations')
-            .insert(batch);
-
-          if (error) throw error;
-
-          logger.debug(`Flushed batch of ${batch.length} workflow mutations`);
-          return true;
-        }, 'Flush workflow mutations');
-
-        if (!result) {
-          this.addToDeadLetterQueue(batch);
-          return false;
-        }
-      }
-
-      return true;
-    } catch (error) {
-      logger.debug('Failed to flush mutations:', error);
-      throw new TelemetryError(
-        TelemetryErrorType.NETWORK_ERROR,
-        'Failed to flush mutations',
-        { error: error instanceof Error ? error.message : String(error) },
-        true
-      );
-    } finally {
-      this.isFlushingMutations = false;
-    }
-  }
-}
-```
-
----
-
-## 5. Integration with Workflow Tools
-
-### 5.1 n8n_autofix_workflow
-
-```typescript
-// Where n8n_autofix_workflow applies fixes
-import { telemetry } from '../telemetry';
-
-export async function n8n_autofix_workflow(
-  workflow: any,
-  options?: AutofixOptions
-): Promise<WorkflowFixResult> {
-
-  const beforeWorkflow = JSON.parse(JSON.stringify(workflow)); // Deep copy
-
-  try {
-    // Apply fixes
-    const fixed = await applyFixes(workflow, options);
-
-    // Track mutation
-    await telemetry.trackWorkflowMutation(
-      beforeWorkflow,
-      'Auto-fix validation errors',
-      fixed,
-      {
-        instructionType: 'auto_fix',
-        mutationSource: 'n8n_autofix_workflow',
-        success: true,
-        executionDurationMs: duration
-      }
-    );
-
-    return fixed;
-  } catch (error) {
-    // Track failed mutation attempt
-    await telemetry.trackWorkflowMutation(
-      beforeWorkflow,
-      'Auto-fix validation errors',
-      beforeWorkflow, // No changes
-      {
-        instructionType: 'auto_fix',
-        mutationSource: 'n8n_autofix_workflow',
-        success: false
-      }
-    );
-    throw error;
-  }
-}
-```
-
-### 5.2 n8n_update_partial_workflow
-
-```typescript
-// Partial workflow updates
-export async function n8n_update_partial_workflow(
-  workflow: any,
-  operations: DiffOperation[]
-): Promise<UpdateResult> {
-
-  const beforeWorkflow = JSON.parse(JSON.stringify(workflow));
-  const instructionText = formatOperationsAsInstruction(operations);
-
-  try {
-    const updated = applyOperations(workflow, operations);
-
-    await telemetry.trackWorkflowMutation(
-      beforeWorkflow,
-      instructionText,
-      updated,
-      {
-        instructionType: 'user_provided',
-        mutationSource: 'n8n_update_partial_workflow'
-      }
-    );
-
-    return updated;
-  } catch (error) {
-    await telemetry.trackWorkflowMutation(
-      beforeWorkflow,
-      instructionText,
-      beforeWorkflow,
-      {
-        instructionType: 'user_provided',
-        mutationSource: 'n8n_update_partial_workflow',
-        success: false
-      }
-    );
-    throw error;
-  }
-}
-```
-
----
-
-## 6. Data Quality & Validation
-
-### 6.1 Mutation Validation Rules
-
-```typescript
-// In src/telemetry/mutation-validator.ts
-
-export class WorkflowMutationValidator {
-  /**
-   * Validate mutation data before storage
-   */
-  static validate(mutation: WorkflowMutation): ValidationResult {
-    const errors: string[] = [];
-
-    // Required fields
-    if (!mutation.user_id) errors.push('user_id is required');
-    if (!mutation.before_workflow_json) errors.push('before_workflow_json required');
-    if (!mutation.after_workflow_json) errors.push('after_workflow_json required');
-    if (!mutation.before_workflow_hash) errors.push('before_workflow_hash required');
-    if (!mutation.after_workflow_hash) errors.push('after_workflow_hash required');
-    if (!mutation.instruction) errors.push('instruction is required');
-    if (!mutation.instruction_type) errors.push('instruction_type is required');
-
-    // Hash verification
-    const beforeHash = calculateHash(mutation.before_workflow_json);
-    const afterHash = calculateHash(mutation.after_workflow_json);
-
-    if (beforeHash !== mutation.before_workflow_hash) {
-      errors.push('before_workflow_hash mismatch');
-    }
-    if (afterHash !== mutation.after_workflow_hash) {
-      errors.push('after_workflow_hash mismatch');
-    }
-
-    // Deduplication: Skip if before == after
-    if (beforeHash === afterHash) {
-      errors.push('before and after states are identical (skipping)');
-    }
-
-    // Size validation
-    const beforeSize = JSON.stringify(mutation.before_workflow_json).length;
-    const afterSize = JSON.stringify(mutation.after_workflow_json).length;
-
-    if (beforeSize > 10 * 1024 * 1024) {
-      errors.push('before_workflow_json exceeds 10MB size limit');
-    }
-    if (afterSize > 10 * 1024 * 1024) {
-      errors.push('after_workflow_json exceeds 10MB size limit');
-    }
-
-    // Instruction validation
-    if (mutation.instruction.length > 5000) {
-      mutation.instruction = mutation.instruction.substring(0, 5000);
-    }
-    if (mutation.instruction.length < 3) {
-      errors.push('instruction too short (min 3 chars)');
-    }
-
-    // Error count validation
-    if (mutation.before_error_count && mutation.before_error_count < 0) {
-      errors.push('before_error_count cannot be negative');
-    }
-    if (mutation.after_error_count && mutation.after_error_count < 0) {
-      errors.push('after_error_count cannot be negative');
-    }
-
-    return {
-      isValid: errors.length === 0,
-      errors
-    };
-  }
-}
-```
-
-### 6.2 Data Compression Strategy
-
-For large workflows (>1MB):
-
-```typescript
-import { gzipSync, gunzipSync } from 'zlib';
-
-export function compressWorkflow(workflow: any): {
-  compressed: string;  // base64
-  originalSize: number;
-  compressedSize: number;
-} {
-  const json = JSON.stringify(workflow);
-  const buffer = Buffer.from(json, 'utf-8');
-  const compressed = gzipSync(buffer);
-  const base64 = compressed.toString('base64');
-
-  return {
-    compressed: base64,
-    originalSize: buffer.length,
-    compressedSize: compressed.length
-  };
-}
-
-export function decompressWorkflow(compressed: string): any {
-  const buffer = Buffer.from(compressed, 'base64');
-  const decompressed = gunzipSync(buffer);
-  const json = decompressed.toString('utf-8');
-  return JSON.parse(json);
-}
-```
-
----
-
-## 7. Query Examples for Analysis
-
-### 7.1 Basic Mutation Statistics
-
-```sql
--- Overall mutation metrics
-SELECT
-  COUNT(*) as total_mutations,
-  COUNT(*) FILTER(WHERE mutation_success) as successful,
-  COUNT(*) FILTER(WHERE validation_improved) as validation_improved,
-  ROUND(100.0 * COUNT(*) FILTER(WHERE mutation_success) / COUNT(*), 2) as success_rate,
-  ROUND(100.0 * COUNT(*) FILTER(WHERE validation_improved) / COUNT(*), 2) as improvement_rate,
-  AVG(nodes_modified_count) as avg_nodes_modified,
-  AVG(properties_modified_count) as avg_properties_modified,
-  AVG(execution_duration_ms)::INTEGER as avg_duration_ms
-FROM workflow_mutations
-WHERE created_at >= NOW() - INTERVAL '7 days';
-```
-
-### 7.2 Success by Instruction Type
-
-```sql
-SELECT
-  instruction_type,
-  COUNT(*) as count,
-  ROUND(100.0 * COUNT(*) FILTER(WHERE mutation_success) / COUNT(*), 2) as success_rate,
-  ROUND(100.0 * COUNT(*) FILTER(WHERE validation_improved) / COUNT(*), 2) as improvement_rate,
-  AVG(validation_errors_fixed) as avg_errors_fixed,
-  AVG(new_errors_introduced) as avg_new_errors
-FROM workflow_mutations
-WHERE created_at >= NOW() - INTERVAL '30 days'
-GROUP BY instruction_type
-ORDER BY count DESC;
-```
-
-### 7.3 Most Common Mutations
-
-```sql
-SELECT
-  properties_modified,
-  COUNT(*) as frequency,
-  ROUND(100.0 * COUNT(*) / (SELECT COUNT(*) FROM workflow_mutations
-                              WHERE created_at >= NOW() - INTERVAL '30 days'), 2) as percentage
-FROM workflow_mutations
-WHERE created_at >= NOW() - INTERVAL '30 days'
-ORDER BY frequency DESC
-LIMIT 20;
-```
-
-### 7.4 Complexity Impact
-
-```sql
-SELECT
-  complexity_before,
-  complexity_after,
-  COUNT(*) as transitions,
-  ROUND(100.0 * COUNT(*) FILTER(WHERE mutation_success) / COUNT(*), 2) as success_rate
-FROM workflow_mutations
-WHERE created_at >= NOW() - INTERVAL '30 days'
-GROUP BY complexity_before, complexity_after
-ORDER BY transitions DESC;
-```
-
----
-
-## 8. Implementation Roadmap
-
-### Phase 1: Infrastructure (Week 1)
-- [ ] Create `workflow_mutations` table in Supabase
-- [ ] Add indexes for common query patterns
-- [ ] Update TypeScript types
-- [ ] Create mutation analyzer service
-- [ ] Add mutation validator
-
-### Phase 2: Integration (Week 2)
-- [ ] Extend TelemetryManager with trackWorkflowMutation()
-- [ ] Extend EventTracker with mutation queue
-- [ ] Extend BatchProcessor with flush logic
-- [ ] Add mutation event type
-
-### Phase 3: Tool Integration (Week 3)
-- [ ] Integrate with n8n_autofix_workflow
-- [ ] Integrate with n8n_update_partial_workflow
-- [ ] Add test cases
-- [ ] Documentation
-
-### Phase 4: Validation & Analysis (Week 4)
-- [ ] Run sample queries
-- [ ] Validate data quality
-- [ ] Create analytics dashboard
-- [ ] Begin dataset collection
-
----
-
-## 9. Security & Privacy Considerations
-
-- **No Credentials:** Sanitizer strips credentials before storage
-- **No Secrets:** Workflow secret references removed
-- **User Anonymity:** User ID is anonymized
-- **Hash Verification:** All workflow hashes verified before storage
-- **Size Limits:** 10MB max per workflow (with compression option)
-- **Retention:** Define data retention policy separately
-- **Encryption:** Enable Supabase encryption at rest
-- **Access Control:** Restrict table access to application-level only
-
----
-
-## 10. Performance Considerations
-
-| Aspect | Target | Strategy |
-|--------|--------|----------|
-| **Batch Flush** | <5s latency | 5-second flush interval + auto-flush |
-| **Large Workflows** | >1MB support | Gzip compression + base64 encoding |
-| **Query Performance** | <100ms | Strategic indexing + materialized views |
-| **Storage Growth** | <50GB/month | Compression + retention policies |
-| **Network Throughput** | <1MB/batch | Compress before transmission |
-
----
-
-*End of Specification*

TELEMETRY_N8N_FIXER_DATASET.md

@@ -1,450 +0,0 @@
-# N8N-Fixer Dataset: Telemetry Infrastructure Analysis
-
-**Analysis Completed:** November 12, 2025
-**Scope:** N8N-MCP Telemetry Database Schema & Workflow Mutation Tracking
-**Status:** Ready for Implementation Planning
-
----
-
-## Overview
-
-This document synthesizes a comprehensive analysis of the n8n-mcp telemetry infrastructure and provides actionable recommendations for building an n8n-fixer dataset with before/instruction/after workflow snapshots.
-
-**Key Findings:**
-- Telemetry system is production-ready with 276K+ events tracked
-- Supabase PostgreSQL backend stores all events
-- Current system **does NOT capture workflow mutations** (before→after transitions)
-- Requires new table + instrumentation to collect fixer dataset
-- Implementation is straightforward with 3-4 weeks of development
-
----
-
-## Documentation Map
-
-### 1. TELEMETRY_ANALYSIS.md (Primary Reference)
-**Length:** 720 lines | **Read Time:** 20-30 minutes
-**Contains:**
-- Complete schema analysis (tables, columns, types)
-- All 12 event types with examples
-- Current workflow tracking capabilities
-- Missing data for mutation tracking
-- Recommended schema additions
-- Technical implementation details
-
-**Start Here If:** You need the complete picture of current capabilities and gaps
-
----
-
-### 2. TELEMETRY_MUTATION_SPEC.md (Implementation Blueprint)
-**Length:** 918 lines | **Read Time:** 30-40 minutes
-**Contains:**
-- Detailed SQL schema for `workflow_mutations` table
-- Complete TypeScript interfaces and types
-- Integration points with existing tools
-- Mutation analyzer service specification
-- Batch processor extensions
-- Query examples for dataset analysis
-
-**Start Here If:** You're ready to implement the mutation tracking system
-
----
-
-### 3. TELEMETRY_QUICK_REFERENCE.md (Developer Guide)
-**Length:** 503 lines | **Read Time:** 10-15 minutes
-**Contains:**
-- Supabase connection details
-- Common queries and patterns
-- Performance tips and tricks
-- Code file references
-- Quick lookup for event types
-
-**Start Here If:** You need to query existing telemetry data or reference specific details
-
----
-
-### 4. TELEMETRY_QUICK_REFERENCE.md (Archive)
-These documents from November 8 contain additional context:
-- `TELEMETRY_ANALYSIS_REPORT.md` - Executive summary with visualizations
-- `TELEMETRY_EXECUTIVE_SUMMARY.md` - High-level overview
-- `TELEMETRY_TECHNICAL_DEEP_DIVE.md` - Architecture details
-- `TELEMETRY_DATA_FOR_VISUALIZATION.md` - Sample data for dashboards
-
----
-
-## Current State Summary
-
-### Telemetry Backend
-```
-URL:     https://ydyufsohxdfpopqbubwk.supabase.co
-Database: PostgreSQL
-Tables:   telemetry_events (276K rows)
-          telemetry_workflows (6.5K rows)
-Privacy:  PII sanitization enabled
-Scope:    Anonymous tool usage, workflows, errors
-```
-
-### Tracked Event Categories
-1. **Tool Usage** (40-50%) - Which tools users employ
-2. **Tool Sequences** (20-30%) - How tools are chained together
-3. **Errors** (10-15%) - Error types and context
-4. **Validation** (5-10%) - Configuration validation details
-5. **Workflows** (5-10%) - Workflow creation and structure
-6. **Performance** (5-10%) - Operation latency
-7. **Sessions** (misc) - User session metadata
-
-### What's Missing for N8N-Fixer
-```
-MISSING: Workflow Mutation Events
-- No before workflow capture
-- No instruction/transformation storage
-- No after workflow snapshot
-- No mutation success metrics
-- No validation improvement tracking
-```
-
----
-
-## Recommended Implementation Path
-
-### Phase 1: Infrastructure (1-2 weeks)
-1. Create `workflow_mutations` table in Supabase
-   - See TELEMETRY_MUTATION_SPEC.md Section 2.1 for full SQL
-   - Includes 20+ strategic indexes
-   - Supports compression for large workflows
-
-2. Update TypeScript types
-   - New `WorkflowMutation` interface
-   - New `WorkflowMutationEvent` event type
-   - Mutation analyzer service
-
-3. Add data validators
-   - Hash verification
-   - Deduplication logic
-   - Size validation
-
----
-
-### Phase 2: Core Integration (1-2 weeks)
-1. Extend TelemetryManager
-   - Add `trackWorkflowMutation()` method
-   - Auto-flush mutations to prevent loss
-
-2. Extend EventTracker
-   - Add mutation queue
-   - Mutation analyzer integration
-   - Validation state detection
-
-3. Extend BatchProcessor
-   - Flush workflow mutations to Supabase
-   - Retry logic and dead letter queue
-   - Performance monitoring
-
----
-
-### Phase 3: Tool Integration (1 week)
-Instrument 3 key tools to capture mutations:
-
-1. **n8n_autofix_workflow**
-   - Before: Broken workflow
-   - Instruction: "Auto-fix validation errors"
-   - After: Fixed workflow
-   - Type: `auto_fix`
-
-2. **n8n_update_partial_workflow**
-   - Before: Current workflow
-   - Instruction: Diff operations
-   - After: Updated workflow
-   - Type: `user_provided`
-
-3. **Validation Engine** (if applicable)
-   - Before: Invalid workflow
-   - Instruction: Validation correction
-   - After: Valid workflow
-   - Type: `validation_correction`
-
----
-
-### Phase 4: Validation & Analysis (1 week)
-1. Data quality verification
-   - Hash validation
-   - Size checks
-   - Deduplication effectiveness
-
-2. Sample query execution
-   - Success rate by instruction type
-   - Common mutations
-   - Complexity impact
-
-3. Dataset assessment
-   - Volume estimates
-   - Data distribution
-   - Quality metrics
-
----
-
-## Key Metrics You'll Collect
-
-### Per Mutation Record
-- **Identification:** User ID, Workflow ID, Timestamp
-- **Before State:** Full workflow JSON, hash, validation status
-- **Instruction:** The transformation prompt/directive
-- **After State:** Full workflow JSON, hash, validation status
-- **Changes:** Nodes modified, properties changed, connections modified
-- **Outcome:** Success boolean, validation improvement, errors fixed
-
-### Aggregate Analysis
-```sql
--- Success rates by instruction type
-SELECT instruction_type, COUNT(*) as count,
-       ROUND(100.0 * COUNT(*) FILTER(WHERE mutation_success) / COUNT(*), 2) as success_rate
-FROM workflow_mutations
-GROUP BY instruction_type;
-
--- Validation improvement distribution
-SELECT validation_errors_fixed, COUNT(*) as count
-FROM workflow_mutations
-WHERE validation_improved = true
-GROUP BY 1
-ORDER BY 2 DESC;
-
--- Complexity transitions
-SELECT complexity_before, complexity_after, COUNT(*) as transitions
-FROM workflow_mutations
-GROUP BY 1, 2;
-```
-
----
-
-## Storage Requirements
-
-### Data Size Estimates
-```
-Average Before Workflow:     10 KB
-Average After Workflow:      10 KB
-Average Instruction:         500 B
-Indexes & Metadata:          5 KB
-Per Mutation Total:          25 KB
-
-Monthly Mutations (estimate): 10K-50K
-Monthly Storage:             250 MB - 1.2 GB
-Annual Storage:              3-14 GB
-```
-
-### Optimization Strategies
-1. **Compression:** Gzip workflows >1MB
-2. **Deduplication:** Skip identical before/after pairs
-3. **Retention:** Define archival policy (90 days? 1 year?)
-4. **Indexing:** Materialized views for common queries
-
----
-
-## Data Safety & Privacy
-
-### Current Protections
-- User IDs are anonymized
-- Credentials are stripped from workflows
-- Email addresses are masked [EMAIL]
-- API keys are masked [KEY]
-- URLs are masked [URL]
-- Error messages are sanitized
-
-### For Mutations Table
-- Continue PII sanitization
-- Hash verification for integrity
-- Size limits (10 MB per workflow with compression)
-- User consent (telemetry opt-in)
-
----
-
-## Integration Points
-
-### Where to Add Tracking Calls
-```typescript
-// In n8n_autofix_workflow
-await telemetry.trackWorkflowMutation(
-  originalWorkflow,
-  'Auto-fix validation errors',
-  fixedWorkflow,
-  { instructionType: 'auto_fix', success: true }
-);
-
-// In n8n_update_partial_workflow
-await telemetry.trackWorkflowMutation(
-  currentWorkflow,
-  formatOperationsAsInstruction(operations),
-  updatedWorkflow,
-  { instructionType: 'user_provided' }
-);
-```
-
-### No Breaking Changes
-- Fully backward compatible
-- Existing telemetry unaffected
-- Optional feature (can disable if needed)
-- Doesn't require version bump
-
----
-
-## Success Criteria
-
-### Phase 1 Complete When:
-- [ ] `workflow_mutations` table created with all indexes
-- [ ] TypeScript types defined and compiling
-- [ ] Validators written and tested
-- [ ] No schema changes needed (validated against use cases)
-
-### Phase 2 Complete When:
-- [ ] TelemetryManager has `trackWorkflowMutation()` method
-- [ ] EventTracker queues mutations properly
-- [ ] BatchProcessor flushes mutations to Supabase
-- [ ] Integration tests pass
-
-### Phase 3 Complete When:
-- [ ] 3+ tools instrumented with tracking calls
-- [ ] Manual testing shows mutations captured
-- [ ] Sample mutations visible in Supabase
-- [ ] No performance regression in tools
-
-### Phase 4 Complete When:
-- [ ] 100+ mutations collected and validated
-- [ ] Sample queries execute correctly
-- [ ] Data quality metrics acceptable
-- [ ] Dataset ready for ML training
-
----
-
-## File Structure for Implementation
-
-```
-src/telemetry/
-├── telemetry-types.ts          (Update: Add WorkflowMutation interface)
-├── telemetry-manager.ts        (Update: Add trackWorkflowMutation method)
-├── event-tracker.ts            (Update: Add mutation tracking)
-├── batch-processor.ts          (Update: Add flush mutations)
-├── mutation-analyzer.ts        (NEW: Analyze workflow diffs)
-├── mutation-validator.ts       (NEW: Validate mutation data)
-└── index.ts                    (Update: Export new functions)
-
-tests/
-└── unit/telemetry/
-    ├── mutation-analyzer.test.ts        (NEW)
-    ├── mutation-validator.test.ts       (NEW)
-    └── telemetry-integration.test.ts    (Update)
-```
-
----
-
-## Risk Assessment
-
-### Low Risk
-- No changes to existing event system
-- Supabase table addition is non-breaking
-- TypeScript types only (no runtime impact)
-
-### Medium Risk
-- Large workflows may impact performance if not compressed
-- Storage costs if dataset grows faster than estimated
-- Mitigation: Compression + retention policy
-
-### High Risk
-- None identified if implemented as specified
-
----
-
-## Next Steps
-
-1. **Review This Analysis**
-   - Read TELEMETRY_ANALYSIS.md (main reference)
-   - Review TELEMETRY_MUTATION_SPEC.md (implementation guide)
-
-2. **Plan Implementation**
-   - Estimate developer hours
-   - Assign implementation tasks
-   - Create Jira tickets or equivalent
-
-3. **Phase 1: Create Infrastructure**
-   - Create Supabase table
-   - Define TypeScript types
-   - Write validators
-
-4. **Phase 2: Integrate Core**
-   - Extend telemetry system
-   - Write integration tests
-
-5. **Phase 3: Instrument Tools**
-   - Add tracking calls to 3+ mutation sources
-   - Test end-to-end
-
-6. **Phase 4: Validate**
-   - Collect sample data
-   - Run analysis queries
-   - Begin dataset collection
-
----
-
-## Questions to Answer Before Starting
-
-1. **Data Retention:** How long should mutations be kept? (90 days? 1 year?)
-2. **Storage Budget:** What's acceptable monthly storage cost?
-3. **Workflow Size:** What's the max workflow size to store? (with or without compression?)
-4. **Dataset Timeline:** When do you need first 1K/10K/100K samples?
-5. **Privacy:** Any additional PII to sanitize beyond current approach?
-6. **User Consent:** Should mutation tracking be separate opt-in from telemetry?
-
----
-
-## Useful Commands
-
-### View Current Telemetry Tables
-```sql
-SELECT table_name FROM information_schema.tables
-WHERE table_schema = 'public'
-AND table_name LIKE 'telemetry%';
-```
-
-### Count Current Events
-```sql
-SELECT event, COUNT(*) FROM telemetry_events
-GROUP BY event ORDER BY 2 DESC;
-```
-
-### Check Workflow Deduplication Rate
-```sql
-SELECT COUNT(*) as total,
-       COUNT(DISTINCT workflow_hash) as unique
-FROM telemetry_workflows;
-```
-
----
-
-## Document References
-
-All documents are in the n8n-mcp repository root:
-
-| Document | Purpose | Read Time |
-|----------|---------|-----------|
-| TELEMETRY_ANALYSIS.md | Complete schema & event analysis | 20-30 min |
-| TELEMETRY_MUTATION_SPEC.md | Implementation specification | 30-40 min |
-| TELEMETRY_QUICK_REFERENCE.md | Developer quick lookup | 10-15 min |
-| TELEMETRY_ANALYSIS_REPORT.md | Executive summary (archive) | 15-20 min |
-| TELEMETRY_TECHNICAL_DEEP_DIVE.md | Architecture (archive) | 20-25 min |
-
----
-
-## Summary
-
-The n8n-mcp telemetry infrastructure is mature, privacy-conscious, and well-designed. It currently tracks user interactions effectively but lacks workflow mutation capture needed for the n8n-fixer dataset.
-
-**The solution is straightforward:** Add a single `workflow_mutations` table, extend the tracking system, and instrument 3-4 key tools.
-
-**Implementation effort:** 3-4 weeks for a complete, production-ready system.
-
-**Result:** A high-quality dataset of before/instruction/after workflow transformations suitable for training ML models to fix broken n8n workflows automatically.
-
----
-
-**Analysis completed by:** Telemetry Data Analyst
-**Date:** November 12, 2025
-**Status:** Ready for implementation planning
-
-For questions or clarifications, refer to the detailed specifications or raise issues on GitHub.

TELEMETRY_QUICK_REFERENCE.md

@@ -1,503 +0,0 @@
-# Telemetry Quick Reference Guide
-
-Quick lookup for telemetry data access, queries, and common analysis patterns.
-
----
-
-## Supabase Connection Details
-
-### Database
-- **URL:** `https://ydyufsohxdfpopqbubwk.supabase.co`
-- **Project:** n8n-mcp telemetry database
-- **Region:** (inferred from URL)
-
-### Anon Key
-Located in: `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/telemetry-types.ts` (line 105)
-
-### Tables
-| Name | Rows | Purpose |
-|------|------|---------|
-| `telemetry_events` | 276K+ | Discrete events (tool usage, errors, validation) |
-| `telemetry_workflows` | 6.5K+ | Workflow metadata (structure, complexity) |
-
-### Proposed Table
-| Name | Rows | Purpose |
-|------|------|---------|
-| `workflow_mutations` | TBD | Before/instruction/after workflow snapshots |
-
----
-
-## Event Types & Properties
-
-### High-Volume Events
-
-#### `tool_used` (40-50% of traffic)
-```json
-{
-  "event": "tool_used",
-  "properties": {
-    "tool": "get_node_info",
-    "success": true,
-    "duration": 245
-  }
-}
-```
-**Query:** Find most used tools
-```sql
-SELECT properties->>'tool' as tool, COUNT(*) as count
-FROM telemetry_events
-WHERE event = 'tool_used' AND created_at >= NOW() - INTERVAL '7 days'
-GROUP BY 1 ORDER BY 2 DESC;
-```
-
-#### `tool_sequence` (20-30% of traffic)
-```json
-{
-  "event": "tool_sequence",
-  "properties": {
-    "previousTool": "search_nodes",
-    "currentTool": "get_node_info",
-    "timeDelta": 1250,
-    "isSlowTransition": false,
-    "sequence": "search_nodes->get_node_info"
-  }
-}
-```
-**Query:** Find common tool sequences
-```sql
-SELECT properties->>'sequence' as flow, COUNT(*) as count
-FROM telemetry_events
-WHERE event = 'tool_sequence' AND created_at >= NOW() - INTERVAL '30 days'
-GROUP BY 1 ORDER BY 2 DESC LIMIT 20;
-```
-
----
-
-### Error & Validation Events
-
-#### `error_occurred` (10-15% of traffic)
-```json
-{
-  "event": "error_occurred",
-  "properties": {
-    "errorType": "validation_error",
-    "context": "Node config failed [KEY]",
-    "tool": "config_validator",
-    "error": "[SANITIZED] type error",
-    "mcpMode": "stdio",
-    "platform": "darwin"
-  }
-}
-```
-**Query:** Error frequency by type
-```sql
-SELECT
-  properties->>'errorType' as error_type,
-  COUNT(*) as frequency,
-  COUNT(DISTINCT user_id) as affected_users
-FROM telemetry_events
-WHERE event = 'error_occurred' AND created_at >= NOW() - INTERVAL '24 hours'
-GROUP BY 1 ORDER BY 2 DESC;
-```
-
-#### `validation_details` (5-10% of traffic)
-```json
-{
-  "event": "validation_details",
-  "properties": {
-    "nodeType": "nodes_base_httpRequest",
-    "errorType": "required_field_missing",
-    "errorCategory": "required_field_error",
-    "details": { /* error details */ }
-  }
-}
-```
-**Query:** Validation errors by node type
-```sql
-SELECT
-  properties->>'nodeType' as node_type,
-  properties->>'errorType' as error_type,
-  COUNT(*) as count
-FROM telemetry_events
-WHERE event = 'validation_details' AND created_at >= NOW() - INTERVAL '7 days'
-GROUP BY 1, 2 ORDER BY 3 DESC;
-```
-
----
-
-### Workflow Events
-
-#### `workflow_created`
-```json
-{
-  "event": "workflow_created",
-  "properties": {
-    "nodeCount": 3,
-    "nodeTypes": 2,
-    "complexity": "simple",
-    "hasTrigger": true,
-    "hasWebhook": false
-  }
-}
-```
-**Query:** Workflow creation trends
-```sql
-SELECT
-  DATE(created_at) as date,
-  COUNT(*) as workflows_created,
-  AVG((properties->>'nodeCount')::int) as avg_nodes,
-  COUNT(*) FILTER(WHERE properties->>'complexity' = 'simple') as simple_count
-FROM telemetry_events
-WHERE event = 'workflow_created' AND created_at >= NOW() - INTERVAL '30 days'
-GROUP BY 1 ORDER BY 1;
-```
-
-#### `workflow_validation_failed`
-```json
-{
-  "event": "workflow_validation_failed",
-  "properties": {
-    "nodeCount": 5
-  }
-}
-```
-**Query:** Validation failure rate
-```sql
-SELECT
-  COUNT(*) FILTER(WHERE event = 'workflow_created') as successful,
-  COUNT(*) FILTER(WHERE event = 'workflow_validation_failed') as failed,
-  ROUND(100.0 * COUNT(*) FILTER(WHERE event = 'workflow_validation_failed')
-        / NULLIF(COUNT(*), 0), 2) as failure_rate
-FROM telemetry_events
-WHERE created_at >= NOW() - INTERVAL '7 days'
-  AND event IN ('workflow_created', 'workflow_validation_failed');
-```
-
----
-
-### Session & System Events
-
-#### `session_start`
-```json
-{
-  "event": "session_start",
-  "properties": {
-    "version": "2.22.15",
-    "platform": "darwin",
-    "arch": "arm64",
-    "nodeVersion": "v18.17.0",
-    "isDocker": false,
-    "cloudPlatform": null,
-    "mcpMode": "stdio",
-    "startupDurationMs": 1234
-  }
-}
-```
-**Query:** Platform distribution
-```sql
-SELECT
-  properties->>'platform' as platform,
-  properties->>'arch' as arch,
-  COUNT(*) as sessions,
-  AVG((properties->>'startupDurationMs')::int) as avg_startup_ms
-FROM telemetry_events
-WHERE event = 'session_start' AND created_at >= NOW() - INTERVAL '30 days'
-GROUP BY 1, 2 ORDER BY 3 DESC;
-```
-
----
-
-## Workflow Metadata Table Queries
-
-### Workflow Complexity Distribution
-```sql
-SELECT
-  complexity,
-  COUNT(*) as count,
-  AVG(node_count) as avg_nodes,
-  MAX(node_count) as max_nodes
-FROM telemetry_workflows
-GROUP BY complexity
-ORDER BY count DESC;
-```
-
-### Most Common Node Type Combinations
-```sql
-SELECT
-  node_types,
-  COUNT(*) as frequency
-FROM telemetry_workflows
-GROUP BY node_types
-ORDER BY frequency DESC
-LIMIT 20;
-```
-
-### Workflows with Triggers vs Webhooks
-```sql
-SELECT
-  has_trigger,
-  has_webhook,
-  COUNT(*) as count,
-  ROUND(100.0 * COUNT(*) / (SELECT COUNT(*) FROM telemetry_workflows), 2) as percentage
-FROM telemetry_workflows
-GROUP BY 1, 2;
-```
-
-### Deduplicated Workflows (by hash)
-```sql
-SELECT
-  COUNT(DISTINCT workflow_hash) as unique_workflows,
-  COUNT(*) as total_rows,
-  COUNT(DISTINCT user_id) as unique_users
-FROM telemetry_workflows;
-```
-
----
-
-## Common Analysis Patterns
-
-### 1. User Journey Analysis
-```sql
--- Tool usage patterns for a user (anonymized)
-WITH user_events AS (
-  SELECT
-    user_id,
-    event,
-    properties->>'tool' as tool,
-    created_at,
-    LAG(event) OVER(PARTITION BY user_id ORDER BY created_at) as prev_event
-  FROM telemetry_events
-  WHERE event IN ('tool_used', 'tool_sequence')
-    AND created_at >= NOW() - INTERVAL '7 days'
-)
-SELECT
-  prev_event,
-  event,
-  COUNT(*) as transitions
-FROM user_events
-WHERE prev_event IS NOT NULL
-GROUP BY 1, 2
-ORDER BY 3 DESC
-LIMIT 20;
-```
-
-### 2. Performance Trends
-```sql
--- Tool execution performance over time
-WITH perf_data AS (
-  SELECT
-    properties->>'tool' as tool,
-    (properties->>'duration')::int as duration,
-    DATE(created_at) as date
-  FROM telemetry_events
-  WHERE event = 'tool_used'
-    AND created_at >= NOW() - INTERVAL '30 days'
-)
-SELECT
-  date,
-  tool,
-  COUNT(*) as executions,
-  AVG(duration)::INTEGER as avg_duration_ms,
-  PERCENTILE_CONT(0.95) WITHIN GROUP(ORDER BY duration) as p95_duration_ms,
-  MAX(duration) as max_duration_ms
-FROM perf_data
-GROUP BY date, tool
-ORDER BY date DESC, tool;
-```
-
-### 3. Error Analysis with Context
-```sql
--- Recent errors with affected tools
-SELECT
-  properties->>'errorType' as error_type,
-  properties->>'tool' as affected_tool,
-  properties->>'context' as context,
-  COUNT(*) as occurrences,
-  MAX(created_at) as most_recent,
-  COUNT(DISTINCT user_id) as users_affected
-FROM telemetry_events
-WHERE event = 'error_occurred'
-  AND created_at >= NOW() - INTERVAL '24 hours'
-GROUP BY 1, 2, 3
-ORDER BY 4 DESC, 5 DESC;
-```
-
-### 4. Node Configuration Patterns
-```sql
--- Most configured nodes and their complexity
-WITH config_data AS (
-  SELECT
-    properties->>'nodeType' as node_type,
-    (properties->>'propertiesSet')::int as props_set,
-    properties->>'usedDefaults' = 'true' as used_defaults
-  FROM telemetry_events
-  WHERE event = 'node_configuration'
-    AND created_at >= NOW() - INTERVAL '30 days'
-)
-SELECT
-  node_type,
-  COUNT(*) as configurations,
-  AVG(props_set)::INTEGER as avg_props_set,
-  ROUND(100.0 * SUM(CASE WHEN used_defaults THEN 1 ELSE 0 END)
-        / COUNT(*), 2) as default_usage_rate
-FROM config_data
-GROUP BY node_type
-ORDER BY 2 DESC
-LIMIT 20;
-```
-
-### 5. Search Effectiveness
-```sql
--- Search queries and their success
-SELECT
-  properties->>'searchType' as search_type,
-  COUNT(*) as total_searches,
-  COUNT(*) FILTER(WHERE (properties->>'hasResults')::boolean) as with_results,
-  ROUND(100.0 * COUNT(*) FILTER(WHERE (properties->>'hasResults')::boolean)
-        / COUNT(*), 2) as success_rate,
-  AVG((properties->>'resultsFound')::int) as avg_results
-FROM telemetry_events
-WHERE event = 'search_query'
-  AND created_at >= NOW() - INTERVAL '7 days'
-GROUP BY 1
-ORDER BY 2 DESC;
-```
-
----
-
-## Data Size Estimates
-
-### Current Data Volume
-- **Total Events:** ~276K rows
-- **Size per Event:** ~200 bytes (average)
-- **Total Size (events):** ~55 MB
-
-- **Total Workflows:** ~6.5K rows
-- **Size per Workflow:** ~2 KB (sanitized)
-- **Total Size (workflows):** ~13 MB
-
-**Total Current Storage:** ~68 MB
-
-### Growth Projections
-- **Daily Events:** ~1,000-2,000
-- **Monthly Growth:** ~30-60 MB
-- **Annual Growth:** ~360-720 MB
-
----
-
-## Helpful Constants
-
-### Event Type Values
-```
-tool_used
-tool_sequence
-error_occurred
-validation_details
-node_configuration
-performance_metric
-search_query
-workflow_created
-workflow_validation_failed
-session_start
-startup_completed
-startup_error
-```
-
-### Complexity Values
-```
-'simple'
-'medium'
-'complex'
-```
-
-### Validation Status Values (for mutations)
-```
-'valid'
-'invalid'
-'unknown'
-```
-
-### Instruction Type Values (for mutations)
-```
-'ai_generated'
-'user_provided'
-'auto_fix'
-'validation_correction'
-```
-
----
-
-## Tips & Tricks
-
-### Finding Zero-Result Searches
-```sql
-SELECT properties->>'query' as search_term, COUNT(*) as attempts
-FROM telemetry_events
-WHERE event = 'search_query'
-  AND (properties->>'isZeroResults')::boolean = true
-  AND created_at >= NOW() - INTERVAL '7 days'
-GROUP BY 1 ORDER BY 2 DESC;
-```
-
-### Identifying Slow Operations
-```sql
-SELECT
-  properties->>'operation' as operation,
-  COUNT(*) as count,
-  PERCENTILE_CONT(0.99) WITHIN GROUP(ORDER BY (properties->>'duration')::int) as p99_ms
-FROM telemetry_events
-WHERE event = 'performance_metric'
-  AND created_at >= NOW() - INTERVAL '7 days'
-GROUP BY 1
-HAVING PERCENTILE_CONT(0.99) WITHIN GROUP(ORDER BY (properties->>'duration')::int) > 1000
-ORDER BY 3 DESC;
-```
-
-### User Retention Analysis
-```sql
--- Active users by week
-WITH weekly_users AS (
-  SELECT
-    DATE_TRUNC('week', created_at) as week,
-    COUNT(DISTINCT user_id) as active_users
-  FROM telemetry_events
-  WHERE created_at >= NOW() - INTERVAL '90 days'
-  GROUP BY 1
-)
-SELECT week, active_users
-FROM weekly_users
-ORDER BY week DESC;
-```
-
-### Platform Usage Breakdown
-```sql
-SELECT
-  properties->>'platform' as platform,
-  properties->>'arch' as architecture,
-  COALESCE(properties->>'cloudPlatform', 'local') as deployment,
-  COUNT(DISTINCT user_id) as unique_users
-FROM telemetry_events
-WHERE event = 'session_start'
-  AND created_at >= NOW() - INTERVAL '30 days'
-GROUP BY 1, 2, 3
-ORDER BY 4 DESC;
-```
-
----
-
-## File References for Development
-
-### Source Code
-- **Types:** `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/telemetry-types.ts`
-- **Manager:** `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/telemetry-manager.ts`
-- **Tracker:** `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/event-tracker.ts`
-- **Processor:** `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/batch-processor.ts`
-
-### Documentation
-- **Full Analysis:** `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/TELEMETRY_ANALYSIS.md`
-- **Mutation Spec:** `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/TELEMETRY_MUTATION_SPEC.md`
-- **This Guide:** `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/TELEMETRY_QUICK_REFERENCE.md`
-
----
-
-*Last Updated: November 12, 2025*

TELEMETRY_TECHNICAL_DEEP_DIVE.md

@@ -1,654 +0,0 @@
-# n8n-MCP Telemetry Technical Deep-Dive
-## Detailed Error Patterns and Root Cause Analysis
-
----
-
-## 1. ValidationError Root Causes (3,080 occurrences)
-
-### 1.1 Workflow Structure Validation (21,423 node-level errors - 39.11%)
-
-**Error Distribution by Node:**
-- `workflow` node: 21,423 errors (39.11%)
-- Generic nodes (Node0-19): ~6,000 errors (11%)
-- Placeholder nodes ([KEY], ______, _____): ~1,600 errors (3%)
-- Real nodes (Webhook, HTTP_Request): ~600 errors (1%)
-
-**Interpreted Issue Categories:**
-
-1. **Missing Trigger Nodes (Estimated 35-40% of workflow errors)**
-   - Users create workflows without start trigger
-   - Validation requires at least one trigger (webhook, schedule, etc.)
-   - Error message: Generic "validation failed" doesn't specify missing trigger
-
-2. **Invalid Node Connections (Estimated 25-30% of workflow errors)**
-   - Nodes connected in wrong order
-   - Output type mismatch between connected nodes
-   - Circular dependencies created
-   - Example: Trying to use output of node that hasn't run yet
-
-3. **Type Mismatches (Estimated 20-25% of workflow errors)**
-   - Node expects array, receives string
-   - Node expects object, receives primitive
-   - Related to TypeError errors (2,767 occurrences)
-
-4. **Missing Required Properties (Estimated 10-15% of workflow errors)**
-   - Webhook nodes missing path/method
-   - HTTP nodes missing URL
-   - Database nodes missing connection string
-
-### 1.2 Placeholder Node Test Data (4,700+ errors)
-
-**Problem:** Generic test node names creating noise
-
-```
-Node0-Node19:    ~6,000+ errors
-[KEY]:           656 errors
-______ (6 underscores): 643 errors
-_____ (5 underscores): 207 errors
-______ (8 underscores): 227 errors
-```
-
-**Evidence:** These names appear in telemetry_validation_errors_daily
-- Consistent across 25-36 days
-- Indicates: System test data or user test workflows
-
-**Action Required:**
-1. Filter test data from telemetry (add flag for test vs. production)
-2. Clean up existing test workflows from database
-3. Implement test isolation so test events don't pollute metrics
-
-### 1.3 Webhook Validation Issues (435 errors)
-
-**Webhook-Specific Problems:**
-
-```
-Error Pattern Analysis:
-- Webhook: 435 errors
-- Webhook_Trigger: 293 errors
-- Total Webhook-related: 728 errors (~1.3% of validation errors)
-```
-
-**Common Webhook Failures:**
-1. **Missing Required Fields:**
-   - No HTTP method specified (GET/POST/PUT/DELETE)
-   - No URL path configured
-   - No authentication method selected
-
-2. **Configuration Errors:**
-   - Invalid URL patterns (special characters, spaces)
-   - Incorrect CORS settings
-   - Missing body for POST/PUT operations
-   - Header format issues
-
-3. **Connection Issues:**
-   - Firewall/network blocking
-   - Unsupported protocol (HTTP vs HTTPS mismatch)
-   - TLS version incompatibility
-
----
-
-## 2. TypeError Root Causes (2,767 occurrences)
-
-### 2.1 Type Mismatch Categories
-
-**Pattern Analysis:**
-- 31.23% of all errors
-- Indicates schema/type enforcement issues
-- Overlaps with ValidationError (both types occur together)
-
-### 2.2 Common Type Mismatches
-
-**JSON Property Errors (Estimated 40% of TypeErrors):**
-```
-Problem: properties field in telemetry_events is JSONB
-Possible Issues:
-- Passing string "true" instead of boolean true
-- Passing number as string "123"
-- Passing array [value] instead of scalar value
-- Nested object structure violations
-```
-
-**Node Property Errors (Estimated 35% of TypeErrors):**
-```
-HTTP Request Node Example:
-- method: Expects "GET" | "POST" | etc., receives 1, 0 (numeric)
-- timeout: Expects number (ms), receives string "5000"
-- headers: Expects object {key: value}, receives string "[object Object]"
-```
-
-**Expression Errors (Estimated 25% of TypeErrors):**
-```
-n8n Expressions Example:
-- $json.count expects number, receives $json.count_str (string)
-- $node[nodeId].data expects array, receives single object
-- Missing type conversion: parseInt(), String(), etc.
-```
-
-### 2.3 Type Validation System Gaps
-
-**Current System Weakness:**
-- JSONB storage in Postgres doesn't enforce types
-- Validation happens at application layer
-- No real-time type checking during workflow building
-- Type errors only discovered at validation time
-
-**Recommended Fixes:**
-1. Implement strict schema validation in node parser
-2. Add TypeScript definitions for all node properties
-3. Generate type stubs from node definitions
-4. Validate types during property extraction phase
-
----
-
-## 3. Generic Error Root Causes (2,711 occurrences)
-
-### 3.1 Why Generic Errors Are Problematic
-
-**Current Classification:**
-- 30.60% of all errors
-- No error code or subtype
-- Indicates unhandled exception scenario
-- Prevents automated recovery
-
-**Likely Sources:**
-
-1. **Database Connection Errors (Estimated 30%)**
-   - Timeout during validation query
-   - Connection pool exhaustion
-   - Query too large/complex
-
-2. **Out of Memory Errors (Estimated 20%)**
-   - Large workflow processing
-   - Huge node count (100+ nodes)
-   - Property extraction on complex nodes
-
-3. **Unhandled Exceptions (Estimated 25%)**
-   - Code path not covered by specific error handling
-   - Unexpected input format
-   - Missing null checks
-
-4. **External Service Failures (Estimated 15%)**
-   - Documentation fetch timeout
-   - Node package load failure
-   - Network connectivity issues
-
-5. **Unknown Issues (Estimated 10%)**
-   - No further categorization available
-
-### 3.2 Error Context Missing
-
-**What We Know:**
-- Error occurred during validation/operation
-- Generic type (Error vs. ValidationError vs. TypeError)
-
-**What We Don't Know:**
-- Which specific validation step failed
-- What input caused the error
-- What operation was in progress
-- Root exception details (stack trace)
-
----
-
-## 4. Tool-Specific Failure Analysis
-
-### 4.1 `get_node_info` - 11.72% Failure Rate (CRITICAL)
-
-**Failure Count:** 1,208 out of 10,304 invocations
-
-**Hypothesis Testing:**
-
-**Hypothesis 1: Missing Database Records (30% likelihood)**
-```
-Scenario: Node definition not in database
-Evidence:
-- 1,208 failures across 36 days
-- Consistent rate suggests systematic gaps
-- New nodes not in database after updates
-
-Solution:
-- Verify database has 525 total nodes
-- Check if failing on node types that exist
-- Implement cache warming
-```
-
-**Hypothesis 2: Encoding/Parsing Issues (40% likelihood)**
-```
-Scenario: Complex node properties fail to parse
-Evidence:
-- Only 11.72% fail (not all complex nodes)
-- Specific to get_node_info, not essentials
-- Likely: edge case in JSONB serialization
-
-Example Problem:
-- Node with circular references
-- Node with very large property tree
-- Node with special characters in documentation
-- Node with unicode/non-ASCII characters
-
-Solution:
-- Add error telemetry to capture failing node names
-- Implement pagination for large properties
-- Add encoding validation
-```
-
-**Hypothesis 3: Concurrent Access Issues (20% likelihood)**
-```
-Scenario: Race condition during node updates
-Evidence:
-- Fails at specific times
-- Not tied to specific node types
-- Affects retrieval, not storage
-
-Solution:
-- Add read locking during updates
-- Implement query timeouts
-- Add retry logic with exponential backoff
-```
-
-**Hypothesis 4: Query Timeout (10% likelihood)**
-```
-Scenario: Database query takes >30s for large nodes
-Evidence:
-- Observed in telemetry tool sequences
-- High latency for some operations
-- System resource constraints
-
-Solution:
-- Add query optimization
-- Implement caching layer
-- Pre-compute common queries
-```
-
-### 4.2 `get_node_documentation` - 4.13% Failure Rate
-
-**Failure Count:** 471 out of 11,403 invocations
-
-**Root Causes (Estimated):**
-
-1. **Missing Documentation (40%)** - Some nodes lack comprehensive docs
-2. **Retrieval Errors (30%)** - Timeout fetching from n8n.io API
-3. **Parsing Errors (20%)** - Documentation format issues
-4. **Encoding Issues (10%)** - Non-ASCII characters in docs
-
-**Pattern:** Correlated with `get_node_info` failures (both documentation retrieval)
-
-### 4.3 `validate_node_operation` - 6.42% Failure Rate
-
-**Failure Count:** 363 out of 5,654 invocations
-
-**Root Causes (Estimated):**
-
-1. **Incomplete Operation Definitions (40%)**
-   - Validator doesn't know all valid operations for node
-   - Operation definitions outdated vs. actual node
-   - New operations not in validator database
-
-2. **Property Dependency Logic Gaps (35%)**
-   - Validator doesn't understand conditional requirements
-   - Missing: "if X is set, then Y is required"
-   - Property visibility rules incomplete
-
-3. **Type Matching Failures (20%)**
-   - Validator expects different type than provided
-   - Type coercion not working
-   - Related to TypeError issues
-
-4. **Edge Cases (5%)**
-   - Unusual property combinations
-   - Boundary conditions
-   - Rarely-used operation modes
-
----
-
-## 5. Temporal Error Patterns
-
-### 5.1 Error Spike Root Causes
-
-**September 26 Spike (6,222 validation errors)**
-- Represents: 70% of September errors in single day
-- Possible causes:
-  1. Batch workflow import test
-  2. Database migration or schema change
-  3. Node definitions updated incompatibly
-  4. System performance issue (slow validation)
-
-**October 12 Spike (567.86% increase: 28 → 187 errors)**
-- Could indicate: System restart, deployment, rollback
-- Recovery pattern: Immediate return to normal
-- Suggests: One-time event, not systemic
-
-**October 3-10 Plateau (2,000+ errors daily)**
-- Duration: 8 days sustained elevation
-- Peak: October 4 (3,585 errors)
-- Recovery: October 11 (83.72% drop to 28 errors)
-- Interpretation: Incident period with mitigation
-
-### 5.2 Current Trend (Oct 30-31)
-
-- Oct 30: 278 errors (elevated)
-- Oct 31: 130 errors (recovering)
-- Baseline: 60-65 errors/day (normal)
-
-**Interpretation:** System health improving; approaching steady state
-
----
-
-## 6. Tool Sequence Performance Bottlenecks
-
-### 6.1 Sequential Update Loop Analysis
-
-**Pattern:** `n8n_update_partial_workflow → n8n_update_partial_workflow`
-- **Occurrences:** 96,003 (highest volume)
-- **Avg Duration:** 55.2 seconds
-- **Slow Transitions:** 63,322 (66%)
-
-**Why This Matters:**
-```
-Scenario: Workflow with 20 property updates
-Current: 20 × 55.2s = 18.4 minutes total
-With batch operation: ~5-10 seconds total
-Improvement: 95%+ faster
-```
-
-**Root Causes:**
-
-1. **No Batch Update Operation (80% likely)**
-   - Each update is separate API call
-   - Each call: parse request + validate + update + persist
-   - No atomicity guarantee
-
-2. **Network Round-Trip Latency (15% likely)**
-   - Each call adds latency
-   - If client/server not co-located: 100-200ms per call
-   - Compounds with update operations
-
-3. **Validation on Each Update (5% likely)**
-   - Full workflow validation on each property change
-   - Could be optimized to field-level validation
-
-**Solution:**
-```typescript
-// Proposed Batch Update Operation
-interface BatchUpdateRequest {
-  workflowId: string;
-  operations: [
-    { type: 'updateNode', nodeId: string, properties: object },
-    { type: 'updateConnection', from: string, to: string, config: object },
-    { type: 'updateSettings', settings: object }
-  ];
-  validateFull: boolean; // Full or incremental validation
-}
-
-// Returns: Updated workflow with all changes applied atomically
-```
-
-### 6.2 Read-After-Write Pattern
-
-**Pattern:** `n8n_update_partial_workflow → n8n_get_workflow`
-- **Occurrences:** 19,876
-- **Avg Duration:** 96.6 seconds
-- **Pattern:** Users verify state after update
-
-**Root Causes:**
-
-1. **Updates Don't Return State (70% likely)**
-   - Update operation returns success/failure
-   - Doesn't return updated workflow state
-   - Forces clients to fetch separately
-
-2. **Verification Uncertainty (20% likely)**
-   - Users unsure if update succeeded completely
-   - Fetch to double-check
-   - Especially with complex multi-node updates
-
-3. **Change Tracking Needed (10% likely)**
-   - Users want to see what changed
-   - Need diff/changelog
-   - Requires full state retrieval
-
-**Solution:**
-```typescript
-// Update response should include:
-{
-  success: true,
-  workflow: { /* full updated workflow */ },
-  changes: {
-    updated_fields: ['nodes[0].name', 'settings.timezone'],
-    added_connections: [{ from: 'node1', to: 'node2' }],
-    removed_nodes: []
-  }
-}
-```
-
-### 6.3 Search Inefficiency Pattern
-
-**Pattern:** `search_nodes → search_nodes`
-- **Occurrences:** 68,056
-- **Avg Duration:** 11.2 seconds
-- **Slow Transitions:** 11,544 (17%)
-
-**Root Causes:**
-
-1. **Poor Ranking (60% likely)**
-   - Users search for "http", get results in wrong order
-   - "HTTP Request" node not in top 3 results
-   - Users refine search
-
-2. **Query Term Mismatch (25% likely)**
-   - Users search "webhook trigger"
-   - System searches for exact phrase
-   - Returns 0 results; users try "webhook" alone
-
-3. **Incomplete Result Matching (15% likely)**
-   - Synonym support missing
-   - Category/tag matching weak
-   - Users don't know official node names
-
-**Solution:**
-```
-Analyze top 50 repeated search sequences:
-- "http" → "http request" → "HTTP Request"
-  Action: Rank "HTTP Request" in top 3 for "http" search
-
-- "schedule" → "schedule trigger" → "cron"
-  Action: Tag scheduler nodes with "cron", "schedule trigger" synonyms
-
-- "webhook" → "webhook trigger" → "HTTP Trigger"
-  Action: Improve documentation linking webhook triggers
-```
-
----
-
-## 7. Validation Accuracy Issues
-
-### 7.1 `validate_workflow` - 5.50% Failure Rate
-
-**Root Causes:**
-
-1. **Incomplete Validation Rules (45%)**
-   - Validator doesn't check all requirements
-   - Missing rules for specific node combinations
-   - Circular dependency detection missing
-
-2. **Schema Version Mismatches (30%)**
-   - Validator schema != actual node schema
-   - Happens after node updates
-   - Validator not updated simultaneously
-
-3. **Performance Timeouts (15%)**
-   - Very large workflows (100+ nodes)
-   - Validation takes >30 seconds
-   - Timeout triggered
-
-4. **Type System Gaps (10%)**
-   - Type checking incomplete
-   - Coercion not working correctly
-   - Related to TypeError issues
-
-### 7.2 `validate_node_operation` - 6.42% Failure Rate
-
-**Root Causes (Estimated):**
-
-1. **Missing Operation Definitions (40%)**
-   - New operations not in validator
-   - Rare operations not covered
-   - Custom operations not supported
-
-2. **Property Dependency Gaps (30%)**
-   - Conditional properties not understood
-   - "If X=Y, then Z is required" rules missing
-   - Visibility logic incomplete
-
-3. **Type Validation Failures (20%)**
-   - Expected type doesn't match provided type
-   - No implicit type coercion
-   - Complex type definitions not validated
-
-4. **Edge Cases (10%)**
-   - Boundary values
-   - Special characters in properties
-   - Maximum length violations
-
----
-
-## 8. Systemic Issues Identified
-
-### 8.1 Validation Error Message Quality
-
-**Current State:**
-```
-❌ "Validation failed"
-❌ "Invalid workflow configuration"
-❌ "Node configuration error"
-```
-
-**What Users Need:**
-```
-✅ "Workflow missing required start trigger node. Add a trigger (Webhook, Schedule, or Manual Trigger)"
-✅ "HTTP Request node 'call_api' missing required URL property"
-✅ "Cannot connect output from 'set_values' (type: string) to 'http_request' input (expects: object)"
-```
-
-**Impact:** Generic errors prevent both users and AI agents from self-correcting
-
-### 8.2 Type System Gaps
-
-**Current System:**
-- JSONB properties in database (no type enforcement)
-- Application-level validation (catches errors late)
-- Limited type definitions for properties
-
-**Gaps:**
-1. No strict schema validation during ingestion
-2. Type coercion not automatic
-3. Complex type definitions (unions, intersections) not supported
-
-### 8.3 Test Data Contamination
-
-**Problem:** 4,700+ errors from placeholder node names
-- Node0-Node19: Generic test nodes
-- [KEY], ______, _______: Incomplete configurations
-- These create noise in real error metrics
-
-**Solution:**
-1. Flag test vs. production data at ingestion
-2. Separate test telemetry database
-3. Filter test data from production analysis
-
----
-
-## 9. Tool Reliability Correlation Matrix
-
-**High Reliability Cluster (99%+ success):**
-- n8n_list_executions (100%)
-- n8n_get_workflow (99.94%)
-- n8n_get_execution (99.90%)
-- search_nodes (99.89%)
-
-**Medium Reliability Cluster (95-99% success):**
-- get_node_essentials (96.19%)
-- n8n_create_workflow (96.35%)
-- get_node_documentation (95.87%)
-- validate_workflow (94.50%)
-
-**Problematic Cluster (<95% success):**
-- get_node_info (88.28%) ← CRITICAL
-- validate_node_operation (93.58%)
-
-**Pattern:** Information retrieval tools have lower success than state manipulation tools
-
-**Hypothesis:** Read operations affected by:
-- Stale caches
-- Missing data
-- Encoding issues
-- Network timeouts
-
----
-
-## 10. Recommendations by Root Cause
-
-### Validation Error Improvements (Target: 50% reduction)
-
-1. **Specific Error Messages** (+25% reduction)
-   - Map 39% workflow errors → specific structural requirements
-   - "Missing start trigger" vs. "validation failed"
-
-2. **Test Data Isolation** (+15% reduction)
-   - Remove 4,700+ errors from placeholder nodes
-   - Separate test telemetry pipeline
-
-3. **Type System Strictness** (+10% reduction)
-   - Implement schema validation on ingestion
-   - Prevent type mismatches at source
-
-### Tool Reliability Improvements (Target: 10% reduction overall)
-
-1. **get_node_info Reliability** (-1,200 errors potential)
-   - Add retry logic
-   - Implement read cache
-   - Fallback to essentials
-
-2. **Workflow Validation** (-500 errors potential)
-   - Improve validation logic
-   - Add missing edge case handling
-   - Optimize performance
-
-3. **Node Operation Validation** (-360 errors potential)
-   - Complete operation definitions
-   - Implement property dependency logic
-   - Add type coercion
-
-### Performance Improvements (Target: 90% latency reduction)
-
-1. **Batch Update Operation**
-   - Reduce 96,003 sequential updates from 55.2s to <5s each
-   - Potential: 18-minute reduction per workflow construction
-
-2. **Return Updated State**
-   - Eliminate 19,876 redundant get_workflow calls
-   - Reduce round trips by 40%
-
-3. **Search Ranking**
-   - Reduce 68,056 sequential searches
-   - Improve hit rate on first search
-
----
-
-## Conclusion
-
-The n8n-MCP system exhibits:
-
-1. **Strong Infrastructure** (99%+ reliability for core operations)
-2. **Weak Information Retrieval** (`get_node_info` at 88%)
-3. **Poor User Feedback** (generic error messages)
-4. **Validation Gaps** (39% of errors unspecified)
-5. **Performance Bottlenecks** (sequential operations at 55+ seconds)
-
-Each issue has clear root causes and actionable solutions. Implementing Priority 1 recommendations would address 80% of user-facing problems and significantly improve AI agent success rates.
-
----
-
-**Report Prepared By:** AI Telemetry Analyst
-**Technical Depth:** Deep Dive Level
-**Audience:** Engineering Team / Architecture Review
-**Date:** November 8, 2025

VALIDATION_ANALYSIS_REPORT.md

@@ -1,683 +0,0 @@
-# N8N-MCP Telemetry Analysis: Validation Failures as System Feedback
-
-**Analysis Date:** November 8, 2025
-**Data Period:** September 26 - November 8, 2025 (90 days)
-**Report Type:** Comprehensive Validation Failure Root Cause Analysis
-
----
-
-## Executive Summary
-
-Validation failures in n8n-mcp are NOT system failures—they are the system working exactly as designed, catching configuration errors before deployment. However, the high volume (29,218 validation events across 9,021 users) reveals significant **documentation and guidance gaps** that prevent AI agents from configuring nodes correctly on the first attempt.
-
-### Critical Findings:
-
-1. **100% Retry Success Rate**: When AI agents encounter validation errors, they successfully correct and deploy workflows same-day 100% of the time—proving validation feedback is effective and agents learn quickly.
-
-2. **Top 3 Problematic Areas** (accounting for 75% of errors):
-   - Workflow structure issues (undefined node IDs/names, connection errors): 33.2%
-   - Webhook/trigger configuration: 6.7%
-   - Required field documentation: 7.7%
-
-3. **Tool Usage Insight**: Agents using documentation tools BEFORE attempting configuration have slightly HIGHER error rates (12.6% vs 10.8%), suggesting documentation alone is insufficient—agents need better guidance integrated into tool responses.
-
-4. **Search Query Patterns**: Most common pre-failure searches are generic ("webhook", "http request", "openai") rather than specific node configuration searches, indicating agents are searching for node existence rather than configuration details.
-
-5. **Node-Specific Crisis Points**:
-   - **Webhook/Webhook Trigger**: 127 combined failures (47 unique users)
-   - **AI Agent**: 36 failures (20 users) - missing AI model connections
-   - **Slack variants**: 101 combined failures (7 users)
-   - **Generic nodes** ([KEY], underscores): 275 failures - likely malformed JSON from agents
-
----
-
-## Detailed Analysis
-
-### 1. Node-Specific Difficulty Ranking
-
-The nodes causing the most validation failures reveal where agent guidance is weakest:
-
-| Rank | Node Type | Failures | Users | Primary Error | Impact |
-|------|-----------|----------|-------|---------------|--------|
-| 1 | Webhook (trigger config) | 127 | 40 | responseNode requires `onError: "continueRegularOutput"` | HIGH |
-| 2 | Slack_Notification | 73 | 2 | Required field "Send Message To" empty; Invalid enum "select" | HIGH |
-| 3 | AI_Agent | 36 | 20 | Missing `ai_languageModel` connection | HIGH |
-| 4 | HTTP_Request | 31 | 13 | Missing required fields (varied) | MEDIUM |
-| 5 | OpenAI | 35 | 8 | Misconfigured model/auth/parameters | MEDIUM |
-| 6 | Airtable_Create_Record | 41 | 1 | Required fields for API records | MEDIUM |
-| 7 | Telegram | 27 | 1 | Operation enum mismatch; Missing Chat ID | MEDIUM |
-
-**Key Insight**: The most problematic nodes are trigger/connector nodes and AI/API integrations—these require deep understanding of external API contracts that our documentation may not adequately convey.
-
----
-
-### 2. Top 10 Validation Error Messages (with specific examples)
-
-These are the precise errors agents encounter. Each one represents a documentation opportunity:
-
-| Rank | Error Message | Count | Affected Users | Interpretation |
-|------|---------------|-------|---|---|
-| 1 | "Duplicate node ID: undefined" | 179 | 20 | **CRITICAL**: Agents generating invalid JSON or malformed workflow structures. Likely JSON parsing issues on LLM side. |
-| 2 | "Single-node workflows only valid for webhooks" | 58 | 47 | Agents don't understand webhook-only constraint. Need explicit documentation. |
-| 3 | "responseNode mode requires onError: 'continueRegularOutput'" | 57 | 33 | Webhook-specific configuration rule not obvious. **Error message is helpful but documentation missing context.** |
-| 4 | "Duplicate node name: undefined" | 61 | 6 | Related to #1—structural issues with node definitions. |
-| 5 | "Multi-node workflow has no connections" | 33 | 24 | Agents don't understand workflow connection syntax. **Need examples in documentation.** |
-| 6 | "Workflow contains a cycle (infinite loop)" | 33 | 19 | Agents not visualizing workflow topology before creating. |
-| 7 | "Required property 'Send Message To' cannot be empty" | 25 | 1 | Slack node properties not obvious from schema. |
-| 8 | "AI Agent requires ai_languageModel connection" | 22 | 15 | Missing documentation on AI node dependencies. |
-| 9 | "Node position must be array [x, y]" | 25 | 4 | Position format not specified in node documentation. |
-| 10 | "Invalid value for 'operation'. Must be one of: [list]" | 14 | 1 | Enum values not provided before validation. |
-
----
-
-### 3. Error Categories & Root Causes
-
-Breaking down all 4,898 validation details events into categories reveals the real problems:
-
-```
-Error Category Distribution:
-┌─────────────────────────────────┬───────────┬──────────┐
-│ Category                        │ Count     │ % of All │
-├─────────────────────────────────┼───────────┼──────────┤
-│ Other (workflow structure)       │ 1,268     │ 25.89%   │
-│ Connection/Linking Errors       │ 676       │ 13.80%   │
-│ Missing Required Field          │ 378       │ 7.72%    │
-│ Invalid Field Value/Enum        │ 202       │ 4.12%    │
-│ Error Handler Configuration     │ 148       │ 3.02%    │
-│ Invalid Position                │ 109       │ 2.23%    │
-│ Unknown Node Type               │ 88        │ 1.80%    │
-│ Missing typeVersion             │ 50        │ 1.02%    │
-├─────────────────────────────────┼───────────┼──────────┤
-│ SUBTOTAL (Top Issues)           │ 2,919     │ 59.60%   │
-│ All Other Errors                │ 1,979     │ 40.40%   │
-└─────────────────────────────────┴───────────┴──────────┘
-```
-
-### 3.1 Root Cause Analysis by Category
-
-**[25.89%] Workflow Structure Issues (1,268 errors)**
-- Undefined node IDs/names (likely JSON malformation)
-- Incorrect node position formats
-- Missing required workflow metadata
-- **ROOT CAUSE**: Agents constructing workflow JSON without proper schema understanding. Need better template examples and validation error context.
-
-**[13.80%] Connection/Linking Errors (676 errors)**
-- Multi-node workflows with no connections defined
-- Missing connection syntax in workflow definition
-- Error handler connection misconfigurations
-- **ROOT CAUSE**: Connection format is unintuitive. Sample workflows in documentation critically needed.
-
-**[7.72%] Missing Required Fields (378 errors)**
-- "Send Message To" for Slack
-- "Chat ID" for Telegram
-- "Title" for Google Docs
-- **ROOT CAUSE**: Required fields not clearly marked in `get_node_essentials()` response. Need explicit "REQUIRED" labeling.
-
-**[4.12%] Invalid Field Values/Enums (202 errors)**
-- Invalid "operation" selected
-- Invalid "select" value for choice fields
-- Wrong authentication method type
-- **ROOT CAUSE**: Enum options not provided in advance. Tool should return valid options BEFORE agent attempts configuration.
-
-**[3.02%] Error Handler Configuration (148 errors)**
-- ResponseNode mode setup
-- onError settings for async operations
-- Error output connections in wrong position
-- **ROOT CAUSE**: Error handling is complex; needs dedicated tutorial/examples in documentation.
-
----
-
-### 4. Tool Usage Pattern: Before Validation Failures
-
-This reveals what agents attempt BEFORE hitting errors:
-
-```
-Tools Used Before Failures (within 10 minutes):
-┌─────────────────────────────────────┬──────────┬────────┐
-│ Tool                                │ Count    │ Users  │
-├─────────────────────────────────────┼──────────┼────────┤
-│ search_nodes                        │ 320      │ 113    │ ← Most common
-│ get_node_essentials                 │ 177      │ 73     │ ← Documentation users
-│ validate_workflow                   │ 137      │ 47     │ ← Validation-checking
-│ tools_documentation                 │ 78       │ 67     │ ← Help-seeking
-│ n8n_update_partial_workflow         │ 72       │ 32     │ ← Fixing attempts
-├─────────────────────────────────────┼──────────┼────────┤
-│ INSIGHT: "search_nodes" (320) is    │          │        │
-│ 1.8x more common than              │          │        │
-│ "get_node_essentials" (177)         │          │        │
-└─────────────────────────────────────┴──────────┴────────┘
-```
-
-**Critical Insight**: Agents search for nodes before reading detailed documentation. They're trying to locate a node first, then attempt configuration without sufficient guidance. The search_nodes tool should provide better configuration hints.
-
----
-
-### 5. Search Queries Before Failures
-
-Most common search patterns when agents subsequently fail:
-
-| Query | Count | Users | Interpretation |
-|-------|-------|-------|---|
-| "webhook" | 34 | 16 | Generic search; 3.4min before failure |
-| "http request" | 32 | 20 | Generic search; 4.1min before failure |
-| "openai" | 23 | 7 | Generic search; 3.4min before failure |
-| "slack" | 16 | 9 | Generic search; 6.1min before failure |
-| "gmail" | 12 | 4 | Generic search; 0.1min before failure |
-| "telegram" | 10 | 10 | Generic search; 5.8min before failure |
-
-**Finding**: Searches are too generic. Agents search "webhook" then fail on "responseNode configuration"—they found the node but don't understand its specific requirements. Need **operation-specific search results**.
-
----
-
-### 6. Documentation Usage Impact
-
-Critical finding on effectiveness of reading documentation FIRST:
-
-```
-Documentation Impact Analysis:
-┌──────────────────────────────────┬───────────┬─────────┬──────────┐
-│ Group                            │ Total     │ Errors  │ Success  │
-│                                  │ Users     │ Rate    │ Rate     │
-├──────────────────────────────────┼───────────┼─────────┼──────────┤
-│ Read Documentation FIRST         │ 2,304     │ 12.6%   │ 87.4%    │
-│ Did NOT Read Documentation       │ 673       │ 10.8%   │ 89.2%    │
-└──────────────────────────────────┴───────────┴─────────┴──────────┘
-
-Result: Counter-intuitive!
-- Documentation readers have 1.8% HIGHER error rate
-- BUT they attempt MORE workflows (21,748 vs 3,869)
-- Interpretation: Advanced users read docs and attempt complex workflows
-```
-
-**Critical Implication**: Current documentation doesn't prevent errors. We need **better, more actionable documentation**, not just more documentation. Documentation should have:
-1. Clear required field callouts
-2. Example configurations
-3. Common pitfall warnings
-4. Operation-specific guidance
-
----
-
-### 7. Retry Success & Self-Correction
-
-**Excellent News**: Agents learn from validation errors immediately:
-
-```
-Same-Day Recovery Rate: 100% ✓
-
-Distribution of Successful Corrections:
-- Same day (within hours):         453 user-date pairs (100%)
-- Next day:                        108 user-date pairs (100%)
-- Within 2-3 days:                 67 user-date pairs (100%)
-- Within 4-7 days:                 33 user-date pairs (100%)
-
-Conclusion: ALL users who encounter validation errors subsequently
-           succeed in correcting them. Validation feedback works perfectly.
-           The system is teaching agents what's wrong.
-```
-
-**This validates the premise: Validation is not broken. Guidance is broken.**
-
----
-
-### 8. Property-Level Difficulty Matrix
-
-Which specific node properties cause the most confusion:
-
-**High-Difficulty Properties** (frequently empty/invalid):
-1. **Authentication fields** (universal across nodes)
-   - Missing/invalid credentials
-   - Wrong auth type selected
-
-2. **Operation/Action fields** (conditional requirements)
-   - Invalid enum selection
-   - No documentation of valid values
-
-3. **Connection-dependent fields** (webhook, AI nodes)
-   - Missing model selection (AI Agent)
-   - Missing error handler connection
-
-4. **Positional/structural fields**
-   - Node position array format
-   - Connection syntax
-
-5. **Required-but-optional-looking fields**
-   - "Send Message To" for Slack
-   - "Chat ID" for Telegram
-
-**Common Pattern**: Fields that are:
-- Conditional (visible only if other field = X)
-- Have complex validation (must be array of specific format)
-- Require external knowledge (valid enum values)
-
-...are the most error-prone.
-
----
-
-## Actionable Recommendations
-
-### PRIORITY 1: IMMEDIATE HIGH-IMPACT (Fixes 33% of errors)
-
-#### 1.1 Fix Webhook Configuration Documentation
-**Impact**: 127 failures, 40 unique users
-
-**Action Items**:
-- Create a dedicated "Webhook & Trigger Configuration" guide
-- Explicitly document the `responseNode mode` requires `onError: "continueRegularOutput"` rule
-- Provide before/after examples showing correct vs incorrect configuration
-- Add to `get_node_essentials()` for Webhook nodes: "⚠️ IMPORTANT: If using responseNode, add onError field"
-
-**SQL Query for Verification**:
-```sql
-SELECT
-  properties->>'nodeType' as node_type,
-  properties->'details'->>'message' as error_message,
-  COUNT(*) as count
-FROM telemetry_events
-WHERE event = 'validation_details'
-  AND properties->>'nodeType' IN ('Webhook', 'Webhook_Trigger')
-  AND created_at >= NOW() - INTERVAL '90 days'
-GROUP BY node_type, properties->'details'->>'message'
-ORDER BY count DESC;
-```
-
-**Expected Outcome**: 10-15% reduction in webhook-related failures
-
----
-
-#### 1.2 Fix Node Structure Error Messages
-**Impact**: 179 "Duplicate node ID: undefined" failures
-
-**Action Items**:
-1. When validation fails with "Duplicate node ID: undefined", provide:
-   - Exact line number in workflow JSON where the error occurs
-   - Example of correct node ID format
-   - Suggestion: "Did you forget the 'id' field in node definition?"
-
-2. Enhance `n8n_validate_workflow` to detect structural issues BEFORE attempting validation:
-   - Check all nodes have `id` field
-   - Check all nodes have `type` field
-   - Provide detailed structural report
-
-**Code Location**: `/src/services/workflow-validator.ts`
-
-**Expected Outcome**: 50-60% reduction in "undefined" node errors
-
----
-
-#### 1.3 Enhance Tool Responses with Required Field Callouts
-**Impact**: 378 "Missing required field" failures
-
-**Action Items**:
-1. Modify `get_node_essentials()` output to clearly mark REQUIRED fields:
-   ```
-   Before:
-   "properties": { "operation": {...} }
-
-   After:
-   "properties": {
-     "operation": {..., "required": true, "required_label": "⚠️ REQUIRED"}
-   }
-   ```
-
-2. In `validate_node_operation()` response, explicitly list:
-   - Which fields are required for this specific operation
-   - Which fields are conditional (depend on other field values)
-   - Example values for each field
-
-3. Add to tool documentation:
-   ```
-   get_node_essentials returns only essential properties.
-   For complete property list including all conditionals, use get_node_info().
-   ```
-
-**Code Location**: `/src/services/property-filter.ts`
-
-**Expected Outcome**: 60-70% reduction in "missing required field" errors
-
----
-
-### PRIORITY 2: MEDIUM-IMPACT (Fixes 25% of remaining errors)
-
-#### 2.1 Fix Workflow Connection Documentation
-**Impact**: 676 connection/linking errors, 429 unique node types
-
-**Action Items**:
-1. Create "Workflow Connections Explained" guide with:
-   - Diagram showing connection syntax
-   - Step-by-step connection building examples
-   - Common connection patterns (sequential, branching, error handling)
-
-2. Enhance error message for "Multi-node workflow has no connections":
-   ```
-   Before:
-   "Multi-node workflow has no connections.
-    Nodes must be connected to create a workflow..."
-
-   After:
-   "Multi-node workflow has no connections.
-    You created nodes: [list]
-    Add connections to link them. Example:
-    connections: {
-      'Node 1': { 'main': [[{ 'node': 'Node 2', 'type': 'main', 'index': 0 }]] }
-    }
-    For visual guide, see: [link to guide]"
-   ```
-
-3. Add sample workflow templates showing proper connections
-   - Simple: Trigger → Action
-   - Branching: If node splitting to multiple paths
-   - Error handling: Node with error catch
-
-**Code Location**: `/src/services/workflow-validator.ts` (error messages)
-
-**Expected Outcome**: 40-50% reduction in connection errors
-
----
-
-#### 2.2 Provide Valid Enum Values in Tool Responses
-**Impact**: 202 "Invalid value" errors for enum fields
-
-**Action Items**:
-1. Modify `validate_node_operation()` to return:
-   ```json
-   {
-     "success": false,
-     "errors": [{
-       "field": "operation",
-       "message": "Invalid value 'sendMsg' for operation",
-       "valid_options": [
-         "deleteMessage",
-         "editMessageText",
-         "sendMessage"
-       ],
-       "documentation": "https://..."
-     }]
-   }
-   ```
-
-2. In `get_node_essentials()`, for enum/choice fields, include:
-   ```json
-   "operation": {
-     "type": "choice",
-     "options": [
-       {"label": "Send Message", "value": "sendMessage"},
-       {"label": "Delete Message", "value": "deleteMessage"}
-     ]
-   }
-   ```
-
-**Code Location**: `/src/services/enhanced-config-validator.ts`
-
-**Expected Outcome**: 80%+ reduction in enum selection errors
-
----
-
-#### 2.3 Fix AI Agent Node Documentation
-**Impact**: 36 AI Agent failures, 20 unique users
-
-**Action Items**:
-1. Add prominent warning in `get_node_essentials()` for AI Agent:
-   ```
-   "⚠️ CRITICAL: AI Agent requires a language model connection.
-    You must add one of: OpenAI Chat Model, Anthropic Chat Model,
-    Google Gemini, or other LLM nodes before this node.
-    See example: [link]"
-   ```
-
-2. Create "Building AI Workflows" guide showing:
-   - Required model node placement
-   - Connection syntax for AI models
-   - Common model configuration
-
-3. Add validation check: AI Agent node must have incoming connection from an LLM node
-
-**Code Location**: `/src/services/node-specific-validators.ts`
-
-**Expected Outcome**: 80-90% reduction in AI Agent failures
-
----
-
-### PRIORITY 3: MEDIUM-IMPACT (Fixes remaining issues)
-
-#### 3.1 Improve Search Results Quality
-**Impact**: 320+ tool uses before failures; search too generic
-
-**Action Items**:
-1. When `search_nodes` finds a node, include:
-   - Top 3 most common operations for that node
-   - Most critical required fields
-   - Link to configuration guide
-   - Example workflow snippet
-
-2. Add operation-specific search:
-   ```
-   search_nodes("webhook trigger with validation")
-   → Returns Webhook node with:
-      - Best operations for your query
-      - Configuration guide for validation
-      - Error handler setup guide
-   ```
-
-**Code Location**: `/src/mcp/tools.ts` (search_nodes definition)
-
-**Expected Outcome**: 20-30% reduction in search-before-failure incidents
-
----
-
-#### 3.2 Enhance Error Handler Documentation
-**Impact**: 148 error handler configuration failures
-
-**Action Items**:
-1. Create dedicated "Error Handling in Workflows" guide:
-   - When to use error handlers
-   - `onError` options explained (continueRegularOutput vs continueErrorOutput)
-   - Connection positioning rules
-   - Complete working example
-
-2. Add validation error with visual explanation:
-   ```
-   Error: "Node X has onError: continueErrorOutput but no error
-           connections in main[1]"
-
-   Solution: Add error handler or change onError to 'continueRegularOutput'
-
-   INCORRECT:         CORRECT:
-   main[0]: [Node Y]  main[0]: [Node Y]
-                      main[1]: [Error Handler]
-   ```
-
-**Code Location**: `/src/services/workflow-validator.ts`
-
-**Expected Outcome**: 70%+ reduction in error handler failures
-
----
-
-#### 3.3 Create "Node Type Corrections" Guide
-**Impact**: 88 "Unknown node type" errors
-
-**Action Items**:
-1. Add helpful suggestions when unknown node type detected:
-   ```
-   Unknown node type: "nodes-base.googleDocsTool"
-
-   Did you mean one of these?
-   - nodes-base.googleDocs (87% match)
-   - nodes-base.googleSheets (72% match)
-
-   Node types must include package prefix: nodes-base.nodeName
-   ```
-
-2. Build fuzzy matcher for common node type mistakes
-
-**Code Location**: `/src/services/workflow-validator.ts`
-
-**Expected Outcome**: 70%+ reduction in unknown node type errors
-
----
-
-## Implementation Roadmap
-
-### Phase 1 (Weeks 1-2): Quick Wins
-- [ ] Fix Webhook documentation and error messages (1.1)
-- [ ] Enhance required field callouts in tools (1.3)
-- [ ] Improve error structure validation messages (1.2)
-
-**Expected Impact**: 25-30% reduction in validation failures
-
-### Phase 2 (Weeks 3-4): Documentation
-- [ ] Create "Workflow Connections" guide (2.1)
-- [ ] Create "Error Handling" guide (3.2)
-- [ ] Add enum value suggestions to tool responses (2.2)
-
-**Expected Impact**: Additional 15-20% reduction
-
-### Phase 3 (Weeks 5-6): Advanced Features
-- [ ] Enhance search results (3.1)
-- [ ] Add AI Agent node validation (2.3)
-- [ ] Create node type correction suggestions (3.3)
-
-**Expected Impact**: Additional 10-15% reduction
-
-### Target: 50-65% reduction in validation failures through better guidance
-
----
-
-## Measurement & Validation
-
-### KPIs to Track Post-Implementation
-
-1. **Validation Failure Rate**: Currently 12.6% for documentation users
-   - Target: 6-7% (50% reduction)
-
-2. **First-Attempt Success Rate**: Currently unknown, but retry success is 100%
-   - Target: 85%+ (measure in new telemetry)
-
-3. **Time to Valid Configuration**: Currently unknown
-   - Target: Measure and reduce by 30%
-
-4. **Tool Usage Before Failures**: Currently search_nodes dominates
-   - Target: Measure shift toward get_node_essentials/info
-
-5. **Specific Node Improvements**:
-   - Webhook: 127 → <30 failures (76% reduction)
-   - AI Agent: 36 → <5 failures (86% reduction)
-   - Slack: 101 → <20 failures (80% reduction)
-
-### SQL to Track Progress
-
-```sql
--- Monitor validation failure trends by node type
-SELECT
-  DATE(created_at) as date,
-  properties->>'nodeType' as node_type,
-  COUNT(*) as failure_count
-FROM telemetry_events
-WHERE event = 'validation_details'
-GROUP BY DATE(created_at), properties->>'nodeType'
-ORDER BY date DESC, failure_count DESC;
-
--- Monitor recovery rates
-WITH failures_then_success AS (
-  SELECT
-    user_id,
-    DATE(created_at) as failure_date,
-    COUNT(*) as failures,
-    SUM(CASE WHEN LEAD(event) OVER (PARTITION BY user_id ORDER BY created_at) = 'workflow_created' THEN 1 ELSE 0 END) as recovered
-  FROM telemetry_events
-  WHERE event = 'validation_details'
-    AND created_at >= NOW() - INTERVAL '7 days'
-  GROUP BY user_id, DATE(created_at)
-)
-SELECT
-  failure_date,
-  SUM(failures) as total_failures,
-  SUM(recovered) as immediate_recovery,
-  ROUND(100.0 * SUM(recovered) / NULLIF(SUM(failures), 0), 1) as recovery_rate_pct
-FROM failures_then_success
-GROUP BY failure_date
-ORDER BY failure_date DESC;
-```
-
----
-
-## Conclusion
-
-The n8n-mcp validation system is working perfectly—it catches errors and provides feedback that agents learn from instantly. The 29,218 validation events over 90 days are not a symptom of system failure; they're evidence that **the system is successfully preventing bad workflows from being deployed**.
-
-The challenge is not validation; it's **guidance quality**. Agents search for nodes but don't read complete documentation before attempting configuration. Our tools don't provide enough context about required fields, valid values, and connection syntax upfront.
-
-By implementing the recommendations above, focusing on:
-1. Clearer required field identification
-2. Better error messages with actionable solutions
-3. More comprehensive workflow structure documentation
-4. Valid enum values provided in advance
-5. Operation-specific configuration guides
-
-...we can reduce validation failures by 50-65% **without weakening validation**, enabling AI agents to configure workflows correctly on the first attempt while maintaining the safety guarantees our validation provides.
-
----
-
-## Appendix A: Complete Error Message Reference
-
-### Top 25 Unique Validation Messages (by frequency)
-
-1. **"Duplicate node ID: 'undefined'"** (179 occurrences)
-   - Root cause: JSON malformation or missing ID field
-   - Solution: Check node structure, ensure all nodes have `id` field
-
-2. **"Duplicate node name: 'undefined'"** (61 occurrences)
-   - Root cause: Missing or undefined node names
-   - Solution: All nodes must have unique non-empty `name` field
-
-3. **"Single-node workflows are only valid for webhook endpoints..."** (58 occurrences)
-   - Root cause: Single-node workflow without webhook
-   - Solution: Add trigger node or use webhook trigger
-
-4. **"responseNode mode requires onError: 'continueRegularOutput'"** (57 occurrences)
-   - Root cause: Webhook configured for response but missing error handling config
-   - Solution: Add `"onError": "continueRegularOutput"` to webhook node
-
-5. **"Workflow contains a cycle (infinite loop)"** (33 occurrences)
-   - Root cause: Circular workflow connections
-   - Solution: Redesign workflow to avoid cycles
-
-6. **"Multi-node workflow has no connections..."** (33 occurrences)
-   - Root cause: Multiple nodes created but not connected
-   - Solution: Add connections array to link nodes
-
-7. **"Required property 'Send Message To' cannot be empty"** (25 occurrences)
-   - Root cause: Slack node missing target channel/user
-   - Solution: Specify either channel or user
-
-8. **"Invalid value for 'select'. Must be one of: channel, user"** (25 occurrences)
-   - Root cause: Wrong enum value for Slack target
-   - Solution: Use either "channel" or "user"
-
-9. **"Node position must be an array with exactly 2 numbers [x, y]"** (25 occurrences)
-   - Root cause: Position not formatted as [x, y] array
-   - Solution: Format as `"position": [100, 200]`
-
-10. **"AI Agent 'AI Agent' requires an ai_languageModel connection..."** (22 occurrences)
-    - Root cause: AI Agent node created without language model
-    - Solution: Add LLM node and connect it
-
-[Additional messages follow same pattern...]
-
----
-
-## Appendix B: Data Quality Notes
-
-- **Data Source**: PostgreSQL Supabase database, `telemetry_events` table
-- **Sample Size**: 29,218 validation_details events from 9,021 unique users
-- **Time Period**: 43 days (Sept 26 - Nov 8, 2025)
-- **Data Quality**: 100% of validation events marked with `errorType: "error"`
-- **Limitations**:
-  - User IDs aggregated for privacy (individual user behavior not exposed)
-  - Workflow content sanitized (no actual code/credentials captured)
-  - Error categorization performed via pattern matching on error messages
-
----
-
-**Report Prepared**: November 8, 2025
-**Next Review Date**: November 22, 2025 (2-week progress check)
-**Responsible Team**: n8n-mcp Development Team

VALIDATION_ANALYSIS_SUMMARY.md

@@ -1,377 +0,0 @@
-# N8N-MCP Validation Analysis: Executive Summary
-
-**Date**: November 8, 2025 | **Period**: 90 days (Sept 26 - Nov 8) | **Data Quality**: ✓ Verified
-
----
-
-## One-Page Executive Summary
-
-### The Core Finding
-**Validation failures are NOT broken—they're evidence the system is working correctly.** 29,218 validation events prevented bad configurations from deploying to production. However, these events reveal **critical documentation and guidance gaps** that cause AI agents to misconfigure nodes.
-
----
-
-## Key Metrics at a Glance
-
-```
-VALIDATION HEALTH SCORECARD
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Metric                          Value           Status
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Total Validation Events         29,218          Normal
-Unique Users Affected           9,021           Normal
-First-Attempt Success Rate      ~77%*           ⚠️ Fixable
-Retry Success Rate              100%            ✓ Excellent
-Same-Day Recovery Rate          100%            ✓ Excellent
-Documentation Reader Error Rate 12.6%           ⚠️ High
-Non-Reader Error Rate           10.8%           ✓ Better
-
-* Estimated: 100% same-day retry success on 29,218 failures
-  suggests ~77% first-attempt success (29,218 + 21,748 = 50,966 total)
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
----
-
-## Top 3 Problem Areas (75% of all errors)
-
-### 1. Workflow Structure Issues (33.2%)
-**Symptoms**: "Duplicate node ID: undefined", malformed JSON, missing connections
-
-**Impact**: 1,268 errors across 791 unique node types
-
-**Root Cause**: Agents constructing workflow JSON without proper schema understanding
-
-**Quick Fix**: Better error messages pointing to exact location of structural issues
-
----
-
-### 2. Webhook & Trigger Configuration (6.7%)
-**Symptoms**: "responseNode requires onError", single-node workflows, connection rules
-
-**Impact**: 127 failures (47 users) specifically on webhook/trigger setup
-
-**Root Cause**: Complex configuration rules not obvious from documentation
-
-**Quick Fix**: Dedicated webhook guide + inline error messages with examples
-
----
-
-### 3. Required Fields (7.7%)
-**Symptoms**: "Required property X cannot be empty", missing Slack channel, missing AI model
-
-**Impact**: 378 errors; Agents don't know which fields are required
-
-**Root Cause**: Tool responses don't clearly mark required vs optional fields
-
-**Quick Fix**: Add required field indicators to `get_node_essentials()` output
-
----
-
-## Problem Nodes (Top 7)
-
-| Node | Failures | Users | Primary Issue |
-|------|----------|-------|---------------|
-| Webhook/Trigger | 127 | 40 | Error handler configuration rules |
-| Slack Notification | 73 | 2 | Missing "Send Message To" field |
-| AI Agent | 36 | 20 | Missing language model connection |
-| HTTP Request | 31 | 13 | Missing required parameters |
-| OpenAI | 35 | 8 | Authentication/model configuration |
-| Airtable | 41 | 1 | Required record fields |
-| Telegram | 27 | 1 | Operation enum selection |
-
-**Pattern**: Trigger/connector nodes and AI integrations are hardest to configure
-
----
-
-## Error Category Breakdown
-
-```
-What Goes Wrong (root cause distribution):
-┌────────────────────────────────────────┐
-│ Workflow structure (undefined IDs)  26% │ ■■■■■■■■■■■■
-│ Connection/linking errors          14% │ ■■■■■■
-│ Missing required fields             8% │ ■■■■
-│ Invalid enum values                 4% │ ■■
-│ Error handler configuration         3% │ ■
-│ Invalid position format             2% │ ■
-│ Unknown node types                  2% │ ■
-│ Missing typeVersion                 1% │
-│ All others                         40% │ ■■■■■■■■■■■■■■■■■■
-└────────────────────────────────────────┘
-```
-
----
-
-## Agent Behavior: Search Patterns
-
-**Agents search for nodes generically, then fail on specific configuration:**
-
-```
-Most Searched Terms (before failures):
-  "webhook" ................. 34x (failed on: responseNode config)
-  "http request" ............ 32x (failed on: missing required fields)
-  "openai" .................. 23x (failed on: model selection)
-  "slack" ................... 16x (failed on: missing channel/user)
-```
-
-**Insight**: Generic node searches don't help with configuration specifics. Agents need targeted guidance on each node's trickiest fields.
-
----
-
-## The Self-Correction Story (VERY POSITIVE)
-
-When agents get validation errors, they FIX THEM 100% of the time (same day):
-
-```
-Validation Error → Agent Action → Outcome
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Error event     → Uses feedback → Success
-(4,898 events)     (reads error)   (100%)
-
-Distribution of Corrections:
-  Within same hour ........ 453 cases (100% succeeded)
-  Within next day ......... 108 cases (100% succeeded)
-  Within 2-3 days ......... 67 cases (100% succeeded)
-  Within 4-7 days ......... 33 cases (100% succeeded)
-```
-
-**This proves validation messages are effective. Agents learn instantly. We just need BETTER messages.**
-
----
-
-## Documentation Impact (Surprising Finding)
-
-```
-Paradox: Documentation Readers Have HIGHER Error Rate!
-
-Documentation Readers:   2,304 users | 12.6% error rate | 87.4% success
-Non-Documentation:       673 users   | 10.8% error rate | 89.2% success
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Explanation: Doc readers attempt COMPLEX workflows (6.8x more attempts)
-            Simple workflows have higher natural success rate
-
-Action Item: Documentation should PREVENT errors, not just explain them
-            Need: Better structure, examples, required field callouts
-```
-
----
-
-## Critical Success Factors Discovered
-
-### What Works Well
-✓ Validation catches errors effectively
-✓ Error messages lead to quick fixes (100% same-day recovery)
-✓ Agents attempt workflows again after failures (persistence)
-✓ System prevents bad deployments
-
-### What Needs Improvement
-✗ Required fields not clearly marked in tool responses
-✗ Enum values not provided before validation
-✗ Workflow structure documentation lacks examples
-✗ Connection syntax unintuitive and not well-documented
-✗ Error messages could be more specific
-
----
-
-## Top 5 Recommendations (Priority Order)
-
-### 1. FIX WEBHOOK DOCUMENTATION (25-day impact)
-**Effort**: 1-2 days | **Impact**: 127 failures resolved | **ROI**: HIGH
-
-Create dedicated "Webhook Configuration Guide" explaining:
-- responseNode mode setup
-- onError requirements
-- Error handler connections
-- Working examples
-
----
-
-### 2. ENHANCE TOOL RESPONSES (2-3 days impact)
-**Effort**: 2-3 days | **Impact**: 378 failures resolved | **ROI**: HIGH
-
-Modify tools to output:
-```
-For get_node_essentials():
-  - Mark required fields with ⚠️ REQUIRED
-  - Include valid enum options
-  - Link to configuration guide
-
-For validate_node_operation():
-  - Show valid field values
-  - Suggest fixes for each error
-  - Provide contextual examples
-```
-
----
-
-### 3. IMPROVE WORKFLOW STRUCTURE ERRORS (5-7 days impact)
-**Effort**: 3-4 days | **Impact**: 1,268 errors resolved | **ROI**: HIGH
-
-- Better validation error messages pointing to exact issues
-- Suggest corrections ("Missing 'id' field in node definition")
-- Provide JSON structure examples
-
----
-
-### 4. CREATE CONNECTION DOCUMENTATION (3-4 days impact)
-**Effort**: 2-3 days | **Impact**: 676 errors resolved | **ROI**: MEDIUM
-
-Create "How to Connect Nodes" guide:
-- Connection syntax explained
-- Step-by-step workflow building
-- Common patterns (sequential, branching, error handling)
-- Visual diagrams
-
----
-
-### 5. ADD ERROR HANDLER GUIDE (2-3 days impact)
-**Effort**: 1-2 days | **Impact**: 148 errors resolved | **ROI**: MEDIUM
-
-Document error handling clearly:
-- When/how to use error handlers
-- onError options explained
-- Configuration examples
-- Common pitfalls
-
----
-
-## Implementation Impact Projection
-
-```
-Current State (Week 0):
-  - 29,218 validation failures (90-day sample)
-  - 12.6% error rate (documentation users)
-  - ~77% first-attempt success rate
-
-After Recommendations (Weeks 4-6):
-  ✓ Webhook issues: 127 → 30 (-76%)
-  ✓ Structure errors: 1,268 → 500 (-61%)
-  ✓ Required fields: 378 → 120 (-68%)
-  ✓ Connection issues: 676 → 340 (-50%)
-  ✓ Error handlers: 148 → 40 (-73%)
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Total Projected Impact: 50-65% reduction in validation failures
-  New error rate target: 6-7% (50% reduction)
-  First-attempt success: 77% → 85%+
-```
-
----
-
-## Files for Reference
-
-Full analysis with detailed recommendations:
-- **Main Report**: `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/VALIDATION_ANALYSIS_REPORT.md`
-- **This Summary**: `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/VALIDATION_ANALYSIS_SUMMARY.md`
-
-### SQL Queries Used (for reproducibility)
-
-#### Query 1: Overview
-```sql
-SELECT COUNT(*), COUNT(DISTINCT user_id), MIN(created_at), MAX(created_at)
-FROM telemetry_events
-WHERE event = 'workflow_validation_failed' AND created_at >= NOW() - INTERVAL '90 days';
-```
-
-#### Query 2: Top Error Messages
-```sql
-SELECT
-  properties->'details'->>'message' as error_message,
-  COUNT(*) as count,
-  COUNT(DISTINCT user_id) as affected_users
-FROM telemetry_events
-WHERE event = 'validation_details' AND created_at >= NOW() - INTERVAL '90 days'
-GROUP BY properties->'details'->>'message'
-ORDER BY count DESC
-LIMIT 25;
-```
-
-#### Query 3: Node-Specific Failures
-```sql
-SELECT
-  properties->>'nodeType' as node_type,
-  COUNT(*) as total_failures,
-  COUNT(DISTINCT user_id) as affected_users
-FROM telemetry_events
-WHERE event = 'validation_details' AND created_at >= NOW() - INTERVAL '90 days'
-GROUP BY properties->>'nodeType'
-ORDER BY total_failures DESC
-LIMIT 20;
-```
-
-#### Query 4: Retry Success Rate
-```sql
-WITH failures AS (
-  SELECT user_id, DATE(created_at) as failure_date
-  FROM telemetry_events WHERE event = 'validation_details'
-)
-SELECT
-  COUNT(DISTINCT f.user_id) as users_with_failures,
-  COUNT(DISTINCT w.user_id) as users_with_recovery_same_day,
-  ROUND(100.0 * COUNT(DISTINCT w.user_id) / COUNT(DISTINCT f.user_id), 1) as recovery_rate_pct
-FROM failures f
-LEFT JOIN telemetry_events w ON w.user_id = f.user_id
-  AND w.event = 'workflow_created'
-  AND DATE(w.created_at) = f.failure_date;
-```
-
-#### Query 5: Tool Usage Before Failures
-```sql
-WITH failures AS (
-  SELECT DISTINCT user_id, created_at FROM telemetry_events
-  WHERE event = 'validation_details' AND created_at >= NOW() - INTERVAL '90 days'
-)
-SELECT
-  te.properties->>'tool' as tool,
-  COUNT(*) as count_before_failure
-FROM telemetry_events te
-INNER JOIN failures f ON te.user_id = f.user_id
-  AND te.created_at < f.created_at AND te.created_at >= f.created_at - INTERVAL '10 minutes'
-WHERE te.event = 'tool_used'
-GROUP BY te.properties->>'tool'
-ORDER BY count DESC;
-```
-
----
-
-## Next Steps
-
-1. **Review this summary** with product team (30 min)
-2. **Prioritize recommendations** based on team capacity (30 min)
-3. **Assign work** for Priority 1 items (1-2 days effort)
-4. **Set up KPI tracking** for post-implementation measurement
-5. **Plan review cycle** for Nov 22 (2-week progress check)
-
----
-
-## Questions This Analysis Answers
-
-✓ Why do AI agents have so many validation failures?
-→ Documentation gaps + unclear required field marking + missing examples
-
-✓ Is validation working?
-→ YES, perfectly. 100% error recovery rate proves validation provides good feedback
-
-✓ Which nodes are hardest to configure?
-→ Webhooks (33), Slack (73), AI Agent (36), HTTP Request (31)
-
-✓ Do agents learn from validation errors?
-→ YES, 100% same-day recovery for all 29,218 failures
-
-✓ Does reading documentation help?
-→ Counterintuitively, it correlates with HIGHER error rates (but only because doc readers attempt complex workflows)
-
-✓ What's the single biggest source of errors?
-→ Workflow structure/JSON malformation (1,268 errors, 26% of total)
-
-✓ Can we reduce validation failures without weakening validation?
-→ YES, 50-65% reduction possible through documentation and guidance improvements alone
-
----
-
-**Report Status**: ✓ Complete | **Data Verified**: ✓ Yes | **Recommendations**: ✓ 5 Priority Items Identified
-
-**Prepared by**: N8N-MCP Telemetry Analysis
-**Date**: November 8, 2025
-**Confidence Level**: High (comprehensive 90-day dataset, 9,000+ users, 29,000+ events)

_config.yml

@@ -1,41 +0,0 @@
-# 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

@@ -1,53 +0,0 @@
-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

@@ -1,232 +0,0 @@
-#!/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.buildkit.yml

@@ -20,19 +20,19 @@ services:
     image: n8n-mcp:latest
     container_name: n8n-mcp
     ports:
-      - "${PORT:-3000}:${PORT:-3000}"
+      - "3000:3000"
     environment:
       - MCP_MODE=${MCP_MODE:-http}
       - AUTH_TOKEN=${AUTH_TOKEN}
       - NODE_ENV=${NODE_ENV:-production}
       - LOG_LEVEL=${LOG_LEVEL:-info}
-      - PORT=${PORT:-3000}
+      - PORT=3000
     volumes:
       # Mount data directory for persistence
       - ./data:/app/data
     restart: unless-stopped
     healthcheck:
-      test: ["CMD", "sh", "-c", "curl -f http://localhost:$${PORT:-3000}/health"]
+      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
       interval: 30s
       timeout: 10s
       retries: 3

docker-compose.extract.yml

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

docker-compose.n8n.yml

@@ -1,74 +0,0 @@
-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}:${MCP_PORT:-3000}"
-    environment:
-      - NODE_ENV=production
-      - N8N_MODE=true
-      - MCP_MODE=http
-      - PORT=${MCP_PORT:-3000}
-      - 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", "sh", "-c", "curl -f http://localhost:$${MCP_PORT:-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

@@ -0,0 +1,56 @@
+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

@@ -1,24 +0,0 @@
-# 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,11 +23,7 @@ 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}
@@ -41,7 +37,7 @@ services:
     
     # Port mapping
     ports:
-      - "${PORT:-3000}:${PORT:-3000}"
+      - "${PORT:-3000}:3000"
     
     # Resource limits
     deploy:
@@ -53,7 +49,7 @@ services:
     
     # Health check
     healthcheck:
-      test: ["CMD", "sh", "-c", "curl -f http://127.0.0.1:$${PORT:-3000}/health"]
+      test: ["CMD", "curl", "-f", "http://127.0.0.1:3000/health"]
       interval: 30s
       timeout: 10s
       retries: 3

docker/README.md

@@ -1,87 +0,0 @@
-# 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,166 +1,55 @@
 #!/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
-    log_message "ERROR: AUTH_TOKEN or AUTH_TOKEN_FILE is required for HTTP mode" >&2
+    echo "ERROR: AUTH_TOKEN or AUTH_TOKEN_FILE is required for HTTP mode"
     exit 1
 fi
 
 # Validate AUTH_TOKEN_FILE if provided
 if [ -n "$AUTH_TOKEN_FILE" ] && [ ! -f "$AUTH_TOKEN_FILE" ]; then
-    log_message "ERROR: AUTH_TOKEN_FILE specified but file not found: $AUTH_TOKEN_FILE" >&2
+    echo "ERROR: AUTH_TOKEN_FILE specified but file not found: $AUTH_TOKEN_FILE"
     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 "$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
+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"
                 exit 1
             }
         fi
-    fi
+    ) 200>/app/data/.db.lock
 fi
 
 # Fix permissions if running as root (for development)
 if [ "$(id -u)" = "0" ]; then
-    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
+    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 "$*"
 fi
 
-# 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 "$@"
+# 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
 fi
 
-# 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
+# Execute the main command in background
+# In stdio mode, use the wrapper for clean output
 if [ "$MCP_MODE" = "stdio" ]; then
     # Debug: Log to stderr to check if wrapper exists
     if [ "$DEBUG_DOCKER" = "true" ]; then
@@ -170,7 +59,6 @@ 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
@@ -178,10 +66,5 @@ if [ "$MCP_MODE" = "stdio" ]; then
     fi
 else
     # HTTP mode or other
-    if [ $# -eq 0 ]; then
-        # No arguments provided, use default
-        exec node /app/dist/mcp/index.js
-    else
-        exec "$@"
-    fi
+    exec "$@"
 fi

docker/n8n-mcp

@@ -1,45 +0,0 @@
-#!/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

@@ -1,192 +0,0 @@
-#!/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

@@ -1,384 +0,0 @@
-# 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

@@ -1,185 +0,0 @@
-# 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/CI_TEST_INFRASTRUCTURE.md

@@ -1,111 +0,0 @@
-# CI Test Infrastructure - Known Issues
-
-## Integration Test Failures for External Contributor PRs
-
-### Issue Summary
-
-Integration tests fail for external contributor PRs with "No response from n8n server" errors, despite the code changes being correct. This is a **test infrastructure issue**, not a code quality issue.
-
-### Root Cause
-
-1. **GitHub Actions Security**: External contributor PRs don't get access to repository secrets (`N8N_API_URL`, `N8N_API_KEY`, etc.)
-2. **MSW Mock Server**: Mock Service Worker (MSW) is not properly intercepting HTTP requests in the CI environment
-3. **Test Configuration**: Integration tests expect `http://localhost:3001/mock-api` but the mock server isn't responding
-
-### Evidence
-
-From CI logs (PR #343):
-```
-[CI-DEBUG] Global setup complete, N8N_API_URL: http://localhost:3001/mock-api
-❌ No response from n8n server (repeated 60+ times across 20 tests)
-```
-
-The tests ARE using the correct mock URL, but MSW isn't intercepting the requests.
-
-### Why This Happens
-
-**For External PRs:**
-- GitHub Actions doesn't expose repository secrets for security reasons
-- Prevents malicious PRs from exfiltrating secrets
-- MSW setup runs but requests don't get intercepted in CI
-
-**Test Configuration:**
-- `.env.test` line 19: `N8N_API_URL=http://localhost:3001/mock-api`
-- `.env.test` line 67: `MSW_ENABLED=true`
-- CI workflow line 75-80: Secrets set but empty for external PRs
-
-### Impact
-
-- ✅ **Code Quality**: NOT affected - the actual code changes are correct
-- ✅ **Local Testing**: Works fine - MSW intercepts requests locally
-- ❌ **CI for External PRs**: Integration tests fail (infrastructure issue)
-- ✅ **CI for Internal PRs**: Works fine (has access to secrets)
-
-### Current Workarounds
-
-1. **For Maintainers**: Use `--admin` flag to merge despite failing tests when code is verified correct
-2. **For Contributors**: Run tests locally where MSW works properly
-3. **For CI**: Unit tests pass (don't require n8n API), integration tests fail
-
-### Files Affected
-
-- `tests/integration/setup/integration-setup.ts` - MSW server setup
-- `tests/setup/msw-setup.ts` - MSW configuration
-- `tests/mocks/n8n-api/handlers.ts` - Mock request handlers
-- `.github/workflows/test.yml` - CI configuration
-- `.env.test` - Test environment configuration
-
-### Potential Solutions (Not Implemented)
-
-1. **Separate Unit/Integration Runs**
-   - Run integration tests only for internal PRs
-   - Skip integration tests for external PRs
-   - Rely on unit tests for external PR validation
-
-2. **MSW CI Debugging**
-   - Add extensive logging to MSW setup
-   - Check if MSW server actually starts in CI
-   - Verify request interception is working
-
-3. **Mock Server Process**
-   - Start actual HTTP server in CI instead of MSW
-   - More reliable but adds complexity
-   - Would require test infrastructure refactoring
-
-4. **Public Test Instance**
-   - Use publicly accessible test n8n instance
-   - Exposes test data, security concerns
-   - Would work for external PRs
-
-### Decision
-
-**Status**: Documented but not fixed
-
-**Rationale**:
-- Integration test infrastructure refactoring is separate concern from code quality
-- External PRs are relatively rare compared to internal development
-- Unit tests provide sufficient coverage for most changes
-- Maintainers can verify integration tests locally before merging
-
-### Testing Strategy
-
-**For External Contributor PRs:**
-1. ✅ Unit tests must pass
-2. ✅ TypeScript compilation must pass
-3. ✅ Build must succeed
-4. ⚠️ Integration test failures are expected (infrastructure issue)
-5. ✅ Maintainer verifies locally before merge
-
-**For Internal PRs:**
-1. ✅ All tests must pass (unit + integration)
-2. ✅ Full CI validation
-
-### References
-
-- PR #343: First occurrence of this issue
-- PR #345: Documented the infrastructure issue
-- Issue: External PRs don't get secrets (GitHub Actions security)
-
-### Last Updated
-
-2025-10-21 - Documented as part of PR #345 investigation

docs/CLAUDE_CODE_SETUP.md

@@ -1,169 +0,0 @@
-# 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)
-
-**For Linux, macOS, or Windows (WSL/Git Bash):**
-```bash
-claude mcp add n8n-mcp \
-  -e MCP_MODE=stdio \
-  -e LOG_LEVEL=error \
-  -e DISABLE_CONSOLE_OUTPUT=true \
-  -- npx n8n-mcp
-```
-
-**For native Windows PowerShell:**
-```powershell
-# Note: The backtick ` is PowerShell's line continuation character.
-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)
-
-**For Linux, macOS, or Windows (WSL/Git Bash):**
-```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
-```
-
-**For native Windows PowerShell:**
-```powershell
-# Note: The backtick ` is PowerShell's line continuation character.
-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
-```
-
-## 🎓 Add Claude Skills (Optional)
-
-Supercharge your n8n workflow building with specialized Claude Code skills! The [n8n-skills](https://github.com/czlonkowski/n8n-skills) repository provides 7 complementary skills that teach AI assistants how to build production-ready n8n workflows.
-
-### What You Get
-
-- ✅ **n8n Expression Syntax** - Correct {{}} patterns and common mistakes
-- ✅ **n8n MCP Tools Expert** - How to use n8n-mcp tools effectively
-- ✅ **n8n Workflow Patterns** - 5 proven architectural patterns
-- ✅ **n8n Validation Expert** - Interpret and fix validation errors
-- ✅ **n8n Node Configuration** - Operation-aware setup guidance
-- ✅ **n8n Code JavaScript** - Write effective JavaScript in Code nodes
-- ✅ **n8n Code Python** - Python patterns with limitation awareness
-
-### Installation
-
-**Method 1: Plugin Installation** (Recommended)
-```bash
-/plugin install czlonkowski/n8n-skills
-```
-
-**Method 2: Via Marketplace**
-```bash
-# Add as marketplace, then browse and install
-/plugin marketplace add czlonkowski/n8n-skills
-
-# Then browse available plugins
-/plugin install
-# Select "n8n-mcp-skills" from the list
-```
-
-**Method 3: Manual Installation**
-```bash
-# 1. Clone the repository
-git clone https://github.com/czlonkowski/n8n-skills.git
-
-# 2. Copy skills to your Claude Code skills directory
-cp -r n8n-skills/skills/* ~/.claude/skills/
-
-# 3. Reload Claude Code
-# Skills will activate automatically
-```
-
-For complete installation instructions, configuration options, and usage examples, see the [n8n-skills README](https://github.com/czlonkowski/n8n-skills#-installation).
-
-Skills work seamlessly with n8n-mcp to provide expert guidance throughout the workflow building process!
-
-## 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 only have access to documentation and validation tools. With credentials, you get full workflow management capabilities.
-- **Scope Management:**
-    - By default, `claude mcp add` uses `--scope local` (also called "user scope"), which saves the configuration to your global user settings and keeps API keys private.
-    - To share the configuration with your team, use `--scope project`. This saves the configuration to a `.mcp.json` file in your project's root directory.
-- **Switching Scope:** The cleanest method is to `remove` the server and then `add` it back with the desired scope flag (e.g., `claude mcp remove n8n-mcp` followed by `claude mcp add n8n-mcp --scope project`).
-- **Manual Switching (Advanced):** You can manually edit your `.claude.json` file (e.g., `C:\Users\YourName\.claude.json`). To switch, cut the `"n8n-mcp": { ... }` block from the top-level `"mcpServers"` object (user scope) and paste it into the nested `"mcpServers"` object under your project's path key (project scope), or vice versa. **Important:** You may need to restart Claude Code for manual changes to take effect.
-- Claude Code will automatically start the MCP server when you begin a conversation.

docs/CODECOV_SETUP.md

@@ -1,113 +0,0 @@
-# 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

@@ -1,34 +0,0 @@
-# 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

@@ -1,73 +0,0 @@
-# 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,44 +64,9 @@ 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:
@@ -170,25 +135,12 @@ For local Claude Desktop integration without HTTP:
 
 ```bash
 # Run in stdio mode (interactive)
-docker run --rm -i --init \
+docker run --rm -i \
   -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
 {
@@ -199,7 +151,6 @@ Configure Claude Desktop:
         "run",
         "--rm",
         "-i",
-        "--init",
         "-e", "MCP_MODE=stdio",
         "-v", "n8n-mcp-data:/app/data",
         "ghcr.io/czlonkowski/n8n-mcp:latest"
@@ -286,36 +237,7 @@ docker ps --format "table {{.Names}}\t{{.Status}}"
 docker inspect n8n-mcp | jq '.[0].State.Health'
 ```
 
-## 🔒 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
+## 🔒 Security Considerations
 
 ### Authentication
 
@@ -420,28 +342,6 @@ 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
@@ -558,7 +458,7 @@ secrets:
 
 ### Image Details
 
-- Base: `node:22-alpine`
+- Base: `node:20-alpine`
 - Size: ~280MB compressed
 - Features: Pre-built database with all node information
 - Database: Complete SQLite with 525+ nodes
@@ -606,4 +506,4 @@ services:
 
 ---
 
-*Last updated: July 2025 - Docker implementation v1.1*
+*Last updated: June 2025 - Docker implementation v1.0*

docs/DOCKER_TROUBLESHOOTING.md

@@ -1,422 +0,0 @@
-# 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

@@ -1,371 +0,0 @@
-# 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,16 +1,18 @@
 # HTTP Deployment Guide for n8n-MCP
 
-Deploy n8n-MCP as a remote HTTP server to provide n8n knowledge to compatible MCP Client from anywhere.
+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)
 
 ## 🎯 Overview
 
 n8n-MCP HTTP mode enables:
 - ☁️ Cloud deployment (VPS, Docker, Kubernetes)
-- 🌐 Remote access from any Claude Desktop /Windsurf / other MCP Client 
+- 🌐 Remote access from any Claude Desktop 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
 
@@ -43,8 +45,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
 
@@ -73,13 +75,6 @@ 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
@@ -144,22 +139,18 @@ 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 stable implementation | `true` |
-| `AUTH_TOKEN` or `AUTH_TOKEN_FILE` | Authentication method | See security section |
+| `USE_FIXED_HTTP` | **Important**: Set to `true` for v2.3.2 fixes | `true` |
+| `AUTH_TOKEN` | Secure token (32+ characters) | `generated-token` |
 
 ### Optional Settings
 
-| 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 |
+| 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` |
 
 ### n8n Management Tools (Optional)
 
@@ -176,7 +167,7 @@ Enable 16 additional tools for managing n8n workflows by configuring API access:
 
 #### What This Enables
 
-When configured, you get **16 additional tools** (total: 39 tools):
+When configured, you get **16 additional tools** (total: 38 tools):
 
 **Workflow Management (11 tools):**
 - `n8n_create_workflow` - Create new workflows
@@ -207,64 +198,8 @@ When configured, you get **16 additional tools** (total: 39 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:
@@ -337,10 +272,22 @@ your-domain.com {
 
 ## 💻 Client Configuration
 
-⚠️ **Requirements**: Node.js 18+ must be installed on the client machine for `mcp-remote`
+### 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
+```
 
 ### Method 1: Using mcp-remote (Recommended)
 
+**Requirements**: Node.js 18+ installed locally
+
 ```json
 {
   "mcpServers": {
@@ -351,15 +298,16 @@ your-domain.com {
         "mcp-remote",
         "https://your-server.com/mcp",
         "--header",
-        "Authorization: Bearer YOUR_AUTH_TOKEN_HERE"
-      ]
+        "Authorization: Bearer ${AUTH_TOKEN}"
+      ],
+      "env": {
+        "AUTH_TOKEN": "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:
@@ -402,9 +350,18 @@ 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 (Complete Example)
+### Docker Compose Setup
 
 ```yaml
 version: '3.8'
@@ -415,153 +372,66 @@ 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
-      
-      # 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
-      
+      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}
     ports:
-      - "127.0.0.1:3000:3000"  # Only expose to localhost
-      
+      - "127.0.0.1:3000:3000"  # Bind to localhost only
     volumes:
-      - n8n-mcp-data:/app/data:ro  # Read-only database
-      
+      - n8n-mcp-data:/app/data
     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: 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
+          memory: 256M
 
 volumes:
   n8n-mcp-data:
 ```
 
-### Systemd Service (Production Linux)
+### Systemd Service (Linux)
+
+Create `/etc/systemd/system/n8n-mcp.service`:
 
 ```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
 
-# Use file-based secret
-Environment="AUTH_TOKEN_FILE=/etc/n8n-mcp/auth_token"
+# Environment
 Environment="MCP_MODE=http"
 Environment="USE_FIXED_HTTP=true"
 Environment="NODE_ENV=production"
-Environment="TRUST_PROXY=1"
-Environment="BASE_URL=https://n8n-mcp.example.com"
+EnvironmentFile=/opt/n8n-mcp/.env
 
-# 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
+# Security
 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
@@ -570,127 +440,66 @@ sudo systemctl start n8n-mcp
 
 ## 📡 Monitoring & Maintenance
 
-### Health Endpoint Details
+### Health Checks
 
 ```bash
 # Basic health check
-curl -H "Authorization: Bearer $AUTH_TOKEN" \
-     https://your-server.com/health
+curl https://your-server.com/health
 
 # Response:
 {
   "status": "ok",
   "mode": "http-fixed",
-  "version": "2.7.17",
+  "version": "2.3.2",
   "uptime": 3600,
   "memory": {
-    "used": 95,
+    "used": 45,
     "total": 512,
-    "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
+    "unit": "MB"
   }
 }
 ```
 
-## 🔒 Security Features (v2.16.3+)
+### Monitoring with Prometheus
 
-### Rate Limiting
-
-Built-in rate limiting protects authentication endpoints from brute force attacks:
-
-**Configuration:**
-```bash
-# Defaults (15 minutes window, 20 attempts per IP)
-AUTH_RATE_LIMIT_WINDOW=900000  # milliseconds
-AUTH_RATE_LIMIT_MAX=20
+```yaml
+# prometheus.yml
+scrape_configs:
+  - job_name: 'n8n-mcp'
+    static_configs:
+      - targets: ['localhost:3000']
+    metrics_path: '/health'
+    bearer_token: 'your-auth-token'
 ```
 
-**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)
+### Log Management
 
-**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)
+```bash
+# Docker logs
+docker logs -f n8n-mcp --tail 100
 
-### SSRF Protection
+# Systemd logs
+journalctl -u n8n-mcp -f
 
-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.
+# Log rotation (Docker)
+docker run -d \
+  --log-driver json-file \
+  --log-opt max-size=10m \
+  --log-opt max-file=3 \
+  n8n-mcp
+```
 
 ## 🔒 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 token
+# Generate strong tokens
 openssl rand -base64 32
 
-# 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)
+# Rotate tokens regularly
+AUTH_TOKEN_NEW=$(openssl rand -base64 32)
+docker exec n8n-mcp env AUTH_TOKEN=$AUTH_TOKEN_NEW
 ```
 
 ### 2. Network Security
@@ -716,64 +525,20 @@ docker scan ghcr.io/czlonkowski/n8n-mcp:latest
 
 ## 🔍 Troubleshooting
 
-### Common Issues & Solutions
+### Common Issues
 
-#### Authentication Issues
+**"Stream is not readable" error:**
+- ✅ Solution: Ensure `USE_FIXED_HTTP=true` is set
+- This is fixed in v2.3.2
 
-**"Unauthorized" error:**
-```bash
-# Check token is set correctly
-docker exec n8n-mcp env | grep AUTH
+**"TransformStream is not defined" (client-side):**
+- 🔄 Update Node.js to v18+ on client machine
+- Or use Docker stdio mode instead
 
-# 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+
+**"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
 
 **Bridge script not working:**
 ```bash
@@ -801,51 +566,60 @@ 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
-# 1. Enable debug logging
-docker run -e LOG_LEVEL=debug ...
+# Enable debug logging
+LOG_LEVEL=debug docker run ...
 
-# 2. Test MCP endpoint
+# Test MCP endpoint directly
 curl -X POST https://your-server.com/mcp \
   -H "Authorization: Bearer $AUTH_TOKEN" \
   -H "Content-Type: application/json" \
-  -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"
+  -d '{"jsonrpc":"2.0","method":"list_nodes","params":{"limit":5},"id":1}'
 ```
 
-### Cloud Platform Deployments
+## 🚀 Scaling & Performance
 
-**Railway:** See our [Railway Deployment Guide](./RAILWAY_DEPLOYMENT.md)
+### 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.
 
 ## 🔧 Using n8n Management Tools
 
@@ -884,43 +658,21 @@ curl -X POST https://your-server.com/mcp \
 
 ## 📦 Updates & Maintenance
 
-### Version Updates
-
 ```bash
-# Check current version
-docker exec n8n-mcp node -e "console.log(require('./package.json').version)"
-
-# Update to latest
+# Update to latest version
 docker pull ghcr.io/czlonkowski/n8n-mcp:latest
-docker stop n8n-mcp
-docker rm n8n-mcp
-# Re-run with same environment
+docker compose up -d
 
-# Update to specific version
-docker pull ghcr.io/czlonkowski/n8n-mcp:v2.7.17
-```
+# Backup database
+docker cp n8n-mcp:/app/data/nodes.db ./backup-$(date +%Y%m%d).db
 
-### 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
-  }'
+# Restore database
+docker cp ./backup.db n8n-mcp:/app/data/nodes.db
+docker restart n8n-mcp
 ```
 
 ## 🆘 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)
-- 💬 [Community Discussions](https://github.com/czlonkowski/n8n-mcp/discussions)
+- 💬 [Discussions](https://github.com/czlonkowski/n8n-mcp/discussions)

docs/INSTALLATION.md

@@ -59,10 +59,10 @@ docker compose up -d
          - n8n-mcp-data:/app/data
        
        ports:
-         - "${PORT:-3000}:${PORT:-3000}"
-
+         - "${PORT:-3000}:3000"
+       
        healthcheck:
-         test: ["CMD", "sh", "-c", "curl -f http://127.0.0.1:$${PORT:-3000}/health"]
+         test: ["CMD", "curl", "-f", "http://127.0.0.1:3000/health"]
          interval: 30s
          timeout: 10s
          retries: 3

docs/LIBRARY_USAGE.md

@@ -1,724 +0,0 @@
-# Library Usage Guide - Multi-Tenant / Hosted Deployments
-
-This guide covers using n8n-mcp as a library dependency for building multi-tenant hosted services.
-
-## Overview
-
-n8n-mcp can be used as a Node.js library to build multi-tenant backends that provide MCP services to multiple users or instances. The package exports all necessary components for integration into your existing services.
-
-## Installation
-
-```bash
-npm install n8n-mcp
-```
-
-## Core Concepts
-
-### Library Mode vs CLI Mode
-
-- **CLI Mode** (default): Single-player usage via `npx n8n-mcp` or Docker
-- **Library Mode**: Multi-tenant usage by importing and using the `N8NMCPEngine` class
-
-### Instance Context
-
-The `InstanceContext` type allows you to pass per-request configuration to the MCP engine:
-
-```typescript
-interface InstanceContext {
-  // Instance-specific n8n API configuration
-  n8nApiUrl?: string;
-  n8nApiKey?: string;
-  n8nApiTimeout?: number;
-  n8nApiMaxRetries?: number;
-
-  // Instance identification
-  instanceId?: string;
-  sessionId?: string;
-
-  // Extensible metadata
-  metadata?: Record<string, any>;
-}
-```
-
-## Basic Example
-
-```typescript
-import express from 'express';
-import { N8NMCPEngine } from 'n8n-mcp';
-
-const app = express();
-const mcpEngine = new N8NMCPEngine({
-  sessionTimeout: 3600000, // 1 hour
-  logLevel: 'info'
-});
-
-// Handle MCP requests with per-user context
-app.post('/mcp', async (req, res) => {
-  const instanceContext = {
-    n8nApiUrl: req.user.n8nUrl,
-    n8nApiKey: req.user.n8nApiKey,
-    instanceId: req.user.id
-  };
-
-  await mcpEngine.processRequest(req, res, instanceContext);
-});
-
-app.listen(3000);
-```
-
-## Multi-Tenant Backend Example
-
-This example shows a complete multi-tenant implementation with user authentication and instance management:
-
-```typescript
-import express from 'express';
-import { N8NMCPEngine, InstanceContext, validateInstanceContext } from 'n8n-mcp';
-
-const app = express();
-const mcpEngine = new N8NMCPEngine({
-  sessionTimeout: 3600000, // 1 hour
-  logLevel: 'info'
-});
-
-// Start MCP engine
-await mcpEngine.start();
-
-// Authentication middleware
-const authenticate = async (req, res, next) => {
-  const token = req.headers.authorization?.replace('Bearer ', '');
-  if (!token) {
-    return res.status(401).json({ error: 'Unauthorized' });
-  }
-
-  // Verify token and attach user to request
-  req.user = await getUserFromToken(token);
-  next();
-};
-
-// Get instance configuration from database
-const getInstanceConfig = async (instanceId: string, userId: string) => {
-  // Your database logic here
-  const instance = await db.instances.findOne({
-    where: { id: instanceId, userId }
-  });
-
-  if (!instance) {
-    throw new Error('Instance not found');
-  }
-
-  return {
-    n8nApiUrl: instance.n8nUrl,
-    n8nApiKey: await decryptApiKey(instance.encryptedApiKey),
-    instanceId: instance.id
-  };
-};
-
-// MCP endpoint with per-instance context
-app.post('/api/instances/:instanceId/mcp', authenticate, async (req, res) => {
-  try {
-    // Get instance configuration
-    const instance = await getInstanceConfig(req.params.instanceId, req.user.id);
-
-    // Create instance context
-    const context: InstanceContext = {
-      n8nApiUrl: instance.n8nApiUrl,
-      n8nApiKey: instance.n8nApiKey,
-      instanceId: instance.instanceId,
-      metadata: {
-        userId: req.user.id,
-        userAgent: req.headers['user-agent'],
-        ip: req.ip
-      }
-    };
-
-    // Validate context before processing
-    const validation = validateInstanceContext(context);
-    if (!validation.valid) {
-      return res.status(400).json({
-        error: 'Invalid instance configuration',
-        details: validation.errors
-      });
-    }
-
-    // Process request with instance context
-    await mcpEngine.processRequest(req, res, context);
-
-  } catch (error) {
-    console.error('MCP request error:', error);
-    res.status(500).json({ error: 'Internal server error' });
-  }
-});
-
-// Health endpoint
-app.get('/health', async (req, res) => {
-  const health = await mcpEngine.healthCheck();
-  res.status(health.status === 'healthy' ? 200 : 503).json(health);
-});
-
-// Graceful shutdown
-process.on('SIGTERM', async () => {
-  await mcpEngine.shutdown();
-  process.exit(0);
-});
-
-app.listen(3000);
-```
-
-## API Reference
-
-### N8NMCPEngine
-
-#### Constructor
-
-```typescript
-new N8NMCPEngine(options?: {
-  sessionTimeout?: number;  // Session TTL in ms (default: 1800000 = 30min)
-  logLevel?: 'error' | 'warn' | 'info' | 'debug';  // Default: 'info'
-})
-```
-
-#### Methods
-
-##### `async processRequest(req, res, context?)`
-
-Process a single MCP request with optional instance context.
-
-**Parameters:**
-- `req`: Express request object
-- `res`: Express response object
-- `context` (optional): InstanceContext with per-instance configuration
-
-**Example:**
-```typescript
-const context: InstanceContext = {
-  n8nApiUrl: 'https://instance1.n8n.cloud',
-  n8nApiKey: 'instance1-key',
-  instanceId: 'tenant-123'
-};
-
-await engine.processRequest(req, res, context);
-```
-
-##### `async healthCheck()`
-
-Get engine health status for monitoring.
-
-**Returns:** `EngineHealth`
-```typescript
-{
-  status: 'healthy' | 'unhealthy';
-  uptime: number;  // seconds
-  sessionActive: boolean;
-  memoryUsage: {
-    used: number;
-    total: number;
-    unit: string;
-  };
-  version: string;
-}
-```
-
-**Example:**
-```typescript
-app.get('/health', async (req, res) => {
-  const health = await engine.healthCheck();
-  res.status(health.status === 'healthy' ? 200 : 503).json(health);
-});
-```
-
-##### `getSessionInfo()`
-
-Get current session information for debugging.
-
-**Returns:**
-```typescript
-{
-  active: boolean;
-  sessionId?: string;
-  age?: number;  // milliseconds
-  sessions?: {
-    total: number;
-    active: number;
-    expired: number;
-    max: number;
-    sessionIds: string[];
-  };
-}
-```
-
-##### `async start()`
-
-Start the engine (for standalone mode). Not needed when using `processRequest()` directly.
-
-##### `async shutdown()`
-
-Graceful shutdown for service lifecycle management.
-
-**Example:**
-```typescript
-process.on('SIGTERM', async () => {
-  await engine.shutdown();
-  process.exit(0);
-});
-```
-
-### Types
-
-#### InstanceContext
-
-Configuration for a specific user instance:
-
-```typescript
-interface InstanceContext {
-  n8nApiUrl?: string;
-  n8nApiKey?: string;
-  n8nApiTimeout?: number;
-  n8nApiMaxRetries?: number;
-  instanceId?: string;
-  sessionId?: string;
-  metadata?: Record<string, any>;
-}
-```
-
-#### Validation Functions
-
-##### `validateInstanceContext(context: InstanceContext)`
-
-Validate and sanitize instance context.
-
-**Returns:**
-```typescript
-{
-  valid: boolean;
-  errors?: string[];
-}
-```
-
-**Example:**
-```typescript
-import { validateInstanceContext } from 'n8n-mcp';
-
-const validation = validateInstanceContext(context);
-if (!validation.valid) {
-  console.error('Invalid context:', validation.errors);
-}
-```
-
-##### `isInstanceContext(obj: any)`
-
-Type guard to check if an object is a valid InstanceContext.
-
-**Example:**
-```typescript
-import { isInstanceContext } from 'n8n-mcp';
-
-if (isInstanceContext(req.body.context)) {
-  // TypeScript knows this is InstanceContext
-  await engine.processRequest(req, res, req.body.context);
-}
-```
-
-## Session Management
-
-### Session Strategies
-
-The MCP engine supports flexible session ID formats:
-
-- **UUIDv4**: Internal n8n-mcp format (default)
-- **Instance-prefixed**: `instance-{userId}-{hash}-{uuid}` for multi-tenant isolation
-- **Custom formats**: Any non-empty string for mcp-remote and other proxies
-
-Session validation happens via transport lookup, not format validation. This ensures compatibility with all MCP clients.
-
-### Multi-Tenant Configuration
-
-Set these environment variables for multi-tenant mode:
-
-```bash
-# Enable multi-tenant mode
-ENABLE_MULTI_TENANT=true
-
-# Session strategy: "instance" (default) or "shared"
-MULTI_TENANT_SESSION_STRATEGY=instance
-```
-
-**Session Strategies:**
-
-- **instance** (recommended): Each tenant gets isolated sessions
-  - Session ID: `instance-{instanceId}-{configHash}-{uuid}`
-  - Better isolation and security
-  - Easier debugging per tenant
-
-- **shared**: Multiple tenants share sessions with context switching
-  - More efficient for high tenant count
-  - Requires careful context management
-
-## Security Considerations
-
-### API Key Management
-
-Always encrypt API keys server-side:
-
-```typescript
-import { createCipheriv, createDecipheriv } from 'crypto';
-
-// Encrypt before storing
-const encryptApiKey = (apiKey: string) => {
-  const cipher = createCipheriv('aes-256-gcm', encryptionKey, iv);
-  return cipher.update(apiKey, 'utf8', 'hex') + cipher.final('hex');
-};
-
-// Decrypt before using
-const decryptApiKey = (encrypted: string) => {
-  const decipher = createDecipheriv('aes-256-gcm', encryptionKey, iv);
-  return decipher.update(encrypted, 'hex', 'utf8') + decipher.final('utf8');
-};
-
-// Use decrypted key in context
-const context: InstanceContext = {
-  n8nApiKey: await decryptApiKey(instance.encryptedApiKey),
-  // ...
-};
-```
-
-### Input Validation
-
-Always validate instance context before processing:
-
-```typescript
-import { validateInstanceContext } from 'n8n-mcp';
-
-const validation = validateInstanceContext(context);
-if (!validation.valid) {
-  throw new Error(`Invalid context: ${validation.errors?.join(', ')}`);
-}
-```
-
-### Rate Limiting
-
-Implement rate limiting per tenant:
-
-```typescript
-import rateLimit from 'express-rate-limit';
-
-const limiter = rateLimit({
-  windowMs: 15 * 60 * 1000, // 15 minutes
-  max: 100, // limit each IP to 100 requests per windowMs
-  keyGenerator: (req) => req.user?.id || req.ip
-});
-
-app.post('/api/instances/:instanceId/mcp', authenticate, limiter, async (req, res) => {
-  // ...
-});
-```
-
-## Error Handling
-
-Always wrap MCP requests in try-catch blocks:
-
-```typescript
-app.post('/api/instances/:instanceId/mcp', authenticate, async (req, res) => {
-  try {
-    const context = await getInstanceConfig(req.params.instanceId, req.user.id);
-    await mcpEngine.processRequest(req, res, context);
-  } catch (error) {
-    console.error('MCP error:', error);
-
-    // Don't leak internal errors to clients
-    if (error.message.includes('not found')) {
-      return res.status(404).json({ error: 'Instance not found' });
-    }
-
-    res.status(500).json({ error: 'Internal server error' });
-  }
-});
-```
-
-## Monitoring
-
-### Health Checks
-
-Set up periodic health checks:
-
-```typescript
-setInterval(async () => {
-  const health = await mcpEngine.healthCheck();
-
-  if (health.status === 'unhealthy') {
-    console.error('MCP engine unhealthy:', health);
-    // Alert your monitoring system
-  }
-
-  // Log metrics
-  console.log('MCP engine metrics:', {
-    uptime: health.uptime,
-    memory: health.memoryUsage,
-    sessionActive: health.sessionActive
-  });
-}, 60000); // Every minute
-```
-
-### Session Monitoring
-
-Track active sessions:
-
-```typescript
-app.get('/admin/sessions', authenticate, async (req, res) => {
-  if (!req.user.isAdmin) {
-    return res.status(403).json({ error: 'Forbidden' });
-  }
-
-  const sessionInfo = mcpEngine.getSessionInfo();
-  res.json(sessionInfo);
-});
-```
-
-## Testing
-
-### Unit Testing
-
-```typescript
-import { N8NMCPEngine, InstanceContext } from 'n8n-mcp';
-
-describe('MCP Engine', () => {
-  let engine: N8NMCPEngine;
-
-  beforeEach(() => {
-    engine = new N8NMCPEngine({ logLevel: 'error' });
-  });
-
-  afterEach(async () => {
-    await engine.shutdown();
-  });
-
-  it('should process request with context', async () => {
-    const context: InstanceContext = {
-      n8nApiUrl: 'https://test.n8n.io',
-      n8nApiKey: 'test-key',
-      instanceId: 'test-instance'
-    };
-
-    const mockReq = createMockRequest();
-    const mockRes = createMockResponse();
-
-    await engine.processRequest(mockReq, mockRes, context);
-
-    expect(mockRes.status).toBe(200);
-  });
-});
-```
-
-### Integration Testing
-
-```typescript
-import request from 'supertest';
-import { createApp } from './app';
-
-describe('Multi-tenant MCP API', () => {
-  let app;
-  let authToken;
-
-  beforeAll(async () => {
-    app = await createApp();
-    authToken = await getTestAuthToken();
-  });
-
-  it('should handle MCP request for instance', async () => {
-    const response = await request(app)
-      .post('/api/instances/test-instance/mcp')
-      .set('Authorization', `Bearer ${authToken}`)
-      .send({
-        jsonrpc: '2.0',
-        method: 'initialize',
-        params: {
-          protocolVersion: '2024-11-05',
-          capabilities: {}
-        },
-        id: 1
-      });
-
-    expect(response.status).toBe(200);
-    expect(response.body.result).toBeDefined();
-  });
-});
-```
-
-## Deployment Considerations
-
-### Environment Variables
-
-```bash
-# Required for multi-tenant mode
-ENABLE_MULTI_TENANT=true
-MULTI_TENANT_SESSION_STRATEGY=instance
-
-# Optional: Logging
-LOG_LEVEL=info
-DISABLE_CONSOLE_OUTPUT=false
-
-# Optional: Session configuration
-SESSION_TIMEOUT=1800000  # 30 minutes in milliseconds
-MAX_SESSIONS=100
-
-# Optional: Performance
-NODE_ENV=production
-```
-
-### Docker Deployment
-
-```dockerfile
-FROM node:20-alpine
-
-WORKDIR /app
-
-COPY package*.json ./
-RUN npm ci --only=production
-
-COPY . .
-
-ENV NODE_ENV=production
-ENV ENABLE_MULTI_TENANT=true
-ENV LOG_LEVEL=info
-
-EXPOSE 3000
-
-CMD ["node", "dist/server.js"]
-```
-
-### Kubernetes Deployment
-
-```yaml
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: n8n-mcp-backend
-spec:
-  replicas: 3
-  selector:
-    matchLabels:
-      app: n8n-mcp-backend
-  template:
-    metadata:
-      labels:
-        app: n8n-mcp-backend
-    spec:
-      containers:
-      - name: backend
-        image: your-registry/n8n-mcp-backend:latest
-        ports:
-        - containerPort: 3000
-        env:
-        - name: ENABLE_MULTI_TENANT
-          value: "true"
-        - name: LOG_LEVEL
-          value: "info"
-        resources:
-          requests:
-            memory: "256Mi"
-            cpu: "250m"
-          limits:
-            memory: "512Mi"
-            cpu: "500m"
-        livenessProbe:
-          httpGet:
-            path: /health
-            port: 3000
-          initialDelaySeconds: 10
-          periodSeconds: 30
-        readinessProbe:
-          httpGet:
-            path: /health
-            port: 3000
-          initialDelaySeconds: 5
-          periodSeconds: 10
-```
-
-## Examples
-
-### Complete Multi-Tenant SaaS Example
-
-For a complete implementation example, see:
-- [n8n-mcp-backend](https://github.com/czlonkowski/n8n-mcp-backend) - Full hosted service implementation
-
-### Migration from Single-Player
-
-If you're migrating from single-player (CLI/Docker) to multi-tenant:
-
-1. **Keep backward compatibility** - Use environment fallback:
-```typescript
-const context: InstanceContext = {
-  n8nApiUrl: instanceUrl || process.env.N8N_API_URL,
-  n8nApiKey: instanceKey || process.env.N8N_API_KEY,
-  instanceId: instanceId || 'default'
-};
-```
-
-2. **Gradual rollout** - Start with a feature flag:
-```typescript
-const isMultiTenant = process.env.ENABLE_MULTI_TENANT === 'true';
-
-if (isMultiTenant) {
-  const context = await getInstanceConfig(req.params.instanceId);
-  await engine.processRequest(req, res, context);
-} else {
-  // Legacy single-player mode
-  await engine.processRequest(req, res);
-}
-```
-
-## Troubleshooting
-
-### Common Issues
-
-#### Module Resolution Errors
-
-If you see `Cannot find module 'n8n-mcp'`:
-
-```bash
-# Clear node_modules and reinstall
-rm -rf node_modules package-lock.json
-npm install
-
-# Verify package has types field
-npm info n8n-mcp
-
-# Check TypeScript can resolve it
-npx tsc --noEmit
-```
-
-#### Session ID Validation Errors
-
-If you see `Invalid session ID format` errors:
-
-- Ensure you're using n8n-mcp v2.18.9 or later
-- Session IDs can be any non-empty string
-- No need to generate UUIDs - use your own format
-
-#### Memory Leaks
-
-If memory usage grows over time:
-
-```typescript
-// Ensure proper cleanup
-process.on('SIGTERM', async () => {
-  await engine.shutdown();
-  process.exit(0);
-});
-
-// Monitor session count
-const sessionInfo = engine.getSessionInfo();
-console.log('Active sessions:', sessionInfo.sessions?.active);
-```
-
-## Further Reading
-
-- [MCP Protocol Specification](https://modelcontextprotocol.io/docs)
-- [n8n API Documentation](https://docs.n8n.io/api/)
-- [Express.js Guide](https://expressjs.com/en/guide/routing.html)
-- [n8n-mcp Main README](../README.md)
-
-## Support
-
-- **Issues**: [GitHub Issues](https://github.com/czlonkowski/n8n-mcp/issues)
-- **Discussions**: [GitHub Discussions](https://github.com/czlonkowski/n8n-mcp/discussions)
-- **Security**: For security issues, see [SECURITY.md](../SECURITY.md)

docs/N8N_DEPLOYMENT.md

@@ -1,758 +0,0 @@
-# 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/RAILWAY_DEPLOYMENT.md

@@ -1,339 +0,0 @@
-# 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

@@ -0,0 +1,221 @@
+# 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/VS_CODE_PROJECT_SETUP.md

@@ -1,201 +0,0 @@
-# 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', updates: {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

@@ -1,69 +0,0 @@
-# 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/local/DEEP_DIVE_ANALYSIS_README.md

@@ -1,225 +0,0 @@
-# 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.*