---
name: tuelia-agent-kit
description: Usare quando un agente deve installare o verificare Tuelia su un sito autorizzato, configurare il client MCP oppure diagnosticare banner e scansioni tramite il kit locale.
---

# Tuelia per agenti

## Preparare il kit

Scaricare https://app.tuelia.com/downloads/tuelia-agent-kit.tar.gz e i metadati
https://app.tuelia.com/downloads/tuelia-agent-kit.json. Verificare SHA-256 e bytes
come descritto nella [guida](https://app.tuelia.com/downloads/tuelia-agent-guide.md),
poi estrarre l'archivio. Non serve il checkout del repository.

```bash
tar -xzf tuelia-agent-kit.tar.gz
cd tuelia-agent-kit
npm ci --ignore-scripts
node cli.js --help
```

Richiede Node.js 22+. Per MCP stdio, configurare `node` con il percorso assoluto
`/absolute/path/to/tuelia-agent-kit/mcp.js` nel client. Il server espone sei tool;
non esiste un endpoint MCP HTTP. La guida include la configurazione.

L'account autenticato gestisce le chiavi su https://app.tuelia.com/admin/api-keys.
Il login web non autentica il processo MCP. Il processo riceve `TUELIA_API_KEY`
dall'ambiente o dalla gestione segreti del client. Mai chiedere o mostrare la
chiave in chat, log, argomenti CLI, snippet o file del sito. La chiave è personale
e vale per i siti dell'account; non è limitata a un sito.

## Eseguire il lavoro autorizzato

1. Accertare sito autorizzato, stack e origin API. `TUELIA_API_URL` predefinita è `https://app.tuelia.com`.
2. Chiamare `bootstrap` con URL, stack e lingua facoltativa. Conservare `bannerId`. Ripetere lo stesso account e URL riusa il banner senza cambiare configurazione. Anche dopo timeout o errore, riprovare lo stesso URL.
3. Chiamare `install_code`. Applicare lo snippet e le `installationNotes` dello stack corretto prima dei tracker. Distinguere Next App Router e Pages Router; per React preferire l'HTML iniziale.
4. Verificare build e flusso browser. Pubblicare solo nello scope autorizzato dal proprietario. Il kit non pubblica codice.
5. Chiamare `verify`. `unreachable` è inconcludente; `not_found` richiede controllare runtime e snippet. Non dichiarare installato sulla sola presenza del tag.
6. Chiamare `scan` quando autorizzato. Se restituisce `status: busy` senza un record `scan`, attendere prima di un nuovo avvio. Altrimenti conservare l'ID dello scan e seguire quel record con `scan_status`, senza confonderlo con uno scan precedente.
7. Chiamare `compliance`. Verificare nel browser richieste vendor, accettazione, rifiuto, revoca e nuova accettazione. Riportare risultati e limiti, inclusa la copertura degli scan parziali.

Tool di lettura: `install_code`, `scan_status`, `compliance`. `bootstrap` e `scan`
scrivono. `verify` avvia un browser e richiede scope `write`, senza salvare il
risultato. Piano, ownership e quote sono controllati dalle API. Nessun tool
cancella banner, modifica consensi storici o invia email. I risultati sono
riepiloghi; per i dettagli usare la dashboard autorizzata su
https://app.tuelia.com/admin/agents. Non accedere ai dati reali dei visitatori.

CLI dalla cartella del kit:

```bash
node cli.js bootstrap '{"url":"https://example.test","stack":"html"}'
node cli.js verify '{"bannerId":"0123456789abcdef0123456789abcdef"}'
```

Per `401`, controllare autenticazione e scadenza; per `403`, scope e ownership;
per `402`, piano e limite siti. Per `429`, rispettare `Retry-After`; per `busy`,
`5xx` o timeout, usare attese e retry limitati. Non mostrare segreti durante la
diagnostica. Il report non certifica conformità legale. Completare e rivedere
le policy prima del lancio; il bootstrap non le inventa.