fix: resolve Claude Desktop stdio communication issues and update documentation

- Fixed console output interference with stdio JSON-RPC protocol: - Modified logger to suppress ALL output in stdio mode - Added DISABLE_CONSOLE_OUTPUT environment variable support - Updated error handlers to respect stdio mode - Updated Claude Desktop configuration documentation: - Added required environment variables for clean stdio communication - Promoted local installation as recommended method - Fixed remote connection instructions (removed broken mcp-remote) - Added troubleshooting section for common issues - Updated both README.md and docs/README_CLAUDE_SETUP.md - Environment variables now required for stdio mode: - MCP_MODE=stdio - LOG_LEVEL=error - DISABLE_CONSOLE_OUTPUT=true - NODE_ENV=production This ensures clean JSON-RPC communication without console output corruption. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-06-16 00:50:06 +02:00
parent 7d6691cd42
commit 4d955a5b4b
4 changed files with 116 additions and 72 deletions
--- a/README.md
+++ b/README.md
@@ -75,23 +75,27 @@ npm run start:http # HTTP mode for remote access

 ## 🔧 Claude Desktop Configuration

-### For Local Installation (stdio mode)
+### For Local Installation (stdio mode) - Recommended

-**macOS/Linux:**
 ```json
 {
  "mcpServers": {
-    "n8n-documentation": {
+    "n8n-mcp": {
      "command": "node",
      "args": ["/path/to/n8n-mcp/dist/mcp/index.js"],
      "env": {
-        "NODE_ENV": "production"
+        "NODE_ENV": "production",
+        "LOG_LEVEL": "error",
+        "MCP_MODE": "stdio",
+        "DISABLE_CONSOLE_OUTPUT": "true"
      }
    }
  }
 }
 ```

+⚠️ **Important**: The environment variables above are required for proper stdio communication.
+
 ### For Docker (stdio mode)

 ```json
@@ -102,6 +106,8 @@ npm run start:http # HTTP mode for remote access
      "args": [
        "run", "--rm", "-i",
        "-e", "MCP_MODE=stdio",
+        "-e", "LOG_LEVEL=error",
+        "-e", "DISABLE_CONSOLE_OUTPUT=true",
        "-v", "n8n-mcp-data:/app/data",
        "ghcr.io/czlonkowski/n8n-mcp:latest"
      ]
@@ -112,22 +118,19 @@ npm run start:http # HTTP mode for remote access

 ### For Remote Server (HTTP mode)

-**Important**: Requires Node.js 18+ on your local machine.
+For production deployments with HTTP mode, use the custom HTTP client:

 ```json
 {
  "mcpServers": {
    "n8n-remote": {
-      "command": "npx",
+      "command": "node",
      "args": [
-        "-y",
-        "mcp-remote",
-        "https://your-server.com/mcp",
-        "--header",
-        "Authorization: Bearer ${AUTH_TOKEN}"
+        "/path/to/n8n-mcp/scripts/mcp-http-client.js",
+        "http://your-server.com:3000/mcp"
      ],
      "env": {
-        "AUTH_TOKEN": "your-auth-token"
+        "MCP_AUTH_TOKEN": "your-auth-token"
      }
    }
  }
--- a/docs/README_CLAUDE_SETUP.md
+++ b/docs/README_CLAUDE_SETUP.md
@@ -1,38 +1,16 @@
 # Claude Desktop Configuration for n8n-MCP

-This guide helps you connect n8n-MCP to Claude Desktop, giving Claude comprehensive knowledge about n8n's 450+ workflow automation nodes.
+This guide helps you connect n8n-MCP to Claude Desktop, giving Claude comprehensive knowledge about n8n's 525+ workflow automation nodes.

 ## 🎯 Prerequisites

 - Claude Desktop installed
- For remote connections: Node.js 18+ on your local machine
+- For local installation: Node.js (any version)
 - For Docker: Docker Desktop or Docker Engine

 ## 🛠️ Configuration Methods

-### Method 1: Docker (Simplest) 🐳
-
-No installation needed - runs directly from Docker:
-
-```json
-{
-  "mcpServers": {
-    "n8n-docker": {
-      "command": "docker",
-      "args": [
-        "run", "--rm", "-i",
-        "-e", "MCP_MODE=stdio",
-        "-v", "n8n-mcp-data:/app/data",
-        "ghcr.io/czlonkowski/n8n-mcp:latest"
-      ]
-    }
-  }
-}
-```
-
-✨ **Benefits**: No setup required, always up-to-date, isolated environment.
-
-### Method 2: Local Installation
+### Method 1: Local Installation (Recommended) 💻

 1. **Install and build:**
   ```bash
@@ -47,44 +25,75 @@ No installation needed - runs directly from Docker:
   ```json
   {
     "mcpServers": {
-       "n8n-documentation": {
+       "n8n-mcp": {
         "command": "node",
         "args": ["/absolute/path/to/n8n-mcp/dist/mcp/index.js"],
         "env": {
-           "NODE_ENV": "production"
+           "NODE_ENV": "production",
+           "LOG_LEVEL": "error",
+           "MCP_MODE": "stdio",
+           "DISABLE_CONSOLE_OUTPUT": "true"
         }
       }
     }
   }
   ```

-⚠️ **Important**: Use absolute paths, not relative paths.
+⚠️ **Important**: 
+- Use absolute paths, not relative paths
+- The environment variables shown above are critical for proper stdio communication

-### Method 3: Remote Server Connection
+### Method 2: Docker 🐳

-**Requirements**: Node.js 18+ installed locally
+No installation needed - runs directly from Docker:

 ```json
 {
  "mcpServers": {
-    "n8n-remote": {
-      "command": "npx",
+    "n8n-docker": {
+      "command": "docker",
      "args": [
-        "-y",
-        "mcp-remote",
-        "https://your-server.com/mcp",
-        "--header",
-        "Authorization: Bearer ${AUTH_TOKEN}"
-      ],
-      "env": {
-        "AUTH_TOKEN": "your-auth-token"
-      }
+        "run", "--rm", "-i",
+        "-e", "MCP_MODE=stdio",
+        "-e", "LOG_LEVEL=error",
+        "-e", "DISABLE_CONSOLE_OUTPUT=true",
+        "-v", "n8n-mcp-data:/app/data",
+        "ghcr.io/czlonkowski/n8n-mcp:latest"
+      ]
    }
  }
 }
 ```

-📝 **Note**: Remote MCP is also natively supported in Claude Pro/Team/Enterprise via Settings > Integrations.
+✨ **Benefits**: No setup required, always up-to-date, isolated environment.
+
+### Method 3: Remote Server Connection (Advanced)
+
+⚠️ **Note**: Remote connections are complex and may have compatibility issues. Consider using local installation instead.
+
+For production deployments with multiple users:
+
+1. **Deploy server with HTTP mode** (see [HTTP Deployment Guide](./HTTP_DEPLOYMENT.md))
+
+2. **Connect using custom HTTP client:**
+   ```json
+   {
+     "mcpServers": {
+       "n8n-remote": {
+         "command": "node",
+         "args": [
+           "/path/to/n8n-mcp/scripts/mcp-http-client.js",
+           "http://your-server.com:3000/mcp"
+         ],
+         "env": {
+           "MCP_AUTH_TOKEN": "your-auth-token"
+         }
+       }
+     }
+   }
+   ```
+
+📝 **Note**: Native remote MCP support is available in Claude Pro/Team/Enterprise via Settings > Integrations.

 ## 📁 Configuration File Locations

@@ -164,11 +173,30 @@ docker pull ghcr.io/czlonkowski/n8n-mcp:latest
 docker ps
 ```

+### Common Issues
+
+**"Expected ',' or ']' after array element" errors in logs:**
+- Cause: Console output interfering with stdio communication
+- Fix: Ensure all required environment variables are set:
+  - `MCP_MODE=stdio`
+  - `LOG_LEVEL=error`
+  - `DISABLE_CONSOLE_OUTPUT=true`
+
+**"NODE_MODULE_VERSION mismatch" warnings:**
+- Not a problem! The server automatically falls back to a pure JavaScript implementation
+- The warnings are suppressed with proper environment variables
+
+**Server appears but tools don't work:**
+- Check that you've built the project: `npm run build`
+- Verify the database exists: `npm run rebuild`
+- Restart Claude Desktop completely (quit and reopen)
+
 ### Quick Fixes

 - 🔄 **Always restart Claude** after config changes
 - 📋 **Copy example configs exactly** (watch for typos)
 - 📂 **Use absolute paths** (/Users/... not ~/...)
 - 🔍 **Check logs**: View > Developer > Logs in Claude Desktop
+- 🛑 **Set all environment variables** shown in the examples

 For more help, see [Troubleshooting Guide](./TROUBLESHOOTING.md)
--- a/src/mcp/index.ts
+++ b/src/mcp/index.ts
@@ -5,21 +5,25 @@ import { logger } from '../utils/logger';

 // Add error details to stderr for Claude Desktop debugging
 process.on('uncaughtException', (error) => {
+  if (process.env.MCP_MODE !== 'stdio') {
    console.error('Uncaught Exception:', error);
+  }
  logger.error('Uncaught Exception:', error);
  process.exit(1);
 });

 process.on('unhandledRejection', (reason, promise) => {
+  if (process.env.MCP_MODE !== 'stdio') {
    console.error('Unhandled Rejection at:', promise, 'reason:', reason);
+  }
  logger.error('Unhandled Rejection:', reason);
  process.exit(1);
 });

 async function main() {
-  try {
  const mode = process.env.MCP_MODE || 'stdio';
  
+  try {
    // Only show debug messages in HTTP mode to avoid corrupting stdio communication
    if (mode === 'http') {
      console.error(`Starting n8n Documentation MCP Server in ${mode} mode...`);
@@ -55,6 +59,8 @@ async function main() {
      await server.run();
    }
  } catch (error) {
+    // In stdio mode, we cannot output to console at all
+    if (mode !== 'stdio') {
      console.error('Failed to start MCP server:', error);
      logger.error('Failed to start MCP server', error);
      
@@ -70,6 +76,7 @@ async function main() {
        console.error('2. Run: npm rebuild better-sqlite3');
        console.error('3. If that doesn\'t work, try: rm -rf node_modules && npm install');
      }
+    }
    
    process.exit(1);
  }
--- a/src/utils/logger.ts
+++ b/src/utils/logger.ts
@@ -54,6 +54,12 @@ export class Logger {
    if (level <= this.config.level) {
      const formattedMessage = this.formatMessage(levelName, message);
      
+      // In stdio mode, suppress ALL console output to avoid corrupting JSON-RPC
+      if (process.env.MCP_MODE === 'stdio' || process.env.DISABLE_CONSOLE_OUTPUT === 'true') {
+        // Silently drop all logs in stdio mode
+        return;
+      }
+      
      // In HTTP mode during request handling, suppress console output
      // The ConsoleManager will handle this, but we add a safety check
      if (process.env.MCP_MODE === 'http' && process.env.MCP_REQUEST_ACTIVE === 'true') {