# relayos-mcp

<div align="center">

<h3>🤖 Claude Code 即 AI 团队指挥部</h3>
<p><b>让昂贵的模型运筹帷幄，让免费的终端 Agent 披荆斩棘。</b></p>

[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue?style=flat-square&logo=anthropic)](https://modelcontextprotocol.io/)
[![Python](https://img.shields.io/badge/Python-3.10%2B-blue?style=flat-square&logo=python)](https://python.org)
[![Claude Code](https://img.shields.io/badge/Claude%20Code-Plugin-purple?style=flat-square)](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code)
[![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)](LICENSE)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://github.com/jjjjjjjjnnjnn/relayos-mcp/pulls)

[English](#-english) • [中文说明](#-中文说明) • [快速安装](#-快速安装) • [工具清单](#-mcp-工具矩阵)

</div>

---

## 🌟 核心理念：以最小 Token 消耗，做最高质量的交付

```mermaid
graph LR
    User["👤 开发者需求"] --> Orchestrator["🧠 Claude Code / Cursor (统帅)"]
    Orchestrator -->|"MCP 调度协议"| RelayOS["⚡ relayos-mcp 核心网关"]
    RelayOS -->|"免费并行派发"| Worker1["💻 Mimo AI (基础分析)"]
    RelayOS -->|"并行任务"| Worker2["🛠️ OpenCode (代码生成)"]
    RelayOS -->|"本地沙箱执行"| Worker3["⚙️ Local CLI (测试与运行)"]
    Worker1 --> RelayOS
    Worker2 --> RelayOS
    Worker3 --> RelayOS
    RelayOS -->|"聚合报告"| Orchestrator
    Orchestrator -->|"高质量收敛输出"| User
```

- **💰 降本 90%**：单调重复的文档抓取、语法检查、单元测试跑批全部下沉给免费或轻量终端 Agent；
- **⚡ 并行异步**：多任务并发调度，不阻塞主对话上下文；
- **🎯 质量把关**：Claude Code 专注于核心架构设计、逻辑审核与最终代码合入。

---

## 🚀 快速安装

### 1. 安装 pip 包
```bash
pip install relayos-mcp[mcp]
```

### 2. 检查本地 Agent 可用性
```bash
relay-task agents
```
输出应显示可用 Agent 列表：
```text
[ok] mimo (local / free)
[ok] opencode (terminal worker)
[ok] claude (deep reasoning)
```

### 3. 配置到 Claude Code
编辑 `~/.claude/settings.json`（或项目级 `.claude.json`）：
```json
{
  "mcpServers": {
    "relayos": {
      "command": "relayos-mcp",
      "args": []
    }
  }
}
```

*如果你使用 Claude Desktop，同样可将上述配置添加至 `claude_desktop_config.json`。*

---

## 🛠️ MCP 工具矩阵

| 工具名称 | 对应功能 | 推荐场景 | 计费成本 |
| :--- | :--- | :--- | :---: |
| `run_command` | 本地安全沙箱命令执行 | 跑测试、构建项目、环境探测 | **免费** |
| `ask_mimo` | 调度 Mimo AI 终端 | 基础语法审查、初阶重构建议 | **免费** |
| `ask_opencode` | 调度 OpenCode 编写代码 | 批量模版生成、脚手架构建 | **免费** |
| `ask_claude` | 复杂深度多步推理任务 | 高难度算法推演、架构最终仲裁 | 按 Token 计费 |

---

## 💡 典型实战场景

```text
你: "给这个项目写完全部单元测试，并跑通 pytest"
 └─► Claude Code (主脑规划):
      ├─► 调用 ask_opencode: 生成 5 个模块的基础单元测试代码 (免费)
      ├─► 调用 run_command: "pytest tests/ -v" (免费本地执行)
      ├─► 发现 1 个边界条件断言失败
      └─► Claude Code 亲自修复 bug，提交代码，输出优雅报告给你！
```

---

## 📂 项目结构

```
relayos-mcp/
├── relayos_mcp/
│   ├── __init__.py
│   ├── server.py         # MCP 服务端核心实现
│   ├── agents/           # Mimo / OpenCode / Claude 适配驱动
│   └── utils/            # 协议编解码与超时重试控制
├── claude_prompt.md      # 推荐给 Claude Code 的系统提示词模板
├── pyproject.toml        # 构建配置文件
└── README.md
```

## 📄 开源许可证

本项目采用 [MIT 许可证](LICENSE)。欢迎提交 Issue 或 Pull Request！