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.

---

💡 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

git clone https://github.com/aditya1503/MCPRelay.git
cd MCPRelay
npm install
npm run build

3. Verify Health

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:

# 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:

npm run rollup

Example Output:

=== 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:

open index.html

---

📄 License

MIT License. Designed and maintained by ADIS (Artificially Developed Intelligence Services).