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.

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 on a local ONNX embedding model 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).

Related MCP server: SocratiCode

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

The server runs over stdio by default and works with any MCP client. The recommended launcher is uvx (no install step -- it fetches and runs the published package in an isolated environment):

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

Or install it as a Python package:

uvx better-code-review-graph        # run without installing
pip install better-code-review-graph

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

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

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

Install MCP server 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 per-client setup (Claude Code, Codex, Gemini CLI, Cursor, Windsurf, raw mcp.json) is at mcp.n24q02m.com/servers/better-code-review-graph/setup/.

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 a local qwen3-embed ONNX model (Qwen3-Embedding-0.6B, ~570 MB downloaded on first graph embed). All environment variables below are optional and only needed for cloud embeddings or LLM summaries.

Model chains

Embeddings and summaries are each driven by an ordered model chain -- a CSV of provider/model entries where the order is the litellm fallback order (first entry is the active model). The provider is inferred from the model prefix, so the matching <PROVIDER>_API_KEY is all you need to add.

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 <PROVIDER>_API_KEY.

Advanced

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=<sha> for temporal (point-in-time) snapshots and 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, 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 <PUBLIC_URL>/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 (this is what an MCP client launches). A leading positional argument routes to a subcommand instead -- handy for building or embedding the graph directly from a shell or CI step, before any MCP client connects. 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 (or incrementally update) the graph for the current repo
uvx better-code-review-graph graph build

# Full re-parse of every file instead of a git-diff incremental
uvx better-code-review-graph graph build --full-rebuild

# Compute embeddings for semantic search (local ONNX by default)
uvx better-code-review-graph graph embed

The graph build and graph embed subcommands print a JSON result and exit non-zero on error. The config, doctor, and relay subcommands come from the shared mcp-core CLI.

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

• Graceful fallbacks -- Cloud embedding failure falls 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 <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 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

MIT -- See LICENSE.