Kit MCP e API per sviluppatori

Installa il kit

Estrai l’archivio in una cartella di lavoro. Il download contiene il codice del client, il lockfile delle dipendenze, la guida e SKILL.md.

Comandi di installazione

curl --fail --location https://app.tuelia.com/downloads/tuelia-agent-kit.tar.gz --output tuelia-agent-kit.tar.gz
tar -xzf tuelia-agent-kit.tar.gz
cd tuelia-agent-kit
npm ci --ignore-scripts
node cli.js --help

Il comando finale mostra l’elenco dei tool della CLI. Il kit non è pubblicato su npm: usa questo download ufficiale.

Prepara la chiave

Accedi a API Keys e crea una chiave per il tuo agente. Per il percorso completo servono gli scope read e write. Una chiave con sola lettura può leggere snippet, stato delle scansioni e riepiloghi.

Salva la chiave nel gestore dei segreti del client. Il processo MCP deve riceverla nella variabile TUELIA_API_KEY. La chiave viene mostrata una sola volta nel pannello: non inserirla nella chat, nel codice del sito o nel file di configurazione condiviso.

La chiave appartiene al tuo account e rispetta permessi, piano e quote. Non è limitata a un singolo sito. Il login al pannello non autentica automaticamente il processo MCP.

Collega il client MCP

Aggiungi un server con trasporto stdio, comando node e percorso assoluto di mcp.js. Questo è uno schema JSON comune: adatta i campi al tuo client, che può usare un formato diverso.

Configurazione MCP senza segreti

{
  "mcpServers": {
    "tuelia": {
      "command": "node",
      "args": [
        "/percorso/assoluto/tuelia-agent-kit/mcp.js"
      ]
    }
  }
}

Assicurati che il client passi TUELIA_API_KEY al processo. Se filtra le variabili d’ambiente, configurane l’inoltro nella gestione segreti. Riavvia il collegamento: il server deve esporre i sei tool elencati sotto.

La destinazione predefinita è https://app.tuelia.com. TUELIA_API_URL serve per installazioni su un altro ambiente autorizzato. Il server gira sulla tua macchina; non esiste un URL MCP HTTP pubblico da incollare al posto del comando.

Dai il compito all’agente

Fai leggere all’agente il file SKILL.md incluso nell’archivio. Poi sostituisci URL e stack in questo testo.

Istruzioni per l’agente

Configura Tuelia sul sito autorizzato [URL DEL SITO], nello stack [STACK].
Leggi prima SKILL.md del kit Tuelia. La chiave è già nell'ambiente del processo: non chiederla in chat.
Usa bootstrap per creare o riusare il banner, poi install_code per ottenere lo snippet corretto.
Controlla l'ordine degli script e applica le modifiche nel repository del sito.
Pubblica solo se autorizzato. Verifica il runtime con verify e controlla il comportamento nel browser.
Avvia scan entro i limiti del piano, attendi il risultato con scan_status e leggi compliance.
Riporta cosa è stato verificato, cosa resta da fare e i limiti del report.

Gli stack accettati sono html, wordpress, nextjs, nextjs-pages, react, nuxt, shopify, gtm e angular. L’agente applica le modifiche al tuo progetto con i propri strumenti: il kit non modifica né pubblica il repository del sito.

Strumenti disponibili

Tool	Comportamento	Scope
`bootstrap`	Crea o riusa la configurazione del sito senza sovrascrivere le impostazioni esistenti.	Scrittura
`install_code`	Legge snippet e indicazioni per la piattaforma scelta.	Lettura
`verify`	Apre un browser per verificare il runtime. Non salva lo stato nel database.	Scrittura
`scan`	Avvia una scansione asincrona, soggetta a budget e disponibilità.	Scrittura
`scan_status`	Legge stato e contatori degli ultimi dieci scan.	Lettura
`compliance`	Legge il riepilogo del report e le azioni suggerite.	Lettura

Gli output MCP contengono riepiloghi. Per elenco dei tuoi siti, dettagli dei report, configurazioni e chiavi usa il pannello autenticato. Il kit non espone valori dei cookie, traffico grezzo o dati dei visitatori.

Errori e limiti

Il server MCP non si avvia: Controlla la versione di Node, il percorso assoluto, le dipendenze installate e la presenza della variabile d’ambiente. Se il client non trova Node, usa il percorso del suo eseguibile.
401 o 403: Verifica che la chiave sia attiva, non scaduta e dotata degli scope necessari. Non mostrare la chiave per diagnosticare l’errore.
402: Controlla il piano e la quota siti nel pannello. I siti che superano la quota possono restare consultabili senza essere modificabili.
429 oppure scan busy: Attendi il tempo indicato da Retry-After, se presente. Una risposta busy non conferma l’avvio di una nuova scansione. Evita tentativi ravvicinati.
Verifica unreachable: Il controllo non è stato completato. Risolvi l’accessibilità del sito o attendi capacità disponibile; non interpretarlo come banner assente.

Un runtime rilevato non dimostra da solo il blocco dei tracker. Controlla richieste e storage prima del consenso, dopo accettazione, rifiuto e revoca. Il report tecnico non certifica la conformità legale del sito.

Riferimenti

Guida completa in Markdown Istruzioni leggibili dagli agenti Manifest di discovery Contratto OpenAPI 3.1 Piani e quote dei siti