claude-code-docker-mcp by SamuraiBuddha - MCP Server

Claude Code Docker MCP

🚀 Distributed AI Agent Architecture for 10000x Amplification

A containerized Claude Code environment with MCP (Model Context Protocol) server integration. This project enables systematic infrastructure for distributed AI agents working in parallel coordination.

🎯 Philosophy

"Careful architecture beats rushed implementation" - Jordan Ehrig

This project embodies systematic infrastructure development, preventing technical debt while enabling genuine productivity amplification through specialized AI coordination.

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────┐
│                     CLAUDE (MELCHIOR)                  │
│                  ┌─────────────────┐                   │
│                  │  MCP Tools      │                   │
│                  │  Ecosystem      │                   │
│                  └─────────┬───────┘                   │
└──────────────────────────────┼───────────────────────────┘
                              │
                    ┌─────────┴───────────┐
                    │   Claude Code MCP   │
                    │   (This Project)    │
                    └─────────┬───────────┘
                              │
┌─────────────────────────────┼───────────────────────────┐
│             DOCKER CONTAINER                           │
│  ┌──────────────────────────┼─────────────────────────┐  │
│  │        MCP SERVER        │                         │  │
│  │                          ▼                         │  │
│  │  ┌─────────────────────────────────────────────┐   │  │
│  │  │           CLAUDE CODE ENGINE                │   │  │
│  │  │                                             │   │  │
│  │  │  • Project Analysis                         │   │  │
│  │  │  • Multi-file Implementation               │   │  │
│  │  │  • Recursive Debugging                     │   │  │
│  │  │  • Comprehensive Refactoring               │   │  │
│  │  └─────────────────────────────────────────────┘   │  │
│  └─────────────────────────────────────────────────────┘  │
│                                                           │
│  Mounted Volumes: /workspace -> Host Project Directories  │
└───────────────────────────────────────────────────────────┘

⚡ Amplification Architecture

Current Workflow Evolution

L1 (10x):   Memory → Sequential → Store
L2 (100x):  Memory → Sequential → Sandbox → Store  
L3 (1000x): Memory → Sequential → (Parallel: Sandbox + LocalLLM) → Store
L4 (10000x): Memory → Sequential → (Parallel: Sandbox + LocalLLM + ClaudeCode) → Store

Agent Specialization

MELCHIOR (Claude): Conductor & Architect - Planning, coordination, high-level decisions
CLAUDE CODE: Coding Specialist - Project-wide context, recursive resolution, comprehensive implementation
LOCAL LLM: Research Sidekick - Domain knowledge, parallel analysis, validation
SANDBOXES: Computation Engine - Heavy processing, testing, data analysis

🚀 Quick Start

Prerequisites

Docker & Docker Compose
Anthropic API key
Windows with Docker Desktop (Claude Code requires Linux container)

Installation

Clone the repository

git clone https://github.com/SamuraiBuddha/claude-code-docker-mcp.git
cd claude-code-docker-mcp

Configure environment

cp .env.template .env
# Edit .env and add your ANTHROPIC_API_KEY

Create project directories
```
mkdir -p projects logs
```

Build and start

docker-compose build
docker-compose up -d

Verify installation
```
curl http://localhost:3001/health
```

📚 API Endpoints

Health Check

GET /health
# Returns: server status, uptime, active tasks

Project Analysis

POST /claude-code/analyze
{
  "project_path": "my-project",
  "analysis_type": "structure|health|dependencies|issues"
}

Task Execution

POST /claude-code/execute
{
  "task_description": "Add error handling to main file",
  "project_path": "my-project",
  "context": "Express.js application with TypeScript",
  "priority": "medium"
}

Status Check

GET /claude-code/status
# Returns: Claude Code version, task summary, system health

Task Monitoring

GET /claude-code/task/:taskId
# Returns: detailed task status and results

🛡️ Security Features

Container Security: Non-root user, limited capabilities, resource limits
API Security: Rate limiting, input validation, CORS policies, security headers
Secret Management: Environment-based configuration, no secrets in images
Network Security: Localhost binding, isolated container networking

📁 Project Structure

claude-code-docker-mcp/
├── .env.template          # Environment configuration template
├── .gitignore            # Comprehensive exclusions (secrets, logs, etc.)
├── secrets.md            # Secret management protocols
├── SECURITY.md           # Security policy and incident response
├── Dockerfile            # Multi-stage container build
├── docker-compose.yml    # Service orchestration with security
├── src/
│   ├── mcp-server.js     # Main MCP server implementation
│   ├── health-check.js   # Container health monitoring
│   └── package.json      # Node.js dependencies
├── projects/             # Mount point for project access
├── logs/                 # Container logs
└── README.md            # This file

🔧 Configuration

Environment Variables

Variable	Default	Description
`ANTHROPIC_API_KEY`	required	Your Anthropic API key
`MCP_PORT`	3001	MCP server port
`MCP_HOST`	127.0.0.1	Bind address (localhost only)
`CLAUDE_CODE_LOG_LEVEL`	info	Logging verbosity
`CLAUDE_CODE_TIMEOUT`	300000	Task timeout in milliseconds
`CONTAINER_MEMORY_LIMIT`	2g	Docker memory limit
`CONTAINER_CPU_LIMIT`	1.0	Docker CPU limit

Volume Mounts

./projects:/workspace/projects:rw - Project file access
./logs:/workspace/logs:rw - Container logs

🚀 Usage Examples

Analyze Project Structure

curl -X POST http://localhost:3001/claude-code/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "project_path": "my-webapp",
    "analysis_type": "structure"
  }'

Implement Feature

curl -X POST http://localhost:3001/claude-code/execute \
  -H "Content-Type: application/json" \
  -d '{
    "task_description": "Add user authentication with JWT tokens",
    "project_path": "my-webapp",
    "context": "Express.js REST API with MongoDB",
    "priority": "high"
  }'

Debug Issues

curl -X POST http://localhost:3001/claude-code/execute \
  -H "Content-Type: application/json" \
  -d '{
    "task_description": "Fix memory leak in user session management",
    "project_path": "my-webapp",
    "context": "Memory usage increases over time, suspect session storage",
    "priority": "critical"
  }'

📊 Monitoring

Health Checks

Docker health check every 30 seconds
HTTP endpoint monitoring
Claude Code binary verification
Resource usage tracking

Logging

Structured JSON logging
Request/response tracking
Claude Code execution logs
Error handling and reporting

🔄 Development Phases

✅ Phase 1: Proof of Concept

Basic Dockerfile with Claude Code installation
Container startup and health verification
Simple command execution test
Volume mounting validation

✅ Phase 2: Basic MCP Server

MCP server framework implementation
Health check and status endpoints
Basic error handling and logging
Container networking configuration

✅ Phase 3: Core Functionality

claude_code_analyze function implementation
claude_code_execute function implementation
Request validation and sanitization
Comprehensive error handling

🎯 Phase 4: Integration Testing

Integration with existing MCP ecosystem
Real project testing scenarios
Performance benchmarking
Tool chain validation

🎯 Phase 5: Production Hardening

Security audit and hardening
Resource optimization
Monitoring and alerting
Documentation and runbooks

🤝 Contributing

Contributions are welcome! Please read our security policy and follow the systematic development approach:

Fork the repository
Create a feature branch
Test thoroughly in isolation
Submit pull request with detailed description

📄 License

MIT License - see LICENSE file for details.

🆘 Support

Issues: GitHub Issues
Security: See SECURITY.md for vulnerability reporting
Documentation: Check the /docs directory for detailed guides

🔗 Related Projects

CORTEX-AI-Orchestrator-v2 - n8n-based AI orchestration
tool-combo-chains - Memory × Sequential × Sandbox architecture

🎯 Ready to unlock 10000x amplification through distributed AI coordination! 🚀

Built with systematic infrastructure principles by Jordan Ehrig for the MAGI distributed AI architecture.