MCP 도구 참조

성공하면 get-screen-image를 제외한 모든 도구가 결과를 두 번 반환합니다. 하나는 structuredContent(도구의 게시된 출력 스키마로 검증됨)이고, 다른 하나는 구조화된 콘텐츠를 읽지 않는 클라이언트를 위해 같은 객체를 텍스트 블록 { type: "text", text: "<json-string>" }으로 직렬화한 것입니다. get-screen-image는 MCP 이미지 블록 { type: "image", data: "<base64>", mimeType: "image/png" }만 반환합니다. 실패하면 isError: true가 설정되고, 텍스트 블록에 짧은 오류 메시지가 담깁니다. 직접 조치할 수 있는 오류(삭제 시 이름 불일치, 잘못된 Figma 링크, 잘못된 디자인 가이드라인, 첨부 파일 문제, 생성 시간 초과)는 해결 방법을 설명합니다. 그 밖의 실패는 Failed to list files처럼 일반적인 메시지를 반환합니다.

가격: 세 가지 AI 디자인 도구(ai-design-screens, ai-generate-screen-variant, ai-edit-screen-variant)는 Flowstep 앱과 같은 메시지 사용량 한도를 사용합니다. 다른 모든 도구는 무료입니다. 사용 한도를 참고하세요.

각 도구는 클라이언트가 동작을 파악할 수 있도록 MCP 주석도 게시합니다. delete-file, delete-screen, delete-design-guidelines, replace-screen-jsx, ai-design-screens, ai-edit-screen-variant는 기존 콘텐츠를 제거하거나 덮어쓰므로 파괴적(destructive)으로 표시됩니다.

파일 도구

`list-files`

Flowstep 파일의 메타데이터를 나열합니다. 관련 파일이 이미 있는지 확인하려면 먼저 이 도구를 호출하세요. 화면 콘텐츠는 반환되지 않습니다. 콘텐츠가 필요하면 get-screen-image 또는 get-screen-jsx를 사용하세요. 입력

매개변수	유형	기본값	설명
`orderByCreation`	`boolean`	`true`	`created_at` 기준 최신순(`true`) 또는 `updated_at` 기준(`false`)으로 정렬합니다. 최근에 편집한 파일을 찾으려면 `false`를 사용하세요
`limit`	`integer` (1–100)	`20`	반환할 최대 파일 수. 페이지가 가득 차 있다면 더 많은 파일이 있을 수 있습니다
`offset`	`integer` (≥0)	`0`	건너뛸 파일 수. 다음 페이지는 `offset + limit`입니다

출력 — { files }.

{
  "files": [
    {
      "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",
      "organisation_id": "0b7f3c9e-2d4a-4f1b-9a5e-6c8d7e1f2a3b",
      "shared_with_me": false,
      "owner": true,
      "url": "https://app.flowstep.ai/file?activeFileId=5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0"
    }
  ]
}

owner — 파일을 만들었다면 true입니다.
shared_with_me — 조직을 거치지 않고 직접 공유된 파일이면 true입니다.
url — Flowstep 편집기에서 파일을 엽니다.

`get-file`

단일 파일의 메타데이터를 가져옵니다. 파일 콘텐츠는 의도적으로 제외됩니다. 화면을 확인하려면 get-screen-image 또는 get-screen-jsx를 사용하고, 첨부된 가이드라인을 가져오려면 get-design-guidelines를 사용하세요. 파일에 대기 중인 초대가 있다면 get-file을 호출하면 수락됩니다. 입력

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

출력 — { file, user_access_level }.

{
  "file": {
    "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",
    "project_id": "81cb84d6-c69f-492c-a895-7421b60d1a6d",
    "access_level": "private",
    "visibility": "private",
    "owner": true,
    "url": "https://app.flowstep.ai/file?activeFileId=5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0"
  },
  "user_access_level": "write"
}

access_level — private, read, write 중 하나입니다.
visibility — 일반 액세스 설정으로, private(제한됨), member(멤버 전용), public(공개) 중 하나입니다.
user_access_level — 파일에 대한 사용자의 액세스 권한으로, read 또는 write입니다.

`create-file`

화면이 없는 빈 Flowstep 파일을 만듭니다. 파일을 만들면서 한 단계에서 화면도 생성하려면 fileId 없이 ai-design-screens를 호출하세요. 코드 우선 워크플로에는 create-file을 사용한 뒤 add-screen-jsx를 호출하세요. 입력

매개변수	유형	설명
`name`	`string` (최소 1자)	새 파일의 표시 이름

출력 — { file, user_access_level }이며, get-file과 같은 형태입니다. owner는 항상 true이고 user_access_level은 항상 write입니다. 이후 도구 호출에서 반환된 file.id를 fileId로 사용하세요.

`update-file`

파일 이름을 바꿉니다. 입력

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

출력 — { file, user_access_level }이며, get-file과 같은 형태입니다.

`delete-file`

파일을 영구적으로 삭제합니다. 전달한 name은 삭제 전에 파일의 현재 표시 이름과 대조됩니다. 일치하지 않으면 삭제가 중단되어, 잘못된 파일을 실수로 지우는 일을 막습니다. 에이전트는 먼저 사용자에게 확인하도록 지시받습니다. 입력

매개변수	유형	설명
`id`	`uuid`	파일 ID
`name`	`string`	파일의 현재 표시 이름. 일치해야 하며, 그렇지 않으면 삭제가 중단됩니다

출력 — { "deleted": true }

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

화면 도구

`list-screens`

파일의 화면을 캔버스 순서대로 나열합니다. list-files 다음에 호출해 파일에 이미 있는 내용을 확인하세요. 반환된 screenId 값은 다른 화면 도구와 AI 디자인 도구에 사용하세요. 입력

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

출력 — { screens }.

{
  "screens": [
    {
      "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbe",
      "name": "Mobile login screen",
      "prompt": "Generate a simple mobile login screen with email and password fields and a sign in button",
      "fidelity": "ui"
    }
  ]
}

prompt — 화면의 마지막 생성 프롬프트입니다. 생성된 적이 없다면(예: add-screen-jsx로 추가한 화면) 빈 문자열입니다.
fidelity — lofi, hifi, ui 중 하나입니다.

`get-screen-image`

화면을 PNG로 렌더링해 인라인 이미지로 반환합니다. 이미지 콘텐츠 블록을 지원하는 클라이언트가 필요합니다. AI 디자인 도구, add-screen-jsx, replace-screen-jsx, import-figma가 반환한 각 screenId에 대해 한 번씩 호출하세요. 입력

매개변수	유형	설명
`fileId`	`uuid`	파일 ID
`screenId`	`uuid`	`list-screens`의 `screenId` 또는 디자인 도구가 반환한 `screenIds` 배열의 값

출력 — MCP 이미지 콘텐츠 블록(image/png). data는 데이터 URI가 아니라 PNG 바이트의 표준 base64입니다. 이 도구에는 structuredContent가 없습니다.

`get-screen-jsx`

화면을 JSX와 메타데이터로 가져옵니다. 코드베이스에서 구현하거나, 편집한 뒤 replace-screen-jsx로 다시 쓸 수 있습니다. 시각적 미리보기가 필요하면 대신 get-screen-image를 사용하세요. 입력

매개변수	유형	기본값	설명
`fileId`	`uuid`	—	파일 ID
`screenId`	`uuid`	—	`list-screens`의 `screenId` 또는 디자인 도구가 반환한 `screenIds` 배열의 값
`includeIds`	`boolean`	`false`	`jsx`의 요소에 `data-id` 속성을 포함합니다. `ai-design-screens`에 `elementIds`로 전달할 요소 ID가 필요할 때(편집 범위 지정 또는 시각 참조용) 사용하세요

출력 — { fileId, screenId, name, prompt, fidelity, screenType, colorTheme, jsx, fragments }.

{
  "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
  "screenId": "c13d3707-0efe-49f5-b6cb-0ca5ac5223d0",
  "name": "World clock",
  "prompt": "A world clock screen with a city search and alert button",
  "fidelity": "ui",
  "screenType": "iphone-x-vertical",
  "colorTheme": "blue",
  "jsx": "<div className=\"bg-white text-zinc-950 w-full h-fit\">\n  <div className=\"flex p-6 flex-col gap-6\">\n    …\n  </div>\n</div>",
  "fragments": []
}

jsx — 마크업만 포함합니다. data-id 속성은 includeIds가 true일 때만 포함됩니다.
prompt — 마지막 생성 프롬프트입니다. 생성된 적이 없다면 빈 문자열입니다.
fragments — 화면에 저장된 공용 크롬(내비게이션 바, 헤더, 로고 등)으로, { purpose, markup } 객체입니다. 없으면 비어 있습니다. 유지하거나 업데이트하려면 replace-screen-jsx에 다시 전달하세요.

fidelity, screenType, colorTheme 값은 화면 필드 값을 참고하세요.

`add-screen-jsx`

직접 작성한 JSX로 파일에 새 화면을 추가합니다. 코드 우선 방식이며 무료입니다. Flowstep의 AI가 화면을 디자인하게 하려면 ai-design-screens를 사용하세요. add-screen-jsx는 항상 새 화면을 만듭니다. 기존 화면을 덮어쓰려면 replace-screen-jsx를 사용하세요. 업로드한 이미지를 표시하려면 JSX의 이미지를 참고하세요. 새 화면이 기존 화면을 기반으로 한다면, get-screen-jsx(includeIds 없이)에서 name, fidelity, screenType, colorTheme, jsx를 가져온 다음 달라야 할 부분만 바꾸세요. 입력

매개변수	유형	기본값	설명
`fileId`	`uuid`	—	파일 ID
`name`	`string` (1–100자)	—	선택 사항인 표시 이름. 생략하면 화면 이름이 `Screen N`으로 자동 지정됩니다
`fidelity`	`string`	`"ui"`	화면 충실도
`screenType`	`string`	—	필수 — 화면이 디자인된 기기 또는 뷰포트
`colorTheme`	`string`	`"default"`	색상 테마
`jsx`	`string`	—	JSX 마크업만 포함합니다. `data-id` 속성은 무시되며, 새 화면에는 새 요소 ID가 부여됩니다

출력 — { fileId, screenId }. 결과를 보려면 screenId로 get-screen-image를 호출하세요.

{
  "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
  "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbf"
}

`replace-screen-jsx`

직접 작성한 JSX로 기존 화면을 덮어씁니다. 화면은 screenId와 캔버스 위치를 유지하고, 중첩된 요소는 새 ID를 받습니다. 코드 우선 방식이며 무료입니다. AI로 변경하려면 ai-design-screens 또는 ai-edit-screen-variant를 사용하고, 새 화면을 만들려면 add-screen-jsx를 사용하세요. get-screen-jsx(includeIds 없이)에서 시작한 다음, 달라야 할 부분만 바꾸세요. 업로드한 이미지를 표시하려면 JSX의 이미지를 참고하세요. 입력

매개변수	유형	설명
`fileId`	`uuid`	파일 ID
`screenId`	`uuid`	덮어쓸 화면
`jsx`	`string`	JSX 마크업만 포함합니다. `data-id` 속성은 무시됩니다
`name`	`string` (1–100자)	선택 사항. 생략하면 현재 이름을 유지합니다
`fidelity`	`string`	선택 사항. 생략하면 현재 충실도를 유지합니다
`screenType`	`string`	선택 사항. 생략하면 현재 화면 유형을 유지합니다
`colorTheme`	`string`	선택 사항. 생략하면 현재 색상 테마를 유지합니다
`fragments`	`{ purpose, markup }[]`	선택 사항. `get-screen-jsx`의 공용 크롬입니다. 생략하면 현재 fragments를 유지하고, `[]`를 전달하면 모두 지웁니다

출력 — { fileId, screenId }. 결과를 보려면 screenId로 get-screen-image를 호출하세요.

이 작업은 화면의 콘텐츠를 제자리에서 교체합니다.

`rename-screen`

화면의 캔버스 라벨을 바꿉니다. 이는 list-screens와 편집기에 표시되는 이름입니다. 라벨만 바뀌며 레이아웃, 크기, 콘텐츠는 바뀌지 않습니다. 그런 변경에는 ai-design-screens를 사용하세요. 입력

매개변수	유형	설명
`fileId`	`uuid`	파일 ID
`screenId`	`uuid`	`list-screens`가 반환한 `screenId`
`name`	`string` (1–100자)	새 화면 이름. 앞뒤 공백은 제거됩니다

출력 — { screenId, name }.

{ "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbe", "name": "Checkout — empty cart" }

`delete-screen`

파일에서 화면을 영구적으로 삭제합니다. 전달한 name은 화면의 현재 표시 이름과 대조되며, 일치하지 않으면 삭제가 중단됩니다. 에이전트는 먼저 사용자에게 확인하도록 지시받습니다. 입력

매개변수	유형	설명
`fileId`	`uuid`	파일 ID
`screenId`	`uuid`	삭제할 화면
`name`	`string`	화면의 현재 표시 이름. 일치해야 하며, 그렇지 않으면 삭제가 중단됩니다

출력 — { "deleted": true }

JSX의 이미지

add-screen-jsx와 replace-screen-jsx는 img의 src나 className의 bg-[url(...)] 배경으로 이미지를 받습니다. alt 텍스트를 작성하고, 각 이미지의 용도에 맞게 크기를 지정하세요. 직접 만든 이미지를 배치하려면 다음을 따르세요.

모드 A(mimeType + fileName)로 upload-attachment를 사용해 이미지를 업로드하고, 반환된 uploadCommand를 실행하세요.
응답의 type이 "image"이면, 반환된 assetUrl을 그대로 img src 또는 bg-[url(assetUrl)]에 넣으세요.

다른 이미지 URL은 get-screen-jsx가 반환한 그대로 두세요. src에 path, signedUrl, uploadCommand를 넣으면 안 됩니다.

<img src="ASSET_URL" alt="Team photo" className="w-full h-48 object-cover rounded-lg" />

화면 필드 값

get-screen-jsx가 반환하고, add-screen-jsx와 replace-screen-jsx가 허용하는 값은 다음과 같습니다.

필드	값
`fidelity`	`lofi`, `hifi`, `ui`
`screenType`	`web`, `desktop`, `desktop-large`, `desktop-medium`, `desktop-small`, `tablet`, `ipad-tablet-horizontal`, `ipad-tablet-vertical`, `android-tablet-horizontal`, `android-tablet-vertical`, `mobile_ios`, `mobile_android`, `iphone-vertical`, `iphone-horizontal`, `iphone-x-vertical`, `iphone-x-horizontal`, `android-vertical`, `android-horizontal`, `android-small-vertical`, `android-small-horizontal`
`colorTheme`	`default`, `defaultDark`, `blue`, `blueDark`, `ice`, `iceDark`, `grayscale`, `grayscaleDark`, `green`, `greenDark`, `orange`, `orangeDark`, `red`, `redDark`, `rose`, `roseDark`, `violet`, `violetDark`, `yellow`, `yellowDark`

디자인 가이드라인 도구

디자인 가이드라인은 파일에 저장된 DESIGN.md 텍스트입니다. 설정되면 해당 파일의 모든 AI 생성에 주입됩니다. 디자인 가이드라인을 참고하세요.

`get-design-guidelines`

파일에 첨부된 디자인 가이드라인을 가져옵니다. 입력

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

출력 — { guidelines }.

{
  "guidelines": "## Colors\n\nPrimary: #6366F1\nBackground: #FFFFFF\n\n## Typography\n\nFont: Inter"
}

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

`update-design-guidelines`

파일의 디자인 가이드라인을 설정하거나 교체합니다. 가이드라인은 객체나 JSON이 아니라, Google의 DESIGN.md 형식을 따르는 일반 문자열로 전달하세요. 파일에서 읽는 경우에는 그 파일의 텍스트를 전달하세요. 입력

매개변수	유형	설명
`fileId`	`uuid`	파일 ID
`designGuidelines`	`string` (최소 1자)	가이드라인의 원문 텍스트. 일반 문자열이어야 하며 JSON으로 인코딩되어 있으면 안 됩니다

검증 규칙

프런트매터는 올바르게 열리고 닫혀야 합니다
프런트매터 줄은 올바른 블록 스타일 YAML이어야 합니다
마크다운 본문에 중복된 ## 섹션 제목이 있으면 안 됩니다

검증에 실패하면 Invalid design guidelines:로 시작하는 오류가 반환됩니다. 출력 — { updated, warnings? }.

{ "updated": true, "warnings": ["…"] }

warnings에는 허용되었지만 AI가 무시할 수 있는 소프트 검증 문제(알 수 없는 키, 16진수가 아닌 색상)가 나열됩니다. 없으면 생략됩니다. 이 내용을 사용자에게 알리세요.

`delete-design-guidelines`

파일의 디자인 가이드라인을 지웁니다. 존재하지 않는 가이드라인을 삭제해도 아무 작업도 일어나지 않습니다. 입력

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

출력 — { "deleted": true }

채팅 도구

`get-chat-history`

파일과 연결된 디자인 대화를 가져옵니다. 이는 MCP 클라이언트의 대화가 아니라 파일의 Flowstep 채팅입니다. 파일에서 이전 작업을 이어가려면 이 도구를 사용하세요. 입력

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

출력 — { messages }. 파일에 디자인 대화가 없으면 messages는 비어 있습니다. 각 메시지에는 type("request" 또는 "response"), author("human" 또는 "ai"), content_type이 있습니다. 응답 메시지는 "text", "summary", "followup"을 사용합니다.

{
  "messages": [
    {
      "id": "453f593d-2380-425b-ba29-127db08d6a8e",
      "type": "request",
      "status": "success",
      "content": "Generate a simple mobile login screen with email and password fields",
      "author": "human",
      "content_type": "text",
      "sequence": 1,
      "targets": [],
      "attachments": []
    },
    {
      "id": "d860186b-82d5-4bd1-8e8e-8ba5377a14bf",
      "type": "response",
      "status": "success",
      "content": "Generated a mobile login screen with email and password input fields, a sign in button, and a 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" }]
    }
  ]
}

첨부 파일 도구

`upload-attachment`

ai-design-screens의 첨부 파일로 사용할 참고 파일이나, add-screen-jsx 또는 replace-screen-jsx로 직접 만든 JSX에 넣을 이미지를 업로드합니다. ai-generate-screen-variant와 ai-edit-screen-variant는 첨부 파일을 받지 않습니다. 파일 바이트는 모델을 거치지 않으며, 서버는 사용자를 대신해 URL을 가져오지 않습니다. 웹페이지를 참조하려면 대신 ai-design-screens의 message에 URL을 넣으세요. 두 가지 모드가 있습니다. 하나만 사용하고, 둘을 함께 사용하지 마세요. 모드 A — 파일과 이미지(mimeType + fileName) 이미지, PDF, 크기가 큰 텍스트 파일에는 다음 세 단계 흐름이 필요합니다.

mimeType과 fileName만 넣어 upload-attachment를 호출하세요(예: image/png와 dog.png). 응답은 저장된 파일이 아니라 준비된 업로드입니다.

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "path": "attachments/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "assetUrl": "https://…",
  "type": "image",
  "mimeType": "image/png",
  "signedUrl": "https://…",
  "uploadCommand": "curl -sS -f -X PUT '…' -H 'Content-Type: image/png' -H 'x-metadata: …' --data-binary @LOCAL_FILE_PATH",
  "nextStep": "…"
}

uploadCommand의 LOCAL_FILE_PATH를 파일의 절대 경로로 바꾸고, 그 명령을 셸에서 그대로 실행하세요. 명령이 0으로 종료되어야 합니다. signedUrl의 토큰은 이 단일 업로드만 허용합니다. 이 단계를 건너뛰면 저장소가 비어 있게 되고, 디자인 도구의 사전 점검이 실패합니다.
ai-design-screens의 attachments 배열에는 { id, path, type }만 전달하세요. signedUrl, uploadCommand, nextStep은 전달하면 안 됩니다. 대신 직접 만든 JSX에 이미지를 넣으려면 assetUrl을 add-screen-jsx 또는 replace-screen-jsx에 전달하는 JSX의 img src 또는 bg-[url(...)]에 넣으세요. JSX의 이미지를 참고하세요.

원격 파일을 첨부하려면 먼저 직접 로컬 경로로 내려받은 다음(예: curl 사용), 같은 세 단계를 따르세요. upload-attachment에는 절대 URL을 전달하지 마세요.

매개변수	유형	설명
`mimeType`	enum	파일 MIME 유형. `image/jpeg`, `image/png`, `image/webp`, `application/pdf`, `text/markdown`, `text/plain`, `text/javascript` 중 하나입니다. `.jsx`, `.tsx`, `.js`, `.ts` 파일에는 `text/javascript`를 사용하세요
`fileName`	`string` (최소 1자)	확장자를 포함한 원래 파일 이름(예: `cat.png` 또는 `design.md`)

모드 B — 짧은 텍스트(text + mimeType) 이미 컨텍스트에 있는 텍스트를 업로드합니다. 셸 명령은 필요하지 않습니다. 응답은 바로 사용할 수 있습니다.

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "path": "attachments/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "assetUrl": "https://…",
  "type": "document",
  "mimeType": "text/plain"
}

매개변수	유형	설명
`text`	`string` (최대 64,000자)	원문 텍스트 콘텐츠. 텍스트 파일 전용이며 이미지나 PDF에는 사용하지 마세요. 64,000자를 넘나요? 대신 모드 A를 사용하세요
`mimeType`	enum	`text/markdown`, `text/plain`, `text/javascript` 중 하나

결과로 얻은 { id, path, type }을 ai-design-screens의 attachments 배열에 전달하세요. 두 모드 모두 최대 파일 크기는 3 MB이며, PDF는 100페이지로 제한됩니다. 출력 — { id, path, assetUrl, type, mimeType, signedUrl?, uploadCommand?, nextStep? }.

type — 이미지 파일은 "image", PDF와 텍스트 파일은 "document"입니다.
assetUrl — 업로드된 파일의 URL이며, 두 모드 모두에서 반환됩니다. type이 "image"이고 모드 A의 uploadCommand를 실행한 후에만 add-screen-jsx 또는 replace-screen-jsx의 JSX에 사용하세요.
signedUrl, uploadCommand, nextStep — 모드 A에서만 설정됩니다. 디자인 도구에는 전달하지 마세요.

Figma 도구

`import-figma`

Figma 프레임을 Flowstep 파일의 캔버스에 편집 가능한 요소로 가져옵니다. 가져올 때마다 새 화면이 추가되므로, 같은 프레임을 두 번 가져오면 화면이 두 개 생깁니다. 교체하려던 것이라면 delete-screen으로 이전 화면을 삭제하세요. 파일이 속한 조직에서 Flowstep 설정으로 Figma가 연결되어 있어야 합니다. 입력

매개변수	유형	설명
`fileId`	`uuid`	프레임을 가져올 Flowstep 파일. `figmaUrl`의 Figma 파일 키가 아닙니다
`figmaUrl`	`string`	`node-id`가 포함된 특정 Figma 프레임 링크. Figma에서 프레임을 마우스 오른쪽 버튼으로 클릭하고 Copy/Paste as → Copy link to selection을 선택하세요. 페이지 링크를 사용하면 해당 페이지의 최상위 프레임이 모두 가져와집니다(MCP에서는 20개 프레임으로 제한됩니다)

출력 — { fileId, screenId, frameCount? }. screenId는 가져온 화면입니다. 결과를 보려면 이 값을 get-screen-image에 전달하세요. 페이지 URL이 여러 프레임을 가져오면 screenId는 null이 되고 대신 frameCount가 반환됩니다. 이 경우 list-screens를 호출한 다음, 새 화면마다 get-screen-image를 호출하세요.

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

요금제 및 청구 도구

`get-plan-details`

조직의 Flowstep 요금제, 구독 상태, 사용량, 남은 할당량을 가져옵니다. 입력은 필요하지 않습니다. 조직은 로그인한 사용자에게서 확인됩니다. AI 디자인 도구를 호출하기 전에 사용량 한도를 확인하는 데 사용하세요. 출력 — { plan, subscription, limits, usage, remaining }.

필드	설명
`plan`	`{ name, code, type }`. `type`은 `"free"` 또는 `"paid"`입니다
`subscription`	`{ isPaid, isTrial, startDate, endDate, trialDaysRemaining }`
`limits`	기능별 한도로, 기능 이름(예: `messages`)을 키로 사용합니다. 각 항목에는 선택적 `daily` 및 `monthly` 객체(`max`와 `warn` 값 포함)와 `unlimited` 플래그가 있습니다
`usage`	기능별 지금까지의 사용량으로, `{ daily, monthly }` 형식입니다
`remaining`	기능별 남은 할당량으로, `{ daily, monthly }` 형식입니다. 무제한 기능에서는 생략됩니다

한도는 요금제마다 다릅니다. 요금과 사용 한도를 참고하세요.

AI 디자인 도구

이 세 도구는 설명이나 프리셋으로 디자인합니다. JSX를 받거나 재사용하지 않습니다. 각 호출은 Flowstep 앱과 같은 메시지 사용량 한도를 사용하며, 생성이 완료되거나 시간이 초과(180초)될 때까지 기다립니다.

도구	용도
`ai-design-screens`	자유 형식 설명으로 새 화면을 생성하거나, 기존 화면을 제자리에서 변경하거나, 둘 다 수행합니다
`ai-generate-screen-variant`	기존 화면 하나에서 다음 단계, 오류 또는 빈 상태, 플랫폼 버전 화면을 추가합니다
`ai-edit-screen-variant`	편집 또는 재디자인 프리셋을 기존 화면 하나 전체에 적용합니다

세 도구 모두 { status, fileId, screenIds, designGuidelinesUpdated }를 반환합니다. 결과를 보려면 각 screenId에 대해 get-screen-image를 한 번씩 호출하세요.

designGuidelinesUpdated — 이번 턴에 파일의 DESIGN.md 가이드라인이 자동으로 업데이트되었을 때 변경 사항을 짧게 요약합니다. 그렇지 않으면 null입니다.

`ai-design-screens`

텍스트 설명으로 새 화면을 하나 이상 생성하거나, 기존 화면을 제자리에서 변경하거나, 한 번의 호출에서 둘 다 수행합니다. 새 흐름, 테마, 문구, 레이아웃, 여러 화면에 걸친 조정된 변경이 여기에 포함됩니다. Flowstep 편집기의 채팅과 같은 디자인 에이전트이며, message와 elementIds를 바탕으로 무엇을 만들고 무엇을 바꿀지 결정합니다. 새 파일을 시작하려면 fileId를 생략하고, 기존 파일에서 작업하려면 fileId를 전달하세요. 요청이 이미 가진 파일에 적용될 수 있다면, 에이전트는 먼저 list-files와 list-screens를 확인해야 합니다. 화면 하나의 다음 단계, 오류 또는 빈 상태, 플랫폼 버전이 필요하면 ai-generate-screen-variant를 사용하세요. 화면 하나에 프리셋 편집이나 재디자인을 적용하려면 ai-edit-screen-variant를 사용하세요. 이미 JSX가 있다면 대신 add-screen-jsx 또는 replace-screen-jsx를 사용하세요. 입력

매개변수	유형	기본값	설명
`fileId`	`uuid`	—	대상 파일. 새 파일을 만들려면 생략하세요. `elementIds`를 설정하면 필수입니다
`message`	`string`	—	생성할 화면과 또는 적용할 변경 사항에 대한 설명. `elementIds`를 전달할 때는 그 요소를 편집할지 참조용으로만 쓸지 밝히세요. Flowstep이 참조하길 원하는 웹페이지 URL도 여기에 포함하세요
`elementIds`	`uuid[]`	`[]`	선택 사항. `list-screens`의 `screenId`와 `get-screen-jsx`(`includeIds` 사용)의 요소 `data-id`를 편집기의 선택 영역처럼 전달합니다. 제자리에서 편집하거나 새 화면의 시각 참조로 사용할 수 있습니다. `screenId`는 화면 전체를 대상으로 합니다
`attachments`	`{ id, path, type }[]` (최대 5개)	`[]`	`upload-attachment`로 업로드한 파일입니다. 이미지, PDF, 코드 및 텍스트 파일을 사용할 수 있습니다. 메시지에 파일 콘텐츠를 직접 넣지 마세요

예시 — 한 번의 호출로 화면 하나를 편집하고 다른 화면을 추가합니다.

{
  "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
  "message": "Switch this sign-in screen to dark mode, then add a matching forgot-password screen.",
  "elementIds": ["3f9e6eb6-5525-4383-9375-67e0bd762dbe"]
}

출력 — { status, fileId, screenIds, designGuidelinesUpdated, reply? }.

{
  "status": "generated",
  "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
  "screenIds": [
    "3f9e6eb6-5525-4383-9375-67e0bd762dbe",
    "c13d3707-0efe-49f5-b6cb-0ca5ac5223d0"
  ],
  "designGuidelinesUpdated": null
}

status — 화면이 만들어지거나 변경되면 "generated"입니다. Flowstep이 만들지 않고 답변만 하면 "chat"이며, 이때 reply에 답변이 담기고 screenIds는 비어 있습니다. 요청이 모호하다면 에이전트가 사용자에게 명확히 해 달라고 요청한 다음 도구를 다시 호출해야 합니다.
screenIds — 호출 중에 만들었거나 변경한 모든 화면으로, 제자리에서 편집한 화면도 포함됩니다. 일부 화면이 만들어진 뒤 호출이 시간 초과되면, 오류 대신 그 화면들을 반환합니다.

편집하도록 요청한 화면은 제자리에서 덮어쓰입니다.

`ai-generate-screen-variant`

기존 화면 하나에서 파생된 새 화면을 추가합니다. 흐름의 다음 단계, 오류 또는 빈 상태, 다른 플랫폼용 버전이 해당합니다. 원본 화면은 바뀌지 않습니다. 기존 화면의 변형이 아닌 화면(예: 설정 화면)을 추가하려면 fileId와 함께 ai-design-screens를 사용하세요. 입력

매개변수	유형	설명
`fileId`	`uuid`	대상 파일
`screenId`	`uuid`	파생의 기준이 되는 기존 화면
`operationVariant`	enum	필수 — 새 화면이 기존 화면과 어떤 관계인지 지정합니다

`operationVariant`	추가되는 화면
`next_screen`	사용자 흐름의 다음 화면
`error_state`	화면의 오류 상태
`empty_state`	화면의 빈 상태
`web_version`	웹 버전
`mobile_version`	모바일 버전
`tablet_version`	태블릿 버전
`mobile_ios_version`	iOS 버전
`mobile_android_version`	Android 버전

출력 — { status, fileId, screenIds, designGuidelinesUpdated }. status는 항상 "generated"입니다.

`ai-edit-screen-variant`

프리셋을 사용해 기존 화면 하나를 제자리에서 변경합니다. 테마를 바꾸거나 다듬고, 다른 레이아웃이나 시각 스타일을 시도하거나, 처음부터 다시 디자인할 수 있습니다. 새 화면, 자유 형식 지시, 개별 요소의 정밀한 편집에는 ai-design-screens를 사용하세요. 입력

매개변수	유형	설명
`fileId`	`uuid`	대상 파일
`screenId`	`uuid`	변경할 기존 화면
`operationVariant`	enum	필수 — 적용할 편집 또는 재디자인 프리셋

`operationVariant`	유형	효과
`dark_theme`	편집	화면을 다크 테마로 전환합니다
`light_theme`	편집	화면을 라이트 테마로 전환합니다
`make_pretty`	편집	화면의 시각 디자인을 다듬습니다
`different_layout`	재디자인	다른 레이아웃을 시도합니다
`different_style`	재디자인	다른 시각 스타일을 시도합니다
`from_scratch`	재디자인	화면을 처음부터 다시 디자인합니다

출력 — { status, fileId, screenIds, designGuidelinesUpdated }. status는 항상 "generated"입니다.

이 작업은 화면의 콘텐츠를 제자리에서 덮어씁니다.

이름이 바뀐 도구

도구 이름은 2026년 9월과 10월에 변경되었습니다. 이전 이름을 사용하는 프롬프트, 스크립트, 에이전트 지침이 있다면 업데이트하세요.

이전 이름	새 이름
`get-screen`	`get-screen-jsx`
`add-screen`	`add-screen-jsx`
`replace-screen`	`replace-screen-jsx`
`ai-generate-screens`	`ai-design-screens`
`ai-edit-screens`	`ai-design-screens`
`create-new-design`	`ai-design-screens`
`edit-design` (자유 형식 지시)	`ai-design-screens`
`edit-design` (`operationVariant` 프리셋 사용)	`ai-edit-screen-variant`
`regenerate-design`	`ai-edit-screen-variant`
`expand-design`	`ai-generate-screen-variant`

입력도 바뀌었습니다. AI 디자인 도구는 targets 대신 elementIds를 받고(변형 도구는 단일 screenId를 받음), add-screen-jsx는 메타데이터 주석이 있는 jsxContent 대신 jsx와 명시적인 메타데이터 필드를 받습니다. create-file은 title 대신 name을 받고, 디자인 가이드라인 도구는 resourceId와 linkedTo 대신 fileId를 받습니다.

​파일 도구

​list-files

​get-file

​create-file

​update-file

​delete-file

​화면 도구

​list-screens

​get-screen-image

​get-screen-jsx

​add-screen-jsx

​replace-screen-jsx

​rename-screen

​delete-screen

​JSX의 이미지

​화면 필드 값

​디자인 가이드라인 도구

​get-design-guidelines

​update-design-guidelines

​delete-design-guidelines

​채팅 도구

​get-chat-history

​첨부 파일 도구

​upload-attachment

​Figma 도구

​import-figma

​요금제 및 청구 도구

​get-plan-details

​AI 디자인 도구

​ai-design-screens

​ai-generate-screen-variant

​ai-edit-screen-variant

​이름이 바뀐 도구

파일 도구

`list-files`

`get-file`

`create-file`

`update-file`

`delete-file`

화면 도구

`list-screens`

`get-screen-image`

`get-screen-jsx`

`add-screen-jsx`

`replace-screen-jsx`

`rename-screen`

`delete-screen`

JSX의 이미지

화면 필드 값

디자인 가이드라인 도구

`get-design-guidelines`

`update-design-guidelines`

`delete-design-guidelines`

채팅 도구

`get-chat-history`

첨부 파일 도구

`upload-attachment`

Figma 도구

`import-figma`

요금제 및 청구 도구

`get-plan-details`

AI 디자인 도구

`ai-design-screens`

`ai-generate-screen-variant`

`ai-edit-screen-variant`

이름이 바뀐 도구