pi-tldraw 0.1.0

package/mcp-app/src/worker.ts

@@ -0,0 +1,305 @@
+/// <reference types="@cloudflare/workers-types" />
+
+/**
+ * Cloudflare Workers entry point for the tldraw MCP server.
+ *
+ * Uses a Durable Object (McpAgent) with SQLite for persistent checkpoint storage,
+ * R2 for image uploads, and the shared registerTools() for tool registration.
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { McpAgent } from 'agents/mcp'
+import { Logger } from './logger'
+import { registerTools } from './register-tools'
+import { loadEditorApiSpecFromAssets, loadMethodMapFromAssets } from './shared/generated-data'
+import { PendingRequests } from './shared/pending-requests'
+import {
+	MAX_CHECKPOINTS,
+	MCP_SERVER_DESCRIPTION,
+	MCP_SERVER_INSTRUCTIONS,
+	MCP_SERVER_NAME,
+	MCP_SERVER_TITLE,
+	MCP_SERVER_VERSION,
+	MCP_SERVER_WEBSITE_URL,
+} from './shared/types'
+import type { MCP_APP_HOST_NAMES, PendingBootstrap, ServerDeps } from './shared/types'
+import { resolveMcpAppHostNameFromServerInfo } from './shared/utils'
+
+// --- Types ---
+
+interface Env {
+	MCP_OBJECT: DurableObjectNamespace
+	ASSETS: Fetcher
+	LOADER: WorkerLoader
+	RATE_LIMITER: RateLimit
+	MCP_AUTH_TOKEN: string
+	MCP_IS_DEV: string
+	WORKER_ORIGIN: string
+	MCP_ANALYTICS?: AnalyticsEngineDataset
+}
+
+// --- Widget HTML loader ---
+
+async function loadWidgetHtml(assets: Fetcher): Promise<string> {
+	const response = await assets.fetch(new Request('https://assets.local/mcp-app.html'))
+	if (!response.ok) throw new Error(`Failed to load widget HTML: ${response.status}`)
+	return response.text()
+}
+
+// --- CORS helpers ---
+
+const CORS_HEADERS: Record<string, string> = {
+	'Access-Control-Allow-Origin': '*',
+	'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+	'Access-Control-Allow-Headers': 'Content-Type, Accept, Authorization, Mcp-Session-Id',
+}
+
+function corsResponse(response: Response): Response {
+	const headers = new Headers(response.headers)
+	for (const [key, value] of Object.entries(CORS_HEADERS)) {
+		headers.set(key, value)
+	}
+	return new Response(response.body, { status: response.status, headers })
+}
+
+// --- McpAgent Durable Object ---
+
+export class TldrawMCP extends McpAgent<Env> {
+	override server = new McpServer(
+		{
+			name: MCP_SERVER_NAME,
+			title: MCP_SERVER_TITLE,
+			version: MCP_SERVER_VERSION,
+			description: MCP_SERVER_DESCRIPTION,
+			websiteUrl: MCP_SERVER_WEBSITE_URL,
+		},
+		{
+			instructions: MCP_SERVER_INSTRUCTIONS,
+		}
+	)
+	isDev = this.env.MCP_IS_DEV === 'true'
+	logsEnabled = this.isDev
+	activeCheckpointId: string | null = null
+	sessionId: string = ''
+	logger = new Logger('TldrawMCP', this.logsEnabled)
+	clientHostName: MCP_APP_HOST_NAMES | undefined = undefined
+	pendingRequests = new PendingRequests()
+	pendingBootstrap: PendingBootstrap | null = null
+
+	/** The MCP session ID used for DO routing (extracted from DO name). */
+	getMcpSessionId(): string {
+		return (this as any).name?.replace(/^streamable-http:/, '') ?? ''
+	}
+
+	async init() {
+		this.server.server.oninitialized = () => {
+			const clientInfo = this.server.server.getClientVersion()
+			const resolved = resolveMcpAppHostNameFromServerInfo(clientInfo?.name ?? '')
+			if (resolved) {
+				this.clientHostName = resolved
+				void this
+					.sql`INSERT OR REPLACE INTO meta (key, value) VALUES ('clientHostName', ${resolved})`
+			}
+			this.logger.info(`Client connected: ${this.clientHostName ?? 'unknown'}`)
+		}
+
+		// --- DO SQLite setup ---
+		void this
+			.sql`CREATE TABLE IF NOT EXISTS checkpoints (id TEXT PRIMARY KEY, data TEXT, created_at INTEGER)`
+		void this.sql`CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT)`
+		void this
+			.sql`CREATE TABLE IF NOT EXISTS canvas_checkpoints (canvas_id TEXT PRIMARY KEY, checkpoint_id TEXT)`
+
+		// Restore active checkpoint on reconnect
+		const rows = [...this.sql`SELECT value FROM meta WHERE key = 'activeCheckpointId'`]
+		if (rows.length > 0) {
+			this.activeCheckpointId = rows[0].value as string
+			this.logger.info('Restored active checkpoint', { checkpointId: this.activeCheckpointId })
+		}
+
+		// Restore client host name on reconnect
+		const hostNameRows = [...this.sql`SELECT value FROM meta WHERE key = 'clientHostName'`]
+		if (hostNameRows.length > 0) {
+			this.clientHostName = hostNameRows[0].value as MCP_APP_HOST_NAMES
+			this.logger.info(`Restored client host name: ${this.clientHostName}`)
+		}
+
+		// Restore or generate session ID
+		const sessionRows = [...this.sql`SELECT value FROM meta WHERE key = 'sessionId'`]
+		if (sessionRows.length > 0) {
+			this.sessionId = sessionRows[0].value as string
+		} else {
+			this.sessionId = crypto.randomUUID()
+			void this
+				.sql`INSERT OR REPLACE INTO meta (key, value) VALUES ('sessionId', ${this.sessionId})`
+
+			// Track new session
+			this.env.MCP_ANALYTICS?.writeDataPoint({
+				blobs: ['session_start', this.sessionId],
+				doubles: [Date.now()],
+			})
+		}
+
+		// --- Widget HTML (loaded once from Assets binding) ---
+		const widgetHtml = await loadWidgetHtml(this.env.ASSETS)
+		let editorApiSpecPromise: ReturnType<typeof loadEditorApiSpecFromAssets> | null = null
+		let methodMapPromise: ReturnType<typeof loadMethodMapFromAssets> | null = null
+
+		// --- Build ServerDeps from SQLite ---
+		const deps: ServerDeps = {
+			saveCheckpoint: (id, shapes, assets = [], bindings = []) =>
+				this.saveCheckpoint(id, shapes, assets, bindings),
+			loadCheckpoint: (id) => this.loadCheckpoint(id),
+			getActiveCheckpointId: () => this.activeCheckpointId,
+			setActiveCheckpointId: (id) => {
+				this.activeCheckpointId = id
+				void this.sql`INSERT OR REPLACE INTO meta (key, value) VALUES ('activeCheckpointId', ${id})`
+			},
+			getCanvasCheckpointId: (canvasId) => {
+				const rows = [
+					...this.sql`SELECT checkpoint_id FROM canvas_checkpoints WHERE canvas_id = ${canvasId}`,
+				]
+				return rows.length > 0 ? (rows[0].checkpoint_id as string) : null
+			},
+			setCanvasCheckpointId: (canvasId, checkpointId) => {
+				void this
+					.sql`INSERT OR REPLACE INTO canvas_checkpoints (canvas_id, checkpoint_id) VALUES (${canvasId}, ${checkpointId})`
+			},
+			setPendingBootstrap: (bootstrap) => {
+				this.pendingBootstrap = bootstrap
+			},
+			consumePendingBootstrap: () => {
+				const b = this.pendingBootstrap
+				this.pendingBootstrap = null
+				return b
+			},
+			getSessionId: () => this.sessionId,
+			getMcpSessionId: () => this.getMcpSessionId(),
+			loadWidgetHtml: async () => widgetHtml,
+			loadEditorApiSpec: async () => {
+				editorApiSpecPromise ??= loadEditorApiSpecFromAssets(this.env.ASSETS)
+				return editorApiSpecPromise
+			},
+			loadMethodMap: async () => {
+				methodMapPromise ??= loadMethodMapFromAssets(this.env.ASSETS)
+				return methodMapPromise
+			},
+		}
+
+		const workerOrigin = this.env.WORKER_ORIGIN
+
+		registerTools(this.server, deps, {
+			log: this.logger.toLogFn(),
+			extraResourceDomains: workerOrigin ? [workerOrigin] : [],
+			extraConnectDomains: workerOrigin ? [workerOrigin] : [],
+			searchWorkerLoader: this.env.LOADER,
+			workerOrigin,
+			isDev: this.isDev,
+			analytics: this.env.MCP_ANALYTICS,
+			getClientHostName: () => this.clientHostName,
+			pendingRequests: this.pendingRequests,
+		})
+	}
+
+	// --- Checkpoint helpers ---
+
+	saveCheckpoint(id: string, shapes: unknown[], assets: unknown[] = [], bindings: unknown[] = []) {
+		const data = JSON.stringify({ shapes, assets, bindings })
+		void this
+			.sql`INSERT OR REPLACE INTO checkpoints (id, data, created_at) VALUES (${id}, ${data}, ${Date.now()})`
+		this.activeCheckpointId = id
+		void this.sql`INSERT OR REPLACE INTO meta (key, value) VALUES ('activeCheckpointId', ${id})`
+
+		// Evict old checkpoints beyond MAX_CHECKPOINTS (LRU)
+		void this
+			.sql`DELETE FROM checkpoints WHERE id NOT IN (SELECT id FROM checkpoints ORDER BY created_at DESC LIMIT ${MAX_CHECKPOINTS})`
+
+		this.logger.debug('Checkpoint saved', { checkpointId: id, shapes: shapes.length })
+	}
+
+	loadCheckpoint(id: string): { shapes: unknown[]; assets: unknown[]; bindings: unknown[] } | null {
+		const rows = [...this.sql`SELECT data FROM checkpoints WHERE id = ${id}`]
+		if (rows.length === 0) return null
+		const parsed = JSON.parse(rows[0].data as string)
+		// Backwards compat: old checkpoints stored a plain array of shapes
+		if (Array.isArray(parsed)) return { shapes: parsed, assets: [], bindings: [] }
+		return {
+			shapes: parsed.shapes ?? [],
+			assets: parsed.assets ?? [],
+			bindings: parsed.bindings ?? [],
+		}
+	}
+}
+
+// --- Fetch handler ---
+// McpAgent.serve() handles CORS, session management, and transport internally.
+// Expose both transports: Streamable HTTP at /mcp, SSE at /sse.
+
+const mcpHandler = TldrawMCP.serve('/mcp')
+const sseHandler = TldrawMCP.serveSSE('/sse')
+
+export default {
+	async fetch(request: Request, env: Env, ctx: ExecutionContext) {
+		try {
+			const requireAuth = Boolean(env.MCP_AUTH_TOKEN)
+			const url = new URL(request.url)
+
+			// CORS preflight
+			if (request.method === 'OPTIONS') {
+				return new Response(null, { status: 204, headers: CORS_HEADERS })
+			}
+
+			// Health check (no auth)
+			if (url.pathname === '/health') {
+				return Response.json({ status: 'ok', timestamp: Date.now() })
+			}
+
+			// Domain verification (no auth)
+			if (url.pathname === '/.well-known/openai-apps-challenge') {
+				return new Response('SG4iyi_lKvsvOJA-QN3UOJZeISqeAf4tnnxqgRMTU0k', {
+					headers: { 'Content-Type': 'text/plain' },
+				})
+			}
+
+			// Require bearer auth only when an auth token is configured.
+			if (requireAuth) {
+				const auth = request.headers.get('Authorization')
+				if (auth !== `Bearer ${env.MCP_AUTH_TOKEN}`) {
+					return corsResponse(new Response('Unauthorized', { status: 401 }))
+				}
+			}
+
+			// SSE transport (legacy)
+			if (url.pathname === '/sse' || url.pathname.startsWith('/sse/')) {
+				return sseHandler.fetch(request, env, ctx)
+			}
+
+			// Streamable HTTP transport
+			if (url.pathname === '/mcp' || url.pathname.startsWith('/mcp/')) {
+				const sessionId = request.headers.get('mcp-session-id')
+				const forwardedFor = request.headers.get('x-forwarded-for')
+				const clientIp =
+					request.headers.get('cf-connecting-ip') ?? forwardedFor?.split(',')[0]?.trim()
+				const rateLimitKey = sessionId
+					? `mcp-session:${sessionId}`
+					: `mcp-ip:${clientIp ?? 'unknown'}`
+
+				const { success } = await env.RATE_LIMITER.limit({ key: rateLimitKey })
+				if (!success) {
+					return corsResponse(new Response('Rate limited', { status: 429 }))
+				}
+
+				// POST without a session ID is the initial handshake.
+				if (!sessionId && request.method !== 'POST') {
+					return corsResponse(new Response('Missing session', { status: 400 }))
+				}
+				return mcpHandler.fetch(request, env, ctx)
+			}
+
+			return new Response('Not found', { status: 404 })
+		} catch (err) {
+			console.error(err)
+			return new Response('Internal Server Error', { status: 500 })
+		}
+	},
+}

package/mcp-app/tsconfig.json

@@ -0,0 +1,23 @@
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "ESNext",
+		"moduleResolution": "bundler",
+		"strict": true,
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		"forceConsistentCasingInFileNames": true,
+		"jsx": "react-jsx",
+		"sourceMap": true,
+		"outDir": "dist",
+		"lib": ["ES2022", "DOM", "DOM.Iterable"],
+		"types": ["vite/client"]
+	},
+	"include": ["src/**/*.ts", "src/**/*.tsx", "vite.config.ts"],
+	"exclude": ["node_modules", "dist"],
+	"references": [
+		{
+			"path": "../../packages/tldraw"
+		}
+	]
+}

package/mcp-app/vite.config.ts

@@ -0,0 +1,13 @@
+import react from '@vitejs/plugin-react'
+import { defineConfig } from 'vite'
+import { viteSingleFile } from 'vite-plugin-singlefile'
+
+export default defineConfig({
+	plugins: [react(), viteSingleFile()],
+	root: 'src/widget',
+	envDir: '../..',
+	build: {
+		outDir: '../../dist',
+		emptyOutDir: false,
+	},
+})

package/mcp-app/wrangler.toml

@@ -0,0 +1,45 @@
+name = "tldraw-mcp-app"
+main = "src/worker.ts"
+# Keep in sync with WORKER_COMPATIBILITY_DATE in src/shared/types.ts
+compatibility_date = "2025-03-10"
+compatibility_flags = ["nodejs_compat"]
+preview_urls = true
+
+[assets]
+directory = "./dist"
+binding = "ASSETS"
+run_worker_first = true
+
+[durable_objects]
+bindings = [{ class_name = "TldrawMCP", name = "MCP_OBJECT" }]
+
+[[migrations]]
+tag = "v1"
+new_sqlite_classes = ["TldrawMCP"]
+
+[vars]
+# Set this to the public URL of the worker. Used for constructing absolute image URLs.
+# Override with `--var WORKER_ORIGIN:https://your-tunnel.trycloudflare.com` for cloudflared tunnels.
+WORKER_ORIGIN = "https://tldraw-mcp-app.tldraw.workers.dev"
+# Default to production-safe widget behavior. Local dev scripts override this with
+# `--var MCP_IS_DEV:true` so local HTTP connectors omit `ui.domain`.
+MCP_IS_DEV = "false"
+
+[[analytics_engine_datasets]]
+binding = "MCP_ANALYTICS"
+dataset = "MCP_ANALYTICS"
+
+[[worker_loaders]]
+binding = "LOADER"
+
+#################### Rate limiting ####################
+[[ratelimits]]
+name = "RATE_LIMITER"
+namespace_id = "2001"
+
+[ratelimits.simple]
+limit = 30
+period = 60
+
+[observability]
+enabled = true

package/mcp-app-source.json

@@ -0,0 +1,36 @@
+{
+  "repo": "https://github.com/tldraw/tldraw.git",
+  "commit": "4b0cfc539e074217e1e248461afa596fc7d02040",
+  "appPath": "apps/mcp-app",
+  "patches": [
+    "patches/tldraw-mcp-app/001-pi-runtime.patch"
+  ],
+  "build": [
+    {
+      "cwd": ".",
+      "command": "yarn install --immutable"
+    },
+    {
+      "cwd": "apps/mcp-app",
+      "command": "yarn build"
+    }
+  ],
+  "assembledFiles": [
+    "LICENSE.md",
+    "README.md",
+    "package.json",
+    "server.json",
+    "tsconfig.json",
+    "vite.config.ts",
+    "wrangler.toml",
+    "dev-tunnel.sh",
+    "src/",
+    "scripts/",
+    "plugins/",
+    "dist/"
+  ],
+  "notes": [
+    "The bundled mcp-app/ keeps the existing runtime contract: cd mcp-app && yarn dev.",
+    "The patch preserves Pi autosave of assets/bindings and iframe fullscreen sizing fixes."
+  ]
+}

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "pi-tldraw",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Pi extension that opens and persists a local tldraw MCP canvas.",
+  "license": "MIT",
+  "author": {
+    "name": "Zeebee Siwiec",
+    "email": "zeebee@dicr.tech",
+    "url": "https://github.com/zeebeeCoder"
+  },
+  "contributors": [
+    {
+      "name": "Zeebee Siwiec",
+      "email": "zeebee@dicr.tech",
+      "url": "https://github.com/zeebeeCoder"
+    }
+  ],
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "mcp",
+    "mcp-app",
+    "tldraw"
+  ],
+  "files": [
+    "src/",
+    "bridge/",
+    "scripts/",
+    "static/",
+    "mcp-app/",
+    "README.md",
+    "tsconfig.json",
+    "LICENSE",
+    "mcp-app-source.json",
+    "patches/"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "check": "npm run typecheck && npm test && npm run verify:bundle && npm run verify:mcp-app && npm run verify:mcp-app-source && npm run verify:package",
+    "pack:dry": "npm run build && npm run verify:package",
+    "prepublishOnly": "npm run build && npm run check",
+    "build:bridge": "node scripts/build-bridge.mjs",
+    "build": "npm run build:bridge",
+    "verify:bundle": "node scripts/verify-bundle.mjs",
+    "e2e:mcp": "node scripts/e2e-mcp.mjs",
+    "assemble:mcp-app": "node scripts/assemble-mcp-app.mjs",
+    "verify:mcp-app": "node scripts/verify-mcp-app.mjs",
+    "e2e:packaged-mcp-app": "node scripts/e2e-packaged-mcp-app.mjs",
+    "assemble:mcp-app:pinned": "node scripts/assemble-mcp-app.mjs --pinned",
+    "verify:mcp-app-source": "node scripts/verify-mcp-app-source.mjs",
+    "verify:package": "node scripts/verify-package-files.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "esbuild": "^0.28.1",
+    "typebox": "*",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/zeebeeCoder/pi-tldraw.git"
+  },
+  "bugs": {
+    "url": "https://github.com/zeebeeCoder/pi-tldraw/issues"
+  },
+  "homepage": "https://github.com/zeebeeCoder/pi-tldraw#readme",
+  "dependencies": {
+    "@modelcontextprotocol/ext-apps": "^1.7.4",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "agents": "^0.5.0",
+    "wrangler": "4.75.0",
+    "zod": "^4.4.3"
+  }
+}

package/patches/tldraw-mcp-app/001-pi-runtime.patch

@@ -0,0 +1,35 @@
+diff --git a/apps/mcp-app/src/widget/mcp-app.css b/apps/mcp-app/src/widget/mcp-app.css
+index 03f10d198..1bc9271bb 100644
+--- a/apps/mcp-app/src/widget/mcp-app.css
++++ b/apps/mcp-app/src/widget/mcp-app.css
+@@ -80,6 +80,8 @@
+ 	position: fixed;
+ 	inset: 0;
+ 	z-index: 9999;
++	height: 100%;
++	min-height: 0;
+ 	background: var(--tl-color-background);
+ }
+ 
+diff --git a/apps/mcp-app/src/widget/persistence.ts b/apps/mcp-app/src/widget/persistence.ts
+index a65d1cb14..feb5244f7 100644
+--- a/apps/mcp-app/src/widget/persistence.ts
++++ b/apps/mcp-app/src/widget/persistence.ts
+@@ -259,6 +259,8 @@ export function pushCanvasContext(app: App, editor: Editor, opts?: { message?: s
+ 	const shapes = [...editor.getCurrentPageShapes()].map((shape) =>
+ 		convertTldrawShapeToFocusedShape(editor, shape)
+ 	)
++	const assets = [...editor.getAssets()].map((asset) => structuredClone(asset))
++	const bindings = getEditorBindings(editor)
+ 
+ 	const canvasStatus = shapes.length > 0 ? `Current canvas state is attached.` : 'Canvas is empty.'
+ 
+@@ -268,6 +270,8 @@ export function pushCanvasContext(app: App, editor: Editor, opts?: { message?: s
+ 		content: [{ type: 'text', text }],
+ 		structuredContent: {
+ 			shapes,
++			assets,
++			bindings,
+ 		},
+ 	})
+ }