Merge branch 'main' into kimbo128/main - resolve conflicts

docs/CHANGELOG.md

@@ -5,6 +5,54 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.7.15] - 2025-07-15
+
+### Fixed
+- **HTTP Server URL Handling**: Fixed hardcoded localhost URLs in HTTP server output (Issue #41, #42)
+  - Added intelligent URL detection that considers BASE_URL, PUBLIC_URL, and proxy headers
+  - Server now displays correct public URLs when deployed behind reverse proxies
+  - Added support for X-Forwarded-Proto and X-Forwarded-Host headers when TRUST_PROXY is enabled
+  - Fixed port display logic to hide standard ports (80/443) in URLs
+  - Added new GET endpoints (/, /mcp) for better API discovery
+
+### Security
+- **Host Header Injection Prevention**: Added hostname validation to prevent malicious proxy headers
+  - Only accepts valid hostnames (alphanumeric, dots, hyphens, optional port)
+  - Rejects hostnames with paths, usernames, or special characters
+  - Falls back to safe defaults when invalid headers are detected
+- **URL Scheme Validation**: Restricted URL schemes to http/https only
+  - Blocks dangerous schemes like javascript:, file://, data:
+  - Validates all configured URLs (BASE_URL, PUBLIC_URL)
+- **Information Disclosure**: Removed sensitive environment data from API responses
+  - Root endpoint no longer exposes internal configuration
+  - Only shows essential API information
+
+### Added
+- **URL Detection Utility**: New `url-detector.ts` module for intelligent URL detection
+  - Prioritizes explicit configuration (BASE_URL/PUBLIC_URL)
+  - Falls back to proxy headers when TRUST_PROXY is enabled
+  - Uses host/port configuration as final fallback
+  - Includes comprehensive security validations
+- **Test Scripts**: Added test scripts for URL configuration and security validation
+  - `test-url-configuration.ts`: Tests various URL detection scenarios
+  - `test-security.ts`: Validates security fixes for malicious headers
+
+### Changed
+- **Consistent Versioning**: Fixed version inconsistency between server implementations
+  - Both http-server.ts and http-server-single-session.ts now use PROJECT_VERSION
+  - Removed hardcoded version strings
+- **HTTP Bridge**: Updated to use HOST/PORT environment variables for default URL construction
+- **Documentation**: Updated HTTP deployment guide with URL configuration section
+
+## [2.7.14] - 2025-07-15
+
+### Fixed
+- **Partial Update Tool**: Fixed validation/execution discrepancy that caused "settings must NOT have additional properties" error (Issue #45)
+  - Removed logic in `cleanWorkflowForUpdate` that was incorrectly adding default settings to workflows
+  - The function now only removes read-only fields without adding any new properties
+  - This fixes the issue where partial updates would pass validation but fail during execution
+  - Added comprehensive test coverage in `test-issue-45-fix.ts`
+
 ## [2.7.13] - 2025-07-11
 
 ### Fixed

docs/CLAUDE_CODE_SETUP.md

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

docs/CURSOR_SETUP.md

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

docs/DOCKER_README.md

@@ -64,6 +64,7 @@ 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 |
 
 *Either `AUTH_TOKEN` or `AUTH_TOKEN_FILE` must be set for HTTP mode. If both are set, `AUTH_TOKEN` takes precedence.
 
@@ -342,6 +343,28 @@ docker run --rm \
   alpine tar xzf /backup/n8n-mcp-backup.tar.gz -C /target
 ```
 
+### Custom Database Path (v2.7.16+)
+
+You can specify a custom database location using `NODE_DB_PATH`:
+
+```bash
+# Use custom path within mounted volume
+docker run -d \
+  --name n8n-mcp \
+  -e MCP_MODE=http \
+  -e AUTH_TOKEN=your-token \
+  -e NODE_DB_PATH=/app/data/custom/my-nodes.db \
+  -v n8n-mcp-data:/app/data \
+  -p 3000:3000 \
+  ghcr.io/czlonkowski/n8n-mcp:latest
+```
+
+**Important Notes:**
+- The path must end with `.db`
+- For data persistence, ensure the path is within a mounted volume
+- Paths outside mounted volumes will be lost on container restart
+- The directory will be created automatically if it doesn't exist
+
 ## 🐛 Troubleshooting
 
 ### Common Issues
@@ -506,4 +529,4 @@ services:
 
 ---
 
-*Last updated: June 2025 - Docker implementation v1.0*
+*Last updated: July 2025 - Docker implementation v1.1*

docs/DOCKER_TROUBLESHOOTING.md

@@ -0,0 +1,349 @@
+# 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
+
+### 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 Name Conflicts
+
+**Symptoms:**
+- Error: "Container with name '/n8n-mcp-container' already exists"
+- Claude Desktop shows duplicate containers
+
+**Root Cause:** Claude Desktop bug that spawns containers twice.
+
+**Solutions:**
+
+1. **Remove container name (Recommended):**
+```json
+{
+  "command": "docker",
+  "args": [
+    "run", "-i", "--rm",
+    // Remove: "--name", "n8n-mcp-container",
+    "ghcr.io/czlonkowski/n8n-mcp:latest"
+  ]
+}
+```
+
+2. **Manual cleanup when it happens:**
+```bash
+docker rm -f n8n-mcp-container
+```
+
+3. **Use HTTP mode instead** (avoids the issue entirely)
+
+### 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/HTTP_DEPLOYMENT.md

@@ -151,6 +151,8 @@ Skip HTTP entirely and use stdio mode directly:
 | `LOG_LEVEL` | Log verbosity | `info` |
 | `NODE_ENV` | Environment | `production` |
 | `TRUST_PROXY` | Trust proxy headers for correct IP logging | `0` |
+| `BASE_URL` | Public URL for the server (v2.7.14+) | Auto-detected |
+| `PUBLIC_URL` | Alternative to BASE_URL | Auto-detected |
 
 ### n8n Management Tools (Optional)
 
@@ -200,6 +202,39 @@ When configured, you get **16 additional tools** (total: 38 tools):
 
 ## 🌐 Reverse Proxy Configuration
 
+### URL Configuration (v2.7.14+)
+
+n8n-MCP now intelligently detects the correct URL for your deployment:
+
+1. **Explicit Configuration** (highest priority):
+   ```bash
+   BASE_URL=https://n8n-mcp.example.com  # Explicitly set public URL
+   # or
+   PUBLIC_URL=https://your-domain.com:8443
+   ```
+
+2. **Auto-Detection from Proxy Headers** (when TRUST_PROXY is enabled):
+   - Detects from `X-Forwarded-Proto` and `X-Forwarded-Host` headers
+   - Perfect for Cloudflare, Nginx, and other proxies
+
+3. **Fallback** (when not configured):
+   - Uses `HOST` and `PORT` configuration
+   - Shows `localhost` when bound to `0.0.0.0`
+
+**Example scenarios:**
+```bash
+# Behind Cloudflare (auto-detected)
+TRUST_PROXY=1
+# Console shows: https://n8n-mcp.example.com
+
+# Explicit configuration
+BASE_URL=https://api.mycompany.com/mcp
+# Console shows: https://api.mycompany.com/mcp
+
+# Local development (no proxy)
+# Console shows: http://localhost:3000
+```
+
 ### 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:

docs/VS_CODE_PROJECT_SETUP.md

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

docs/WINDSURF_SETUP.md

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