ros/n8n-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add release guide and improve Docker documentation structure

Browse Source
This commit is contained in:
czlonkowski
2025-06-14 10:00:14 +02:00
parent 8878c99c3b
commit d67c04dd52
5 changed files with 557 additions and 238 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.github/workflows/docker-build.yml vendored
View File

@@ -52,6 +52,7 @@ jobs:
type=ref,event=pr type=ref,event=pr
type=semver,pattern={{version}} type=semver,pattern={{version}}
type=semver,pattern={{major}}.{{minor}} type=semver,pattern={{major}}.{{minor}}
type=semver,pattern={{major}}
type=sha,prefix={{branch}}-,format=short type=sha,prefix={{branch}}-,format=short
type=raw,value=latest,enable={{is_default_branch}} type=raw,value=latest,enable={{is_default_branch}}

2
README.md
View File

@@ -133,7 +133,7 @@ To build the Docker image locally:
docker build -t n8n-mcp:local . docker build -t n8n-mcp:local .
``` ```
For detailed Docker documentation, see [DOCKER_README.md](./DOCKER_README.md). For detailed Docker documentation, see [Docker Deployment Guide](./docs/DOCKER_README.md).
## Usage ## Usage

618
docs/DOCKER_README.md
View File

@@ -2,97 +2,108 @@
This guide provides comprehensive instructions for deploying n8n-MCP using Docker. This guide provides comprehensive instructions for deploying n8n-MCP using Docker.
## Table of Contents ## 🚀 Quick Start
- [Quick Start](#quick-start) ### Prerequisites
- [Configuration](#configuration) - Docker Engine 20.10+ or Docker Desktop
- [Deployment Options](#deployment-options) - Docker Compose V2
- [Development Setup](#development-setup) - (Optional) openssl for generating auth tokens
- [Production Deployment](#production-deployment)
- [Troubleshooting](#troubleshooting)
## Quick Start ### 1. HTTP Server Mode (Recommended)
### Using Pre-built Images The simplest way to deploy n8n-MCP is using Docker Compose with HTTP mode:
The fastest way to get started is using our pre-built Docker images from GitHub Container Registry:
```bash ```bash
# 1. Create a .env file with your authentication token # Clone the repository
git clone https://github.com/czlonkowski/n8n-mcp.git
cd n8n-mcp
# Create .env file with auth token
echo "AUTH_TOKEN=$(openssl rand -base64 32)" > .env echo "AUTH_TOKEN=$(openssl rand -base64 32)" > .env
# 2. Start the container
docker compose up -d
# 3. Check it's running
docker compose ps
docker compose logs
```
### Building Locally
To build the image yourself:
```bash
# Build the image
docker build -t n8n-mcp:local .
# Run with docker compose (update image in docker-compose.yml first)
docker compose up -d
```
## Configuration
### Environment Variables
Create a `.env` file in the project root:
```bash
# Required for HTTP mode
AUTH_TOKEN=your-secure-token-here
# Server configuration
PORT=3000
NODE_ENV=production
LOG_LEVEL=info
# MCP mode (stdio or http)
MCP_MODE=http
# Database
NODE_DB_PATH=/app/data/nodes.db
REBUILD_ON_START=false
```
### Docker Compose Options
The project includes several Docker Compose configurations:
- `docker-compose.yml` - Production HTTP server
- `docker-compose.override.yml.example` - Development overrides template
- `docker-compose.nginx.yml` - HTTPS with nginx (Phase 2)
## Deployment Options
### Option 1: HTTP Server Mode
Best for remote access and integration with Claude Desktop via mcp-remote:
```bash
# Start the server # Start the server
docker compose up -d docker compose up -d
# Check logs
docker compose logs -f
# Test the health endpoint # Test the health endpoint
curl http://localhost:3000/health curl http://localhost:3000/health
# Test with authentication
curl -H "Authorization: Bearer $AUTH_TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/list","id":1}' \
http://localhost:3000/mcp
``` ```
Configure Claude Desktop: ### 2. Using Pre-built Images
Pre-built images are available on GitHub Container Registry:
```bash
# Pull the latest image
docker pull ghcr.io/czlonkowski/n8n-mcp:latest
# Run with HTTP mode
docker run -d \
--name n8n-mcp \
-e MCP_MODE=http \
-e AUTH_TOKEN=your-secure-token \
-p 3000:3000 \
-v n8n-mcp-data:/app/data \
ghcr.io/czlonkowski/n8n-mcp:latest
```
## 📋 Configuration Options
### Environment Variables
| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `MCP_MODE` | Server mode: `stdio` or `http` | `stdio` | No |
| `AUTH_TOKEN` | Bearer token for HTTP authentication | - | Yes (HTTP mode) |
| `PORT` | HTTP server port | `3000` | No |
| `NODE_ENV` | Environment: `development` or `production` | `production` | No |
| `LOG_LEVEL` | Logging level: `debug`, `info`, `warn`, `error` | `info` | No |
### Docker Compose Configuration
The default `docker-compose.yml` provides:
- Automatic restart on failure
- Named volume for data persistence
- Memory limits (512MB max, 256MB reserved)
- Health checks every 30 seconds
- Container labels for organization
### Custom Configuration
Create a `docker-compose.override.yml` for local customizations:
```yaml
# docker-compose.override.yml
services:
n8n-mcp:
ports:
- "8080:3000" # Use different port
environment:
LOG_LEVEL: debug
NODE_ENV: development
volumes:
- ./custom-data:/app/data # Use local directory
```
## 🔧 Usage Modes
### HTTP Mode (Remote Access)
Perfect for cloud deployments and remote access:
```bash
# Start in HTTP mode
docker run -d \
--name n8n-mcp-http \
-e MCP_MODE=http \
-e AUTH_TOKEN=your-secure-token \
-p 3000:3000 \
ghcr.io/czlonkowski/n8n-mcp:latest
```
Configure Claude Desktop with mcp-remote:
```json ```json
{ {
"mcpServers": { "mcpServers": {
@@ -102,20 +113,29 @@ Configure Claude Desktop:
"-y", "-y",
"@modelcontextprotocol/mcp-remote@latest", "@modelcontextprotocol/mcp-remote@latest",
"connect", "connect",
"http://localhost:3000/mcp" "http://your-server:3000/mcp"
], ],
"env": { "env": {
"MCP_AUTH_TOKEN": "your-auth-token-here" "MCP_AUTH_TOKEN": "your-secure-token"
} }
} }
} }
} }
``` ```
### Option 2: stdio Mode (Direct) ### Stdio Mode (Local Direct Access)
For local-only usage without network exposure: For local Claude Desktop integration without HTTP:
```bash
# Run in stdio mode (interactive)
docker run --rm -i \
-e MCP_MODE=stdio \
-v n8n-mcp-data:/app/data \
ghcr.io/czlonkowski/n8n-mcp:latest
```
Configure Claude Desktop:
```json ```json
{ {
"mcpServers": { "mcpServers": {
@@ -134,145 +154,142 @@ For local-only usage without network exposure:
} }
``` ```
### Option 3: HTTPS with nginx (Coming Soon) ## 🏗️ Building from Source
For production deployments with SSL/TLS: ### Build Locally
```bash ```bash
# Use the nginx-enhanced compose file # Clone repository
docker compose -f docker-compose.nginx.yml up -d git clone https://github.com/czlonkowski/n8n-mcp.git
cd n8n-mcp
# Build image
docker build -t n8n-mcp:local .
# Run your local build
docker run -d \
--name n8n-mcp-local \
-e MCP_MODE=http \
-e AUTH_TOKEN=test-token \
-p 3000:3000 \
n8n-mcp:local
``` ```
## Development Setup ### Multi-architecture Build
### Local Development with Docker Build for multiple platforms:
1. Copy the override template:
```bash ```bash
cp docker-compose.override.yml.example docker-compose.override.yml # Enable buildx
docker buildx create --use
# Build for amd64 and arm64
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t n8n-mcp:multiarch \
--load \
.
``` ```
2. Customize for your needs: ## 🔍 Health Monitoring
### Health Check Endpoint
The container includes a health check that runs every 30 seconds:
```bash
# Check health status
curl http://localhost:3000/health
```
Response example:
```json
{
"status": "healthy",
"uptime": 120.5,
"memory": {
"used": "8.5 MB",
"rss": "45.2 MB",
"external": "1.2 MB"
},
"version": "2.3.0",
"mode": "http",
"database": {
"adapter": "better-sqlite3",
"ready": true
}
}
```
### Docker Health Status
```bash
# Check container health
docker ps --format "table {{.Names}}\t{{.Status}}"
# View health check logs
docker inspect n8n-mcp | jq '.[0].State.Health'
```
## 🔒 Security Considerations
### Authentication
- Always use a strong AUTH_TOKEN (minimum 32 characters)
- Never commit tokens to version control
- Rotate tokens regularly
```bash
# Generate secure token
openssl rand -base64 32
# Or use uuidgen
uuidgen | tr -d '-' | base64
```
### Network Security
For production deployments:
1. **Use HTTPS** - Put a reverse proxy (nginx, Caddy) in front
2. **Firewall** - Restrict access to trusted IPs only
3. **VPN** - Consider VPN access for internal use
Example with Caddy:
```
your-domain.com {
reverse_proxy n8n-mcp:3000
basicauth * {
admin $2a$14$... # bcrypt hash
}
}
```
### Container Security
- Runs as non-root user (uid 1001)
- Read-only root filesystem compatible
- No unnecessary packages installed
- Regular security updates via GitHub Actions
## 📊 Resource Management
### Memory Limits
Default limits in docker-compose.yml:
- Maximum: 512MB
- Reserved: 256MB
Adjust based on your needs:
```yaml ```yaml
# docker-compose.override.yml
version: '3.8'
services: services:
n8n-mcp: n8n-mcp:
build: . # Build locally instead of using pre-built
environment:
NODE_ENV: development
LOG_LEVEL: debug
REBUILD_ON_START: "true"
volumes:
# Mount source for development
- ./src:/app/src:ro
- ./scripts:/app/scripts:ro
- ./dist:/app/dist:rw
```
3. Start in development mode:
```bash
docker compose up --build
```
### Testing Docker Builds
Run the test script to validate your Docker setup:
```bash
./scripts/test-docker.sh
```
This script will:
- Build the Docker image
- Test stdio mode functionality
- Test HTTP mode with authentication
- Verify volume persistence
- Check health endpoints
## Production Deployment
### Security Considerations
1. **Authentication**: Always set a strong `AUTH_TOKEN`:
```bash
openssl rand -base64 32
```
2. **Network Security**: Consider using a reverse proxy (nginx, Traefik) for:
- SSL/TLS termination
- Rate limiting
- Access control
3. **Resource Limits**: The compose file includes memory limits:
```yaml
deploy: deploy:
resources: resources:
limits: limits:
memory: 512M memory: 1G
reservations: reservations:
memory: 256M memory: 512M
```
### Deployment Checklist
- [ ] Generate secure AUTH_TOKEN
- [ ] Configure environment variables
- [ ] Set up volume backups for `/app/data`
- [ ] Configure monitoring/logging
- [ ] Set up SSL/TLS (if exposing publicly)
- [ ] Test health endpoints
- [ ] Verify Claude Desktop connectivity
### Multi-Architecture Support
The images support both amd64 and arm64 architectures:
```bash
# The correct architecture is automatically selected
docker pull ghcr.io/czlonkowski/n8n-mcp:latest
```
## Troubleshooting
### Common Issues
#### Container fails to start
```bash
# Check logs
docker compose logs -f
# Verify environment variables
docker compose config
# Check file permissions
docker compose exec n8n-mcp ls -la /app/data
```
#### Database initialization fails
```bash
# Manually initialize
docker compose exec n8n-mcp node dist/scripts/rebuild.js
# Check database file
docker compose exec n8n-mcp ls -la /app/data/nodes.db
```
#### Authentication errors
```bash
# Verify token is set
echo $AUTH_TOKEN
# Test with curl
curl -v -H "Authorization: Bearer $AUTH_TOKEN" http://localhost:3000/health
```
### Debug Mode
Enable debug logging:
```bash
LOG_LEVEL=debug docker compose up
``` ```
### Volume Management ### Volume Management
@@ -284,42 +301,179 @@ docker volume ls | grep n8n-mcp
# Inspect volume # Inspect volume
docker volume inspect n8n-mcp-data docker volume inspect n8n-mcp-data
# Remove volume (WARNING: deletes data) # Backup data
docker compose down -v docker run --rm \
-v n8n-mcp-data:/source:ro \
-v $(pwd):/backup \
alpine tar czf /backup/n8n-mcp-backup.tar.gz -C /source .
# Restore data
docker run --rm \
-v n8n-mcp-data:/target \
-v $(pwd):/backup:ro \
alpine tar xzf /backup/n8n-mcp-backup.tar.gz -C /target
``` ```
## Advanced Configuration ## 🐛 Troubleshooting
### Custom Certificates (Phase 2) ### Common Issues
For the nginx-enhanced version: #### Container Exits Immediately
```yaml
volumes:
- ./certs/server.crt:/app/certs/server.crt:ro
- ./certs/server.key:/app/certs/server.key:ro
```
### Database Persistence
The SQLite database is stored in a named volume for persistence:
```yaml
volumes:
n8n-mcp-data:
driver: local
```
To backup:
```bash ```bash
docker run --rm -v n8n-mcp-data:/data -v $(pwd):/backup alpine \ # Check logs
tar czf /backup/n8n-mcp-backup.tar.gz -C /data . docker logs n8n-mcp
# Common causes:
# - Missing AUTH_TOKEN in HTTP mode
# - Database initialization failure
# - Port already in use
``` ```
## Next Steps #### Database Not Initialized
```bash
# Manually initialize database
docker exec n8n-mcp node dist/scripts/rebuild.js
- Check [GitHub Releases](https://github.com/czlonkowski/n8n-mcp/releases) for updates # Or recreate container with fresh volume
- Report issues at [GitHub Issues](https://github.com/czlonkowski/n8n-mcp/issues) docker compose down -v
- Join discussions in [GitHub Discussions](https://github.com/czlonkowski/n8n-mcp/discussions) docker compose up -d
```
## License #### Permission Errors
```bash
# Fix volume permissions
docker exec n8n-mcp chown -R nodejs:nodejs /app/data
```
This project uses the Sustainable Use License. See [LICENSE](./LICENSE) for details. ### Debug Mode
Enable debug logging:
```bash
docker run -d \
--name n8n-mcp-debug \
-e MCP_MODE=http \
-e AUTH_TOKEN=test \
-e LOG_LEVEL=debug \
-p 3000:3000 \
ghcr.io/czlonkowski/n8n-mcp:latest
```
### Container Shell Access
```bash
# Access running container
docker exec -it n8n-mcp sh
# Run as root for debugging
docker exec -it -u root n8n-mcp sh
```
## 🚀 Production Deployment
### Recommended Setup
1. **Use Docker Compose** for easier management
2. **Enable HTTPS** with reverse proxy
3. **Set up monitoring** (Prometheus, Grafana)
4. **Configure backups** for the data volume
5. **Use secrets management** for AUTH_TOKEN
### Example Production Stack
```yaml
# docker-compose.prod.yml
services:
n8n-mcp:
image: ghcr.io/czlonkowski/n8n-mcp:latest
restart: always
environment:
MCP_MODE: http
AUTH_TOKEN_FILE: /run/secrets/auth_token
NODE_ENV: production
secrets:
- auth_token
networks:
- internal
deploy:
resources:
limits:
memory: 1G
reservations:
memory: 512M
nginx:
image: nginx:alpine
restart: always
ports:
- "443:443"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf:ro
- ./certs:/etc/nginx/certs:ro
networks:
- internal
- external
networks:
internal:
external:
secrets:
auth_token:
file: ./secrets/auth_token.txt
```
## 📦 Available Images
- `ghcr.io/czlonkowski/n8n-mcp:latest` - Latest stable release
- `ghcr.io/czlonkowski/n8n-mcp:2.3.0` - Specific version
- `ghcr.io/czlonkowski/n8n-mcp:main-abc123` - Development builds
### Image Details
- Base: `node:20-alpine`
- Size: ~150MB compressed
- Architectures: `linux/amd64`, `linux/arm64`
- Updated: Automatically via GitHub Actions
## 🔄 Updates and Maintenance
### Updating
```bash
# Pull latest image
docker compose pull
# Recreate container
docker compose up -d
# View update logs
docker compose logs -f
```
### Automatic Updates (Watchtower)
```yaml
# Add to docker-compose.yml
services:
watchtower:
image: containrrr/watchtower
volumes:
- /var/run/docker.sock:/var/run/docker.sock
command: --interval 86400 n8n-mcp
```
## 📚 Additional Resources
- [Main Documentation](./docs/README.md)
- [HTTP Deployment Guide](./docs/HTTP_DEPLOYMENT.md)
- [Troubleshooting Guide](./docs/TROUBLESHOOTING.md)
- [Installation Guide](./docs/INSTALLATION.md)
## 🤝 Support
- Issues: [GitHub Issues](https://github.com/czlonkowski/n8n-mcp/issues)
- Discussions: [GitHub Discussions](https://github.com/czlonkowski/n8n-mcp/discussions)
---
*Last updated: June 2025 - Docker implementation v1.0*

3
docs/README.md
View File

@@ -11,13 +11,14 @@ Welcome to the n8n-MCP documentation. This directory contains comprehensive guid
### Deployment ### Deployment
- **[HTTP Deployment Guide](./HTTP_DEPLOYMENT.md)** - Deploy n8n-MCP as an HTTP server for remote access - **[HTTP Deployment Guide](./HTTP_DEPLOYMENT.md)** - Deploy n8n-MCP as an HTTP server for remote access
- **[Docker Deployment](../DOCKER_README.md)** - Comprehensive Docker deployment guide - **[Docker Deployment](./DOCKER_README.md)** - Comprehensive Docker deployment guide
- **[Docker Testing Results](./DOCKER_TESTING_RESULTS.md)** - Docker implementation test results and findings - **[Docker Testing Results](./DOCKER_TESTING_RESULTS.md)** - Docker implementation test results and findings
### Development ### Development
- **[Implementation Plan](../IMPLEMENTATION_PLAN.md)** - Technical implementation details - **[Implementation Plan](../IMPLEMENTATION_PLAN.md)** - Technical implementation details
- **[HTTP Implementation Guide](./HTTP_IMPLEMENTATION_GUIDE.md)** - HTTP server implementation details - **[HTTP Implementation Guide](./HTTP_IMPLEMENTATION_GUIDE.md)** - HTTP server implementation details
- **[Development Setup](./INSTALLATION.md#development-setup)** - Set up development environment - **[Development Setup](./INSTALLATION.md#development-setup)** - Set up development environment
- **[Release Guide](./RELEASE_GUIDE.md)** - How to create releases and manage Docker tags
### Reference ### Reference
- **[Troubleshooting Guide](./TROUBLESHOOTING.md)** - Solutions for common issues - **[Troubleshooting Guide](./TROUBLESHOOTING.md)** - Solutions for common issues

163
docs/RELEASE_GUIDE.md Normal file
View File

@@ -0,0 +1,163 @@
# Release Guide
This guide explains how to create releases for n8n-MCP and how Docker tags are managed.
## Version Tag Strategy
When you create a Git tag starting with `v`, the GitHub Actions workflow automatically builds and pushes Docker images with the following tags:
### Example: Creating Release v1.2.3
```bash
# Create and push a version tag
git tag -a v1.2.3 -m "Release version 1.2.3"
git push origin v1.2.3
```
This will automatically create the following Docker tags:
- `ghcr.io/czlonkowski/n8n-mcp:1.2.3` (exact version)
- `ghcr.io/czlonkowski/n8n-mcp:1.2` (minor version)
- `ghcr.io/czlonkowski/n8n-mcp:1` (major version)
- `ghcr.io/czlonkowski/n8n-mcp:latest` (if from main branch)
## Tag Types Explained
### Latest Tag
- **When**: Every push to main branch
- **Usage**: Default tag for users who want the latest stable version
- **Example**: `docker pull ghcr.io/czlonkowski/n8n-mcp:latest`
### Version Tags
- **When**: When you create a Git tag like `v1.2.3`
- **Usage**: Users who want a specific version
- **Example**: `docker pull ghcr.io/czlonkowski/n8n-mcp:1.2.3`
### Branch Tags
- **When**: Every push to a branch
- **Usage**: Testing specific branches
- **Example**: `docker pull ghcr.io/czlonkowski/n8n-mcp:main`
### SHA Tags
- **When**: Every commit
- **Usage**: Debugging specific commits
- **Example**: `docker pull ghcr.io/czlonkowski/n8n-mcp:main-abc123`
## Release Process
### 1. Prepare Release
```bash
# Update version in package.json
npm version patch # or minor/major
# Update CHANGELOG.md
echo "## v1.2.3 - $(date +%Y-%m-%d)" >> CHANGELOG.md
echo "- Feature: Added X" >> CHANGELOG.md
echo "- Fix: Fixed Y" >> CHANGELOG.md
# Commit changes
git add -A
git commit -m "chore: prepare release v1.2.3"
git push origin main
```
### 2. Create Release Tag
```bash
# Create annotated tag
git tag -a v1.2.3 -m "Release v1.2.3
- Feature: Added X
- Fix: Fixed Y"
# Push tag to trigger Docker build
git push origin v1.2.3
```
### 3. Create GitHub Release
```bash
# Using GitHub CLI
gh release create v1.2.3 \
--title "Release v1.2.3" \
--notes "See CHANGELOG.md for details" \
--latest
```
### 4. Verify Docker Images
```bash
# Wait for GitHub Actions to complete, then verify
docker pull ghcr.io/czlonkowski/n8n-mcp:1.2.3
docker pull ghcr.io/czlonkowski/n8n-mcp:latest
# Test the new version
docker run --rm ghcr.io/czlonkowski/n8n-mcp:1.2.3 --version
```
## Semantic Versioning
Follow [Semantic Versioning](https://semver.org/):
- **MAJOR** (1.0.0 → 2.0.0): Breaking changes
- **MINOR** (1.0.0 → 1.1.0): New features, backwards compatible
- **PATCH** (1.0.0 → 1.0.1): Bug fixes, backwards compatible
### Examples:
- Breaking API change → v2.0.0
- New MCP tool added → v1.1.0
- Bug fix in parser → v1.0.1
## Pre-releases
For testing releases:
```bash
# Create pre-release tag
git tag -a v1.2.3-beta.1 -m "Beta release"
git push origin v1.2.3-beta.1
```
This creates:
- `ghcr.io/czlonkowski/n8n-mcp:1.2.3-beta.1`
## Docker Compose Updates
When releasing, update documentation to reference specific versions:
```yaml
# Stable version (recommended for production)
services:
n8n-mcp:
image: ghcr.io/czlonkowski/n8n-mcp:1.2
# Latest version (for development/testing)
services:
n8n-mcp:
image: ghcr.io/czlonkowski/n8n-mcp:latest
```
## Best Practices
1. **Always test** before creating a release tag
2. **Update documentation** to reference new versions
3. **Use annotated tags** (`-a` flag) with descriptive messages
4. **Follow semver** for version numbers
5. **Update CHANGELOG.md** with every release
## Rollback Process
If a release has issues:
```bash
# Users can pin to previous version
docker pull ghcr.io/czlonkowski/n8n-mcp:1.1.0
# Or use minor version for automatic patches
docker pull ghcr.io/czlonkowski/n8n-mcp:1.1
```
## Checking Available Tags
```bash
# Using Docker Hub API (for public registries)
curl -s https://ghcr.io/v2/czlonkowski/n8n-mcp/tags/list
# Or check GitHub packages page
# https://github.com/czlonkowski/n8n-mcp/pkgs/container/n8n-mcp
```