Better Code Review Graph

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

Knowledge graph for token-efficient code reviews -- fixed search, configurable embeddings, qualified call resolution.

Table of contents

• Features

• Status

• Documentation

• Tools

• Security

• Build from Source

• Trust Model

• License

Fork of code-review-graph with critical bug fixes, configurable embeddings, and production CI/CD. 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.

v2.0 migration (BREAKING)

See BREAKING_CHANGES.md for the full schema-change list, behavior-change summary, environment requirements, and rollback procedure.

This release 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 if needed.

To downgrade and restore the pre-2.0 backup:

CRG_DOWNGRADE_TO_1_X=1 uv run better-code-review-graph

The backup is created the first time alembic crosses the breaking boundary (revision 005_temporal_columns); subsequent runs reuse the existing backup file. After a downgrade the v2-state DB is preserved at <graph_db>.post-2.0.archived so you can forward-roll again later.

What you get on v2.0+:

• Temporal queries -- query/search/impact accept as_of=<sha> for snapshot semantics; query(action="diff", from_sha=X, to_sha=Y) returns {added, removed, modified} buckets driven entirely by the temporal columns (no re-parse). See help(topic="query").

• Refactor auditing -- review(action="delta", show_line_shifts=true, ...) surfaces symbols whose line_start moved between two commits.

• Security scanning -- security(action="scan", ...) runs a regex-based Tier-1 scanner (5 rules) by default; pass engine="semgrep" (after uv add 'better-code-review-graph[security]') for the ~120-rule Tier-2 overlay. Findings persist on nodes.security_tags; report re-emits the cache as JSON or SARIF v2.1.0. See help(topic="security").

What's new in v1.6

• LLM-generated summaries -- graph(action="summarize") writes a one-paragraph docstring for each Function node via Gemini or OpenAI (cloud opt-in, no key = no-op). Run it after graph(action="update") to lift semantic-search recall by ~15% on repos with terse function names.

• Graph export in 4 formats -- graph(action="export", format=...) emits graphml (Gephi/Cytoscape), json-ld, dot (Graphviz), or cypher (Neo4j replay). Inline by default; pass output_path to write to disk.

• Source text capture -- Function nodes now persist their raw source so summaries can be regenerated whenever an edit changes the body. The cache key is sha256(source_text):provider; unchanged nodes cost zero LLM calls on re-run.

• Cost cap on summaries -- max_nodes (default 500) caps LLM calls per invocation; pair with cron / update cadence for predictable spend.

• Phase 1 quality wins (also new in this train): query(action="spot_check") for random callsite snippets, query(action="renamed_in_diff") for shifted callsites, dynamic-dispatch hints in callers_of results, a dedicated recipes help topic, and embeddings_count exposed in graph(action="stats").

Example -- after pulling new functions in, refresh embeddings with summaries:

graph(action="update")
graph(action="summarize", max_nodes=200)
graph(action="embed")

Features

Status

2026-05-02 -- Architecture stabilization update

Past months saw significant churn around credential handling and the daemon-bridge auto-spawn pattern. This caused multi-process races, browser tab spam, and inconsistent setup UX across plugins. As of v, the architecture is stable: 2 clean modes (stdio + HTTP), no daemon-bridge layer, no auto-spawn from stdio.

Apologies for the instability period. If you encountered issues with prior versions, please update to v+ and follow the current docs/setup-manual.md -- most prior workarounds are no longer needed.

Related plugins from the same author:

• wet-mcp -- Web search + content extraction

• mnemo-mcp -- Persistent AI memory

• imagine-mcp -- Image/video understanding + generation

• better-notion-mcp -- Notion API

• better-email-mcp -- Email management

• better-telegram-mcp -- Telegram

• better-godot-mcp -- Godot Engine

All plugins share the same architecture -- install once, learn pattern transfers.

Documentation

Full docs at mcp.n24q02m.com/servers/better-code-review-graph/:

• 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

Install with 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

Tools

graph -- Graph lifecycle

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

query -- Graph queries

Actions: query | search | impact | large_functions

review -- Code review context

Token-optimized review context with structural summary, source snippets, and review guidance. Auto-detects changed files from git diff.

config -- Server configuration

Actions: status | set | cache_clear

setup -- Credential setup

Actions: status | start | skip | reset | complete

help -- Full documentation

Topics: graph | query | review | config

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

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 repo as :ro (read-only)

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 mcp-core/docs/TRUST-MODEL.md for full classification.

License

MIT -- See LICENSE.