tldraw Topology MCP

A shared local tldraw topology service with a persistent HTTP daemon and a thin stdio MCP adapter.

Architecture

• daemon.mjs owns the authoritative tldraw document store, persistence, browser/static HTTP service, synchronization API, page-scoped topology projections, health endpoint, and topology mutations.

• server.mjs is a thin stdio MCP adapter. It exposes fourteen Page/topology/shape tools and forwards requests to the daemon over HTTP.

• tldraw Pages are first-class MCP scope boundaries. Normal reads and Page-targeted mutations operate on one explicit page_id.

• Geo nodes and Arrow edges retain the topology convenience tools, while a generic Shape layer exposes every built-in tldraw shape type through native records and props.

• No parallel style state is introduced: MCP edits the same native tldraw properties used by the browser UI.

• The MCP adapter does not own the daemon lifecycle. MCP clients can connect and disconnect without destroying the shared canvas state.

Related MCP server: Canvas AIGC

Install and build

npm install
npm run build

Run the long-lived daemon:

npm start

Run the stdio MCP adapter in an MCP host:

npm run mcp

MCP tools

Page discovery and reads

• page_list — list tldraw document pages with stable page IDs, names, order, and topology node/edge counts.

• topology_get(page_id) — read exactly one Page. Geo nodes and Arrow edges include their editable presentation properties so writes can be verified through the same read surface.

Generic Shape editing

The generic Shape layer keeps Page scoping and works on native tldraw records:

• shape_list(page_id, types?) — list compact summaries for shapes belonging to one Page, including shapes nested under Frames or Groups.

• shape_get(id) — return the complete native shape record plus owning pageId.

• shape_add(page_id, type, ...) — create a built-in shape using tldraw-compatible defaults plus an optional native props override. parent_id may target the same Page or a container shape on that Page.

• shape_update(id, ...) — patch base shape fields, metadata, native props, and rich-text content without changing the shape's type or Page ownership.

• shape_delete(id) — delete a shape, its container descendants, and bindings/arrows that would otherwise reference deleted shapes.

Supported built-in types:

arrow bookmark draw embed frame geo group highlight image line note text video

For shapes with native richText (geo, arrow, text, note), generic add/update also accepts text, bold, italic, bulletList, and highlight. Low-level type-specific properties remain available through the native props object and are validated by the tldraw store schema.

The topology tools below remain as convenient higher-level operations for Geo nodes and bound Arrow edges.

Geo node editing

node_add(page_id, ...) and node_update(id, ...) support:

• geometry: x, y, w, h, rotation, opacity, scale, flipX, flipY

• Geo shape: geo

• outline / fill: color, fill, dash, size

• label: label, labelColor, font, align, verticalAlign

• whole-label rich text: bold, italic, bulletList, highlight

• link: url

Supported Geo values:

cloud rectangle ellipse triangle diamond pentagon hexagon octagon star
rhombus rhombus-2 oval trapezoid arrow-right arrow-left arrow-up arrow-down
x-box check-box heart

Arrow edge editing

edge_add(from, to, ...) and edge_update(id, ...) support:

• arrow form: kind, bend, elbowMidPoint

• arrowheads: arrowheadStart, arrowheadEnd

• line / head appearance: color, fill, dash, size, opacity, scale, rotation

• label: label, labelColor, font, labelPosition

• whole-label rich text: bold, italic, bulletList, highlight

Arrow kinds are arc and elbow.

Arrowhead values:

arrow triangle square dot pipe diamond inverted bar none

Shared style values

Colors:

black grey light-violet violet blue light-blue yellow orange green
light-green light-red red white

Dash:

draw solid dashed dotted none

Fill:

none semi solid pattern fill lined-fill

Size:

s m l xl

Font:

draw sans serif mono

Horizontal alignment:

start middle end

Vertical alignment:

start middle end

Deletion and clearing

• node_delete(id) — delete a topology node and connected topology arrows.

• edge_delete(id) — delete one topology arrow and its bindings.

• topology_clear(page_id) — clear topology Geo/Arrow content from exactly one Page while keeping the Page itself, non-topology containers, and every other Page unchanged.

Page identity is authoritative by page_id; page names are display metadata only. Shape ownership is resolved through the full tldraw parent ancestry, so shapes nested under frames or groups still belong to the correct page.

There is intentionally no implicit current-browser-page fallback, no whole-document topology read/clear compatibility mode, and no continuous browser View bridge.

Editing semantics

All update fields are optional. An update changes only the supplied properties.

The MCP does not maintain a parallel style model. It writes the same native tldraw Geo / Arrow properties used by the browser UI. Whole-label rich-text operations modify the shape's native richText; they do not create separate bold/italic/list/highlight flags in persisted data.

topology_get summarizes whole-label rich-text state as true, false, or mixed where applicable.

Daemon configuration

The default bind is loopback. External interface exposure belongs to deployment configuration and is not hard-coded in the application.

MCP adapter configuration

HTTP endpoints

• GET /healthz — daemon health and current revision.

• GET /api/state — complete authoritative tldraw document snapshot for synchronization/recovery.

• GET /api/changes?since=<revision> — incremental browser synchronization.

• POST /api/changes — browser document changes.

• POST /api/topology/command — semantic page/topology command endpoint used by the MCP adapter.

The complete /api/state document snapshot remains an internal synchronization/recovery surface. It is not the normal MCP topology read surface.

Persistence and concurrency

The daemon is the single writer for the authoritative local document. Runtime document state is stored in data/store.json by default and is intentionally excluded from source control. Writes use a temporary file followed by rename. Semantic mutations are serialized so multiple MCP adapters can safely share one daemon.

Service supervision

Operating-system service registration, startup policy, and external supervision are intentionally outside this repository. The daemon is designed to be hosted by a generic supervisor without coupling that supervisor to the MCP adapter.

Version

Current release: v0.1.0.

Upstream

The browser UI is built with the tldraw SDK. See the upstream tldraw project for its licensing and trademark terms.