Skip to content

base

Base classes for MCPServer prompts.

Message

Bases: BaseModel

Base class for all prompt messages.

Source code in src/mcp/server/mcpserver/prompts/base.py 
23
24
25
26
27
28
29
30
31
32
class Message(BaseModel):
    """Base class for all prompt messages."""

    role: Literal["user", "assistant"]
    content: ContentBlock

    def __init__(self, content: str | ContentBlock, **kwargs: Any):
        if isinstance(content, str):
            content = TextContent(type="text", text=content)
        super().__init__(content=content, **kwargs)

UserMessage

Bases: Message

A message from the user.

Source code in src/mcp/server/mcpserver/prompts/base.py 
35
36
37
38
39
40
41
class UserMessage(Message):
    """A message from the user."""

    role: Literal["user", "assistant"] = "user"

    def __init__(self, content: str | ContentBlock, **kwargs: Any):
        super().__init__(content=content, **kwargs)

AssistantMessage

Bases: Message

A message from the assistant.

Source code in src/mcp/server/mcpserver/prompts/base.py 
44
45
46
47
48
49
50
class AssistantMessage(Message):
    """A message from the assistant."""

    role: Literal["user", "assistant"] = "assistant"

    def __init__(self, content: str | ContentBlock, **kwargs: Any):
        super().__init__(content=content, **kwargs)

PromptArgument

Bases: BaseModel

An argument that can be passed to a prompt.

Source code in src/mcp/server/mcpserver/prompts/base.py 
59
60
61
62
63
64
class PromptArgument(BaseModel):
    """An argument that can be passed to a prompt."""

    name: str = Field(description="Name of the argument")
    description: str | None = Field(None, description="Description of what the argument does")
    required: bool = Field(default=False, description="Whether the argument is required")

Prompt

Bases: BaseModel

A prompt template that can be rendered with parameters.

Source code in src/mcp/server/mcpserver/prompts/base.py 
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
class Prompt(BaseModel):
    """A prompt template that can be rendered with parameters."""

    name: str = Field(description="Name of the prompt")
    title: str | None = Field(None, description="Human-readable title of the prompt")
    description: str | None = Field(None, description="Description of what the prompt does")
    arguments: list[PromptArgument] | None = Field(None, description="Arguments that can be passed to the prompt")
    fn: Callable[..., PromptResult | Awaitable[PromptResult]] = Field(exclude=True)
    icons: list[Icon] | None = Field(default=None, description="Optional list of icons for this prompt")
    context_kwarg: str | None = Field(None, description="Name of the kwarg that should receive context", exclude=True)

    @classmethod
    def from_function(
        cls,
        fn: Callable[..., PromptResult | Awaitable[PromptResult]],
        name: str | None = None,
        title: str | None = None,
        description: str | None = None,
        icons: list[Icon] | None = None,
        context_kwarg: str | None = None,
    ) -> Prompt:
        """Create a Prompt from a function.

        The function can return:
        - A string (converted to a message)
        - A Message object
        - A dict (converted to a message)
        - A sequence of any of the above
        """
        func_name = name or fn.__name__

        if func_name == "<lambda>":  # pragma: no cover
            raise ValueError("You must provide a name for lambda functions")

        # Find context parameter if it exists
        if context_kwarg is None:  # pragma: no branch
            context_kwarg = find_context_parameter(fn)

        # Get schema from func_metadata, excluding context parameter
        func_arg_metadata = func_metadata(
            fn,
            skip_names=[context_kwarg] if context_kwarg is not None else [],
        )
        parameters = func_arg_metadata.arg_model.model_json_schema()

        # Convert parameters to PromptArguments
        arguments: list[PromptArgument] = []
        if "properties" in parameters:  # pragma: no branch
            for param_name, param in parameters["properties"].items():
                required = param_name in parameters.get("required", [])
                arguments.append(
                    PromptArgument(
                        name=param_name,
                        description=param.get("description"),
                        required=required,
                    )
                )

        # ensure the arguments are properly cast
        fn = validate_call(fn)

        return cls(
            name=func_name,
            title=title,
            description=description or fn.__doc__ or "",
            arguments=arguments,
            fn=fn,
            icons=icons,
            context_kwarg=context_kwarg,
        )

    async def render(
        self,
        arguments: dict[str, Any] | None,
        context: Context[LifespanContextT, RequestT],
    ) -> list[Message]:
        """Render the prompt with arguments.

        Raises:
            ValueError: If required arguments are missing, or if rendering fails.
        """
        # Validate required arguments
        if self.arguments:
            required = {arg.name for arg in self.arguments if arg.required}
            provided = set(arguments or {})
            missing = required - provided
            if missing:
                raise ValueError(f"Missing required arguments: {missing}")

        try:
            # Add context to arguments if needed
            call_args = inject_context(self.fn, arguments or {}, context, self.context_kwarg)

            fn = self.fn
            if is_async_callable(fn):
                result = await fn(**call_args)
            else:
                result = await anyio.to_thread.run_sync(functools.partial(self.fn, **call_args))

            # Validate messages
            if not isinstance(result, list | tuple):
                result = [result]

            # Convert result to messages
            messages: list[Message] = []
            for msg in result:  # type: ignore[reportUnknownVariableType]
                try:
                    if isinstance(msg, Message):
                        messages.append(msg)
                    elif isinstance(msg, dict):
                        messages.append(message_validator.validate_python(msg))
                    elif isinstance(msg, str):
                        content = TextContent(type="text", text=msg)
                        messages.append(UserMessage(content=content))
                    else:  # pragma: no cover
                        content = pydantic_core.to_json(msg, fallback=str, indent=2).decode()
                        messages.append(Message(role="user", content=content))
                except Exception:  # pragma: no cover
                    raise ValueError(f"Could not convert prompt result to message: {msg}")

            return messages
        except Exception as e:  # pragma: no cover
            raise ValueError(f"Error rendering prompt {self.name}: {e}")

from_function classmethod 

from_function(
    fn: Callable[
        ..., PromptResult | Awaitable[PromptResult]
    ],
    name: str | None = None,
    title: str | None = None,
    description: str | None = None,
    icons: list[Icon] | None = None,
    context_kwarg: str | None = None,
) -> Prompt

Create a Prompt from a function.

The function can return: - A string (converted to a message) - A Message object - A dict (converted to a message) - A sequence of any of the above

Source code in src/mcp/server/mcpserver/prompts/base.py 
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
@classmethod
def from_function(
    cls,
    fn: Callable[..., PromptResult | Awaitable[PromptResult]],
    name: str | None = None,
    title: str | None = None,
    description: str | None = None,
    icons: list[Icon] | None = None,
    context_kwarg: str | None = None,
) -> Prompt:
    """Create a Prompt from a function.

    The function can return:
    - A string (converted to a message)
    - A Message object
    - A dict (converted to a message)
    - A sequence of any of the above
    """
    func_name = name or fn.__name__

    if func_name == "<lambda>":  # pragma: no cover
        raise ValueError("You must provide a name for lambda functions")

    # Find context parameter if it exists
    if context_kwarg is None:  # pragma: no branch
        context_kwarg = find_context_parameter(fn)

    # Get schema from func_metadata, excluding context parameter
    func_arg_metadata = func_metadata(
        fn,
        skip_names=[context_kwarg] if context_kwarg is not None else [],
    )
    parameters = func_arg_metadata.arg_model.model_json_schema()

    # Convert parameters to PromptArguments
    arguments: list[PromptArgument] = []
    if "properties" in parameters:  # pragma: no branch
        for param_name, param in parameters["properties"].items():
            required = param_name in parameters.get("required", [])
            arguments.append(
                PromptArgument(
                    name=param_name,
                    description=param.get("description"),
                    required=required,
                )
            )

    # ensure the arguments are properly cast
    fn = validate_call(fn)

    return cls(
        name=func_name,
        title=title,
        description=description or fn.__doc__ or "",
        arguments=arguments,
        fn=fn,
        icons=icons,
        context_kwarg=context_kwarg,
    )

render async 

render(
    arguments: dict[str, Any] | None,
    context: Context[LifespanContextT, RequestT],
) -> list[Message]

Render the prompt with arguments.

Raises:

Type Description
ValueError

If required arguments are missing, or if rendering fails.
Source code in src/mcp/server/mcpserver/prompts/base.py 
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
async def render(
    self,
    arguments: dict[str, Any] | None,
    context: Context[LifespanContextT, RequestT],
) -> list[Message]:
    """Render the prompt with arguments.

    Raises:
        ValueError: If required arguments are missing, or if rendering fails.
    """
    # Validate required arguments
    if self.arguments:
        required = {arg.name for arg in self.arguments if arg.required}
        provided = set(arguments or {})
        missing = required - provided
        if missing:
            raise ValueError(f"Missing required arguments: {missing}")

    try:
        # Add context to arguments if needed
        call_args = inject_context(self.fn, arguments or {}, context, self.context_kwarg)

        fn = self.fn
        if is_async_callable(fn):
            result = await fn(**call_args)
        else:
            result = await anyio.to_thread.run_sync(functools.partial(self.fn, **call_args))

        # Validate messages
        if not isinstance(result, list | tuple):
            result = [result]

        # Convert result to messages
        messages: list[Message] = []
        for msg in result:  # type: ignore[reportUnknownVariableType]
            try:
                if isinstance(msg, Message):
                    messages.append(msg)
                elif isinstance(msg, dict):
                    messages.append(message_validator.validate_python(msg))
                elif isinstance(msg, str):
                    content = TextContent(type="text", text=msg)
                    messages.append(UserMessage(content=content))
                else:  # pragma: no cover
                    content = pydantic_core.to_json(msg, fallback=str, indent=2).decode()
                    messages.append(Message(role="user", content=content))
            except Exception:  # pragma: no cover
                raise ValueError(f"Could not convert prompt result to message: {msg}")

        return messages
    except Exception as e:  # pragma: no cover
        raise ValueError(f"Error rendering prompt {self.name}: {e}")