Rbkmen/qa-orchestrator

A Python/FastMCP toolkit for evidence-bound code and QA reviews: deterministic workflow, eleven specialist profiles, nine fixed bundles, structured findings, and optional execution and evaluation tools.
The host (Codex, Claude Code, or another integration) retrieves evidence, runs models, validates findings, and owns the final QA decision. The MCP server checks workflow and report contracts. Optional Python tools supervise actual execution; connecting the MCP server alone does not activate them.
## Quick start
Requires Python 3.12+, Git, uv, and an MCP host. Supports Windows, macOS, and Linux. Model access is configured in the host.
For installation without a checkout, replace with the full immutable revision you intend to install:
bash
codex mcp add qa-orchestrator -- uvx --from 'git+https://github.com/Rbkmen/qa-orchestrator.git@ ' qa-orchestrator-mcp
Use the same revision for server and host instructions. Remote installs contain only published code; local upgrades require a checkout installation.
With no saved policy, modelpolicy is hostdefault: the host uses its own model and reasoning. Existing explicit policies remain active.
For a checkout installation:
bash
git clone https://github.com/Rbkmen/qa-orchestrator.git
cd qa-orchestrator
uv sync --locked
uv run qa-orchestrator-doctor --json
Register scripts/qa-orchestrator on macOS/Linux or .venv\Scripts\qa-orchestrator-mcp.exe on Windows. The client starts the STDIO server on demand. See Installation, Codex, and Claude Code.
Reference the canonical host rules from existing instructions. Verify the connection with getqaorchestrationcatalog, getqaorchestrationmodelpolicy, and prepareqaorchestration(agentprofile="codeexplorer"); these calls create no session.
## Architecture and responsibilities
| Layer | Responsibility |
| MCP server | Checklists, stage/group validation, fixed escalation rules, bounded session state |
| Evidence utilities | Immutable Git source/diff hashes, citation coordinates, exact context packets |
| HostReviewAdapter | Async executor supervision, concurrency/time budgets, group barriers and attempts |
| CodexProfileExecutor | Installed CLI execution, strict output schema, report validation and reported usage |
| Benchmark tools | Snapshot identity and scoring of explicitly adjudicated runs |
The host owns source retrieval, defect confirmation, severity, final decisions, code edits, and external writes. Jira, GitLab, CI, TestRail, Sentry, and other sources come through the host's tools. Initialization instructions are advisory; readonly=true and hostownsdecisions=true describe review ownership, while session tools mutate local state.
## Review workflow
text
Pinned evidence → triage → primary review groups → optional deep review
→ synthesis → awaitinghostoutcome → host final outcome
1. Build the evidence input; use ReviewContext for an auditable bound review.
2. Call startqaorchestration, then complete triage through advanceqaorchestration with one selectedprofile or selectedbundle.
3. Run the returned executiongroups. Profiles in one group may run concurrently; wait for all, then record the ordered completedprofiles and reports in one transition. Transition calls are sequential.