claude-subagent-mcp

Claude Code Subagent MCP

English | 简体中文

项目简介

Claude Code Subagent MCP 是一个用户级 stdio MCP server，让 Codex Desktop 或 Codex CLI 可以调用 Claude Code CLI 作为实现者。Codex 负责协调任务、展示 Claude 的回复，并审核目标仓库的变更。 server 将经解析、目录验证且确认为 Git 仓库的 workspacePath 用作 Git 和 Claude Code 子进程的 cwd；这只是工作目录设置，不是操作系统级文件系统沙箱。

工作流程

1. 先使用状态工具检查目标工作区。
2. 通过显式的 workspacePath 将实现任务委派给 Claude Code。
3. 审核 server 返回的 Git 状态和未暂存差异摘要，再自行检查 git diff、git diff --cached，并逐个 打开 git status --short 列出的未跟踪文件，确认完整变更后再决定是否接受结果。

环境要求

• Node.js 18 或更高版本
• Git
• Claude Code CLI
• Codex Desktop 或 Codex CLI

安装前请检查本地环境：

node --version
git --version
claude --version

本项目没有运行时 npm 依赖，因此不需要执行 npm install。

安装

Windows PowerShell

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex-tools" | Out-Null
git clone https://github.com/ltxzs/claude-subagent-mcp.git "$env:USERPROFILE\.codex-tools\claude-subagent-mcp"
Set-Location "$env:USERPROFILE\.codex-tools\claude-subagent-mcp"
node --check src/server.mjs
npm test

macOS / Linux

mkdir -p ~/.codex-tools
git clone https://github.com/ltxzs/claude-subagent-mcp.git ~/.codex-tools/claude-subagent-mcp
cd ~/.codex-tools/claude-subagent-mcp
node --check src/server.mjs
npm test

注册到 Codex

将相应配置添加到全局 Codex 配置文件。Windows 的配置文件是 %USERPROFILE%\.codex\config.toml；macOS 和 Linux 的配置文件是 ~/.codex/config.toml。

可参考 examples/config.example.toml 中的完整配置模板。模板中的 REPLACE_WITH_ABSOLUTE_PATH_TO_SRC_SERVER_MJS 必须替换为当前电脑上的实际路径。

args 必须写入 src/server.mjs 的实际绝对路径。不要指望 TOML 中的 %USERPROFILE% 或 ~ 被展开。

Windows

[mcp_servers.claude_subagent]
command = "node"
args = ["C:\\Users\\alice\\.codex-tools\\claude-subagent-mcp\\src\\server.mjs"]
startup_timeout_sec = 20
tool_timeout_sec = 1200
default_tools_approval_mode = "prompt"
enabled_tools = ["get_claude_subagent_status", "delegate_to_claude"]

[mcp_servers.claude_subagent.env]
NODE_ENV = "production"

macOS

[mcp_servers.claude_subagent]
command = "node"
args = ["/Users/alice/.codex-tools/claude-subagent-mcp/src/server.mjs"]
startup_timeout_sec = 20
tool_timeout_sec = 1200
default_tools_approval_mode = "prompt"
enabled_tools = ["get_claude_subagent_status", "delegate_to_claude"]

[mcp_servers.claude_subagent.env]
NODE_ENV = "production"

Linux

[mcp_servers.claude_subagent]
command = "node"
args = ["/home/alice/.codex-tools/claude-subagent-mcp/src/server.mjs"]
startup_timeout_sec = 20
tool_timeout_sec = 1200
default_tools_approval_mode = "prompt"
enabled_tools = ["get_claude_subagent_status", "delegate_to_claude"]

[mcp_servers.claude_subagent.env]
NODE_ENV = "production"

验证 MCP server

保存配置后重启 Codex，再确认下列两个工具可见：

claude_subagent.get_claude_subagent_status
claude_subagent.delegate_to_claude

也可独立于 Codex，在项目目录向 server 进程发送 initialize JSON-RPC 请求，以验证进程本身。 这不能替代重启 Codex 和检查工具注册。响应必须包含 claude-code-subagent。

printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"manual","version":"1.0.0"}}}\n' | node src/server.mjs

'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"manual","version":"1.0.0"}}}' | node src/server.mjs

使用方法

检查目标仓库

先调用 claude_subagent.get_claude_subagent_status：

{
  "workspacePath": "C:\\path\\to\\repo"
}

委派实现任务

再调用 claude_subagent.delegate_to_claude，传入具体实现要求：

{
  "task": "实现具体需求并运行相关测试",
  "workspacePath": "C:\\path\\to\\repo",
  "allowDirty": false,
  "timeoutMs": 1200000
}

审核返回结果

Claude 返回后，server 在结构化结果的 Git 部分包含审核相关字段 statusShort、diffStat 和 diffNameOnly，分别来自 git status --short、git diff --stat 和 git diff --name-only；结果还包含 changedFiles 和 errors（可能为空），但不提供完整 diff。后两个 命令与 git diff 一样，默认只覆盖未暂存变更；暂存变更需另行检查 git diff --cached。Codex 或用户 还必须逐个打开 git status --short 列出的未跟踪文件检查其内容，确认未暂存、暂存和未跟踪变更后再决定 是否接受实现结果。

工具参数

delegate_to_claude 接受以下参数：

参数	要求
task	必填，非空字符串。
workspacePath	必填，非空目录路径，且必须是 Git 仓库。
allowDirty	可选布尔值，默认 false。
resumeSessionId	可选的非空 Claude Code 会话 ID。
timeoutMs	可选整数，单位为毫秒；默认 1200000，且不得小于 1000。

get_claude_subagent_status 要求传入指向 Git 仓库的非空 workspacePath。

为什么必须传 workspacePath

这是全局 MCP server，不属于任何应用仓库。显式指定 workspacePath 后，server 会解析并验证该目录， 确认它是 Git 仓库，再将其用作 Git 和 Claude Code 子进程的 cwd，避免默认在 MCP server 目录或其他 误选目录运行。这不会限制子进程对其他文件系统路径的访问，也不构成操作系统级沙箱，因此只应传入可信仓库。

工作树有未提交改动

默认 allowDirty=false。当 git status --short 非空时，委派会停止，避免 Claude Code 在未经审核的 改动上叠加修改。只有在审核过现有改动并明确接受其作为上下文后，才将 allowDirty 设为 true。

继续 Claude Code 会话

将此前 Claude Code 结果中的非空 session_id 作为 resumeSessionId 传入，即可继续该会话。server 会以 claude --resume <session_id> 调用 Claude Code。

安全说明

• server 从不使用 --dangerously-skip-permissions。
• Claude Code 默认允许的工具仅限文件读写，以及 server 列出的常用 Git、测试和构建命令。
• workspacePath 只用作子进程的 cwd，不是文件系统访问边界。只传入可信仓库，并保留 Claude Code 的 权限审批和人工审核。
• server 自身不执行 commit 或 push；附加系统提示会要求 Claude 不 commit、不 push，但默认允许的 Bash(git:*) 仍可执行 Git 命令。这是行为约束，不是技术 denylist 或强制拦截。
• 接受任何实现前，必须保留审批并检查 git status --short、git diff、git diff --cached，以及每个 未跟踪文件的内容。

常见错误排查

Git 不可用

安装 Git，并在 Codex 使用的同一终端环境中确认 git --version 成功。

Claude Code CLI 不可用

安装 Claude Code CLI，并在 Codex 使用的同一终端环境中确认 claude --version 成功。

workspacePath 不是 Git 仓库

请传入目标项目根目录，并确保在那里执行 git rev-parse --is-inside-work-tree 成功。必要时使用 git init 初始化项目。

工作树有未提交改动

检查 git status --short、适用的 git diff 和 git diff --cached，并逐个打开未跟踪文件。清理或 提交无关改动；只有在这些改动本就应作为上下文时，才明确设置 allowDirty 为 true。

Claude Code 超时

默认超时为 20 分钟。对于确定耗时较长的任务可增大 timeoutMs，或将任务拆分为更小的请求。

Codex 中看不到工具

确认全局配置使用绝对 args 路径，重启 Codex，并确认 server 名称为 claude_subagent。

开发验证

npm run check
npm test

许可证

本项目采用 MIT License 授权。