# What Is the `build_or_update_graph_tool`? A Deep Dive into the code-review-graph MCP Tool

> Discover the build_or_update_graph_tool, the core FastMCP utility for the code-review-graph project. It parses code with Tree-sitter to build and maintain an incremental knowledge graph in SQLite.

- Repository: [Tirth Kanani/code-review-graph](https://github.com/tirth8205/code-review-graph)
- Tags: deep-dive
- Published: 2026-08-08

---

**The `build_or_update_graph_tool` is the core FastMCP utility in the `tirth8205/code-review-graph` project that parses repository source code with Tree-sitter to create and maintain a persistent incremental knowledge graph stored in SQLite.**

The `build_or_update_graph_tool` serves as the foundation of the `tirth8205/code-review-graph` system, transforming raw codebases into queryable graph structures. This async-aware MCP tool enables both full repository indexing and incremental updates, making it essential for AI-powered code review workflows that depend on accurate structural analysis.

## Core Purpose and Architecture

The `build_or_update_graph_tool` functions as the primary ingestion engine for the code-review-graph ecosystem. It traverses the repository filesystem, using **Tree-sitter** parsers to extract structural elements—including modules, classes, functions, imports, and test relationships—and persists these as nodes and edges in an on-disk **SQLite database**.

This persistent graph powers downstream analytical capabilities such as:

- **Impact analysis** – determining which components affect others
- **Flow detection** – tracing execution paths through the codebase
- **Community detection** – identifying tightly coupled modules
- **Embedding generation** – creating vector representations of code for semantic search

## How Incremental Builds Work

### First-Time Repository Indexing

When invoked with `full_rebuild=True`, the tool performs a complete parse of every source file in the repository. This initial build establishes the baseline graph structure and records the current Git commit hash for future differential comparisons.

### Incremental Update Strategy

For subsequent invocations, `build_or_update_graph_tool` defaults to incremental mode. It compares the working tree against the last recorded Git base (or an explicit `base` reference provided via parameter), re-parsing only files that have changed. This approach significantly reduces processing time for large repositories while keeping the graph synchronized with the current code state.

### Async Implementation Details

To maintain responsiveness within the MCP STDIO event loop—particularly critical on Windows platforms—the heavy Tree-sitter parsing workload is dispatched to a background thread using `asyncio.to_thread`. This implementation detail in [`code_review_graph/main.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/main.py) prevents the tool from blocking during intensive graph construction operations.

## Tool Parameters and Configuration

The `build_or_update_graph_tool` accepts several parameters that control its behavior:

- **`full_rebuild`** (bool) – Forces a complete re-parse of all source files, ignoring any cached state.
- **`repo_root`** (Optional[str]) – Explicit path to the repository root; if omitted, the tool auto-detects the repository from the current working directory.
- **`base`** (Optional[str]) – Git reference (commit hash or branch) to diff against; if omitted, the tool resolves the last-synced commit automatically.
- **`postprocess`** (str) – Controls the level of post-processing applied to the graph. Accepts `"full"` (comprehensive analysis), `"minimal"` (basic cleanup), or `"none"` (raw graph output).
- **`recurse_submodules`** (Optional[bool]) – Whether to include Git submodules in the parsing scope; defaults to the value of the `CRG_RECURSE_SUBMODULES` environment variable.
- **`embedding_provider`** / **`embedding_model`** – Optional hooks to trigger a one-off embedding refresh immediately after the graph is built or updated.

## Usage Examples

### Full Repository Build

Use this pattern when initializing the graph for the first time:

```python
import asyncio
from code_review_graph.main import build_or_update_graph_tool

async def full_build():
    result = await build_or_update_graph_tool(full_rebuild=True)
    print("Graph built:", result["status"])

asyncio.run(full_build())

```

### Incremental Update

For daily synchronization, invoke the tool without parameters to process only changed files:

```python
import asyncio
from code_review_graph.main import build_or_update_graph_tool

async def incremental_update():
    # Uses the last-synced Git ref automatically

    result = await build_or_update_graph_tool()
    print("Updated nodes:", result["updated_node_count"])

asyncio.run(incremental_update())

```

### Fast Build with Minimal Post-Processing

When speed is prioritized over analytical depth:

```python
import asyncio
from code_review_graph.main import build_or_update_graph_tool

async def fast_build():
    result = await build_or_update_graph_tool(postprocess="minimal")
    print(result)

asyncio.run(fast_build())

```

## Integration Interfaces

The tool is exposed through two primary interfaces:

1. **MCP Command Line** – Invoke via the slash-command `/code-review-graph:build-graph` or directly from any MCP client. The parameter definitions in [`docs/COMMANDS.md`](https://github.com/tirth8205/code-review-graph/blob/main/docs/COMMANDS.md) document the CLI usage patterns and match the Python API signature.

2. **Python API** – Import the async function directly from `code_review_graph.main` for use in custom scripts, test suites (as demonstrated in [`tests/test_integration_git.py`](https://github.com/tirth8205/code-review-graph/blob/main/tests/test_integration_git.py)), or skill workflows outlined in [`skills/build-graph/SKILL.md`](https://github.com/tirth8205/code-review-graph/blob/main/skills/build-graph/SKILL.md).

## Summary

- The `build_or_update_graph_tool` creates persistent knowledge graphs using Tree-sitter parsing and SQLite storage, enabling structural code analysis.
- It supports both **full rebuilds** for initialization and **incremental updates** based on Git diffs to minimize processing overhead.
- The async architecture uses `asyncio.to_thread` to maintain MCP responsiveness during CPU-intensive parsing operations.
- The tool is defined in [`code_review_graph/main.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/main.py) and accessible via both MCP CLI commands and direct Python imports.

## Frequently Asked Questions

### What is the primary function of `build_or_update_graph_tool`?

The tool parses repository source code to build a structural knowledge graph of modules, classes, functions, imports, and test relationships. It stores these entities and their connections in an on-disk SQLite database, which downstream tools query for impact analysis, flow detection, and embedding generation.

### How does the tool determine which files to parse during incremental updates?

The tool resolves the last-synced Git commit automatically from its internal state (or uses an explicit `base` reference parameter) to diff against the current working tree. Only files with modifications relative to that base commit are re-parsed and updated in the graph, preserving unchanged nodes to minimize latency.

### Can I invoke `build_or_update_graph_tool` programmatically outside of an MCP client?

Yes. You can import the tool directly from `code_review_graph.main` and await it in an async Python context. This makes it suitable for custom automation scripts, CI/CD pipelines, and integration tests that need to programmatically rebuild or update the code knowledge graph.

### Why does the tool use `asyncio.to_thread` for parsing operations?

The Tree-sitter parsing workload is dispatched to a background thread via `asyncio.to_thread` to prevent blocking the MCP STDIO event loop. This architectural choice ensures the tool remains responsive during intensive graph construction, which is particularly important for maintaining protocol stability on Windows systems.