Merge pull request #63 from czlonkowski/kimbo128/main

Merging with admin privileges - Railway deployment support

.github/workflows/docker-build.yml

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

Dockerfile.railway

@@ -9,7 +9,7 @@ WORKDIR /app
 RUN apk add --no-cache python3 make g++ && \
     rm -rf /var/cache/apk/*
 
-# Copy package files
+# Copy package files and tsconfig
 COPY package*.json tsconfig.json ./
 
 # Install all dependencies (including devDependencies for build)
@@ -44,6 +44,10 @@ 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
@@ -61,11 +65,16 @@ RUN addgroup -g 1001 -S nodejs && \
     chown -R nodejs:nodejs /app
 USER nodejs
 
-# Set environment variables
+# 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
@@ -74,5 +83,6 @@ EXPOSE 3000
 HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
   CMD curl -f http://127.0.0.1:${PORT:-3000}/health || exit 1
 
-# Start the application in HTTP mode
+# Optimized entrypoint (identical to main Dockerfile)
+ENTRYPOINT ["/usr/local/bin/docker-entrypoint.sh"]
 CMD ["node", "dist/mcp/index.js", "--http"]

README.md

@@ -606,6 +606,7 @@ npm run dev:http       # HTTP dev mode
 - [Validation System](./docs/validation-improvements-v2.4.2.md) - Smart validation profiles
 
 ### Development & Deployment
+- [Railway Deployment](./docs/RAILWAY_DEPLOYMENT.md) - One-click cloud deployment guide
 - [HTTP Deployment](./docs/HTTP_DEPLOYMENT.md) - Remote server setup guide
 - [Dependency Management](./docs/DEPENDENCY_UPDATES.md) - Keeping n8n packages in sync
 - [Claude's Interview](./docs/CLAUDE_INTERVIEW.md) - Real-world impact of n8n-MCP

docs/RAILWAY_DEPLOYMENT.md

@@ -0,0 +1,247 @@
+# 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/Ep_b-Y?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:
+
+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
+
+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
+
+### 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 |
+
+### Optional: n8n API Integration
+
+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
+
+### 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.
+
+## 📝 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!

railway.json

@@ -1,10 +1,19 @@
 {
-  "name": "n8n-mcp",
+  "build": {
-  "services": [
+    "builder": "DOCKERFILE",
-    {
+    "dockerfilePath": "Dockerfile.railway"
-      "name": "n8n-mcp",
+  },
-      "source": ".",
+  "deploy": {
-      "dockerfilePath": "Dockerfile.railway"
+    "runtime": "V2",
-    }
+    "numReplicas": 1,
-  ]
+    "sleepApplication": false,
+    "restartPolicyType": "ON_FAILURE",
+    "restartPolicyMaxRetries": 10,
+    "volumes": [
+      {
+        "mount": "/app/data",
+        "name": "n8n-mcp-data"
+      }
+    ]
+  }
 }

src/http-server-single-session.ts

@@ -81,6 +81,20 @@ export class SingleSessionHTTPServer {
     if (this.authToken.length < 32) {
       logger.warn('AUTH_TOKEN should be at least 32 characters for security');
     }
+    
+    // Check for default token and show prominent warnings
+    if (this.authToken === 'REPLACE_THIS_AUTH_TOKEN_32_CHARS_MIN_abcdefgh') {
+      logger.warn('⚠️ SECURITY WARNING: Using default AUTH_TOKEN - CHANGE IMMEDIATELY!');
+      logger.warn('Generate secure token with: openssl rand -base64 32');
+      
+      // Only show console warnings in HTTP mode
+      if (process.env.MCP_MODE === 'http') {
+        console.warn('\n⚠️  SECURITY WARNING ⚠️');
+        console.warn('Using default AUTH_TOKEN - CHANGE IMMEDIATELY!');
+        console.warn('Generate secure token: openssl rand -base64 32');
+        console.warn('Update via Railway dashboard environment variables\n');
+      }
+    }
   }
   
   /**
@@ -420,6 +434,16 @@ export class SingleSessionHTTPServer {
       console.log(`MCP endpoint: ${endpoints.mcp}`);
       console.log('\nPress Ctrl+C to stop the server');
       
+      // Start periodic warning timer if using default token
+      if (this.authToken === 'REPLACE_THIS_AUTH_TOKEN_32_CHARS_MIN_abcdefgh') {
+        setInterval(() => {
+          logger.warn('⚠️ Still using default AUTH_TOKEN - security risk!');
+          if (process.env.MCP_MODE === 'http') {
+            console.warn('⚠️ REMINDER: Still using default AUTH_TOKEN - please change it!');
+          }
+        }, 300000); // Every 5 minutes
+      }
+      
       if (process.env.BASE_URL || process.env.PUBLIC_URL) {
         console.log(`\nPublic URL configured: ${baseUrl}`);
       } else if (process.env.TRUST_PROXY && Number(process.env.TRUST_PROXY) > 0) {

src/http-server.ts

@@ -69,6 +69,20 @@ function validateEnvironment() {
     logger.warn('AUTH_TOKEN should be at least 32 characters for security');
     console.warn('WARNING: AUTH_TOKEN should be at least 32 characters for security');
   }
+  
+  // Check for default token and show prominent warnings
+  if (authToken === 'REPLACE_THIS_AUTH_TOKEN_32_CHARS_MIN_abcdefgh') {
+    logger.warn('⚠️ SECURITY WARNING: Using default AUTH_TOKEN - CHANGE IMMEDIATELY!');
+    logger.warn('Generate secure token with: openssl rand -base64 32');
+    
+    // Only show console warnings in HTTP mode
+    if (process.env.MCP_MODE === 'http') {
+      console.warn('\n⚠️  SECURITY WARNING ⚠️');
+      console.warn('Using default AUTH_TOKEN - CHANGE IMMEDIATELY!');
+      console.warn('Generate secure token: openssl rand -base64 32');
+      console.warn('Update via Railway dashboard environment variables\n');
+    }
+  }
 }
 
 /**
@@ -486,6 +500,16 @@ export async function startFixedHTTPServer() {
     console.log(`MCP endpoint: ${endpoints.mcp}`);
     console.log('\nPress Ctrl+C to stop the server');
     
+    // Start periodic warning timer if using default token
+    if (authToken === 'REPLACE_THIS_AUTH_TOKEN_32_CHARS_MIN_abcdefgh') {
+      setInterval(() => {
+        logger.warn('⚠️ Still using default AUTH_TOKEN - security risk!');
+        if (process.env.MCP_MODE === 'http') {
+          console.warn('⚠️ REMINDER: Still using default AUTH_TOKEN - please change it!');
+        }
+      }, 300000); // Every 5 minutes
+    }
+    
     if (process.env.BASE_URL || process.env.PUBLIC_URL) {
       console.log(`\nPublic URL configured: ${baseUrl}`);
     } else if (process.env.TRUST_PROXY && Number(process.env.TRUST_PROXY) > 0) {