Docker Integration - johnpeterman72/CursorRIPER.sigma GitHub Wiki

🐳 Docker MCP Integration

Overview

Docker integration within the CursorRIPER.sigma framework provides containerized Model Context Protocol (MCP) services, enabling scalable and isolated execution environments for various framework components.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                 CursorRIPER.sigma Framework                 │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │   MCP-1     │  │   MCP-2     │  │   MCP-N     │        │
│  │ Container   │  │ Container   │  │ Container   │        │
│  └─────────────┘  └─────────────┘  └─────────────┘        │
│           │               │               │                │
│  ┌─────────────────────────────────────────────────────────┤
│  │              Docker Engine                              │
│  └─────────────────────────────────────────────────────────┤
├─────────────────────────────────────────────────────────────┤
│                    Host System                             │
└─────────────────────────────────────────────────────────────┘

Prerequisites

System Requirements

  • Docker Engine 20.10+
  • Docker Compose 2.0+
  • Minimum 4GB RAM
  • 10GB available disk space

Framework Dependencies

  • CursorRIPER.sigma framework v1.0+
  • Node.js 18+ (for MCP client)
  • Python 3.8+ (for MCP server components)

Installation

1. Install Docker (if not already installed)

Windows:

# Download and install Docker Desktop from docker.com
# Or use Chocolatey
choco install docker-desktop

Linux (Ubuntu/Debian):

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

macOS:

# Download Docker Desktop from docker.com
# Or use Homebrew
brew install --cask docker

2. Framework Integration Setup

# Navigate to framework directory
cd "D:\Cursor Projects\CursorRIPER.sigma"

# Initialize Docker MCP configuration
npm run docker:init

# Or manually create configuration
mkdir -p docker/mcp

3. MCP Container Configuration

Create docker/mcp/docker-compose.yml:

version: '3.8'

services:
  mcp-server:
    build:
      context: ./server
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - MCP_CONFIG_PATH=/app/config
    volumes:
      - ./config:/app/config:ro
      - ./data:/app/data
      - ./logs:/app/logs
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  mcp-client:
    build:
      context: ./client
      dockerfile: Dockerfile
    depends_on:
      - mcp-server
    environment:
      - MCP_SERVER_URL=http://mcp-server:3000
      - CLIENT_CONFIG_PATH=/app/config
    volumes:
      - ./config:/app/config:ro
      - ./client-data:/app/data
    restart: unless-stopped

  mcp-redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data
    restart: unless-stopped
    command: redis-server --appendonly yes

volumes:
  redis-data:

networks:
  default:
    name: mcp-network

Framework Integration

1. MCP Server Setup

Create docker/mcp/server/Dockerfile:

FROM node:18-alpine

WORKDIR /app

# Install dependencies
COPY package*.json ./
RUN npm ci --only=production

# Copy application code
COPY src/ ./src/
COPY config/ ./config/

# Create necessary directories
RUN mkdir -p /app/data /app/logs

# Set up non-root user
RUN addgroup -g 1001 -S mcp && \
    adduser -S mcp -u 1001 -G mcp
RUN chown -R mcp:mcp /app
USER mcp

EXPOSE 3000

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1

CMD ["npm", "start"]

2. Framework Configuration

Update framework.config.js:

module.exports = {
  mcp: {
    enabled: true,
    docker: {
      enabled: true,
      compose_file: './docker/mcp/docker-compose.yml',
      auto_start: true,
      health_check_timeout: 30000
    },
    servers: [
      {
        name: 'primary-mcp',
        container: 'mcp-server',
        url: 'http://localhost:3000',
        capabilities: ['analysis', 'processing', 'storage']
      }
    ],
    clients: [
      {
        name: 'framework-client',
        container: 'mcp-client',
        server: 'primary-mcp',
        timeout: 10000
      }
    ]
  }
};

3. Framework MCP Manager

Create src/services/MCPDockerManager.js:

const { exec } = require('child_process');
const Docker = require('dockerode');
const path = require('path');

class MCPDockerManager {
  constructor(config) {
    this.config = config;
    this.docker = new Docker();
    this.composePath = path.resolve(config.docker.compose_file);
  }

  async initialize() {
    try {
      await this.ensureNetwork();
      await this.startServices();
      await this.waitForHealthChecks();
      console.log('MCP Docker services initialized successfully');
    } catch (error) {
      console.error('Failed to initialize MCP Docker services:', error);
      throw error;
    }
  }

  async ensureNetwork() {
    try {
      await this.docker.getNetwork('mcp-network').inspect();
    } catch (error) {
      console.log('Creating MCP network...');
      await this.docker.createNetwork({
        Name: 'mcp-network',
        Driver: 'bridge'
      });
    }
  }

  async startServices() {
    return new Promise((resolve, reject) => {
      const cmd = `docker-compose -f "${this.composePath}" up -d`;
      exec(cmd, (error, stdout, stderr) => {
        if (error) {
          reject(new Error(`Failed to start services: ${error.message}`));
          return;
        }
        console.log('MCP services started');
        resolve();
      });
    });
  }

  async waitForHealthChecks() {
    const maxWait = this.config.docker.health_check_timeout;
    const startTime = Date.now();

    while (Date.now() - startTime < maxWait) {
      try {
        const container = this.docker.getContainer('mcp-server');
        const inspect = await container.inspect();
        
        if (inspect.State.Health?.Status === 'healthy') {
          return;
        }
      } catch (error) {
        // Container might not be ready yet
      }

      await new Promise(resolve => setTimeout(resolve, 2000));
    }

    throw new Error('Health check timeout exceeded');
  }

  async stop() {
    return new Promise((resolve, reject) => {
      const cmd = `docker-compose -f "${this.composePath}" down`;
      exec(cmd, (error, stdout, stderr) => {
        if (error) {
          reject(new Error(`Failed to stop services: ${error.message}`));
          return;
        }
        console.log('MCP services stopped');
        resolve();
      });
    });
  }

  async restart() {
    await this.stop();
    await this.initialize();
  }

  async getLogs(service = 'mcp-server', lines = 100) {
    return new Promise((resolve, reject) => {
      const cmd = `docker-compose -f "${this.composePath}" logs --tail=${lines} ${service}`;
      exec(cmd, (error, stdout, stderr) => {
        if (error) {
          reject(error);
          return;
        }
        resolve(stdout);
      });
    });
  }

  async getStatus() {
    try {
      const containers = await this.docker.listContainers({
        filters: { label: ['com.docker.compose.project=mcp'] }
      });

      return containers.map(container => ({
        name: container.Names[0].replace('/', ''),
        status: container.State,
        ports: container.Ports,
        created: container.Created
      }));
    } catch (error) {
      throw new Error(`Failed to get status: ${error.message}`);
    }
  }
}

module.exports = MCPDockerManager;

Usage Examples

1. Basic Framework Integration

// In your framework initialization
const MCPDockerManager = require('./src/services/MCPDockerManager');
const config = require('./framework.config');

const mcpManager = new MCPDockerManager(config.mcp);

// Initialize MCP services
await mcpManager.initialize();

// Use MCP services through framework
const result = await framework.mcp.analyze(data);

2. Custom MCP Container

# Custom analysis container
FROM python:3.9-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install -r requirements.txt

COPY analysis/ ./analysis/

EXPOSE 8000

CMD ["python", "-m", "analysis.server"]

3. Framework Service Discovery

// Automatic service discovery
class FrameworkMCPClient {
  constructor(dockerManager) {
    this.dockerManager = dockerManager;
    this.services = new Map();
  }

  async discoverServices() {
    const containers = await this.dockerManager.getStatus();
    
    for (const container of containers) {
      if (container.name.includes('mcp-')) {
        const serviceInfo = await this.inspectService(container);
        this.services.set(serviceInfo.name, serviceInfo);
      }
    }
  }

  async callService(serviceName, method, params) {
    const service = this.services.get(serviceName);
    if (!service) {
      throw new Error(`Service ${serviceName} not found`);
    }

    // Make RPC call to containerized service
    return await this.makeRPCCall(service.endpoint, method, params);
  }
}

Monitoring and Maintenance

1. Health Monitoring

# Check service health
docker-compose -f docker/mcp/docker-compose.yml ps

# View logs
docker-compose -f docker/mcp/docker-compose.yml logs -f mcp-server

# Check resource usage
docker stats mcp-server mcp-client mcp-redis

2. Maintenance Scripts

Create scripts/mcp-maintenance.sh:

#!/bin/bash

MCP_DIR="docker/mcp"

case "$1" in
  "start")
    echo "Starting MCP services..."
    docker-compose -f "$MCP_DIR/docker-compose.yml" up -d
    ;;
  "stop")
    echo "Stopping MCP services..."
    docker-compose -f "$MCP_DIR/docker-compose.yml" down
    ;;
  "restart")
    echo "Restarting MCP services..."
    docker-compose -f "$MCP_DIR/docker-compose.yml" restart
    ;;
  "logs")
    docker-compose -f "$MCP_DIR/docker-compose.yml" logs -f "${2:-mcp-server}"
    ;;
  "clean")
    echo "Cleaning up MCP resources..."
    docker-compose -f "$MCP_DIR/docker-compose.yml" down -v
    docker system prune -f
    ;;
  "backup")
    echo "Backing up MCP data..."
    docker run --rm -v mcp_redis-data:/data -v $(pwd)/backups:/backup \
      alpine tar czf /backup/mcp-redis-$(date +%Y%m%d_%H%M%S).tar.gz -C /data .
    ;;
  *)
    echo "Usage: $0 {start|stop|restart|logs|clean|backup}"
    exit 1
    ;;
esac

3. Auto-Update Configuration

# docker/mcp/docker-compose.override.yml
version: '3.8'

services:
  watchtower:
    image: containrrr/watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WATCHTOWER_POLL_INTERVAL=3600
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_INCLUDE_STOPPED=true
    command: mcp-server mcp-client

Security Considerations

1. Network Isolation

# Secure network configuration
networks:
  mcp-internal:
    driver: bridge
    internal: true
  mcp-external:
    driver: bridge

services:
  mcp-server:
    networks:
      - mcp-internal
      - mcp-external
    
  mcp-redis:
    networks:
      - mcp-internal  # No external access

2. Secret Management

# Use Docker secrets for sensitive data
echo "my-secret-key" | docker secret create mcp_api_key -

# Reference in compose file
services:
  mcp-server:
    secrets:
      - mcp_api_key
    environment:
      - API_KEY_FILE=/run/secrets/mcp_api_key

secrets:
  mcp_api_key:
    external: true

3. Resource Limits

services:
  mcp-server:
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 1G
        reservations:
          cpus: '0.5'
          memory: 512M
    security_opt:
      - no-new-privileges:true
    read_only: true
    tmpfs:
      - /tmp

Troubleshooting

Common Issues

  1. Port Conflicts: Change ports in docker-compose.yml
  2. Permission Issues: Check file ownership and Docker daemon permissions
  3. Network Issues: Verify Docker network configuration
  4. Resource Limits: Monitor memory and CPU usage

Debug Commands

# Check Docker daemon
docker info

# Inspect containers
docker inspect mcp-server

# Check networks
docker network ls
docker network inspect mcp-network

# View container processes
docker top mcp-server

Last Updated: June 28, 2025
Framework Version: CursorRIPER.sigma v1.0+
Docker Integration Version: 1.0.0