内容
# orcho-mcp
[](https://pypi.org/project/orcho-mcp/)
[](https://pypi.org/project/orcho-mcp/)
[](LICENSE)
[](https://github.com/symphos-ai/orcho-mcp/actions/workflows/ci.yml)
[](https://github.com/symphos-ai/orcho-mcp/actions/workflows/dco.yml)
[](https://github.com/symphos-ai/orcho-mcp/actions/workflows/release.yml)
[](https://codecov.io/gh/symphos-ai/orcho-mcp)
[](https://scorecard.dev/viewer/?uri=github.com/symphos-ai/orcho-mcp)
适用于 Orcho 的[模型上下文协议](https://modelcontextprotocol.io) 服务器。
通过 stdio 向 MCP 感知客户端（Claude Code、Cursor、Zed 等其他 MCP 客户端）公开 Orcho 的运行时。完整的异步控制循环 — 执行、观察、决策、检查 — 无需原始日志抓取。
> **状态：** `v0.1.0` 公共发布线。核心控制循环表面可用：
>
> - **执行**：`orcho_run_start` / `orcho_run_resume` / `orcho_run_cancel`，具有 L4 测试固定语义（进程组信号处理、监督者拥有的重启恢复、竞争感知取消）。
> - **观察**：`orcho_run_status` / `orcho_run_history` / `orcho_run_metrics` / `orcho_run_events_tail` — 只读、适合轮询。
> - **决策**：`orcho_phase_handoff_decide` — 通用阶段交接状态转换，用于暂停运行。管道在阶段的声明 `handoff` 策略触发时暂停，状态为 `awaiting_phase_handoff`；`continue` / `retry_feedback` / `halt` 编写决策工件（`halt` 同步翻转 `meta.status` 为 `halted`）。纯状态转换；从不生成。
> - **检查**：`orcho_run_evidence` — 类型检查切片（`plan` / `findings` / `commands` / `artifacts` / `errors` / `sub_runs` / `all`），具有严重性过滤（P0..P3）。
>
> 实时进度：`orcho_run_watch` 在 MCP 请求携带 `progressToken` 时发出有序 `notifications/progress`。不携带 `progressToken` 的客户端轮询 `orcho_run_status` / `orcho_run_events_tail` 以获取相同运行状态。
## 安装
如果缺少 `pipx`，请先安装它。在使用 Homebrew 的 macOS 上：
```bash
brew install pipx
pipx ensurepath
exec zsh -l
```
对于 Linux 或 Windows，请使用
[官方 pipx 安装指南](https://pipx.pypa.io/stable/installation/).
### 推荐的 CLI 安装
使用带有 `mcp` 额外功能的 `orcho` 发行版，您希望从 shell 中获得 Orcho 命令和 MCP 服务器。`pipx` 将命令集与当前项目或 Python 环境隔离。
```bash
pipx install "orcho[mcp]"
orcho-mcp --help
```
### 直接 MCP 包安装
在您有意将 `orcho-mcp` 放入活动虚拟环境、CI 镜像、开发容器或 Docker 镜像中时，请使用 `pip`。
```bash
python -m pip install orcho-mcp
```
这将拉取 `orcho-core`（引擎）、官方 `mcp` Python SDK 和 orcho-mcp 依赖的运行时件。
## 创建工作区
Orcho 将运行状态写入 Orcho 工作区。首先，将其指向分组您的项目仓库的文件夹：
```bash
orcho workspace init ~/www/my-workspace
```
该命令创建 `~/www/my-workspace/workspace-orchestrator/`，包括 `.orcho/` 设置和扩展点指南，并打印该工作区的 MCP 配置片段。要将片段直接写入项目本地 MCP 配置：
```bash
ORCHO_MCP_COMMAND="$(command -v orcho-mcp)"
orcho workspace init ~/www/my-workspace \
--mcp-config ~/www/my-workspace/.mcp.json \
--mcp-server-name orcho-my-workspace \
--orcho-mcp-command "$ORCHO_MCP_COMMAND"
```
`ORCHO_MCP_COMMAND` 必须指向 MCP 客户端可以运行的命令。对于打包安装，通常这是 `orcho-mcp`。对于源代码安装，请使用 Orcho 环境中的绝对路径，例如 `/Users/me/orcho-preview/orcho-core/.venv/bin/orcho-mcp`。
每个 MCP 服务器进程通过 `ORCHO_WORKSPACE` 拥有一个工作区。对于多个工作区，请添加多个 MCP 服务器条目。
## 注册到 MCP 感知客户端
每个客户端都有自己的 MCP 注册表/配置格式。请使用
[`docs/mcp_client_setup.md`](docs/mcp_client_setup.md) 中的复制粘贴说明，适用于 Codex CLI/app、Claude Code、Gemini CLI、Claude 应用程序和 Antigravity。
## 内容
```bash
npx @modelcontextprotocol/inspector orcho-mcp
```
在 localhost 上打开一个 Web UI，显示每个注册的工具、资源和提示，并具有完整的 JSON 模式 - Anthropic 的官方 Inspector ≈ Swagger UI for MCP。
静态目录也提交在 [`docs/mcp_schema.json`](docs/mcp_schema.json) 中 - 相同的形状，在 CI 中快照。
## 控制循环
完整的合约 — 通过 MCP 线启动、观察、恢复、取消、决策（QA 关卡）和检查运行 — 位于 [`docs/run_lifecycle.md`](docs/run_lifecycle.md) 中。工具文档字符串保持简洁；该文件是长格式参考。
工具命名一致：每个运行生命周期工具都是 `orcho_run_<verb>`。状态转换和检查工具与该组一起位于它们自己的名称下：
| 组 | 工具 |
|---|---|
| **执行** | `orcho_run_start`、`orcho_run_resume`、`orcho_run_cancel` |
| **观察** | `orcho_run_status`、`orcho_run_history`、`orcho_run_metrics`、`orcho_run_events_tail` |
| **决策** | `orcho_phase_handoff_decide` |
| **检查** | `orcho_run_evidence`、`orcho_run_diff` |
有关使用代码完成整个控制循环的演练，请参阅 [`docs/control_loop_walkthrough.md`](docs/control_loop_walkthrough.md)。
## 架构
orcho-mcp 是公共 Orcho 运行时包之一：
- `orcho-core` — 管道运行时 + CLI（Apache-2.0）。
- **`orcho-mcp`** — MCP 服务器，本仓库（Apache-2.0）。
v1 跨 MCP 消费者路线图（orcho-as-MCP-client — 管道代理调用外部 GitHub / Linear / Slack MCP 服务器）记录在 `orcho-core/docs/plans/2026-05-06-cross-mcp-orchestration.md` 中。
对于贡献者面向的架构和测试指导：
- [`docs/architecture/mcp_boundaries.md`](docs/architecture/mcp_boundaries.md)
描述了架构测试强制执行的包边界。
- [`docs/architecture/observation_delivery.md`](docs/architecture/observation_delivery.md)
定义了 MCP 观察和通知使用的持久重放合约。
- [`docs/testing.md`](docs/testing.md) 解释了测试理念、分层模型、夹具样式和验证命令。
## 许可证
Apache-2.0。参见 [LICENSE](LICENSE)。
