π The fast, Pythonic way to build MCP servers and clients.
Carry prompt argument titles through PromptArgument and proxies (#5749)
Aarnav Noble288485cc2c5a
diff --git a/docs/servers/prompts.mdx b/docs/servers/prompts.mdxindex 1986a50bf..e12791ae9 100644--- a/docs/servers/prompts.mdx+++ b/docs/servers/prompts.mdx@@ -219,6 +219,26 @@ The free-form text above the `Args` section β whether a single line or multiplIf an argument already has an explicit description β via `Annotated[x, "..."]` or `Field(description=...)` β that description takes precedence over the docstring. This makes it safe to adopt docstring-based descriptions incrementally: existing annotations keep working, and docstrings fill in the gaps.+### Argument Titles++An argument's name is what clients send, so it is usually short. To show clients a human-readable label instead, give the parameter a title with `Field(title=...)`:++```python+from typing import Annotated++from pydantic import Field+++def write_story(+ topic: Annotated[str, Field(title="Story topic")],+ tone: str = Field(default="playful", title="Tone of voice"),+) -> str:+ return f"Write a {tone} short story about {topic}."+```++The title becomes the `title` of the corresponding `PromptArgument` in the MCP protocol. Arguments without an explicit title are listed without one. A proxy keeps the argument titles its backend lists.+### Return ValuesPrompt functions must return one of these types:diff --git a/fastmcp_slim/fastmcp/prompts/base.py b/fastmcp_slim/fastmcp/prompts/base.pyindex c9c8e7625..ef38cd62c 100644--- a/fastmcp_slim/fastmcp/prompts/base.py+++ b/fastmcp_slim/fastmcp/prompts/base.py@@ -99,6 +99,9 @@ class PromptArgument(FastMCPBaseModel):"""An argument that can be passed to a prompt."""name: str = Field(description="Name of the argument")+ title: str | None = Field(+ default=None, description="Human-readable name of the argument for display"+ )description: str | None = Field(default=None, description="Description of what the argument does")@@ -241,6 +244,7 @@ class Prompt(FastMCPComponent):arguments = [SDKPromptArgument(name=arg.name,+ title=arg.title,description=arg.description,required=arg.required,)diff --git a/fastmcp_slim/fastmcp/prompts/function_prompt.py b/fastmcp_slim/fastmcp/prompts/function_prompt.pyindex b8c2cd300..bac7362b1 100644--- a/fastmcp_slim/fastmcp/prompts/function_prompt.py+++ b/fastmcp_slim/fastmcp/prompts/function_prompt.py@@ -15,12 +15,14 @@ from typing import (Protocol,TypeVar,cast,+ get_type_hints,overload,runtime_checkable,)import pydantic_corefrom mcp_types import Icon+from pydantic.fields import FieldInfofrom pydantic.json_schema import SkipJsonSchemafrom fastmcp.exceptions import PromptError, ValidationError@@ -203,6 +205,8 @@ class FunctionPrompt(Prompt):):properties[param_name]["description"] = param_desc+ titles = _explicit_parameter_titles(fn)+# Convert parameters to PromptArgumentsarguments: list[PromptArgument] = []if "properties" in parameters:@@ -245,6 +249,7 @@ class FunctionPrompt(Prompt):arguments.append(PromptArgument(name=param_name,+ title=titles.get(param_name),description=arg_description,required=param_name in parameters.get("required", []),)@@ -460,3 +465,31 @@ def prompt(return decorator(fn, prompt_name)return wrapper+++def _explicit_parameter_titles(fn: Callable[..., Any]) -> dict[str, str]:+ """Return the titles set with `Field(title=...)` on fn's parameters.++ The parameter schema cannot tell these apart from the titles Pydantic+ generates for every parameter, and they are pruned from it, so read them+ from the annotations and defaults instead.+ """+ try:+ hints = get_type_hints(fn, include_extras=True)+ except Exception:+ # Unresolvable annotations: titles set as defaults still count.+ hints = {}+ titles: dict[str, str] = {}+ for name, param in inspect.signature(fn).parameters.items():+ annotation = hints.get(name, param.annotation)+ if annotation is inspect.Parameter.empty or isinstance(annotation, str):+ annotation = Any+ default = (+ pydantic_core.PydanticUndefined+ if param.default is inspect.Parameter.empty+ else param.default+ )+ title = FieldInfo.from_annotated_attribute(annotation, default).title+ if title is not None:+ titles[name] = title+ return titlesdiff --git a/fastmcp_slim/fastmcp/server/providers/proxy.py b/fastmcp_slim/fastmcp/server/providers/proxy.pyindex 4d58c1725..6a1136af7 100644--- a/fastmcp_slim/fastmcp/server/providers/proxy.py+++ b/fastmcp_slim/fastmcp/server/providers/proxy.py@@ -757,6 +757,7 @@ class ProxyPrompt(Prompt):arguments = [PromptArgument(name=arg.name,+ title=arg.title,description=arg.description,required=arg.required or False,)diff --git a/tests/prompts/test_prompt.py b/tests/prompts/test_prompt.pyindex 0f84c2c41..c02ab7027 100644--- a/tests/prompts/test_prompt.py+++ b/tests/prompts/test_prompt.py@@ -689,6 +689,24 @@ class TestPromptArgumentDescriptions:assert mcp_prompt.meta is not Noneassert meta_data.items() <= mcp_prompt.meta.items()+ def test_argument_titles_from_field(self):+ """An explicit Field(title=...) becomes the argument's MCP title."""+ from pydantic import Field++ def test_prompt(+ name: Annotated[str, Field(title="Your name")],+ tone: str = Field(default="playful", title="Tone of voice"),+ topic: str = "dogs",+ ) -> str:+ return f"Hello, {name}!"++ arguments = Prompt.from_function(test_prompt).to_mcp_prompt().arguments or []+ assert {arg.name: arg.title for arg in arguments} == {+ "name": "Your name",+ "tone": "Tone of voice",+ "topic": None,+ }+class TestMessage:def test_message_string_content(self):diff --git a/tests/server/providers/proxy/test_proxy_server.py b/tests/server/providers/proxy/test_proxy_server.pyindex 4906280d4..a8a27c027 100644--- a/tests/server/providers/proxy/test_proxy_server.py+++ b/tests/server/providers/proxy/test_proxy_server.py@@ -883,6 +883,31 @@ class TestPrompts:proxy_result = await client.list_prompts()assert proxy_result == result+ async def test_list_prompts_keeps_argument_titles(self):+ """A backend's argument titles reach the proxy's clients."""+ from fastmcp.prompts import Prompt+ from fastmcp.prompts.base import PromptArgument++ def greet(name: str) -> str:+ return f"Hello, {name}!"++ prompt = Prompt.from_function(greet)+ prompt = prompt.model_copy(+ update={+ "arguments": [+ PromptArgument(name="name", title="Your name", required=True)+ ]+ }+ )+ backend = FastMCP("Backend")+ backend.add_prompt(prompt)++ async with Client(create_proxy(backend)) as client:+ (listed,) = await client.list_prompts()+ assert listed.arguments == [+ mcp_types.PromptArgument(name="name", title="Your name", required=True)+ ]+async def test_render_prompt_same_as_original(self, fastmcp_server: FastMCP, proxy_server: FastMCPProxy):