dropbox-automation

通过 Rube MCP 自动化 Dropbox

通过 Composio 的 Dropbox 工具包自动执行 Dropbox 操作，包括文件上传/下载、搜索、文件夹管理、共享链接、批量操作和元数据检索。

工具包文档：composio.dev/toolkits/dropbox

前提条件

• 必须连接 Rube MCP（可使用 RUBE_SEARCH_TOOLS）
• 通过 RUBE_MANAGE_CONNECTIONS 建立有效的 Dropbox 连接，工具包为 dropbox
• 始终先调用 RUBE_SEARCH_TOOLS，获取当前工具架构

设置

获取 Rube MCP：在客户端配置中将 https://rube.app/mcp 添加为 MCP 服务。无需 API 密钥——只需添加端点即可使用。

1. 确认 RUBE_SEARCH_TOOLS 能正常响应，以验证 Rube MCP 是否可用
2. 使用工具包 dropbox 调用 RUBE_MANAGE_CONNECTIONS
3. 如果连接状态不是 ACTIVE，请按照返回的授权链接完成 Dropbox OAuth
4. 运行任何工作流前，确认连接状态为 ACTIVE

核心工作流

1. 搜索文件和文件夹

适用场景：用户想按名称、内容或类型查找文件或文件夹

工具调用顺序：

1. DROPBOX_SEARCH_FILE_OR_FOLDER - 使用查询字符串搜索，可选指定路径范围和筛选条件［必需］
2. DROPBOX_SEARCH_CONTINUE - 使用游标分页获取更多结果［若 has_more，则必需］
3. DROPBOX_GET_METADATA - 验证搜索结果并获取规范路径［可选］
4. DROPBOX_READ_FILE - 读取文件内容，确认它是目标文档［可选］

关键参数：

• query：搜索字符串（不区分大小写，至少包含 1 个非空白字符）
• options.path：将搜索范围限定在某个文件夹（例如 "/Documents"）；根目录使用空字符串
• options.file_categories：按类型筛选（如 "image"、"document"、"pdf"、"folder" 等）
• options.file_extensions：按扩展名筛选（例如 ["jpg", "png"]）
• options.filename_only：设为 true，仅匹配文件名（不匹配内容）
• options.max_results：每页结果数（默认值为 100，最大值为 1000）

注意事项：

• 如果还有更多结果，搜索会返回 has_more: true 和 cursor；必须继续搜索，避免遗漏匹配项
• 搜索和 search_continue 的所有分页结果总计最多为 10,000 条
• DROPBOX_GET_METADATA 返回的 path_display 大小写可能与用户输入不同；始终使用返回的规范路径
• DROPBOX_READ_FILE 返回的文件内容可能是 Base64 编码的 file_content_bytes；解析前需先解码

2. 上传和下载文件

适用场景：用户想将文件上传到 Dropbox，或从 Dropbox 下载文件

工具调用顺序：

1. DROPBOX_UPLOAD_FILE - 将文件上传到指定路径［上传时必需］
2. DROPBOX_READ_FILE - 从 Dropbox 下载/读取文件［下载时必需］
3. DROPBOX_DOWNLOAD_ZIP - 将整个文件夹下载为 ZIP 文件［可选］
4. DROPBOX_SAVE_URL - 将公共 URL 中的文件直接保存到 Dropbox［可选］
5. DROPBOX_GET_SHARED_LINK_FILE - 从共享链接 URL 下载文件［可选］
6. DROPBOX_EXPORT_FILE - 将 Dropbox Paper 等无法直接下载的文件导出为 Markdown/HTML［可选］

关键参数：

• path：Dropbox 路径（必须以 / 开头，例如 "/Documents/report.pdf"）
• mode："add"（默认值，冲突时失败）或 "overwrite"（覆盖上传）
• autorename：设为 true，冲突时自动重命名，而不是失败
• content：用于上传的 FileUploadable 对象，包含 s3key、mimetype 和 name
• url：供 DROPBOX_SAVE_URL 使用的公共 URL
• export_format：Paper 文档的导出格式，可为 "markdown"、"html" 或 "plain_text"

注意事项：

• DROPBOX_SAVE_URL 为异步操作，大文件可能需要最多 15 分钟
• 使用 DROPBOX_DOWNLOAD_ZIP 下载的文件夹必须小于 20 GB，且单个文件不得超过 4 GB，条目数必须少于 10,000
• DROPBOX_READ_FILE 返回的内容可能是 Base64 编码；请检查响应格式
• 通过 DROPBOX_GET_SHARED_LINK_FILE 下载共享链接中的文件时，受保护的链接可能需要提供 link_password

3. 共享文件和管理链接

使用场景：用户希望创建共享链接或管理现有共享链接

工具调用顺序：

1. DROPBOX_GET_METADATA - 确认文件/文件夹存在并获取规范路径 [前置条件]
2. DROPBOX_LIST_SHARED_LINKS - 检查是否已有共享链接，避免重复 [前置条件]
3. DROPBOX_CREATE_SHARED_LINK - 创建新的共享链接 [必需]
4. DROPBOX_GET_SHARED_LINK_METADATA - 将共享链接 URL 解析为元数据 [可选]
5. DROPBOX_LIST_SHARED_FOLDERS - 列出用户有权访问的所有共享文件夹 [可选]

关键参数：

• path：创建链接所用的文件或文件夹路径
• settings.audience："public"、"team" 或 "no_one"
• settings.access："viewer" 或 "editor"
• settings.expires：ISO 8601 到期日期（例如，"2026-12-31T23:59:59Z"）
• settings.require_password / settings.link_password：密码保护
• settings.allow_download：是否允许下载的布尔值
• direct_only：对于 LIST_SHARED_LINKS，设为 true，仅返回直接链接（不包含父文件夹链接）

注意事项：

• 如果该路径已存在共享链接，DROPBOX_CREATE_SHARED_LINK 会因 409 Conflict 而失败；请先使用 DROPBOX_LIST_SHARED_LINKS 检查
• 创建链接前，务必使用 DROPBOX_GET_METADATA 验证路径，以避免出现 path/not_found 错误
• 复用 DROPBOX_LIST_SHARED_LINKS 返回的现有链接，而不是创建重复链接
• requested_visibility 已弃用；较新的实现应使用 audience

4. 管理文件夹（创建、移动、删除）

使用场景：用户希望创建、移动、重命名或删除文件和文件夹

工具调用顺序：

1. DROPBOX_CREATE_FOLDER - 创建单个文件夹 [创建时必需]
2. DROPBOX_CREATE_FOLDER_BATCH - 一次创建多个文件夹 [可选]
3. DROPBOX_MOVE_FILE_OR_FOLDER - 移动或重命名单个文件/文件夹 [移动时必需]
4. DROPBOX_MOVE_BATCH - 一次移动多个项目 [可选]
5. DROPBOX_DELETE_FILE_OR_FOLDER - 删除单个文件或文件夹 [删除时必需]
6. DROPBOX_DELETE_BATCH - 一次删除多个项目 [可选]
7. DROPBOX_COPY_FILE_OR_FOLDER - 将文件或文件夹复制到新位置 [可选]
8. DROPBOX_CHECK_MOVE_BATCH / DROPBOX_CHECK_FOLDER_BATCH - 轮询异步批量作业状态 [批量操作时必需]

关键参数：

• path：目标路径（必须以 / 开头，区分大小写）
• from_path / to_path：移动/复制操作的源路径和目标路径
• autorename：冲突时设为 true 以自动重命名
• entries：批量移动时为 {from_path, to_path} 数组；批量创建时为路径数组
• allow_shared_folder：设为 true 以允许移动共享文件夹
• allow_ownership_transfer：移动会改变所有权时设为 true

注意事项：

• 所有路径都区分大小写，且必须以 / 开头
• 路径不得以 / 或空白字符结尾
• 批量操作可能是异步的；请使用 DROPBOX_CHECK_MOVE_BATCH 或 DROPBOX_CHECK_FOLDER_BATCH 轮询
• DROPBOX_FILES_MOVE_BATCH (v1) 采用“要么全部成功，要么全部失败”的行为——任何条目失败，整个批次都会失败
• 优先使用 DROPBOX_MOVE_BATCH (v2)，而非 DROPBOX_FILES_MOVE_BATCH (v1)
• 每次批量删除/移动最多处理 1000 个条目；批量创建文件夹最多处理 10,000 个路径
• 批量移动操作不支持仅更改大小写的重命名

5. 列出文件夹内容

适用场景：用户想浏览或枚举 Dropbox 文件夹中的文件

工具调用顺序：

1. DROPBOX_LIST_FILES_IN_FOLDER - 列出文件夹内容【必需】
2. DROPBOX_LIST_FOLDERS - 另一种支持列出已删除条目的文件夹列表方式【可选】
3. DROPBOX_GET_METADATA - 获取特定项目的详情【可选】

关键参数：

• path：文件夹路径（根目录使用空字符串 ""）
• recursive：设为 true 可列出所有嵌套内容
• limit：每次请求的最大结果数（默认值／最大值为 2000）
• include_deleted：设为 true 可包含已删除但可恢复的项目
• include_media_info：设为 true 可获取照片／视频元数据

注意事项：

• 根目录使用空字符串 ""，不要使用 "/"
• 递归列表可能非常庞大；使用 limit 控制分页大小
• 即使限制较小，结果也可能通过游标分页
• 如果路径不正确，DROPBOX_LIST_FILES_IN_FOLDER 会返回带有 path/not_found 的 409 Conflict

常见模式

ID 解析

• 基于路径：大多数 Dropbox 工具使用路径字符串（例如 "/Documents/file.pdf"）
• 基于 ID：某些工具接受 id:... 格式（例如 "id:4g0reWVRsAAAAAAAAAAAQ"）
• 规范路径：后续调用始终使用 DROPBOX_GET_METADATA 响应中的 path_display 或 path_lower
• 共享链接 URL：使用 DROPBOX_GET_SHARED_LINK_METADATA 将 URL 解析为路径／ID

分页

Dropbox 大多数端点都使用基于游标的分页：

• 搜索：使用 DROPBOX_SEARCH_CONTINUE 根据 has_more 和 cursor 继续获取结果（总匹配数上限为 10,000）
• 文件夹列表：根据响应中的游标继续获取结果，直到没有更多页面
• 共享链接：在 DROPBOX_LIST_SHARED_LINKS 中根据 has_more 和 cursor 继续获取结果
• 批处理作业状态：使用 DROPBOX_CHECK_MOVE_BATCH / DROPBOX_CHECK_FOLDER_BATCH 轮询

异步操作

Dropbox 的多项操作会异步运行：

• DROPBOX_SAVE_URL - 返回作业 ID；进行轮询或设置 wait: true（默认最长 120s）
• DROPBOX_MOVE_BATCH / DROPBOX_FILES_MOVE_BATCH - 可能返回作业 ID
• DROPBOX_CREATE_FOLDER_BATCH - 可能返回作业 ID
• DROPBOX_DELETE_BATCH - 返回作业 ID

已知注意事项

路径格式

• 所有路径都必须以 / 开头（某些端点中根目录的空字符串除外）
• 路径不得以 / 结尾，也不得包含尾随空格
• 写入操作中的路径区分大小写
• API 返回的 path_display 可能与用户输入的大小写不同；始终优先使用 API 返回的路径

速率限制

• Dropbox API 按端点设置速率限制；批处理操作有助于减少调用次数
• 所有分页中的搜索结果总数上限为 10,000
• 对于大型文件，DROPBOX_SAVE_URL 的超时时间为 15 分钟

文件内容

• DROPBOX_READ_FILE 可能会以 Base64 编码的 file_content_bytes 返回内容
• 不可下载的文件（Dropbox Paper、Google Docs）需要改用 DROPBOX_EXPORT_FILE
• 共享链接中的下载 URL 需要正确的身份验证标头

共享

• 如果共享链接已存在，创建共享链接会返回 409 Conflict 错误
• 创建新链接前，始终检查 DROPBOX_LIST_SHARED_LINKS
• 共享文件夹可能不会显示在标准路径列表中；请使用 DROPBOX_LIST_SHARED_FOLDERS

快速参考

任务	工具标识	关键参数
搜索文件	DROPBOX_SEARCH_FILE_OR_FOLDER	query, options.path
继续搜索	DROPBOX_SEARCH_CONTINUE	cursor
列出文件夹内容	DROPBOX_LIST_FILES_IN_FOLDER	path, recursive, limit
列出文件夹	DROPBOX_LIST_FOLDERS	path, recursive
获取元数据	DROPBOX_GET_METADATA	path
读取/下载文件	DROPBOX_READ_FILE	path
上传文件	DROPBOX_UPLOAD_FILE	path, content, mode
将 URL 保存到 Dropbox	DROPBOX_SAVE_URL	path, url
下载文件夹压缩包	DROPBOX_DOWNLOAD_ZIP	path
导出 Paper 文档	DROPBOX_EXPORT_FILE	path, export_format
下载共享链接文件	DROPBOX_GET_SHARED_LINK_FILE	url
创建共享链接	DROPBOX_CREATE_SHARED_LINK	path, settings
列出共享链接	DROPBOX_LIST_SHARED_LINKS	path, direct_only
共享链接元数据	DROPBOX_GET_SHARED_LINK_METADATA	url
列出共享文件夹	DROPBOX_LIST_SHARED_FOLDERS	limit
创建文件夹	DROPBOX_CREATE_FOLDER	path
批量创建文件夹	DROPBOX_CREATE_FOLDER_BATCH	paths
移动文件/文件夹	DROPBOX_MOVE_FILE_OR_FOLDER	from_path, to_path
批量移动	DROPBOX_MOVE_BATCH	entries
删除文件/文件夹	DROPBOX_DELETE_FILE_OR_FOLDER	path
批量删除	DROPBOX_DELETE_BATCH	entries
复制文件/文件夹	DROPBOX_COPY_FILE_OR_FOLDER	from_path, to_path
检查批处理状态	DROPBOX_CHECK_MOVE_BATCH	async_job_id

---

由 Composio 提供支持