# MCP Prompts Workflow Templates Architecture in code-review-graph

> Explore the MCP prompts workflow templates architecture in code-review-graph. Discover its modular, token-efficient design combining a static preamble with five parameterized functions for streamlined code reviews.

- Repository: [Tirth Kanani/code-review-graph](https://github.com/tirth8205/code-review-graph)
- Tags: architecture
- Published: 2026-07-26

---

**The MCP prompts workflow templates follow a modular, token-efficient architecture defined in [`code_review_graph/prompts.py`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/__init__.py) and validated in [`tests/test_prompts.py`](https://github.com/tirth8205/code-review-graph/blob/main/tests/test_prompts.py).

## Core Components of the Prompt Architecture

The architecture rests on three foundational elements defined in [`code_review_graph/prompts.py`](https://github.com/tirth8205/code-review-graph/blob/main/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:

```python
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:

```python
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:

```python
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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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.