docs: refresh translations for recent English changes (#3379)
This commit is contained in:
parent
d8b638304e
commit
c5d7d0b6d0
2 changed files with 3149 additions and 1047 deletions
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
translation:
|
||||
sections: [2c79b6338e09b7ac, 7edc43b3fae11314, 1086e77ce561cd7f, a3f71823df5efc31, 9fc7109f72201cae, 7bf25983df655b66, 6330e1f4c6029683, 2f1749c8c133fa1c, b3530fcf4d11fd56, ebc33704fbd74262, cd0e9c933350390e]
|
||||
sections: [2c79b6338e09b7ac, 7edc43b3fae11314, 1086e77ce561cd7f, a3f71823df5efc31, 9fc7109f72201cae, d50fe7faead8cf68, 7bf25983df655b66, 6330e1f4c6029683, 2f1749c8c133fa1c, 8db7116fc8ddd0ee, ebc33704fbd74262, cd0e9c933350390e]
|
||||
tool: 1
|
||||
---
|
||||
# 底层 Server {#the-low-level-server}
|
||||
|
|
@ -116,6 +116,17 @@ asyncio.run(main())
|
|||
|
||||
服务器从不比较这两个字段。本 SDK 的 `Client` 会:返回的 `structured_content` 不满足你声明的 `output_schema` 时,`call_tool` 会抛出一个 `RuntimeError`,开头是 `Invalid structured content returned by tool search_books`,后面引用 `jsonschema` 的失败信息。承诺一个模式很便宜;信守它是你的事。返回类型和模式的完整阶梯详见 **[结构化输出](../servers/structured-output.md)**。
|
||||
|
||||
## 方言是 JSON Schema 2020-12 {#the-dialect-is-json-schema-2020-12}
|
||||
|
||||
`input_schema` 和 `output_schema` 是 JSON Schema,而 [MCP 规范](https://modelcontextprotocol.io/specification/latest/basic#json-schema-usage) 固定了方言:没有 `$schema` 键的模式就是 **JSON Schema 2020-12**。`MCPServer` 生成的模式依赖这个默认值(Pydantic 写的是 2020-12 并省略该键),手写的 dict 也按同样的标准对待,所以完整的 2020-12 词汇表都可以用:
|
||||
|
||||
```python title="server.py" hl_lines="8 14-15"
|
||||
--8<-- "docs_src/lowlevel/tutorial007.py"
|
||||
```
|
||||
|
||||
* `input_schema` 的根必须是 `"type": "object"`。在它旁边,`oneOf`、`additionalProperties`、`anyOf`、`if`/`then`/`else`、`prefixItems`、带本地 `$ref` 的 `$defs`,以及其余 2020-12 关键字,都会一字不差地到达客户端。
|
||||
* 不需要 `$schema` 键。只有想选用更早的草案时才加:本 SDK 的 `Client` 会按工具的 `output_schema` 校验 `structured_content`,它根据 `$schema` 选择校验器,没有时就用 2020-12。
|
||||
|
||||
## `_meta`:给应用程序,不是给模型 {#\_meta-for-the-application-not-the-model}
|
||||
|
||||
`content` 是答案里模型读取的部分。`structured_content` 是同一个答案的类型化数据形式。`_meta` 是第三条通道:随结果一起传递、面向**客户端应用程序**的数据,根本不属于答案的一部分。
|
||||
|
|
@ -166,7 +177,7 @@ asyncio.run(main())
|
|||
--8<-- "docs_src/lowlevel/tutorial006.py"
|
||||
```
|
||||
|
||||
* 第一个参数是方法字符串。通知有一个对应的 `add_notification_handler`。
|
||||
* 第一个参数是方法字符串。通知有一个对应的 `add_notification_handler`。它的处理函数在 stdio 和握手时代的 HTTP 连接上触发;在 `2026-07-28` 的 Streamable HTTP 路径上,客户端发来的通知 POST 会得到 `202` 确认但不会分发,因为那个修订版没有定义通过 HTTP 的客户端到服务器通知。
|
||||
* `params_type` 是传入的 `params` 在处理函数运行**之前**校验所依据的模型,所以自定义方法**确实**得到了工具没有的校验。继承 `RequestParams`,这样 `_meta` 字段的解析方式和其他方法一样。
|
||||
* 处理函数返回 `BaseModel`、`dict` 或 `None`。SDK 把它序列化进 JSON-RPC 结果。
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
translation:
|
||||
sections: [6048b4f308edbb8c, 068bda0f21ee9c1b, c3e565b61acd75c5, c62422b159c6ed09, 47204fab253cc45c]
|
||||
sections: [6048b4f308edbb8c, 46056f318ef205e4, c3e565b61acd75c5, c62422b159c6ed09, 420968f514138f43]
|
||||
tool: 1
|
||||
---
|
||||
# 中间件 {#middleware}
|
||||
|
|
@ -42,7 +42,7 @@ tools/call took 0.1 ms
|
|||
这正是关键所在。中间件包裹**每一条**入站消息:
|
||||
|
||||
* 连接建立:`server/discover`,或者旧版会话上的 `initialize` 和 `notifications/initialized`。
|
||||
* 每一个请求和每一个通知。对于通知,`ctx.request_id is None`,`call_next(ctx)` 返回 `None`,而你返回的任何东西都会被丢弃。
|
||||
* 每一个到达服务器的请求和通知。对于通知,`ctx.request_id is None`,`call_next(ctx)` 返回 `None`,而你返回的任何东西都会被丢弃。(在 `2026-07-28` 的 Streamable HTTP 路径上,客户端的通知 POST 在传输层就以 `202` 确认,从不分发,所以也到不了中间件;该修订版本没有定义任何经由 HTTP 的客户端到服务器通知。)
|
||||
* 甚至包括服务器没有处理函数的方法:`call_next` 会抛出 `MCPError(-32601, "Method not found")`,**穿过**你的中间件送往客户端。
|
||||
|
||||
## 在中间件里能做什么 {#what-you-can-do-inside-one}
|
||||
|
|
@ -75,7 +75,7 @@ SDK 自带的中间件恰好只有一个,而且已经在你服务器的列表
|
|||
## 回顾 {#recap}
|
||||
|
||||
* 中间件是 `async (ctx, call_next) -> result`,以 `MCPServer(middleware=[...])` 传入(或追加到 `mcp.middleware`),在低层 `Server` 上则追加到 `server.middleware`。
|
||||
* 它包裹**每一条**入站消息(`server/discover`、`initialize`、请求、通知、未知方法),按从外到内的顺序执行。
|
||||
* 它包裹**每一条**到达服务器的入站消息(`server/discover`、`initialize`、请求、通知、未知方法),按从外到内的顺序执行。
|
||||
* 用 `ctx.request_id is None` 区分通知和请求。
|
||||
* 抛出异常而不调用 `call_next` 即可拒绝一条消息;连接不受影响。
|
||||
* SDK 自己的 OpenTelemetry 追踪也是一个中间件,已经在列表上了。见 **[OpenTelemetry](../run/opentelemetry.md)**。
|
||||
|
|
|
|||
Loading…
Reference in a new issue