> ## 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 > Schema de entrada, formato de saída e exemplos para as 20 ferramentas MCP do Flowstep. Todas as ferramentas devolvem um array `content` de blocos de conteúdo MCP. Ferramentas de texto devolvem `{ type: "text", text: "" }`. Ferramentas de imagem devolvem `{ type: "image", data: "", mimeType: "image/png" }`. Em caso de erro, `isError: true` é definido e o bloco de texto contém a mensagem de erro. *** ## Ferramentas de ficheiros ### `list-files` Lista os ficheiros do Flowstep do utilizador atual. **Entrada** | Parâmetro | Tipo | Predefinição | Descrição | | ----------------- | ----------------- | ------------ | ------------------------------ | | `orderByCreation` | `boolean` | `true` | Ordenar por data de criação | | `limit` | `integer` (1–100) | `20` | Número de ficheiros a devolver | | `offset` | `integer` (≥0) | `0` | Offset de paginação | **Saída** — Array JSON de objetos de ficheiro. ```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` Obtém um único ficheiro por ID. O conteúdo do ficheiro é propositalmente omitido — utiliza `get-screen` ou `get-screen-image` para inspecionar ecrãs, e `get-design-guidelines` para recuperar as diretrizes anexadas. **Entrada** | Parâmetro | Tipo | Descrição | | --------- | ------ | -------------- | | `id` | `uuid` | ID do ficheiro | **Saída** — Objeto JSON de ficheiro. ```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` Cria um novo ficheiro Flowstep. **Entrada** | Parâmetro | Tipo | Descrição | | --------- | ---------------- | ---------------- | | `title` | `string` (min 1) | Nome do ficheiro | **Saída** — Objeto JSON de ficheiro com o `id` do novo ficheiro. ```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" } ``` Utiliza o `id` devolvido como `fileId` nas chamadas de ferramenta subsequentes. *** ### `update-file` Muda o nome de um ficheiro. **Entrada** | Parâmetro | Tipo | Descrição | | --------- | ---------------- | -------------- | | `id` | `uuid` | ID do ficheiro | | `name` | `string` (min 1) | Novo nome | **Saída** — Objeto de ficheiro atualizado com a mesma forma 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` Elimina permanentemente um ficheiro. O `name` que passes é verificado contra o nome real do ficheiro antes da eliminação — se não corresponder, a eliminação é abortada. Isto previne a eliminação acidental do ficheiro errado. **Entrada** | Parâmetro | Tipo | Descrição | | --------- | -------- | ---------------------------------------------------------------------------------- | | `id` | `uuid` | ID do ficheiro | | `name` | `string` | Nome atual do ficheiro — tem de corresponder exatamente ou a eliminação é abortada | **Saída** — `"File deleted successfully"` Isto é irreversível. Todos os ecrãs do ficheiro são eliminados. *** ## Ferramentas de ecrã ### `list-screens` Lista todos os ecrãs gerados para um ficheiro. Utiliza os valores de `screenId` devolvidos para referenciar ecrãs 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 ficheiro | **Saída** — Array JSON de resumos de ecrã. ```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 do ecrã atribuído pelo utilizador, ou `null` se sem nome. *** ### `get-screen` Obtém o código JSX para um ecrã permitindo-te editar ou utilizar o código fora do Flowstep. Utiliza `get-screen-image` para uma pré-visualização visual em vez disso. **Entrada** | Parâmetro | Tipo | Descrição | | ---------- | ------ | -------------------------------------------------------------------------------------------------------- | | `fileId` | `uuid` | ID do ficheiro | | `screenId` | `uuid` | O `screenId` devolvido por `list-screens` ou do array `screenIds` devolvido por uma ferramenta de design | **Saída** — O ecrã como código (JSX). Nota o comentário da primeira linha que é necessário ao utilizar a ferramenta `add-screen`. ```json theme={"system"}
World Clock
Search cities...
...
; ``` *** ### `add-screen` Adiciona um novo ecrã a um ficheiro Flowstep a partir de uma string JSX bruta. **Entrada** | Parâmetro | Tipo | Descrição | | ------------ | -------- | ------------------------------------------------------------------------------------- | | `fileId` | `uuid` | ID do ficheiro | | `jsxContent` | `string` | JSX para adicionar ao ficheiro como um ecrã | | `screenType` | `string` | Necessário se o tipo de ecrã não estiver definido como um comentário no início do JSX | **Nota** - Um comentário semelhante ao abaixo TEM de estar presente como a primeira linha do JSX já que é utilizado para adicionar o ecrã corretamente. `screenType`, `name`, e `screenId` são todos opcionais — `screenId` é utilizado (internamente) se presente (por exemplo, ao passar JSX copiado da saída de `get-screen`) mas não é obrigatório. O nome do ecrã é tirado do campo `name` do comentário (apresentado como "Copy of \"), ou "Untitled" se ausente. `` **Saída** — O ID do ecrã recém-adicionado. ```json theme={"system"} { "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbf" } ``` *** ### `get-screen-image` Renderiza um ecrã para PNG e devolve-o como uma imagem em linha. Requer um cliente que suporte blocos de conteúdo de imagem. **Entrada** | Parâmetro | Tipo | Descrição | | ---------- | ------ | -------------------------------------------------------------------------------------------------------- | | `fileId` | `uuid` | ID do ficheiro | | `screenId` | `uuid` | O `screenId` devolvido por `list-screens` ou do array `screenIds` devolvido 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 só está presente em ecrãs originalmente gerados com um array `designs`. Ecrãs gerados sem contexto de design devolverão um erro. Solução: utiliza `upload-attachment` para renderizar o ecrã como uma imagem, depois chama `create-new-design` com a imagem em `attachments` e uma mensagem descrevendo as mudanças desejadas. ### `create-new-design` Gera um ou mais designs de ecrã a partir de um prompt de texto. Omite `fileId` para criar um novo ficheiro automaticamente. Bloqueia até a geração estar completa ou até expiração do tempo (180 segundos). **Entrada** | Parâmetro | Tipo | Predefinição | Descrição | | ------------- | --------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `fileId` | `uuid` | — | Ficheiro alvo — omite para criar um novo ficheiro automaticamente | | `message` | `string` | — | Prompt descrevendo os ecrãs a gerar | | `attachments` | `AttachmentRequestData[]` (max 5) | `[]` | Anexos pré-enviados — imagens, PDFs, ou ficheiros de código. Sempre envia via `upload-attachment` primeiro; não coloquinhas o conteúdo do ficheiro em linha na mensagem | | `designs` | `DesignRequestData[]` | `[]` | Referências de design | **Saída** — `{ fileId, screenIds }`. Passa cada `screenId` para `get-screen-image` para ver resultados. ```json theme={"system"} { "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0", "screenIds": ["3f9e6eb6-5525-4383-9375-67e0bd762dbe"] } ``` *** ### `regenerate-design` Refaz ecrãs existentes do zero ou com uma variação de estilo. Requer pelo menos um `screenId` em `targets`. Bloqueia até a geração estar completa ou até expiração do tempo (180 segundos). **Entrada** | Parâmetro | Tipo | Predefinição | Descrição | | ------------------ | ----------------------------------------------------------- | ------------ | -------------------------------------------------- | | `fileId` | `uuid` | — | Ficheiro alvo | | `message` | `string` | — | Texto de prompt | | `targets` | `uuid[]` (min 1) | — | screenIds dos ecrãs 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 }`. Passa cada `screenId` para `get-screen-image` para ver resultados. *** ### `expand-design` Adiciona ecrãs de seguimento a um design existente. Requer pelo menos um `screenId` em `targets` e um `operationVariant` obrigatório. Bloqueia até a geração estar completa ou até expiração do tempo (180 segundos). **Entrada** | Parâmetro | Tipo | Predefinição | Descrição | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------- | | `fileId` | `uuid` | — | Ficheiro alvo | | `message` | `string` | — | Texto de prompt | | `targets` | `uuid[]` (min 1) | — | screenIds dos ecrãs 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 ecrã de seguimento a gerar | | `designs` | `DesignRequestData[]` | `[]` | Referências de design (resolvidas automaticamente) | **Saída** — `{ fileId, screenIds }`. Passa cada `screenId` para `get-screen-image` para ver resultados. *** ### `edit-design` Modifica ecrãs existentes através de um prompt. Requer pelo menos um `screenId` em `targets`. Bloqueia até a geração estar completa ou até expiração do tempo (180 segundos). **Entrada** | Parâmetro | Tipo | Predefinição | Descrição | | ------------------ | ------------------------------------------------ | ------------ | ------------------------------------------------------------------ | | `fileId` | `uuid` | — | Ficheiro alvo | | `message` | `string` | — | Instruções descrevendo as edições a aplicar | | `targets` | `uuid[]` (min 1) | — | screenIds dos ecrãs a editar | | `operationVariant` | `"dark_theme" \| "light_theme" \| "make_pretty"` | — | Atalho de estilo opcional | | `attachments` | `AttachmentRequestData[]` (max 5) | `[]` | Anexos pré-enviados. Sempre envia via `upload-attachment` primeiro | | `designs` | `DesignRequestData[]` | `[]` | Referências de design (resolvidas automaticamente) | **Saída** — `{ fileId, screenIds }`. Passa cada `screenId` para `get-screen-image` para ver resultados. *** ### `upload-attachment` Envia um ficheiro para utilizar como um anexo em `create-new-design` ou `edit-design`. Devolve `{ id, path, type, mimeType }` — passa este objeto diretamente no array `attachments`. Dois modos: **Modo 1 — Ecrã por ID** Passa `screenId` e `fileId`. O servidor obtém o estado do ecrã da base de dados e renderiza-o como uma imagem. | Parâmetro | Tipo | Descrição | | ---------- | ------ | -------------------------------------- | | `fileId` | `uuid` | Ficheiro contendo o ecrã (obrigatório) | | `screenId` | `uuid` | Ecrã a renderizar | **Modo 2 — Ficheiro externo** Passa o conteúdo do ficheiro diretamente. Ficheiros binários têm de estar codificados em base64; ficheiros de texto (incluindo código-fonte) são passados como strings UTF-8 simples. | Parâmetro | Tipo | Descrição | | ---------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | `fileData` | `string` | Conteúdo do ficheiro — base64 para binário, string UTF-8 para texto | | `fileName` | `string` | Nome original do ficheiro | | `mimeType` | `"image/jpeg" \| "image/png" \| "image/webp" \| "application/pdf" \| "text/plain" \| "text/javascript"` | Tipo MIME. Utiliza `text/javascript` para ficheiros `.jsx`, `.tsx`, `.js`, `.ts` | Tamanho máximo do ficheiro: **3 MB**. Para imagens grandes, prefere `image/jpeg` em relação 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 ficheiros de texto/código. *** ## Ferramentas de chat ### `get-chat-history` Obtém o histórico de mensagens de chat para um ficheiro. **Entrada** | Parâmetro | Tipo | Descrição | | --------- | ------ | -------------- | | `fileId` | `uuid` | ID do ficheiro | **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` Obtém as diretrizes de design armazenadas para um ficheiro. **Entrada** | Parâmetro | Tipo | Predefinição | Descrição | | ------------ | -------- | ------------ | --------------- | | `resourceId` | `uuid` | — | ID do ficheiro | | `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 não foram definidas diretrizes. *** ### `update-design-guidelines` Define ou substitui as diretrizes de design para um ficheiro. As diretrizes são passadas como uma string de texto simples no formato `design.md` do Google — não passes um objeto ou JSON. O servidor realiza validação branda e pode devolver uma secção `Warnings:` na resposta listando problemas (chaves desconhecidas, cores não-hex) que foram aceites mas podem ser ignoradas pela IA. Mostra estes ao utilizador. **Entrada** | Parâmetro | Tipo | Predefinição | Descrição | | ------------------ | ---------------- | ------------ | ---------------------------------------------------------------------------------------- | | `resourceId` | `uuid` | — | ID do ficheiro | | `designGuidelines` | `string` (min 1) | — | Conteúdo de texto bruto das diretrizes. Tem de ser uma string simples — não JSON-encoded | | `linkedTo` | `"file"` | `"file"` | Tipo de recurso | **Regras de validação** * O frontmatter tem de estar aberto e fechado corretamente * As linhas frontmatter têm de ser YAML válido em estilo de bloco * O corpo Markdown não deve conter cabeçalhos `##` duplicados **Saída** — `"Design guidelines updated successfully"`, opcionalmente seguido por uma secção `Warnings:`. *** ### `delete-design-guidelines` Limpa as diretrizes de design para um ficheiro. **Entrada** | Parâmetro | Tipo | Predefinição | Descrição | | ------------ | -------- | ------------ | --------------- | | `resourceId` | `uuid` | — | ID do ficheiro | | `linkedTo` | `"file"` | `"file"` | Tipo de recurso | **Saída** — `"Design guidelines deleted successfully"` *** ## Ferramentas de Figma ### `import-figma` Importa um frame do Figma para um ficheiro Flowstep como elementos editáveis na sua tela. Re-importar o mesmo frame actualiza-o no local. A organização do ficheiro tem de ter o Figma ligado nas definições do Flowstep. **Entrada** | Parâmetro | Tipo | Descrição | | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `figmaUrl` | `string` | Ligação para um frame específico do Figma. No Figma, clica com o botão direito no frame e escolhe **Copy link to selection**. Uma ligação para uma página importa todos os frames de nível superior nessa página (limitado a 20 frames através do MCP). | | `fileId` | `uuid` | O ficheiro Flowstep para o qual importar o frame | **Saída** — `{ fileId, screenId }`. `screenId` é o id do elemento de ecrã importado — passa-o para `get-screen-image` para ver o resultado. Quando uma URL de página importa múltiplos frames, `screenId` é `null` e `frameCount` é devolvido em vez disso. ```json theme={"system"} { "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0", "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbe" } ``` *** ## Ferramentas de faturação ### `get-plan-details` Obtém o plano atual do utilizador, estado de subscrição e quota restante. Não requer 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. Chama esta ferramenta antes de um lote de gerações para verificar a quota disponível.