> ## 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` (min 1) | 文件名 |

**输出** — JSON 文件对象，包含新文件的 `id`。

```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` 数组中的值 |

**输出** — 屏幕作为代码（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 时）会被使用，但不是强制性的。屏幕名称取自注释的 `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` 将屏幕渲染为图像，然后使用图像在 `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 |

**输出** — JSON 对象，包含 `messages` 数组。每个消息都有 `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"` | 资源类型                           |

**验证规则**

* 前置部分必须正确打开和关闭
* 前置部分行必须是有效的块样式 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 }
  }
}
```

限制因套餐而异。运行该工具以查看你的具体数字。有关每套餐详情，请参阅 [定价](https://flowstep.ai/pricing)。