Metadata-Version: 2.4
Name: wb-clouddocs-mcp
Version: 1.2.0
Summary: 云文档协作连接器（云端层对接开放平台：云文档/云空间/多维表格，含本地免密钥文档生成）
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.2.0
Requires-Dist: requests
Requires-Dist: python-docx
Requires-Dist: python-pptx
Requires-Dist: openpyxl
Requires-Dist: Pillow

# 云文档协作助手 —— 在线云文档协作与本地文档生成

**开发者：牛魔科技工作室**

面向在线云文档的协作连接器。云端层对接**开放平台**（免费、应用身份零交互），
用自然语言创建、编辑、搜索、协作在线文档（云文档 / 云空间文件 / 多维表格），
同时保留**本地免密钥生成**（DOCX/PPTX/思维导图/流程图/OCR）。

## 能力矩阵

| 能力 | 工具 | 是否需要 Key |
|------|------|--------------|
| 创建云文档 | `cdoc_file_create` | 需要 |
| 读取/搜索/下载/上传云空间 | `cdoc_file_content` / `cdoc_file_search` / `cdoc_file_download` / `cdoc_file_upload` | 需要 |
| 多维表格 | `cdoc_dbt_*` | 需要 |
| 权限 / 分享 / 消息 | `cdoc_file_permission` / `cdoc_notification_send` | 需要 |
| 本地免密钥生成 | `cdoc_local_*` / `cdoc_ocr_*` | **无需** |

> **云端未提供等效 REST 接口的能力（调用会明确报错，不会静默失败）**：
> 回收站列举/恢复/彻底删除、文档版本历史、收集表创建/答卷、格式转换(doc→pdf 等)、
> 多维表 Webhook 管理、空间配额、传统电子表格单元格精细写入。
> 这些请在网页/客户端完成，或改用本地生成能力。

## 首次配置（仅云端能力需要）

> 本连接器云端层对接开放平台，需自建应用获取凭证（注册入口见连接器配置页的帮助链接）。

1. 从连接器配置页的帮助链接进入开放平台开发者后台，登录后点击「创建应用 → 企业自建应用」
   （个人用户可在创建时顺手建一个属于自己的免费「企业/组织」，无需营业执照）；
2. 进入应用「凭证与基础信息」，复制 **App ID**（cli_ 开头）与 **App Secret**；
3. 在「权限管理」勾选所需权限（云文档/云空间/多维表类，如
   `docx:document:readonly`、`drive:drive:readonly`、`drive:file`、`bitable:app`、`bitable:app:readonly` 等）；
   **部分权限需在「版本管理与发布」创建版本并申请发布后生效**（在自建的测试企业内通常免审）；
4. 将 `config.example.json` 复制为连接器根目录的 `config.json`，填入真实值：

```json
{
  "appName": "clouddocs",
  "appId": "你的开放平台 App ID（cli_ 开头）",
  "appSecret": "你的开放平台 App Secret",
  "folderToken": "（可选）云端上传目标文件夹 token",
  "environment": "production"
}
```

鉴权说明：采用 `tenant_access_token` 应用身份，连接器用 `App ID`+`App Secret` 直接换取，
**无需浏览器回调/OAuth 跳转**，沙箱/审核环境填好这对密钥即可零交互调用。

也可通过环境变量 `CLOUDDOCS_CONFIG` 指定 config 路径。缺少 config 时，云端工具会返回中文指引，本地免密钥工具仍可正常使用。

## 运行

由 WorkBuddy 按 `mcp.json` 自动拉起：

```bash
python -m engine.api_mcp_server --config ./config.json
```

## 本地增强（可选）

本连接器已内置本地生成能力（DOCX/PPTX/OCR），零密钥可用。

## 安全

- Token 仅存内存，不落盘；明文 App Secret 只来自本地 config.json，绝不进入源码
- 429 限流自动指数退避重试（最多 5 次）
- 默认拦截 `.exe/.bat/.ps1/.zip` 等上传类型
- 按本机 CPU/内存自动分配并发，不拖累电脑

## 反馈

有更好建议：njskills@agent.qq.com
