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/uk/pages/servers/completions.md
Normal file
130
i18n/uk/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