# Deployment Guide

# European Parliament MCP Server - Deployment Guide

Complete deployment configurations for all MCP clients
Claude Desktop, VS Code, Docker, and production deployments

## 📋 Table of Contents

- Prerequisites
- Claude Desktop Deployment
- VS Code Extension Deployment
- Docker Deployment
- Production Deployment
- Environment Variables
- Troubleshooting

## ✅ Prerequisites

### Required Software

- Node.js: v26.x or higher
- npm: v10.x or higher
- Git: Latest version

### Build Requirements

    # Clone repository
    git clone https://github.com/Hack23/European-Parliament-MCP-Server.git
    cd European-Parliament-MCP-Server

    # Install dependencies
    npm install

    # Build project
    npm run build

    # Verify build
    test -f dist/index.js && echo "Build successful"

## 🖥️ Claude Desktop Deployment

### 1. Build the Server

    cd /path/to/European-Parliament-MCP-Server
    npm install
    npm run build

### 2. Configure Claude Desktop

Config Location:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Linux: `~/.config/claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Configuration:

    {
      "mcpServers": {
        "european-parliament": {
          "command": "node",
          "args": [
            "/absolute/path/to/European-Parliament-MCP-Server/dist/index.js"
          ],
          "env": {
            "LOG_LEVEL": "info"
          }
        }
      }
    }

Important:

- Use absolute paths (not `~` or relative paths)
- Use forward slashes `/` even on Windows
- Restart Claude Desktop after configuration changes

### 3. Verify Installation

1. Open Claude Desktop
2. Start a new conversation
3. Type: "What European Parliament tools are available?"
4. Claude should list the 62 MCP tools

### Troubleshooting

Tools not appearing:

    # Check file exists
    test -f /path/to/dist/index.js && echo "OK" || echo "Missing"

    # Check permissions
    ls -la /path/to/dist/index.js

    # Check Claude logs (macOS)
    tail -f ~/Library/Logs/Claude/main.log

## 📝 VS Code Extension Deployment

### 1. Install MCP Extension

    # Install from VS Code Marketplace
    code --install-extension mcp-extension

### 2. Build the Server

    cd ${workspaceFolder}/European-Parliament-MCP-Server
    npm install
    npm run build

### 3. Configure VS Code

Create `.vscode/mcp.json` in your workspace:

    {
      "servers": {
        "european-parliament": {
          "type": "stdio",
          "command": "node",
          "args": ["./dist/index.js"],
          "cwd": "${workspaceFolder}/European-Parliament-MCP-Server",
          "env": {
            "LOG_LEVEL": "info"
          }
        }
      }
    }

### 4. Reload VS Code

    Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux)
    > Developer: Reload Window

### 5. Verify Installation

1. Open Command Palette
2. Search for "MCP: List Tools"
3. Should show 62 European Parliament tools

## 🐳 Docker Deployment

### 1. Create Dockerfile

    FROM node:22-alpine

    WORKDIR /app

    # Copy package files
    COPY package*.json ./

    # Install dependencies
    RUN npm ci --only=production

    # Copy built files
    COPY dist/ ./dist/

    # Expose WebSocket port
    EXPOSE 3000

    # Health check
    HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
      CMD node -e "require('http').get('http://localhost:3000/health')"

    # Run server
    CMD ["node", "dist/index.js", "--transport", "websocket", "--port", "3000"]

### 2. Create docker-compose.yml

    version: '3.8'

    services:
      ep-mcp-server:
        build: .
        ports:
          - "3000:3000"
        environment:
          - NODE_ENV=production
          - LOG_LEVEL=info
          - CACHE_MAX_SIZE=500
          - CACHE_TTL=900000
          - RATE_LIMIT_REQUESTS=100
          - RATE_LIMIT_WINDOW=900000
        volumes:
          - cache-data:/app/cache
          - logs:/app/logs
        restart: unless-stopped
        networks:
          - mcp-network

    volumes:
      cache-data:
      logs:

    networks:
      mcp-network:

### 3. Build and Run

    # Build image
    docker-compose build

    # Start service
    docker-compose up -d

    # Check logs
    docker-compose logs -f

    # Check health
    curl http://localhost:3000/health

### 4. Connect MCP Client

    {
      "mcpServers": {
        "european-parliament": {
          "type": "websocket",
          "url": "ws://localhost:3000"
        }
      }
    }

## 🚀 Production Deployment

### Architecture

                                        ┌─────────────────┐
                                        │  Load Balancer  │
                                        │    (nginx)      │
                                        └────────┬────────┘
                                                 │
                        ┌────────────────────────┼────────────────────────┐
                        │                        │                        │
                  ┌─────▼─────┐           ┌─────▼─────┐           ┌─────▼─────┐
                  │ MCP Server│           │ MCP Server│           │ MCP Server│
                  │ Instance 1│           │ Instance 2│           │ Instance 3│
                  └───────────┘           └───────────┘           └───────────┘
                        │                        │                        │
                        └────────────────────────┼────────────────────────┘
                                                 │
                                        ┌────────▼────────┐
                                        │  Shared Cache   │
                                        │    (Redis)      │
                                        └─────────────────┘

### 1. Nginx Load Balancer

`/etc/nginx/sites-available/mcp-server`:

    upstream mcp_backend {
        least_conn;
        server 127.0.0.1:3001;
        server 127.0.0.1:3002;
        server 127.0.0.1:3003;
    }

    server {
        listen 443 ssl http2;
        server_name mcp.yourdomain.com;

        ssl_certificate /etc/letsencrypt/live/mcp.yourdomain.com/fullchain.pem;
        ssl_certificate_key /etc/letsencrypt/live/mcp.yourdomain.com/privkey.pem;

        location / {
            proxy_pass http://mcp_backend;
            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;

            # WebSocket timeouts
            proxy_read_timeout 3600s;
            proxy_send_timeout 3600s;
        }

        # Health check endpoint
        location /health {
            access_log off;
            proxy_pass http://mcp_backend;
        }
    }

### 2. Systemd Service

`/etc/systemd/system/ep-mcp-server@.service`:

    [Unit]
    Description=European Parliament MCP Server (instance %i)
    After=network.target

    [Service]
    Type=simple
    User=mcp
    WorkingDirectory=/opt/european-parliament-mcp-server
    ExecStart=/usr/bin/node dist/index.js --transport websocket --port 300%i
    Restart=always
    RestartSec=10
    StandardOutput=journal
    StandardError=journal
    SyslogIdentifier=ep-mcp-server-%i

    # Environment
    Environment="NODE_ENV=production"
    Environment="LOG_LEVEL=info"
    Environment="PORT=300%i"

    # Security
    NoNewPrivileges=true
    PrivateTmp=true
    ProtectSystem=strict
    ProtectHome=true
    ReadWritePaths=/opt/european-parliament-mcp-server/cache
    ReadWritePaths=/opt/european-parliament-mcp-server/logs

    # Resource limits
    LimitNOFILE=65536
    MemoryLimit=512M

    [Install]
    WantedBy=multi-user.target

Enable and start services:

    # Enable 3 instances
    sudo systemctl enable ep-mcp-server@{1..3}

    # Start services
    sudo systemctl start ep-mcp-server@{1..3}

    # Check status
    sudo systemctl status ep-mcp-server@*

    # View logs
    sudo journalctl -u ep-mcp-server@* -f

### 3. Monitoring

Prometheus metrics (if enabled):

    # prometheus.yml
    scrape_configs:
      - job_name: 'ep-mcp-server'
        static_configs:
          - targets:
              - 'localhost:3001'
              - 'localhost:3002'
              - 'localhost:3003'

Log aggregation with journald:

    # View all server logs
    sudo journalctl -u 'ep-mcp-server@*' --since "1 hour ago"

    # Follow logs in real-time
    sudo journalctl -u 'ep-mcp-server@*' -f

    # Export logs
    sudo journalctl -u 'ep-mcp-server@*' --since "24 hours ago" > server.log

### 4. Backup and Recovery

    #!/bin/bash
    # backup.sh - Backup cache and logs

    DATE=$(date +%Y%m%d_%H%M%S)
    BACKUP_DIR="/backup/ep-mcp-server"

    # Create backup directory
    mkdir -p "$BACKUP_DIR/$DATE"

    # Backup cache
    tar -czf "$BACKUP_DIR/$DATE/cache.tar.gz" /opt/european-parliament-mcp-server/cache/

    # Backup logs
    tar -czf "$BACKUP_DIR/$DATE/logs.tar.gz" /opt/european-parliament-mcp-server/logs/

    # Backup configuration
    cp /etc/systemd/system/ep-mcp-server@.service "$BACKUP_DIR/$DATE/"
    cp /etc/nginx/sites-available/mcp-server "$BACKUP_DIR/$DATE/"

    # Keep only last 7 days
    find "$BACKUP_DIR" -type d -mtime +7 -exec rm -rf {} +

    echo "Backup completed: $BACKUP_DIR/$DATE"

## 🔧 Environment Variables

### Available Variables

Variable | Default | Description
--- | --- | ---
`NODE_ENV` | `development` | Environment mode (development/production)
`LOG_LEVEL` | `info` | Logging level (debug/info/warn/error)
`PORT` | `3000` | WebSocket server port
`CACHE_MAX_SIZE` | `500` | Maximum cache entries
`CACHE_TTL` | `900000` | Cache TTL in milliseconds (15 min)
`RATE_LIMIT_REQUESTS` | `100` | Maximum requests per window
`RATE_LIMIT_WINDOW` | `900000` | Rate limit window in ms (15 min)
`EP_API_BASE_URL` | (EP API) | European Parliament API base URL

### Example Configuration

Development:

    export NODE_ENV=development
    export LOG_LEVEL=debug
    export CACHE_TTL=60000  # 1 minute for testing

Production:

    export NODE_ENV=production
    export LOG_LEVEL=info
    export CACHE_TTL=900000  # 15 minutes
    export RATE_LIMIT_REQUESTS=100

## 🔍 Troubleshooting

### Server Won't Start

    # Check Node.js version
    node --version  # Must be v26.x+

    # Check if port is in use
    lsof -i :3000

    # Check build
    test -f dist/index.js && echo "OK" || echo "Run npm run build"

    # Check dependencies
    npm list --depth=0

### High Memory Usage

    # Monitor memory
    watch -n 1 'ps aux | grep "node.*index.js"'

    # Reduce cache size
    export CACHE_MAX_SIZE=100
    export CACHE_TTL=300000  # 5 minutes

### Performance Issues

    # Enable debug logging
    export LOG_LEVEL=debug

    # Check EP API response time
    time curl -s https://data.europarl.europa.eu/api/v2/meps > /dev/null

    # Monitor with metrics
    curl http://localhost:3000/metrics

## 📚 Additional Resources

- API Usage Guide
- Architecture Diagrams
- Troubleshooting Guide
- Developer Guide
- Performance Guide

Built with ❤️ by Hack23 AB
ISMS-compliant deployment demonstrating security excellence