深入解读MCP协议最新版本的4大升级【下】：批处理与增强的工具注解

本文链接：https://blog.csdn.net/2401_85373898/article/details/147821994

本篇接着为大家解读MCP协议最新修订版本（2025-03-26）的四个较大升级的后两项

JSON-RPC批处理
增强的工具注解

JSON-RPC批处理

JSON-RPC 2.0规范本身支持批量（Batch）模式，允许一次性发送一个包含多个请求对象的数组，服务器随后可以返回一个数组，其中包含对应的多个响应。MCP的新版本规范也明确了这一批处理功能，它允许客户端在单一操作中发送多个请求或通知，这与JSON-RPC 2.0标准保持一致。

【背景与动机】

当前版本中，每个MCP的请求必须单独发送至对端。对于那些需要一次性调用多个工具或进行批量处理任务的场景，批处理技术能够显著提升效率并减轻服务器的压力。比如：

当一个AI 智能体在编写总结报告时，可能需要同时调用多个数据源工具。比如：
- 查询销售数据库：获取2024年销售额前10的产品
- 市场研究：通过工具获取2025年市场产品销售趋势*
  ***
- *竞争对手数据：查询获取竞争对手市场份额变化*
  
  *
  *
通过使用批处理，智能体可以将这些操作全部包含在一个请求中发送给MCP服务端，并一次性获得返回结果列表。减少了串行等待的时间，提高了整体的响应速度。
在涉及多模型协作或事务性操作的场景中，批处理同样具有重要意义：可以将多个子请求作为一个原子事务发送，服务器在执行过程中确保要么全部成功，要么整体失败，这可以简化了错误处理的逻辑。

【变更说明】

客户端可以通过POST 方式发送一个 JSON-RPC 请求的数组，数组中的每个元素为一个合法的请求。例如，一个包含两个方法调用的批处理示例如下：

[
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"sum","arguments":{"a":1,"b":2}}},
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"multiply","arguments":{"x":5,"y":6}}}
]

服务器接收到这个批处理后，可以并行或顺序执行每个请求，最终返回一个包含对应响应对象的数组：

[
  {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"3"}]}},
  {"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"30"}]}}
]

*【影响和应用】*

尽管批处理能够提高性能，客户端仍需记录每个请求的唯一标识符（ID）及其响应，以确保结果的正确对应。错误处理也更为复杂：

开发者需要增强对批量消息的编码**/**解码和追踪能力，并妥善处理可能出现的部分错误。在批处理过程中，若某个请求失败，服务器会在响应数组中为该条目返回一个错误对象。因此，开发者应确保批处理消息的大小和复杂性保持在可控范围内。

JSON-RPC批处理在旧版协议中未被提及。因此，新版客户端在与旧版服务器通信时应避免发送批请求，除非通过版本协商确认对方支持。同样，新版服务器在未确定客户端版本支持前，也应谨慎返回批量结果，可在初始化时告知支持批处理，以便客户端决定是否使用。

由于批处理特性不影响非批处理的正常单请求路径，一个兼容的方法是：一端检测到另一端不支持批量模式，则自动退化为逐条请求模式。

*02*

增强的工具注解

MCP新规范在工具的元数据中新增了一组工具注解（Tool Annotations）字段，可以为每个工具提供更丰富的行为元数据。

该功能在最新的Python SDK 1.7.1版本已经被支持。

【背景与动机】

增强工具注解旨在满足安全性和用户体验的需求，尤其是在自动化调用场景中，缺乏对工具功能的了解可能会引发安全风险。例如：

一个AI智能体可能在没有任何警告的情况下调用了具有副作用的工具，从而修改了用户数据。如果能够预先获知某工具会产生破坏性效果，它就可以采取谨慎行动，甚至引入用户参与流程。因此工具注解某种意义上是MCP工具的“安全提醒”：

如果说OAuth2.1授权确保了**“谁”可以调用工具，那么工具注解则提示“调用此工具将产生何种后果”****，这两者共同增强了工具行为的可控性和透明度。**

【变更说明】

新版规范对工具定义添加了一个可选字段annotations（注释），用于描述工具的行为属性和使用提示注释内部可以包含若干布尔或字符串字段，表示该工具的特性。常见的注解包括：

title：工具的可读标题，用于向用户或模型展示。
readOnlyHint：设置为 true 表明该工具不会改变环境状态（即为只读工具）。
destructiveHint：设置为 true 表明该工具可能会执行破坏性操作。
idempotentHint：设置为 true 表明多次使用相同参数调用该工具结果相同。
openWorldHint：设置为 true 表明工具可能会与外部开放系统进行交互（例如网络搜索、数据库查询等）。

这些注解字段提供了关于工具行为方式的元数据信息。例如，一个“删除文件”的工具现在你可以这样装饰（FastMCP模式）：

@app.tool(
    name="delete_file",
    annotations=types.ToolAnnotations(
        title="文件删除工具",
        readOnlyHint=False,
        destructiveHint=True,
        idempotentHint=True,
        openWorldHint=False
    )
)
defdelete_file(query: str) -> str:
...

此示例表示delete_files工具会改变环境设置（readOnlyHint:false），并且可能具有破坏性（destructiveHint:true）。然而，多次使用相同的参数调用该函数不会产生额外的影响（idempotentHint:true），且其操作仅限于本地环境（openWorldHint:false）。

【影响和应用】

通过工具注解，MCP客户端获得了更丰富的工具使用“参考说明”，这有助于提高安全性和交互体验（例如，防止误用破坏性工具），模型和客户端能够更加智能地做出决策和展示信息。例如：

大模型在规划调用工具时可以参考注解。面对具有相同功能的两个工具，它可以选择优先使用标记为readOnly的工具；如果必须使用具有破坏性的工具，它还可以在执行前向用户请求确认，以防止误用。
客户端UI可以标注工具的注解信息以提醒客户。 例如，在一个AI智能体的工具面板中，可以使用特殊图标或警示颜色来标注“此工具会修改数据”或“需要网络访问”等信息，让用户更加明了风险。
对于大量工具调用组成的AI工作流，注解还能协助上下文管理：客户端可以追踪并记录哪些工具产生了外部影响，哪些仅用于获取信息。这对于调试和审计同样具有重要价值。

总的来说，工具注解使得客户端和大模型对工具的理解更加深入，并让用户对智能体的行为感到更可控。

需要注意的是，这些注释字段都是**“提示（hint）”，它们**仅作为参考信息而非强制性限制**** — 规范要求客户端不应完全依赖工具注解，除非这些工具来自可信的服务器。当然，这也确保了无论新旧规范的实现，都能按照各自的逻辑运行。