介绍
# Dropbox Manager Skill
通过 MCP 服务器和 CLI 管理 Dropbox 文件。使用 SwiftyDropbox SDK 的 Swift 原生实现，支持 OAuth 2.0 PKCE 和安全的 Keychain 令牌存储。
## 设置
### 先决条件
```bash # Clone and build Dropbook git clone https://github.com/RyanLisse/Dropbook.git cd Dropbook make build ```
### 身份验证
#### 选项 1：使用 Keychain 的 OAuth 登录（推荐）
使用具有安全 Keychain 存储的交互式 OAuth 流程：
```bash export DROPBOX_APP_KEY="your_dropbox_app_key" export DROPBOX_APP_SECRET="your_dropbox_app_secret" make login # or: swift run dropbook login ```
这将执行以下操作： 1. 生成 PKCE 代码验证器和质询（SHA256, RFC 7636） 2. 打开带有状态参数（CSRF 保护）的授权 URL 3. 提示您粘贴授权码 4. 交换代码以获取访问令牌和刷新令牌 5. **将令牌保存到 macOS Keychain**（硬件支持的加密） 6. 如果 Keychain 不可用，则回退到 `~/.dropbook/auth.json` 7. 启用自动令牌刷新
**安全功能（符合 RFC 9700 标准）：** - 使用 S256 质询方法的 PKCE - 用于 CSRF 保护的状态参数 - 使用 `kSecAttrAccessibleWhenUnlocked` 的 Keychain 存储 - 用于加密操作的 CryptoKit
#### 选项 2：环境变量（旧版）
```bash export DROPBOX_APP_KEY="your_dropbox_app_key" export DROPBOX_APP_SECRET="your_dropbox_app_secret" export DROPBOX_ACCESS_TOKEN="your_dropbox_access_token" ```
**注意**：手动令牌不支持自动刷新。请在生产环境中使用 OAuth 登录。
### 注销
从 Keychain 和文件存储中清除存储的令牌：
```bash make logout # or: swift run dropbook logout ```
## MCP 服务器（推荐）
启动 MCP 服务器：
```bash make mcp # or: ./.build/debug/dropbook mcp ```
### MCP 工具
| 工具 | 描述 | |------|-------------| | `list_directory` | 列出 Dropbox 目录中的文件和文件夹 | | `search` | 按名称或内容搜索文件 | | `upload` | 将文件上传到 Dropbox | | `download` | 从 Dropbox 下载文件 | | `delete` | 删除文件或文件夹（移至废纸篓） | | `get_account_info` | 获取帐户名称和电子邮件 | | `read_file` | 读取文本文件的内容 |
#### list_directory
列出 Dropbox 目录中的文件和文件夹。
**参数：** - `path`（字符串，可选）：目录路径。默认值："/"
**响应：** ```json { "files": [ {"type": "file", "name": "doc.pdf", "path": "/Docs/doc.pdf", "size": 1024}, {"type": "folder", "name": "Projects", "path": "/Projects"} ] } ```
#### search
按名称或内容搜索文件。
**参数：** - `query`（字符串，必填）：搜索词 - `path`（字符串，可选）：搜索范围路径。默认值："/"
**响应：** ```json { "count": 2, "results": [ {"matchType": "filename", "metadata": {"name": "report.pdf", "path": "/Docs/report.pdf"}} ] } ```
#### upload
将文件上传到 Dropbox。
**参数：** - `localPath`（字符串，必填）：本地文件的绝对路径 - `remotePath`（字符串，必填）：Dropbox 中的目标路径 - `overwrite`（布尔值，可选）：如果存在则替换。默认值：false
**响应：** ```json { "uploaded": true, "name": "file.txt", "path": "/Uploads/file.txt", "size": 5000 } ```
#### download
从 Dropbox 下载文件。
**参数：** - `remotePath`（字符串，必填）：Dropbox 中的文件路径 - `localPath`（字符串，必填）：本地目标路径
**响应：** ```json { "downloaded": true, "to": "/tmp/report.pdf" } ```
#### delete
从 Dropbox 删除文件或文件夹（移至废纸篓）。
**参数：** - `path`（字符串，必填）：Dropbox 中要删除的路径
**响应：** ```json { "deleted": true, "path": "/Docs/old-file.pdf" } ```
#### get_account_info
获取 Dropbox 帐户信息。
**参数：** 无
**响应：** ```json { "name": "Ryan Lisse", "email": "[email protected]" } ```
#### read_file
读取并返回 Dropbox 中文本文件的内容。
**参数：** - `path`（字符串，必填）：Dropbox 中的文件路径
**响应：** 以文本形式返回文件内容。仅适用于 UTF-8 编码的文本文件。
## CLI 命令
```bash # Authentication make login # OAuth login with Keychain storage make logout # Clear stored tokens
# File operations make list # List root directory swift run dropbook list /path
# Search files swift run dropbook search "query" [path]
# Upload file swift run dropbook upload /local/path /remote/path [--overwrite]
# Download file swift run dropbook download /remote/path /local/path
# Start MCP server make mcp ```
## MCP 客户端配置
### Claude Code（项目级）
项目包含一个配置 MCP 服务器的 `.mcp.json` 文件：
```json { "mcpServers": { "dropbox": { "command": "/path/to/Dropbook/.build/debug/dropbook", "args": ["mcp"], "env": { "DROPBOX_APP_KEY": "${DROPBOX_APP_KEY}", "DROPBOX_APP_SECRET": "${DROPBOX_APP_SECRET}" } } } } ```
在 Claude Code settings.json 中启用项目 MCP 服务器： ```json { "enableAllProjectMcpServers": true } ```
### Claude Desktop
```json { "mcpServers": { "dropbox": { "command": "/path/to/dropbook/.build/debug/dropbook", "args": ["mcp"], "env": { "DROPBOX_APP_KEY": "${DROPBOX_APP_KEY}", "DROPBOX_APP_SECRET": "${DROPBOX_APP_SECRET}" } } } } ```
## 错误处理
| 错误 | 原因 | 解决方案 | |-------|-------|----------| | `notConfigured` | 缺少环境变量 | 设置 DROPBOX_APP_KEY, DROPBOX_APP_SECRET | | `invalidArguments` | 缺少必填参数 | 检查工具参数 | | `notFound` | 路径不存在 | 使用 `list_directory` 验证路径 | | `itemNotFound` | Keychain 中没有令牌 | 运行 `make login` 进行身份验证 |
## 架构
``` Dropbook/ ├── Sources/ │ ├── DropbookCore/ # Business logic (actor-based) │ │ ├── Auth/ # Keychain & file token storage │ │ ├── Config/ # Configuration management │ │ ├── Models/ # Domain models │ │ └── Services/ # DropboxService actor │ ├── DropbookCLI/ # CLI adapter │ │ └── Commands/ # Login, logout, file commands │ └── DropbookMCP/ # MCP server ├── dropbox-skill/ # Skill documentation ├── Makefile # Build automation ├── .mcp.json # MCP server configuration └── Package.swift ```
## 使用 rclone 进行批量操作
对于大规模操作（如备份、同步或批量传输），请使用 [rclone](https://rclone.org/) - 一个具有原生 Dropbox 支持的强大云同步工具。
### 安装 rclone
```bash brew install rclone ```
### 配置 rclone for Dropbox
```bash # Interactive setup (opens browser for OAuth) rclone authorize dropbox
# Save the token output to config mkdir -p ~/.config/rclone cat > ~/.config/rclone/rclone.conf << 'EOF' [dropbox] type = dropbox token = {"access_token":"...paste token here..."} EOF ```
### 备份到网络驱动器 / Time Capsule
```bash # Full backup with progress rclone copy dropbox: /Volumes/TimeCapsule/Dropbox-Backup \ --progress \ --transfers 4 \ --checkers 8 \ --retries 10 \ --log-file /tmp/dropbox-backup.log
# Sync (mirror - deletes files not in source) rclone sync dropbox: /Volumes/Backup/Dropbox --progress
# Check what would be copied (dry run) rclone copy dropbox: /Volumes/Backup --dry-run ```
### 常用 rclone 命令
```bash # List remote contents rclone lsd dropbox: # List directories rclone ls dropbox: # List all files rclone size dropbox: # Calculate total size
# Copy operations rclone copy dropbox:folder /local/path # Download folder rclone copy /local/path dropbox:folder # Upload folder
# Sync (bidirectional) rclone bisync dropbox: /local/path --resync
# Mount as filesystem (macOS - requires macFUSE) rclone mount dropbox: /mnt/dropbox --vfs-cache-mode full ```
### rclone 可靠性标志
| 标志 | 描述 | |------|-------------| | `--progress` | 显示实时传输进度 | | `--transfers 4` | 并行传输数量 | | `--checkers 8` | 并行检查器数量 | | `--retries 10` | 重试失败的操作 | | `--low-level-retries 20` | 重试低级错误 | | `--log-file path` | 将日志写入文件 | | `--dry-run` | 显示将要执行的操作 | | `--checksum` | 使用校验和验证 |
### 速率限制
Dropbox 有严格的 API 速率限制。如果您看到 `too_many_requests` 错误：
```bash # Use bandwidth limiting rclone copy dropbox: /backup --bwlimit 1M
# Or add delays between operations rclone copy dropbox: /backup --tpslimit 2 ```
rclone 会通过指数退避自动处理速率限制。
## 最佳实践
1. **使用 OAuth 登录** - 具有自动令牌刷新的安全 Keychain 存储 2. **对代理使用 MCP** - 编程访问更可靠 3. **对批量操作使用 rclone** - 更适合备份和大型传输 4. **先验证路径** - 在操作之前使用 `list_directory` 5. **优雅地处理错误** - 检查响应中的错误字段 6. **遵守速率限制** - 在批量操作之间添加延迟 7. **使用绝对路径** - 始终为文件操作提供完整路径
## 安全性
- **Keychain 存储**：使用硬件支持的加密存储令牌 - **PKCE**：代码交换证明密钥可防止授权码拦截 - **状态参数**：OAuth 流程的 CSRF 保护 - **令牌刷新**：在过期前自动刷新 - **CryptoKit**：现代 Swift 加密库
## 依赖项
- **SwiftyDropbox** (v10.2.4+)：官方 Dropbox Swift SDK - **MCP (swift-sdk)**：模型上下文协议 SDK - **CryptoKit**：Apple 加密框架 - **rclone**（可选）：用于批量操作和备份（`brew install rclone`）
## 另请参阅
- [Dropbook GitHub](https://github.com/RyanLisse/Dropbook) - [CLAUDE.md](../CLAUDE.md) - 完整项目文档 - [Dropbox API 文档](https://www.dropbox.com/developers/documentation) - [rclone Dropbox 文档](https://rclone.org/dropbox/) - 批量同步和备份 - [RFC 7636 - PKCE](https://datatracker.ietf.org/doc/html/rfc7636) - [RFC 9700 - OAuth 2.0 安全最佳实践](https://datatracker.ietf.org/doc/html/rfc9700)