docs: refresh translations for recent English changes (#3379)
This commit is contained in:
Max
GitHub
parent
d8b638304e
commit
c5d7d0b6d0
1 changed files with 3149 additions and 1047 deletions
|
|
@ -1,11 +1,11 @@
|
|||
---
|
||||
translation:
|
||||
sections: [20541a40dbdd5980, 01262a123ad9501d, 429db5b574a2ac08, 56b2d49da412cb28, 6a1717123fe4513c]
|
||||
sections: [490237e61c3a7a44, 01262a123ad9501d, 429db5b574a2ac08, e2d0d273fbd2d74b, 64ab0331e868f3d4, 6c8878ce2d1f6d56, 4068f23e371bf0b3, eaef75b8725bc931]
|
||||
tool: 1
|
||||
---
|
||||
# 已棄用的功能 {#deprecated-features}
|
||||
|
||||
2026-07-28 規格讓五樣東西退場。SDK 仍然實作了其中每一項，而每一項現在都帶有**棄用警告**。
|
||||
2026-07-28 規格讓五樣東西退場。SDK 仍然實作了其中每一項，而每一項現在都帶有**棄用警告**。另外有一個 SDK 輔助函式是因為自身的原因棄用，列在[最後](#deprecated-sdk-helpers)。
|
||||
|
||||
下表列出每一項已棄用的功能、它為什麼要退場，以及應該改用的替代做法。
|
||||
|
||||
|
|
@ -49,6 +49,55 @@ MCPDeprecationWarning: The logging capability is deprecated as of 2026-07-28 (SE
|
|||
|
||||
兩個訊號，依這個順序出現。`MCPDeprecationWarning` 在呼叫方法的那一刻就會發出，任何連線都一樣。錯誤則是 SDK 接著嘗試傳送時回傳來的東西。這兩者只有在用戶端註冊了對應回呼的 `mode="legacy"` 連線上，才能從頭到尾正常運作。
|
||||
|
||||
## 舊版工作階段上的 `ping` {#ping-on-a-legacy-session}
|
||||
|
||||
**ping** 是一個空的請求，任何一方都可以送出，用來確認對方還有回應。2026-07-28 規格移除了它（[SEP-2575](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575)）：現代用戶端送出的每個請求本身就已經證明伺服器還在，而現代伺服器也沒有通道可以送出 ping。兩個 SDK 方法在交握世代的工作階段上仍然有效。從用戶端：
|
||||
|
||||
```python
|
||||
async def main() -> None:
|
||||
async with Client("http://localhost:8000/mcp", mode="legacy") as client:
|
||||
await client.send_ping() # warns; returns an EmptyResult
|
||||
```
|
||||
|
||||
從伺服器端，在任何處理函式內：
|
||||
|
||||
```python
|
||||
@mcp.tool()
|
||||
async def check_client(ctx: Context) -> str:
|
||||
"""A tool that still pings the client mid-call."""
|
||||
await ctx.session.send_ping() # no warning; an EmptyResult while the client is connected
|
||||
return "client answered"
|
||||
```
|
||||
|
||||
* `client.send_ping()` 每次呼叫都會發出 `MCPDeprecationWarning`。在預設（`2026-07-28`）的連線上，伺服器則改為回應 `MCPError: Method not found`。
|
||||
* `ctx.session.send_ping()` 不帶警告。在現代連線上，它會和其他任何伺服器發起的請求一樣，引發沒有反向通道（back-channel）的錯誤。
|
||||
* 兩邊都不需要註冊任何東西來回應 ping。
|
||||
|
||||
## 根目錄變更通知 {#roots-change-notifications}
|
||||
|
||||
宣告了根目錄能力的 2025 世代用戶端，可以送出 `notifications/roots/list_changed` 告訴伺服器它的工作區資料夾變了；伺服器的回應是再次請求 `roots/list`。2026-07-28 規格把這個通知連同其餘推送式的根目錄流程一起移除。在用戶端，傳入 `list_roots_callback=`（**[用戶端回呼](client/callbacks.md)**）就是宣告 `"roots": {"listChanged": true}` 的那一步，而兌現這個承諾只需要一次呼叫：
|
||||
|
||||
```python
|
||||
async def open_folder(client: Client, uri: str, name: str) -> None:
|
||||
"""The user opened another folder: expose it through the roots callback, then tell the server."""
|
||||
workspace.append(Root(uri=FileUrl(uri), name=name))
|
||||
await client.send_roots_list_changed()
|
||||
```
|
||||
|
||||
在伺服器端，接收端的處理函式由低階 `Server` 接手：
|
||||
|
||||
```python
|
||||
async def roots_changed(ctx: ServerRequestContext, params: NotificationParams | None) -> None:
|
||||
"""The client's roots changed: ask for the new list."""
|
||||
roots = (await ctx.session.list_roots()).roots
|
||||
|
||||
|
||||
server = Server("Bookshop", on_roots_list_changed=roots_changed)
|
||||
```
|
||||
|
||||
* `workspace` 是 `list_roots_callback` 回傳的那個清單。`client.send_roots_list_changed()` 會發出警告，而且需要 `mode="legacy"` 的用戶端：在現代連線上，這個通知會被默默丟棄。之後要讓工作階段保持開啟，因為伺服器後續的 `roots/list` 會從這條工作階段送來。
|
||||
* `MCPServer` 沒有對應這個通知的掛鉤。在低階 `Server` 上，`on_roots_list_changed=` 用來註冊處理函式（同樣已棄用，建構時就會發出警告）。這個通知不帶任何酬載，所以處理函式要呼叫 `ctx.session.list_roots()` 取得新清單。
|
||||
|
||||
## 讓警告靜音 {#silencing-the-warning}
|
||||
|
||||
新程式碼裡，不要這麼做。
|
||||
|
|
@ -66,21 +115,30 @@ warnings.filterwarnings("ignore", category=MCPDeprecationWarning)
|
|||
整個 API 就這樣。沒有逐方法的開關，你也不會想要：只用一個類別的意義在於，一行就能關掉它，一行就能把它叫回來。
|
||||
|
||||
!!! check
|
||||
把過濾器反過來用，就免費得到一個回歸測試。在 pytest 設定的 `filterwarnings` 裡加上 `"error::mcp.MCPDeprecationWarning"`，已棄用的呼叫就會**引發例外**而不是發出警告。一個名為 `old_log`、還在呼叫 `ctx.info()` 的工具會不再通過，開始回報：
|
||||
把過濾器反過來用，就免費得到一個回歸測試。在 pytest 設定的 `filterwarnings` 裡加上 `"error::mcp.MCPDeprecationWarning"`，已棄用的呼叫就會**引發例外**而不是發出警告。一個名為 `old_log`、還在呼叫 `ctx.info()` 的工具會不再通過：呼叫回來時是 `is_error=True`，帶著 `Error executing tool old_log`，而擷取到的伺服器記錄會點名元凶：
|
||||
|
||||
```text
|
||||
Error executing tool old_log: The logging capability is deprecated as of 2026-07-28 (SEP-2577).
|
||||
mcp.shared.exceptions.MCPDeprecationWarning: The logging capability is deprecated as of 2026-07-28 (SEP-2577).
|
||||
```
|
||||
|
||||
一行 pytest 設定，已棄用的呼叫就再也沒辦法在不讓測試失敗的情況下溜回程式碼庫。
|
||||
|
||||
## 已棄用的 SDK 輔助函式 {#deprecated-sdk-helpers}
|
||||
|
||||
這些不是規格變更，只是有了更好替代做法的 SDK 內部實作。它們用同樣的 `MCPDeprecationWarning` 發出警告，並會在 3.0 移除。
|
||||
|
||||
| 已棄用項目 | 替代做法 |
|
||||
|---|---|
|
||||
| `FuncMetadata.call_fn_with_arg_validation()` | 先 `FuncMetadata.validate_arguments()`，再 `FuncMetadata.call_fn()`。只有直接操作 `FuncMetadata` 的程式碼（例如自訂的 `Tool` 子類別）才會呼叫過它。 |
|
||||
|
||||
## 重點回顧 {#recap}
|
||||
|
||||
* 2026-07-28 規格棄用了**根目錄**、伺服器發起的**取樣**和協定**記錄**（全部來自 [SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577)），把**進度**限制為只能從伺服器到用戶端，並移除了 **`ping`**。
|
||||
* 替代做法那一欄指引你接下來往哪走：取樣和根目錄看 **[多輪往返請求](handlers/multi-round-trip.md)**，記錄看 **[記錄](handlers/logging.md)**，進度看 **[進度](handlers/progress.md)**。`ping` 什麼都不需要。
|
||||
* 棄用只是勸告性質：線路沒有變更，一切在 2026 之前的工作階段上都能繼續運作，而且你會看到明顯的 `MCPDeprecationWarning`（它是 `UserWarning`，所以預設就會顯示）。
|
||||
* 取樣和根目錄還額外需要一條反向通道（back-channel），而 2026-07-28 的工作階段沒有。在現代連線上，它們會先警告，再引發例外。
|
||||
* 取樣和根目錄還額外需要一條反向通道，而 2026-07-28 的工作階段沒有。在現代連線上，它們會先警告，再引發例外。
|
||||
* `warnings.filterwarnings("ignore", category=MCPDeprecationWarning)` 會讓整個類別靜音；pytest 裡的 `"error::mcp.MCPDeprecationWarning"` 則把它變成測試失敗。
|
||||
* 有一個 SDK 輔助函式 `FuncMetadata.call_fn_with_arg_validation()` 另外單獨棄用，預計在 3.0 移除。
|
||||
* 新程式碼不應該建立在這些東西之上。
|
||||
|
||||
這份說明文件的其他每一頁教的都是目前的 API。
|
||||
|
|
|
|||
Loading…
Reference in a new issue