pmx-canvas 0.1.5 → 0.1.7

package/src/server/canvas-schema.ts

@@ -22,6 +22,7 @@ export interface CanvasCreateTypeSchema {
   kind: 'node' | 'virtual-node';
   description: string;
   endpoint: string;
+  mcpTool?: string;
   fields: CanvasCreateField[];
   example: Record<string, unknown>;
   notes?: string[];
@@ -63,6 +64,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'node',
     description: 'Freeform markdown note.',
     endpoint: '/api/canvas/node',
+    mcpTool: 'canvas_add_node',
     fields: [
       { name: 'title', type: 'string', required: false, description: 'Optional node title.' },
       { name: 'content', type: 'string', required: false, description: 'Markdown body.' },
@@ -85,6 +87,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'node',
     description: 'Compact status indicator.',
     endpoint: '/api/canvas/node',
+    mcpTool: 'canvas_add_node',
     fields: [
       { name: 'title', type: 'string', required: false, description: 'Status label.' },
       { name: 'content', type: 'string', required: false, description: 'Rendered status text.' },
@@ -100,6 +103,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'node',
     description: 'Agent context card container.',
     endpoint: '/api/canvas/node',
+    mcpTool: 'canvas_add_node',
     fields: [
       { name: 'title', type: 'string', required: false, description: 'Optional title override.' },
       { name: 'content', type: 'string', required: false, description: 'Optional context body.' },
@@ -115,6 +119,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'node',
     description: 'Structured ledger/log node.',
     endpoint: '/api/canvas/node',
+    mcpTool: 'canvas_add_node',
     fields: [
       { name: 'title', type: 'string', required: false, description: 'Optional title.' },
       { name: 'content', type: 'string', required: false, description: 'Ledger body text.' },
@@ -130,6 +135,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'node',
     description: 'Execution trace viewer.',
     endpoint: '/api/canvas/node',
+    mcpTool: 'canvas_add_node',
     fields: [
       { name: 'title', type: 'string', required: false, description: 'Optional title.' },
       { name: 'content', type: 'string', required: false, description: 'Trace summary.' },
@@ -145,6 +151,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'node',
     description: 'Workspace file viewer.',
     endpoint: '/api/canvas/node',
+    mcpTool: 'canvas_add_node',
     fields: [
       { name: 'content', type: 'string', required: true, description: 'Workspace-relative or absolute file path.' },
       { name: 'title', type: 'string', required: false, description: 'Optional title override.' },
@@ -162,6 +169,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'node',
     description: 'Image node backed by a path, URL, or data URI.',
     endpoint: '/api/canvas/node',
+    mcpTool: 'canvas_add_node',
     fields: [
       { name: 'content', type: 'string', required: true, description: 'Image path, URL, or data URI.' },
       { name: 'title', type: 'string', required: false, description: 'Optional title override.' },
@@ -187,6 +195,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'node',
     description: 'Persisted webpage snapshot with server-side fetch and refresh.',
     endpoint: '/api/canvas/node',
+    mcpTool: 'canvas_add_node',
     fields: [
       { name: 'url', type: 'string', required: true, description: 'HTTP(S) URL to fetch and cache.', aliases: ['content'] },
       { name: 'title', type: 'string', required: false, description: 'Optional title override.' },
@@ -210,6 +219,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'node',
     description: 'Hosted iframe/app node.',
     endpoint: '/api/canvas/node',
+    mcpTool: 'canvas_open_mcp_app',
     fields: [
       { name: 'title', type: 'string', required: false, description: 'App title.' },
       { name: 'content', type: 'string', required: false, description: 'Optional inline content.' },
@@ -223,11 +233,35 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
       'Tool-backed MCP app nodes and hosted artifact nodes persist `data.provenance` when the server can infer a reopen or rehydrate path.',
     ],
   },
+  {
+    type: 'external-app',
+    kind: 'virtual-node',
+    description: 'Tool-backed hosted app opened from an external MCP server, such as Excalidraw.',
+    endpoint: '/api/canvas/mcp-app/open',
+    mcpTool: 'canvas_open_mcp_app',
+    fields: [
+      { name: 'toolName', type: 'string', required: true, description: 'Tool name on the external MCP server.' },
+      { name: 'transport', type: '{ type: "stdio", command, args? } | { type: "http", url, headers? }', required: true, description: 'External MCP transport definition.' },
+      { name: 'toolArguments', type: 'record<string, unknown>', required: false, description: 'Arguments passed to the external MCP tool.' },
+      { name: 'title', type: 'string', required: false, description: 'Optional canvas node title override.' },
+    ],
+    example: {
+      toolName: 'create_view',
+      transport: { type: 'http', url: 'https://mcp.excalidraw.com/mcp' },
+      toolArguments: { elements: '[]' },
+      title: 'Excalidraw Diagram',
+    },
+    notes: [
+      'For Excalidraw specifically, prefer canvas_add_diagram because it fills in the built-in transport, toolName, and checkpoint wiring.',
+      'The CLI convenience command `external-app add --kind excalidraw` maps to this built-in Excalidraw preset; MCP canvas_open_mcp_app is the lower-level transport form.',
+    ],
+  },
   {
     type: 'group',
     kind: 'node',
     description: 'Canvas group frame.',
     endpoint: '/api/canvas/group',
+    mcpTool: 'canvas_create_group',
     fields: [
       { name: 'title', type: 'string', required: false, description: 'Group title.' },
       { name: 'childIds', type: 'string[]', required: false, description: 'Initial child node IDs.' },
@@ -244,6 +278,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'virtual-node',
     description: 'Native structured UI panel rendered from a validated json-render spec.',
     endpoint: '/api/canvas/json-render',
+    mcpTool: 'canvas_add_json_render_node',
     fields: [
       { name: 'title', type: 'string', required: true, description: 'Rendered node title.' },
       { name: 'spec', type: 'JsonRenderSpec', required: true, description: 'Complete json-render spec.' },
@@ -276,6 +311,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'virtual-node',
     description: 'Native chart node backed by the json-render chart catalog.',
     endpoint: '/api/canvas/graph',
+    mcpTool: 'canvas_add_graph_node',
     fields: [
       {
         name: 'graphType',
@@ -325,6 +361,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'virtual-node',
     description: 'Bundled single-file HTML artifact that can open as an embedded canvas node.',
     endpoint: '/api/canvas/web-artifact',
+    mcpTool: 'canvas_build_web_artifact',
     fields: [
       { name: 'title', type: 'string', required: true, description: 'Artifact title used for default paths.' },
       { name: 'appTsx', type: 'string', required: true, description: 'Contents for src/App.tsx. The CLI also accepts piped contents via --stdin.', aliases: ['app-file', 'app-tsx'] },
@@ -349,6 +386,16 @@ function clone<T>(value: T): T {
   return JSON.parse(JSON.stringify(value)) as T;
 }
 
+function buildMcpNodeTypeRouting(nodeTypes: CanvasCreateTypeSchema[]): Record<string, string> {
+  const routing: Record<string, string> = {};
+  for (const entry of nodeTypes) {
+    if (typeof entry.mcpTool === 'string') {
+      routing[entry.type] = entry.mcpTool;
+    }
+  }
+  return routing;
+}
+
 export function describeCanvasSchema(): {
   ok: true;
   source: 'running-server';
@@ -364,13 +411,15 @@ export function describeCanvasSchema(): {
   mcp: {
     tools: string[];
     resources: string[];
+    nodeTypeRouting: Record<string, string>;
   };
 } {
+  const nodeTypes = clone(CANVAS_CREATE_TYPES);
   return {
     ok: true,
     source: 'running-server',
     version: readPackageVersion(),
-    nodeTypes: clone(CANVAS_CREATE_TYPES),
+    nodeTypes,
     jsonRender: {
       rootShape: {
         root: 'string',
@@ -388,10 +437,13 @@ export function describeCanvasSchema(): {
         'canvas_add_json_render_node',
         'canvas_add_graph_node',
         'canvas_build_web_artifact',
+        'canvas_open_mcp_app',
+        'canvas_create_group',
         'canvas_describe_schema',
         'canvas_validate_spec',
       ],
       resources: ['canvas://schema'],
+      nodeTypeRouting: buildMcpNodeTypeRouting(nodeTypes),
     },
   };
 }

package/src/server/server.ts

@@ -473,6 +473,10 @@ export async function evaluateCanvasAutomationWebView(expression: string): Promi
     ));
 }
 
+export function wrapCanvasAutomationScript(script: string): string {
+  return `(async () => {\n${script}\n})()`;
+}
+
 export async function resizeCanvasAutomationWebView(
   width: number,
   height: number,
@@ -1501,6 +1505,12 @@ async function handleCanvasBuildWebArtifact(req: Request): Promise<Response> {
       bytes: result.fileSize,
       projectPath: result.projectPath,
       openedInCanvas: result.openedInCanvas,
+      // `id` is the canvas node id alias used by every other add-style
+      // response. It is only present when a canvas node was actually
+      // created (i.e. openInCanvas was not explicitly disabled). When
+      // there is no canvas node, the alias is intentionally omitted so
+      // consumers can `'id' in response` to detect the build-only case.
+      ...(typeof result.nodeId === 'string' ? { id: result.nodeId } : {}),
       nodeId: result.nodeId,
       url: result.url,
       metadata: result.metadata,
@@ -2383,10 +2393,10 @@ async function handleWorkbenchWebViewEvaluate(req: Request): Promise<Response> {
   if ((expression ? 1 : 0) + (script ? 1 : 0) !== 1) {
     return responseJson({
       ok: false,
-      error: 'Pass exactly one of "expression" (single JS expression) or "script" (multi-statement body, wrapped in an IIFE).',
+      error: 'Pass exactly one of "expression" (single JS expression) or "script" (multi-statement body, wrapped in an async IIFE).',
     }, 400);
   }
-  const source = script ? `(() => {\n${script}\n})()` : expression;
+  const source = script ? wrapCanvasAutomationScript(script) : expression;
 
   try {
     const value = await evaluateCanvasAutomationWebView(source);
@@ -2893,7 +2903,7 @@ async function handleSnapshotSave(req: Request): Promise<Response> {
   if (!name) return responseText('Missing snapshot name', 400);
   const snapshot = saveCanvasSnapshot(name);
   if (!snapshot) return responseText('Failed to save snapshot', 500);
-  return responseJson({ ok: true, snapshot });
+  return responseJson({ ok: true, id: snapshot.id, snapshot });
 }
 
 async function handleContextPinsUpdate(req: Request): Promise<Response> {