> ## 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. # Tài liệu tham khảo công cụ MCP > Lược đồ đầu vào, hình dạng đầu ra và ví dụ cho tất cả 20 công cụ Flowstep MCP. Tất cả các công cụ trả về một mảng `content` của các khối nội dung MCP. Các công cụ văn bản trả về `{ type: "text", text: "" }`. Các công cụ hình ảnh trả về `{ type: "image", data: "", mimeType: "image/png" }`. Khi thất bại, `isError: true` được đặt và khối văn bản chứa thông báo lỗi. *** ## Công cụ tệp ### `list-files` Liệt kê các tệp Flowstep cho người dùng hiện tại. **Đầu vào** | Tham số | Loại | Mặc định | Mô tả | | ----------------- | ----------------- | -------- | ---------------------- | | `orderByCreation` | `boolean` | `true` | Sắp xếp theo ngày tạo | | `limit` | `integer` (1–100) | `20` | Số lượng tệp để trả về | | `offset` | `integer` (≥0) | `0` | Độ dời phân trang | **Đầu ra** — Mảng JSON các đối tượng tệp. ```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` Lấy một tệp duy nhất theo ID. Nội dung tệp được bỏ qua một cách cố ý — sử dụng `get-screen` hoặc `get-screen-image` để kiểm tra các màn hình, và `get-design-guidelines` để lấy các nguyên tắc đính kèm. **Đầu vào** | Tham số | Loại | Mô tả | | ------- | ------ | ------ | | `id` | `uuid` | ID tệp | **Đầu ra** — Đối tượng tệp 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` Tạo một tệp Flowstep mới. **Đầu vào** | Tham số | Loại | Mô tả | | ------- | ---------------- | ------- | | `title` | `string` (min 1) | Tên tệp | **Đầu ra** — Đối tượng tệp JSON với `id` của tệp mới. ```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" } ``` Sử dụng `id` được trả về làm `fileId` trong các lệnh công cụ tiếp theo. *** ### `update-file` Đổi tên một tệp. **Đầu vào** | Tham số | Loại | Mô tả | | ------- | ---------------- | ------- | | `id` | `uuid` | ID tệp | | `name` | `string` (min 1) | Tên mới | **Đầu ra** — Đối tượng tệp được cập nhật có cùng hình dạng như `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` Xóa vĩnh viễn một tệp. `name` mà bạn chuyển được xác minh với tên thực tế của tệp trước khi xóa — nếu nó không khớp, việc xóa sẽ bị hủy. Điều này ngăn chặn việc xóa nhầm tệp. **Đầu vào** | Tham số | Loại | Mô tả | | ------- | -------- | ------------------------------------------------------------------ | | `id` | `uuid` | ID tệp | | `name` | `string` | Tên hiện tại của tệp — phải khớp chính xác hoặc việc xóa sẽ bị hủy | **Đầu ra** — `"File deleted successfully"` Điều này không thể đảo ngược. Tất cả các màn hình trong tệp sẽ bị xóa. *** ## Công cụ màn hình ### `list-screens` Liệt kê tất cả các màn hình được tạo cho một tệp. Sử dụng các giá trị `screenId` được trả về để tham chiếu các màn hình trong `get-screen`, `get-screen-image`, `upload-attachment`, và như `targets` trong `edit-design`, `regenerate-design`, hoặc `expand-design`. **Đầu vào** | Tham số | Loại | Mô tả | | -------- | ------ | ------ | | `fileId` | `uuid` | ID tệp | **Đầu ra** — Mảng JSON các bản tóm tắt màn hình. ```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` là tên màn hình được gán bởi người dùng, hoặc `null` nếu chưa được đặt tên. *** ### `get-screen` Lấy mã JSX cho một màn hình cho phép bạn chỉnh sửa hoặc sử dụng mã bên ngoài Flowstep. Sử dụng `get-screen-image` để xem trước trực quan thay thế. **Đầu vào** | Tham số | Loại | Mô tả | | ---------- | ------ | --------------------------------------------------------------------------------------------------- | | `fileId` | `uuid` | ID tệp | | `screenId` | `uuid` | `screenId` được trả về bởi `list-screens` hoặc từ mảng `screenIds` được trả về bởi công cụ thiết kế | **Đầu ra** — Màn hình dưới dạng mã (JSX). Lưu ý bình luận dòng đầu tiên cần thiết khi sử dụng công cụ `add-screen`. ```json theme={"system"}
World Clock
Search cities...
...
; ``` *** ### `add-screen` Thêm một màn hình mới vào tệp Flowstep từ chuỗi JSX thô. **Đầu vào** | Tham số | Loại | Mô tả | | ------------ | -------- | ---------------------------------------------------------------------------- | | `fileId` | `uuid` | ID tệp | | `jsxContent` | `string` | JSX để thêm vào tệp dưới dạng màn hình | | `screenType` | `string` | Bắt buộc nếu loại màn hình không được xác định dưới dạng bình luận ở đầu JSX | **Lưu ý** - Một bình luận tương tự như bên dưới PHẢI có mặt dưới dạng dòng đầu tiên của JSX vì nó được sử dụng để thêm màn hình một cách chính xác. `screenType`, `name`, và `screenId` đều là tùy chọn — `screenId` được sử dụng (bên trong) nếu có (ví dụ khi chuyển JSX được sao chép từ đầu ra `get-screen`) nhưng không bắt buộc. Tên màn hình được lấy từ trường `name` của bình luận (hiển thị dưới dạng "Copy of \"), hoặc "Untitled" nếu không có. `` **Đầu ra** — ID của màn hình mới được thêm. ```json theme={"system"} { "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbf" } ``` *** ### `get-screen-image` Hiển thị một màn hình thành PNG và trả về nó dưới dạng hình ảnh nội dòng. Yêu cầu ứng dụng khách hỗ trợ các khối nội dung hình ảnh. **Đầu vào** | Tham số | Loại | Mô tả | | ---------- | ------ | --------------------------------------------------------------------------------------------------- | | `fileId` | `uuid` | ID tệp | | `screenId` | `uuid` | `screenId` được trả về bởi `list-screens` hoặc từ mảng `screenIds` được trả về bởi công cụ thiết kế | **Đầu ra** — Khối nội dung hình ảnh MCP (`image/png`). *** ## Công cụ AI `regenerate-design`, `expand-design`, và `edit-design` yêu cầu bối cảnh thiết kế chỉ có trong các màn hình được tạo ban đầu với mảng `designs`. Các màn hình được tạo mà không có bối cảnh thiết kế sẽ trả về lỗi. Cách giải quyết: sử dụng `upload-attachment` để hiển thị màn hình dưới dạng hình ảnh, sau đó gọi `create-new-design` với hình ảnh trong `attachments` và tin nhắn mô tả những thay đổi mong muốn. ### `create-new-design` Tạo một hoặc nhiều thiết kế màn hình từ lời nhắc văn bản. Bỏ qua `fileId` để tự động tạo tệp mới. Chặn cho đến khi tạo hoàn thành hoặc hết thời gian chờ (180 giây). **Đầu vào** | Tham số | Loại | Mặc định | Mô tả | | ------------- | --------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `fileId` | `uuid` | — | Tệp đích — bỏ qua để tự động tạo tệp mới | | `message` | `string` | — | Lời nhắc mô tả các màn hình cần tạo | | `attachments` | `AttachmentRequestData[]` (max 5) | `[]` | Tệp đính kèm được tải lên trước — hình ảnh, PDF hoặc tệp mã. Luôn tải lên qua `upload-attachment` trước; không nội dòng nội dung tệp trong tin nhắn | | `designs` | `DesignRequestData[]` | `[]` | Tham chiếu thiết kế | **Đầu ra** — `{ fileId, screenIds }`. Chuyển mỗi `screenId` đến `get-screen-image` để xem kết quả. ```json theme={"system"} { "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0", "screenIds": ["3f9e6eb6-5525-4383-9375-67e0bd762dbe"] } ``` *** ### `regenerate-design` Tạo lại các màn hình hiện có từ đầu hoặc với biến thể kiểu. Yêu cầu ít nhất một `screenId` trong `targets`. Chặn cho đến khi tạo hoàn thành hoặc hết thời gian chờ (180 giây). **Đầu vào** | Tham số | Loại | Mặc định | Mô tả | | ------------------ | ----------------------------------------------------------- | -------- | --------------------------------------------- | | `fileId` | `uuid` | — | Tệp đích | | `message` | `string` | — | Văn bản lời nhắc | | `targets` | `uuid[]` (min 1) | — | screenIds của các màn hình cần tạo lại | | `operationVariant` | `"different_layout" \| "different_style" \| "from_scratch"` | — | Biến thể kiểu tùy chọn | | `designs` | `DesignRequestData[]` | `[]` | Tham chiếu thiết kế (được giải quyết tự động) | **Đầu ra** — `{ fileId, screenIds }`. Chuyển mỗi `screenId` đến `get-screen-image` để xem kết quả. *** ### `expand-design` Thêm các màn hình tiếp theo vào thiết kế hiện có. Yêu cầu ít nhất một `screenId` trong `targets` và `operationVariant` bắt buộc. Chặn cho đến khi tạo hoàn thành hoặc hết thời gian chờ (180 giây). **Đầu vào** | Tham số | Loại | Mặc định | Mô tả | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------- | | `fileId` | `uuid` | — | Tệp đích | | `message` | `string` | — | Văn bản lời nhắc | | `targets` | `uuid[]` (min 1) | — | screenIds của các màn hình cần mở rộng từ | | `operationVariant` | `"next_screen" \| "error_state" \| "empty_state" \| "web_version" \| "mobile_version" \| "tablet_version" \| "mobile_ios_version" \| "mobile_android_version"` | — | **Bắt buộc** — loại màn hình tiếp theo cần tạo | | `designs` | `DesignRequestData[]` | `[]` | Tham chiếu thiết kế (được giải quyết tự động) | **Đầu ra** — `{ fileId, screenIds }`. Chuyển mỗi `screenId` đến `get-screen-image` để xem kết quả. *** ### `edit-design` Sửa đổi các màn hình hiện có thông qua lời nhắc. Yêu cầu ít nhất một `screenId` trong `targets`. Chặn cho đến khi tạo hoàn thành hoặc hết thời gian chờ (180 giây). **Đầu vào** | Tham số | Loại | Mặc định | Mô tả | | ------------------ | ------------------------------------------------ | -------- | --------------------------------------------------------------------------- | | `fileId` | `uuid` | — | Tệp đích | | `message` | `string` | — | Hướng dẫn mô tả các chỉnh sửa cần áp dụng | | `targets` | `uuid[]` (min 1) | — | screenIds của các màn hình cần chỉnh sửa | | `operationVariant` | `"dark_theme" \| "light_theme" \| "make_pretty"` | — | Phím tắt kiểu tùy chọn | | `attachments` | `AttachmentRequestData[]` (max 5) | `[]` | Tệp đính kèm được tải lên trước. Luôn tải lên qua `upload-attachment` trước | | `designs` | `DesignRequestData[]` | `[]` | Tham chiếu thiết kế (được giải quyết tự động) | **Đầu ra** — `{ fileId, screenIds }`. Chuyển mỗi `screenId` đến `get-screen-image` để xem kết quả. *** ### `upload-attachment` Tải lên một tệp để sử dụng làm tệp đính kèm trong `create-new-design` hoặc `edit-design`. Trả về `{ id, path, type, mimeType }` — chuyển đối tượng này trực tiếp vào mảng `attachments`. Hai chế độ: **Chế độ 1 — Màn hình theo ID** Chuyển `screenId` và `fileId`. Máy chủ tải nạp trạng thái màn hình từ cơ sở dữ liệu và hiển thị nó dưới dạng hình ảnh. | Tham số | Loại | Mô tả | | ---------- | ------ | ---------------------------- | | `fileId` | `uuid` | Tệp chứa màn hình (bắt buộc) | | `screenId` | `uuid` | Màn hình để hiển thị | **Chế độ 2 — Tệp bên ngoài** Chuyển nội dung tệp trực tiếp. Các tệp nhị phân phải được mã hóa base64; các tệp văn bản (bao gồm mã nguồn) được chuyển dưới dạng chuỗi UTF-8 thuần túy. | Tham số | Loại | Mô tả | | ---------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | `fileData` | `string` | Nội dung tệp — base64 cho nhị phân, chuỗi UTF-8 cho văn bản | | `fileName` | `string` | Tên tệp gốc | | `mimeType` | `"image/jpeg" \| "image/png" \| "image/webp" \| "application/pdf" \| "text/plain" \| "text/javascript"` | Loại MIME. Sử dụng `text/javascript` cho các tệp `.jsx`, `.tsx`, `.js`, `.ts` | Kích thước tệp tối đa: **3 MB**. Đối với hình ảnh lớn, ưu tiên `image/jpeg` hơn `image/png`. **Đầu ra** ```json theme={"system"} { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "path": "attachments/a1b2c3d4-e5f6-7890-abcd-ef1234567890", "type": "image", "mimeType": "image/jpeg" } ``` `type` là `"image"` cho tải lên hình ảnh/PDF và `"document"` cho tệp văn bản/mã. *** ## Công cụ trò chuyện ### `get-chat-history` Lấy lịch sử tin nhắn trò chuyện cho một tệp. **Đầu vào** | Tham số | Loại | Mô tả | | -------- | ------ | ------ | | `fileId` | `uuid` | ID tệp | **Đầu ra** — Đối tượng JSON với mảng `messages`. Mỗi tin nhắn có `type` (`"request"` hoặc `"response"`), `author` (`"human"` hoặc `"ai"`), và `content_type` (`"text"`, `"summary"`, hoặc `"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": [] } ] } ``` *** ## Công cụ thiết kế ### `get-design-guidelines` Lấy các hướng dẫn thiết kế được lưu trữ cho một tệp. **Đầu vào** | Tham số | Loại | Mặc định | Mô tả | | ------------ | -------- | -------- | --------------- | | `resourceId` | `uuid` | — | ID tệp | | `linkedTo` | `"file"` | `"file"` | Loại tài nguyên | **Đầu ra** ```json theme={"system"} { "guidelines": "## Colors\n\nPrimary: #6366F1\nBackground: #FFFFFF\n\n## Typography\n\nFont: Inter", "linkedTo": "file" } ``` `guidelines` là `null` nếu không có hướng dẫn nào được đặt. *** ### `update-design-guidelines` Đặt hoặc thay thế các hướng dẫn thiết kế cho một tệp. Các hướng dẫn được chuyển dưới dạng chuỗi văn bản thuần túy trong định dạng `design.md` của Google — không chuyển đối tượng hoặc JSON. Máy chủ thực hiện xác thực mềm và có thể trả về phần `Warnings:` trong phản hồi liệt kê các vấn đề (khóa chưa biết, màu sắc không phải hex) đã được chấp nhận nhưng có thể bị AI bỏ qua. Hiển thị chúng cho người dùng. **Đầu vào** | Tham số | Loại | Mặc định | Mô tả | | ------------------ | ---------------- | -------- | ---------------------------------------------------------------------------------------- | | `resourceId` | `uuid` | — | ID tệp | | `designGuidelines` | `string` (min 1) | — | Nội dung văn bản thô của các hướng dẫn. Phải là chuỗi thuần túy — không được mã hóa JSON | | `linkedTo` | `"file"` | `"file"` | Loại tài nguyên | **Quy tắc xác thực** * Frontmatter phải được mở và đóng đúng cách * Các dòng Frontmatter phải là YAML kiểu khối hợp lệ * Nội dung Markdown không được chứa các tiêu đề phần `##` trùng lặp **Đầu ra** — `"Design guidelines updated successfully"`, tùy chọn theo sau phần `Warnings:`. *** ### `delete-design-guidelines` Xóa các hướng dẫn thiết kế cho một tệp. **Đầu vào** | Tham số | Loại | Mặc định | Mô tả | | ------------ | -------- | -------- | --------------- | | `resourceId` | `uuid` | — | ID tệp | | `linkedTo` | `"file"` | `"file"` | Loại tài nguyên | **Đầu ra** — `"Design guidelines deleted successfully"` *** ## Công cụ Figma ### `import-figma` Nhập khung Figma vào tệp Flowstep dưới dạng các phần tử có thể chỉnh sửa trên canvas của nó. Nhập lại cùng một khung sẽ cập nhật nó tại chỗ. Tổ chức của tệp phải có Figma được kết nối trong cài đặt Flowstep. **Đầu vào** | Tham số | Loại | Mô tả | | ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `figmaUrl` | `string` | Liên kết đến một khung Figma cụ thể. Trong Figma, nhấp chuột phải vào khung và chọn **Copy link to selection** (Sao chép liên kết vào lựa chọn). Liên kết đến trang nhập tất cả các khung cấp cao nhất trên trang đó (giới hạn 20 khung trên MCP). | | `fileId` | `uuid` | Tệp Flowstep để nhập khung vào | **Đầu ra** — `{ fileId, screenId }`. `screenId` là id của phần tử màn hình được nhập — chuyển nó đến `get-screen-image` để xem kết quả. Khi URL trang nhập nhiều khung, `screenId` là `null` và `frameCount` được trả về thay thế. ```json theme={"system"} { "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0", "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbe" } ``` *** ## Công cụ thanh toán ### `get-plan-details` Lấy gói hiện tại, trạng thái đăng ký và hạn ngạch còn lại của người dùng. Không có đầu vào. **Đầu ra** ```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 } } } ``` Giới hạn khác nhau theo gói. Gọi công cụ này trước một loạt các bước tạo để kiểm tra hạn ngạch khả dụng.