技能

Showly Skill 快速上手

安装 @showly/mcp-server，在浏览器中完成授权，并从终端生成真实的预览 URL。

Showly 的核心体验是“直接通过智能体部署网站”。本指南给出完整的 端到端流程。在一台新电脑上，从安装到获得第一个预览通常只需约 90 秒；生产发布还需要一次人工浏览器确认。

1. 安装到智能体

官方安装入口是 @showly/mcp-server 软件包（可执行文件为 showly-mcp）。Claude Code 使用：

npx @showly/mcp-server install --to claude-code

Codex 使用：

npx @showly/mcp-server install --to codex

命令会向 ~/.claude.json 或 ~/.codex/config.toml 写入一个 MCP 服务器条目，其中只包含传输方式和服务器 URL，不会写入令牌。 智能体会从端点发现 Showly 的 OAuth 授权服务器，并在首次使用时 启动浏览器登录。软件包还提供带类型的 manifest.json，列出每个 Showly 工具、所需作用域，以及该工具能否从 MCP 发起。

浏览器登录与无头登录的说明见安装 Skill。

如果安装程序暂不支持你的智能体，请运行 npx @showly/mcp-server install --to stdout 并手动粘贴片段。

2. 在真实对话中授权

打开 Claude Code、Codex 或其他已接入的智能体，然后提出一个会调用 Showly 的请求，例如：

“列出我的 Showly 网站。”

智能体会调用 list_sites。如果当前设备尚未获得 Showly 令牌，宿主会打开 浏览器登录页，由人点击 Allow。

如果这台机器没有浏览器（服务器、容器、CI、远程终端），或者你不在它旁边， 改用无头登录：

npx @showly/mcp-server login --to claude-code

它会原样打印下面这段，然后一直等待：

Showly needs one approval from you. If you do not have a Showly
account yet, you will be asked to create one first.

  1. Open this page:   https://showly.ai/oauth/device
  2. Enter this code:  K7QM-3XPD

Same machine as your browser? Use the direct link instead:
  https://showly.ai/oauth/device?user_code=K7QM-3XPD

The page will show the code K7QM-3XPD before you approve.
Approve ONLY if it matches the code above. If it shows a
different code, someone else is trying to get in - refuse it.

Waiting for approval until 14:58 local. Once you approve, this
command picks it up on its own - no need to come back and tell it.

在任意设备上打开该页面（手机也可以），使用注册 Showly 时的账号登录。 授权确认页会显示短码、请求的作用域，以及允许和拒绝按钮。

核对页面上的短码与终端一致，勾选确认框，再点击允许。这一步核对是关键： 确认页显示的客户端名称是它自己填写的，只有短码是你能验证的部分。回到终端， 命令会在几秒内返回，读取类工具立即可用。

3. 进行一行更改并预览

向智能体提出请求：

“在 northstar 站点上，将 H1 更改为‘Hello from W7’并给我预览。”

智能体会依次调用四个工具：

  1. create_change_plan — 将自然语言请求整理成结构化计划。
  2. apply_site_patch — 把修改暂存为 _changeset_（作用域 site:write）。
  3. create_preview — 构建 changeset，并返回受保护的预览 URL

（作用域 preview:create）。

  1. run_checks — 读取该部署的 lint、类型检查和构建状态

（作用域 checks:run）。

简单修改通常约 5 秒完成，完整 Next.js 应用通常约 30 秒。智能体会 返回受保护的预览 URL；打开它即可审核变更，不会影响当前正式站点。

4. 发布到生产环境

Showly 不允许智能体绕过人工确认直接发布到生产环境。智能体调用 request_publish（作用域 publish:request）后，会创建一个待审批请求 并返回 webApprovalUrl 深层链接，而不是直接上线：

{
  "ok": true,
  "data": {
    "approvalId": "appr_xxx",
    "deploymentId": "dep_xxx",
    "state": "pending",
    "expiresAt": "2026-05-31T10:00:00.000Z",
    "reused": false,
    "webApprovalUrl": "https://showly.ai/app/deployments/dep_xxx/publish"
  }
}

智能体会把 webApprovalUrl 交给你。打开链接，核对将要发布的预览， 并完成套餐策略要求的队友审批；该流程不要求预先注册 OTP/MFA。发布 开始后，智能体会调用 get_preview_status，设置 waitForChange: true 进行长轮询（默认 30 秒，最长 60 秒）。 生产部署状态变为 ready 后，响应会包含 productionUrl，智能体将其 作为最终线上 URL 返回。

哪些内容会离开本机

  • 智能体在本地运行，例如 Claude Code 或 Codex。
  • 读取站点上下文时，只会返回 MCP 令牌作用域允许的数据。
  • 调用 apply_site_patch 或其他上传工具时，改动文件会发送给 Showly。
  • Showly 使用这些文件构建私有预览，并把适用操作写入工作区审计记录。

完整交付流程见系统架构。

常见错误

  • missing_bearer_token — 智能体没有携带

Authorization: Bearer mcp_…。重新运行 npx @showly/mcp-server install 并重启智能体。

  • invalid_token — 您的令牌已过期、已撤销或不是 MCP 令牌。

再次调用 Showly 工具即可触发新的浏览器登录，智能体会自动取得新 令牌。如需强制重新授权，请先在管理 → 智能体中撤销旧记录。

  • insufficient_scope — 请求的工具需要尚未授权的作用域。撤销后

重新授权，并在确认页批准相应作用域。

  • 生产发布 — publish_site 会在用户明确回答“是”后执行短时有效的

两步确认。如果工作区启用了第二位审批人策略，请改用 request_publish 返回的 webApprovalUrl。两种流程都不要求预先注册 OTP/MFA。

后续步骤