netdisk-organizer-mcp

官方是地基，本 MCP 是二楼。

百度官方已把"碰网盘"做成了标准 MCP 数据层（baidu-netdisk，SSE: https://mcp-pan.baidu.com/sse）。 本项目不重新实现任何网盘协议，只在官方数据层之上叠加三层整理智能：

• 语义层：pan_scan / pan_events / pan_ask —— 事件聚类 + 跨目录认领孤儿照片，补官方 file_keyword_search 答不了"去年暑假度假的照片在哪"的缺口
• 安全层：不提供 delete tool；pan_move 内置 protect_patterns 拦截（珍藏/合同/发票直接拒绝）；journal 自动留痕 + pan_undo 可回滚
• 个性化层：pan_profile + 可移植的 profiles/ 偏好文件，各用户各改各的，互不干扰

---

目录

• 快速开始
• 架构
• 环境要求
• 安装
• 配置
• 工具清单（21 个）
• 个性化
• 安全模型
• 获取 Access Token
• 项目结构
• 开发与测试
• License

---

1. 快速开始

# 1. 安装
git clone <your-repository-url>          # 替换为你的仓库地址
cd netdisk-organizer-mcp
pip install -e .

# 2. 配置 token（见「获取 Access Token」）
export BAIDU_NETDISK_ACCESS_TOKEN="你的AccessToken"
export NETDISK_BACKEND="official"        # 默认值，可省略

# 3. 启动 MCP server（stdio）
python server.py

然后在你的 MCP 客户端（WorkBuddy / Trae / Claude / Cursor 等）里注册连接器，即可开始使用。

---

2. 架构

┌─────────────────────────────────────────────────────────────┐
│  你的 agent（WorkBuddy / Trae / 任何标准 MCP 客户端）          │
└───────────────┬─────────────────────────────────────────────┘
                │  stdio MCP
┌───────────────▼─────────────────────────────────────────────┐
│  netdisk-organizer-mcp  （本仓库 · 二楼 · 整理智能）          │
│   pan_scan/events/ask/stat/issues  ·  pan_move/undo/history  │
│   pan_profile  ·  pan_mkdir/save/quota/semantic              │
└───────────────┬─────────────────────────────────────────────┘
                │  委托（OfficialDataClient / BaiduBackend）
┌───────────────▼─────────────────────────────────────────────┐
│  官方数据层（地基 · 百度维护 · 标准 MCP）                     │
│   file_list / file_move / upload_by_url / get_quota /        │
│   file_semantics_search / make_dir ...                       │
└─────────────────────────────────────────────────────────────┘

边界原则：本仓库只做"整理"，绝不复刻"增删改查"。任何纯数据 I/O 都委托给官方数据层。

模块	职责
server.py	MCP stdio server 入口，工具路由
index.py	语义层：扫描 → 打标 → 事件聚类 → 结构化检索
ops.py	安全层：move / undo / history，journal 留痕
io_ops.py	数据层薄封装：委托官方 file_* 工具
backend.py	后端抽象：OfficialDataClient / BaiduBackend / LocalBackend
profiles/	可移植整理偏好（JSON），加载 + 严格校验

---

3. 环境要求

依赖	版本
Python	≥ 3.12
mcp	≥ 1.0.0
httpx	≥ 0.27.0
anyio	≥ 4.0.0
python-dotenv	≥ 1.0.0

sdk 兜底后端（NETDISK_BACKEND=sdk）额外需要：urllib3 / certifi / six / python-dateutil。

---

4. 安装

git clone <your-repository-url>
cd netdisk-organizer-mcp
pip install -e .          # 或 uv sync
# 若用 sdk 兜底后端（NETDISK_BACKEND=sdk）：
pip install -e ".[sdk]"

---

5. 配置

本 server 是标准 MCP stdio server，mcpServers 的 JSON schema 所有客户端通用 —— 差异只在配置文件存放路径（各客户端约定），不在本项目的分叉。

{
  "mcpServers": {
    "netdisk-organizer": {
      "command": "python",
      "args": ["/absolute/path/to/netdisk-organizer-mcp/server.py"],
      "env": {
        "BAIDU_NETDISK_ACCESS_TOKEN": "你的AccessToken",
        "NETDISK_BACKEND": "official",
        "NETDISK_DATA_MCP_URL": "https://mcp-pan.baidu.com/sse"
      }
    }
  }
}

客户端	配置文件位置
WorkBuddy	设置 → 连接器 → 添加自定义连接器（stdio 模式）
Trae	项目根 .trae/mcp.json 或 ~/.trae/mcp.json
Claude	.mcp.json
Cursor	~/.cursor/mcp.json
其他标准 MCP 客户端	同一段 JSON，仅文件路径不同

若用 uv 管理：把 command 改为 uv，args 改为 ["--directory","/absolute/path/to/netdisk-organizer-mcp","run","python","server.py"]。

环境变量

变量	取值	说明
NETDISK_BACKEND	official（默认）/ sdk	official=连官方数据层；sdk=vendored BaiduBackend 兜底
NETDISK_DATA_MCP_URL	URL	官方数据层端点，默认 https://mcp-pan.baidu.com/sse
BAIDU_NETDISK_ACCESS_TOKEN	token	official 模式必填；个人用户 OAuth 令牌，非应用凭证
NETDISK_SDK_PATH	目录	仅 sdk 模式可指定自定义 SDK 位置
NETDISK_PROFILE	名称/路径	指定整理偏好（见第 7 节），缺省用内置 default

无 token 又传 backend_root → LocalBackend（本地测试 / mock，无需账号）。

---

6. 工具清单（21 个）

语义层（6 · 独有护城河，官方零覆盖）

工具	作用	改写官方
pan_scan	扫描网盘/目录建语义索引（事件聚类+标签传播）	否
pan_scan_status	查看索引状态（已扫文件数/最后扫描时间/覆盖）	否
pan_events	列出识别出的事件（旅行/节日/纪念/集中拍摄）	否
pan_ask	结构化检索（时间窗+类别+标签+关键词）	否
pan_stat	全盘体检报告（类别/来源/风险分级）	否
pan_issues	扫描已索引数据返回发现（孤儿/垃圾/重复/命名混乱/大文件）	否

安全层（3 · 独有护城河）

工具	作用	改写官方
pan_move	移动文件（内置 protect_patterns 拦截）	✅ 包官方 file_move
pan_undo	回滚指定批次的 move（LIFO）	否
pan_history	查看可回滚的操作历史（按批次聚合）	否

个性化层（1 · 独有护城河）

工具	作用	改写官方
pan_profile	读取当前生效的整理偏好（只读）	否

数据层薄封装（11 · 官方对等，零逻辑复刻）

工具	作用	改写官方
pan_mkdir	建整理用目标目录	委托 make_dir
pan_save	转存外链资源进收件箱	委托 upload_by_url
pan_quota	读取容量使用	委托 get_quota
pan_semantic	透传官方语义检索	委托 file_semantics_search
pan_search_keyword	按文件名关键词搜索	委托 file_keyword_search
pan_meta	获取文件详情（按 fs_id，最多 10）	委托 file_meta
pan_upload_text	把一段文本直接写成网盘文件	委托 file_upload_by_content
pan_copy	复制文件（ondup=newcopy 防覆盖）	委托 file_copy
pan_share_link	创建文件分享链接	委托 file_sharelink_set
pan_user	获取已鉴权用户信息（头像/会员/UID）	委托 user_info
pan_del	删除/移入回收站	委托 file_del（⚠️ 见下）

pan_del 使用警示：官方 SSE 数据层未暴露删除（仅 vendored sdk 后端可用），且删除风险系数高。作者立场：不把它作为默认分发能力 —— 清理请走隔离目录 /_待清理_/（profile 的 quarantine_dir）+ 用户手动删除；pan_del 仅保留后端完整性，使用需自担风险，且 pan_undo 不支持回滚删除（回收站无恢复 API）。

官方 16 个数据工具已覆盖 15 个；唯一刻意不提供的是 file_upload_stdio（本地文件直传，web 场景用不到）。

使用示例

用户意图	工具调用
扫描我的网盘	pan_scan
2025年夏季时间段的照片在哪	agent 解析为 {years:[2025], months:[7,8], category:"照片", scene:"旅行"} 调 pan_ask
把截图归档到 /整理后/截图/	pan_move（每个 move 自动写 journal）
刚才那批撤回	pan_undo(batch=...)
转存这个链接	pan_save({url, to_folder})

---

7. 个性化

整理偏好是纯 JSON，放在 profiles/：

• profiles/default.profile.json —— 内置默认（保护规则 + 隔离目录 + 软偏好）
• profiles/schema.json —— JSON Schema，加载时严格校验（配置非法宁可失败，不带病动用户文件）

自定义：复制 default.profile.json 改名，运行时设 NETDISK_PROFILE=我的.profile.json。

可改项：额外 protect_patterns（永不移动的路径/关键词）、never_touch（前缀黑名单）、quarantine_dir（清理隔离区）、preferences（软偏好，如默认按事件聚类）。

内置保护规则不可被 profile 关闭 —— 这是铁律，防止误配把重要文件挪走。

---

8. 安全模型

1. 永不删除：不暴露 delete tool，清理只能 move 到隔离目录
2. move 内置保护：protect_patterns / never_touch 命中直接拒绝（珍藏/纪念/毕业/合同/发票/身份证/微信备份…）
3. journal 自动留痕：每次 move 记录，undo 一键回滚（LIFO）
4. 凭证不入库：token 走 env / .env（.gitignore 屏蔽），绝不提交
5. 防提示注入：不提供读取文件内容的工具，文件名当不可信数据

---

9. 获取 Access Token

MCP 配置里要的是**「用户」令牌**（代表某百度账号授权访问其网盘），不是开放平台的「应用」凭证（AppKey/SecretKey 不能直接当 token 用）。 个人使用：用你自己的 AppKey + SecretKey 走一次 OAuth，把你自己的网盘授权给应用。

pip install requests
python tools/get_baidu_token.py --app-key 你的AppKey --app-secret 你的SecretKey
# 打开打印的验证 URL，登录百度账号授权 → 脚本自动拿到 access_token / refresh_token

token 约 30 天有效；过期用 --refresh 续期。（个人应用最多授权 10 个账号，自用绰绰有余。）

⚠️ 脚本会在终端打印 access_token / refresh_token。请勿把终端输出截图发给他人，token 等同于你的网盘访问权限。

---

10. 项目结构

netdisk-organizer-mcp/
├── server.py                 # MCP stdio server 入口，工具路由
├── index.py                  # 语义层：扫描/事件聚类/检索/体检
├── ops.py                    # 安全层：move/undo/history + journal
├── io_ops.py                 # 数据层薄封装（委托官方）
├── backend.py                # 后端抽象（Official/Baidu/Local）
├── tools/
│   └── get_baidu_token.py    # OAuth 设备码取 token 脚本
├── profiles/
│   ├── __init__.py           # profile 加载器 + 严格校验
│   ├── default.profile.json  # 内置默认偏好
│   └── schema.json           # JSON Schema
├── openapi_client/           # vendored 官方 SDK（sdk 兜底模式用）
├── pyproject.toml
├── .env.example              # 环境变量模板
└── .gitignore

---

11. 开发与测试

pip install -e ".[dev]"
python -m pytest -q

说明：当前分享版为精简裁剪，未包含测试套件与 CI 配置。若需完整开发环境，请基于 backend.py 的 FakeDataClient 注入点自行补充单元测试（可离线验证代理逻辑，无需真实 token / 网络）。

---

12. License

MIT