Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

fix(prompts): honor field aliases when rendering prompts (#5836)

ε“ˆεŸΊη±³a450fd8b0bbf
diff --git a/fastmcp_slim/fastmcp/prompts/function_prompt.py b/fastmcp_slim/fastmcp/prompts/function_prompt.py
index bac7362b1..d09596405 100644
--- a/fastmcp_slim/fastmcp/prompts/function_prompt.py
+++ b/fastmcp_slim/fastmcp/prompts/function_prompt.py
@@ -42,6 +42,51 @@ F = TypeVar("F", bound=Callable[..., Any])
logger = get_logger(__name__)
+def _python_names_by_argument_name(fn: Callable[..., Any]) -> dict[str, str]:
+ """Map advertised prompt-argument names to Python parameter names.
+
+ Prompt arguments are advertised from the Pydantic call schema, so a
+ parameter with an alias is listed under the alias. MCP callers send the
+ advertised name, which must be translated back before the arguments are
+ converted and filtered against the Python signature.
+ """
+ mapping: dict[str, str] = {}
+ try:
+ hints = get_type_hints(fn, include_extras=True)
+ except Exception:
+ hints = {}
+ for param_name, param in inspect.signature(fn).parameters.items():
+ annotation = hints.get(param_name, param.annotation)
+ default = param.default
+ try:
+ if isinstance(default, FieldInfo):
+ # A Field(...) default is part of the call schema too. Merge
+ # it with Annotated metadata exactly as pydantic does, so the
+ # alias pydantic advertises is the one we map.
+ if annotation is inspect.Parameter.empty:
+ field_info = default
+ else:
+ field_info = FieldInfo.from_annotated_attribute(annotation, default)
+ elif annotation is not inspect.Parameter.empty:
+ field_info = FieldInfo.from_annotation(annotation)
+ else:
+ continue
+ except Exception as e:
+ logger.debug(
+ "Could not determine alias for prompt argument %s: %s", param_name, e
+ )
+ continue
+
+ advertised_name = (
+ field_info.validation_alias
+ if isinstance(field_info.validation_alias, str)
+ else field_info.alias
+ )
+ if advertised_name and advertised_name != param_name:
+ mapping[advertised_name] = param_name
+ return mapping
+
+
@runtime_checkable
class DecoratedPrompt(Protocol):
"""Protocol for functions decorated with @prompt."""
@@ -280,11 +325,15 @@ class FunctionPrompt(Prompt):
# Preserve the existing fallback for unresolved forward references.
type_hints = getattr(wrapper_fn, "__annotations__", {})
converted_kwargs = {}
+ # Callers send advertised names; an advertised name may be a Pydantic
+ # alias whose Python parameter is declared under a different name.
+ aliases = _python_names_by_argument_name(self.fn)
for param_name, param_value in kwargs.items():
- if param_name in sig.parameters:
- param = sig.parameters[param_name]
- annotation = type_hints.get(param_name, param.annotation)
+ python_name = aliases.get(param_name, param_name)
+ param = sig.parameters.get(python_name)
+ if param is not None:
+ annotation = type_hints.get(python_name, param.annotation)
if annotation == inspect.Parameter.empty or not isinstance(
param_value, str
@@ -356,9 +405,12 @@ class FunctionPrompt(Prompt):
# This is important for security: dependencies should not be overridable
# from external callers. self.fn is wrapped by without_injected_parameters,
# so we only accept arguments that are in the wrapped function's signature.
+ # Advertised names may be Pydantic aliases; those are accepted too
+ # and validated under the alias by the type adapter below.
sig = inspect.signature(self.fn)
valid_params = set(sig.parameters.keys())
- kwargs = {k: v for k, v in kwargs.items() if k in valid_params}
+ aliases = _python_names_by_argument_name(self.fn)
+ kwargs = {k: v for k, v in kwargs.items() if k in valid_params or k in aliases}
# Use type adapter to validate arguments and handle Field() defaults
# This matches the behavior of tools in function_tool
diff --git a/tests/prompts/test_dual_alias.py b/tests/prompts/test_dual_alias.py
new file mode 100644
index 000000000..59aee46e3
--- /dev/null
+++ b/tests/prompts/test_dual_alias.py
@@ -0,0 +1,30 @@
+from pydantic import Field
+
+from fastmcp.prompts import Prompt
+from fastmcp.prompts.base import Message
+
+
+async def test_validation_alias_takes_precedence_over_alias():
+ def total(
+ numbers: list[int] = Field(alias="Numbers", validation_alias="Input"),
+ ) -> str:
+ return f"sum={sum(numbers)}"
+
+ prompt = Prompt.from_function(total)
+ assert prompt.arguments is not None
+ assert [arg.name for arg in prompt.arguments] == ["Input"]
+ result = await prompt.render({"Input": "[1, 2, 3]"})
+ assert result.messages == [Message("sum=6")]
+
+
+async def test_validation_alias_takes_precedence_with_default():
+ def total(
+ numbers: list[int] = Field(
+ default=[7], alias="Numbers", validation_alias="Input"
+ ),
+ ) -> str:
+ return f"sum={sum(numbers)}"
+
+ prompt = Prompt.from_function(total)
+ assert (await prompt.render({"Input": "[1, 2]"})).messages == [Message("sum=3")]
+ assert (await prompt.render({})).messages == [Message("sum=7")]
diff --git a/tests/prompts/test_prompt.py b/tests/prompts/test_prompt.py
index c02ab7027..8cfcb2fe5 100644
--- a/tests/prompts/test_prompt.py
+++ b/tests/prompts/test_prompt.py
@@ -1020,3 +1020,100 @@ class TestPromptCallableAndConcurrency:
prompt.render(),
)
assert all(r.messages == [Message("done")] for r in results)
+
+
+class TestPromptArgumentAliases:
+ """Pydantic aliases on prompt parameters must work like tool aliases."""
+
+ async def test_alias_is_advertised_and_renderable(self):
+ def greet(name: Annotated[int, Field(alias="Name")]) -> str:
+ return f"Hello, {name}!"
+
+ prompt = Prompt.from_function(greet)
+
+ assert prompt.arguments is not None
+ assert [arg.name for arg in prompt.arguments] == ["Name"]
+ assert prompt.arguments[0].required is True
+
+ result = await prompt.render({"Name": "5"})
+ assert result.messages == [Message("Hello, 5!")]
+
+ async def test_alias_on_field_default_is_advertised_and_renderable(self):
+ def greet(name: str = Field(alias="Name")) -> str:
+ return f"Hello, {name}!"
+
+ prompt = Prompt.from_function(greet)
+
+ assert prompt.arguments is not None
+ assert [arg.name for arg in prompt.arguments] == ["Name"]
+ assert prompt.arguments[0].required is True
+
+ result = await prompt.render({"Name": "Ada"})
+ assert result.messages == [Message("Hello, Ada!")]
+
+ async def test_alias_on_field_default_with_default_value(self):
+ def greet(name: int = Field(default=7, alias="Name")) -> str:
+ return f"Hello, {name}!"
+
+ prompt = Prompt.from_function(greet)
+
+ assert prompt.arguments is not None
+ assert [arg.name for arg in prompt.arguments] == ["Name"]
+ assert prompt.arguments[0].required is False
+
+ result = await prompt.render({"Name": "9"})
+ assert result.messages == [Message("Hello, 9!")]
+
+ default_result = await prompt.render({})
+ assert default_result.messages == [Message("Hello, 7!")]
+
+ async def test_validation_alias_on_field_default_is_advertised_and_renderable(self):
+ def greet(name: int = Field(default=7, validation_alias="Name")) -> str:
+ return f"Hello, {name}!"
+
+ prompt = Prompt.from_function(greet)
+
+ assert prompt.arguments is not None
+ assert [arg.name for arg in prompt.arguments] == ["Name"]
+
+ result = await prompt.render({"Name": "9"})
+ assert result.messages == [Message("Hello, 9!")]
+
+ async def test_aliased_non_string_argument_accepts_json_string(self):
+ def total(numbers: Annotated[list[int], Field(alias="Numbers")]) -> str:
+ return f"sum={sum(numbers)}"
+
+ prompt = Prompt.from_function(total)
+
+ result = await prompt.render({"Numbers": "[1, 2, 3]"})
+ assert result.messages == [Message("sum=6")]
+
+ async def test_alias_with_injected_parameter(self):
+ from fastmcp.dependencies import Depends
+
+ def greet(
+ name: Annotated[int, Field(alias="Name")],
+ dependency: str = Depends(lambda: "injected"),
+ ) -> str:
+ return f"Hello, {name}! {dependency}"
+
+ prompt = Prompt.from_function(greet)
+
+ assert prompt.arguments is not None
+ assert [arg.name for arg in prompt.arguments] == ["Name"]
+
+ # Injected parameters remain unaddressable from the outside.
+ result = await prompt.render({"Name": "5", "dependency": "override"})
+ assert result.messages == [Message("Hello, 5! injected")]
+
+ async def test_ordinary_argument_names_unchanged(self):
+ def greet(name: int, greeting: str = "Hello") -> str:
+ return f"{greeting}, {name}!"
+
+ prompt = Prompt.from_function(greet)
+
+ assert prompt.arguments is not None
+ assert [arg.name for arg in prompt.arguments] == ["name", "greeting"]
+
+ result = await prompt.render({"name": "5"})
+ assert result.messages == [Message("Hello, 5!")]