内容
# 兔子 CLI 和 MCP 服务器
[](https://www.npmjs.com/package/bunny-tools)
[](https://www.npmjs.com/package/bunny-tools)
[](https://github.com/bytekcorp/bunny-tools/actions/workflows/ci.yml)
[](https://github.com/bytekcorp/bunny-tools/actions/workflows/e2e-nightly.yml)
[](LICENSE)
**软件包：** `bunny-tools` · **二进制文件：** `bunny` · **Node.js 版本：** ≥20
## 为什么使用 bunny-tools
Bunny.net 是一个优秀的 CDN/存储/DNS/流媒体平台，但是从终端管理它需要自己动手。bunny-tools 解决了这个问题，提供了一个二进制文件，涵盖了存储、CDN、DNS、流媒体和边缘脚本 - 以及一个内置的 MCP 服务器，以便 AI 代理可以驱动每个命令：
- **`bunny deploy` 适用于静态网站。** 熟悉的用法，如果你使用过 `firebase deploy` - 遍历公共目录 → SHA 缓存差异 → 并行上传 → CDN 清除，全部在一个命令中。
- **`bunny.json` 是你的单一事实来源。** 版本控制在 git 中。每个命令都遵循它。JSON 模式发布在 `unpkg.com/bunny-tools/schema/bunny.schema.json`。
- **通过 MCP 实现 AI 原生。** AI 代理看到的表面与你看到的一样 - 不需要为每个代理单独的插件。 `bunny install mcp` 一次注册到 Claude Code。
- **验证端到端。** 185 个单元测试 + 每晚针对真实的 Bunny 账户进行漂移检测。我们在部署失败之前捕获 Bunny API 更改。
## 安装
### 作为 CLI
```bash
npm install -g bunny-tools
```
### 作为 MCP 服务器（推荐用于 AI 工作流）
对于 Claude Code：
```bash
claude mcp add bunny-tools npx -y bunny-tools mcp
```
对于 Claude Desktop，添加到 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"bunny-tools": {
"command": "npx",
"args": ["-y", "bunny-tools", "mcp"]
}
}
}
```
安装后，任何 Claude 会话都可以使用 15 个高级工具（`bunny.deploy`、`bunny.purge`、区域/ DNS CRUD）加上 3 个资源（`bunny://manifest`、`bunny://agents`、`bunny://config/current`），而无需事先了解。有关完整的工具表面，请参见下面的 [MCP 服务器](#mcp-服务器-ai-集成)。
## 快速入门
```bash
bunny init # 交互式：身份验证 + 功能选择器 + bunny.json
bunny deploy --dry-run # 预览
bunny deploy # 存储同步 + CDN 清除
```
`bunny init` 会引导您完成：
1. Bunny 账户 API 密钥（如果已在环境变量或密钥链中，则跳过）
2. 功能多选 - 存储 + CDN、DNS、流媒体、Magic Containers、边缘脚本
3. 每个功能的配置（例如，对于存储 + CDN：公共目录、存储区域、密码、拉取区域、清除策略）
CI 的非交互式表单：
```bash
bunny init --non-interactive --features=storage \
--api-key=$BUNNY_API_KEY \
--storage-zone=my-app \
--storage-password=$BUNNY_STORAGE_PASSWORD \
--pull-zone=12345
```
添加 `--ci` 还可以生成 `.github/workflows/bunny-deploy.yml` 以用于 GitHub Actions。
## AI 代理的快速入门
安装了 MCP 服务器（参见 [安装](#安装)）后，Claude Code 和 Claude Desktop 可以驱动每个命令。进入任何项目并尝试：
| 您说的话 | 发生的情况 |
| --- | --- |
| **"使用 bunny-tools 为该项目设置 CI/CD"** | 运行 `bunny init`，使用官方操作写入 `.github/workflows/deploy.yml`，并列出您需要添加的机密 |
| **"将此网站部署到 Bunny"** | 读取现有的 `bunny.json`，运行 `bunny deploy`（先进行干燥运行预览） |
| **"清除标记为 release-2026-04 的 CDN 缓存"** | 调用 `bunny.purge`，带有 `tag:release-2026-04` |
| **"显示我的 Bunny 账户信息"** | 调用 `bunny.whoami` + 列出可达区域计数 |
| **"在我的 Bunny DNS 区域 example.com 中添加一个 A 记录，指向 www → 1.2.3.4"** | 解析区域 ID，调用 `bunny.dns_record_add` |
为了在新项目中获得最佳结果，请在项目的 `CLAUDE.md` 中添加一个 2 行提示：
```markdown
## 部署
该项目使用 bunny-tools。运行 `bunny init` 进行首次设置，然后运行 `bunny deploy`。
```
这将 Claude 锚定到该项目的 bunny-tools。
---
## 设置和身份验证
| 命令 | 描述 |
| --- | --- |
| `bunny init` | 交互式设置 - 身份验证 + 功能选择器 + bunny.json |
| `bunny configure` | 演练 - 在命名配置文件中存储凭据 |
| `bunny configure list` | 列出所有凭据配置文件 + 范围（掩码） |
| `bunny configure switch <name>` | 设置活动配置文件 |
| `bunny configure remove <name> [scope]` | 删除配置文件或其中的单个范围 |
| `bunny use [alias]` | 从 `.bunnyrc` 切换活动别名（或列出别名） |
| `bunny whoami` | 显示当前帐户上下文 + 可达区域计数 |
| `bunny docs [topic]` | 在浏览器中打开 Bunny.net 文档 |
**示例**
```bash
bunny configure --profile=staging
bunny configure switch staging
```
## 部署和清除
| 命令 | 描述 |
| --- | --- |
| `bunny deploy` | 将公共目录同步到存储区域并清除 CDN 缓存 |
| `bunny purge <target>` | 按 URL、 `tag:<name>` 或 `pullzone:<id>` 清除 |
**示例**
```bash
bunny deploy --dry-run
bunny purge tag:release-2026-05
```
## 存储（文件操作）
| 命令 | 描述 |
| --- | --- |
| `bunny storage upload <local> <remote>` | 将单个文件上传到活动区域 |
| `bunny storage download <remote> <local>` | 从区域下载单个文件 |
| `bunny storage list [path]` | 列出存储区域路径 |
| `bunny storage delete <path>` | 删除文件或路径（对目录使用 `--recursive`） |
| `bunny storage sync <local-dir>` | 将本地目录镜像到区域 - SHA 缓存差异，并行上传 |
**示例**
```bash
bunny storage sync ./dist --zone=my-app
```
## 存储区域
| 命令 | 描述 |
| --- | --- |
| `bunny storagezone list` | 列出存储区域 |
| `bunny storagezone get <id\|name>` | 获取存储区域 |
| `bunny storagezone create <name>` | 创建存储区域 |
| `bunny storagezone update <id> --body=<json>` | 更新存储区域（原始 JSON 正文） |
| `bunny storagezone delete <id>` | 删除存储区域 |
## 拉取区域（CDN）
> **提示：** `bunny cdn ...` 在任何 `bunny pullzone ...` 可以使用的地方都可以使用 - Bunny 的仪表板称这些为“CDN”，所以别名是为了肌肉记忆。规范名称遵循 Bunny 的 API（`pullzone`）。
| 命令 | 描述 |
| --- | --- |
| `bunny pullzone list`（或 `bunny cdn list`） | 列出拉取区域 |
| `bunny pullzone get <id>` | 获取拉取区域 |
| `bunny pullzone create <name>` | 创建拉取区域 |
| `bunny pullzone update <id> --body=<json>` | 更新拉取区域（原始 JSON 正文） |
| `bunny pullzone delete <id>` | 删除拉取区域 |
| `bunny pullzone edgerule list <id>` | 列出拉取区域上的边缘规则 |
| `bunny pullzone edgerule add <id> --rule=<json>` | 添加边缘规则（原始 JSON 规则） |
| `bunny pullzone edgerule delete <id> <rule-id>` | 删除边缘规则 |
| `bunny pullzone hostname list <id>` | 列出链接到拉取区域的自定义主机名 |
| `bunny pullzone hostname add <id> <hostname>` | 链接主机名 + 配置 Let's Encrypt 证书 + ForceSSL。幂等。 `--no-force-ssl` 退出 HTTP→HTTPS 重定向 |
| `bunny pullzone hostname remove <id> <hostname>` | 取消链接自定义主机名 |
**示例**
```bash
bunny cdn edgerule list 12345
# 将 DNS 连接到拉取区域（2 步 - `add` 链接 + 证书 + ForceSSL
# 在一个幂等调用中；DNS 记录指向连接的 PZ）：
bunny pullzone hostname add 5780316 example.com # ~2-90s
bunny dns record add 783181 PULLZONE @ --pull-zone=5780316
# 或通过原子连接域名命令一次性完成所有操作：
bunny domain connect 5780316 example.com --dns-zone=783181
```
## DNS
| 命令 | 描述 |
| --- | --- |
| `bunny dns list` | 列出 DNS 区域 |
| `bunny dns get <id\|domain>` | 获取 DNS 区域 |
| `bunny dns create <domain>` | 创建 DNS 区域 |
| `bunny dns delete <id>` | 删除 DNS 区域 |
| `bunny dns record list <zone>` | 列出区域中的记录 |
| `bunny dns record add <zone> <type> <name> <value>` | 添加记录（位置参数） |
| `bunny dns record update <zone> <record-id> --body=<json>` | 更新记录 |
| `bunny dns record delete <zone> <record-id>` | 删除记录 |
**支持的记录类型：** 标准 `A`、`AAAA`、`CNAME`、`TXT`、`MX`、`SRV`、`CAA`、`NS` 加上 Bunny 路由类型 `REDIRECT`、`PULLZONE`、`PTR`、`SCRIPT`。`PULLZONE` 和 `SCRIPT` 需要 `--link-name=<id>`（链接的拉取区域/脚本 ID）。对于 `PULLZONE`，您可以使用便捷标志 `--pull-zone=<id>` 代替，CLI 将从拉取区域的元数据中填充值和链接名称。（`FLATTEN` 在 Bunny 的 OpenAPI 规范中记录，但实时 API 拒绝它；如果 Bunny 在服务端启用，则删除支持的类型 - 重新添加。）
**示例**
```bash
# 标准 A 记录
bunny dns record add 783181 A www 1.2.3.4 --ttl=300
# 重定向 www → https://example.com
bunny dns record add 783181 REDIRECT www https://example.com
# 将 DNS 连接到拉取区域 - 自动填充值 + 链接名称
bunny dns record add 783181 PULLZONE "" --pull-zone=5780316
# 或原始表单，如果您已经知道 PZ 名称
bunny dns record add 783181 PULLZONE "" my-pz-name --link-name=5780316
```
## 流媒体
| 命令 | 描述 |
| --- | --- |
| `bunny stream library list` | 列出流媒体库 |
| `bunny stream library create <name>` | 创建流媒体库 |
| `bunny stream library delete <id>` | 删除流媒体库 |
| `bunny stream video list <library>` | 列出库中的视频 |
| `bunny stream video upload <library> <file>` | 将视频上传到库 |
| `bunny stream video delete <library> <video-id>` | 删除视频 |
**示例**
```bash
bunny stream video upload 42 ./demo.mp4 --title="My demo"
```
## 魔法容器
| 命令 | 描述 |
| --- | --- |
| `bunny containers app list` | 列出容器应用 |
| `bunny containers app delete <id>` | 删除容器应用 |
> `containers app create` 延迟到 v0.2 - Bunny 的 v3 模式需要 `runtimeType` + `containerTemplates[]` + `autoScaling`，而当前 CLI 界面尚未对其进行建模。目前，请通过 Bunny 仪表板进行管理。
## 边缘脚本
| 命令 | 描述 |
| --- | --- |
| `bunny scripting list` | 列出边缘脚本 |
| `bunny scripting deploy <name> --code=<file>` | 创建或更新脚本（双模式） |
| `bunny scripting delete <id>` | 删除脚本 |
**示例**
```bash
bunny scripting deploy my-router --code=./worker.js
```
## 发现和 AI
| 命令 | 描述 |
| --- | --- |
| `bunny manifest --pretty` | 完整的注册表作为 JSON（机器可读表面） |
| `bunny manifest --names` | 每行一个命令名称 - 适用于 shell 补全 |
| `bunny <any-command> --help-json` | 任何命令的帮助作为 JSON |
| `bunny mcp` | 启动 MCP stdio 服务器（15 个工具，3 个资源） |
参见 [`AGENTS.md`](./AGENTS.md) 获取 AI 代理指南。
---
## 全局标志
适用于任何命令：
| 标志 | 效果 |
| --- | --- |
| `-c, --config <path>` | 覆盖 `bunny.json` 位置 |
| `--cwd <dir>` | 运行于此目录 |
| `-e, --env <alias>` | 一次性 `.bunnyrc` 别名 |
| `-p, --profile <name>` | 一次性凭据配置文件 |
**示例**
```bash
bunny --profile=staging deploy
```
## 配置
**`bunny.json`** （每个项目，git 跟踪）：
```jsonc
{
"$schema": "https://unpkg.com/bunny-tools/schema/bunny.schema.json",
"deploy": {
"publicDir": "dist",
"ignore": ["bunny.json", ".bunnyrc", "**/.*", "**/node_modules/**"],
"storageZone": "my-app",
"region": "ny",
"concurrency": 8,
"pullZones": [{ "id": 12345, "purge": "all" }]
}
}
```
**`.bunnyrc`** （每个开发人员的别名，无 git 忽略）：
```json
{
"default": "prod",
"aliases": {
"prod": { "storageZone": "my-app", "pullZones": [12345] },
"staging": { "storageZone": "my-app-stg", "pullZones": [12346] }
}
}
```
**多账户配置文件** (`~/.config/bunny-tools/credentials.json`)：
```jsonc
{
"active": "default",
"profiles": {
"default": { "account": "...", "storage:my-app": "..." },
"staging": { "account": "...", "storage:my-app-stg": "..." }
}
}
```
使用 `bunny configure switch <name>` 切换活动配置文件，或使用 `bunny --profile=<name> <cmd>` 或 `BUNNY_PROFILE=<name>` 进行一次性切换。
## 身份验证模型
四个凭据范围（都使用 `AccessKey` HTTP 头）：
- `account` - 账户 API 密钥
- `storage:<zone>` - 存储区域密码（每个区域）
- `stream:<lib>` - 流媒体库 API 密钥（每个库）
- `database:<name>` - 数据库访问密钥
**解析链（每个调用站点）：** `--flag` → 作用域环境变量（例如 `BUNNY_STORAGE_PASSWORD_MY_APP`）→ 常规环境变量（`BUNNY_STORAGE_PASSWORD`）→ 操作系统密钥链（`<profile>:<scope>` 密钥）→ `~/.config/bunny-tools/credentials.json` → 交互式提示。
## GitHub Actions
`bunny init --ci` 生成一个工作流，使用 npm-install + `bunny deploy`：
```yaml
- name: Install bunny-tools
run: npm install -g bunny-tools
- name: Deploy
env:
BUNNY_API_KEY: ${{ secrets.BUNNY_API_KEY }}
BUNNY_STORAGE_PASSWORD_MY_APP: ${{ secrets.BUNNY_STORAGE_PASSWORD_MY_APP }}
run: bunny deploy
```
一个复合动作包装器（`bytekcorp/bunny-tools-deploy-action@v1`）正在 v0.2 路线图中开发，以提供更紧密的用法。上述 npm-install 形式是 v0.1 的规范路径。
## MCP 服务器（AI 集成）
安装步骤在 [安装 → 作为 MCP 服务器](#作为-mcp-服务器-推荐用于-ai工作流) 中提供。一旦配置完成，服务器就会暴露：
**工具（15）：** `bunny.deploy`、`bunny.purge`、`bunny.init`、`bunny.manifest`、`bunny.whoami`、存储区域 CRUD、拉取区域 CRUD、DNS 区域 + 记录 CRUD，以及 `bunny.run` 作为任何 CLI 调用的逃生阀。
**资源（3）：**
- `bunny://manifest` - 完整的 JSON 命令注册表
- `bunny://agents` - AGENTS.md（AI 代理的工作流程、陷阱和约定）
- `bunny://config/current` - 来自 `bunny.json` 和活动别名的已解析配置
**跨项目使用。** 安装了 MCP 服务器后，在任何新项目的 `CLAUDE.md` 中添加一个 2 行提示，将 Claude 锚定到该项目的 bunny-tools：
```markdown
## 部署
该项目使用 bunny-tools。运行 `bunny init` 进行首次设置，然后运行 `bunny deploy`。
```
## 开发
```bash
git clone https://github.com/bytekcorp/bunny-tools
cd bunny-tools
npm ci
npm run build
npm test
npm run dev -- manifest --pretty
```
有关针对真实 Bunny 账户（漂移检测）的端到端测试，请参见 [`docs/e2e-testing.md`](docs/e2e-testing.md)。
有关发布说明，请参见 [`docs/deployment-guide.md`](docs/deployment-guide.md)。
## 常见问题
**这是官方的 Bunny.net CLI 吗？**
不，bunny-tools 是一个社区 CLI。Bunny.net 发布了 [`@bunny.net/cli`](https://www.npmjs.com/package/@bunny.net/cli)，专注于数据库、Magic Containers 和边缘脚本。bunny-tools 涵盖了不同的表面（存储、CDN、DNS、流媒体、边缘脚本），并附带一个用于 AI 代理的 MCP 服务器。
**为什么二进制文件名为 `bunny`？**
短小且符合品牌。注意，`@bunny.net/cli` 也会安装一个 `bunny` 二进制文件，因此同时安装两者将会发生冲突 - 选择一个或为另一个使用 `npx`。
**我可以在 CI 中使用吗？**
是的。`bunny init --ci` 生成一个 `.github/workflows/bunny-deploy.yml`。所有命令都遵循 `BUNNY_API_KEY` 和每个区域的作用域环境变量。
**它在没有 Node.js 的情况下是否有效？**
目前仅限 npm（Node 20+）。独立二进制文件正在 v0.2 路线图中开发。
## 许可证
MIT - 参见 [LICENSE](./LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器