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


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