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. 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：アップロード用の s3key、mimetype、name を含む FileUploadable オブジェクト
• 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 は招待されたユーザーの「すべてのファイル」ページの読み込み時間を増加させます。ユーザーあたり最大 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 は 2 種類のページネーション方式をサポートしています：

• オフセットベース：offset と limit を使用します（offset の最大値は 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 のいずれかが必要です。それぞれ単独では省略できますが、どちらか一方は指定する必要があります
• lock を null に設定した BOX_UPDATE_FILE は、ロックを解除します（raw 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 提供