Build MCP Prompts That Trigger Multi-Step Workflows on macOS

mkdir -p mcp-prompt-workflows-macos
cd mcp-prompt-workflows-macos
touch .gitignore

uv init --name macmcp --no-workspace
rm -f main.py hello.py
uv add fastmcp
uv add --dev pytest pytest-asyncio

[project]
name = "macmcp"
version = "0.1.0"
description = "MCP prompts that trigger multi-step release-prep workflows"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "fastmcp>=3.4.5",
]

[dependency-groups]
dev = [
    "pytest>=9.1.1",
    "pytest-asyncio>=1.4.0",
]

mkdir -p data
touch data/changes.json

[
  {
    "id": "CH-101",
    "release": "2.4.0",
    "type": "feat",
    "component": "search",
    "summary": "Add fuzzy matching to the document search index.",
    "breaking": false,
    "migration": null
  },
  {
    "id": "CH-102",
    "release": "2.4.0",
    "type": "fix",
    "component": "auth",
    "summary": "Refresh tokens no longer expire early under clock skew.",
    "breaking": false,
    "migration": null
  },
  {
    "id": "CH-103",
    "release": "2.4.0",
    "type": "feat",
    "component": "api",
    "summary": "Replace the limit query parameter with page_size.",
    "breaking": true,
    "migration": "Rename limit to page_size. The old name is accepted until 3.0.0 and logs a deprecation warning."
  },
  {
    "id": "CH-104",
    "release": "2.4.0",
    "type": "chore",
    "component": "build",
    "summary": "Drop Python 3.10 from the supported test matrix.",
    "breaking": true,
    "migration": "Upgrade to Python 3.11 or newer before installing 2.4.0."
  },
  {
    "id": "CH-105",
    "release": "2.3.1",
    "type": "fix",
    "component": "search",
    "summary": "Escape regex metacharacters in user-supplied queries.",
    "breaking": false,
    "migration": null
  }
]

touch server.py

"""A release-prep MCP server whose prompts trigger multi-step workflows.

The three tools here are deliberately small and single-purpose. The prompts are
what turn them into a repeatable procedure: each prompt renders an ordered plan
that names the exact tools and arguments to use, ships the house policy inline as
an embedded resource, and injects facts the server looked up while rendering, so
the model starts from real data instead of guessing.

Run over stdio with `python server.py`, or drive it with client.py.
"""

import json
from pathlib import Path

from fastmcp import FastMCP
from fastmcp.prompts.prompt import Message
from mcp.types import EmbeddedResource, TextResourceContents

mcp = FastMCP("release-prep")

DATA = Path(__file__).parent / "data" / "changes.json"
POLICY_URI = "policy://release-notes"

POLICY = """Release-notes house rules:
1. Lead with what a reader can now do, not with the internal component name.
2. Every breaking change gets a "Migration" line written in the imperative.
3. One line per change. No marketing adjectives.
4. Order sections: Highlights, Breaking changes, All changes.
"""


def load_changes() -> list[dict]:
    """Every change record on disk."""
    return json.loads(DATA.read_text())


def changes_for(release: str) -> list[dict]:
    """Change records for one release, in file order."""
    return [c for c in load_changes() if c["release"] == release]


def known_releases() -> list[str]:
    """Sorted list of releases that have at least one change."""
    return sorted({c["release"] for c in load_changes()})


def require_release(release: str) -> list[dict]:
    """Resolve a release or fail now, while the prompt is being rendered."""
    changes = changes_for(release)
    if not changes:
        raise ValueError(
            f"Unknown release {release!r}. Known releases: {', '.join(known_releases())}"
        )
    return changes


@mcp.resource(POLICY_URI)
def release_policy() -> str:
    """The house rules for writing release notes."""
    return POLICY


@mcp.tool
def list_changes(release: str) -> list[dict]:
    """List every recorded change for a release."""
    return require_release(release)


@mcp.tool
def migration_note(change_id: str) -> dict:
    """Return the migration note for one breaking change."""
    for change in load_changes():
        if change["id"] == change_id:
            if not change["breaking"]:
                return {"id": change_id, "breaking": False, "migration": None}
            return {
                "id": change_id,
                "breaking": True,
                "migration": change["migration"],
            }
    raise ValueError(f"Unknown change id {change_id!r}")


@mcp.tool
def render_notes(release: str, highlights: list[str]) -> str:
    """Render final release notes from the highlight lines you wrote."""
    changes = require_release(release)
    breaking = [c for c in changes if c["breaking"]]

    lines = [f"# {release}", "", "## Highlights", ""]
    lines += [f"- {h}" for h in highlights]

    if breaking:
        lines += ["", "## Breaking changes", ""]
        for change in breaking:
            lines.append(f"- {change['id']} ({change['component']}): {change['summary']}")
            lines.append(f"  Migration: {change['migration']}")

    lines += ["", "## All changes", ""]
    for change in changes:
        lines.append(
            f"- {change['id']} {change['type']}({change['component']}): {change['summary']}"
        )

    return "\n".join(lines) + "\n"


def policy_message() -> Message:
    """Wrap the policy resource so a prompt can carry it inline by URI."""
    return Message(
        role="user",
        content=EmbeddedResource(
            type="resource",
            resource=TextResourceContents(
                uri=POLICY_URI,
                mimeType="text/plain",
                text=POLICY,
            ),
        ),
    )


@mcp.prompt
def draft_release_notes(release: str, audience: str = "developers") -> list[Message]:
    """Run the full release-notes workflow for a release."""
    changes = require_release(release)
    breaking = [c["id"] for c in changes if c["breaking"]]
    breaking_text = ", ".join(breaking) if breaking else "none"

    plan = f"""You are drafting release notes for {release}, written for {audience}.

Follow these steps in order and do not skip one:

1. Call `list_changes` with release="{release}" to read all {len(changes)} changes.
2. For each breaking change ({breaking_text}), call `migration_note` with its id
   and keep the migration text verbatim.
3. Write exactly one highlight line per change, following the policy below. Do
   not put migration text in a highlight line; `render_notes` builds the
   Breaking changes section from the records itself.
4. Call `render_notes` with release="{release}" and your highlight lines.
5. Show the rendered notes and stop. Do not invent changes that are not listed.

The attached policy resource is authoritative. If a highlight line would break a
rule in it, rewrite the line rather than the rule."""

    request = (
        f"Draft the {release} release notes. This release has {len(changes)} changes "
        f"and {len(breaking)} breaking change(s): {breaking_text}."
    )

    return [
        Message(role="assistant", content=plan),
        policy_message(),
        Message(role="user", content=request),
    ]


@mcp.prompt
def triage_breaking_changes(release: str) -> list[Message]:
    """Check that every breaking change in a release has a usable migration note."""
    changes = require_release(release)
    breaking = [c["id"] for c in changes if c["breaking"]]

    if not breaking:
        return [
            Message(
                role="user",
                content=(
                    f"Release {release} has {len(changes)} change(s) and no breaking "
                    "changes. Confirm that and stop; no triage is needed."
                ),
            )
        ]

    plan = f"""Triage the breaking changes in {release}.

1. Call `migration_note` for each of: {", ".join(breaking)}.
2. For each note, judge it against two tests: does it name the exact thing that
   changed, and does it tell the reader what to do in the imperative?
3. Report one line per change: the id, pass or fail, and the reason if it fails.
4. Do not call `render_notes`. This workflow ends with the report."""

    return [
        Message(role="assistant", content=plan),
        Message(
            role="user",
            content=f"Triage the {len(breaking)} breaking change(s) in {release}.",
        ),
    ]


if __name__ == "__main__":
    mcp.run()

touch client.py

"""Render the workflow prompts, then run the workflow one of them describes.

Part 1 shows what a client sees: the prompt list with its arguments, and the
messages `draft_release_notes` renders. Part 2 walks the same tool sequence the
prompt asks the model to follow, so you can check the procedure actually produces
release notes before you point a real client at it.
"""

import asyncio

from fastmcp import Client

from server import mcp

RELEASE = "2.4.0"


def show(label: str, body: str) -> None:
    print(f"\n{label}")
    print("-" * len(label))
    print(body)


async def main() -> None:
    async with Client(mcp) as client:
        print("=== Prompts this server offers ===\n")
        for prompt in await client.list_prompts():
            args = ", ".join(
                f"{a.name}{'' if a.required else '?'}" for a in prompt.arguments
            )
            print(f"/{prompt.name}({args})  {prompt.description}")

        print(f"\n\n=== Rendering draft_release_notes(release={RELEASE!r}) ===")
        rendered = await client.get_prompt("draft_release_notes", {"release": RELEASE})
        for i, message in enumerate(rendered.messages, start=1):
            content = message.content
            if content.type == "resource":
                body = f"[embedded resource {content.resource.uri}]\n{content.resource.text}"
            else:
                body = content.text
            show(f"message {i} ({message.role}, {content.type})", body)

        print("\n\n=== Running the workflow the prompt describes ===")
        changes = (await client.call_tool("list_changes", {"release": RELEASE})).data
        print(f"\nstep 1: list_changes -> {len(changes)} changes")

        for change in changes:
            if change["breaking"]:
                note = (
                    await client.call_tool("migration_note", {"change_id": change["id"]})
                ).data
                print(f"step 2: migration_note({change['id']}) -> {note['migration']}")

        highlights = [
            "Search now matches close spellings, so typos still find the document.",
            "Sessions survive clock skew between your machine and the auth service.",
            "Paging uses page_size; limit still works until 3.0.0.",
            "Python 3.11 is the minimum supported version.",
        ]
        notes = (
            await client.call_tool(
                "render_notes", {"release": RELEASE, "highlights": highlights}
            )
        ).data
        show("step 4: render_notes ->", notes)


if __name__ == "__main__":
    asyncio.run(main())

uv run python client.py

=== Prompts this server offers ===

/draft_release_notes(release, audience?)  Run the full release-notes workflow for a release.
/triage_breaking_changes(release)  Check that every breaking change in a release has a usable migration note.


=== Rendering draft_release_notes(release='2.4.0') ===

message 1 (assistant, text)
---------------------------
You are drafting release notes for 2.4.0, written for developers.

Follow these steps in order and do not skip one:

1. Call `list_changes` with release="2.4.0" to read all 4 changes.
2. For each breaking change (CH-103, CH-104), call `migration_note` with its id
   and keep the migration text verbatim.
...

message 2 (user, resource)
--------------------------
[embedded resource policy://release-notes]
Release-notes house rules:
1. Lead with what a reader can now do, not with the internal component name.
...

message 3 (user, text)
----------------------
Draft the 2.4.0 release notes. This release has 4 changes and 2 breaking change(s): CH-103, CH-104.


=== Running the workflow the prompt describes ===

step 1: list_changes -> 4 changes
step 2: migration_note(CH-103) -> Rename limit to page_size. The old name is accepted until 3.0.0 and logs a deprecation warning.
step 2: migration_note(CH-104) -> Upgrade to Python 3.11 or newer before installing 2.4.0.

step 4: render_notes ->
-----------------------
# 2.4.0

## Highlights

- Search now matches close spellings, so typos still find the document.
...

## Breaking changes

- CH-103 (api): Replace the limit query parameter with page_size.
  Migration: Rename limit to page_size. The old name is accepted until 3.0.0 and logs a deprecation warning.
- CH-104 (build): Drop Python 3.10 from the supported test matrix.
  Migration: Upgrade to Python 3.11 or newer before installing 2.4.0.

## All changes

- CH-101 feat(search): Add fuzzy matching to the document search index.
- CH-102 fix(auth): Refresh tokens no longer expire early under clock skew.
- CH-103 feat(api): Replace the limit query parameter with page_size.
- CH-104 chore(build): Drop Python 3.10 from the supported test matrix.

mkdir -p tests
touch tests/__init__.py tests/test_workflow_prompts.py pytest.ini

[pytest]
asyncio_mode = auto
filterwarnings =
    ignore::DeprecationWarning

"""Tests for the release-prep workflow prompts.

A workflow prompt is worth testing for the same reason a tool is: the text it
renders is a contract with the model. These tests pin the parts that a careless
edit would break — the ordered tool plan, the facts injected at render time, the
embedded policy, and the render-time failure on a bad argument.
"""

import pytest
from fastmcp import Client
from mcp.shared.exceptions import McpError

from server import mcp

RELEASE = "2.4.0"
QUIET_RELEASE = "2.3.1"


async def render(name: str, args: dict):
    async with Client(mcp) as client:
        return await client.get_prompt(name, args)


async def test_prompts_declare_required_and_optional_arguments():
    async with Client(mcp) as client:
        prompts = {p.name: p for p in await client.list_prompts()}

    assert set(prompts) == {"draft_release_notes", "triage_breaking_changes"}
    required = {a.name: a.required for a in prompts["draft_release_notes"].arguments}
    assert required == {"release": True, "audience": False}


async def test_plan_names_each_tool_in_order():
    result = await render("draft_release_notes", {"release": RELEASE})
    plan = result.messages[0].content.text

    positions = [plan.index(tool) for tool in ("list_changes", "migration_note", "render_notes")]
    assert positions == sorted(positions)


async def test_plan_injects_facts_looked_up_at_render_time():
    result = await render("draft_release_notes", {"release": RELEASE})
    plan = result.messages[0].content.text

    # 4 changes in 2.4.0, of which CH-103 and CH-104 are breaking.
    assert "all 4 changes" in plan
    assert "(CH-103, CH-104)" in plan
    assert "CH-105" not in plan  # belongs to 2.3.1


async def test_optional_audience_argument_changes_the_framing():
    default = await render("draft_release_notes", {"release": RELEASE})
    assert "written for developers" in default.messages[0].content.text

    override = await render(
        "draft_release_notes", {"release": RELEASE, "audience": "site operators"}
    )
    assert "written for site operators" in override.messages[0].content.text


async def test_policy_travels_as_an_embedded_resource():
    result = await render("draft_release_notes", {"release": RELEASE})
    resource = result.messages[1].content

    assert resource.type == "resource"
    assert str(resource.resource.uri) == "policy://release-notes"
    assert "Migration" in resource.resource.text


async def test_roles_are_only_user_and_assistant():
    result = await render("draft_release_notes", {"release": RELEASE})
    assert [m.role for m in result.messages] == ["assistant", "user", "user"]


async def test_unknown_release_fails_while_rendering():
    # The client sees a protocol error, not a rendered prompt: the bad argument
    # never reaches the model.
    with pytest.raises(McpError) as excinfo:
        await render("draft_release_notes", {"release": "9.9.9"})

    message = str(excinfo.value)
    assert "Unknown release '9.9.9'" in message
    assert "2.3.1, 2.4.0" in message


async def test_triage_prompt_covers_exactly_the_breaking_changes():
    result = await render("triage_breaking_changes", {"release": RELEASE})
    plan = result.messages[0].content.text

    assert "CH-103, CH-104" in plan
    assert "Do not call `render_notes`" in plan


async def test_triage_prompt_short_circuits_when_nothing_is_breaking():
    result = await render("triage_breaking_changes", {"release": QUIET_RELEASE})

    assert len(result.messages) == 1
    assert result.messages[0].role == "user"
    assert "no breaking changes" in result.messages[0].content.text


async def test_render_notes_omits_the_breaking_section_when_empty():
    async with Client(mcp) as client:
        notes = (
            await client.call_tool(
                "render_notes", {"release": QUIET_RELEASE, "highlights": ["Safer search."]}
            )
        ).data

    assert "## Breaking changes" not in notes
    assert "CH-105 fix(search)" in notes


async def test_workflow_tools_round_trip():
    async with Client(mcp) as client:
        changes = (await client.call_tool("list_changes", {"release": RELEASE})).data
        assert [c["id"] for c in changes] == ["CH-101", "CH-102", "CH-103", "CH-104"]

        note = (await client.call_tool("migration_note", {"change_id": "CH-103"})).data
        assert note["breaking"] is True
        assert note["migration"].startswith("Rename limit to page_size")

        quiet = (await client.call_tool("migration_note", {"change_id": "CH-101"})).data
        assert quiet["breaking"] is False
        assert quiet["migration"] is None

uv run pytest -q

...........                                                              [100%]
11 passed in 0.35s

touch Makefile render_prompt.py

"""Print a prompt's rendered messages as plain text.

A slash command is only a delivery mechanism: what reaches the model is the text
the prompt rendered. Flattening it here lets you pipe the same text into any
client (`claude -p`, a test harness, a diff) and check that the procedure holds
up on its own.

Usage: uv run python render_prompt.py <prompt-name> <release> [audience]
"""

import asyncio
import sys

from fastmcp import Client

from server import mcp


async def main() -> None:
    if len(sys.argv) < 3:
        sys.exit(__doc__.strip().splitlines()[-1])

    name, release = sys.argv[1], sys.argv[2]
    args = {"release": release}
    if len(sys.argv) > 3:
        args["audience"] = sys.argv[3]

    async with Client(mcp) as client:
        result = await client.get_prompt(name, args)

    for message in result.messages:
        content = message.content
        if content.type == "resource":
            print(content.resource.text)
        else:
            print(content.text)
        print()


if __name__ == "__main__":
    asyncio.run(main())

.DEFAULT_GOAL := help

# Claude Code launches the server without your shell's PATH or working
# directory, so the register recipe resolves `uv` and passes the project
# directory explicitly.
NAME    ?= release-prep
RELEASE ?= 2.4.0
UV      := $(shell command -v uv)
DIR     := $(shell pwd)
TOOLS   := mcp__$(NAME)__list_changes mcp__$(NAME)__migration_note mcp__$(NAME)__render_notes

.PHONY: help install demo render workflow serve test test-v register show unregister clean

help:  ## Show this help screen
	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) \
		| awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-12s\033[0m %s\n", $$1, $$2}'

install:  ## Sync runtime and dev dependencies
	uv sync

demo:  ## Render the workflow prompts and run the workflow they describe
	uv run python client.py

render:  ## Print the text draft_release_notes renders (RELEASE=2.4.0)
	uv run python render_prompt.py draft_release_notes $(RELEASE)

workflow:  ## Feed that text to Claude Code and let it run the workflow
	uv run python render_prompt.py draft_release_notes $(RELEASE) \
		| claude -p --allowedTools "$(TOOLS)"

serve:  ## Run the server over stdio (for a real MCP client)
	uv run python server.py

test:  ## Run the test suite
	uv run pytest -q

test-v:  ## Run the test suite verbosely
	uv run pytest -v

register:  ## Register the server with Claude Code (local scope)
	claude mcp add $(NAME) -- $(UV) run --directory $(DIR) python server.py

show:  ## Show the registered server and its connection status
	claude mcp get $(NAME)

unregister:  ## Remove the server from Claude Code
	-claude mcp remove $(NAME)

clean:  ## Remove caches
	rm -rf .pytest_cache __pycache__ tests/__pycache__

make register
make show

release-prep:
  Scope: Local config (private to you in this project)
  Status: ✔ Connected
  Type: stdio
  Command: /opt/homebrew/bin/uv
  Args: run --directory /path/to/mcp-prompt-workflows-macos python server.py
  Environment:

/mcp__release-prep__draft_release_notes 2.4.0
/mcp__release-prep__draft_release_notes 2.4.0 "site operators"
/mcp__release-prep__triage_breaking_changes 2.4.0

make workflow

# 2.4.0

## Highlights

- Find documents even when your query is misspelled — search now matches fuzzily.
- Stay signed in on machines whose clocks drift; refresh tokens no longer expire early.
- Page through API results with the page_size query parameter, which replaces limit.
- Run on Python 3.11 or newer; 3.10 is no longer in the supported test matrix.

## Breaking changes

- CH-103 (api): Replace the limit query parameter with page_size.
  Migration: Rename limit to page_size. The old name is accepted until 3.0.0 and logs a deprecation warning.
- CH-104 (build): Drop Python 3.10 from the supported test matrix.
  Migration: Upgrade to Python 3.11 or newer before installing 2.4.0.

## All changes

- CH-101 feat(search): Add fuzzy matching to the document search index.
- CH-102 fix(auth): Refresh tokens no longer expire early under clock skew.
- CH-103 feat(api): Replace the limit query parameter with page_size.
- CH-104 chore(build): Drop Python 3.10 from the supported test matrix.

3. Write one highlight line per user-visible change, following the policy below.

3. Write exactly one highlight line per change, following the policy below. Do
   not put migration text in a highlight line; `render_notes` builds the
   Breaking changes section from the records itself.