🌊 Cloudflare Workspace MCP

🌐 English | 中文

一句话：让手机上的 AI 助手拥有真实的命令行工作区，并直接管理你的 Cloudflare 账户（Pages / D1 / KV / R2）。

<div align="center">

</div>

---

这是干什么的？

让手机上的 AI 助手能真正"动手干活"。

普通的 MCP 服务器只给 AI 几个固定函数（查天气、发邮件之类）。这个项目给 AI 的是一个真实的命令行工作区，外加 Cloudflare 账户管理能力。

主要面向安卓端的 AI 助手（RikkaHub、Coomi 等）。在电脑上，AI 助手通常能直接调用本机终端，不太需要这个项目；但在 Android 上 AI 没有独立运行环境，本项目用 proot 沙箱补上——给手机里的 AI 一个完整的 Debian 环境。

场景	说明
让 AI 写代码并运行	手机上让 AI 自己 clone 项目、装依赖、跑命令、看输出
部署到 Cloudflare	手机上让 AI 直接执行 wrangler deploy，真实部署
管理 Cloudflare 资源	一句话让 AI 查 Pages / D1 / KV / R2，不用登录控制台
查/改手机上的文件	AI 在工作区内读写文件，路径限制在工作区内

---

🚀 30 秒上手（手机 + AI，全自动）

只需要 3 步：

步骤	操作
1	下载本项目 ZIP（GitHub 页面 → Code → Download ZIP）
2	把 ZIP 丢给手机上的 AI 助手（RikkaHub / Coomi 等），粘贴下面这句提示词：
3	等 AI 装完，把 .env 里的 Cloudflare 凭据填上（AI 会告诉你怎么填），直接开用

📋 复制这段提示词给 AI

请把 cloudflare-workspace-mcp.zip 解压到当前工作区，然后运行 bash install.sh。
如果安装中遇到问题，根据报错自动修复后重试，直到 install.sh 自检全部通过。
完成后告诉我：
1. MCP 客户端配置方法（run.sh 的绝对路径）
2. 需要我手动填写的 Cloudflare 凭据（.env 文件路径和获取地址）
全程自动执行，不要让我手动操作。

🤖 AI 会自动做什么？

步骤	AI 做的事
1	解压 ZIP 到工作区
2	运行 install.sh：装 Node 依赖，生成 run.sh 和工作区 .env 模板（wrangler 可选，仅 cloudflare_deploy 需要）
3	自检所有依赖，缺什么当场补装
4	输出 MCP 配置 + 提示你填凭据

💡 你唯一要手动做的：在 .env 里填 Cloudflare API Token 和 Account ID（这是你的私有密钥，AI 无法替你生成）。install.sh 会提前创建好模板，不会等你用到 Cloudflare 功能才发现环境不完整。

---

手动安装（不想用 AI？）

# 1. 解压后进入目录，一键安装（自动装依赖 + 生成 run.sh + .env 模板 + 自检）
bash install.sh

# 2. 编辑工作区 .env 填入凭据
#    ~/workspace/.env

# 3. 把 run.sh 接入 MCP 客户端

MCP 客户端配置（mcpServers 里加一条）：

{
  "mcpServers": {
    "cf-workspace": {
      "command": "/绝对路径/cloudflare-workspace-mcp/run.sh",
      "type": "stdio"
    }
  }
}

---

和别的 MCP 有什么不一样？

对比项	本项目	官方 Cloudflare MCP	社区远程 Workers MCP
本地 shell 工作区	✅ 有（local / proot 双后端）	❌	❌
Android 支持（无 root）	✅ proot 沙箱	❌	❌
Cloudflare 管理	✅ Pages / D1 / KV / R2	✅	✅
凭据在哪	🔒 本机 .env，不出设备	远程服务	远程服务
可扩展性	完整 shell，想装什么装什么	只有预置函数	只有预置函数
部署方式	本地 wrangler CLI + REST API，真环境	远程 API	远程 API

核心区别：别的项目给 AI 的是"专用工具包"，这个项目给 AI 的是"整间办公室"——而且是本地的，凭据不出设备。

---

Android / proot 后端

在 Android（Termux / RikkaHub 等）上，无需 root 即可获得完整 Debian 环境：

# 1. 准备 proot 二进制（来自 Termux 的 proot 或 RikkaHub 内置）：
#    libproot_exec.so + libproot_loader.so → ~/proot-bin/
# 2. 准备 Debian rootfs（约 1GB）→ ~/debian-fs/
# 3. install.sh 自动检测：存在 proot 则用 proot 后端；否则用 local

CFMCP_BACKEND 取值：

值	行为
auto（默认）	已运行在沙箱内（如 RikkaHub 工作区即 rootfs）→ 自动用 local，避免沙箱嵌套；否则检测到 proot 二进制则用 proot
local	直接本机 shell
proot	强制 proot 沙箱

RikkaHub 用户注意：RikkaHub 的工作区本身就是 rootfs（已处于沙箱内），不要再套一层 proot——auto 会自动检测并回落 local。启动日志打印 inSandbox=true/false 供排查。

依赖说明：cloudflare_api / cloudflare_status / d1_query 是纯 REST（宿主 Node 原生 fetch），不需要 wrangler；只有 cloudflare_deploy 需要 wrangler（npm install -g wrangler）。

---

工具

工具	说明
execute_command	在工作区执行任意 shell 命令（command / cwd / timeout）
read_file	读取工作区文件（UTF-8）
write_file	写入/覆盖工作区文件（自动建目录）
list_files	列出工作区目录内容
cloudflare_api	Cloudflare REST API 通用网关：任意 method/path/body 直通全部权限（自动注入 token / {account_id}），常用路径见 CF_API.md
cloudflare_status	只读资源清单：Pages / D1 / KV / R2 / Zones / Workers，type 可选（纯 REST，无需 wrangler）
d1_query	对 D1 执行只读 SQL（仅 SELECT，纯 REST，无需 wrangler/jq；database 参数默认取 CFMCP_D1_DB）
cloudflare_deploy	部署到 Pages：project/branch/src_dir/build_cmd 全参数化；不传参数且工作区有 CFMCP_DEPLOY_SCRIPT 时优先执行脚本（需 wrangler）

---

环境变量

变量	必填	默认	说明
CFMCP_WORKSPACE	✅	—	工作区目录（映射为 /workspace）
CFMCP_BACKEND		auto	local / proot / auto
CFMCP_HOME		$HOME	proot 二进制/rootfs 所在目录
CFMCP_D1_DB		—	D1 数据库名（d1_query 的 database 默认值）
CFMCP_PAGES_PROJECT		—	Pages 项目名（cloudflare_deploy 的 project 默认值）
CFMCP_DEPLOY_SRC		.	部署源目录（相对工作区，cloudflare_deploy 的 src_dir 默认值）
CFMCP_DEPLOY_SCRIPT		deploy.sh	部署脚本（相对工作区，无显式参数时优先执行）
CFMCP_ENV_FILE		$CFMCP_WORKSPACE/.env	Cloudflare 凭据文件

---

安全说明

• 凭据：CLOUDFLARE_API_TOKEN / CLOUDFLARE_ACCOUNT_ID 仅从工作区 .env 读取，注入命令环境，绝不写入仓库或输出。
• 路径防护：read_file / write_file 拒绝解析到工作区之外的路径。
• 只读 SQL：d1_query 强制 SELECT 前缀。
• 部署授权：cloudflare_deploy 动线上，建议在 MCP 客户端层要求用户确认。
• 危险操作：execute_command 是完整 shell，AI 可能执行任何命令——请只对可信的 AI 暴露此服务器。

---

开发

npm test        # 语法检查
# CI（GitHub Actions）：全新 Ubuntu 环境自动跑「install.sh 一键安装 → 启动 → 工具清单 → 执行命令」验证

---

License

MIT