Better Code Review Graph

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.

Sister projects from n24q02m (click to expand)

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 `.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 CLI

plus the bundled `skills/` workflows. The skills invoke the CLI directly and do

not require an MCP server mapping.

# Run without a persistent install
uvx --python 3.13 better-code-review-graph graph build --full-rebuild \
  --repo-root /path/to/repo
uvx --python 3.13 better-code-review-graph graph stats \
  --repo-root /path/to/repo

# Or install the console script
pip install better-code-review-graph
better-code-review-graph 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 with an AI agent -- paste this to your AI coding agent:

> Install `better-code-review-graph` following the steps at

> https://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 at

**mcp.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 domain

services; it does not maintain a separate graph implementation.

• Graph state stays in `/.code-review-graph/graph.db` unless an explicit

multi-user/self-host configuration selects another data directory.

• PyPI, CI, security scanning, GitHub releases, and eligible stable MCP Registry

publication remain active. Historical public OCI tags are retained, but new

public 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 and

run through Smithery. It deploys over stdio and needs

no startup configuration -- the config schema is empty, and any optional cloud

embedding/summary keys are supplied at runtime through the server's own config

flow (see Configuration below). The launch command is the same

`uvx` 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 search

uses the local ONNX registry from fastretrieval

(`Qwen3-Embedding-0.6B` is the current built-in reference entry, ~570 MB

downloaded on first `graph embed`). This reference entry is not a Qwen-only

boundary: any built-in registry ID or valid non-Qwen artifact manifest follows

the same resolver. All environment variables below are optional and only needed

for cloud embeddings, LLM summaries, or an explicit BYO local artifact.

Model selection

Embeddings select the first `provider/model` entry in `EMBEDDING_MODELS`; later

entries are retained as configuration but are not runtime fallbacks. Summaries

use their ordered `SUMMARY_MODELS` chain. Providers are inferred from model

prefixes and use the matching `_API_KEY`.

All vectors are stored at a fixed 768 dimensions (MRL truncation), so the

embeddings table schema stays valid across providers. Switching embedding

*model* changes the vector space; embeddings are tracked per provider and a

provider switch triggers re-embedding rather than mixing incomparable vectors.

Provider API keys

Cloud models need the provider key for whatever prefixes appear in your chains.

Without any cloud key the server stays on local ONNX. Summarizers must expose a

chat-completion API (so Jina and Cohere are embedding-only).

Any other litellm provider works via

its standard `_API_KEY`.

Advanced

When `LOCAL_RERANK_MODEL` is configured, semantic vector search retrieves a

bounded candidate pool of `min(max(limit * 4, limit), 100)` rows, applies the

existing `kind`, `repo`, and live-row filters, then reranks that pool and returns

at most `limit` rows. The response uses `search_mode="semantic_reranked"` and

adds `rerank_score` while preserving `similarity_score`. Blank keeps the

existing `limit * 2` vector path and `search_mode="semantic"`. Configured

reranker failures return an explicit error; CRG does not silently fall back to

vector or keyword results. Keyword searches, including `as_of` snapshots, do

not 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": "jina_ai/jina-embeddings-v5-text-small,gemini/gemini-embedding-001",
        "SUMMARY_MODELS": "gemini/gemini-2.5-flash",
        "JINA_AI_API_KEY": "jina_...",
        "GEMINI_API_KEY": "AIza..."
      }
    }
  }
}

You can also configure cloud keys interactively in HTTP mode via the relay

setup form (`config(action="setup_start")` returns the browser URL). See the

modes overview and

multi-user setup.

Workspace username (HTTP setup form)

The relay setup form has an optional workspace username field. Entering the

same username always lands you in the same per-`sub` bucket, so your keys and

graph stay reachable across a re-authorization and across devices, instead of

being 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`, the

username is a partition key, not a secret -- anyone who knows that password can

type any username and reach that bucket. That is fine for a trusted group; an

untrusted multi-tenant deployment needs a per-user secret or delegated OAuth

instead.

One-time migration: existing users must re-enter their credentials once after

this change. Nothing is deleted; credentials stored under the old random subject

are 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=` for temporal (point-in-time) snapshots

and `repo=` to scope a federated multi-repo graph.

`review` -- Code review context

Actions: `context` (default) | `delta`

Token-optimized review context with structural summary, impacted nodes, source

snippets, and review guidance. `context` auto-detects changed files from the

git 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's

`p/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 compressed

descriptions above are insufficient.

`config__open_relay` -- Re-trigger the relay setup form

Registered automatically from mcp-core.

In HTTP mode it returns `/authorize` so the agent can re-open the

browser setup form (e.g. after credential expiry); in stdio mode it returns

`status: 'stdio_unsupported'`.

CLI

Running `better-code-review-graph` with no arguments starts the MCP server

over stdio. A leading positional argument routes to a local CLI subcommand

that calls the same domain services used by the MCP adapter. Run these with

`uvx` (or `uv run` from a source checkout):

# Start the MCP server over stdio (default -- no subcommand)
uvx better-code-review-graph

# Build, inspect, and embed the local graph
uvx better-code-review-graph graph build
uvx better-code-review-graph graph stats
uvx better-code-review-graph graph embed

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

# Produce review context and run a local security scan
uvx better-code-review-graph review context --base HEAD~1
uvx better-code-review-graph security scan --engine heuristic

CLI subcommands print structured JSON and exit non-zero on an error. The

`config`, `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/better-code-review-graph
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

The v2.0 release added temporal columns (`valid_from_sha` / `valid_to_sha`

on every node and edge) plus 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

written to `.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 at

**mcp.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.