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.

Returns a starter bundle to write locally: widget.json, index.html, and an example tool (tools/hello.js). It does not write anything server-side.

Returns { name, 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 a later widget_publish / widget_snapshot sees the change. 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, 2 MB per file. The underlying writer also supports in-place edits (find / replace) for patching a large file without resending it.

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

Publishes a folder bundle as an 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.

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

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.

Forks a published app into your own copy: clones the bundle subtree onto your account, replays publish (minting a fresh dedicated agent), and stamps the remix lineage. Bumps the source post's remix count.

Returns { newPostId, newAgentId, newWidgetContentId, ordinal }. Some kinds are not remixable (passive / native / system widgets, and live canvas items) and return an error.

Mounts an app on a workspace canvas and returns where to open it.

Returns { workspaceId, itemId, canvasUrl }.

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).

Returns { folderId, count, files: [{ id, path, mime, binary, text }] }.

Server-side debug: reads an agent's recent custom-function invocations with status, error code, and duration. Useful for diagnosing why a published tool is failing.

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). Richer orchestration (durable queues, multi-tab) is on the way; see What's ready.

Lists the workspaces you currently have open in a live tab, with the apps open in each. These are the only places a command can be dispatched right now. No arguments.

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

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. Requires the app to be open in a browser tab.

Builtin command names:

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. Routes to the live tab; requires the workspace open in a browser.

Returns { tabId, result }.