# mcp-multi-agent

An MCP server that gives your AI editor a small team: a **BA**, a **developer**, a **reviewer** and a **refactor** agent. You give it a ticket number; it works out which agent is needed, pulls the context from Jira, GitHub and SonarQube in parallel, and hands the model in your editor a short, precise plan. The project's own rules files decide how the agents behave.

What a run looks like, summarised:

```text
you   ›  do PROJ-142

router   no open PR · ticket has acceptance criteria → developer
jira     PROJ-142 "Discount codes at checkout" · 3 acceptance criteria
sandbox  git worktree ../sandbox-PROJ-142 on feature/PROJ-142
rules    AGENTS.md (from .mcp-agent.json) + 4 learned rules
context  3 files distilled to a skeleton for the model
plan     .mcp-plan-PROJ-142.md → your editor implements it, you approve the edits
```

It is not a model. It is the orchestration around one: what to read, where to work, which rules apply and what must never happen.

## Why

AI coding sessions tend to go like this: paste the ticket, paste some files, repeat the team's rules for the hundredth time, and hope the agent doesn't touch something it shouldn't. This server makes the routine parts automatic and the dangerous parts impossible:

- **One command per ticket.** `do PROJ-142` picks the agent from the state of the work.
- **The team's rules, from the team's files.** `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `.clinerules`, Copilot instructions: the agents read the files you choose, fresh on every run.
- **A sandbox per ticket.** Each ticket gets its own git worktree and branch; your working copy is never touched.
- **Guardrails that are code, not prompts.** Commands are checked against an allowlist before they run.
- **Less context, same meaning.** Large files reach the model as a skeleton of types and signatures.

## The agents

| Agent | When the router picks it | What it does |
| --- | --- | --- |
| **BA** | The ticket has no acceptance criteria, or they are vague or still open | Extracts the criteria (a section, Given/When/Then or a checklist) and lists the questions to settle with the product owner: untestable words ("fast", "intuitive"), TBDs, UI work without a design, no error cases. |
| **Developer** | The ticket is ready and there is no PR yet | Creates the sandbox, applies the rules, distills the files in scope and writes a plan with the acceptance criteria as a checklist. Your editor makes the edits, with your approval. |
| **Reviewer** | `feature/<ticket>` already has an open PR | Reads the diff, Sonar issues and the acceptance criteria in parallel, runs checks on the added lines and drafts a review. It returns a **preview**; it posts on the PR only with `post: true`. |
| **Refactor** | The ticket is labelled `refactor` or `tech-debt` | Distills the files, pulls Sonar issues and plans a refactor that keeps the public API. |
| **Squad** | `squad: true` | Developer and reviewer in parallel. |

Every decision can be forced with a flag (`ba`, `refactor`, `squad`).

## Rules files

The agents follow the rules your project already keeps for AI tools. Which files, in order:

1. `rulesFiles` passed to the tool
2. `rulesFiles` in **`.mcp-agent.json`** at the project root (commit it, so the whole team gets the same rules)
3. `rulesFiles` saved by the setup script, for that project
4. every known rules file found in the project: `.clinerules`, `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `.cursor/rules/`, `.windsurfrules`, `.github/copilot-instructions.md`, `GEMINI.md`

```json
// .mcp-agent.json
{ "rulesFiles": ["AGENTS.md", "docs/frontend-guidelines.md"] }
```

On top of that, **learned rules**: when you reject something ("don't use `any`"), `capture_behavior_feedback` stores it as a rule for that project. Learned rules are one line each, at most 300 characters and 50 per project (the least used go first), and you can list and remove them. `show_rules` tells you exactly what the agents will follow and why.

## Safety

- **Sandbox:** a git worktree per ticket at `../sandbox-<ticket>`, on `feature/<ticket>`.
- **The server itself only runs `git`**, without a shell, with arguments as an array, an allowlist of subcommands, and every absolute path scoped to the project.
- **`check_command`** lets the editor ask before running anything. Known programs only (git, npm, node, tsc, eslint, test runners, read-only file tools); blocked: deleting files, force pushes, pushing to `main`, `reset --hard`, publishing packages, `npx` of arbitrary packages, piping into a shell, command substitution, and any path outside the sandbox.
- **Ticket text is input, not instructions:** file paths taken from a ticket cannot leave the sandbox, and learned rules are sanitized to a single line before they reach a prompt.
- **Reviews are previews by default.** Nothing is posted on a PR unless you ask.
- **Secrets stay local:** tokens live in your editor's MCP config; logs redact anything that looks like a credential.
- **Auditable:** every step, command and downstream call is logged; `parse_audit_log` and `generate_task_metrics_report` show what happened and roughly how much context it sent.

## Quick start

> Running the server requires a licence from the author (see [Licence](#licence)). These steps are for licensed users.

Requirements: Node 18+, git, an editor with MCP support (Cline, Cursor, Claude Desktop, Claude Code, Codex CLI), and tokens for the services you use.

```bash
git clone <this repo> mcp-multi-agent
cd mcp-multi-agent
npm install
npm run setup
```

`npm run setup` builds the server and asks: which project, **which of its rules files the agents should follow** (or creates an `AGENTS.md` starter), which editor, which services, and the tokens. It registers the server in your editor and saves defaults so `do PROJ-123` needs nothing else. Restart the editor and ask it to run `do` with a ticket id.

Manual setup and every option: [docs/setup.md](docs/setup.md).

## Tools

| Tool | Purpose |
| --- | --- |
| `do` | One entry point: pick and run the right agent for a ticket. |
| `agent_ba`, `agent_developer`, `agent_reviewer`, `agent_refactor`, `run_squad` | Run an agent directly. |
| `show_rules` | Which rules files are in use and why, which exist, and the learned rules. |
| `capture_behavior_feedback`, `list_behavior_rules`, `remove_behavior_rule` | Manage learned rules. |
| `check_command` | Allowed or not, and why, before running a shell command in a sandbox. |
| `parse_audit_log`, `generate_task_metrics_report` | What happened, and the estimated context per session. |
| `execute_parallel_pipeline`, `downstream_call`, `downstream_list_tools` | Lower-level building blocks. |

## How it works

```text
editor (Cline · Cursor · Claude · Codex)
   │  stdio
   ▼
mcp-multi-agent ── router ── BA · developer · reviewer · refactor
   │                    │
   │                    ├─ rules      rules files + learned rules → prompt
   │                    ├─ sandbox    git worktree, command allowlist
   │                    ├─ distiller  TypeScript-compiler skeletons
   │                    └─ logger     audit log, redaction, session report
   ▼  stdio, spawned on demand and pooled
GitHub MCP · Jira MCP · SonarQube MCP · Confluence MCP · Chrome DevTools MCP
```

More in [docs/architecture.md](docs/architecture.md).

## Development

```bash
npm install
npm run build
npm test        # node:test, no extra test framework
```

Tests cover the router, the BA analysis, the sandbox (including real worktrees and the command policy), the distiller, rules loading and learned rules, and log redaction. CI runs them on Node 18, 20 and 22.

## Limitations

- The BA analysis is deterministic text analysis, not a model. It finds what is missing; it does not invent requirements.
- Token figures are estimates (about 4 characters per token): the model runs in your editor, so the server never sees real counts.
- `check_command` only protects you if the editor calls it. Keep the editor's own command approval on.
- The Jira integration uses the REST passthrough of `@aashari/mcp-server-atlassian-jira` (Jira Cloud, API v3).
- The npm builds of the GitHub and SonarQube MCP servers are deprecated upstream. They are pinned to their last versions here; moving to GitHub's and SonarSource's official servers is next on the list.

## Licence

© 2026 Alex Cenusa. All rights reserved. The code is public so it can be read; using, copying, modifying or distributing it requires my written permission. See [LICENSE](LICENSE).