Codex Subagent MCP

法典子代理mcp

Codex CLI的基于文件的子代理。一个MCP工具。零绒毛。

本仓库在 MIT 许可下基于原项目 https://github.com/leonardsellem/codex-subagents-mcp 进行了大幅修改后独立维护，当前不计划同步上游代码。

• 可审计：代理人是PR中审查的文件
• CI友好型： validate_agents, list_agents
• 更安全的操作：临时工作目录、安静的标准输出、git工作树隔离

通过微型MCP服务器为Codex CLI提供克劳德风格的子代理。每次调用都会在临时工作目录中创建一个干净的上下文，并通过以下方式注入一个角色 AGENTS.md，并运行 codex exec --profile 保持孤立状态。

快速入门

• 前提条件：Node.js>=18，npm，Codex CLI已安装并位于PATH上。
• 安装deps并构建：

npm install
npm run build

• 启动服务器（手动运行）：

npm start

此服务器公开的工具：

• 主要的，重要的 delegate
• 技术支持： list_agents, validate_agents

代理目录发现（按顺序）： --agents-dir arg， CODEX_SUBAGENTS_DIR env，然后是默认值 ./agents, ./.codex-subagents/agents, dist/../agents.

60秒快速入门（复制粘贴）

# 1) Install + build
npm i && npm run build

# 2) Point Codex at the built server (absolute paths recommended)
# ~/.codex/config.toml
[mcp_servers.subagents]
command = "/usr/bin/env"
args    = ["node", "/ABS/PATH/TO/dist/codex-subagents.mcp.js", "--agents-dir", "/ABS/PATH/TO/agents"]

# Example profiles you can reference from agent frontmatter
[profiles.review]
model = "gpt-5"
approval_policy = "on-request"
sandbox_mode    = "read-only"

[profiles.debugger]
model = "o3"
approval_policy = "on-request"
sandbox_mode    = "workspace-write"

# 3) In Codex, verify tools and agents
tools.call name=list_agents
tools.call name=validate_agents

# 4) Delegate one task to an agent
subagents.delegate(agent="review", task="Summarize and review the last commit")

提示：请参阅 docs/SECURITY.md 信任边界和 docs/OPERATIONS.md 用于E2E和测井。

使用Codex CLI进行布线

构建服务器并将Codex指向 绝对的 编译入口点的路径。显式传递代理目录，以便服务器在握手后才进行扫描。服务器也回退到 agents/ 安装的二进制文件旁边的文件夹（例如。 dist/../agents)如果 --agents-dir 和 CODEX_SUBAGENTS_DIR 未提供：

# ~/.codex/config.toml
[mcp_servers.subagents]
command = "/absolute/path/to/node"
args    = ["/absolute/path/to/dist/codex-subagents.mcp.js", "--agents-dir", "/absolute/path/to/agents"]

[profiles.review]
model = "gpt-5"
approval_policy = "on-request"
sandbox_mode    = "read-only"

[profiles.debugger]
model = "o3"
approval_policy = "on-request"
sandbox_mode    = "workspace-write"

[profiles.security]
model = "gpt-5"
approval_policy = "never"
sandbox_mode    = "workspace-write"

用法（在食品法典中）：

• “查看我上次提交的内容。使用查看子代理。”
• “使用调试器子代理在api/中重现并修复失败的测试。”
• “审核机密和不安全的shell调用；使用安全子代理提出修复方案。”

代理商提示进入您的回购 AGENTS.md

Route all work through the orchestrator:

subagents.delegate(agent="orchestrator", task="")

Example security review routed via orchestrator:

subagents.delegate(agent="orchestrator", task="Audit the repo for secrets and unsafe shell calls")

Prefer tool calls over in-thread analysis to keep the main context clean.

注意：MCP服务器在Codex的沙盒之外运行。保持表面狭窄并经过审核。此服务器公开了一个工具： delegate.

这是给谁的/不是给谁的

• 适用对象：已经使用Codex CLI的团队，他们需要可审计的专业代理和CI门控。
• 不适合：寻求通用代理框架或多工具编排器的人。

术语：代理与配置文件

• agent （你传递给什么 subagents.delegate)：从注册表目录加载的代理的名称。该名称是文件基名。， agents/review.md → agent review.
• profile （Codex CLI）：您在中定义的执行配置文件 ~/.codex/config.toml 在...之下 [profiles.]代理通常通过frontmatter指定要使用的配置文件(profile: )，但代理名称和配置文件名称不必匹配。

只有 orchestrator 是内置的，用于引导路由；其他代理均从磁盘加载（agents/*.md|*.json），或在调用时同时提供 persona 与 profile 作为内联定义。

工具： delegate

• 参数：

- agent：string--注册表中的代理名称（basename） agents/.md|json) - task：string（必填） - cwd?：string（默认为当前工作目录） - mirror_repo?：boolean（默认为false）。如果是真的 cwd 提供，将仓库镜像到临时工作目录中，以实现最大程度的隔离。 - profile? 和 persona?：可选的特殊定义 agent 在注册表中找不到。两者都提供。

• 行为：

1. 如果 mirror_repo 为true：创建一个临时工作目录，镜像仓库，写入 AGENTS.md 该角色加上目录样式代理的资源提示。 1. 如果 mirror_repo 为false：无临时目录；角色（和资源提示，如果有的话）是任务文本的前缀。 - 更安全的替代方案（建议用于大型仓库）： git worktree add （记录于 docs/INTEGRATION.md). 3. 生成物 codex exec --profile "" 随着 cwd 如果镜像，则设置为temp目录，否则您提供 cwd. 1. 返回JSON： { stdout } （仅记录退出代码/working_dir等其他详细信息）。

海关代理

添加代理而不更改代码：

1. 基于文件的注册表（推荐）

• 创建一个代理目录，并通过以下任一方式将服务器指向该目录：

- 配置参数：添加 "--agents-dir", "/path/to/agents" 在 ~/.codex/config.toml 在MCP服务器参数下 - ENV 是 ： CODEX_SUBAGENTS_DIR=/path/to/agents - 默认值（自动检测）： ./agents 或 ./.codex-subagents/agents

• 使用basename作为代理名称将代理定义为文件：

示例 agents/perf.md:

---
profile: debugger
approval_policy: on-request   # one of: never | on-request | on-failure | untrusted
sandbox_mode: workspace-write # one of: read-only | workspace-write | danger-full-access
---
You are a pragmatic performance analyst. Identify hotspots, measure, propose minimal fixes with benchmarks.

或JSON agents/migrations.json:

{
  "profile": "debugger",
  "approval_policy": "on-request",
  "sandbox_mode": "workspace-write",
  "persona": "You plan and validate safe DB migrations with rollbacks.",
  "personaFile": null
}

• 目录样式代理：将文件放置在 agents// 具有名为的强制角色文件 .md （正面+身体）或 .json （个人资料+人物/个人档案）。其他文件放在旁边；服务器不会复制它们，而是将它们的绝对路径显示给代理（in AGENTS.md 当被镜像时；未镜像时作为任务的前缀）。

1. 通过工具参数进行临时代理

呼叫 delegate 使用新名称并提供两者 profile 和 persona:

subagents.delegate(
  agent="perf",
  task="Analyze render jank",
  profile="debugger",
  approval_policy="on-request",
  sandbox_mode="workspace-write",
  persona="You are a perf specialist..."
)

列出可用代理：

tools.call name=list_agents

验证： approval_policy 和 sandbox_mode 根据上述允许值进行验证。它们是咨询元数据，应与您运行的Codex配置文件相匹配。通过中的配置文件强制执行实际行为 ~/.codex/config.toml.

验证代理文件：

tools.call name=validate_agents
# or
tools.call name=validate_agents arguments={"dir":"/abs/path/to/agents"}

返回每个文件的错误/警告和摘要。标记无效值；缺失 profile Markdown中有一个警告（加载器默认为 default).

构建、缝合、测试

npm install
npm run build
npm run lint
npm test

注意：不要编辑 dist/ 手动；它是构建输出。

E2E演示

使用真正的Codex CLI进行自动端到端检查：

npm run e2e

它将：

1. 构建项目。
2. 写一个临时 ~/.codex/config.toml 指向已构建的服务器。
3. 跑 /mcp 以验证服务器是否已连接。
4. 选择磁盘上的第一个代理并调用 subagents.delegate.

脚本要求 OPENAI_API_KEY 以及一个工作的Codex CLI二进制文件。

安全与操作

MCP超时故障排除

警告：Stout只能是换行符分隔的JSON。stdout上的任何日志都会中断MCP握手。使用 DEBUG_MCP=1 向stderr发出诊断。

• “找不到codex”：安装codex CLI并确保它在PATH上。重新运行 npm run e2e.
• 启动超时：确认绝对配置点 dist/codex-subagents.mcp.js 路径和通道 --agents-dir.
• stdout上的日志会中断握手。集 DEBUG_MCP=1 仅将计时记录到stderr。
• 服务器发出换行符分隔的JSON；期望HTTP标头的旧配置将停止。
• 大回购：首选 git worktree 超过 mirror_repo=true （参见 docs/INTEGRATION.md).
• 启动缓慢：初始化后代理文件加载缓慢。

代理商食谱（初学者角色）

这些是基于文件的代理 agents/每个链接都包含一个单行目标和建议的元数据（frontmatter）。

• agents/review.md：代码审查和重构检查表。前台： profile: review （建议： approval_policy: on-request, sandbox_mode: read-only).
• agents/debugger.md：重现故障并提出最小限度的修复。前台： profile: debugger （建议： approval_policy: on-request, sandbox_mode: workspace-write).
• agents/security.md：威胁建模和具体缓解措施。前台： profile: security （建议： approval_policy: never, sandbox_mode: workspace-write).
• agents/perf.md：确定热点；测量和优化。前台： profile: default （建议： approval_policy: on-request, sandbox_mode: workspace-write).
• agents/docs.md：改进和重组文档。前台： profile: default （建议： approval_policy: on-request, sandbox_mode: read-only).
• agents/a11y.md：无障碍审查和修复。前台： profile: default （建议： approval_policy: on-request, sandbox_mode: read-only).

邀请添加新代理的PR——请参阅“贡献代理”。

贡献一个代理（快速通道）

1. 分叉并创建 agents/.md 与frontmatter：

   profile: debugger
   approval_policy: on-request
   sandbox_mode: workspace-write

然后用自由文本描述角色。

1. 跑 tools.call name=validate_agents.

1. 使用“代理请求/贡献”模板打开PR。

我们在GitHub讨论中跟踪所请求的角色（如果还不存在，请在“显示和告诉”下打开一个新主题）。

比较

• 与构建自己的MCP服务器相比：此仓库保留了一个工具和基于文件的代理，以最大限度地减少攻击面。
• 与复杂的编排器相比：这有意避免了图形/路由器——Codex CLI配置文件+文件角色使其保持简单。

如果这个项目有帮助，那么一颗星星会帮助其他人发现它。

文档

• docs/INTEGRATION.md：更深层次的布线、剖面图、AGENTS.md指南。
• docs/SECURITY.md：隔离、信任边界、沙盒指导。
• docs/OPERATIONS.md：日志、环境变量、升级。

许可证

麻省理工学院