Partager un TUI en direct via MCP

Cette page est traduite de la documentation anglaise. Les commandes, identifiants et exemples sont inchangés. Runtime 7.24.4 · SDK 2.6.7. Source anglaise

Statut : expérimental Portée : public, état actuel Dernière revue : 2026-10-04 Responsable : mainteneurs d’AX Code

TUIMCP est un adaptateur MCP expérimental, sur activation, pour le TUI d’AX Code sur macOS et Linux. Il permet à un agent externe de lire un état d’interface borné et de naviguer dans le même TUI que vous utilisez. Windows n’est pas pris en charge dans cette version.

Démarrez un TUI avec un partage explicite :

ax-code --tui-mcp
# Or attach to an existing local backend:
ax-code attach http://localhost:4096 --tui-mcp

La barre TUIMCP affiche le chemin privé absolu endpoint.json. Configurez votre client MCP pour lancer :

{
  "mcpServers": {
    "ax-code-tui": {
      "command": "ax-code",
      "args": ["mcp", "tui", "--endpoint", "/absolute/path/from/the/TUI/endpoint.json"]
    }
  }
}

Utilisez le chemin affiché par votre TUI en cours. Chaque TUI a son propre point de terminaison ; il n’y a ni découverte automatique ni choix de cible. Le client doit s’exécuter sous le même utilisateur du système. Traitez le fichier de point de terminaison comme une capacité : il contient un jeton secret. Ne le commitez pas, ne le copiez pas dans des invites et n’en partagez pas le contenu. Les identifiants du backend ne sont jamais transmis à l’adaptateur.

Outils

get_view_context : renvoie l’instance et la génération, la révision, la route, un identifiant de session facultatif, la disponibilité et si la navigation est bloquée. Il ne renvoie ni transcriptions, ni brouillons, ni titres de session, ni chemins d’espace de travail, ni identifiants.
select_session : exige l’identité et la révision d’un contexte frais, un identifiant de session de projet et un UUID unique requestId. Il valide la session via la connexion de backend déjà authentifiée du TUI. Une réponse réussie accuse réception de l’état de route de l’application ; le rendu et le chargement de session peuvent encore être en cours. Les identifiants de session peuvent s’obtenir à part, via les interfaces de session ordinaires d’AX Code.

La navigation est refusée tant qu’un brouillon ou une pièce jointe existe, qu’une modale ou une approbation est en attente, que des sessions sont occupées, que le backend est déconnecté, que des superpositions de démarrage ou de sortie sont actives, ou que l’utilisateur a interagi au cours des 1.5 dernières secondes. Un changement d’interface ou d’espace de travail invalide les anciennes révisions. Ces outils ne peuvent ni soumettre d’invites, ni exécuter des commandes shell, ni approuver des permissions, ni démarrer un travail d’agent.

Un requestId identique répété renvoie son reçu d’origine, y compris son contexte d’origine. Le réutiliser avec des arguments différents est une erreur. Après 128 requêtes de navigation, les nouvelles requêtes sont refusées pour ce processus de TUI ; l’accès en lecture et les reçus existants restent disponibles. Redémarrez avec un partage explicite pour remettre cette limite à zéro. Les reçus ne sont pas évincés vers un rejeu non sûr.

deadline_exceeded signifie que la validation a été annulée avant la navigation. timeout_unknown ou outcome_unknown signifie que l’appelant n’a pas reçu d’issue définitive ; l’opération a peut-être été appliquée. Lisez le contexte courant pour réconcilier. L’adaptateur ne réessaie jamais automatiquement. Une réussite de connexion ou de transport, à elle seule, ne signifie pas qu’une navigation a réussi ; inspectez isError et le résultat structuré.

Révocation et cycle de vie

Cliquez sur [Révoquer] dans la barre TUIMCP ou lancez /tui-mcp-revoke. La révocation bloque immédiatement la navigation en attente et ferme le socket. La sortie ferme aussi le point de terminaison ; un redémarrage crée une nouvelle identité et un nouveau jeton. Un processus planté peut laisser un répertoire temporaire privé inerte ; les anciens clients ne peuvent pas s’attacher à un nouveau TUI par ce biais.

Le partage est désactivé par défaut et n’est pas persisté. Les contrôles locaux de propriétaire et de mode protègent contre les autres utilisateurs du système ; TUIMCP n’est pas un bac à sable contre du code qui s’exécute déjà sous votre utilisateur. Si le démarrage signale que le chemin de socket est trop long, utilisez une racine temporaire privée plus courte via TMPDIR et démarrez un nouveau TUI.