<div align="center">

<img src="https://raw.githubusercontent.com/Devopstrio/.github/main/assets/Browser_logo.png" height="90"/>

<h1>mcp-runtime</h1>

<p><strong>High-Performance Model Context Protocol (MCP) Execution Engine & Sandbox Runtime</strong></p>

[![Build Status](https://img.shields.io/badge/Build-Passing-10B981?style=flat-square)](https://devopstrio.co.uk)
[![Python Version](https://img.shields.io/badge/Python-3.11%2B-3776AB.svg?style=flat-square)](https://python.org)
[![MCP Sandbox](https://img.shields.io/badge/MCP-Sandbox_Runtime-8B5CF6?style=flat-square)](https://modelcontextprotocol.io)
[![Terraform](https://img.shields.io/badge/IaC-OpenTofu_1.8.5-FF5733?style=flat-square)](https://opentofu.org)

</div>

---

## Executive Summary

The **mcp-runtime** repository delivers a high-performance, isolated execution engine and context state lifecycle manager built specifically for the Model Context Protocol (MCP). It provisions ephemeral, resource-constrained sandbox containers to execute untrusted MCP tool code securely without exposing host enterprise infrastructure.

## Business Problem

Executing tools invoked by LLMs and autonomous agents presents severe runtime security and stability risks:
- **Resource Exhaustion**: Unconstrained tool code can consume excessive CPU or memory, causing noisy-neighbor degradation.
- **Malicious Payload Execution**: Untrusted code or shell tools can attempt unauthorized host file system or network access.
- **State Loss**: Stateful multi-turn tool conversations require persistent context tracking across ephemeral container executions.

## Business Value

- **Zero-Trust Process Isolation**: Enforces process sandboxing with strict cgroup memory and CPU limits per tool execution.
- **Sub-Millisecond Execution Overhead**: Low-overhead runtime container provisioning for real-time AI assistant responsiveness.
- **Stateful Context Lifecycle Persistence**: Automatically persists conversation context state across multi-turn tool calls.

## Architecture

![Architecture Diagram](images/architecture.png)

### High-Level Execution Sequence

```mermaid
graph TD
    Gateway["MCP Gateway / AI Assistant"] --> RuntimeAPI["MCP Runtime Execution API"]
    RuntimeAPI --> Executor["MCP Tool Execution Engine"]
    RuntimeAPI --> SandboxMgr["Process Sandbox Isolation Manager"]
    RuntimeAPI --> ContextMgr["Context State Persistence Manager"]
    SandboxMgr --> Container1["Sandbox Container - Memory Limit 512MB"]
    SandboxMgr --> Container2["Sandbox Container - Memory Limit 1024MB"]
```

## Core Components

- **MCP Tool Execution Engine (`src/mcp_runtime/core/executor.py`)**: Core execution pipeline running tool handlers inside isolated sandbox containers.
- **Process Sandbox Isolation Manager (`src/mcp_runtime/sandbox/process_sandbox.py`)**: Provisions, monitors, and terminates ephemeral process containers.
- **Context Lifecycle State Manager (`src/mcp_runtime/services/context_manager.py`)**: Manages state storage and context restoration for agent sessions.
- **FastAPI Async Transport Layer (`src/mcp_runtime/api/routes.py`)**: Asynchronous REST endpoints for tool execution, sandbox management, and state persistence.

## Repository Structure

```
mcp-runtime/
├── .github/              # CI/CD workflows, issue & PR templates, CODEOWNERS
├── architecture/         # Mermaid sequence flow diagrams
├── deployment/           # Kubernetes manifests & Kustomize environment overlays
├── docs/                 # Enterprise architectural, deployment, & operational guides
├── examples/             # Real-world request/response JSON payloads
├── images/               # High-resolution architecture & workflow diagrams
├── src/mcp_runtime/      # Python Runtime source (api, core, sandbox, services)
├── terraform/            # Multi-cloud OpenTofu / Terraform IaC modules
├── tests/                # Unit, integration, and API test suites
├── Dockerfile            # Container build specification
├── docker-compose.yml    # Multi-container local orchestration
├── pyproject.toml        # PEP 621 package configuration
└── README.md             # Accelerator documentation manual
```

## Capabilities

- **Ephemeral Container Sandbox**: Dynamic spawning and destruction of process sandboxes.
- **Memory & CPU Throttling**: Strict memory caps (default 512MB) and CPU core allocation per container.
- **Context State Persistence**: High-speed in-memory state tracking with disk serialization.
- **Health & Liveness Probes**: Native Kubernetes probes for container health monitoring.

## Technology Stack

- **Core Runtime**: Python 3.11+, FastAPI 0.110+, Pydantic v2
- **Infrastructure as Code**: OpenTofu 1.8.5 / Terraform 1.6+
- **Containerization**: Docker, Docker Compose, Kubernetes 1.28+
- **Quality Assurance**: Pytest 8.0+, GitHub Actions CI

## Implementation

```bash
# Clone repository
git clone https://github.com/Devopstrio/mcp-runtime.git
cd mcp-runtime

# Install in editable mode
pip install -e .[dev]

# Run automated unit and integration tests
pytest -v tests/
```

## Deployment

### OpenTofu / Terraform Provisioning

```bash
cd terraform
tofu init
tofu plan
tofu apply -auto-approve
```

### Kubernetes Kustomize Deployment

```bash
kubectl apply -k deployment/kubernetes/overlays/prod/
```

## API Reference

- `GET /health` &mdash; Returns runtime health status and version.
- `POST /api/v1/execute` &mdash; Executes an MCP tool payload inside isolated sandbox.
- `POST /api/v1/sandbox/spawn` &mdash; Spawns an ephemeral process container.
- `DELETE /api/v1/sandbox/{container_id}` &mdash; Terminates a running sandbox container.
- `POST /api/v1/context/state` &mdash; Persists context state for session.

## Examples

- [`examples/sandbox-tool-execution/`](examples/sandbox-tool-execution/) &mdash; Isolated tool execution payload
- [`examples/runtime-container-lifecycle/`](examples/runtime-container-lifecycle/) &mdash; Ephemeral container spawn payload
- [`examples/context-state-persistence/`](examples/context-state-persistence/) &mdash; Context state persistence payload

## Security

Refer to [`SECURITY.md`](SECURITY.md) for reporting security vulnerabilities. The runtime enforces process sandboxing and cgroup resource isolation.

## Observability

The platform exports structured CloudWatch log groups (`/aws/mcp-runtime/mcp-runtime`) and metric alarms for sandbox memory exhaustion tracking.

## Scalability

Horizontal pod autoscaling (HPA) overlays scale runtime worker replicas dynamically based on active container CPU load.

## Multi-cloud Strategy

Infrastructure blueprints support AWS ECS/VPC deployment with modular extensions for Docker and Kubernetes containerd runtimes.

## Roadmap

See [`docs/Roadmap.md`](docs/Roadmap.md) for upcoming milestones including gVisor / Firecracker MicroVM integration and dynamic CPU cgroup throttling.

## Contribution

See [`CONTRIBUTING.md`](CONTRIBUTING.md) and [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) for community standards and contribution workflows.

---

<div align="center">
© 2026 Devopstrio — Engineering the Autonomous Enterprise.
</div>