better-code-review-graph 3.5.0

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.

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.

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	5 tools: graph + query + review + config + help
Plugin hooks	Invalid PostEdit/PostGit	Valid PostToolUse

Quick Start

Claude Code Plugin (Recommended)

Via marketplace (includes skills: /refactor-check, /review-delta, /review-pr + hooks):

/plugin marketplace add n24q02m/claude-plugins
/plugin install better-code-review-graph@n24q02m-plugins

Includes hooks (SessionStart auto-build, PostToolUse auto-update). Configure env vars in ~/.claude/settings.local.json or shell profile.

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.better-code-review-graph]
command = "uvx"
args = ["--python", "3.13", "better-code-review-graph"]

MCP Server

Option 1: uvx

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

Other MCP clients (Cursor, Codex, Gemini CLI, Windsurf, Cline, Amp, OpenCode)

// Cursor (~/.cursor/mcp.json)
// Windsurf (~/.codeium/windsurf/mcp_config.json)
// Cline (cline_mcp_settings.json)
// Amp (~/.config/amp/settings.json)
// OpenCode (~/.opencode.json)
{
  "mcpServers": {
    "better-code-review-graph": {
      "command": "uvx",
      "args": ["--python", "3.13", "better-code-review-graph"]
    }
  }
}

# Codex (~/.codex/config.toml)
[mcp_servers.better-code-review-graph]
command = "uvx"
args = ["--python", "3.13", "better-code-review-graph"]

// Gemini CLI (~/.gemini/settings.json)
{
  "mcpServers": {
    "better-code-review-graph": {
      "command": "uvx",
      "args": ["--python", "3.13", "better-code-review-graph"]
    }
  }
}

Option 2: Docker

{
  "mcpServers": {
    "better-code-review-graph": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", ".:/repo:ro", "n24q02m/better-code-review-graph:latest"]
    }
  }
}

Tools

graph -- Graph lifecycle

Actions: build | update | stats | embed

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.

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.

help -- Full documentation

Topics: graph | query | review | config

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

Zero-Config Setup

No environment variables needed. On first start, the server opens a setup page in your browser:

1. Start the server (via plugin, uvx, or Docker)
2. A setup URL appears -- open it in any browser
3. Fill in your credentials on the guided form
4. Credentials are encrypted and stored locally

Your credentials never leave your machine. The relay server only sees encrypted data.

For CI/automation, you can still use environment variables (see below).

Configuration

Variable	Default	Description
EMBEDDING_BACKEND	(auto-detect)	local or cloud. Auto-detects from available API keys.
EMBEDDING_MODEL	(provider default)	Override cloud model name. Provider auto-detected from model prefix.
JINA_AI_API_KEY	-	Jina AI API key (embedding, highest priority).
GEMINI_API_KEY	-	Google Gemini API key (embedding). Also accepts GOOGLE_API_KEY.
OPENAI_API_KEY	-	OpenAI API key (embedding).
COHERE_API_KEY	-	Cohere API key (embedding). Also accepts CO_API_KEY.

Claude Code Plugin Details

When installed as a plugin, you get:

Hooks:

• SessionStart: Auto-builds the code graph when a conversation starts
• PostToolUse: Auto-updates the graph after file modifications (Write, Edit, Bash)

Skills:

• refactor-check: Safety analysis before refactoring -- dependency graph, blast radius
• review-delta: Review uncommitted changes using graph context
• review-pr: Review a pull request with structural analysis

Embedding Backends

Backend	Config	Size	Description
local (default)	Nothing needed	~570 MB (first use)	qwen3-embed ONNX. Zero-config.
cloud	Any supported API key	0 MB	Multi-provider: Jina AI, Gemini, OpenAI, Cohere (priority order).

• Auto-detection: Any supported API key set -> cloud (priority: Jina > Gemini > OpenAI > Cohere). Otherwise -> local ONNX.
• Override: EMBEDDING_BACKEND=local or EMBEDDING_BACKEND=cloud.
• Fixed 768-dim storage: Switching backends does NOT invalidate existing vectors.

Supported Languages

Python, TypeScript, JavaScript, Go, Rust, Java, C#, Ruby, Kotlin, Swift, PHP, C/C++, Solidity

Ignore Files

Create .code-review-graphignore in your project root:

generated/**
*.generated.ts
vendor/**
node_modules/**

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

License

MIT -- See LICENSE.