Floot

Compatibility alias of get_guides — the identical tool under its common misspelling. Prefer get_guides; see it for full usage.

get_guide

Floot documentation for agents. Call with no arguments to list available guides. Pass `topic` for one guide (e.g. topic:'floot-overview') or `topics` (an array of ids) to fetch several at once. floot-overview explains how Floot projects work — read it before your first code change. Skill guides that ship seed code (marked in the list) AUTO-INJECT it into the project the first time they're loaded with a projectId — pass projectId whenever you're working on a project; idempotent, never overwrites existing files.

get_guides

Generate AI image assets directly into the project. Each image is written to the project's own asset storage and registered in its asset manifest; the tool returns the project-relative asset paths (/_cdn/static/...), which only resolve on the app's own domain — reference them in code or set one as the app/PWA icon via update_project_metadata (iconUrl). Use this for PROJECT-SPECIFIC imagery (mascots, tailored illustrations, app/PWA icons, imagery in a particular style); for generic stock imagery (nature, textures, generic people) use Unsplash URLs instead; if you already HAVE an image as a local file (generated or downloaded yourself), use upload_asset. Generate BEFORE building the components that use the images.

generate_image

What the user is looking at RIGHT NOW in their open Floot editor: the active page/component, the preview element they selected (mapped to source file:line), the preview device size, whether they drew a screenshot annotation for you, whether they REVERTED recent changes (undoing edits — re-read before editing if so), and any requests they queued via editor action buttons ("Fix with Floot" etc.). Call this FIRST when the user refers to something without naming it ("this", "here", "the button"), reports a problem without saying where ("it's broken", "looks wrong"), or implies they triggered something in Floot ("go", "I clicked fix", "I undid that"). Cheap and text-only. With several windows open, one answers (the result says which) — but a selection made in ANY window is merged in, so a "no selection" from the answering window plus a deposited selection from another window means the deposited one is what the user means. If it reports a pending annotation, call view_annotation to see the image.

get_current_context

Poll a pending tool call by its jobId. Each poll either returns the final result (succeeded/failed/cancelled), or reports the call as still running — call it again until you get the result. Failed calls return their stored error message. A jobId belongs to exactly ONE task: it never blocks other tools or other jobs (run them freely in parallel), and once terminal it is frozen history — a NEW user request means a fresh call on the originating tool, never re-polling an old jobId. Legacy v!/b! job ids are also accepted.

get_job_status

Your FIRST step when debugging any runtime problem — a 500, a failed request, a blank page, or 'it doesn't work' from the user. Call this before theorizing from an error message alone. Reads the project's runtime logs. source 'server' (default): the dev backend's request logs from the last hour — method, URL, status, duration, and per-request server log lines (pass log_reference_id from a previous listing for one request's full logs); includes background jobs (queueTask/scheduled/failure). source 'browser': console output AND client-side network requests (each fetch as `⇄ METHOD url → status`, with the error body for failed/4xx/5xx ones — the client-side view server logs miss, e.g. CORS/timeouts/third-party calls) captured from the user's open editor session. A browser network line's `ref=<id>` is a log_reference_id you can pass back with source 'server' for that request's full server logs. Empty if no editor is open. NOT CloudWatch: entries live ~1 hour and cover the dev backend + live session only — for the PUBLISHED app's logs, use run_code_in_vm's `_floot.getProdBackendLogs` (details: get_guides('prod-backend-logs')).

get_logs

Show the user a live preview card and return the preview link. On an EXISTING project this is typically called EARLY, before the first change, so the user watches edits live from the start; the result is informational and a working session normally continues past it. Do NOT call it right after create_project — that result already showed the same card; calling both duplicates it. The preview URL carries an access token in its query string and only works shared EXACTLY as returned (no Floot login, view-only — which is also what lets it open on a phone); it live-updates as you edit, so it also suits an in-app browser tab if your client has one. The result additionally includes the sandbox API base for your own headless /_api/* testing — the frontend does not render there and it is not a user-facing URL; the preview link is the one meant for the user. Floot HOSTS the app — to go to production use publish_app; never suggest deploying a Floot app to an external host.

get_preview_url

Read-only publish snapshot for a project: published (true/false, with the live URL when published), customDomains (the user's own domains attached to the project — apex and www are listed separately; empty when none), paid (the workspace owner has a paid plan, which allows removing the Floot badge), and displayFlootLogo (whether the live app shows the 'Made with Floot' badge; true until a paid owner turns it off). This is the ONLY tool that reports attached custom domains — read it before telling a user whether their domain is connected, and never conclude a domain is unattached from any other output. The publish card calls this on load to render fresh state; also check it before publishing — publish_app errors when the app is already published (use republish_app then), and republish_app errors when it is not.

get_publish_status

List the env vars a project's code can use and the resources behind them: (1) resources CONNECTED to the project — usable as process.env.<NAME> in endpoint code now; (2) the owner's other account-level credentials — reusable, but not usable in code until connected; (3) everything Floot can add. Call it to learn what env vars exist before writing backend code, and BEFORE provisioning or requesting any credential (the owner may already have the one you need). Pass query (case-insensitive substring over names, descriptions, types, and env var names) to filter when the account has many resources. Read-only. Details: get_guides('resources').

list_resources

List a Floot project's virtual file tree with sizes, plus its dependencies, current version (pass the version to write tools as expected_version), and current project metadata — title, description, app icon (iconUrl), splash screen, mobile app id, SSR, iOS Info.plist overrides, share target (iOS + Android), native system bars. This is where to look up those settings; update_project_metadata changes them.

list_files

List your Floot projects (id, name, last-updated, whether an app icon is set), most recently updated first. name_filter is a case-insensitive substring match on the stored name, which is often not the name the user uses for a project — on a small account a filter that matches nothing returns the whole list instead.

list_projects

Point the user's OPEN Floot preview at a page URL, a component's examples, or a page's examples — use it to SHOW the user what you just built ("here's the new dashboard page", "here's the Button component's states"), and pair it with screenshot_preview to see the result yourself. targetType "page" navigates the app's router to `path` — a URL path with optional query/hash ("/", "/user/123?tab=settings#top"; pages/user.$id.tsx serves /user/<id>). targetType "component" renders the component's .example.tsx showcase for `name` ("HeroSection", exactly as list_files shows it; tell the user if it has no example — you can create one). targetType "page-examples" renders the staged screens in pages/<name>.__example.tsx for the page `name` ("dashboard", "_index") — the same view as the preview's Live/Examples switch, so it needs that file to exist. Requires a Floot window to be open for this project; fails fast with guidance when none answers. Does not modify the project.

navigate_preview

Provision a Floot-managed backend resource for the project — fully server-side (Floot mints all secrets; no keys to paste). Also seeds the working code for it. Available: - database — A Floot-managed Postgres database (Neon). FLOOT_DATABASE_URL is set for the app. - auth — Email/password + session auth (JWT_SECRET, auto-provisions a database if none). Injects auth pages, endpoints, and helpers. - oauth-login — Sign in with Google via Floot's brokered OAuth (FLOOT_OAUTH). Injects OAuth provider classes, login buttons, helpers. - microsoft-login — Sign in with Microsoft via Floot's brokered login (FLOOT_MICROSOFT_LOGIN). Injects button + auth endpoints. - google-integration — Google API access (Gmail/Calendar/etc.) via Floot's brokered Google OAuth (FLOOT_GOOGLE_INTEGRATIONS). Injects Connect button + endpoints. - microsoft-integration — Microsoft Graph access (Outlook/Teams/etc.) via Floot's brokered Microsoft OAuth (FLOOT_MICROSOFT_INTEGRATIONS). Injects Connect button + endpoints. - push-notifications — Web + native push (FLOOT_PUSH). Mints VAPID keys, injects helpers/pushClient (subscribe/unsubscribe) + a service worker. For a user's OWN external key (their OpenAI key, an external database), this is NOT the tool — use request_external_resource instead. Idempotent: re-running returns the existing resource and skips seed files that already exist.

provision_resource

Publish the app to production or set up a custom domain — call when the user wants the app live or asks about a domain. Already-published apps needing a rebuild use republish_app instead. Read get_guides('publishing') for modes, inputs, and statuses before your first call.

publish_app

Introspect the database and write a typed schema helper the app uses for queries (kysely). Usually NOT needed after execute_sql — schema-changing statements re-pull automatically. Use it to refresh manually, or with helper_name to generate the helper for an additional/external database. The helper is GENERATED — never hand-edit it or cast around its types: if a column's type is too loose (e.g. role as string when code expects "user" | "admin"), fix the DATABASE (CREATE TYPE … AS ENUM + ALTER COLUMN … TYPE) and re-pull, and the union type falls out.

pull_database_schema

Run a READ-ONLY SQL query against the project's Postgres database (SELECT, EXPLAIN, etc.). Writes are rejected — use execute_sql for those. Returns JSON: `{rows, rowCount, command, truncated?}` (or `{results: [...]}` for multi-statement queries). Pass `database` only if the project has more than one.

query_database

Read a file from a Floot project (cat -n style). Paths follow the item scheme: components/Name.tsx, components/Name.module.css, helpers/Name.tsx, pages/name.tsx, pages/name.pageLayout.tsx, endpoints/route_POST.ts, endpoints/route_POST.schema.ts, static/file.txt, base.css. Use offset/limit for large files. Pass include_references:true to also list which project files reference this one (static import graph plus queueTask/runCode name references and, for endpoints, URL-path string usage) — check it before renaming or deleting a file, or use rename_file which rewrites importers itself. Hosted assets are readable too: pass the project-relative asset path (/_cdn/<name>, as returned by upload_asset / generate_image or used in the app's <img src>; private/<name> for private storage) and a png/jpeg/gif/webp image is returned as an image you can see (≤3.75 MB), text-typed assets as text, other binaries as a size/type summary. For a .ts/.tsx file, the file's CURRENT type errors are appended when the project's compute VM is already warm (so you see latent errors before editing); pass diagnostics:"off" to skip, or "wait" to boot the VM and force the check.

read_file

Read MULTIPLE files from a Floot project in ONE call — much cheaper than repeated read_file (the whole project is loaded once, one round-trip). Prefer this whenever you need several files together (e.g. an endpoint + its .schema.ts + the hook that calls it, or orienting in a feature). Pass up to 20 paths (same item scheme as read_file; /_cdn/<name> asset paths are accepted too and images come back as image blocks). Each file is returned cat -n style under a header. Each .ts/.tsx file's current type errors are appended when the compute VM is warm (diagnostics:"off" to skip, "wait" to force). include_references:true appends each file's referencing files (same analysis as read_file). Output is capped overall; if the batch is too large, whole files at the end are omitted and listed by name so you can read them individually.

read_files

Remove npm packages from a Floot project's dependency record (record-only; nothing runs).

remove_dependency

Rename one or more items and automatically rewrite every file that imports them. Use item names WITHOUT extensions (e.g. {from:'components/OldName', to:'components/NewName'}). Preferred over delete+create — preserves content and fixes importers. Same type only. Pass several renames to apply them atomically in ONE pass; importer rewrites are resolved across the whole batch (including chains where one rename's target is another's source).

rename_file

Rebuild the LIVE production app with the current project code — call after changes the user wants live (the app must already be published; otherwise use publish_app). Details: get_guides('publishing').

republish_app

Request the USER'S OWN external credential for this project — their OpenAI or Anthropic API key, an external Postgres connection string, or any other service's key (type GENERIC, e.g. Stripe/Resend — name the env vars via secret_env_vars). NOT for Floot-managed resources (database/auth/push/oauth/…) — use provision_resource for those; they need no user input. Returns a secure connect link: SHOW it to the user (UI-capable hosts render a Connect button automatically; on terminal hosts with shell access open it in the user's default browser yourself and paste the URL as plain text) and ask them to open it. The call completes only when the user finishes the connect flow — it never expires. Do NOT block on it: request the credential EARLY, keep building everything that doesn't need the secret (the env var names are known now — reference process.env.X in code before the secret exists), and check the request between tasks; the user may never connect it, and the build must not stall. NEVER ask the user to paste a secret into the chat. On completion you get the env var names — never the secret values. Re-calling with the same type returns the same pending request.

request_external_resource

Show the user an inline upload card so they can hand you a file from their device (image/font/audio/…) — it lands in the project's hosted assets and the card gives you the hosted publicUrl. This is the path for any file the user has: an image they attached in this chat (attachments never reach MCP servers — you see them through vision only, so the user re-picks the same file here), a file on their machine, or a user-provided file you hold but can't upload yourself (over the 3 MB inline cap with no S3 egress — the card uploads from their browser, which is never egress-blocked). Returns a jobId — poll get_job_status; it stays running until they upload, then returns the publicUrl to reference in code. When you show the card, tell the user in a sentence why you're asking — e.g. that you can see their image but the file itself doesn't reach Floot, so re-adding it here is a one-click step — and ask them to say "uploaded" when done in case your polling ends before they finish. For files you hold yourself, use upload_asset; for AI-generated imagery, use generate_image.

request_user_upload

Run a TypeScript snippet inside the RUNNING APP's preview document in the user's open Floot editor (`document`/`window` ARE the live app's DOM — query `document` directly; do NOT look for a preview iframe, there is none from the snippet's point of view). This is the CANONICAL way to read the live app's DOM — measuring elements, reading computed styles, inspecting rendered output. If you ALSO have your own browser/DevTools automation, it CANNOT reach into the Floot preview (it renders in a cross-origin iframe — your clicks silently no-op and its DOM is invisible to you), so use THIS tool for anything inside the app, not those. `_floot.*` helpers are available. The snippet MUST `export default async function` and return a string — the returned value is the tool result (unlike run_code_in_vm, which is a plain script returning stdout). It can import project files by relative path from the root (e.g. `./helpers/foo`). Requires the user to have the project open in the editor — fails fast with guidance if no browser is connected; prefer run_code_in_vm for anything that doesn't need the DOM. Simple interaction checks work well: element.click() a button, await a beat, then read the resulting DOM/state to verify a flow end-to-end — do this instead of asking the user to test basic interactions. Multi-step e2e journeys and typed text input are where simulation gets unreliable (React controlled inputs ignore assigned values) — leave THOSE to the user.

run_code_in_browser

Run a Node.js snippet on the project's compute VM (headless — no browser needed). The project's npm dependencies are importable; network access works, so you can call the project's /_api/* endpoints (get_preview_url → apiBaseUrl). ESM by default; bare require() snippets run as CJS. Returns stdout+stderr. Runs in an ISOLATED temp dir, NOT the project root, with NO access to the project's environment: `process.env` carries none of the project's env vars or secrets (only PATH/HOME/NODE_ENV are set — anything like `process.env.POSTHOG_API_KEY` reads back `undefined`), and project source files are NOT importable by relative path (`import './helpers/foo'` fails with ERR_MODULE_NOT_FOUND — only npm dependencies resolve; contrast run_code_in_browser, which runs at the project root and CAN import project files). For anything that needs project secrets, env config, or DB access, use the `_floot` helpers below (they proxy to the project's server context) or fetch the project's /_api/* endpoints over the network — those run server-side WITH the full env; the VM snippet itself never sees it. A `_floot` global is available with project-scoped server-data helpers (no DB creds needed, no HTTP wiring): `await _floot.runSQLQuery({ query, resourceName?, reasonAndExplanationForNotReadOnly? })` (omit the reason for a read-only query; pass it to allow writes; resolves to `{rows, rowCount, command, truncated?}` — or `{results: [...]}` for multi-statement queries), `getHostingUsage({days?})`, `getLambdaUsage({days?})`, `getPushHistory({subscription?,from?,to?,offset?})`, `getProdBackendLogs({filter?,from?,to?,nextToken?,limit?})` (the PUBLISHED app's backend CloudWatch logs; details: get_guides('prod-backend-logs')), `storageList(prefix)` (prefix MUST start with "public/" or "private/" — e.g. storageList("public/") to list everything public), `storageGetUrl(key)`, `storageGetFileSizes(visibility, continuationToken?)`, `storageUpload({filename,sizeBytes,contentType})`, `storageDelete(key)`, and `getFileById(id)` (returns `{url, fileName, contentType}` — fetch the url for bytes). Same surface as runCodeInBrowser's `_floot`, minus the DOM/editor-only helpers.

run_code_in_vm

Run the project's Jasmine spec files (helpers/*.spec.tsx) headlessly on the project VM (jsdom — no browser needed). Frontend AND backend code is testable: specs may render components (@testing-library/react) or import endpoint handlers/backend helpers and call them directly. Limits: fetch throws inside tests (mock with spyOn(globalThis, "fetch")), process.env secrets are absent, and specs importing @floot/* service modules are skipped (no mocks yet). Returns per-file PASS/FAIL with failing expectations. Defaults to all spec files except hook specs (file name contains "use" — those need real React scheduling and are excluded, matching the in-editor checker); pass `paths` to run specific spec files, including hook specs.

run_tests

Capture a screenshot of the user app. Call it whenever you want to SEE what the app currently looks like (layout, styling, rendered state) or want to debug the app.

screenshot_preview

Search a Floot project's files (string or regex) with optional glob filters (e.g. ['components/*', 'endpoints/**']). Returns file:line excerpts plus filename matches; capped at 40 results.

search_code

Search your Floot projects and their code. Returns result ids usable with fetch. For richer options, list_projects enumerates projects and search_code does code-level search.

search

Typecheck the project (incremental tsc on the project VM). Type errors don't block the app from running.

typecheck

Take the published app offline and release its subdomain — destructive, confirm with the user first. Details: get_guides('publishing').

unpublish_app

Update project settings. Keys: title (2-100 chars), description, iconUrl, splashUrl, mobileAppId, enableSSR (boolean), flootAiDisallowed (boolean — true opts the project out of @floot/ai), and iOS Info.plist purpose strings (NS…UsageDescription — set to a string, or null to remove) plus boolean Info.plist keys (UIViewControllerBasedStatusBarAppearance — set to a boolean, or null to restore the template default). Invalid keys/values are reported and skipped. NOTE: these take effect on the published app only after the next publish (publish_app, or the user's Publish button).

update_project_metadata

Upload a binary asset (image, font, audio, …) to the project's hosted storage. This uploads bytes you actually hold — a file you generated, downloaded, or read yourself. Chat attachments don't qualify: the user's attachments never reach MCP servers (you see attached images through vision only; there is no file, id, or URL behind them you can read), so for those use request_user_upload instead and the user re-picks the file in a card that uploads from their browser. Three modes. ChatGPT conversation files — a generated image, a file ChatGPT itself holds: pass the file as the `file` parameter and the host attaches a download link itself; this server fetches the bytes directly, at full quality (nothing goes through your sandbox or through base64 in arguments; content_type and size_bytes are optional here). Never downscale or re-encode a generated image to fit the inline cap — pass it as `file` instead. Files up to 3 MB you hold yourself — pass content_base64 plus size_bytes (the decoded byte count) and the upload completes in this call, returning publicUrl. Larger files — pass size_bytes alone to get an uploadUrl; PUT the raw bytes to it with the same content_type and exact byte count (e.g. `curl -X PUT -H 'Content-Type: image/png' --data-binary @file.png '<uploadUrl>'`), then reference publicUrl. Some sandboxes (claude.ai Cowork, ChatGPT containers) block egress to S3: if the PUT fails in any way — connection failure, proxy error, or a response without an x-amz-request-id header — that block is permanent for the session, so switch paths instead of retrying or re-encoding smaller: the `file` parameter in ChatGPT for any file that exists in this conversation, content_base64 for files under 3 MB, request_user_upload for user-provided files, or a PUT from inside the project VM via run_code_in_vm (re-mint the URL first; it is short-lived). For AI imagery generated fresh, use generate_image. A single file can be at most 100 MB via the presigned mode (the inline content_base64 mode is capped at 3 MB).

upload_asset

Internal bridge for the upload card (not for agents — use request_user_upload / upload_asset). phase 'presign' mints the PUT URL for the picked file; phase 'complete' verifies the object landed and finishes the request_user_upload call with the publicUrl.

card_upload_asset

View a screenshot annotation the user drew on the app preview (annotationId comes from get_current_context). Returns the annotated image — the user's drawings/text point at what they mean. Annotations expire after ~1 day.

view_annotation

Create or fully overwrite a file in a Floot project. Content is written literally. Paths must follow the item scheme (see read_file); invalid paths are rejected with the rule they broke. Pass expected_version (from list_files/read_file) to detect concurrent edits. Writing components/Name.module.css sets the css of components/Name — other properties of the item are preserved.

write_file