MCP build tools

These are the build and control tools exposed at https://robutler.ai/mcp once your coding agent is connected. Apps are built as widgets, so the tools are named widget_* (authoring) and workspace_* (driving apps you have open). For the discovery and platform tools (search, delegate, and so on) see the MCP tool catalog.

Every tool authorizes as the connected user and re-checks ownership in the underlying pipeline. Client-supplied ids are never trusted: you cannot publish a folder you do not own or invoke a command in a workspace you cannot access.

Each tool returns JSON. Errors come back as a text result flagged isError.

Two ids per app, and they are not interchangeable. An app has a widget id (widgetContentId — the row that mounts and renders) and a bundle folder id (folderId — where its files live). Mount and share with the widget id; read and write files with the folder id. widget_instantiate resolves an owned bundle folder to its widget for you, but the distinction is worth keeping straight.

Permissions. Every tool carries MCP annotations: read-only tools (widget_catalog, widget_download, widget_fn_logs, widget_scaffold, the workspace_* listing and log tools) run without a per-call confirmation in clients such as Claude; write tools create or update something you own; destructive tools (widget_put_files, which overwrites files, widget_publish, which replaces the live public version, and workspace_widgets_invoke, which runs whatever command an app declares) prompt before each call. See the MCP tool catalog.

Publishing is open to every owner. widget_publish and widget_snapshot are registered for every account; both re-check that you own the folder or working app before anything reaches the catalog. An unpublished app still runs, mounts, and can be shared privately.

The one-call authoring path: scaffolds the chosen template, lands it as an editable bundle folder you own, registers it as a private widget you can mount immediately, and mints a dev token.

Returns { folderId, widgetContentId, widgetType, name, template, fileCount, files, openUrl, devToken, hint }. Mount with widget_instantiate(refId=widgetContentId); edit with widget_put_files(folderId, …); openUrl opens the app full screen.

Returns the same starter bundle as a files map to write locally: widget.json, the entry HTML, app code, and (for collab-app) an AGENT.md, tests, and a server function. It does not write anything server-side — prefer create_widget unless you want to iterate locally first.

Returns { name, template, files, hint } where files is a path-to-contents map.

The edit step of the loop. Upserts text files into a bundle folder you own, writing the bytes inline so the sandbox serves them immediately. Creates parent subfolders as needed.

UTF-8 text only: widget.json, the entry HTML, JS / CSS modules, AGENT.md. Binary assets (images, fonts) go through the dev-token upload path, not this tool. Limits: at most 100 files per call, 32 MiB per file. Storage is automatic: small files live inline, larger ones go to content-addressed blob storage — edits patch a file of any size either way (a remixed app's multi-MB built boot.js included).

File edits are live in the bundle — reload the mounted instance (workspace_widgets_invoke builtin __reload) to see them, and bump any ?v= cache token on assets you changed. Changes to widget.json or the declared command surface are snapshotted onto the widget row and refresh on republish.

Returns { folderId, results: [{ path, action: 'created' | 'updated', id }], hint }.

Mounts an app on a workspace canvas and returns where to open it. Validates the ref before mounting: an id that does not resolve to content you can read is an error, and a bundle folder id is auto-resolved to its widget row (registering one for a folder you own) rather than mounting an inert file.

Returns { workspaceId, itemId, refId, mountKind, canvasUrl } (+ reused, and resolvedFrom when a folder id was resolved). Assert on mountKind: "widget" is a running sandboxed app, "document" is content opened by its handler. Then confirm the render — workspace_widgets_list shows the instance and workspace_widgets_logs reaches loadState: "ready"; a successful mount call alone proves nothing rendered.

Lists the apps available to this account — each with the refId to pass to widget_instantiate, whether it is collaborative, and the document mimes it opens (for create_document).

Returns { count, widgets: [{ widgetType, refId, title, collab, opensMimes }], hint }.

Creates an empty project document (an ADR-0022 project folder) stamped with the mime that decides which app opens it. The returned contentId mounts with widget_instantiate and names the document's collab room.

Returns { contentId, room, projectMime, openUrl, handler, hint }.

Clones an app you can use into your own private, editable copy — the same operation as the UI Remix button. No publish entitlement needed; nothing is published and the original is untouched. Works on any app you can access: published, or shared with you. If the app reached you as a shared document (you hold access to the document, not the app), pass that document's id as via — the server verifies the chain (you can read the document, the app is its opener, and the document's author is entitled to the app).

Returns { widgetContentId, folderId, displayName, canPublish, hint }. Mount the copy with widget_instantiate(refId=widgetContentId), edit it with widget_put_files(folderId, …). canPublish says whether this account can later widget_publish it. Some kinds are not remixable (passive and native external widgets, and live canvas items) and return an error. See Publishing and remix.

Publishing-enabled accounts. Publishes a folder bundle as a public app. In one transaction it mints (or reuses) a dedicated agent for the app, wires each declared tool as a custom function, stamps the app's command interface, and upserts the catalog and post rows. Idempotent per (author, folder): republishing updates in place — and a republish is also how manifest / command-surface changes reach the widget row.

Returns { postId, agentId, widgetContentId, publicMcpAppUrl }. The publicMcpAppUrl is the app's own outbound MCP App manifest (/api/widgets/<postId>/mcp).

Publishing-enabled accounts. Cuts an immutable, content-addressed version of a working app and, when listed, creates or repoints a marketplace post. Idempotent: an unchanged tree (same Merkle hash as the last version) is a no-op that just clears the dirty flag.

Returns { versionId, widgetContentId, treeFolderId, treeHash, postId, deduped }. See Publishing and remix.

Lists and reads the files of a bundle folder for local editing or debug. Walks the subtree and returns text inline (binary files are flagged, not inlined) up to a byte budget, so a bundle with multi-MB built assets never lands in the conversation whole.

Returns { folderId, count, bytes, files: [{ id, path, mime, binary, text, bytes }], omitted?, hint? }. A file past the budget is still listed, with text: null and omitted: true; call again with paths set to the ones you need, or a larger maxBytes.

Server-side debug: reads the recent custom-function invocations of an agent you own, with status, error code, and duration. Useful for diagnosing why a published tool is failing. A published app's functions run under the agent minted for it at publish time, which the publisher owns.

Returns { agentId, count, invocations: [{ functionName, sourceSkill, status, errorCode, durationMs, createdAt }] }.

Mints a short-lived, least-privilege widget-dev Bearer so a locally running app can reach the portal during development. This token is for the local dev server only and is rejected at /mcp.

Returns { token, portalUrl, agentId, expiresAt, scope }. Keep it on the dev machine and never commit it. See the security model.

These drive apps you already have open in a live browser tab, the same command surface the in-workspace agent uses. A command only lands while the app is open in a live tab: there is no durable offline queue and the RPC times out (up to 5 minutes). They also answer for a standalone /w/ share view — pass the shared contentId (or share-<contentId>) where a workspace id is expected.

Lists the surfaces you currently have open in a live tab, with the apps open in each — workspaces (kind: "workspace") and standalone /w/ share views (kind: "share"). The result names the instance and identity that answered, which matters when more than one Robutler deployment is connected. No arguments.

Returns { instance, user, open: [{ workspaceId, title, tabIds, openWidgetItemIds, kind }] }.

Lists the apps on a workspace and the commands each understands (its agent-control surface). Static, so it works without a live tab. Each entry is flagged live when it is open in one of your tabs and therefore invokable now.

Returns { workspaceId, hasLiveTab, widgets: [{ itemId, ..., live }] }. See Agent command interface.

Runs a command on an app open in your live tab.

Builtin command names every app answers:

Returns { tabId, result }.

Reads a deployed app instance's captured browser console logs plus load state (loading / ready / failed), including script errors, CSP blocks, and Permissions-Policy violations. Use it to debug why an app on the canvas is blank or broken. An item that is not a running app (content mounted as a file attachment) is refused outright with an explanation, rather than reporting loading forever. Routes to the live tab; requires the workspace open in a browser.

Returns { tabId, result }.