better-code-review-graph

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.

Why Better

All fixes are submitted upstream as standalone PRs (see Upstream PRs). If all are merged, this repo will be archived.

Quick Start

Prerequisites

• Python 3.13 (required -- requires-python = "==3.13.*")

Option 1: uvx (Recommended)

{
  "mcpServers": {
    "better-code-review-graph": {
      "command": "uvx",
      "args": ["--python", "3.13", "better-code-review-graph", "serve"],
      "env": {
        // -- optional: cloud embeddings via LiteLLM
        // "API_KEYS": "GOOGLE_API_KEY:AIza...",
        // -- optional: LiteLLM Proxy (selfhosted gateway)
        // "LITELLM_PROXY_URL": "http://10.0.0.20:4000",
        // "LITELLM_PROXY_KEY": "sk-your-virtual-key"
        // -- without API_KEYS, uses built-in local qwen3-embed ONNX (zero-config)
      }
    }
  }
}

Option 2: pip

pip install better-code-review-graph
better-code-review-graph install   # creates .mcp.json in project root

Option 3: Docker

{
  "mcpServers": {
    "better-code-review-graph": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "crg-data:/data",
        "-e", "API_KEYS",
        "n24q02m/better-code-review-graph:latest"
      ],
      "env": {
        // -- optional: cloud embeddings
        // "API_KEYS": "GOOGLE_API_KEY:AIza..."
      }
    }
  }
}

Option 4: Claude Code Plugin

claude plugin install n24q02m/better-code-review-graph@better-code-review-graph

Then open your project and tell Claude:

Build the code review graph for this project

MCP Tools

Claude uses these automatically once the graph is built.

Embedding Backends

Embeddings enable semantic search (vector similarity instead of keyword matching). Two backends are available:

• Auto-detection: If API_KEYS or LITELLM_PROXY_URL is set, uses LiteLLM. Otherwise, uses local ONNX.
• Override: Set EMBEDDING_BACKEND=local or EMBEDDING_BACKEND=litellm explicitly.
• Fixed 768-dim storage: All embeddings stored at 768 dimensions via MRL truncation. Switching backends does NOT invalidate existing vectors.
• Lazy loading: Model downloads on first embed call, not on server start.

CLI Reference

better-code-review-graph install     # Register MCP server with Claude Code (creates .mcp.json)
better-code-review-graph init        # Alias for install
better-code-review-graph build       # Full graph build (parse all files)
better-code-review-graph update      # Incremental update (changed files only)
better-code-review-graph watch       # Auto-update on file changes
better-code-review-graph status      # Show graph statistics
better-code-review-graph serve       # Start MCP server (stdio transport)

Configuration

Ignore files

Create .code-review-graphignore in your project root to exclude paths:

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

Supported Languages

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

Each language has full Tree-sitter grammar support for functions, classes, imports, call sites, inheritance, and test detection.

Cross-Agent Compatibility

Upstream PRs

All fixes in this fork are submitted as standalone PRs to the original code-review-graph:

• #37 -- Multi-word search AND logic
• #38 -- Parser call target resolution (fixes #20)
• #39 -- Impact radius output pagination

If all upstream PRs are merged, this repository will be archived.

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 serve

Requirements: Python 3.13 (not 3.14+), uv

Compatible With

Also by n24q02m

License

MIT - See LICENSE