Box Automation

1---
2name: box-automation
3description: "Automate Box cloud storage operations including file upload/download, search, folder management, sharing, collaborations, and metadata queries via Rube MCP (Composio). Always search tools first for current schemas."
4requires:
5  mcp: [rube]
6---
7 
8# Box Automation via Rube MCP
9 
10Automate Box operations including file upload/download, content search, folder management, collaboration, metadata queries, and sign requests through Composio's Box toolkit.
11 
12## Prerequisites
13 
14- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
15- Active Box connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `box`
16- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
17 
18## Setup
19 
20**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
21 
22 
231. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
242. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `box`
253. If connection is not ACTIVE, follow the returned auth link to complete Box OAuth
264. Confirm connection status shows ACTIVE before running any workflows
27 
28## Core Workflows
29 
30### 1. Upload and Download Files
31 
32**When to use**: User wants to upload files to Box or download files from it
33 
34**Tool sequence**:
351. `BOX_SEARCH_FOR_CONTENT` - Find the target folder if path is unknown [Prerequisite]
362. `BOX_GET_FOLDER_INFORMATION` - Verify folder exists and get folder_id [Prerequisite]
373. `BOX_LIST_ITEMS_IN_FOLDER` - Browse folder contents and discover file IDs [Optional]
384. `BOX_UPLOAD_FILE` - Upload a file to a specific folder [Required for upload]
395. `BOX_DOWNLOAD_FILE` - Download a file by file_id [Required for download]
406. `BOX_CREATE_ZIP_DOWNLOAD` - Bundle multiple files/folders into a zip [Optional]
41 
42**Key parameters**:
43- `parent_id`: Folder ID for upload destination (use `"0"` for root folder)
44- `file`: FileUploadable object with `s3key`, `mimetype`, and `name` for uploads
45- `file_id`: Unique file identifier for downloads
46- `version`: Optional file version ID for downloading specific versions
47- `fields`: Comma-separated list of attributes to return
48 
49**Pitfalls**:
50- Uploading to a folder with existing filenames can trigger conflict behavior; decide overwrite vs rename semantics
51- Files over 50MB should use chunk upload APIs (not available via standard tools)
52- The `attributes` part of upload must come before the `file` part or you get HTTP 400 with `metadata_after_file_contents`
53- File IDs and folder IDs are numeric strings extractable from Box web app URLs (e.g., `https://*.app.box.com/files/123` gives file_id `"123"`)
54 
55### 2. Search and Browse Content
56 
57**When to use**: User wants to find files, folders, or web links by name, content, or metadata
58 
59**Tool sequence**:
601. `BOX_SEARCH_FOR_CONTENT` - Full-text search across files, folders, and web links [Required]
612. `BOX_LIST_ITEMS_IN_FOLDER` - Browse contents of a specific folder [Optional]
623. `BOX_GET_FILE_INFORMATION` - Get detailed metadata for a specific file [Optional]
634. `BOX_GET_FOLDER_INFORMATION` - Get detailed metadata for a specific folder [Optional]
645. `BOX_QUERY_FILES_FOLDERS_BY_METADATA` - Search by metadata template values [Optional]
656. `BOX_LIST_RECENTLY_ACCESSED_ITEMS` - List recently accessed items [Optional]
66 
67**Key parameters**:
68- `query`: Search string supporting operators (`""` exact match, `AND`, `OR`, `NOT` - uppercase only)
69- `type`: Filter by `"file"`, `"folder"`, or `"web_link"`
70- `ancestor_folder_ids`: Limit search to specific folders (comma-separated IDs)
71- `file_extensions`: Filter by file type (comma-separated, no dots)
72- `content_types`: Search in `"name"`, `"description"`, `"file_content"`, `"comments"`, `"tags"`
73- `created_at_range` / `updated_at_range`: Date filters as comma-separated RFC3339 timestamps
74- `limit`: Results per page (default 30)
75- `offset`: Pagination offset (max 10000)
76- `folder_id`: For `LIST_ITEMS_IN_FOLDER` (use `"0"` for root)
77 
78**Pitfalls**:
79- Queries with offset > 10000 are rejected with HTTP 400
80- `BOX_SEARCH_FOR_CONTENT` requires either `query` or `mdfilters` parameter
81- Misconfigured filters can silently omit expected items; validate with small test queries first
82- Boolean operators (`AND`, `OR`, `NOT`) must be uppercase
83- `BOX_LIST_ITEMS_IN_FOLDER` requires pagination via `marker` or `offset`/`usemarker`; partial listings are common
84- Standard folders sort items by type first (folders before files before web links)
85 
86### 3. Manage Folders
87 
88**When to use**: User wants to create, update, move, copy, or delete folders
89 
90**Tool sequence**:
911. `BOX_GET_FOLDER_INFORMATION` - Verify folder exists and check permissions [Prerequisite]
922. `BOX_CREATE_FOLDER` - Create a new folder [Required for create]
933. `BOX_UPDATE_FOLDER` - Rename, move, or update folder settings [Required for update]
944. `BOX_COPY_FOLDER` - Copy a folder to a new location [Optional]
955. `BOX_DELETE_FOLDER` - Move folder to trash [Required for delete]
966. `BOX_PERMANENTLY_REMOVE_FOLDER` - Permanently delete a trashed folder [Optional]
97 
98**Key parameters**:
99- `name`: Folder name (no `/`, `\`, trailing spaces, or `.`/`..`)
100- `parent__id`: Parent folder ID (use `"0"` for root)
101- `folder_id`: Target folder ID for operations
102- `parent.id`: Destination folder ID for moves via `BOX_UPDATE_FOLDER`
103- `recursive`: Set `true` to delete non-empty folders
104- `shared_link`: Object with `access`, `password`, `permissions` for creating shared links on folders
105- `description`, `tags`: Optional metadata fields
106 
107**Pitfalls**:
108- `BOX_DELETE_FOLDER` moves to trash by default; use `BOX_PERMANENTLY_REMOVE_FOLDER` for permanent deletion
109- Non-empty folders require `recursive: true` for deletion
110- Root folder (ID `"0"`) cannot be copied or deleted
111- Folder names cannot contain `/`, `\`, non-printable ASCII, or trailing spaces
112- Moving folders requires setting `parent.id` via `BOX_UPDATE_FOLDER`
113 
114### 4. Share Files and Manage Collaborations
115 
116**When to use**: User wants to share files, manage access, or handle collaborations
117 
118**Tool sequence**:
1191. `BOX_GET_FILE_INFORMATION` - Get file details and current sharing status [Prerequisite]
1202. `BOX_LIST_FILE_COLLABORATIONS` - List who has access to a file [Required]
1213. `BOX_UPDATE_COLLABORATION` - Change access level or accept/reject invitations [Required]
1224. `BOX_GET_COLLABORATION` - Get details of a specific collaboration [Optional]
1235. `BOX_UPDATE_FILE` - Create shared links, lock files, or update permissions [Optional]
1246. `BOX_UPDATE_FOLDER` - Create shared links on folders [Optional]
125 
126**Key parameters**:
127- `collaboration_id`: Unique collaboration identifier
128- `role`: Access level (`"editor"`, `"viewer"`, `"co-owner"`, `"owner"`, `"previewer"`, `"uploader"`, `"viewer uploader"`, `"previewer uploader"`)
129- `status`: `"accepted"`, `"pending"`, or `"rejected"` for collaboration invites
130- `file_id`: File to share or manage
131- `lock__access`: Set to `"lock"` to lock a file
132- `permissions__can__download`: `"company"` or `"open"` for download permissions
133 
134**Pitfalls**:
135- Only certain roles can invite collaborators; insufficient permissions cause authorization errors
136- `can_view_path` increases load time for the invitee's "All Files" page; limit to 1000 per user
137- Collaboration expiration requires enterprise admin settings to be enabled
138- Nested parameter names use double underscores (e.g., `lock__access`, `parent__id`)
139 
140### 5. Box Sign Requests
141 
142**When to use**: User wants to manage document signature requests
143 
144**Tool sequence**:
1451. `BOX_LIST_BOX_SIGN_REQUESTS` - List all signature requests [Required]
1462. `BOX_GET_BOX_SIGN_REQUEST_BY_ID` - Get details of a specific sign request [Optional]
1473. `BOX_CANCEL_BOX_SIGN_REQUEST` - Cancel a pending sign request [Optional]
148 
149**Key parameters**:
150- `sign_request_id`: UUID of the sign request
151- `shared_requests`: Set `true` to include requests where user is a collaborator (not owner)
152- `senders`: Filter by sender emails (requires `shared_requests: true`)
153- `limit` / `marker`: Pagination parameters
154 
155**Pitfalls**:
156- Requires Box Sign to be enabled for the enterprise account
157- Deleted sign files or parent folders cause requests to not appear in listings
158- Only the creator can cancel a sign request
159- Sign request statuses include: `converting`, `created`, `sent`, `viewed`, `signed`, `declined`, `cancelled`, `expired`, `error_converting`, `error_sending`
160 
161## Common Patterns
162 
163### ID Resolution
164Box uses numeric string IDs for all entities:
165- **Root folder**: Always ID `"0"`
166- **File ID from URL**: `https://*.app.box.com/files/123` gives file_id `"123"`
167- **Folder ID from URL**: `https://*.app.box.com/folder/123` gives folder_id `"123"`
168- **Search to ID**: Use `BOX_SEARCH_FOR_CONTENT` to find items, then extract IDs from results
169- **ETag**: Use `if_match` with file's ETag for safe concurrent delete operations
170 
171### Pagination
172Box supports two pagination methods:
173- **Offset-based**: Use `offset` + `limit` (max offset 10000)
174- **Marker-based**: Set `usemarker: true` and follow `marker` from responses (preferred for large datasets)
175- Always paginate to completion to avoid partial results
176 
177### Nested Parameters
178Box tools use double underscore notation for nested objects:
179- `parent__id` for parent folder reference
180- `lock__access`, `lock__expires__at`, `lock__is__download__prevented` for file locks
181- `permissions__can__download` for download permissions
182 
183## Known Pitfalls
184 
185### ID Formats
186- All IDs are numeric strings (e.g., `"123456"`, not integers)
187- Root folder is always `"0"`
188- File and folder IDs can be extracted from Box web app URLs
189 
190### Rate Limits
191- Box API has per-endpoint rate limits
192- Search and list operations should use pagination responsibly
193- Bulk operations should include delays between requests
194 
195### Parameter Quirks
196- `fields` parameter changes response shape: when specified, only mini representation + requested fields are returned
197- Search requires either `query` or `mdfilters`; both are optional individually but one must be present
198- `BOX_UPDATE_FILE` with `lock` set to `null` removes the lock (raw API only)
199- Metadata query `from` field format: `enterprise_{enterprise_id}.templateKey` or `global.templateKey`
200 
201### Permissions
202- Deletions fail without sufficient permissions; always handle error responses
203- Collaboration roles determine what operations are allowed
204- Enterprise settings may restrict certain sharing options
205 
206## Quick Reference
207 
208| Task | Tool Slug | Key Params |
209|------|-----------|------------|
210| Search content | `BOX_SEARCH_FOR_CONTENT` | `query`, `type`, `ancestor_folder_ids` |
211| List folder items | `BOX_LIST_ITEMS_IN_FOLDER` | `folder_id`, `limit`, `marker` |
212| Get file info | `BOX_GET_FILE_INFORMATION` | `file_id`, `fields` |
213| Get folder info | `BOX_GET_FOLDER_INFORMATION` | `folder_id`, `fields` |
214| Upload file | `BOX_UPLOAD_FILE` | `file`, `parent_id` |
215| Download file | `BOX_DOWNLOAD_FILE` | `file_id` |
216| Create folder | `BOX_CREATE_FOLDER` | `name`, `parent__id` |
217| Update folder | `BOX_UPDATE_FOLDER` | `folder_id`, `name`, `parent` |
218| Copy folder | `BOX_COPY_FOLDER` | `folder_id`, `parent__id` |
219| Delete folder | `BOX_DELETE_FOLDER` | `folder_id`, `recursive` |
220| Permanently delete folder | `BOX_PERMANENTLY_REMOVE_FOLDER` | folder_id |
221| Update file | `BOX_UPDATE_FILE` | `file_id`, `name`, `parent__id` |
222| Delete file | `BOX_DELETE_FILE` | `file_id`, `if_match` |
223| List collaborations | `BOX_LIST_FILE_COLLABORATIONS` | `file_id` |
224| Update collaboration | `BOX_UPDATE_COLLABORATION` | `collaboration_id`, `role` |
225| Get collaboration | `BOX_GET_COLLABORATION` | `collaboration_id` |
226| Query by metadata | `BOX_QUERY_FILES_FOLDERS_BY_METADATA` | `from`, `ancestor_folder_id`, `query` |
227| List collections | `BOX_LIST_ALL_COLLECTIONS` | (none) |
228| List collection items | `BOX_LIST_COLLECTION_ITEMS` | `collection_id` |
229| List sign requests | `BOX_LIST_BOX_SIGN_REQUESTS` | `limit`, `marker` |
230| Get sign request | `BOX_GET_BOX_SIGN_REQUEST_BY_ID` | `sign_request_id` |
231| Cancel sign request | `BOX_CANCEL_BOX_SIGN_REQUEST` | `sign_request_id` |
232| Recent items | `BOX_LIST_RECENTLY_ACCESSED_ITEMS` | (none) |
233| Create zip download | `BOX_CREATE_ZIP_DOWNLOAD` | item IDs |
234