Перейти к основному содержанию
Все инструменты работают с одним магазином, который вы одобрили. На 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 МБ. У отсутствующих файлов указано 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 равным false). Также отмечает неизвестные блоки приложений, неизвестные или неверно типизированные аргументы (с подсказкой вида «возможно, вы имели в виду»), блоки, которые не поддерживает данный вид темы, неизвестные вызовы 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-ключ типа «Темы» в качестве Bearer-токена.