FastMCP项目中TextContent的高级定制：audience与priority的应用实践

在FastMCP项目开发过程中，开发者everdrone提出了一个关于TextContent功能增强的需求，希望暴露其audience（受众）和priority（优先级）属性，以便更好地控制工具调用结果的展示逻辑。这个需求反映了现代AI应用开发中一个常见场景：如何优雅地处理不同优先级和不同受众的系统反馈。

核心需求解析

TextContent作为FastMCP中内容传递的基本单元，默认情况下主要关注文本内容的序列化输出。但在实际应用中，我们经常需要：

1. 区分内容的目标受众（如用户可见内容vs系统内部信息）
2. 设置内容的优先级（关键信息优先展示）
3. 避免不必要的信息干扰用户体验

技术实现方案

项目维护者jlowin提供了简洁而强大的解决方案：通过TextContent的annotations参数实现自定义标注。这种设计既保持了接口的简洁性，又提供了足够的扩展能力。

@mcp.tool()
def memory_retrieval_tool():
    return TextContent(
        text="用户记忆数据",
        annotations={
            'audience': 'system',
            'priority': 'low'
        }
    )

最佳实践建议

1. 受众分类策略：

   • 'user'：直接展示给终端用户的内容
   • 'system'：仅用于系统内部处理
   • 'developer'：开发调试信息

2. 优先级标准：

   • 'critical'：必须立即处理的关键信息
   • 'high'：重要但不紧急
   • 'normal'：常规信息（默认值）
   • 'low'：低优先级后台信息

3. UI集成方案： 前端可根据这些标注实现智能过滤：

   function shouldDisplay(content) {
       return content.annotations?.audience !== 'system';
   }
   

架构思考

这种设计体现了良好的关注点分离原则：

• 工具开发者只需关注业务逻辑
• 内容展示策略由上层应用控制
• 系统保持了足够的灵活性应对未来需求变化

对于需要更复杂标注的场景，建议建立项目级的标注规范文档，确保团队对各类标注值的含义有统一理解。

总结

FastMCP通过灵活的TextContent设计，巧妙地解决了工具调用结果的展示控制问题。这种模式值得在类似AI应用框架中借鉴，它既满足了当前的需求，又为未来的扩展留下了空间。开发者可以根据实际项目需求，进一步丰富标注体系，构建更智能的信息分发机制。