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

# MCP 도구 참조

> 모든 20개의 Flowstep MCP 도구에 대한 입력 스키마, 출력 형태, 예제입니다.

모든 도구는 MCP 콘텐츠 블록의 `content` 배열을 반환합니다. 텍스트 도구는 `{ type: "text", text: "<json-string>" }`을 반환합니다. 이미지 도구는 `{ type: "image", data: "<base64>", mimeType: "image/png" }`을 반환합니다. 오류 발생 시 `isError: true`가 설정되고 텍스트 블록에 오류 메시지가 포함됩니다.

***

## 파일 도구

### `list-files`

현재 사용자의 Flowstep 파일을 나열합니다.

**입력**

| 매개변수              | 유형                | 기본값    | 설명          |
| ----------------- | ----------------- | ------ | ----------- |
| `orderByCreation` | `boolean`         | `true` | 생성 날짜순으로 정렬 |
| `limit`           | `integer` (1–100) | `20`   | 반환할 파일 개수   |
| `offset`          | `integer` (≥0)    | `0`    | 페이지 매김 오프셋  |

**출력** — 파일 객체의 JSON 배열입니다.

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

파일 ID로 단일 파일을 가져옵니다. 파일 콘텐츠는 의도적으로 생략됩니다 — 화면을 검사하려면 `get-screen` 또는 `get-screen-image`를 사용하고, 첨부된 가이드라인을 검색하려면 `get-design-guidelines`을 사용합니다.

**입력**

| 매개변수 | 유형     | 설명    |
| ---- | ------ | ----- |
| `id` | `uuid` | 파일 ID |

**출력** — 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`

새로운 Flowstep 파일을 만듭니다.

**입력**

| 매개변수    | 유형              | 설명    |
| ------- | --------------- | ----- |
| `title` | `string` (최소 1) | 파일 이름 |

**출력** — 새 파일의 `id`를 포함하는 JSON 파일 객체입니다.

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

반환된 `id`를 후속 도구 호출에서 `fileId`로 사용합니다.

***

### `update-file`

파일의 이름을 바꿉니다.

**입력**

| 매개변수   | 유형              | 설명    |
| ------ | --------------- | ----- |
| `id`   | `uuid`          | 파일 ID |
| `name` | `string` (최소 1) | 새 이름  |

**출력** — `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`

파일을 영구적으로 삭제합니다. 전달하는 `name`은 삭제 전에 파일의 실제 이름과 비교하여 검증됩니다 — 일치하지 않으면 삭제가 중단됩니다. 이렇게 하면 실수로 잘못된 파일을 삭제하는 것을 방지합니다.

**입력**

| 매개변수   | 유형       | 설명                               |
| ------ | -------- | -------------------------------- |
| `id`   | `uuid`   | 파일 ID                            |
| `name` | `string` | 파일의 현재 이름 — 정확히 일치해야 하거나 삭제가 중단됨 |

**출력** — `"File deleted successfully"`

<Warning>
  이 작업은 되돌릴 수 없습니다. 파일의 모든 화면이 삭제됩니다.
</Warning>

***

## 화면 도구

### `list-screens`

파일의 모든 생성된 화면을 나열합니다. 반환된 `screenId` 값을 `get-screen`, `get-screen-image`, `upload-attachment`에서 화면을 참조할 때와 `edit-design`, `regenerate-design`, `expand-design`에서 `targets`로 사용합니다.

**입력**

| 매개변수     | 유형     | 설명    |
| -------- | ------ | ----- |
| `fileId` | `uuid` | 파일 ID |

**출력** — 화면 요약의 JSON 배열입니다.

```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`은 사용자가 지정한 화면 이름이며, 이름이 없으면 `null`입니다.

***

### `get-screen`

화면의 JSX 코드를 가져와 Flowstep 외부에서 코드를 편집하거나 사용할 수 있도록 합니다. 시각적 미리보기는 `get-screen-image`를 사용합니다.

**입력**

| 매개변수       | 유형     | 설명                                                            |
| ---------- | ------ | ------------------------------------------------------------- |
| `fileId`   | `uuid` | 파일 ID                                                         |
| `screenId` | `uuid` | `list-screens`에서 반환된 `screenId` 또는 설계 도구에서 반환된 `screenIds` 배열 |

**출력** — 화면을 코드(JSX)로 나타낸 것입니다. `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`

원시 JSX 문자열에서 Flowstep 파일에 새 화면을 추가합니다.

**입력**

| 매개변수         | 유형       | 설명                                   |
| ------------ | -------- | ------------------------------------ |
| `fileId`     | `uuid`   | 파일 ID                                |
| `jsxContent` | `string` | 파일에 화면으로 추가할 JSX                     |
| `screenType` | `string` | JSX 시작 부분의 주석에서 화면 유형이 정의되지 않은 경우 필수 |

**참고** — JSX의 첫 줄로 다음과 유사한 주석이 있어야 합니다. `screenType`, `name`, `screenId`는 모두 선택 사항입니다 — `screenId`는 있으면 사용됩니다(`get-screen` 출력에서 복사한 JSX를 전달할 때 예: `get-screen` 출력). `screenId`는 필수가 아닙니다. 화면 이름은 주석의 `name` 필드에서 가져오며("Copy of \<name>" 형태로 표시됨), 없으면 "Untitled"입니다.

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

**출력** — 새로 추가된 화면 ID입니다.

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

***

### `get-screen-image`

화면을 PNG로 렌더링하고 인라인 이미지로 반환합니다. 이미지 콘텐츠 블록을 지원하는 클라이언트가 필요합니다.

**입력**

| 매개변수       | 유형     | 설명                                                            |
| ---------- | ------ | ------------------------------------------------------------- |
| `fileId`   | `uuid` | 파일 ID                                                         |
| `screenId` | `uuid` | `list-screens`에서 반환된 `screenId` 또는 설계 도구에서 반환된 `screenIds` 배열 |

**출력** — MCP 이미지 콘텐츠 블록(`image/png`).

***

## AI 도구

<Warning>
  `regenerate-design`, `expand-design`, `edit-design`은 원래 `designs` 배열로 생성된 화면에만 있는 설계 컨텍스트가 필요합니다. 설계 컨텍스트 없이 생성된 화면은 오류를 반환합니다. 해결 방법: `upload-attachment`를 사용하여 화면을 이미지로 렌더링한 후 `create-new-design`을 호출할 때 `attachments`의 이미지와 원하는 변경 사항을 설명하는 메시지를 사용합니다.
</Warning>

### `create-new-design`

텍스트 프롬프트에서 하나 이상의 화면 설계를 생성합니다. `fileId`를 생략하면 새 파일이 자동으로 생성됩니다. 생성이 완료되거나 시간 초과될 때까지 블로킹됩니다(180초).

**입력**

| 매개변수          | 유형                               | 기본값  | 설명                                                                                                        |
| ------------- | -------------------------------- | ---- | --------------------------------------------------------------------------------------------------------- |
| `fileId`      | `uuid`                           | —    | 대상 파일 — 생략하면 새 파일이 자동으로 생성됩니다                                                                             |
| `message`     | `string`                         | —    | 생성할 화면을 설명하는 프롬프트                                                                                         |
| `attachments` | `AttachmentRequestData[]` (최대 5) | `[]` | 사전 업로드된 첨부 파일 — 이미지, PDF 또는 코드 파일. 항상 `upload-attachment`를 통해 먼저 업로드합니다. 메시지에 파일 콘텐츠를 인라인 방식으로 포함시키지 않습니다 |
| `designs`     | `DesignRequestData[]`            | `[]` | 설계 참조                                                                                                     |

**출력** — `{ fileId, screenIds }`. 각 `screenId`를 `get-screen-image`에 전달하여 결과를 봅니다.

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

***

### `regenerate-design`

기존 화면을 처음부터 다시 만들거나 스타일 변형으로 다시 만듭니다. `targets`에 최소한 하나의 `screenId`가 필요합니다. 생성이 완료되거나 시간 초과될 때까지 블로킹됩니다(180초).

**입력**

| 매개변수               | 유형                                                          | 기본값  | 설명                 |
| ------------------ | ----------------------------------------------------------- | ---- | ------------------ |
| `fileId`           | `uuid`                                                      | —    | 대상 파일              |
| `message`          | `string`                                                    | —    | 프롬프트 텍스트           |
| `targets`          | `uuid[]` (최소 1)                                             | —    | 재생성할 화면의 screenIds |
| `operationVariant` | `"different_layout" \| "different_style" \| "from_scratch"` | —    | 선택 사항 스타일 변형       |
| `designs`          | `DesignRequestData[]`                                       | `[]` | 설계 참조(자동으로 해결됨)    |

**출력** — `{ fileId, screenIds }`. 각 `screenId`를 `get-screen-image`에 전달하여 결과를 봅니다.

***

### `expand-design`

기존 설계에 후속 화면을 추가합니다. `targets`에 최소한 하나의 `screenId`와 필수 `operationVariant`가 필요합니다. 생성이 완료되거나 시간 초과될 때까지 블로킹됩니다(180초).

**입력**

| 매개변수               | 유형                                                                                                                                                             | 기본값  | 설명                     |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | ---------------------- |
| `fileId`           | `uuid`                                                                                                                                                         | —    | 대상 파일                  |
| `message`          | `string`                                                                                                                                                       | —    | 프롬프트 텍스트               |
| `targets`          | `uuid[]` (최소 1)                                                                                                                                                | —    | 확장할 화면의 screenIds      |
| `operationVariant` | `"next_screen" \| "error_state" \| "empty_state" \| "web_version" \| "mobile_version" \| "tablet_version" \| "mobile_ios_version" \| "mobile_android_version"` | —    | **필수** — 생성할 후속 화면의 유형 |
| `designs`          | `DesignRequestData[]`                                                                                                                                          | `[]` | 설계 참조(자동으로 해결됨)        |

**출력** — `{ fileId, screenIds }`. 각 `screenId`를 `get-screen-image`에 전달하여 결과를 봅니다.

***

### `edit-design`

프롬프트를 통해 기존 화면을 수정합니다. `targets`에 최소한 하나의 `screenId`가 필요합니다. 생성이 완료되거나 시간 초과될 때까지 블로킹됩니다(180초).

**입력**

| 매개변수               | 유형                                               | 기본값  | 설명                                                  |
| ------------------ | ------------------------------------------------ | ---- | --------------------------------------------------- |
| `fileId`           | `uuid`                                           | —    | 대상 파일                                               |
| `message`          | `string`                                         | —    | 적용할 편집을 설명하는 지침                                     |
| `targets`          | `uuid[]` (최소 1)                                  | —    | 편집할 화면의 screenIds                                   |
| `operationVariant` | `"dark_theme" \| "light_theme" \| "make_pretty"` | —    | 선택 사항 스타일 단축키                                       |
| `attachments`      | `AttachmentRequestData[]` (최대 5)                 | `[]` | 사전 업로드된 첨부 파일. 항상 `upload-attachment`를 통해 먼저 업로드합니다 |
| `designs`          | `DesignRequestData[]`                            | `[]` | 설계 참조(자동으로 해결됨)                                     |

**출력** — `{ fileId, screenIds }`. 각 `screenId`를 `get-screen-image`에 전달하여 결과를 봅니다.

***

### `upload-attachment`

`create-new-design` 또는 `edit-design`에서 첨부 파일로 사용할 파일을 업로드합니다. `{ id, path, type, mimeType }`을 반환합니다 — 이 객체를 `attachments` 배열에 직접 전달합니다.

두 가지 모드:

**모드 1 — ID별 화면**

`screenId`와 `fileId`를 전달합니다. 서버가 데이터베이스에서 화면 상태를 가져오고 이미지로 렌더링합니다.

| 매개변수       | 유형     | 설명              |
| ---------- | ------ | --------------- |
| `fileId`   | `uuid` | 화면을 포함하는 파일(필수) |
| `screenId` | `uuid` | 렌더링할 화면         |

**모드 2 — 외부 파일**

파일 콘텐츠를 직접 전달합니다. 바이너리 파일은 base64로 인코딩해야 하고, 텍스트 파일(소스 코드 포함)은 평문 UTF-8 문자열로 전달합니다.

| 매개변수       | 유형                                                                                                      | 설명                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `fileData` | `string`                                                                                                | 파일 콘텐츠 — 바이너리는 base64, 텍스트는 UTF-8 문자열                             |
| `fileName` | `string`                                                                                                | 원본 파일 이름                                                          |
| `mimeType` | `"image/jpeg" \| "image/png" \| "image/webp" \| "application/pdf" \| "text/plain" \| "text/javascript"` | MIME 유형. `.jsx`, `.tsx`, `.js`, `.ts` 파일의 경우 `text/javascript` 사용 |

최대 파일 크기: **3 MB**. 큰 이미지의 경우 `image/png`보다 `image/jpeg`를 사용합니다.

**출력**

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

`type`은 이미지/PDF 업로드의 경우 `"image"`이고 텍스트/코드 파일의 경우 `"document"`입니다.

***

## 채팅 도구

### `get-chat-history`

파일의 채팅 메시지 기록을 가져옵니다.

**입력**

| 매개변수     | 유형     | 설명    |
| -------- | ------ | ----- |
| `fileId` | `uuid` | 파일 ID |

**출력** — `messages` 배열을 포함하는 JSON 객체입니다. 각 메시지는 `type` (`"request"` 또는 `"response"`), `author` (`"human"` 또는 `"ai"`), `content_type` (`"text"`, `"summary"`, `"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": []
    }
  ]
}
```

***

## 설계 도구

### `get-design-guidelines`

파일에 저장된 설계 가이드라인을 가져옵니다.

**입력**

| 매개변수         | 유형       | 기본값      | 설명     |
| ------------ | -------- | -------- | ------ |
| `resourceId` | `uuid`   | —        | 파일 ID  |
| `linkedTo`   | `"file"` | `"file"` | 리소스 유형 |

**출력**

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

`guidelines`는 설정된 가이드라인이 없으면 `null`입니다.

***

### `update-design-guidelines`

파일의 설계 가이드라인을 설정하거나 바꿉니다. 가이드라인은 Google의 `design.md` 형식의 평문 텍스트 문자열로 전달됩니다 — 객체나 JSON으로 전달하지 않습니다.

서버는 소프트 검증을 수행하고 응답에 받아들여졌지만 AI에서 무시될 수 있는 문제(알 수 없는 키, 16진수가 아닌 색상)를 나열하는 `Warnings:` 섹션을 반환할 수 있습니다. 사용자에게 이를 표시합니다.

**입력**

| 매개변수               | 유형              | 기본값      | 설명                                                 |
| ------------------ | --------------- | -------- | -------------------------------------------------- |
| `resourceId`       | `uuid`          | —        | 파일 ID                                              |
| `designGuidelines` | `string` (최소 1) | —        | 가이드라인의 원시 텍스트 콘텐츠. 평문 문자열이어야 합니다 — JSON으로 인코딩되지 않음 |
| `linkedTo`         | `"file"`        | `"file"` | 리소스 유형                                             |

**검증 규칙**

* Frontmatter는 올바르게 열고 닫아야 합니다
* Frontmatter 줄은 유효한 블록 스타일 YAML이어야 합니다
* Markdown 본문에는 중복 `##` 섹션 제목이 없어야 합니다

**출력** — `"Design guidelines updated successfully"`, 선택 사항으로 `Warnings:` 섹션이 뒤따릅니다.

***

### `delete-design-guidelines`

파일의 설계 가이드라인을 지웁니다.

**입력**

| 매개변수         | 유형       | 기본값      | 설명     |
| ------------ | -------- | -------- | ------ |
| `resourceId` | `uuid`   | —        | 파일 ID  |
| `linkedTo`   | `"file"` | `"file"` | 리소스 유형 |

**출력** — `"Design guidelines deleted successfully"`

***

## Figma 도구

### `import-figma`

Figma 프레임을 Flowstep 파일로 캔버스의 편집 가능한 요소로 가져옵니다. 동일한 프레임을 다시 가져오면 제자리에서 업데이트됩니다. 파일의 조직에서 Flowstep 설정의 Figma를 연결해야 합니다.

**입력**

| 매개변수       | 유형       | 설명                                                                                                                                              |
| ---------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `figmaUrl` | `string` | 특정 Figma 프레임으로의 링크. Figma에서 프레임을 마우스 오른쪽 클릭하고 **Copy link to selection**을 선택합니다. 페이지 링크는 한 번에 해당 페이지의 모든 최상위 프레임을 가져옵니다(MCP를 통해 20개 프레임으로 제한됨). |
| `fileId`   | `uuid`   | 프레임을 가져올 Flowstep 파일                                                                                                                            |

**출력** — `{ fileId, screenId }`. `screenId`는 가져온 화면 요소의 ID입니다 — `get-screen-image`에 전달하여 결과를 봅니다. 페이지 URL이 여러 프레임을 가져올 때 `screenId`는 `null`이고 `frameCount`가 대신 반환됩니다.

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

***

## 청구 도구

### `get-plan-details`

현재 사용자의 요금제, 구독 상태, 남은 할당량을 가져옵니다. 입력이 필요 없습니다.

**출력**

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

제한은 요금제에 따라 다릅니다. 특정 숫자를 보려면 도구를 실행합니다.