> ## 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 tool reference

> Every tool of the PapelShip theme MCP server, its arguments and what it returns.

All tools work on the one store you approved. A theme id of another store answers `not_found`. Write tools (`save_draft`, `propose_edit`) are listed only when the connection has the `themes:write` scope.

Results are JSON wrapped in an untrusted-data block. Failures are tool errors with a `code`: `invalid_input`, `not_found`, `forbidden`, `conflict`, `limit`, `busy`, `unsupported` or `internal`.

## Typical workflow

1. `get_reference` (topic `overview`, then for example `commerce` or `app_blocks` with the theme kind) to learn what the platform supports.
2. `list_themes` to find the copy, then `list_files`, `read_file` or `search`.
3. `save_draft` with `baseHash` from your read.
4. `validate` the file, and `scan` for an uploaded design.
5. `preview_link` and give the link to the user. The user publishes in the panel.

## Read tools

### get\_reference

The platform reference, generated from the same registry the editor and `validate` use. No store data.

| Argument | Type | |
| - | - | - |
| `topic` | string | `overview` (default), `kinds`, `app_blocks`, `commerce`, `sdk`, `liquid`, `platform_pages`, `limits` or `pitfalls` |
| `kind` | string | `liquid`, `design`, `code` or `twin`: only what applies to that theme kind. `list_themes` returns the kind. `twin` is an ejected built-in section |
| `name` | string | With `app_blocks`, one block (for example `buy_now`). With `sdk`, one member (for example `checkout` or `cart`) |

Returns compact JSON. For example, `{ "topic": "app_blocks", "name": "buy_now" }` returns its arguments with types, required flags and aliases, its behaviour, and its support per theme kind.

### Resources

The same reference is available as MCP resources (`resources/list`, `resources/read`, `resources/templates/list`):

| URI | Content |
| - | - |
| `papelship://reference/<topic>` | One topic: `overview`, `kinds`, `app-blocks`, `commerce`, `sdk`, `liquid`, `platform-pages`, `limits`, `pitfalls` |
| `papelship://reference/<topic>/<kind>` | The topic for one theme kind |

### list\_themes

The store's theme copies: Liquid themes, uploaded designs and theme code packages, with `id`, `name`, `kind`, `live` and `updatedAt`. No arguments.

### list\_files

| Argument | Type | |
| - | - | - |
| `themeId` | integer | Required |
| `prefix` | string | Only paths that start with it, for example `sections/` |

Returns `files` (`path`, `size`, `kind`, `contentHash`), at most 400, and `truncated`.

### read\_file

| Argument | Type | |
| - | - | - |
| `themeId` | integer | Required |
| `path` | string | Required, for example `sections/hero.liquid` |
| `startLine`, `endLine` | integer | Optional 1-based line window |

Returns `content`, `contentHash`, `startLine`, `endLine` and `totalLines`. Binary media returns `binary: true` without content.

### read\_files

| Argument | Type | |
| - | - | - |
| `themeId` | integer | Required |
| `paths` | string\[] | Required, 1–20 paths |

Returns `files` with `content` and `contentHash` each, at most 1 MB in total. Missing files have `missing: true`; files past the size budget have `skipped`.

### search

| Argument | Type | |
| - | - | - |
| `themeId` | integer | Required |
| `query` | string | Required, literal text, 1–200 characters |
| `caseSensitive` | boolean | Default `false` |
| `pathPrefix` | string | Limit to a folder |
| `maxResults` | integer | 1–100 |

Returns hits with `path`, `line`, `column` and a line preview.

### get\_schema

| Argument | Type | |
| - | - | - |
| `themeId` | integer | Required |
| `path` | string | A section file |

Without `path`: the theme settings from `config/settings_schema.json` and every section with its name, setting ids and block types. With `path`: the section's full `{% schema %}` JSON. Both answers include `sectionObject`: the section fields and the `section.css_id` note.

### validate

| Argument | Type | |
| - | - | - |
| `themeId` | integer | Required |
| `path` | string | One stored file |
| `proposalId` | string | A proposal from `propose_edit` or `save_draft` |

Without `path` and `proposalId`, validates the whole copy as publishing would. Returns `valid` and `problems` (`path`, `line`, `column`, `message`, `severity`). For theme code packages, a raw `section.id` in CSS or `id=`/`for=` is a `warning` (never makes `valid` false). Also flags unknown app blocks, unknown or wrongly typed arguments (with a did-you-mean suggestion), blocks the theme kind does not support, unknown `PapelShip` calls, and SDK calls that never run there (for example inline scripts on Liquid theme pages).

### scan

| Argument | Type | |
| - | - | - |
| `themeId` | integer | Required, an uploaded design |
| `proposalId` | string | Scan with a proposal applied |

Dry run of the design security scanner. Nothing is recorded. Liquid themes answer `unsupported`.

### preview\_link

| Argument | Type | |
| - | - | - |
| `themeId` | integer | Required |
| `page` | string | Page path, for example `/` or `/shop` |

Returns `url`, a link to the preview in the PapelShip panel. The user must be signed in. It shows the copy's saved (draft) files. Test clicks, toggles and links in this page; the visual editor canvas selects on click.

## Write tools

### save\_draft

Requires `themes:write`.

| Argument | Type | |
| - | - | - |
| `themeId` | integer | Required |
| `path` | string | Required |
| `content` | string | Full new content, up to 512 KB. Creates the file if it doesn't exist. |
| `edits` | `{ find, replace }[]` | 1–50 search and replace pairs. Each `find` must match exactly once. |
| `baseHash` | string | `contentHash` from your read. A file changed since then answers `conflict`. |
| `note` | string | Kept in the file history |

Pass exactly one of `content` or `edits`. Saves are validated like editor saves; an invalid file answers `invalid_input` with the first problem.

| `mode` | When | Effect |
| - | - | - |
| `copy` | The copy is not live | Saved, with a new version. `saved: true` |
| `code_package_draft` | A theme code package | Saved. Live pages keep the published version. `saved: true` |
| `live_copy_draft` | The live theme copy or the live design | Saved as a draft. The store keeps the published version until Publish. `saved: true` |

Every result includes `problems` from the editor diagnostics, for example the `section.css_id` warning in code packages.

### propose\_edit

Requires `themes:write`. Same arguments as `save_draft` plus a required one-line `summary`; `note` is not used. Never saves: the proposal waits for the owner to accept it in the code editor and expires after 24 hours. Use it when you want the owner to review every change.

## Protocol

* Transport: Streamable HTTP, JSON responses, no sessions. `GET` answers `405`.
* Protocol versions: `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`.
* Batches: up to 10 messages. Every message counts toward the rate limit.
* Authorization: OAuth 2.1 with PKCE, discovered from `https://app.papelship.com/.well-known/oauth-protected-resource/mcp`, or a Themes API key as a Bearer token.


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