Condividere una TUI attiva tramite MCP

Questa pagina è tradotta dalla documentazione inglese. Comandi, identificatori ed esempi restano invariati. Runtime 7.24.4 · SDK 2.6.7. Testo inglese

Stato: Sperimentale Ambito: pubblico, stato attuale Ultima revisione: 2026-10-04 Responsabile: responsabili di AX Code

TUIMCP è un adattatore MCP sperimentale e facoltativo per la TUI di AX Code su macOS e Linux. Permette a un agente esterno di leggere uno stato di interfaccia limitato e di navigare la stessa TUI che stai usando. Windows non è supportato in questa versione.

Avvia una TUI con la condivisione esplicita:

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

La barra TUIMCP mostra il percorso privato assoluto di endpoint.json. Configura il client MCP perché avvii:

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

Usa il percorso mostrato dalla TUI in esecuzione. Ogni TUI ha il proprio endpoint; non c’è scoperta automatica né selezione del bersaglio. Il client deve essere eseguito dallo stesso utente del sistema operativo. Tratta il file dell’endpoint come una capacità: contiene un token segreto. Non eseguirne il commit, non copiarlo nei prompt e non condividerne il contenuto. Le credenziali del backend non vengono mai passate all’adattatore.

Strumenti

get_view_context: restituisce istanza e generazione, revisione, route, ID di sessione facoltativo, prontezza e se la navigazione è bloccata. Non restituisce trascrizioni, bozze, titoli di sessione, percorsi del workspace né credenziali.
select_session: richiede l’identità e la revisione di un contesto aggiornato, un ID di sessione del progetto e un UUID univoco requestId. Valida la sessione attraverso la connessione autenticata al backend già usata dalla TUI. Una risposta riuscita conferma lo stato della route applicativa; il rendering e il caricamento della sessione possono essere ancora in corso. Gli ID di sessione si possono ottenere separatamente tramite le interfacce ordinarie di sessione di AX Code.

La navigazione viene rifiutata mentre esiste una bozza o un allegato, un modale o un’approvazione è in attesa, le sessioni sono occupate, il backend è disconnesso, gli overlay di avvio o uscita sono attivi, oppure l’utente ha interagito negli ultimi 1.5 secondi. Uno stato di interfaccia o di workspace cambiato invalida le revisioni precedenti. Questi strumenti non possono inviare prompt, eseguire comandi di shell, approvare autorizzazioni né avviare il lavoro dell’agente.

Un requestId identico e ripetuto restituisce la ricevuta originale, incluso il contesto originale. Riutilizzarlo con argomenti diversi è un errore. Dopo 128 richieste di navigazione, le nuove richieste vengono rifiutate per quel processo TUI; l’accesso in lettura e le ricevute esistenti restano disponibili. Riavvia con la condivisione esplicita per azzerare questo limite. Le ricevute non vengono espulse verso una riproduzione non sicura.

deadline_exceeded significa che la validazione è stata annullata prima della navigazione. timeout_unknown o outcome_unknown significa che il chiamante non ha ricevuto un esito definitivo; l’operazione potrebbe essere stata applicata. Leggi il contesto corrente per riconciliare. L’adattatore non riprova mai in automatico. Il solo successo di connessione o di trasporto non significa che una navigazione sia riuscita; controlla isError e il risultato strutturato.

Revoca e ciclo di vita

Fai clic su [Revoke] nella barra TUIMCP oppure esegui /tui-mcp-revoke. La revoca chiude subito la navigazione in attesa e chiude il socket. Anche l’uscita chiude l’endpoint; il riavvio crea una nuova identità e un nuovo token. Un processo andato in crash può lasciare una directory temporanea privata inerte; i client vecchi non possono agganciarsi a una nuova TUI attraverso di essa.

La condivisione è disattivata per impostazione predefinita e non viene persistita. I controlli locali di proprietario e modalità proteggono dagli altri utenti del sistema operativo; TUIMCP non è una sandbox contro il codice che è già in esecuzione come il tuo utente. Se l’avvio segnala che il percorso del socket è troppo lungo, usa una radice temporanea privata più corta tramite TMPDIR e avvia una nuova TUI.