Passer au contenu principal
Tous les outils agissent sur l’unique boutique que vous avez approuvée. Un identifiant de thème d’une autre boutique renvoie not_found. Les outils d’écriture (save_draft, propose_edit) ne sont listés que si la connexion dispose de la portée themes:write. Les résultats sont du JSON encapsulé dans un bloc de données non fiables. Les échecs sont des erreurs d’outil avec un code : invalid_input, not_found, forbidden, conflict, limit, busy, unsupported ou internal.

Déroulement type

  1. get_reference (sujet overview, puis par exemple commerce ou app_blocks avec le type de thème) pour découvrir ce que la plateforme prend en charge.
  2. list_themes pour trouver la copie, puis list_files, read_file ou search.
  3. save_draft avec le baseHash issu de votre lecture.
  4. validate sur le fichier, et scan pour un design importé.
  5. preview_link, puis transmettez le lien à l’utilisateur. L’utilisateur publie depuis le panneau.

Outils de lecture

get_reference

La référence de la plateforme, générée à partir du même registre que celui utilisé par l’éditeur et par validate. Aucune donnée de boutique. Renvoie du JSON compact. Par exemple, { "topic": "app_blocks", "name": "buy_now" } renvoie ses arguments avec leurs types, leur caractère obligatoire et leurs alias, son comportement et sa prise en charge par type de thème.

Ressources

La même référence est disponible sous forme de ressources MCP (resources/list, resources/read, resources/templates/list) :

list_themes

Les copies de thème de la boutique : thèmes Liquid, designs importés et paquets de code de thème, avec id, name, kind, live et updatedAt. Aucun argument.

list_files

Renvoie files (path, size, kind, contentHash), 400 au maximum, et truncated.

read_file

Renvoie content, contentHash, startLine, endLine et totalLines. Les médias binaires renvoient binary: true sans contenu.

read_files

Renvoie files, chacun avec content et contentHash, pour 1 Mo au maximum au total. Les fichiers manquants ont missing: true ; les fichiers qui dépassent le budget de taille ont skipped. Renvoie les résultats avec path, line, column et un aperçu de la ligne.

get_schema

Sans path : les paramètres du thème issus de config/settings_schema.json et chaque section avec son nom, les identifiants de ses paramètres et ses types de blocs. Avec path : le JSON complet du {% schema %} de la section. Les deux réponses incluent sectionObject : les champs de section et la remarque sur section.css_id.

validate

Sans path ni proposalId, valide l’ensemble de la copie comme le ferait la publication. Renvoie valid et problems (path, line, column, message, severity). Pour les paquets de code de thème, un section.id brut dans le CSS ou dans id=/for= est un warning (il ne rend jamais valid faux). Signale aussi les blocs d’application inconnus, les arguments inconnus ou mal typés (avec une suggestion de correction), les blocs que le type de thème ne prend pas en charge, les appels PapelShip inconnus et les appels au SDK qui ne s’exécutent jamais à cet endroit (par exemple les scripts en ligne sur les pages de thème Liquid).

scan

Exécution à blanc du scanner de sécurité des designs. Rien n’est enregistré. Les thèmes Liquid renvoient unsupported. Renvoie url, un lien vers l’aperçu dans le panneau PapelShip. L’utilisateur doit être connecté. Il affiche les fichiers enregistrés (brouillons) de la copie. Testez les clics, les bascules et les liens sur cette page ; le canevas de l’éditeur visuel sélectionne les éléments au clic.

Outils d’écriture

save_draft

Nécessite themes:write. Transmettez exactement l’un des deux : content ou edits. Les enregistrements sont validés comme ceux de l’éditeur ; un fichier invalide renvoie invalid_input avec le premier problème. Chaque résultat inclut problems, issus des diagnostics de l’éditeur, par exemple l’avertissement section.css_id dans les paquets de code.

propose_edit

Nécessite themes:write. Mêmes arguments que save_draft, plus un summary obligatoire d’une ligne ; note n’est pas utilisé. N’enregistre jamais : la proposition attend que le propriétaire l’accepte dans l’éditeur de code et expire au bout de 24 heures. Utilisez-le lorsque vous voulez que le propriétaire examine chaque modification.

Protocole

  • Transport : Streamable HTTP, réponses JSON, sans sessions. GET renvoie 405.
  • Versions du protocole : 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05.
  • Lots : jusqu’à 10 messages. Chaque message compte dans la limite de débit.
  • Autorisation : OAuth 2.1 avec PKCE, découvert via https://app.papelship.com/.well-known/oauth-protected-resource/mcp, ou une clé API Themes comme jeton Bearer.