# MCP Goose Subagents Server

An MCP (Model Context Protocol) server that enables AI clients to delegate tasks to autonomous developer teams using Goose CLI subagents.

## Features

- **Delegate to Subagents**: Create specialized AI agents for different development roles
- **Parallel & Sequential Execution**: Run agents simultaneously or in sequence
- **Recipe System**: Create reusable agent configurations
- **Session Management**: Track and retrieve results from active subagent sessions
- **Pure Goose CLI Integration**: Uses only Goose CLI for subagent delegation

## Prerequisites

1. **Goose CLI** installed and configured
2. **Node.js** (v18 through v24; the tested package compatibility bound is `>=18 <25`)
3. **Alpha features enabled** for Goose subagents

## Installation

```bash
npm install
```

## Usage

### 1. Add to MCP Configuration

Add this server to your MCP client configuration (e.g., `mcp_config.json`):

```json
{
  "mcpServers": {
    "goose-subagents": {
      "command": "node",
      "args": ["path/to/mcp-goose-subagents/src/index.js"],
      "env": {
        "ALPHA_FEATURES": "true"
      }
    }
  }
}
```

### 2. Enable Goose Alpha Features

```bash
export ALPHA_FEATURES=true
```

## Available Tools

### `delegate_to_subagents`

Delegate development tasks to specialized Goose subagents.

**Parameters:**
- `task` (string): The development task to delegate
- `agents` (array): Array of subagent configurations
  - `role` (string): Agent role (e.g., "backend_developer", "frontend_developer")
  - `instructions` (string): Specific instructions for the agent
  - `recipe` (string, optional): Recipe name to use
- `execution_mode` (string): "parallel" or "sequential"
- `working_directory` (string, optional): Working directory for agents

`working_directory` must already exist beneath `GOOSE_MCP_ROOT` (the server's startup directory by default). Relative or absolute paths that resolve inside the root are accepted; traversal and symlinks that resolve outside it are rejected.

**Example:**
```json
{
  "task": "Build a REST API with authentication",
  "agents": [
    {
      "role": "backend_developer",
      "instructions": "Create Express.js API with JWT authentication"
    },
    {
      "role": "database_engineer", 
      "instructions": "Design and implement user database schema"
    },
    {
      "role": "security_auditor",
      "instructions": "Review authentication implementation for security issues"
    }
  ],
  "execution_mode": "parallel"
}
```

### `create_goose_recipe`

Create reusable Goose recipes for specialized subagents.

**Parameters:**
- `recipe_name` (string): Name of the recipe
- `role` (string): Agent role
- `instructions` (string): Detailed instructions
- `extensions` (array, optional): Goose extensions to enable
- `parameters` (object, optional): Recipe parameters

### `list_active_subagents`

List currently active subagent sessions and their status.

### `get_subagent_results`

Retrieve results from completed subagent sessions.

**Parameters:**
- `session_id` (string): Session ID to get results for

## Example Workflows

### Autonomous Full-Stack Development

```javascript
// Delegate a complete web app development task
{
  "task": "Create a todo app with React frontend and Node.js backend",
  "agents": [
    {
      "role": "project_architect",
      "instructions": "Design overall architecture and create project structure"
    },
    {
      "role": "backend_developer", 
      "instructions": "Build REST API with CRUD operations for todos"
    },
    {
      "role": "frontend_developer",
      "instructions": "Create React components and integrate with API"
    },
    {
      "role": "qa_engineer",
      "instructions": "Write tests and ensure quality standards"
    }
  ],
  "execution_mode": "sequential"
}
```

### Parallel Code Review

```javascript
{
  "task": "Review authentication module for security and performance",
  "agents": [
    {
      "role": "security_auditor",
      "instructions": "Analyze for security vulnerabilities and best practices"
    },
    {
      "role": "performance_reviewer",
      "instructions": "Identify performance bottlenecks and optimization opportunities"  
    },
    {
      "role": "code_quality_reviewer",
      "instructions": "Check code style, maintainability, and documentation"
    }
  ],
  "execution_mode": "parallel"
}
```

## Agent Roles Examples

- `backend_developer` - API development, server-side logic
- `frontend_developer` - UI/UX implementation, client-side code
- `database_engineer` - Schema design, query optimization
- `devops_engineer` - Deployment, CI/CD, infrastructure
- `qa_engineer` - Testing, quality assurance
- `security_auditor` - Security review, vulnerability assessment
- `code_reviewer` - Code quality, best practices
- `documentation_writer` - Technical documentation, API docs
- `project_architect` - System design, architecture planning

## Environment Variables

- `ALPHA_FEATURES=true` - Required for Goose subagents
- `GOOSE_RECIPE_PATH` - Path to custom recipe directory
- `GOOSE_MCP_ROOT` - Trusted workspace root. Defaults to the server startup directory.
- `GOOSE_MCP_TIMEOUT_MS` - Goose process timeout in milliseconds (default 15 minutes, capped at 1 hour).

## Security boundary

Tool arguments are model-controlled. This server constrains Goose's working directory and generated recipe paths to `GOOSE_MCP_ROOT`, invokes Goose without a shell, limits captured output, times out child processes, and terminates their process group during timeout or shutdown. Dependency versions are pinned in `package.json` and `package-lock.json`.

These are application-level guardrails, **not a sandbox**. Goose inherits the server's environment and operating-system permissions and may access resources outside the workspace through its own tools or subprocesses. Run the server under a dedicated, least-privileged OS account or container, expose only necessary credentials, and set `GOOSE_MCP_ROOT` explicitly for untrusted requests.

## Troubleshooting

1. **Subagents not working**: Ensure `ALPHA_FEATURES=true` is set
2. **Goose not found**: Verify Goose CLI is installed and in PATH
3. **Recipe not found**: Check `GOOSE_RECIPE_PATH` or place recipes in working directory

## License

MIT