mirror of https://github.com/PrefectHQ/fastmcp.git synced 2026-08-09 15:19:10 +02:00

Jeremiah Lowin 4b09a040be

Unpublish v4 development notes; prep docs for beta 1 (#4644 )

* Unpublish v4 development notes; prep docs for beta 1

* Nest development notes under dev-docs/

* Rewrite site-root links in dev notes as absolute URLs for GitHub rendering

2026-07-26 14:08:34 -04:00

3 KiB

Raw Permalink Blame History

Prompt Internal Types - Message and PromptResult

Version: 3.0.0 Impact: Breaking change for prompts returning mcp.types.PromptMessage

Summary

Prompts now use FastMCP's Message and PromptResult types internally, following the same pattern as resources (#2734). MCP SDK types are only used at the protocol boundary.

What Changed

Before (v2.x)

from mcp.types import PromptMessage, TextContent

@mcp.prompt
def my_prompt() -> PromptMessage:
    return PromptMessage(
        role="user",
        content=TextContent(type="text", text="Hello")
    )

After (v3.0)

from fastmcp.prompts import Message

@mcp.prompt
def my_prompt() -> Message:
    return Message("Hello")  # role defaults to "user"

Type Constraints

Prompt Function Return Types

str | list[Message | str] | PromptResult

Valid:

return "Hello" → wrapped as single user Message
return [Message("Hi"), Message("Response", role="assistant")]
return ["Hi", "Response"] → strings auto-wrapped as user Messages
return PromptResult(messages=[...], meta={...})

Invalid (now raises error):

return PromptMessage(...) → Use Message instead
return Message(...) as single value → Use PromptResult([Message(...)]) or return a list

Message Class

Message(
    content: Any,  # Auto-serializes non-str to JSON
    role: Literal["user", "assistant"] = "user"
)

Auto-Serialization:

str → passes through as TextContent
dict → JSON-serialized to text
list → JSON-serialized to text
BaseModel → JSON-serialized to text
TextContent / EmbeddedResource → passes through directly

PromptResult Class

PromptResult(
    messages: str | list[Message],  # str wrapped as single Message
    description: str | None = None,
    meta: dict[str, Any] | None = None
)

Why This Change?

Simpler API - Message("Hello") vs PromptMessage(role="user", content=TextContent(type="text", text="Hello"))
Auto-serialization - Dicts/lists/models automatically become JSON
Consistent with resources - Same pattern as ResourceContent/ResourceResult
Type safety - Strict typing catches errors at development time

Migration Guide

Simple Message

# Before
from mcp.types import PromptMessage, TextContent
return PromptMessage(role="user", content=TextContent(type="text", text="Hello"))

# After
from fastmcp.prompts import Message
return Message("Hello")

Conversation

# Before
return [
    PromptMessage(role="user", content=TextContent(type="text", text="Hi")),
    PromptMessage(role="assistant", content=TextContent(type="text", text="Hello!")),
]

# After
return [
    Message("Hi"),
    Message("Hello!", role="assistant"),
]

With Metadata

from fastmcp.prompts import Message, PromptResult

return PromptResult(
    messages=[Message("Analyze this")],
    meta={"priority": "high"}
)

PR

#2738 - Introduce Message and PromptResult as canonical prompt types

3 KiB Raw Permalink Blame History