Referència d'eines de MCP

En cas d’èxit, cada eina excepte get-screen-image retorna el seu resultat dues vegades: com a structuredContent (validat contra l’esquema de sortida publicat de l’eina) i com el mateix objecte serialitzat en un bloc de text, { type: "text", text: "<json-string>" }, per als clients que no llegeixen contingut estructurat. get-screen-image retorna només un bloc d’imatge de MCP: { type: "image", data: "<base64>", mimeType: "image/png" }. En cas d’error, isError: true s’estableix i el bloc de text conté un missatge d’error breu. Els errors que pots resoldre (una discrepància de nom en esborrar, un enllaç de Figma no vàlid, unes directrius de disseny no vàlides, un problema amb un adjunt o un temps d’espera de generació esgotat) expliquen què cal corregir. Altres errors retornen un missatge genèric com Failed to list files.

Preus: les quatre eines de disseny amb IA (ai-generate-screens, ai-edit-screens, ai-generate-screen-variant i ai-edit-screen-variant) consumeixen la mateixa quota de missatges que l’aplicació de Flowstep. Totes les altres eines són gratuïtes. Consulta Límits d’ús.

Cada eina també publica anotacions de MCP perquè el client sàpiga què fa. delete-file, delete-screen, delete-design-guidelines, replace-screen-jsx, ai-edit-screens i ai-edit-screen-variant estan marcades com a destructives perquè eliminen o sobreescriuen contingut existent.

Eines de fitxers

`list-files`

Llista les metadades dels teus fitxers de Flowstep. Crida-la primer per comprovar si ja existeix un fitxer rellevant. No retorna contingut de pantalles: fes servir get-screen-image o get-screen-jsx per a això. Entrada

Paràmetre	Tipus	Per defecte	Descripció
`orderByCreation`	`boolean`	`true`	Ordena del més recent al més antic per `created_at` (`true`) o per `updated_at` (`false`). Fes servir `false` per trobar fitxers editats recentment
`limit`	`integer` (1–100)	`20`	Nombre màxim de fitxers retornats. Una pàgina completa pot significar que hi ha més fitxers
`offset`	`integer` (≥0)	`0`	Fitxers que cal saltar. La pàgina següent és `offset + limit`

Sortida: { 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 si has creat el fitxer.
shared_with_me: true si el fitxer s’ha compartit directament amb tu, no només a través de la teva organització.
url: obre el fitxer a l’editor de Flowstep.

`get-file`

Obté les metadades d’un sol fitxer. El contingut del fitxer s’omet intencionadament: fes servir get-screen-image o get-screen-jsx per inspeccionar pantalles, i get-design-guidelines per obtenir les directrius adjuntes. Si tens una invitació pendent al fitxer, cridar get-file l’accepta. Entrada

Paràmetre	Tipus	Descripció
`id`	`uuid`	ID del fitxer

Sortida: { 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: el teu accés al fitxer, read o write.

`create-file`

Crea un fitxer de Flowstep en blanc, sense pantalles. Per crear un fitxer i generar pantalles en un sol pas, crida ai-generate-screens sense fileId. Fes servir create-file per als fluxos code-first, seguit de add-screen-jsx. Entrada

Paràmetre	Tipus	Descripció
`name`	`string` (mín. 1)	Nom visible del fitxer nou

Sortida: { file, user_access_level }, amb la mateixa forma que get-file. owner és sempre true i user_access_level és sempre write. Fes servir el file.id retornat com a fileId en les crides posteriors a les eines.

`update-file`

Canvia el nom d’un fitxer. Entrada

Paràmetre	Tipus	Descripció
`id`	`uuid`	ID del fitxer
`name`	`string` (mín. 1)	Nou nom visible

Sortida: { file, user_access_level }, amb la mateixa forma que get-file.

`delete-file`

Elimina un fitxer de manera permanent. El name que passes es compara amb el nom visible actual del fitxer abans de l’eliminació; si no coincideix, l’eliminació s’aborta. Així s’evita esborrar per error el fitxer equivocat. Els agents tenen instruccions de confirmar-ho amb tu abans. Entrada

Paràmetre	Tipus	Descripció
`id`	`uuid`	ID del fitxer
`name`	`string`	Nom visible actual del fitxer: ha de coincidir o l’eliminació s’aborta

Sortida: { "deleted": true }

Això és irreversible. Totes les pantalles del fitxer s’eliminen.

Eines de pantalles

`list-screens`

Llista les pantalles d’un fitxer, en l’ordre del llenç. Crida-la després de list-files per veure què hi ha en un fitxer. Fes servir els valors screenId retornats amb les altres eines de pantalla i amb les eines de disseny amb IA. Entrada

Paràmetre	Tipus	Descripció
`fileId`	`uuid`	ID del fitxer

Sortida: { 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’últim prompt de generació de la pantalla, o una cadena buida si mai no s’ha generat (per exemple, una pantalla afegida amb add-screen-jsx).
fidelity: lofi, hifi o ui.

`get-screen-image`

Renderitza una pantalla a PNG i la retorna com a imatge en línia. Requereix un client que admeti blocs d’imatge. Crida-la una vegada per a cada screenId retornat per una eina de disseny amb IA, add-screen-jsx, replace-screen-jsx o import-figma. Entrada

Paràmetre	Tipus	Descripció
`fileId`	`uuid`	ID del fitxer
`screenId`	`uuid`	Un `screenId` de `list-screens` o de l’array `screenIds` retornat per una eina de disseny

Sortida: bloc de contingut d’imatge de MCP (image/png). data és base64 estàndard dels bytes del PNG, no un URI de dades. Aquesta eina no té structuredContent.

`get-screen-jsx`

Obté una pantalla com a JSX, més les seves metadades, perquè puguis construir-ne a partir d’ella al teu codi, o editar-la i escriure-la de nou amb replace-screen-jsx. Fes servir get-screen-image per a una vista prèvia visual. Entrada

Paràmetre	Tipus	Per defecte	Descripció
`fileId`	`uuid`	—	ID del fitxer
`screenId`	`uuid`	—	Un `screenId` de `list-screens` o de l’array `screenIds` retornat per una eina de disseny
`includeIds`	`boolean`	`false`	Inclou un atribut `data-id` als elements de `jsx`. Fes-lo servir quan necessitis identificadors d’elements per passar com a `elementIds` a `ai-generate-screens` (referència visual) o `ai-edit-screens` (àmbit d’edició)

Sortida: { 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: només marcatge. Els atributs data-id s’inclouen només quan includeIds és true.
prompt: l’últim prompt de generació, o una cadena buida si la pantalla mai no s’ha generat.
fragments: elements compartits emmagatzemats a la pantalla, com una barra de navegació, una capçalera o un logotip, com a objectes { purpose, markup }. És buit quan no n’hi ha cap. Passa’ls de nou a replace-screen-jsx per conservar-los o actualitzar-los.

Consulta Valors dels camps de pantalla per als valors de fidelity, screenType i colorTheme.

`add-screen-jsx`

Afegeix una pantalla nova a un fitxer a partir de JSX que has escrit. És el camí code-first i és gratuït: fes servir ai-generate-screens quan vulguis que la IA de Flowstep dissenyi la pantalla. add-screen-jsx sempre crea una pantalla nova: per sobreescriure’n una d’existent, fes servir replace-screen-jsx. Quan la pantalla nova es basa en una d’existent, parteix de get-screen-jsx (sense includeIds) per a name, fidelity, screenType, colorTheme i jsx, i després canvia el que hagi de ser diferent. Entrada

Paràmetre	Tipus	Per defecte	Descripció
`fileId`	`uuid`	—	ID del fitxer
`name`	`string` (1–100 caràcters)	—	Nom visible opcional. Omet-lo perquè la pantalla rebi el nom automàtic `Screen N`
`fidelity`	`string`	`"ui"`	Fidelitat de la pantalla
`screenType`	`string`	—	Obligatori: el dispositiu o la finestra per a la qual està dissenyada la pantalla
`colorTheme`	`string`	`"default"`	Tema de color
`jsx`	`string`	—	Només marcatge JSX. Qualsevol atribut `data-id` s’ignora: la pantalla nova obté identificadors d’elements nous

Sortida: { fileId, screenId }. Crida get-screen-image amb screenId per veure el resultat.

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

`replace-screen-jsx`

Sobreescriu una pantalla existent amb JSX que has escrit. La pantalla conserva el seu screenId i la seva posició al llenç; els elements niuats reben identificadors nous. És el camí code-first i és gratuït: fes servir ai-edit-screens o ai-edit-screen-variant per als canvis amb IA, i add-screen-jsx per crear-ne una de nova. Parteix de get-screen-jsx (sense includeIds) i després canvia el que hagi de ser diferent. Entrada

Paràmetre	Tipus	Descripció
`fileId`	`uuid`	ID del fitxer
`screenId`	`uuid`	La pantalla que cal sobreescriure
`jsx`	`string`	Només marcatge JSX. Qualsevol atribut `data-id` s’ignora
`name`	`string` (1–100 caràcters)	Opcional. Omet-lo per conservar el nom actual
`fidelity`	`string`	Opcional. Omet-lo per conservar la fidelitat actual
`screenType`	`string`	Opcional. Omet-lo per conservar el tipus de pantalla actual
`colorTheme`	`string`	Opcional. Omet-lo per conservar el tema de color actual
`fragments`	`{ purpose, markup }[]`	Opcional. Elements compartits de `get-screen-jsx`. Omet-lo per conservar els fragments actuals, o passa `[]` per esborrar-los

Sortida: { fileId, screenId }. Crida get-screen-image amb screenId per veure el resultat.

Això substitueix el contingut de la pantalla in situ.

`rename-screen`

Canvia el nom de l’etiqueta d’una pantalla al llenç: el nom que mostren list-screens i l’editor. Només canvia l’etiqueta, no la disposició, la mida ni el contingut de la pantalla; per a això fes servir ai-edit-screens. Entrada

Paràmetre	Tipus	Descripció
`fileId`	`uuid`	ID del fitxer
`screenId`	`uuid`	El `screenId` retornat per `list-screens`
`name`	`string` (1–100 caràcters)	Nou nom de la pantalla. Els espais al principi i al final s’eliminen

Sortida: { screenId, name }.

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

`delete-screen`

Elimina una pantalla d’un fitxer de manera permanent. El name que passes es compara amb el nom visible actual de la pantalla; si no coincideix, l’eliminació s’aborta. Els agents tenen instruccions de confirmar-ho amb tu abans. Entrada

Paràmetre	Tipus	Descripció
`fileId`	`uuid`	ID del fitxer
`screenId`	`uuid`	La pantalla que cal eliminar
`name`	`string`	Nom visible actual de la pantalla: ha de coincidir o l’eliminació s’aborta

Sortida: { "deleted": true }

Valors dels camps de pantalla

get-screen-jsx retorna aquests valors, i add-screen-jsx i replace-screen-jsx els accepten:

Camp	Valors
`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`

Eines de directrius de disseny

Les directrius de disseny són text DESIGN.md emmagatzemat en un fitxer. Quan s’estableixen, s’injecten en cada generació amb IA d’aquest fitxer. Consulta Directrius de disseny.

`get-design-guidelines`

Obté les directrius de disseny adjuntes a un fitxer. Entrada

Paràmetre	Tipus	Descripció
`fileId`	`uuid`	ID del fitxer

Sortida: { guidelines }.

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

guidelines és null si no s’han establert directrius.

`update-design-guidelines`

Estableix o substitueix les directrius de disseny d’un fitxer. Passa les directrius com a cadena de text pla en el format DESIGN.md de Google, no com a objecte ni com a JSON. Si les llegeixes d’un fitxer, passa el text d’aquell fitxer. Entrada

Paràmetre	Tipus	Descripció
`fileId`	`uuid`	ID del fitxer
`designGuidelines`	`string` (mín. 1)	Text brut de les directrius. Ha de ser una cadena de text pla, no codificada en JSON

Regles de validació

El frontmatter s’ha d’obrir i tancar correctament
Les línies del frontmatter han de ser YAML vàlid d’estil de bloc
El cos Markdown no ha de contenir encapçalaments de secció ## duplicats

Si la validació falla, la crida retorna un error que comença amb Invalid design guidelines: (directrius de disseny no vàlides). Sortida: { updated, warnings? }.

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

warnings enumera els problemes de validació tova (claus desconegudes, colors no hexadecimals) que s’han acceptat però que la IA podria ignorar. S’omet quan no n’hi ha cap. Mostra’ls a l’usuari.

`delete-design-guidelines`

Esborra les directrius de disseny d’un fitxer. Esborrar directrius que no existeixen no té cap efecte. Entrada

Paràmetre	Tipus	Descripció
`fileId`	`uuid`	ID del fitxer

Sortida: { "deleted": true }

Eines de xat

`get-chat-history`

Obté la conversa de disseny associada a un fitxer: el xat de Flowstep del fitxer, no la conversa del teu client de MCP. Fes-la servir per reprendre el treball anterior sobre el fitxer. Entrada

Paràmetre	Tipus	Descripció
`fileId`	`uuid`	ID del fitxer

Sortida: { messages }. messages és buit quan no tens cap conversa de disseny al fitxer. Cada missatge té un type ("request" o "response"), un author ("human" o "ai") i un content_type. Els missatges de resposta fan servir "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" }]
    }
  ]
}

Eines d’adjunts

`upload-attachment`

Puja un fitxer de referència per fer-lo servir com a adjunt a ai-generate-screens o ai-edit-screens (ai-generate-screen-variant i ai-edit-screen-variant no accepten adjunts). Els bytes del fitxer mai no passen pel model, i el servidor mai no obté URL en nom teu. Per referenciar una pàgina web, inclou-ne la URL al message de l’eina de disseny. Hi ha dues modalitats: fes servir exactament una i no les combinis. Modalitat A: fitxers i imatges (mimeType + fileName) Un flux obligatori de tres passos per a qualsevol imatge, PDF o fitxer de text més gran:

Crida upload-attachment només amb mimeType i fileName (per exemple image/png i dog.png). La resposta és una pujada preparada, no un fitxer emmagatzemat:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "path": "attachments/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "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": "…"
}

Substitueix LOCAL_FILE_PATH a uploadCommand pel camí absolut del teu fitxer i executa exactament aquesta ordre a la teva shell: ha de sortir amb codi 0. El token de signedUrl autoritza només aquesta única pujada. Si saltes aquest pas, l’emmagatzematge queda buit i l’eina de disseny falla la comprovació prèvia.
Passa només { id, path, type } a l’array attachments de l’eina de disseny: no signedUrl, uploadCommand ni nextStep.

Per adjuntar un fitxer remot, descarrega’l primer en un camí local tu mateix (per exemple amb curl) i després segueix els mateixos tres passos. Mai no passis una URL a upload-attachment.

Paràmetre	Tipus	Descripció
`mimeType`	enum	Tipus MIME del fitxer. Un de `image/jpeg`, `image/png`, `image/webp`, `application/pdf`, `text/markdown`, `text/plain` o `text/javascript`. Fes servir `text/javascript` per a fitxers `.jsx`, `.tsx`, `.js` i `.ts`
`fileName`	`string` (mín. 1)	Nom original del fitxer amb extensió, per exemple `cat.png` o `design.md`

Modalitat B: text curt (text + mimeType) Puja text que ja és al context; no cal cap ordre de shell. La resposta està a punt per fer-la servir directament:

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

Paràmetre	Tipus	Descripció
`text`	`string` (màx. 64.000 caràcters)	Contingut de text brut. Només fitxers de text: no els facis servir per a imatges ni PDF. Més de 64.000 caràcters? Fes servir la modalitat A
`mimeType`	enum	Un de `text/markdown`, `text/plain` o `text/javascript`

Passa el { id, path, type } resultant a l’array attachments de ai-generate-screens o ai-edit-screens. La mida màxima de fitxer és de 3 MB en totes dues modalitats, i els PDF estan limitats a 100 pàgines. type és "image" per als fitxers d’imatge i "document" per als PDF i els fitxers de text.

Eines de Figma

`import-figma`

Importa un marc de Figma en un fitxer de Flowstep com a elements editables al seu llenç. Cada importació afegeix una pantalla nova: importar el mateix marc dues vegades et dóna dues pantalles, de manera que has d’eliminar l’antiga amb delete-screen si la volies substituir. L’organització del fitxer ha de tenir Figma connectat a la configuració de Flowstep. Entrada

Paràmetre	Tipus	Descripció
`fileId`	`uuid`	El fitxer de Flowstep on importar el marc. No és la clau del fitxer de Figma de `figmaUrl`
`figmaUrl`	`string`	Enllaç a un marc específic de Figma, amb un `node-id`. A Figma, fes clic dret al marc i tria Copy/Paste as → Copy link to selection. Un enllaç a una pàgina importa tots els marcs de primer nivell d’aquella pàgina (limitat a 20 marcs a través de MCP)

Sortida: { fileId, screenId, frameCount? }. screenId és la pantalla importada: passa-la a get-screen-image per veure el resultat. Quan un enllaç de pàgina importa diversos marcs, screenId és null i es retorna frameCount en lloc seu; crida list-screens i després get-screen-image per a cada pantalla nova.

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

Eines de pla i facturació

`get-plan-details`

Obté el pla de Flowstep de la teva organització, l’estat de la subscripció, l’ús i la quota restant. No té entrada: l’organització es resol a partir de l’usuari autenticat. Fes-lo servir per comprovar la teva quota abans de cridar les eines de disseny amb IA. Sortida: { plan, subscription, limits, usage, remaining }.

Camp	Descripció
`plan`	`{ name, code, type }`. `type` és `"free"` o `"paid"`
`subscription`	`{ isPaid, isTrial, startDate, endDate, trialDaysRemaining }`
`limits`	Límits per funcionalitat, indexats per funcionalitat (per exemple `messages`). Cada un té objectes `daily` i `monthly` opcionals amb valors `max` i `warn`, més un indicador `unlimited`
`usage`	Ús per funcionalitat fins ara, com a `{ daily, monthly }`
`remaining`	Quota restant per funcionalitat, com a `{ daily, monthly }`. S’omet per a les funcionalitats il·limitades

Els límits varien segons el pla: consulta Preus i Límits d’ús.

Eines de disseny amb IA

Aquestes quatre eines dissenyen a partir d’una descripció o d’una preconfiguració: mai no accepten ni reutilitzen JSX. Cada crida consumeix la mateixa quota de missatges que l’aplicació de Flowstep i es bloqueja fins que la generació es completa o expira (180 segons).

Eina	Serveix per a
`ai-generate-screens`	Generar una o més pantalles noves a partir d’una descripció
`ai-edit-screens`	Canviar una o més pantalles existents in situ a partir d’instruccions de text lliure
`ai-generate-screen-variant`	Afegir una variant del pas següent, d’un estat d’error o buit, o d’una plataforma d’una pantalla existent
`ai-edit-screen-variant`	Aplicar una preconfiguració d’edició o de redisseny a una pantalla existent completa

Totes quatre retornen { status, fileId, screenIds, designGuidelinesUpdated }. Crida get-screen-image una vegada per a cada screenId per veure el resultat.

designGuidelinesUpdated: un resum breu del canvi quan les directrius DESIGN.md del fitxer s’han actualitzat automàticament durant aquest torn; altrament, null.

`ai-generate-screens`

Genera una o més pantalles noves a partir d’una descripció en text. Omet fileId per crear un fitxer nou automàticament; passa fileId per afegir pantalles a un fitxer existent. Aquesta eina sempre crea pantalles noves: mai no edita les existents in situ. Entrada

Paràmetre	Tipus	Per defecte	Descripció
`fileId`	`uuid`	—	Fitxer de destinació. Omet-lo per crear un fitxer nou automàticament. Obligatori quan `elementIds` està definit
`message`	`string`	—	Descripció de les pantalles que cal generar. Inclou aquí les URL de pàgines web que vols que Flowstep referenciï
`elementIds`	`uuid[]`	`[]`	Referències visuals opcionals: `screenId` de `list-screens` i/o `data-id` d’elements de `get-screen-jsx` (amb `includeIds`). Només s’usen com a inspiració d’estil i de disposició; no s’editen, i el seu JSX no es reutilitza
`attachments`	`{ id, path, type }[]` (màx. 5)	`[]`	Fitxers de `upload-attachment`: imatges, PDF o fitxers de codi i text. No incrustis el contingut dels fitxers al missatge

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

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

status: "generated" quan s’han construït pantalles. "chat" quan Flowstep ha respost sense construir res; en aquest cas reply conté la resposta i screenIds és buit. Si el teu encàrrec és ambigu, el teu agent hauria de demanar-te que l’aclareixis i tornar a cridar l’eina.

`ai-edit-screens`

Canvia una o més pantalles existents in situ a partir d’una instrucció de text: tematització, text, disposició o canvis coordinats en diverses pantalles. Pots apuntar a pantalles completes o a elements individuals dins d’elles. Per a un canvi preconfigurat d’una pantalla completa, ai-edit-screen-variant és més senzill. Entrada

Paràmetre	Tipus	Per defecte	Descripció
`fileId`	`uuid`	—	Fitxer de destinació
`message`	`string`	—	Instruccions que descriuen els canvis a fer. Inclou aquí les URL de pàgines web que vols que Flowstep referenciï
`elementIds`	`uuid[]` (mín. 1)	—	Què editar: `screenId` de `list-screens` i/o `data-id` d’elements de `get-screen-jsx` (amb `includeIds`). Un `screenId` edita la pantalla completa
`attachments`	`{ id, path, type }[]` (màx. 5)	`[]`	Fitxers de `upload-attachment`

Sortida: { status, fileId, screenIds, designGuidelinesUpdated, reply? }, amb el mateix comportament de status i reply que ai-generate-screens.

Això sobreescriu el contingut de les pantalles destinatàries in situ.

`ai-generate-screen-variant`

Afegeix una pantalla nova derivada exactament d’una pantalla existent: el pas següent del flux, un estat d’error o buit, o una versió per a una altra plataforma. La pantalla original no es modifica. Per afegir una pantalla que no sigui una variant d’una pantalla existent (per exemple, una pantalla de configuració), fes servir ai-generate-screens amb un fileId. Entrada

Paràmetre	Tipus	Descripció
`fileId`	`uuid`	Fitxer de destinació
`screenId`	`uuid`	La pantalla existent d’on derivar
`operationVariant`	enum	Obligatori: com es relaciona la pantalla nova amb l’existent

`operationVariant`	Afegeix
`next_screen`	La pantalla següent del flux d’usuari
`error_state`	Un estat d’error de la pantalla
`empty_state`	Un estat buit de la pantalla
`web_version`	Una versió web
`mobile_version`	Una versió mòbil
`tablet_version`	Una versió de tauleta
`mobile_ios_version`	Una versió per a iOS
`mobile_android_version`	Una versió per a Android

Sortida: { status, fileId, screenIds, designGuidelinesUpdated }. status és sempre "generated".

`ai-edit-screen-variant`

Canvia exactament una pantalla existent in situ fent servir una preconfiguració: millora’n el tema o l’acabat, prova una disposició o un estil visual diferents, o redissenya-la des de zero. Per a instruccions de text lliure o per a una edició precisa d’elements individuals, fes servir ai-edit-screens. Entrada

Paràmetre	Tipus	Descripció
`fileId`	`uuid`	Fitxer de destinació
`screenId`	`uuid`	La pantalla existent a canviar
`operationVariant`	enum	Obligatori: la preconfiguració d’edició o de redisseny a aplicar

`operationVariant`	Tipus	Efecte
`dark_theme`	Edició	Canvia la pantalla a un tema fosc
`light_theme`	Edició	Canvia la pantalla a un tema clar
`make_pretty`	Edició	Millora l’aspecte visual de la pantalla
`different_layout`	Redisseny	Prova una disposició diferent
`different_style`	Redisseny	Prova un estil visual diferent
`from_scratch`	Redisseny	Redissenya la pantalla des de zero

Sortida: { status, fileId, screenIds, designGuidelinesUpdated }. status és sempre "generated".

Això sobreescriu el contingut de la pantalla in situ.

Eines reanomenades

Els noms de les eines han canviat el setembre del 2026. Si tens prompts, scripts o instruccions d’agent que fan servir els noms antics, actualitza’ls:

Nom antic	Nom nou
`get-screen`	`get-screen-jsx`
`add-screen`	`add-screen-jsx`
`replace-screen`	`replace-screen-jsx`
`create-new-design`	`ai-generate-screens`
`edit-design` (instruccions de text lliure)	`ai-edit-screens`
`edit-design` (amb una preconfiguració `operationVariant`)	`ai-edit-screen-variant`
`regenerate-design`	`ai-edit-screen-variant`
`expand-design`	`ai-generate-screen-variant`

Els noms dels paràmetres també han canviat: les eines de disseny amb IA reben elementIds (o un únic screenId per a les eines de variant) en lloc de targets; add-screen-jsx rep jsx i camps de metadades explícits en lloc de jsxContent amb un comentari de metadades; create-file rep name en lloc de title; i les eines de directrius de disseny reben fileId en lloc de resourceId i linkedTo.

​Eines de fitxers

​list-files

​get-file

​create-file

​update-file

​delete-file

​Eines de pantalles

​list-screens

​get-screen-image

​get-screen-jsx

​add-screen-jsx

​replace-screen-jsx

​rename-screen

​delete-screen

​Valors dels camps de pantalla

​Eines de directrius de disseny

​get-design-guidelines

​update-design-guidelines

​delete-design-guidelines

​Eines de xat

​get-chat-history

​Eines d’adjunts

​upload-attachment

​Eines de Figma

​import-figma

​Eines de pla i facturació

​get-plan-details

​Eines de disseny amb IA

​ai-generate-screens

​ai-edit-screens

​ai-generate-screen-variant

​ai-edit-screen-variant

​Eines reanomenades

Eines de fitxers

`list-files`

`get-file`

`create-file`

`update-file`

`delete-file`

Eines de pantalles

`list-screens`

`get-screen-image`

`get-screen-jsx`

`add-screen-jsx`

`replace-screen-jsx`

`rename-screen`

`delete-screen`

Valors dels camps de pantalla

Eines de directrius de disseny

`get-design-guidelines`

`update-design-guidelines`

`delete-design-guidelines`

Eines de xat

`get-chat-history`

Eines d’adjunts

`upload-attachment`

Eines de Figma

`import-figma`

Eines de pla i facturació

`get-plan-details`

Eines de disseny amb IA

`ai-generate-screens`

`ai-edit-screens`

`ai-generate-screen-variant`

`ai-edit-screen-variant`

Eines reanomenades