add_dependency
ChatGPTAdd npm packages to the project (validated against Floot's supported set — rejected packages get a supported alternative named; some versions are pinned/substituted). Avoid node-gyp/native packages (exception: sharp is supported, auto-pinned), WASM modules, and packages bundling large binaries (e.g. ffmpeg/ffprobe); pure JS/TS preferred. A bare kysely keeps the version the project already records (a project without one gets 0.28.17), the version its db/schema helpers are written against; pass an explicit kysely@<version> only when upgrading it deliberately. Installs on the project VM and persists resolved versions. After a slow install completes as a job, call add_dependency again with the same packages — the second call is fast and persists.
apply_patch
ChatGPTApply a V4A patch to a Floot project — create and update multiple files in ONE atomic operation. Format: "* Begin Patch" envelope with " Add File: path" (+ prefixed lines) and " Update File: path" (hunks: optional "@@ anchor" locator, space-prefixed context, -/+ lines, optional " End of File"), then " End Patch". Paths follow the Floot item scheme (see read_file). To replace a file wholesale use Add File on its own path; the item's other files (e.g. its .module.css) are kept. This tool does not delete or rename: " Delete File:" sections are skipped and listed in the result (delete_file removes files), and " Move to:" is rejected (rename_file renames items and rewrites their importers). Every applied patch is recorded in the project history and can be reverted. Keep each patch MODEST (a few files / few hundred lines): chat clients cap per-message output, and a patch cut off mid-way is rejected whole ("missing * End Patch") — split big changes across several apply_patch calls.
call_app_function
ChatGPTCall one function of this project's own backend, the way its own code would: a function the project exports from helpers/flootAppExports.tsx, run in its published app, returning that function's JSON result. list_files shows the project's exported functions with their signatures; the function name and its input come from there. Use it to test an export after publishing it, or to do something for the user through the app's own logic instead of raw SQL. The function runs for real (a function that writes, sends or charges does so), so call one that changes anything only when the user asked for that change. Only functions in the last publish; needs edit access to the project. Up to 25 seconds; no answer in time does not mean it did not run. Details: get_guides("app-calls").
cancel_request
ChatGPTWithdraw a pending request you created — a credential request from request_external_resource, a custom-domain setup request from publish_app, or an open screenshot job from screenshot_preview (jobId from that tool). Only pending requests can be cancelled — completed ones are final — and cancelling is final too: a cancelled request can't be resumed (the user would need a new one). Use when the user says to stop or they don't want to proceed.
card_upload_asset
ChatGPTInternal 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.
compare_branches
ChatGPTShow what merging one branch (main or a fork) into another branch of the same project would change. projectId is always the TARGET (the branch merged into); sourceProjectId is the branch merged in. - Output: changed files, every conflict with its marker text, the migration script (static/__dev/migration.js on the branch the merge edits), key conflicts, new env vars the target lacks, missing resources, and targetVersion / sourceVersion for start_merge. - With no conflicts it also starts the pre-merge checks (install, typecheck, build, frontend, migration script typecheck and dry run) in the background. Neither branch is changed. - Conflicts: a merge from x into y edits y; a merge into main edits the source branch (main is never edited by a merge). Fix each conflicted file there with edit_file / apply_patch so it holds both sides' changes, then compare again. - When to use: the user asks to merge branches or forks, what a merge would change, or to fix a failed merge. Flow: compare_branches → read_merge_conflict and fix each conflict → write static/__dev/migration.js if the database or storage needs changes (get_guides("fork")) → compare_branches → start_merge → get_merge_status.
copy_file
ChatGPTCopy one or more items to new names (e.g. {from:'components/Card', to:'components/BigCard'}). Item names without extensions; same type only. Importers of the source are left unchanged. Pass several copies to apply them in one call.
create_checkpoint
ChatGPTCreate a NAMED checkpoint — a labeled restore point the user sees in the project's Checkpoints panel and can revert to later. All file/dependency changes since the previous checkpoint are grouped under it. Call this AFTER completing a coherent unit of work (a feature, a fix, a requested change set) — not after every file write. Give it a short user-meaningful title describing what was accomplished (e.g. 'Added login page with email auth'), optionally a description with detail. No-op when nothing changed since the last checkpoint. Restoring a checkpoint reverts code and project config only — database rows, uploaded assets and published deployments are not rolled back.
create_project
ChatGPTCreate a new Floot project (pre-seeded with the shared component library) and return its id. initial_prompt describes the app to build — what it does and for whom — keeping the user's own wording where they gave one rather than a summary. It becomes the project's system prompt (static/__dev/system-prompt.md, which the user can edit) and grounds the project (served back as <project-instructions> in list_files). The result renders a live preview card for the user and includes the first-build playbook: a fresh project is EMPTY until pages are written, so a session normally continues straight into get_guides("design") and the first page rather than ending at the card.
delete_file
ChatGPTDelete a project file. Deleting an item's main code file (e.g. components/Foo.tsx) removes the whole item including its css/tests; deleting an aux file (e.g. Foo.module.css) only clears that part.
delete_storage_file
ChatGPTDelete files from the project's storage (what the app uploaded or serves from /_cdn/), by their full keys as run_code_in_vm's _floot.storageList returns them ("public/…" or "private/…"), up to 100 per call. The bytes are gone for good. For a public file of a published app, its CDN copy is removed too; the result says what to tell the user about that. Only when the user asked for the files to be deleted: to stop using a file, remove its reference from the code instead. Needs edit access to the project.
edit_file
ChatGPTReplace old_string with new_string in a project file. old_string must match the current content exactly (including whitespace) and be unique unless replace_all is set. Prefer this over write_file for changes to existing files.
execute_sql
ChatGPTRun a WRITE SQL statement against the project's Postgres database (the Floot-managed one, or an external Postgres the user connected) — CREATE/ALTER TABLE, INSERT, UPDATE, DELETE, DROP, migrations. Destructive statements are allowed but your MCP client will show the user the SQL and ask them to approve it (they can allow once or for the session). Schema-changing statements (CREATE/ALTER/DROP of tables, types, …) automatically re-pull the typed schema helper and return the updated schema — no separate pull_database_schema call needed. Pass database only if the project has more than one. By default the whole query (every statement in it) runs on one connection in one transaction that Floot opens and commits: if any statement fails, or the query times out before its COMMIT, nothing is applied. Leave BEGIN/COMMIT/ROLLBACK out of the query — a COMMIT or ROLLBACK inside it ends that transaction early, so a later failure no longer undoes what came before. Set no_transaction for statements that cannot run inside a transaction block (VACUUM, CREATE INDEX CONCURRENTLY, …); each statement then applies as it finishes. Queries are stopped after 75 seconds either way; split a longer migration into several calls. A disconnect does not stop a call that has started: if you got no result, check the schema before running it again.
fetch
ChatGPTFetch a search result by id: a project overview ('<projectId>') or a file ('<projectId>:<path>'). For direct access to a known file or project, read_file/list_files give more detail.
floot_app_preview
ChatGPTOpens a live preview of a Floot project beside the conversation. Opened by the user, not by the assistant.
floot_home
ChatGPTOpens Floot (your projects and their live previews) from ChatGPT's navigation. Opened by the user, not by the assistant.
floot_home_update
ChatGPTInternal to the Floot app view: star/unstar a project, and create, rename, delete folders or move a project between them. Not for the assistant.
fork_project
ChatGPTFork a project (main or any fork) into a new branch project, with its own database branch and test keys. Early access: refused on accounts without branching. When to use: the user asks to fork, branch, or try changes away from the current project. - name: chosen by the user. copyFlootDb only when the user said which database; omitted, nothing is forked and a card lets the user pick it, edit the name and press Fork. - copyFlootDb "full": the parent's current data. "schema": same tables, no rows. "pointInTime" + databaseAt (ISO 8601 with zone): the parent's database as it was then (code, files and keys stay current), to see or recover older data; the result states the time used. - Output: the fork's project id and preview link. Merge it back with compare_branches, then start_merge. Code that breaks on a fork: get_guides("fork").
generate_image
ChatGPTGenerate 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); if you already HAVE an image as a local file (generated or downloaded yourself), use upload_asset. To edit or restyle an existing image, or keep a character/product/logo consistent, pass it in reference_images (this project's stored assets only: an outside image or the user's photo goes in with upload_asset / request_user_upload first, then pass the path it returns); the prompt then says what to change or produce from it. Generate BEFORE building the components that use the images.
get_branch_settings
ChatGPTRead a branch's six switches (all off by default): Receive main's email, Send email, Scheduled jobs, Receive main's realtime messages, Send realtime messages to main, Queued jobs. Lists only those the branch's code uses, as the UI does. - When to use: a branch sends or receives no email, its scheduled or queued jobs don't run or run twice, or realtime messages or presence aren't shared with main. - Read-only: the user changes them in the branch's Project Settings › Advanced (branch creator or project owner).
get_current_context
ChatGPTWhat 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_guides
ChatGPTFloot 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_job_status
ChatGPTPoll 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_live_payments
ChatGPTLook up your Floot Payments records in Stripe across all your projects: one record by id, or a list of one record type. Read-only. Reads LIVE mode unless mode is "test", which reads the test payments made in the preview (those never appear in the user's Stripe dashboard). Refunds, cancels and every other change are not possible here; for those the user logs in at stripe.com. Read get_guides('live-payments') before your first call. Responses follow Stripe API version 2026-08-26.dahlia.
get_logs
ChatGPTYour 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. source 'background': not log lines but the live state of background work, for the preview AND the published app — the schedules actually deployed (scheduled jobs, recurring and delayed queueTask) with their next run, the runs in progress right now, and the runs that were long or cut off at the 15-minute limit in the last 7 days. Use it to answer 'is that job still running?', 'did it time out?' and 'can anything start it again?' (limit and log_reference_id are ignored). Sources 'server' and 'browser' are 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_merge_status
ChatGPTState of a merge by mergeId (merges started in the UI too): running, done or failed. On failed: the failing step or migration script and its exact error. On done: the keys added to the target and the passed pre-merge checks.
get_preview_url
ChatGPTShow 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. It is not needed right after create_project, whose result already includes the same card. 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: publish_app publishes it to production.
get_publish_status
ChatGPTRead-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), plan (free | pro | power — paid cannot tell Pro from Power), nativeBuilds (the owner's remaining monthly iOS/Android app-build allowance; unlimited is true on plans where the ceiling is only a fair-use backstop, and while an Action Boost is live (boostUntil says until when; builds started before then never count toward the allowance) — read this BEFORE passing mobile: true, and on a metered plan build only when the user asked for a native/TestFlight/Play build), displayFlootLogo (whether the live app shows the 'Made with Floot' badge; true until a paid owner turns it off), and mobileBuild (the project's latest native app build: building, succeeded, or failed with what to fix; isMobileTestMode marks a mobile test build — an app build finishes minutes AFTER the publish job it rode on, so read this to learn how it ended before telling the user it worked). 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 to know whether publish_app will publish fresh or publish the live app again.
list_branches
ChatGPTList a project's main project and every branch you can open, with their ids, names and status. projectId may be the main project or any of its branches. - When to use: the user names a branch of a project, or asks which branches it has.
list_files
ChatGPTList 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_projects
ChatGPTList 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_resources
ChatGPTList 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').
navigate_preview
ChatGPTPoint 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.
provision_resource
ChatGPTProvision 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 — FLOOT_GOOGLE_INTEGRATIONS is built-in Google integration. Use it to let end users connect their Google account so the app can read/write their Gmail, Google Calendar, or Google Drive — unless the user specifies they want to use their own Google client. See get_guides("floot-provided-google-integrations"). - 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. Enum values not listed above are beta-gated and unavailable on most accounts. SENDING email from the app is NOT a resource — the builtin @floot/email handles it with zero setup (get_guides("email")). 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. - app-connection — let this project's backend call functions ANOTHER Floot app exports (no API keys): pass app_target and app_functions. Only apps the user can edit, only functions in the other app's helpers/flootAppExports.tsx (saved is enough: write both apps first, connect, then publish both); the user confirms in a dialog. Read get_guides("app-calls") first.
publish_app
ChatGPTPublish the app to production — call for the first publish, to publish again after changes the user wants live, and to set up a custom domain. Omit domain and the user gets the publish form instead (nothing is published until they press Publish on it; to publish a live app again without the form, pass domain_type 'floot_subdomain' and its current subdomain). Pass mobile: true whenever the user mentions iOS, Android, TestFlight, App Store, Google Play, or a mobile/native app — with no store account connected that returns a Connect card; with one connected it publishes with the store builds attached. When the project takes payments and its owner has not finished Stripe setup, the publish is refused and a Set up payments card is returned (nothing published): tell the owner to click the button on the card and finish Stripe setup, then call publish_app again. publish_app always publishes live (web, and the mobile app when it is built; payments in Stripe live mode) — never ask the user test or live. Mobile test builds are started by the user on floot.com. Read get_guides('publishing') for modes, inputs, and statuses before your first call.
pull_database_schema
ChatGPTIntrospect the database and write a typed schema helper the app uses for queries (kysely on current projects; some legacy projects use drizzle or snake_case kysely — the pull matches whatever the project already uses). 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.
query_database
ChatGPTRun a READ-ONLY SQL query against the project's Postgres database (SELECT, EXPLAIN, etc.) — the Floot-managed database, or an external Postgres the user connected to the project. 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.
read_file
ChatGPTRead 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. A read does not typecheck by default: pass diagnostics:"auto" to append a .ts/.tsx file's CURRENT type errors when the project's compute VM is already warm (so you see latent errors before editing), or "wait" to boot the VM and force the check. older_than walks the file's HISTORY: pass "current" to see the file as it was just before its latest change, then the cursor from that result to step one change further back — use it when something used to work and you want to compare or restore an earlier version (write the old content back with write_file).
read_files
ChatGPTRead 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. Reads do not typecheck by default: diagnostics:"auto" appends each .ts/.tsx file's current type errors when the compute VM is warm, "wait" forces the check. 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. With older_than (up to 5 paths) the files are walked back through history TOGETHER on one timeline — the way to keep a component and its stylesheet consistent.
read_merge_conflict
ChatGPTRead one conflicted file of a merge in pages (cat -n style, 400 lines by default), with its conflict block line ranges. projectId is always the TARGET (the branch merged into); sourceProjectId is the branch merged in. - view: "markers" (the file with conflict markers; default), "source" or "target" (that branch's current file).
remove_dependency
ChatGPTRemove npm packages from a Floot project's dependency record (record-only; nothing runs).
rename_file
ChatGPTRename 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).
request_external_resource
ChatGPTRequest 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_user_upload
ChatGPTShow 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. Some clients can't show the card (Microsoft Copilot Studio, for one): if the user says they don't see it, give them the project's preview link (get_preview_url) and ask them to sign in there and drag the file into Storage › Static (or use its Upload button), then call list_files — the file is listed under "Files uploaded in the editor" with the /_cdn/static/ path to use.
run_code_in_browser
ChatGPTRun 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_vm
ChatGPTRun 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_tests
ChatGPTRun 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.
screenshot_preview
ChatGPTCapture 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. By default it shows whatever device the user has the preview on. Pass viewport to see it on another device — this is how to check a mobile or tablet layout: the preview switches to that device for the capture only, then back. Never build a separate "mobile" page or example just to look at a narrow layout.
search
ChatGPTSearch 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_code
ChatGPTSearch 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.
start_merge
ChatGPTMerge sourceProjectId into projectId (the target). This changes the target: its code becomes the merged code, and the migration script runs on its database and storage. Only when the user asked to merge. - targetVersion / sourceVersion: from the latest compare_branches. conflictSides: conflict path → "source" | "target" (that branch's current file wins). addKeys: new env vars from compare to add to the target after the merge. keyChoices: env var → "target" | "source" for every key conflict ("source" overwrites the target's value). - Waits up to ~40 s for the pre-merge checks ("Checks still running" → call again), then starts the merge and returns its mergeId: poll get_merge_status. - A started merge is atomic: it ends done (code + migration applied) or failed (nothing changed on the target). - Refused (with the reason) on failed checks ("Failed at <step>: …": fix the branch, compare, start again), unresolved conflicts, changed versions, an already merged branch or a running merge. - Migration script: static/__dev/migration.js on the branch the merge edits (never main), written with write_file; dry-run, then run in one transaction on the target on every merge, so idempotent; ctx.sourceQuery / targetQuery / storageCopy / storageDelete only, no network, ~7 min per run. get_guides("fork").
typecheck
ChatGPTTypecheck the project (incremental tsc on the project VM). Type errors don't block the app from running.
unpublish_app
ChatGPTTake the published app offline and release its subdomain — destructive, confirm with the user first. Details: get_guides('publishing').
update_project_metadata
ChatGPTUpdate project settings (current values appear at the top of list_files). Keys: title (2-100 chars), description, iconUrl (the app's icon/logo: favicon, home-screen icon and native app icon — a /_cdn/static/… path from upload_asset, generate_image or request_user_upload, or an absolute https URL; null resets), splashUrl (native splash screen, same value forms), 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). The iosInfoPlist keys only affect builds made before the first iOS publish; after the iOS app is published, edit the project file static/__dev/native/ios-info.plist directly with write_file/edit_file (see get_guides('ios-info-plist')). Likewise, after the first Android publish, edit static/__dev/native/android-manifest.xml directly for manifest changes (see get_guides('android-manifest')). shareTarget makes the native app appear in the iOS and Android share sheets (other apps can share photos/videos/files/text into it): pass { enabled: true, mimeTypes?, allowMultiple? } to register, { enabled: false } to remove; receiving the shared items still needs the handler in app code — read get_guides('share-target') first and ship both together. nativeSystemBars controls how the native app treats the status bar / Android navigation bar: mode 'inset' (default) keeps the app below the bars and paints the exposed strips color (default black — set it to the app's header color for a seamless look); mode 'edge-to-edge' runs the app under the bars, which REQUIRES the app to pad by var(--safe-area-inset-top/bottom) itself — read get_guides('native-system-bars') first and ship both changes together. Not superseded by the __dev/native files. serverMemoryMb sets the memory (MB) of the project's server Lambda, which runs every endpoint, queued task, scheduled job and SSR render (default 1024 MB; 2048 for the published app when SSR is on — the dev backend never bumps). EXPERT SETTING — NEVER change it on your own initiative or as a side effect of another request, only when the user explicitly asks to change the server memory AND understands the trade-off: too low and the backend stops working entirely (killed out-of-memory); Lambda CPU scales with memory, so a lower value also makes every request slower and — because compute is billed per GB-second of billed duration — can cost MORE, not less; a higher value costs more per millisecond. Allowed range 512–4096 MB, whole MB (if a size turns out not to be available for the app's server, the deploy fails and the error names this setting). It applies to the dev backend at the next backend deploy and to the published app at the next publish. Pass null to restore the default. Read get_guides('server-memory') before changing it. analyticsMode controls the built-in visitor analytics tracker every published app includes (the project's Analytics tab): 'storage' (default) keeps a 30-minute session id in the visitor's localStorage, which is device storage that needs consent under EU ePrivacy / UK PECR — an app with EU/UK visitors pairs it with a consent banner that calls window.flootAnalytics.setMode(); 'memory' keeps the id in memory only (nothing stored on the device, no consent needed, but a reload or new tab counts as a new session); 'off' sends no analytics at all. Only change it when the user asks about analytics, cookies, consent or privacy for their published app; it takes effect at the next publish. Read get_guides('analytics') for the consent-banner API before changing it. iosDeviceFamily picks the devices the native iOS app is built for: 'iphone-and-ipad' (default, universal) or 'iphone' (iPhone only — the app still installs on iPads but…
upload_asset
ChatGPTUpload 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).
view_annotation
ChatGPTView 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.
write_file
ChatGPTCreate 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.
add_dependency
Claudeapply_patch
Claudecancel_request
Claudecard_upload_asset
Claudecopy_file
Claudecreate_checkpoint
Claudecreate_project
Claudedelete_file
Claudeedit_file
Claudeexecute_sql
Claudefetch
Claudegenerate_image
Claudeget_current_context
Claudeget_guide
Claudeget_guides
Claudeget_job_status
Claudeget_logs
Claudeget_preview_url
Claudeget_publish_status
Claudelist_files
Claudelist_projects
Claudelist_resources
Claudenavigate_preview
Claudeprovision_resource
Claudepublish_app
Claudepull_database_schema
Claudequery_database
Clauderead_file
Clauderead_files
Clauderemove_dependency
Clauderename_file
Clauderepublish_app
Clauderequest_external_resource
Clauderequest_user_upload
Clauderun_code_in_browser
Clauderun_code_in_vm
Clauderun_tests
Claudescreenshot_preview
Claudesearch
Claudesearch_code
Claudetypecheck
Claudeunpublish_app
Claudeupdate_project_metadata
Claudeupload_asset
Claudeview_annotation
Claudewrite_file
Claude