mirrors/mcphub
1
0
Fork 0
mirror of https://github.com/samanhappy/mcphub.git synced 2025-12-24 02:39:19 -05:00
Code Issues Packages Projects Releases Wiki Activity

generate documents using mintlify (#153)

Browse Source
This commit is contained in:
samanhappy
2025-06-01 00:17:09 +08:00
committed by GitHub
parent 65c95aaa0b
commit 9675cd8533
40 changed files with 18018 additions and 165 deletions
Download Patch File Download Diff File Expand all files Collapse all files

539
docs/configuration/docker-setup.mdx Normal file
View File

@@ -0,0 +1,539 @@
---
title: 'Docker Setup'
description: 'Deploy MCPHub using Docker and Docker Compose'
---
# Docker Setup
This guide covers deploying MCPHub using Docker, including development and production configurations.
## Quick Start with Docker
### Using Pre-built Image
```bash
# Pull the latest image
docker pull mcphub/mcphub:latest
# Run with default configuration
docker run -d \
--name mcphub \
-p 3000:3000 \
-v $(pwd)/mcp_settings.json:/app/mcp_settings.json \
mcphub/mcphub:latest
```
### Building from Source
```bash
# Clone the repository
git clone https://github.com/your-username/mcphub.git
cd mcphub
# Build the Docker image
docker build -t mcphub:local .
# Run the container
docker run -d \
--name mcphub \
-p 3000:3000 \
-v $(pwd)/mcp_settings.json:/app/mcp_settings.json \
mcphub:local
```
## Docker Compose Setup
### Basic Configuration
Create a `docker-compose.yml` file:
```yaml
version: '3.8'
services:
mcphub:
image: mcphub/mcphub:latest
# For local development, use:
# build: .
container_name: mcphub
ports:
- '3000:3000'
environment:
- NODE_ENV=production
- PORT=3000
- JWT_SECRET=${JWT_SECRET:-your-jwt-secret}
- DATABASE_URL=postgresql://mcphub:password@postgres:5432/mcphub
volumes:
- ./mcp_settings.json:/app/mcp_settings.json:ro
- ./servers.json:/app/servers.json:ro
- mcphub_data:/app/data
depends_on:
postgres:
condition: service_healthy
restart: unless-stopped
networks:
- mcphub-network
postgres:
image: postgres:15-alpine
container_name: mcphub-postgres
environment:
- POSTGRES_DB=mcphub
- POSTGRES_USER=mcphub
- POSTGRES_PASSWORD=password
volumes:
- postgres_data:/var/lib/postgresql/data
- ./scripts/init-db.sql:/docker-entrypoint-initdb.d/init-db.sql:ro
ports:
- '5432:5432'
healthcheck:
test: ['CMD-SHELL', 'pg_isready -U mcphub -d mcphub']
interval: 10s
timeout: 5s
retries: 5
restart: unless-stopped
networks:
- mcphub-network
volumes:
postgres_data:
mcphub_data:
networks:
mcphub-network:
driver: bridge
```
### Production Configuration with Nginx
```yaml
version: '3.8'
services:
nginx:
image: nginx:alpine
container_name: mcphub-nginx
ports:
- '80:80'
- '443:443'
volumes:
- ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
- ./ssl:/etc/nginx/ssl:ro
- nginx_logs:/var/log/nginx
depends_on:
- mcphub
restart: unless-stopped
networks:
- mcphub-network
mcphub:
image: mcphub/mcphub:latest
container_name: mcphub-app
expose:
- '3000'
environment:
- NODE_ENV=production
- PORT=3000
- JWT_SECRET=${JWT_SECRET}
- JWT_EXPIRES_IN=${JWT_EXPIRES_IN:-24h}
- DATABASE_URL=postgresql://mcphub:${POSTGRES_PASSWORD}@postgres:5432/mcphub
- OPENAI_API_KEY=${OPENAI_API_KEY}
- REDIS_URL=redis://redis:6379
volumes:
- ./mcp_settings.json:/app/mcp_settings.json:ro
- ./servers.json:/app/servers.json:ro
- mcphub_data:/app/data
- mcphub_logs:/app/logs
depends_on:
postgres:
condition: service_healthy
redis:
condition: service_healthy
restart: unless-stopped
networks:
- mcphub-network
healthcheck:
test: ['CMD', 'wget', '--quiet', '--tries=1', '--spider', 'http://localhost:3000/health']
interval: 30s
timeout: 10s
retries: 3
postgres:
image: postgres:15-alpine
container_name: mcphub-postgres
environment:
- POSTGRES_DB=mcphub
- POSTGRES_USER=mcphub
- POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
volumes:
- postgres_data:/var/lib/postgresql/data
- ./backups:/backups
healthcheck:
test: ['CMD-SHELL', 'pg_isready -U mcphub -d mcphub']
interval: 10s
timeout: 5s
retries: 5
restart: unless-stopped
networks:
- mcphub-network
redis:
image: redis:7-alpine
container_name: mcphub-redis
command: redis-server --appendonly yes --requirepass ${REDIS_PASSWORD}
volumes:
- redis_data:/data
healthcheck:
test: ['CMD', 'redis-cli', 'ping']
interval: 10s
timeout: 5s
retries: 5
restart: unless-stopped
networks:
- mcphub-network
volumes:
postgres_data:
redis_data:
mcphub_data:
mcphub_logs:
nginx_logs:
networks:
mcphub-network:
driver: bridge
```
### Environment Variables
Create a `.env` file for Docker Compose:
```env
# Application
NODE_ENV=production
JWT_SECRET=your-super-secret-jwt-key-change-this
JWT_EXPIRES_IN=24h
# Database
POSTGRES_PASSWORD=your-secure-database-password
# Redis
REDIS_PASSWORD=your-secure-redis-password
# External APIs
OPENAI_API_KEY=your-openai-api-key
# Optional: Custom port
# PORT=3000
```
## Development Setup
### Development Docker Compose
Create `docker-compose.dev.yml`:
```yaml
version: '3.8'
services:
mcphub-dev:
build:
context: .
dockerfile: Dockerfile.dev
container_name: mcphub-dev
ports:
- '3000:3000'
- '5173:5173' # Frontend dev server
- '9229:9229' # Debug port
environment:
- NODE_ENV=development
- PORT=3000
- DATABASE_URL=postgresql://mcphub:password@postgres:5432/mcphub
volumes:
- .:/app
- /app/node_modules
- /app/frontend/node_modules
depends_on:
- postgres
command: pnpm dev
networks:
- mcphub-dev
postgres:
image: postgres:15-alpine
container_name: mcphub-postgres-dev
environment:
- POSTGRES_DB=mcphub
- POSTGRES_USER=mcphub
- POSTGRES_PASSWORD=password
ports:
- '5432:5432'
volumes:
- postgres_dev_data:/var/lib/postgresql/data
networks:
- mcphub-dev
volumes:
postgres_dev_data:
networks:
mcphub-dev:
driver: bridge
```
### Development Dockerfile
Create `Dockerfile.dev`:
```dockerfile
FROM node:20-alpine
# Install pnpm
RUN npm install -g pnpm
# Set working directory
WORKDIR /app
# Copy package files
COPY package.json pnpm-lock.yaml ./
COPY frontend/package.json ./frontend/
# Install dependencies
RUN pnpm install
# Copy source code
COPY . .
# Expose ports
EXPOSE 3000 5173 9229
# Start development server
CMD ["pnpm", "dev"]
```
## Running the Application
### Development Mode
```bash
# Start development environment
docker-compose -f docker-compose.dev.yml up -d
# View logs
docker-compose -f docker-compose.dev.yml logs -f mcphub-dev
# Stop development environment
docker-compose -f docker-compose.dev.yml down
```
### Production Mode
```bash
# Start production environment
docker-compose up -d
# View logs
docker-compose logs -f mcphub
# Stop production environment
docker-compose down
```
## Configuration Management
### MCP Settings Volume Mount
Create your `mcp_settings.json`:
```json
{
"mcpServers": {
"fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"]
},
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest", "--headless"]
},
"amap": {
"command": "npx",
"args": ["-y", "@amap/amap-maps-mcp-server"],
"env": {
"AMAP_MAPS_API_KEY": "your-api-key"
}
}
}
}
```
### Secrets Management
For production, use Docker secrets:
```yaml
version: '3.8'
services:
mcphub:
image: mcphub/mcphub:latest
environment:
- JWT_SECRET_FILE=/run/secrets/jwt_secret
- DATABASE_PASSWORD_FILE=/run/secrets/db_password
secrets:
- jwt_secret
- db_password
secrets:
jwt_secret:
file: ./secrets/jwt_secret.txt
db_password:
file: ./secrets/db_password.txt
```
## Data Persistence
### Database Backups
Add backup service to your `docker-compose.yml`:
```yaml
services:
backup:
image: postgres:15-alpine
container_name: mcphub-backup
environment:
- PGPASSWORD=${POSTGRES_PASSWORD}
volumes:
- ./backups:/backups
- ./scripts/backup.sh:/backup.sh:ro
command: /bin/sh -c "chmod +x /backup.sh && /backup.sh"
depends_on:
- postgres
profiles:
- backup
networks:
- mcphub-network
```
Create `scripts/backup.sh`:
```bash
#!/bin/sh
BACKUP_FILE="/backups/mcphub_$(date +%Y%m%d_%H%M%S).sql"
pg_dump -h postgres -U mcphub -d mcphub > "$BACKUP_FILE"
echo "Backup created: $BACKUP_FILE"
# Keep only last 7 days of backups
find /backups -name "mcphub_*.sql" -mtime +7 -delete
```
Run backup:
```bash
docker-compose --profile backup run --rm backup
```
## Monitoring and Health Checks
### Health Check Endpoint
Add to your application:
```javascript
// In your Express app
app.get('/health', (req, res) => {
res.json({
status: 'healthy',
timestamp: new Date().toISOString(),
uptime: process.uptime(),
memory: process.memoryUsage(),
version: process.env.npm_package_version,
});
});
```
### Docker Health Checks
```yaml
services:
mcphub:
# ... other config
healthcheck:
test: ['CMD', 'wget', '--quiet', '--tries=1', '--spider', 'http://localhost:3000/health']
interval: 30s
timeout: 10s
retries: 3
start_period: 60s
```
### Monitoring with Watchtower
Add automatic updates:
```yaml
services:
watchtower:
image: containrrr/watchtower
container_name: mcphub-watchtower
volumes:
- /var/run/docker.sock:/var/run/docker.sock
environment:
- WATCHTOWER_CLEANUP=true
- WATCHTOWER_POLL_INTERVAL=3600
- WATCHTOWER_INCLUDE_STOPPED=true
restart: unless-stopped
```
## Troubleshooting
### Common Issues
**Container fails to start**: Check logs with `docker-compose logs mcphub`
**Database connection errors**: Ensure PostgreSQL is healthy and accessible
**Port conflicts**: Check if ports 3000/5432 are already in use
**Volume mount issues**: Verify file paths and permissions
### Debug Commands
```bash
# Check container status
docker-compose ps
# View logs
docker-compose logs -f [service_name]
# Execute commands in container
docker-compose exec mcphub sh
# Check database connection
docker-compose exec postgres psql -U mcphub -d mcphub
# Restart specific service
docker-compose restart mcphub
# Rebuild and restart
docker-compose up --build -d
```
### Performance Optimization
```yaml
services:
mcphub:
# ... other config
deploy:
resources:
limits:
memory: 512M
cpus: '0.5'
reservations:
memory: 256M
cpus: '0.25'
```
This Docker setup provides a complete containerized environment for MCPHub with development and production configurations.

389
docs/configuration/environment-variables.mdx Normal file
View File

@@ -0,0 +1,389 @@
---
title: 'Environment Variables'
description: 'Configure MCPHub using environment variables'
---
# Environment Variables
MCPHub uses environment variables for configuration. This guide covers all available variables and their usage.
## Core Application Settings
### Server Configuration
| Variable | Default | Description |
| ----------- | ------------- | ------------------------------------------------------------- |
| `PORT` | `3000` | Port number for the HTTP server |
| `HOST` | `0.0.0.0` | Host address to bind the server |
| `NODE_ENV` | `development` | Application environment (`development`, `production`, `test`) |
| `LOG_LEVEL` | `info` | Logging level (`error`, `warn`, `info`, `debug`) |
```env
PORT=3000
HOST=0.0.0.0
NODE_ENV=production
LOG_LEVEL=info
```
### Database Configuration
| Variable | Default | Description |
| -------------- | ----------- | ---------------------------------- |
| `DATABASE_URL` | - | PostgreSQL connection string |
| `DB_HOST` | `localhost` | Database host |
| `DB_PORT` | `5432` | Database port |
| `DB_NAME` | `mcphub` | Database name |
| `DB_USER` | `mcphub` | Database username |
| `DB_PASSWORD` | - | Database password |
| `DB_SSL` | `false` | Enable SSL for database connection |
| `DB_POOL_MIN` | `2` | Minimum database pool size |
| `DB_POOL_MAX` | `10` | Maximum database pool size |
```env
# Option 1: Full connection string
DATABASE_URL=postgresql://username:password@localhost:5432/mcphub
# Option 2: Individual components
DB_HOST=localhost
DB_PORT=5432
DB_NAME=mcphub
DB_USER=mcphub
DB_PASSWORD=your-password
DB_SSL=false
```
## Authentication & Security
### JWT Configuration
| Variable | Default | Description |
| ------------------------ | ------- | ------------------------------------------- |
| `JWT_SECRET` | - | Secret key for JWT token signing (required) |
| `JWT_EXPIRES_IN` | `24h` | JWT token expiration time |
| `JWT_REFRESH_EXPIRES_IN` | `7d` | Refresh token expiration time |
| `JWT_ALGORITHM` | `HS256` | JWT signing algorithm |
```env
JWT_SECRET=your-super-secret-key-change-this-in-production
JWT_EXPIRES_IN=24h
JWT_REFRESH_EXPIRES_IN=7d
```
### Session & Security
| Variable | Default | Description |
| ------------------- | ------- | ------------------------------- |
| `SESSION_SECRET` | - | Session encryption secret |
| `BCRYPT_ROUNDS` | `12` | bcrypt hashing rounds |
| `RATE_LIMIT_WINDOW` | `15` | Rate limiting window in minutes |
| `RATE_LIMIT_MAX` | `100` | Maximum requests per window |
| `CORS_ORIGIN` | `*` | Allowed CORS origins |
```env
SESSION_SECRET=your-session-secret
BCRYPT_ROUNDS=12
RATE_LIMIT_WINDOW=15
RATE_LIMIT_MAX=100
CORS_ORIGIN=https://your-domain.com,https://admin.your-domain.com
```
## External Services
### OpenAI Configuration
| Variable | Default | Description |
| ------------------------ | ------------------------ | -------------------------------- |
| `OPENAI_API_KEY` | - | OpenAI API key for smart routing |
| `OPENAI_MODEL` | `gpt-3.5-turbo` | OpenAI model for embeddings |
| `OPENAI_EMBEDDING_MODEL` | `text-embedding-ada-002` | Model for vector embeddings |
| `OPENAI_MAX_TOKENS` | `1000` | Maximum tokens per request |
| `OPENAI_TEMPERATURE` | `0.1` | Temperature for AI responses |
```env
OPENAI_API_KEY=sk-your-openai-api-key
OPENAI_MODEL=gpt-3.5-turbo
OPENAI_EMBEDDING_MODEL=text-embedding-ada-002
OPENAI_MAX_TOKENS=1000
OPENAI_TEMPERATURE=0.1
```
### Redis Configuration (Optional)
| Variable | Default | Description |
| ---------------- | ----------- | ----------------------- |
| `REDIS_URL` | - | Redis connection string |
| `REDIS_HOST` | `localhost` | Redis host |
| `REDIS_PORT` | `6379` | Redis port |
| `REDIS_PASSWORD` | - | Redis password |
| `REDIS_DB` | `0` | Redis database number |
| `REDIS_PREFIX` | `mcphub:` | Key prefix for Redis |
```env
# Option 1: Full connection string
REDIS_URL=redis://username:password@localhost:6379/0
# Option 2: Individual components
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=your-redis-password
REDIS_DB=0
REDIS_PREFIX=mcphub:
```
## MCP Server Configuration
### Default Settings
| Variable | Default | Description |
| ------------------- | ------------------- | -------------------------------------------- |
| `MCP_SETTINGS_FILE` | `mcp_settings.json` | Path to MCP settings file |
| `MCP_SERVERS_FILE` | `servers.json` | Path to servers configuration |
| `MCP_TIMEOUT` | `30000` | Default timeout for MCP operations (ms) |
| `MCP_MAX_RETRIES` | `3` | Maximum retry attempts for failed operations |
| `MCP_RESTART_DELAY` | `5000` | Delay before restarting failed servers (ms) |
```env
MCP_SETTINGS_FILE=./config/mcp_settings.json
MCP_SERVERS_FILE=./config/servers.json
MCP_TIMEOUT=30000
MCP_MAX_RETRIES=3
MCP_RESTART_DELAY=5000
```
### Smart Routing
| Variable | Default | Description |
| --------------------------- | ------- | -------------------------------- |
| `SMART_ROUTING_ENABLED` | `true` | Enable AI-powered smart routing |
| `SMART_ROUTING_THRESHOLD` | `0.7` | Similarity threshold for routing |
| `SMART_ROUTING_MAX_RESULTS` | `5` | Maximum tools to return |
| `VECTOR_CACHE_TTL` | `3600` | Vector cache TTL in seconds |
```env
SMART_ROUTING_ENABLED=true
SMART_ROUTING_THRESHOLD=0.7
SMART_ROUTING_MAX_RESULTS=5
VECTOR_CACHE_TTL=3600
```
## File Storage & Uploads
| Variable | Default | Description |
| -------------------- | ---------------- | ----------------------------------- |
| `UPLOAD_DIR` | `./uploads` | Directory for file uploads |
| `MAX_FILE_SIZE` | `10485760` | Maximum file size in bytes (10MB) |
| `ALLOWED_FILE_TYPES` | `image/*,text/*` | Allowed MIME types |
| `STORAGE_TYPE` | `local` | Storage type (`local`, `s3`, `gcs`) |
```env
UPLOAD_DIR=./data/uploads
MAX_FILE_SIZE=10485760
ALLOWED_FILE_TYPES=image/*,text/*,application/json
STORAGE_TYPE=local
```
### S3 Storage (Optional)
| Variable | Default | Description |
| ---------------------- | ----------- | ------------------ |
| `S3_BUCKET` | - | S3 bucket name |
| `S3_REGION` | `us-east-1` | S3 region |
| `S3_ACCESS_KEY_ID` | - | S3 access key |
| `S3_SECRET_ACCESS_KEY` | - | S3 secret key |
| `S3_ENDPOINT` | - | Custom S3 endpoint |
```env
S3_BUCKET=mcphub-uploads
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=your-access-key
S3_SECRET_ACCESS_KEY=your-secret-key
```
## Monitoring & Logging
### Application Monitoring
| Variable | Default | Description |
| ------------------------ | ------- | ----------------------------- |
| `METRICS_ENABLED` | `true` | Enable metrics collection |
| `METRICS_PORT` | `9090` | Port for metrics endpoint |
| `HEALTH_CHECK_INTERVAL` | `30000` | Health check interval (ms) |
| `PERFORMANCE_MONITORING` | `false` | Enable performance monitoring |
```env
METRICS_ENABLED=true
METRICS_PORT=9090
HEALTH_CHECK_INTERVAL=30000
PERFORMANCE_MONITORING=true
```
### Logging Configuration
| Variable | Default | Description |
| ------------------ | ------------ | --------------------------------------- |
| `LOG_FORMAT` | `json` | Log format (`json`, `text`) |
| `LOG_FILE` | - | Log file path (if file logging enabled) |
| `LOG_MAX_SIZE` | `10m` | Maximum log file size |
| `LOG_MAX_FILES` | `5` | Maximum number of log files |
| `LOG_DATE_PATTERN` | `YYYY-MM-DD` | Date pattern for log rotation |
```env
LOG_FORMAT=json
LOG_FILE=./logs/mcphub.log
LOG_MAX_SIZE=10m
LOG_MAX_FILES=5
LOG_DATE_PATTERN=YYYY-MM-DD
```
## Development & Debug
| Variable | Default | Description |
| ------------------------ | ------- | ----------------------------------- |
| `DEBUG` | - | Debug namespaces (e.g., `mcphub:*`) |
| `DEV_TOOLS_ENABLED` | `false` | Enable development tools |
| `HOT_RELOAD` | `true` | Enable hot reload in development |
| `MOCK_EXTERNAL_SERVICES` | `false` | Mock external API calls |
```env
DEBUG=mcphub:*
DEV_TOOLS_ENABLED=true
HOT_RELOAD=true
MOCK_EXTERNAL_SERVICES=false
```
## Production Optimization
| Variable | Default | Description |
| ------------------ | ------- | -------------------------------------- |
| `CLUSTER_MODE` | `false` | Enable cluster mode |
| `WORKER_PROCESSES` | `0` | Number of worker processes (0 = auto) |
| `MEMORY_LIMIT` | - | Memory limit per process |
| `CPU_LIMIT` | - | CPU limit per process |
| `GC_OPTIMIZE` | `false` | Enable garbage collection optimization |
```env
CLUSTER_MODE=true
WORKER_PROCESSES=4
MEMORY_LIMIT=512M
GC_OPTIMIZE=true
```
## Configuration Examples
### Development Environment
```env
# .env.development
NODE_ENV=development
PORT=3000
LOG_LEVEL=debug
# Database
DATABASE_URL=postgresql://mcphub:password@localhost:5432/mcphub_dev
# Auth
JWT_SECRET=dev-secret-key
JWT_EXPIRES_IN=24h
# OpenAI (optional for development)
# OPENAI_API_KEY=your-dev-key
# Debug
DEBUG=mcphub:*
DEV_TOOLS_ENABLED=true
HOT_RELOAD=true
```
### Production Environment
```env
# .env.production
NODE_ENV=production
PORT=3000
LOG_LEVEL=info
LOG_FORMAT=json
# Database
DATABASE_URL=postgresql://mcphub:secure-password@db.example.com:5432/mcphub
DB_SSL=true
DB_POOL_MAX=20
# Security
JWT_SECRET=your-super-secure-production-secret
SESSION_SECRET=your-session-secret
BCRYPT_ROUNDS=14
# External Services
OPENAI_API_KEY=your-production-openai-key
REDIS_URL=redis://redis.example.com:6379
# Monitoring
METRICS_ENABLED=true
PERFORMANCE_MONITORING=true
# Optimization
CLUSTER_MODE=true
GC_OPTIMIZE=true
```
### Docker Environment
```env
# .env.docker
NODE_ENV=production
HOST=0.0.0.0
PORT=3000
# Use service names for Docker networking
DATABASE_URL=postgresql://mcphub:password@postgres:5432/mcphub
REDIS_URL=redis://redis:6379
# Security
JWT_SECRET_FILE=/run/secrets/jwt_secret
DB_PASSWORD_FILE=/run/secrets/db_password
# File paths in container
MCP_SETTINGS_FILE=/app/mcp_settings.json
UPLOAD_DIR=/app/data/uploads
LOG_FILE=/app/logs/mcphub.log
```
## Environment Variable Loading
MCPHub loads environment variables in the following order:
1. System environment variables
2. `.env.local` (ignored by git)
3. `.env.{NODE_ENV}` (e.g., `.env.production`)
4. `.env`
### Using dotenv-expand
MCPHub supports variable expansion:
```env
BASE_URL=https://api.example.com
API_ENDPOINT=${BASE_URL}/v1
DATABASE_URL=postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_NAME}
```
## Security Best Practices
1. **Never commit secrets** to version control
2. **Use strong, unique secrets** for production
3. **Rotate secrets regularly**
4. **Use environment-specific files**
5. **Validate all environment variables** at startup
6. **Use Docker secrets** for container deployments
## Validation
MCPHub validates environment variables at startup. Invalid configurations will prevent the application from starting with helpful error messages.
Required variables for production:
- `JWT_SECRET`
- `DATABASE_URL` or individual DB components
- `OPENAI_API_KEY` (if smart routing is enabled)
This comprehensive environment configuration ensures MCPHub can be properly configured for any deployment scenario.

564
docs/configuration/mcp-settings.mdx Normal file
View File

@@ -0,0 +1,564 @@
---
title: 'MCP Settings Configuration'
description: 'Configure MCP servers and their settings for MCPHub'
---
# MCP Settings Configuration
This guide explains how to configure MCP servers in MCPHub using the `mcp_settings.json` file and related configurations.
## Configuration Files Overview
MCPHub uses several configuration files:
- **`mcp_settings.json`**: Main MCP server configurations
- **`servers.json`**: Server metadata and grouping
- **`.env`**: Environment variables and secrets
## Basic MCP Settings Structure
### mcp_settings.json
```json
{
"mcpServers": {
"server-name": {
"command": "command-to-run",
"args": ["arg1", "arg2"],
"env": {
"ENV_VAR": "value"
},
"cwd": "/working/directory",
"timeout": 30000,
"restart": true
}
}
}
```
### Example Configuration
```json
{
"mcpServers": {
"fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"],
"env": {
"USER_AGENT": "MCPHub/1.0"
}
},
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest", "--headless"],
"timeout": 60000
},
"slack": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-slack"],
"env": {
"SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
"SLACK_TEAM_ID": "${SLACK_TEAM_ID}"
}
}
}
}
```
## Server Configuration Options
### Required Fields
| Field | Type | Description |
| --------- | ------ | -------------------------- |
| `command` | string | Executable command or path |
| `args` | array | Command-line arguments |
### Optional Fields
| Field | Type | Default | Description |
| -------------- | ------- | --------------- | --------------------------- |
| `env` | object | `{}` | Environment variables |
| `cwd` | string | `process.cwd()` | Working directory |
| `timeout` | number | `30000` | Startup timeout (ms) |
| `restart` | boolean | `true` | Auto-restart on failure |
| `maxRestarts` | number | `5` | Maximum restart attempts |
| `restartDelay` | number | `5000` | Delay between restarts (ms) |
| `stdio` | string | `pipe` | stdio configuration |
## Common MCP Server Examples
### Web and API Servers
#### Fetch Server
```json
{
"fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"],
"env": {
"USER_AGENT": "MCPHub/1.0",
"MAX_REDIRECTS": "10"
}
}
}
```
#### Web Scraping with Playwright
```json
{
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest", "--headless"],
"timeout": 60000,
"env": {
"PLAYWRIGHT_BROWSERS_PATH": "/tmp/browsers"
}
}
}
```
### File and System Servers
#### Filesystem Server
```json
{
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
"env": {
"ALLOWED_OPERATIONS": "read,write,list"
}
}
}
```
#### SQLite Server
```json
{
"sqlite": {
"command": "uvx",
"args": ["mcp-server-sqlite", "--db-path", "/path/to/database.db"],
"env": {
"SQLITE_READONLY": "false"
}
}
}
```
### Communication Servers
#### Slack Server
```json
{
"slack": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-slack"],
"env": {
"SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
"SLACK_TEAM_ID": "${SLACK_TEAM_ID}",
"SLACK_APP_TOKEN": "${SLACK_APP_TOKEN}"
}
}
}
```
#### Email Server
```json
{
"email": {
"command": "python",
"args": ["-m", "mcp_server_email"],
"env": {
"SMTP_HOST": "smtp.gmail.com",
"SMTP_PORT": "587",
"EMAIL_USER": "${EMAIL_USER}",
"EMAIL_PASSWORD": "${EMAIL_PASSWORD}"
}
}
}
```
### Development and API Servers
#### GitHub Server
```json
{
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
}
}
}
```
#### Google Drive Server
```json
{
"gdrive": {
"command": "npx",
"args": ["-y", "@google/mcp-server-gdrive"],
"env": {
"GOOGLE_CLIENT_ID": "${GOOGLE_CLIENT_ID}",
"GOOGLE_CLIENT_SECRET": "${GOOGLE_CLIENT_SECRET}",
"GOOGLE_REFRESH_TOKEN": "${GOOGLE_REFRESH_TOKEN}"
}
}
}
```
### Map and Location Services
#### Amap (高德地图) Server
```json
{
"amap": {
"command": "npx",
"args": ["-y", "@amap/amap-maps-mcp-server"],
"env": {
"AMAP_MAPS_API_KEY": "${AMAP_API_KEY}",
"AMAP_LANGUAGE": "zh-cn"
}
}
}
```
#### OpenStreetMap Server
```json
{
"osm": {
"command": "python",
"args": ["-m", "mcp_server_osm"],
"env": {
"OSM_USER_AGENT": "MCPHub/1.0"
}
}
}
```
## Advanced Configuration
### Environment Variable Substitution
MCPHub supports environment variable substitution using `${VAR_NAME}` syntax:
```json
{
"mcpServers": {
"api-server": {
"command": "python",
"args": ["-m", "api_server"],
"env": {
"API_KEY": "${API_KEY}",
"API_URL": "${API_BASE_URL}/v1",
"DEBUG": "${NODE_ENV:development}"
}
}
}
}
```
Default values can be specified with `${VAR_NAME:default}`:
```json
{
"timeout": "${MCP_TIMEOUT:30000}",
"maxRestarts": "${MCP_MAX_RESTARTS:5}"
}
```
### Conditional Configuration
Use different configurations based on environment:
```json
{
"mcpServers": {
"database": {
"command": "python",
"args": ["-m", "db_server"],
"env": {
"DB_URL": "${NODE_ENV:development == 'production' ? DATABASE_URL : DEV_DATABASE_URL}"
}
}
}
}
```
### Custom Server Scripts
#### Local Python Server
```json
{
"custom-python": {
"command": "python",
"args": ["./servers/custom_server.py"],
"cwd": "/app/custom-servers",
"env": {
"PYTHONPATH": "/app/custom-servers",
"CONFIG_FILE": "./config.json"
}
}
}
```
#### Local Node.js Server
```json
{
"custom-node": {
"command": "node",
"args": ["./servers/custom-server.js"],
"cwd": "/app/custom-servers",
"env": {
"NODE_ENV": "production"
}
}
}
```
## Server Metadata Configuration
### servers.json
Complement `mcp_settings.json` with server metadata:
```json
{
"servers": {
"fetch": {
"name": "Fetch Server",
"description": "HTTP client for web requests",
"category": "web",
"tags": ["http", "api", "web"],
"version": "1.0.0",
"author": "MCPHub Team",
"documentation": "https://docs.mcphub.com/servers/fetch",
"enabled": true
},
"playwright": {
"name": "Playwright Browser",
"description": "Web automation and scraping",
"category": "automation",
"tags": ["browser", "scraping", "automation"],
"version": "2.0.0",
"enabled": true
}
},
"groups": {
"web-tools": {
"name": "Web Tools",
"description": "Tools for web interaction",
"servers": ["fetch", "playwright"],
"access": "public"
},
"admin-tools": {
"name": "Admin Tools",
"description": "Administrative utilities",
"servers": ["filesystem", "database"],
"access": "admin"
}
}
}
```
## Group Management
### Group Configuration
```json
{
"groups": {
"production": {
"name": "Production Tools",
"description": "Stable production servers",
"servers": ["fetch", "slack", "github"],
"access": "authenticated",
"rateLimit": {
"requestsPerMinute": 100,
"burstLimit": 20
}
},
"experimental": {
"name": "Experimental Features",
"description": "Beta and experimental servers",
"servers": ["experimental-ai", "beta-search"],
"access": "admin",
"enabled": false
}
}
}
```
### Access Control
| Access Level | Description |
| --------------- | -------------------------- |
| `public` | No authentication required |
| `authenticated` | Valid JWT token required |
| `admin` | Admin role required |
| `custom` | Custom permission logic |
## Dynamic Configuration
### Hot Reloading
MCPHub supports hot reloading of configurations:
```bash
# Reload configurations without restart
curl -X POST http://localhost:3000/api/admin/reload-config \
-H "Authorization: Bearer your-admin-token"
```
### Configuration Validation
MCPHub validates configurations on startup and reload:
```json
{
"validation": {
"strict": true,
"allowUnknownServers": false,
"requireDocumentation": true
}
}
```
## Best Practices
### Security
1. **Use environment variables** for sensitive data:
```json
{
"env": {
"API_KEY": "${API_KEY}",
"DATABASE_PASSWORD": "${DB_PASSWORD}"
}
}
```
2. **Limit server permissions**:
```json
{
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/restricted/path"],
"env": {
"READONLY": "true"
}
}
}
```
### Performance
1. **Set appropriate timeouts**:
```json
{
"timeout": 30000,
"maxRestarts": 3,
"restartDelay": 5000
}
```
2. **Resource limits**:
```json
{
"env": {
"NODE_OPTIONS": "--max-old-space-size=512",
"MEMORY_LIMIT": "512MB"
}
}
```
### Monitoring
1. **Enable health checks**:
```json
{
"healthCheck": {
"enabled": true,
"interval": 30000,
"timeout": 5000
}
}
```
2. **Logging configuration**:
```json
{
"env": {
"LOG_LEVEL": "info",
"LOG_FORMAT": "json"
}
}
```
## Troubleshooting
### Common Issues
**Server won't start**: Check command and arguments
```bash
# Test command manually
uvx mcp-server-fetch
```
**Environment variables not found**: Verify `.env` file
```bash
# Check environment
printenv | grep API_KEY
```
**Permission errors**: Check file permissions and paths
```bash
# Verify executable permissions
ls -la /path/to/server
```
### Debug Configuration
Enable debug mode for detailed logging:
```json
{
"debug": {
"enabled": true,
"logLevel": "debug",
"includeEnv": false,
"logStartup": true
}
}
```
### Validation Errors
Common validation errors and solutions:
1. **Missing required fields**: Add `command` and `args`
2. **Invalid timeout**: Use number, not string
3. **Environment variable not found**: Check `.env` file
4. **Command not found**: Verify installation and PATH
This comprehensive guide covers all aspects of configuring MCP servers in MCPHub for various use cases and environments.

373
docs/configuration/nginx.mdx Normal file
View File

@@ -0,0 +1,373 @@
---
title: 'Nginx Configuration'
description: 'Configure Nginx as a reverse proxy for MCPHub'
---
# Nginx Configuration
This guide explains how to configure Nginx as a reverse proxy for MCPHub, including SSL termination, load balancing, and caching strategies.
## Basic Reverse Proxy Setup
### Configuration File
Create or update your Nginx configuration file (`/etc/nginx/sites-available/mcphub`):
```nginx
server {
listen 80;
server_name your-domain.com;
# Redirect HTTP to HTTPS
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl http2;
server_name your-domain.com;
# SSL Configuration
ssl_certificate /path/to/your/certificate.crt;
ssl_certificate_key /path/to/your/private.key;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384;
ssl_prefer_server_ciphers off;
# Security Headers
add_header X-Frame-Options DENY;
add_header X-Content-Type-Options nosniff;
add_header X-XSS-Protection "1; mode=block";
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
# Gzip Compression
gzip on;
gzip_vary on;
gzip_min_length 1024;
gzip_types
text/plain
text/css
text/xml
text/javascript
application/json
application/javascript
application/xml+rss
application/atom+xml
image/svg+xml;
# Main application
location / {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_cache_bypass $http_upgrade;
proxy_read_timeout 86400;
}
# API endpoints with longer timeout for MCP operations
location /api/ {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_cache_bypass $http_upgrade;
proxy_read_timeout 300;
proxy_connect_timeout 60;
proxy_send_timeout 60;
}
# Static assets caching
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
proxy_pass http://127.0.0.1:3000;
proxy_cache_valid 200 1d;
proxy_cache_valid 404 1m;
add_header Cache-Control "public, immutable";
expires 1y;
}
}
```
### Enable the Configuration
```bash
# Create symbolic link to enable the site
sudo ln -s /etc/nginx/sites-available/mcphub /etc/nginx/sites-enabled/
# Test configuration
sudo nginx -t
# Reload Nginx
sudo systemctl reload nginx
```
## Load Balancing Configuration
For high-availability setups with multiple MCPHub instances:
```nginx
upstream mcphub_backend {
least_conn;
server 127.0.0.1:3000 weight=1 max_fails=3 fail_timeout=30s;
server 127.0.0.1:3001 weight=1 max_fails=3 fail_timeout=30s;
server 127.0.0.1:3002 weight=1 max_fails=3 fail_timeout=30s;
# Health check (Nginx Plus feature)
# health_check interval=5s fails=3 passes=2;
}
server {
listen 443 ssl http2;
server_name your-domain.com;
# SSL and other configurations...
location / {
proxy_pass http://mcphub_backend;
# Other proxy settings...
}
}
```
## Caching Configuration
### Browser Caching
```nginx
# Cache static assets
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
proxy_pass http://127.0.0.1:3000;
expires 1y;
add_header Cache-Control "public, immutable";
}
# Cache API responses (be careful with dynamic content)
location /api/public/ {
proxy_pass http://127.0.0.1:3000;
proxy_cache mcphub_cache;
proxy_cache_valid 200 5m;
proxy_cache_key "$scheme$request_method$host$request_uri";
add_header X-Cache-Status $upstream_cache_status;
}
```
### Nginx Proxy Cache
Add to the `http` block in `nginx.conf`:
```nginx
http {
# Proxy cache configuration
proxy_cache_path /var/cache/nginx/mcphub
levels=1:2
keys_zone=mcphub_cache:10m
max_size=1g
inactive=60m
use_temp_path=off;
# Other configurations...
}
```
## WebSocket Support
For real-time features and SSE (Server-Sent Events):
```nginx
location /api/stream {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# Disable buffering for real-time responses
proxy_buffering off;
proxy_cache off;
# Timeouts for long-lived connections
proxy_read_timeout 24h;
proxy_send_timeout 24h;
}
```
## Security Configuration
### Rate Limiting
```nginx
http {
# Define rate limiting zones
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
limit_req_zone $binary_remote_addr zone=login:10m rate=1r/s;
server {
# Apply rate limiting to API endpoints
location /api/ {
limit_req zone=api burst=20 nodelay;
# Other configurations...
}
# Strict rate limiting for login endpoints
location /api/auth/login {
limit_req zone=login burst=5;
# Other configurations...
}
}
}
```
### IP Whitelisting
```nginx
# Allow specific IPs for admin endpoints
location /api/admin/ {
allow 192.168.1.0/24;
allow 10.0.0.0/8;
deny all;
proxy_pass http://127.0.0.1:3000;
# Other proxy settings...
}
```
## Monitoring and Logging
### Access Logs
```nginx
http {
# Custom log format
log_format mcphub_format '$remote_addr - $remote_user [$time_local] '
'"$request" $status $body_bytes_sent '
'"$http_referer" "$http_user_agent" '
'$request_time $upstream_response_time';
server {
# Enable access logging
access_log /var/log/nginx/mcphub_access.log mcphub_format;
error_log /var/log/nginx/mcphub_error.log;
# Other configurations...
}
}
```
### Status Page
```nginx
location /nginx_status {
stub_status;
allow 127.0.0.1;
deny all;
}
```
## Docker Integration
When running MCPHub in Docker, update the proxy configuration:
```nginx
upstream mcphub_docker {
server mcphub:3000; # Docker service name
}
server {
location / {
proxy_pass http://mcphub_docker;
# Other proxy settings...
}
}
```
## Complete Example Configuration
Here's a production-ready example using the provided `nginx.conf.example`:
```bash
# Copy the example configuration
cp nginx.conf.example /etc/nginx/sites-available/mcphub
# Update the configuration with your domain and paths
sudo nano /etc/nginx/sites-available/mcphub
# Enable the site
sudo ln -s /etc/nginx/sites-available/mcphub /etc/nginx/sites-enabled/
# Test and reload
sudo nginx -t && sudo systemctl reload nginx
```
## Troubleshooting
### Common Issues
**502 Bad Gateway**: Check if MCPHub is running and accessible
**504 Gateway Timeout**: Increase `proxy_read_timeout` for long-running operations
**WebSocket connection failures**: Ensure proper `Upgrade` and `Connection` headers
**Cache issues**: Clear proxy cache or disable for development
### Debug Commands
```bash
# Test Nginx configuration
sudo nginx -t
# Check Nginx status
sudo systemctl status nginx
# View error logs
sudo tail -f /var/log/nginx/error.log
# Check if MCPHub is responding
curl -I http://localhost:3000
```
## Performance Optimization
### Worker Processes
```nginx
# In nginx.conf
worker_processes auto;
worker_connections 1024;
```
### Buffer Sizes
```nginx
proxy_buffering on;
proxy_buffer_size 128k;
proxy_buffers 4 256k;
proxy_busy_buffers_size 256k;
```
### Keep-Alive
```nginx
upstream mcphub_backend {
server 127.0.0.1:3000;
keepalive 32;
}
location / {
proxy_pass http://mcphub_backend;
proxy_http_version 1.1;
proxy_set_header Connection "";
}
```
This configuration provides a solid foundation for running MCPHub behind Nginx with proper security, performance, and reliability features.