# MCPRelay ⚒️

> **Model Context Protocol (MCP) bridge for hybrid agentic coding — delegating token-heavy implementation to local open-source models.**  
> *Architect in the cloud. Implement locally. Save 60–90% premium API tokens.*

[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue.svg)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20-green.svg)](https://nodejs.org/)
[![Built by ADIS](https://img.shields.io/badge/Built%20by-ADIS-purple.svg)](https://adis.ltd)

---

## 💡 The Problem & The Solution

In traditional agentic coding setups, frontier models (OpenAI Codex, Claude 3.7 Sonnet / Opus) execute every step of the workflow: from high-level reasoning to reading thousands of repository lines, running test suites, and fixing compiler errors.

**This is extremely expensive and inefficient:**
- Over **80% of total tokens** are consumed in repetitive, mechanical loops (file discovery, syntax fixes, unit-test iterations).
- Proprietary codebase context is repeatedly streamed to external cloud APIs.

**MCPRelay solves this with Hybrid Agentic Coding:**
1. **Frontier Model (Cloud)**: Acts as the **Architect and Reviewer** (high intelligence, low token volume).
2. **MCPRelay (MCP Boundary)**: Dispatches structured, bounded task specifications and manages local sandboxes.
3. **Local Open-Source Model (Local LLM)**: Runs high-token implementation, editing, and test-debug loops locally with zero marginal API cost.
4. **Frontier Review**: The cloud model inspects only the concise diff, logs, and summary to verify correctness.

```
   ┌──────────────────────────────────────────────────────────┐
   │                  1. ARCHITECT / REVIEWER                 │
   │                      (Codex / Claude)                    │
   │       • Understands requirement  • Reviews diff & logs   │
   └────────────────────────────┬─────────────────────────────┘
                                │
                    [MCP Task Specification]
                                │
                                ▼
   ┌──────────────────────────────────────────────────────────┐
   │                    2. MCPRELAY (MCP)                     │
   │      • Session continuity      • Privacy boundary        │
   │      • Cross-process locks     • Telemetry ledger        │
   └────────────────────────────┬─────────────────────────────┘
                                │
                    [Local Inference Stream]
                                │
                                ▼
   ┌──────────────────────────────────────────────────────────┐
   │                3. IMPLEMENTATION WORKER                  │
   │           (DeepSeek V4 Flash / Qwen 2.5 / 3.5)           │
   │  ┌────────────────────────────────────────────────────┐  │
   │  │ 🔄 LOCAL ITERATION LOOP                            │  │
   │  │ Read Repo ➔ Edit Code ➔ Run Tests ➔ Fix Errors    │  │
   │  └────────────────────────────────────────────────────┘  │
   └──────────────────────────────────────────────────────────┘
```

---

## ✨ Key Features

- 📉 **60–90% Premium Token Reduction**: Keeps token-intensive code edits, file indexing, and test-debugging entirely on local hardware.
- 🛡️ **Strict Privacy & Security Boundaries**: Sensitive internal files and multi-round diagnostic dumps stay inside your local network.
- 🔄 **Session Continuity**: Multi-turn follow-ups (`opencode_followup`) resume the same execution session without re-sending the whole repository context.
- 🔒 **Cross-Process Repository Locking**: Prevents conflicting concurrent writes across multiple agent tabs or clients.
- 📊 **Telemetry & Audit Ledger**: Automatic recording of execution duration, files touched, lines added/deleted, and estimated token savings to `state/ledger.jsonl`.
- ⚡ **Zero-Config Client Registration**: Single command setup for **Codex**, **Claude Code**, **Claude Desktop**, and **Antigravity**.

---

## 🛠️ MCP Tools Reference

MCPRelay registers 8 native tools over standard Model Context Protocol (stdio/JSON-RPC):

| Tool | Description |
| :--- | :--- |
| `opencode_implement` | Dispatches a bounded task specification (goal, constraints, interfaces, context) to the local worker. |
| `opencode_wait` | Single blocking wait until a running task reaches terminal state (`completed` / `failed`). Replaces status polling loops. |
| `opencode_status` | Non-blocking status snapshot of an active or finished task. |
| `opencode_diff` | Returns a scoped git diff of changes made by the local worker against the baseline commit. |
| `opencode_followup` | Resumes an existing OpenCode session to fix defects, adjust edge cases, or add tests based on review feedback. |
| `opencode_cancel` | Gracefully terminates a running task and its child processes. |
| `opencode_health` | Checks local model endpoint availability, opencode CLI health, and active model configuration. |
| `opencode_history` | Queries past delegation outcomes, duration, and success rates for a given repository. |

---

## 🚀 Quick Start

### 1. Prerequisites
- **Node.js**: `>= 20.0.0`
- **OpenCode CLI**: Installed and accessible in `PATH` (`npm i -g opencode-ai` or binary)
- **Local Inference Model**: A running OpenAI-compatible endpoint (e.g. DeepSeek V4 Flash, Qwen 2.5/3.5 on vLLM, Ollama, SGLang, or dual DGX Spark clusters).

### 2. Install & Build
```bash
git clone https://github.com/aditya1503/MCPRelay.git
cd MCPRelay
npm install
npm run build
```

### 3. Verify Health
```bash
npm run dev
# or run health check
tsx tests/v2.test.ts
```

### 4. Connect to Your AI Client

MCPRelay includes an automated client registrar script:

```bash
# Register with OpenAI Codex / Antigravity
node scripts/register-client.mjs antigravity

# Register with Claude Code
node scripts/register-client.mjs claude-code

# Register with Claude Desktop
node scripts/register-client.mjs claude-desktop
```

---

## ⚙️ Configuration

Set environment variables in your environment or client config:

| Variable | Default | Description |
| :--- | :--- | :--- |
| `OPENCODE_MODEL` | `spark/deepseek-v4-flash-0731` | Model identifier passed to OpenCode. |
| `WORKER_HEALTH_URL` | `http://127.0.0.1:8890/v1/models` | Health endpoint for the local inference server. |
| `ALLOWED_REPO_ROOT` | Current working directory | Root directory whitelist to prevent path traversal. |
| `TASK_TIMEOUT_MS` | `600000` (10 mins) | Maximum execution time before automatic termination. |

---

## 📊 Telemetry & Reporting

Every finished task automatically records telemetry into `state/ledger.jsonl`. Run the built-in rollup tool to analyze savings:

```bash
npm run rollup
```

**Example Output:**
```text
=== MCPRelay Telemetry Rollup ===
Total Tasks: 42
Success Rate: 95.2%
Avg Task Duration: 28.4s
Estimated Cloud Tokens Saved: ~1.85M tokens
Top Task Classes: unit-test-generation, bugfix, refactoring
```

---

## 🎨 Interactive Architecture Infographic

This repository includes a standalone interactive HTML infographic diagram visualizing the complete MCP delegation flow:

```bash
open index.html
```

---

## 📄 License

MIT License. Designed and maintained by [ADIS (Artificially Developed Intelligence Services)](https://adis.ltd).