box-automation

Rube MCP による Box の自動化

Composio の Box ツールキットを使用して、ファイルのアップロード／ダウンロード、コンテンツ検索、フォルダー管理、コラボレーション、メタデータのクエリ、署名リクエストなど、Box の操作を自動化します。

前提条件

• Rube MCP が接続されていること（RUBE_SEARCH_TOOLS が利用可能）
• box ツールキットを指定した RUBE_MANAGE_CONNECTIONS による有効な Box 接続
• 最新のツールスキーマを取得するため、必ず最初に RUBE_SEARCH_TOOLS を呼び出すこと

セットアップ

既存の承認済み Rube 接続を使用します。エンドポイントの設定だけでは Box の認証は行われません。要求された範囲内で、サポートされているホスト認証フローを使用してください。

1. RUBE_SEARCH_TOOLS が応答することを確認し、Rube MCP が利用可能であることを確認します
2. ツールキットに box を指定して RUBE_MANAGE_CONNECTIONS を呼び出します
3. 接続が ACTIVE でない場合は、返された認証リンクに従って Box OAuth を完了します
4. ワークフローを実行する前に、接続ステータスが ACTIVE であることを確認します

これらのスラッグやデフォルト値は過去の例として扱い、操作には検出されたスキーマを適用してください。書き込みを要求された場合は、対象の企業／アカウント、ファイル／フォルダー／バージョン、保存先、共有範囲を正確に確認してください。コラボレーションの変更や署名リクエストは、他のユーザーに通知したり、義務を変更したりする可能性があるため、その操作範囲の承認を得てください。デフォルトでは公開リンクを避け、ダウンロード URL を保護し、変更が不確かな場合は再試行する前に状態を照合してください。

主なワークフロー

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" に設定します
• ダウンロード権限については、現在のスキーマを確認してください。"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 は数値文字列です。Sign リクエストなど、その他のエンティティでは UUID が使われる場合があります。返された識別子はそれぞれそのまま保持してください。

• ルートフォルダー：常に 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 は数値文字列です。その他のエンティティ ID を数値に変換しないでください
• ルートフォルダーは常に "0" です
• Box の Web アプリの URL からファイル ID とフォルダー ID を抽出できます

レート制限

• 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 の Box ツールキットを通じて、ファイルのアップロード／ダウンロード、コンテンツ検索、フォルダー管理、コラボレーション、メタデータクエリ、署名リクエストなどの Box 操作を自動化してください。

制限事項

• このスキルは、タスクが上記の説明の範囲に明確に該当する場合にのみ使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中断して確認してください。