docs: publish translated docs in twelve languages and the tool that maintains them (#3280)

i18n/uk/pages/advanced/pagination.md

@@ -0,0 +1,85 @@
+---
+translation:
+  sections: [a9aba7a026c7bd85, ed32bda7ba9ae33a, 7e64cc5646abb91f, 22a0129ee78b3c63, d875373c06d8d2f9]
+  tool: 1
+---
+# Пагінація {#pagination}
+
+Більшості серверів вона не знадобиться ніколи.
+
+`MCPServer` відповідає на кожен запит `list_*` усім, що має, однією сторінкою з `next_cursor=None`. Для кількох десятків інструментів, ресурсів чи промптів це правильна відповідь, і налаштовувати нічого не потрібно.
+
+Пагінація — для сервера, у якого список ресурсів насправді є базою даних: тисячі рядків, які він відмовляється серіалізувати в одну відповідь. Відповідь протоколу — **курсор**: сервер повертає сторінку плюс непрозорий токен, а клієнт надсилає цей токен назад, щоб отримати наступну сторінку.
+
+У `@mcp.resource()` немає жодного гачка для цього. Щоб розбивати на сторінки, обробник списку пишуть власноруч, на **[низькорівневому Server](low-level-server.md)**.
+
+## Сервер зі сторінками {#a-server-that-pages}
+
+```python title="server.py" hl_lines="12 15-16"
+--8<-- "docs_src/pagination/tutorial001.py"
+```
+
+* На низькорівневому `Server` обробники — це аргументи конструктора, а не декоратори. `on_list_resources` відповідає на кожен запит `resources/list`; оце й усе під'єднання.
+* Кожен обробник зі сторінками має тип `params: PaginatedRequestParams | None`, і приклад приймає обидва варіанти. Утім, через з'єднання SDK ніколи не передає `None` (запит без члена `params` доходить до обробника як модель із типовими значеннями), тож важливий сигнал — `params.cursor is None`: **починайте з початку**.
+* Ви вирішуєте, чим курсор *є*. Тут це зсув, записаний як рядок. Мітка часу, первинний ключ, base64-блоб — будь-що, що можна видати на виході й упізнати на вході.
+* `next_cursor=None` — спосіб сказати «це була остання сторінка». Немає ні лічильника, ні загальної кількості, ні `has_more`. `None` — це весь сигнал.
+
+!!! tip
+    `PAGE_SIZE` у 10 робить приклад читабельним. Свій розмір обирайте для кожної кінцевої точки окремо: список
+    однорядкових ресурсів може дозволити собі сторінку на 500; список важких шаблонів промптів — ні.
+    Клієнт на це не впливає, і так задумано.
+
+### Спробуйте самі {#try-it}
+
+`Client(server)` під'єднується до низькорівневого `Server` у пам'яті так само, як і до `MCPServer`.
+
+Викличте `list_resources()` без аргументів. Повертається десять ресурсів, від `book-1` до `book-10`, а `next_cursor` — рядок `"10"`.
+
+Передайте його назад через `list_resources(cursor="10")` — і перший ресурс уже `book-11`, а новий `next_cursor` — `"20"`.
+
+Десята сторінка приходить із `next_cursor`, що дорівнює `None`. Готово.
+
+## Цикл на клієнті {#the-client-loop}
+
+Кожен метод `list_*` класу `Client` (`list_tools`, `list_resources`, `list_resource_templates`, `list_prompts`) приймає іменований параметр `cursor=`. Вичерпати список зі сторінками — це один `while True`:
+
+```python title="client.py" hl_lines="26-32"
+--8<-- "docs_src/pagination/tutorial002.py"
+```
+
+* `cursor` починається з `None`, тому перший запит курсора не несе.
+* Розширюйте список **до** того, як дивитися на `next_cursor`: на останній сторінці теж є ресурси.
+* `next_cursor is None` — це вихід. Усе інше йде прямо назад у `cursor=`, без змін.
+
+Запустіть його `main()` — і він надрукує `100 resources`: десять сторінок по десять, зшитих циклом, який так і не дізнався, що сторінок було десять.
+
+Це той самий цикл, який **[Клієнт](../client/index.md)** показує для кожного дієслова `list_*`, і проти сервера без сторінок він нічого не коштує: `next_cursor` дорівнює `None` вже в першій відповіді, і цикл виконується один раз.
+
+## Три правила {#the-three-rules}
+
+**Курсори непрозорі.** Клієнт ніколи не повинен розбирати, будувати чи вгадувати курсор. Єдине законне джерело курсора — `next_cursor` попередньої сторінки, дослівно.
+
+**Розмір сторінки обирає сервер.** У протоколі немає `limit=`. Якщо потрібен інший розмір сторінки, змінюють сервер.
+
+**Клієнт, що ігнорує пагінацію, усе одно працює.** Він викликає `list_resources()` один раз, отримує перші десять і навіть не помічає `next_cursor`, який викинув. Нічого не ламається; він просто бачить менше.
+
+!!! check
+    Непрозорий означає непрозорий. Вигадайте курсор (`list_resources(cursor="page-2")`) — і
+    протокол нічим не зможе допомогти. Цей сервер пробує `int("page-2")`, обробник викидає виняток,
+    а до клієнта повертається:
+
+    ```text
+    MCPError(-32603, 'Internal server error', None)
+    ```
+
+    Курсор, отриманий не від сервера, — це помилка, а не запит на нову можливість.
+
+## Підсумки {#recap}
+
+* `MCPServer` повертає все однією сторінкою. Пагінацію вмикають свідомо, і роблять це на низькорівневому `Server`.
+* `on_list_resources` (а також `on_list_tools`, `on_list_prompts`, `on_list_resource_templates`) отримує `PaginatedRequestParams | None`; для першої сторінки `params.cursor` дорівнює `None`.
+* Повертається сторінка плюс `next_cursor`: будь-який рядок, який ви згодом упізнаєте, або `None`, коли більше нічого не лишилося.
+* Цикл на клієнті: передати `cursor=`, накопичити, повторювати, доки `next_cursor is None`.
+* Курсори непрозорі, розмір сторінки належить серверу, а клієнт без пагінації все одно отримує першу сторінку.
+
+Решта написаного власноруч API `Server` (`on_call_tool`, словники `input_schema`, `_meta`) — на сторінці **[Низькорівневий Server](low-level-server.md)**.