> ## 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 工具的輸入結構、輸出形狀和範例。

所有工具傳回 `content` 陣列的 MCP 內容區塊。文字工具傳回 `{ 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` (min 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` (min 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` 陣列中的 ID |

**輸出** — 畫面代碼（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` 都是選用的 — 如果存在（例如當傳遞從 `get-screen` 輸出複製的 JSX 時），會使用 `screenId`（內部），但非強制。畫面名稱取自註解的 `name` 欄位（顯示為"\<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` 陣列中的 ID |

**輸出** — MCP 影像內容區塊 (`image/png`)。

***

## AI 工具

<Warning>
  `regenerate-design`、`expand-design` 和 `edit-design` 需要僅存在於原本用 `designs` 陣列產生的畫面上的設計內容。無設計內容的產生畫面將傳回錯誤。因應措施：使用 `upload-attachment` 將畫面呈現為影像，然後使用影像在 `attachments` 中呼叫 `create-new-design`，並搭配描述所需變更的訊息。
</Warning>

### `create-new-design`

從文字提示詞產生一或多個畫面設計。省略 `fileId` 以自動建立新檔案。區塊直到產生完成或逾時（180 秒）。

**輸入**

| 參數            | 類型                                | 預設   | 描述                                                              |
| ------------- | --------------------------------- | ---- | --------------------------------------------------------------- |
| `fileId`      | `uuid`                            | —    | 目標檔案 — 省略以自動建立新檔案                                               |
| `message`     | `string`                          | —    | 描述要產生的畫面的提示詞                                                    |
| `attachments` | `AttachmentRequestData[]` (max 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[]` (min 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[]` (min 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[]` (min 1)                                 | —    | 要編輯的畫面的 screenIds                   |
| `operationVariant` | `"dark_theme" \| "light_theme" \| "make_pretty"` | —    | 選用風格快捷方式                            |
| `attachments`      | `AttachmentRequestData[]` (max 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/jpeg` 勝於 `image/png`。

**輸出**

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

伺服器執行軟驗證，可能在回應中傳回列出問題（未知金鑰、非十六進位顏色）的 `Warnings:` 區段，這些問題已被接受但可能被 AI 忽略。向使用者表示這些。

**輸入**

| 參數                 | 類型               | 預設       | 描述                            |
| ------------------ | ---------------- | -------- | ----------------------------- |
| `resourceId`       | `uuid`           | —        | 檔案 ID                         |
| `designGuidelines` | `string` (min 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 }
  }
}
```

限制因方案而異。呼叫此工具以在一批產生前檢查可用配額。