How MCP Prompts (review_changes, architecture_map, debug_issue) Work in code-review-graph

The MCP prompts in code-review-graph provide structured, token-efficient workflows that guide LLMs through pre-commit reviews, architecture mapping, and debugging by sequencing specific graph-analysis tool calls defined in code_review_graph/prompts.py.

The tirth8205/code-review-graph package implements a Multi-Chat-Prompt (MCP) layer that constructs ready-to-run prompt messages for the fastmcp engine. These MCP prompts encode step-by-step workflows that instruct the model on which graph-analysis tools to invoke—such as detect_changes, query_graph, and semantic_search_nodes—and when to escalate detail levels to minimize token consumption while maximizing code review accuracy.

The MCP Prompt Architecture in code-review-graph

All three prompt templates reside in code_review_graph/prompts.py and share a common construction pattern designed for the fastmcp framework.

Token-Efficiency Preamble and Message Helpers

Each prompt begins with a static preamble that enforces token-efficient behavior:

_TOKEN_EFFICIENCY_PREAMBLE = """\

## Rules for Token-Efficient Graph Usage

...
"""

Additionally, a helper function _user wraps content into the Message structure required by fastmcp ≥3.2:

def _user(content: str) -> list[Message]:
    return [Message(role="user", content=content)]

This helper ensures the prompt returns a single-message list that the MCP driver can process directly.

How review_changes Works for Pre-Commit Reviews

The review_changes_prompt function generates a workflow for analyzing code changes before commits. It accepts a base parameter (defaulting to "HEAD~1") to specify the comparison reference.

The prompt returned by this function instructs the LLM to:

1. Start with get_minimal_context(task="review changes against {base}") to obtain a high-level risk overview.
2. If the risk is low, call detect_changes(detail_level="minimal") to get a concise change list and test gaps.
3. If the risk is medium or high:
   • Call detect_changes(detail_level="standard") for the full change set.
   • For each high-risk function, use query_graph(pattern="callers_of") to discover potential impact.
   • Call get_affected_flows(detail_level="minimal") only if more than three functions changed.
4. Summarize the risk level, changes, test coverage gaps, and concrete improvement hints.

The implementation in code_review_graph/prompts.py (lines 45-71) embeds the base reference directly into the workflow instructions, allowing callers to customize the comparison target without modifying the source code.

How architecture_map Generates Architecture Documentation

The architecture_map_prompt creates a structured workflow for visualizing codebase architecture. This prompt guides the model to produce Mermaid diagrams showing module communities and data flows.

The workflow steps encoded in this prompt include:

1. Call get_minimal_context(task="map architecture") to establish the task context.
2. Call get_architecture_overview(detail_level="minimal") to collect high-level module community data.
3. Call list_flows(detail_level="minimal") to retrieve critical data-flow names and importance scores.
4. Only call get_community(name=<X>, detail_level="standard") for specific communities requiring deeper inspection.
5. Produce a concise Mermaid diagram showing communities as boxes and key flows as arrows.

According to the source code in code_review_graph/prompts.py (lines 74-89), this prompt never escalates to standard detail unless the model explicitly needs to drill into a specific community, adhering strictly to the token-efficiency rules.

How debug_issue Guides Issue Investigation

The debug_issue_prompt function accepts an optional description parameter and returns a troubleshooting workflow tailored to the specific issue.

The debugging workflow instructs the LLM to:

1. Call get_minimal_context(task="debug: {description}") to get an initial risk assessment based on the problem description.
2. Call semantic_search_nodes(query=<keywords from description>) to perform semantic search over the code graph.
3. For the top 1-2 results, call query_graph(pattern="callers_of") to trace where the faulty behavior may propagate.
4. If the issue involves execution flow, call get_flow(name=<relevant flow>) to examine the full execution path.
5. Only call get_review_context or get_impact_radius when needing concrete source snippets or blast-radius analysis.

Located in code_review_graph/prompts.py (lines 92-104), this prompt dynamically inserts the user-provided description into the workflow instructions, ensuring the semantic search targets relevant code elements.

Using the MCP Prompts with fastmcp

Below are minimal Python examples demonstrating how to use these prompts with the fastmcp engine:

from code_review_graph.prompts import (
    review_changes_prompt,
    architecture_map_prompt,
    debug_issue_prompt,
)

# Pre-commit review comparing against HEAD~1 (default)

review_messages = review_changes_prompt()

# Architecture documentation for current codebase

arch_messages = architecture_map_prompt()

# Debug a specific production issue

debug_messages = debug_issue_prompt(
    description="Login fails with 500 error after recent deployment"
)

Each function returns a list containing one Message object ready for the MCP client:

from fastmcp import MCP

client = MCP()
response = client.run(messages=review_messages)

# The model follows the numbered workflow instructions,

# making appropriate tool calls in sequence

The model processes the single user-role message and executes the workflow steps, invoking the appropriate graph-analysis tools—defined in supporting modules like code_review_graph/changes.py and code_review_graph/analysis.py—as it constructs its final response.

Summary

• Token efficiency first: All three MCP prompts begin with _TOKEN_EFFICIENCY_PREAMBLE to enforce minimal detail levels unless explicitly required.
• Workflow-driven: Each prompt encodes a numbered sequence of tool calls (detect_changes, get_minimal_context, query_graph, etc.) that the LLM executes in order.
• Configurable inputs: review_changes_prompt accepts a base parameter for custom commit ranges, while debug_issue_prompt accepts a description for targeted semantic search.
• Single-message output: Each function returns a list containing one Message object compatible with fastmcp ≥3.2, simplifying integration with MCP clients.
• Source location: All implementations reside in code_review_graph/prompts.py and reference tools implemented across changes.py, analysis.py, and graph.py.

Frequently Asked Questions

What is the purpose of the token-efficiency preamble in code-review-graph MCP prompts?

The preamble stored in _TOKEN_EFFICIENCY_PREAMBLE instructs the LLM to start every workflow with get_minimal_context and maintain detail_level="minimal" unless the specific task requires deeper investigation. This design minimizes token consumption and API costs while ensuring the model escalates detail only when necessary.

How does review_changes_prompt determine which detail level to use?

The prompt instructs the LLM to assess risk from the initial get_minimal_context call. If the risk is low, it uses detect_changes(detail_level="minimal"). For medium or high risk, it escalates to detail_level="standard" and additionally queries callers via query_graph and affected flows via get_affected_flows, providing comprehensive analysis only when warranted by risk level.

Can I customize the base reference in review_changes_prompt?

Yes, the base parameter defaults to "HEAD~1" but accepts any valid git reference. When calling review_changes_prompt(base="main"), the function embeds this reference into the workflow instructions, causing the LLM to compare changes against the specified branch or commit rather than the default previous commit.

What MCP tools does debug_issue_prompt use to investigate issues?

The debugging workflow utilizes get_minimal_context for initial assessment, semantic_search_nodes for finding relevant code via natural language queries, query_graph with pattern="callers_of" to trace propagation paths, and conditionally get_flow, get_review_context, or get_impact_radius when execution flow details or blast-radius analysis are required to pinpoint the root cause.

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