Skip to main content
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. 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):

​
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

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

​
read_file

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

​
read_files

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. Returns hits with path, line, column and a line preview.

​
get_schema

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

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

Dry run of the design security scanner. Nothing is recorded. Liquid themes answer unsupported. 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. Pass exactly one of content or edits. Saves are validated like editor saves; an invalid file answers invalid_input with the first problem. 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.