# Squad Mcp > MCP server + Claude Code plugin: multi-agent advisory squad with PRD-decomposed tasks, persistent learnings, weighted rubric scorecard, and PR posting. - **Type:** MCP server - **Install:** `agentstack add mcp-ggemba-squad-mcp` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [ggemba](https://agentstack.voostack.com/s/ggemba) - **Installs:** 0 - **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [ggemba](https://github.com/ggemba) - **Source:** https://github.com/ggemba/squad-mcp - **Website:** https://www.npmjs.com/package/@gempack/squad-mcp ## Install ```sh agentstack add mcp-ggemba-squad-mcp ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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) ```text /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) ```bash 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): ```json { "mcpServers": { "squad": { "command": "npx", "args": ["-y", "@gempack/squad-mcp"] } } } ``` #### Cursor `.cursor/mcp.json` (workspace-scoped) or global Cursor settings: ```json { "mcpServers": { "squad": { "command": "npx", "args": ["-y", "@gempack/squad-mcp"] } } } ``` #### Warp Settings → MCP servers → add. Command `npx`, args `["-y", "@gempack/squad-mcp"]`. ### From source (development) ```bash 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: ```text /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; `apply_consolidation_rules` 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. ```mermaid 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: ```mermaid 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`:** ```text /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`:** ```text /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:** ```text /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:** ```text /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:** ```text /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:** ```text /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: ```mermaid 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"] ``` ```text /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. | ```text # 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, files_count, new_module, 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](https://github.com/ggemba) - **Source:** [ggemba/squad-mcp](https://github.com/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. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-ggemba-squad-mcp - Seller: https://agentstack.voostack.com/s/ggemba - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.