box-automation
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseBox Automation via Rube MCP
通过Rube MCP实现Box自动化
Automate Box operations including file upload/download, content search, folder management, collaboration, metadata queries, and sign requests through Composio's Box toolkit.
Toolkit docs: composio.dev/toolkits/box
借助Composio的Box工具包,自动化Box操作,包括文件上传/下载、内容搜索、文件夹管理、协作、元数据查询以及签名请求。
Prerequisites
前提条件
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
- Active Box connection via with toolkit
RUBE_MANAGE_CONNECTIONSbox - Always call first to get current tool schemas
RUBE_SEARCH_TOOLS
- 必须已连接Rube MCP(需有可用的RUBE_SEARCH_TOOLS)
- 通过并使用工具包
RUBE_MANAGE_CONNECTIONS完成Box的激活连接box - 请始终先调用以获取最新的工具架构
RUBE_SEARCH_TOOLS
Setup
设置步骤
Get Rube MCP: Add as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
https://rube.app/mcp- Verify Rube MCP is available by confirming responds
RUBE_SEARCH_TOOLS - Call with toolkit
RUBE_MANAGE_CONNECTIONSbox - If connection is not ACTIVE, follow the returned auth link to complete Box OAuth
- Confirm connection status shows ACTIVE before running any workflows
获取Rube MCP:在客户端配置中添加作为MCP服务器。无需API密钥 —— 只需添加端点即可使用。
https://rube.app/mcp- 通过确认可响应,验证Rube MCP是否可用
RUBE_SEARCH_TOOLS - 调用并指定工具包
RUBE_MANAGE_CONNECTIONSbox - 如果连接状态未显示为ACTIVE,请按照返回的授权链接完成Box OAuth认证
- 在运行任何工作流之前,确认连接状态为ACTIVE
Core Workflows
核心工作流
1. Upload and Download Files
1. 文件上传与下载
When to use: User wants to upload files to Box or download files from it
Tool sequence:
- - Find the target folder if path is unknown [Prerequisite]
BOX_SEARCH_FOR_CONTENT - - Verify folder exists and get folder_id [Prerequisite]
BOX_GET_FOLDER_INFORMATION - - Browse folder contents and discover file IDs [Optional]
BOX_LIST_ITEMS_IN_FOLDER - - Upload a file to a specific folder [Required for upload]
BOX_UPLOAD_FILE - - Download a file by file_id [Required for download]
BOX_DOWNLOAD_FILE - - Bundle multiple files/folders into a zip [Optional]
BOX_CREATE_ZIP_DOWNLOAD
Key parameters:
- : Folder ID for upload destination (use
parent_idfor root folder)"0" - : FileUploadable object with
file,s3key, andmimetypefor uploadsname - : Unique file identifier for downloads
file_id - : Optional file version ID for downloading specific versions
version - : Comma-separated list of attributes to return
fields
Pitfalls:
- Uploading to a folder with existing filenames can trigger conflict behavior; decide overwrite vs rename semantics
- Files over 50MB should use chunk upload APIs (not available via standard tools)
- The part of upload must come before the
attributespart or you get HTTP 400 withfilemetadata_after_file_contents - File IDs and folder IDs are numeric strings extractable from Box web app URLs (e.g., gives file_id
https://*.app.box.com/files/123)"123"
适用场景:用户需要将文件上传至Box或从Box下载文件
工具执行顺序:
- - 若目标文件夹路径未知,先查找目标文件夹 [前提步骤]
BOX_SEARCH_FOR_CONTENT - - 验证文件夹是否存在并获取folder_id [前提步骤]
BOX_GET_FOLDER_INFORMATION - - 浏览文件夹内容并查找文件ID [可选]
BOX_LIST_ITEMS_IN_FOLDER - - 将文件上传至指定文件夹 [上传必填]
BOX_UPLOAD_FILE - - 通过file_id下载文件 [下载必填]
BOX_DOWNLOAD_FILE - - 将多个文件/文件夹打包为ZIP文件 [可选]
BOX_CREATE_ZIP_DOWNLOAD
关键参数:
- : 上传目标文件夹的ID(根文件夹使用
parent_id)"0" - : 用于上传的FileUploadable对象,包含
file、s3key和mimetypename - : 文件的唯一标识符,用于下载
file_id - : 可选参数,用于下载特定版本文件的版本ID
version - : 以逗号分隔的需返回的属性列表
fields
注意事项:
- 上传至已有同名文件的文件夹时,会触发冲突处理逻辑;需提前决定是覆盖还是重命名
- 超过50MB的文件应使用分块上传API(标准工具不支持该功能)
- 上传时,部分必须在
attributes部分之前,否则会返回HTTP 400错误,错误信息为filemetadata_after_file_contents - 文件ID和文件夹ID为数字字符串,可从Box网页应用的URL中提取(例如:中的file_id为
https://*.app.box.com/files/123)"123"
2. Search and Browse Content
2. 内容搜索与浏览
When to use: User wants to find files, folders, or web links by name, content, or metadata
Tool sequence:
- - Full-text search across files, folders, and web links [Required]
BOX_SEARCH_FOR_CONTENT - - Browse contents of a specific folder [Optional]
BOX_LIST_ITEMS_IN_FOLDER - - Get detailed metadata for a specific file [Optional]
BOX_GET_FILE_INFORMATION - - Get detailed metadata for a specific folder [Optional]
BOX_GET_FOLDER_INFORMATION - - Search by metadata template values [Optional]
BOX_QUERY_FILES_FOLDERS_BY_METADATA - - List recently accessed items [Optional]
BOX_LIST_RECENTLY_ACCESSED_ITEMS
Key parameters:
- : Search string supporting operators (
queryexact match,"",AND,OR- uppercase only)NOT - : Filter by
type,"file", or"folder""web_link" - : Limit search to specific folders (comma-separated IDs)
ancestor_folder_ids - : Filter by file type (comma-separated, no dots)
file_extensions - : Search in
content_types,"name","description","file_content","comments""tags" - /
created_at_range: Date filters as comma-separated RFC3339 timestampsupdated_at_range - : Results per page (default 30)
limit - : Pagination offset (max 10000)
offset - : For
folder_id(useLIST_ITEMS_IN_FOLDERfor root)"0"
Pitfalls:
- Queries with offset > 10000 are rejected with HTTP 400
- requires either
BOX_SEARCH_FOR_CONTENTorqueryparametermdfilters - Misconfigured filters can silently omit expected items; validate with small test queries first
- Boolean operators (,
AND,OR) must be uppercaseNOT - requires pagination via
BOX_LIST_ITEMS_IN_FOLDERormarker/offset; partial listings are commonusemarker - Standard folders sort items by type first (folders before files before web links)
适用场景:用户需要按名称、内容或元数据查找文件、文件夹或网页链接
工具执行顺序:
- - 对文件、文件夹和网页链接进行全文搜索 [必填]
BOX_SEARCH_FOR_CONTENT - - 浏览指定文件夹的内容 [可选]
BOX_LIST_ITEMS_IN_FOLDER - - 获取特定文件的详细元数据 [可选]
BOX_GET_FILE_INFORMATION - - 获取特定文件夹的详细元数据 [可选]
BOX_GET_FOLDER_INFORMATION - - 按元数据模板值进行搜索 [可选]
BOX_QUERY_FILES_FOLDERS_BY_METADATA - - 列出最近访问的项目 [可选]
BOX_LIST_RECENTLY_ACCESSED_ITEMS
关键参数:
- : 支持运算符的搜索字符串(
query表示精确匹配,""、AND、OR需大写)NOT - : 按
type、"file"或"folder"进行过滤"web_link" - : 将搜索范围限制在特定文件夹(以逗号分隔的ID列表)
ancestor_folder_ids - : 按文件类型过滤(以逗号分隔,无需加圆点)
file_extensions - : 指定搜索范围,包括
content_types、"name"、"description"、"file_content"、"comments""tags" - /
created_at_range: 日期过滤器,格式为以逗号分隔的RFC3339时间戳updated_at_range - : 每页返回的结果数(默认30条)
limit - : 分页偏移量(最大值为10000)
offset - : 用于
folder_id(根文件夹使用BOX_LIST_ITEMS_IN_FOLDER)"0"
注意事项:
- 偏移量超过10000的查询会被拒绝,并返回HTTP 400错误
- 必须提供
BOX_SEARCH_FOR_CONTENT或query参数之一mdfilters - 配置错误的过滤器可能会静默遗漏预期结果;请先用小型测试查询验证
- 布尔运算符(、
AND、OR)必须大写NOT - 需要通过
BOX_LIST_ITEMS_IN_FOLDER或marker/offset进行分页;部分结果返回是常见情况usemarker - 标准文件夹会先按类型排序(文件夹优先,其次是文件,最后是网页链接)
3. Manage Folders
3. 文件夹管理
When to use: User wants to create, update, move, copy, or delete folders
Tool sequence:
- - Verify folder exists and check permissions [Prerequisite]
BOX_GET_FOLDER_INFORMATION - - Create a new folder [Required for create]
BOX_CREATE_FOLDER - - Rename, move, or update folder settings [Required for update]
BOX_UPDATE_FOLDER - - Copy a folder to a new location [Optional]
BOX_COPY_FOLDER - - Move folder to trash [Required for delete]
BOX_DELETE_FOLDER - - Permanently delete a trashed folder [Optional]
BOX_PERMANENTLY_REMOVE_FOLDER
Key parameters:
- : Folder name (no
name,/, trailing spaces, or\/.).. - : Parent folder ID (use
parent__idfor root)"0" - : Target folder ID for operations
folder_id - : Destination folder ID for moves via
parent.idBOX_UPDATE_FOLDER - : Set
recursiveto delete non-empty folderstrue - : Object with
shared_link,access,passwordfor creating shared links on folderspermissions - ,
description: Optional metadata fieldstags
Pitfalls:
- moves to trash by default; use
BOX_DELETE_FOLDERfor permanent deletionBOX_PERMANENTLY_REMOVE_FOLDER - Non-empty folders require for deletion
recursive: true - Root folder (ID ) cannot be copied or deleted
"0" - Folder names cannot contain ,
/, non-printable ASCII, or trailing spaces\ - Moving folders requires setting via
parent.idBOX_UPDATE_FOLDER
适用场景:用户需要创建、更新、移动、复制或删除文件夹
工具执行顺序:
- - 验证文件夹是否存在并检查权限 [前提步骤]
BOX_GET_FOLDER_INFORMATION - - 创建新文件夹 [创建必填]
BOX_CREATE_FOLDER - - 重命名、移动或更新文件夹设置 [更新必填]
BOX_UPDATE_FOLDER - - 将文件夹复制到新位置 [可选]
BOX_COPY_FOLDER - - 将文件夹移至回收站 [删除必填]
BOX_DELETE_FOLDER - - 永久删除已移入回收站的文件夹 [可选]
BOX_PERMANENTLY_REMOVE_FOLDER
关键参数:
- : 文件夹名称(不能包含
name、/、末尾空格或\/.).. - : 父文件夹ID(根文件夹使用
parent__id)"0" - : 操作目标文件夹的ID
folder_id - : 通过
parent.id移动文件夹时的目标文件夹IDBOX_UPDATE_FOLDER - : 设置为
recursive可删除非空文件夹true - : 用于创建文件夹共享链接的对象,包含
shared_link、access、passwordpermissions - ,
description: 可选的元数据字段tags
注意事项:
- 默认将文件夹移至回收站;若需永久删除,请使用
BOX_DELETE_FOLDERBOX_PERMANENTLY_REMOVE_FOLDER - 删除非空文件夹需设置
recursive: true - 根文件夹(ID为)无法被复制或删除
"0" - 文件夹名称不能包含、
/、不可打印ASCII字符或末尾空格\ - 移动文件夹需通过设置
BOX_UPDATE_FOLDERparent.id
4. Share Files and Manage Collaborations
4. 文件共享与协作管理
When to use: User wants to share files, manage access, or handle collaborations
Tool sequence:
- - Get file details and current sharing status [Prerequisite]
BOX_GET_FILE_INFORMATION - - List who has access to a file [Required]
BOX_LIST_FILE_COLLABORATIONS - - Change access level or accept/reject invitations [Required]
BOX_UPDATE_COLLABORATION - - Get details of a specific collaboration [Optional]
BOX_GET_COLLABORATION - - Create shared links, lock files, or update permissions [Optional]
BOX_UPDATE_FILE - - Create shared links on folders [Optional]
BOX_UPDATE_FOLDER
Key parameters:
- : Unique collaboration identifier
collaboration_id - : Access level (
role,"editor","viewer","co-owner","owner","previewer","uploader","viewer uploader")"previewer uploader" - :
status,"accepted", or"pending"for collaboration invites"rejected" - : File to share or manage
file_id - : Set to
lock__accessto lock a file"lock" - :
permissions__can__downloador"company"for download permissions"open"
Pitfalls:
- Only certain roles can invite collaborators; insufficient permissions cause authorization errors
- increases load time for the invitee's "All Files" page; limit to 1000 per user
can_view_path - Collaboration expiration requires enterprise admin settings to be enabled
- Nested parameter names use double underscores (e.g., ,
lock__access)parent__id
适用场景:用户需要共享文件、管理访问权限或处理协作事项
工具执行顺序:
- - 获取文件详情及当前共享状态 [前提步骤]
BOX_GET_FILE_INFORMATION - - 列出拥有文件访问权限的用户 [必填]
BOX_LIST_FILE_COLLABORATIONS - - 更改访问级别或接受/拒绝协作邀请 [必填]
BOX_UPDATE_COLLABORATION - - 获取特定协作的详细信息 [可选]
BOX_GET_COLLABORATION - - 创建共享链接、锁定文件或更新权限 [可选]
BOX_UPDATE_FILE - - 为文件夹创建共享链接 [可选]
BOX_UPDATE_FOLDER
关键参数:
- : 协作的唯一标识符
collaboration_id - : 访问级别(
role、"editor"、"viewer"、"co-owner"、"owner"、"previewer"、"uploader"、"viewer uploader")"previewer uploader" - : 协作邀请的状态(
status、"accepted"或"pending")"rejected" - : 需共享或管理的文件ID
file_id - : 设置为
lock__access可锁定文件"lock" - : 下载权限,可选
permissions__can__download或"company""open"
注意事项:
- 只有特定角色的用户可以邀请协作者;权限不足会导致授权错误
- 会增加受邀者“所有文件”页面的加载时间;每个用户最多设置1000条
can_view_path - 协作过期功能需要企业管理员启用相关设置
- 嵌套参数名称使用双下划线(例如:、
lock__access)parent__id
5. Box Sign Requests
5. Box签名请求
When to use: User wants to manage document signature requests
Tool sequence:
- - List all signature requests [Required]
BOX_LIST_BOX_SIGN_REQUESTS - - Get details of a specific sign request [Optional]
BOX_GET_BOX_SIGN_REQUEST_BY_ID - - Cancel a pending sign request [Optional]
BOX_CANCEL_BOX_SIGN_REQUEST
Key parameters:
- : UUID of the sign request
sign_request_id - : Set
shared_requeststo include requests where user is a collaborator (not owner)true - : Filter by sender emails (requires
senders)shared_requests: true - /
limit: Pagination parametersmarker
Pitfalls:
- Requires Box Sign to be enabled for the enterprise account
- Deleted sign files or parent folders cause requests to not appear in listings
- Only the creator can cancel a sign request
- Sign request statuses include: ,
converting,created,sent,viewed,signed,declined,cancelled,expired,error_convertingerror_sending
适用场景:用户需要管理文档签名请求
工具执行顺序:
- - 列出所有签名请求 [必填]
BOX_LIST_BOX_SIGN_REQUESTS - - 获取特定签名请求的详情 [可选]
BOX_GET_BOX_SIGN_REQUEST_BY_ID - - 取消待处理的签名请求 [可选]
BOX_CANCEL_BOX_SIGN_REQUEST
关键参数:
- : 签名请求的UUID
sign_request_id - : 设置为
shared_requests可包含用户作为协作者(而非所有者)的请求true - : 按发送者邮箱过滤(需设置
senders)shared_requests: true - /
limit: 分页参数marker
注意事项:
- 企业账户需启用Box Sign功能
- 已删除的签名文件或父文件夹会导致请求不显示在列表中
- 只有创建者可以取消签名请求
- 签名请求状态包括:、
converting、created、sent、viewed、signed、declined、cancelled、expired、error_convertingerror_sending
Common Patterns
通用模式
ID Resolution
ID解析
Box uses numeric string IDs for all entities:
- Root folder: Always ID
"0" - File ID from URL: gives file_id
https://*.app.box.com/files/123"123" - Folder ID from URL: gives folder_id
https://*.app.box.com/folder/123"123" - Search to ID: Use to find items, then extract IDs from results
BOX_SEARCH_FOR_CONTENT - ETag: Use with file's ETag for safe concurrent delete operations
if_match
Box为所有实体使用数字字符串ID:
- 根文件夹: ID固定为
"0" - 从URL提取文件ID: 中的file_id为
https://*.app.box.com/files/123"123" - 从URL提取文件夹ID: 中的folder_id为
https://*.app.box.com/folder/123"123" - 通过搜索获取ID: 使用查找项目,然后从结果中提取ID
BOX_SEARCH_FOR_CONTENT - ETag: 为安全的并发删除操作,可结合文件的ETag使用参数
if_match
Pagination
分页
Box supports two pagination methods:
- Offset-based: Use +
offset(max offset 10000)limit - Marker-based: Set and follow
usemarker: truefrom responses (preferred for large datasets)marker - Always paginate to completion to avoid partial results
Box支持两种分页方式:
- 基于偏移量: 使用+
offset(最大偏移量为10000)limit - 基于标记: 设置并跟随响应中的
usemarker: true(推荐用于大型数据集)marker - 请始终完成全部分页,以避免获取部分结果
Nested Parameters
嵌套参数
Box tools use double underscore notation for nested objects:
- for parent folder reference
parent__id - ,
lock__access,lock__expires__atfor file lockslock__is__download__prevented - for download permissions
permissions__can__download
Box工具使用双下划线表示嵌套对象:
- 表示父文件夹引用
parent__id - 、
lock__access、lock__expires__at用于文件锁定lock__is__download__prevented - 用于下载权限
permissions__can__download
Known Pitfalls
已知注意事项
ID Formats
ID格式
- All IDs are numeric strings (e.g., , not integers)
"123456" - Root folder is always
"0" - File and folder IDs can be extracted from Box web app URLs
- 所有ID均为数字字符串(例如:,而非整数)
"123456" - 根文件夹ID固定为
"0" - 文件和文件夹ID可从Box网页应用的URL中提取
Rate Limits
速率限制
- Box API has per-endpoint rate limits
- Search and list operations should use pagination responsibly
- Bulk operations should include delays between requests
- Box API对每个端点都有速率限制
- 搜索和列表操作应合理使用分页
- 批量操作应在请求之间添加延迟
Parameter Quirks
参数特性
- parameter changes response shape: when specified, only mini representation + requested fields are returned
fields - Search requires either or
query; both are optional individually but one must be presentmdfilters - with
BOX_UPDATE_FILEset tolockremoves the lock (raw API only)null - Metadata query field format:
fromorenterprise_{enterprise_id}.templateKeyglobal.templateKey
- 参数会改变响应结构:指定该参数后,仅返回精简表示及请求的字段
fields - 搜索必须提供或
query参数;两者单独可选,但必须提供其中一个mdfilters - 使用并将
BOX_UPDATE_FILE设置为lock可解除锁定(仅原生API支持)null - 元数据查询的字段格式:
from或enterprise_{enterprise_id}.templateKeyglobal.templateKey
Permissions
权限
- Deletions fail without sufficient permissions; always handle error responses
- Collaboration roles determine what operations are allowed
- Enterprise settings may restrict certain sharing options
- 权限不足时,删除操作会失败;请始终处理错误响应
- 协作角色决定了允许执行的操作
- 企业设置可能会限制某些共享选项
Quick Reference
快速参考
| Task | Tool Slug | Key Params |
|---|---|---|
| Search content | | |
| List folder items | | |
| Get file info | | |
| Get folder info | | |
| Upload file | | |
| Download file | | |
| Create folder | | |
| Update folder | | |
| Copy folder | | |
| Delete folder | | |
| Permanently delete folder | | folder_id |
| Update file | | |
| Delete file | | |
| List collaborations | | |
| Update collaboration | | |
| Get collaboration | | |
| Query by metadata | | |
| List collections | | (none) |
| List collection items | | |
| List sign requests | | |
| Get sign request | | |
| Cancel sign request | | |
| Recent items | | (none) |
| Create zip download | | item IDs |
Powered by Composio
| 任务 | 工具标识 | 关键参数 |
|---|---|---|
| 搜索内容 | | |
| 列出文件夹项目 | | |
| 获取文件信息 | | |
| 获取文件夹信息 | | |
| 上传文件 | | |
| 下载文件 | | |
| 创建文件夹 | | |
| 更新文件夹 | | |
| 复制文件夹 | | |
| 删除文件夹 | | |
| 永久删除文件夹 | | folder_id |
| 更新文件 | | |
| 删除文件 | | |
| 列出协作信息 | | |
| 更新协作 | | |
| 获取协作信息 | | |
| 按元数据查询 | | |
| 列出所有集合 | | (无) |
| 列出集合项目 | | |
| 列出签名请求 | | |
| 获取签名请求 | | |
| 取消签名请求 | | |
| 最近访问项目 | | (无) |
| 创建ZIP下载包 | | 项目ID |
由 Composio 提供支持