MCP Prompts Workflow Templates Architecture in code-review-graph

The MCP prompts workflow templates follow a modular, token-efficient architecture defined in code_review_graph/prompts.py, combining a static efficiency preamble with five parameterized functions that return fastmcp Message lists for orchestrating code reviews.

The code-review-graph repository implements a Model-Centric Prompt (MCP) subsystem that standardizes AI-driven code review interactions. Understanding the MCP prompts workflow templates architecture reveals how the project maintains token efficiency while providing a consistent interface for the fastmcp runtime, with functions conveniently re-exported through code_review_graph/__init__.py and validated in tests/test_prompts.py.

Core Components of the Prompt Architecture

The architecture rests on three foundational elements defined in code_review_graph/prompts.py: a token-efficiency preamble, a normalization wrapper, and workflow-specific generators.

Token-Efficiency Preamble

All generated prompts embed the _TOKEN_EFFICIENCY_PREAMBLE, a multiline string defined at lines 17-30 that enforces hard-coded rules for minimal token usage and disciplined tool-call patterns. This preamble ensures every MCP workflow starts with consistent constraints, preventing agents from requesting excessive context prematurely.

Message Wrapper Helper

The _user(content: str) → list[Message] function (lines 34-42) normalizes raw prompt strings into fastmcp.prompts.Message objects. This helper guarantees compatibility with fastmcp ≥ 3.2 requirements while providing a uniform return type for all workflow templates.

Workflow Template Functions

Five primary functions construct specific MCP workflows by concatenating the preamble with step-by-step instructions:

• review_changes_prompt(base: str = "HEAD~1") (lines 45-59)
• architecture_map_prompt() (lines 74-89)
• debug_issue_prompt(description: str = "") (lines 92-115)
• onboard_developer_prompt() (lines 117-132)
• pre_merge_check_prompt() (lines 135-159)

Each returns list[Message], making them interchangeable for downstream agents. Functions accept optional arguments—such as base for git references or description for debugging contexts—that are interpolated into the prompt text, enabling reuse across different code-review scenarios.

FastMCP Integration and Tool References

The templates reference fastmcp primitives including get_minimal_context, detect_changes, query_graph, and list_flows. According to the code-review-graph source code, the architecture deliberately places minimal detail-level tool calls first, escalating context requests only when necessary to adhere to the preamble's efficiency rules. For example, review_changes_prompt orchestrates get_minimal_context, detect_changes, query_graph, and get_affected_flows in sequence (lines 51-66).

Practical Usage Examples

Generate a pre-commit review prompt using the default git base:

from code_review_graph.prompts import review_changes_prompt

# Use the default git base (HEAD~1)

prompt = review_changes_prompt()

# `prompt` is a list[Message] ready for a FastMCP agent:

# >>> prompt[0].role

# 'user'

# >>> print(prompt[0].content)

# ## Rules for Token-Efficient Graph Usage …

# ## Review Workflow …

Create a debugging prompt for a specific issue:

from code_review_graph.prompts import debug_issue_prompt

issue = "NullReferenceError when loading user profile"
debug_prompt = debug_issue_prompt(description=issue)

# Pass `debug_prompt` to a FastMCP agent to start the guided-debug workflow.

Generate an onboarding workflow for a new developer:

from code_review_graph.prompts import onboard_developer_prompt

onboard_prompt = onboard_developer_prompt()

# The prompt will instruct the agent to fetch graph stats, architecture overview, etc.

Summary

• Modular design: The architecture separates static prompt definitions in code_review_graph/prompts.py from the fastmcp runtime execution, allowing the prompt language to evolve independently.
• Token efficiency: The _TOKEN_EFFICIENCY_PREAMBLE embedded at lines 17-30 enforces minimal token usage and disciplined tool-call escalation across all workflows.
• Consistent API: All five workflow functions return list[Message] via the _user wrapper (lines 34-42), ensuring interoperability with fastmcp ≥ 3.2.
• Parameterization: Functions accept optional arguments like base and description for flexible reuse across different code-review scenarios.

Frequently Asked Questions

What file contains the MCP prompts workflow templates in code-review-graph?

The workflow templates are defined in code_review_graph/prompts.py. This file contains the _TOKEN_EFFICIENCY_PREAMBLE, the _user helper function, and all five workflow generation functions including review_changes_prompt and debug_issue_prompt. The package initializer at code_review_graph/__init__.py re-exports these for convenient top-level imports.

How do the MCP prompt functions handle token efficiency?

Each prompt embeds the _TOKEN_EFFICIENCY_PREAMBLE defined at lines 17-30, which establishes rules for minimal token usage. The templates also structure tool calls to request minimal context first—using primitives like get_minimal_context before escalating to query_graph—ensuring agents follow disciplined patterns and avoid premature large-context requests.

What return type do the workflow template functions produce?

All workflow functions return list[Message] as enforced by the _user wrapper function (lines 34-42). This normalization ensures compatibility with the fastmcp library version 3.2 and higher, as validated by the unit tests in tests/test_prompts.py.

Can I customize the git reference used in review prompts?

Yes. The review_changes_prompt function accepts an optional base parameter defaulting to "HEAD~1". Pass a different git reference string to analyze changes against specific commits or branches, and the value is interpolated directly into the generated prompt instructions.

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