ZynoHosting

ZynoHosting CLI 和 MCP 服务

@zyno-io/zynohosting 是 ZynoHosting 的公开命令行工具和本地 MCP 客户端。它可以：

• 列出当前租户凭据已授权访问的站点；
• 检查、下载、上传和删除单个文件；
• 预览并应用由清单驱动的完整部署；
• 下载完整的可部署快照，或使用额外权限下载所有用户内容；
• 发现、创建、检查、编辑、嵌入和配置已发布的 ZynoForms；
• 通过本地 stdio MCP 服务向 Agent 提供相同的操作。

此软件包需要 Node.js 24。

完整的 CLI 和 MCP 文档请参阅 zyno-io.github.io/zynohosting-cli。

安装

npm install --global @zyno-io/zynohosting
zynohosting --help

此软件包会安装两个可执行文件：

• zynohosting — 面向用户和 CI 的命令行界面；
• zynohosting-mcp — 本地 stdio MCP 服务。

也可以在不进行全局安装的情况下运行命令：

npx -y @zyno-io/zynohosting sites list

身份验证

交互式用户可运行：

zynohosting login --permission hosting.sitesRead
zynohosting login \
  --name "Claude MCP — work laptop" \
  --permission hosting.sitesRead \
  --permission hosting.deploy \
  --permission forms.create \
  --permission forms.edit \
  --renewable

浏览器登录会创建与租户绑定的 CLI 令牌，并为其限定权限范围。如果未提供 --permission，则会请求 hosting.sitesRead；重复指定此选项，可为工作流请求最小且完整的权限集合。访问令牌始终会在 60 分钟后过期。--renewable 会将轮换续期凭据存储在操作系统的凭据存储区中，使长时间运行的 CLI/MCP 进程能够自动续期。只要 MCP 持续运行，即使没有调用任何工具，它也会在后台续期；每个请求也会检查凭据是否有效，以作为后备保障。续期密钥绝不会写入 JSON 配置文件。

运行 zynohosting logout 可撤销已保存的限定权限授权并删除本地凭据。

对于 CI 或其他非交互式环境，请注入租户 API 密钥：

export ZYNOHOSTING_API_KEY='...'

CLI 还支持 --environment production|alpha|dev 和 --api-url。凭据按以下顺序解析：

1. 命令选项；
2. 环境变量；
3. 已保存的登录文件。

相关环境变量包括：

• ZYNOHOSTING_API_KEY
• ZYNOHOSTING_ACCESS_TOKEN
• ZYNOHOSTING_TENANT_ID
• ZYNOHOSTING_TOKEN_EXPIRES_AT
• ZYNOHOSTING_API_URL
• ZYNO_SUITE_API_URL
• ZYNO_AUTH_API_URL
• ZYNOHOSTING_ENVIRONMENT
• ZYNOHOSTING_CONFIG
• ZYNOHOSTING_LOGIN_URL

站点

zynohosting sites list
zynohosting sites get example.com
zynohosting sites get 11111111-1111-4111-8111-111111111111 --json

站点可通过其 UUID、主机名、个性化主机名或已授权别名指定。

单个文件

远程路径相对于站点文档根目录。系统会拒绝绝对路径、..、控制字符、反斜杠和符号链接遍历。

zynohosting files list example.com
zynohosting files list example.com wp-content/themes --recursive

zynohosting files get example.com index.html --output ./index.html
zynohosting files put example.com ./index.html index.html
zynohosting files rm example.com obsolete.html --yes

使用 ETag 可防止覆盖自上次检查后发生更改的文件：

zynohosting files put example.com ./index.html index.html --etag '"etag-from-list"'
zynohosting files rm example.com obsolete.html --etag '"etag-from-list"' --yes

使用 --create 可要求上传路径尚不存在。

完整部署

zynohosting deploy example.com ./dist
zynohosting deploy example.com ./dist --dry-run
zynohosting deploy example.com ./dist --yes

部署始终会先进行规划，然后再应用。客户端和节点 Agent 会：

1. 就协议限制和强制忽略项达成一致；
2. 清点本地和远程内容；
3. 仅对大小相同的候选文件进行哈希计算；
4. 返回精确的创建、替换和删除计划；
5. 仅上传已更改的文件；
6. 在进行修改前重新验证远程快照；
7. 成功应用后使站点缓存失效。

强制部署范围不包括由平台管理的配置、上传内容、缓存、日志、版本控制系统数据和依赖项。可在 .zynohostingignore 中添加项目排除项，或使用 --ignore 添加。

本地部署内容为空时，必须使用 --allow-empty 才能删除远程可部署范围内的内容。

完整下载

默认快照与可部署范围一致：

zynohosting download example.com ./site-copy

下载受保护的配置和用户生成内容需要单独的 hosting.downloadSensitive 权限：

zynohosting download example.com ./complete-copy --sensitive

目标目录必须是新建或空目录。归档字节会按照托管节点生成的方式解压；CLI 会验证传输是否完成、gzip 数据流以及 tar 条目，然后再以原子方式安装暂存目录树。系统会拒绝绝对路径、路径遍历、链接、设备文件和其他不受支持的条目。

本地 MCP 服务

MCP 服务仅使用本地 stdio。它不会开放端口，也不提供托管式／云端 MCP 端点。

对于非技术用户，请将以下内容粘贴到 Codex 或 Claude Code 中：

如果此项目尚未配置，请为其设置 ZynoHosting MCP。详情请参阅 https://raw.githubusercontent.com/zyno-io/zynohosting-cli/main/docs/mcp/agent.md。

Agent 只会配置自己的项目文件——Claude Code 使用 .mcp.json，Codex 使用 .codex/config.toml——且不会存储凭据。完成后请重启 Agent；MCP 工具不会添加到已运行的会话中。该提示词指向为 Agent 编写的安装说明；配套的面向用户的提示词涵盖登录、发布和表单。

ZYNOHOSTING_MCP_ROOTS 是 MCP 进程可选的本地计算机允许列表。未设置时，本地文件工具可以使用 MCP 进程用户有权访问的任何绝对路径。配置根目录后，本地文件读取、写入、部署源文件、忽略文件和下载目标路径都会在规范化路径解析后限制在这些根目录内。

直接调用：

zynohosting-mcp --root /absolute/path/to/project

该软件包的主二进制文件还提供适用于注册表的形式：

npx -y @zyno-io/zynohosting mcp --root /absolute/path/to/project

客户端配置示例：

{
    "mcpServers": {
        "zynohosting": {
            "command": "npx",
            "args": ["-y", "@zyno-io/zynohosting", "mcp"],
            "env": {
                "ZYNOHOSTING_MCP_ROOTS": "/absolute/path/to/project"
            }
        }
    }
}

在 macOS 和 Linux 上，多个 ZYNOHOSTING_MCP_ROOTS 使用 : 作为分隔符。Windows 使用 ;。也支持重复使用 --root 参数。

MCP 工具包括：

• login
• list_sites
• get_site
• list_forms
• get_form_integration
• describe_form
• create_basic_form
• update_form
• update_form_bot_protection
• update_form_origins
• list_files
• get_file
• put_file
• delete_file
• plan_deploy
• apply_deploy
• plan_download
• apply_download

完整部署和下载会有意使用单独的 plan/apply 调用。计划仅保存在本地 MCP 进程中，不包含可见的 bearer token，会随短期访问会话过期，并且在服务重启后无法应用。

MCP 可以在未保存登录信息的情况下启动。Agent 会调用 login 打开 ZynoSuite 浏览器登录流程，并在工具结果中收到一次性 URL；浏览器回调后，它会调用 login 并传入 action: "status" 以确认登录。它绝不能根据项目推断部署域名，也不能选择相似的已授权站点；如果项目未说明目标域名，它应先询问。如果当前登录上下文中无法使用所述域名，它不得改用其他域名，而应再次提供 login，以切换上下文。

权限

租户凭据受明确的 Hosting 和 Forms 权限限制：

权限	功能
hosting.sitesRead	列出和查看站点
hosting.filesRead	列出文件并下载单个文件
hosting.filesWrite	创建和替换单个文件
hosting.filesDelete	删除单个文件
hosting.deploy	规划并执行完整部署
hosting.download	下载可部署快照
hosting.downloadSensitive	包含受保护内容和用户生成的内容
hosting.analyticsRead	读取 Hosting 分析数据
hosting.analyticsManage	更改分析配置
forms.create	创建并立即发布基本表单
forms.edit	编辑表单、其 Cap 保护设置和允许的 CORS 来源

表单发现和集成工具使用同一租户凭据访问 ZynoSuite API。根据 Hosting 站点引用添加来源还需要 hosting.sitesRead。

租户管理员拥有常规管理权限默认值。非管理员凭据仅获得明确授予的操作权限。

以上表格列出了全部权限。zynohosting login --help 会打印该表格，MCP login 工具也会在其架构中列出这些权限，因此诸如 hosting.sitesWrite 这样的虚构键会在本地被拒绝，并提示最接近的有效键；此时浏览器尚未打开。CLI 令牌请求不能包含 msp.login、msp.impersonate、core.changePassword 或 core.manageFingerprints。浏览器也会拒绝未知权限和当前用户不具备的权限；它绝不会部分授予请求的权限。

一次只能运行一个 MCP 浏览器流程。使用相同请求重复调用 login 会返回相同的一次性 URL（"reused": true）；请求不同权限会取消正在进行的流程并生成新的 URL，而不会返回先前的权限范围。action: "cancel" 会放弃流程并关闭其环回监听器。

JSON 输出

大多数 CLI 命令都接受 --json。部署会以换行分隔的形式输出进度、计划和结果事件；列表和文件命令则输出单个 JSON 文档。

公共 API 和发布流程

公共文档站点介绍了 CLI 命令、MCP 工具、配置、权限和安全性。管理器与节点 Agent 的契约见 BACKEND_PLAN.md。维护者的发布设置和仅基于标签的镜像设计见 RELEASING.md。