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

# Dokumentacja narzędzi MCP

> Schemat wejścia, format wyjścia i przykłady dla wszystkich 20 narzędzi Flowstep MCP.

Wszystkie narzędzia zwracają tablicę `content` z blokami zawartości MCP. Narzędzia tekstowe zwracają `{ type: "text", text: "<json-string>" }`. Narzędzia obrazów zwracają `{ type: "image", data: "<base64>", mimeType: "image/png" }`. W przypadku błędu ustawiany jest `isError: true` i blok tekstowy zawiera komunikat o błędzie.

***

## Narzędzia do pracy z plikami

### `list-files`

Wyświetl pliki Flowstep dla bieżącego użytkownika.

**Input**

| Parameter         | Type              | Default | Description                |
| ----------------- | ----------------- | ------- | -------------------------- |
| `orderByCreation` | `boolean`         | `true`  | Sortuj po dacie utworzenia |
| `limit`           | `integer` (1–100) | `20`    | Liczba plików do zwrócenia |
| `offset`          | `integer` (≥0)    | `0`     | Przesunięcie stronicowania |

**Output** — Tablica JSON obiektów plików.

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

Pobierz pojedynczy plik na podstawie ID. Zawartość pliku jest celowo pominięta — użyj `get-screen` lub `get-screen-image` do inspekcji ekranów, a `get-design-guidelines` do pobrania załączonych wytycznych.

**Input**

| Parameter | Type   | Description |
| --------- | ------ | ----------- |
| `id`      | `uuid` | ID pliku    |

**Output** — Obiekt JSON pliku.

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

Utwórz nowy plik Flowstep.

**Input**

| Parameter | Type             | Description |
| --------- | ---------------- | ----------- |
| `title`   | `string` (min 1) | Nazwa pliku |

**Output** — Obiekt JSON pliku z ID nowego pliku.

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

Użyj zwróconego `id` jako `fileId` w kolejnych wywołaniach narzędzi.

***

### `update-file`

Zmień nazwę pliku.

**Input**

| Parameter | Type             | Description |
| --------- | ---------------- | ----------- |
| `id`      | `uuid`           | ID pliku    |
| `name`    | `string` (min 1) | Nowa nazwa  |

**Output** — Zaktualizowany obiekt pliku w tym samym formacie co `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`

Trwale usuń plik. Nazwa, którą przechodzisz, jest weryfikowana względem rzeczywistej nazwy pliku przed usunięciem — jeśli nie pasuje, usunięcie zostanie przerwane. Zapobiega to przypadkowemu usunięciu niewłaściwego pliku.

**Input**

| Parameter | Type     | Description                                                                   |
| --------- | -------- | ----------------------------------------------------------------------------- |
| `id`      | `uuid`   | ID pliku                                                                      |
| `name`    | `string` | Bieżąca nazwa pliku — musi dokładnie pasować lub usunięcie zostanie przerwane |

**Output** — `"File deleted successfully"`

<Warning>
  Jest to nieodwracalne. Wszystkie ekrany w pliku są usuwane.
</Warning>

***

## Narzędzia do pracy z ekranami

### `list-screens`

Wyświetl wszystkie wygenerowane ekrany dla pliku. Użyj zwróconych wartości `screenId` do odniesienia ekranów w `get-screen`, `get-screen-image`, `upload-attachment` i jako `targets` w `edit-design`, `regenerate-design` lub `expand-design`.

**Input**

| Parameter | Type   | Description |
| --------- | ------ | ----------- |
| `fileId`  | `uuid` | ID pliku    |

**Output** — Tablica JSON podsumowań ekranów.

```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` to przypisana przez użytkownika nazwa ekranu, lub `null` jeśli bez nazwy.

***

### `get-screen`

Pobierz kod JSX dla ekranu, co pozwala edytować lub używać kod poza Flowstep. Użyj `get-screen-image` do podglądu wizualnego.

**Input**

| Parameter  | Type   | Description                                                                                                |
| ---------- | ------ | ---------------------------------------------------------------------------------------------------------- |
| `fileId`   | `uuid` | ID pliku                                                                                                   |
| `screenId` | `uuid` | `screenId` zwrócony przez `list-screens` lub z tablicy `screenIds` zwróconej przez narzędzie projektowania |

**Output** — Ekran jako kod (JSX). Zwróć uwagę na komentarz w pierwszej linii, który jest wymagany podczas korzystania z narzędzia `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`

Dodaje nowy ekran do pliku Flowstep ze surowego ciągu JSX.

**Input**

| Parameter    | Type     | Description                                                                     |
| ------------ | -------- | ------------------------------------------------------------------------------- |
| `fileId`     | `uuid`   | ID pliku                                                                        |
| `jsxContent` | `string` | JSX do dodania do pliku jako ekran                                              |
| `screenType` | `string` | Wymagany, jeśli typ ekranu nie jest zdefiniowany jako komentarz na początku JSX |

**Note** - Komentarz podobny do poniższego MUSI być obecny jako pierwsza linia JSX, ponieważ jest używany do prawidłowego dodania ekranu. `screenType`, `name` i `screenId` są wszystkie opcjonalne — `screenId` jest używany (wewnętrznie), jeśli jest obecny (np. podczas przekazywania JSX skopiowanego z wyjścia `get-screen`), ale nie jest obowiązkowy. Nazwa ekranu jest pobierana z pola `name` komentarza (wyświetlane jako "Copy of \<name>"), lub "Untitled" jeśli jest nieobecne.

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

**Output** — Nowo dodany ID ekranu.

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

***

### `get-screen-image`

Wyrenderuj ekran do PNG i zwróć go jako obraz wbudowany. Wymaga klienta, który obsługuje bloki zawartości obrazu.

**Input**

| Parameter  | Type   | Description                                                                                                |
| ---------- | ------ | ---------------------------------------------------------------------------------------------------------- |
| `fileId`   | `uuid` | ID pliku                                                                                                   |
| `screenId` | `uuid` | `screenId` zwrócony przez `list-screens` lub z tablicy `screenIds` zwróconej przez narzędzie projektowania |

**Output** — Blok zawartości MCP (`image/png`).

***

## Narzędzia AI

<Warning>
  `regenerate-design`, `expand-design` i `edit-design` wymagają kontekstu projektowego, który jest obecny tylko na ekranach pierwotnie wygenerowanych z tablicą `designs`. Ekrany wygenerowane bez kontekstu projektowego zwrócą błąd. Obejście: użyj `upload-attachment` do wyrenderowania ekranu jako obrazu, a następnie wywołaj `create-new-design` z obrazem w `attachments` i wiadomością opisującą żądane zmiany.
</Warning>

### `create-new-design`

Generuj jeden lub więcej projektów ekranów z prompta tekstowego. Pomiń `fileId`, aby automatycznie utworzyć nowy plik. Blokuje się aż do ukończenia generowania lub przekroczenia limitu czasu (180 sekund).

**Input**

| Parameter     | Type                              | Default | Description                                                                                                                                                              |
| ------------- | --------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `fileId`      | `uuid`                            | —       | Plik docelowy — pomiń, aby automatycznie utworzyć nowy plik                                                                                                              |
| `message`     | `string`                          | —       | Prompt opisujący ekrany do wygenerowania                                                                                                                                 |
| `attachments` | `AttachmentRequestData[]` (max 5) | `[]`    | Wstępnie przesłane załączniki — obrazy, pliki PDF lub kody. Zawsze przesyłaj za pośrednictwem `upload-attachment` najpierw; nie umieszczaj zawartości pliku w wiadomości |
| `designs`     | `DesignRequestData[]`             | `[]`    | Referencje projektowe                                                                                                                                                    |

**Output** — `{ fileId, screenIds }`. Przechodzę każdy `screenId` do `get-screen-image`, aby zobaczyć wyniki.

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

***

### `regenerate-design`

Przywróć istniejące ekrany od nowa lub z wariacją stylu. Wymaga co najmniej jednego `screenId` w `targets`. Blokuje się aż do ukończenia generowania lub przekroczenia limitu czasu (180 sekund).

**Input**

| Parameter          | Type                                                        | Default | Description                                        |
| ------------------ | ----------------------------------------------------------- | ------- | -------------------------------------------------- |
| `fileId`           | `uuid`                                                      | —       | Plik docelowy                                      |
| `message`          | `string`                                                    | —       | Tekst promptu                                      |
| `targets`          | `uuid[]` (min 1)                                            | —       | screenIds ekranów do przywrócenia                  |
| `operationVariant` | `"different_layout" \| "different_style" \| "from_scratch"` | —       | Opcjonalna wariacją stylu                          |
| `designs`          | `DesignRequestData[]`                                       | `[]`    | Referencje projektowe (rozwiązywane automatycznie) |

**Output** — `{ fileId, screenIds }`. Przechodzę każdy `screenId` do `get-screen-image`, aby zobaczyć wyniki.

***

### `expand-design`

Dodaj następne ekrany do istniejącego projektu. Wymaga co najmniej jednego `screenId` w `targets` i obowiązkowego `operationVariant`. Blokuje się aż do ukończenia generowania lub przekroczenia limitu czasu (180 sekund).

**Input**

| Parameter          | Type                                                                                                                                                           | Default | Description                                           |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------- |
| `fileId`           | `uuid`                                                                                                                                                         | —       | Plik docelowy                                         |
| `message`          | `string`                                                                                                                                                       | —       | Tekst promptu                                         |
| `targets`          | `uuid[]` (min 1)                                                                                                                                               | —       | screenIds ekranów do rozszerzenia                     |
| `operationVariant` | `"next_screen" \| "error_state" \| "empty_state" \| "web_version" \| "mobile_version" \| "tablet_version" \| "mobile_ios_version" \| "mobile_android_version"` | —       | **Wymagany** — typ następnego ekranu do wygenerowania |
| `designs`          | `DesignRequestData[]`                                                                                                                                          | `[]`    | Referencje projektowe (rozwiązywane automatycznie)    |

**Output** — `{ fileId, screenIds }`. Przechodzę każdy `screenId` do `get-screen-image`, aby zobaczyć wyniki.

***

### `edit-design`

Modyfikuj istniejące ekrany za pośrednictwem prompta. Wymaga co najmniej jednego `screenId` w `targets`. Blokuje się aż do ukończenia generowania lub przekroczenia limitu czasu (180 sekund).

**Input**

| Parameter          | Type                                             | Default | Description                                                                                   |
| ------------------ | ------------------------------------------------ | ------- | --------------------------------------------------------------------------------------------- |
| `fileId`           | `uuid`                                           | —       | Plik docelowy                                                                                 |
| `message`          | `string`                                         | —       | Instrukcje opisujące edycje do zastosowania                                                   |
| `targets`          | `uuid[]` (min 1)                                 | —       | screenIds ekranów do edycji                                                                   |
| `operationVariant` | `"dark_theme" \| "light_theme" \| "make_pretty"` | —       | Opcjonalny skrót stylu                                                                        |
| `attachments`      | `AttachmentRequestData[]` (max 5)                | `[]`    | Wstępnie przesłane załączniki. Zawsze przesyłaj za pośrednictwem `upload-attachment` najpierw |
| `designs`          | `DesignRequestData[]`                            | `[]`    | Referencje projektowe (rozwiązywane automatycznie)                                            |

**Output** — `{ fileId, screenIds }`. Przechodzę każdy `screenId` do `get-screen-image`, aby zobaczyć wyniki.

***

### `upload-attachment`

Prześlij plik do użytku jako załącznik w `create-new-design` lub `edit-design`. Zwraca `{ id, path, type, mimeType }` — przechodzę ten obiekt bezpośrednio do tablicy `attachments`.

Dwa tryby:

**Mode 1 — Screen by ID**

Przechodzę `screenId` i `fileId`. Serwer pobiera stan ekranu z bazy danych i renderuje go jako obraz.

| Parameter  | Type   | Description                       |
| ---------- | ------ | --------------------------------- |
| `fileId`   | `uuid` | Plik zawierający ekran (wymagany) |
| `screenId` | `uuid` | Ekran do wyrenderowania           |

**Mode 2 — External file**

Przechodzę zawartość pliku bezpośrednio. Pliki binarne muszą być zakodowane base64; pliki tekstowe (włączając kod źródłowy) są przechodzane jako zwykłe ciągi UTF-8.

| Parameter  | Type                                                                                                    | Description                                                              |
| ---------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `fileData` | `string`                                                                                                | Zawartość pliku — base64 dla binarnych, ciąg UTF-8 dla tekstu            |
| `fileName` | `string`                                                                                                | Oryginalna nazwa pliku                                                   |
| `mimeType` | `"image/jpeg" \| "image/png" \| "image/webp" \| "application/pdf" \| "text/plain" \| "text/javascript"` | Typ MIME. Użyj `text/javascript` dla plików `.jsx`, `.tsx`, `.js`, `.ts` |

Maksymalny rozmiar pliku: **3 MB**. Dla dużych obrazów preferuj `image/jpeg` zamiast `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` to `"image"` dla przesłań obrazu/PDF i `"document"` dla plików tekstowych/kodowych.

***

## Narzędzia czatu

### `get-chat-history`

Pobierz historię wiadomości czatu dla pliku.

**Input**

| Parameter | Type   | Description |
| --------- | ------ | ----------- |
| `fileId`  | `uuid` | ID pliku    |

**Output** — Obiekt JSON z tablicą `messages`. Każda wiadomość ma `type` (`"request"` lub `"response"`), `author` (`"human"` lub `"ai"`) i `content_type` (`"text"`, `"summary"` lub `"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": []
    }
  ]
}
```

***

## Narzędzia projektowe

### `get-design-guidelines`

Pobierz wytyczne projektowe przechowywane dla pliku.

**Input**

| Parameter    | Type     | Default  | Description |
| ------------ | -------- | -------- | ----------- |
| `resourceId` | `uuid`   | —        | ID pliku    |
| `linkedTo`   | `"file"` | `"file"` | Typ zasobu  |

**Output**

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

`guidelines` to `null` jeśli żadne wytyczne nie zostały ustawione.

***

### `update-design-guidelines`

Ustaw lub zastąp wytyczne projektowe dla pliku. Wytyczne są przechodzane jako zwykły ciąg tekstowy w formacie `design.md` Google — nie przechodzaj obiektu ani JSON.

Serwer wykonuje łagodną walidację i może zwrócić sekcję `Warnings:` w odpowiedzi zawierającą problemy (nieznane klucze, kolory nie-hex), które były zaakceptowane, ale mogą być zignorowane przez AI. Wyświetl je użytkownikowi.

**Input**

| Parameter          | Type             | Default  | Description                                                                         |
| ------------------ | ---------------- | -------- | ----------------------------------------------------------------------------------- |
| `resourceId`       | `uuid`           | —        | ID pliku                                                                            |
| `designGuidelines` | `string` (min 1) | —        | Surowa zawartość tekstowa wytycznych. Musi być zwykłym ciągiem — nie JSON-kodowanym |
| `linkedTo`         | `"file"`         | `"file"` | Typ zasobu                                                                          |

**Validation rules**

* Frontmatter muszą być otwarte i zamknięte prawidłowo
* Linie Frontmatter muszą być prawidłowymi YAML w stylu bloku
* Treść Markdown nie powinna zawierać zduplikowanych nagłówków `##`

**Output** — `"Design guidelines updated successfully"`, opcjonalnie następnie sekcja `Warnings:`.

***

### `delete-design-guidelines`

Wyczyść wytyczne projektowe dla pliku.

**Input**

| Parameter    | Type     | Default  | Description |
| ------------ | -------- | -------- | ----------- |
| `resourceId` | `uuid`   | —        | ID pliku    |
| `linkedTo`   | `"file"` | `"file"` | Typ zasobu  |

**Output** — `"Design guidelines deleted successfully"`

***

## Narzędzia Figmy

### `import-figma`

Importuj ramkę Figmy do pliku Flowstep jako edytowalne elementy na kanwie. Ponowne importowanie tej samej ramki zaktualizuje ją w miejscu. Organizacja pliku musi mieć najpierw połączoną Figmę w ustawieniach Flowstep.

**Input**

| Parameter  | Type     | Description                                                                                                                                                                                                                                                          |
| ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `figmaUrl` | `string` | Link do określonej ramki Figmy. W Figmie kliknij prawym przyciskiem myszy ramkę i wybierz **Copy link to selection** (Skopiuj link do zaznaczenia). Link do strony importuje wszystkie ramki najwyższego poziomu na tej stronie (ograniczone do 20 ramek przez MCP). |
| `fileId`   | `uuid`   | Plik Flowstep, do którego importować ramkę                                                                                                                                                                                                                           |

**Output** — `{ fileId, screenId }`. `screenId` to id importowanego elementu ekranu — przechodzę go do `get-screen-image`, aby zobaczyć wynik. Gdy URL strony importuje wiele ramek, `screenId` to `null` i zamiast tego zwracany jest `frameCount`.

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

***

## Narzędzia rozliczeniowe

### `get-plan-details`

Pobierz plan bieżącego użytkownika, status subskrypcji i pozostały limit. Nie przyjmuje danych wejściowych.

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

Limity się różnią w zależności od planu. Wywołaj to narzędzie, aby zobaczyć twoje konkretne liczby przed partią generacji w celu sprawdzenia dostępnego limitu.