tldraw-m9810223

A Claude Code plugin: 26-tool MCP server for editing tldraw .tldr files via JSON manipulation (headless, no browser needed), plus a tldraw-screenshot skill that renders a .tldr to PNG via tldraw.com so Claude can SEE the diagram.

Status

Working skeleton. Schema validation is wired (@tldraw/tlschema validators run before every write), fractional indexing uses @tldraw/utils, file writes are guarded by proper-lockfile. Output verified end-to-end against the real tldraw runtime via Store.loadStoreSnapshot() in the contract test layer.

Quick Start

Requires Node ≥ 20.

1. Install as a Claude Code plugin (one command registers the marketplace, the second installs the bundled MCP server + skill):

claude plugin marketplace add m9810223/tldraw-m9810223
claude plugin install tldraw-m9810223@tldraw-m9810223

Restart Claude Code. /mcp lists tldraw-m9810223 (26 tools); /plugin lists tldraw-m9810223; the tldraw-screenshot skill is available too.

If you'd rather wire just the MCP server (no skill), see Install / Update / Remove below.

2. Try the demo prompt in Claude Code:

Draw the Shai-Hulud supply-chain attack flow described in this article with MCP `tldraw-m9810223`, save to `./demo.tldr`:
https://semgrep.dev/blog/2026/malicious-dependency-in-pytorch-lightning-used-for-ai-training/

- Match the actors and how data/control flows between them
- Polish the result at the end

3. View the result — drop ./demo.tldr onto tldraw.com, or use the tldraw VS Code extension for live preview.

Source file: docs/demo.tldr

Tools

File / page lifecycle

Shapes

Layout / text fitting

Discovery & escape hatch

Checkpoints (safety)

The token-saving design: tools take primitive args, return ids or ok. The full JSON only enters context when you call get_shape deliberately.

Install / Update / Remove

jq only needed for exec_jq (brew install jq / apt-get install jq).

As a plugin (recommended — bundles MCP server + skill)

# Install (user scope by default)
claude plugin marketplace add m9810223/tldraw-m9810223
claude plugin install tldraw-m9810223@tldraw-m9810223

# Update
claude plugin update tldraw-m9810223

# Remove
claude plugin uninstall tldraw-m9810223
claude plugin marketplace remove tldraw-m9810223
rm -rf ~/.claude/plugins/cache/tldraw-m9810223   # optional — also drop the cached clone

# Verify clean (both should print nothing)
claude plugin list | grep tldraw
claude mcp list | grep -i tldraw

MCP server only (no skill)

Use this if you want the editing tools but not the screenshot skill, or you're on a Claude client that doesn't speak Code's plugin system.

# Install — user scope: every project on this machine
claude mcp remove tldraw-m9810223 -s user 2>/dev/null; rm -rf ~/.npm/_npx
claude mcp add -s user tldraw-m9810223 -- npx -y github:m9810223/tldraw-m9810223

# Install — local scope (default): only the current project directory
claude mcp remove tldraw-m9810223 2>/dev/null; rm -rf ~/.npm/_npx
claude mcp add tldraw-m9810223 -- npx -y github:m9810223/tldraw-m9810223

The first arg (tldraw-m9810223) is the local server name — pick whatever you like, then refer to it the same way in subsequent commands. Restart Claude Code, then /mcp lists it with 26 tools.

Wire up to other MCP clients

Same JSON shape, different config file location:

Bootstrapping a .tldr file

Use the create_empty_file tool, or save an empty canvas from tldraw.com and point tools at the absolute path.

create_empty_file({ file: "/tmp/demo.tldr" })

Viewing / editing the output

The VS Code extension is the smoothest dev loop — keep code path/to/file.tldr open in a tab while the MCP edits it; the editor refreshes on disk change.

The tldraw-screenshot skill is the smoothest agent loop — Claude edits via the MCP, renders via the skill, looks at the PNG, edits again. See skills/tldraw-screenshot/SKILL.md for the workflow and gotchas. Requires playwright-cli on PATH.

Design comparison vs official tldraw-mcp-app

The Cloudflare-hosted official MCP exposes only search + exec (run any JS in a live tldraw Editor). This skeleton goes the opposite way — typed JSON edits over .tldr files — and borrows the discovery pattern (search_api) and escape hatch (exec_jq) so an LLM can fall through when typed tools don't cover an operation.

Known gaps

• index (z-order) only supports appending above the current max — no insert-between

• No image / video / asset support

• Schema version pinning is informational only — opening a file in a newer tldraw may trigger migrations

• search_api curated list is hand-maintained alongside the live @tldraw/tlschema reflection

Architecture

.claude-plugin/
  plugin.json       Plugin metadata + pointers to mcpServers + skills
  marketplace.json  Marketplace manifest so `claude plugin install` can find this
.mcp.json           Plugin-scoped MCP server declaration (npx-from-github)

skills/
  tldraw-screenshot/
    SKILL.md        Workflow for rendering .tldr → PNG via playwright-cli + tldraw.com

src/
  index.ts       MCP server entry, tool registration (stdio transport)
  tools.ts       Tool handlers + zod input schemas
  shapes.ts      tldraw record factories (geo/text/arrow/group/binding)
  store.ts       Load/save .tldr + withFileLock; helpers (id gen, indexing, find, page-of-shape, bindings-for-shape)
  template.ts    Empty .tldr generator using @tldraw/tlschema serialize()
  validate.ts    validateShape / validateBinding using createShapeValidator + createBindingValidator
  checkpoint.ts  Timestamped backups under .tldraw-mcp-checkpoints/
  jq.ts          Shell-out to jq for the exec_jq escape hatch
  text-metrics.ts Text size heuristics for autoFit + label measurement
  graph-layout.ts Dagre wrapper for graph_layout
  arrow-bending.ts Detect parallel-edge overlap + assign symmetric bend values

test/
  unit/          store + validate + text-metrics + arrow-bending (34 tests)
  integration/   tools end-to-end on tmp .tldr (39 tests)
  contract/      loadStoreSnapshot against real @tldraw/store (4 tests)
  boundary/      N-1 / N / N+1 limits + concurrent writes (89 tests)

Pure JSON manipulation — no @tldraw/store, no DOM, no React.