Squad Mcp

squad-mcp

[](https://www.npmjs.com/package/@gempack/squad-mcp) [](https://github.com/ggemba/squad-mcp/actions/workflows/ci.yml) [](LICENSE) [](https://squad.devthinks.com.br/)

Website:

MCP server that exposes the squad-dev workflow as deterministic tools, prompts, and resources. It classifies a task, scores its risk, picks an advisory squad of specialist reviewers, slices the changed files per agent, validates the plan, and consolidates the advisory verdicts. The host LLM (Claude Code, Cursor, Warp, Claude Desktop, …) orchestrates; squad-mcp provides the building blocks.

It also ships as a Claude Code plugin that bundles the MCP server, the slash commands (/squad:implement, /squad:review, /squad:question, /squad:debug, /squad:tasks, /squad:next, /squad:task, /squad:grillme, /squad:pipeline, /squad:inventory, /squad:stats, /brainstorm, /commit-suggest, /squad:enable-journaling), and the matching skills behind a single /plugin install.

Install

Claude Code plugin (recommended)

/plugin marketplace add ggemba/squad-mcp
/plugin install squad@gempack

The plugin bundles the MCP server plus the slash commands and skills (/squad:implement, /squad:review, /squad:question, /squad:debug, /squad:tasks, /squad:next, /squad:task, /squad:grillme, /squad:pipeline, /squad:inventory, /squad:stats, /brainstorm, /commit-suggest, /squad:enable-journaling). After install, restart Claude Code to pick up the new commands and the squad MCP server.

npm package (any MCP client)

npx -y @gempack/squad-mcp

The package exposes the squad-mcp binary and works with any MCP-capable client. Examples below.

Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json (Windows) / ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "squad": {
      "command": "npx",
      "args": ["-y", "@gempack/squad-mcp"]
    }
  }
}

Cursor

.cursor/mcp.json (workspace-scoped) or global Cursor settings:

{
  "mcpServers": {
    "squad": {
      "command": "npx",
      "args": ["-y", "@gempack/squad-mcp"]
    }
  }
}

Warp

Settings → MCP servers → add. Command npx, args ["-y", "@gempack/squad-mcp"].

From source (development)

git clone https://github.com/ggemba/squad-mcp.git
cd squad-mcp
npm install
npm run build
node dist/index.js

Your first /squad:implement in 60 seconds

After install, the plugin is silent until you invoke it. Drop into a repo with at least one staged or recently committed change and run:

/squad:implement add a /health endpoint that returns {"status":"ok"}

What happens, in order:

1. Classification. compose_squad_workflow looks at your prompt + changed files and prints something like work_type: Feature, risk: Low, agents: [developer, qa].
2. Depth resolution. It also picks an execution depth — quick, normal, or deep — and surfaces it as mode + mode_source on the output. Auto-detect rules: deep on risk == High / Security work / auth-money-migration signals; quick on Low-risk diffs with ≤5 files and no high-risk signals; normal otherwise. Pass --quick / --normal / --deep to override. If you force --quick on a high-risk diff, security is force-included and a structured mode_warning is set so the host can surface it.
3. Plan. The skill drafts an implementation plan and sends it to tech-lead-planner for review (skipped in quick). You see the plan in chat.
4. Gate 1. The skill stops and asks you to approve. Reply approved, go, or equivalent to proceed; anything else cancels.
5. Implementation. After approval, the skill writes code. Never commits or pushes — that's your call.
6. Advisory squad. In v1.5+ the advisory runs AFTER implementation against the actual diff, not a plan draft. Every selected agent (architect, dba, dev, qa, security, reviewer — depends on the selection; capped at 2 for quick, force-includes architect + security for deep) reviews in parallel and emits a findings list + a Score: NN/100.
7. Consolidation. tech-lead-consolidator produces a verdict (APPROVED / CHANGES_REQUIRED / REJECTED) plus a scorecard like:

`` SQUAD RUBRIC — weighted 82 / 100 (threshold 75) Application Code ████████████████░░░░ 82 ×18% developer Testing & QA ███████████████░░░░░ 78 ×14% qa ` The tech-lead-consolidator persona is skipped in quick mode; applyconsolidationrules still runs to produce the verdict. If the verdict is CHANGES_REQUIRED / REJECTED`, the reject-loop dispatches the implementer again against the delta.

Other commands to try once /squad:implement works:

• /squad:review — same agents, but on an existing diff or PR (no implementation).
• /squad:question — fast read-only code Q&A. Spawns the code-explorer subagent to grep + excerpt the relevant lines and answers with file:line citations. Use it for "where is X defined?", "what calls Y?", "how does the auth flow work?". No plan, no gates, no implementation.
• /squad:debug — read-only bug investigation. Takes a bug description + optional stack trace + repro steps, orients via code-explorer, then dispatches the debugger persona to emit N ranked hypotheses (1 on --quick, 3 on --normal, 5 with a cross-check pass on --deep) with file:line evidence and verification steps. The missing middle between /squad:question (lookup) and /squad:implement (fix).
• /squad:tasks docs/prd.md — decompose a PRD into atomic tasks with confirmation before they land in .squad/tasks.json.
• /squad:next — pick the next ready task; /squad:task 3 — work on a specific one.
• /squad:grillme — Socratic plan validation. Grills your plan one question at a time against the project's domain language (CONTEXT.md) and prior decisions (ADRs in docs/adr/), and writes resolved terms back to both as it goes. Run it before /squad:implement to stress-test a plan; pass --no-write for a dry run.
• /squad:pipeline — runs the six squad steps as one guided, human-gated sequence: brainstorm → grillme → tasks → next → implement → review. See [Cradle-to-grave with /squad:pipeline](#cradle-to-grave-with-squadpipeline) below.
• /squad:inventory — codebase audit/inventory. Scans the repo for a named pattern (defined by a YAML "recipe pack") and emits a structured Markdown report cross-referenced with framework metadata (routes, handlers). Hybrid pipeline: a deterministic rg sweep does the file IO, then tiered LLM enrichment (Haiku tier-1, Sonnet escalation on requires_semantic rules or low confidence) classifies each finding. Bundled pack v1: php-inline-sql (inline SQL in PHP/Laravel). Writes one MD to ./docs/inventory/-.md by default; --out overrides (accepts Obsidian vault paths). Reads source; never edits code.
• /brainstorm — exploratory Q&A, no code.
• /commit-suggest — generate a Conventional Commits message for staged changes.
• /squad:stats — observability dashboard over .squad/runs.jsonl. Bar charts (verdict mix, score buckets), Unicode sparkline trend, per-agent breakdown of avg wall-clock and estimated tokens. Read-only; never writes. Flags: --quick (last 7d), --thorough (full history + health panel), --since , --last , --no-color. Token figures are estimates (chars ÷ 3.5).

Stuck? Check INSTALL.md → Troubleshooting. The most common failures (Failed to reconnect to plugin:squad:squad, marketplace cache, SSH key) all have entries.

How it works

squad-mcp is a deterministic server — it makes no LLM calls of its own. The host LLM does all the reasoning; the server hands it building blocks (tools, prompts, resources) and the skills wire them into a workflow.

flowchart LR
  subgraph Host["Host LLM · Claude Code / Cursor / Warp / Claude Desktop"]
    SK["Skills/squad:implement · /review/pipeline · /stats · ..."]
    SA["Subagentsarchitect · developersecurity · qa · ..."]
  end
  subgraph Server["squad-mcp server · deterministic, no LLM calls"]
    T["Toolsclassify · score_riskselect_squad · consolidate"]
    P["Promptsorchestrationadvisory · consolidator"]
    R["Resourcesagent://...severity://..."]
  end
  SK -->|invoke tools| T
  SK -->|load| P
  SA -->|read role def| R
  T -->|verdict + rubric scorecard| SK

A single /squad:implement run threads two human gates — plan approval and a Blocker halt — so the squad never writes code you did not sign off on:

flowchart TD
  A["/squad:implement <task>"] --> B["classify · score risk · select squad · pick depth"]
  B --> C{"Gate 1plan approved?"}
  C -->|no| X1["stop — nothing written"]
  C -->|yes| D["advisory squad runs in paralleleach agent emits Score 0-100"]
  D --> E{"Gate 2any Blocker?"}
  E -->|yes| X2["halt — ask the user"]
  E -->|no| F["implement the approved plan"]
  F --> G["consolidate → verdict + rubric scorecard"]
  G --> H{"verdict"}
  H -->|APPROVED| I["done — committing is your call"]
  H -->|CHANGES_REQUIRED / REJECTED| J["reject loop → re-review the delta"]
  J --> G

Depth (quick / normal / deep) auto-scales the run: quick caps the squad at 2 agents and skips the planner + consolidator personas; deep force-includes architect + security and raises the reject-loop ceiling. See [Your first /squad:implement](#your-first-squadimplement-in-60-seconds) for the auto-detect rules.

Examples in practice

Every example is a single line you type into the host. The squad sizes itself from the prompt + the changed files — you only reach for a flag to override.

Low-risk feature — auto-detected quick:

/squad:implement add a /health endpoint that returns {"status":"ok"}

> work_type: Feature · risk: Low · mode: quick (auto) · agents: [developer, qa] > Planner skipped, 2-agent advisory, sub-30s feedback. Stops at Gate 1 for your approval.

Auth refactor — auto-detected deep:

/squad:implement refactor src/auth/jwt-validator to rotate signing keys

> work_type: Security · risk: High · mode: deep (auto) · agents: [architect, security, developer, qa, reviewer] > touches_auth fires → deep. Planner + consolidator personas run, reject-loop ceiling raised to 3.

Forcing --quick on a risky diff — the safety override:

/squad:implement --quick patch the refund amount rounding in src/billing/ledger.ts

> mode: quick (user) · mode_warning set — --quick is honoured but security is force-included as one of the 2 agents because touches_money fired. The host surfaces the mode_warning so the downgrade is never silent.

Review an existing PR and post the verdict:

/squad:review #42

> Runs the advisory on PR #42's diff, renders the scorecard, then dry-runs the PR post — shows the exact request and the markdown body it would post, and waits for your go.

Fast read-only code Q&A — no plan, no gates:

/squad:question where is the rubric weighted score computed?

> Spawns code-explorer, answers with file:line citations. Sub-second on --quick.

See where your runs went:

/squad:stats

> Reads .squad/runs.jsonl and renders a cyan ANSI panel — verdict mix, score buckets, sparkline trend, per-agent token + wall-clock breakdown.

Cradle-to-grave with /squad:pipeline

Each squad skill runs standalone. /squad:pipeline chains them into one guided sequence for a feature going from idea to verified change, so you never have to remember what comes next or how to wire one step's output into the next:

flowchart LR
  BS["/brainstormdecide what to build"] --> GM["/squad:grillmestress-test the plan"]
  GM --> TK["/squad:tasksdecompose into tasks"]
  TK --> NX["/squad:nextpick the next task"]
  NX --> IM["/squad:implementbuild it"]
  IM --> RV["/squad:reviewreview the change"]

/squad:pipeline add multi-currency support to the checkout flow

The pipeline is an executor that auto-invokes each sub-skill and halts only at explicit user-decision gates (proceed / adjust / skip / exit). Each time you invoke it, it:

1. Reconstructs how far the feature has progressed from the conversation context (or the .squad/pipeline-state.json resume cache).
2. Dispatches the next sub-skill via the Skill tool with arguments pre-filled and depth flags forwarded.
3. Stops at each inter-phase gate to explain the decision you are about to make.

Sub-skills' own internal gates (e.g. /squad:implement Gate 1 plan approval, Gate 2 Blocker halt) keep firing as before — those remain in-skill human checkpoints. Reserved interruption commands (pipeline stop, pipeline skip, pipeline redo, pipeline back) break the auto-flow at any gate. The pipeline records no telemetry of its own; each sub-skill still records its own run, so /squad:stats aggregates them normally.

| Flag | Purpose | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | --from | Enter the pipeline mid-sequence (brainstorm / grillme / tasks / next / implement / review). Skip the phases you have already done. | | --quick / --normal / --deep | Forwarded as-is to every step the pipeline recommends. |

# already brainstormed — jump straight to stress-testing the plan
/squad:pipeline --from grillme add multi-currency support to the checkout flow

# take a small change cradle-to-grave at quick depth
/squad:pipeline --quick fix the timezone bug in the daily report job

What it provides

Tools (deterministic, pure functions)

| Tool | Purpose | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | detect_changed_files | Hardened git diff --name-status --no-renames for a workspace. Allowlisted refs, 10s timeout, 1MB stdout cap. | | classify_work_type | Heuristic WorkType from prompt + paths (Feature / Bug Fix / Refactor / Performance / Security / Business Rule) with Low/Medium/High confidence. | | score_risk | Compute Low/Medium/High from boolean signals (auth, money, migration, filescount, newmodule, api_change). | | select_squad | Select advisory agents for a work type. Combines matrix + path hints + content sniff. Returns evidence per file. | | slice_files_for_agent | Filter a file list to those owned by a single agent. Used to build sliced advisory prompts.

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ggemba
• Source: ggemba/squad-mcp
• License: Apache-2.0
• Homepage: https://www.npmjs.com/package/@gempack/squad-mcp

Install and usage instructions live in the source repository linked above.