> ## 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. # Referência de Ferramentas MCP > Esquema de entrada, forma de saída e exemplos para todas as 20 ferramentas MCP do Flowstep. Todas as ferramentas retornam um array `content` com blocos de conteúdo MCP. Ferramentas de texto retornam `{ type: "text", text: "" }`. Ferramentas de imagem retornam `{ type: "image", data: "", mimeType: "image/png" }`. Em caso de falha, `isError: true` é definido e o bloco de texto contém a mensagem de erro. *** ## Ferramentas de arquivo ### `list-files` Listar arquivos Flowstep do usuário atual. **Entrada** | Parâmetro | Tipo | Padrão | Descrição | | ----------------- | ----------------- | ------ | ----------------------------- | | `orderByCreation` | `boolean` | `true` | Ordenar por data de criação | | `limit` | `integer` (1–100) | `20` | Número de arquivos a retornar | | `offset` | `integer` (≥0) | `0` | Deslocamento de paginação | **Saída** — Array JSON de objetos de arquivo. ```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` Obter um único arquivo pelo ID. O conteúdo do arquivo é intencionalmente omitido — use `get-screen` ou `get-screen-image` para inspecionar telas e `get-design-guidelines` para recuperar diretrizes de design anexadas. **Entrada** | Parâmetro | Tipo | Descrição | | --------- | ------ | ------------- | | `id` | `uuid` | ID do arquivo | **Saída** — Objeto JSON do arquivo. ```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` Criar um novo arquivo Flowstep. **Entrada** | Parâmetro | Tipo | Descrição | | --------- | ---------------- | --------------- | | `title` | `string` (min 1) | Nome do arquivo | **Saída** — Objeto JSON do arquivo com o `id` do novo arquivo. ```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" } ``` Use o `id` retornado como `fileId` em chamadas de ferramentas subsequentes. *** ### `update-file` Renomear um arquivo. **Entrada** | Parâmetro | Tipo | Descrição | | --------- | ---------------- | ------------- | | `id` | `uuid` | ID do arquivo | | `name` | `string` (min 1) | Novo nome | **Saída** — Objeto de arquivo atualizado no mesmo formato que `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` Excluir permanentemente um arquivo. O `name` que você passa é verificado em relação ao nome real do arquivo antes da exclusão — se não corresponder, a exclusão é abortada. Isso previne exclusões acidentais. **Entrada** | Parâmetro | Tipo | Descrição | | --------- | -------- | -------------------------------------------------------------------------------- | | `id` | `uuid` | ID do arquivo | | `name` | `string` | Nome atual do arquivo — deve corresponder exatamente ou a exclusão será abortada | **Saída** — `"File deleted successfully"` Isso é irreversível. Todas as telas no arquivo são excluídas. *** ## Ferramentas de tela ### `list-screens` Listar todas as telas geradas para um arquivo. Use os valores `screenId` retornados para referenciar telas em `get-screen`, `get-screen-image`, `upload-attachment` e como `targets` em `edit-design`, `regenerate-design` ou `expand-design`. **Entrada** | Parâmetro | Tipo | Descrição | | --------- | ------ | ------------- | | `fileId` | `uuid` | ID do arquivo | **Saída** — Array JSON de resumos de telas. ```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` é o nome da tela atribuído pelo usuário ou `null` se não nomeada. *** ### `get-screen` Obter o código JSX para uma tela permitindo que você edite ou use o código fora do Flowstep. Use `get-screen-image` para uma visualização visual em vez disso. **Entrada** | Parâmetro | Tipo | Descrição | | ---------- | ------ | -------------------------------------------------------------------------------------------------------- | | `fileId` | `uuid` | ID do arquivo | | `screenId` | `uuid` | O `screenId` retornado por `list-screens` ou do array `screenIds` retornado por uma ferramenta de design | **Saída** — A tela como código (JSX). Note o comentário da primeira linha que é necessário ao usar a ferramenta `add-screen`. ```json theme={"system"}
World Clock
Search cities...
...
; ``` *** ### `add-screen` Adicionar uma nova tela a um arquivo Flowstep a partir de uma string JSX bruta. **Entrada** | Parâmetro | Tipo | Descrição | | ------------ | -------- | ---------------------------------------------------------------------------------- | | `fileId` | `uuid` | ID do arquivo | | `jsxContent` | `string` | JSX a adicionar ao arquivo como uma tela | | `screenType` | `string` | Necessário se o tipo de tela não estiver definido como comentário no início do JSX | **Nota** - Um comentário similar ao mostrado abaixo DEVE estar presente como a primeira linha do JSX pois é usado para adicionar a tela corretamente. `screenType`, `name` e `screenId` são todos opcionais — `screenId` é usado (internamente) se presente (por exemplo, ao passar JSX copiado da saída de `get-screen`) mas não é obrigatório. O nome da tela é tirado do campo `name` do comentário (exibido como "Copy of \"), ou "Untitled" se ausente. `` **Saída** — O ID da tela recém-adicionada. ```json theme={"system"} { "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbf" } ``` *** ### `get-screen-image` Renderizar uma tela para PNG e retorná-la como uma imagem inline. Requer um cliente que suporte blocos de conteúdo de imagem. **Entrada** | Parâmetro | Tipo | Descrição | | ---------- | ------ | -------------------------------------------------------------------------------------------------------- | | `fileId` | `uuid` | ID do arquivo | | `screenId` | `uuid` | O `screenId` retornado por `list-screens` ou do array `screenIds` retornado por uma ferramenta de design | **Saída** — Bloco de conteúdo de imagem MCP (`image/png`). *** ## Ferramentas de IA `regenerate-design`, `expand-design` e `edit-design` requerem contexto de design que está presente apenas em telas geradas originalmente com um array `designs`. Telas geradas sem contexto de design retornarão um erro. Alternativa: use `upload-attachment` para renderizar a tela como uma imagem, então chame `create-new-design` com a imagem em `attachments` e uma mensagem descrevendo as alterações desejadas. ### `create-new-design` Gerar um ou mais designs de tela a partir de um prompt de texto. Omita `fileId` para criar um novo arquivo automaticamente. Bloqueia até que a geração seja concluída ou expire (180 segundos). **Entrada** | Parâmetro | Tipo | Padrão | Descrição | | ------------- | --------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `fileId` | `uuid` | — | Arquivo de destino — omita para criar um novo arquivo automaticamente | | `message` | `string` | — | Prompt descrevendo as telas a gerar | | `attachments` | `AttachmentRequestData[]` (max 5) | `[]` | Anexos pré-enviados — imagens, PDFs ou arquivos de código. Sempre envie via `upload-attachment` primeiro; não inclua conteúdo de arquivo na mensagem | | `designs` | `DesignRequestData[]` | `[]` | Referências de design | **Saída** — `{ fileId, screenIds }`. Passe cada `screenId` para `get-screen-image` para visualizar os resultados. ```json theme={"system"} { "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0", "screenIds": ["3f9e6eb6-5525-4383-9375-67e0bd762dbe"] } ``` *** ### `regenerate-design` Refazer telas existentes do zero ou com uma variação de estilo. Requer pelo menos um `screenId` em `targets`. Bloqueia até que a geração seja concluída ou expire (180 segundos). **Entrada** | Parâmetro | Tipo | Padrão | Descrição | | ------------------ | ----------------------------------------------------------- | ------ | -------------------------------------------------- | | `fileId` | `uuid` | — | Arquivo de destino | | `message` | `string` | — | Texto do prompt | | `targets` | `uuid[]` (min 1) | — | screenIds das telas a regenerar | | `operationVariant` | `"different_layout" \| "different_style" \| "from_scratch"` | — | Variação de estilo opcional | | `designs` | `DesignRequestData[]` | `[]` | Referências de design (resolvidas automaticamente) | **Saída** — `{ fileId, screenIds }`. Passe cada `screenId` para `get-screen-image` para visualizar os resultados. *** ### `expand-design` Adicionar telas de acompanhamento a um design existente. Requer pelo menos um `screenId` em `targets` e um `operationVariant` obrigatório. Bloqueia até que a geração seja concluída ou expire (180 segundos). **Entrada** | Parâmetro | Tipo | Padrão | Descrição | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | -------------------------------------------------------- | | `fileId` | `uuid` | — | Arquivo de destino | | `message` | `string` | — | Texto do prompt | | `targets` | `uuid[]` (min 1) | — | screenIds das telas a expandir | | `operationVariant` | `"next_screen" \| "error_state" \| "empty_state" \| "web_version" \| "mobile_version" \| "tablet_version" \| "mobile_ios_version" \| "mobile_android_version"` | — | **Obrigatório** — tipo de tela de acompanhamento a gerar | | `designs` | `DesignRequestData[]` | `[]` | Referências de design (resolvidas automaticamente) | **Saída** — `{ fileId, screenIds }`. Passe cada `screenId` para `get-screen-image` para visualizar os resultados. *** ### `edit-design` Modificar telas existentes via um prompt. Requer pelo menos um `screenId` em `targets`. Bloqueia até que a geração seja concluída ou expire (180 segundos). **Entrada** | Parâmetro | Tipo | Padrão | Descrição | | ------------------ | ------------------------------------------------ | ------ | ------------------------------------------------------------------ | | `fileId` | `uuid` | — | Arquivo de destino | | `message` | `string` | — | Instruções descrevendo as edições a aplicar | | `targets` | `uuid[]` (min 1) | — | screenIds das telas a editar | | `operationVariant` | `"dark_theme" \| "light_theme" \| "make_pretty"` | — | Atalho de estilo opcional | | `attachments` | `AttachmentRequestData[]` (max 5) | `[]` | Anexos pré-enviados. Sempre envie via `upload-attachment` primeiro | | `designs` | `DesignRequestData[]` | `[]` | Referências de design (resolvidas automaticamente) | **Saída** — `{ fileId, screenIds }`. Passe cada `screenId` para `get-screen-image` para visualizar os resultados. *** ### `upload-attachment` Enviar um arquivo para usar como anexo em `create-new-design` ou `edit-design`. Retorna `{ id, path, type, mimeType }` — passe este objeto diretamente no array `attachments`. Dois modos: **Modo 1 — Tela por ID** Passe `screenId` e `fileId`. O servidor obtém o estado da tela do banco de dados e a renderiza como uma imagem. | Parâmetro | Tipo | Descrição | | ---------- | ------ | ------------------------------------- | | `fileId` | `uuid` | Arquivo contendo a tela (obrigatório) | | `screenId` | `uuid` | Tela a renderizar | **Modo 2 — Arquivo externo** Passe o conteúdo do arquivo diretamente. Arquivos binários devem ser codificados em base64; arquivos de texto (incluindo código-fonte) são passados como strings UTF-8 simples. | Parâmetro | Tipo | Descrição | | ---------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | `fileData` | `string` | Conteúdo do arquivo — base64 para binário, string UTF-8 para texto | | `fileName` | `string` | Nome original do arquivo | | `mimeType` | `"image/jpeg" \| "image/png" \| "image/webp" \| "application/pdf" \| "text/plain" \| "text/javascript"` | Tipo MIME. Use `text/javascript` para arquivos `.jsx`, `.tsx`, `.js`, `.ts` | Tamanho máximo do arquivo: **3 MB**. Para imagens grandes, prefira `image/jpeg` a `image/png`. **Saída** ```json theme={"system"} { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "path": "attachments/a1b2c3d4-e5f6-7890-abcd-ef1234567890", "type": "image", "mimeType": "image/jpeg" } ``` `type` é `"image"` para uploads de imagem/PDF e `"document"` para arquivos de texto/código. *** ## Ferramentas de chat ### `get-chat-history` Obter o histórico de mensagens de chat para um arquivo. **Entrada** | Parâmetro | Tipo | Descrição | | --------- | ------ | ------------- | | `fileId` | `uuid` | ID do arquivo | **Saída** — Objeto JSON com um array `messages`. Cada mensagem tem um `type` (`"request"` ou `"response"`), `author` (`"human"` ou `"ai"`), e `content_type` (`"text"`, `"summary"` ou `"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": [] } ] } ``` *** ## Ferramentas de design ### `get-design-guidelines` Obter as diretrizes de design armazenadas para um arquivo. **Entrada** | Parâmetro | Tipo | Padrão | Descrição | | ------------ | -------- | -------- | --------------- | | `resourceId` | `uuid` | — | ID do arquivo | | `linkedTo` | `"file"` | `"file"` | Tipo de recurso | **Saída** ```json theme={"system"} { "guidelines": "## Colors\n\nPrimary: #6366F1\nBackground: #FFFFFF\n\n## Typography\n\nFont: Inter", "linkedTo": "file" } ``` `guidelines` é `null` se nenhuma diretriz tiver sido definida. *** ### `update-design-guidelines` Definir ou substituir as diretrizes de design para um arquivo. As diretrizes são passadas como uma string de texto simples no formato `design.md` do Google — não passe um objeto ou JSON. O servidor executa validação suave e pode retornar uma seção `Warnings:` na resposta listando problemas (chaves desconhecidas, cores não-hex) que foram aceitos mas podem ser ignorados pela IA. Exiba-os ao usuário. **Entrada** | Parâmetro | Tipo | Padrão | Descrição | | ------------------ | ---------------- | -------- | -------------------------------------------------------------------------------------------- | | `resourceId` | `uuid` | — | ID do arquivo | | `designGuidelines` | `string` (min 1) | — | Conteúdo de texto bruto das diretrizes. Deve ser uma string simples — não codificado em JSON | | `linkedTo` | `"file"` | `"file"` | Tipo de recurso | **Regras de validação** * O preâmbulo deve ser aberto e fechado corretamente * As linhas do preâmbulo devem ser YAML válido em estilo de bloco * O corpo do Markdown não deve conter cabeçalhos `##` duplicados **Saída** — `"Design guidelines updated successfully"`, opcionalmente seguido de uma seção `Warnings:`. *** ### `delete-design-guidelines` Limpar as diretrizes de design para um arquivo. **Entrada** | Parâmetro | Tipo | Padrão | Descrição | | ------------ | -------- | -------- | --------------- | | `resourceId` | `uuid` | — | ID do arquivo | | `linkedTo` | `"file"` | `"file"` | Tipo de recurso | **Saída** — `"Design guidelines deleted successfully"` *** ## Ferramentas Figma ### `import-figma` Importar um frame Figma para um arquivo Flowstep como elementos editáveis em sua tela. Reimportar o mesmo frame o atualiza no lugar. A organização do arquivo deve ter Figma conectado nas configurações do Flowstep. **Entrada** | Parâmetro | Tipo | Descrição | | ---------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `figmaUrl` | `string` | Link para um frame Figma específico. No Figma, clique com o botão direito no frame e escolha **Copy link to selection**. Um link para uma página importa todos os frames de nível superior nessa página (limitado a 20 frames sobre MCP). | | `fileId` | `uuid` | O arquivo Flowstep para importar o frame | **Saída** — `{ fileId, screenId }`. `screenId` é o id do elemento de tela importado — passe-o para `get-screen-image` para visualizar o resultado. Quando um URL de página importa múltiplos frames, `screenId` é `null` e `frameCount` é retornado em vez disso. ```json theme={"system"} { "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0", "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbe" } ``` *** ## Ferramentas de cobrança ### `get-plan-details` Obter o plano atual do usuário, status de inscrição e cota restante. Não recebe entrada. **Saída** ```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 } } } ``` Os limites variam por plano. Chame esta ferramenta antes de um lote de gerações para verificar a cota disponível.