Перейти до основного вмісту
Усі інструменти працюють із тим єдиним магазином, який ви схвалили. На 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. Без даних магазину. Повертає компактний JSON. Наприклад, { "topic": "app_blocks", "name": "buy_now" } повертає його аргументи з типами, прапорцями обов’язковості та псевдонімами, його поведінку та підтримку для кожного типу теми.

Ресурси

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

list_themes

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

list_files

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

read_file

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

read_files

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

get_schema

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

validate

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

scan

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

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

save_draft

Потребує themes:write. Передайте рівно один із аргументів content або edits. Збереження перевіряються так само, як у редакторі; для некоректного файлу повертається invalid_input із першою проблемою. Кожен результат містить 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-токен.