box

Box

概要

Box に関するあらゆるタスクの基盤となるスキルです。リクエストを適切なツール（MCP、CLI、REST）と適切なドメインリファレンスに振り分けます。次の用途に使用します。

• 利用可能な Box ツールを確認し（MCP → CLI → REST）、不足しているものをセットアップします。
• 以下のツール選択表を使って、操作に適したツールを選びます。
• ユーザーのドメインを扱うリファレンスファイルを特定します。
• よくある Box エラー（401/403/404/409/429、コンテンツの欠落、アクターの不一致）を診断します。

CLI の使用が明示的にリクエストされた場合は、インストールされていれば box-cli を使用してください。それ以外の場合は、以下のツール選択とドメインの振り分けに従ってください。

リクエストの振り分け

ツールの選択

ツールが指定されていないリクエストについては、利用可能かどうかを確認し、次の表を使用してください。

操作の種類	優先するツール	理由
ほとんどのエージェントワークフロー（検索、AI、コンテンツ管理、メタデータ、ハブ）	MCP	構造化された入出力、並行処理に対応し、一般的なケースを網羅します
一括操作（複数の移動、フォルダーツリー、一括メタデータ）	CLI	コンパクトな出力、--fields によるフィルタリング、REST 認証を手動で設定することなく API 全体を利用できます
検証とスモークテスト	CLI	再現性があり、ユーザーがコマンドをコピーして実行できます
MCP の対象範囲外の操作	CLI	API 全体を利用できます
MCP が利用できず、CLI も利用できない、または選択肢にならない場合の最終手段	直接 REST	ユーザーの明示的な確認と REST 認証のセットアップ手順を案内した後に限ります
アプリケーションコードの作成（SDK／REST エンドポイント、Webhook ハンドラー）	コード内の SDK または REST	エージェント用ツールではありません。ユーザーがリリースするコードを作成します

CLI の使用が明示的にリクエストされた場合は、CLI が利用可能か確認し、CLI のセットアップ手順に従ってください。それ以外のリクエストでは、まず MCP のセットアップを案内し、次に CLI のセットアップを案内してください。直接 REST を使用するのは、ユーザーが代替手段として許容できることを明示的に確認した後に限ります。

ドメインの振り分け

ユーザーのニーズに応じて、読み込むリファレンスファイルを選択してください。

ユーザーのニーズ	最初に読む	組み合わせる	最小限の検証
アップロード、フォルダー、一覧表示、ダウンロード、プレビュー、移動、メタデータ	references/content-workflows.md	references/auth-and-setup.md	同じアクターで書き込み後に読み取る
共有、コラボレーション（ユーザー／グループ）、共有リンク	references/collaboration.md	references/content-workflows.md、references/auth-and-setup.md	変更の前後にコラボレーションを一覧表示する
ファイルまたはフォルダーの検索（キーワード、フォルダー名、メタデータ検索）	references/mcp-search.md	references/auth-and-setup.md	操作前にアイテムの詳細を確認する
Box AI による質問応答、要約、抽出、ドキュメント検索	references/ai-and-retrieval.md	references/auth-and-setup.md	回答を整形する前に検索品質を確認する
Box Hubs — ハブの作成、キュレーション、クエリ	references/mcp-hubs.md	references/ai-and-retrieval.md、references/auth-and-setup.md	変更後にハブのアイテムを確認する
テンプレートからのドキュメント生成（Doc Gen）	references/mcp-doc-gen.md	references/content-workflows.md、references/auth-and-setup.md	一括処理の前にテンプレートと保存先を確認する
フォルダー間でのファイルの整理、再整理、一括移動、一括メタデータタグ付け、フォルダー構造の移行	references/bulk-operations.md	references/content-workflows.md、references/auth-and-setup.md、references/ai-and-retrieval.md	ソースを一覧化し、移動数が計画と一致することを確認する
イベント駆動の取り込み、新規ファイルのトリガー、Webhook のデバッグ	references/webhooks-and-events.md	references/auth-and-setup.md、references/troubleshooting.md	署名の確認と重複配信テスト
401、403、404、409、429、コンテンツの欠落、アクター不一致のバグ	references/troubleshooting.md	references/auth-and-setup.md	正確なアクター、オブジェクト ID、エンドポイントを使って再現する
どのワークフローが当てはまるかわからない場合	references/workflows.md	references/auth-and-setup.md	まず、最小の Box オブジェクト／アクションの組み合わせを選ぶ

MCP

Box MCP サーバーは、エージェントのワークフローで標準となるツールです。構造化された入出力を提供し、並行処理にも安全で、一般的なユースケース（検索、Box AI、コンテンツ管理、メタデータ、ハブ）に対応しています。CLI または REST よりも MCP を優先すべきケースについては、上記のツール選択表を参照してください。

利用可能かどうかの確認

• who_am_i を呼び出します。失敗した場合は、クライアントが提供する MCP OAuth フローを完了してから再試行します。
• 認証に引き続き失敗する場合は、references/auth-and-setup.md を読んで MCP のセットアップ手順を確認し、他のツールを検討する前にユーザーのセットアップを支援します。
• MCP が利用可能かどうかを記録します。

ツールの利用可否とドキュメント

Box MCP ツールの最新かつメンテナンスされている一覧は、https://docs.box.com/en/box-mcp/tools に記載されています。想定しているツールが見つからない、または利用できない場合は、診断手順と管理コンソールでの有効化について、references/troubleshooting.md の「MCP tool missing」セクションを参照してください。

一般的なガイドライン

• フォルダーの内容を一覧表示する際は、必要に応じてページネーションを行い、大きなディレクトリではすべての項目を表示するのではなく要約します。
• ファイルを操作する前に、get_file_details でファイルの詳細を確認することを優先します。ファイルの存在を確認し、現在の状態を把握できます。
• 調査やデモで使用する場合は、ユーザーの Box アカウント全体を操作するのではなく、専用フォルダー内で作業することを優先します。
• 企業全体にわたる広範なアクセス権を付与したり、あるものと想定したりしないでください。最小権限をデフォルトとし、タスクに必要なフォルダーとファイルにのみアクセスします。

使用方法

Box MCP の機能は、目的別のリファレンスファイルに記載されています。タスクに適したファイルを選ぶには、上記のドメイン別ルーティング表を参照してください。

MCP カテゴリ	リファレンス
ファイル、フォルダー、アップロード、ダウンロード、プレビュー、メタデータ	references/content-workflows.md
検索（キーワード、フォルダー、メタデータ）	references/mcp-search.md
コラボレーション（ユーザー／グループ）と共有リンク	references/collaboration.md
Box AI の Q&A、抽出、構造化メタデータ抽出、エージェント	references/ai-and-retrieval.md
Box Hubs の作成、アイテム管理、ハブレベルの Q&A	references/mcp-hubs.md
Box Doc Gen のテンプレートとドキュメント生成バッチ	references/mcp-doc-gen.md

CLI / REST API

CLI または直接 REST を利用するタイミングは、上記のツール選択表に従います。ツールが指定されていないリクエストでは、MCP、CLI、直接 REST の順に優先します。直接 REST は、ユーザーの明示的な確認を得た後に限る最後の手段です。

CLI

利用可能かどうかの確認

• box users:get me --json を実行します。CLI が利用可能かどうかを記録します。
• CLI が利用できない場合は、CLI のセットアップをユーザーに案内し、box users:get me --json を再試行します。

使用方法

• CLI を優先した認証、スモークテスト用コマンド、安全な検証パターン、並行処理に関する注意事項については、references/box-cli.md を読んでください。

REST API

ツール選択表に従い、直接 REST は最後の手段です。MCP と CLI の両方が利用できない、またはユーザーが利用を断った場合に限ります。

ユーザーがリリースするアプリケーションコード（SDK／REST エンドポイント、Webhook ハンドラー）の構築は別のケースです。これはエージェント用ツールではなく、作成するコードです。コードベースに公式 Box SDK がすでに存在する場合、または対象言語向けの SDK がある場合は、そちらを優先してください。 SDK を使用したアプリケーションコードには、インストールされている場合は独立した box-sdk-development スキルを使用してください。バージョン固有の呼び出し、転送方法の選択、バルクジョブ、再試行、オブザーバビリティを扱っています。

確認とセットアップ

• 直接 REST へのフォールバックを、ユーザーに知らせずに使用してはいけません。実行に移る前に、ユーザーに明示的な確認を求めてください。
• リクエストを送信する前に、トークンのセットアップ（BOX_ACCESS_TOKEN）と安全な認証情報の取り扱いについてユーザーを案内してください。
• アクセストークン、クライアントシークレット、秘密鍵、Webhook シークレットは、環境変数またはプロジェクトのシークレットマネージャーに保管します。

使用方法

• 直接 REST へのフォールバックパターン、認証のセットアップ、安全なリクエストテンプレートについては、references/rest-calls.md を読んでください。

ワークフロー

Box を使用してコーディングする際は、次の手順を順番に実行します。

0. CLI の使用を明示的に求められた場合は、CLI が利用可能か確認し、インストールされていれば box-cli を使用し、そうでなければ references/box-cli.md を参照します。それ以外の依頼では、上記の MCP セクションと CLI / REST API セクションに記載された利用可否の確認手順を使用して、利用可能な Box ツールを調べます。まず MCP を確認し（who_am_i を実行し、必要に応じてクライアントが提供する OAuth を完了します）、次に CLI（box users:get me --json）を確認して、利用可能なツールを記録します。ツールが利用できない場合は、Route The Request に記載されたエスカレーションの順序に従います（MCP のセットアップ → CLI のセットアップ → 明示的な確認後に REST）。タスクがアプリケーションコードの構築（SDK エンドポイントや webhook ハンドラーの追加）の場合は、ツールの利用可否は優先事項ではありません。手順 1 に進んでください。
1. リポジトリを調査し、既存の Box 認証、SDK または HTTP クライアント、環境変数、webhook ハンドラー、Box ID の永続化、テストを確認します。
2. エンドポイントを選択する前に、操作主体の ID を特定します。接続済みユーザー、エンタープライズサービスアカウント、アプリユーザー、またはプラットフォーム提供のトークンのいずれかです。
3. ツール選択表を使用してツールを選び、上記のドメインルーティング表を使用してドメインリファレンスを特定します。
4. タスクによってアクセスやデータの公開範囲が変わるか確認します。共有リンク、コラボレーション、認証の変更、大規模なダウンロード、広範な AI 検索によってアクセスや範囲を拡大する場合は、事前にユーザーの明示的な確認が必要です。
5. 選択したツール（MCP、CLI、または REST）のリファレンスと、ツール選択表およびドメインルーティング表で特定したドメインリファレンスを読みます。各ファイルの対象範囲を注釈付きでまとめた一覧については、このファイル末尾の References セクションを参照してください。
6. 統合が機能することを示せる、最小限のエンドツーエンドのフローを実装します。
7. 実行可能な検証手順を追加します。まずリポジトリのテストを優先します。それ以外の場合は、CLI が利用可能で認証済みであれば、Box のネイティブ CLI コマンドを使用します。Box REST に直接アクセスして検証するのは、最後の手段として、ユーザーの明示的な確認後にのみ行ってください。
8. 認証コンテキスト、Box ID、環境変数または設定、実行する検証コマンドまたはテストを正確に含めて、成果物を要約します。

ガードレール

すべてのセッションで references/guardrails.md を読み、従ってください。 破壊的な操作、ハブの変更、ファイルへのコメント、Doc Gen の出力先、外部共有フォルダー、コンテンツの表示設定、Box AI のガバナンスに関する確認ゲートについて説明しています。

• ユーザーから明示的に変更を求められない限り、既存の Box 認証モデルを維持してください。
• 新しい認証経路を導入する場合、認証スコープを変更する場合、または Box AI の動作を変更する場合は、最新の Box 公式ドキュメントを確認してください。
• コードベースですでに公式 Box SDK を使用している場合、または対象言語に保守されている SDK がある場合は、それを優先してください。それ以外の場合は、リクエストとレスポンスを明示的に処理する直接 REST 呼び出しを使用してください。
• エージェントのワークフローでは、MCP または CLI をセットアップできる場合に、すぐ直接 REST に移行しないでください。REST の代替手段を提案する前に、まず MCP、次に CLI のセットアップ方法を案内してください。
• 直接 REST の代替手段を黙って使用してはいけません。REST 呼び出しを実行する前に、ユーザーに明示的な確認を求めてください。
• アクセストークン、クライアントシークレット、秘密鍵、Webhook シークレットは、環境変数またはプロジェクトのシークレットマネージャーに保管してください。
• ファイル ID、フォルダー ID、共有リンク、メタデータテンプレート識別子、コラボレーション ID を区別してください。
• 共有リンク、コラボレーション、メタデータへの書き込みは、権限に影響する変更として扱ってください。実装または適用する前に、対象者、スコープ、最小権限を確認してください。
• 外部アクセスの範囲を広げる場合、操作する ID を切り替える場合、またはタスクに本当に必要な量を超えるドキュメントコンテンツを取得する場合は、明示的な確認を求めてください。
• ドキュメントの内容を理解する必要があるタスクでは、最初に Box AI を試してください。Box AI はサーバー側で動作し、ダウンロードを必要としません。優先順位とフォールバックの全手順については、references/ai-and-retrieval.md を参照してください。
• Box AI の呼び出しは、少なくとも 1～2 秒間隔で行ってください。一括分類では、references/bulk-operations.md のサンプル優先方式を使用してください。
• Box ネイティブの方法（Box AI、検索、メタデータ、プレビュー）でサーバー側から質問に回答できる場合は、ファイル本文をダウンロードしたり、コンテンツを外部 AI パイプラインに渡したりしないでください。
• アプリケーションが実際に必要とするフィールドのみを要求し、後でパスを再構築するのではなく、返された Box ID を保存してください。
• 関連する CLI 書き込みは順番に実行し、予防策として、同じ OAuth 環境を共有するプロセスは直列化してください。詳細は references/box-cli.md を参照してください。一括処理では CLI を既定で使用し、MCP／CLI のセットアップを試して失敗した場合、またはユーザーが REST の代替手段を明示的に承認した場合にのみ REST を使用してください。
• Webhook とイベントのコンシューマーは冪等性を保ってください。Box の配信および再試行の経路では、重複が発生することがあります。
• 検索と Q&A のタスクでは、AI による取得範囲を絞ってください。まず検索とフィルタリングを行い、回答に必要なファイルのみを取得してください。ただし、これは Box AI による分類には適用されません。ドキュメントを分類する場合は、上記のコンテンツ理解に関するガードレールに従い、最初に Box AI を試してください。
• 定常的な認証チェックに box configure:environments:get --current を使用しないでください。機密性の高い環境情報が出力される可能性があります。

検証

• 変更した Box の動作をリポジトリに既存のテストやアプリのフローで検証できる場合は、それらを優先してください。
• より適切な検証方法がない場合は、box がインストールされ、認証済みであれば、ネイティブの box CLI コマンドを優先してください。
• MCP と CLI が利用できない、または選択肢にならないことを確認し、ユーザーが REST の代替手段を明示的に承認した後にのみ、直接 REST で検証してください。
• REST の代替手段を使う場合は、リクエストを実行する前に、トークンの設定（BOX_ACCESS_TOKEN）と安全な認証情報の取り扱いをユーザーに案内してください。
• box users:get me --json で CLI の認証を確認してください。
• 変更は同じ実行者による読み取り後の書き込み確認で検証し、オブジェクト ID を記録してください。
• Webhook では、最小限の正常系、重複配信、署名検証の失敗処理をテストしてください。
• AI のフローでは、取得品質と回答の書式設定を分けてテストしてください。

スモークテスト用コマンドの例については、references/box-cli.md（一般的な検証コマンド）を参照してください。

成果物

最終回答には、以下を含めてください。

• 変更に使用した認証コンテキスト
• 対象となった Box オブジェクトの種類と ID
• インテグレーションで必要となる環境変数、シークレット、または設定
• 追加または変更したファイルやエンドポイント
• 検証に使用した正確なコマンド、スクリプト、またはテストパス
• 確認が必要な、権限に関する前提条件

参考資料

• references/guardrails.md：Box MCP ツールの使用に関する必須の安全性とスコープの制約
• references/content-workflows.md：ファイルとフォルダー — アップロード、ダウンロード、プレビュー、フォルダーツリー、移動、メタデータ；MCP ツール + CLI/REST のパターン
• references/collaboration.md：共有とアクセス — コラボレーターのロール、共有リンク、外部共有のルール；MCP ツール + CLI/REST のパターン
• references/mcp-search.md：コンテンツの検索 — MCP によるキーワード、フォルダー名、メタデータの検索
• references/ai-and-retrieval.md：Box AI と検索拡張 — Q&A、抽出、エージェント、コンテンツ理解の優先順位；MCP ツール + CLI コマンド
• references/mcp-hubs.md：Box Hubs — MCP による作成、アイテム管理、ハブレベルの Q&A
• references/mcp-doc-gen.md：Box Doc Gen — MCP によるテンプレート登録とドキュメント生成
• references/bulk-operations.md：大規模なファイル整理 — 一括移動、フォルダー階層の作成、順次実行、レート制限への対応
• references/auth-and-setup.md：認証方式の選択、MCP サーバーのセットアップ、SDK と REST の選択、既存コードベースの確認、Box の最新ドキュメントへのアンカー
• references/box-cli.md：CLI 優先のローカル認証、スモークテストコマンド、安全な検証パターン
• references/rest-calls.md：REST への直接フォールバックのパターン、認証のセットアップ、安全なリクエストテンプレート
• references/webhooks-and-events.md：Webhook のセットアップ、イベントフィードの使用、冪等性、検証
• references/workflows.md：タスクが曖昧な場合に使用する、ワークフローのクイックルーター
• references/troubleshooting.md：よくある障害とデバッグ用チェックリスト