> ## 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.

# Referință MCP Tools

> Schema de intrare, formă de ieșire și exemple pentru toate 20 de unelte MCP Flowstep.

Toate uneltele returnează un tablou `content` de blocuri de conținut MCP. Uneltele de text returnează `{ type: "text", text: "<json-string>" }`. Uneltele de imagine returnează `{ type: "image", data: "<base64>", mimeType: "image/png" }`. La eșec, se setează `isError: true` și blocul de text conține mesajul de eroare.

***

## Unelte de fișiere

### `list-files`

Listează fișierele Flowstep pentru utilizatorul curent.

**Intrare**

| Parametru         | Tip               | Implicit | Descriere                      |
| ----------------- | ----------------- | -------- | ------------------------------ |
| `orderByCreation` | `boolean`         | `true`   | Sortează după data creării     |
| `limit`           | `integer` (1–100) | `20`     | Numărul de fișiere de returnat |
| `offset`          | `integer` (≥0)    | `0`      | Offset-ul paginației           |

**Ieșire** — Tablou JSON de obiecte fișier.

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

Obțin un singur fișier după ID. Conținutul fișierului este intenționat omis — utilizați `get-screen` sau `get-screen-image` pentru a inspecta ecranele, și `get-design-guidelines` pentru a prelua ghidurile atașate.

**Intrare**

| Parametru | Tip    | Descriere        |
| --------- | ------ | ---------------- |
| `id`      | `uuid` | ID-ul fișierului |

**Ieșire** — Obiect fișier 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`

Creează un nou fișier Flowstep.

**Intrare**

| Parametru | Tip              | Descriere         |
| --------- | ---------------- | ----------------- |
| `title`   | `string` (min 1) | Numele fișierului |

**Ieșire** — Obiect fișier JSON cu `id`-ul noului fișier.

```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"
}
```

Utilizați `id`-ul returnat ca `fileId` în apelurile ulterioare de unealtă.

***

### `update-file`

Redenumiți un fișier.

**Intrare**

| Parametru | Tip              | Descriere        |
| --------- | ---------------- | ---------------- |
| `id`      | `uuid`           | ID-ul fișierului |
| `name`    | `string` (min 1) | Noul nume        |

**Ieșire** — Obiect fișier actualizat în aceeași formă ca `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`

Ștergeți permanent un fișier. `name`-ul pe care îl transmiteți este verificat în raport cu numele actual al fișierului înainte de ștergere — dacă nu se potrivește, ștergerea este anulată. Aceasta previne ștergerea accidentală a fișierului greșit.

**Intrare**

| Parametru | Tip      | Descriere                                                                                 |
| --------- | -------- | ----------------------------------------------------------------------------------------- |
| `id`      | `uuid`   | ID-ul fișierului                                                                          |
| `name`    | `string` | Numele actual al fișierului — trebuie să se potrivească exact sau ștergerea va fi anulată |

**Ieșire** — `"File deleted successfully"`

<Warning>
  Aceasta este ireversibilă. Toate ecranele din fișier sunt șterse.
</Warning>

***

## Unelte de ecran

### `list-screens`

Listează toate ecranele generate pentru un fișier. Utilizați valorile `screenId` returnate pentru a face referință la ecrane în `get-screen`, `get-screen-image`, `upload-attachment`, și ca `targets` în `edit-design`, `regenerate-design`, sau `expand-design`.

**Intrare**

| Parametru | Tip    | Descriere        |
| --------- | ------ | ---------------- |
| `fileId`  | `uuid` | ID-ul fișierului |

**Ieșire** — Tablou JSON de rezumate de ecran.

```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` este numele ecranului asignat de utilizator, sau `null` dacă nu are nume.

***

### `get-screen`

Obțineți codul JSX pentru un ecran, permițând editare sau utilizare a codului în afara Flowstep. Utilizați `get-screen-image` pentru o previzualizare vizuală.

**Intrare**

| Parametru  | Tip    | Descriere                                                                                            |
| ---------- | ------ | ---------------------------------------------------------------------------------------------------- |
| `fileId`   | `uuid` | ID-ul fișierului                                                                                     |
| `screenId` | `uuid` | `screenId`-ul returnat de `list-screens` sau din tabloul `screenIds` returnat de o unealtă de design |

**Ieșire** — Ecranul ca cod (JSX). Observați comentariul din prima linie care este obligatoriu atunci când utilizați unealta `add-screen`.

```json theme={"system"}
<!-- screenType: "iphone-x-vertical" width: "375" height: "812" name: "Change to a light theme" colorTheme: "blue" screenId: "c13d3707-0efe-49f5-b6cb-0ca5ac5223d0" -->
<div className="bg-white text-zinc-950 w-full h-fit">
  <div className="flex p-6 flex-col gap-6">
    <div className="flex pt-4 justify-between items-center">
      <ArrowLeft className="size-5 text-[#71717b]" />
      <span className="font-semibold text-zinc-950 text-lg leading-7">
        World Clock
      </span>
      <Plus className="size-5 text-[#2b7fff]" />
    </div>
    <div className="rounded-xl bg-zinc-100 flex p-2 items-center gap-2">
      <Search className="size-4 text-[#71717b] ml-2" />
      <span className="text-[#71717b] text-sm leading-5">Search cities...</span>
    </div>
...
    <div className="flex pt-2 pb-4 justify-center items-center gap-4">
      <Button variant="outline" className="rounded-full px-6 gap-2">
        <Clock className="size-4" />
        <span>Compare</span>
      </Button>
      <Button className="rounded-full bg-[#2b7fff] text-blue-50 px-6 gap-2">
        <Bell className="size-4" />
        <span>Set Alert</span>
      </Button>
    </div>
  </div>
</div>;

```

***

### `add-screen`

Adaugă un nou ecran la un fișier Flowstep dintr-un șir JSX brut.

**Intrare**

| Parametru    | Tip      | Descriere                                                                       |
| ------------ | -------- | ------------------------------------------------------------------------------- |
| `fileId`     | `uuid`   | ID-ul fișierului                                                                |
| `jsxContent` | `string` | JSX de adăugat la fișier ca ecran                                               |
| `screenType` | `string` | Obligatoriu dacă tipul ecranului nu este definit ca comentariu la începutul JSX |

**Notă** - Un comentariu asemănător celui de mai jos TREBUIE să fie prezent ca prima linie a JSX, deoarece este utilizat pentru a adăuga ecranul corect. `screenType`, `name`, și `screenId` sunt toate opționale — `screenId` este utilizat (intern) dacă este prezent (de exemplu, atunci când transmiteți JSX copiat din ieșirea `get-screen`) dar nu este obligatoriu. Numele ecranului este preluat din câmpul `name` al comentariului (afișat ca "Copy of \<name>"), sau "Untitled" dacă lipsește.

`<!-- screenType: "iphone-x-vertical" width: "375" height: "812" name: "Change to a light theme" colorTheme: "blue" -->`

**Ieșire** — ID-ul ecranului nou adăugat.

```json theme={"system"}
{ "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbf" }
```

***

### `get-screen-image`

Redați un ecran la PNG și întoarceți-l ca o imagine în linie. Necesită un client care să suporte blocuri de conținut imagine.

**Intrare**

| Parametru  | Tip    | Descriere                                                                                            |
| ---------- | ------ | ---------------------------------------------------------------------------------------------------- |
| `fileId`   | `uuid` | ID-ul fișierului                                                                                     |
| `screenId` | `uuid` | `screenId`-ul returnat de `list-screens` sau din tabloul `screenIds` returnat de o unealtă de design |

**Ieșire** — Bloc de conținut imagine MCP (`image/png`).

***

## Unelte AI

<Warning>
  `regenerate-design`, `expand-design`, și `edit-design` necesită context de design care este prezent doar pe ecranele generate inițial cu un tablou `designs`. Ecranele generate fără context de design vor returna o eroare. Soluție: utilizați `upload-attachment` pentru a reda ecranul ca imagine, apoi apelați `create-new-design` cu imaginea în `attachments` și un mesaj descriind schimbările dorite.
</Warning>

### `create-new-design`

Generați unul sau mai multe design-uri de ecran dintr-un prompt text. Omiteți `fileId` pentru a crea automat un nou fișier. Se blochează până când generarea se completează sau expirează (180 de secunde).

**Intrare**

| Parametru     | Tip                               | Implicit | Descriere                                                                                                                                                                    |
| ------------- | --------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fileId`      | `uuid`                            | —        | Fișier țintă — omiteți pentru a crea automat un nou fișier                                                                                                                   |
| `message`     | `string`                          | —        | Prompt descriind ecranele de generat                                                                                                                                         |
| `attachments` | `AttachmentRequestData[]` (max 5) | `[]`     | Atașamente preîncărcate — imagini, PDF-uri sau fișiere de cod. Încărcați întotdeauna via `upload-attachment` mai întâi; nu încărcați în linie conținutul fișierelor în mesaj |
| `designs`     | `DesignRequestData[]`             | `[]`     | Referințe de design                                                                                                                                                          |

**Ieșire** — `{ fileId, screenIds }`. Transmiteți fiecare `screenId` la `get-screen-image` pentru a vedea rezultatele.

```json theme={"system"}
{
  "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
  "screenIds": ["3f9e6eb6-5525-4383-9375-67e0bd762dbe"]
}
```

***

### `regenerate-design`

Refaceți ecranele existente de la zero sau cu o variație de stil. Necesită cel puțin un `screenId` în `targets`. Se blochează până când generarea se completează sau expirează (180 de secunde).

**Intrare**

| Parametru          | Tip                                                         | Implicit | Descriere                               |
| ------------------ | ----------------------------------------------------------- | -------- | --------------------------------------- |
| `fileId`           | `uuid`                                                      | —        | Fișier țintă                            |
| `message`          | `string`                                                    | —        | Text prompt                             |
| `targets`          | `uuid[]` (min 1)                                            | —        | screenIds ale ecranelor de regenerat    |
| `operationVariant` | `"different_layout" \| "different_style" \| "from_scratch"` | —        | Variantă de stil opțională              |
| `designs`          | `DesignRequestData[]`                                       | `[]`     | Referințe de design (rezolvate automat) |

**Ieșire** — `{ fileId, screenIds }`. Transmiteți fiecare `screenId` la `get-screen-image` pentru a vedea rezultatele.

***

### `expand-design`

Adaugă ecrane suplimentare la un design existent. Necesită cel puțin un `screenId` în `targets` și un `operationVariant` obligatoriu. Se blochează până când generarea se completează sau expirează (180 de secunde).

**Intrare**

| Parametru          | Tip                                                                                                                                                            | Implicit | Descriere                                                |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------- |
| `fileId`           | `uuid`                                                                                                                                                         | —        | Fișier țintă                                             |
| `message`          | `string`                                                                                                                                                       | —        | Text prompt                                              |
| `targets`          | `uuid[]` (min 1)                                                                                                                                               | —        | screenIds ale ecranelor din care să se extindă           |
| `operationVariant` | `"next_screen" \| "error_state" \| "empty_state" \| "web_version" \| "mobile_version" \| "tablet_version" \| "mobile_ios_version" \| "mobile_android_version"` | —        | **Obligatoriu** — tipul ecranului suplimentar de generat |
| `designs`          | `DesignRequestData[]`                                                                                                                                          | `[]`     | Referințe de design (rezolvate automat)                  |

**Ieșire** — `{ fileId, screenIds }`. Transmiteți fiecare `screenId` la `get-screen-image` pentru a vedea rezultatele.

***

### `edit-design`

Modificați ecranele existente printr-un prompt. Necesită cel puțin un `screenId` în `targets`. Se blochează până când generarea se completează sau expirează (180 de secunde).

**Intrare**

| Parametru          | Tip                                              | Implicit | Descriere                                                                        |
| ------------------ | ------------------------------------------------ | -------- | -------------------------------------------------------------------------------- |
| `fileId`           | `uuid`                                           | —        | Fișier țintă                                                                     |
| `message`          | `string`                                         | —        | Instrucțiuni descriind editările de aplicat                                      |
| `targets`          | `uuid[]` (min 1)                                 | —        | screenIds ale ecranelor de editat                                                |
| `operationVariant` | `"dark_theme" \| "light_theme" \| "make_pretty"` | —        | Scurtătură de stil opțională                                                     |
| `attachments`      | `AttachmentRequestData[]` (max 5)                | `[]`     | Atașamente preîncărcate. Încărcați întotdeauna via `upload-attachment` mai întâi |
| `designs`          | `DesignRequestData[]`                            | `[]`     | Referințe de design (rezolvate automat)                                          |

**Ieșire** — `{ fileId, screenIds }`. Transmiteți fiecare `screenId` la `get-screen-image` pentru a vedea rezultatele.

***

### `upload-attachment`

Încărcați un fișier pentru a-l folosi ca atașament în `create-new-design` sau `edit-design`. Returnează `{ id, path, type, mimeType }` — transmiteți acest obiect direct în tabloul `attachments`.

Două moduri:

**Modul 1 — Ecran după ID**

Transmiteți `screenId` și `fileId`. Serverul preia starea ecranului din baza de date și o redă ca imagine.

| Parametru  | Tip    | Descriere                                 |
| ---------- | ------ | ----------------------------------------- |
| `fileId`   | `uuid` | Fișier care conține ecranul (obligatoriu) |
| `screenId` | `uuid` | Ecranul de redat                          |

**Modul 2 — Fișier extern**

Transmiteți conținutul fișierului direct. Fișierele binare trebuie codificate în base64; fișierele text (inclusiv codul sursă) sunt transmise ca șiruri UTF-8 plain.

| Parametru  | Tip                                                                                                     | Descriere                                                                           |
| ---------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `fileData` | `string`                                                                                                | Conținutul fișierului — base64 pentru binar, șir UTF-8 pentru text                  |
| `fileName` | `string`                                                                                                | Numele fișierului original                                                          |
| `mimeType` | `"image/jpeg" \| "image/png" \| "image/webp" \| "application/pdf" \| "text/plain" \| "text/javascript"` | Tip MIME. Utilizați `text/javascript` pentru fișierele `.jsx`, `.tsx`, `.js`, `.ts` |

Dimensiune maximă a fișierului: **3 MB**. Pentru imagini mari, preferați `image/jpeg` în locul `image/png`.

**Ieșire**

```json theme={"system"}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "path": "attachments/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "image",
  "mimeType": "image/jpeg"
}
```

`type` este `"image"` pentru încărcări de imagine/PDF și `"document"` pentru fișiere text/cod.

***

## Unelte de chat

### `get-chat-history`

Obțineți istoricul mesajelor de chat pentru un fișier.

**Intrare**

| Parametru | Tip    | Descriere        |
| --------- | ------ | ---------------- |
| `fileId`  | `uuid` | ID-ul fișierului |

**Ieșire** — Obiect JSON cu un tablou `messages`. Fiecare mesaj are un `type` (`"request"` sau `"response"`), `author` (`"human"` sau `"ai"`), și `content_type` (`"text"`, `"summary"`, sau `"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": []
    }
  ]
}
```

***

## Unelte de design

### `get-design-guidelines`

Obțineți ghidurile de design stocate pentru un fișier.

**Intrare**

| Parametru    | Tip      | Implicit | Descriere        |
| ------------ | -------- | -------- | ---------------- |
| `resourceId` | `uuid`   | —        | ID-ul fișierului |
| `linkedTo`   | `"file"` | `"file"` | Tipul resursei   |

**Ieșire**

```json theme={"system"}
{
  "guidelines": "## Colors\n\nPrimary: #6366F1\nBackground: #FFFFFF\n\n## Typography\n\nFont: Inter",
  "linkedTo": "file"
}
```

`guidelines` este `null` dacă nu au fost setate ghiduri.

***

### `update-design-guidelines`

Setați sau înlocuiți ghidurile de design pentru un fișier. Ghidurile sunt transmise ca șir de text plain în formatul `design.md` al Google — nu transmiteți un obiect sau JSON.

Serverul efectuează validare ușoară și poate returna o secțiune `Warnings:` în răspuns listând probleme (chei necunoscute, culori non-hex) care au fost acceptate dar pot fi ignorate de AI. Afișați-le utilizatorului.

**Intrare**

| Parametru          | Tip              | Implicit | Descriere                                                                         |
| ------------------ | ---------------- | -------- | --------------------------------------------------------------------------------- |
| `resourceId`       | `uuid`           | —        | ID-ul fișierului                                                                  |
| `designGuidelines` | `string` (min 1) | —        | Conținutul text brut al ghidurilor. Trebuie să fie un șir plain — nu JSON-encoded |
| `linkedTo`         | `"file"`         | `"file"` | Tipul resursei                                                                    |

**Reguli de validare**

* Prefața trebuie deschisă și închisă corect
* Liniile din prefață trebuie să fie YAML valid în stil bloc
* Corpul Markdown nu trebuie să conțină titluri duplicate `##`

**Ieșire** — `"Design guidelines updated successfully"`, opțional urmată de o secțiune `Warnings:`.

***

### `delete-design-guidelines`

Ștergeți ghidurile de design pentru un fișier.

**Intrare**

| Parametru    | Tip      | Implicit | Descriere        |
| ------------ | -------- | -------- | ---------------- |
| `resourceId` | `uuid`   | —        | ID-ul fișierului |
| `linkedTo`   | `"file"` | `"file"` | Tipul resursei   |

**Ieșire** — `"Design guidelines deleted successfully"`

***

## Unelte Figma

### `import-figma`

Importă un cadru din Figma într-un fișier Flowstep ca elemente editabile pe canvas-ul acestuia. Re-importarea aceluiași cadru îl actualizează la loc. Organizația fișierului trebuie să aibă Figma conectată în setările Flowstep.

**Intrare**

| Parametru  | Tip      | Descriere                                                                                                                                                                                                                  |
| ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `figmaUrl` | `string` | Link la un cadru Figma specific. În Figma, fă clic dreapta pe cadru și alege **Copy link to selection**. Un link la o pagină importă toate cadrele de nivel superior de pe acea pagină (limitat la 20 de cadre peste MCP). |
| `fileId`   | `uuid`   | Fișierul Flowstep în care să importe cadrul                                                                                                                                                                                |

**Ieșire** — `{ fileId, screenId }`. `screenId` este id-ul elementului de ecran importat — transmite-l lui `get-screen-image` pentru a vedea rezultatul. Când un URL de pagină importă mai multe cadre, `screenId` este `null` și se returnează `frameCount` în loc.

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

***

## Unelte de facturare

### `get-plan-details`

Obțineți planul curent al utilizatorului, starea abonamentului și cota rămasă. Nu necesită intrare.

**Ieșire**

```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 }
  }
}
```

Limitele variază după plan. Apelați această unealtă înainte de o serie de generări pentru a verifica cota disponibilă.