ModelContextProtocol Python SDK 中提示参数类型的客户端传递机制分析

在ModelContextProtocol（MCP）Python SDK的开发过程中，提示(Prompt)系统的参数类型传递机制是一个值得深入探讨的技术细节。本文将从技术实现角度分析当前系统中存在的类型传递问题，并探讨其解决方案。

问题背景

在MCP架构中，服务器端定义的提示参数可以通过特定方式将其类型信息传递给客户端。例如，当服务器端这样定义提示参数时：

PromptArgument(
    name=CodePromptArgs.NOTES,
    description="Notes about the task",
    type="str",
    required=False,
)

客户端能够接收到完整的参数元数据，包括参数名称、描述、是否必需以及类型信息。这种机制使得客户端能够在发送请求前进行输入验证，提高了系统的健壮性。

然而，在FastMCP实现中，这一机制存在缺陷——类型信息无法正确传递给客户端。虽然开发者可以通过在描述字段中手动添加类型信息作为临时解决方案，但这不仅不够优雅，也降低了系统的可靠性。

技术实现分析

通过对源码的深入分析，我们发现问题的根源在于FastMCP服务器的list_prompts方法实现。当前实现中，该方法在构造MCPPromptArgument对象时没有包含类型信息：

MCPPromptArgument(
    name=arg.name,
    description=arg.description,
    required=arg.required
    # 缺少type参数
)

要解决这个问题，需要同时在几个层面进行修改：

1. 模型定义层：需要在PromptArgument基类中添加type字段
2. 参数提取层：在从函数提取参数时需要正确获取类型信息
3. 接口响应层：在构造响应时需要包含类型信息

解决方案

完整的解决方案包括以下关键修改点：

1. 在PromptArgument类定义中添加type字段：

class PromptArgument(BaseModel):
    name: str
    description: Optional[str] = None
    required: Optional[bool] = None
    type: Optional[str] = None  # 新增类型字段

2. 修改服务器端的prompt列表接口实现：

async def list_prompts(self) -> list[MCPPrompt]:
    prompts = self._prompt_manager.list_prompts()
    return [
        MCPPrompt(
            name=prompt.name,
            description=prompt.description,
            arguments=[
                MCPPromptArgument(
                    name=arg.name,
                    description=arg.description,
                    required=arg.required,
                    type=arg.type  # 添加类型传递
                )
                for arg in (prompt.arguments or [])
            ],
        )
        for prompt in prompts
    ]

3. 在参数提取逻辑中正确设置类型信息：

@classmethod
def from_function(cls, func: Callable) -> "Prompt":
    arguments = []
    for param_name, param in sig.parameters.items():
        arguments.append(
            PromptArgument(
                name=param_name,
                description=param.get("description"),
                required=required,
                type=param.annotation.__name__  # 添加类型提取
            )
        )

技术价值与展望

实现参数类型的完整传递具有多重技术价值：

1. 客户端验证：客户端可以在请求前进行严格的类型检查，减少无效请求
2. 开发体验：开发者可以获得更完整的API文档和类型提示
3. 系统健壮性：类型系统为整个调用流程增加了编译时检查的保障

虽然当前的MCP规范尚未正式将参数类型纳入标准，但从技术发展趋势来看，类型系统在现代API设计中变得越来越重要。特别是在AI应用场景下，明确的类型约束可以显著提高提示工程的可靠性和可维护性。

总结

本文详细分析了ModelContextProtocol Python SDK中提示参数类型传递的技术实现问题，并提出了完整的解决方案。通过系统性地修改模型定义、参数提取和接口响应三个层面的代码，我们能够实现类型信息的完整传递，从而提升整个系统的可靠性和开发体验。这一改进不仅解决了当前的技术痛点，也为未来的功能扩展奠定了良好的基础。