box-automation

通过 Rube MCP 自动化 Box

通过 Composio 的 Box 工具包自动执行 Box 操作，包括上传/下载文件、搜索内容、管理文件夹、协作、查询元数据和签名请求。

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

前提条件

• 必须已连接 Rube MCP（可使用 RUBE_SEARCH_TOOLS）
• 通过 RUBE_MANAGE_CONNECTIONS 建立有效的 Box 连接，并指定工具包 box
• 始终先调用 RUBE_SEARCH_TOOLS，以获取当前工具架构

设置

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

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

核心工作流

1. 上传和下载文件

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

工具调用顺序：

1. BOX_SEARCH_FOR_CONTENT - 如果路径未知，则查找目标文件夹 [前置条件]
2. BOX_GET_FOLDER_INFORMATION - 确认文件夹存在并获取 folder_id [前置条件]
3. BOX_LIST_ITEMS_IN_FOLDER - 浏览文件夹内容并查找文件 ID [可选]
4. BOX_UPLOAD_FILE - 将文件上传到指定文件夹 [上传必需]
5. BOX_DOWNLOAD_FILE - 根据 file_id 下载文件 [下载必需]
6. BOX_CREATE_ZIP_DOWNLOAD - 将多个文件/文件夹打包为 zip [可选]

关键参数：

• parent_id：上传目标文件夹的 ID（根文件夹使用 "0"）
• file：用于上传的 FileUploadable 对象，包含 s3key、mimetype 和 name
• file_id：下载文件时使用的唯一文件标识符
• version：可选的文件版本 ID，用于下载特定版本
• fields：以逗号分隔的待返回属性列表

注意事项：

• 上传到包含同名文件的文件夹可能触发冲突处理；请确定要覆盖还是重命名
• 大于 50MB 的文件应使用分块上传 API（标准工具不支持）
• 上传内容中的 attributes 部分必须位于 file 部分之前，否则会因 metadata_after_file_contents 返回 HTTP 400
• 文件 ID 和文件夹 ID 是数字字符串，可从 Box 网页应用 URL 中提取（例如，https://*.app.box.com/files/123 中的 file_id 为 "123"）

2. 搜索和浏览内容

适用场景：用户希望按名称、内容或元数据查找文件、文件夹或网页链接

工具调用顺序：

1. BOX_SEARCH_FOR_CONTENT - 对文件、文件夹和网页链接进行全文搜索【必需】
2. BOX_LIST_ITEMS_IN_FOLDER - 浏览指定文件夹的内容【可选】
3. BOX_GET_FILE_INFORMATION - 获取指定文件的详细元数据【可选】
4. BOX_GET_FOLDER_INFORMATION - 获取指定文件夹的详细元数据【可选】
5. BOX_QUERY_FILES_FOLDERS_BY_METADATA - 按元数据模板值搜索【可选】
6. BOX_LIST_RECENTLY_ACCESSED_ITEMS - 列出最近访问的项目【可选】

关键参数：

• query：支持运算符的搜索字符串（"" 精确匹配，AND、OR、NOT——仅限大写）
• type：按 "file"、"folder" 或 "web_link" 筛选
• ancestor_folder_ids：将搜索范围限制在指定文件夹（以逗号分隔的 ID）
• file_extensions：按文件类型筛选（以逗号分隔，不带点号）
• content_types：在 "name"、"description"、"file_content"、"comments"、"tags" 中搜索
• created_at_range / updated_at_range：按日期筛选，使用以逗号分隔的 RFC3339 时间戳
• limit：每页结果数（默认值为 30）
• offset：分页偏移量（最大为 10000）
• folder_id：用于 LIST_ITEMS_IN_FOLDER（根目录使用 "0"）

注意事项：

• offset 大于 10000 的查询会被拒绝，并返回 HTTP 400
• BOX_SEARCH_FOR_CONTENT 必须提供 query 或 mdfilters 参数
• 配置错误的筛选条件可能会悄然遗漏预期项目；请先使用小型测试查询进行验证
• 布尔运算符（AND、OR、NOT）必须使用大写
• BOX_LIST_ITEMS_IN_FOLDER 需要通过 marker 或 offset/usemarker 进行分页；只获取到部分列表的情况很常见
• 标准文件夹先按类型排序（文件夹在文件之前，文件在网页链接之前）

3. 管理文件夹

适用场景：用户希望创建、更新、移动、复制或删除文件夹

工具调用顺序：

1. BOX_GET_FOLDER_INFORMATION - 确认文件夹存在并检查权限【前置条件】
2. BOX_CREATE_FOLDER - 创建新文件夹【创建时必需】
3. BOX_UPDATE_FOLDER - 重命名、移动文件夹或更新其设置【更新时必需】
4. BOX_COPY_FOLDER - 将文件夹复制到新位置【可选】
5. BOX_DELETE_FOLDER - 将文件夹移至回收站【删除时必需】
6. BOX_PERMANENTLY_REMOVE_FOLDER - 永久删除已移至回收站的文件夹【可选】

关键参数：

• name：文件夹名称（不能包含 /、\、末尾空格或 ./..）
• parent__id：父文件夹 ID（根目录使用 "0"）
• folder_id：操作目标文件夹的 ID
• parent.id：通过 BOX_UPDATE_FOLDER 移动文件夹时的目标文件夹 ID
• recursive：设置为 true 以删除非空文件夹
• shared_link：用于为文件夹创建共享链接的对象，包含 access、password、permissions
• description、tags：可选元数据字段

注意事项：

• BOX_DELETE_FOLDER 默认会将文件夹移至回收站；如需永久删除，请使用 BOX_PERMANENTLY_REMOVE_FOLDER
• 删除非空文件夹时需要设置 recursive: true
• 根文件夹（ID "0"）无法复制或删除
• 文件夹名称不能包含 /、\、不可打印的 ASCII 字符或末尾空格
• 移动文件夹时，需要通过 BOX_UPDATE_FOLDER 设置 parent.id

4. 共享文件并管理协作

使用场景：用户想要共享文件、管理访问权限或处理协作

工具调用顺序：

1. BOX_GET_FILE_INFORMATION - 获取文件详细信息和当前共享状态 [前置条件]
2. BOX_LIST_FILE_COLLABORATIONS - 列出有权访问文件的人员 [必需]
3. BOX_UPDATE_COLLABORATION - 更改访问级别，或接受／拒绝邀请 [必需]
4. BOX_GET_COLLABORATION - 获取特定协作的详细信息 [可选]
5. BOX_UPDATE_FILE - 创建共享链接、锁定文件或更新权限 [可选]
6. BOX_UPDATE_FOLDER - 为文件夹创建共享链接 [可选]

关键参数：

• collaboration_id：唯一的协作标识符
• role：访问级别（"editor"、"viewer"、"co-owner"、"owner"、"previewer"、"uploader"、"viewer uploader"、"previewer uploader"）
• status：协作邀请的状态，可为 "accepted"、"pending" 或 "rejected"
• file_id：要共享或管理的文件
• lock__access：设为 "lock" 以锁定文件
• permissions__can__download：下载权限，可设为 "company" 或 "open"

注意事项：

• 只有特定角色可以邀请协作者；权限不足会导致授权错误
• can_view_path 会增加受邀者的 “All Files” 页面的加载时间；每位用户最多限制为 1000 个
• 协作到期功能需要启用企业管理员设置
• 嵌套参数名使用双下划线（例如 lock__access、parent__id）

5. Box Sign 请求

使用场景：用户想要管理文档签名请求

工具调用顺序：

1. BOX_LIST_BOX_SIGN_REQUESTS - 列出所有签名请求 [必需]
2. BOX_GET_BOX_SIGN_REQUEST_BY_ID - 获取特定签名请求的详细信息 [可选]
3. BOX_CANCEL_BOX_SIGN_REQUEST - 取消待处理的签名请求 [可选]

关键参数：

• sign_request_id：签名请求的 UUID
• shared_requests：设为 true 以包含用户作为协作者（而非所有者）的请求
• senders：按发件人邮箱筛选（需要 shared_requests: true）
• limit / marker：分页参数

注意事项：

• 需要为企业账户启用 Box Sign
• 签名文件或父文件夹被删除时，请求不会显示在列表中
• 只有创建者可以取消签名请求
• 签名请求状态包括：converting、created、sent、viewed、signed、declined、cancelled、expired、error_converting、error_sending

常见模式

ID 解析

Box 使用数字字符串 ID 标识所有实体：

• 根文件夹：ID 始终为 "0"
• 从 URL 获取文件 ID：https://*.app.box.com/files/123 对应的 file_id 为 "123"
• 从 URL 获取文件夹 ID：https://*.app.box.com/folder/123 对应的 folder_id 为 "123"
• 通过搜索获取 ID：使用 BOX_SEARCH_FOR_CONTENT 查找项目，然后从结果中提取 ID
• ETag：安全地执行并发删除操作时，将文件的 ETag 用于 if_match

分页

Box 支持两种分页方式：

• 基于偏移量：使用 offset + limit（偏移量最大为 10000）
• 基于标记：设置 usemarker: true，并使用响应中的 marker 继续分页（大型数据集优先使用此方式）
• 始终分页至完成，以避免结果不完整

嵌套参数

Box 工具使用双下划线表示嵌套对象：

• parent__id 用于引用父文件夹
• lock__access、lock__expires__at、lock__is__download__prevented 用于文件锁定
• permissions__can__download 用于下载权限

已知注意事项

ID 格式

• 所有 ID 均为数字字符串（例如 "123456"，而非整数）
• 根文件夹始终为 "0"
• 可以从 Box 网页应用 URL 中提取文件和文件夹 ID

速率限制

• Box API 对不同端点设有速率限制
• 搜索和列表操作应合理使用分页
• 批量操作应在请求之间加入延迟

参数注意事项

• fields 参数会更改响应格式：指定该参数时，仅返回精简表示和所请求的字段
• 搜索必须提供 query 或 mdfilters；两者都可以单独省略，但必须至少提供一个
• 将 BOX_UPDATE_FILE 的 lock 设为 null 会移除锁定（仅限原始 API）
• 元数据查询的 from 字段格式：enterprise_{enterprise_id}.templateKey 或 global.templateKey

权限

• 权限不足时删除操作会失败；请始终处理错误响应
• 协作角色决定允许执行哪些操作
• 企业设置可能会限制某些共享选项

快速参考

任务	工具标识	关键参数
搜索内容	BOX_SEARCH_FOR_CONTENT	query、type、ancestor_folder_ids
列出文件夹项目	BOX_LIST_ITEMS_IN_FOLDER	folder_id、limit、marker
获取文件信息	BOX_GET_FILE_INFORMATION	file_id、fields
获取文件夹信息	BOX_GET_FOLDER_INFORMATION	folder_id、fields
上传文件	BOX_UPLOAD_FILE	file、parent_id
下载文件	BOX_DOWNLOAD_FILE	file_id
创建文件夹	BOX_CREATE_FOLDER	name、parent__id
更新文件夹	BOX_UPDATE_FOLDER	folder_id、name、parent
复制文件夹	BOX_COPY_FOLDER	folder_id、parent__id
删除文件夹	BOX_DELETE_FOLDER	folder_id、recursive
永久删除文件夹	BOX_PERMANENTLY_REMOVE_FOLDER	folder_id
更新文件	BOX_UPDATE_FILE	file_id、name、parent__id
删除文件	BOX_DELETE_FILE	file_id、if_match
列出协作关系	BOX_LIST_FILE_COLLABORATIONS	file_id
更新协作关系	BOX_UPDATE_COLLABORATION	collaboration_id、role
获取协作关系	BOX_GET_COLLABORATION	collaboration_id
按元数据查询	BOX_QUERY_FILES_FOLDERS_BY_METADATA	from、ancestor_folder_id、query
列出合集	BOX_LIST_ALL_COLLECTIONS	（无）
列出合集项目	BOX_LIST_COLLECTION_ITEMS	collection_id
列出签署请求	BOX_LIST_BOX_SIGN_REQUESTS	limit、marker
获取签署请求	BOX_GET_BOX_SIGN_REQUEST_BY_ID	sign_request_id
取消签署请求	BOX_CANCEL_BOX_SIGN_REQUEST	sign_request_id
最近访问的项目	BOX_LIST_RECENTLY_ACCESSED_ITEMS	（无）
创建 ZIP 下载	BOX_CREATE_ZIP_DOWNLOAD	项目 ID

---

由 Composio 提供支持