Docs
LoginTry for free

Get started

Build

Platform

AI

Data & content

Automation

Developers

Developers

MCP tools

Every tool the Turbofy MCP gives your assistant: what it does, the inputs it takes, and how pushes, background jobs and locking work. You rarely call these tools yourself. The assistant picks them, guided by the skills, and this page helps you follow what it is doing.

How the tools fit together

Almost every tool takes an orgId and a workspaceId, so the assistant always says which workspace it works in. list_workspaces gives it both.

The record and file tools act on your workspace directly. Apps, schemas and flows work differently: the assistant pulls them into a session workspace, edits the files there, and pushes them back. The session workspace is a private sandbox computer with Node.js, npm and internet access. It belongs to you, and your edits stay in it between conversations until you push or pull again.

  1. 1Pull: app_pull, workspace_pull or flow_pull copies the current state into the session workspace.
  2. 2Edit: fs_read, fs_search and fs_edit change the files.
  3. 3Check: the push tool runs as a dry run first and shows what would change.
  4. 4Apply: the same push tool with dryRun: false makes the change.

Every push tool defaults to dryRun: true. The first push only shows what would change; nothing is applied until the assistant pushes again with dryRun: false.

Discovery and skills

list_organizations

Lists the organizations you belong to, with their ids. It takes no inputs.

list_workspaces

Lists every workspace you can open, with its organization. The assistant usually starts here to find the orgId and workspaceId that every other tool needs. It takes no inputs.

table_list

Lists the workspace's tables with the ofType value each one uses in the record tools. For each table it also shows its parent tables and the link column a child record stores to point at its parent.

  • includeFields: include every table's fields (default true).

list_skills and load_skill

list_skills lists the Turbofy skills: written instructions for one area each, such as apps, blocks or flows. load_skill loads one by name, so the assistant reads how that area works before it starts.

Records

The record tools read and write the data in your tables. ofType names the table; table_list shows the values. They run with your permissions, so the assistant only sees and changes what you can.

data_list

Lists the records of one table. With parentType and parentId it lists only one record's children, for example the files in one Assets folder.

  • fields: return only these columns, plus id.
  • limit and nextToken: page through a large table.
  • sortOrder and sortRange: order the records and narrow them by their sort key.

data_get

Reads one full record by ofType and id.

data_query

Filters and sorts the records of a searchable table by column values, and returns the matching page together with the total number of matches.

  • where: one condition per column; all of them must match. Operators: eq, ne, lt, le, gt, ge, in, contains, beginsWith and isNull.
  • Localized fields take a language suffix, such as title.en. Keys inside a JSON field use dotted paths, such as attributes.voltage.
  • orderBy and order sort the results; limit and offset page through them.

data_search

Full-text search over the columns you name in fields, ranked by relevance. Search terms match the beginnings of words. An empty query lists the newest records. Use lang to pick the language of localized fields.

data_query and data_search only work on tables that are marked as searchable. For every other table, use data_list.

data_create

Creates one record from item, with the columns directly on the object.

data_add_many

Creates many records in one batch. Every item is checked for unknown columns before anything is written, so a typo fails the whole batch instead of half of it. An item with the id of an existing record replaces that record.

data_update

Changes the columns you pass in item on one record. Columns you leave out keep their values.

data_delete

Deletes one record. It requires confirm: true, so a delete is always deliberate.

Files and assets

Files live in Assets. Some of these tools move files between Assets and the session workspace, so the assistant can open documents and images it cannot read directly.

file_upload

Uploads a file to Assets and creates its record. It takes exactly one source: text in content, binary data in contentBase64, or a public HTTPS address in sourceUrl, which the server downloads itself (up to 25 MB). Without a folderId, the file goes to the workspace's root folder.

file_upload_intent

For larger files: returns a short-lived upload address, so the file goes straight to storage without passing through the conversation. The file's record is created right away.

file_set_visibility

Makes a file PUBLIC or PRIVATE. A private file has no address an app can load, so an image shown in an app must be public. Files you attach in the Turbofy chat are stored as private files under Assets → Chats, and the assistant publishes one only when you clearly mean it to be public.

file_pull

Copies a file from Assets into the session workspace under files/<fileId>, so the assistant can open Word, Excel and PowerPoint files, archives and long texts with its own tools. The original stays unchanged in Assets. Files up to 50 MB.

file_push

The opposite of file_pull: saves a file from the session workspace to Assets as a new file, such as an edited PDF or a generated chart. It never overwrites an existing file. New files are private unless the assistant passes PUBLIC. Files up to 50 MB.

file_view

Shows the assistant an image so it can look at it, either from Assets (fileId) or from the session workspace (path). It takes PNG, JPEG, GIF and WebP up to 3.75 MB, for example a slide the assistant rendered or a chart it drew.

Session workspace files

These tools work on the files in your session workspace: the apps, schema and flows the assistant pulled. Paths are relative to the workspace, such as apps/<appId>/app.ts.

fs_list

Lists the files in a directory, by default the workspace root.

fs_read

Reads a file, or only part of it with offset (the first line) and limit (the number of lines).

fs_search

Searches file contents and returns the matching lines, so the assistant can find code before it reads a whole file. Patterns are regular expressions; fixedStrings searches for literal text and ignoreCase ignores case. It skips node_modules and returns up to 100 matches by default, 500 at most.

fs_write

Writes a whole file. The assistant uses it for new files and changes existing ones with fs_edit.

fs_edit

Replaces exact pieces of text in a file. Each piece must appear exactly once, unless replaceAll is set. All replacements in one call succeed together, or none of them is written.

fs_exec

Runs a shell command in the session workspace, for example npm install after adding a package to an app. It waits up to 20 seconds by default and 25 at most, then returns the exit code and the end of the output.

  • cwd: the directory to run in, such as apps/<appId>. By default the workspace root.
  • async: true: starts the command in the background and returns a taskId right away. Use it for anything that takes longer than 25 seconds.
  • mutates: false: says the command only reads, so the app files are not saved afterwards.

fs_task_status

Checks a background command started with fs_exec: whether it is running, done or failed, plus the output so far. The assistant calls it again until the command ends.

While an app is being pushed, fs_write, fs_edit and fs_exec refuse to change it. The reading tools keep working. See Editing while a push runs below.

Workspace schema

workspace_pull

Pulls the workspace's tables and fields into the session workspace as schema.ts, together with a snapshot of the pulled state that the push later merges against.

workspace_push

Compiles the edited schema.ts and applies the changes. It merges three versions: the pulled one, the edited one and the current one in Turbofy, so changes someone else made in the meantime are kept. New tables and fields are left without ids and get them when they are created. It defaults to a dry run.

An app tree has its own schema.ts, and app_push applies its changes along with the app. For schema-only work, use workspace_pull and workspace_push.

Apps

app_init

Creates a new app with a Home page and pulls it into the session workspace, ready to edit.

app_pull

Pulls an app into the session workspace as files: app.ts, one file per page, the schema, every block type with its React sources, shared modules under shared/, and the app's documents under docs/. It keeps a snapshot of what it pulled, which app_push merges against.

  • If generated files were edited since the last pull, it refuses to overwrite them. force: true overwrites them and discards those edits.
  • It reads every record of the app, up to 10,000 per kind, so apps with many languages and translations pull completely.
  • It is refused while the app is being pushed.

app_push

Publishes the app tree to the app's preview. The next three sections describe it in detail.

app_push_status

Waits for a push that is still running in the background and returns its result. It takes the same orgId, workspaceId and appId as the push.

app_preview_create

Creates a preview link for an app that works without signing in to Turbofy. The link must be opened within 60 seconds and works once. It starts a 15-minute browser session with your permissions, including writing data. For a later look, the assistant creates a new link; old links stop working.

block_type_open

Downloads one block type's sources into the session workspace and starts installing its dependencies. app_pull already does this for every block type of an app, so it is rarely needed.

block_type_check

Checks one block type: lint, typecheck and a test bundle. It is much faster than a full push while the assistant works on a single block.

How app_push works

app_push takes everything in the pulled app tree and makes the app match it. It works through these steps in order and stops at the first one that fails, with nothing applied:

  1. 1Check the code: typecheck and lint the sources of every block type and shared module.
  2. 2Compile app.ts into the app's pages, blocks and settings.
  3. 3Read the current app from Turbofy and merge three versions: what was pulled, what changed in the tree, and what changed in Turbofy since the pull.
  4. 4Check the npm packages the blocks import and record the installed version of each one.
  5. 5Bundle every changed block type and shared module. Unchanged ones are skipped.
  6. 6Plan the changes to pages, blocks, block types, the schema, translations and the documents in docs/.
  7. 7Apply them, only when dryRun is false: schema first, then the app itself, translations, newly created blocks, shared modules and documents. Finally the session tree is refreshed to the new state.

Dry run first

By default app_push is a dry run: it runs every check and bundles the blocks, but uploads and changes nothing. Its result shows the typecheck and lint output, the merged changes, the planned operations, any block that failed to bundle, and the schema and document changes. The assistant reviews it and then pushes again with dryRun: false.

When a push is refused

  • Typecheck, lint or a package import fails. The result shows the errors.
  • A conflict: the same page, block or block type changed both in the tree and in Turbofy since the last pull. The result lists them. Pull again (force: true discards the tree's edits), or bring the tree in line with the other change and push again.
  • The app has no page at /, or that page has no blocks.
  • A new block type is placed on a page but has no React source yet.
  • The app has login pages, but the workspace doesn't have the App users product.

A push changes the app's preview. The public site only changes when you publish the app.

Long pushes run in the background

Pushing a big app can take minutes: hundreds of pages, many languages, dozens of blocks to bundle. One tool call can't wait that long, so every push runs as a background job on Turbofy's servers, and app_push waits for it for up to 20 seconds.

  • If the push finishes within 20 seconds, app_push returns the result directly. For most apps nothing looks different.
  • If it takes longer, app_push answers with status: running instead. The answer includes the current step (phase), how many steps are done (completedPhases) and the time so far (elapsedSeconds).
  • The push keeps running. The assistant calls app_push_status with the same orgId, workspaceId and appId. Each call waits up to 20 seconds again and returns either the final result or the running status, so the assistant calls it until the result arrives.
  • A push can run for up to 15 minutes.
app_push: still running
{
  "status": "running",
  "dryRun": false,
  "phase": "publish_blocks",
  "completedPhases": 9,
  "elapsedSeconds": 41,
  "next": "The push is still running in the background. Call app_push_status ..."
}

Calling app_push again

  • While your push runs, calling app_push again doesn't start a second one. It waits for the running push, just like app_push_status.
  • Once the push is done, calling app_push again returns that finished result, as long as the app's files haven't changed since. After an edit, it starts a new push.
  • A dry run and a real push of the same app never run at the same time. While one runs, the other is refused with a request to wait for the first.
  • If someone else is pushing the same app, your push is refused with a request to try again in a minute.

If a push stops

If the background job stops unexpectedly, app_push_status says so and names the step it stopped in. Run app_push again: blocks that were already uploaded are reused, so the second run is faster. A finished result stays available for 24 hours.

Editing while a push runs

A push reads the app's files at several points. If they changed in between, part of one version and part of another could go live. So Turbofy keeps edits and pushes of the same app apart, for everyone working on it:

  • While a push runs, fs_write, fs_edit, fs_exec, app_pull and block_type_open refuse to change that app and ask to wait with app_push_status. fs_read, fs_list and fs_search keep working.
  • While an edit runs, a push waits for it, for up to 20 seconds. If the edit takes longer, the push is refused with a request to try again shortly.
  • A background command (fs_exec with async: true), such as a long npm install, holds the app until it ends. Checking it with fs_task_status releases the app as soon as the command is done; otherwise the app is released after 15 minutes at the latest.
  • fs_exec in the workspace root can reach every app, so it holds every app you pulled in that workspace. Run commands in apps/<appId> to hold only that app.

The lock keeps a push from reading half-finished files. It does not give each person their own copy: everyone who pushes an app changes the same preview, so changes from several people go live together when the app is published.

Flows

flow_pull

Pulls every flow of the workspace into flows/<flowId>/flow.ts, and the cloud functions they use into flows/functions/<name>/.

flow_init

Creates an empty flow with the given name and pulls all flows, so the new flow.ts is ready to edit.

flow_push

Compiles one edited flow.ts, along with the cloud functions it references, and applies it. Before anything changes it checks branches and loops, cycles, cloud functions, triggers from other flows, secrets and AI models, and whether the flow changed in Turbofy since the pull. It defaults to a dry run.

flow_delete

Deletes a flow and refreshes the flows in the session workspace. It requires confirm: true.

On this page