MCP 工具

端到端流程

实际部署表示为一系列 MCP 工具调用。

MCP工具参考单独列出了每个工具。此页面将它们作为单个真实部署连接在一起，以便您可以看到代理会话的实际情况。

该流程假设：

  • 至少有一个站点的 Showly 工作区
  • MCP令牌，范围为project:read、site:read、site:write、preview:create、checks:run、publish:request、publish:confirm、logs:read
  • 连接到 https://mcp.showly.ai/mcp 的 Claude Code 或 Codex 客户端 — 例如

claude mcp add --scope user --transport http showly https://mcp.showly.ai/mcp, 然后在浏览器中对第一个工具调用进行授权。请参阅 每个其他主机的连接指南。

下面的输入和输出被缩短JSON。有关完整模式，请参阅工具参考。

1. list_projects — 选择项目

找到代理将运营的项目。

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

代理选择相关的 projectId 并在会话的其余部分中记住它。

2. list_sites — 找到站点

一个项目可以拥有多个站点，因此代理会在所选的projectId下列出站点，以获得具体的siteId进行操作。

// 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"
    }
  ]
}

代理选择匹配的 siteId 并将其用于会话的其余部分。

3. get_site_context — 读取当前状态

获取用户想要更改的站点的清单+最近的活动。

// 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 — 声明意图

描述你想要改变什么。此调用不修改文件。

// 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"
  }
}

代理通常会在继续之前向用户显示计划以供确认。

5. apply_site_patch — 写入更改

暂存实际的文件编辑。

// 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"
  }
}

变更集是临时的——如果您没有在 ttlSeconds 内实现它，它就会过期。

6. create_preview — 构建预览 URL

将变更集具体化为预览版本。

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

构建在隔离的工作区中运行。大多数营销网站在 90 秒内完成。

7. run_checks — 烟雾 + 棉绒

根据预览运行工作区的检查矩阵。

// 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"
  }
}

如果检查失败，代理应向用户显示失败情况，并使用更正的计划返回到步骤 4。

8. request_publish — 开启审批

当工作区启用审批工作流时，发布路由通过 人类批准者。此调用打开请求并向审阅者返回深层链接 访问以批准或拒绝。否则，代理将使用两步 publish_site确认。这两个流程都不需要 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"
}

代理向用户呈现webApprovalUrl。审阅者单击它，审阅差异并批准； Showly 然后将预览工件提升到生产环境。

旧版 rollback_deployment 不是 MCP 工具，只存在于需要 MFA 提权的 Web UI 中。publish_site 和 rollback_to_version 可以通过两步确认从 MCP 调用；详情见工具参考。

9. get_deployment_logs — 确认

批准后，生产部署带有相同的deploymentId。拉取日志以确认构建工件已干净地升级。

// 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"
    ]
  }
}

这就是完整的循环：计划→补丁→预览→检查→批准→发货→确认。

接下来是什么