> ## Documentation Index
> Fetch the complete documentation index at: https://developers.papelship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Довідник інструментів MCP

> Усі інструменти MCP-сервера тем PapelShip, їхні аргументи та що вони повертають.

Усі інструменти працюють із тим єдиним магазином, який ви схвалили. На ID теми іншого магазину повертається `not_found`. Інструменти запису (`save_draft`, `propose_edit`) відображаються лише тоді, коли підключення має область доступу `themes:write`.

Результати повертаються у вигляді JSON, обгорнутого в блок ненадійних даних. Збої є помилками інструментів із `code`: `invalid_input`, `not_found`, `forbidden`, `conflict`, `limit`, `busy`, `unsupported` або `internal`.

## Типовий робочий процес

1. `get_reference` (тема `overview`, потім, наприклад, `commerce` або `app_blocks` із типом теми), щоб дізнатися, що підтримує платформа.
2. `list_themes`, щоб знайти копію, потім `list_files`, `read_file` або `search`.
3. `save_draft` із `baseHash` від вашого читання.
4. `validate` для файлу та `scan` для завантаженого дизайну.
5. `preview_link`, і передайте посилання користувачеві. Користувач публікує зміни в панелі.

## Інструменти читання

### get\_reference

Довідник платформи, згенерований із того самого реєстру, який використовують редактор і `validate`. Без даних магазину.

| Аргумент | Тип | |
| - | - | - |
| `topic` | string | `overview` (за замовчуванням), `kinds`, `app_blocks`, `commerce`, `sdk`, `liquid`, `platform_pages`, `limits` або `pitfalls` |
| `kind` | string | `liquid`, `design`, `code` або `twin`: лише те, що стосується цього типу теми. `list_themes` повертає тип. `twin` означає виокремлену вбудовану секцію |
| `name` | string | Разом із `app_blocks`: один блок (наприклад, `buy_now`). Разом із `sdk`: один член (наприклад, `checkout` або `cart`) |

Повертає компактний JSON. Наприклад, `{ "topic": "app_blocks", "name": "buy_now" }` повертає його аргументи з типами, прапорцями обов'язковості та псевдонімами, його поведінку та підтримку для кожного типу теми.

### Ресурси

Той самий довідник доступний як MCP-ресурси (`resources/list`, `resources/read`, `resources/templates/list`):

| URI | Вміст |
| - | - |
| `papelship://reference/<topic>` | Одна тема: `overview`, `kinds`, `app-blocks`, `commerce`, `sdk`, `liquid`, `platform-pages`, `limits`, `pitfalls` |
| `papelship://reference/<topic>/<kind>` | Тема для одного типу теми |

### list\_themes

Копії тем магазину: теми Liquid, завантажені дизайни та пакети коду тем, із `id`, `name`, `kind`, `live` і `updatedAt`. Без аргументів.

### list\_files

| Аргумент | Тип | |
| - | - | - |
| `themeId` | integer | Обов'язковий |
| `prefix` | string | Лише шляхи, що починаються з нього, наприклад `sections/` |

Повертає `files` (`path`, `size`, `kind`, `contentHash`), не більше 400, і `truncated`.

### read\_file

| Аргумент | Тип | |
| - | - | - |
| `themeId` | integer | Обов'язковий |
| `path` | string | Обов'язковий, наприклад `sections/hero.liquid` |
| `startLine`, `endLine` | integer | Необов'язковий діапазон рядків із нумерацією з 1 |

Повертає `content`, `contentHash`, `startLine`, `endLine` і `totalLines`. Для бінарних медіафайлів повертається `binary: true` без вмісту.

### read\_files

| Аргумент | Тип | |
| - | - | - |
| `themeId` | integer | Обов'язковий |
| `paths` | string\[] | Обов'язковий, від 1 до 20 шляхів |

Повертає `files`, кожен із `content` і `contentHash`, загалом не більше 1 MB. Відсутні файли мають `missing: true`; файли, що виходять за межі ліміту розміру, мають `skipped`.

### search

| Аргумент | Тип | |
| - | - | - |
| `themeId` | integer | Обов'язковий |
| `query` | string | Обов'язковий, точний текст, від 1 до 200 символів |
| `caseSensitive` | boolean | За замовчуванням `false` |
| `pathPrefix` | string | Обмежити папкою |
| `maxResults` | integer | Від 1 до 100 |

Повертає збіги з `path`, `line`, `column` і попереднім переглядом рядка.

### get\_schema

| Аргумент | Тип | |
| - | - | - |
| `themeId` | integer | Обов'язковий |
| `path` | string | Файл секції |

Без `path`: налаштування теми з `config/settings_schema.json` і всі секції з їхніми назвами, ID налаштувань і типами блоків. З `path`: повний JSON `{% schema %}` секції. Обидві відповіді містять `sectionObject`: поля секції та примітку про `section.css_id`.

### validate

| Аргумент | Тип | |
| - | - | - |
| `themeId` | integer | Обов'язковий |
| `path` | string | Один збережений файл |
| `proposalId` | string | Пропозиція від `propose_edit` або `save_draft` |

Без `path` і `proposalId` перевіряє всю копію так, як це робить публікація. Повертає `valid` і `problems` (`path`, `line`, `column`, `message`, `severity`). Для пакетів коду тем необроблений `section.id` у CSS або `id=`/`for=` є `warning` (ніколи не робить `valid` хибним). Також позначає невідомі app blocks, невідомі або неправильно типізовані аргументи (з підказкою «можливо, ви мали на увазі»), блоки, які тип теми не підтримує, невідомі виклики `PapelShip` і виклики SDK, які там ніколи не виконуються (наприклад, вбудовані скрипти на сторінках тем Liquid).

### scan

| Аргумент | Тип | |
| - | - | - |
| `themeId` | integer | Обов'язковий, завантажений дизайн |
| `proposalId` | string | Сканувати з застосованою пропозицією |

Пробний запуск сканера безпеки дизайну. Нічого не записується. Для тем Liquid повертається `unsupported`.

### preview\_link

| Аргумент | Тип | |
| - | - | - |
| `themeId` | integer | Обов'язковий |
| `page` | string | Шлях сторінки, наприклад `/` або `/shop` |

Повертає `url`, посилання на попередній перегляд у панелі PapelShip. Користувач має бути авторизований. Показує збережені (чернеткові) файли копії. Тестуйте натискання, перемикачі та посилання на цій сторінці; полотно візуального редактора виділяє елементи під час натискання.

## Інструменти запису

### save\_draft

Потребує `themes:write`.

| Аргумент | Тип | |
| - | - | - |
| `themeId` | integer | Обов'язковий |
| `path` | string | Обов'язковий |
| `content` | string | Повний новий вміст, до 512 KB. Створює файл, якщо його не існує. |
| `edits` | `{ find, replace }[]` | Від 1 до 50 пар пошуку та заміни. Кожен `find` має збігатися рівно один раз. |
| `baseHash` | string | `contentHash` від вашого читання. Якщо файл відтоді змінився, повертається `conflict`. |
| `note` | string | Зберігається в історії файлу |

Передайте рівно один із аргументів `content` або `edits`. Збереження перевіряються так само, як у редакторі; для некоректного файлу повертається `invalid_input` із першою проблемою.

| `mode` | Коли | Результат |
| - | - | - |
| `copy` | Копія не є активною | Збережено, із новою версією. `saved: true` |
| `code_package_draft` | Пакет коду теми | Збережено. Активні сторінки показують опубліковану версію. `saved: true` |
| `live_copy_draft` | Активна копія теми або активний дизайн | Збережено як чернетку. Магазин залишається на опублікованій версії до натискання Publish. `saved: true` |

Кожен результат містить `problems` із діагностики редактора, наприклад попередження про `section.css_id` у пакетах коду.

### propose\_edit

Потребує `themes:write`. Ті самі аргументи, що й у `save_draft`, плюс обов'язковий однорядковий `summary`; `note` не використовується. Ніколи не зберігає: пропозиція чекає, поки власник прийме її в редакторі коду, і спливає через 24 години. Використовуйте його, коли хочете, щоб власник перевіряв кожну зміну.

## Протокол

* Транспорт: Streamable HTTP, JSON-відповіді, без сесій. `GET` повертає `405`.
* Версії протоколу: `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`.
* Пакети: до 10 повідомлень. Кожне повідомлення враховується в ліміт запитів.
* Авторизація: OAuth 2.1 з PKCE, виявлення через `https://app.papelship.com/.well-known/oauth-protected-resource/mcp`, або API-ключ Themes як Bearer-токен.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.