Bloom

Edit existing files by exact text replacement: files: [{ path, edits: [{ old, new, replaceAll?, startLine?, endLine? }] }]. Each old must be copied from the file and match exactly once (line-ending, trailing-whitespace and curly-quote differences still match and are reported in matchedWith). Use read_files find to locate the text first. Pass intent (one sentence) on each entry: if an old text does not match, Bloom asks a merge model to apply the change from your intent, checks the result, and returns the diff with appliedVia: intent_fallback. Re-read the diff. When it cannot, the original error carries errorDetail.fallback.outcome. Accepts canonical bloom:frame/pages/<Page>/<Frame>.tsx and bloom:devbox/<checkout-path> paths. All files are resolved before any is written: a missing (EDIT_TARGET_NOT_FOUND, with nearest lines; newTextAt means it was probably already applied), ambiguous (EDIT_TARGET_AMBIGUOUS) or overlapping edit writes nothing. The edit applies against the text the server read, so a person typing elsewhere in the file is kept; if they changed the text you replaced, the result is EDIT_CONFLICT with observedText (re-read and retry). EDIT_CONTENDED and FILE_BUSY carry retryAfterMs. Write-time failures (EDIT_CONFLICT, EDIT_CONTENDED, FILE_DELETED, EDIT_INVALID_RESULT) are per file. idempotencyKey makes a resend replay (replayed: true). Use write_files basis to replace a whole file. returnDiff adds a canonical path-scoped unified diff. Existing dependency pins are retained; packageVersions covers newly introduced unresolved dependencies. Returns post-edit contentHash, current rect, openCommentThreads and page identity. This operation preserves frame kind and does not promote components. Committed bloom:repo/ paths reject mutations. Verification is asynchronous: entries return typeStatus pending, and the envelope's verification reports checksInFlight plus frames[] with type errors, lint and perf findings and counts {type, lint, perf} equal to the canvas frame label. Runtime cost (perf) is measured by browse_frame commands, not by edits. Scope: canvas:write.

edit_files

Read Bloom authoring documentation requested by the user. Without name, returns an index of names/descriptions; with name, returns the selected documentation as markdown. This operation provides reference material and does not change account, project or canvas state.

skills

End a canvas activity after reviewing the results, or abandon it when stopping. Retries are idempotent while the record is retained. This works even if canvas write access was revoked after begin.

finish_canvas_work

Resolve a project, page, frame, comment thread, comment or notification ID to the app's shareable Bloom URL. Returns url, equivalent to Copy link. Links address the project's preview branch; deleted targets or targets existing only on another branch return errors. Scope: project:read.

get_link

Return the profile represented by this request's authenticated credentials. The opaque id is unique within Bloom and remains unchanged across token refresh, reconnection, scope upgrades and display-metadata changes. Display name and email identify the selected connection; workspace selection does not switch accounts. Scope: project:read.

get_profile

Read the account's authorized live or recent Bloom canvas tabs, ranked by last focus. Returns source-backed selection anchors, selected comment-thread IDs, and page IDs/names without source text or comment bodies. Useful for user requests about selected objects or the current canvas. A headless account with no open tab returns items: []. Scope: project:read.

get_user_selection

List branches, with the project they belong to on every row: { branches: [{ branchId, name, isMain, status, projectId, projectName, workspaceName?, devDeploymentId?, parentBranchId? }] }. `devDeploymentId` is the `deploymentId` `run_one_off` takes; `parentBranchId` is the branch frames are inherited from (copy-on-write). `projectId` is optional — omit it to span every project you can read. This is the one discovery call for picking a branch; there is no separate project-listing tool. Scope: project:read.

list_branches

Inventory active frames visible on one page/branch. Rows include name, kind, componentName, render status/error, board rect/renderSize/order, contentHash, import relationships, originating comment thread, originKind, own/parent/unprojected provenance, lastEdit and openCommentThreads. Default sorting is newest edit first; layout sorting follows z-order. Deleted frames are absent. There is no separate server-side hidden/collapsed frame state. Scope: project:read.

list_canvas_frames

List pages in the branch's project, including subpages via parentCanvasPageId, with active frameCount and lastChangedAt for changes by any actor. Returns page identity and distinguishes empty pages from populated ones. Existing frame-addressed operations resolve their page automatically; ambiguous page errors enumerate candidates. Scope: project:read.

list_canvas_pages

List recent semantic canvas changes with actor, scope, targets, timestamps, and exact/inferred grouping evidence. Each item names its page (`canvasPageName`) and its frame targets by `name`, `kind` and `state` (`active`, or `gone` when the frame no longer resolves). A frame delete, move or create arrives as `operationKind: 'layout'` with a page-root target (`frameId: null`), because it is one opaque update to the page's layout doc; `detail: 'patch'` attaches a `layout` delta that names the frames added and removed. Defaults to this credential's OWN changes — the result echoes `actors` so an empty page-scoped read is legible as 'none of yours', not 'nothing happened' — and `actors: 'all'` (with `scope: { branchId }`; `projectId` is derived) is how to see the human's edits. Scope: project:read.

list_recent_canvas_changes

Read a branch's canvas comment threads and Bloom chat, newest message first. Filters support kind, frame/thread IDs, status, text query, involving "me" and since (new since your last read). Rows include threadId, messageId, author/body; comments include status/page/target, while chat includes role and agent editId. complete, matched and returned counts distinguish complete results from bounded prefixes. Runtime evidence is descriptor-only with captureKey and source/payload hashes; placement uses path/spot/routePath. Scope: project:read.

list_threads

Inspect a Bloom canvas frame or interact with its private browser. Without commands/time, returns the current shared capture's status and, when ready, a one-hour image URL, dimensions and source contentHash. pending includes retryAfterMs; failed includes failure.code/message. render_content identifies defective frame code; infrastructure and timeout failures identify incomplete observations. One-shot capture has a 1500ms browser budget. retry requests another failed observation. With commands/time, clicks, typing and playhead state persist in a private session; screenshots return images. Source changes return stale with state reapplied/dropped and skip acting commands; browser restoration is reported. Command output distinguishes ran, failed and skipped operations. runtimeCost reports measured DOM, long-task and React rendering findings, or explicit measurement failures. The anchor command returns a rendered element/quote target; record enables mp4 recording. Live browsers close when the canvas activity finishes. The shared capture also returns runtimeCost for its source: over-budget findings earlier live calls recorded, or unavailable. Scope: project:read.

browse_frame

Reposition existing canvas frames to absolute coordinates in one layout update. Source, size and screenshots are unchanged. Each success returns x/y/width/height. Unknown frames return not_found and are not created. This operation does not resize frames. Scope: canvas:write.

move_frames

Move or rename canonical Canvas Frame or devbox files within one authority. Every source import is rewritten in the same fenced publication. Frame identity, source CRDT, placement, comments and historical snapshots remain stable. basis is the source contentHash returned by read_files. Committed bloom:repo paths reject mutations. Scope:canvas:write.

move_files

Read canonical TSX and full-file SHA-256 contentHash for canvas frames, or read-only files in the Bloom project sandbox. Canvas entries include stable JSX sourcePath locators (50 per page; continue with elementsCursor and the same query), truncatedElementsCount, kind, importedFrameIds, openCommentThreads, and page ID/name. Batches may span pages. Sandbox reads address the Bloom project, not the client's local repository. Direct sandbox mutation is unavailable through this operation. Canvas entries also carry the checks on exactly that source: typeStatus, typeCheck with lint, and runtimeCost, which is ran with over-budget rules, values and budgets, or unavailable when no browse_frame call recorded one. Each entry may take startLine/endLine (1-based, inclusive) or find (only the lines containing that text, as matches); every success reports totalLines for the whole file. A find or line-range read leaves out element locators (elementsOmitted; pass query to get them). The envelope's verification lists the batch's own frames; otherFilesWithErrors counts the rest of the branch's failing files. Arguments take the shape { files: [{ path }] }. Scope: project:read.

read_files

Read frontend hooks, stores or storage from an authorized private frame-browser session, live Bloom tab, or comment capture. Overview returns a bounded map; storageKey/valuePath and cursors select detailed values. Truncated strings include prefix and omittedCharacters. Results include payloadHash. Scope: project:read.

read_frame_state

Reply to a canvas comment thread or the branch Bloom chat. Chat replies start asynchronous Bloom agent runs; comment replies reopen resolved threads and return threadStatus. The author comes from the MCP client identity. Mentions may tag Bloom or frames. Replies do not replace captured runtime state. Scope: comments:write for comments; project:write for chat.

reply_thread

Request browser review of this connection, including additional projects, whole workspaces or OAuth scopes. Returns an approval URL; never grants access itself. Show the URL to the user. Approved project and workspace access applies to this OAuth connection immediately: retry after the user approves. Only newly requested OAuth scopes need the plugin or MCP host's reconnect/reauthenticate action (`reconnectRequired`); hosts supporting OAuth step-up may do this automatically. API-key connections return key-management instructions. Cancel leaves existing access unchanged.

request_access

Run temporary TypeScript against one exact Bloom deployment. Every mode requires live deployment:admin permission. Queries execute immediately. Mutation, read_action, and action calls require a personal approval unless the same Bloom user already allowed this exact deployment + mode. The preference follows the user across Bloom Agent and MCP clients; it is never shared with another workspace member.

run_one_off

Search canvas TSX or the Bloom project sandbox codebase. Canvas search spans all pages unless canvasPageId narrows it, follows branch inheritance, and repairs an empty index from canonical Yjs source once. Canvas hits include stable JSX sourcePath locators (50 per page; continue with elementsCursor and the same query), truncatedElementsCount, page identity, contentHash, import relationships and own/parent provenance. Geometry and edit history are not included. Codebase search uses the project sandbox. Arbitrary public repositories are outside this operation's scope. Scope: project:read.

code_search

Look at screenshots of real products before designing a frame. Describe in one query what the frame must show, and name a product or platform if one fits (e.g. 'issue list like Linear', 'mobile onboarding with a progress bar'). Returns the best-matching screenshots, best first. Use them for layout, hierarchy, density and type scale; never copy logos, brand assets or text. Returns { results: [{ imageUrl, mimeType, videoUrl?, preview? }] }, best first; the first screenshots are attached as images. Read-only; no project needed. Rate limited per caller.

design_inspiration_search

Submit user-requested feedback to Bloom engineering. Supports feedback categories including praise and reports deduplicated/rate-limited outcomes. Client identity and server version are attached automatically. No additional project scope is required.

send_feedback

Create a canvas comment thread when target is present, or post to the branch Bloom chat and start an asynchronous agent run when target is omitted. Chat results include agentRun.editId. Mentions may tag Bloom or frames; mentioning Bloom in a comment requests agent work. Rendered element/code-span targets must resolve or return MCP_COMMENT_TARGET_UNRESOLVED. Pin a comment about one thing to it: browse_frame, `anchor @eN`, then pass the printed target with state "browser"; a target without spot sits on the frame as a whole and returns a nextStep. Browser-backed targets preserve the selected element/quote and runtime context. Returns resolved anchor, captureKey and app link. Author identity comes from the MCP client. Scope: comments:write for comments; project:write for chat and supplied live context IDs.

create_thread

Update a canvas comment thread's target, captured runtime state, or open/resolved status. At least one of target, state or status is required. Moving a target retains replies; moving without state drops the old placement's runtime evidence. State may reference an authorized private browser session or live canvas context. Bloom chat threads have no placement/status and are rejected. Message text and deletion are outside this operation. Scope: comments:write; supplied live context IDs also require project:write.

update_thread

Read the authenticated principal, credential narrowing, accessible project count, serverVersion and toolCount. Unambiguous defaultContext includes project/branch/page IDs and their names, matching calls without explicit IDs. ambiguousAt identifies branch/page ambiguity. Version and toolCount provide evidence of stale client discovery caches.

whoami

Create or overwrite Bloom canvas frames from TSX, or write files in the live devbox checkout. Paths use bloom:frame/pages/<Page>/<Frame>.tsx or bloom:devbox/<checkout-path>. A missing frame requires basis:null. Frames become components when another frame imports them. The authored Frame kind is artboard. Device previews are metadata, not source files. React DOM, React Native, and Tailwind are supported. packageVersions pins otherwise unresolved npm dependencies. basis is the canonical source hash for conflict checking. Successful entries return contentHash, board rect, and openCommentThreads and the envelope identifies the page. Committed bloom:repo/ paths reject mutations. Verification is asynchronous: entries return typeStatus pending, and the envelope's verification reports checksInFlight plus frames[] with type errors, lint and perf findings and counts {type, lint, perf} equal to the canvas frame label. Runtime cost (perf) is measured by browse_frame commands, not by writes. Scope: canvas:write.

write_files