not_found. Las herramientas de escritura (save_draft, propose_edit) solo aparecen cuando la conexión tiene el alcance themes:write.
Los resultados son JSON envuelto en un bloque de datos no confiables. Los fallos son errores de herramienta con un code: invalid_input, not_found, forbidden, conflict, limit, busy, unsupported o internal.
Flujo de trabajo habitual
get_reference(temaoverviewy luego, por ejemplo,commerceoapp_blockscon el tipo de tema) para saber qué admite la plataforma.list_themespara encontrar la copia y luegolist_files,read_fileosearch.save_draftcon elbaseHashde su lectura.validatesobre el archivo, yscanpara un diseño subido.preview_linky entregue el enlace al usuario. El usuario publica en el panel.
Herramientas de lectura
get_reference
La referencia de la plataforma, generada a partir del mismo registro que usan el editor yvalidate. Sin datos de la tienda.
Devuelve JSON compacto. Por ejemplo,
{ "topic": "app_blocks", "name": "buy_now" } devuelve sus argumentos con tipos, indicadores de obligatoriedad y alias, su comportamiento y su compatibilidad por tipo de tema.
Recursos
La misma referencia está disponible como recursos MCP (resources/list, resources/read, resources/templates/list):
list_themes
Las copias de tema de la tienda: temas Liquid, diseños subidos y paquetes de código de tema, conid, name, kind, live y updatedAt. Sin argumentos.
list_files
Devuelve
files (path, size, kind, contentHash), como máximo 400, y truncated.
read_file
Devuelve
content, contentHash, startLine, endLine y totalLines. Los archivos multimedia binarios devuelven binary: true sin contenido.
read_files
Devuelve
files con content y contentHash cada uno, con un máximo de 1 MB en total. Los archivos que faltan tienen missing: true; los archivos que superan el límite de tamaño tienen skipped.
search
Devuelve coincidencias con
path, line, column y una vista previa de la línea.
get_schema
Sin
path: la configuración del tema de config/settings_schema.json y cada sección con su nombre, los ID de sus opciones y sus tipos de bloque. Con path: el JSON completo del {% schema %} de la sección. Ambas respuestas incluyen sectionObject: los campos de la sección y la nota sobre section.css_id.
validate
Sin
path ni proposalId, valida toda la copia como lo haría la publicación. Devuelve valid y problems (path, line, column, message, severity). En los paquetes de código de tema, un section.id sin procesar en CSS o en id=/for= es un warning (nunca hace que valid sea false). También señala bloques de aplicación desconocidos, argumentos desconocidos o con un tipo incorrecto (con una sugerencia de corrección), bloques que el tipo de tema no admite, llamadas a PapelShip desconocidas y llamadas al SDK que nunca se ejecutan ahí (por ejemplo, scripts en línea en las páginas de temas Liquid).
scan
Ejecución de prueba del escáner de seguridad de diseños. No se registra nada. Los temas Liquid responden
unsupported.
preview_link
Devuelve
url, un enlace a la vista previa en el panel de PapelShip. El usuario debe haber iniciado sesión. Muestra los archivos guardados (borradores) de la copia. Pruebe los clics, interruptores y enlaces en esta página; el lienzo del editor visual selecciona al hacer clic.
Herramientas de escritura
save_draft
Requierethemes:write.
Pase exactamente uno de
content o edits. Los guardados se validan igual que los del editor; un archivo no válido responde invalid_input con el primer problema.
Cada resultado incluye
problems de los diagnósticos del editor, por ejemplo la advertencia sobre section.css_id en los paquetes de código.
propose_edit
Requierethemes:write. Los mismos argumentos que save_draft más un summary obligatorio de una línea; note no se usa. Nunca guarda: la propuesta espera a que el propietario la acepte en el editor de código y caduca a las 24 horas. Úsela cuando quiera que el propietario revise cada cambio.
Protocolo
- Transporte: Streamable HTTP, respuestas JSON, sin sesiones.
GETresponde405. - Versiones del protocolo:
2025-11-25,2025-06-18,2025-03-26,2024-11-05. - Lotes: hasta 10 mensajes. Cada mensaje cuenta para el límite de solicitudes.
- Autorización: OAuth 2.1 con PKCE, descubierto desde
https://app.papelship.com/.well-known/oauth-protected-resource/mcp, o una clave de API de Temas como token Bearer.