MCP 工具

MCP 概述

为什么 Showly 通过 MCP 工具提供能力，而不是只暴露原始 REST API。

Showly 通过模型上下文协议向编码智能体 提供能力。本页解释采用 MCP 的原因；具体工具见 工具参考。

为什么使用 MCP

如果只提供 REST API，每个智能体都要分别理解认证流程、请求结构和错误 语义。MCP 统一解决了这三个问题：

  • 类型化工具。 每项能力都是带 JSON Schema 输入和输出的 tool。

Claude Code、Codex 等宿主可以自动向用户展示工具列表。

  • 带作用域的令牌。 Showly MCP 令牌绑定到工作区、可选项目、通过

OAuth/设备流程完成授权的用户，以及明确的工具作用域。令牌只获得 智能体实际需要的权限。

  • 原生审计。 每次工具调用都会记录客户端 ID、操作、经过敏感信息

脱敏的参数和结果。

智能体看到什么

安装 Showly MCP 客户端后，智能体会看到按功能分组的工具：

  • 阅读 — list_projects、list_sites、get_site_context、get_site_files、get_preview_status
  • 计划 — create_change_plan
  • 应用 — apply_site_patch
  • 构建 — create_preview、run_checks、retry_deployment
  • 发布 — request_publish（创建人工审批流程）；publish_site 和

rollback_to_version 通过对话内的两步确认执行

  • 检查 — get_deployment_logs、diagnose_deployment、list_deployments、list_site_versions、diff_site_versions
  • 创建 — list_templates、create_site_from_template、create_site_from_html、claim_trial_site
  • 传输 — request_upload_url、request_download_url（为不应进入模型

上下文的大文件生成签名 URL）

  • 清理 — delete_preview、delete_site

每个工具的 schema 都明确限定影响范围。例如，request_publish 必须 指定预览的 deploymentId。旧版 rollback_deployment 不通过 MCP 公开，只存在于需要 MFA 提权的 Web UI 中。会影响生产环境的 MCP 工具 （publish_site、rollback_to_version、delete_site）第一次调用不会 执行操作，而是返回短时确认令牌；第二次调用必须原样提交该令牌。

如何限定令牌

工作区管理员从 工作区设置 → MCP 客户端 颁发 MCP 令牌。每个令牌具有：

  • 客户端名称（让审计日志显示为“Claude Code（alice@acme）”）
  • 可选的项目限制（限定客户端可访问的项目）
  • 作用域集合 — 不存在层级或隐式继承的扁平字符串，默认包含

project:read、site:read、preview:read；完整列表见 作用域和令牌

  • TTL（默认 90 天，最长 365 天）

可以从同一面板立即撤销令牌。

边界

MCP 表面故意不暴露：

  • 直接数据库访问。
  • 生产环境变量值。
  • 任何类型的跨租户读取。
  • 工作区计费或用户管理写操作。

如果智能体工作流需要列表之外的能力，请提交问题。通常应新增一个权限 更窄的工具，而不是直接开放底层 API。

下一步