orangepro-mcp

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

OrangePro maps every public behavior in your codebase, scores each one by real test evidence, and shows you the structural blind spots before your users find them. Runs locally. Your code never leaves your machine.

npx -y @orangepro/mcp-server@latest start .

Table of Contents

• What you get
• Evidence tiers
• Quick start
• Use with your coding agent
• How it works
• Language support
• Privacy
• CLI reference
• MCP tools
• Platform
• Contributing

What you get

One command produces an interactive HTML report:

npx -y @orangepro/mcp-server@latest start .
open .orangepro/behavior-coverage.html

The report has two modes: Simple (integration-level blind spots, plain English) and Expert (full behavior list, evidence tiers, flows, system map). Toggle with the pill switch at the top.

*System map — entry lanes (GraphQL, HTTP, Jobs) flowing into services, sized by traffic, colored by evidence tier, red-ringed by risk.*

*Priority gaps of another open source Project HONO — top 20 unproven behaviors ranked by blast radius, with generated test drafts.*

Evidence tiers

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

> "Dynamically Proven 0" is normal on first run. Proof requires running tests against targeted mutations. That's the trust model.

Quick start

cd /path/to/your/repo
npm install          # install the repo's own dependencies first

npx -y @orangepro/mcp-server@latest start .
open .orangepro/behavior-coverage.html

No API key needed. The report shows your system map, evidence tiers, priority gaps, and delta since last run.

Want test generation? Add a model key (BYOK):

export ANTHROPIC_API_KEY="..."   # or OPENAI_API_KEY / OLLAMA_BASE_URL
npx -y @orangepro/mcp-server@latest start .

AI output never changes evidence tiers. Only the mutation-kill oracle can mint Dynamically Proven.

Output:

.orangepro/
├── behavior-coverage.html   ← open this
├── graph.json               ← deterministic evidence graph
├── COVERAGE_REPORT.md       ← coverage and gap summary
└── ai/                      ← candidate flows (when a key is configured)

orangepro_generated/         ← generated tests; your source files are never touched

Each rerun shows a delta banner: what entered the codebase, what moved up in risk, what got resolved.

Use with your coding agent

OrangePro runs as an MCP server. Add to your client's config:

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

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.

Works with

Claude Code · Cursor · GitHub Copilot · Codex · Windsurf · OpenCode · VS Code

Any MCP-compatible agent can drive OrangePro. No vendor lock-in.

How it works

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  Your Code  │ ──► │  Knowledge   │ ──► │  Evidence   │
│  (any lang) │     │    Graph     │     │   Tiers     │
└─────────────┘     └──────────────┘     └─────────────┘
                           │
                    ┌──────┴──────┐
                    ▼             ▼
             ┌───────────┐  ┌──────────┐
             │ Gap Report│  │ Generate │
             │ + Risks   │  │  Tests   │
             └───────────┘  └──────────┘

Same code = same score. Deterministic. Always.

Language support

Static mapping works across many languages via tree-sitter. Dynamic proof is deliberately narrower — each language needs a runner, mutation locator, and sandbox profile.

Highest-value local run

Use the repository's own setup and test commands first, and keep unit and integration

coverage in separate artifacts. Then run `opro start`; it performs analysis, ingests

the artifacts, attempts targeted proof, generates report-visible drafts, and writes the

final report. A separate `opro analyze` is unnecessary when `opro start` follows it.

# 1. Install/build exactly as the repository documents.
# 2. Run the repository's unit and integration coverage commands separately.
# 3. Record artifact provenance (example paths and commands):
mkdir -p .orangepro
# create .orangepro/coverage-suites.json using the schema below

opro coverage .                    # optional preflight: discover/generate artifacts
opro start . --proof-limit 5 --generate-limit 20

{
  "artifacts": {
    ".orangepro/coverage/unit.coverprofile": {
      "suite": "unit",
      "command": "make unit-test-coverage"
    },
    ".orangepro/coverage/integration.coverprofile": {
      "suite": "integration",
      "command": "make integration-test-coverage"
    }
  }
}

Without this manifest, OrangePro conservatively infers clear `unit`/`integration` names

and labels everything else `unclassified`; it never guesses that an aggregate profile is

unit-only. The report shows unit, integration, their overlap, unclassified coverage, and

the combined union separately. `--proof-limit` controls dynamic proof attempts (which

may draft a test for proof); `--generate-limit` independently controls the additional

report-visible risk-gap drafting lane. A generation run

also records its terminal status and exact reason, so a compiler/import failure is not

misreported as a generic dependency problem.

Privacy

• No stored source. Reads code in-process. Never uploads to an OrangePro server.
• No existing-source mutation. Never edits your source or test files.
• Your keys stay yours. Read from env at call time, never persisted.
• BYOK is direct. Code context goes to the model provider you configure. OrangePro is not in that path.

CLI reference

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
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 coverage                 # discover/generate artifacts; analyze or start ingests them

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

MCP tools (18 total)

PR workflow

opro generate --base main              # tests for what this branch changed
opro generate --pr 1234                # checks out PR #1234
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 — what failure mode it targets

If dependencies aren't installed, tests are kept as Manual tests (Given/When/Then steps with the blocker named). Install dependencies and re-run to convert them to runnable tests.

Test categories

Generation is evidence-gated. A category is produced only when the graph has supporting evidence.

Model setup (BYOK)

Analysis, scoring, and proof need no model key. Generation does.

Auto-detect order: OpenAI → Ollama → Anthropic. Override with `--provider` and `--model`.

The defaults are `gpt-5.3-codex` for OpenAI and `claude-sonnet-5` for Anthropic.

Run `opro setup` to configure interactively. Keys stay in your environment — never written to graph, config, or artifacts.

AI candidate lanes

With a provider key, OrangePro stages weak AI behavior→symbol links and AI-suggested candidate flows. These are review/generation worklists, not evidence:

• AI links appear as `AI-linked` suggestions.
• AI flows are stored separately from deterministic flows.
• Neither lane changes evidence tiers or denominator counts.

Use them when you want the agent to find likely service-boundary flows faster; ignore them for a deterministic-only report.

What's on the hosted platform

This repo is the free local tool. The OrangePro platform adds:

• Persistent knowledge graph across PRs and repos
• PR/CI policy gates over evidence tiers and risk deltas
• Jira / Confluence / TestRail / OpenAPI enrichment
• Cross-repo intelligence and recurring-flow memory
• Production incident correlation and regression targeting
• Team dashboards and test lifecycle management

Contributing

git clone https://github.com/OrangeproAI/orangepro-mcp.git
cd orangepro-mcp && npm ci && npm run build
npm test

PRs welcome. Please open an issue first for large changes.

MIT License ·