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

> Verify code-review-graph installation and troubleshoot connection issues using the status command and MCP queries. Learn to confirm node counts and test connectivity effectively.

- Repository: [Tirth Kanani/code-review-graph](https://github.com/tirth8205/code-review-graph)
- Tags: how-to-guide
- Published: 2026-08-14

---

**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:

```bash
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](https://github.com/tirth8205/code-review-graph/blob/main/README.md#L67), 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:

```bash

# 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](https://github.com/tirth8205/code-review-graph/blob/main/README.md#L38).

## 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:

```bash
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](https://github.com/tirth8205/code-review-graph/blob/main/README.md#L70) 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:

```bash
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](https://github.com/tirth8205/code-review-graph/blob/main/README.md#L85).

## 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](https://github.com/tirth8205/code-review-graph/blob/main/README.md#L58) |
| 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](https://github.com/tirth8205/code-review-graph/blob/main/README.md#L76) |
| 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](https://github.com/tirth8205/code-review-graph/blob/main/README.md#L52) |

## Advanced Diagnostics

When basic checks fail, proceed systematically:

### Run Network Diagnostic Script

```bash
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)](https://github.com/tirth8205/code-review-graph/blob/main/scripts/diagnose_pypi_connectivity.py) as noted in [README.md lines 72‑74](https://github.com/tirth8205/code-review-graph/blob/main/README.md#L72).

### 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:

```bash
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)](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)](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.