mcp-delegate

一个 MCP 服务器，为 Claude Code（作为编排者）提供一个工具，将任务委托给一个独立的、完整的代理循环，该循环运行在不同的模型上（本地通过 Ollama，或远程通过 OpenRouter），并拥有自己的工具访问权限（文件、bash 等），只返回最终结果——功能上等同于原生子代理，但与模型无关。

完整构建计划请参阅 mcp-subagent-delegation-plan.md，该计划分阶段提交/检查点。

状态

阶段 1、2、3 和 4 已完成。

• delegate_task — 针对配置的 OpenAI 兼容端点（Ollama、LM Studio、vLLM、OpenRouter 等）的单次聊天补全。

• delegate_agentic_task — 为被委托的模型提供自己的工具使用循环（read_file、write_file、run_bash），范围限定在调用者指定的工作目录内，运行直到它停止调用工具、达到 max_iterations 或超过 timeout_seconds。

• list_recent_delegations — 检查过去的委托（任一工具）实际做了什么，无需翻阅日志或重新运行任何内容。

• get_delegation_transcript — 获取一次委托的完整消息/工具调用记录，前提是它以 capture_transcript=True 运行（例如用于模型比较/评估运行）。

与原计划的偏差： 阶段 2 要求将 agent-loop 作为子进程包装。agent-loop 仅支持 Linux/macOS/WSL，而此服务器需要在 Windows 上原生运行，因此我们构建了阶段 5 中描述的替代方案——进程内循环——相同的工具接口，没有子进程/ANSI 剥离的复杂性，并且完全绕过了 agent-loop 的 AGPL/非商业许可。请参阅 delegate/agentic.py。

安全说明： working_dir 由调用者指定，不是固定的沙箱——被委托的模型可以不受监督地访问其指向的任何目录的文件/bash。文件工具（read_file/write_file）被限制在 working_dir 内；run_bash 以该目录作为 cwd 运行，但 shell 命令并未完全沙箱化，可能逃逸（例如 cd ..）。请将其指向一个你愿意让不受监督的模型读取、写入和执行命令的目录。

护栏说明： 原计划的阶段 4 要求确认 agent-loop 自身的护栏（迭代上限、重复检测）是否生效。由于我们不使用 agent-loop，这不直接适用——我们的循环有自己的 max_iterations 和 timeout_seconds 上限（已在测试中验证），但没有重复检测。如果模型卡在两个工具调用之间交替，它将一直运行到达到 max_iterations，而不是被提前捕获。如果实践中出现这种情况，值得添加。

Related MCP server: Thinking Agent MCP

设置

uv sync
cp .env.example .env             # fill in DELEGATE_BASE_URL / DELEGATE_API_KEY / DELEGATE_MODEL
cp models.json.example models.json   # optional: named backends, see below

多个后端

两个工具都接受可选的 backend 参数，该参数从 models.json 中查找 base_url/model/api_key，而不是使用默认的 DELEGATE_* 环境变量——例如，一次调用使用 backend="ollama-local"，另一次调用使用 backend="openrouter-free"，在同一轮中并发运行。如果同时给出 model，则仅覆盖该后端中的模型字符串。

引用环境变量作为密钥，而不是直接写入 models.json：

{
  "openrouter-free": {
    "base_url": "https://openrouter.ai/api/v1",
    "model": "nvidia/nemotron-nano-9b-v2:free",
    "api_key_env": "OPENROUTER_API_KEY"
  }
}

models.json 与 .env 一样被 gitignore。

并发

MCP 工具调用已经在单独的工作线程上运行，因此并发委托无需额外管道即可并行执行。DELEGATE_MAX_CONCURRENCY（默认 4，见 .env.example）限制同时运行的委托数量——跨两个工具、任何后端——以避免大规模扇出压垮本地模型服务器或触发付费 API 的速率限制。

直接运行服务器（主要用于检查它能否无错误启动——然后它会等待 MCP 客户端的 stdio）：

uv run server.py

日志

每次 delegate_task/delegate_agentic_task 调用——无论成功还是失败——都会记录到本地 SQLite 文件 delegations.db（gitignore，首次使用时创建）：工具、后端、模型、任务文本、开始/结束时间、迭代次数、成功/失败、截断的结果/错误预览，以及后端返回的 token 使用情况。可通过 list_recent_delegations 工具查询，或直接使用 sqlite3 delegations.db "select * from delegations order by id desc limit 20"。日志记录是尽力而为的——日志记录失败不会导致本来成功的委托失败。

两个工具还会在返回值的末尾附加一行 [tokens: N prompt / N completion / N total ($cost)]，当后端报告使用情况时，调用代理无需单独调用 list_recent_delegations 即可立即看到。

成本跟踪

pricing.json 将模型字符串映射到 {input_per_million, output_per_million} 美元费率。当调用的解析模型有条目时，成本根据实际 token 使用量计算，记录到 delegations.db（cost_usd 列），并包含在 [tokens: ...] 后缀中。没有条目的模型记录 cost_usd = NULL——未知，而不是假定免费——因此缺失条目不会静默低估支出。本地模型通常不会有条目，原因就在于此；真正免费的模型（例如 OpenRouter :free 模型）会获得显式的 {"input_per_million": 0, "output_per_million": 0} 条目，而不是被省略。

与 .env/models.json 不同，pricing.json 不是秘密或环境特定的，因此直接提交而不是 gitignore。价格会漂移——随附的文件于 2026-08-21 从 OpenRouter 的 /api/v1/models 获取，用于此构建所针对的模型比较 bake-off；重新获取并编辑以根据需要添加/更新模型。

记录捕获（模型比较 / 评估运行）

两个工具都接受 capture_transcript: bool = False。设置后，完整的消息交换——每条模型消息、工具调用和工具结果，而不仅仅是最终答案——都会被记录，返回值会附加 [delegation_id: N] 后缀。使用 get_delegation_transcript(delegation_id) 获取。

这用于通过多个不同的模型/后端运行同一任务，并比较不仅最终答案，还有每个模型如何到达那里（工具选择、格式错误的工具调用、重试）——例如，在挑选生产用模型之前，对候选模型进行 bake-off。默认关闭，因为这是常规委托不需要的额外日志开销。

注册到 Claude Code

项目范围的 .mcp.json 已检入（uv run server.py）。在此目录中重启 Claude Code，或运行 claude mcp list 确认它已拾取 delegate 服务器，然后要求它使用一个简单提示调用 delegate_task 以确认往返。

工具

• delegate_task(prompt, model=None, system_prompt=None, backend=None, capture_transcript=False) -> str — 针对配置后端的单次聊天补全。

• delegate_agentic_task(task, working_dir, model=None, max_iterations=20, timeout_seconds=600, backend=None, capture_transcript=False) -> str — 多步骤委托，使用 read_file/write_file/run_bash 工具，范围限定在 working_dir 内。 仅返回最终答案，不返回完整记录，除非 capture_transcript=True。

• list_recent_delegations(limit=20) -> list[dict] — 最近的委托记录，最新的在前。

• get_delegation_transcript(delegation_id) -> list[dict] — 一次委托的完整记录，该委托以 capture_transcript=True 记录。

delegate_task/delegate_agentic_task 将错误（配置错误、端点不可达、超时、迭代上限）作为 "Error: ..." 字符串返回，而不是抛出异常，以便调用代理可以看到出了什么问题。