FastMCP项目中字符串参数被意外转换为整数的Bug分析与修复

问题背景

在FastMCP项目(一个基于FastAPI构建的MCP协议实现)中，用户报告了一个关于参数类型处理的异常行为。当通过客户端调用工具函数并传递字符串参数时，系统错误地将字符串值转换为整数类型，导致类型验证失败。

问题现象

用户在使用FastMCP 2.2.8版本时发现，当定义一个接受字符串参数的函数：

@mcp.tool()
async def nothing(p: str) -> str:
    return "r"

然后通过客户端传递字符串参数：

await c.call_tool("nothing", {"p": "12345"})

系统会抛出类型验证错误，提示"Input should be a valid string"，但实际上输入的是一个有效的字符串"12345"。这表明系统内部错误地将字符串参数转换为了整数类型。

技术分析

这个问题的根源在于FastMCP的类型转换逻辑中存在一个特殊处理，原本是为了解决Claude AI在JSON序列化时的特定问题而添加的。这种处理在某些情况下会过度积极地尝试将看似数字的字符串转换为数值类型。

在Python的类型系统中，虽然"12345"是一个合法的字符串，但由于其内容全部由数字组成，某些自动类型转换机制会错误地将其识别为整数。这种自动类型转换在JSON处理中尤其常见，因为JSON规范本身不区分数字字符串和数值类型。

解决方案

项目维护者迅速响应并发布了两个修复版本：

1. 紧急修复版本2.2.9：针对这个特定问题提供了热修复
2. 后续版本2.2.10：提供了更全面的解决方案，从根本上改进了类型转换逻辑

最佳实践建议

对于开发者使用FastMCP时，建议：

1. 及时升级到最新版本以避免此类问题
2. 对于确实需要保持字符串类型的参数，即使其内容是数字，可以在参数注释中明确说明
3. 在关键业务逻辑中添加额外的类型验证，作为防御性编程措施

总结

这个案例展示了在框架开发中类型系统处理的重要性，特别是当涉及自动类型转换时。FastMCP团队通过快速响应和分阶段修复，既解决了紧急问题，又为长期稳定性提供了保障。对于使用者而言，理解框架的类型处理机制有助于编写更健壮的代码。