Box

Aperçu

Implémentez les workflows de contenu Box dans le code applicatif. Réutilisez le modèle d'authentification et la pile HTTP ou SDK existants du repository si possible, identifiez l'identité Box agissante avant de coder, et faites fonctionner le plus petit chemin bout à bout avant d'ajouter du partage, des métadonnées, des webhooks ou de l'IA.

Router la requête

Sélection d'outil

Après avoir complété l'étape 0 (inventaire d'outils), utilisez ce tableau pour choisir le bon outil pour l'opération :

MCP couvre la majorité des workflows d'agent courants et est le défaut quand il a un outil correspondant. Utilisez CLI quand l'opération sort du scope MCP, quand la sortie compacte et filtrée par champs importe, ou pour les commandes de vérification reproductibles. Si MCP est indisponible, guidez d'abord l'utilisateur dans la configuration MCP ; si CLI est indisponible, guidez-le ensuite dans la configuration CLI. Utilisez REST direct seulement en dernier recours après avoir demandé explicitement à l'utilisateur de confirmer que le fallback REST est acceptable.

Routage par domaine

Choisissez quels fichiers de référence lire selon ce dont l'utilisateur a besoin :

Workflow

Suivez ces étapes dans l'ordre quand vous codez contre Box.

0. Inventoriez le tooling Box disponible :
   • MCP : Appelez who_am_i. S'il échoue, essayez mcp_auth. Si l'authentification échoue toujours, lisez references/auth-and-setup.md pour les étapes de configuration MCP. Enregistrez si MCP est disponible.
   • CLI : Exécutez box users:get me --json. Enregistrez si CLI est disponible.
   • Si MCP est indisponible, guidez l'utilisateur dans la configuration MCP et réessayez l'authentification MCP avant de considérer d'autres outils.
   • Si CLI est indisponible, guidez l'utilisateur dans la configuration CLI et réessayez box users:get me --json.
   • Si MCP reste indisponible et CLI reste indisponible ou l'utilisateur refuse CLI, demandez une confirmation explicite avant d'utiliser le fallback REST direct. S'il est approuvé, utilisez references/rest-calls.md pour les modèles d'authentification et de requête.
   • Si la tâche consiste à construire du code applicatif (ajouter des endpoints SDK, des handlers de webhooks), la disponibilité d'outil est secondaire — passez à l'étape 1.
1. Inspectez le repository pour l'authentification Box existante, le client SDK ou HTTP, les variables env, les handlers de webhooks, la persistance d'ID Box et les tests.
2. Déterminez l'identité agissante avant de choisir les endpoints : utilisateur connecté, compte de service d'entreprise, utilisateur d'application ou token fourni par la plateforme.
3. Sélectionnez l'outil en utilisant le tableau de sélection d'outil et identifiez la référence de domaine en utilisant le tableau de routage par domaine ci-dessus.
4. Confirmez si la tâche change l'accès ou l'exposition des données. Les liens partagés, collaborations, changements d'authentification, téléchargements à grande échelle et récupération d'IA large ont tous besoin d'une confirmation explicite de l'utilisateur avant d'élargir l'accès ou le scope.
5. Lisez la référence pour l'outil sélectionné (references/mcp-tool-patterns.md pour MCP, references/box-cli.md pour CLI, references/rest-calls.md pour le fallback REST direct) et la référence de domaine du tableau de routage :
   • Modèles d'usage Box MCP : references/mcp-tool-patterns.md
   • Vérification locale Box CLI : references/box-cli.md
   • Modèles de fallback REST direct : references/rest-calls.md
   • Configuration d'authentification, sélection d'acteur, SDK vs REST : references/auth-and-setup.md
   • Routeur de workflow : references/workflows.md
   • Opérations de contenu : references/content-workflows.md
   • Organisation de fichiers en masse, déplacements par lot, restructuration de dossiers : references/bulk-operations.md
   • Webhooks et événements : references/webhooks-and-events.md
   • IA et récupération : references/ai-and-retrieval.md
   • Debug et modes de défaillance : references/troubleshooting.md
6. Implémentez le plus petit flux bout à bout qui prouve que l'intégration fonctionne.
7. Ajoutez une étape de vérification exécutable. Préférez d'abord les tests du repository ; sinon utilisez les commandes Box CLI natives quand CLI est disponible et authentifié. Utilisez la vérification REST Box directe seulement en dernier recours après confirmation explicite de l'utilisateur.
8. Résumez le livrable avec le contexte d'authentification, les ID Box, les variables env ou configuration, et la commande de vérification exacte ou le test.

Garde-fous

• Préservez le modèle d'authentification Box existant sauf si l'utilisateur demande explicitement de le modifier.
• Vérifiez la documentation officielle Box actuelle avant d'introduire un nouveau chemin d'authentification, de changer le scope d'authentification ou de changer le comportement de Box AI.
• Préférez un SDK Box officiel si la base de code l'utilise déjà ou si le langage cible a un SDK maintenu. Sinon, utilisez les appels REST directs avec une gestion explicite des requêtes et réponses.
• Dans les workflows d'agent, ne sautez pas directement à REST direct quand MCP ou CLI peut être configuré. Offrez un guide de configuration pour MCP d'abord et CLI ensuite avant de proposer le fallback REST.
• Ne jamais utiliser le fallback REST direct silencieusement. Demandez à l'utilisateur une confirmation explicite avant de procéder avec les appels REST.
• Gardez les tokens d'accès, secrets client, clés privées et secrets de webhooks dans des variables env ou le gestionnaire de secrets du projet.
• Distinguez les ID de fichier, ID de dossier, liens partagés, identifiants de modèle de métadonnées et ID de collaboration.
• Traitez les liens partagés, collaborations et écritures de métadonnées comme des changements sensibles aux permissions. Confirmez l'audience, le scope et le privilège minimal avant de coder ou de les appliquer.
• Demandez une confirmation explicite avant d'élargir l'accès externe, de changer l'identité agissante ou de récupérer plus de contenu de document que ce que la tâche nécessite vraiment.
• Quand une tâche nécessite de comprendre le contenu du document — classification, extraction, catégorisation — utilisez Box AI (Q&A, extract) comme première méthode tentée. Box AI opère côté serveur et ne nécessite pas de télécharger les corps de fichiers. Retournez à l'inspection de métadonnées, aperçus ou analyse locale seulement si Box AI est indisponible, non autorisé ou retourne une erreur à la première tentative.
• Cadencez les appels Box AI à au moins 1–2 secondes d'intervalle. Pour la classification basée sur le contenu de nombreux fichiers, classifiez d'abord un petit échantillon pour valider le prompt et découvrir si des signaux moins chers (nom de fichier, extension, métadonnées) peuvent trier les fichiers restants sans appels d'IA supplémentaires.
• Évitez de télécharger les corps de fichiers ou router le contenu via des pipelines d'IA externes quand les méthodes natives de Box (Box AI, recherche, métadonnées, aperçus) peuvent répondre à la question côté serveur.
• Demandez seulement les champs dont l'application a réellement besoin et persistez les ID Box retournés au lieu de reconstruire les chemins plus tard.
• Exécutez les commandes Box CLI strictement une à la fois. La CLI ne supporte pas les invocations concurrentes et les appels parallèles causent des conflits d'authentification et des opérations perdues. Pour le travail en masse dans les sessions pilotées par agent, par défaut à CLI et utilisez REST seulement après l'échec des tentatives de configuration MCP/CLI ou CLI n'est pas une option et l'utilisateur confirme explicitement le fallback REST.
• Rendez les consommateurs de webhooks et événements idempotents. Box livraison et les chemins de retry peuvent produire des doublons.
• Gardez la récupération d'IA étroite pour les tâches de recherche et Q&A. Recherchez et filtrez d'abord, puis récupérez seulement les fichiers nécessaires pour la réponse. Cela ne s'applique pas à la classification Box AI — quand vous classifiez des documents, Box AI doit être essayé d'abord selon le garde-fou de compréhension de contenu ci-dessus.
• Ne pas utiliser box configure:environments:get --current comme vérification d'authentification de routine car cela peut imprimer des détails d'environnement sensibles.

Vérification

• Préférez les tests existants du repository ou les flux d'application quand ils couvrent déjà le comportement Box modifié.
• S'il n'existe pas de meilleur chemin de vérification, préférez les commandes box CLI natives quand box est installé et authentifié.
• Utilisez la vérification REST directe seulement après avoir confirmé que MCP et CLI sont indisponibles ou non viables et après que l'utilisateur a explicitement approuvé le fallback REST.
• Pour le fallback REST, guidez l'utilisateur dans la configuration de token (BOX_ACCESS_TOKEN) et la gestion d'authentification sûre avant d'émettre des requêtes.
• Confirmez l'authentification CLI avec box users:get me --json.
• Vérifiez les mutations avec un appel lecture-après-écriture utilisant le même acteur et enregistrez l'ID d'objet.
• Pour les webhooks, testez le chemin heureux minimal, la livraison dupliquée et la gestion de défaillance de signature.
• Pour les flux d'IA, testez la qualité de récupération séparément du formatage de réponse.

Exemples de vérifications de santé :

box users:get me --json
box folders:get 0 --json --fields id,name,item_collection
box folders:items 0 --json --max-items 20
box search "invoice" --json --limit 10
curl -sS -H "Authorization: Bearer $BOX_ACCESS_TOKEN" -H "Accept: application/json" "https://api.box.com/2.0/folders/0?fields=id,name,item_collection"

Livrable

La réponse finale doit inclure :

• Contexte d'authentification agissant utilisé pour le changement
• Type d'objet Box et ID touchés
• Variables env, secrets ou configuration attendus par l'intégration
• Fichiers ou endpoints ajoutés ou modifiés
• Commande, script ou chemin de test de vérification exact
• Toute hypothèse sensible aux permissions qui nécessite toujours une confirmation

Références

• references/mcp-tool-patterns.md : modèles de bonnes pratiques pour travailler avec le contenu Box via le serveur MCP Box — recherche, écritures de fichiers, extraction de métadonnées, sélection d'outil Box AI et directives générales
• references/auth-and-setup.md : sélection de chemin d'authentification, choix SDK vs REST, inspection de base de code existante et ancres de doc Box actuelles
• references/box-cli.md : authentification locale CLI en premier, commandes de vérification de santé et modèles de vérification sûrs
• references/rest-calls.md : modèles de fallback REST direct, configuration d'authentification et modèles de requête sûrs
• references/workflows.md : routeur de workflow rapide quand la tâche est ambiguë
• references/content-workflows.md : uploads, dossiers, listes, téléchargements, liens partagés, collaborations, métadonnées et déplacements de fichiers
• references/bulk-operations.md : organisation de fichiers à l'échelle, déplacements par lot, création de hiérarchie de dossiers, exécution en série et gestion de limite de débit
• references/webhooks-and-events.md : configuration de webhook, utilisation de flux d'événements, idempotence et vérification
• references/ai-and-retrieval.md : récupération axée sur la recherche, utilisation de Box AI et garde-fous d'IA externe
• references/troubleshooting.md : modes de défaillance courants et liste de vérification de debug
• examples/box-prompts.md : exemples de prompts pour les cas d'usage réalistes