> ## Documentation Index > Fetch the complete documentation index at: https://docs.flowstep.ai/llms.txt > Use this file to discover all available pages before exploring further. # Riferimento strumenti MCP > Schema di input, forma di output ed esempi per tutti i 20 strumenti MCP di Flowstep. Tutti gli strumenti restituiscono un array `content` di blocchi di contenuto MCP. Gli strumenti di testo restituiscono `{ type: "text", text: "" }`. Gli strumenti di immagine restituiscono `{ type: "image", data: "", mimeType: "image/png" }`. In caso di errore, `isError: true` è impostato e il blocco di testo contiene il messaggio di errore. *** ## Strumenti file ### `list-files` Elenca i file Flowstep per l'utente corrente. **Input** | Parametro | Tipo | Impostazione predefinita | Descrizione | | ----------------- | ----------------- | ------------------------ | ---------------------------- | | `orderByCreation` | `boolean` | `true` | Ordina per data di creazione | | `limit` | `integer` (1–100) | `20` | Numero di file da restituire | | `offset` | `integer` (≥0) | `0` | Offset di paginazione | **Output** — Array JSON di oggetti file. ```json theme={"system"} [ { "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", "owner": true, "url": "https://app.flowstep.ai/file?activeFileId=5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0" } ] ``` *** ### `get-file` Ottieni un singolo file per ID. Il contenuto del file è volutamente omesso — usa `get-screen` o `get-screen-image` per ispezionare le schermate, e `get-design-guidelines` per recuperare le linee guida di design allegate. **Input** | Parametro | Tipo | Descrizione | | --------- | ------ | ----------- | | `id` | `uuid` | ID file | **Output** — Oggetto file JSON. ```json theme={"system"} { "file": { "id": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0", "name": "Dashboard redesign", "project_id": "81cb84d6-c69f-492c-a895-7421b60d1a6d", "created_at": "2026-04-30T15:02:13.120152+00:00", "updated_at": "2026-04-30T15:02:13.120152+00:00", "access_level": "private", "owner": true, "url": "https://app.flowstep.ai/file?activeFileId=5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0" }, "user_access_level": "write" } ``` *** ### `create-file` Crea un nuovo file Flowstep. **Input** | Parametro | Tipo | Descrizione | | --------- | ---------------- | ----------- | | `title` | `string` (min 1) | Nome file | **Output** — Oggetto file JSON con l'`id` del nuovo file. ```json theme={"system"} { "id": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0", "name": "Dashboard redesign", "project_id": "81cb84d6-c69f-492c-a895-7421b60d1a6d", "created_at": "2026-04-30T15:02:13.120152+00:00", "updated_at": "2026-04-30T15:02:13.120152+00:00", "access_level": "private", "user_access_level": "write", "owner": true, "url": "https://app.flowstep.ai/file?activeFileId=5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0" } ``` Usa l'`id` restituito come `fileId` nelle successive chiamate agli strumenti. *** ### `update-file` Rinomina un file. **Input** | Parametro | Tipo | Descrizione | | --------- | ---------------- | ----------- | | `id` | `uuid` | ID file | | `name` | `string` (min 1) | Nuovo nome | **Output** — Oggetto file aggiornato nella stessa forma di `get-file`. ```json theme={"system"} { "file": { "id": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0", "name": "Dashboard redesign (v2)", "project_id": "81cb84d6-c69f-492c-a895-7421b60d1a6d", "created_at": "2026-04-30T15:02:13.120152+00:00", "updated_at": "2026-04-30T15:02:13.120152+00:00", "access_level": "private", "owner": true, "url": "https://app.flowstep.ai/file?activeFileId=5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0" }, "user_access_level": "write" } ``` *** ### `delete-file` Elimina permanentemente un file. Il `name` che passi viene verificato rispetto al nome effettivo del file prima dell'eliminazione — se non corrisponde, l'eliminazione viene interrotta. Questo previene l'eliminazione accidentale del file sbagliato. **Input** | Parametro | Tipo | Descrizione | | --------- | -------- | ----------------------------------------------------------------------------------------- | | `id` | `uuid` | ID file | | `name` | `string` | Nome corrente del file — deve corrispondere esattamente o l'eliminazione viene interrotta | **Output** — `"File deleted successfully"` Questa azione è irreversibile. Tutte le schermate nel file vengono eliminate. *** ## Strumenti schermata ### `list-screens` Elenca tutte le schermate generate per un file. Usa i valori `screenId` restituiti per fare riferimento alle schermate in `get-screen`, `get-screen-image`, `upload-attachment`, e come `targets` in `edit-design`, `regenerate-design`, o `expand-design`. **Input** | Parametro | Tipo | Descrizione | | --------- | ------ | ----------- | | `fileId` | `uuid` | ID file | **Output** — Array JSON di riepiloghi schermata. ```json theme={"system"} [ { "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbe", "name": "Mobile login screen", "fidelity": "ui", "prompt": "Generate a simple mobile login screen with email and password fields and a sign in button", "createdAt": "2026-04-30T15:02:37.444139+00:00" } ] ``` `name` è il nome della schermata assegnato dall'utente, oppure `null` se senza nome. *** ### `get-screen` Ottieni il codice JSX per una schermata per poterlo modificare o utilizzare al di fuori di Flowstep. Usa `get-screen-image` per un'anteprima visiva invece. **Input** | Parametro | Tipo | Descrizione | | ---------- | ------ | -------------------------------------------------------------------------------------------------------- | | `fileId` | `uuid` | ID file | | `screenId` | `uuid` | L'`screenId` restituito da `list-screens` o dall'array `screenIds` restituito da uno strumento di design | **Output** — La schermata come codice (JSX). Nota il commento sulla prima riga che è obbligatorio quando si usa lo strumento `add-screen`. ```json theme={"system"}
World Clock
Search cities...
...
; ``` *** ### `add-screen` Aggiungi una nuova schermata a un file Flowstep da una stringa JSX raw. **Input** | Parametro | Tipo | Descrizione | | ------------ | -------- | ------------------------------------------------------------------------------------ | | `fileId` | `uuid` | ID file | | `jsxContent` | `string` | JSX da aggiungere al file come schermata | | `screenType` | `string` | Obbligatorio se il tipo di schermata non è definito come commento all'inizio del JSX | **Note** - Un commento simile a quello sottostante DEVE essere presente come prima riga del JSX poiché viene utilizzato per aggiungere correttamente la schermata. `screenType`, `name`, e `screenId` sono tutti facoltativi — `screenId` viene utilizzato (internamente) se presente (ad es. quando si passa JSX copiato dall'output di `get-screen`) ma non è obbligatorio. Il nome della schermata viene preso dal campo `name` del commento (visualizzato come "Copy of \"), oppure "Untitled" se assente. `` **Output** — L'ID della schermata appena aggiunta. ```json theme={"system"} { "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbf" } ``` *** ### `get-screen-image` Rendering di una schermata in PNG e restituzione come immagine inline. Richiede un client che supporti blocchi di contenuto immagine. **Input** | Parametro | Tipo | Descrizione | | ---------- | ------ | -------------------------------------------------------------------------------------------------------- | | `fileId` | `uuid` | ID file | | `screenId` | `uuid` | L'`screenId` restituito da `list-screens` o dall'array `screenIds` restituito da uno strumento di design | **Output** — Blocco di contenuto immagine MCP (`image/png`). *** ## Strumenti AI `regenerate-design`, `expand-design`, e `edit-design` richiedono il contesto di design che è presente solo sulle schermate generate originariamente con un array `designs`. Le schermate generate senza contesto di design restituiranno un errore. Workaround: usa `upload-attachment` per eseguire il rendering della schermata come immagine, quindi chiama `create-new-design` con l'immagine in `attachments` e un messaggio che descrive le modifiche desiderate. ### `create-new-design` Genera uno o più design di schermata da un prompt di testo. Ometti `fileId` per creare automaticamente un nuovo file. Si blocca fino al completamento della generazione o al timeout (180 secondi). **Input** | Parametro | Tipo | Impostazione predefinita | Descrizione | | ------------- | --------------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `fileId` | `uuid` | — | File di destinazione — ometti per creare automaticamente un nuovo file | | `message` | `string` | — | Prompt che descrive le schermate da generare | | `attachments` | `AttachmentRequestData[]` (max 5) | `[]` | Allegati pre-caricati — immagini, PDF o file di codice. Carica sempre tramite `upload-attachment` prima; non inserire il contenuto del file nel messaggio | | `designs` | `DesignRequestData[]` | `[]` | Riferimenti di design | **Output** — `{ fileId, screenIds }`. Passa ogni `screenId` a `get-screen-image` per visualizzare i risultati. ```json theme={"system"} { "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0", "screenIds": ["3f9e6eb6-5525-4383-9375-67e0bd762dbe"] } ``` *** ### `regenerate-design` Ripeti le schermate esistenti da zero o con una variazione di stile. Richiede almeno un `screenId` in `targets`. Si blocca fino al completamento della generazione o al timeout (180 secondi). **Input** | Parametro | Tipo | Impostazione predefinita | Descrizione | | ------------------ | ----------------------------------------------------------- | ------------------------ | ----------------------------------------------- | | `fileId` | `uuid` | — | File di destinazione | | `message` | `string` | — | Testo del prompt | | `targets` | `uuid[]` (min 1) | — | screenIds delle schermate da rigenerare | | `operationVariant` | `"different_layout" \| "different_style" \| "from_scratch"` | — | Variante di stile facoltativa | | `designs` | `DesignRequestData[]` | `[]` | Riferimenti di design (risolti automaticamente) | **Output** — `{ fileId, screenIds }`. Passa ogni `screenId` a `get-screen-image` per visualizzare i risultati. *** ### `expand-design` Aggiungi schermate successive a un design esistente. Richiede almeno un `screenId` in `targets` e un `operationVariant` obbligatorio. Si blocca fino al completamento della generazione o al timeout (180 secondi). **Input** | Parametro | Tipo | Impostazione predefinita | Descrizione | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | ----------------------------------------------------------- | | `fileId` | `uuid` | — | File di destinazione | | `message` | `string` | — | Testo del prompt | | `targets` | `uuid[]` (min 1) | — | screenIds delle schermate da cui espandere | | `operationVariant` | `"next_screen" \| "error_state" \| "empty_state" \| "web_version" \| "mobile_version" \| "tablet_version" \| "mobile_ios_version" \| "mobile_android_version"` | — | **Obbligatorio** — tipo di schermata successive da generare | | `designs` | `DesignRequestData[]` | `[]` | Riferimenti di design (risolti automaticamente) | **Output** — `{ fileId, screenIds }`. Passa ogni `screenId` a `get-screen-image` per visualizzare i risultati. *** ### `edit-design` Modifica le schermate esistenti tramite un prompt. Richiede almeno un `screenId` in `targets`. Si blocca fino al completamento della generazione o al timeout (180 secondi). **Input** | Parametro | Tipo | Impostazione predefinita | Descrizione | | ------------------ | ------------------------------------------------ | ------------------------ | ---------------------------------------------------------------------- | | `fileId` | `uuid` | — | File di destinazione | | `message` | `string` | — | Istruzioni che descrivono le modifiche da applicare | | `targets` | `uuid[]` (min 1) | — | screenIds delle schermate da modificare | | `operationVariant` | `"dark_theme" \| "light_theme" \| "make_pretty"` | — | Scorciatoia di stile facoltativa | | `attachments` | `AttachmentRequestData[]` (max 5) | `[]` | Allegati pre-caricati. Carica sempre tramite `upload-attachment` prima | | `designs` | `DesignRequestData[]` | `[]` | Riferimenti di design (risolti automaticamente) | **Output** — `{ fileId, screenIds }`. Passa ogni `screenId` a `get-screen-image` per visualizzare i risultati. *** ### `upload-attachment` Carica un file da usare come allegato in `create-new-design` o `edit-design`. Restituisce `{ id, path, type, mimeType }` — passa questo oggetto direttamente nell'array `attachments`. Due modalità: **Modalità 1 — Schermata per ID** Passa `screenId` e `fileId`. Il server recupera lo stato della schermata dal database e la esegue il rendering come immagine. | Parametro | Tipo | Descrizione | | ---------- | ------ | --------------------------------------------- | | `fileId` | `uuid` | File che contiene la schermata (obbligatorio) | | `screenId` | `uuid` | Schermata da renderizzare | **Modalità 2 — File esterno** Passa il contenuto del file direttamente. I file binari devono essere codificati in base64; i file di testo (incluso il codice sorgente) vengono passati come stringhe UTF-8 semplici. | Parametro | Tipo | Descrizione | | ---------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | `fileData` | `string` | Contenuto del file — base64 per binari, stringa UTF-8 per testo | | `fileName` | `string` | Nome file originale | | `mimeType` | `"image/jpeg" \| "image/png" \| "image/webp" \| "application/pdf" \| "text/plain" \| "text/javascript"` | Tipo MIME. Usa `text/javascript` per i file `.jsx`, `.tsx`, `.js`, `.ts` | Dimensione massima file: **3 MB**. Per le immagini grandi, preferisci `image/jpeg` a `image/png`. **Output** ```json theme={"system"} { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "path": "attachments/a1b2c3d4-e5f6-7890-abcd-ef1234567890", "type": "image", "mimeType": "image/jpeg" } ``` `type` è `"image"` per upload di immagini/PDF e `"document"` per file di testo/codice. *** ## Strumenti chat ### `get-chat-history` Ottieni la cronologia dei messaggi di chat per un file. **Input** | Parametro | Tipo | Descrizione | | --------- | ------ | ----------- | | `fileId` | `uuid` | ID file | **Output** — Oggetto JSON con un array `messages`. Ogni messaggio ha un `type` (`"request"` o `"response"`), `author` (`"human"` o `"ai"`), e `content_type` (`"text"`, `"summary"`, o `"followup"`). ```json theme={"system"} { "messages": [ { "id": "453f593d-2380-425b-ba29-127db08d6a8e", "chat_id": "146d0f19-497e-450c-ba53-3de15f6bd70b", "type": "request", "status": "success", "content": "Generate a simple mobile login screen with email and password fields", "author": "human", "content_type": "text", "sequence": 1, "request_message_id": null, "targets": [], "attachments": [] }, { "id": "d860186b-82d5-4bd1-8e8e-8ba5377a14bf", "chat_id": "146d0f19-497e-450c-ba53-3de15f6bd70b", "type": "response", "status": "success", "content": "Generated a mobile login screen with email and password input fields, sign in button, remember me checkbox, forgot password link, social login options (Apple/Google), and 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" }], "attachments": [] } ] } ``` *** ## Strumenti design ### `get-design-guidelines` Ottieni le linee guida di design memorizzate per un file. **Input** | Parametro | Tipo | Impostazione predefinita | Descrizione | | ------------ | -------- | ------------------------ | --------------- | | `resourceId` | `uuid` | — | ID file | | `linkedTo` | `"file"` | `"file"` | Tipo di risorsa | **Output** ```json theme={"system"} { "guidelines": "## Colors\n\nPrimary: #6366F1\nBackground: #FFFFFF\n\n## Typography\n\nFont: Inter", "linkedTo": "file" } ``` `guidelines` è `null` se non sono state impostate linee guida. *** ### `update-design-guidelines` Imposta o sostituisci le linee guida di design per un file. Le linee guida vengono passate come stringa di testo semplice nel formato `design.md` di Google — non passare un oggetto o JSON. Il server esegue la convalida soft e può restituire una sezione `Warnings:` nella risposta che elenca i problemi (chiavi sconosciute, colori non-hex) che sono stati accettati ma potrebbero essere ignorati dall'IA. Presentali all'utente. **Input** | Parametro | Tipo | Impostazione predefinita | Descrizione | | ------------------ | ---------------- | ------------------------ | ------------------------------------------------------------------------------------------------ | | `resourceId` | `uuid` | — | ID file | | `designGuidelines` | `string` (min 1) | — | Contenuto di testo raw delle linee guida. Deve essere una stringa semplice — non JSON-codificata | | `linkedTo` | `"file"` | `"file"` | Tipo di risorsa | **Regole di convalida** * Il frontmatter deve essere aperto e chiuso correttamente * Le righe frontmatter devono essere YAML valido in stile blocco * Il corpo Markdown non deve contenere intestazioni `##` duplicate **Output** — `"Design guidelines updated successfully"`, opzionalmente seguito da una sezione `Warnings:`. *** ### `delete-design-guidelines` Cancella le linee guida di design per un file. **Input** | Parametro | Tipo | Impostazione predefinita | Descrizione | | ------------ | -------- | ------------------------ | --------------- | | `resourceId` | `uuid` | — | ID file | | `linkedTo` | `"file"` | `"file"` | Tipo di risorsa | **Output** — `"Design guidelines deleted successfully"` *** ## Strumenti Figma ### `import-figma` Importa un frame di Figma in un file di Flowstep come elementi modificabili sulla sua canvas. Reimportando lo stesso frame lo aggiorna sul posto. L'organizzazione del file deve avere Figma connesso nelle impostazioni di Flowstep. **Input** | Parametro | Tipo | Descrizione | | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `figmaUrl` | `string` | Link a uno specifico frame di Figma. In Figma, fai clic con il tasto destro sul frame e scegli **Copy link to selection**. Un link a una pagina importa tutti i frame di primo livello su quella pagina (limitati a 20 frame su MCP). | | `fileId` | `uuid` | Il file di Flowstep in cui importare il frame | **Output** — `{ fileId, screenId }`. `screenId` è l'id dell'elemento schermata importato — passalo a `get-screen-image` per visualizzare il risultato. Quando un URL di pagina importa più frame, `screenId` è `null` e `frameCount` viene restituito invece. ```json theme={"system"} { "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0", "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbe" } ``` *** ## Strumenti fatturazione ### `get-plan-details` Ottieni il piano corrente dell'utente, lo stato dell'abbonamento e la quota rimanente. Non richiede input. **Output** ```json theme={"system"} { "plan": { "name": "Starter", "code": "starter", "type": "paid" }, "subscription": { "isPaid": true, "isTrial": false, "startDate": "2025-01-01T00:00:00Z", "endDate": null, "trialDaysRemaining": null }, "limits": { "messages": { "daily": { "max": 50, "warn": 40 }, "monthly": { "max": 500, "warn": 400 }, "unlimited": false } }, "usage": { "messages": { "daily": 12, "monthly": 87 } }, "remaining": { "messages": { "daily": 38, "monthly": 413 } } } ``` I limiti variano in base al piano. Chiama questo strumento prima di un batch di generazioni per verificare la quota disponibile.