Dropbox 管理器技能

通过 MCP 服务器和 CLI 管理 Dropbox 文件。使用 SwiftyDropbox SDK 的 Swift 原生实现，支持 OAuth 2.0 PKCE 和安全密钥链令牌存储。

设置

先决条件

# 克隆并构建 Dropbook
git clone https://github.com/RyanLisse/Dropbook.git
cd Dropbook
make build

身份验证

选项 1：使用密钥链进行 OAuth 登录（推荐）

使用交互式 OAuth 流程和安全密钥链存储：

export DROPBOX_APP_KEY="你的_dropbox_应用密钥"
export DROPBOX_APP_SECRET="你的_dropbox_应用密钥"
make login
# 或者: swift run dropbook login

此操作将：
1. 生成 PKCE 代码验证器和质询（SHA256，RFC 7636）
2. 打开带有状态参数（CSRF 保护）的授权 URL
3. 提示您粘贴授权码
4. 将代码交换为访问令牌和刷新令牌
5. 将令牌保存到 macOS 密钥链（硬件加密支持）
6. 如果密钥链不可用，则回退到 ~/.dropbook/auth.json
7. 启用自动令牌刷新

安全特性（符合 RFC 9700）：
- 使用 S256 质询方法的 PKCE
- 用于 CSRF 保护的状态参数
- 使用 kSecAttrAccessibleWhenUnlocked 的密钥链存储
- 使用 CryptoKit 进行加密操作

选项 2：环境变量（旧版）

export DROPBOX_APP_KEY="你的_dropbox_应用密钥"
export DROPBOX_APP_SECRET="你的_dropbox_应用密钥"
export DROPBOX_ACCESS_TOKEN="你的_dropbox_访问令牌"

注意：手动令牌不支持自动刷新。生产环境请使用 OAuth 登录。

注销

清除密钥链和文件存储中的令牌：

make logout
# 或者: swift run dropbook logout

MCP 服务器（推荐）

启动 MCP 服务器：

make mcp
# 或者: ./.build/debug/dropbook mcp

MCP 工具

list_directory

列出 Dropbox 目录中的文件和文件夹。

参数：
- path (字符串，可选)：目录路径。默认值："/"

响应：

{
  "files": [
    {"type": "file", "name": "doc.pdf", "path": "/Docs/doc.pdf", "size": 1024},
    {"type": "folder", "name": "Projects", "path": "/Projects"}
  ]
}

search

按名称或内容搜索文件。

参数：
- query (字符串，必需)：搜索词
- path (字符串，可选)：搜索路径。默认值："/"

响应：

{
  "count": 2,
  "results": [
    {"matchType": "filename", "metadata": {"name": "report.pdf", "path": "/Docs/report.pdf"}}
  ]
}

upload

上传文件到 Dropbox。

参数：
- localPath (字符串，必需)：本地文件的绝对路径
- remotePath (字符串，必需)：Dropbox 中的目标路径
- overwrite (布尔值，可选)：如果存在则替换。默认值：false

响应：

{
  "uploaded": true,
  "name": "file.txt",
  "path": "/Uploads/file.txt",
  "size": 5000
}

download

从 Dropbox 下载文件。

参数：
- remotePath (字符串，必需)：Dropbox 中的文件路径
- localPath (字符串，必需)：本地目标路径

响应：

{
  "downloaded": true,
  "to": "/tmp/report.pdf"
}

delete

从 Dropbox 删除文件或文件夹（移至回收站）。

参数：
- path (字符串，必需)：要删除的 Dropbox 路径

响应：

{
  "deleted": true,
  "path": "/Docs/old-file.pdf"
}

get_account_info

获取 Dropbox 账户信息。

参数： 无

响应：

{
  "name": "Ryan Lisse",
  "email": "user@example.com"
}

read_file

读取并返回 Dropbox 中文本文件的内容。

参数：
- path (字符串，必需)：Dropbox 中的文件路径

响应：
以文本形式返回文件内容。仅适用于 UTF-8 编码的文本文件。

CLI 命令

# 身份验证
make login                 # 使用密钥链存储进行 OAuth 登录
make logout                # 清除存储的令牌

# 文件操作
make list                  # 列出根目录
swift run dropbook list /path

# 搜索文件
swift run dropbook search "query" [path]

# 上传文件
swift run dropbook upload /local/path /remote/path [--overwrite]

# 下载文件
swift run dropbook download /remote/path /local/path

# 启动 MCP 服务器
make mcp

MCP 客户端配置

Claude Code（项目级）

项目包含一个配置 MCP 服务器的 .mcp.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 服务器：

{
  "enableAllProjectMcpServers": true
}

Claude Desktop

{
  "mcpServers": {
    "dropbox": {
      "command": "/path/to/dropbook/.build/debug/dropbook",
      "args": ["mcp"],
      "env": {
        "DROPBOX_APP_KEY": "${DROPBOX_APP_KEY}",
        "DROPBOX_APP_SECRET": "${DROPBOX_APP_SECRET}"
      }
    }
  }
}

错误处理

架构

Dropbook/
├── Sources/
│   ├── DropbookCore/           # 业务逻辑（基于 actor）
│   │   ├── Auth/               # 密钥链和文件令牌存储
│   │   ├── Config/             # 配置管理
│   │   ├── Models/             # 领域模型
│   │   └── Services/           # DropboxService actor
│   ├── DropbookCLI/            # CLI 适配器
│   │   └── Commands/           # 登录、注销、文件命令
│   └── DropbookMCP/            # MCP 服务器
├── dropbox-skill/              # 技能文档
├── Makefile                    # 构建自动化
├── .mcp.json                   # MCP 服务器配置
└── Package.swift

使用 rclone 进行批量操作

对于备份、同步或批量传输等大规模操作，请使用 rclone——一个功能强大的云同步工具，原生支持 Dropbox。

安装 rclone

brew install rclone

为 Dropbox 配置 rclone

# 交互式设置（打开浏览器进行 OAuth）
rclone authorize dropbox

# 将令牌输出保存到配置
mkdir -p ~/.config/rclone
cat > ~/.config/rclone/rclone.conf << 'EOF'
[dropbox]
type = dropbox
token = {"access_token":"...在此处粘贴令牌..."}
EOF

备份到网络驱动器 / Time Capsule

# 完整备份并显示进度
rclone copy dropbox: /Volumes/TimeCapsule/Dropbox-Backup \
    --progress \
    --transfers 4 \
    --checkers 8 \
    --retries 10 \
    --log-file /tmp/dropbox-backup.log

# 同步（镜像 - 删除源中不存在的文件）
rclone sync dropbox: /Volumes/Backup/Dropbox --progress

# 检查将要复制的内容（试运行）
rclone copy dropbox: /Volumes/Backup --dry-run

常用 rclone 命令

# 列出远程内容
rclone lsd dropbox:              # 列出目录
rclone ls dropbox:               # 列出所有文件
rclone size dropbox:             # 计算总大小

# 复制操作
rclone copy dropbox:folder /local/path    # 下载文件夹
rclone copy /local/path dropbox:folder    # 上传文件夹

# 同步（双向）
rclone bisync dropbox: /local/path --resync

# 挂载为文件系统（macOS - 需要 macFUSE）
rclone mount dropbox: /mnt/dropbox --vfs-cache-mode full

用于可靠性的 rclone 标志

速率限制

Dropbox 有严格的 API 速率限制。如果遇到 too_many_requests 错误：

# 使用带宽限制
rclone copy dropbox: /backup --bwlimit 1M

# 或在操作之间添加延迟
rclone copy dropbox: /backup --tpslimit 2

rclone 会自动通过指数退避处理速率限制。

最佳实践

1. 使用 OAuth 登录 - 安全的密钥链存储和自动令牌刷新
2. 对代理使用 MCP - 程序化访问更可靠
3. 对批量操作使用 rclone - 更适合备份和大文件传输
4. 先验证路径 - 操作前使用 list_directory
5. 优雅地处理错误 - 检查响应中的错误字段
6. 遵守速率限制 - 批量操作之间添加延迟
7. 使用绝对路径 - 文件操作始终提供完整路径

安全性

• 密钥链存储：使用硬件加密存储令牌
• PKCE：代码交换证明密钥，防止授权码被截获
• 状态参数：OAuth 流程的 CSRF 保护
• 令牌刷新：过期前自动刷新
• CryptoKit：现代 Swift 加密库

依赖项

• SwiftyDropbox (v10.2.4+)：官方 Dropbox Swift SDK
• MCP (swift-sdk)：模型上下文协议 SDK
• CryptoKit：Apple 的加密框架
• rclone (可选)：用于批量操作和备份 (brew install rclone)

另请参阅

• Dropbook GitHub
• CLAUDE.md - 完整项目文档
• Dropbox API 文档
• rclone Dropbox 文档 - 批量同步和备份
• RFC 7636 - PKCE
• RFC 9700 - OAuth 2.0 安全最佳实践