docs: publish translated docs in twelve languages and the tool that maintains them (#3280)
This commit is contained in:
parent
14aa889992
commit
52ad0a8876
1 changed files with 89737 additions and 54 deletions
130
i18n/ru/pages/servers/completions.md
Normal file
130
i18n/ru/pages/servers/completions.md
Normal file
|
|
@ -0,0 +1,130 @@
|
|||
---
|
||||
translation:
|
||||
sections: [72f9c964769076dd, 9a2c14e10935b515, 235299eb78ab12d7, 8aee1e78c8237fb8, 9bd86acd4112138f, 55343cb7f250dc7b]
|
||||
tool: 1
|
||||
---
|
||||
# Автодополнение {#completions}
|
||||
|
||||
Клиент, который строит пользовательский интерфейс поверх вашего сервера, хочет дополнять значения аргументов прямо по мере ввода: названия языков, имена репозиториев, пути к файлам.
|
||||
|
||||
**Автодополнение** (completions) — это способ, которым сервер выдаёт такие подсказки.
|
||||
|
||||
## Что стоит дополнять {#something-worth-completing}
|
||||
|
||||
Автодополнение применяется ровно к двум вещам: к аргументам **промпта** и к параметрам **шаблона ресурса**. Поэтому начнём с сервера, в котором есть и то и другое:
|
||||
|
||||
```python title="server.py" hl_lines="6 12"
|
||||
--8<-- "docs_src/completions/tutorial001.py"
|
||||
```
|
||||
|
||||
Пока здесь нет ничего про автодополнение.
|
||||
|
||||
* `review_code` принимает `language`. Пользователь не должен угадывать, какие варианты написания вы принимаете.
|
||||
* `github_repo` принимает `owner` и `repo`. Два поля для свободного ввода — плохая форма.
|
||||
|
||||
## Обработчик автодополнения {#the-completion-handler}
|
||||
|
||||
Добавьте **одну** функцию с декоратором `@mcp.completion()`:
|
||||
|
||||
```python title="server.py" hl_lines="21-29"
|
||||
--8<-- "docs_src/completions/tutorial002.py"
|
||||
```
|
||||
|
||||
* Обработчик на сервер один. Все запросы автодополнения попадают сюда, а дальше вы ветвитесь в зависимости от того, что именно дополняется.
|
||||
* Он должен быть `async def`: SDK вызывает его через await.
|
||||
* Он получает три аргумента:
|
||||
* `ref`: *какой* промпт или шаблон ресурса — в виде `PromptReference` или `ResourceTemplateReference`. Различить их можно через `isinstance`.
|
||||
* `argument`: `argument.name` — дополняемый аргумент, `argument.value` — то, что пользователь уже успел набрать.
|
||||
* `context`: уже определённые аргументы. Пока не обращайте на него внимания.
|
||||
* Верните `Completion(values=[...])` или `None`, если предложить нечего.
|
||||
|
||||
!!! tip
|
||||
`argument.value` — это префикс, который набрал пользователь. SDK **не** фильтрует за вас: что
|
||||
положите в `values`, то интерфейс и покажет. `startswith` пишете вы сами.
|
||||
|
||||
### Попробуйте сами {#try-it}
|
||||
|
||||
Проверьте его с помощью `Client` в памяти со страницы **[Тестирование](../get-started/testing.md)**. Вызовите
|
||||
`client.complete()` с `ref=PromptReference(name="review_code")` и
|
||||
`argument={"name": "language", "value": "py"}`:
|
||||
|
||||
```python
|
||||
result.completion.values # ['python']
|
||||
```
|
||||
|
||||
* `ref` — тот же ссылочный тип, что получает обработчик.
|
||||
* `argument` — обычный словарь ровно с двумя ключами: `name` и `value`.
|
||||
|
||||
Отправьте пустое `value` — и вернётся весь список. `lang.startswith("")` истинно для любого языка:
|
||||
|
||||
```python
|
||||
result.completion.values # ['go', 'javascript', 'python', 'rust', 'typescript']
|
||||
```
|
||||
|
||||
Спросите про `code` (аргумент, который обработчик не знает) — он вернёт `None`, а SDK превратит его в пустой список:
|
||||
|
||||
```python
|
||||
result.completion.values # []
|
||||
```
|
||||
|
||||
`None` означает *«подсказок нет»* и никогда не ошибку. Интерфейс откатывается к обычному текстовому полю.
|
||||
|
||||
## Возможность, которую вы не объявляли {#a-capability-you-never-declared}
|
||||
|
||||
Регистрация обработчика и есть объявление. Подключите клиент и посмотрите:
|
||||
|
||||
```python
|
||||
client.server_capabilities.completions # CompletionsCapability()
|
||||
```
|
||||
|
||||
Вы нигде не указывали `completions`. SDK увидел обработчик и объявил возможность за вас. Так работает каждая *необязательная* возможность: обработчик — это и есть объявление. (Три примитива к необязательным не относятся: `MCPServer` объявляет их всегда, есть обработчики или нет.)
|
||||
|
||||
!!! check
|
||||
Вернитесь к первому `server.py` (тому, где обработчика нет) и всё равно спросите. Вызов завершится
|
||||
ошибкой JSON-RPC:
|
||||
|
||||
```text
|
||||
Method not found
|
||||
```
|
||||
|
||||
А `client.server_capabilities.completions` равно `None`. В этом и смысл возможности:
|
||||
корректный клиент проверяет её и никогда не отправляет запрос, на который вы не можете ответить.
|
||||
|
||||
## Зависимые аргументы {#dependent-arguments}
|
||||
|
||||
У `github://repos/{owner}/{repo}` два параметра, и полезные значения для `repo` зависят от того, какой `owner` выбрали первым.
|
||||
|
||||
Для этого и нужен `context`. Он несёт аргументы, которые пользователь **уже определил**:
|
||||
|
||||
```python title="server.py" hl_lines="8-11 34-38"
|
||||
--8<-- "docs_src/completions/tutorial003.py"
|
||||
```
|
||||
|
||||
* Новая ветка срабатывает для параметра `repo` шаблона.
|
||||
* `context.arguments` — это `dict[str, str] | None` со значениями, выбранными к этому моменту (здесь `owner`).
|
||||
* Нет `owner` — нет и осмысленных подсказок, поэтому обработчик возвращает `None`.
|
||||
|
||||
Клиент отправляет эти определённые значения через `context_arguments=`. На этот раз `ref` — это
|
||||
`ResourceTemplateReference(uri="github://repos/{owner}/{repo}")`. Запросите `repo` с
|
||||
пустым `value` и передайте `context_arguments={"owner": "modelcontextprotocol"}`:
|
||||
|
||||
```python
|
||||
result.completion.values # ['python-sdk', 'typescript-sdk', 'inspector']
|
||||
```
|
||||
|
||||
Уберите `context_arguments=` — и тот же вызов вернёт `[]`. Обработчик не может знать, какие репозитории предложить, пока не знает владельца.
|
||||
|
||||
!!! info
|
||||
`Completion` принимает также `total=` и `has_more=`. Задавайте их, когда `values` — лишь часть
|
||||
более длинного списка, чтобы интерфейс мог показать *«и ещё 200»*. Большинству обработчиков они не нужны.
|
||||
|
||||
## Итоги {#recap}
|
||||
|
||||
* Автодополнение — это подсказки для **аргументов промптов** и **параметров шаблонов ресурсов**. И ничего больше.
|
||||
* `@mcp.completion()` регистрирует единственный обработчик. Это `async def (ref, argument, context) -> Completion | None`.
|
||||
* Ветвитесь по `isinstance(ref, ...)` и по `argument.name`. Фильтруйте по `argument.value` сами.
|
||||
* `None` превращается в пустой список. Это никогда не ошибка.
|
||||
* В `context.arguments` лежат уже определённые значения; клиент передаёт их как `context_arguments=`.
|
||||
* Возможность `completions` появляется, как только вы регистрируете обработчик. Без него ответ на запрос — `Method not found`.
|
||||
|
||||
Подсказки помогают, пока пользователь ещё *заполняет* промпт или шаблон; чтобы задать ему вопрос *посреди* вызова инструмента, нужна **[элицитация](../handlers/elicitation.md)** (elicitation). Всё, что инструмент может вернуть помимо текста, — на странице **[Изображения, аудио и значки](media.md)**.
|
||||
Loading…
Reference in a new issue