名称： box-automation
描述： 通过 Rube MCP (Composio) 自动化 Box 云存储操作，包括文件上传/下载、搜索、文件夹管理、共享、协作和元数据查询。始终首先搜索工具以获取当前模式。
requires:
mcp: [rube]

通过 Rube MCP 实现 Box 自动化

通过 Composio 的 Box 工具包，自动化 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. 调用 RUBE_MANAGE_CONNECTIONS，指定工具包 box。
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 部分之前，否则会收到 HTTP 400 错误，提示 metadata_after_file_contents。
- 文件 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 会增加受邀者“所有文件”页面的加载时间；每个用户限制在 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：使用 if_match 参数配合文件的 ETag，以实现安全的并发删除操作。

分页

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"。
• 文件 ID 和文件夹 ID 可以从 Box 网页应用 URL 中提取。

速率限制

• Box API 有每个端点的速率限制。
• 搜索和列表操作应负责任地使用分页。
• 批量操作应在请求之间包含延迟。

参数特性

• fields 参数会改变响应结构：指定后，只返回精简表示和请求的字段。
• 搜索需要 query 或 mdfilters 中的至少一个；两者单独都是可选的，但必须有一个存在。
• BOX_UPDATE_FILE 将 lock 设置为 null 会移除锁定（仅限原始 API）。
• 元数据查询的 from 字段格式：enterprise_{enterprise_id}.templateKey 或 global.templateKey。

权限

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

快速参考