mcp-server-subagent

# MCP Subagent Server This is a Model Context Protocol (MCP) server that allows dispatching of tasks to sub-agent (like Claude Code, Q or Aider) The purpose of this MCP is to allow a "planning" agent to delegate tasks to "executor" agents ![screenshot](./screenshot.png) ## Features - Configure and run sub-agents through MCP tools - Each sub-agent exposes three tools: - `run_subagent_<n>`: Runs the sub-agent with provided input - `check_subagent_status`: Allows the agent to check on the status of a sub-agent - `get_subagent_logs`: Retrieves the logs of a sub-agent run - `update_subagent_status`: Updates the status and adds a summary of a previous run - **Bi-directional communication**: Sub-agents can ask questions to parent agents during execution using `ask_parent`, parents can reply using `reply_subagent`, and sub-agents can check for replies using `check_message_status` - Currently supports the 'q' sub-agent (Amazon Q CLI) and 'claude' sub-agent (Claude CLI) - Real-time streaming logs for monitoring sub-agent execution ## Installation Add this to your MCP configuration file (`~/.aws/amazonq/mcp.json`): ```json { "mcpServers": { "subagent": { "command": "npx", "args": ["-y", "mcp-server-subagent"] } } } ``` Or if you installed it locally: ```json { "mcpServers": { "subagent": { "command": "node", "args": ["/ABSOLUTE/PATH/TO/mcp-server-subagent/build/index.js"] } } } ``` ### Available Tools #### Sub-agent Execution Tools - `run_subagent_q`: Run a query through the Amazon Q CLI - Parameters: `input` (string) - The query to send to Amazon Q - Returns: A run ID that can be used to check the status or get logs - `run_subagent_claude`: Run a query through the Claude CLI - Parameters: `input` (string) - The query to send to Claude - Returns: A run ID that can be used to check the status or get logs - `check_subagent_status`: Check the status of a previous run - Parameters: `runId` (string) - The UUID of the run to check - Returns: The status and metadata of the run - `get_subagent_logs`: Get the logs of a previous run - Parameters: `runId` (string) - The UUID of the run to get logs for - Returns: The complete logs of the run - `update_subagent_status`: Update the status and add a summary of a previous run - Parameters: - `runId` (string) - The UUID of the run to update - `status` (string) - The new status to set (one of: "success", "error", "running", "completed") - `summary` (string, optional) - A summary or result message to include with the status update - Returns: The updated status and metadata of the run #### Bi-directional Communication Tools - `ask_parent`: Enables sub-agents to ask questions to the parent agent - Parameters: `runId` (string), `question` (string) - Returns: Message ID and polling instructions - `reply_subagent`: Enables parents to reply to sub-agent questions - Parameters: `runId` (string), `messageId` (string), `answer` (string) - Returns: Confirmation of the reply - `check_message_status`: Check message status and retrieve replies - Parameters: `runId` (string), `messageId` (string) - Returns: Message details and answer if available ## Bi-directional Communication The MCP Subagent Server supports bi-directional communication between parent agents and sub-agents through a message passing system. This allows sub-agents to ask questions during execution and receive guidance from the parent agent. ### Communication Tools - `ask_parent`: Enables sub-agents to ask questions to the parent agent - Parameters: - `runId` (string) - The sub-agent's current run ID - `question` (string) - The question/message content - Returns: A message ID and instructions for polling the answer - `reply_subagent`: Enables parents to reply to specific questions from sub-agents - Parameters: - `runId` (string) - The sub-agent's run ID - `messageId` (string) - The ID of the message being replied to - `answer` (string) - The parent's reply content - Returns: Confirmation of the reply - `check_message_status`: Check the status of a specific message and retrieve replies - Parameters: - `runId` (string) - Run ID to check message status for - `messageId` (string) - Message ID to check status for - Returns: Message details and answer if available (acknowledges the message) ### Example Workflow Here's how bi-directional communication works in practice: #### 1. Sub-agent asks a question The sub-agent uses the `ask_parent` tool during execution: ```json { "tool": "ask_parent", "arguments": { "runId": "abc-123-def", "question": "I found multiple config files. Which one should I modify: config.json or settings.yaml?" } } ``` Response: ```json { "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. Parent checks sub-agent status When the parent checks the sub-agent status, they'll see: ``` 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. Parent provides an answer The parent uses the `reply_subagent` tool: ```json { "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. Sub-agent retrieves the answer The sub-agent polls for the answer using `check_message_status`: ```json { "tool": "check_message_status", "arguments": { "runId": "abc-123-def", "messageId": "msg-456-789" } } ``` Response when answer is available: ```json { "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 } ``` The sub-agent can then continue execution with the parent's guidance. ### Best Practices - **Polling Frequency**: Use `sleep 30` between status checks and message polling to avoid overwhelming the system - **Question Clarity**: Ask specific, actionable questions that help guide the task execution - **Timely Responses**: Parents should monitor sub-agent status regularly to provide timely guidance - **Message Acknowledgment**: The `check_message_status` tool automatically acknowledges messages when answers are retrieved ## Adding New Sub-agents To add a new sub-agent, modify the `SUBAGENTS` object in `src/index.ts`: ```typescript 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 All sub-agent runs are logged to the `logs` directory with two files per run: - `<run-id>.log`: Contains the real-time output logs - `<run-id>.prompt.md`: Contains the prompt passed to the agent - `<run-id>.meta.json`: Contains metadata about the run (including communication messages)