MCP referencia de herramienta

Cada herramienta que expone el servidor Showly MCP. Cada entrada enumera el alcance requerido, el esquema de entrada en formato breve, la forma de retorno y lo que se escribe en el registro de auditoría.

Todas las herramientas requieren un cliente MCP autenticado. Los tokens se emiten desde Configuración del espacio de trabajo → MCP clientes.

Cuando una llamada se bloquea

Todo fallo que Showly devuelve usa la misma envoltura: tanto los que decide una herramienta como los que decide la capa MCP antes de ejecutarla (un ámbito que el token no tiene, un argumento o un resultado demasiado grande). ok es false y error es un código de tipo string sobre el que puedes ramificar, nunca un objeto. Un rechazo de la capa MCP además activa el indicador isError de MCP, de modo que un cliente que se base en él sigue viendo una llamada fallida; el texto que acompaña al indicador es ese mismo JSON.

Tres fallos no usan esta envoltura, porque los responde el SDK de MCP antes de que se ejecute código de Showly. Los tres llegan como isError: true con un mensaje de texto plano:

• Un argumento ausente o con el tipo equivocado: MCP error -32602: Input validation error: Invalid arguments for tool <name>: …. Es el fallo más frecuente que produce una integración, así que analiza el cuerpo de forma defensiva.
• Un nombre de herramienta que este servidor no expone: MCP error -32602: Tool <name> not found.
• Un error inesperado: una avería de transporte o un defecto.

Un argumento que la herramienta no declara no está en esa lista y ni siquiera es un fallo: el SDK descarta las claves desconocidas antes de la llamada, así que la herramienta solo ve los argumentos que declaró.

Trata un cuerpo que no puedas analizar como un error desconocido en lugar de suponer un código.

{
  ok: false,
  error: "insufficient_credits",
  message: "A production deployment costs 5 credits and this workspace has 2 left.",
  status?: 402,

  resolvedBy: "agent" | "human",
  actionUrl?: "https://showly.ai/app/billing#upgrade",
  humanAction?: "Open Plan & Billing and add credits, then tell the agent to retry.",
  agentNext: {
    kind: "retry" | "retry_with" | "call_tool" | "poll" | "wait_for_human" | "stop",
    tool?: "publish_site",
    afterSeconds?: 10,
    note: "After the balance changes, start the publish over from step 1."
  }
}

Lee resolvedBy primero. "agent" significa que puedes resolverlo tú mismo con las herramientas que ya tienes: elegir otro previewSlug, obtener el id que faltaba, o llamar a la herramienta que indica agentNext.tool. "human" significa que ninguna secuencia de llamadas servirá: transmite humanAction y actionUrl al usuario y luego sigue agentNext.

actionUrl es absoluta y apunta a una página de la aplicación web de Showly, nunca a un área reservada a administradores. Transmite actionUrl como enlace cuando esté presente, y transmite humanAction siempre: esa frase es lo que hace que el enlace sirva a la persona adecuada. Plan y facturación es el caso que importa: está limitado a propietarios, administradores y al rol de facturación, y el pago exige además billing:write, así que a un miembro que siga el enlace se le devuelve al panel. Showly no puede saber cuál de los dos está leyendo tu mensaje —la página decide a partir de la sesión web de la persona, mientras que un token MCP describe al agente—, así que el enlace se envía siempre y humanAction lleva la salvedad: un propietario actúa sobre él y cualquier otra persona lo reenvía. El antiguo webUpgradeUrl en un fallo de plan o de créditos lleva la misma URL y la misma salvedad.

Los mismos cuatro campos aparecen en el único éxito que necesita a una persona: request_publish devuelve resolvedBy, actionUrl, humanAction y agentNext en el nivel superior, exactamente donde los pone un fallo, de modo que if (result.actionUrl) funciona en ambos casos. También se repiten dentro de data, junto al antiguo webApprovalUrl, para que una integración que lea data.actionUrl siga funcionando.

Dos campos anteriores se siguen enviando junto a actionUrl con el mismo valor, de modo que las integraciones existentes siguen funcionando: webVerificationUrl en email_verification_required y webApprovalUrl en un request_publish correcto.

list_projects

Alcance: project:read

Enumera los proyectos (espacios de trabajo) que el token puede ver.

Input:  {}
Output: { ok, data: Array<{ id, name, slug, createdAt }> }
Audit:  mcp.list_projects

list_sites

Alcance: site:read

Enumera los sitios en el espacio de trabajo actual. Pase projectId para determinar el alcance del listado; un token MCP con alcance de proyecto fuerza este filtro independientemente del parámetro.

Input:  { projectId?: string }
Output: { ok, data: Array<Site>, view: ListSitesView }
Audit:  mcp.list_sites

Esta es la única herramienta que responde con dos bloques de texto. El primero es un resumen redactado en el servidor —los nombres de los sitios, cuáles son públicos y una acción recomendada— por lo que se lee igual en cada llamada. El segundo es el sobre JSON anterior, sin cambios: léalo desde content[content.length - 1], no desde content[0]. El mismo sobre también se devuelve como structuredContent, y view es la proyección de la que parten tanto el resumen como la representación interactiva descrita a continuación.

Un cliente que declara la extensión MCP Apps io.modelcontextprotocol/ui en sus capacidades de initialize también recibe _meta.ui.resourceUri en esta herramienta, que apunta a un recurso HTML ui:// que el anfitrión representa en un iframe aislado. Un cliente que no la declara nunca ve esos metadatos, y nada más del resultado cambia.

get_site_context

Alcance: site:read

Devuelve el sitio, su marco detectado, rutas, nombres de var de entorno a los que se hace referencia, la última URL de vista previa y la última identificación de implementación de producción para un siteId determinado. Vea la forma Site en [Tipos comunes](#common-types).

Input:  { siteId }
Output: { ok, data: { site, framework, routes, envReferences, latestPreviewUrl, lastProductionDeploymentId } }
Audit:  mcp.get_site_context  (records siteId)

create_change_plan

Alcance: site:read

Produce una propuesta de plan de cambio. _No_ modifica ningún archivo. El agente normalmente lee el plan devuelto, solicita confirmación al usuario y luego llama al apply_site_patch.

Input:  { siteId, request: string }
Output: { ok, data: { siteId, request, plan, nextStep } }
Audit:  mcp.create_change_plan

apply_site_patch

Alcance: site:write

Etapas de ediciones de archivos para un sitio. El conjunto de cambios preparado es temporal y debe materializarse antes del create_preview.

Input:  { siteId, files: Array<{ path, content }>, message: string }
Output: { ok, data: { changesetId, siteId, fileCount, ttlSeconds, nextStep } }
Audit:  mcp.apply_site_patch  (records siteId + changesetId + file count)

create_preview

Alcance: preview:create

Crea el espacio de trabajo parcheado y genera una URL de vista previa. El usuario es propietario del decisión de acceso privado: omitir access para un breve XXX-XXX generado por el servidor contraseña, pase una contraseña personalizada de 6 a 128 caracteres o seleccione organization (Pro+) o organization_or_password. El texto plano generado se devuelve una vez y no se puede recuperar más tarde. Una vista previa no puede ser pública; publicarlo en vivo cuando debe ser visible para todos. previewSlug puede elegir una dirección separada de un solo nivel: <previewSlug>.showly.site.

Input:  { changesetId?, siteId?, files?, previewSlug?, access?: { mode, password? } }
Output: { deploymentId, previewUrl, framework?, fileCount?, access: { mode, passwordConfigured, password? } }
Audit:  mcp.create_preview

create_github_preview

Alcance: preview:create

Crea una vista previa privada a partir de la última confirmación en el GitHub conectado de un sitio rama. La credencial de instalación se queda dentro de Showly. Omita access para obtener un contraseña corta generada por el servidor XXX-XXX devuelta una vez, pase una personalizada 6–128 contraseña de caracteres, o elija acceso de miembro de la organización en Pro+. esta herramienta nunca publica Live. Encuesta get_preview_status con los devueltos deploymentId.

Si el sitio no tiene un repositorio de aplicaciones GitHub activo, conéctelo primero en Showly Web. La creación automática de repositorios actualmente admite objetivos de implementación estáticos; una dinámica El objetivo del contenedor regresa repository_build_target_unsupported antes que nada. está en cola. Un correo electrónico Showly no verificado devuelve email_verification_required con una URL web para completar la verificación.

set_preview_access

Alcance: preview:create

Cambia la política de acceso de una vista previa o de un despliegue Live publicado sin cambiar su URL. Para proteger un sitio publicado, usa el id production listo de list_deployments; la herramienta conserva su nombre histórico por compatibilidad. El modo de contraseña rota la contraseña; pasa un valor de 6 a 128 caracteres u omite password para generar un código corto para compartir XXX-XXX en el lado del servidor. la respuesta muestra la nueva contraseña en texto plano una vez junto a previewUrl. Cada política El cambio invalida las cookies de acceso a vista previa emitidas anteriormente.

Los modos de organización verifican la membresía activa de la organización Showly del visitante, para que los compañeros de equipo inicien sesión en lugar de compartir una contraseña. organization_or_password mantiene ese flujo interno al tiempo que permite que un revisor externo use una contraseña.

Input:  { deploymentId, access: { mode: "password" | "organization" | "organization_or_password", password? } }
Output: { deploymentId, target, previewUrl, access: { mode, passwordConfigured, password? }, policyVersion, advancedDeploymentControls }
Audit:  mcp.set_preview_access

Ejemplo de rotación de contraseña personalizada:

{
  "deploymentId": "00000000-0000-4000-8000-000000000000",
  "access": { "mode": "password", "password": "ABC-123" }
}

retry_deployment

Alcance: preview:create

Reconstruye una implementación de vista previa fallida o cancelada. Vuelva a suministrar el mismo files que proporcionó create_preview; la fuente no se conserva en el lado del servidor, por lo que files es obligatorio. Acuña un nuevo deploymentId (el fallido permanece como historial) en status: "building" y lo devuelve para su sondeo. Cada reintento cuenta contra su cuota de implementación mensual: es una versión nueva. Devuelve 409 not_retryable si la implementación aún se está construyendo o ya está lista, 404 si no es visible para su token, 402 si excede la cuota.

Input:  { deploymentId, files: [{ path, content }] }
Output: { ok, data: { deploymentId, status: "building", pollUrl, retriedFrom } }
Audit:  mcp.retry_deployment

run_checks

Alcance: checks:run

Ejecuta la matriz de verificación del espacio de trabajo (lints, tipos, enlaces de CI personalizados) en una vista previa. checks es una lista de { id, status } filas (lint / typecheck / build / audit-gate); summary es una cadena de una línea como "3 passed / 1 pending".

Input:  { deploymentId }
Output: { ok, data: { deploymentId, checks: [{ id, status }], summary } }
Audit:  mcp.run_checks

request_publish

Alcance: publish:request

Abre una solicitud de aprobación para una implementación de vista previa lista. La respuesta incluye un enlace profundo webApprovalUrl; mostrar ese enlace para que el usuario pueda revisar la información exacta Obtenga una vista previa y complete cualquier aprobación en segunda persona requerida por el plan. La publicación no no requiere inscripción OTP/MFA. El usuario vinculado al token MCP debe tener un cuenta de correo electrónico verificada Showly. Si la herramienta regresa email_verification_required, envía el usuario a webVerificationUrl para reenviar y complete la verificación antes de volver a intentarlo.

Input:  { deploymentId, message: string }
Output: { approvalId, deploymentId, state: "pending", expiresAt, reused, webApprovalUrl }
Audit:  mcp.request_publish

publish_site

Alcance: publish:confirm

Publica una implementación de vista previa lista para producción directamente desde la conversación, para espacios de trabajo individuales y planes sin flujos de trabajo de aprobación. El usuario vinculado al token MCP debe tener una cuenta de correo electrónico Showly verificada. Si la herramienta devuelve email_verification_required, envíe al usuario a webVerificationUrl, espere a que complete la verificación y luego reinicie el flujo de dos pasos; el sitio aún no está activo. Dos pasos confirmado por humanos: llame con siteId + deploymentId (no confirmationToken) para obtener un resumen + confirmationToken de corta duración; Muestre al usuario lo que está a punto de publicarse y luego vuelva a llamar con el token. El paso 2 regresa 202 publishing. En planes con flujos de trabajo de aprobación habilitados, use request_publish en su lugar: esta herramienta lo dirige allí.

Step 1: { siteId, deploymentId }                        → { confirmationToken, summary }
Step 2: { siteId, deploymentId, confirmationToken }      → { siteId, deploymentId, status: "publishing" }
Audit:  mcp.publish_site

Los hosts que renderizan MCP Apps pueden ahorrarse la ida y vuelta del paso 1: la tarjeta de una Preview lista lleva un botón Publish live, y al pulsarlo la confirmación del usuario llega a la conversación como un mensaje. Trata ese mensaje como la confirmación: encadena la comprobación previa y la publicación confirmada, y responde una sola vez con el resultado. Lo demás no cambia: las mismas dos llamadas, el mismo token emitido por el servidor, los mismos bloqueos y el mismo coste en créditos que cualquier despliegue de producción.

get_preview_status

Alcance: preview:read

Devuelve el estado actual de una implementación de vista previa. Opcionalmente, realiza encuestas largas (por defecto, 30 segundos, hasta 60 segundos) hasta que el estado se aleja de un valor conocido, lo cual es útil después de request_publish mientras se espera a un revisor. Cuando status es failed o canceled, el resultado también lleva errorCode, errorMessage, stage y un breve logTail que explica por qué falló la compilación; empareje con retry_deployment para reconstruir.

Input:  { deploymentId, waitForChange?: boolean, currentStatus?: string, timeoutMs?: number }
Output: { ok, data: Deployment & { productionUrl?, errorCode?, errorMessage?, stage?, logTail? }, changed?, timedOut? }
Audit:  mcp.get_preview_status

get_deployment_logs

Alcance: logs:read

Devuelve el final del registro de compilación para una implementación (las últimas lineCount líneas, por defecto 200, del resultado de la compilación capturada). source discrimina db (líneas de registro reales), pending (la implementación existe pero aún no se ha capturado ningún registro; aún se está construyendo o no hay cola), o not-found (no existe dicha implementación para este token).

Input:  { deploymentId, lineCount?: number }
Output: { ok, data: { deploymentId, lineCount, source, lines } }
Audit:  mcp.get_deployment_logs

diagnose_deployment

Alcance: logs:read

Autodiagnostique una de sus implementaciones propias. Devuelve un único paquete de diagnóstico estructurado y consumible por IA para que el agente pueda razonar sobre por qué una compilación falló en una llamada y luego corrija la fuente y retry_deployment, en lugar de unir lecturas get_preview_status / get_deployment_logs separadas. El paquete agrega: el error de compilación (stage, errorCode, errorMessage, un logTail), errores de tiempo de ejecución relacionados de Sentry (correlacionados por el compromiso SHA + entorno + una ventana alrededor de la implementación, falla suave), el estado del ops-job de la implementación, el estado de la cuota de la organización, cualquier clientLogs enviado por el agente (redactado + limitado) y determinista hypotheses: causas fundamentales probables con confianza (por ejemplo, quota_exceeded / build_install_failed), derivadas de reglas (no de IA) como punto de partida de alta calidad.

Aislado por inquilino: solo puede diagnosticar implementaciones en su propia organización. Una identificación de implementación que no es visible para su token devuelve 404 (indistinguible de una identificación inexistente; no se filtra la existencia entre organizaciones). Este es el gemelo orientado al agente del paquete del Centro de diagnóstico del personal; ambos comparten un agregador de backend. Llamadas GET /deployments/:deploymentId/diagnostics.

Input:  { deploymentId }
Output: { ok, data: { deployment, failure, jobRun, quota, sentry, clientLogs, hypotheses } }
Audit:  mcp.diagnose_deployment

list_templates

Alcance: template:read

Enumera Showly plantillas de sitio disponibles para el token actual. Emparéjelo con create_site_from_template para incorporar un nuevo sitio sin un repositorio de Git.

Input:  { framework?: string }
Output: { ok, data: Array<{ slug, displayName, description, framework, screenshots }> }
Audit:  mcp.list_templates

create_site_from_template

Ámbitos: template:create, site:write

Materializa un nuevo sitio administrado por Showly a partir de una plantilla y construye su primer Vista previa privada. Omitido access genera una contraseña propiedad del servidor devuelta exactamente una vez con initialPreviewUrl; Los modos de organización requieren Pro. siteSlug es la dirección estable <siteSlug>.showly.site tanto para esta primera vista previa como para Live.

Input:  { projectId, templateSlug, name, siteSlug, variables?: Record<string, unknown>, access?: { mode, password? } }
Output: { ok, data: { siteId, projectId, initialVersionId, initialPreviewDeploymentId, initialPreviewUrl, access, templateSlug, createdAt } }
Audit:  mcp.create_site_from_template

create_site_from_html

Ámbitos: site:write, preview:create

Crea un nuevo sitio administrado por Showly directamente a partir de archivos HTML/CSS/JS simples: sin plantilla, sin marco, sin repositorio Git. Pase ya sea los archivos en línea (se requiere index.html; encoding: "base64" para activos binarios), o un sourceBundleId para una fuente grande que cargó fuera de banda a través de request_upload_url (exactamente uno de files / sourceBundleId). Se crea el sitio y se construye su primera vista previa en una sola llamada; sondea el deploymentId devuelto con get_preview_status. siteSlug se convierte en la dirección compartida <siteSlug>.showly.site de Vista previa/Live. La producción permanece en el flujo de publicación.

Input:  { projectId, name, siteSlug, files?: Array<{ path, content, encoding?: "utf8" | "base64" }>, sourceBundleId?, framework?, access?: { mode, password? } }
Output: { ok, data: { siteId, deploymentId, status | previewUrl, access, ... } }
Audit:  mcp.create_site_from_html

request_upload_url

Ámbitos: site:write, preview:create

Crea una URL de carga de corta duración y un solo uso para una fuente de sitio grande que no debe pasar por el modelo. Envía un archivo tar al uploadUrl devuelto mediante PUT con Content-Type: application/x-tar y llama a create_site_from_html con el sourceBundleId devuelto en lugar de files.

Input:  {}
Output: { ok, data: { uploadUrl, sourceBundleId, contentType, expiresInSeconds } }
Audit:  mcp.request_upload_url

request_download_url

Alcance: site:read

La herramienta de lectura equivalente a request_upload_url. Pasa un deploymentId visible para recibir un downloadUrl de corta duración y un solo uso para su archivo fuente conservado. Edita el archivo localmente, carga la nueva fuente con request_upload_url y pasa su sourceBundleId a create_preview. Devuelve source_not_retained (422) cuando no hay un archivo fuente disponible; usa get_site_files para sitios pequeños.

Input:  { deploymentId }
Output: { ok, data: { downloadUrl, expiresInSeconds } }
Audit:  mcp.request_download_url

claim_trial_site

Alcances: site:write

Reclama un sitio creado mediante el flujo de prueba público de Showly en la cuenta autenticada actual, para que deje de caducar y se vuelva permanente. Pasa el trialId + guestToken proporcionado por el servidor. Falla si la prueba ya expiró o si el espacio de trabajo tiene una restricción explícita de sitios activos; elimina un sitio sin usar o contacta con el soporte de Showly y vuelve a intentarlo. Free y Pro permiten sitios de vista previa y publicados ilimitados de forma predeterminada; actualizar el plan no añade sitios.

Input:  { trialId: string, guestToken: string }
Output: { ok, data: { trialId, siteId, claimed: true } }
Audit:  mcp.claim_trial_site

delete_preview

Alcance: preview:create

Elimina temporalmente una implementación de vista previa por identificación. Devuelve deletedAt. Idempotente: al eliminar una vista previa ya eliminada se devuelve 404 preview_not_found. Aquí sólo se pueden eliminar las vistas previas; la producción no se ve afectada.

Input:  { deploymentId }
Output: { ok, data: { deploymentId, deletedAt } }
Audit:  mcp.delete_preview

delete_site

Alcance: site:delete

Elimina temporalmente un sitio y conecta en cascada a sus implementaciones, versiones y dominios personalizados. Dos pasos confirmado por humanos: llame con siteId (no confirmationToken) para obtener un resumen (el slug + cuántas implementaciones en cascada) más un confirmationToken de corta duración; muéstrele al usuario, luego llame nuevamente con el token para eliminar. Recuperable sólo desde la copia de seguridad.

Step 1: { siteId }                          → { confirmationToken, summary: { siteSlug, cascade: { deployments } } }
Step 2: { siteId, confirmationToken }        → { siteId, deletedAt }
Audit:  mcp.delete_site

list_site_domains

Alcance: site:read

Enumera los dominios personalizados adjuntos a un sitio, incluido el paso guiado actual, los registros DNS, el estado del certificado, la CTA de recuperación, la página de administración y la URL activa. Los resultados incluyen 50 filas de forma predeterminada y admiten hasta 100. Cuando pagination.nextCursor no sea null, devuélvalo sin cambios como cursor; los cursores son opacos y están vinculados a un solo sitio.

Para un resultado no vacío, siga domains[].journey en cada fila de destino; no hay un journey de nivel superior. El journey de nivel superior solo se devuelve para una lista vacía, donde guía la primera conexión de dominio. Consulte un dominio de destino únicamente mientras su fase sea setting_up_https y deténgase si llega a needs_attention.

Input:  { siteId, limit?, cursor? }
Output: { ok,
          journeyGuide: { steps, whatShowlyGivesYou },
          domains: [{ id, hostname, status, isLive, certStatus, liveUrl,
                      manageUrl, dnsRecords, proxyNote, apexNote?,
                      journey: { phase, currentStep, stepStatuses,
                                 whereYouAre, userAction, agentAction,
                                 actionUrl }, recovery? }],
          pagination: { count, total, nextCursor },
          journey? }
Audit:  mcp.list_site_domains

add_custom_domain

Alcance: site:write · Disponible en todos los planes

Adjunta el propio dominio de un cliente a un sitio y devuelve los registros DNS que el usuario debe publicar en su proveedor de dominio.

No puede completar este paso por ellos. El reclamo crea un registro pendiente y no dirige tráfico; el dominio solo se vuelve real una vez que el cliente edita DNS a quien se lo compró. Entrégueles los registros, dígales claramente que no pasa nada hasta que los agreguen y espere. En un dominio raíz, la respuesta lleva un apexNote: salga a la superficie, porque un CNAME simple no es válido en el vértice de una zona. Toda respuesta lleva además un proxyNote: transmítalo, porque el CNAME debe publicarse sin proxy (en Cloudflare, nube gris; los registros nuevos son naranjas) o el certificado nunca podrá emitirse, y el registro TXT se verifica igual, así que nada más en el flujo lo detectará.

Conservar el verificationToken devuelto; verify_custom_domain lo necesita y se muestra solo una vez.

Input:  { siteId, hostname }
Output: { ok, domain: { id, hostname, status, dnsRecords, proxyNote, apexNote?, verificationToken }, nextStep }
Audit:  mcp.add_custom_domain

verify_custom_domain

Alcance: site:write · Disponible en todos los planes

Vuelve a comprobar DNS si hay un dominio pendiente. Llámelo después de que el usuario diga que ha agregado los registros. Solo tiene éxito si el registro realmente se publica y propaga; un error generalmente significa "todavía no", no "roto", así que espere unos minutos y vuelva a intentarlo en lugar de informar un error.

En caso de éxito, el certificado TLS se solicita automáticamente y el dominio se activa en una hora. Encuesta list_site_domains para isLive.

Input:  { siteId, domainId, token }
Output: { ok, domain: { id, hostname, status, isLive, ... } }
Audit:  mcp.verify_custom_domain

La eliminación de un dominio deliberadamente no está disponible para los agentes. Archivar un dominio activo desconecta el sitio del cliente en una dirección que ha anunciado, instantáneamente y sin que nada externo a Showly necesite aceptar, por lo que permanece como acción de una persona en el panel. Ver ADR 0015.

list_site_versions

Alcance: site:read

Enumera el historial de versiones de un sitio (la más reciente primero): id, source, changeSummary, autor, createdAt. Emparéjelo con get_site_files (pasando un versionId) para leer el contenido de esa versión.

Paginado por conjunto de claves. limit mayúsculas a 100 por página; para llegar a versiones anteriores, pase el pagination.nextCursor de la respuesta anterior como cursor. Un nextCursor de null significa que has llegado al final del historial. El cursor es opaco y está vinculado a un sitio: fija el catálogo en el instante de su primera página, por lo que las versiones creadas mientras su página no pueden desplazar filas a una página que ya ha leído.

hasMore está obsoleto y refleja pagination.nextCursor !== null; prefiera pagination.

Input:  { siteId, limit?, cursor? }
Output: { ok, data: {
          versions: [{ id, source, changeSummary, authorUserId, createdAt }],
          hasMore,
          pagination: { limit, nextCursor: string | null }
        } }
Audit:  mcp.list_site_versions

list_deployments

Alcance: site:read

Enumera las implementaciones de un sitio (las más recientes primero): id, target (preview / staging / production), status, url, createdAt. De aquí es de donde proviene el deploymentId: use el id devuelto con retry_deployment, delete_preview, request_publish o publish_site.

Input:  { siteId }
Output: { ok, data: [{ id, siteId, target, status, url, createdAt }] }
Audit:  mcp.list_deployments

get_site_files

Alcance: site:read

Lee el árbol de archivos de la versión de un sitio (path → content) para que pueda ver el contenido actual antes de editarlo. Pase siteId + versionId (de list_site_versions). Las versiones grandes/respaldadas por manifiesto devuelven files: null más un note.

Input:  { siteId, versionId }
Output: { ok, data: { versionId, source, changeSummary, files: Record<string,string> | null, note? } }
Audit:  mcp.get_site_files

diff_site_versions

Alcance: site:read

Compara dos versiones y devuelve exactamente lo que cambió: estado por archivo (added / removed / changed) más nivel de línea add / remove / context. Pase siteId + versionA (el "antes" más antiguo) + versionB (el "después" más nuevo), ambos de list_site_versions. Responde preguntas como "qué cambió entre ayer y hoy". Las versiones grandes o respaldadas por manifiestos no se pueden diferenciar y devuelven un error.

Input:  { siteId, versionA, versionB }
Output: { ok, data: {
          versionA: { id, source, changeSummary, createdAt },
          versionB: { id, source, changeSummary, createdAt },
          summary: { filesChanged, filesAdded, filesRemoved, linesChanged },
          files: Array<{ path, status, lines: Array<{ type, text }> }>
        } }
Audit:  mcp.diff_site_versions

rollback_to_version

Alcance: rollback:confirm

Recupera PRODUCCIÓN a una versión anterior y la publica SIN vista previa: la herramienta más importante aquí. Dos pasos confirmado por humanos: llame con siteId + versionId (no confirmationToken) para obtener un warning + resumen + confirmationToken; Muestre al usuario la advertencia y luego vuelva a llamar con el token. El paso 2 regresa 202 building — Showly crea una vista previa de esa versión y la promociona automáticamente a producción. Recuperable al avanzar a una versión más nueva.

Step 1: { siteId, versionId }                       → { confirmationToken, warning, summary: { changeSummary, versionCreatedAt, previewed: false } }
Step 2: { siteId, versionId, confirmationToken }     → { siteId, versionId, deploymentId, status: "building" }
Audit:  mcp.rollback_to_version

Herramientas de producción (no expuestas a MCP)

No expuesto a MCP: requiere flujo de aprobación Web/API.

La acción heredada rollback_deployment no está disponible mediante MCP. No aparece en tools/list y no se puede invocar con un token MCP; usa la pantalla de aprobación correspondiente de Showly Web.

La publicación de producción es MCP-invocable: publish_site (confirmación de dos pasos, arriba) publica directamente y rollback_to_version revierte la producción, ambas herramientas de estilo kind: "confirm-publish" que nunca actúan en la primera llamada.

Tipos comunes

La referencia utiliza algunas de las formas nombradas arriba. El conjunto de campos concreto se muestra en el flujo de extremo a extremo, que recorre una sesión completa con JSON real. Resúmenes rápidos:

status es uno de queued, building, ready, failed, canceled. ready es el estado de éxito del terminal para implementaciones de versión preliminar y de producción. framework se detecta automáticamente en el momento de la compilación y es uno de astro, vite, next-export, static-html, custom o unknown; no es algo que usted establezca en el manifiesto.

Versionado

Los esquemas de herramientas siguen semver a través del campo MCP version. Los cambios importantes incluyen un nuevo nombre de herramienta (apply_site_patch_v2); el nombre anterior continúa funcionando durante al menos un ciclo de lanzamiento con una nota de obsolescencia en notes.