Dropbox 管理器技能

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

设置

先决条件

# Clone and build Dropbook
git clone https://github.com/RyanLisse/Dropbook.git
cd Dropbook
make build

身份验证

选项 1：使用 Keychain 进行 OAuth 登录（推荐）

使用交互式 OAuth 流程，并安全存储到 Keychain：

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防护的State参数
• 钥匙串存储，使用kSecAttrAccessibleWhenUnlocked属性
• 用于加密操作的CryptoKit

选项2：环境变量（传统方式）

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登录。

登出

清除钥匙串和文件存储中的令牌：

make logout
# or: swift run dropbook logout

MCP服务器（推荐）

启动MCP服务器：

make mcp
# or: ./.build/debug/dropbook mcp

MCP工具

list_directory

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

参数：

• 路径（字符串，可选）：目录路径。默认值："/"

响应：

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

search

按名称或内容搜索文件。

参数：

• 查询（字符串，必需）：搜索词
• 路径（字符串，可选）：搜索范围内的路径。默认值："/"

响应：

{
  "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 命令

# 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.json文件，用于配置 MCP 服务器：

{
  "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/           # 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- 一款功能强大的云同步工具，原生支持 Dropbox。

安装 rclone

brew install rclone

为 Dropbox 配置 rclone

# 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

备份到网络驱动器/时间胶囊

# 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命令

# 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可靠性相关标志

速率限制

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

# Use bandwidth limiting
rclone copy dropbox: /backup --bwlimit 1M

# Or add delays between operations
rclone copy dropbox: /backup --tpslimit 2

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

最佳实践

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

钥匙串存储

• ：令牌通过硬件加密存储: Tokens stored with hardware-backed encryption
• 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 安全最佳实践