How to Query the CRG Knowledge Graph: A Complete Guide to query_graph_tool

Use the query_graph_tool MCP tool in code_review_graph/main.py with a specific pattern (e.g., callers_of, tests_for) and target node to traverse structural relationships like call chains, imports, and test coverage in the Code-Review-Graph knowledge graph.

The Code-Review-Graph (CRG) open-source project captures structural relationships between code entities to power intelligent code reviews. When you need to query the CRG knowledge graph to understand dependencies, test coverage, or call hierarchies, the built-in MCP tool query_graph_tool serves as the primary interface for graph traversal. This tool exposes the underlying graph database through 16 semantic patterns that map directly to software engineering concepts.

Understanding the query_graph_tool Interface

The query_graph_tool implementation in code_review_graph/main.py (lines 46-85) defines the contract for all graph explorations. The tool accepts parameters that specify both the traversal pattern and the scope of returned data.

Required Parameters

To successfully query the CRG knowledge graph, you must provide two mandatory arguments:

• pattern – A string identifying the relationship type to traverse. Valid values include callers_of, callees_of, tests_for, and 13 other predefined patterns.
• target – The node identifier serving as the query origin. This can be a fully-qualified function name (e.g., my_pkg.utils.calculate), a class reference (e.g., com.example.MyService), or a file path present in the graph.

Optional Configuration

You can refine results using additional parameters:

• repo_root – The repository root path; auto-detected if omitted.
• detail_level – Either "standard" (default, full metadata) or "minimal" (compact summary).
• max_results – Integer limit for the result set size.

Available Query Patterns for the CRG Knowledge Graph

The CRG knowledge graph supports 16 predefined traversal patterns covering structural, behavioral, and dependency relationships:

Call and Reference Patterns

• callers_of – Functions or methods that invoke the target.
• callees_of – Functions called by the target.
• references_to – Any nodes referencing the target.

Module and Import Patterns

• imports_of – Modules imported by the target file.
• importers_of – Files that import the target module.

Structural Containment

• children_of – Entities contained within a file or class.
• file_summary – All nodes present in a specific file.

Inheritance and Testing

• inheritors_of – Classes that inherit from the target.
• tests_for – Test cases exercising the target function or class.

Event and Scheduler Patterns

• triggers_of – Scheduler-triggered methods invoked by the target.
• triggered_by – Schedulers or triggers that invoke the target.
• publishers_of – Methods that publish an event.
• listeners_of – Methods listening for an event.

API and Configuration Patterns

• handlers_of – Methods handling a specific endpoint.
• endpoints_for – Endpoints served by the target method.
• consumers_of – Spring configuration consumers.

Practical Examples for Querying the CRG Knowledge Graph

Command-Line Interface

Use the code-review-graph mcp command defined in code_review_graph/cli.py to invoke query_graph_tool directly from your terminal. This approach requires no Python scripting for quick lookups.

Find all callers of a Python function:

code-review-graph mcp \
  --tool query_graph_tool \
  --pattern callers_of \
  --target my_pkg.utils.calculate \
  --detail_level minimal

Python API Integration

Import query_graph_tool from code_review_graph.main to embed graph queries into custom analysis scripts.

Retrieve test coverage for a Java class:

from code_review_graph.main import query_graph_tool

result = query_graph_tool(
    pattern="tests_for",
    target="com.example.MyService",
    detail_level="standard",
    max_results=50,
)

print(result["nodes"])   # List of test nodes covering the class

Chaining with Impact Analysis

Combine query_graph_tool with get_impact_radius_tool to drill down into high-risk change areas. This workflow starts with impact detection, then uses targeted graph queries to map dependencies.

from code_review_graph.main import get_impact_radius_tool, query_graph_tool

# Identify high-risk functions from recent changes

impact = get_impact_radius_tool(max_depth=2, detail_level="minimal")
high_risk = [node["name"] for node in impact["high_risk"]]

# For each high-risk function, list its callees

for fn in high_risk:
    callees = query_graph_tool(
        pattern="callees_of",
        target=fn,
        detail_level="minimal",
    )
    print(f"Callees of {fn}:", callees["nodes"])

Integrating with the Broader MCP Ecosystem

While query_graph_tool handles structural traversal, the CRG platform provides complementary MCP tools for comprehensive analysis. According to the documentation in code_review_graph/docs/LLM-OPTIMIZED-REFERENCE.md, you can chain query_graph_tool with:

• get_review_context_tool – For semantic context around code changes.
• get_impact_radius_tool – To identify high-risk modification areas.
• semantic_search_nodes_tool – For vector-based similarity search across the graph.

Typical workflows begin with get_minimal_context_tool to obtain a risk overview, then apply query_graph_tool to specific high-risk items using patterns like callers_of or tests_for.

Summary

• The query_graph_tool in code_review_graph/main.py is the primary interface to query the CRG knowledge graph.
• You must specify a pattern (one of 16 relationship types) and a target node to execute any query.
• Supported patterns cover call hierarchies (callers_of, callees_of), dependencies (imports_of, importers_of), testing (tests_for), and event handling (listeners_of, publishers_of).
• Use detail_level="minimal" for quick summaries or "standard" for full node metadata.
• The tool integrates with the code-review-graph CLI (cli.py) and can be chained with other MCP tools like get_impact_radius_tool for advanced workflows.

Frequently Asked Questions

What is the difference between detail_level "standard" and "minimal"?

The "standard" detail level (default) returns complete node metadata including all properties stored in the CRG knowledge graph. The "minimal" setting returns a compact summary containing only essential identifiers, which improves performance when processing large result sets or when you only need entity names for downstream filtering.

Can I use wildcards or regex in the target parameter?

No, the target parameter requires a specific, fully-qualified identifier present in the graph such as my_pkg.utils.calculate or com.example.MyService. For fuzzy matching or semantic similarity searches, use the semantic_search_nodes_tool instead, which performs vector-based retrieval across the knowledge graph.

How do I find all tests that cover a specific function?

Use the tests_for pattern. Invoke query_graph_tool with pattern="tests_for" and set target to your function name. The tool returns test nodes that exercise the target according to the test coverage relationships captured during the graph construction phase.

Where is the complete list of query patterns defined?

The authoritative list of 16 supported patterns is implemented in the query_graph_tool function definition within code_review_graph/main.py (lines 46-85). Additional documentation and usage examples are available in code_review_graph/docs/LLM-OPTIMIZED-REFERENCE.md.

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