Riferimento agli strumenti MCP

In caso di successo, ogni strumento tranne get-screen-image restituisce il risultato due volte: come structuredContent (validato rispetto allo schema di output pubblicato dallo strumento) e come lo stesso oggetto serializzato in un blocco di testo, { type: "text", text: "<json-string>" }, per i client che non leggono il contenuto strutturato. get-screen-image restituisce solo un blocco immagine MCP: { type: "image", data: "<base64>", mimeType: "image/png" }. In caso di errore, viene impostato isError: true e il blocco di testo contiene un breve messaggio di errore. Gli errori su cui puoi intervenire, come una mancata corrispondenza del nome durante un’eliminazione, un link Figma non valido, linee guida di design non valide, un problema con un allegato o il timeout di una generazione, spiegano cosa correggere. Gli altri errori restituiscono un messaggio generico come Failed to list files.

Prezzi: i tre strumenti di design AI (ai-design-screens, ai-generate-screen-variant e ai-edit-screen-variant) usano la stessa quota di messaggi dell’app Flowstep. Tutti gli altri strumenti sono gratuiti. Vedi Limiti di utilizzo.

Ogni strumento pubblica anche annotazioni MCP, così il tuo client sa cosa fa. delete-file, delete-screen, delete-design-guidelines, replace-screen-jsx, ai-design-screens e ai-edit-screen-variant sono contrassegnati come distruttivi perché rimuovono o sovrascrivono contenuti esistenti.

Strumenti per i file

`list-files`

Elenca i metadati dei tuoi file Flowstep. Chiamalo per primo per verificare se esiste già un file pertinente. Non restituisce contenuto delle schermate: per quello usa get-screen-image o get-screen-jsx. Input

Parametro	Tipo	Predefinito	Descrizione
`orderByCreation`	`boolean`	`true`	Ordina dal più recente per `created_at` (`true`) oppure per `updated_at` (`false`). Usa `false` per trovare i file modificati di recente
`limit`	`integer` (1–100)	`20`	Numero massimo di file restituiti. Una pagina piena può significare che esistono altri file
`offset`	`integer` (≥0)	`0`	File da saltare. La pagina successiva è `offset + limit`

Output: { files }.

{
  "files": [
    {
      "id": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
      "name": "Dashboard redesign",
      "created_at": "2026-04-30T15:02:13.120152+00:00",
      "updated_at": "2026-04-30T15:02:13.120152+00:00",
      "organisation_id": "0b7f3c9e-2d4a-4f1b-9a5e-6c8d7e1f2a3b",
      "shared_with_me": false,
      "owner": true,
      "url": "https://app.flowstep.ai/file?activeFileId=5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0"
    }
  ]
}

owner: true se hai creato tu il file.
shared_with_me: true se il file è stato condiviso direttamente con te, non solo tramite la tua organizzazione.
url: apre il file nell’editor di Flowstep.

`get-file`

Ottieni i metadati di un singolo file. Il contenuto del file è volutamente omesso: usa get-screen-image o get-screen-jsx per ispezionare le schermate, e get-design-guidelines per recuperare le linee guida associate. Se hai un invito in sospeso per il file, chiamare get-file lo accetta. Input

Parametro	Tipo	Descrizione
`id`	`uuid`	ID del file

Output: { file, user_access_level }.

{
  "file": {
    "id": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
    "name": "Dashboard redesign",
    "created_at": "2026-04-30T15:02:13.120152+00:00",
    "updated_at": "2026-04-30T15:02:13.120152+00:00",
    "project_id": "81cb84d6-c69f-492c-a895-7421b60d1a6d",
    "access_level": "private",
    "visibility": "private",
    "owner": true,
    "url": "https://app.flowstep.ai/file?activeFileId=5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0"
  },
  "user_access_level": "write"
}

access_level: private, read o write.
visibility: private, member o public.
user_access_level: il tuo accesso al file, cioè read o write.

`create-file`

Crea un file Flowstep vuoto, senza schermate. Per creare un file e generare schermate in un solo passaggio, chiama invece ai-design-screens senza fileId. Usa create-file per i flussi di lavoro basati sul codice, seguito da add-screen-jsx. Input

Parametro	Tipo	Descrizione
`name`	`string` (min 1)	Nome visualizzato del nuovo file

Output: { file, user_access_level }, con la stessa struttura di get-file. owner è sempre true e user_access_level è sempre write. Usa il file.id restituito come fileId nelle chiamate successive.

`update-file`

Rinomina un file. Input

Parametro	Tipo	Descrizione
`id`	`uuid`	ID del file
`name`	`string` (min 1)	Nuovo nome visualizzato

Output: { file, user_access_level }, con la stessa struttura di get-file.

`delete-file`

Elimina definitivamente un file. Il name che passi viene confrontato con il nome visualizzato attuale del file prima dell’eliminazione: se non corrisponde, l’eliminazione viene annullata. Questo evita di eliminare per errore il file sbagliato. Agli agenti viene chiesto di confermare prima con te. Input

Parametro	Tipo	Descrizione
`id`	`uuid`	ID del file
`name`	`string`	Nome visualizzato attuale del file: deve corrispondere, altrimenti l’eliminazione viene annullata

Output: { "deleted": true }

Operazione irreversibile. Tutte le schermate del file vengono eliminate.

Strumenti per le schermate

`list-screens`

Elenca le schermate di un file, nell’ordine del canvas. Chiamalo dopo list-files per vedere cosa contiene già un file. Usa i valori screenId restituiti con gli altri strumenti per le schermate e con gli strumenti di design AI. Input

Parametro	Tipo	Descrizione
`fileId`	`uuid`	ID del file

Output: { screens }.

{
  "screens": [
    {
      "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbe",
      "name": "Mobile login screen",
      "prompt": "Generate a simple mobile login screen with email and password fields and a sign in button",
      "fidelity": "ui"
    }
  ]
}

prompt: l’ultimo prompt di generazione della schermata, oppure una stringa vuota se non è mai stata generata (per esempio una schermata aggiunta con add-screen-jsx).
fidelity: lofi, hifi o ui.

`get-screen-image`

Renderizza una schermata in PNG e la restituisce come immagine in linea. Richiede un client che supporti i blocchi di contenuto immagine. Chiamalo una volta per ogni screenId restituito da uno strumento di design AI, da add-screen-jsx, da replace-screen-jsx o da import-figma. Input

Parametro	Tipo	Descrizione
`fileId`	`uuid`	ID del file
`screenId`	`uuid`	Un `screenId` da `list-screens` o dall’array `screenIds` restituito da uno strumento di design

Output: blocco di contenuto immagine MCP (image/png). data è base64 standard dei byte PNG, non un data URI. Questo strumento non ha structuredContent.

`get-screen-jsx`

Ottieni una schermata come JSX, insieme ai suoi metadati, così puoi costruire a partire da essa nella tua codebase oppure modificarla e riscriverla con replace-screen-jsx. Per un’anteprima visiva, usa invece get-screen-image. Input

Parametro	Tipo	Predefinito	Descrizione
`fileId`	`uuid`	—	ID del file
`screenId`	`uuid`	—	Un `screenId` da `list-screens` o dall’array `screenIds` restituito da uno strumento di design
`includeIds`	`boolean`	`false`	Include un attributo `data-id` sugli elementi di `jsx`. Usalo quando ti servono gli id degli elementi da passare come `elementIds` a `ai-design-screens`, per modificarli in place o come riferimento visivo

Output: { fileId, screenId, name, prompt, fidelity, screenType, colorTheme, jsx, fragments }.

{
  "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
  "screenId": "c13d3707-0efe-49f5-b6cb-0ca5ac5223d0",
  "name": "World clock",
  "prompt": "A world clock screen with a city search and alert button",
  "fidelity": "ui",
  "screenType": "iphone-x-vertical",
  "colorTheme": "blue",
  "jsx": "<div className=\"bg-white text-zinc-950 w-full h-fit\">\n  <div className=\"flex p-6 flex-col gap-6\">\n    …\n  </div>\n</div>",
  "fragments": []
}

jsx: solo markup. Gli attributi data-id sono inclusi solo quando includeIds è true.
prompt: l’ultimo prompt di generazione, oppure una stringa vuota se la schermata non è mai stata generata.
fragments: elementi comuni salvati sulla schermata, come una barra di navigazione, un’intestazione o un logo, sotto forma di oggetti { purpose, markup }. È vuoto se non ce ne sono. Passali di nuovo a replace-screen-jsx per mantenerli o aggiornarli.

Vedi Valori dei campi della schermata per i valori di fidelity, screenType e colorTheme.

`add-screen-jsx`

Aggiunge una nuova schermata a un file a partire da JSX che hai scritto. È il percorso basato sul codice ed è gratuito: usa ai-design-screens quando vuoi che l’AI di Flowstep progetti la schermata. add-screen-jsx crea sempre una nuova schermata: per sovrascrivere una esistente, usa replace-screen-jsx. Per mostrare un’immagine che hai caricato, vedi Immagini in JSX. Quando la nuova schermata si basa su una esistente, parti da get-screen-jsx (senza includeIds) per name, fidelity, screenType, colorTheme e jsx, poi modifica ciò che deve essere diverso. Input

Parametro	Tipo	Predefinito	Descrizione
`fileId`	`uuid`	—	ID del file
`name`	`string` (1–100 caratteri)	—	Nome visualizzato facoltativo. Omettilo per assegnare automaticamente alla schermata il nome `Screen N`
`fidelity`	`string`	`"ui"`	Fedeltà della schermata
`screenType`	`string`	—	Obbligatorio: il dispositivo o la finestra per cui è progettata la schermata
`colorTheme`	`string`	`"default"`	Tema di colore
`jsx`	`string`	—	Solo markup JSX. Eventuali attributi `data-id` vengono ignorati: la nuova schermata riceve nuovi id degli elementi

Output: { fileId, screenId }. Chiama get-screen-image con screenId per vedere il risultato.

{
  "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
  "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbf"
}

`replace-screen-jsx`

Sovrascrive una schermata esistente con JSX che hai scritto. La schermata mantiene il suo screenId e la sua posizione sul canvas; gli elementi annidati ricevono nuovi id. È il percorso basato sul codice ed è gratuito: usa ai-design-screens o ai-edit-screen-variant per le modifiche AI, e add-screen-jsx per creare invece una nuova schermata. Parti da get-screen-jsx (senza includeIds), poi modifica ciò che deve essere diverso. Per mostrare un’immagine che hai caricato, vedi Immagini in JSX. Input

Parametro	Tipo	Descrizione
`fileId`	`uuid`	ID del file
`screenId`	`uuid`	La schermata da sovrascrivere
`jsx`	`string`	Solo markup JSX. Eventuali attributi `data-id` vengono ignorati
`name`	`string` (1–100 caratteri)	Facoltativo. Omettilo per mantenere il nome attuale
`fidelity`	`string`	Facoltativo. Omettilo per mantenere la fedeltà attuale
`screenType`	`string`	Facoltativo. Omettilo per mantenere il tipo di schermata attuale
`colorTheme`	`string`	Facoltativo. Omettilo per mantenere il tema di colore attuale
`fragments`	`{ purpose, markup }[]`	Facoltativo: elementi comuni da `get-screen-jsx`. Omettilo per mantenere i frammenti attuali, oppure passa `[]` per cancellarli

Output: { fileId, screenId }. Chiama get-screen-image con screenId per vedere il risultato.

Questa operazione sostituisce il contenuto della schermata sul posto.

`rename-screen`

Rinomina l’etichetta di una schermata sul canvas, cioè il nome mostrato da list-screens e nell’editor. Cambia solo l’etichetta, non il layout, le dimensioni o il contenuto della schermata: per quelli usa ai-design-screens. Input

Parametro	Tipo	Descrizione
`fileId`	`uuid`	ID del file
`screenId`	`uuid`	Il `screenId` restituito da `list-screens`
`name`	`string` (1–100 caratteri)	Nuovo nome della schermata. Gli spazi iniziali e finali vengono rimossi

Output: { screenId, name }.

{ "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbe", "name": "Checkout — empty cart" }

`delete-screen`

Elimina definitivamente una schermata da un file. Il name che passi viene confrontato con il nome visualizzato attuale della schermata: se non corrisponde, l’eliminazione viene annullata. Agli agenti viene chiesto di confermare prima con te. Input

Parametro	Tipo	Descrizione
`fileId`	`uuid`	ID del file
`screenId`	`uuid`	La schermata da eliminare
`name`	`string`	Nome visualizzato attuale della schermata: deve corrispondere, altrimenti l’eliminazione viene annullata

Output: { "deleted": true }

Immagini in JSX

add-screen-jsx e replace-screen-jsx accettano immagini in un src di img, oppure come sfondo in className con bg-[url(...)]. Scrivi il testo alt e dimensiona ogni immagine in base al suo scopo. Per inserire un’immagine tua:

Caricala con upload-attachment in modalità A (mimeType + fileName) ed esegui il uploadCommand restituito.
Se il type della risposta è "image", incolla il suo assetUrl esattamente come restituito in img src o in bg-[url(assetUrl)].

Lascia ogni altro URL di immagine esattamente come l’ha restituito get-screen-jsx. Non inserire path, signedUrl o uploadCommand in src.

<img src="ASSET_URL" alt="Team photo" className="w-full h-48 object-cover rounded-lg" />

Valori dei campi della schermata

get-screen-jsx restituisce, e add-screen-jsx e replace-screen-jsx accettano, questi valori:

Campo	Valori
`fidelity`	`lofi`, `hifi`, `ui`
`screenType`	`web`, `desktop`, `desktop-large`, `desktop-medium`, `desktop-small`, `tablet`, `ipad-tablet-horizontal`, `ipad-tablet-vertical`, `android-tablet-horizontal`, `android-tablet-vertical`, `mobile_ios`, `mobile_android`, `iphone-vertical`, `iphone-horizontal`, `iphone-x-vertical`, `iphone-x-horizontal`, `android-vertical`, `android-horizontal`, `android-small-vertical`, `android-small-horizontal`
`colorTheme`	`default`, `defaultDark`, `blue`, `blueDark`, `ice`, `iceDark`, `grayscale`, `grayscaleDark`, `green`, `greenDark`, `orange`, `orangeDark`, `red`, `redDark`, `rose`, `roseDark`, `violet`, `violetDark`, `yellow`, `yellowDark`

Strumenti per le linee guida di design

Le linee guida di design sono testo DESIGN.md salvato su un file. Quando sono impostate, vengono inserite in ogni generazione AI per quel file. Vedi Linee guida di design.

`get-design-guidelines`

Ottieni le linee guida di design associate a un file. Input

Parametro	Tipo	Descrizione
`fileId`	`uuid`	ID del file

Output: { guidelines }.

{
  "guidelines": "## Colors\n\nPrimary: #6366F1\nBackground: #FFFFFF\n\n## Typography\n\nFont: Inter"
}

guidelines è null se non sono state impostate linee guida.

`update-design-guidelines`

Imposta o sostituisce le linee guida di design di un file. Passa le linee guida come stringa semplice nel formato DESIGN.md di Google, non come oggetto o JSON. Se le leggi da un file, passa il testo di quel file. Input

Parametro	Tipo	Descrizione
`fileId`	`uuid`	ID del file
`designGuidelines`	`string` (min 1)	Testo grezzo delle linee guida. Deve essere una stringa semplice, non codificata in JSON

Regole di validazione

Il frontmatter deve essere aperto e chiuso correttamente
Le righe del frontmatter devono essere YAML valido in stile block
Il corpo Markdown non deve contenere intestazioni di sezione ## duplicate

Se la validazione fallisce, la chiamata restituisce un errore che inizia con Invalid design guidelines:. Output: { updated, warnings? }.

{ "updated": true, "warnings": ["…"] }

warnings elenca problemi di validazione non bloccanti (chiavi sconosciute, colori non esadecimali) che sono stati accettati ma che l’AI potrebbe ignorare. Viene omesso se non ce ne sono. Riportali all’utente.

`delete-design-guidelines`

Cancella le linee guida di design di un file. Eliminare linee guida inesistenti non ha effetto. Input

Parametro	Tipo	Descrizione
`fileId`	`uuid`	ID del file

Output: { "deleted": true }

Strumenti di chat

`get-chat-history`

Ottieni la conversazione di design associata a un file, cioè la chat Flowstep del file, non la conversazione del tuo client MCP. Usala per riprendere il lavoro precedente sul file. Input

Parametro	Tipo	Descrizione
`fileId`	`uuid`	ID del file

Output: { messages }. messages è vuoto se non hai una conversazione di design sul file. Ogni messaggio ha un type ("request" o "response"), un author ("human" o "ai") e un content_type. I messaggi di risposta usano "text", "summary" o "followup".

{
  "messages": [
    {
      "id": "453f593d-2380-425b-ba29-127db08d6a8e",
      "type": "request",
      "status": "success",
      "content": "Generate a simple mobile login screen with email and password fields",
      "author": "human",
      "content_type": "text",
      "sequence": 1,
      "targets": [],
      "attachments": []
    },
    {
      "id": "d860186b-82d5-4bd1-8e8e-8ba5377a14bf",
      "type": "response",
      "status": "success",
      "content": "Generated a mobile login screen with email and password input fields, a sign in button, and a sign up link.",
      "author": "ai",
      "content_type": "summary",
      "sequence": 7,
      "request_message_id": "453f593d-2380-425b-ba29-127db08d6a8e",
      "targets": [{ "target_id": "3f9e6eb6-5525-4383-9375-67e0bd762dbe" }]
    }
  ]
}

Strumenti per gli allegati

`upload-attachment`

Carica un file di riferimento da usare come allegato in ai-design-screens, oppure un’immagine da inserire nel tuo JSX con add-screen-jsx o replace-screen-jsx. ai-generate-screen-variant e ai-edit-screen-variant non accettano allegati. I byte dei file non passano mai dal modello, e il server non recupera mai URL per tuo conto. Per fare riferimento a una pagina web, includi il suo URL nel message di ai-design-screens. Esistono due modalità: usane esattamente una, senza combinarle. Modalità A: file e immagini (mimeType + fileName) Un flusso obbligatorio in tre passaggi per qualsiasi immagine, PDF o file di testo più grande:

Chiama upload-attachment solo con mimeType e fileName (per esempio image/png e dog.png). La risposta è un caricamento preparato, non un file già salvato:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "path": "attachments/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "assetUrl": "https://…",
  "type": "image",
  "mimeType": "image/png",
  "signedUrl": "https://…",
  "uploadCommand": "curl -sS -f -X PUT '…' -H 'Content-Type: image/png' -H 'x-metadata: …' --data-binary @LOCAL_FILE_PATH",
  "nextStep": "…"
}

Sostituisci LOCAL_FILE_PATH in uploadCommand con il percorso assoluto del tuo file ed esegui esattamente quel comando nella shell: deve terminare con codice 0. Il token in signedUrl autorizza solo questo singolo caricamento. Saltare questo passaggio lascia lo storage vuoto e lo strumento di design non supera il controllo preliminare.
Passa solo { id, path, type } nell’array attachments di ai-design-screens, non signedUrl, uploadCommand o nextStep. Per inserire invece un’immagine nel tuo JSX, metti assetUrl in img src o in bg-[url(...)] del JSX che passi a add-screen-jsx o replace-screen-jsx. Vedi Immagini in JSX.

Per allegare un file remoto, scaricalo prima in un percorso locale (per esempio con curl), poi segui gli stessi tre passaggi. Non passare mai un URL a upload-attachment.

Parametro	Tipo	Descrizione
`mimeType`	enum	Tipo MIME del file. Uno tra `image/jpeg`, `image/png`, `image/webp`, `application/pdf`, `text/markdown`, `text/plain`, `text/javascript`. Usa `text/javascript` per i file `.jsx`, `.tsx`, `.js`, `.ts`
`fileName`	`string` (min 1)	Nome originale del file con estensione, per esempio `cat.png` o `design.md`

Modalità B: testo breve (text + mimeType) Carica testo già presente nel contesto: non serve alcun comando di shell. La risposta è subito pronta all’uso:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "path": "attachments/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "assetUrl": "https://…",
  "type": "document",
  "mimeType": "text/plain"
}

Parametro	Tipo	Descrizione
`text`	`string` (max 64.000 caratteri)	Contenuto di testo grezzo. Solo file di testo: non usarlo per immagini o PDF. Più lungo di 64.000 caratteri? Usa la modalità A
`mimeType`	enum	Uno tra `text/markdown`, `text/plain`, `text/javascript`

Passa l’oggetto { id, path, type } risultante nell’array attachments di ai-design-screens. La dimensione massima del file è 3 MB in entrambe le modalità, e i PDF sono limitati a 100 pagine. Output: { id, path, assetUrl, type, mimeType, signedUrl?, uploadCommand?, nextStep? }.

type: "image" per i file immagine e "document" per PDF e file di testo.
assetUrl: l’URL del file caricato, restituito in entrambe le modalità. Usalo nel JSX per add-screen-jsx o replace-screen-jsx solo quando type è "image", e solo dopo che è stato eseguito il uploadCommand della modalità A.
signedUrl, uploadCommand, nextStep: impostati solo nella modalità A. Non passarli agli strumenti di design.

Strumenti per Figma

`import-figma`

Importa un frame Figma in un file Flowstep come elementi modificabili sul suo canvas. Ogni importazione aggiunge una nuova schermata: importare due volte lo stesso frame produce due schermate, quindi elimina quella vecchia con delete-screen se intendevi sostituirla. L’organizzazione del file deve avere Figma collegato nelle impostazioni di Flowstep. Input

Parametro	Tipo	Descrizione
`fileId`	`uuid`	Il file Flowstep in cui importare il frame. Non è la chiave del file Figma presente in `figmaUrl`
`figmaUrl`	`string`	Link a un frame Figma specifico, con un `node-id`. In Figma, fai clic destro sul frame e scegli Copy/Paste as → Copy link to selection. Un link a una pagina importa tutti i frame di primo livello di quella pagina (massimo 20 frame tramite MCP)

Output: { fileId, screenId, frameCount? }. screenId è la schermata importata: passala a get-screen-image per vedere il risultato. Quando un URL di pagina importa più frame, screenId è null e viene restituito frameCount: chiama list-screens, poi get-screen-image per ogni nuova schermata.

{
  "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
  "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbe"
}

Strumenti per piano e fatturazione

`get-plan-details`

Ottieni il piano Flowstep della tua organizzazione, lo stato dell’abbonamento, l’utilizzo e la quota residua. Non richiede input: l’organizzazione viene risolta a partire dall’utente connesso. Usalo per verificare la tua quota prima di chiamare gli strumenti di design AI. Output: { plan, subscription, limits, usage, remaining }.

Campo	Descrizione
`plan`	`{ name, code, type }`. `type` è `"free"` o `"paid"`
`subscription`	`{ isPaid, isTrial, startDate, endDate, trialDaysRemaining }`
`limits`	Limiti per funzione, indicizzati per funzione (per esempio `messages`). Ognuno ha oggetti facoltativi `daily` e `monthly` con valori `max` e `warn`, più un flag `unlimited`
`usage`	Utilizzo per funzione finora, come `{ daily, monthly }`
`remaining`	Quota residua per funzione, come `{ daily, monthly }`. Omesso per le funzioni illimitate

I limiti variano in base al piano: vedi Prezzi e Limiti di utilizzo.

Strumenti di design AI

Questi tre strumenti progettano a partire da una descrizione o da un preset: non accettano né riutilizzano mai JSX. Ogni chiamata usa la stessa quota di messaggi dell’app Flowstep e attende il completamento della generazione o il timeout (180 secondi).

Strumento	Usalo per
`ai-design-screens`	Generare nuove schermate, modificare schermate esistenti in place, o entrambe le cose, a partire da una descrizione libera
`ai-generate-screen-variant`	Aggiungere una variante successiva, di errore o di stato vuoto, o di piattaforma di una schermata esistente
`ai-edit-screen-variant`	Applicare un preset di modifica o riprogettazione a un’intera schermata esistente

Tutti e tre restituiscono { status, fileId, screenIds, designGuidelinesUpdated }. Chiama get-screen-image una volta per ogni screenId per vedere il risultato.

designGuidelinesUpdated: un breve riepilogo della modifica, quando le linee guida DESIGN.md del file sono state aggiornate automaticamente durante questo turno; altrimenti null.

`ai-design-screens`

Genera una o più nuove schermate, modifica schermate esistenti in place, o entrambe le cose in una sola chiamata, a partire da una descrizione testuale: nuovi flussi, temi, testi, layout o modifiche coordinate su più schermate. È lo stesso agente di design della chat nell’editor di Flowstep: decide, in base al tuo message e a elementIds, cosa costruire e cosa cambiare. Ometti fileId per avviare un nuovo file; passa fileId per lavorare in un file esistente. Se la richiesta potrebbe riguardare un file che hai già, il tuo agente dovrebbe prima controllare list-files e list-screens. Per una variante successiva, di errore o di stato vuoto, o di piattaforma di una schermata, usa ai-generate-screen-variant. Per un preset di modifica o riprogettazione di una schermata, usa ai-edit-screen-variant. Se hai già il JSX, usa invece add-screen-jsx o replace-screen-jsx. Input

Parametro	Tipo	Predefinito	Descrizione
`fileId`	`uuid`	—	File di destinazione. Ometti per creare un nuovo file. Obbligatorio quando è impostato `elementIds`
`message`	`string`	—	Descrizione delle schermate da generare e/o delle modifiche da fare. Quando passi `elementIds`, indica se modificarli o usarli come riferimento. Inserisci qui gli URL di eventuali pagine web che vuoi che Flowstep consulti
`elementIds`	`uuid[]`	`[]`	`screenId` facoltativi da `list-screens` e/o `data-id` degli elementi da `get-screen-jsx` (con `includeIds`), come una selezione nell’editor. Possono essere modificati in place oppure usati come riferimento visivo per nuove schermate. Un `screenId` si riferisce all’intera schermata
`attachments`	`{ id, path, type }[]` (max 5)	`[]`	File da `upload-attachment`: immagini, PDF, o file di codice e testo. Non incorporare il contenuto dei file nel messaggio

Esempio: modifica una schermata e aggiungine un’altra in un’unica chiamata:

{
  "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
  "message": "Switch this sign-in screen to dark mode, then add a matching forgot-password screen.",
  "elementIds": ["3f9e6eb6-5525-4383-9375-67e0bd762dbe"]
}

Output: { status, fileId, screenIds, designGuidelinesUpdated, reply? }.

{
  "status": "generated",
  "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
  "screenIds": [
    "3f9e6eb6-5525-4383-9375-67e0bd762dbe",
    "c13d3707-0efe-49f5-b6cb-0ca5ac5223d0"
  ],
  "designGuidelinesUpdated": null
}

status: "generated" quando sono state costruite o modificate schermate. "chat" quando Flowstep ha risposto senza costruire nulla: in quel caso reply contiene la sua risposta e screenIds è vuoto. Se la tua richiesta è ambigua, il tuo agente dovrebbe chiederti di chiarire e richiamare lo strumento.
screenIds: ogni schermata costruita o modificata durante la chiamata, incluse quelle modificate in place. Se la chiamata scade dopo che alcune schermate sono state costruite, restituisce quelle schermate invece di un errore.

Le schermate che gli chiedi di modificare vengono sovrascritte in place.

`ai-generate-screen-variant`

Aggiunge una nuova schermata derivata da esattamente una schermata esistente: il passo successivo del flusso, uno stato di errore o vuoto, oppure una versione per un’altra piattaforma. La schermata originale resta invariata. Per aggiungere una schermata che non è una variante di una esistente (per esempio una schermata delle impostazioni), usa ai-design-screens con un fileId. Input

Parametro	Tipo	Descrizione
`fileId`	`uuid`	File di destinazione
`screenId`	`uuid`	La schermata esistente da cui derivare
`operationVariant`	enum	Obbligatorio: come la nuova schermata si relaziona a quella esistente

`operationVariant`	Aggiunge
`next_screen`	La schermata successiva nel flusso utente
`error_state`	Uno stato di errore della schermata
`empty_state`	Uno stato vuoto della schermata
`web_version`	Una versione web
`mobile_version`	Una versione mobile
`tablet_version`	Una versione tablet
`mobile_ios_version`	Una versione iOS
`mobile_android_version`	Una versione Android

Output: { status, fileId, screenIds, designGuidelinesUpdated }. status è sempre "generated".

`ai-edit-screen-variant`

Modifica esattamente una schermata esistente in place usando un preset: applica un tema o una rifinitura, prova un layout o uno stile visivo diverso, oppure riprogettala da zero. Per nuove schermate, istruzioni libere o una modifica precisa di singoli elementi, usa ai-design-screens. Input

Parametro	Tipo	Descrizione
`fileId`	`uuid`	File di destinazione
`screenId`	`uuid`	La schermata esistente da modificare
`operationVariant`	enum	Obbligatorio: il preset di modifica o riprogettazione da applicare

`operationVariant`	Tipo	Effetto
`dark_theme`	Modifica	Passa la schermata a un tema scuro
`light_theme`	Modifica	Passa la schermata a un tema chiaro
`make_pretty`	Modifica	Rifinisce il design visivo della schermata
`different_layout`	Riprogettazione	Prova un layout diverso
`different_style`	Riprogettazione	Prova uno stile visivo diverso
`from_scratch`	Riprogettazione	Riprogetta la schermata da zero

Output: { status, fileId, screenIds, designGuidelinesUpdated }. status è sempre "generated".

Questa operazione sovrascrive il contenuto della schermata sul posto.

Strumenti rinominati

I nomi di alcuni strumenti sono cambiati a settembre e ottobre 2026. Se hai prompt, script o istruzioni per agenti che usano i nomi precedenti, aggiornali:

Nome precedente	Nuovo nome
`get-screen`	`get-screen-jsx`
`add-screen`	`add-screen-jsx`
`replace-screen`	`replace-screen-jsx`
`ai-generate-screens`	`ai-design-screens`
`ai-edit-screens`	`ai-design-screens`
`create-new-design`	`ai-design-screens`
`edit-design` (istruzioni libere)	`ai-design-screens`
`edit-design` (con un preset `operationVariant`)	`ai-edit-screen-variant`
`regenerate-design`	`ai-edit-screen-variant`
`expand-design`	`ai-generate-screen-variant`

Anche gli input sono cambiati: gli strumenti di design AI accettano elementIds (oppure un singolo screenId per gli strumenti di variante) invece di targets; add-screen-jsx accetta jsx e campi di metadati espliciti invece di jsxContent con un commento di metadati; create-file accetta name invece di title; e gli strumenti per le linee guida di design accettano fileId invece di resourceId e linkedTo.

​Strumenti per i file

​list-files

​get-file

​create-file

​update-file

​delete-file

​Strumenti per le schermate

​list-screens

​get-screen-image

​get-screen-jsx

​add-screen-jsx

​replace-screen-jsx

​rename-screen

​delete-screen

​Immagini in JSX

​Valori dei campi della schermata

​Strumenti per le linee guida di design

​get-design-guidelines

​update-design-guidelines

​delete-design-guidelines

​Strumenti di chat

​get-chat-history

​Strumenti per gli allegati

​upload-attachment

​Strumenti per Figma

​import-figma

​Strumenti per piano e fatturazione

​get-plan-details

​Strumenti di design AI

​ai-design-screens

​ai-generate-screen-variant

​ai-edit-screen-variant

​Strumenti rinominati

Strumenti per i file

`list-files`

`get-file`

`create-file`

`update-file`

`delete-file`

Strumenti per le schermate

`list-screens`

`get-screen-image`

`get-screen-jsx`

`add-screen-jsx`

`replace-screen-jsx`

`rename-screen`

`delete-screen`

Immagini in JSX

Valori dei campi della schermata

Strumenti per le linee guida di design

`get-design-guidelines`

`update-design-guidelines`

`delete-design-guidelines`

Strumenti di chat

`get-chat-history`

Strumenti per gli allegati

`upload-attachment`

Strumenti per Figma

`import-figma`

Strumenti per piano e fatturazione

`get-plan-details`

Strumenti di design AI

`ai-design-screens`

`ai-generate-screen-variant`

`ai-edit-screen-variant`

Strumenti rinominati