pi-tldraw 0.1.0

package/mcp-app/src/shared/types.ts

@@ -0,0 +1,76 @@
+import type { TLShape } from 'tldraw'
+import packageJson from '../../package.json'
+import type { EditorApiSpec, MethodMap } from './generated-data'
+import type { PendingRequests } from './pending-requests'
+
+export interface PendingBootstrap {
+	canvasId: string
+	checkpointId: string | null
+}
+
+export interface ServerDeps {
+	saveCheckpoint(id: string, shapes: TLShape[], assets?: unknown[], bindings?: unknown[]): void
+	loadCheckpoint(id: string): { shapes: unknown[]; assets: unknown[]; bindings: unknown[] } | null
+	getActiveCheckpointId(): string | null
+	setActiveCheckpointId(id: string): void
+	getCanvasCheckpointId(canvasId: string): string | null
+	setCanvasCheckpointId(canvasId: string, checkpointId: string): void
+	setPendingBootstrap(bootstrap: PendingBootstrap): void
+	consumePendingBootstrap(): PendingBootstrap | null
+	getSessionId(): string
+	getMcpSessionId(): string
+	loadWidgetHtml(): Promise<string>
+	loadEditorApiSpec(): Promise<EditorApiSpec>
+	loadMethodMap(): Promise<MethodMap>
+}
+
+export interface RegisterToolsOptions {
+	/** Extra CSP resource domains (e.g. R2 image URLs). */
+	extraResourceDomains?: string[]
+	/** Extra CSP connect domains. */
+	extraConnectDomains?: string[]
+	/** Dynamic Workers loader for sandboxed server-side code execution. */
+	searchWorkerLoader: DynamicWorkerLoader
+	/** Public origin of the deployed MCP worker, used for host-specific widget domains. */
+	workerOrigin?: string
+	/** Flag so the tools, and thus the widget, know if they are running in dev mode. */
+	isDev: boolean
+	/** Logging function (defaults to console.error). */
+	log?(...args: unknown[]): void
+	/** Analytics engine dataset. */
+	analytics?: AnalyticsEngineDataset
+	/** Returns the resolved host name of the connected client. */
+	getClientHostName(): MCP_APP_HOST_NAMES | undefined
+	/** Pending requests store for widget→server callback bridge. */
+	pendingRequests: PendingRequests
+}
+
+export interface DynamicWorkerLoader {
+	load(code: {
+		compatibilityDate: string
+		mainModule: string
+		modules: Record<string, string | { js: string }>
+		env?: unknown
+		globalOutbound?: null
+	}): {
+		getEntrypoint(name?: string): unknown
+	}
+}
+
+export const MCP_SERVER_NAME = 'tldraw'
+export const MCP_SERVER_VERSION = packageJson.version
+export const MCP_SERVER_TITLE = 'tldraw Canvas'
+export const MCP_SERVER_DESCRIPTION =
+	'An interactive tldraw canvas with tools for diagramming, drawing, and more.'
+export const MCP_SERVER_WEBSITE_URL = 'https://www.tldraw.com'
+export const MCP_SERVER_INSTRUCTIONS =
+	'Use `search` to query the tldraw Editor API spec (e.g. search for methods by category or name). Use `exec` to run JavaScript on the canvas — your code receives `editor` (the tldraw Editor instance) and helpers like toRichText, createShapeId, createArrowBetweenShapes. The current canvas state is kept in model context as raw TLShape, asset, and binding data.'
+
+export const CANVAS_RESOURCE_URI = 'ui://show-canvas/mcp-app.html'
+
+/** Must match `compatibility_date` in wrangler.toml. */
+export const WORKER_COMPATIBILITY_DATE = '2025-03-10'
+
+export const MAX_CHECKPOINTS = 200
+
+export type MCP_APP_HOST_NAMES = 'cursor' | 'vscode' | 'claude' | 'chatgpt'

package/mcp-app/src/shared/utils.ts

@@ -0,0 +1,132 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js'
+import type { TLShape } from 'tldraw'
+import type { MCP_APP_HOST_NAMES } from './types'
+
+const CANVAS_ID_CHARS = 'abcdefghijklmnopqrstuvwxyz0123456789'
+const CANVAS_ID_LENGTH = 8
+
+export function generateCanvasId(): string {
+	const bytes = new Uint8Array(CANVAS_ID_LENGTH)
+	crypto.getRandomValues(bytes)
+	return Array.from(bytes, (b) => CANVAS_ID_CHARS[b % CANVAS_ID_CHARS.length]).join('')
+}
+
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+export function parseTlShapes(value: unknown[]): TLShape[] {
+	return value.filter(
+		(s): s is TLShape => isPlainObject(s) && typeof s.id === 'string' && typeof s.type === 'string'
+	)
+}
+
+export function errorResponse(toolName: string, err: unknown, hint?: string): CallToolResult {
+	const message = err instanceof Error ? err.message : String(err)
+	const parts = [`[${toolName}] Error: ${message}`]
+	if (hint) parts.push(hint)
+	return {
+		content: [{ type: 'text', text: parts.join('\n\n') }],
+		isError: true,
+	}
+}
+
+// these are what we get from server.server.getClientVersion() in the worker
+export function resolveMcpAppHostNameFromServerInfo(
+	potentialHostName: string
+): MCP_APP_HOST_NAMES | undefined {
+	const normalizedPotentialHostName = potentialHostName.trim().toLowerCase()
+
+	if (normalizedPotentialHostName.includes('cursor-vscode')) return 'cursor' // we expect something like "cursor-vscode (via mcp-remote 0.1.37)"
+	if (normalizedPotentialHostName.includes('visual studio code')) return 'vscode' // we expect something like "Visual Studio Code (via mcp-remote 0.1.37)"
+	if (
+		normalizedPotentialHostName.includes('openai-mcp') ||
+		normalizedPotentialHostName.includes('chatgpt')
+	)
+		return 'chatgpt' // we expect something like "openai-mcp"
+	if (normalizedPotentialHostName.includes('claude-ai')) return 'claude' // we expect something like "claude-ai (via mcp-remote 0.1.37)"
+
+	return undefined
+}
+
+// these are what we expect from app.getHostVersion() (called in the client)
+export function resolveMcpAppHostNameFromClientInfo(
+	potentialHostName: string
+): MCP_APP_HOST_NAMES | undefined {
+	const normalizedPotentialHostName = potentialHostName.trim().toLowerCase()
+
+	if (normalizedPotentialHostName.includes('cursor')) return 'cursor'
+	if (normalizedPotentialHostName.includes('visual studio code')) return 'vscode'
+	if (normalizedPotentialHostName.includes('chatgpt')) return 'chatgpt'
+	if (normalizedPotentialHostName.includes('claude')) return 'claude'
+
+	return undefined
+}
+
+const CODE_EDITOR_HOST_NAMES: MCP_APP_HOST_NAMES[] = ['cursor', 'vscode']
+const ANALYTICS_ENGINE_MAX_BLOB_BYTES = 16 * 1024
+const TRUNCATED_ANALYTICS_SUFFIX = '...[truncated]'
+
+export function isHostCodeEditor(hostName: MCP_APP_HOST_NAMES): boolean {
+	return CODE_EDITOR_HOST_NAMES.includes(hostName)
+}
+
+function truncateUtf8String(value: string, maxBytes: number): string {
+	const encoder = new TextEncoder()
+	if (maxBytes <= 0) return ''
+	if (encoder.encode(value).byteLength <= maxBytes) return value
+
+	const suffixByteLength = encoder.encode(TRUNCATED_ANALYTICS_SUFFIX).byteLength
+	if (suffixByteLength >= maxBytes) {
+		let low = 0
+		let high = TRUNCATED_ANALYTICS_SUFFIX.length
+
+		while (low < high) {
+			const mid = Math.ceil((low + high) / 2)
+			if (encoder.encode(TRUNCATED_ANALYTICS_SUFFIX.slice(0, mid)).byteLength <= maxBytes) {
+				low = mid
+			} else {
+				high = mid - 1
+			}
+		}
+
+		return TRUNCATED_ANALYTICS_SUFFIX.slice(0, low)
+	}
+
+	const maxValueBytes = maxBytes - suffixByteLength
+	let low = 0
+	let high = value.length
+
+	while (low < high) {
+		const mid = Math.ceil((low + high) / 2)
+		if (encoder.encode(value.slice(0, mid)).byteLength <= maxValueBytes) {
+			low = mid
+		} else {
+			high = mid - 1
+		}
+	}
+
+	return `${value.slice(0, low)}${TRUNCATED_ANALYTICS_SUFFIX}`
+}
+
+export function writeToolAnalytics(
+	analytics: AnalyticsEngineDataset | undefined,
+	toolName: string,
+	code: string
+) {
+	if (!analytics) return
+
+	const encoder = new TextEncoder()
+	const baseBlobs = ['tool_called', toolName]
+	const maxCodeBytes =
+		ANALYTICS_ENGINE_MAX_BLOB_BYTES -
+		baseBlobs.reduce((total, blob) => total + encoder.encode(blob).byteLength, 0)
+
+	try {
+		analytics.writeDataPoint({
+			blobs: [...baseBlobs, truncateUtf8String(code, maxCodeBytes)],
+		})
+	} catch {
+		// writeDataPoint returns immediately and never throws, so we won't know if it failed
+	}
+}

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

@@ -0,0 +1,120 @@
+import { registerAppTool } from '@modelcontextprotocol/ext-apps/server'
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js'
+import { z } from 'zod'
+import type { PendingRequests } from '../shared/pending-requests'
+import { CANVAS_RESOURCE_URI } from '../shared/types'
+import { generateCanvasId, writeToolAnalytics } from '../shared/utils'
+
+const EXEC_CALLBACK_TIMEOUT_MS = 30_000
+
+export function registerExecTool(
+	server: McpServer,
+	opts: {
+		analytics?: AnalyticsEngineDataset
+		log(...args: unknown[]): void
+		pendingRequests: PendingRequests
+		setCurrentExecCanvasId(id: string): void
+	}
+) {
+	registerAppTool(
+		server,
+		'exec',
+		{
+			title: 'Execute Code',
+			description: `Execute JavaScript code on a tldraw canvas. The code runs in the widget with access to the live \`editor\` instance, helper functions, and normal js. Use the \`search\` tool first to discover available Editor methods and shape types.
+
+Each canvas has a unique \`canvasId\`. Omit \`canvasId\` to create a new blank canvas. To edit an existing canvas, pass the \`canvasId\` that was returned by a previous exec call.
+
+Shapes and text grow depending on the amount of text they have. Use clever scripting to ensure there are no unintended overlaps.
+
+Examples:
+- Create a rectangle: editor.createShape({ _type: 'rectangle', shapeId: 'box1', x: 200, y: 120, w: 320, h: 180, text: 'Hello' })
+- Connect shapes with an arrow: editor.createShape({ _type: 'arrow', shapeId: 'a1', fromId: 'box1', toId: 'box2', x1: 0, y1: 0, x2: 100, y2: 0 })
+- Select and zoom: editor.select('box1'); editor.zoomToSelection()
+- Read shapes: return editor.getCurrentPageShapes()
+- Distribute evenly: editor.distributeShapes(editor.getSelectedShapeIds(), 'horizontal')
+- Box around shapes: boxShapes(['box1', 'box2'], { text: 'Group label', color: 'blue' })
+- Stack shapes dynamically: editor.createShape({ _type: 'rectangle', shapeId: 'a', x: 0, y: 0, w: 300, h: 200, text: 'First box\\nwith wrapping text' }); const bounds = editor.getShapePageBounds('a'); editor.createShape({ _type: 'rectangle', shapeId: 'b', x: 0, y: bounds.maxY + 20, w: 300, h: 200, text: 'Below first' })`,
+			inputSchema: z.object({
+				code: z
+					.string()
+					.describe(
+						'JavaScript code to execute. Has access to `editor` (tldraw Editor instance) and helper functions.'
+					),
+				canvasId: z
+					.string()
+					.optional()
+					.describe(
+						'Canvas ID to edit. Omit to create a new blank canvas. Pass a canvasId from a previous exec result to continue editing that canvas.'
+					),
+			}),
+			annotations: {
+				readOnlyHint: false,
+				destructiveHint: false,
+				idempotentHint: false,
+				openWorldHint: false,
+			},
+			_meta: { ui: { resourceUri: CANVAS_RESOURCE_URI } },
+		},
+		async ({
+			code,
+			canvasId: inputCanvasId,
+		}: {
+			code: string
+			canvasId?: string
+		}): Promise<CallToolResult> => {
+			writeToolAnalytics(opts.analytics, 'exec', code)
+
+			const canvasId = inputCanvasId || generateCanvasId()
+			opts.setCurrentExecCanvasId(canvasId)
+
+			opts.log(`[tldraw-mcp] exec called: canvasId=${canvasId}, existing=${Boolean(inputCanvasId)}`)
+
+			try {
+				const result = (await opts.pendingRequests.create('exec', EXEC_CALLBACK_TIMEOUT_MS)) as {
+					success: boolean
+					result?: unknown
+					error?: string
+				}
+
+				if (!result.success) {
+					opts.log(`[tldraw-mcp] exec failed: ${result.error}`)
+					return {
+						content: [
+							{
+								type: 'text',
+								text: `Runtime error executing code on canvas. The code was NOT applied successfully. Fix the error and try again.\n\nCanvas ID: ${canvasId} — to retry on this canvas, pass this canvasId.\n\nError: ${result.error}`,
+							},
+						],
+						isError: true,
+					}
+				}
+
+				const resultStr =
+					result.result !== undefined ? JSON.stringify(result.result, null, 2) : undefined
+				const lines = [
+					resultStr
+						? `Code executed successfully on canvas. Return value:\n${resultStr}`
+						: 'Code executed successfully on canvas.',
+					`\nCanvas ID: ${canvasId} — to edit this canvas again, pass this as the canvasId parameter.`,
+				]
+
+				opts.log(`[tldraw-mcp] exec succeeded, canvasId=${canvasId}`)
+				return { content: [{ type: 'text', text: lines.join('\n') }] }
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err)
+				opts.log(`[tldraw-mcp] exec error: ${message}`)
+				return {
+					content: [
+						{
+							type: 'text',
+							text: `Exec failed: ${message}`,
+						},
+					],
+					isError: true,
+				}
+			}
+		}
+	)
+}

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

@@ -0,0 +1,16 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+const DIST_DIR = path.join(__dirname, '..', '..', 'dist')
+
+let cachedHtml: string | null = null
+
+export async function loadCachedCanvasWidgetHtml(): Promise<string> {
+	if (cachedHtml) return cachedHtml
+	const html = await fs.readFile(path.join(DIST_DIR, 'mcp-app.html'), 'utf-8')
+	cachedHtml = html
+	return html
+}

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

@@ -0,0 +1,150 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js'
+import { z } from 'zod'
+import type { EditorApiSpec } from '../shared/generated-data'
+import { WORKER_COMPATIBILITY_DATE } from '../shared/types'
+import type { DynamicWorkerLoader } from '../shared/types'
+import { writeToolAnalytics } from '../shared/utils'
+
+const SEARCH_TIMEOUT_MS = 5_000
+const SEARCH_RUNNER_MODULE = 'search-runner.js'
+const SEARCH_RUNNER_ENTRYPOINT = 'SearchRunner'
+
+type SearchWorkerResult = { success: true; value: unknown } | { success: false; error: string }
+type SearchSpec = Pick<
+	EditorApiSpec,
+	'members' | 'categories' | 'types' | 'helperCount' | 'helpers'
+>
+
+function createSearchRunnerModule(code: string) {
+	return `import { WorkerEntrypoint } from 'cloudflare:workers'
+
+function serializeResult(result) {
+	try {
+		return JSON.parse(JSON.stringify(result))
+	} catch {
+		return String(result)
+	}
+}
+
+export class ${SEARCH_RUNNER_ENTRYPOINT} extends WorkerEntrypoint {
+	async run() {
+		try {
+			const spec = this.env.SPEC
+			const result = await (async () => {
+${code}
+			})()
+			return { success: true, value: serializeResult(result) }
+		} catch (err) {
+			return {
+				success: false,
+				error: err instanceof Error ? err.message : String(err),
+			}
+		}
+	}
+}
+`
+}
+
+async function runSearchInDynamicWorker(
+	loader: DynamicWorkerLoader,
+	spec: SearchSpec,
+	code: string
+) {
+	const worker = loader.load({
+		compatibilityDate: WORKER_COMPATIBILITY_DATE,
+		mainModule: SEARCH_RUNNER_MODULE,
+		modules: {
+			[SEARCH_RUNNER_MODULE]: {
+				js: createSearchRunnerModule(code),
+			},
+		},
+		env: {
+			SPEC: spec,
+		},
+		globalOutbound: null,
+	})
+
+	const entrypoint = worker.getEntrypoint(SEARCH_RUNNER_ENTRYPOINT) as {
+		run(): Promise<SearchWorkerResult>
+	}
+	const result = await Promise.race([
+		entrypoint.run(),
+		new Promise<never>((_, reject) =>
+			setTimeout(
+				() => reject(new Error(`Search timed out after ${SEARCH_TIMEOUT_MS}ms`)),
+				SEARCH_TIMEOUT_MS
+			)
+		),
+	])
+
+	if (!result.success) {
+		throw new Error(result.error)
+	}
+
+	return result.value
+}
+
+export function registerSearchTool(
+	server: McpServer,
+	opts: {
+		analytics?: AnalyticsEngineDataset
+		loader: DynamicWorkerLoader
+		loadSpec(): Promise<EditorApiSpec>
+		log(...args: unknown[]): void
+	}
+) {
+	let specPromise: Promise<SearchSpec> | null = null
+
+	server.registerTool(
+		'search',
+		{
+			title: 'Search Editor API',
+			description: `Search the tldraw Editor API spec by writing JavaScript that receives a \`spec\` object and returns a result. The spec contains: spec.members (all Editor methods/properties with name, kind, signature, description, category), spec.categories (category names), spec.types.shapes (focused shape type definitions with props), spec.types.shapeTypes (list of all shape type strings), spec.helpers (exec helper functions with descriptions, params, examples).
+
+Examples:
+- Find shape methods: return spec.members.filter(m => m.category === "shapes").map(m => ({ name: m.name, signature: m.signature }))
+- Get arrow shape props: return spec.types.shapes.find(s => s.shapeType === "arrow")
+- List all categories: return spec.categories
+- Find a helper: return spec.helpers.find(h => h.name === "createArrowBetweenShapes")`,
+			inputSchema: z.object({
+				code: z
+					.string()
+					.describe(
+						'JavaScript code that receives `spec` and returns a result. Must use `return` to produce output.'
+					),
+			}),
+			annotations: {
+				readOnlyHint: true,
+				idempotentHint: true,
+				openWorldHint: false,
+				destructiveHint: false,
+			},
+		},
+		async ({ code }: { code: string }): Promise<CallToolResult> => {
+			writeToolAnalytics(opts.analytics, 'search', code)
+			opts.log('[tldraw-mcp] search called')
+
+			try {
+				specPromise ??= opts.loadSpec().then((editorApi) => ({
+					members: editorApi.members,
+					categories: editorApi.categories,
+					types: editorApi.types,
+					helperCount: editorApi.helperCount,
+					helpers: editorApi.helpers,
+				}))
+				const serialized = await runSearchInDynamicWorker(opts.loader, await specPromise, code)
+
+				return {
+					content: [{ type: 'text', text: JSON.stringify(serialized, null, 2) }],
+				}
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err)
+				return {
+					content: [{ type: 'text', text: `Error: ${message}` }],
+					isError: true,
+				}
+			}
+		}
+	)
+}

package/mcp-app/src/widget/app-context.tsx

@@ -0,0 +1,29 @@
+import { type App, type McpUiDisplayMode } from '@modelcontextprotocol/ext-apps/react'
+import { createContext } from 'react'
+import type { MCP_APP_HOST_NAMES } from '../shared/types'
+
+export const McpAppContext = createContext<{
+	displayMode: McpUiDisplayMode
+	toggleFullscreen: (() => Promise<void>) | null
+	canFullscreen: boolean
+	canDownload: boolean
+	app: App | null
+	lastEditor: 'user' | 'ai'
+	hostName: MCP_APP_HOST_NAMES | null
+	isDev: boolean
+	isDevLogVisible: boolean
+	toggleDevLog: (() => void) | null
+	logIfDevMode: ((message: string) => void) | null
+}>({
+	displayMode: 'inline',
+	toggleFullscreen: null,
+	canFullscreen: true,
+	canDownload: true,
+	app: null,
+	lastEditor: 'ai',
+	hostName: null,
+	isDev: false,
+	isDevLogVisible: false,
+	toggleDevLog: null,
+	logIfDevMode: null,
+})

package/mcp-app/src/widget/dev-log.tsx

@@ -0,0 +1,70 @@
+import { useCallback, useRef, useState } from 'react'
+
+const MAX_DEV_LOG_ENTRIES = 200
+export const DEV_LOG_PANEL_HEIGHT = 140
+export const DEV_LOG_PANEL_GAP = 8
+
+export function useDevLog() {
+	const [isDev, setIsDev] = useState(false)
+	const [isDevLogVisible, setIsDevLogVisible] = useState(false)
+	const [devLogEntries, setDevLogEntries] = useState<string[]>([])
+	const isDevRef = useRef(false)
+
+	const logIfDevMode = useCallback((message: string) => {
+		if (!isDevRef.current) return
+		setDevLogEntries((entries) => {
+			const timestamp = new Date().toLocaleTimeString()
+			const nextEntries = [...entries, `[${timestamp}] ${message}`]
+			return nextEntries.slice(-MAX_DEV_LOG_ENTRIES)
+		})
+	}, [])
+
+	const toggleDevLog = useCallback(() => {
+		setIsDevLogVisible((visible) => !visible)
+	}, [])
+
+	const enableDevMode = useCallback(() => {
+		isDevRef.current = true
+		setIsDev(true)
+		setIsDevLogVisible(true)
+	}, [])
+
+	return {
+		isDev,
+		isDevLogVisible,
+		devLogEntries,
+		isDevRef,
+		logIfDevMode,
+		toggleDevLog,
+		enableDevMode,
+	}
+}
+
+export function DevLogPanel({
+	entries,
+	isFullscreen,
+}: {
+	entries: string[]
+	isFullscreen: boolean
+}) {
+	return (
+		<div
+			style={{
+				flex: isFullscreen ? '0 0 160px' : undefined,
+				minHeight: 80,
+				maxHeight: isFullscreen ? 200 : DEV_LOG_PANEL_HEIGHT,
+				overflow: 'auto',
+				padding: 12,
+				border: '1px solid var(--tl-color-muted-2)',
+				borderRadius: 8,
+				background: 'var(--tl-color-panel)',
+				fontFamily: 'monospace',
+				fontSize: 12,
+				lineHeight: 1.5,
+				whiteSpace: 'pre-wrap',
+			}}
+		>
+			{entries.length > 0 ? entries.join('\n') : 'Dev log ready.'}
+		</div>
+	)
+}