MCP Subagent Server

MCP Subagent Server

这是一个 Model Context Protocol (MCP) 服务，可将任务分派给子 Agent（例如 Claude Code、Q 或 Aider）。

此 MCP 的用途是让“规划” Agent 将任务委派给“执行” Agent。

功能

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

安装

将以下内容添加到 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"]
    }
  }
}

可用工具

子 Agent 执行工具

• 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：允许子 Agent 向父 Agent 提问

  • 参数：runId（字符串）、question（字符串）
  • 返回：消息 ID 和轮询说明

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

  • 参数：runId（字符串）、messageId（字符串）、answer（字符串）
  • 返回：回复确认信息

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

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

双向通信

MCP Subagent Server 通过消息传递系统支持父 Agent 与子 Agent 之间的双向通信。子 Agent 可在执行期间提问并接收父 Agent 的指导。

通信工具

• ask_parent：允许子 Agent 向父 Agent 提问

  • 参数：
    • runId（字符串）- 子 Agent 当前运行的 ID
    • question（字符串）- 问题/消息内容
  • 返回：消息 ID，以及用于轮询答案的说明

• reply_subagent：允许父 Agent 回复子 Agent 的特定问题

  • 参数：
    • runId（字符串）- 子 Agent 的运行 ID
    • messageId（字符串）- 要回复的消息 ID
    • answer（字符串）- 父 Agent 的回复内容
  • 返回：回复确认信息

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

  • 参数：
    • runId（字符串）- 要检查消息状态的运行 ID
    • messageId（字符串）- 要检查状态的消息 ID
  • 返回：消息详情，以及（如有）答案（同时确认已收到该消息）

工作流示例

以下是在实践中进行双向通信的方式：

1. 子 Agent 提问

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

{
  "tool": "ask_parent",
  "arguments": {
    "runId": "abc-123-def",
    "question": "I found multiple config files. Which one should I modify: config.json or settings.yaml?"
  }
}

响应：

{
  "messageId": "msg-456-789",
  "instructions": "Poll for the answer using the 'check_message_status' tool with your runId and messageId. Since this could take a while for the parent to respond, use 'sleep 60' between calls to avoid spamming."
}

2. 父 Agent 检查子 Agent 状态

父 Agent 检查子 Agent 状态时，会看到：

Status: waiting_parent_reply

Question awaiting reply (Message ID: msg-456-789):
  I found multiple config files. Which one should I modify: config.json or settings.yaml?
  (Asked at: 2025-01-15T10:30:00.000Z)
  To reply, use the 'reply_subagent' tool.

Note: This may take a while for the parent to respond. Use 'sleep 60' between status checks to avoid spamming.

3. 父 Agent 提供答案

父 Agent 使用 reply_subagent 工具：

{
  "tool": "reply_subagent",
  "arguments": {
    "runId": "abc-123-def",
    "messageId": "msg-456-789",
    "answer": "Please modify config.json - it's the main configuration file. The settings.yaml is just for development overrides."
  }
}

4. 子 Agent 获取答案

子 Agent 使用 check_message_status 轮询答案：

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

答案可用时的响应：

{
  "messageId": "msg-456-789",
  "questionContent": "I found multiple config files. Which one should I modify: config.json or settings.yaml?",
  "answerContent": "Please modify config.json - it's the main configuration file. The settings.yaml is just for development overrides.",
  "messageStatus": "acknowledged_by_subagent",
  "hasAnswer": true
}

随后，子 Agent 可以在父 Agent 的指导下继续执行。

最佳实践

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

添加新的子 Agent

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

const SUBAGENTS = {
  q: {
    name: "q",
    command: "q",
    getArgs: () => ["chat", "--trust-all-tools", "--no-interactive"],
    description: "Run a query through the 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: "Run a query through the Claude CLI",
  },
  // Add your new sub-agent here
  newagent: {
    name: "newagent",
    command: "your-command",
    getArgs: () => ["--some-flag", "--other-flags"],
    description: "Description of your new agent",
  },
};

日志

所有子 Agent 运行记录都会写入 logs 目录，每次运行包含以下三个文件：

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