pi-tldraw 0.1.0

package/mcp-app/server.json

@@ -0,0 +1,21 @@
+{
+	"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+	"name": "io.github.tldraw/tldraw",
+	"description": "Draw and visually collaborate with your agents on tldraw's canvas.",
+	"repository": {
+		"url": "https://github.com/tldraw/tldraw",
+		"source": "github",
+		"subfolder": "apps/mcp-app"
+	},
+	"version": "0.1.0",
+	"remotes": [
+		{
+			"type": "streamable-http",
+			"url": "https://tldraw-mcp-app.tldraw.workers.dev/mcp"
+		},
+		{
+			"type": "sse",
+			"url": "https://tldraw-mcp-app.tldraw.workers.dev/sse"
+		}
+	]
+}

package/mcp-app/src/logger.ts

@@ -0,0 +1,45 @@
+/**
+ * Structured logger for the tldraw MCP Durable Object.
+ *
+ * Outputs JSON lines to console.error so that
+ * Cloudflare Workers Observability can capture and query them.
+ */
+
+export class Logger {
+	constructor(
+		private prefix: string,
+		private enabled: boolean
+	) {}
+
+	info(message: string, data?: Record<string, unknown>) {
+		if (!this.enabled) return
+		console.error(
+			JSON.stringify({ level: 'info', prefix: this.prefix, message, ...data, ts: Date.now() })
+		)
+	}
+
+	error(message: string, data?: Record<string, unknown>) {
+		if (!this.enabled) return
+		console.error(
+			JSON.stringify({ level: 'error', prefix: this.prefix, message, ...data, ts: Date.now() })
+		)
+	}
+
+	debug(message: string, data?: Record<string, unknown>) {
+		if (!this.enabled) return
+		console.error(
+			JSON.stringify({ level: 'debug', prefix: this.prefix, message, ...data, ts: Date.now() })
+		)
+	}
+
+	child(prefix: string): Logger {
+		return new Logger(`${this.prefix}:${prefix}`, this.enabled)
+	}
+
+	/** Returns a log function compatible with RegisterToolsOptions.log */
+	toLogFn(): (...args: unknown[]) => void {
+		return (...args: unknown[]) => {
+			this.info(args.map(String).join(' '))
+		}
+	}
+}

package/mcp-app/src/register-tools.ts

@@ -0,0 +1,368 @@
+import { registerAppResource, RESOURCE_MIME_TYPE } from '@modelcontextprotocol/ext-apps/server'
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import type { CallToolResult, ReadResourceResult } from '@modelcontextprotocol/sdk/types.js'
+import { z } from 'zod'
+import { CANVAS_RESOURCE_URI } from './shared/types'
+import type { RegisterToolsOptions, ServerDeps } from './shared/types'
+import { errorResponse, parseTlShapes } from './shared/utils'
+import { registerExecTool } from './tools/exec'
+import { registerSearchTool } from './tools/search'
+
+/**
+ * Shared tool/resource registration logic for the MCP worker runtime.
+ *
+ * Tools:
+ * - search: Query the Editor API spec (server-side)
+ * - exec: Execute JS against the live editor in the widget
+ * - read_checkpoint: Read checkpoint data (app-only)
+ * - save_checkpoint: Save checkpoint data (app-only)
+ * - tldraw-canvas: Interactive canvas widget resource
+ */
+
+// --- Helpers ---
+
+function injectBootstrapData(html: string, bootstrap: Record<string, unknown>): string {
+	const toBase64 =
+		typeof Buffer !== 'undefined' ? (s: string) => Buffer.from(s).toString('base64') : btoa
+	const encoded = toBase64(JSON.stringify(bootstrap))
+	const bootstrapScript = `<script>window.__TLDRAW_BOOTSTRAP__=JSON.parse(atob("${encoded}"))</script>`
+	const lastIdx = html.lastIndexOf('</head>')
+	if (lastIdx === -1) return html
+	return html.slice(0, lastIdx) + bootstrapScript + html.slice(lastIdx)
+}
+
+function parseArrayJson(json: string, fieldName: string): unknown[] {
+	const parsed = JSON.parse(json)
+	if (!Array.isArray(parsed)) {
+		throw new Error(
+			`${fieldName} must be a JSON array string. Build an array first, then pass JSON.stringify(array).`
+		)
+	}
+	return parsed
+}
+
+async function getWidgetDomain(
+	hostName: string | undefined,
+	isDev: boolean,
+	workerOrigin?: string
+): Promise<string | undefined> {
+	if (isDev) return undefined
+	if (hostName === 'chatgpt') return 'https://tldraw.com'
+	if (hostName === 'claude' && workerOrigin) {
+		const mcpUrl = new URL('/mcp', workerOrigin).toString()
+		const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(mcpUrl))
+		const hash = Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0'))
+			.join('')
+			.slice(0, 32)
+		return `${hash}.claudemcpcontent.com`
+	}
+	return undefined
+}
+
+// --- Registration ---
+
+export function registerTools(
+	server: McpServer,
+	deps: ServerDeps,
+	opts: RegisterToolsOptions
+): void {
+	const log = opts.log ?? ((...args: unknown[]) => console.error(...args))
+	const analytics = opts.analytics
+
+	// --- search (server-side spec query) ---
+
+	registerSearchTool(server, {
+		analytics,
+		log,
+		loader: opts.searchWorkerLoader,
+		loadSpec: deps.loadEditorApiSpec,
+	})
+
+	// --- exec (client-side code execution) ---
+
+	let currentExecCanvasId: string | null = null
+
+	registerExecTool(server, {
+		analytics,
+		log,
+		pendingRequests: opts.pendingRequests,
+		setCurrentExecCanvasId: (id) => {
+			currentExecCanvasId = id
+		},
+	})
+
+	// --- _exec_callback (app-only: widget resolves pending exec via callServerTool) ---
+
+	const execCallbackSchema = z.object({
+		channel: z.string(),
+		result: z
+			.object({
+				success: z.boolean(),
+				result: z.unknown().optional(),
+				error: z.string().optional(),
+			})
+			.optional(),
+		error: z.string().optional(),
+	})
+
+	server.registerTool(
+		'_exec_callback',
+		{
+			title: 'Exec Callback',
+			description: 'App-only: widget calls this to resolve a pending exec request.',
+			inputSchema: execCallbackSchema,
+			annotations: {
+				readOnlyHint: false,
+				destructiveHint: false,
+				idempotentHint: false,
+				openWorldHint: false,
+			},
+			_meta: { ui: { visibility: ['app'] } },
+		},
+		async ({
+			channel,
+			result,
+			error,
+		}: z.infer<typeof execCallbackSchema>): Promise<CallToolResult> => {
+			const handled = error
+				? opts.pendingRequests.reject(channel, error)
+				: opts.pendingRequests.resolve(channel, result)
+
+			if (!handled) {
+				log(`[tldraw-mcp] Ignoring exec callback for non-pending channel "${channel}"`)
+				return { content: [{ type: 'text', text: JSON.stringify({ ok: false }) }] }
+			}
+
+			const canvasId = currentExecCanvasId
+			currentExecCanvasId = null
+			return { content: [{ type: 'text', text: JSON.stringify({ ok: true, canvasId }) }] }
+		}
+	)
+
+	// --- _get_canvas_state (app-only: widget fetches fork data by canvasId) ---
+
+	server.registerTool(
+		'_get_canvas_state',
+		{
+			title: 'Get Canvas State',
+			description: 'App-only: get the latest checkpoint for a canvas by its canvasId.',
+			inputSchema: z.object({ canvasId: z.string().min(1) }),
+			annotations: {
+				readOnlyHint: true,
+				destructiveHint: false,
+				idempotentHint: true,
+				openWorldHint: false,
+			},
+			_meta: { ui: { visibility: ['app'] } },
+		},
+		async ({ canvasId }: { canvasId: string }): Promise<CallToolResult> => {
+			const checkpointId = deps.getCanvasCheckpointId(canvasId)
+			if (!checkpointId) {
+				return {
+					content: [
+						{ type: 'text', text: JSON.stringify({ shapes: [], assets: [], bindings: [] }) },
+					],
+				}
+			}
+			const checkpoint = deps.loadCheckpoint(checkpointId)
+			if (!checkpoint) {
+				return {
+					content: [
+						{ type: 'text', text: JSON.stringify({ shapes: [], assets: [], bindings: [] }) },
+					],
+				}
+			}
+			const shapes = parseTlShapes(checkpoint.shapes)
+			return {
+				content: [
+					{
+						type: 'text',
+						text: JSON.stringify({
+							checkpointId,
+							shapes,
+							assets: checkpoint.assets,
+							bindings: checkpoint.bindings,
+						}),
+					},
+				],
+			}
+		}
+	)
+
+	// --- read_checkpoint (app-only) ---
+
+	server.registerTool(
+		'read_checkpoint',
+		{
+			title: 'Read Checkpoint',
+			description: 'App-only: read shapes from a checkpoint by ID.',
+			inputSchema: z.object({ checkpointId: z.string().min(1) }),
+			annotations: {
+				readOnlyHint: true,
+				destructiveHint: false,
+				idempotentHint: true,
+				openWorldHint: false,
+			},
+			_meta: { ui: { visibility: ['app'] } },
+		},
+		async ({ checkpointId }: { checkpointId: string }): Promise<CallToolResult> => {
+			const checkpoint = deps.loadCheckpoint(checkpointId)
+			if (!checkpoint) {
+				return {
+					content: [{ type: 'text', text: 'Not found.' }],
+					structuredContent: {
+						sessionId: deps.getSessionId(),
+						shapes: [],
+						assets: [],
+						bindings: [],
+					},
+				}
+			}
+
+			const shapes = parseTlShapes(checkpoint.shapes)
+			const assets = checkpoint.assets
+			const bindings = checkpoint.bindings
+
+			return {
+				content: [{ type: 'text', text: `${shapes.length} shape(s), ${assets.length} asset(s).` }],
+				structuredContent: {
+					sessionId: deps.getSessionId(),
+					shapes,
+					assets,
+					bindings,
+				},
+			}
+		}
+	)
+
+	// --- save_checkpoint (app-only) ---
+
+	server.registerTool(
+		'save_checkpoint',
+		{
+			title: 'Save Checkpoint',
+			description:
+				'App-only: save shapes to a checkpoint (from user edits). shapesJson and assetsJson must be JSON array strings.',
+			inputSchema: z.object({
+				checkpointId: z.string().min(1),
+				shapesJson: z.string(),
+				assetsJson: z.string().optional(),
+				bindingsJson: z.string().optional(),
+				canvasId: z.string().optional(),
+			}),
+			annotations: {
+				readOnlyHint: false,
+				destructiveHint: false,
+				idempotentHint: false,
+				openWorldHint: false,
+			},
+			_meta: { ui: { visibility: ['app'] } },
+		},
+		async ({
+			checkpointId,
+			shapesJson,
+			assetsJson,
+			bindingsJson,
+			canvasId,
+		}: {
+			checkpointId: string
+			shapesJson: string
+			assetsJson?: string
+			bindingsJson?: string
+			canvasId?: string
+		}): Promise<CallToolResult> => {
+			try {
+				log(
+					`[tldraw-mcp] save_checkpoint called: checkpointId=${checkpointId}, canvasId=${canvasId ?? 'none'}, prev activeCheckpointId=${deps.getActiveCheckpointId()}`
+				)
+				const raw = parseArrayJson(shapesJson, 'shapesJson')
+				const shapes = parseTlShapes(raw)
+				const assets = assetsJson ? parseArrayJson(assetsJson, 'assetsJson') : []
+				const bindings = bindingsJson ? parseArrayJson(bindingsJson, 'bindingsJson') : []
+				deps.saveCheckpoint(checkpointId, shapes, assets, bindings)
+				deps.setActiveCheckpointId(checkpointId)
+				if (canvasId) {
+					deps.setCanvasCheckpointId(canvasId, checkpointId)
+				}
+				log(
+					`[tldraw-mcp] save_checkpoint done: activeCheckpointId=${deps.getActiveCheckpointId()}, canvasId=${canvasId ?? 'none'}, shapes=${shapes.length}, assets=${assets.length}`
+				)
+				return {
+					content: [
+						{ type: 'text', text: `Saved ${shapes.length} shape(s), ${assets.length} asset(s).` },
+					],
+					structuredContent: {
+						checkpointId,
+						sessionId: deps.getSessionId(),
+						shapesCount: shapes.length,
+						assetsCount: assets.length,
+					},
+				}
+			} catch (err) {
+				return errorResponse('save_checkpoint', err)
+			}
+		}
+	)
+
+	// --- canvas resource ---
+
+	registerAppResource(
+		server,
+		'tldraw-canvas',
+		CANVAS_RESOURCE_URI,
+		{
+			title: 'tldraw Canvas',
+			description: 'Interactive tldraw canvas.',
+			mimeType: RESOURCE_MIME_TYPE,
+		},
+		async (): Promise<ReadResourceResult> => {
+			analytics?.writeDataPoint({
+				blobs: ['resource_called', 'tldraw-canvas'],
+			})
+			let html = await deps.loadWidgetHtml()
+
+			const sid = deps.getSessionId()
+			const hostName = opts.getClientHostName()
+
+			const bootstrap: Record<string, unknown> = {
+				sessionId: sid,
+				isDev: opts.isDev,
+				workerOrigin: opts.workerOrigin,
+				mcpSessionId: deps.getMcpSessionId(),
+				methodMap: await deps.loadMethodMap(),
+			}
+
+			html = injectBootstrapData(html, bootstrap)
+
+			const domain = await getWidgetDomain(hostName, opts.isDev, opts.workerOrigin)
+
+			log(`[tldraw-mcp] Serving resource to "${hostName}" with domain: ${domain}`)
+
+			return {
+				contents: [
+					{
+						uri: CANVAS_RESOURCE_URI,
+						mimeType: RESOURCE_MIME_TYPE,
+						text: html,
+						_meta: {
+							ui: {
+								csp: {
+									resourceDomains: [
+										'https://cdn.tldraw.com',
+										'https://fonts.googleapis.com',
+										'https://fonts.gstatic.com',
+										...(opts.extraResourceDomains ?? []),
+										'blob:',
+									],
+									connectDomains: opts.extraConnectDomains ?? [],
+								},
+								permissions: { clipboardWrite: {} },
+								...(domain ? { domain } : {}),
+							},
+						},
+					},
+				],
+			}
+		}
+	)
+}

package/mcp-app/src/shared/generated-data.ts

@@ -0,0 +1,160 @@
+type ArgKind =
+	| 'id'
+	| 'id-or-shape'
+	| 'ids-or-shapes'
+	| 'spread-ids'
+	| 'shape-partial'
+	| 'shape-partials'
+	| 'update-partial'
+	| 'update-partials'
+
+export type RetKind =
+	| 'this'
+	| 'shape'
+	| 'shape-or-null'
+	| 'shapes'
+	| 'id'
+	| 'id-or-null'
+	| 'ids'
+	| 'id-set'
+
+interface MethodSpec {
+	args: ArgKind[]
+	ret: RetKind
+}
+
+export type MethodMap = Record<string, MethodSpec>
+
+export interface EditorApiSpec {
+	extractedAt: string
+	memberCount: number
+	categories: string[]
+	members: unknown[]
+	types: {
+		shapeTypes: string[]
+		shapes: unknown[]
+	}
+	helperCount: number
+	helpers: unknown[]
+}
+
+interface AssetFetcher {
+	fetch(input: Request): Promise<Response>
+}
+
+const GENERATED_ASSET_BASE_URL = 'https://assets.local/'
+
+let cachedEmbeddedMethodMap: MethodMap | null | undefined
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function parseMethodMap(value: unknown): MethodMap {
+	if (!isPlainObject(value)) {
+		throw new Error('Generated method map is missing or invalid.')
+	}
+
+	const entries = Object.entries(value).map(([methodName, spec]) => {
+		if (!isPlainObject(spec) || !Array.isArray(spec.args) || typeof spec.ret !== 'string') {
+			throw new Error(`Generated method map entry "${methodName}" is invalid.`)
+		}
+
+		return [
+			methodName,
+			{
+				args: spec.args as ArgKind[],
+				ret: spec.ret as RetKind,
+			},
+		] as const
+	})
+
+	return Object.fromEntries(entries)
+}
+
+function parseEditorApiSpec(value: unknown): EditorApiSpec {
+	if (!isPlainObject(value)) {
+		throw new Error('Generated editor API spec is missing or invalid.')
+	}
+
+	if (
+		!Array.isArray(value.categories) ||
+		!Array.isArray(value.members) ||
+		!isPlainObject(value.types) ||
+		!Array.isArray(value.types.shapeTypes) ||
+		!Array.isArray(value.types.shapes) ||
+		!Array.isArray(value.helpers)
+	) {
+		throw new Error('Generated editor API spec is malformed.')
+	}
+
+	return {
+		extractedAt: typeof value.extractedAt === 'string' ? value.extractedAt : '',
+		memberCount: typeof value.memberCount === 'number' ? value.memberCount : value.members.length,
+		categories: value.categories.filter(
+			(category): category is string => typeof category === 'string'
+		),
+		members: value.members,
+		types: {
+			shapeTypes: value.types.shapeTypes.filter(
+				(shapeType): shapeType is string => typeof shapeType === 'string'
+			),
+			shapes: value.types.shapes,
+		},
+		helperCount: typeof value.helperCount === 'number' ? value.helperCount : value.helpers.length,
+		helpers: value.helpers,
+	}
+}
+
+async function loadGeneratedJsonFromAssets<T>(
+	assets: AssetFetcher,
+	filename: string,
+	parser: (value: unknown) => T
+): Promise<T> {
+	const response = await assets.fetch(new Request(new URL(filename, GENERATED_ASSET_BASE_URL)))
+	if (!response.ok) {
+		throw new Error(`Failed to load generated asset "${filename}": ${response.status}`)
+	}
+
+	return parser(await response.json())
+}
+
+function readMethodMapFromBootstrap(): MethodMap | null {
+	if (typeof window === 'undefined') return null
+
+	const bootstrap = (window as Window & { __TLDRAW_BOOTSTRAP__?: unknown }).__TLDRAW_BOOTSTRAP__
+	if (!isPlainObject(bootstrap) || !('methodMap' in bootstrap)) {
+		return null
+	}
+
+	try {
+		return parseMethodMap(bootstrap.methodMap)
+	} catch {
+		return null
+	}
+}
+
+export async function loadEditorApiSpecFromAssets(assets: AssetFetcher): Promise<EditorApiSpec> {
+	return loadGeneratedJsonFromAssets(assets, 'editor-api.json', parseEditorApiSpec)
+}
+
+export async function loadMethodMapFromAssets(assets: AssetFetcher): Promise<MethodMap> {
+	return loadGeneratedJsonFromAssets(assets, 'method-map.json', parseMethodMap)
+}
+
+export function primeEmbeddedMethodMap(): void {
+	if (cachedEmbeddedMethodMap !== undefined) return
+	cachedEmbeddedMethodMap = readMethodMapFromBootstrap()
+}
+
+export function getRequiredEmbeddedMethodMap(): MethodMap {
+	if (cachedEmbeddedMethodMap === undefined) {
+		cachedEmbeddedMethodMap = readMethodMapFromBootstrap()
+	}
+
+	if (!cachedEmbeddedMethodMap) {
+		throw new Error('Missing embedded method map. Rebuild the widget assets and reload the app.')
+	}
+
+	return cachedEmbeddedMethodMap
+}

package/mcp-app/src/shared/pending-requests.ts

@@ -0,0 +1,69 @@
+/**
+ * Generic pending-request store for bridging async server↔widget communication.
+ *
+ * One pending request per named channel. The server creates a pending request
+ * and awaits it; the widget resolves or rejects it via `callServerTool('_exec_callback')`.
+ *
+ * Callbacks without an active pending request are ignored. This prevents late
+ * duplicate callbacks from being replayed into a later request on the same channel.
+ */
+
+interface PendingEntry {
+	resolve(value: unknown): void
+	reject(reason: Error): void
+	timer: ReturnType<typeof setTimeout>
+}
+
+export class PendingRequests {
+	private pending = new Map<string, PendingEntry>()
+
+	/**
+	 * Create a pending request for the given channel.
+	 * Returns a promise that resolves when `resolve()` is called,
+	 * or rejects on timeout or if `reject()` is called.
+	 *
+	 * Throws if a request is already pending for this channel.
+	 */
+	create(channel: string, timeoutMs = 30_000): Promise<unknown> {
+		if (this.pending.has(channel)) {
+			throw new Error(`A request is already pending for channel "${channel}"`)
+		}
+
+		return new Promise<unknown>((resolve, reject) => {
+			const timer = setTimeout(() => {
+				this.pending.delete(channel)
+				reject(new Error(`Callback timed out after ${timeoutMs}ms for channel "${channel}"`))
+			}, timeoutMs)
+
+			this.pending.set(channel, { resolve, reject, timer })
+		})
+	}
+
+	/**
+	 * Resolve the pending request for the given channel.
+	 * Returns false if no request is currently pending.
+	 */
+	resolve(channel: string, value: unknown): boolean {
+		const entry = this.pending.get(channel)
+		if (!entry) return false
+
+		clearTimeout(entry.timer)
+		this.pending.delete(channel)
+		entry.resolve(value)
+		return true
+	}
+
+	/**
+	 * Reject the pending request for the given channel.
+	 * Returns false if no request is currently pending.
+	 */
+	reject(channel: string, error: string): boolean {
+		const entry = this.pending.get(channel)
+		if (!entry) return false
+
+		clearTimeout(entry.timer)
+		this.pending.delete(channel)
+		entry.reject(new Error(error))
+		return true
+	}
+}