使用说明

子代理-MCP（Model Context Protocol）——用于特定任务子代理的模型上下文协议服务器

一个最小化的TypeScript MCP服务器，它提供了一个专注的工具界面，通过显式的CLI封装器（如Codex或Cursor）来运行任务特定的子代理（如审查、调试器、安全等）。代理角色从一个简单的文件中加载 agents/ 目录（Markdown 或 JSON 格式），这样您就可以添加或调整子代理，而无需更改代码。

特点/功能

用TypeScript实现的最小化、可审计的MCP服务器（标准输出仅包含JSON）
单一职责工具表面： delegate， delegate_batch， list_agents， validate_agents
零代码代理创建：轻松上手 agents/*.md|json 注册角色和元数据
基于配置文件的执行：使用代理选择的配置文件调用Codex或Cursor
可选的工作区隔离：使用镜像仓库或 git worktree 对于较大的代码库
在令牌门控和每请求状态管理下的协调执行 orchestration/<request_id>/
与 Node.js 18 及更高版本兼容

快速入门

通过 npx 运行（无需本地构建）

npx -y @loft-902-co/subagents-mcp --version

或者：本地构建：

npm install
npm run build

将你的客户端（Codex 或 Cursor）指向 MCP 服务器（需要显式封装）

Codex CLI 电路连接

把这个加到你的（清单/计划/内容等）里 ~/.codex/config.toml 并根据需要进行调整：

[mcp_servers.subagents]
command = "npx"
args    = ["-y", "@loft-902-co/subagents-mcp", "--agents-dir", "/ABS/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"

通过启动Codex并运行来验证连接 /mcp。

Cursor CLI 线路连接（或“Cursor CLI 电路布线”）

使用 npx 注册 Cursor 包装器（需要显式选择；可选地，指定您的代理目录）：

[mcp_servers.subagents]
command = "npx"
args    = ["-y", "@loft-902-co/subagents-mcp", "--client", "cursor", "--agents-dir", "/ABS/PATH/TO/agents"]

选择是明确的；没有默认客户端。请使用 Codex 或 Cursor 包装器。

使用

内置工具

这些MCP工具是暴露的：

delegate(args)运行单个子代理
delegate_batch({ items, token? })并行运行多个子代理
list_agents()列出内置和磁盘加载的代理
validate_agents({ dir? })验证代理注册文件
start_orchestration({ goal?, cwd?, mirror_repo? })启动编排器并运行 *help 或者 *plan {goal}

最小化示例（来自能够调用MCP工具的客户端）：

{ "name": "list_agents" }

{
  "name": "delegate",
  "arguments": { "agent": "review", "task": "Review the last commit for readability" }
}

为了保持工作流程中的主要上下文清晰，当子代理适合完成任务时，建议直接调用这些工具，而不是进行冗长的线程内分析。如果您的项目维护着一个 AGENTS.md，在那里添加建议的呼叫模式。

自定义代理注册表

服务器从磁盘加载代理定义，并将其与一些内置定义合并。您可以通过命令行界面（CLI）参数或环境变量指定一个注册表目录，或者依赖自动发现功能。

首选： --agents-dir /abs/path/to/agents 或者设置 SUBAGENTS_AGENTS_DIR=/abs/path/to/agents
自动发现候选对象（按顺序）： ./agents， ./.<client-id>-subagents/agents （例如。， ./.codex-subagents/agents)，以及该仓库的打包文件 dist/../agents

Markdown 工具（或“Markdown 代理”）agents/<name>.md):

---
profile: debugger
approval_policy: on-request   # never | on-request | on-failure | untrusted
sandbox_mode: workspace-write # read-only | workspace-write | danger-full-access
---
You are a pragmatic performance analyst. Identify hotspots, propose minimal, measurable fixes,
and outline validation steps with lightweight metrics.

JSON代理（agents/<name>.json)：

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

验证并列出您的注册表：

{ "name": "validate_agents" }

{ "name": "list_agents" }

快速开始编排（展示 *help 默认情况下或计划一个目标：

{ "name": "start_orchestration", "arguments": { "goal": "Plan sprint for onboarding flow" } }

提示：

保持角色简介、具体且侧重行动（任务检查清单胜过哲学思考）
对齐 approval_policy 和 sandbox_mode 带着您的客户资料 ~/.codex/config.toml

编排模型

所有工作都通过一个（系统/平台/渠道等）进行处理 orchestrator 代理。类似调用：

{
  "name": "delegate",
  "arguments": { "agent": "security", "task": "Scan for secrets and unsafe shell exec" }
}

它们被透明地封装后写入到编排器中。服务器注入 available_agents 放入信封中，以便协调者知道可以委托什么任务。代币门控确保只有协调者才能进一步委托。每个请求都会创建一个状态文件夹：

orchestration/<request_id>/
  ├─ todo.json           # request lifecycle, steps, status
  └─ steps/<step-id>/
       ├─ stdout.txt
       └─ stderr.txt

并行性：使用 delegate_batch 对于独立项目；结果保持输入顺序。

隔离：设置 mirror_repo=true 将您的工作区复制到临时工作目录中，或者更倾向于使用 git worktree 对于大型回购（或大型库）而言。

环境变量

客户端选择和参数（需要显式配置）：

SUBAGENTS_CLIENT — 客户标识符（无默认值）
SUBAGENTS_CLIENT_ID — 路径和默认值中使用的标识符
SUBAGENTS_SERVER_NAME — 握手过程中的MCP服务器名称
SUBAGENTS_WORKDIR_PREFIX — 临时工作目录的前缀
SUBAGENTS_CLIENT_ARGS_BEFORE_TASK — 用 JSON 数组或空格分隔的模板覆盖 CLI 参数；模板支持 {profile} 并且 {task}
SUBAGENTS_CLIENT_ARGS_AFTER_TASK — JSON数组或空格分隔的模板，用于覆盖CLI参数；模板支持 {profile} 并且 {task}
SUBAGENTS_CLIENT_CONFIG — 用于一次性覆盖多个字段的JSON对象

注册表与行为：

SUBAGENTS_AGENTS_DIR — 您的绝对路径 agents 注册表
SUBAGENTS_MIRROR_ALL=1 — 在镜像时包含通常会被跳过的路径（例如。， .git， .env， node_modules)
DEBUG_MCP=1 — 在标准错误输出(stderr)中记录带时间戳的握手和工具调用调试日志（标准输出(stdout)保持仅输出JSON）

您的客户端（例如，Codex CLI）可能还需要额外的环境变量，如 OPENAI_API_KEY 运行实际的模型调用。

将计划/任务展示为 @tasks

某些工作流引用了一个 @tasks/ 规划工件的别名（例如。， planning/tasks/）。你可以通过两种方式将此目录暴露给客户端进程：

选项A — 在委托时镜像仓库，以便任务在其原生路径下可读：
- 通过（考试/测试） mirror_repo: true 到；对于；向；朝 delegate(...) 当你希望代理人阅读时 planning/tasks/ 直接在临时工作目录中。
选项B — 通过客户端参数挂载别名（如果您的客户端支持上下文/资源标志，建议使用此方法）：
- 使用环境变量透传在任务前添加特定于客户端的标志。以下是一个假设示例： --context 标志：

POSIX shell（或：POSIX 交互式解释器）：

export SUBAGENTS_CLIENT_ARGS_BEFORE_TASK='exec --profile {profile} --context @tasks=/ABS/PATH/TO/planning/tasks'

Windows PowerShell：

$env:SUBAGENTS_CLIENT_ARGS_BEFORE_TASK = 'exec --profile {profile} --context @tasks=C:\ABS\PATH\planning\tasks'

注释：

确切的标志名称取决于您的客户端（例如。， --context， --resource（或类似表达）。服务器只是将这些参数转发出去。
如果您的客户端缺少这样的标志，请使用选项A（mirror_repo=true）和参考 planning/tasks/ 直接路径。
打包：在构建时， agents/ 和 planning/ 被复制到 dist/ （见 scripts/copy-static.js）并且两者都已发布到npm。消费者可以直接引用这些打包后的路径。

NPM 安装 —— 打包的路径

本地项目安装（推荐）：

# map @tasks to the package-bundled tasks directory
export SUBAGENTS_CLIENT_ARGS_BEFORE_TASK='exec --profile {profile} --context @tasks=./node_modules/@loft-902-co/subagents-mcp/dist/planning/tasks'

全局安装（POSIX）：

export SUBAGENTS_CLIENT_ARGS_BEFORE_TASK="exec --profile {profile} --context @tasks=$(npm root -g)/@loft-902-co/subagents-mcp/dist/planning/tasks"

Windows PowerShell（本地安装）：

$env:SUBAGENTS_CLIENT_ARGS_BEFORE_TASK = 'exec --profile {profile} --context @tasks=.\nnode_modules
a loft-902-co
subagents-mcp
dist
planning
tasks' -replace "\n","\\"

代理注册表（来自 npm 包）：

你也可以指出 --agents-dir 或者 CODEX_SUBAGENTS_DIR) to（这个短语本身在中文里没有直接对应的翻译，因为它是一个介词短语的一部分，通常需要结合上下文来理解。如果单独翻译，可以大致理解为“到”或“向”，但具体含义需根据上下文确定。例如，如果句子是“go to the store”，那么“to”翻译为“到”。） ./node_modules/@loft-902-co/subagents-mcp/dist/agents 如果您想使用打包的示例代理。

运营/操作

常用命令：

构建： npm run build
启动（Codex服务器）： npm run start:codex → node dist/codex/codex-subagents.mcp.js
启动（光标服务器）： npm run start:cursor → node dist/cursor/cursor-subagents.mcp.js
开发（TypeScript）： npm run dev:codex 或者 npm run dev:cursor
Lint（代码检查工具）： npm run lint
测试： npm test
端到端： npm run e2e （需要 codex （在PATH上并配置了配置文件）

故障排除要点：

MCP 握手停滞：确保 stdout 仅输出以换行符分隔的 JSON；使用 DEBUG_MCP=1
Unknown tool确认您正在执行从（某处）构建的JS dist/
未找到代理：set --agents-dir 或者 SUBAGENTS_AGENTS_DIR，或创建 ./agents
大型仓库的超时设置：建议 git worktree 过度镜像（或完全镜像，根据上下文可能有所不同）

看见 docs/OPERATIONS.md 详情如下。

安全

此服务器运行在客户端沙盒之外，并继承您的用户权限。请保持工具界面简洁，并定期检查代理注册表。

信任边界与最小权限原则指南：

狭窄的工具表面： delegate， delegate_batch， list_agents， validate_agents
对齐 approval_policy/sandbox_mode 根据客户资料设置写入访问权限和审批流程
更喜欢 read-only 对于审阅者；对高风险工作使用审批流程
避免镜像秘密；更倾向于 git worktree 对于敏感/大型仓库
保持标准输出简洁（仅输出JSON）；将调试信息输出到标准错误流 DEBUG_MCP=1

请看 docs/SECURITY.md 以获取更全面的风险/缓解措施清单及审计要点。

发展

语言：TypeScript（编译为CommonJS）
节点：≥ 18
依赖项：最少（运行时： zod)
MCP协议： 2024-11-05

脚本：

{
  "build": "tsc -p tsconfig.json",
  "dev": "tsx src/codex/codex-subagents.mcp.ts",
  "dev:cursor": "tsx src/cursor/cursor-subagents.mcp.ts",
  "start": "node dist/codex/codex-subagents.mcp.js",
  "start:cursor": "node dist/cursor/cursor-subagents.mcp.js",
  "lint": "eslint . --ext .ts",
  "test": "vitest run"
}

项目布局（高层次）：

src/
  codex/
    codex-subagents.mcp.ts   # main MCP server (Codex)
  cursor/                    # Cursor variant wrapper
  orchestration.ts           # token gating + request lifecycle
docs/                        # integration, operations, security, orchestration
agents/                      # example agents registry (load from disk)
dist/                        # compiled outputs for MCP wiring

常见问题解答（FAQ）

我如何将服务器指向我的代理目录？

通过（考试/测试） --agents-dir /abs/path/to/agents 或者设置 SUBAGENTS_AGENTS_DIR=/abs/path/to/agents如果未指定，服务器将自动检测 ./agents， ./.<client-id>-subagents/agents （例如。， ./.codex-subagents/agents), 然后是一个捆绑的回退方案。

我可以并行执行多个步骤吗？

是的。使用 delegate_batch({ items })协调器并行处理独立项目，并返回有序结果。

我在哪里可以查看日志和生命周期状态？

对于每个请求，请参阅 orchestration/<request_id>/todo.json 并且每一步（或按步骤） stdout.txt/stderr.txt 下面；在……之下 steps/<step-id>/.

如果我不想复制整个仓库怎么办？

离开 mirror_repo as false (默认) 和更倾向于 git worktree 当你需要隔离而又不想进行大量复制时。

更新日志

见 CHANGELOG.md 关注显著变更。版本发布遵循语义化版本控制（SemVer）。

子代理模型协议服务器

使用说明

子代理-MCP（Model Context Protocol）——用于特定任务子代理的模型上下文协议服务器

目录

特点/功能

快速入门

Codex CLI 电路连接

Cursor CLI 线路连接（或“Cursor CLI 电路布线”）

选择是明确的；没有默认客户端。请使用 Codex 或 Cursor 包装器。

使用

内置工具

自定义代理注册表

编排模型

环境变量

将计划/任务展示为 @tasks

运营/操作

安全

发展

常见问题解答（FAQ）

更新日志

许可证

相关文档

规则文件（编排器）

使用说明

子代理-MCP（Model Context Protocol）——用于特定任务子代理的模型上下文协议服务器

目录

特点/功能

快速入门

Codex CLI 电路连接

Cursor CLI 线路连接（或“Cursor CLI 电路布线”）

选择是明确的；没有默认客户端。请使用 Codex 或 Cursor 包装器。

使用

内置工具

自定义代理注册表

编排模型

环境变量

将计划/任务展示为 @tasks

运营/操作

安全

发展

常见问题解答（FAQ）

更新日志

许可证

相关文档

规则文件（编排器）

相关 MCP

自动化控制服务器

AI桌面工作站

AI编程助手管理控制台

浏览器自动化服务

GitHub项目管理MCP服务

项目任务批量管理服务