Herramientas MCP

Flujo de extremo a extremo

Una implementación real expresada como una secuencia de llamadas a herramientas MCP.

La MCP referencia de herramienta enumera cada herramienta individualmente. Esta página los agrupa como una única implementación real para que pueda ver cómo se ve realmente la sesión de un agente.

El flujo supone:

  • un espacio de trabajo Showly con al menos un sitio
  • una ficha MCP con alcances project:read, site:read, site:write, preview:create, checks:run, publish:request, publish:confirm, logs:read
  • un cliente Claude Code o Codex conectado a https://mcp.showly.ai/mcp, p.

claude mcp add --scope user --transport http showly https://mcp.showly.ai/mcp, luego autorice en el navegador en la primera llamada a la herramienta. Ver el guía de conexión para todos los demás hosts.

Las entradas y salidas siguientes se acortan JSON. Consulte la referencia de herramienta para ver esquemas completos.

1. list_projects — elige el proyecto

Encuentre el proyecto en el que operará el agente.

// Input
{}
// Output
{
  "ok": true,
  "data": [
    {
      "id": "22222222-2222-4222-8222-222222222222",
      "name": "Acme",
      "slug": "acme",
      "createdAt": "2026-05-01T10:00:00.000Z"
    }
  ]
}

El agente elige el projectId relevante y lo recuerda durante el resto de la sesión.

2. list_sites — encuentra el sitio

Un proyecto puede contener varios sitios, por lo que el agente enumera los sitios bajo el projectId elegido para obtener un siteId concreto para operar.

// Input
{ "projectId": "22222222-2222-4222-8222-222222222222" }
// Output
{
  "ok": true,
  "data": [
    {
      "id": "33333333-3333-4333-8333-333333333301",
      "name": "Marketing site",
      "slug": "marketing-site",
      "projectId": "22222222-2222-4222-8222-222222222222"
    }
  ]
}

El agente elige la coincidencia siteId y la usa durante el resto de la sesión.

3. get_site_context — leer el estado actual

Obtenga el manifiesto + actividad reciente del sitio que el usuario desea cambiar.

// Input
{ "siteId": "33333333-3333-4333-8333-333333333301" }
// Output
{
  "ok": true,
  "data": {
    "site": {
      "id": "33333333-3333-4333-8333-333333333301",
      "name": "Marketing site"
    },
    "framework": "next",
    "routes": ["/", "/pricing", "/about"],
    "envReferences": ["NEXT_PUBLIC_ANALYTICS_ID"],
    "latestPreviewUrl": "https://acme-pr-12.showly.site",
    "lastProductionDeploymentId": "99999999-9999-4999-8999-999999999902"
  }
}

4. create_change_plan - declarar intención

Describe lo que quieres cambiar. Esta llamada no modifica archivos.

// Input
{
  "siteId": "33333333-3333-4333-8333-333333333301",
  "request": "Change the hero headline to 'Ship without ceremony'"
}
// Output
{
  "ok": true,
  "data": {
    "siteId": "33333333-3333-4333-8333-333333333301",
    "request": "Change the hero headline to 'Ship without ceremony'",
    "plan": [
      {
        "path": "app/page.tsx",
        "action": "edit",
        "summary": "Replace H1 text"
      }
    ],
    "nextStep": "apply_site_patch"
  }
}

El agente normalmente muestra el plan al usuario para que lo confirme antes de continuar.

5. apply_site_patch — escribe el cambio

Prepare las ediciones de archivos reales.

// Input
{
  "siteId": "33333333-3333-4333-8333-333333333301",
  "files": [
    {
      "path": "app/page.tsx",
      "content": "export default function Page() {\n  return <h1>Ship without ceremony</h1>;\n}\n"
    }
  ],
  "message": "Update hero headline"
}
// Output
{
  "ok": true,
  "data": {
    "changesetId": "cs_01HZ8K2QRR3KKTYR4MA8YPNZRC",
    "siteId": "33333333-3333-4333-8333-333333333301",
    "fileCount": 1,
    "ttlSeconds": 3600,
    "nextStep": "create_preview"
  }
}

El conjunto de cambios es temporal: si no lo materializa dentro de ttlSeconds, caduca.

6. create_preview: crea una URL de vista previa

Materialice el conjunto de cambios como una versión preliminar.

// Input
{ "changesetId": "cs_01HZ8K2QRR3KKTYR4MA8YPNZRC" }
// Output
{
  "deploymentId": "99999999-9999-4999-8999-99999999990a",
  "previewUrl": "https://acme-pr-13.showly.site",
  "framework": "next",
  "fileCount": 1
}

La compilación se ejecuta en un espacio de trabajo aislado. La mayoría de los sitios de marketing finalizan en menos de 90 segundos.

7. run_checks — humo + pelusa

Ejecute la matriz de verificación del espacio de trabajo con la vista previa.

// Input
{ "deploymentId": "99999999-9999-4999-8999-99999999990a" }
// Output
{
  "ok": true,
  "data": {
    "deploymentId": "99999999-9999-4999-8999-99999999990a",
    "checks": [
      { "id": "lint", "status": "passed" },
      { "id": "typecheck", "status": "passed" },
      { "id": "build", "status": "passed" },
      { "id": "audit-gate", "status": "pending" }
    ],
    "summary": "3 passed / 1 pending"
  }
}

Si una verificación falla, el agente debe mostrarle la falla al usuario y regresar al paso 4 con un plan corregido.

8. request_publish — abre la aprobación

Cuando el espacio de trabajo tiene flujos de trabajo de aprobación habilitados, la publicación se dirige a través de un aprobador humano. Esta llamada abre la solicitud y devuelve un enlace profundo al revisor. Visitas para aprobar o rechazar. De lo contrario, el agente utiliza el método de dos pasos. publish_site confirmación. Ninguno de los flujos requiere inscripción OTP/MFA.

// Input
{
  "deploymentId": "99999999-9999-4999-8999-99999999990a",
  "message": "Hero headline update — agent-proposed"
}
// Output
{
  "approvalId": "ap_01HZ8K2QRRA0V01Q3Q7H7R7K2P",
  "deploymentId": "99999999-9999-4999-8999-99999999990a",
  "state": "pending",
  "expiresAt": "2026-05-26T11:00:00.000Z",
  "reused": false,
  "webApprovalUrl": "https://showly.ai/app/deployments/99999999-9999-4999-8999-99999999990a/publish",
  "actionUrl": "https://showly.ai/app/deployments/99999999-9999-4999-8999-99999999990a/publish"
}

El agente muestra webApprovalUrl al usuario. Un revisor hace clic en él, revisa la diferencia y aprueba; Showly luego promueve el artefacto de vista previa a producción.

El verbo rollback_deployment heredado no es una herramienta MCP: reside en la interfaz de usuario web detrás de la MFA mejorada. publish_site y rollback_to_version se pueden llamar a MCP mediante una confirmación de dos pasos; consulte la referencia de herramienta para obtener más detalles.

9. get_deployment_logs — confirmar

Después de la aprobación, la implementación de producción lleva el mismo deploymentId. Extraiga registros para confirmar que el artefacto de compilación se promocionó limpiamente.

// Input
{
  "deploymentId": "99999999-9999-4999-8999-99999999990a",
  "lineCount": 50
}
// Output
{
  "ok": true,
  "data": {
    "deploymentId": "99999999-9999-4999-8999-99999999990a",
    "lineCount": 50,
    "source": "db",
    "lines": [
      "[build] starting pnpm build",
      "[build] generated 1 page in 14s",
      "[deploy] promoted to production at 2026-05-26T10:05:21Z"
    ]
  }
}

Ese es el ciclo completo: planificar → parchear → vista previa → verificar → aprobar → enviar → confirmar.

¿Qué sigue?