MCP 工具參考 - Flowstep

所有工具傳回 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 陣列。

[
  {
    "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 檔案物件。

{
  "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 檔案物件。

{
  "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 相同形狀的更新檔案物件。

{
  "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"

這是不可逆的。檔案中的所有畫面都會被刪除。

畫面工具

`list-screens`

列出檔案的所有產生畫面。使用返回的 screenId 值在 get-screen、get-screen-image、upload-attachment 中參考畫面，以及在 edit-design、regenerate-design 或 expand-design 中作為 targets。輸入

參數	類型	描述
`fileId`	`uuid`	檔案 ID

輸出 — 畫面摘要的 JSON 陣列。

[
  {
    "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 工具時需要。

<!-- 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”。  輸出 — 新增畫面的 ID。

{ "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbf" }

`get-screen-image`

將畫面呈現為 PNG 並作為內聯影像傳回。需要支援影像內容區塊的客戶端。輸入

參數	類型	描述
`fileId`	`uuid`	檔案 ID
`screenId`	`uuid`	`list-screens` 返回的 `screenId` 或設計工具返回的 `screenIds` 陣列中的 ID

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

AI 工具

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

`create-new-design`

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

參數	類型	預設	描述
`fileId`	`uuid`	—	目標檔案 — 省略以自動建立新檔案
`message`	`string`	—	描述要產生的畫面的提示詞
`attachments`	`AttachmentRequestData[]` (max 5)	`[]`	預上傳的附件 — 影像、PDF 或代碼檔案。一律先透過 `upload-attachment` 上傳；不要在訊息中內聯檔案內容
`designs`	`DesignRequestData[]`	`[]`	設計參考

輸出 — { fileId, screenIds }。將每個 screenId 傳遞到 get-screen-image 以查看結果。

{
  "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。輸出

{
  "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"）。

{
  "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"`	資源類型

輸出

{
  "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"

計費工具

`get-plan-details`

取得現行使用者的方案、訂閱狀態和剩餘配額。不需要輸入。輸出

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

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

​檔案工具

​list-files

​get-file

​create-file

​update-file

​delete-file

​畫面工具

​list-screens

​get-screen

​add-screen

​get-screen-image

​AI 工具

​create-new-design

​regenerate-design

​expand-design

​edit-design

​upload-attachment

​聊天工具

​get-chat-history

​設計工具

​get-design-guidelines

​update-design-guidelines

​delete-design-guidelines

​計費工具

​get-plan-details

檔案工具

`list-files`

`get-file`

`create-file`

`update-file`

`delete-file`

畫面工具

`list-screens`

`get-screen`

`add-screen`

`get-screen-image`

AI 工具

`create-new-design`

`regenerate-design`

`expand-design`

`edit-design`

`upload-attachment`

聊天工具

`get-chat-history`

設計工具

`get-design-guidelines`

`update-design-guidelines`

`delete-design-guidelines`

計費工具

`get-plan-details`