orangepro-mcp

# OrangePro

**Find the behaviors your tests miss. Generate grounded tests that actually run.**

`opro` builds a knowledge graph from your local checkout, maps every behavior in your code, shows which ones are tested and which aren't, and generates integration-level tests grounded in real symbols — not hallucinated imports. It runs as a CLI and a local stdio MCP server.

Install the target repository's dependencies first, then run OrangePro from that repository:

```bash
cd /path/to/your/repo
npm install # or pnpm install / bun install / the repository's package manager

# Optional: enables AI candidate links, candidate flows, and test generation.
export ANTHROPIC_API_KEY="..." # or OPENAI_API_KEY / OLLAMA_BASE_URL

npx -y @orangepro/mcp-server@latest start . --prompt-version v5
open .orangepro/behavior-coverage.html
```

With no model key, the same command still performs deterministic analysis, renders the report, and dynamically proves eligible behaviors using existing tests. With a key, it also discovers AI candidate flows and drafts grounded tests for the highest-risk gaps. AI output never changes evidence tiers; only the mutation-kill oracle can mint **Dynamically Proven**.

The command writes:

```
.orangepro/
├── behavior-coverage.html   ← open this: system map, risks, flows, behaviors
├── graph.json               ← deterministic evidence graph
├── COVERAGE_REPORT.md       ← coverage and gap summary
├── rtm.md                   ← requirements traceability matrix
└── ai/                      ← candidate AI links/flows when a provider is configured

orangepro_generated/         ← contained generated tests; existing source files are untouched
```

The report opens on a **system map** of your repo — entry lanes (GraphQL/HTTP/Jobs) flowing into the services they reach, sized by traffic, colored by evidence tier, risk-ringed — identical on every run. Each completed rerun shows a **delta banner** against the previous completed run. The report discloses when bounded path enumeration prunes additional branch expansions. Every behavior gets a plain-English description; every top risk gets a deterministic context line and a state-aware next step.

Run `opro export` when you want a machine-readable evidence pack.
<img width="895" height="960" alt="Screenshot 2026-07-08 at 1 18 01 AM" src="https://github.com/user-attachments/assets/73b8a812-2eab-43a1-8aed-4289545e630b" />

---

## Install

```bash
# No install needed: run the full local workflow in the current repository
npx -y @orangepro/mcp-server@latest start . --prompt-version v5

# Or global install
npm install -g @orangepro/orangepro-mcp
opro start . --prompt-version v5

# Or from source
git clone https://github.com/OrangeproAI/orangepro-mcp.git
cd orangepro-mcp && npm ci && npm run build && npm link
```

---

## Use with your coding agent

OrangePro runs as an MCP server. Any MCP-compatible agent (Cursor, Claude Code, Codex, Copilot, OpenCode) can drive it.

### Quick agent setup

If you already have `opro` on your PATH, print the exact config for your client:

```bash
opro agent --client codex
opro agent --client claude-code
opro agent --client cursor
opro agent --client opencode
opro agent --client generic
```

No global install is required. These commands use the published package:

```bash
# Codex
npx -y @orangepro/mcp-server@latest agent --client codex

# Claude Code
npx -y @orangepro/mcp-server@latest agent --client claude-code

# Cursor
npx -y @orangepro/mcp-server@latest agent --client cursor

# OpenCode
npx -y @orangepro/mcp-server@latest agent --client opencode

# Generic MCP clients, including VS Code/Copilot-style MCP settings
npx -y @orangepro/mcp-server@latest agent --client generic
```

### Manual MCP config

Add to your client's MCP config:

```json
{
  "mcpServers": {
    "orangepro-local": {
      "command": "npx",
      "args": ["-y", "@orangepro/mcp-server@latest", "mcp"]
    }
  }
}
```

| Client | Config location |
| --- | --- |
| Claude Code | `.mcp.json` or `~/.claude.json` |
| Cursor | `~/.cursor/mcp.json` or Settings → MCP |
| Codex | Config printed by `opro agent --client codex` or `npx -y @orangepro/mcp-server@latest agent --client codex` |
| VS Code / Copilot | MCP settings; use the `generic` config if your client accepts raw MCP server JSON |
| OpenCode | Config printed by `opro agent --client opencode` |

### The workflow

Tell your agent:

> "Use `orangepro_start`, then `orangepro_generate_tests` with base_ref=main. Write each test to its suggested_path, run it, and report pass/fail."

The agent writes the test, runs it, calls `orangepro_prove`, and the behavior turns Dynamically Proven. One prompt, full loop.

### MCP tools (18 total)

| Tool | What it does |
|------|--------------|
| `orangepro_start` | One-command setup: analyze + report + next actions |
| `orangepro_analyze_sources` | Build/refresh the evidence graph |
| `orangepro_generate_tests` | Generate grounded tests for gaps |
| `orangepro_prove` | Run mutation-kill oracle on a behavior |
| `orangepro_prove_loop` | Setup commands + dynamic proof + report refresh for one behavior |
| `orangepro_find_test_gaps` | List behaviors with weak/missing tests, ranked by risk |
| `orangepro_graph_score` | Graph readiness score (0–100) |
| `orangepro_status` | Workspace state without generating anything |
| `orangepro_doctor` | Recommend next evidence to improve quality |
| `orangepro_rtm` | Requirements traceability matrix |
| `orangepro_stats` | Aggregate statistics |
| `orangepro_changed_impact` | What a diff touches (requires git + base ref) |
| `orangepro_record_run` | Record a test run result |
| `orangepro_explain_test` | Explain why a test was generated |
| `orangepro_export_evidence_pack` | Export metadata-only evidence pack |
| `orangepro_update_graph` | Incremental graph update |
| `orangepro_ai_links` | Weak behavior→symbol suggestions (optional AI) |
| `orangepro_ai_flows` | Candidate flow discovery (optional AI) |

---

## CLI reference

```bash
opro                          # analyze + report + agent next actions
opro start --base main        # same, scoped to a branch diff
opro analyze                  # build the evidence graph
opro score                    # graph readiness (0–100)
opro gaps --limit 10          # top 10 untested behaviors
opro generate --base main     # tests for PR diff
opro generate --single        # top gap, whole repo
opro prove                    # mutation-kill oracle (use the prove_run args returned by generate)
opro rtm                      # traceability matrix
opro export                   # metadata-only evidence pack
opro mcp                      # run as MCP server (stdio)
opro doctor                   # what evidence to add next
opro doctor --proof           # explain why dynamic proof could not close
opro coverage                 # ingest runtime coverage
```

Add `--json` to any read command for machine output. Run `opro help` for the full reference.

---

## PR workflow

```bash
opro generate --base main              # tests for what this branch changed
opro generate --pr 1234                # checks out PR #1234 — mutates your working tree; needs gh + confirmation (prefer --base)
opro generate --changed                # current branch diff vs main
```

Each generated test includes:
- **Grounding** — the real files, symbols, and existing tests it cites
- **Run hints** — where to write it, how to run it
- **Scenario bucket + technique** — what failure mode it targets and how

If the environment can't run tests yet (dependencies not installed, runner unconfigured), rejected drafts are kept as **Manual tests** — scenario, Given/When/Then steps, synthetic test data, and expected outcome in plain English, with the exact blocker named. Install dependencies and re-run `opro start` to turn them into runnable tests. Runnable tests always replace Manual tests for the same behavior; the two are never mixed.

---

## Test categories

Generation is evidence-gated. A category is produced only when the graph has supporting evidence — never padded with generic filler. These are the local generation buckets. The report additionally shows each risk's **applicable testing categories** (contract, boundary limits, integration flow, state lifecycle, failure recovery, …), derived deterministically from graph facts. Categories with generated drafts are highlighted as drafts; they are not coverage or proof, and remaining applicable categories stay outlined. Neither taxonomy changes evidence tiers.

| Category | What it targets |
|----------|-----------------|
| Happy path | Primary expected behavior |
| Validation error | Bad/invalid input handling |
| Edge case | Boundaries, empty/null, concurrency, retries |
| Integration flow | Multi-step behavior across services |
| Security / privacy | Auth, injection, data leakage |
| Regression | Pinning a previously-broken behavior |

---

## Evidence tiers

Every behavior gets exactly one tier. Nothing is labeled "tested" on faith.

| Tier | What it means | How you get there |
|------|---------------|------------------|
| **Dynamically Proven** | A real test kills a targeted mutant of this behavior | `opro prove` after writing/running a test |
| **Runtime-covered** | Coverage tool executed this code | `opro start --generate-coverage` |
| **Statically Linked** | A test **imports and calls** this code — a hard structural link | Automatic during analysis |
| **Unconfirmed Candidate** | A lexically similar test file exists, but nothing links it — a lead, **not evidence** | Automatic; upgrade it by writing the linking test |
| **No Signal** | Nothing tests this behavior yet | — |

> **"Dynamically Proven 0" is normal on first run.** Static analysis always runs. Dynamic proof requires running tests against targeted mutations. That's the trust model — nothing is Dynamically Proven until a real test kills a real mutant.

When runtime coverage is available, `opro start` also compares Runtime-covered and Dynamically Pr