ai-agent-book/chapter4/DOCKER_DEPLOYMENT.md

Docker Deployment Guide for MCP Servers

This guide explains how to deploy the three MCP servers (execution-tools, perception-tools, collaboration-tools) using Docker.

Overview

All three MCP servers are containerized with Docker support, making them:

• Portable: Run anywhere Docker is available
• Isolated: Each server runs in its own environment
• Reproducible: Consistent behavior across different machines
• Easy to deploy: Simple setup with docker-compose

Prerequisites

1. Docker (version 20.10 or later)
2. Docker Compose (version 2.0 or later)
3. API Keys for external services (OpenAI, Google, etc.)

Quick Start

1. Set Up Environment Variables

Copy the example environment file and configure your API keys:

cd /Users/boj/ai-agent-book/projects/week4
cp .env.example .env

Edit .env and add your API keys:

OPENAI_API_KEY=your-openai-api-key
GOOGLE_API_KEY=your-google-key
# ... other keys

2. Build and Run All Services

Use the provided script:

./build_and_run.sh

Or manually:

# Build all images
docker-compose build

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

3. Build Individual Services

To build/run a single service:

# Build execution-tools only
docker-compose build execution-tools

# Run execution-tools only
docker-compose up -d execution-tools

Service Details

Execution Tools

Purpose: Multi-language code execution with scientific computing support

Languages Supported:

• Python 3.11 (with NumPy, Pandas, Scikit-learn, etc.)
• JavaScript/Node.js 20.x
• TypeScript (with tsx/ts-node)
• Go 1.21
• Java 17 (OpenJDK)
• C++ (GCC)
• Rust
• PHP
• Bash

Volume Mounts:

• execution-workspace:/workspace - Code execution workspace

Key Environment Variables:

• WORKSPACE_DIR: Working directory for code execution
• AUTO_VERIFY_CODE: Automatically verify code before execution
• AUTO_SUMMARIZE_COMPLEX_OUTPUT: Summarize long outputs

Perception Tools

Purpose: Document processing, web search, and data retrieval

Features:

• PDF/document processing
• Web search (Google, Arxiv)
• Data extraction and analysis
• OCR support (Tesseract)

Volume Mounts:

• perception-data:/data - Processed document storage

Key Environment Variables:

• DATA_DIR: Data storage directory
• GOOGLE_API_KEY: Google search API key
• GOOGLE_CSE_ID: Custom Search Engine ID

Collaboration Tools

Purpose: Browser automation, Excel processing, HITL interactions

Features:

• Headless browser automation (Chromium)
• Excel file processing
• Human-in-the-loop interactions
• Chess game analysis
• Timer and notification tools

Volume Mounts:

• collaboration-workspace:/workspace - Working directory

Key Environment Variables:

• WORKSPACE_DIR: Working directory
• DISPLAY: X11 display (for headless browser)

Local Development

For local development without Docker:

Execution Tools

cd execution-tools
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your settings
python server.py

Perception Tools

cd perception-tools
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp env.example .env
# Edit .env with your settings
python src/main.py

Collaboration Tools

cd collaboration-tools
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp env.example .env
# Edit .env with your settings
python src/main.py

Testing Multi-Language Code Execution

Once the execution-tools service is running, you can test different languages:

Python Example

code = """
import numpy as np
import pandas as pd

data = pd.DataFrame({'A': [1, 2, 3], 'B': [4, 5, 6]})
print(data.describe())
"""
# Execute via MCP: code_interpreter(code=code, language="python")

JavaScript Example

code = """
console.log('Hello from Node.js!');
const numbers = [1, 2, 3, 4, 5];
const sum = numbers.reduce((a, b) => a + b, 0);
console.log('Sum:', sum);
"""
# Execute via MCP: code_interpreter(code=code, language="javascript")

Go Example

code = """
package main
import "fmt"

func main() {
    fmt.Println("Hello from Go!")
    sum := 0
    for i := 1; i <= 10; i++ {
        sum += i
    }
    fmt.Printf("Sum: %d\\n", sum)
}
"""
# Execute via MCP: code_interpreter(code=code, language="go")

Docker Commands Reference

# Build all services
docker-compose build

# Start all services
docker-compose up -d

# Stop all services
docker-compose down

# View logs
docker-compose logs -f [service-name]

# Restart a service
docker-compose restart [service-name]

# View running containers
docker-compose ps

# Execute command in container
docker-compose exec execution-tools bash

# Remove all containers and volumes
docker-compose down -v

# Rebuild a service
docker-compose up -d --build [service-name]

Troubleshooting

Issue: Service won't start

Check logs:

docker-compose logs [service-name]

Issue: Permission denied

Ensure volumes have correct permissions:

docker-compose down -v
docker-compose up -d

Issue: Out of memory

Increase Docker memory limit in Docker Desktop settings or add to docker-compose.yml:

services:
  execution-tools:
    mem_limit: 4g

Issue: Python packages missing

Rebuild the image:

docker-compose build --no-cache execution-tools

Security Considerations

1. Never commit .env files with real API keys
2. Use non-root users in containers (already configured)
3. Limit resource usage with Docker resource constraints
4. Keep images updated regularly rebuild with latest security patches
5. Use secrets management for production deployments (Docker Swarm secrets, Kubernetes secrets)

Production Deployment

For production deployments, consider:

1. Orchestration: Use Kubernetes or Docker Swarm
2. Secrets Management: Use external secret stores (Vault, AWS Secrets Manager)
3. Monitoring: Add Prometheus/Grafana for metrics
4. Logging: Centralized logging with ELK or Loki
5. Resource Limits: Set proper CPU/memory limits
6. Health Checks: Already configured in docker-compose.yml
7. Auto-restart: Already configured with restart: unless-stopped

Architecture Diagram

┌─────────────────────────────────────────────────────────┐
│                   MCP Client (Claude)                    │
└────────────┬────────────┬────────────┬──────────────────┘
             │            │            │
             │ stdio      │ stdio      │ stdio
             │            │            │
   ┌─────────▼───────┐ ┌─▼──────────┐ ┌▼────────────────┐
   │ execution-tools │ │ perception-│ │ collaboration-  │
   │   Container     │ │   tools    │ │   tools         │
   │                 │ │ Container  │ │   Container     │
   │ • Python 3.11   │ │ • Doc Proc │ │ • Browser       │
   │ • Node.js 20    │ │ • Search   │ │ • Excel         │
   │ • Go 1.21       │ │ • OCR      │ │ • HITL          │
   │ • Java 17       │ │ • APIs     │ │ • Timers        │
   │ • C++/Rust/PHP  │ │            │ │                 │
   └────────┬────────┘ └─┬──────────┘ └┬────────────────┘
            │            │             │
            ▼            ▼             ▼
      /workspace      /data       /workspace
       (volume)      (volume)      (volume)

Additional Resources

• Docker Documentation
• Docker Compose Reference
• MCP Protocol Specification

Support

For issues or questions:

1. Check the logs: docker-compose logs -f
2. Review this documentation
3. Check the individual README files in each service directory