hostrunner-mcp

English | [繁體中文](README_zh.md) # 主机运行器-MCP [](https://github.com/jerryctt/hostrunner-mcp/actions/workflows/ci.yml) [](LICENSE) 本地MCP服务器 + Claude插件，用于在您的机器上进行只读Codex代码审查 — 编辑 → 审查 → 编辑循环，连接Claude沙盒到您的主机代码编辑器。 --- ## 目的 / 为什么 [Claude Cowork](https://claude.ai) 在隔离的沙盒中编辑代码。该沙盒无法运行主机的 `codex` CLI（它未安装在那里，并且无法访问您的身份验证令牌或本地文件）。**hostrunner-mcp** 弥补了这一差距： - 它作为 **Mac或Linux机器上的本地进程** 运行，由Claude Desktop通过stdio启动。 - 它可以访问主机的文件系统、您的 `codex` 二进制文件和身份验证凭证。 - Cowork在您共享的文件夹中编辑文件，然后调用服务器的工具来触发主机上的只读 `codex` 审查，并接收审查结果。 - 这使得在不离开Cowork的情况下实现紧密的 **编辑 → 审查 → 编辑** 循环。 --- ## 工作原理 ``` ┌─────────────────────────────────────────────────────────┐ │ Claude Cowork (沙盒) │ │ │ │ ┌────────────┐ 编辑文件 ┌──────────────────┐ │ │ │ AI 代理 │ ──────────────► │ 挂载文件夹 │ │ │ │ (Cowork) │ │ /sessions/…/mnt │ │ │ └─────┬──────┘ └────────┬─────────┘ │ │ │ MCP工具调用 │ │ │ │ codex_review(folder=/Users/…) │ │ └────────┼─────────────────────────────────┼─────────────┘ │ stdio (MCP协议) │ 主机文件系统挂载 ▼ ▼ ┌─────────────────────────────────────────────────────────┐ │ 主机机器 │ │ │ │ ┌──────────────────┐ ┌────────────────┐ │ │ │ hostrunner-mcp │ codex审查│ git仓库 │ │ │ │ (本地进程) │ ────────────►│ /Users/…/proj │ │ │ │ │ │ codex CLI │ │ │ └──────────────────┘ └────────────────┘ │ │ 由Claude Desktop启动 │ └─────────────────────────────────────────────────────────┘ ``` --- ## 功能 - **`codex_review`** — 对未提交的更改、基准分支差异或特定提交运行只读 `codex审查`。`codex` 自身计算差异 — 无需我们的git处理。 - **`run_command`** — 在主机文件夹中运行任何允许的CLI（例如 `git`、`codex`），作为argv数组（从不使用shell）。 - **严格的安全性** — 命令名称允许列表、根目录限制、符号链接解析路径检查、从不使用shell。 - **可配置** — 允许的根目录、允许的命令、超时、最大输出大小和可选的额外codex标志。 - **审计日志** — 每个工具调用都通过zerolog记录到stderr。 - **可扩展** — 通过在配置中允许列表来添加其他CLI（例如 `gemini`）。 --- ## 要求 | 要求 | 说明 | |---|---| | **codex CLI** | 必须在主机上安装并认证（`codex` 在 `$PATH` 中） | | **Claude Desktop** | 需要注册和启动MCP服务器 | | **Go 1.25+** | 仅在从源代码构建时需要；预构建的发布二进制文件不需要Go | --- ## 安装 ### 选项1：使用 `go install` 安装（推荐，如果您有Go） ```bash go install github.com/jerryctt/hostrunner-mcp/cmd/hostrunner@latest ``` 二进制文件放置在 `$GOPATH/bin/hostrunner`（通常为 `~/go/bin/hostrunner`）。 ### 选项2：下载发布二进制文件 从 [发布页面](https://github.com/jerryctt/hostrunner-mcp/releases) 下载适用于您平台的预构建二进制文件，解压并将 `hostrunner` 放置在您的 `$PATH` 中的某个位置（例如 `/usr/local/bin/hostrunner`）。 ### 选项3：从源代码构建 ```bash git clone https://github.com/jerryctt/hostrunner-mcp.git cd hostrunner-mcp make build # 生成 ./hostrunner ``` ### 选项4：作为Claude插件安装（市场） **在Claude Desktop中：**前往添加市场 → 输入 `jerryctt/hostrunner-mcp`，然后安装 **hostrunner** 插件。 **在Claude Code中：** ```bash /plugin marketplace add jerryctt/hostrunner-mcp ``` 然后从列表中安装 `hostrunner` 插件。 通过市场安装同时安装MCP服务器（由捆绑的启动器自动启动）和 `codex-loop` 技能。 **前提 — 创建配置文件：** 服务器默认查找其配置文件位于 `~/.config/hostrunner/config.yaml`。从 `examples/config.example.yaml` 创建它，然后启动Claude Desktop/Code： ```bash mkdir -p ~/.config/hostrunner cp examples/config.example.yaml ~/.config/hostrunner/config.yaml # 编辑文件以匹配您的路径 ``` 您可以通过 `-config` 标志或 `HOSTRUNNER_CONFIG` 环境变量覆盖配置文件路径。 > **macOS GUI应用程序和环境变量：** 由于macOS不将shell环境变量传递给GUI应用程序，因此在shell配置文件（`.zshrc`、`.bashrc`等）中设置`HOSTRUNNER_CONFIG`不会在从Claude Desktop启动插件时产生影响。将您的配置文件放在默认路径 `~/.config/hostrunner/config.yaml` — 二进制文件将找到它而无需任何环境变量。 **macOS/Linux：** 捆绑的 `bin/launch.sh` 启动器在首次运行时下载匹配的发布二进制文件，并根据发布 `checksums.txt` 进行验证，然后执行它。不需要手动二进制安装。 **Windows：** 启动器在Windows上不受支持。手动安装二进制文件（上述选项2），并通过 `claude_desktop_config.json` 注册，如“与Claude Desktop注册”部分所述。 > **信任说明：** 启动器从GitHub Releases下载并运行二进制文件，根据发布验证校验和。如果您有疑虑，请查看 `bin/launch.sh` 源代码。 --- ## 配置 服务器按以下顺序解析其配置文件： 1. 如果提供，则使用 `-config` 标志给出的路径。 2. 如果设置，则使用 `HOSTRUNNER_CONFIG` 环境变量。 3. 默认的 `~/.config/hostrunner/config.yaml`。 **推荐：** 将您的配置文件放在 `~/.config/hostrunner/config.yaml`。这在从Claude Desktop使用插件时尤为重要，因为GUI应用程序不会继承shell环境变量 — 在shell配置文件中设置的`HOSTRUNNER_CONFIG` 在从Claude Desktop启动服务器时将不可见。 从提供的示例创建配置文件 — **路径是占位符；请更改它们以匹配您自己的设置**: ```bash mkdir -p ~/.config/hostrunner cp examples/config.example.yaml ~/.config/hostrunner/config.yaml ``` ```yml # 工具允许访问的绝对主机路径。 # 工具拒绝任何解析到这些根目录之外的请求。 allowed_roots: - /Users/yourname/code # run_command可以调用的CLI可执行文件。 # 只有此处列出的名称是允许的；二进制文件必须位于主机上的$PATH中。 # codex_review只需要'codex' — 它不运行git本身。 # 添加更多（例如git、gemini）以便与run_command一起使用。 allowed_commands: - codex # 单个工具调用的最大时钟时间。 timeout: 180s # 单个工具调用返回的最大字节数（输出被截断并附有通知）。 max_output_bytes: 200000 # 每個 'codex review' 调用时可选的额外标志（例如配置覆盖）。 # codex_extra_args: ["-c", "model=o3"] # 是否将codex/command的输出实时传输到服务器的stderr（默认为true）。 # Claude Desktop捕获此输出到 ~/Library/Logs/Claude/mcp-server-hostrunner.log。 # 启用stream_output（默认为true）后，codex的实时输出在该日志中可见。 # 将其设置为false以保持沉默。 stream_output: true ``` --- ## 与Claude Desktop注册 将以下内容添加到您的Claude Desktop配置文件（通常为 `~/Library/Application Support/Claude/claude_desktop_config.json`）： ```json { "mcpServers": { "hostrunner": { "command": "/usr/local/bin/hostrunner", "args": ["-config", "/Users/yourname/.config/hostrunner/config.yaml"] } } } ``` 将 `/usr/local/bin/hostrunner` 替换为二进制文件的实际路径（例如 `~/go/bin/hostrunner`），并相应地更新配置文件路径。存储库中的 `examples/claude_desktop_config.example.json` 文件显示了相同的代码段。 编辑配置文件后重启Claude Desktop。您应该在MCP服务器列表中看到 **hostrunner**。 --- ## 可用工具 ### `codex_review` 对主机git仓库中的更改运行只读 `codex审查`。使用本地 `codex审查` 子命令，它计算差异本身并且不修改文件。仅需要 `codex` CLI — 无需我们的git处理。 | 参数 | 类型 | 必需 | 描述 | |---|---|---|---| | `folder` | 字符串 | 是 | 主机git仓库的绝对路径（例如 `/Users/you/proj`）。永远不是 `/sessions/…` 沙盒路径。 | | `scope` | 字符串 | 否 | `uncommitted`（默认 — 暂存+未暂存+未跟踪），`base`（相对于基准分支），或 `commit`（特定提交） | | `base` | 字符串 | 否 | 基准分支或引用；当 `scope=base` 时需要（例如 `main`） | | `commit` | 字符串 | 否 | 提交SHA；当 `scope=commit` 时需要 | | `prompt` | 字符串 | 否 | 可选的自定义审查说明，作为传递给 `codex审查` 的尾部位置参数（例如 `"关注错误处理"`，`"仅审查身份验证更改"`）。留空以进行常规审查。 | **返回：** 一个包含模式和完整的 `codex审查` 输出的文本块。 ``` 模式： uncommitted --- Codex审查 --- … codex发现 … ``` ### `run_command` 在主机文件夹中运行允许的命令（argv，无shell）。 | 参数 | 类型 | 必需 | 描述 | |---|---|---|---| | `command` | 字符串 | 是 | 可执行名称；必须在 `allowed_commands` 中 | | `args` | 字符串[] | 否 | 参数作为字符串数组 | | `folder` | 字符串 | 是 | `allowed_root`内的绝对**主机**路径 | **返回：** 退出代码、耗时、stdout和stderr。 ``` exit=0 elapsed=1.23s --- stdout --- … --- stderr --- … ``` --- ## 安装Cowork技能 存储库中提供了现成的Cowork技能，位于 `skills/codex-loop/SKILL.md`。此技能教导Cowork如何在每次编辑后自动调用 `codex_review`。 要安装它，请将技能目录复制到您的Cowork技能文件夹中： ```bash cp -r skills/codex-loop ~/.config/claude/skills/ ``` （确切的技能目录可能因您的Cowork安装而异。请检查Cowork的设置以获取配置的路径。） 安装后，您可以通过说以下内容来触发该技能： - “用codex审查我的更改” - “对我的编辑运行codex审查” - “启动编辑-审查循环” --- ## 用法 以下是Claude Cowork中典型的 **编辑 → 审查 → 编辑** 会话： 1. **分享您的项目文件夹** 与Cowork会话。Cowork将其挂载到 `/sessions/<id>/mnt/yourproject`。 2. **编辑文件** 使用Cowork的读写/编辑工具。例如，Cowork编辑 `/sessions/<id>/mnt/yourproject/src/handler.go`。 3. **触发codex审查。** 调用 `codex_review` 工具，指定 **主机** 路径： ```bash codex_review( folder = "/Users/yourname/code/yourproject", scope = "uncommitted" ) ``` 传递主机路径 — 您在Mac上的Finder或终端中看到的路径 — **不是** `/sessions/…` 沙盒路径。 4. **阅读发现结果。** 工具返回模式和codex的审查输出。 5. **迭代。** 修复Cowork发现的问题，然后再次调用 `codex_review`。重复直到审查干净。 --- ## 安全 - **命令允许列表。** 只有在 `allowed_commands` 中明确列出的命令才能被调用。对其他命令的请求将被拒绝。 - **根目录限制。** 每个路径参数都会被解析（包括符号链接）并与 `allowed_roots` 进行检查。对超出这些根目录的路径的请求将被拒绝。 - **无shell。** 命令作为argv数组通过 `os/exec` 运行。没有 `sh -c`，没有glob展开，没有shell注入。 - **本地主机进程，不是Docker。** 服务器作为普通OS进程运行，不在容器内运行。在Docker中运行它将破坏对主机 `codex` 二进制文件、身份验证令牌和文件的访问 — 完全破坏其目的。 - **仅主机路径。** 工具仅接受绝对主机路径（例如 `/Users/…`）。任何以 `/sessions/` 开头的路径都将被拒绝，并附有描述性错误，指出正确的主机路径。 - **只读codex。** `codex_review` 使用 `codex审查` 子命令，该命令为非交互式和只读的 — 它计算差异本身，从不修改文件。不会传递写入或自动应用标志。可选的 `codex_extra_args` 配置字段允许您传递附加标志（例如模型覆盖），而不会影响安全性。 --- ## 开发 ```bash # 构建二进制文件 make build # 运行所有测试 make test # 检查代码 make vet ``` --- ## 许可证 MIT — 请参阅 [LICENSE](LICENSE)。