docs: publish translated docs in twelve languages and the tool that maintains them (#3280)
This commit is contained in:
parent
14aa889992
commit
52ad0a8876
10 changed files with 89737 additions and 54 deletions
128
i18n/zh-hant/pages/handlers/context.md
Normal file
128
i18n/zh-hant/pages/handlers/context.md
Normal file
|
|
@ -0,0 +1,128 @@
|
|||
---
|
||||
translation:
|
||||
sections: [b50152f05c81e786, b302059b22fb7cb4, 85682a1bf561243a, 53fc48838eb6837a, b24190e0842786ec, 85f93e150fc9b240]
|
||||
tool: 1
|
||||
---
|
||||
# Context {#the-context}
|
||||
|
||||
工具的引數來自模型。其他的一切(正在處理的請求、所在的伺服器、與用戶端溝通的方式)都來自同一個物件:**`Context`**。
|
||||
|
||||
不需要自己建立,也不需要設定,只要開口要就好。
|
||||
|
||||
## 開口要它 {#ask-for-it}
|
||||
|
||||
在任何工具上加一個以 `Context` 註記的參數:
|
||||
|
||||
```python title="server.py" hl_lines="2 8"
|
||||
--8<-- "docs_src/context/tutorial001.py"
|
||||
```
|
||||
|
||||
* SDK 會為每個請求建立一個全新的 `Context` 並傳進來。
|
||||
* 參數的**名稱不重要**。`ctx`、`context`、`c` 都可以:SDK 是靠型別註記找到它的。
|
||||
* 資源和提示詞也可以用同樣的方式宣告一個。
|
||||
* `ctx.request_id` 是函式此刻正在處理的那個請求的 id。
|
||||
|
||||
!!! info
|
||||
如果用過 FastAPI,這一招應該不陌生:用框架自己的型別宣告一個參數(那邊是 `Request`,這邊是 `Context`),框架就會幫你補上。不用註冊,不用設定:型別註記就是整套機制。
|
||||
|
||||
### 模型看不到它 {#invisible-to-the-model}
|
||||
|
||||
這是要記在心裡的部分。以下是 `tools/list` 針對 `search_books` 回報的輸入 schema:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"query": {"title": "Query", "type": "string"}
|
||||
},
|
||||
"required": ["query"],
|
||||
"title": "search_booksArguments"
|
||||
}
|
||||
```
|
||||
|
||||
只有一個屬性。`ctx` 不是引數:它永遠不會出現在 schema 裡,模型永遠不會知道它的存在,也沒有任何用戶端能填入它。這是你和 SDK 之間的約定,在線路上看不到。
|
||||
|
||||
### 試試看 {#try-it}
|
||||
|
||||
用 MCP Inspector 執行伺服器:
|
||||
|
||||
```console
|
||||
uv run mcp dev server.py
|
||||
```
|
||||
|
||||
`search_books` 的表單只有一個 `query` 欄位。用 `dune` 呼叫它:
|
||||
|
||||
```text
|
||||
[request 3] Found 3 books matching 'dune'.
|
||||
```
|
||||
|
||||
數字是這次剛好輪到的請求編號。再呼叫一次工具,數字就會變:每個請求都有自己的 `Context`。
|
||||
|
||||
## 它給你什麼 {#what-it-gives-you}
|
||||
|
||||
注入的物件很小。除了 `request_id` 之外:
|
||||
|
||||
* `await ctx.read_resource(uri)`:在工具內部讀取伺服器**自己的**資源。下一節會介紹。
|
||||
* `await ctx.report_progress(progress, total, message)`:在長時間的呼叫期間,把進度串流回傳給呼叫端。完整說明請見 **[進度](progress.md)**。
|
||||
* `await ctx.elicit(message, schema)` 和 `await ctx.elicit_url(...)`:暫停工具,向使用者問一個問題。那是 **[徵詢(elicitation)](elicitation.md)**。
|
||||
* `ctx.session`:伺服器這一側與這個用戶端的對話。要送給用戶端的通知都在這裡;最後一節會用到它。
|
||||
* `ctx.headers`:傳輸方式帶過來的請求標頭,在 stdio 上則是 `None`。用 `(ctx.headers or {}).get("x-...")` 讀取自訂標頭。標頭是用戶端提供的輸入,拿來傳語系或功能旗標沒問題,但絕不能當作身分。
|
||||
* `ctx.request_context`:原始的每請求紀錄。最常用到的欄位是 `lifespan_context`,也就是啟動程式碼 yield 出來的物件(見 **[生命週期](lifespan.md)**)。
|
||||
|
||||
記錄刻意不在這張清單上。伺服器和其他 Python 程式一樣,用 Python 的 `logging` 模組記錄。**[記錄](logging.md)** 這一頁簡短說明了原因。
|
||||
|
||||
!!! tip
|
||||
注入只發生在你註冊的那個函式上。工具呼叫的輔助函式不會拿到自己的 `Context`;把 `ctx` 當作普通引數往下傳就好。沒有什麼環境中的「目前 context」可以從別處取得。
|
||||
|
||||
## 讀取自己的資源 {#read-your-own-resources}
|
||||
|
||||
伺服器的資源不只是給用戶端用的。工具也可以讀取:
|
||||
|
||||
```python title="server.py" hl_lines="16"
|
||||
--8<-- "docs_src/context/tutorial002.py"
|
||||
```
|
||||
|
||||
`ctx.read_resource` 透過和 `resources/read` 同一套登錄機制解析 URI,所以工具拿到的東西和用戶端拿到的一樣:一個 `ReadResourceContents` 的可迭代物件,每個內容區塊一個。這個 URI 只有一個:
|
||||
|
||||
```python
|
||||
contents.content # 'fiction, non-fiction, poetry'
|
||||
contents.mime_type # 'text/plain'
|
||||
```
|
||||
|
||||
* `content` 正是 `genres()` 回傳的內容。單一事實來源:用戶端瀏覽這個資源,工具取用它,沒有人需要複製那個字串。
|
||||
* `describe_catalog` 唯一的參數是 `Context`,所以它的輸入 schema **完全沒有屬性**。模型用 `{}` 呼叫它。
|
||||
|
||||
## 告訴用戶端清單變了 {#tell-the-client-the-list-changed}
|
||||
|
||||
伺服器提供的內容並不是在 import 時就固定下來的。可以在執行時註冊工具,然後告訴用戶端:
|
||||
|
||||
```python title="server.py" hl_lines="15-16"
|
||||
--8<-- "docs_src/context/tutorial003.py"
|
||||
```
|
||||
|
||||
* `mcp.add_tool(recommend_book)` 把一個普通函式註冊成工具:名稱、描述和 schema 的推導方式與 `@mcp.tool()` 完全相同。
|
||||
* `await ctx.session.send_tool_list_changed()` 會送出 `notifications/tools/list_changed`。收到它的用戶端會再次呼叫 `tools/list`,然後看到 `recommend_book`。
|
||||
|
||||
同系列的還有 `send_resource_list_changed()`、`send_prompt_list_changed()`,以及針對某個特定資源變更的 `send_resource_updated(uri)`。
|
||||
|
||||
在 2026-07-28 連線上,用戶端只會在自己開啟的 `subscriptions/listen` 串流上收到變更通知,所以上面的 `send_*` 方法到不了那些串流。`Context` 的發布方法會一次送達所有已訂閱的串流:`await ctx.notify_tools_changed()`、`await ctx.notify_prompts_changed()`、`await ctx.notify_resources_changed()` 和 `await ctx.notify_resource_updated(uri)`。完整說明(包括跨副本橫向擴展)請見 **[訂閱](subscriptions.md)**。
|
||||
|
||||
!!! check
|
||||
在有人執行 `enable_recommendations` 之前,你承諾的那個工具並不存在。硬是呼叫它,結果會是模型讀得懂的錯誤:
|
||||
|
||||
```text
|
||||
Unknown tool: recommend_book
|
||||
```
|
||||
|
||||
執行 `enable_recommendations` 之後,一模一樣的呼叫就成功了。工具清單是真正動態的:`tools/list` 反映的是**此刻**註冊了什麼。
|
||||
|
||||
## 重點回顧 {#recap}
|
||||
|
||||
* 用 `Context` 註記一個參數(在工具、資源或提示詞裡),SDK 就會注入它。名稱隨你取。
|
||||
* 模型看不到它:輸入 schema 永遠只包含真正的引數。
|
||||
* `ctx.request_id` 標識請求;`ctx.request_context.lifespan_context` 是啟動時 yield 出來的東西。
|
||||
* `await ctx.read_resource(uri)` 讓工具讀取伺服器自己的資源。
|
||||
* `ctx.session` 是回到用戶端的通道:`send_tool_list_changed()` 和同系列的方法會通知它重新抓取你改過的清單。
|
||||
* 進度回報和徵詢也都從 `Context` 開始;各有自己的頁面。
|
||||
|
||||
模型永遠看不到、由你自己的函式填入的參數,就是 **[相依性](dependencies.md)**。
|
||||
137
i18n/zh-hant/pages/handlers/dependencies.md
Normal file
137
i18n/zh-hant/pages/handlers/dependencies.md
Normal file
|
|
@ -0,0 +1,137 @@
|
|||
---
|
||||
translation:
|
||||
sections: [b0389403e98d25ad, e2cf58b43b285e86, a363e1a38e1a5971, 6cfac078feb18013, b4535bd61df337e6, e97ed44207f929fd]
|
||||
tool: 1
|
||||
---
|
||||
# 相依性 {#dependencies}
|
||||
|
||||
工具的引數來自模型。但有些值根本不該由模型提供:從自己的紀錄查出來的價格、只有真人能給的確認,以及任何模型一旦憑空捏造就可能出錯的東西。
|
||||
|
||||
**相依性**是由你自己的函式填入的參數。在參數上加註記、指名函式,SDK 就會在工具執行前呼叫它。
|
||||
|
||||
## 宣告一個 {#declare-one}
|
||||
|
||||
把參數的型別包進 `Annotated[...]`,再加上 `Resolve(fn)`:
|
||||
|
||||
```python title="server.py" hl_lines="18-19 23"
|
||||
--8<-- "docs_src/dependencies/tutorial001.py"
|
||||
```
|
||||
|
||||
* `check_stock` 是一個**解析器**:一個普通函式,SDK 會在 `reserve_book` 之前執行它,回傳值就成為 `stock` 引數。
|
||||
* 它的 `title` 參數就是工具本身的 `title` 引數,**依名稱**比對。解析器看到的值,和工具本體將看到的驗證後的值完全相同。
|
||||
* 工具本體一開始就拿到一個現成的 `Stock`。工具裡沒有查詢程式碼,也沒有「萬一找不到怎麼辦」的開場白。
|
||||
|
||||
!!! info
|
||||
如果用過 FastAPI,這就是 `Depends`。同樣的做法,同樣的理由:函式宣告自己需要什麼,框架負責供應,接線全寫在型別註記裡。
|
||||
|
||||
### 模型看不到 {#invisible-to-the-model}
|
||||
|
||||
這是 `tools/list` 為 `reserve_book` 回報的輸入 schema:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"title": {"title": "Title", "type": "string"}
|
||||
},
|
||||
"required": ["title"],
|
||||
"title": "reserve_bookArguments"
|
||||
}
|
||||
```
|
||||
|
||||
只有一個屬性。和 **[Context](context.md)** 裡的 `Context` 一樣,解析出來的參數是你和 SDK 之間的約定:`stock` 不在 schema 裡,模型從頭到尾不知道它的存在,用戶端就算硬是送來 `stock` 值也會被忽略。解析器的值是工具唯一可能收到的值。
|
||||
|
||||
最後這點正是重點。模型無法提供的參數,就是模型無法弄錯的參數。
|
||||
|
||||
### 試試看 {#try-it}
|
||||
|
||||
用 MCP Inspector 執行伺服器:
|
||||
|
||||
```console
|
||||
uv run mcp dev server.py
|
||||
```
|
||||
|
||||
`reserve_book` 的表單只有一個 `title` 欄位,完全沒有 `stock`。用 `Dune` 呼叫它:
|
||||
|
||||
```text
|
||||
Reserved 'Dune' (6 copies left).
|
||||
```
|
||||
|
||||
工具本體什麼都沒查:`check_stock` 先執行,它回傳的 `Stock` 以引數的形式送了進來。試試 `Neuromancer`,同一個解析器會交給工具一個零。
|
||||
|
||||
!!! tip
|
||||
其實可以直接在工具本體裡呼叫 `check_stock(title)`。當這個值值得比一個輔助函式呼叫更鄭重的對待時,再把它宣告成相依性:每個需要庫存的工具都宣告同一個參數,而且不管有多少個工具宣告它,SDK 每次呼叫最多只執行解析器一次。接下來幾節補上其餘部分:彼此相依的解析器,以及會詢問使用者的解析器。
|
||||
|
||||
## 相依性的相依性 {#dependencies-of-dependencies}
|
||||
|
||||
解析器可以用同樣的註記宣告自己的相依性:
|
||||
|
||||
```python title="server.py" hl_lines="22 29-30"
|
||||
--8<-- "docs_src/dependencies/tutorial002.py"
|
||||
```
|
||||
|
||||
* `estimate_delivery` 相依於 `check_stock`。SDK 依序執行這張圖:先是庫存,再來是預估,最後是工具。
|
||||
* `stock` 和 `delivery` 最終都需要 `check_stock`,但它**每次呼叫只執行一次**。一次庫存查詢,兩個取用端。
|
||||
* 不需要註冊任何東西。這張圖**就是**那些註記。
|
||||
|
||||
!!! check
|
||||
別光憑信任就接受「每次呼叫一次」。在 `check_stock` 裡放一個 `print`,再從 Inspector 呼叫 `order_book`:每次呼叫印出一行。兩個取用端,一次查詢。
|
||||
|
||||
SDK 在工具註冊時分析這張圖,而不是在呼叫時。無法歸類的參數(不是 `Context`、不是 `Resolve(...)`、也不是工具引數的名稱)以及解析器之間的循環,都會在啟動時引發 `InvalidSignature`。伺服器在任何用戶端連上之前就會失敗,錯誤訊息裡會指出出問題的參數或解析器。
|
||||
|
||||
解析器的參數解析方式和工具的完全一樣:另一個 `Resolve(...)`、依名稱對應的工具引數,或是 `Context`:`ctx.headers`、生命週期物件,全部都拿得到。
|
||||
|
||||
!!! warning
|
||||
在 HTTP 傳輸上,`Context` 包含 `ctx.headers`。標頭和任何工具引數一樣,是**用戶端提供的輸入**:拿來放語系或功能旗標沒問題,但絕不能當作身分。呼叫端是誰,要由授權層(**[授權](../run/authorization.md)**)決定,而不是任何人都能設定的標頭。
|
||||
|
||||
!!! tip
|
||||
「每次呼叫一次」就是字面上的意思:下一次 `tools/call` 會再執行一次 `check_stock`。應該活得比單一請求久的資源(資料庫連線池、HTTP 用戶端)屬於 **[生命週期](lifespan.md)** 的範疇,解析器可以透過 `ctx.request_context.lifespan_context` 取得它。
|
||||
|
||||
## 非問不可時才問 {#ask-when-you-must}
|
||||
|
||||
解析器不一定要知道答案。它可以回傳 `Elicit(message, Model)`,SDK 就會去問使用者,動用的是 **[徵詢(elicitation)](elicitation.md)** 機制,替你代勞:
|
||||
|
||||
```python title="server.py" hl_lines="26-32 39"
|
||||
--8<-- "docs_src/dependencies/tutorial003.py"
|
||||
```
|
||||
|
||||
* 有庫存:`confirm_backorder` 直接回傳一個 `Backorder`。**不提問,不往返。**只有在使用者的答案有影響時才會打擾他們。
|
||||
* 沒庫存:SDK 送出徵詢,依 `Backorder` 驗證答案,再注入進來。解析器完全不碰協定。
|
||||
* 工具像讀其他引數一樣讀取 `backorder.confirm`。回答**不要**也算是一種回答:徵詢以 `confirm=False` 被接受,工具照樣執行,只是不下訂單。提問變成了前置條件,而不是塞在工具本體裡的管線程式碼。
|
||||
|
||||
那如果使用者根本不回答,拒絕了這個問題或是取消它呢?
|
||||
|
||||
!!! check
|
||||
對 `Neuromancer` 執行 `order_book`,然後拒絕這個問題。註記寫成 `Annotated[Backorder, Resolve(...)]` 時,工具本體根本不會執行;呼叫會失敗,回傳模型讀得懂的錯誤結果:
|
||||
|
||||
```text
|
||||
Error executing tool order_book: Resolver for parameter 'backorder' could not resolve: elicitation was decline
|
||||
```
|
||||
|
||||
對前置條件來說,這是正確的預設行為:沒有答案,就沒有訂單。如果拒絕是工具想自己處理的結果(跳過缺貨預訂,但仍然推薦另一本書),就改註記成 `ElicitationResult[Backorder]`,工具會收到完整的接受/拒絕/取消結果,可以據此分支。**[徵詢](elicitation.md)** 示範了那種寫法,以及關於提問的其他一切:schema 規則、三種回答、對話中用戶端那一側。
|
||||
|
||||
!!! info
|
||||
框架依協商出的協定版本決定問題走哪種傳輸;上面的程式碼在兩種情況下完全相同。在 **2026-07-28** 及之後,問題搭在一個多輪往返(multi-round-trip)的 `tools/call` 裡:伺服器回傳問題,用戶端的 `elicitation_callback` 回答它,`Client` 替你重試這次呼叫(**[多輪往返請求](multi-round-trip.md)**)。在 **2025-11-25** 及更早,則是呼叫途中的一個同步徵詢請求。每個問題在每次呼叫中恰好問一次,這是對問題的保證,不是對解析器的保證。在多輪往返的形式下,每當呼叫在提問後恢復,任何解析器都可能再執行一次,所以 `return Elicit(...)` 之前的程式碼在每一輪都會執行;已記錄的答案接著會滿足重複出現的問題,不會再次詢問使用者。已記錄的答案只在解析器提問時才會被查閱;像 `check_stock` 這樣**不**提問就給出答案的解析器,永遠提供自己計算出的值。因為每個答案都要對回它的問題,會徵詢的解析器必須從工具的引數和先前的答案確定性地推導出它的問題。每次呼叫才產生的值(`default_factory` 產生的 id、時間戳記)在每一輪都會重新推導,不能出現在答案要綁定的問題裡。用這種易變資料組出的問題會讓每個已記錄的答案看起來都過期,於是伺服器每一輪都重問一次,直到用戶端的輪數上限結束這次呼叫。
|
||||
|
||||
## 問用戶端,不是問使用者 {#ask-the-client-not-the-user}
|
||||
|
||||
徵詢是解析器能問的三種問題之一,而多輪往返流程不允許其他種類。另外兩種是問**用戶端**而不是使用者:回傳 `Sample(...)` 透過用戶端執行一次 LLM 呼叫(一個 `sampling/createMessage` 請求),或回傳 `ListRoots()` 取得用戶端目前的根目錄(roots)。兩者都沒有接受/拒絕的結果;取用端直接註記結果型別,`CreateMessageResult`(請求帶有 `tools` 或 `tool_choice` 時是 `CreateMessageResultWithTools`)或 `ListRootsResult`:
|
||||
|
||||
```python title="server.py" hl_lines="10-15 21"
|
||||
--8<-- "docs_src/dependencies/tutorial004.py"
|
||||
```
|
||||
|
||||
* 框架替它們安排路徑的方式和 `Elicit` 完全一樣:在 **2026-07-28** 上走多輪往返的 `tools/call` 內部,在 **2025-11-25** 上走獨立的伺服器→用戶端請求。未宣告的能力會以 `-32021` 協定錯誤拒絕這次呼叫(`sampling`、`roots`、表單模式的 `elicitation`;請求帶有 `tools` 或 `tool_choice` 時是 `sampling.tools`)。
|
||||
* 上面資訊框裡關於問題的一切原封不動地適用:`Sample` 請求是以它精確的呈現內容對應到已記錄的結果,所以要從工具的引數和先前的答案確定性地建構它;這樣用戶端每次工具呼叫只付一次 LLM 呼叫的代價,而不是每一輪一次。已記錄的結果在這次呼叫剩餘的過程中都搭在 `request_state` 上,所以非常大的生成結果會讓剩下的每次往返都變得更重。
|
||||
* 獨立的取樣(sampling)和根目錄**功能**在 2026-07-28 已棄用(SEP-2577)。需要用戶端模型的新伺服器透過這個載體來問;不需要的伺服器應該直接整合 LLM 供應商。`"none"` 以外的 `include_context` 值本身也已棄用;避免使用。
|
||||
|
||||
## 重點回顧 {#recap}
|
||||
|
||||
* 在工具參數上寫 `Annotated[T, Resolve(fn)]`:SDK 執行 `fn` 並注入它的回傳值。
|
||||
* 解析出來的參數模型看不到,用戶端也無法提供。模型不該自己捏造的值(價格、身分、權限)就屬於這裡。
|
||||
* 解析器的參數用同樣的方式解析:`Context`、另一個 `Resolve(...)`,或依名稱對應的工具引數。不管有多少取用端,這張圖每一輪最多執行每個解析器一次;每個問題恰好問一次,而呼叫在提問後恢復時,任何解析器都可能再執行一次。
|
||||
* 有問題的圖在註冊時就以 `InvalidSignature` 失敗,而不是呼叫到一半才出錯。
|
||||
* 回傳 `Elicit(message, Model)` 來詢問使用者,而且只在非問不可時才問。未包裝的註記遇到拒絕會中止;`ElicitationResult[T]` 讓工具可以分支。
|
||||
* 回傳 `Sample(...)` 或 `ListRoots()` 向用戶端要一個 LLM 生成結果或根目錄清單;注入的是單純的結果。
|
||||
|
||||
伺服器在啟動時建立一次的狀態,以及處理函式如何取得它,請見 **[生命週期](lifespan.md)** 頁面。
|
||||
175
i18n/zh-hant/pages/handlers/elicitation.md
Normal file
175
i18n/zh-hant/pages/handlers/elicitation.md
Normal file
|
|
@ -0,0 +1,175 @@
|
|||
---
|
||||
translation:
|
||||
sections: [335ca2a0b266f003, d1ad562d3fe87bc0, 0bb1396c86daeba4, d1cb1235bb9ee267, 833179c09d239c83, e5d6dec2d2e655e8]
|
||||
tool: 1
|
||||
---
|
||||
# 徵詢 {#elicitation}
|
||||
|
||||
工具做到一半、只差一個答案時,不一定要就此失敗。
|
||||
|
||||
**徵詢(elicitation)** 讓它可以開口問。在工具呼叫進行到一半時,使用者會收到一個問題,而他們的回答會回到同一次函式呼叫裡。
|
||||
|
||||
有兩種模式:
|
||||
|
||||
* **表單模式**:需要一個值(確認、日期、數量)。你描述欄位,用戶端負責呈現表單。
|
||||
* **URL 模式**:需要使用者到別的地方去(OAuth 同意畫面、付款頁面)。他們在那裡做的任何事都不會經過協定。
|
||||
|
||||
問的方式也有兩種。該優先採用的是**解析器**:把問題掛在參數上,由 SDK 來問,不論哪種連線、不論用戶端說的是哪個協定世代都行。直接的方式 `await ctx.elicit(...)` 是從**伺服器**發往**用戶端**的請求,這條通道只有在舊版連線(規格版本 2025-11-25 或更早)上的用戶端才有。兩種本頁都會介紹,先從解析器開始。
|
||||
|
||||
## 用解析器來問 {#ask-with-a-resolver}
|
||||
|
||||
決定整個工具能否繼續的問題(「確定嗎?三個符合的帳號要哪一個?」)可以從工具本體抽出來放進**解析器**,由框架替你問。
|
||||
|
||||
標註為 `Annotated[T, Resolve(fn)]` 的參數,會在工具本體執行前先執行 `fn` 來填入。解析器已經知道答案時就直接回傳值,否則回傳 `Elicit(...)` 讓框架去問:
|
||||
|
||||
```python title="server.py" hl_lines="24-30 35-36"
|
||||
--8<-- "docs_src/elicitation/tutorial004.py"
|
||||
```
|
||||
|
||||
* `confirm_delete` 依名稱讀取工具自己的 `path` 引數,列出資料夾內容,而且**只在必要時才徵詢**:空資料夾直接解析為 `Confirm(ok=True)`,完全不需要與用戶端往返。
|
||||
* `delete_folder` 標註的是 `ElicitationResult[Confirm]`,所以框架會注入完整的結果,工具再用 `match` 處理每一種情況:接受並確認、接受但保留(`ok=False`)、拒絕、取消。
|
||||
* `confirm` 參數永遠不會出現在工具的輸入 schema 裡:`path` 由用戶端提供,`confirm` 由解析器提供。
|
||||
|
||||
如果工具不需要分支處理,改為標註未包裝的模型(`Annotated[Confirm, Resolve(confirm_delete)]`)即可:接受時工具會收到模型,拒絕或取消時整個呼叫會以錯誤中止。
|
||||
|
||||
解析器在**每一種**連線上都能用。對舊版連線上的用戶端,SDK 會直接把問題送過去;在 **2026-07-28** 連線上,SDK 會把問題從呼叫中**回傳**出去,用戶端下一次嘗試時再帶著答案回來。解析器完全不知道其中的差別;底下發生的事請見**[多輪往返(multi-round-trip)請求](multi-round-trip.md)**。
|
||||
|
||||
問問題只是解析器能做的事情之一。通用的機制(不用問就能算出值的相依性、相依性的相依性、模型能提供與不能提供什麼)請見**[相依性](dependencies.md)**頁面。
|
||||
|
||||
## 在工具內部問 {#ask-from-inside-the-tool}
|
||||
|
||||
工具也可以在自己的本體執行到一半時停下來問。
|
||||
|
||||
!!! warning
|
||||
`ctx.elicit()` 和 `ctx.elicit_url()` 是從**伺服器**發往**用戶端**的請求,這條通道只有在舊版連線(規格版本 **2025-11-25** 或更早)上的用戶端才有。在 **2026-07-28** 連線上沒有由伺服器發起的請求,所以這些呼叫會失敗。解析器則兩種都能用。完整說明請見**[協定版本](../protocol-versions.md)**。
|
||||
|
||||
`await ctx.elicit()` 接受一則訊息和一個 Pydantic 模型:
|
||||
|
||||
```python title="server.py" hl_lines="9-11 20-23 25"
|
||||
--8<-- "docs_src/elicitation/tutorial001.py"
|
||||
```
|
||||
|
||||
* **`Context`** 參數就是讓你能用 `ctx.elicit` 的東西;任何工具都可以接收一個。這個物件有自己的頁面:**[Context](context.md)**。
|
||||
* `AlternativeDate` 是你想要的答案的 **schema**。
|
||||
* 這個工具是 `async def`。非如此不可:它會在中途停下來等一個人回答。
|
||||
* 其他任何日期,工具都會直接回傳。只有在必要時才問。
|
||||
* 使用者接受的日期會再經過 `book_table` 本身處理一次。回答和其他輸入沒有兩樣:如果替代日期也訂滿了,會再問一次,而不是盲目確認。
|
||||
|
||||
### 用戶端收到什麼 {#what-the-client-receives}
|
||||
|
||||
用戶端會收到你的訊息,旁邊附上一份從模型產生的 JSON Schema:
|
||||
|
||||
```json
|
||||
{
|
||||
"properties": {
|
||||
"accept_alternative": {
|
||||
"description": "Try another date?",
|
||||
"title": "Accept Alternative",
|
||||
"type": "boolean"
|
||||
},
|
||||
"date": {
|
||||
"default": "2025-12-26",
|
||||
"description": "Alternative date (YYYY-MM-DD)",
|
||||
"title": "Date",
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": ["accept_alternative"],
|
||||
"title": "AlternativeDate",
|
||||
"type": "object"
|
||||
}
|
||||
```
|
||||
|
||||
那份 schema 就是表單。`Field(description=...)` 是標籤;預設值會預先填入輸入框,並讓該欄位變成選填。這和**[工具](../servers/tools.md)**頁面描述工具引數時用的是同一套 Pydantic 轉 JSON Schema 機制。
|
||||
|
||||
!!! warning
|
||||
徵詢用的 schema 表達能力不如工具的輸入 schema。只能用扁平的基本型別欄位:`str`、`int`、`float`、`bool`,或是字串組成的 `Literal`(會變成 `enum`)。如果在模型裡再放一個模型,`ctx.elicit` 會在送出任何東西給用戶端之前就引發例外:
|
||||
|
||||
```text
|
||||
TypeError: Elicitation schema field 'address' rendered as {'$ref': '#/$defs/Address'}, which is not a valid PrimitiveSchemaDefinition
|
||||
```
|
||||
|
||||
你是在打斷一個正在做事的人。如果答案需要巢狀結構,它本來就該是工具的引數。
|
||||
|
||||
### 三種回答 {#the-three-answers}
|
||||
|
||||
`result.action` 告訴你使用者做了什麼,可能性恰好只有三種:
|
||||
|
||||
* `"accept"`:他們送出了表單。`result.data` 是一個 `AlternativeDate` 實例,已經驗證過。
|
||||
* `"decline"`:他們說不要。
|
||||
* `"cancel"`:他們沒有選擇就關掉了問題。
|
||||
|
||||
`result.data` 只在 `"accept"` 時存在,這就是範例先檢查 `result.action` 的原因。型別檢查器會強制這個順序:在 `result.action == "accept"` 之後,`result.data` 是 `AlternativeDate`;在那之前,根本沒有 `.data`。
|
||||
|
||||
拒絕不是錯誤。拒絕代表什麼由工具決定(這裡是不訂位),然後照常回答模型。
|
||||
|
||||
!!! tip
|
||||
回答在你的程式碼看到之前,就會先依照模型驗證。用戶端若在 `bool` 欄位送來 `"maybe"`,也不會弄壞你的訂位:呼叫會以 schema 不符的錯誤失敗,你的 `if` 根本不會執行。
|
||||
|
||||
## 把使用者送往一個 URL {#send-the-user-to-a-url}
|
||||
|
||||
有些東西絕對不能經過模型或用戶端:憑證、卡號、OAuth 同意。遇到這些,你不是要資料,而是請使用者到某個地方去:
|
||||
|
||||
```python title="server.py" hl_lines="10-14 23"
|
||||
--8<-- "docs_src/elicitation/tutorial002.py"
|
||||
```
|
||||
|
||||
* `ctx.elicit_url()` 接受訊息、要造訪的 **URL**,以及一個你自己選的 `elicitation_id`:任何能在伺服器內識別這次徵詢的字串都行。
|
||||
* 結果只有一個 action,沒有別的。`"accept"` 代表使用者同意開啟 URL,**不是**代表他們完成了另一頭的事。
|
||||
* 付款在頻外進行,發生在使用者的瀏覽器和你的金流服務商之間。沒有任何內容會透過 MCP 回來。
|
||||
|
||||
看看第二個工具。當伺服器得知頻外流程完成時(webhook、輪詢;這裡用第二個工具來模擬),`ctx.session.send_elicit_complete(...)` 會以同一個 `elicitation_id` 送出 `notifications/elicitation/complete`。用戶端就是靠這個知道可以停止顯示「等待付款中……」。少了它,用戶端只能猜。
|
||||
|
||||
## 用戶端這一邊 {#the-client-side}
|
||||
|
||||
伺服器負責問。用戶端回答的方式,是把一個 **`elicitation_callback`** 傳給 `Client(...)`:
|
||||
|
||||
```python title="client.py" hl_lines="6-7 18"
|
||||
--8<-- "docs_src/elicitation/tutorial003.py"
|
||||
```
|
||||
|
||||
* 一個回呼處理兩種模式。`params` 是 `ElicitRequestFormParams` 和 `ElicitRequestURLParams` 的聯集;用 `isinstance` 來分支。
|
||||
* 若是 URL,把 `params.url` 顯示給使用者,回傳他們選的 action。絕不帶任何 `content`。
|
||||
* 若是表單,真正的應用程式會呈現 `params.requested_schema`,並把使用者的輸入當作 `content` 回傳。這裡的回呼永遠用一個固定答案說好,正是測試裡想要的那種回呼。
|
||||
* 傳入回呼同時也是**能力宣告**:伺服器就是靠這個得知這個用戶端可以被問。用戶端還能替伺服器回答的其他事情,請見**[用戶端回呼](../client/callbacks.md)**。
|
||||
|
||||
!!! info
|
||||
徵詢是從**伺服器**發往**用戶端**的請求,而這種請求只存在於傳統交握的工作階段(session)上,這就是這個用戶端傳入 `mode="legacy"` 的原因。在 **2026-07-28** 連線上,工具改為把問題從呼叫中**回傳**出去來問;那個流程請見**[多輪往返請求](multi-round-trip.md)**。
|
||||
|
||||
### 試試看 {#try-it}
|
||||
|
||||
用 Streamable HTTP 啟動 `ctx.elicit` 表單模式的 `server.py`(有 `book_table` 的那個;一行指令請見**[執行伺服器](../run/index.md)**),然後執行用戶端的 `main()`,向 `book_table` 訂聖誕節當天。
|
||||
|
||||
回呼會印出它收到的問題:
|
||||
|
||||
```text
|
||||
No tables for 2 on 2025-12-25. Would you like to try another date?
|
||||
```
|
||||
|
||||
它回答 `{"accept_alternative": True, "date": "2025-12-27"}`,而一直在 `await ctx.elicit(...)` 裡等著的工具便完成訂位:
|
||||
|
||||
```text
|
||||
Booked a table for 2 on 2025-12-27.
|
||||
```
|
||||
|
||||
現在換成 URL 模式的 `server.py`,讓同一個 `main()` 改呼叫 `pay_deposit`:同一個回呼會走另一個分支,印出付款連結,工具則回傳「Complete the payment in your browser.」。呼叫途中的一次往返,雙向都走過了。
|
||||
|
||||
!!! check
|
||||
現在把 `elicitation_callback=` 從 `Client` 拿掉,再向 `book_table` 訂一次聖誕節當天。整個呼叫會以協定錯誤失敗:
|
||||
|
||||
```text
|
||||
Elicitation not supported
|
||||
```
|
||||
|
||||
沒有註冊回呼的用戶端從來沒有宣告 `elicitation` 能力,所以沒有人可以問。你的工具拿到的不是 `"decline"`,而是例外。設計時要考慮到這點:每一個徵詢都需要對「如果沒辦法問怎麼辦?」有個合理的答案。
|
||||
|
||||
## 重點回顧 {#recap}
|
||||
|
||||
* 標註為 `Annotated[T, Resolve(fn)]` 的參數由解析器填入,解析器必須問的時候就回傳 `Elicit(...)`。在每一種連線上都能用。
|
||||
* schema 是一個扁平的 Pydantic 模型:只能有基本型別欄位,回來的路上會驗證。
|
||||
* `result.action` 是 `"accept"`、`"decline"` 或 `"cancel"`;`result.data` 只在 accept 時存在。
|
||||
* `await ctx.elicit(message, schema=Model)` 從工具本體內部問,`await ctx.elicit_url(message, url, elicitation_id)` 則用於所有絕對不能經過模型的東西(`ctx.session.send_elicit_complete(elicitation_id)` 表示頻外的部分完成了)。兩者都是伺服器對用戶端的請求:需要用戶端在舊版連線上。
|
||||
* 用戶端用一個 `elicitation_callback` 回答,依 params 的型別分支;註冊它就是宣告能力。
|
||||
* 在 2026-07-28 連線上,伺服器是回傳問題而不是推送問題;同一個回呼改由**[多輪往返請求](multi-round-trip.md)**餵入。
|
||||
|
||||
那個回傳底下的一切(重試迴圈、保護 `requestState`、自己驅動它)請見**[多輪往返請求](multi-round-trip.md)**。
|
||||
24
i18n/zh-hant/pages/handlers/index.md
Normal file
24
i18n/zh-hant/pages/handlers/index.md
Normal file
|
|
@ -0,0 +1,24 @@
|
|||
---
|
||||
translation:
|
||||
sections: [424930166c4bc6f3]
|
||||
tool: 1
|
||||
---
|
||||
# 在處理函式內部 {#inside-your-handler}
|
||||
|
||||
處理函式的引數來自用戶端。除此之外它能讀到的**其他**一切,以及執行時能做的一切,都在這裡。
|
||||
|
||||
它能讀到什麼:
|
||||
|
||||
* **[Context](context.md)** 是任何處理函式都能額外要求的那一個參數:進行中的請求、它的標頭、它的工作階段(session),以及進度與變更通知的操作。
|
||||
* **[相依性](dependencies.md)** 是模型永遠看不到的參數,由你自己的函式透過 `Resolve` 填入。
|
||||
* **[生命週期](lifespan.md)** 說明伺服器在啟動時只建立一次的狀態,以及處理函式如何透過 `Context` 取得它。
|
||||
|
||||
它執行時能做什麼:
|
||||
|
||||
* 用 **[徵詢](elicitation.md)**(elicitation)向使用者要求更多輸入,以及承載它的 2026-07-28 模式 **[多輪往返請求](multi-round-trip.md)**(multi-round-trip)。
|
||||
* 用 **[取樣與根目錄](sampling-and-roots.md)**(sampling 與 roots)向用戶端要求 LLM 生成結果或它的工作區資料夾,這兩者已棄用但仍然提供。
|
||||
* 對耗時的工作回報 **[進度](progress.md)**。
|
||||
* 用 **[記錄](logging.md)** 寫入記錄(寫到標準錯誤輸出,給負責維運伺服器的人看)。
|
||||
* 用 **[訂閱](subscriptions.md)** 告訴已訂閱的用戶端有東西變了。
|
||||
|
||||
如果還沒有註冊處理函式,請從 **[工具](../servers/tools.md)** 開始。這裡的每一頁都假設你已經有一個。
|
||||
101
i18n/zh-hant/pages/handlers/lifespan.md
Normal file
101
i18n/zh-hant/pages/handlers/lifespan.md
Normal file
|
|
@ -0,0 +1,101 @@
|
|||
---
|
||||
translation:
|
||||
sections: [f3ca8ac5f90f2dfa, 85a1ef3588ba0736, 563346d4d5804933, 9e3528340d0bab53]
|
||||
tool: 1
|
||||
---
|
||||
# 生命週期 {#lifespan}
|
||||
|
||||
大多數真實的伺服器在整個生命期間都會持有某些東西:資料庫連線池、HTTP 用戶端、載入好的模型。
|
||||
|
||||
你不會想在每次呼叫時都重新建立它,卻會想乾淨地把它關閉。這就是**生命週期**(lifespan)的用途。
|
||||
|
||||
## 有型別的生命週期 {#a-typed-lifespan}
|
||||
|
||||
生命週期是一個 `@asynccontextmanager`,它接收伺服器並 `yield` **一個物件**。不論 yield 出什麼,只要伺服器還在執行,每個處理函式都能取用它。
|
||||
|
||||
```python title="server.py" hl_lines="25-31 34 38 40"
|
||||
--8<-- "docs_src/lifespan/tutorial001.py"
|
||||
```
|
||||
|
||||
由下往上讀:
|
||||
|
||||
* `app_lifespan` 在 `yield` **之前**連接 `Database`,並在**之後**於 `finally` 區塊中斷開連線。這就是啟動與關閉。
|
||||
* 它 yield 出一個 `AppContext`,一個普通的 dataclass,裝著你設定好的東西。今天一個欄位,明天十個。
|
||||
* `MCPServer("Bookshop", lifespan=app_lifespan)` 就是全部的接線。
|
||||
* 在工具內部,yield 出來的物件就是 `ctx.request_context.lifespan_context`。
|
||||
|
||||
生命週期只會執行**一次**。伺服器啟動時(第一個請求之前)進入,伺服器停止時離開。其間的每個請求都共用同一個 `AppContext`。
|
||||
|
||||
!!! info
|
||||
如果你寫過 FastAPI 的 `lifespan`,這些你早就會了。同樣的裝飾器、同樣的 `yield`、同樣的 `finally`。
|
||||
|
||||
### 模型看到什麼 {#what-the-model-sees}
|
||||
|
||||
沒有新東西。`ctx` 是一個 **Context** 參數,所以 SDK 會注入它,它永遠不會進到輸入 schema:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"genre": {"title": "Genre", "type": "string"}
|
||||
},
|
||||
"required": ["genre"],
|
||||
"title": "count_booksArguments"
|
||||
}
|
||||
```
|
||||
|
||||
`genre` 是模型唯一能傳入的引數。生命週期是伺服器自己的事。
|
||||
|
||||
`@mcp.resource()` 和 `@mcp.prompt()` 函式也可以接收 `ctx` 參數,寫成不帶型別參數的 `Context`,原因下一節會說明。`ctx` 所攜帶的一切,請見 **[Context](context.md)**。
|
||||
|
||||
### 它真的有型別 {#it-really-is-typed}
|
||||
|
||||
再看一次型別註記:`ctx: Context[AppContext]`。
|
||||
|
||||
就是這一個型別參數,讓型別檢查器把 `ctx.request_context.lifespan_context` **當作** `AppContext`。`.db` 會自動完成;`.dbb` 在你執行伺服器之前就是錯誤。
|
||||
|
||||
如果改寫成不帶型別參數的 `Context`,`lifespan_context` 的型別就是 `dict[str, Any]`:型別檢查器無從得知你的生命週期 yield 了什麼。執行時物件還在;你失去的是協助。
|
||||
|
||||
!!! warning
|
||||
`Context[AppContext]` 是**只限工具**的寫法。把它放在 `@mcp.resource()` 或 `@mcp.prompt()` 函式上,對該處理函式的每次呼叫都會失敗。用戶端會收到錯誤,伺服器記錄會顯示原因:
|
||||
|
||||
```text
|
||||
Context is not available outside of a request
|
||||
```
|
||||
|
||||
在資源和提示詞裡,寫不帶型別參數的 `ctx: Context`。生命週期 yield 出來的物件在執行時仍然是 `ctx.request_context.lifespan_context`;放棄的只是型別參數,不是物件。
|
||||
|
||||
!!! tip
|
||||
生命週期永遠存在。如果不傳入,SDK 的預設會 yield 一個空的 `dict`,所以 `ctx.request_context.lifespan_context` 是 `{}`,永遠不會是 `None`。這個預設也是為什麼不帶型別參數的 `Context` 會把它的型別定為 `dict[str, Any]`。
|
||||
|
||||
## 親眼看它發生 {#watch-it-happen}
|
||||
|
||||
「啟動會在第一個請求之前執行」這種句子,不該只能憑信心接受。
|
||||
|
||||
把伺服器精簡到只剩生命週期:替 `Database` 加一個 `connected` 旗標,在 `connect()` 和 `disconnect()` 裡切換它,再加一個回報它的工具。
|
||||
|
||||
```python title="server.py" hl_lines="11 14 17 25 44"
|
||||
--8<-- "docs_src/lifespan/tutorial002.py"
|
||||
```
|
||||
|
||||
`database` 放在模組層級只有一個原因:讓你能從伺服器**外部**觀察它。
|
||||
|
||||
!!! check
|
||||
三個時刻,三個值:
|
||||
|
||||
* 伺服器啟動前,`database.connected` 是 `False`。匯入模組什麼都沒連接。
|
||||
* 執行中,呼叫 `database_status`,結果是 `"connected"`。
|
||||
* 停止伺服器,`finally` 區塊就會執行:`database.connected` 又變回 `False`。
|
||||
|
||||
工作正好發生在你放它的地方:圍繞著 `yield`,不是在匯入時,也不是每個請求一次。
|
||||
|
||||
## 重點回顧 {#recap}
|
||||
|
||||
* `lifespan=` 接收一個 `@asynccontextmanager`,它接收伺服器並 `yield` 一個物件。
|
||||
* `yield` 之前的程式碼是啟動。之後的 `finally` 是關閉。
|
||||
* 它只執行一次,涵蓋伺服器的整個生命,而不是每個請求一次。
|
||||
* 不論 `yield` 什麼,在每個工具、資源和提示詞裡都是 `ctx.request_context.lifespan_context`。
|
||||
* `ctx: Context[AppContext]` 讓工具裡的這種存取完全有型別。資源和提示詞則用不帶型別參數的 `Context`。
|
||||
* 沒有 `lifespan=` 代表一個空的 `dict`,永遠不會是 `None`。
|
||||
|
||||
在呼叫途中停下來、向使用者詢問只有他們才知道的事的處理函式,就是 **[徵詢(elicitation)](elicitation.md)**。
|
||||
79
i18n/zh-hant/pages/handlers/logging.md
Normal file
79
i18n/zh-hant/pages/handlers/logging.md
Normal file
|
|
@ -0,0 +1,79 @@
|
|||
---
|
||||
translation:
|
||||
sections: [c93a3e1aefd77955, 7851abd5ec54393b, f49d1ca2f330f9cd, c03764bd9dfeef7b, 4a0391691a674ae4, 2df5cd279eabf9f5]
|
||||
tool: 1
|
||||
---
|
||||
# 記錄 {#logging}
|
||||
|
||||
在工具裡寫記錄的方式,和在其他任何 Python 函式裡一樣:用標準函式庫。
|
||||
|
||||
MCP 有一個協定層級的 **logging 能力**:伺服器可以透過 `Context` 物件上的方法,把記錄訊息以通知的形式推送給用戶端。規格的 2026-07-28 修訂版**將這個能力標為已棄用,而且沒有提供替代方案**,所以這份說明文件不教它。哪些東西已棄用、該改用什麼,完整清單請見 **[已棄用的功能](../deprecated.md)**。
|
||||
|
||||
該改用的做法,就是在其他任何 Python 程式裡會用的做法:標準函式庫。
|
||||
|
||||
## 會寫記錄的工具 {#a-tool-that-logs}
|
||||
|
||||
```python title="server.py" hl_lines="1 5 13"
|
||||
--8<-- "docs_src/logging/tutorial001.py"
|
||||
```
|
||||
|
||||
* `logging.getLogger(__name__)` 會給你一個以模組名稱命名的 logger。在檔案最上方建立一次就好。
|
||||
* 在工具裡呼叫 `logger.info(...)`,就跟在其他任何函式裡一樣。不用注入什麼、不用 `await` 什麼,也沒有任何 MCP 專屬的東西。
|
||||
|
||||
!!! check
|
||||
呼叫這個工具,看看完整的結果:
|
||||
|
||||
```python
|
||||
result.content # [TextContent(text="Found 3 books matching 'dune'.")]
|
||||
result.structured_content # {'result': "Found 3 books matching 'dune'."}
|
||||
```
|
||||
|
||||
記錄那一行完全不在裡面。記錄是寫給**你**看的,也就是負責維運伺服器的人。模型永遠看不到它。如果有東西該讓模型讀到,就 `return` 它。
|
||||
|
||||
## 記錄去了哪裡 {#where-it-goes}
|
||||
|
||||
對 **stdio** 伺服器來說,這個問題比平常更重要。主機把你的伺服器當成子處理程序啟動,並從它的 **stdout** 讀取 MCP 訊息。標準錯誤是你的。
|
||||
|
||||
標準函式庫本來就做對了:記錄輸出預設寫到 `sys.stderr`。你的 `logger.info(...)` 那些行會出現在終端機(或主機收集子處理程序 stderr 的地方),協定串流則保持乾淨。
|
||||
|
||||
!!! tip
|
||||
不要在 stdio 伺服器裡用 `print()`。`print` 寫到 **stdout**,而 stdout 屬於協定。服務期間,SDK 會把實際**被 flush** 的 stdout 輸出轉向 stderr,所以它不會弄壞線路;但在區塊緩衝的處理程序裡,`print()` 的內容通常會一直留在 `sys.stdout` 的緩衝區裡沒被 flush,直到直譯器在結束時把它排空,直接倒進協定串流。就算被轉向了,那一行也是原封不動地混在記錄輸出之中,沒有層級、沒有 logger 名稱,也沒辦法過濾。
|
||||
|
||||
`logger.debug("got here")` 一樣只是一行的功夫,而且會去到對的地方。
|
||||
|
||||
## 層級 {#the-level}
|
||||
|
||||
不需要自己呼叫 `logging.basicConfig()`。建立 `MCPServer` 時就已經呼叫過了:它裝上一個指向標準錯誤的 handler,層級就是你以 `log_level=` 傳入的值,所以只要 `MCPServer("Bookshop", log_level="DEBUG")` 就能看到 `logger.debug(...)` 那些行。
|
||||
|
||||
預設值是 `"INFO"`。
|
||||
|
||||
`logging.basicConfig()` 永遠不會取代已經存在的 handler。如果在建立伺服器之前就自己設定好記錄,以你的設定為準。
|
||||
|
||||
## 試試看 {#try-it}
|
||||
|
||||
用 MCP Inspector 執行伺服器:
|
||||
|
||||
```console
|
||||
uv run mcp dev server.py
|
||||
```
|
||||
|
||||
從 **Tools** 分頁呼叫 `search_books`。Inspector 會顯示結果:只有回傳值。至於這一行
|
||||
|
||||
```text
|
||||
Searching for 'dune'
|
||||
```
|
||||
|
||||
則去了標準錯誤:終端機,而不是線路。
|
||||
|
||||
!!! info
|
||||
如果你真正想要的是**追蹤**(每個請求、花了多久、有沒有失敗),那你要的不是記錄行,而是 span。你的伺服器已經在送出它們了:SDK 預設就用 OpenTelemetry 追蹤每一則訊息。請見 **[OpenTelemetry](../run/opentelemetry.md)**。
|
||||
|
||||
## 重點回顧 {#recap}
|
||||
|
||||
* MCP 協定的 logging 能力已被 2026-07-28 規格棄用,且沒有替代方案。不要以它為基礎開發。
|
||||
* 模組層級寫 `logger = logging.getLogger(__name__)`,工具裡寫 `logger.info(...)`。整個模式就這樣。
|
||||
* 記錄輸出永遠到不了模型。只有 `return` 的值會。
|
||||
* 標準錯誤是你的;stdout 屬於協定。服務期間,SDK 會把被 flush 的零星 stdout 輸出轉向 stderr,但沒被 flush 的 `print()` 仍可能在結束時排空到線路上,而被轉向的行送達時也沒有任何標示;改用 `logging`,它的 handler 每一筆記錄都會 flush。
|
||||
* `MCPServer(..., log_level="DEBUG")` 設定層級,而你先做好的記錄設定不會被動到。
|
||||
|
||||
要告訴已連線的用戶端伺服器上有東西變了(工具清單、某個資源),請見 **[訂閱](subscriptions.md)**。
|
||||
183
i18n/zh-hant/pages/handlers/multi-round-trip.md
Normal file
183
i18n/zh-hant/pages/handlers/multi-round-trip.md
Normal file
|
|
@ -0,0 +1,183 @@
|
|||
---
|
||||
translation:
|
||||
sections: [74011e683045eea9, 9b64cc175c18b6a9, 4b41be4824030397, e3b1502da786ec33, 71e41161f143c6a9, 9ec2c1eeb8c36378, 8dd027377d46448b, f81491125dcbfe8b]
|
||||
tool: 1
|
||||
---
|
||||
# 多輪往返請求 {#multi-round-trip-requests}
|
||||
|
||||
有時候工具沒辦法在一次往返內完成。它需要某個只有使用者手上才有的東西:一個選擇、一個確認、一組憑證。
|
||||
|
||||
在 2026-07-28 之前,伺服器靠**回頭呼叫**來取得:在處理原本那個請求的途中,自己對用戶端開一個請求(一次徵詢(elicitation)、一次取樣(sampling)呼叫)。2026-07-28 規格淘汰了這條反向通道(back-channel)。
|
||||
|
||||
現在,伺服器改成**回傳**。
|
||||
|
||||
## 回傳,不要回頭呼叫 {#return-dont-call-back}
|
||||
|
||||
伺服器用 **`InputRequiredResult`** 而不是 `CallToolResult` 來回應 `tools/call`。其中兩個欄位負責主要的工作:
|
||||
|
||||
* **`input_requests`**:伺服器還需要什麼,以 dict 表示,鍵是伺服器自己取的名稱。每個值是 `ElicitRequest`、`CreateMessageRequest` 或 `ListRootsRequest`。
|
||||
* **`request_state`**:一個不透明的權杖。用戶端在重試時原封不動地送回來。會讀它的只有你的伺服器。
|
||||
|
||||
用戶端逐一滿足這些請求,然後**再次呼叫同一個工具**,把答案放在 `input_responses`,權杖放在 `request_state`。這時伺服器拿到了原本缺的東西,回傳一般的 `CallToolResult`。
|
||||
|
||||
整個協定就這樣。每一段都是用戶端送往伺服器的普通請求,從來沒有東西反方向流動。
|
||||
|
||||
## 伺服器端 {#the-server-side}
|
||||
|
||||
在 `@mcp.tool()` 上很少需要自己動手組這個:宣告一個相依性來詢問使用者(`Elicit`)、對用戶端的 LLM 取樣(`Sample`),或列出它的根目錄(roots,`ListRoots`),SDK 就會替你回傳 `InputRequiredResult`;這種寫法請見 **[相依性](dependencies.md)** 頁面。兩種寫法不能混用:一次呼叫只有一條 `input_responses`/`request_state` 通道,所以用了 `Resolve(...)` 參數的工具,不能再從函式本體回傳 `InputRequiredResult`。宣告了 `InputRequiredResult` 回傳型別的會在註冊時被拒絕(`InvalidSignature`),沒宣告卻回傳的則會在執行時讓呼叫失敗。手動的寫法是**低階** `Server`,它的 `on_call_tool` 處理函式可以回傳兩種結果型別中的任一種:
|
||||
|
||||
```python title="server.py" hl_lines="43-46"
|
||||
--8<-- "docs_src/mrtr/tutorial001.py"
|
||||
```
|
||||
|
||||
* `on_call_tool` 的型別標註是 `-> CallToolResult | InputRequiredResult`。回傳第二種,就是伺服器端全部的 API。
|
||||
* 第一次呼叫時 `params.input_responses` 是 `None`,所以守衛條件成立,處理函式改成提問而不是作答。
|
||||
* 重試時,用戶端送來的 `ElicitResult` 就放在伺服器當初在 `input_requests` 裡用的**同一個鍵**(`"region"`)底下。
|
||||
|
||||
那個檔案裡其他的東西(明確寫出的 `input_schema`、手動組出的 `CallToolResult`)都是一般的低階 `Server`,在 **[低階 Server](../advanced/low-level-server.md)** 有說明。這一頁只多加了第二種回傳型別。
|
||||
|
||||
## 不只是工具 {#beyond-tools}
|
||||
|
||||
`tools/call` 並不特別:在 2026-07-28,伺服器也可以用同樣的方式回應 `prompts/get` 和 `resources/read`。在 `MCPServer` 上,`@mcp.prompt()` 函式(或 `@mcp.resource()` 的**範本**函式)自己回傳 `InputRequiredResult`,並在重試時從 Context 讀取答案:
|
||||
|
||||
```python title="server.py" hl_lines="20 22 24"
|
||||
--8<-- "docs_src/mrtr/tutorial004.py"
|
||||
```
|
||||
|
||||
* 第一輪回傳 `InputRequiredResult`。重試時,`ctx.input_responses` 在同樣的鍵底下放著答案,函式就回傳它平常的結果——這裡是提示詞訊息,若是範本資源則是資源內容。
|
||||
* 你設定的 `request_state` 在上線路之前會先密封,回送時會驗證,和伺服器上其他東西一樣;下方的 **[保護 `requestState`](#protecting-requeststate)** 說明密封帶來什麼保障,以及什麼時候需要設定金鑰。
|
||||
* `@mcp.tool()` 函式在相依性寫法不合用時,也可以用同樣方式直接回傳這個結果。
|
||||
* 靜態的 `@mcp.resource()` 函式不參與:它們不接收 `Context`,所以永遠讀不到重試的內容。只有範本資源可以提問。
|
||||
* 下方的世代規則照樣適用:在 2026 之前的工作階段(session)上回傳 `InputRequiredResult`,就是那則警告所描述的 `-32603`。
|
||||
|
||||
## 用戶端 {#the-client-side}
|
||||
|
||||
`Client` 會替你執行這個迴圈。
|
||||
|
||||
註冊伺服器可能會用到的回呼(`elicitation_callback`、`sampling_callback`、`list_roots_callback`),然後呼叫工具。收到 `InputRequiredResult` 時,`Client` 把 `input_requests` 裡的每一筆分派給對應的回呼,帶著答案和原樣送回的 `request_state` 重試,一直持續到拿回 `CallToolResult` 為止:
|
||||
|
||||
```python title="client.py" hl_lines="11 12"
|
||||
--8<-- "docs_src/mrtr/tutorial003.py"
|
||||
```
|
||||
|
||||
* 那個 `elicitation_callback`,和 2026 之前的伺服器透過反向通道送出 `elicitation/create` 時會觸發的是同一個。`sampling_callback` 之於 `sampling/createMessage`、`list_roots_callback` 之於 `roots/list` 也一樣:在 2026-07-28,獨立的伺服器→用戶端 RPC 已經不存在,但完全相同的 `ElicitRequest`/`CreateMessageRequest`/`ListRootsRequest` 酬載改搭在 `input_requests` 裡,分派到同樣這三個回呼。一組回呼同時服務兩個世代。
|
||||
* `call_tool` 回傳的是普通的 `CallToolResult`。中間那幾輪對呼叫端來說是看不到的。
|
||||
* `get_prompt` 和 `read_resource` 驅動的也是同一個迴圈。
|
||||
|
||||
!!! check
|
||||
不註冊回呼的話,迴圈在第一輪就會失敗:SDK 的替身回呼對每個徵詢都回以錯誤,`call_tool` 會引發 `MCPError`,訊息是「Elicitation not supported」。
|
||||
|
||||
迴圈是有上限的。`Client(..., input_required_max_rounds=10)` 是預設的上限;伺服器若超過這個次數還繼續回傳 `InputRequiredResult`,`call_tool` 就會引發例外。如果某一輪只帶 `request_state` 而沒有 `input_requests`,`Client` 會先稍微睡一下(從 50 ms 開始加倍,最多 250 ms)再重試,這樣只是在說「還沒好」的伺服器就不會被忙碌輪詢。
|
||||
|
||||
### 自己驅動迴圈 {#driving-the-loop-yourself}
|
||||
|
||||
對單一處理程序的用戶端來說,自動迴圈就夠了。遇到以下情況則改成自己掌握迴圈:
|
||||
|
||||
* 用戶端是**分散式**的:把問題呈現給使用者的處理程序,和呼叫 `call_tool` 的不是同一個,所以重試是由另一個 worker 發出。`request_state` 就是你經由自己的儲存機制、帶著跨越那條邊界的可持久化權杖,而 `input_responses` 則是另一邊連同它一起送回來的東西。
|
||||
* 想要**檢視**每一輪:記錄或稽核每一筆 `input_requests`、拒絕某些種類的請求,或在各段之間套用自己的退避策略。
|
||||
* 想要的是**實際時間**上限而不是輪數上限:用 `anyio.fail_after(...)` 包住自己的迴圈,而不是依賴 `input_required_max_rounds`。
|
||||
|
||||
往下改用底層的工作階段,在那裡 `allow_input_required=True` 會直接把聯集型別交給你:
|
||||
|
||||
```python title="client.py" hl_lines="12 13 19"
|
||||
--8<-- "docs_src/mrtr/tutorial002.py"
|
||||
```
|
||||
|
||||
* `client.session.call_tool(..., allow_input_required=True)` 把回傳型別放寬成 `CallToolResult | InputRequiredResult`。`isinstance` 負責把它收窄回來。
|
||||
* `request_state` 現在在你手上。在各段之間把它寫下來,對話就能從全新的處理程序接續。
|
||||
* 對 `input_requests` 裡的每一筆,都要在 `input_responses` 的**同一個鍵**底下放一個 `InputResponse`。`fulfil` 是放你的 UI 的地方;這個範例把答案寫死了。
|
||||
* 每一段都是同一個工具名稱、同樣的 `arguments`。重試是把原本的呼叫再做一次,不是新的方法。
|
||||
|
||||
## 保護 `requestState` {#protecting-requeststate}
|
||||
|
||||
上面所有內容都把 `request_state` 當作一個回音,在線路上它也確實只是如此。但用戶端在各段之間持有它(跨處理程序把它寫下來,正是上一節所認可的做法),所以送回來的東西是**用戶端提供的輸入**:它可能被修改、已經過期,或根本是從另一次呼叫挪過來的。只要這個狀態會影響授權、資源存取或商業邏輯,規格就要求伺服器對它做完整性保護,並在驗證失敗時拒絕該輪。
|
||||
|
||||
`MCPServer` 預設就會保護它。每個伺服器都用處理程序啟動時產生的金鑰,密封送出的 `requestState` 並驗證每一個回音,解析器的狀態和手動組的狀態都一樣。不需要設定任何東西,寫明文、讀明文;線路上永遠只帶一個不透明的加密權杖。
|
||||
|
||||
預設金鑰與處理程序同生共死,這是部署到超過單一處理程序之前唯一必須知道的事:
|
||||
|
||||
```python
|
||||
from mcp.server.mcpserver import MCPServer, RequestStateSecurity
|
||||
|
||||
# Multi-instance or restart-surviving: one or more shared secret keys (>= 32 bytes each).
|
||||
mcp = MCPServer("fleet", request_state_security=RequestStateSecurity(keys=[key]))
|
||||
```
|
||||
|
||||
* **預設(不做設定)**適合單一處理程序:stdio,或剛好一個 HTTP worker。重試如果落到另一個 worker、負載平衡器後的另一個實例,或重新啟動後的同一台伺服器,密封它的金鑰是那個處理程序沒有的——用戶端會收到下方那則固定的拒絕訊息,必須從頭開始整個流程。
|
||||
* 只要重試可能到達**另一個實例**(多 worker 的 `uvicorn`、負載平衡的 HTTP)或必須撐過重新啟動,就必須設定 **`keys=[...]`**:每個實例都能驗證任何兄弟實例簽發的東西。機制相同,只是用你的祕密金鑰取代自動產生的。
|
||||
* 若要用自己的加密機制,例如 KMS 或既有的權杖服務,改傳 `RequestStateSecurity(codec=...)` 而不是 `keys`;下方的 **[自備加密](#bring-your-own-crypto)** 說明其契約。
|
||||
|
||||
### 密封裡帶了什麼 {#what-the-seal-carries}
|
||||
|
||||
不論是預設還是自行設定,線路上的 `requestState` 都是經過加密與認證的權杖。你的程式碼永遠看不到它:處理函式和解析器寫明文、讀明文(`ctx.request_state`);SDK 在送出時密封、收進來時驗證。除了完整性之外,每個權杖還綁定到:
|
||||
|
||||
* **一段時間窗口。** 每一輪都會用新的到期時間重新密封,所以 `RequestStateSecurity(ttl=...)`(預設 600 秒)限制的是每一輪的思考時間,而不是整個流程。
|
||||
* **經過驗證的主體。** 當請求帶有 SDK 驗證過的 OAuth 存取權杖時,狀態會綁定到權杖的用戶端、簽發者和 subject:為某個使用者簽發的狀態換到另一個使用者底下就會失敗,即使兩個使用者共用同一個 OAuth 用戶端。驗證器若不提供 subject,綁定就退化成只剩用戶端身分,而在以 URL 為基礎的用戶端 ID 之下,這個身分是該用戶端軟體的所有使用者共用的。當驗證在 SDK 之外終結(前置代理),或傳輸未經驗證時,沒有主體可綁,這項檢查就不起作用,除非 `RequestStateSecurity(bind_principal=...)` 從你自己的身分訊號提供一個。不論權杖驗證器提供哪些組成,都必須前後一致地提供:驗證器如果在某些請求附上 subject、在其他請求省略,主體就在流程中途改變,進行中的各輪會被拒絕。
|
||||
* **原始請求。** 方法、工具或提示詞名稱(或資源 URI),以及引數的摘要。把權杖拿去對另一個工具、不同的引數或不同的方法重放,都會失敗。
|
||||
* **問出的確切問題。** 每個解析器的答案都釘在用戶端當時看到的、已轉譯好的問題上,無論是答案剛送達的那一輪,還是之後重用已記錄的答案時。重新部署時若改了訊息措辭或改了 schema,伺服器會重新提問,而不是吃下一個過時的答案。同樣的釘法也會反過來作用:訊息要從工具的引數推導,不要從每次呼叫各異的資料推導。用時間戳記或即時匯率組出來的訊息每一輪轉譯出來都不一樣,於是每個已記錄的答案看起來都過時,伺服器會一直重新提問,直到用戶端的輪數上限結束這次呼叫。
|
||||
|
||||
這些全都是 SDK 的工作,不是你的;如果自備 codec,也不是 codec 的。
|
||||
|
||||
### 輪替金鑰 {#rotating-keys}
|
||||
|
||||
`keys[0]` 負責密封新的狀態;清單裡的每一把金鑰都能驗證。零停機輪替分三個階段,每一階段都要完全推出後才進入下一個:
|
||||
|
||||
```python
|
||||
RequestStateSecurity(keys=[OLD, NEW]) # 1: every instance learns to verify NEW; OLD still mints
|
||||
RequestStateSecurity(keys=[NEW, OLD]) # 2: NEW mints; in-flight OLD state keeps verifying
|
||||
RequestStateSecurity(keys=[NEW]) # 3: one ttl after phase 2 is fully out, retire OLD
|
||||
```
|
||||
|
||||
千萬不要先升格簽發用的金鑰:用某些實例還無法驗證的金鑰簽發,會在推出途中讓進行中的各輪掉落。
|
||||
|
||||
金鑰的作用範圍是單一服務。密封的信封也帶著伺服器名稱作為 audience 宣告,所以由恰好共用同一個祕密的另一個服務所簽發的權杖,照樣會被拒絕。這個宣告的辨識度取決於名稱,所以給了明確策略的伺服器必須有真正的名稱,或設定 `RequestStateSecurity(audience=...)`——沒有名稱的會在建構時引發例外。`audience=` 也適用於刻意設計的多服務拓撲,也就是某個服務必須接受另一個服務簽發的狀態的情形。(不做設定的預設情況不受此限:它的金鑰從不離開處理程序,audience 宣告沒什麼可補充的。)
|
||||
|
||||
### 自備加密 {#bring-your-own-crypto}
|
||||
|
||||
`RequestStateSecurity(codec=...)` 接受任何具有 `seal(bytes) -> str` 與 `unseal(str) -> bytes`、且對任何不是自己簽發的權杖會引發 `InvalidRequestState` 的物件。典型的形式是搭配 KMS 的信封加密:啟動時解包一次資料金鑰,之後每個權杖的加解密都留在本機:
|
||||
|
||||
```python title="server.py" hl_lines="12 26-27 34-35 38"
|
||||
--8<-- "docs_src/mrtr/tutorial005.py"
|
||||
```
|
||||
|
||||
TTL、主體綁定和請求綁定都**不是** codec 的工作:不論哪個 codec,SDK 都會在 `seal` 之前把它們蓋進酬載,在 `unseal` 之後重新驗證。codec 唯一的義務是完整性(被竄改就引發例外),以及最好還有機密性。
|
||||
|
||||
### 驗證失敗時 {#when-verification-fails}
|
||||
|
||||
每一個進來的失敗,不論是被竄改、過期、對不同的請求或主體重放,還是用這台伺服器不認得的金鑰密封,都得到同一個回答:
|
||||
|
||||
```json
|
||||
{"code": -32602, "message": "Invalid or expired requestState"}
|
||||
```
|
||||
|
||||
所有原因都是同一則固定訊息,所以線路上永遠看不出是哪項檢查失敗;真正的原因寫進伺服器記錄。`tools/call`、`prompts/get` 和 `resources/read` 上每一個進來的 `requestState` 都會檢查,連送往從不簽發狀態的處理函式的也包括在內。實務上最常見的拒絕不是攻擊者,而是預設的處理程序內金鑰碰上重新啟動之前或來自另一個實例的重試;用戶端重新開始流程,而在這件事要緊時,`keys=[...]` 就是解法。
|
||||
|
||||
### 手動組的狀態 {#hand-built-state}
|
||||
|
||||
你自己設定的 `request_state`(從工具、提示詞或資源範本函式回傳 `InputRequiredResult`)和解析器狀態由同一套機制密封與驗證,程式碼一行都不用改:寫明文、讀明文,上面每一項綁定都適用。
|
||||
|
||||
即使設定好了,SDK 唯一無法替你釘住的是問題的身分:它不知道你狀態裡的某個答案屬於**你的**哪一個問題。如果你以問題為鍵存放答案,就在狀態裡放進自己的問題識別碼,並在重試時檢查它。
|
||||
|
||||
低階 `Server` 是不附電池的那一層:和 `MCPServer` 不同,在你自己加上那道邊界之前什麼都不會密封,而在那之前你的 `request_state` 會照寫出來的樣子原封不動上線路。那一行的選用寫法請見 **[低階 Server](../advanced/low-level-server.md#the-other-handlers)**。
|
||||
|
||||
## 2026-07-28 的結果型別 {#a-2026-07-28-result}
|
||||
|
||||
`InputRequiredResult` 只存在於協定版本 **2026-07-28**。記憶體內的 `Client(server)` 會替你協商;走線路時,`mode="auto"` 會探知它。連線之後,`client.protocol_version` 會告訴你拿到的是什麼。
|
||||
|
||||
!!! warning
|
||||
2026 之前的工作階段沒有地方放 `InputRequiredResult`。在 `mode="legacy"` 的連線上從處理函式回傳一個,runner 無法把它序列化成協商好的版本;用戶端會拿回 `-32603`「Handler returned an invalid result」錯誤。同時服務兩個世代的伺服器,必須先檢查 `ctx.protocol_version` 再動用它。
|
||||
|
||||
!!! info
|
||||
**URL 模式的徵詢**在 2026 連線上正是搭著這套機制。`input_requests` 裡的那一筆是一個 params 為 `ElicitRequestURLParams` 的 `ElicitRequest`;使用者完成帶外流程後,用戶端重試這次呼叫。同一個迴圈,沒有新的 API。高階伺服器那一半請見 **[徵詢](elicitation.md)**。
|
||||
|
||||
## 重點回顧 {#recap}
|
||||
|
||||
* 在 2026-07-28,呼叫途中需要輸入的伺服器會**回傳** `InputRequiredResult`,從不向用戶端開請求。
|
||||
* `input_requests` 是它需要的東西。`request_state` 是只有伺服器會讀的不透明接續權杖。
|
||||
* `Client` 替你執行重試迴圈:註冊 `elicitation_callback`/`sampling_callback`/`list_roots_callback`,`call_tool` 就回傳普通的 `CallToolResult`。`input_required_max_rounds`(預設 10)替它設上限。
|
||||
* 要檢視或持久化各輪,用 `client.session.call_tool(..., allow_input_required=True)`,自己掌握 `while isinstance(result, InputRequiredResult)` 迴圈。
|
||||
* 在 `@mcp.tool()` 上,會詢問使用者的相依性替你產出這個結果(**[相依性](dependencies.md)**);**低階** `Server` 是手動的寫法。
|
||||
* 提示詞和資源也參與:`@mcp.prompt()` 或範本 `@mcp.resource()` 函式自己回傳 `InputRequiredResult`,重試時讀 `ctx.input_responses`。
|
||||
* `requestState` 回來時是用戶端提供的輸入,所以 `MCPServer` 預設就用處理程序內的金鑰密封它——解析器狀態和手動組的狀態都一樣;多實例部署要傳入 `RequestStateSecurity(keys=[...])`(或自訂 codec),好讓每個實例都能驗證兄弟實例簽發的東西。密封把每個權杖綁定到一段時間窗口、原始請求,以及經過驗證的主體——條件是請求帶有 SDK 驗證過的驗證資訊,或由 `bind_principal=` 提供你自己的身分訊號(**[保護 `requestState`](#protecting-requeststate)**)。
|
||||
|
||||
這就是取代伺服器主動發起的取樣、以及其餘推送式反向通道的機制;請見 **[已棄用的功能](../deprecated.md)**。
|
||||
112
i18n/zh-hant/pages/handlers/progress.md
Normal file
112
i18n/zh-hant/pages/handlers/progress.md
Normal file
|
|
@ -0,0 +1,112 @@
|
|||
---
|
||||
translation:
|
||||
sections: [5315262fe26b33e1, 9d8e98840f1b78f0, 0284b215e85366c4, 8534d8dbb4053a70, 2966fac6fe697007]
|
||||
tool: 1
|
||||
---
|
||||
# 進度 {#progress}
|
||||
|
||||
一個要跑三十秒、而這三十秒內毫無動靜的工具,看起來就像壞了。
|
||||
|
||||
**進度通知**就是用來解決這件事。工具回報自己做到哪裡;用戶端決定拿它畫什麼:進度條、轉圈圈的圖示,或一行記錄。
|
||||
|
||||
## 從工具回報 {#report-it-from-the-tool}
|
||||
|
||||
接收一個 **`Context`** 參數,然後呼叫 `report_progress`:
|
||||
|
||||
```python title="server.py" hl_lines="8 11"
|
||||
--8<-- "docs_src/progress/tutorial001.py"
|
||||
```
|
||||
|
||||
三個引數,意義由你決定:
|
||||
|
||||
* `progress`:做到哪裡了。規格要求它每次回報都要**遞增**;不要重複同一個值,也不要倒退。
|
||||
* `total`:總共有多少,如果知道的話。可省略。
|
||||
* `message`:描述**這一步**的一行人類可讀文字。可省略。
|
||||
|
||||
`ctx` 是因為型別提示而被注入的,模型永遠看不到它:`import_catalog` 的輸入 schema 只有一個屬性,`urls`。**[Context](context.md)** 那一頁專門講這個物件;進度只是它提供的功能之一。
|
||||
|
||||
## 從用戶端監聽 {#listen-for-it-from-the-client}
|
||||
|
||||
用戶端是**逐次呼叫**選擇加入的,做法是把 `progress_callback=` 傳給 `call_tool`:
|
||||
|
||||
```python title="client.py" hl_lines="7 16"
|
||||
import anyio
|
||||
from mcp import Client
|
||||
|
||||
from server import mcp
|
||||
|
||||
|
||||
async def show(progress: float, total: float | None, message: str | None) -> None:
|
||||
print(f"{message} ({progress}/{total})")
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
async with Client(mcp) as client:
|
||||
result = await client.call_tool(
|
||||
"import_catalog",
|
||||
{"urls": ["https://example.com/a.json", "https://example.com/b.json"]},
|
||||
progress_callback=show,
|
||||
)
|
||||
print(result.structured_content)
|
||||
|
||||
|
||||
anyio.run(main)
|
||||
```
|
||||
|
||||
回呼是一個 `async` 函式,接收的正是伺服器回報的內容:`progress`、`total`、`message`。
|
||||
|
||||
!!! info
|
||||
`Client(mcp)` 在記憶體內直接連上伺服器物件,和 **[測試](../get-started/testing.md)** 那一頁用的是同一個用戶端。不管 `Client` 用哪種傳輸方式,`progress_callback` 都是同一個參數;接下來看到的**時序**則是記憶體內連線的。它會就地執行回呼,所以每一筆回報都會在 `call_tool` 回傳之前送達。換成真正的傳輸方式,通知會和結果競速,一個慢的回呼在 `call_tool` 回傳之後可能還在執行。
|
||||
|
||||
### 試試看 {#try-it}
|
||||
|
||||
把 `client.py` 放在 `server.py` 旁邊,然後執行:
|
||||
|
||||
```console
|
||||
python client.py
|
||||
```
|
||||
|
||||
```text
|
||||
Imported https://example.com/a.json (1/2)
|
||||
Imported https://example.com/b.json (2/2)
|
||||
{'result': 'Imported 2 records.'}
|
||||
```
|
||||
|
||||
伺服器上的每一個 `await ctx.report_progress(...)` 都變成用戶端上對 `show` 的一次呼叫,依序發生,而且兩行都在 `call_tool` 回傳**之前**印出。進度不會打包進結果裡;它在工具還在執行時就持續串流過來。
|
||||
|
||||
!!! warning
|
||||
`progress_callback` 屬於那一次**呼叫**,不屬於 `Client`。沒有對應的建構子引數,因為不同的呼叫想要不同的回呼:這一次驅動下載進度條,下一次是一行記錄。
|
||||
|
||||
!!! check
|
||||
現在刪掉 `progress_callback=show`,再執行一次:
|
||||
|
||||
```text
|
||||
{'result': 'Imported 2 records.'}
|
||||
```
|
||||
|
||||
沒有錯誤、沒有警告,結果一樣。**呼叫端沒有要求進度時,`report_progress` 什麼都不做**,所以無條件回報就好,永遠不必去猜有沒有人在聽。
|
||||
|
||||
## 不知道總量的時候 {#when-you-dont-know-the-total}
|
||||
|
||||
`total` 是給知道分母時用的。常常並不知道:正在消化一個 feed、沿著游標往下走,或下載一個沒有長度標頭的東西。
|
||||
|
||||
那就省略它:
|
||||
|
||||
```python title="server.py" hl_lines="20"
|
||||
--8<-- "docs_src/progress/tutorial002.py"
|
||||
```
|
||||
|
||||
回呼會收到 `total=None`。用戶端還是可以顯示**有在動**(「3 imported so far...」),但沒辦法顯示百分比。不要為了讓進度條好看一點就捏造一個總量。
|
||||
|
||||
!!! tip
|
||||
`progress` 不一定要數某個特定的東西。位元組、資料列、頁數:挑使用者認得的單位,而且只承諾做得到的 `total`。
|
||||
|
||||
## 重點回顧 {#recap}
|
||||
|
||||
* 在任何接收 `Context` 的工具裡呼叫 `await ctx.report_progress(progress, total=None, message=None)`。
|
||||
* 用戶端把 `progress_callback=` 傳給 `call_tool`:逐次呼叫,永遠不是設在 `Client` 上。
|
||||
* 回呼的形式是 `async (progress, total, message) -> None`,在工具還在執行時就會觸發。
|
||||
* 呼叫時沒有回呼,`report_progress` 就什麼都不做。無條件回報就好。
|
||||
* 不知道 `total` 就省略;回呼會收到 `None`。
|
||||
|
||||
進度是執行中的工具給**使用者**看的。它為**你**(操作伺服器的人)記下的那些行,是另一條通道:**[記錄](logging.md)**。
|
||||
51
i18n/zh-hant/pages/handlers/sampling-and-roots.md
Normal file
51
i18n/zh-hant/pages/handlers/sampling-and-roots.md
Normal file
|
|
@ -0,0 +1,51 @@
|
|||
---
|
||||
translation:
|
||||
sections: [5c82b20cbd65ded0, 9dc22632be79a533, 1fb8f452e990c456, 42666ab914ff0cb1, c4e0cb3667fd5ff9]
|
||||
tool: 1
|
||||
---
|
||||
# 取樣與根目錄 {#sampling-and-roots}
|
||||
|
||||
處理函式還可以向連線的用戶端多要兩樣東西:由用戶端自己的模型產生的生成結果,也就是**取樣**(sampling);以及用戶端的工作區資料夾,也就是**根目錄**(roots)。
|
||||
|
||||
兩者在 SDK 支援的每個協定版本上都還能用。但在以它們為基礎做設計之前,先讀一下這段警告:
|
||||
|
||||
!!! warning "已於 2026-07-28 規格中棄用"
|
||||
取樣和根目錄自 `2026-07-28` 起已棄用([SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/2577))。它們仍然完全可用,並且會在規格中至少保留 12 個月,之後才可能被移除;但新的實作不應該建立在它們之上。建議的遷移方式:不要用取樣,改為直接整合 LLM 供應商的 API;不要用根目錄,改為透過工具參數、資源 URI 或伺服器設定來傳入目錄。整個 SDK 的清單在 **[已棄用的功能](../deprecated.md)**。
|
||||
|
||||
## 取樣:借用用戶端的模型 {#sampling-borrow-the-clients-model}
|
||||
|
||||
解析器回傳 `Sample(...)`,工具就會收到生成結果,走的是和 **[相依性](dependencies.md)** 中執行 `Elicit` 相同的相依性機制:
|
||||
|
||||
```python title="server.py" hl_lines="10-15 19"
|
||||
--8<-- "docs_src/sampling_and_roots/tutorial001.py"
|
||||
```
|
||||
|
||||
* `Sample(messages, max_tokens=...)` 對應 `sampling/createMessage` 的參數。注入的值是用戶端的 `CreateMessageResult`;如果傳入 `tools` 或 `tool_choice`,則會變成 `CreateMessageResultWithTools`。
|
||||
* 用戶端必須宣告了 `sampling` 能力(如果傳入 `tools` 或 `tool_choice`,則是 `sampling.tools`)。如果沒有,呼叫會以 `-32021` 協定錯誤失敗,而不是送出一個用戶端無法處理的請求。沒有反向通道(back-channel)的 2026 之前的工作階段(session)則會以它一貫的「沒有反向通道」錯誤失敗,因為根本沒有通道可送。
|
||||
* 在 `2026-07-28`,請求是在多輪往返(multi-round-trip)流程中傳遞的(**[多輪往返請求](multi-round-trip.md)**);在 `2025-11-25` 則是對用戶端發出的獨立請求。兩種情況下程式碼都一樣,但要注意多輪往返的規則:請求在各輪重試之間必須呈現得完全相同,所以只能用工具的引數和其他穩定的資料來建構它。
|
||||
* 不要動 `include_context`:`"none"` 以外的值本身也已棄用(SEP-2596),而且需要一個幾乎沒有用戶端會宣告的能力。
|
||||
|
||||
## 根目錄:這個該放哪裡? {#roots-where-should-this-go}
|
||||
|
||||
根目錄是用戶端表示伺服器可以操作的資料夾。它們是參考用的指引,不是存取控制機制。解析器回傳 `ListRoots()`:
|
||||
|
||||
```python title="server.py" hl_lines="10-11 15"
|
||||
--8<-- "docs_src/sampling_and_roots/tutorial002.py"
|
||||
```
|
||||
|
||||
* 注入的 `ListRootsResult` 帶有一個 `Root` 清單:每個包含一個 `file://` URI 和一個選填的顯示名稱。
|
||||
* 把關條件和取樣相同:沒有宣告 `roots` 能力時,呼叫會以 `-32021` 失敗,而不會送出請求。
|
||||
|
||||
在線路的另一端,用戶端用它已有的回呼來回應這兩種請求:`sampling_callback` 和 `list_roots_callback`,說明見 **[用戶端回呼](../client/callbacks.md)**。
|
||||
|
||||
## 在 2025 世代的連線上 {#on-2025-era-connections}
|
||||
|
||||
`ctx.session.create_message(...)` 和 `ctx.session.list_roots()` 仍然存在,供直接操作工作階段的程式碼使用。它們只在有反向通道的地方才能運作(2025 世代、非無狀態的連線),而且呼叫時會引發棄用警告。上面的解析器標記才是受支援的形式:它們會依協商出的版本挑選傳遞方式,也不會發出警告。
|
||||
|
||||
## 重點回顧 {#recap}
|
||||
|
||||
* 從解析器回傳 `Sample(...)` 或 `ListRoots()`;工具會像收到其他相依性一樣收到 `CreateMessageResult` 或 `ListRootsResult`。
|
||||
* 用戶端必須宣告對應的能力,否則呼叫會以 `-32021` 失敗,而不會送出請求。
|
||||
* 兩項功能在 `2026-07-28` 都已棄用:目前完全可用,但不適合新設計。優先選擇供應商 API 而非取樣,優先選擇明確的參數而非根目錄。
|
||||
|
||||
回報慢速工具的進度:**[進度](progress.md)**。
|
||||
152
i18n/zh-hant/pages/handlers/subscriptions.md
Normal file
152
i18n/zh-hant/pages/handlers/subscriptions.md
Normal file
|
|
@ -0,0 +1,152 @@
|
|||
---
|
||||
translation:
|
||||
sections: [60a9de8a0bdaa531, 317bbe7e4355cdcc, a61d660c8029e04a, 8f7e82fcb88df8a9, b165db51249ff8ed, 266f56fb798068a4, 7c0e57030b622139, df18d7c2417a9883]
|
||||
tool: 1
|
||||
---
|
||||
# 訂閱 {#subscriptions}
|
||||
|
||||
伺服器的目錄不是固定的。工具會在執行時出現,資源 URI 背後的內容也會改變。
|
||||
|
||||
**訂閱**是用戶端得知這些變化的方式。用戶端送出一個 `subscriptions/listen` 請求,而這個請求的回應**就是**串流:它會保持開啟,並傳送用戶端要求的變更通知。
|
||||
|
||||
## 從工具發布 {#publish-it-from-the-tool}
|
||||
|
||||
你這邊要做的只有一行:發布變更。
|
||||
|
||||
```python title="server.py" hl_lines="20 32"
|
||||
--8<-- "docs_src/subscriptions/tutorial001.py"
|
||||
```
|
||||
|
||||
* `await ctx.notify_resource_updated("board://sprint")` 會送達每一個訂閱了該 URI 的開啟串流,其他人都不會收到。
|
||||
* `await ctx.notify_tools_changed()` 會送達每一個要求工具清單變更的串流。收到它的用戶端會再次呼叫 `tools/list`,這時就看得到 `sprint_report`。
|
||||
* 同系列的還有 `notify_prompts_changed()` 和 `notify_resources_changed()`。
|
||||
* 沒有訂閱者,就沒有工作。對閒置的伺服器發布是空操作,所以永遠不必檢查有沒有人在聽,只要說明什麼變了。
|
||||
|
||||
`MCPServer` 會替你服務 `subscriptions/listen`。線路上的義務(第一個訊框是確認、逐串流過濾、每個訊框都帶訂閱 id)是 SDK 的工作。
|
||||
|
||||
!!! check
|
||||
在線路上,一個過濾條件指名 `board://sprint` 的串流,在 `complete_task` 執行之後看起來像這樣:
|
||||
|
||||
```json
|
||||
{"method": "notifications/subscriptions/acknowledged",
|
||||
"params": {"notifications": {"resourceSubscriptions": ["board://sprint"]}, "_meta": {"io.modelcontextprotocol/subscriptionId": "listen-1"}}}
|
||||
|
||||
{"method": "notifications/resources/updated",
|
||||
"params": {"uri": "board://sprint", "_meta": {"io.modelcontextprotocol/subscriptionId": "listen-1"}}}
|
||||
```
|
||||
|
||||
注意更新**沒有**帶什麼:看板本身。每個訊框都在 `_meta` 底下帶著 listen 請求的 JSON-RPC id,而那個 id 就是訂閱 id。它由用戶端產生:Python 的 `Client` 使用像 `"listen-1"` 這樣的字串;其他用戶端可能使用整數。
|
||||
|
||||
## 只給要求的內容 {#only-what-was-asked-for}
|
||||
|
||||
過濾條件是一份契約。一個要求了工具清單變更和一個資源 URI 的串流,只會收到這兩種,別的都不會。發布一個提示詞變更,那個串流會保持安靜。
|
||||
|
||||
`MCPServer` 以完全相同的字串比對資源 URI,所以指名 `board://sprint` 的串流完全不會收到 `board://sprint/tasks/1` 的任何動靜。規格允許伺服器回報已訂閱 URI 的子資源變更;`MCPServer` 從不這麼做,但用戶端的設計會預期這種情況。
|
||||
|
||||
串流**不是**的兩件事:
|
||||
|
||||
* **它不是重播記錄。** 斷掉的串流就沒了,沒人連線時發布的事件也不會排入佇列。用戶端會重新 listen 並重新擷取。
|
||||
* **它不是 2025 的路徑。** 呼叫了 `resources/subscribe` 的用戶端由 `ctx.session.send_resource_updated(uri)` 服務。`notify_*` 方法只會送達 `subscriptions/listen` 串流。
|
||||
|
||||
## 決定誰可以觀看 {#deciding-who-may-watch}
|
||||
|
||||
預設情況下,每一種要求的類型和 URI 都會被接受:任何呼叫端都可以觀看你發布的任何 URI。沒有任何東西會去問你的讀取處理函式,因為沒有人在讀取。一個會被 `files://{name}` 處理函式拒絕的呼叫端,仍然可以對 `files://payroll.csv` 開啟串流,得知它變了、什麼時候變的。它永遠不會得知內容,也無法探測有哪些東西存在,因為未知的 URI 一樣會被接受,只是永遠不會觸發。範圍很窄但確實存在,所以在從多租戶伺服器發布每位使用者各自的 URI 之前,先加上把關。
|
||||
|
||||
把關用的是中介軟體。它會在 SDK 確認之前看到 `subscriptions/listen` 請求,並在呼叫端要求任何他們無權讀取的東西時拒絕:
|
||||
|
||||
```python title="server.py" hl_lines="19-26 29"
|
||||
--8<-- "docs_src/subscriptions/tutorial006.py"
|
||||
```
|
||||
|
||||
* `ctx.params` 是原始請求,所以中介軟體自己把它驗證成 `SubscriptionsListenRequestParams`,再讀出用戶端要求的過濾條件。
|
||||
* 拒絕的方式是在 `call_next(ctx)` 之前引發 `MCPError`:用戶端會收到那個錯誤而沒有串流,連線則繼續。訊息要保持一致、不指名任何 URI,這樣拒絕就永遠不會證實哪些 URI 受到保護。
|
||||
* 一個 `can_access(user, uri)` 回答兩個問題。資源處理函式在 `resources/read` 時問它;中介軟體在 `subscriptions/listen` 時問它。把那張表換成資料庫或你的 RBAC 系統,兩邊依然同步。
|
||||
* 這個決定在串流的整個存續期間都有效。沒有逐事件的重新檢查,所以如果呼叫端的存取權可能在串流中途失效(權杖過期),就在失效時結束那個呼叫端的連線。
|
||||
|
||||
完整的中介軟體契約,包括它還包裝了什麼、以及為什麼標示為暫定,請見 **[中介軟體](../advanced/middleware.md)**。
|
||||
|
||||
## 用戶端那一端 {#the-client-end}
|
||||
|
||||
以下是串流另一端的用戶端,正在追蹤看板:
|
||||
|
||||
```python title="client.py" hl_lines="15"
|
||||
--8<-- "docs_src/subscriptions/tutorial003.py"
|
||||
```
|
||||
|
||||
進入 `client.listen(...)` 會送出請求並等待你的確認,所以區塊開始時串流已經接通,而每個有型別的事件都是重新擷取的訊號,從來不是酬載。整份契約一個畫面就講完了。用戶端那一端的其他一切都在它自己的頁面上:在主流程旁邊觀看、串流的結束,以及重新 listen。請見「用戶端」章節下的 **[訂閱](../client/subscriptions.md)**。
|
||||
|
||||
## 擴展到單一處理程序之外 {#scaling-past-one-process}
|
||||
|
||||
發布的內容透過 `SubscriptionBus` 從處理函式送到開啟中的串流。預設是記憶體內的:一個處理程序,所有串流都在裡面。在你於負載平衡器後面執行多個副本之前,這都是正確答案;因為到那時,用戶端的串流會固定在某一個副本上,而另一個副本上的發布必須送得到它。
|
||||
|
||||
那個接縫由你實作:在你的 pub/sub 後端上實作兩個方法。
|
||||
|
||||
```python
|
||||
from collections.abc import Callable
|
||||
|
||||
from redis.asyncio import Redis
|
||||
|
||||
from mcp.server.mcpserver import MCPServer
|
||||
from mcp.server.subscriptions import ServerEvent # SubscriptionBus is a Protocol: no base class
|
||||
|
||||
|
||||
class RedisSubscriptionBus:
|
||||
def __init__(self, redis: Redis) -> None:
|
||||
self._redis = redis
|
||||
self._listeners: dict[object, Callable[[ServerEvent], None]] = {}
|
||||
|
||||
async def publish(self, event: ServerEvent) -> None:
|
||||
await self._redis.publish("mcp-events", encode(event)) # to every replica
|
||||
|
||||
def subscribe(self, listener: Callable[[ServerEvent], None]) -> Callable[[], None]:
|
||||
token = object()
|
||||
self._listeners[token] = listener
|
||||
|
||||
def unsubscribe() -> None:
|
||||
self._listeners.pop(token, None)
|
||||
|
||||
return unsubscribe
|
||||
|
||||
|
||||
mcp = MCPServer("Sprint Board", subscriptions=RedisSubscriptionBus(redis))
|
||||
```
|
||||
|
||||
`encode` 是你的,每個副本上負責解碼送達的訊息並呼叫每個已註冊監聽器的讀取任務也是你的。監聽器是同步的,不可以引發例外,並且在伺服器的事件迴圈上執行。
|
||||
|
||||
匯流排承載的是有型別的 `ServerEvent` 值(四個小小的 dataclass),從來不是 JSON-RPC。加註、過濾和串流生命週期都留在 SDK 裡,所以匯流排的實作不可能破壞協定,只能在處理程序之間搬運事件。
|
||||
|
||||
要從請求之外發布,就自己建構匯流排,這樣你才握有參考。什麼都不傳時 `MCPServer` 會在內部建立一個,而且不會公開它。
|
||||
|
||||
```python
|
||||
from mcp.server.subscriptions import InMemorySubscriptionBus, ToolsListChanged
|
||||
|
||||
bus = InMemorySubscriptionBus()
|
||||
mcp = MCPServer("Sprint Board", subscriptions=bus)
|
||||
|
||||
|
||||
async def tools_reloaded() -> None:
|
||||
await bus.publish(ToolsListChanged()) # from a lifespan task, a webhook, anywhere
|
||||
```
|
||||
|
||||
## 低階組合方式 {#the-low-level-composition}
|
||||
|
||||
在低階的 `Server` 上沒有任何預先接好的東西,同樣的零件三行就能組起來:
|
||||
|
||||
```python title="server.py" hl_lines="8-9 47"
|
||||
--8<-- "docs_src/subscriptions/tutorial002.py"
|
||||
```
|
||||
|
||||
* 匯流排是你的,所以直接對它發布:`await bus.publish(ResourceUpdated(uri=...))`。把它放在處理函式搆得到的地方:這裡是模組範圍,較大的應用程式則放在生命週期裡。
|
||||
* `ListenHandler(bus)` 就是 `MCPServer` 註冊的同一個處理函式,而 `on_subscriptions_listen=` 是一個普通的處理函式插槽。想要不同的語意,就把你自己的 callable 放進那個插槽,規格上的義務就轉到你身上:先確認、每個訊框加註訂閱 id、過濾條件之外的一律不送。
|
||||
* `ListenHandler.close()` 會優雅地結束每一個開啟的串流。每一個都會收到 listen 請求的結果作為最後一個訊框,這是規格用來表示伺服器刻意結束訂閱的方式。它會在那些串流清空完畢之前回傳,所以在拆掉傳輸之前給它們一點時間。沒有它,串流會在用戶端斷線時結束。
|
||||
|
||||
## 重點回顧 {#recap}
|
||||
|
||||
* 用戶端用一個 `subscriptions/listen` 請求選擇加入,而回應就是串流。服務它的功能是內建的。
|
||||
* 用 `ctx.notify_*` 發布,SDK 負責加註、過濾和生命週期的工作。
|
||||
* 事件是訊號,不是酬載。兩端都重新擷取。
|
||||
* 用戶端那一端是 `async with client.listen(...)`:完整說明請見「用戶端」章節下的 **[訂閱](../client/subscriptions.md)**。
|
||||
* 在低階的 `Server` 上,同樣的零件自己組:一個匯流排、`ListenHandler(bus)`、`on_subscriptions_listen` 插槽。
|
||||
* 橫向擴展代表實作 `SubscriptionBus`(兩個方法),然後以 `MCPServer(subscriptions=...)` 傳入。
|
||||
|
||||
執行提供這一切的伺服器,不管是一個副本還是 20 個,請見 **[部署與擴展](../run/deploy.md)**。
|
||||
Loading…
Reference in a new issue