Metadata-Version: 2.4
Name: wb-kingdoc-mcp
Version: 1.0.4
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）。

> 为什么是飞书：金山 WPS 365 云文档接口需商业高级版付费、个人金山文档开放平台已停维，
> 故云端层改为飞书（免费 + 自建应用免费注册 + `tenant_access_token` 应用身份与现有架构天然匹配）。

## 能力矩阵

| 能力 | 工具 | 是否需要 Key |
|------|------|--------------|
| 创建云文档 | `kdoc_file_create` | 需要（飞书） |
| 读取/搜索/下载/上传云空间 | `kdoc_file_content` / `kdoc_file_search` / `kdoc_file_download` / `kdoc_file_upload` | 需要 |
| 多维表格 | `kdoc_dbt_*` | 需要 |
| 权限 / 分享 / 消息 | `kdoc_file_permission` / `kdoc_notification_send` | 需要 |
| 本地免密钥生成 | `kdoc_local_*` / `kdoc_ocr_*` | **无需** |

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

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

> 本连接器对接 **飞书开放平台**（`open.feishu.cn`）。

1. 打开 [飞书开放平台](https://open.feishu.cn/app)，用飞书账号登录；
   点击「创建应用 → 企业自建应用」（个人用户可在创建时顺手建一个属于自己的免费「企业/组织」，无需营业执照）。
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": "kingdoc",
  "appId": "你的飞书 App ID（cli_ 开头）",
  "appSecret": "你的飞书 App Secret",
  "folderToken": "可选：默认父目录 token（fldcn...）",
  "environment": "production"
}
```

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

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

## 运行

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

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

## 本地增强（可选）

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

## 安全

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

## 反馈

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