Better Code Review Graph

Better Code Review Graph

Renamed (2026-09-13): repo is now crg — CLI-first (crg command). PyPI package stays better-code-review-graph; MCP server is a secondary surface.

mcp-name: io.github.n24q02m/better-code-review-graph

Knowledge graph for token-efficient code reviews -- semantic search and call-graph resolution across your codebase.

An MCP server that parses your codebase with Tree-sitter, builds a structural graph of functions/classes/imports, and gives Claude (or any MCP client) precise context so it reads only what matters instead of the whole tree. Semantic search runs through the local ONNX model registry from fastretrieval by default (zero config, no API key), with an optional cloud embedding chain. Fork of code-review-graph with fixed multi-word search, qualified call resolution, dual-mode embeddings, output pagination, and production CI/CD.

v2.0 migration (BREAKING)

v2.0 adds temporal columns (valid_from_sha / valid_to_sha on every node + edge) and an opt-in security scanner. The schema migration is auto-applied on first GraphStore open, and a backup of the pre-2.0 DB is saved to <graph_db>.pre-2.0.bak so you can roll back. See BREAKING_CHANGES.md for the full schema-change list, behavior changes, environment requirements, and the downgrade procedure (CRG_DOWNGRADE_TO_1_X=1 uv run better-code-review-graph).

Table of contents

• v2.0 migration (BREAKING)
• Install
• Smithery
• Configuration
• Tools
• CLI
• Features
• Comparison
• Security
• Build from source
• Trust model
• Migration & changelog
• Documentation
• License

Install

For OMP and other local coding harnesses, the primary surface is the package CLIplus the bundled skills/ workflows. The skills invoke the CLI directly and donot require an MCP server mapping.

# Run without a persistent install (short `crg` script; PyPI package name stays
# better-code-review-graph, so `uvx` needs the explicit --from form)
uvx --python 3.13 --from better-code-review-graph crg graph build --full-rebuild \
  --repo-root /path/to/repo
uvx --python 3.13 --from better-code-review-graph crg graph stats \
  --repo-root /path/to/repo

# Or install the console scripts (installs both `crg` and the legacy long name)
pip install better-code-review-graph
crg query search --search-query "authentication" \
  --repo-root /path/to/repo

The optional Semgrep engine for deeper security scans is a separate extra:

pip install 'better-code-review-graph[security]'

MCP stdio remains a secondary protocol adapter for clients that require it:

{
  "mcpServers": {
    "better-code-review-graph": {
      "command": "uvx",
      "args": ["--python", "3.13", "better-code-review-graph"],
      "env": { "MCP_TRANSPORT": "stdio" }
    }
  }
}

Install matrix (stdio unless noted; the CLI-first usage above stays the primary surface):

Install with an AI agent -- paste this to your AI coding agent:

Install MCP server better-code-review-graph following the steps athttps://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-code-review-graph/setup-with-agent.md

Full CLI usage is in CLI. Optional per-client MCP setup is atmcp.n24q02m.com/servers/better-code-review-graph/setup/.

Local-first boundary

CRG is local-first for coding workflows:

• CLI and bundled Skills are the primary surfaces for graph build/query,impact analysis, review context, security scans, and repository onboarding.
• MCP stdio is the secondary protocol adapter over the same local domainservices; it does not maintain a separate graph implementation.
• Graph state stays in <repo>/.better-code-review-graph/graph.db unless an explicitmulti-user/self-host configuration selects another data directory.
• PyPI, CI, security scanning, GitHub releases, and eligible stable MCP Registrypublication remain active. Historical public OCI tags are retained, but newpublic Docker Hub/GHCR images are no longer published.
• CRG has no hosted Cloudflare runtime in the target topology.

Smithery

The repo ships a smithery.yaml so the server can be built andrun through Smithery. It deploys over stdio and needsno startup configuration -- the config schema is empty, and any optional cloudembedding/summary keys are supplied at runtime through the server's own configflow (see Configuration below). The launch command is the sameuvx invocation as a local install:

startCommand:
  type: stdio
  commandFunction: |-
    (config) => ({ command: 'uvx', args: ['--python', '3.13', 'better-code-review-graph'] })

Configuration

Everything works out of the box with zero configuration -- semantic searchuses the local ONNX registry from fastretrieval(Qwen3-Embedding-0.6B is the current built-in reference entry, ~570 MBdownloaded on first graph embed). This reference entry is not a Qwen-onlyboundary: any built-in registry ID or valid non-Qwen artifact manifest followsthe same resolver. All environment variables below are optional and only neededfor cloud embeddings, LLM summaries, or an explicit BYO local artifact.

Model selection

Embeddings select the first provider/model entry in EMBEDDING_MODELS; laterentries are retained as configuration but are not runtime fallbacks. Summariesselect the first SUMMARY_MODELS entry too, without runtime fallback. Providersare inferred from model prefixes and use the matching <PROVIDER>_API_KEY.

Cohere embed-v4.0 requests and stores 1024 dimensions; other backends retain768-dimensional storage. CRG never slices, pads, or silently accepts a differentprovider width. The embedding row's model and byte width must match before reuse.Run graph(action="embed") after changing models or upgrading an old 768-wideCohere index. Searches reject incompatible widths before a provider call; graphnodes are retained and re-embedding replaces only stale vectors.

Provider API keys

Cloud models need the provider key for the selected model prefix. Keys alonenever select models: an empty embedding chain stays local, and an empty summarychain stays disabled. A configured cloud error does not fall back to local oranother provider. Summarizers require a chat-completion model.

Any other litellm provider works viaits standard <PROVIDER>_API_KEY.

Advanced

When LOCAL_RERANK_MODEL is configured, semantic vector search retrieves abounded candidate pool of min(max(limit * 4, limit), 100) rows, applies theexisting kind, repo, and live-row filters, then reranks that pool and returnsat most limit rows. The response uses search_mode="semantic_reranked" andadds rerank_score while preserving similarity_score. Blank keeps theexisting limit * 2 vector path and search_mode="semantic". Configuredreranker failures return an explicit error; CRG does not silently fall back tovector or keyword results. Keyword searches, including as_of snapshots, donot invoke the reranker.

Example -- cloud embeddings + summaries

{
  "mcpServers": {
    "better-code-review-graph": {
      "command": "uvx",
      "args": ["--python", "3.13", "better-code-review-graph"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "EMBEDDING_MODELS": "cohere/embed-v4.0",
        "SUMMARY_MODELS": "openrouter/minimax/minimax-m3:free",
        "EMBEDDING_API_BASE": "https://gateway.ai.cloudflare.com/v1/<account>/<gateway>/cohere/v2/embed",
        "LLM_API_BASE": "https://gateway.ai.cloudflare.com/v1/<account>/<gateway>/openrouter/v1",
        "COHERE_API_KEY": "<cohere-key>",
        "OPENROUTER_API_KEY": "<openrouter-key>"
      }
    }
  }
}

Cohere embedding is paid. Authorize a bounded budget before a live index/query;the Minimax-free completion choice does not make embeddings free. This exampledoes not add a process-wide model override: in remote mode each authenticatedsubject's relay record supplies its models, endpoints and keys. Missing subjectcredentials fail closed rather than inheriting the server environment.

CRG currently has no cloud rerank call: LOCAL_RERANK_MODEL is its onlyreranking path. Setting RERANK_MODELS or RERANK_API_BASE does not enable one.

You can also configure cloud keys interactively in HTTP mode via the relaysetup form (config(action="setup_start") returns the browser URL). See themodes overview andmulti-user setup.

Workspace username (HTTP setup form)

The relay setup form has an optional workspace username field. Entering thesame username always lands you in the same per-sub bucket, so your keys andgraph stay reachable across a re-authorization and across devices, instead ofbeing tied to the one-off subject minted for each /authorize round-trip.Leaving it blank keeps the previous per-authorize behaviour.

Trust boundary: when the form is gated by a shared MCP_RELAY_PASSWORD, theusername is a partition key, not a secret -- anyone who knows that password cantype any username and reach that bucket. That is fine for a trusted group; anuntrusted multi-tenant deployment needs a per-user secret or delegated OAuthinstead.

One-time migration: existing users must re-enter their credentials once afterthis change. Nothing is deleted; credentials stored under the old random subjectare simply no longer addressed.

Tools

Seven tools, each grouping related actions to keep the tool surface small.

graph -- Graph lifecycle

Actions: build | update | stats | embed | export | summarize

query -- Graph queries

Actions: query | search | impact | large_functions | spot_check | renamed_in_diff | diff

Most read actions accept as_of=<sha> for temporal (point-in-time) snapshotsand repo=<repo_id> to scope a federated multi-repo graph.

review -- Code review context

Actions: context (default) | delta

Token-optimized review context with structural summary, impacted nodes, sourcesnippets, and review guidance. context auto-detects changed files from thegit diff; delta (with from_sha/to_sha, optional show_line_shifts)surfaces refactor moves between two commits.

config -- Server configuration and credential setup

Actions: status | set | cache_clear | setup_status | setup_start | setup_skip | setup_reset | setup_complete

security -- Security scanning

Actions: scan | report | suppress | rule_list

The semgrep engine requires the [security] extra and runs Semgrep'sp/auto registry pack plus a 3-rule curated overlay.

help -- Full documentation

Topics: graph | query | review | config | security | recipes

Returns complete documentation for each tool. Use when the compresseddescriptions above are insufficient.

config__open_relay -- Re-trigger the relay setup form

Registered automatically from mcp-core.In HTTP mode it returns <PUBLIC_URL>/authorize so the agent can re-open thebrowser setup form (e.g. after credential expiry); in stdio mode it returnsstatus: 'stdio_unsupported'.

CLI

The package installs two console scripts: crg (primary) andbetter-code-review-graph (legacy long name). Running either with noarguments starts the MCP server over stdio; a leading positional argumentroutes to a local CLI subcommand that calls the same domain services used bythe MCP adapter. Run them directly after pip install, or without apersistent install via uvx --python 3.13 --from better-code-review-graph crg ....

# Start the MCP server over stdio (default -- no subcommand)
crg

# Build, inspect, and embed the local graph
crg graph build
crg graph stats
crg graph embed

# Query relationships and impact
crg query query \
  --pattern callers_of --target "path/to/module.py::function"
crg query search --search-query "authentication"
crg query impact --changed-files src/app.py

# Produce review context and run a local security scan
crg review context --base HEAD~1
crg security scan --engine heuristic

CLI subcommands print structured JSON and exit non-zero on an error. Theconfig, doctor, and relay subcommands come from shared mcp-core.

Features

What this fork fixes versus the upstream code-review-graph:

Comparison

How better-code-review-graph stacks up against direct competitors in each pillar:

Sources: Greptile · Greptile pricing · Sourcegraph MCP · CodeGraph. Cells marked ? are capabilities the competitor does not publicly document, not confirmed absences.

Security

• Explicit selection -- Cloud embedding errors are reported; the runtime does not silently switch models or fall back to local ONNX.
• Error handling -- Tools return error strings with fix suggestions, never crash.
• Read-only mount -- Docker mode mounts the repo as :ro (read-only).
• SSRF-guarded endpoints -- Custom EMBEDDING_API_BASE / LLM_API_BASE URLs are validated before any outbound call.

To report a vulnerability, see SECURITY.md.

Build from source

git clone https://github.com/n24q02m/crg
cd better-code-review-graph
uv sync --group dev
uv run pytest
uv run better-code-review-graph

Requirements: Python 3.13, uv.

Trust model

This plugin implements TC-Local (machine-bound, single trust principal). See the mcp-core trust model for full classification.

Migration & changelog

Graph, security scan cache, and suppression state now use the package-owned.better-code-review-graph/ directory. Run graph(action="build", full_rebuild=true)once after upgrading, followed by graph(action="embed") if semantic search isneeded. The ambiguous old .code-review-graph/ and .code-review-graph.db pathsand their SQLite sidecars are left untouched: they may belong to the separateupstream package. Review and reapply any desired suppression rules explicitly.

The v2.0 release added temporal columns (valid_from_sha / valid_to_shaon every node and edge) plus an opt-in security scanner. The schema migrationis auto-applied on first GraphStore open, and a backup of the pre-2.0 DB iswritten to <graph_db>.pre-2.0.bak. To downgrade and restore it:

CRG_DOWNGRADE_TO_1_X=1 uvx better-code-review-graph

Full schema-change list, behavior changes, and rollback procedure:BREAKING_CHANGES.md. Release-by-release history:CHANGELOG.md.

Documentation

Full docs atmcp.n24q02m.com/servers/better-code-review-graph/setup/:

• Setup -- install methods for Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json
• Modes overview -- stdio / local-relay / remote-relay / remote-oauth
• Multi-user setup -- per-JWT-sub credential model

Use the help tool from any MCP client for inline per-tool reference.

License

Apache-2.0 -- See LICENSE.