Prompts are reusable message templates that help LLMs generate structured, purposeful responses. FlashMCP simplifies defining these templates, primarily using the @mcp.prompt decorator.
What Are Prompts?
Prompts provide parameterized message templates for LLMs. When a client requests a prompt:
- FlashMCP finds the corresponding prompt definition.
- If it has parameters, they are validated against your function signature.
- Your function executes with the validated inputs.
- The generated message(s) are returned to the LLM to guide its response.
This allows you to define consistent, reusable templates that LLMs can use across different clients and contexts.
Prompts
The @prompt Decorator
The most common way to define a prompt is by decorating a Python function. The decorator uses the function name as the prompt’s identifier.
from FlashMCP import FlashMCP
from FlashMCP.prompts.prompt import Message, PromptMessage, TextContent
mcp = FlashMCP(name="PromptServer")
# Basic prompt returning a string (converted to user message automatically)
@mcp.prompt()
def ask_about_topic(topic: str) -> str:
"""Generates a user message asking for an explanation of a topic."""
return f"Can you please explain the concept of '{topic}'?"
# Prompt returning a specific message type
@mcp.prompt()
def generate_code_request(language: str, task_description: str) -> PromptMessage:
"""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))
- Name: By default, the prompt name is taken from the function name.
- Parameters: The function parameters define the inputs needed to generate the prompt.
- Inferred Metadata: By default:
- Prompt Name: Taken from the function name (
ask_about_topic).
- Prompt Description: Taken from the function’s docstring.
Functions with *args or **kwargs are not supported as prompts. This restriction exists because FlashMCP needs to generate a complete parameter schema for the MCP protocol, which isn’t possible with variable argument lists.
Return Values
FlashMCP intelligently handles different return types from your prompt function:
str: Automatically converted to a single PromptMessage.PromptMessage: Used directly as provided. (Note a more user-friendly Message constructor is available that can accept raw strings instead of TextContent objects.)list[PromptMessage | str]: Used as a sequence of messages (a conversation).Any: If the return type is not one of the above, the return value is attempted to be converted to a string and used as a PromptMessage.
from FlashMCP.prompts.prompt import Message
@mcp.prompt()
def roleplay_scenario(character: str, situation: str) -> list[Message]:
"""Sets up a roleplaying scenario with initial messages."""
return [
Message(f"Let's roleplay. You are {character}. The situation is: {situation}"),
Message("Okay, I understand. I am ready. What happens next?", role="assistant")
]
Type Annotations
Type annotations are important for prompts. They:
- Inform FlashMCP about the expected types for each parameter.
- Allow validation of parameters received from clients.
- Are used to generate the prompt’s schema for the MCP protocol.
from pydantic import Field
from typing import Literal, Optional
@mcp.prompt()
def generate_content_request(
topic: str = Field(description="The main subject to cover"),
format: Literal["blog", "email", "social"] = "blog",
tone: str = "professional",
word_count: Optional[int] = None
) -> str:
"""Create a request for generating content in a specific format."""
prompt = f"Please write a {format} post about {topic} in a {tone} tone."
if word_count:
prompt += f" It should be approximately {word_count} words long."
return prompt
Required vs. Optional Parameters
Parameters in your function signature are considered required unless they have a default value.
@mcp.prompt()
def data_analysis_prompt(
data_uri: str, # Required - no default value
analysis_type: str = "summary", # Optional - has default value
include_charts: bool = False # Optional - has default value
) -> str:
"""Creates a request to analyze data with specific parameters."""
prompt = f"Please perform a '{analysis_type}' analysis on the data found at {data_uri}."
if include_charts:
prompt += " Include relevant charts and visualizations."
return prompt
data_uri. If analysis_type or include_charts are omitted, their default values will be used.
While FlashMCP infers the name and description from your function, you can override these and add tags using arguments to the @mcp.prompt decorator:
@mcp.prompt(
name="analyze_data_request", # Custom prompt name
description="Creates a request to analyze data with specific parameters", # Custom description
tags={"analysis", "data"} # Optional categorization tags
)
def data_analysis_prompt(
data_uri: str = Field(description="The URI of the resource containing the data."),
analysis_type: str = Field(default="summary", description="Type of analysis.")
) -> str:
"""This docstring is ignored when description is provided."""
return f"Please perform a '{analysis_type}' analysis on the data found at {data_uri}."
name: Sets the explicit prompt name exposed via MCP.description: Provides the description exposed via MCP. If set, the function’s docstring is ignored for this purpose.tags: A set of strings used to categorize the prompt. Clients might use tags to filter or group available prompts.
Asynchronous Prompts
FlashMCP seamlessly supports both standard (def) and asynchronous (async def) functions as prompts.
# Synchronous prompt
@mcp.prompt()
def simple_question(question: str) -> str:
"""Generates a simple question to ask the LLM."""
return f"Question: {question}"
# Asynchronous prompt
@mcp.prompt()
async def data_based_prompt(data_id: str) -> str:
"""Generates a prompt based on data that needs to be fetched."""
# In a real scenario, you might fetch data from a database or API
async with aiohttp.ClientSession() as session:
async with session.get(f"https://api.example.com/data/{data_id}") as response:
data = await response.json()
return f"Analyze this data: {data['content']}"
async def when your prompt function performs I/O operations like network requests, database queries, file I/O, or external service calls.
Accessing MCP Context
New in version: 2.2.5
Context object. To access it, add a parameter to your prompt function with a type annotation of Context:
from FlashMCP import FlashMCP, Context
mcp = FlashMCP(name="PromptServer")
@mcp.prompt()
async def generate_report_request(report_type: str, ctx: Context) -> str:
"""Generates a request for a report."""
return f"Please create a {report_type} report. Request ID: {ctx.request_id}"
Server Behavior
Duplicate Prompts
New in version: 2.1.0
on_duplicate_prompts setting during FlashMCP initialization.
from FlashMCP import FlashMCP
mcp = FlashMCP(
name="PromptServer",
on_duplicate_prompts="error" # Raise an error if a prompt name is duplicated
)
@mcp.prompt()
def greeting(): return "Hello, how can I help you today?"
# This registration attempt will raise a ValueError because
# "greeting" is already registered and the behavior is "error".
# @mcp.prompt()
# def greeting(): return "Hi there! What can I do for you?"
"warn" (default): Logs a warning, and the new prompt replaces the old one."error": Raises a ValueError, preventing the duplicate registration."replace": Silently replaces the existing prompt with the new one."ignore": Keeps the original prompt and ignores the new registration attempt.