better-code-review-graph 3.16.2b1

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

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.

Sister projects from n24q02m (click to expand)

Project	Tagline	Tag
better-code-review-graph	Knowledge graph for token-efficient code reviews -- fixed search, configurabl...	MCP
better-email-mcp	IMAP/SMTP email server for AI agents -- 6 composite tools with multi-account ...	MCP
better-godot-mcp	Composite MCP server for Godot Engine -- 17 mega-tools for AI-assisted game d...	MCP
better-notion-mcp	Markdown-first Notion API server for AI agents -- 10 composite tools replacin...	MCP
better-telegram-mcp	MCP server for Telegram with dual-mode support: Bot API (httpx) for quick bot...	MCP
claude-plugins	Full documentation: mcp.n24q02m.com — unified docs for all 8 servers + the mc...	Marketplace
imagine-mcp	Production-grade MCP server for image and video understanding + generation ac...	MCP
jules-task-archiver	Chrome Extension for bulk operations on Jules tasks via batchexecute API -- a...	Tooling
mcp-core	Unified MCP Streamable HTTP 2025-11-25 transport, OAuth 2.1 Authorization Ser...	MCP
mnemo-mcp	Persistent AI memory with hybrid search and embedded sync. Open, free, unlimi...	MCP
qwen3-embed	Lightweight Qwen3 text embedding and reranking via ONNX Runtime and GGUF	Library
skret	Secrets without the server.	CLI
web-core	Shared web infrastructure package for search, scraping, HTTP security, and st...	Library
wet-mcp	Open-source MCP Server for web search, content extraction, library docs & mul...	MCP

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

Feature	code-review-graph	better-code-review-graph
Multi-word search	Broken (literal substring)	AND-logic word splitting
callers_of/callees_of	Empty results (bare name targets)	Qualified name resolution + bare fallback
Embedding	sentence-transformers + torch (1.1 GB)	qwen3-embed ONNX + cloud (200 MB), dual-mode
Output size	Unbounded (500K+ chars)	Paginated (max_results, truncated flag)
Tool design	9 individual tools	6 tools: graph + query + review + config + setup + help
Plugin hooks	Invalid PostEdit/PostGit	Valid PostToolUse

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

Action	Description
build	Full or incremental graph build. Set full_rebuild=true to re-parse all files.
update	Alias for build with full_rebuild=false (incremental).
stats	Graph size, languages, node/edge breakdown, embedding count.
embed	Compute vector embeddings for semantic search. Dual-mode: local ONNX or cloud.
export	Export graph in graphml / json-ld / dot / cypher. Inline or to output_path.
summarize	LLM-generated one-paragraph docstrings for Function nodes (Gemini or OpenAI, cloud opt-in). Cost-capped via max_nodes.

query -- Graph queries

Actions: query | search | impact | large_functions

Action	Description
query	Predefined pattern queries: callers_of, callees_of, imports_of, importers_of, children_of, tests_for, inheritors_of, file_summary.
search	Search code entities by name/keyword or semantic similarity.
impact	Blast radius of changed files. Auto-detects from git diff. Paginated with max_results.
large_functions	Find functions/classes exceeding a line-count threshold.

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

Action	Description
status	Server info: version, graph path, node/edge counts, embedding backend.
set	Update runtime settings (e.g., log_level).
cache_clear	Remove all computed embeddings.

setup -- Credential setup

Actions: status | start | skip | reset | complete

Action	Description
status	Show current credential state and setup URL.
start	Start relay setup to configure API keys via browser.
skip	Set local mode (skip relay permanently, use ONNX only).
reset	Clear credentials and reset state.
complete	Re-resolve credentials from environment variables.

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.

Mode	Storage	Encryption	Who can read your data?
stdio (default)	~/.better-code-review-graph-mcp/config.json	AES-GCM, machine-bound key	Only your OS user (file perm 0600)
HTTP self-host	Same as stdio	Same	Only you (admin = user)

License

MIT -- See LICENSE.