Introduce Message and PromptResult as canonical prompt types#2738
Introduce Message and PromptResult as canonical prompt types#2738
Conversation
Convert Message from factory function to class with auto-serialization. PromptResult now enforces strict typing: str | list[Message]. Breaking change: mcp.types.PromptMessage no longer supported as return type.
jlowin
added
the
feature
marvin-context-protocol
Bot
added
the
breaking change
WalkthroughThis PR replaces the previous PromptMessage/TextContent return model with a new Message pydantic model and a PromptResult wrapper. Prompt.render() now accepts/returns str, list[Message | str], or PromptResult; Prompt.convert_result() normalizes raw outputs to PromptResult. FunctionPrompt/from_function signatures were loosened to Callable[..., Any]. Server caching and proxy layers were updated to wrap/unwrap cached prompt results and to convert runtime messages to the new Message type. Documentation and public examples were updated to reference Message and the new serialization rules. Possibly related PRs
Pre-merge checks and finishing touches❌ Failed checks (1 warning, 1 inconclusive)
✅ Passed checks (1 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (5)
tests/client/tasks/test_prompt_task_mcp_message.pyis excluded by none and included by nonetests/prompts/test_prompt.pyis excluded by none and included by nonetests/server/middleware/test_caching.pyis excluded by none and included by nonetests/server/providers/test_local_provider_prompts.pyis excluded by none and included by nonetests/server/test_server_interactions.pyis excluded by none and included by none
📒 Files selected for processing (5)
docs/development/upgrade-guide.mdxdocs/servers/prompts.mdxsrc/fastmcp/prompts/prompt.pysrc/fastmcp/server/middleware/caching.pysrc/fastmcp/server/providers/proxy.py
🧰 Additional context used
📓 Path-based instructions (4)
docs/**/*.mdx
📄 CodeRabbit inference engine (docs/.cursor/rules/mintlify.mdc)
docs/**/*.mdx: Use clear, direct language appropriate for technical audiences
Write in second person ('you') for instructions and procedures in MDX documentation
Use active voice over passive voice in MDX technical documentation
Employ present tense for current states and future tense for outcomes in MDX documentation
Maintain consistent terminology throughout all MDX documentation
Keep sentences concise while providing necessary context in MDX documentation
Use parallel structure in lists, headings, and procedures in MDX documentation
Lead with the most important information using inverted pyramid structure in MDX documentation
Use progressive disclosure in MDX documentation: present basic concepts before advanced ones
Break complex procedures into numbered steps in MDX documentation
Include prerequisites and context before instructions in MDX documentation
Provide expected outcomes for each major step in MDX documentation
End sections with next steps or related information in MDX documentation
Use descriptive, keyword-rich headings for navigation and SEO in MDX documentation
Focus on user goals and outcomes rather than system features in MDX documentation
Anticipate common questions and address them proactively in MDX documentation
Include troubleshooting for likely failure points in MDX documentation
Provide multiple pathways (beginner vs advanced) but offer an opinionated path to avoid overwhelming users in MDX documentation
Always include complete, runnable code examples that users can copy and execute in MDX documentation
Show proper error handling and edge case management in MDX code examples
Use realistic data instead of placeholder values in MDX code examples
Include expected outputs and results for verification in MDX code examples
Test all code examples thoroughly before publishing in MDX documentation
Specify language and include filename when relevant in MDX code examples
Add explanatory comments for complex logic in MDX code examples
Document all API...
Files:
docs/development/upgrade-guide.mdxdocs/servers/prompts.mdx
docs/**/*.{md,mdx,json}
📄 CodeRabbit inference engine (AGENTS.md)
Documentation uses Mintlify framework. Files must be in docs.json to be included. Never modify docs/python-sdk/** (auto-generated)
Files:
docs/development/upgrade-guide.mdxdocs/servers/prompts.mdx
docs/**/*.{md,mdx}
📄 CodeRabbit inference engine (AGENTS.md)
docs/**/*.{md,mdx}: Code examples in documentation must explain before showing code and make blocks fully runnable (include imports)
Documentation structure: Headers form navigation guide with logical H2/H3 hierarchy. Content should be user-focused with sections motivating features (why) before mechanics (how). Use prose over code comments for important information
Never use 'This isn't...' or 'not just...' constructions in writing - state what something IS directly. Avoid defensive writing patterns
Files:
docs/development/upgrade-guide.mdxdocs/servers/prompts.mdx
src/fastmcp/**/*.py
📄 CodeRabbit inference engine (AGENTS.md)
src/fastmcp/**/*.py: Python ≥ 3.10 with full type annotations required
Prioritize readable, understandable code - clarity over cleverness. Avoid obfuscated or confusing patterns even if shorter
Follow existing patterns and maintain consistency in code implementation
Be intentional about re-exports - don't blindly re-export everything to parent namespaces. Core types defining a module's purpose should be exported. Specialized features can live in submodules. Only re-export to fastmcp.* for most fundamental types
Never use bare except - be specific with exception types
Files:
src/fastmcp/server/middleware/caching.pysrc/fastmcp/server/providers/proxy.pysrc/fastmcp/prompts/prompt.py
🧠 Learnings (2)
📚 Learning: 2025-12-25T15:53:07.646Z
Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-25T15:53:07.646Z
Learning: Applies to src/fastmcp/**/*.py : Python ≥ 3.10 with full type annotations required
Applied to files:
docs/development/upgrade-guide.mdxsrc/fastmcp/server/middleware/caching.pydocs/servers/prompts.mdxsrc/fastmcp/server/providers/proxy.pysrc/fastmcp/prompts/prompt.py
📚 Learning: 2025-12-25T15:53:07.646Z
Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-25T15:53:07.646Z
Learning: Applies to tests/**/*.py : Pass FastMCP servers directly to clients for testing without network complexity; only use HTTP transport when explicitly testing network features
Applied to files:
docs/servers/prompts.mdxsrc/fastmcp/server/providers/proxy.py
🧬 Code graph analysis (2)
src/fastmcp/server/middleware/caching.py (1)
src/fastmcp/prompts/prompt.py (3)
Message(42-95)Prompt(195-365)PromptResult(110-192)
src/fastmcp/server/providers/proxy.py (1)
src/fastmcp/prompts/prompt.py (3)
Message(42-95)Prompt(195-365)PromptResult(110-192)
🪛 Ruff (0.14.10)
src/fastmcp/prompts/prompt.py
176-179: Avoid specifying long messages outside the exception class
(TRY003)
181-183: Avoid specifying long messages outside the exception class
(TRY003)
299-302: Avoid specifying long messages outside the exception class
(TRY003)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)
- GitHub Check: Run tests: Python 3.10 on windows-latest
- GitHub Check: Run tests: Python 3.13 on ubuntu-latest
- GitHub Check: Run tests: Python 3.10 on ubuntu-latest
- GitHub Check: Run tests with lowest-direct dependencies
🔇 Additional comments (16)
docs/development/upgrade-guide.mdx (1)
119-151: LGTM! Clear migration documentation with accurate before/after examples.The upgrade section effectively documents the breaking change with:
- Complete, runnable code examples showing the migration path
- Key changes clearly bullet-pointed
- Appropriate link to detailed documentation
docs/servers/prompts.mdx (3)
31-45: LGTM! Import path and Message usage are correct.The updated import and function signature properly demonstrate the new Message-centric API.
191-209: LGTM! Return values documentation accurately reflects the implementation.The documented return types (
str,list[Message | str],PromptResult) correctly match thePrompt.render()signature and theconvert_result()normalization logic.
211-244: LGTM! Comprehensive Message documentation with clear examples.The new Message section effectively documents:
- Auto-serialization behavior for different content types
- Role parameter with default
- Proper ParamField component usage for API documentation
src/fastmcp/server/providers/proxy.py (2)
36-36: LGTM! Import updated to include Message.The import correctly pulls
Messagefromfastmcp.promptsalongsidePromptandPromptResult.
408-414: LGTM! Correct conversion from MCP PromptMessages to Message objects.The conversion properly handles the MCP response by:
- Extracting
contentandrolefrom each MCPPromptMessage- Wrapping them in
Messageobjects (which correctly pass throughTextContent/EmbeddedResourcecontent types)- Constructing
PromptResultwith the converted messagessrc/fastmcp/server/middleware/caching.py (4)
20-20: LGTM! Import updated to support new caching wrappers.
99-134: Cachable wrappers correctly implement wrap/unwrap pattern.The
CachableMessageandCachablePromptResultclasses follow the established pattern fromCachableResourceResultandCachableToolResult.One observation:
CachableMessage.roleis typed asstrwhileMessage.roleisLiteral["user", "assistant"]. This is acceptable for caching since the data originates from validMessageobjects, but consider adding validation inunwrap()if you want defense-in-depth against corrupted cache data.
273-277: LGTM! Cache adapter correctly typed for CachablePromptResult.
474-485: LGTM! Prompt caching correctly wraps and unwraps PromptResult.The flow properly:
- Unwraps cached
CachablePromptResulttoPromptResulton cache hit- Wraps fresh
PromptResulttoCachablePromptResultbefore cachingsrc/fastmcp/prompts/prompt.py (6)
42-95: LGTM! Well-designed Message class with clear auto-serialization behavior.The implementation correctly:
- Handles passthrough for already-wrapped content types
- Converts strings to
TextContent- JSON-serializes complex types with a safe
fallback=str- Provides clean conversion to MCP types via
to_mcp_prompt_message()
110-192: LGTM! PromptResult properly normalizes inputs and provides clear error messages.The
_normalize_messagesmethod correctly validates inputs and provides actionable error messages when invalid types are passed. The static analysis hint about long exception messages (TRY003) can be safely ignored here—the informative messages improve developer experience.
231-272: LGTM! Updated signatures support the new Message-centric API.The relaxed
fn: Callable[..., Any]type and updatedrender()return signature properly accommodate the new flexible prompt return types.
274-308: LGTM! convert_result correctly normalizes prompt return values.The method properly handles:
PromptResultpassthroughstrwrapped as single-messagePromptResultlist|tuplewith item-by-item conversionNote: Single
Messageobjects are not directly supported (as previously flagged in the documentation review).
368-555: LGTM! FunctionPrompt updated consistently with the new type system.The
fnfield type andfrom_functionsignature changes are consistent with the basePromptclass. Therender()method correctly usesconvert_result()for normalization.
334-336: LGTM! Server entry point correctly normalizes via convert_result.This ensures all prompt execution paths produce consistent
PromptResultobjects.
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (2)
tests/prompts/test_prompt.pyis excluded by none and included by nonetests/server/test_server_interactions.pyis excluded by none and included by none
📒 Files selected for processing (1)
docs/servers/prompts.mdx
🧰 Additional context used
📓 Path-based instructions (3)
docs/**/*.mdx
📄 CodeRabbit inference engine (docs/.cursor/rules/mintlify.mdc)
docs/**/*.mdx: Use clear, direct language appropriate for technical audiences
Write in second person ('you') for instructions and procedures in MDX documentation
Use active voice over passive voice in MDX technical documentation
Employ present tense for current states and future tense for outcomes in MDX documentation
Maintain consistent terminology throughout all MDX documentation
Keep sentences concise while providing necessary context in MDX documentation
Use parallel structure in lists, headings, and procedures in MDX documentation
Lead with the most important information using inverted pyramid structure in MDX documentation
Use progressive disclosure in MDX documentation: present basic concepts before advanced ones
Break complex procedures into numbered steps in MDX documentation
Include prerequisites and context before instructions in MDX documentation
Provide expected outcomes for each major step in MDX documentation
End sections with next steps or related information in MDX documentation
Use descriptive, keyword-rich headings for navigation and SEO in MDX documentation
Focus on user goals and outcomes rather than system features in MDX documentation
Anticipate common questions and address them proactively in MDX documentation
Include troubleshooting for likely failure points in MDX documentation
Provide multiple pathways (beginner vs advanced) but offer an opinionated path to avoid overwhelming users in MDX documentation
Always include complete, runnable code examples that users can copy and execute in MDX documentation
Show proper error handling and edge case management in MDX code examples
Use realistic data instead of placeholder values in MDX code examples
Include expected outputs and results for verification in MDX code examples
Test all code examples thoroughly before publishing in MDX documentation
Specify language and include filename when relevant in MDX code examples
Add explanatory comments for complex logic in MDX code examples
Document all API...
Files:
docs/servers/prompts.mdx
docs/**/*.{md,mdx,json}
📄 CodeRabbit inference engine (AGENTS.md)
Documentation uses Mintlify framework. Files must be in docs.json to be included. Never modify docs/python-sdk/** (auto-generated)
Files:
docs/servers/prompts.mdx
docs/**/*.{md,mdx}
📄 CodeRabbit inference engine (AGENTS.md)
docs/**/*.{md,mdx}: Code examples in documentation must explain before showing code and make blocks fully runnable (include imports)
Documentation structure: Headers form navigation guide with logical H2/H3 hierarchy. Content should be user-focused with sections motivating features (why) before mechanics (how). Use prose over code comments for important information
Never use 'This isn't...' or 'not just...' constructions in writing - state what something IS directly. Avoid defensive writing patterns
Files:
docs/servers/prompts.mdx
🧠 Learnings (2)
📚 Learning: 2025-12-25T15:53:07.646Z
Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-25T15:53:07.646Z
Learning: Applies to src/fastmcp/**/*.py : Python ≥ 3.10 with full type annotations required
Applied to files:
docs/servers/prompts.mdx
📚 Learning: 2025-12-25T15:53:07.646Z
Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-25T15:53:07.646Z
Learning: Applies to tests/**/*.py : Pass FastMCP servers directly to clients for testing without network complexity; only use HTTP transport when explicitly testing network features
Applied to files:
docs/servers/prompts.mdx
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)
- GitHub Check: Run tests: Python 3.13 on ubuntu-latest
- GitHub Check: Run tests: Python 3.10 on windows-latest
- GitHub Check: Run tests: Python 3.10 on ubuntu-latest
- GitHub Check: Run tests with lowest-direct dependencies
| def generate_code_request(language: str, task_description: str) -> Message: | ||
| """Generates a user message requesting code generation.""" | ||
| content = f"Write a {language} function that performs the following task: {task_description}" | ||
| return PromptMessage(role="user", content=TextContent(type="text", text=content)) | ||
| return Message(f"Write a {language} function that performs the following task: {task_description}") |
There was a problem hiding this comment.
Critical: Example contradicts documented return types.
This example shows returning a single Message object with type annotation -> Message, but the documented return types (lines 193-197) only support str, list[Message | str], or PromptResult. Line 293 confirms single Message is not supported. Users following this example will encounter runtime errors.
🔎 Fix: Update example to return a supported type
Option 1: Return a string (simplest):
@mcp.prompt
-def generate_code_request(language: str, task_description: str) -> Message:
+def generate_code_request(language: str, task_description: str) -> str:
"""Generates a user message requesting code generation."""
- return Message(f"Write a {language} function that performs the following task: {task_description}")
+ return f"Write a {language} function that performs the following task: {task_description}"Option 2: Return a list (shows Message usage):
@mcp.prompt
-def generate_code_request(language: str, task_description: str) -> Message:
+def generate_code_request(language: str, task_description: str) -> list[Message]:
"""Generates a user message requesting code generation."""
- return Message(f"Write a {language} function that performs the following task: {task_description}")
+ return [Message(f"Write a {language} function that performs the following task: {task_description}")]Option 3: Return PromptResult (shows metadata capability):
+from fastmcp.prompts import PromptResult, Message
+
@mcp.prompt
-def generate_code_request(language: str, task_description: str) -> Message:
+def generate_code_request(language: str, task_description: str) -> PromptResult:
"""Generates a user message requesting code generation."""
- return Message(f"Write a {language} function that performs the following task: {task_description}")
+ return PromptResult(Message(f"Write a {language} function that performs the following task: {task_description}"))📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| def generate_code_request(language: str, task_description: str) -> Message: | |
| """Generates a user message requesting code generation.""" | |
| content = f"Write a {language} function that performs the following task: {task_description}" | |
| return PromptMessage(role="user", content=TextContent(type="text", text=content)) | |
| return Message(f"Write a {language} function that performs the following task: {task_description}") | |
| def generate_code_request(language: str, task_description: str) -> str: | |
| """Generates a user message requesting code generation.""" | |
| return f"Write a {language} function that performs the following task: {task_description}" |
1 participant
Prompts now follow the same pattern as resources (PR #2734): FastMCP types internally, MCP SDK types at the boundary. Follows up on #2610
Messageis now a proper class with auto-serialization—dicts, lists, and Pydantic models are JSON-serialized automatically:Breaking change: Returning
mcp.types.PromptMessagedirectly is no longer supported. UseMessageinstead.