Intégration CLI, MCP et A2A

Les agents locaux comme Codex et WorkBuddy utilisent OpenFiles via MCP ou CLI + Skill. Ces interfaces partagent les capacités et les tâches avec A2A. Pour un usage courant, installez le CLI et lancez setup ci-dessous. A2A est destiné aux clients personnalisés : /a2a n’est pas une URL MCP et le processus appelant doit fonctionner sur le même ordinateur.

Installer le CLI

Il faut Node.js 22 ou ultérieur et une version de bureau contenant resources/agent. Le CLI est fourni avec l’application ; installez-le une fois depuis ce dossier local. Pour l’emplacement macOS par défaut :

npm install -g "/Applications/OpenFiles.app/Contents/Resources/agent"

Sous Windows, utilisez PowerShell et remplacez le chemin par le dossier resources\agent de votre installation :

npm install -g "C:\path\to\OpenFiles\resources\agent"

Pour développer depuis les sources, exécutez npm run build, puis npm install -g ./dist/agent dans le dépôt. La commande openfiles remplace ensuite le chemin complet du script.

Connecter Codex

Cette commande démarre OpenFiles ou s’y connecte, enregistre MCP avec le CLI Codex et installe le Skill dans ~/.agents/skills/openfiles. La commande codex doit être disponible. Redémarrez ensuite Codex pour charger la configuration.

openfiles setup codex

Connecter WorkBuddy

Cette commande démarre OpenFiles ou s’y connecte et ajoute le serveur à ~/.workbuddy/mcp.json, en conservant les autres serveurs et une sauvegarde de la configuration précédente. Redémarrez WorkBuddy. Pour CLI + Skill, vous pouvez aussi importer le ZIP skillArchive indiqué dans l’interface d’import des Skills. MCP est déjà utilisable.

openfiles setup workbuddy

Le premier setup crée et autorise ~/OpenFilesAgent, avec les résultats dans son sous-dossier output. Placez-y les fichiers et demandez par exemple à votre agent d’exporter un CDR en ZIP de toutes les pages SVG avec OpenFiles, puis d’attendre la fin et de donner le chemin. Utilisez --workspace DIR pour un dossier existant et --output DIR pour la sortie. --dry-run affiche seulement les chemins de configuration.

Les autorisations et le chemin du bureau sont enregistrés dans ~/.openfiles/agent/setup.json. Les appels CLI, MCP et Skill démarrent ensuite le bureau avec cette configuration et lisent automatiquement l’adresse et le token actuels. Aucun port ou token fixe dans la configuration cliente. Pour changer les autorisations d’une passerelle active, quittez OpenFiles puis relancez setup ; les tâches ne sont pas interrompues de force.

Références officielles : Codex MCP · WorkBuddy MCP

Vérifier la connexion et résoudre les problèmes

doctor vérifie la connexion sans démarrer l’application ; capabilities démarre le bureau configuré. schema décrit les arguments hors ligne. L’état MCP connecté confirme seulement le démarrage de l’adaptateur : appelez capabilities pour vérifier le service de fichiers.

openfiles doctor
openfiles capabilities
openfiles schema openfiles_convert

Si le bureau est introuvable, indiquez son exécutable avec setup codex --app /absolute/path/to/OpenFiles, en remplaçant le client pour WorkBuddy. Après un déplacement de Node.js ou de l’application, réinstallez le CLI puis relancez setup. Vérifiez readRoots / outputRoots en cas d’erreur de dossier. Consultez tasks avant de renvoyer une écriture au résultat incertain.

Activer la passerelle manuellement (facultatif)

Utilisez une version contenant resources/agent/openfiles.cjs (dans OpenFiles.app/Contents/Resources sur macOS), avec Node.js 22 ou ultérieur pour le client. Lancez OpenFiles avec --agent-read-root=/absolute/input --agent-output-root=/absolute/output. Les deux dossiers doivent exister ; répétez les options pour plusieurs autorisations. La passerelle est désactivée par défaut. Quittez et relancez pour changer les autorisations. Depuis les sources, utilisez :

npm run build-electron
npm run agent -- capabilities
npm run agent -- mcp-config
npm run agent -- skill

Découvrir et exécuter les opérations

Consultez d’abord capabilities : conversionFormats donne les paires de conversion et metadata.formats les champs modifiables. openfiles_inspect fournit les cibles propres au fichier. HTML, Markdown et SVG peuvent produire PNG/PDF sans scripts ni ressources externes. CDR produit un ZIP de toutes les pages SVG. openfiles_workflow exécute les .ofw enregistrés ; sourcePaths remplace les entrées fichiers, tandis que dossiers batch et masques doivent aussi être autorisés. PDF/OFD utilisent metadata.edit ou metadata.remove. Les nœuds IA nécessitent les moteurs installés et peuvent télécharger des modèles. Enregistrez ceci dans request.json en remplaçant les chemins :

JPEG et JPEG radiométrique partagent les extensions. Avec contentDetectionRequired, les cibles sont des candidates ; le moteur valide le contenu à l’exécution.

{"sourcePaths":["/input/design.cdr"],"outputDir":"/output","format":"zip"}

node dist/agent/openfiles.cjs call openfiles_convert --input request.json --wait

Suivre et retrouver les tâches

Les écritures préservent les originaux et créent un dossier openfiles-* sous outputDir. Interrogez jusqu’à completed, failed ou canceled, puis vérifiez result.paths et les erreurs individuelles. --wait attend 300 secondes par défaut, modifiables avec --timeout. La tâche continue après expiration. Retrouvez son ID avec tasks avant de la soumettre à nouveau. La liste accepte --json ou --input avec state, contextId, pageSize, pageToken ; récupérez la tâche individuelle pour les sorties. La passerelle conserve au plus 100 tâches, dont huit simultanées. Le redémarrage efface l’historique ; l’annulation garde les sorties terminées.

node dist/agent/openfiles.cjs tasks
node dist/agent/openfiles.cjs task TASK_ID --wait
node dist/agent/openfiles.cjs cancel TASK_ID

Connecter MCP et installer le Skill

mcp-config affiche la configuration sans la modifier. Enregistrez la commande et les arguments dans le client externe. mcp utilise JSON-RPC par lignes sur stdio ; skill affiche le guide fourni. Le descripteur est ~/.openfiles/agent/connection.json. Pour un chemin personnalisé, associez --agent-connection=PATH côté bureau et --connection PATH côté client. Gardez le jeton bearer privé. Remplacez si nécessaire dist/agent/openfiles.cjs par le chemin du client installé. Les serveurs MCP sortants du chat sont configurés séparément.

Appeler A2A

Lisez l’URL de boucle locale du descripteur, puis /.well-known/agent-card.json. securityRequirements déclare l’authentification bearer. Envoyez le JSON suivant en POST à /a2a avec Content-Type: application/json, A2A-Version: 1.0, Authorization: Bearer <token>. Réutilisez le même ID et le même message lors d’une nouvelle tentative réseau. Appelez GetTask avec { "id": "TASK_ID" } ou CancelTask. ListTasks accepte contextId, status, statusTimestampAfter, pagination et includeArtifacts. Streaming, notifications push et planification en langage naturel sont indisponibles. Les chemins sont locaux ; édition des captures et installation des plugins restent des actions du bureau.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "unique-request-id",
      "role": "ROLE_USER",
      "parts": [{"data": {"name": "openfiles_capabilities", "arguments": {}}}]
    },
    "configuration": {"returnImmediately": true}
  }
}