深入解讀 MCP 協議最新版本的 4 大升級【下】：批處理與增強的工具註解

本篇接着爲大家解讀 MCP 協議最新修訂版本（2025-03-26）的四個較大升級的後兩項（上篇翻閱：深入解讀 MCP 協議最新版本的 4 大升級【上】：傳輸機制與安全授權）：

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 批處理在舊版協議中未被提及。因此，新版客戶端在與舊版服務器通信時應避免發送批請求，除非通過版本協商確認對方支持。同樣，新版服務器在未確定客戶端版本支持前，也應謹慎返回批量結果，可在初始化時告知支持批處理，以便客戶端決定是否使用。

由於批處理特性不影響非批處理的正常單請求路徑，一個兼容的方法是：一端檢測到另一端不支持批量模式，則自動退化爲逐條請求模式。

增強的工具註解

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(
    ,
    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）”，它們**僅作爲參考信息而非強制性限制 **— 規範要求客戶端不應完全依賴工具註解，除非這些工具來自可信的服務器。當然，這也確保了無論新舊規範的實現，都能按照各自的邏輯運行。

本文由 Readfog 進行 AMP 轉碼，版權歸原作者所有。
來源：https://mp.weixin.qq.com/s/ULH9YUGX4PZ7tUCfMe2dSw

猜你喜歡