# WPS 云文档 · Claude 连接器

让 Claude 直接使用你的**个人 WPS 云文档（金山文档）**。在对话里说一句"帮我写一份实验报告存到 WPS"，Claude 就会创建文档并把在线链接给你。体验和 Google 文档连接器一样：**授权一次，之后直接用**。

- **云端运行**：不需要安装本地 WPS，电脑关机也能用。网页版、桌面版、手机版 Claude 都能用。
- **只需授权**：添加连接器 → 点"允许" → 微信扫码登录 WPS → 完成。不用复制任何令牌，也不用自己部署服务。
- **能力完整**：常用操作（搜、读、建文档、表格、演示，读写单元格，替换文字）有专门工具；WPS 云端的全部 619 项能力（多维表格、表单、批注、页眉页脚、图表、透视表、AI PPT、PDF 转换……）都能通过"查找能力 → 看参数 → 执行"调用。
- **安全**：删除、分享、改权限、发布、全量覆盖、可能消耗会员额度的操作，必须先得到你的明确同意；只读操作 Claude 可以直接执行，写入时才询问。每位用户只能访问自己授权的 WPS 账号。

> 独立社区开源项目，与 WPS / 金山办公、Anthropic 均无关联，也未获其背书。

---

## 一、快速开始（推荐）：添加自定义连接器

适用于 **Claude 网页版、桌面版和手机版**，所有套餐（含免费版，免费版最多添加 1 个自定义连接器）。

**连接地址（复制这一行）：**

```
https://wps-cloud-bridge-for-claude.144-511.workers.dev/mcp
```

**步骤：**

1. 打开 [claude.ai](https://claude.ai)，进入 **设置 → 连接器**（Settings → Connectors）。
2. 点击 **添加自定义连接器**（Add custom connector）。
3. 名称填 `WPS 云文档`，远程 MCP 服务器 URL 填上面的地址，点 **添加**。高级设置留空即可。
4. 在连接器列表里点 **连接**（Connect），浏览器会打开授权页：
   - 第 1 步：确认授权去向是 `claude.ai`，点 **允许并登录 WPS**。
   - 第 2 步：点 **打开 WPS 登录授权**，用 **WPS 个人账号**登录（支持微信扫码、QQ、手机号），确认授权。
   - 登录完成后页面会自动返回 Claude，连接器显示"已连接"。
5. 在对话里开启这个连接器，直接提需求即可，例如：
   - "列出我最近的 WPS 文档"
   - "根据这次对话写一份周报，存成 WPS 文档并给我链接"
   - "新建一个表格，记录频率和幅值，最后一行用公式求和"
   - "把这份大纲做成 PPT 存到 WPS"

手机端：在网页版添加并连接后，手机 App 会自动同步，无需再次操作。

> **团队 / 企业套餐**：需要组织 Owner 先在 **组织设置 → 连接器** 中添加，成员再各自点"连接"授权自己的 WPS 账号。
>
> **企业 WPS 账号暂不支持**：WPS 的个人云文档授权只开放给个人账号。

### 常见问题

- **在连接器里搜不到？** 连接器目录里只列出经过 Anthropic 审核的连接器，本项目尚未上架（见下文第三节），请用上面的"添加自定义连接器"方式。
- **授权页里 WPS 登录在同一个标签打开了？** 登录完成后点浏览器"返回"，回到"第 2 步"页面，会自动继续。
- **需要多久重新授权一次？** WPS 授权有效期约 1 年；失效时 Claude 会自动提示重新连接。
- **怎么断开？** 在 Claude 里说"断开 WPS 连接"（会调用 `wps_disconnect` 吊销授权），或在连接器设置里移除。
- **刚修改的文档读出来还是旧内容？** 修改在在线文档里是实时生效的；读取接口读的是已保存版本，可能晚几分钟同步。

---

## 二、插件市场安装（Claude Code / Claude 桌面版"从仓库添加"）

1. 在 Claude 桌面版的插件市场选择 **添加市场 → 从仓库添加**，填：

   ```
   lisir332-ctrl/wps-cloud-bridge-for-claude
   ```

2. 安装 `wps-cloud` 插件。插件包含两部分：连接上面云端服务的配置，以及一份教 Claude 正确选择工具的使用指南。
3. 首次使用时 Claude 会提示 `wps-cloud` 需要授权，点击后完成与第一节相同的授权步骤。

命令行方式：

```bash
claude plugin marketplace add lisir332-ctrl/wps-cloud-bridge-for-claude
```

```bash
claude plugin install wps-cloud@wps-cloud-for-claude
```

只想加连接、不装插件也可以：

```bash
claude mcp add --transport http wps-cloud https://wps-cloud-bridge-for-claude.144-511.workers.dev/mcp
```

---

## 三、官方连接器目录（上架后可直接搜索使用）

**当前状态：尚未上架。** 上架后，用户可以在 claude.ai 的 **Customize → Connectors** 中直接搜索"WPS"并一键连接，不再需要手动填地址。

按 Anthropic 2026 年的目录规则，本项目的准备情况如下：

| 要求 | 状态 |
| --- | --- |
| 远程 HTTPS MCP、OAuth 2.1（PKCE S256、动态注册与 CIMD）、回调 `https://claude.ai/api/mcp/auth_callback`、未授权返回 401 | ✅ 已满足并测试 |
| 每个工具有 `title` 和 `readOnlyHint` / `destructiveHint` | ✅ 已满足 |
| 不得提供"可执行任意方法名"的通用工具 | ✅ 审核版开关 `DIRECTORY_MODE=1` 只保留 15 个逐项定义的工具 |
| 隐私政策、文档、支持联系方式、测试账号 | 🟡 隐私页已有（`/privacy`），其余提交时准备 |
| 调用的必须是**自有 API 或获授权代理的 API** | ❌ **主要障碍**：本项目调用的是金山办公的 WPS 服务，需要先取得金山办公的授权 |

**完整说明见 [docs/DIRECTORY.md](docs/DIRECTORY.md)**：包括提交入口、材料清单、审核标准，以及取得授权后的上架步骤。如果你是金山办公的相关负责人，或者愿意推动官方合作，欢迎在 Issues 中联系。

---

## 工具一览

| 工具 | 作用 | 类型 |
| --- | --- | --- |
| `wps_connection_check` | 检查连接是否可用 | 只读 |
| `wps_list_files` / `wps_search_files` / `wps_recent_files` | 浏览、搜索、最近文档 | 只读 |
| `wps_get_file` | 文件信息与在线链接 | 只读 |
| `wps_read_document` | 读取正文（Markdown / 纯文本，可分段） | 只读 |
| `wps_sheet_info` / `wps_sheet_read` | 工作表列表、读取单元格（含公式计算结果） | 只读 |
| `wps_create_document` | Markdown → docx / 智能文档 / md / pdf | 新建 |
| `wps_create_spreadsheet` | 二维数据（支持公式）→ xlsx / 智能表格 | 新建 |
| `wps_create_presentation` | 大纲 → 16:9 演示文稿（封面、多级要点、备注） | 新建 |
| `wps_create_folder` | 新建文件夹 | 新建 |
| `wps_sheet_write` | 写入单元格（覆盖目标区域） | 修改 |
| `wps_doc_replace` | 文档查找替换，并用实时搜索核验 | 修改 |
| `wps_find_tools` / `wps_describe_tool` | 在 619 项能力中查找、查看参数 | 只读 |
| `wps_run_read_tool` / `wps_run_write_tool` | 执行任意只读 / 写入能力（敏感操作需确认） | 只读 / 修改 |
| `wps_disconnect` | 吊销授权 | 修改 |

## 测试情况（2026-10-23）

| 测试 | 结果 |
| --- | --- |
| 本地端到端（模拟上游，官方 MCP Python SDK 的 OAuth 客户端） | 50/50 |
| 重新授权、令牌失效、审核版工具集 | 9/9 |
| 线上冒烟测试（真实部署） | 9/9 |
| **真实 WPS 个人账号** | 授权、刷新、列目录、搜索、读文档、新建文件夹/文字/表格/演示、公式计算读回、写入单元格、文档替换（实时核验）、能力查找、敏感操作拦截全部通过 |

真实账号测试中发现并修复的问题：WPS 返回结果多包一层 `{code,data}`；工作表编号字段为 `sheetId`；在线编辑实时生效但读取接口有几分钟延迟；新建文档后几秒内在线服务尚未就绪。

## 工作原理

```
Claude ──OAuth 2.1（PKCE、动态注册）──▶ 本连接器 /authorize ──▶ WPS 官方授权页（用户登录）
   │                                           │ 轮询换取 WPS 令牌，并读根目录核验账号
   │◀──────────── 访问令牌（1 小时）+ 刷新令牌 ─┘
   └──MCP /mcp（Bearer）──▶ 本连接器 ──Bearer WPS 令牌──▶ WPS SkillHub MCP（mcp-center.wps.cn）
```

- WPS 不提供 Claude 连接器所需的标准 OAuth 发现（实测 `/.well-known/oauth-*` 均为 404），所以需要这个"桥"：对 Claude 讲标准 OAuth，对 WPS 用它的个人授权方式。
- WPS 令牌保存在 OAuth 授权数据里，用只有持有访问令牌的一方才能派生出的密钥加密（`@cloudflare/workers-oauth-provider`）。服务端只存密文和哈希，没有数据库。
- WPS 令牌失效时，连接器吊销自己的授权并返回 401，Claude 会提示重新连接。
- 协议细节与核实记录见 [docs/PROTOCOL.md](docs/PROTOCOL.md)。

## 自己部署一份（可选）

想用自己的服务地址？需要 Node.js 22+ 和一个免费的 Cloudflare 账号：

```bash
npm install
```

```bash
powershell -ExecutionPolicy Bypass -File scripts/deploy.ps1
```

脚本会让你登录 Cloudflare，然后自动创建存储、部署、设置地址、写入插件配置并做冒烟测试。详见 [docs/DEPLOY.md](docs/DEPLOY.md)。

## 开发与测试

```bash
npm run typecheck
```

```bash
powershell -ExecutionPolicy Bypass -File scripts/local-test.ps1
```

```bash
python tests/prod_smoke.py https://你的地址
```

## 许可

MIT