How to Verify Installation and Troubleshoot Connection Issues with Code-Review-Graph

Use code-review-graph status to confirm non‑zero node counts, then test MCP connectivity with a natural‑language query like "What calls parse_file?"

Code-review-graph (CRG) is a local‑first, AST‑based code analysis tool that exposes its capabilities through the Model‑Context‑Protocol (MCP). Because core graph operations happen entirely on your machine, verification relies on simple CLI checks and local server diagnostics rather than external API health tests. This guide walks you through confirming a healthy installation and resolving the most common connectivity problems.

Verify the Graph Has Been Built

A functioning installation requires a populated SQLite graph database. Zero nodes mean the parser never ran successfully.

Check Graph Existence

Run the built‑in status command:

code-review-graph status

Look for non‑zero node and edge counts (example: "Nodes: 208,821"). If you see zero nodes, the build never completed or found no parsable files. According to the README.md, this command reports the current state of graph.db in the project root.

Trigger or Refresh the Build

Force a full rebuild or incremental update:

# Full rebuild

code-review-graph build

# Incremental update (faster, SHA‑256 based)

code-review-graph update

The command should finish in seconds for a 500‑file repository and output "Built X nodes, Y edges". Incremental updates only re‑parse files whose hashes changed, keeping latency low as documented in README.md lines 38‑41.

Validate MCP Server Wiring

CRG runs an MCP server that AI assistants query. Three quick checks confirm the server is reachable.

Start the Server

If not already running, launch manually:

code-review-graph serve --host 127.0.0.1

The process should bind to localhost and print "MCP server listening". The install command can also launch this automatically.

List Exposed Tools

From any MCP client (Claude Code, Cursor, etc.), run:

/mcp

The tool list must include:

• query_graph_tool
• detect_changes_tool
• get_review_context_tool

Missing tools indicate server misconfiguration. See README.md lines 70‑73 for the complete tool manifest.

Execute a Test Query

Ask your assistant:

"What calls parse_file?"

A correct setup invokes query_graph internally. If the assistant falls back to grepping files, the MCP handshake failed. Successful completion proves client‑server communication works end‑to‑end.

Quick Sanity Check with Token Savings

The detect-changes command provides concrete evidence the graph is active:

code-review-graph detect-changes --brief

Expected output:

┌───────────────────── Token Savings ──────────────────────┐
│ Full context would be:   12,921 tokens                │
│ Graph context used:        762 tokens                │
│ Saved:                  12,159 tokens (~94%)          │
└───────────────────────────────────────────────────────┘

If the panel reports "0 nodes", rebuild the graph. Add --verify to cross‑check token counts against OpenAI's cl100k_base tokenizer (requires tiktoken installed). This behavior is documented in README.md lines 85‑96.

Troubleshoot Common Connection Issues

Symptom	Root Cause	Resolution
pip/pipx fails with "Bad file descriptor" or cannot download hatchling	Network block (firewall, VPN, proxy) preventing PyPI reach	Run install from system terminal; use uv (uv tool install . --force) for alternative download stack. Reference: README.md lines 58‑71
Windows: "Invalid JSON: EOF while parsing" or "MCP error -32000: Connection closed"	Client wraps CRG executable in cmd /c, breaking stdio pipes	Configure direct .exe invocation; set PYTHONUTF8=1 in environment. See README.md lines 76‑86
MCP server timeout or "connection refused"	Server not running, or bound to non‑localhost address blocked by firewall	Start with code-review-graph serve --host 127.0.0.1; verify port availability with lsof -i :<port>
Cloud embedding egress warnings	Function signatures sent to OpenAI/Gemini when cloud embeddings enabled	Set CRG_ACCEPT_CLOUD_EMBEDDINGS=1 after reviewing warning, or keep embeddings local using code-review-graph[embeddings] (HuggingFace models). Reference: README.md lines 52‑58

Advanced Diagnostics

When basic checks fail, proceed systematically:

Run Network Diagnostic Script

python3 scripts/diagnose_pypi_connectivity.py

A FAILED result confirms network problems rather than CRG bugs. This script is located at [scripts/diagnose_pypi_connectivity.py](https://github.com/tirth8205/code-review-graph/blob/main/scripts/diagnose_pypi_connectivity.py) as noted in README.md lines 72‑74.

Inspect Log Files

Daemon mode writes to ~/.code-review-graph/watch.log. Check for:

• Python stack traces
• SQLite permission errors
• Port binding conflicts

Clean Rebuild

Eliminate corrupted database files:

rm -rf .code-review-graph/graph.db
code-review-graph build

This wipes [code_review_graph/backend/sqlite.py](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/backend/sqlite.py) storage and rebuilds from scratch.

Summary

• Verify installation with code-review-graph status — non‑zero nodes confirm success
• Test MCP connectivity by listing tools and running a natural‑language query
• Validate graph health using detect-changes --brief for token‑savings proof
• Resolve connection issues by checking PyPI reachability, Windows pipe handling, and server binding configuration
• Recover from corruption with log inspection and clean rebuilds

Frequently Asked Questions

Why does code-review-graph status show zero nodes?

The parser never ran successfully or found no supported source files. Run code-review-graph build to trigger parsing. If the issue persists, check that your repository contains files with extensions supported by the Tree‑sitter parser in [code_review_graph/parser.py](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/parser.py).

How do I confirm the MCP server is actually being used?

Ask your AI assistant a semantic question like "What calls parse_file?" and verify it invokes query_graph_tool rather than falling back to text search. The assistant's tool‑use indicator or /mcp command output will show the active tool call.

What's the difference between build and update?

build performs a full reparse of the entire repository. update uses SHA‑256 hashes to incrementally process only changed files, significantly reducing latency for large codebases. Both commands update the SQLite graph in .code-review-graph/graph.db.

Can I use code‑review‑graph completely offline?

Yes. Core functionality requires no network access. Cloud embeddings are optional; install with code-review-graph[embeddings] to use local HuggingFace models instead of OpenAI or Gemini APIs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}