# 🌊 Cloudflare Workspace MCP

[🌐 English](README.en.md) | [中文](README.md)

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

<div align="center">

![MCP](https://img.shields.io/badge/MCP-Server-blue) ![Node](https://img.shields.io/badge/Node-%3E%3D18-green) ![Android](https://img.shields.io/badge/Android-proot%20sandbox-orange) ![License](https://img.shields.io/badge/License-MIT-lightgrey)

</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？）

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

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

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

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

```json
{
  "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 环境：

```bash
# 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 暴露此服务器。

---

## 开发

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

---

## License

MIT