orchestrator-mcp

面向主 Agent 的多模型 Review Hub MCP：按角色提供 UI 审查、代码审查、通用审查能力，返回可追踪的结构化审查结果。

它不是软件交付流水线，也不负责 plan → code → deliver。它不会实现修复、修改工作区、提交 commit、push 或创建 PR；最终如何处理审查结果，由调用它的主 Agent 决定。

调用方必须提供本次审查的目标和真实证据。MCP 负责把请求路由给一个配置好的 review 角色，保存本次 run 的 handoff，并将结果交还给主 Agent。Review verdict 只是审查意见，不会自动成为其他任务的事实依据。

• Review handoff schema 固定（schemas/）

• Provider 按厂商（deepseek / moonshot / zhipu / openai / codex-lb），model 按 role 配置

• 别名：glm → zhipu，gpt → openai

• 凭证：环境变量 → WebUI 本地 JSON → ~/Desktop/服务器.md

• Web 配置界面：编辑 Provider Key / Base URL / 默认模型，以及各 Profile 的 Role 模型

给 AI Agent 的安装指令

若你是 Cursor / Codex 等 AI Agent，帮用户安装 orchestrator-mcp 时，按顺序执行以下命令，不要跳过检测步骤。

# 1. 进入仓库（clone 后或用户已有目录）
cd /path/to/orchestrator-mcp

# 2. 一键安装（创建 venv、装依赖、离线自测、生成 Cursor 配置）
./install.sh

# 3. 确认依赖与健康状态（必须 exit 0）
./install.sh --check-only
./scripts/orchestrator-doctor.sh

# 4. 可选：跑单元测试
PYTHONPATH=src .venv/bin/python -m unittest discover -s tests

安装成功标志：

• ./install.sh 末尾输出 PASS (self-test)

• ./install.sh --check-only 输出 "ok": true

• ./scripts/orchestrator-doctor.sh 输出 "ok": true

• Cursor 中 Settings → Tools & MCP 出现 orchestrator-mcp 且为绿点

安装后告诉用户：

1. 在 Cursor 打开本仓库（或把 .cursor/mcp.json.example 路径改成实际 clone 目录）

2. 配置 API Key：环境变量（见「凭证环境变量」）或 ./start-webui.sh 打开 WebUI

3. MCP 工具以 orchestrate_* 开头；先 orchestrate_run_start，再 orchestrate_dispatch

macOS + Codex 额外步骤：

./install.sh --launchd
./scripts/orchestrator-doctor.sh
# 新建 Codex 任务或重启 Codex App

Related MCP server: spiderswitch

安装与使用指南

前置要求

Python 包（由 install.sh 自动安装，见 requirements.txt）：

• mcp>=1.9.0

• PyYAML>=6.0.1

• fastapi>=0.115.0

• uvicorn[standard]>=0.32.0

一键安装（推荐）

git clone <repo-url> orchestrator-mcp
cd orchestrator-mcp
./install.sh

./install.sh 会自动完成：

1. 检测系统命令（git）

2. 调用 ensure-venv.sh 创建 .venv 并 pip install -r requirements.txt

3. 调用 scripts/check_deps.py 校验 Python 包与仓库文件

4. 赋予启动脚本可执行权限

5. 生成本地 .cursor/mcp.json（含本机绝对路径，不进 git）

6. 运行离线自测 orchestrator_mcp.self_test

脚本速查

安装后验证

# 依赖是否齐全（应输出 "ok": true）
./install.sh --check-only

# 健康检查（应输出 "ok": true）
./scripts/orchestrator-doctor.sh

# 离线功能自测
./verify.sh

# 单元测试（35 项）
PYTHONPATH=src .venv/bin/python -m unittest discover -s tests -v

# 可选：真实 LLM 调用冒烟（需要已配置 API Key）
ORCHESTRATOR_LIVE_TEST=1 ./verify.sh

使用场景

场景 A：Cursor（stdio，推荐）

无需手动 ./start.sh，Cursor 会自动拉起 MCP 进程。

./install.sh                                    # 生成本仓库 .cursor/mcp.json
# Cursor → 打开本仓库 → Settings → Tools & MCP → 启用 orchestrator-mcp

若要在其他项目使用，复制模板并改路径：

cp .cursor/mcp.json.example /your-project/.cursor/mcp.json
# 编辑 mcp.json，把 /ABSOLUTE/PATH/TO/orchestrator-mcp 改成实际路径

场景 B：HTTP 模式（任意 MCP Client）

./install.sh
./start.sh
# MCP 地址：http://127.0.0.1:18067/mcp
# 终端需保持运行；或使用 --launchd 后台运行

场景 C：WebUI 配置 Provider

./install.sh
./start-webui.sh
# 浏览器打开 http://127.0.0.1:18068
# 配置写入 data/providers.local.json、data/roles.local.json（不进 git）

场景 D：macOS Codex + 后台服务

./install.sh --launchd
./scripts/orchestrator-doctor.sh
# 新建 Codex 任务或重启 Codex App（已有任务不会热加载 MCP）

故障排查

重新安装（干净重建 venv）：

rm -rf .venv
./install.sh

快速开始

cd orchestrator-mcp
./install.sh               # 首次安装（推荐）
./start.sh                 # 可选：HTTP MCP :18067
./start-webui.sh           # 可选：配置 WebUI :18068

本机可靠部署（Codex + launchd，macOS）

cd orchestrator-mcp
./install.sh --launchd     # venv + Codex stdio 配置 + launchd HTTP MCP/WebUI
./scripts/orchestrator-doctor.sh

也可分步：

./install.sh               # 基础安装
./scripts/install-local.sh --codex-only   # 仅写 ~/.codex/config.toml
./scripts/install-local.sh --launchd      # 含 launchd 后台服务

安装器会：

• 修复/准备可迁移 venv，并始终通过 python -m pip 安装依赖；

• 将 Codex 配置为 per-session stdio；若客户端转发 CODEX_THREAD_ID 就按线程隔离，否则 wrapper 使用进程级 session id，避免因客户端未转发该变量而无法启动；

• 将 launchd HTTP MCP 固定到 18067，WebUI 固定到 18068；

• 备份现有 Codex 配置和 launchd plist；

• 等待 launchd job 完成卸载、重新加载并真正开始监听后才返回成功。

doctor 同时检查配置路径、transport、plist、监听数量和进程 cwd。安装后需要新建 Codex 任务或重启 Codex/ChatGPT App，已有任务不会热注册新的 MCP 工具。

评审调用必须提供真实可审查证据。code_review 在传入 workspace 时会按 diff_scope （默认 branch_changes）自动注入 unified diff；也可在 extra_context 中直接附 patch/代码。 无 diff/代码证据时 code_review 会返回 verdict=evidence_insufficient，不会假审。 可选结构化字段：requirements / verification / known_risks / custom_instructions / base_sha / head_sha（diff_scope=sha_range 时）。 handoff 为 review.v1：verdict + findings[{severity,location,what,why,fix}] + blocking + suggestions。 一致性：pass 不得含 Critical/Important；revise 至少一条 Critical/Important finding。 模型 JSON 不合 schema 时自动重试修复一轮。自动 diff 会排除 lockfile / 二进制 / node_modules 等噪音路径。 主 Agent 调用约定见仓库 .cursor/skills/orchestrator-code-review/SKILL.md。

主 Agent 与 Review Hub 的交接

推荐交接内容是一个明确的 review request：目标、变更文件、diff 或代码范围、证据、已执行验证和已知风险。Review Hub 将同一份请求上下文交给对应角色，并返回独立的 review handoff；不要依赖隐藏聊天记录补全审查范围。

基本关系如下：

主 Agent -- review request + evidence --> Review Hub
Review Hub -- 同一请求上下文 + 角色规则 --> UI / Code / General Reviewer
Reviewer -- structured findings + blockers + evidence --> Review Hub
Review Hub -- independent handoffs --> 主 Agent

启动入口

安装与排错详见上方 安装与使用指南。

说明：

• WebUI 不是 MCP tool，本身不会出现在工具列表里

• WebUI 只是本地配置界面；真正暴露给 MCP Client 的是 orchestrate_* 这些工具

• 默认端口可通过 ORCHESTRATOR_WEBUI_HOST、ORCHESTRATOR_WEBUI_PORT、ORCHESTRATOR_MCP_HOST、ORCHESTRATOR_MCP_PORT 覆盖

Web 配置界面

本地配置文件不进 git。环境变量仍优先于 WebUI 写入的值。

安全说明

• data/providers.local.json、data/roles.local.json 等 WebUI 写入的本地配置文件包含明文 API key。每次写入后会自动 chmod 600（仅文件属主可读写），请勿手动放宽权限或把这些文件提交到 git。

• WebUI 默认监听 127.0.0.1:18068，仅在本地访问。如需把 WebUI 暴露到非本机网络，务必设置环境变量 ORCHESTRATOR_WEBUI_TOKEN 加锁：设置后所有请求必须携带该 token，否则返回 401。未设置时不强制认证，保持向后兼容。

• 访问 token 的传递方式：HTTP 头 Authorization: Bearer <token>，或查询参数 ?token=<token>。

• 环境变量注入的密钥（*_API_KEY）不会落盘，优先级高于本地 JSON；能用环境变量时优先用环境变量。

Profile

同一厂商下切换模型：只改 YAML 或 WebUI Roles 里的 model，不用建两个 provider。

roles:
  ui_review:
    provider: codex-lb
    model: gpt-5.4
  code_review:
    provider: codex-lb
    model: gpt-5.4
  general_review:
    provider: deepseek
    model: deepseek-v4-flash

凭证环境变量

Codex 中转（Responses API）

与 Codex CLI 配置对应关系：

model = "gpt-5.4"
model_reasoning_effort = "medium"
model_provider = "codex-lb"
env_key = "CODEX_LB_API_KEY"

[model_providers.codex-lb]
base_url = "https://codex-lb.vvicat.dev/backend-api/codex"
wire_api = "responses"

在 WebUI Providers → Codex 中转 填写：

Role 里可把 ui_review / code_review 的 provider 选 codex-lb（或别名 codex），model 填 gpt-5.4。

注意：/chat/completions 在该中转上返回 405；必须用 Responses 协议。

可选覆盖：CODEX_LB_BASE_URL、DEEPSEEK_BASE_URL、MOONSHOT_BASE_URL、ZHIPU_BASE_URL、OPENAI_BASE_URL

服务器.md 标签（下一行或同行）：deepseekApiKey、moonshotApiKey、zhipuApiKey、openaiApiKey

Workspace 项目上下文（与 IDE 共用源文件）

MCP 不单独维护记忆文件。传入 workspace（或设置 ORCHESTRATOR_WORKSPACE）后，每个 role 直接从磁盘读取与 Cursor/Codex 相同的源文件并注入 prompt：

• orchestrate_run_start：role、workspace、extra_context（仅本次 run）

• orchestrate_workspace_context：预览将读取哪些文件

MCP 工具

Provider 选择规则

• Providers 页只表示“这个厂商已配置 key / base_url / 默认模型”。

• 真正决定 MCP 执行使用哪个 provider 的是 Roles 页；保存后写入 data/roles.local.json。

• 调用前可先跑 orchestrate_effective_config(role="ui_review")，确认有效配置，避免误跑到 YAML 默认值。

• 先调用 orchestrate_run_start(goal="...", role="ui_review") 创建单角色 run，再调用 orchestrate_dispatch(run_id) 执行该角色。

• 每个 run 只能绑定一个 Review 角色；MCP 不提供串联或并联多个 Review 角色的入口。

• role_overrides_json 支持短写：{"provider":"codex-lb","model":"gpt-5.4"} 或 {"code_review":{"model":"codex/gpt-5.4"}}。

• 兼容旧入参：review 会映射到 general_review。

Cursor 配置

完整安装流程见 安装与使用指南 → 场景 A。

运行 ./install.sh 会在本仓库生成 .cursor/mcp.json（已 gitignore，含本机绝对路径）。

也可参考 .cursor/mcp.json.example，把路径改成你的 clone 目录后放到任意项目根目录。

1. 用 Cursor 打开目标仓库根目录

2. Settings → Tools & MCP，确认 orchestrator-mcp 已启用（绿点）

3. 若没有，点 Refresh 或重启 Cursor

若仍看不到：Settings → MCP → Edit Config，确认项目级 .cursor/mcp.json 已加载。

验收：./scripts/orchestrator-doctor.sh 应返回 "ok": true。

方式 A（推荐，已写入项目）：Cursor 自动拉起进程

{
  "mcpServers": {
    "orchestrator-mcp": {
      "command": ".../orchestrator-mcp/.venv/bin/python",
      "args": ["-m", "orchestrator_mcp"],
      "env": {
        "PYTHONPATH": ".../orchestrator-mcp/src",
        "ORCHESTRATOR_MCP_TRANSPORT": "stdio"
      }
    }
  }
}

方式 B：先 ./start.sh，再用 URL（需保持终端进程运行）

{
  "mcpServers": {
    "orchestrator-mcp": {
      "url": "http://127.0.0.1:18067/mcp"
    }
  }
}