Crg

Better Code Review Graph

> Renamed (2026-09-13): repo is now crg — CLI-first (crg command). PyPI package stays better-code-review-graph; MCP server is a secondary surface.

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.

[](https://mcp.n24q02m.com/get-started/modes-overview/) [](https://github.com/n24q02m/crg/actions/workflows/ci.yml) [](https://codecov.io/gh/n24q02m/better-code-review-graph) [](https://pypi.org/project/better-code-review-graph/) [](LICENSE)

[](#) [](#) [](https://github.com/python-semantic-release/python-semantic-release) [](https://developer.mend.io/)

Sister projects from n24q02m (click to expand)

| Project | Tagline | Tag | |---|---|---| | agent-chat-plugin | Peer AI agents chat in a shared folder — no human relay, no orchestrator, wor... | Tooling | | better-code-review-graph | Knowledge graph for token-efficient code reviews -- semantic search and call-... | MCP | | better-drive | 2-way Google Drive sync with .driveignore filter — rclone engine, Windows tray | Tooling | | better-email-mcp | IMAP/SMTP email for AI agents -- read, send, organize folders, and manage att... | MCP | | better-godot-mcp | Composite MCP server for Godot Engine -- 17 composite tools for AI-assisted g... | MCP | | better-notion-mcp | Markdown-first Notion for AI agents -- pages, databases, blocks, and comments... | MCP | | better-semantic-release | Drop-in python-semantic-release fork with built-in release-safety guards (orp... | Tooling | | better-telegram-mcp | Telegram for AI agents -- messages, chats, media, and contacts across both bo... | MCP | | better-workspace-mcp | Google Workspace MCP server (Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch... | MCP | | claude-plugins | Claude Code plugin marketplace for the n24q02m MCP servers -- install web sea... | Marketplace | | imagine-mcp | Image and video understanding + generation for AI agents -- across Gemini, Op... | MCP | | jules-task-archiver | Chrome Extension for bulk operations on Jules tasks via batchexecute API -- a... | Tooling | | mcp-core | Shared foundation for building MCP servers -- Streamable HTTP transport, OAut... | MCP | | mnemo-mcp | Persistent AI memory with hybrid search and embedded sync. Open, free, unlimi... | MCP | | fastretrieval | Fast multi-model retrieval runtime for ONNX and GGUF embeddings, reranking, and model contracts | Library | | skret | Secrets without the server. | CLI | | tacet | A self-distilling neuro-symbolic cascade that amortises LLM cost across knowl... | Tooling | | web-core | Shared web infrastructure package for search, scraping, HTTP security, and st... | Library | | wet-mcp | Open-source MCP server for AI agents: web search, content extraction, and lib... | MCP |

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 through the local ONNX model registry from fastretrieval 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 .pre-2.0.bak so you can roll back. See [BREAKINGCHANGES.md](BREAKINGCHANGES.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).

Table of contents

• [v2.0 migration (BREAKING)](#v20-migration-breaking)
• [Install](#install)
• [Smithery](#smithery)
• [Configuration](#configuration)
• [Tools](#tools)
• [CLI](#cli)
• [Features](#features)
• [Comparison](#comparison)
• [Security](#security)
• [Build from source](#build-from-source)
• [Trust model](#trust-model)
• [Migration & changelog](#migration--changelog)
• [Documentation](#documentation)
• [License](#license)

Install

For OMP and other local coding harnesses, the primary surface is the package CLI plus the bundled skills/ workflows. The skills invoke the CLI directly and do not require an MCP server mapping.

# Run without a persistent install
uvx --python 3.13 better-code-review-graph graph build --full-rebuild \
  --repo-root /path/to/repo
uvx --python 3.13 better-code-review-graph graph stats \
  --repo-root /path/to/repo

# Or install the console script
pip install better-code-review-graph
better-code-review-graph query search --search-query "authentication" \
  --repo-root /path/to/repo

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

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

MCP stdio remains a secondary protocol adapter for clients that require it:

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

Install matrix (stdio unless noted; the CLI-first usage above stays the primary surface):

| Client | Install | |---|---| | Claude Code (plugin) | /plugin marketplace add n24q02m/claude-plugins then /plugin install better-code-review-graph@n24q02m-plugins | | Claude Code (stdio) | claude mcp add better-code-review-graph -- uvx --python 3.13 better-code-review-graph | | Codex | register stdio command uvx --python 3.13 better-code-review-graph under mcp_servers in ~/.codex/config.toml | | Gemini CLI | add the mcpServers JSON above to ~/.gemini/settings.json | | Cursor / Windsurf | add the mcpServers JSON above via the client's MCP settings (mcp.json) | | Any client (HTTP self-host) | point the client at https:///mcp (MCP_TRANSPORT=http) -- self-host only, no hosted endpoint |

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 CLI usage is in [CLI](#cli). Optional per-client MCP setup is at mcp.n24q02m.com/servers/better-code-review-graph/setup/.

Local-first boundary

CRG is local-first for coding workflows:

• CLI and bundled Skills are the primary surfaces for graph build/query,

impact analysis, review context, security scans, and repository onboarding.

• MCP stdio is the secondary protocol adapter over the same local domain

services; it does not maintain a separate graph implementation.

• Graph state stays in /.better-code-review-graph/graph.db unless an explicit

multi-user/self-host configuration selects another data directory.

• PyPI, CI, security scanning, GitHub releases, and eligible stable MCP Registry

publication remain active. Historical public OCI tags are retained, but new public Docker Hub/GHCR images are no longer published.

• CRG has no hosted Cloudflare runtime in the target topology.

Smithery

The repo ships a [smithery.yaml](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](#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 the local ONNX registry from fastretrieval (Qwen3-Embedding-0.6B is the current built-in reference entry, ~570 MB downloaded on first graph embed). This reference entry is not a Qwen-only boundary: any built-in registry ID or valid non-Qwen artifact manifest follows the same resolver. All environment variables below are optional and only needed for cloud embeddings, LLM summaries, or an explicit BYO local artifact.

Model selection

Embeddings select the first provider/model entry in EMBEDDING_MODELS; later entries are retained as configuration but are not runtime fallbacks. Summaries select the first SUMMARY_MODELS entry too, without runtime fallback. Providers are inferred from model prefixes and use the matching _API_KEY.

| Variable | Purpose | Empty (default) | |---|---|---| | EMBEDDING_MODELS | Cloud embedding selection; the first entry is active | Local fastretrieval registry | | SUMMARY_MODELS | Completion model selection for graph(action="summarize") | Summaries disabled |

Cohere embed-v4.0 requests and stores 1024 dimensions; other backends retain 768-dimensional storage. CRG never slices, pads, or silently accepts a different provider width. The embedding row's model and byte width must match before reuse. Run graph(action="embed") after changing models or upgrading an old 768-wide Cohere index. Searches reject incompatible widths before a provider call; graph nodes are retained and re-embedding replaces only stale vectors.

Provider API keys

Cloud models need the provider key for the selected model prefix. Keys alone never select models: an empty embedding chain stays local, and an empty summary chain stays disabled. A configured cloud error does not fall back to local or another provider. Summarizers require a chat-completion model.

| Model prefix | API key env var | Get a key | |---|---|---| | jina_ai/ | JINA_AI_API_KEY | | | gemini/ | GEMINI_API_KEY (or GOOGLE_API_KEY) | | | openai/ (or bare text-embedding-*) | OPENAI_API_KEY | | | cohere/ | COHERE_API_KEY | | | openrouter/ | OPENROUTER_API_KEY | | | vertex_express/ | GOOGLE_VERTEX_EXPRESS_API_KEY | |

Any other litellm provider works via its standard _API_KEY.

Advanced

| Variable | Purpose | |---|---| | EMBEDDING_API_BASE | Provider-compatible endpoint for cloud embedding, including CF AI Gateway (SSRF-guarded) | | LLM_API_BASE | Provider-compatible base URL for the summarizer, including CF AI Gateway (SSRF-guarded) | | DISABLE_LOCAL_EMBED | Skip the local ONNX download; embedding is unavailable unless a cloud chain is configured | | LOCAL_EMBEDDING_MODEL | Built-in fastretrieval model ID, or a local directory containing fastretrieval-manifest.json | Built-in default | | LOCAL_RERANK_MODEL | Fastretrieval TextCrossEncoder model ID for bounded semantic reranking | Blank (disabled) | | LOCAL_EMBEDDING_DIM | Required dimension for an external model ID without a manifest | 0 | | LOCAL_EMBEDDING_MODEL_FILE | ONNX file path inside a manifest-backed artifact directory | onnx/model.onnx | | LOCAL_EMBEDDING_POOLING | Explicit pooling for an external ID without a manifest: CLS, MEAN, LAST_TOKEN, or DISABLED | MEAN | | LOCAL_EMBEDDING_NORMALIZE | Explicit L2 normalization for an external ID without a manifest | true | | CRG_DATA_DIR | Override the per-user data directory (default ~/.crg) used for per-user graphs and credentials in HTTP multi-user mode | | EMBEDDING_BACKEND / EMBEDDING_MODEL / SUMMARY_MODEL | Deprecated singular vars, honored one release with a warning -- migrate to the *_MODELS chains |

When LOCAL_RERANK_MODEL is configured, semantic vector search retrieves a bounded candidate pool of min(max(limit * 4, limit), 100) rows, applies the existing kind, repo, and live-row filters, then reranks that pool and returns at most limit rows. The response uses search_mode="semantic_reranked" and adds rerank_score while preserving similarity_score. Blank keeps the existing limit * 2 vector path and search_mode="semantic". Configured reranker failures return an explicit error; CRG does not silently fall back to vector or keyword results. Keyword searches, including as_of snapshots, do not invoke the reranker.

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": "cohere/embed-v4.0",
        "SUMMARY_MODELS": "openrouter/minimax/minimax-m3:free",
        "EMBEDDING_API_BASE": "https://gateway.ai.cloudflare.com/v1///cohere/v2/embed",
        "LLM_API_BASE": "https://gateway.ai.cloudflare.com/v1///openrouter/v1",
        "COHERE_API_KEY": "",
        "OPENROUTER_API_KEY": ""
      }
    }
  }
}

Cohere embedding is paid. Authorize a bounded budget before a live index/query; the Minimax-free completion choice does not make embeddings free. This example does not add a process-wide model override: in remote mode each authenticated subject's relay record supplies its models, endpoints and keys. Missing subject credentials fail closed rather than inheriting the server environment.

CRG currently has no cloud rerank call: LOCAL_RERANK_MODEL is its only reranking path. Setting RERANK_MODELS or RERANK_API_BASE does not enable one.

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 l

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: n24q02m
• Source: n24q02m/crg
• License: Apache-2.0
• Homepage: https://mcp.n24q02m.com/servers/better-code-review-graph/

Install and usage instructions live in the source repository linked above.