dsh-cloudflare-codemode

把 Cloudflare 的全部 API 交给 AI —— 通过官方 Code Mode MCP，不封装任何单个接口。

为 DeepSeek Harness 提供 Cloudflare 全产品读写能力： AI 拿到 search 与 execute 两个工具，就能动态访问 2,500+ 个 Cloudflare API 端点， 覆盖 Workers、DNS、R2、KV、D1、Pages、Zero Trust、AI Gateway……全部产品线。

附带一个可视化设置面板，支持 OAuth 2.1 浏览器授权与 API Token 两种接入方式， 凭据只保存在本机。

---

快速开始

# 从 npm 安装（推荐）
dsh plugin --profile web add dsh-cloudflare-codemode

# 或从 GitHub 源码安装
dsh plugin --profile web add github:aikunx/dsh-cloudflare-codemode

桌面端把 web 换成 desktop。装完重启 DSH、按 Ctrl + Shift + R 刷新页面， 进入 设置 → Cloudflare 全功能管家 完成 OAuth 授权或填入 API Token。

也可以通过市场源安装：把 https://raw.githubusercontent.com/aikunx/dsh-cloudflare-codemode/main/market.json 加到 设置 → 插件 → 市场源。

---

这是什么

Cloudflare 在 2025 年上线了官方的 Code Mode MCP 服务器 https://mcp.cloudflare.com/mcp。 它不暴露几百个固定工具，而是只给两个：

工具	作用
search	在完整 OpenAPI 规格里检索端点、参数与请求体结构
execute	执行一段 JavaScript，通过 cloudflare.request() 调用任意 Cloudflare API

配合 docs（文档问答）与 whoami（身份确认），AI 可以先查规格、再写代码调用—— 这比"为每个产品手写一个工具"覆盖广得多，也永远不会因为 Cloudflare 加新接口而失效。

本插件的职责很简单：让 DSH 里的模型用上这四个工具。

---

为什么需要这个插件

DSH 自带 MCP 客户端（@deepseek-ai/dsh-mcp-client），但它定位是"配置即连接"： 地址、认证头都写死在 profile 配置里，改一次就要编辑 YAML 并重启宿主。

而 Cloudflare 的凭据是会变的——OAuth 访问令牌两小时过期、API Token 可能被吊销重建。 把明文 Token 写进 cordis.patch.yml 既不安全，也不灵活。

本插件的做法是：在本地起一个只做认证注入的代理，MCP 协议仍由官方客户端处理。

---

工作原理

┌──────────────┐
│   AI 模型     │
└──────┬───────┘
       │  mcp__cloudflare__search / execute / docs / whoami
       ▼
┌──────────────────────────────┐
│ @deepseek-ai/dsh-mcp-client  │  ← DSH 官方包，负责 MCP 协议
│   （随 DSH 一起提供）          │
└──────────────┬───────────────┘
               │  Streamable HTTP
               ▼
┌──────────────────────────────┐
│  127.0.0.1:18923/mcp         │  ← 本插件：注入 Authorization 的代理
│  每次请求重读本机凭据文件       │
└──────────────┬───────────────┘
               │  OAuth / Bearer Token
               ▼
┌──────────────────────────────┐
│ https://mcp.cloudflare.com   │  ← Cloudflare 官方 Code Mode MCP
└──────────────────────────────┘

这层代理换来三件事：

1. 密钥不进配置 —— cordis.patch.yml 里只有端口号，凭据在独立文件里（权限 0600）。
2. 改 Token 立刻生效 —— 代理逐请求读取凭据，面板保存后下一次调用就换上了，无需重启。
3. OAuth 自动续期 —— 访问令牌过期时在代理内透明刷新，对 MCP 客户端完全无感。

本插件不封装任何 Cloudflare 接口。全部 2,500+ 端点都来自 Cloudflare 自己维护的规格。

---

功能

• 全产品读写：DNS、Workers、Pages、R2、KV、D1、Zero Trust、R2、Images、Stream、Logpush……
• 双认证：OAuth 2.1 浏览器授权（PKCE + 动态客户端注册）或 API Token
• 可视化面板：设置页「Cloudflare 全功能管家」——认证切换、连接状态、工具数量、权限清单
• 连接自检：一键跑完整 MCP 握手（initialize → tools/list），如实回报发现的工具
• 状态实时：显示 MCP 桥接是否已连接、已注册的工具名
• 零 DSH 依赖：Host 半只用 Node 内置模块，不 import 任何 @deepseek-ai/*，因此不受内核版本闸门限制

---

安装

需要 DSH 0.2.x（已验证 0.2.1-rc.2），Node.js ≥ 22。

方式一：GitHub 源（推荐）

dsh plugin --profile web add github:aikunx/dsh-cloudflare-codemode

桌面端（profile 名为 desktop）：

dsh plugin --profile desktop add github:aikunx/dsh-cloudflare-codemode

方式二：DSH Desktop 插件管理器

打开 设置 → 插件 → 安装插件，填入仓库地址：

https://github.com/aikunx/dsh-cloudflare-codemode

安装完成后完全退出应用并重新打开。

方式三：本地目录

git clone https://github.com/aikunx/dsh-cloudflare-codemode.git
dsh plugin --profile web add ./dsh-cloudflare-codemode

方式四：插件市场源

本仓库自带 market.json（format 1）。在 设置 → 插件 里把下面的市场索引地址加进去， 即可在 Discover / 市场页直接看到并安装本插件：

https://raw.githubusercontent.com/aikunx/dsh-cloudflare-codemode/main/market.json

安装后

1. 重启 DSH（新增 Host 插件必须重启才会加载）
2. 浏览器按 Ctrl + Shift + R 强制刷新页面
3. 进入 设置 → Cloudflare 全功能管家

---

配置

方式 A：OAuth 2.1 授权（推荐）

1. 设置面板中选择 OAuth 授权 标签
2. 点「开始 OAuth 授权」
3. 浏览器会打开 Cloudflare 授权页，登录并授权
4. 回调完成后面板状态变为「已连接」

插件使用 动态客户端注册 + PKCE，不需要你预先创建 OAuth App。 令牌自动续期，offline_access 让刷新令牌长期有效。

方式 B：API Token

1. 面板中选择 API Token 标签
2. 填入 Account ID（控制台右侧「账户 ID」，32 位十六进制）
3. 填入 API Token
4. 点「保存并测试连接」

Token 保存后不再回显，输入框留空表示保留原值。

---

🔑 Token 权限清单

Cloudflare 没有「一键全权限」复选框，必须逐项勾选。要让写操作（部署 Workers、改 DNS、管 R2）可用：

1. 打开 Dash → My Profile → API Tokens
2. Create Custom Token
3. Permissions 区域，把下表中 Account 与 Zone 两个作用域的权限组设为 Edit（不是 Read）

作用域	权限组	级别	用途
Zone	DNS	Edit	增删改 DNS 记录
Zone	Workers Routes	Edit	绑定路由
Zone	Zone Settings	Edit	缓存、SSL 等配置
Account	Workers Scripts	Edit	部署 / 删除 Worker
Account	Cloudflare Pages	Edit	部署静态站
Account	Workers KV Storage	Edit	键值存储
Account	D1	Edit	数据库
Account	Workers R2 Storage	Edit	对象存储（需先在控制台开通 R2）

4. Account Resources → Include → All accounts
5. Zone Resources → Include → All zones
6. 保存后立刻粘贴到面板，点「保存并测试连接」

只给 Read 会怎样？ 列表、查询能过，但部署、改记录、建桶会全部返回 403。

---

使用

连接成功后，直接用自然语言对话即可：

列一下我账号下所有的 Zone
→ execute: GET /zones

给 example.com 加一条 A 记录，指向 1.2.3.4
→ search 找到 POST /zones/{zone_id}/dns_records
→ execute 创建

把这个目录部署到 Workers
→ search 找到上传会话与部署端点
→ execute 分步上传并部署

我的 D1 里有多少张表？
→ execute: POST /accounts/{id}/d1/database/{db}/query

模型会先用 search 查规格、再用 execute 执行——不需要你记任何 API 路径。

---

配置项

cordis.patch.yml 中本插件行支持的字段：

字段	默认	说明
port	18923	本地代理监听端口（仅绑定 127.0.0.1）

改端口后必须同步修改同一文件里 cloudflare-codemode-mcp 行的 url。

凭据文件：~/.dsh/dsh-cloudflare-codemode.json（权限 0600）

{
  "authMode": "oauth",        // "oauth" | "token"
  "accountId": "…32 位十六进制…",
  "apiToken": "…",            // authMode=token 时使用
  "oauth": {                  // authMode=oauth 时使用
    "clientId": "…",
    "accessToken": "…",
    "refreshToken": "…",
    "expiresAt": 1792523692052
  }
}

---

故障排查

现象	原因与处理
面板显示「未连接」，工具列表为空	尚未配置凭据。填入 Token 或完成 OAuth 后等待约 30 秒（桥接有重连间隔）。
保存了 Token 但工具一直不出现	检查是否已重启 DSH。首次启动时若还没有凭据，桥接会持续重试（预算已设为 2000 次，约 8 小时）。
面板报「Cloudflare 拒绝了当前凭据（401）」	Token 失效或被吊销，重新授权。
某个操作返回 403	Token 权限不足，按上面的权限清单补齐对应的 Edit 权限。
R2 操作报 10042	R2 未在该账户开通，需先去 R2 控制台 启用。
端口 18923 被占用	修改 cordis.patch.yml 中两处端口后重启。

查看实时状态（本机）：

curl http://127.0.0.1:18923/cloudflare-codemode/state

---

安全

• 凭据只存本机：~/.dsh/dsh-cloudflare-codemode.json，权限 0600，永不写入 profile 配置。
• 代理只绑回环：127.0.0.1:18923，不对外网开放。设置面板路由校验同源，拒绝跨站请求。
• OAuth 令牌自动刷新：刷新失败会明确报错，不会静默降级。
• 不收集任何数据：没有遥测，没有第三方中转。请求只在你、本机代理与 Cloudflare 之间流动。
• 面板永不回显 Token：只显示「已保存 / 未保存」。

⚠️ 切勿把 Token 粘贴到聊天窗口或 Issue。本插件的设计目的之一就是让凭据不经过对话。

---

兼容性

项目	范围
DSH	0.2.x（已验证 0.2.1-rc.2）
profile	web、desktop 均可
平台	Windows / macOS / Linux
Node.js	≥ 22

不依赖任何 @deepseek-ai/* 运行时导入，因此不会被 DSH 的版本闸门拦截， 也不会因为内核升级而失效。唯一的外部依赖是 DSH 自带的 @deepseek-ai/dsh-mcp-client。

---

目录结构

dsh-cloudflare-codemode/
├── package.json          # 包元数据 + dsh.bundle / dsh.client 声明
├── cordis.patch.yml      # 两行：本插件 Host 半 + 官方 MCP 客户端
├── lib/
│   ├── index.js          # Host 半：配置存储、认证代理、设置路由
│   └── client.js         # Client 半：设置面板（纯 __ModuleLoader__，无构建步骤）
├── locale/
│   ├── zh.json           # 中文标题与描述
│   └── en.json           # 英文标题与描述
├── icon.svg
└── LICENSE

---

开发

无需构建步骤。改 lib/client.js 刷新页面即可；改 lib/index.js 需重启宿主。

语法检查：

node --check lib/index.js
node --check lib/client.js

---

相关链接

• Cloudflare Code Mode MCP 文档
• DeepSeek Harness

---

License

MIT

本项目为独立第三方插件，与 Cloudflare, Inc. 及 DeepSeek 均无隶属或背书关系。 使用本插件访问 Cloudflare API 时，你需自行遵守 Cloudflare 的服务条款。