# squad-mcp

[![License: MIT](https://img.shields.io/github/license/MustafaBozann/squad-mcp)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/Python-3.11+-blue.svg)](https://www.python.org/)
[![Last commit](https://img.shields.io/github/last-commit/MustafaBozann/squad-mcp)](https://github.com/MustafaBozann/squad-mcp/commits/main)
[![Tests](https://github.com/MustafaBozann/squad-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/MustafaBozann/squad-mcp/actions/workflows/ci.yml)

**An MCP server that reviews your code changes with four specialist agents running in parallel — for a fraction of the cost of doing it naively.**

## The problem

Ask an AI coding agent to "review this PR, write tests, update the docs, and check for risky changes" and it usually does these one at a time — reading the whole codebase again for each step. That's slow and it burns a lot of tokens (which means it costs more).

## What squad-mcp does

You call one tool, `dev_squad_process`, with a repo path and a task description. Behind the scenes:

1. It fetches the relevant context **once** (git diff + architecture summary) instead of letting every agent re-read the codebase separately.
2. A cheap model decides which specialists are actually needed — no point running a Test Agent on a comment-only change.
3. The specialists that are needed (Docs, Test, Refactor, Review) run **in parallel**, each using the model that fits the job — a fast/cheap model for simple tasks, a stronger one for anything that needs real judgment.
4. Everything comes back as one combined report with a diff you can apply, plus a cost breakdown.

It doesn't scan your codebase from scratch — it queries an existing indexed code graph ([codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)) for just the structure it needs. squad-mcp doesn't reimplement that part; it builds the orchestration and cost-optimization layer on top of it.

## Example

Input (calling `dev_squad_process` from Claude Code or any MCP client):

```json
{
  "repo_path": "/Users/user/projects/my-python-app",
  "task_description": "Review the recent changes in core/auth.py, suggest unit tests, and check for refactor opportunities.",
  "target": "staged"
}
```

Output (trimmed):

````markdown
# squad-mcp — Pipeline Report

**Total cost:** $0.0244 | **Estimated savings:** 83.5% vs. running everything on Sonnet without caching
**Duration:** 3.42s

## Docs Agent (claude-haiku-4-5-20251001)
Added a missing docstring to `authenticate_user`.

```diff
 def authenticate_user(username, password):
+    """Authenticates a user against the database."""
      return db.query(username, password)
```

## Test Agent (claude-haiku-4-5-20251001)
Added edge-case tests (empty password, SQL injection input).

## Refactor Agent (claude-sonnet-5)
Found a timing-attack risk in the password comparison — suggested `secrets.compare_digest`.

## Review Agent
Skipped — triage determined this change carries no architectural risk.
````

## How it's put together

```mermaid
graph TD
    User([Claude Code / User]) -->|dev_squad_process| Server[squad-mcp]
    Server --> Fetcher[Context Fetcher]
    Fetcher -->|one query| Graph[codebase-memory-mcp]
    Fetcher --> Triage{Triage}
    Triage -->|skip what's not needed| Router[Model Router]
    Router --> Docs[Docs Agent]
    Router --> Test[Test Agent]
    Router --> Refactor[Refactor Agent]
    Router --> Review[Review Agent]
    Docs & Test & Refactor & Review --> Report[Combined report + cost log]
    Report --> User
```

## Setup

```bash
# 1. Install codebase-memory-mcp (squad-mcp depends on it)
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash

# 2. Clone and install squad-mcp
git clone https://github.com/MustafaBozann/squad-mcp.git
cd squad-mcp
python -m venv .venv
.venv\Scripts\activate      # Windows
# source .venv/bin/activate # macOS/Linux
pip install -e .[dev]

# 3. Add your API key
copy .env.example .env      # Windows
# cp .env.example .env      # macOS/Linux
# then fill in ANTHROPIC_API_KEY
```

Add it to Claude Desktop / Claude Code by putting this in your MCP config:

```json
{
  "mcpServers": {
    "squad-mcp": {
      "command": "C:\\path\\to\\squad-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\squad-mcp\\squad_mcp\\mcp_server.py"]
    }
  }
}
```

## Does it actually save money?

The numbers below are from a **simulated** benchmark (`benchmarks/run_benchmark.py`). Run it yourself with `--real` (and a real API key) to get measured numbers on your own repo instead of trusting mine:

| Scenario | Naive (tokens / cost) | squad-mcp (tokens / cost) | Reduction |
|---|---|---|---|
| Small PR (2 files) | 11,600 / $0.054 | 5,800 / $0.010 | 80.8% |
| Medium PR (10 files) | 63,200 / $0.228 | 47,400 / $0.036 | 84.2% |
| Large PR (30+ files) | 226,000 / $0.750 | 226,000 / $0.138 | 81.5% |

## How this compares

| | CodeRabbit | Qodo | squad-mcp |
|---|---|---|---|
| Code graph context | No (diff-only) | Partial | Yes |
| Parallel specialist agents | No | No | Yes |
| Fully local mode (Ollama) | No | No | Yes |
| Per-run cost breakdown | No | No | Yes |
| Language support (v1) | Multiple | Multiple | Python only |

## Known limitations

- v1 only handles Python repositories.
- The Test Agent proposes tests, it doesn't run them yet.
- The GitHub Action in `examples/` is a template, not a published reusable action.
- Benchmarks are simulated by default — see `--real` above.

## Built with

The full build log (what was built in what order, and why) is in [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).

## License

MIT — see [LICENSE](LICENSE).