read
Inspect project canvases, films, and design systems by path, element ID, or filters; return blueprint, summary, or skeleton fences for editing and analysis.
Instructions
Read the project's documents, each answered as the fence you would send back through edit: a canvas as bl with file(path) first and its rows (ids bound), a film as bm, a design system as ```ds. A canvas answer lists the films that name it above its fence (films: Motion/Launch.bm). Pass paths (canvas paths such as "Projects/Dashboard", "Motion/Launch.bm", "Styles/default.ds"), ids (element ids or #refs, with their canvas in paths) and/or the filters (query, textContent, type, fillColor, componentName) to find elements across canvases. format is "blueprint" (default), "summary" (compact metadata) or "skeleton" (summary plus the tokenRefs, no geometry), the fence the carrier. (External MCP clients: call init first for usage docs. Hosted-CLI and sub-agents have docs pre-loaded.)
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "read"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | Element IDs (or #refs) to read, the same as listing them in `scope`. `elementIds` is accepted as an alias. | |
| disk | No | true answers from the saved .bl files on a background isolate: it never loads, opens or writes a canvas, whatever its size, so a heavy or closed canvas is safe to read. Rows come as stored, one header per canvas names its row count and bytes, and a canvas open in the app says a change not saved yet is not here. Takes paths (omit to search every canvas), ids, the filters, depth, limit (rows, default 200) and the disk-only pattern, ancestors, subtree, consumersOf. | |
| full | No | READ-ONLY. When true (with format="blueprint"), return the COMPLETE vector geometry even for a large path. Default false: a vector whose blueprint would blow the per-readback token budget is summarized to node count + bounds + this flag as its continuation door (a one-line note names what was elided). Set true to inspect the full node/edge graph of one big vector; scope it to that element to keep the readback bounded. | |
| type | No | Filter by element type. One of: vector, line, circle, rectangle, text, parent. | |
| depth | No | Subtree depth per match, in every format. 0 = matched element only, 1 = + immediate children, etc. Omitted: unlimited for "blueprint", the matched elements only for "summary" and "skeleton" (each record names its parentId). | |
| limit | No | Max top-level matches across all canvases. Defaults to 50. It applies with explicit element IDs too. | |
| paths | No | The documents to read: canvas paths (e.g. "Projects/Dashboard", .bl optional), films ("Motion/Launch.bm") and design systems ("Styles/default.ds"). Omit with a filter to search every canvas. | |
| query | No | Case-insensitive substring match on element name AND canvas path. Element matches answer as fences; canvas matches ride the `canvases:` line. Canvas matching only runs when no `paths` are given. With a design system in `paths`, its statements whose token name contains it. | |
| format | No | Output shape per canvas, inside its fence. "blueprint" (default) is the rows with their ids, what edit takes back. "summary" is compact metadata (id, name, type, parentId, parentName, childCount, text snippet). "skeleton" adds the design-system tokenRefs and omits geometry. | |
| pattern | No | With disk: a regular expression over each stored row, for what the filters leave unnamed (a font size, a token, an override). | |
| project | No | Optional: run THIS call against a project other than the session's bound one: a name or key from list_projects (or an unambiguous name/handle substring), or the absolute path of a project folder (one holding .bl files, or an empty one), which opens in the background and is added to list_projects. Unknown/ambiguous is refused with candidates. | |
| subtree | No | With disk: each matched row carries its descendants, bounded by depth. | |
| ancestors | No | With disk: each matched row carries its parent chain, board first. | |
| fillColor | No | Find elements with a fill matching this hex color (e.g. "#FFCC00" for yellow). Perceptual color matching, close shades are included. | |
| sessionId | No | Your session id from init: #refs resolve per session. | |
| consumersOf | No | With disk: the id of a component master. Answers each canvas holding a copy of it: the copies, and the canvas row count to weigh a master edit. Set a master's id, not a variant child, for the copies of that master. | |
| textContent | No | Case-insensitive substring match on text element content. | |
| componentName | No | Find instances of a component whose master name contains this substring (case-insensitive). | |
| expandInstances | No | READ-ONLY. When true (with format="blueprint"), a component instance is not collapsed to its compact inst() line: its derived children are shown as full lines with their REAL ids so you can inspect and target them (via read/execute_commands). Those children are managed by the master and are read-only; a change to them is a change to override(...) on the instance. Default false (the compact inst() form). Bounded by `depth` like any subtree. |