Bloom

Replace a comment-thread message authored by this integration; mentions tag frames or people. Other authors' messages return MCP_COMMENT_NOT_OWNED. Bloom chat history cannot be edited. If a person wrote in the thread since this session last read it, nothing is written and the call fails with COMMENT_THREAD_HAS_UNREAD; its `unread` holds those messages, now read for this session: take them into account, then call again. Scope: comments:write.

edit_message

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:file/<Page>/<Frame>.tsx frames, bloom:file/ text files (.css, .json, …) and bloom:devbox/<checkout-path> paths. An edit that would leave a .json file unparseable is refused (MCP_FILE_UPLOAD_JSON_INVALID) and writes nothing. 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 of a frame or devbox edit replay (replayed: true); a text file's edit has no receipt, so after a lost reply read it again before resending (an exact edit that already landed answers EDIT_TARGET_NOT_FOUND with newTextAt). 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 your work when it is done (completed) or when you stop (abandoned). History shows it finished, and later writes naming it are refused. Repeating it is harmless.

finish_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, import relationships, originating comment thread, originKind, own/parent/unprojected provenance, theme (layout, picked or automatic, and mode), lastEdit and openCommentThreads; the envelope names the project default theme (defaultThemeLayout). 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. Deployments switch the server-rendered shared capture off by default: it then answers failed with failure.code server_frame_render_off, retry changes nothing, and commands "screenshot" returns a live image. 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. The state this browser is left in (tab, open panel, tour stop, playhead) is what a thread captures when create_thread or update_thread passes state "browser", so drive the frame to the state that shows your point before you pin a comment; readers open that comment straight into this state, so its text never explains how to get there. 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 any bloom:file/ entry or devbox file within one authority: a frame, a page (its folder, e.g. bloom:file/Brand renames the page, or moves it into another page's or a plain folder), or a plain file or folder (an uploaded photo, Design/theme.css). Every source import is rewritten in the same fenced publication. Frame identity, source CRDT, placement, comments and history remain stable. basis is the source contentHash returned by read_files, required for a frame or devbox file and omitted for a page or plain entry. Page structure changes only on the preview Branch. Committed bloom:repo paths reject mutations. Scope:canvas:write.

move_files

Add or remove your emoji reaction on a V2 Thread Message. Adding returns alreadyReacted: everyone who already reacted with the same emoji (who and when), read in the same transaction as your add, so you can see work someone already took before duplicating it. status is added, already_reacted (yours existed; nothing written) or removed. One reaction per reactor per emoji; you and the person you act for are separate reactors. Bloom attaches no meaning to any emoji. Scope: comments:write.

react_message

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, theme (the layout the frame renders inside, picked or automatic, and its mode), and page ID/name. A bloom:file/ path that is no frame reads a text file (a stylesheet, JSON). 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. To read any file as it was at a version, prefix its path with the version: bloom:file@<snapshotVersionId>/<path> (the snapshotVersionId a message's acceptedCanvasVersionId or submittedCanvasContext names). The answer is that version's file even after a rename, a move or a reuse of the path; a folder path returns its children as JSON with nextCursor (pass it back as cursor); a blob returns its name, type, size and a read URL. Version paths are read-only: every mutating tool rejects them with PROJECT_VFS_VERSION_READ_ONLY. 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, frames or people. Replies do not replace captured runtime state: to show a new state, move the thread with update_thread and state "browser". Before asking a decision, leave the frame in the state that shows the options and pin the question there; a comment on the frame as a whole is for frame-wide summaries only. Show, don't describe: drive the frame to a tour stop, a tab, an open panel or the options side by side (reuse an existing demo frame rather than writing prose). Opening the comment shows the reader the frame in the state it captured, so the body never says how to reach it (no "press 8, then Structure"); name clicks only when the result has no `capture` or its status is "unavailable" or "failed". One thread per decision: if one already asks it, reply there; resolve a duplicate with a line pointing to the live thread. If a person wrote in the thread since this session last read it, nothing is written and the call fails with COMMENT_THREAD_HAS_UNREAD; its `unread` holds those messages, now read for this session: take them into account, then call again. 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. The search spans all pages unless canvasPageId narrows it, follows branch inheritance, and repairs an empty index from canonical Yjs source once. 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. Project source code and public repositories are outside this operation's scope; search them with your own tools. 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.workSessionId. Mentions may tag Bloom, frames or people; 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: target { path, find: "<text the element shows>" } pins it to that element in one call (or browse_frame `anchor @eN` and pass the printed target with state "browser"); a target without spot or find sits on the frame as a whole and returns a nextStep. A decision is a pinned question: pass `questions` with the target, and the person answers it in the thread with one click. Before asking a decision, leave the frame in the state that shows the options and pin the question there; a comment on the frame as a whole is for frame-wide summaries only. Show, don't describe: drive the frame to a tour stop, a tab, an open panel or the options side by side (reuse an existing demo frame rather than writing prose). Opening the comment shows the reader the frame in the state it captured, so the body never says how to reach it (no "press 8, then Structure"); name clicks only when the result has no `capture` or its status is "unavailable" or "failed". One thread per decision: if one already asks it, reply there; resolve a duplicate with a line pointing to the live thread. 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. Use it to move a frame-wide thread onto the element and state it is about, and to resolve a duplicate once it points to the live thread. 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, text files (stylesheets, JSON, Markdown) in Bloom Files, or files in the live devbox checkout. Paths use bloom:file/<Page>/<Frame>.tsx, bloom:file/<folder>/<name>, or bloom:devbox/<checkout-path>. A frame's stylesheets come from its theme: set theme { layout, mode } on its entry (content may be omitted to change only size or theme), and the project default theme on bloom:file/; never import a .css file into a frame. A size- or theme-only entry answers with the frame's rect and theme, not a contentHash. Binary files go through begin_file_upload. A missing frame or file 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 on the written frames; an entry on a canvas path (bloom:file/<Page>/) with only packageVersions sets that canvas's versions for every frame it draws. 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