Skip to main content
Glama
README.md
# aviator-mcp-unofficial

**Unofficial** [Model Context Protocol](https://modelcontextprotocol.io) server for the [Aviator](https://aviator.co) MergeQueue REST API. Lets Claude (or any MCP client) inspect and operate your merge queue: see why a PR isn't merging, find which PR broke a batch, queue or dequeue PRs, pause branches for a release freeze, and read or change the queue config.

> Not affiliated with, endorsed by, or supported by Aviator Technologies, Inc. "Aviator" is their trademark. This project uses only Aviator's public, documented API.

## Tools (14)

| Read (no side effects) | Write (changes the real queue) |
|---|---|
| `list_repositories` — repos + paused/active | `queue_pr` — queue a PR (optional skip-line + reason) |
| `get_queue_stats` — queued / processing / waiting | `dequeue_pr` |
| `list_queued_prs` — queue contents in order | `refresh_or_sync_pr` — `refresh` or `sync` with base |
| `get_pr_status` — by number or branch | `set_queue_paused` — whole repo or a branch glob |
| `get_bot_pr` — PRs inside a batch (draft) PR | `backport_pr` |
| `get_bisection_status` — failed-batch bisection | `update_config` — replace the YAML config (validated locally first) |
| `get_config` — YAML (+ optional change history) | |
| `get_analytics` — summary of queue metrics | |

Write tools are annotated `destructiveHint: true`, so clients can ask for confirmation.

## Install

Requires Python ≥ 3.12.

```bash
pip install git+https://github.com/danielorzeata83-a11y/aviator-mcp
```

Create an API token in Aviator (Settings → API token: an account token, or a personal `av_uat_…` token).

### Claude Code

```bash
claude mcp add aviator --env AVIATOR_API_TOKEN=av_uat_xxx -- aviator-mcp
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "aviator": {
      "command": "aviator-mcp",
      "env": { "AVIATOR_API_TOKEN": "av_uat_xxx", "AVIATOR_DEFAULT_ORG": "acme" }
    }
  }
}
```

### Configuration

| Variable | Required | Meaning |
|---|---|---|
| `AVIATOR_API_TOKEN` | yes | Bearer token |
| `AVIATOR_API_URL` | no | Default `https://api.aviator.co`; set it for on-prem installs |
| `AVIATOR_DEFAULT_ORG` / `AVIATOR_DEFAULT_REPO` | no | Used when a tool call omits `org` / `repo` |

## Examples

- "Why isn't acme/api #1240 merging?" → `get_pr_status` → *blocked: merge conflict with main (code 106)*
- "Batch #5001 failed — who broke it?" → `get_bot_pr` → *#1242, required check build_and_test failed*
- "Pause release-* in acme/api for the freeze" → `set_queue_paused(branch_pattern="release-*")`
- "Switch to parallel mode, 5 builds" → `get_config` → `update_config` with the full edited YAML

A companion **Claude skill** (`skill/aviator-mergequeue`) adds workflows, status codes and the config reference. Install it by copying that folder into your Claude skills directory, or zip it and upload it in Claude.

## Behaviour notes and limitations

- Errors are turned into actionable messages (401 token, 403 permission/repo not configured, 404, 400 field list, 429 rate limit). GET requests retry once on 429/5xx; writes are **never** retried automatically.
- Large outputs are capped: the config YAML is truncated (`max_chars`), lists are limited (`limit`), and analytics return a summary unless `include_daily=true`.
- Not covered in v0.1: the GraphQL API, `user_actions` (Enterprise audit log), and the TestDeck, Releases, Verify and Runbooks APIs.
- Branch-level pause **status** can't be read: tested against the live API, `GET /api/v1/branches` is rejected and the POST form requires `paused` (it changes state). Pausing/resuming branches works via `set_queue_paused`.
- Verified end-to-end against a live Aviator account (Nov 2026): every tool, including queue → merge, a parallel-mode batch, backport, skip-line, sync, branch pause and config update.
- Live-API quirks handled: `affected_targets` and a full merge-commit message (`title` + `body`) are always sent; analytics times are in minutes.
- `AVIATOR_DEMO=1` runs the server on simulated data (no token, no network) for demos.

## Repository layout

| Path | What it is |
|---|---|
| `src/aviator_mcp/` | The MCP server (`server.py` tools, `client.py` HTTP + errors, `logic.py` validation, `demo.py` simulated API) |
| `tests/` | Unit tests (HTTP mocked with respx) |
| `eval/` | 20-task evaluation harness on a simulated Aviator world |
| `skill/aviator-mergequeue/` | Claude skill: `SKILL.md` + references |
| `skill/eval/` | Skill-triggering evaluation |
| `docs/PORTFOLIO.md` | Problem → solution → measured results |

## Development

```bash
pip install -e ".[dev]"
pytest --cov=aviator_mcp          # unit tests (HTTP mocked with respx)
bash eval/oracle.sh               # validates the evaluation harness
```

## License

MIT. API knowledge is derived from Aviator's documentation (github.com/aviator-co/gitbook-docs, MIT).

TDQS

A3.6/5.0

Scored across 14 tools

Disambiguation4/5

Most tools target clearly separate concerns (queue ops, PR status, bot/batch inspection, config, analytics, pause). Minor overlap exists between get_bot_pr, get_pr_status, and get_bisection_status, all of which surface batch/bot PR information during failure investigation, and refresh_or_sync_pr bundles two distinct actions into one tool.

Naming Consistency4/5

Nearly all tools follow a consistent snake_case verb_noun pattern (get_pr_status, list_queued_prs, queue_pr, dequeue_pr, update_config). The only deviation is the compound-verb refresh_or_sync_pr, which is readable but breaks the single-verb convention.

Tool Count5/5

14 tools is well within the well-scoped 3-15 range and each tool maps to a distinct merge-queue operation. No evident filler or redundant tools.

Completeness4/5

The surface covers the core lifecycle: queue/dequeue, status inspection, bisection/batch diagnostics, repo listing, queue stats, config get/update, analytics, pause, and backport. Gaps remain around per-PR skip-line/priority options (dequeue mentions clearing them but nothing sets them) and there is no way to inspect individual PR CI checks or batch contents beyond the bot PR summary.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues