AltairaLabs CodeGen MCP

Distributed sandbox and Model Context Protocol (MCP) provider for LLM-driven code generation and testing.

---

🧩 Overview

AltairaLabs CodeGen MCP is an open-source distributed execution layer that allows LLMs to safely generate, edit, and test code inside isolated sandboxes — all via the Model Context Protocol (MCP).

It provides an MCP provider and runtime that works like a lightweight CI system for agents:

• Coordinated pool of Docker-based worker agents
• Coordinator service exposing the MCP endpoint
• Safe, ephemeral code sandboxes
• Optional shared filesystem or object store for recovery
• Direct integration with PromptKit / Arena workflows

---

🏗️ Architecture

flowchart TB
    subgraph Coordinator["🧠 CodeGen Coordinator (Control Plane)"]
        MCP["MCP Server (public endpoint)"]
        Router["Session Router & Registry"]
        Store["Session Store (Redis/Postgres)"]
    end

    subgraph Worker["⚙️ Docker Worker Agent (Data Plane)"]
        API["Agent API (gRPC)"]
        Sandbox["Per-Session Sandboxes"]
        Vol["Ephemeral FS (mounted volume or object storage)"]
    end

    subgraph Client["🗣️ LLM / PromptKit Runtime"]
        Arena["Arena / PromptPack Workflow"]
    end

    Client -->|"MCP Calls"| MCP
    MCP --> Router
    Router -->|Route Command| API
    API --> Sandbox
    Sandbox --> Vol
    API --> Router
    Router --> Store
    Router -->|Stream Results| MCP
    MCP --> Client

Loading

---

🛠️ Development

📖 Docker Compose Getting Started Guide

Complete deployment guide with:

• 🚀 Quick start instructions
• 📊 Architecture diagrams
• ⚙️ Configuration options
• 🧪 Testing and troubleshooting
• 🔧 Development workflow

Quick Start

# Clone the repository
git clone https://github.com/AltairaLabs/codegen-mcp.git
cd codegen-mcp

# Run the full CI pipeline locally
make ci

Available Make Targets

make help              # Show all available targets
make install           # Install dependencies and protoc plugins
make build             # Build coordinator and worker binaries
make test              # Run all tests
make test-unit         # Run tests with coverage (used in CI)
make lint              # Run linters (development mode)
make lint-ci           # Run linters in strict mode (used in CI)
make coverage          # Generate coverage report
make ci                # Run full CI pipeline locally
make clean             # Clean build artifacts

CI Pipeline

The GitHub Actions CI pipeline uses make targets for consistency:

1. Test Job: make install → make test-unit
2. Lint Job: make install → make lint-ci
3. Build Job: make install → make build

To emulate the CI pipeline locally, simply run:

make ci

This runs the same steps as CI:

• Install dependencies
• Build binaries
• Run tests with coverage
• Run linters in strict mode

Prerequisites

• Go 1.25+
• Protocol Buffers compiler (protoc)
• golangci-lint for linting

Coverage

Current test coverage: ~85%

make coverage

View detailed coverage:

go tool cover -html=coverage.out

---

📚 Documentation

For detailed documentation, see:

• docs/ - Complete documentation
• docs/coordinator/ - Coordinator documentation
• docs/worker/ - Worker documentation
• docs/local-backlog/e2e-test-proposal.md - E2E testing implementation

---

📄 License

Apache 2.0 - See LICENSE for details

Copyright © 2025 AltairaLabs.ai