# Collegare un agente a Tuelia Scarica il [kit MCP e CLI](https://app.tuelia.com/downloads/tuelia-agent-kit.tar.gz). Il kit richiede Node.js 22 o successivo. Funziona sul computer che esegue il client MCP e comunica con le API Tuelia. Il trasporto è stdio; non esiste un URL MCP HTTP da inserire come server remoto. Non serve accedere al repository. ## Installare il kit Scarica archivio e metadati in una cartella locale: ```bash curl --fail --show-error --output tuelia-agent-kit.tar.gz https://app.tuelia.com/downloads/tuelia-agent-kit.tar.gz curl --fail --show-error --output tuelia-agent-kit.json https://app.tuelia.com/downloads/tuelia-agent-kit.json ``` Confronta il checksum prima di estrarre l'archivio: ```bash node -e 'const fs=require("node:fs");const crypto=require("node:crypto");const m=JSON.parse(fs.readFileSync("tuelia-agent-kit.json"));const a=fs.readFileSync("tuelia-agent-kit.tar.gz");if(a.length!==m.bytes||crypto.createHash("sha256").update(a).digest("hex")!==m.sha256)throw Error("Checksum non valido");process.stdout.write("Checksum valido\n")' tar -xzf tuelia-agent-kit.tar.gz cd tuelia-agent-kit npm ci --ignore-scripts node cli.js --help ``` L'ultimo comando elenca i sei tool disponibili. L'archivio contiene il codice locale, `package-lock.json`, questa guida in `README.md`, il riferimento `API.md` e `SKILL.md`. Le dipendenze vengono installate da npm con il lockfile. Il kit Tuelia non è pubblicato come pacchetto npm. ## Preparare l'accesso all'account Accedi a [Agenti e MCP](https://app.tuelia.com/admin/agents), poi apri [Chiavi API](https://app.tuelia.com/admin/api-keys). Crea una chiave personale con scope `write` per bootstrap, verifica e scansione. Usa scope `read` se servono soltanto snippet, stato delle scansioni e report. La chiave appartiene all'account e consente l'accesso ai siti di quell'account; non è limitata a un singolo sito. Piano, quota e ownership restano verificati dal SaaS. Il login nel browser non autentica automaticamente il processo MCP. La creazione e la revoca delle chiavi richiedono la sessione web autenticata. Fornisci `TUELIA_API_KEY` al processo attraverso l'ambiente o la gestione segreti del client. Non inserirla in chat, log, repository, argomenti CLI o codice del sito. Il kit usa `https://app.tuelia.com` come `TUELIA_API_URL` predefinita. ## Configurare il client MCP Registra un server locale stdio che avvia `node` con il percorso assoluto a `mcp.js`. Questa struttura JSON è comune a diversi client. Adattala al formato del tuo client, che può usare altri nomi o un file TOML: ```json { "mcpServers": { "tuelia": { "command": "node", "args": ["/absolute/path/to/tuelia-agent-kit/mcp.js"] } } } ``` Il processo deve ereditare `TUELIA_API_KEY`. Se il client filtra l'ambiente, configura l'inoltro della variabile attraverso la sua gestione segreti. Riavvia il server MCP dal client e controlla che compaiano `bootstrap`, `install_code`, `verify`, `scan`, `scan_status` e `compliance`. Per fornire istruzioni operative all'agente, usa `SKILL.md` incluso nel kit o la [skill pubblica](https://app.tuelia.com/downloads/tuelia-agent-SKILL.md). La skill è un documento da caricare nel client, non un'operazione API. ## Installare e verificare un sito 1. Indica all'agente un sito che sei autorizzato a gestire e il suo stack. 2. Esegui `bootstrap` e conserva `bannerId`. Un retry con lo stesso account e URL riusa il banner e preserva la configurazione. 3. Esegui `install_code`. Applica lo snippet dello stack corretto prima dei tracker opzionali. Le `installationNotes` descrivono i limiti di ciascuna variante, incluso GTM. 4. Pubblica il codice del sito attraverso il tuo normale processo. Il kit non esegue deploy. 5. Esegui `verify`. Controlla il runtime nel browser, oltre alla presenza del tag nell'HTML. 6. Avvia `scan` e consulta `scan_status` fino al completamento dello stesso record. `status: busy` senza un record `scan` significa che il nuovo scan non è partito. 7. Leggi `compliance`, poi prova accettazione, rifiuto e revoca nel browser con i tracker del sito. La CLI usa gli stessi tool. Dalla cartella del kit: ```bash node cli.js bootstrap '{"url":"https://example.test","stack":"nextjs","language":"it"}' node cli.js install_code '{"bannerId":"0123456789abcdef0123456789abcdef"}' node cli.js verify '{"bannerId":"0123456789abcdef0123456789abcdef"}' node cli.js scan '{"bannerId":"0123456789abcdef0123456789abcdef"}' node cli.js scan_status '{"bannerId":"0123456789abcdef0123456789abcdef"}' node cli.js compliance '{"bannerId":"0123456789abcdef0123456789abcdef"}' ``` Sostituisci URL e ID con quelli del sito autorizzato. `bootstrap` scrive la configurazione; `scan` visita il sito e consuma quota. `verify` avvia un browser e richiede scope `write`, ma non salva il risultato. Gli altri tool leggono dati. ## Risolvere errori e risultati incompleti Per `401`, controlla presenza, scadenza e revoca della chiave senza mostrarla. Per `403`, controlla scope, ownership e disponibilità della risorsa. Per `402`, controlla piano e limite siti nel pannello. Le nuove registrazioni hanno 14 giorni Pro con dieci siti; alla scadenza resta Free permanente con un sito incluso. Per `429`, attendi il `Retry-After` numerico quando presente. Per `busy`, timeout o `5xx`, usa retry limitati con attesa. Dopo un errore bootstrap, ripeti lo stesso URL perché la configurazione potrebbe essere già stata creata. Non moltiplicare banner o avvii di scansione per aggirare l'errore. Uno stato verifica `unreachable` è inconcludente; risolvi rete o capacità occupata e riprova. `not_found` indica runtime non osservato nella finestra di verifica. Uno scan parziale non copre tutto il sito. Il punteggio e l'installazione verificata sono risultati tecnici, non una certificazione di conformità legale. I tool restituiscono riepiloghi. `scan_status` legge gli ultimi dieci scan senza valori cookie, traffico raw o dati dei visitatori. I dettagli autorizzati sono nel pannello. Prima del lancio, completa e rivedi titolare e policy. Il client applica un timeout di 60 secondi e un massimo di 256 KiB per risposta. Non segue redirect autenticati e non espone i body di errore upstream. Verifica l'origin prima di impostare `TUELIA_API_URL`, perché riceverà la chiave. HTTP è ammesso solo su loopback con `TUELIA_ALLOW_LOCAL_HTTP=1`, per test locali. Consulta anche il [manifest pubblico](https://app.tuelia.com/api/agent/manifest) e il [riferimento OpenAPI](https://app.tuelia.com/api/agent/openapi.json).