MCP Subagent Server

MCP サブエージェントサーバー

これは、サブエージェント（Claude Code、Q、Aider など）にタスクを委任できる Model Context Protocol（MCP）サーバーです。

この MCP は、「計画」エージェントがタスクを「実行」エージェントに委任できるようにすることを目的としています。

機能

• MCP ツールを通じてサブエージェントを設定して実行できます
• 各サブエージェントは次の 3 つのツールを公開します：
  • 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 Subagent Server は、メッセージパッシングシステムを通じて親エージェントとサブエージェント間の双方向通信をサポートします。これにより、サブエージェントは実行中に質問し、親エージェントからガイダンスを受け取ることができます。

コミュニケーションツール

• 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": "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. 親エージェントがサブエージェントのステータスを確認する

親エージェントがサブエージェントのステータスを確認すると、次のように表示されます。

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. 親エージェントが回答する

親エージェントは 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. サブエージェントが回答を取得する

サブエージェントは 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
}

その後、サブエージェントは親エージェントの指示に従って実行を続行できます。

ベストプラクティス

• ポーリング頻度：システムに過剰な負荷をかけないよう、ステータス確認とメッセージのポーリングの間に sleep 30 を使用します
• 質問の明確さ：タスクの実行を導くのに役立つ、具体的で実行可能な質問をします
• 迅速な返信：親エージェントは、適切なタイミングで指示を提供できるよう、サブエージェントのステータスを定期的に確認します
• メッセージの確認：check_message_status ツールは、回答の取得時にメッセージを自動的に確認済みにします

サブエージェントの追加

新しいサブエージェントを追加するには、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",
  },
};

ログ

すべてのサブエージェントの実行は logs ディレクトリに記録され、1 回の実行につき次の 2 つのファイルが作成されます。

• <run-id>.log：リアルタイムの出力ログが含まれます
• <run-id>.prompt.md：エージェントに渡されたプロンプトが含まれます
• <run-id>.meta.json：実行に関するメタデータ（コミュニケーションメッセージを含む）が含まれます