not_found. Инструменты записи (save_draft, propose_edit) доступны, только если у подключения есть область доступа themes:write.
Результаты возвращаются в формате JSON внутри блока недоверенных данных. Сбои возвращаются как ошибки инструмента с code: invalid_input, not_found, forbidden, conflict, limit, busy, unsupported или internal.
Типичный сценарий
get_reference(темаoverview, затем, например,commerceилиapp_blocksс указанием вида темы), чтобы узнать, что поддерживает платформа.list_themes, чтобы найти копию, затемlist_files,read_fileилиsearch.save_draftсbaseHashиз прочитанных данных.validateдля файла иscanдля загруженного дизайна.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.
search
Возвращает совпадения с
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.
preview_link
Возвращает
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-токена.