docs: refresh translations, and translate pages in parallel (#3458)
This commit is contained in:
Max
GitHub
parent
08a3bc8eaf
commit
fd66270926
1 changed files with 4821 additions and 2277 deletions
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
translation:
|
||||
sections: [9cac816674181eb0, 0700f337babcd4dd, 2bde0dd58cdf00f5, 40b4916d82eaf1d4, 3d0832f39b0d7059, dfa4446556badef0, 5bd93be2ab2ecb9c]
|
||||
sections: [9cac816674181eb0, 7c157764133fea1f, 40b4916d82eaf1d4, 10d151f2cc75317f, 3d0832f39b0d7059, 92742ba36533633d, 0aeca6145e7bd302]
|
||||
tool: 1
|
||||
---
|
||||
# Клиентские транспорты {#client-transports}
|
||||
|
|
@ -11,30 +11,15 @@ translation:
|
|||
|
||||
*Серверная* сторона каждого из них (то, что делает `mcp.run()` и что вы развёртываете) описана на странице **[Запуск сервера](../run/index.md)**.
|
||||
|
||||
## В памяти {#in-memory}
|
||||
|
||||
Передайте сам объект сервера:
|
||||
|
||||
```python title="client.py" hl_lines="14"
|
||||
--8<-- "docs_src/client_transports/tutorial001.py"
|
||||
```
|
||||
|
||||
Ни подпроцесса, ни порта, ни байтов в передаваемых данных. Клиент и сервер — два объекта в одном процессе, и вызов всё равно проходит через настоящий протокольный уровень: `search_books` перечисляется, валидируется и вызывается ровно так же, как это было бы по HTTP.
|
||||
|
||||
Поэтому это сразу две вещи:
|
||||
|
||||
* **Тестовый стенд.** Каждый пример в этой документации проверяется именно так, а страница **[Тестирование](../get-started/testing.md)** строит вокруг этого весь подход.
|
||||
* **API для встраивания.** Приложению, которое создаёт сервер, не нужен сетевой переход, чтобы вызывать его инструменты.
|
||||
|
||||
## Streamable HTTP {#streamable-http}
|
||||
|
||||
Передайте строку с URL — и получите **Streamable HTTP**, транспорт, за которым вы развёртываете сервер:
|
||||
Передайте строку с URL — и получите **Streamable HTTP**, транспорт, за которым вы развёртываете сервер и с которого стоит начинать:
|
||||
|
||||
```python title="client.py" hl_lines="5"
|
||||
--8<-- "docs_src/client_transports/tutorial002.py"
|
||||
```
|
||||
|
||||
Это уже готовый клиент для продакшена. `Client` сам оборачивает URL в `streamable_http_client(...)` поверх `httpx2.AsyncClient`, настроенного так, как нужно MCP: `follow_redirects=True`, таймаут 30 секунд на connect/write/pool и таймаут чтения 300 секунд, потому что сервер может держать поток ответа открытым.
|
||||
Это уже готовый клиент для продакшена. `Client` сам оборачивает URL в `streamable_http_client(...)` поверх `httpx2.AsyncClient`, настроенного так, как нужно MCP: таймаут 30 секунд на connect/write/pool и таймаут чтения 300 секунд, потому что сервер может держать поток ответа открытым.
|
||||
|
||||
!!! check
|
||||
Созданный `Client` **не** подключён. Конструктор только выбирает транспорт;
|
||||
|
|
@ -50,7 +35,7 @@ translation:
|
|||
|
||||
Как только понадобится заголовок `Authorization`, cookie, прокси, mTLS или другой таймаут, создайте `httpx2.AsyncClient` сами и передайте его в `streamable_http_client`:
|
||||
|
||||
```python title="client.py" hl_lines="8-14"
|
||||
```python title="client.py" hl_lines="8-13"
|
||||
--8<-- "docs_src/client_transports/tutorial003.py"
|
||||
```
|
||||
|
||||
|
|
@ -80,9 +65,30 @@ translation:
|
|||
!!! info
|
||||
`httpx2` сохраняет привычный API `httpx`, так что, если вы знаете `httpx`, вы уже умеете делать здесь
|
||||
аутентификацию, прокси, хуки событий, повторные попытки и ограничения соединений. SDK ничего не добавляет сверху
|
||||
и ничего не убирает. Здесь же подключается OAuth:
|
||||
и ничего не убирает, кроме [обработки редиректов](#redirects). Здесь же подключается OAuth:
|
||||
`httpx2.AsyncClient(auth=OAuthClientProvider(...))`. Весь этот сценарий — на странице **[OAuth-клиенты](oauth-clients.md)**.
|
||||
|
||||
### Редиректы {#redirects}
|
||||
|
||||
Транспорт подключается к URL, который вы ему передали, и ни к какому другому источнику (origin).
|
||||
|
||||
* Редирект `307`/`308`, который остаётся на той же схеме, хосте и порту, выполняется; то же касается перехода `http://` → `https://` на том же хосте. Это покрывает обычный редирект с добавлением косой черты `/mcp` → `/mcp/`.
|
||||
* Редирект куда-либо ещё **не** выполняется. Вызов завершается ошибкой:
|
||||
|
||||
```text
|
||||
MCPError: Redirect to https://other.example.com/mcp not followed; use that URL as the endpoint if it is the intended server
|
||||
```
|
||||
|
||||
Если этот URL и есть нужный сервер, укажите его в конфигурации. Если нет — сервер или прокси перед ним настроен неправильно.
|
||||
|
||||
Это верно для любого `httpx2.AsyncClient`, который вы передаёте: его настройка `follow_redirects` для MCP-запросов не учитывается — ни в одну, ни в другую сторону. OAuth-провайдеры SDK применяют то же правило к своим собственным запросам.
|
||||
|
||||
!!! tip
|
||||
Сообщение `Redirect to http://… not followed: it would downgrade this HTTPS endpoint to plain HTTP` означает, что
|
||||
сервер стоит за прокси с терминацией TLS, о котором не знает, и выдаёт редиректы на `http://`.
|
||||
Это исправляется на сервере (**[Развёртывание и масштабирование](../run/deploy.md#behind-a-tls-terminating-proxy)**)
|
||||
либо использованием ровно того URL `https://…/`, который предлагает сообщение.
|
||||
|
||||
## stdio {#stdio}
|
||||
|
||||
Сервер **stdio** — это подпроцесс. Клиент запускает его, пишет JSON-RPC в его stdin и читает JSON-RPC из его stdout. Именно так десктопный хост запускает сервер на вашей машине: хост — это *и есть* этот код плюс UI, а страница **[Подключение к реальному хосту](../get-started/real-host.md)** показывает те же отношения со стороны хоста, в виде файла конфигурации.
|
||||
|
|
@ -105,6 +111,18 @@ stderr дочернего процесса идёт в ваш. Чтобы нап
|
|||
Сервер, которому нужен API-ключ, там его не найдёт. Передайте его явно через `env=`; эти
|
||||
переменные добавляются поверх разрешённого списка. Именно это делает `BOOKSHOP_API_KEY` выше.
|
||||
|
||||
## В памяти {#in-memory}
|
||||
|
||||
В тесте нечего развёртывать и нечего запускать. Передайте сам объект сервера:
|
||||
|
||||
```python hl_lines="14"
|
||||
--8<-- "docs_src/client_transports/tutorial001.py"
|
||||
```
|
||||
|
||||
Ни подпроцесса, ни порта, ни байтов в сети. Клиент и сервер — два объекта в одном процессе, и вызов всё равно проходит через настоящий протокольный уровень: `search_books` перечисляется, валидируется и вызывается ровно так же, как это было бы по HTTP. Страница **[Тестирование](../get-started/testing.md)** строит вокруг этого весь подход.
|
||||
|
||||
Та же форма служит и API для встраивания: приложение, которое само создаёт сервер, может вызывать его инструменты без обращения к сети.
|
||||
|
||||
## SSE {#sse}
|
||||
|
||||
`sse_client(url)` из `mcp.client.sse` — это HTTP-транспорт, который заменил Streamable HTTP. Оборачивайте его так же, `Client(sse_client("http://localhost:8000/sse"))`, чтобы общаться с сервером, который всё ещё на нём говорит, и не стройте на нём ничего нового.
|
||||
|
|
@ -113,15 +131,16 @@ stderr дочернего процесса идёт в ваш. Чтобы нап
|
|||
|
||||
Для `Client` всё перечисленное — одно и то же.
|
||||
|
||||
**Транспорт** — это любой асинхронный контекстный менеджер, который отдаёт пару потоков сообщений `(read, write)`: формально — протокол `Transport` из `mcp.client`. `Client` разрешает свой аргумент по типу: объект сервера подключается внутри процесса, `str` превращается в `streamable_http_client(url)`, `StdioServerParameters` — в `stdio_client(params)`, а всё остальное используется как транспорт напрямую. Благодаря последнему правилу `stdio_client(...)`, `streamable_http_client(...)` и `sse_client(...)` подходят в одно и то же место — и вы можете написать свой.
|
||||
**Транспорт** — это любой асинхронный контекстный менеджер, который отдаёт пару потоков сообщений `(read, write)`: формально — протокол `Transport` из `mcp.client`. `Client` разрешает свой аргумент по типу: `str` превращается в `streamable_http_client(url)`, `StdioServerParameters` — в `stdio_client(params)`, объект сервера подключается внутри процесса, а всё остальное открывается напрямую как транспорт. Благодаря последнему правилу `stdio_client(...)`, `streamable_http_client(...)` и `sse_client(...)` встают в одно и то же место — и поэтому же можно написать свой собственный.
|
||||
|
||||
## Итоги {#recap}
|
||||
|
||||
* `Client(mcp)` (объект сервера) подключается в памяти. Используйте для тестов и для встраивания.
|
||||
* `Client("http://.../mcp")` (URL) подключается по Streamable HTTP, транспорту для продакшена.
|
||||
* Заголовки, аутентификация, прокси и таймауты задаются на `httpx2.AsyncClient`, который передаётся в `streamable_http_client(url, http_client=...)`. Именованного аргумента `headers=` нет.
|
||||
* Редиректы выполняются только в пределах источника самого URL (`307`/`308` с добавлением косой черты) плюс `http`→`https` на том же хосте. Всё остальное завершается ошибкой `Redirect to … not followed`; укажите в конфигурации конечный URL.
|
||||
* stdio — это `Client(StdioServerParameters(...))`. Оборачивайте его в `stdio_client(...)` сами, только чтобы перенаправить stderr дочернего процесса.
|
||||
* Подпроцесс получает окружение из разрешённого списка, а не ваше; `env=` добавляет к нему.
|
||||
* `Client(mcp)` (объект сервера) подключается в памяти. Используйте его в тестах или чтобы встроить сервер в приложение, которое его создало.
|
||||
* Транспорт — это всё, с чем можно написать `async with x as (read, write)`. `Client` передаёт всё, что не объект сервера, не URL и не `StdioServerParameters`, прямо в этот протокол.
|
||||
* Создание `Client` выбирает транспорт. `async with` его открывает.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue