MCP 子代理服务器

这是一个模型上下文协议（MCP）服务器，允许将任务分派给子代理（如 Claude Code、Q 或 Aider）。

该MCP的目的在于让一个“规划”代理能够将任务委托给“执行”代理。

功能

• 通过MCP工具配置并运行子代理
• 每个子代理暴露三个工具：
  • run_subagent_<n>：使用提供的输入运行子代理
  • check_subagent_status：允许代理检查子代理的状态
  • get_subagent_logs：检索子代理运行的日志
  • update_subagent_status：更新状态并添加之前运行的摘要
• 双向通信：子代理在执行过程中可以使用ask_parent向父代理提问，父代理可以使用reply_subagent回复，子代理可以使用check_message_status检查回复
• 目前支持'q'子代理（Amazon Q CLI）和'claude'子代理（Claude CLI）
• 实时流式日志用于监控子代理执行

安装

将以下内容添加到您的MCP配置文件（~/.aws/amazonq/mcp.json）中：

{
  "mcpServers": {
    "subagent": {
      "command": "npx",
      "args": ["-y", "mcp-server-subagent"]
    }
  }
}

或者如果您本地安装了它：

{
  "mcpServers": {
    "subagent": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/mcp-server-subagent/build/index.js"]
    }
  }
}

可用工具

子代理执行工具

• run_subagent_q：通过Amazon Q CLI运行查询

  • 参数：input（字符串）- 发送到Amazon Q的查询
  • 返回值：可用于检查状态或获取日志的运行ID

• run_subagent_claude：通过Claude CLI运行查询

  • 参数：input（字符串）- 发送到Claude的查询
  • 返回值：可用于检查状态或获取日志的运行ID

• check_subagent_status：检查先前运行的状态

  • 参数：runId（字符串）- 要检查的运行UUID
  • 返回值：运行的状态和元数据

• get_subagent_logs：获取先前运行的日志

  • 参数：runId（字符串）- 要获取日志的运行UUID
  • 返回值：运行的完整日志

• update_subagent_status：更新状态并添加先前运行的摘要

  • 参数：
    • runId（字符串）- 要更新的运行UUID
    • status（字符串）- 要设置的新状态（其中之一："success", "error", "running", "completed"）
    • summary（字符串，可选）- 包含在状态更新中的摘要或结果消息
  • 返回值：更新后的状态和运行元数据

双向通信工具

• ask_parent：允许子代理向父代理提问

  • 参数：runId（字符串），question（字符串）
  • 返回值：消息ID和轮询指令

• reply_subagent：允许父代理回复子代理的问题

  • 参数：runId（字符串），messageId（字符串），answer（字符串）
  • 返回值：确认回复

• check_message_status：检查消息状态并检索回复

  • 参数：runId（字符串），messageId（字符串）
  • 返回值：消息详情及可用答案

双向通信

MCP子代理服务器通过消息传递系统支持父代理与子代理之间的双向通信。这允许子代理在执行过程中提问，并从父代理获得指导。

通信工具

• ask_parent：允许子代理向父代理提问

  • 参数：
    • runId（字符串）- 子代理当前的运行ID
    • question（字符串）- 提问/消息内容
  • 返回值：消息ID和轮询答案的指令

• reply_subagent：允许父代理回复子代理的具体问题

  • 参数：
    • runId（字符串）- 子代理的运行ID
  • messageId（字符串）- 正在回复的消息ID
  • answer（字符串）- 父代理的回复内容
  • 返回值：确认回复

• check_message_status：检查特定消息的状态并检索回复

  • 参数：
    • runId（字符串）- 要检查消息状态的运行ID
    • messageId（字符串）- 要检查状态的消息ID
  • 返回值：消息详情及可用答案（确认消息）

示例工作流程

这里是如何在实践中进行双向通信：

1. 子代理提问

子代理在执行期间使用ask_parent工具：

{
  "tool": "ask_parent",
  "arguments": {
    "runId": "abc-123-def",
    "question": "我找到了多个配置文件。应该修改哪一个：config.json还是settings.yaml？"
  }
}

响应：

{
  "messageId": "msg-456-789",
  "instructions": "使用'check_message_status'工具和您的runId和messageId轮询答案。由于父代理可能需要一段时间才能回应，请在调用之间使用'sleep 60'以避免垃圾信息。"
}

2. 父代理检查子代理状态

当父代理检查子代理状态时，他们会看到：

状态：等待父代理回复

待回复的问题（消息ID：msg-456-789）：
  我找到了多个配置文件。应该修改哪一个：config.json还是settings.yaml？
  （提问时间：2025-01-15T10:30:00.000Z）
  使用'reply_subagent'工具回复。

注意：父代理可能需要一段时间才能回应。在状态检查之间使用'sleep 60'以避免垃圾信息。

3. 父代理提供答案

父代理使用reply_subagent工具：

{
  "tool": "reply_subagent",
  "arguments": {
    "runId": "abc-123-def",
    "messageId": "msg-456-789",
    "answer": "请修改config.json - 这是主要配置文件。settings.yaml仅用于开发覆盖。"
  }
}

4. 子代理检索答案

子代理使用check_message_status轮询答案：

{
  "tool": "check_message_status",
  "arguments": {
    "runId": "abc-123-def",
    "messageId": "msg-456-789"
  }
}

当答案可用时的响应：

{
  "messageId": "msg-456-789",
  "questionContent": "我找到了多个配置文件。应该修改哪一个：config.json还是settings.yaml？",
  "answerContent": "请修改config.json - 这是主要配置文件。settings.yaml仅用于开发覆盖。",
  "messageStatus": "已由子代理确认",
  "hasAnswer": true
}

子代理可以根据父代理的指导继续执行。

最佳实践

• 轮询频率：在状态检查和消息轮询之间使用sleep 30以避免过载系统
• 问题清晰度：提出具体、可操作的问题，帮助引导任务执行
• 及时响应：父母应定期监控子代理状态，提供及时指导
• 消息确认：当检索到答案时，check_message_status工具会自动确认消息

添加新子代理

要添加新的子代理，请修改src/index.ts中的SUBAGENTS对象：

const SUBAGENTS = {
  q: {
    name: "q",
    command: "q",
    getArgs: () => ["chat", "--trust-all-tools", "--no-interactive"],
    description: "通过Amazon Q CLI运行查询",
  },
  claude: {
    name: "claude",
    command: "claude",
    getArgs: () => [
      "--print",
      "--allowedTools",
      "Bash(git*) Bash(sleep*) Edit Write mcp__subagent__update_subagent_status",
      "--mcp-config",
      JSON.stringify(mcpConfig),
    ],
    description: "通过Claude CLI运行查询",
  },
  // 在此处添加您的新子代理
  newagent: {
    name: "newagent",
    command: "your-command",
    getArgs: () => ["--some-flag", "--other-flags"],
    description: "您新代理的描述",
  },
};

日志

所有子代理运行的日志都记录在logs目录中，每个运行有两个文件：

• <run-id>.log：包含实时输出日志
• <run-id>.prompt.md：包含传递给代理的提示
• <run-id>.meta.json：包含关于运行的元数据（包括通信消息）