pmx-canvas 0.1.12 → 0.1.14

package/src/mcp/server.ts

@@ -25,7 +25,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { isAbsolute, relative, resolve } from 'node:path';
 import { z } from 'zod';
 import { canvasState, describeCanvasSchema, validateStructuredCanvasPayload } from '../server/index.js';
-import { createCanvasAccess, type CanvasAccess } from './canvas-access.js';
+import { createCanvasAccess, refreshCanvasAccess, type CanvasAccess } from './canvas-access.js';
 import { serializeNodeForAgentContext } from '../server/agent-context.js';
 import { wrapCanvasAutomationScript } from '../server/server.js';
 import { buildSpatialContext, findNeighborhoods } from '../server/spatial-analysis.js';
@@ -34,7 +34,8 @@ import { listBundledSkills, readBundledSkill } from '../server/bundled-skills.js
 
 let canvas: CanvasAccess | null = null;
 let resourceNotificationServer: McpServer | null = null;
-let resourceNotificationsStarted = false;
+let localResourceNotificationsStarted = false;
+let remoteResourceNotificationsBaseUrl: string | null = null;
 
 const jsonRenderSpecSchema = z.union([
   z.object({
@@ -78,6 +79,8 @@ function safeWorkspacePath(pathLike: string): string {
 async function ensureCanvas(): Promise<CanvasAccess> {
   if (!canvas) {
     canvas = await createCanvasAccess();
+  } else {
+    canvas = await refreshCanvasAccess(canvas);
   }
   startResourceNotifications(canvas);
   return canvas;
@@ -139,16 +142,20 @@ async function watchRemoteCanvasEvents(baseUrl: string): Promise<void> {
 }
 
 function startResourceNotifications(c: CanvasAccess): void {
-  if (resourceNotificationsStarted) return;
   const server = resourceNotificationServer;
   if (!server) return;
-  resourceNotificationsStarted = true;
 
   if (c.remoteBaseUrl) {
-    void watchRemoteCanvasEvents(c.remoteBaseUrl);
+    if (remoteResourceNotificationsBaseUrl !== c.remoteBaseUrl) {
+      remoteResourceNotificationsBaseUrl = c.remoteBaseUrl;
+      void watchRemoteCanvasEvents(c.remoteBaseUrl);
+    }
     return;
   }
 
+  if (localResourceNotificationsStarted) return;
+  localResourceNotificationsStarted = true;
+
   canvasState.onChange((type) => {
     sendCanvasResourceNotifications(type);
   });
@@ -184,6 +191,19 @@ function buildSummaryFromLayout(layout: Awaited<ReturnType<CanvasAccess['getLayo
   };
 }
 
+function buildSnapshotRestoreSummary(layout: Awaited<ReturnType<CanvasAccess['getLayout']>>): Record<string, unknown> {
+  const nodesByType: Record<string, number> = {};
+  for (const node of layout.nodes) {
+    nodesByType[node.type] = (nodesByType[node.type] ?? 0) + 1;
+  }
+  return {
+    nodeCount: layout.nodes.length,
+    edgeCount: layout.edges.length,
+    nodesByType,
+    viewport: layout.viewport,
+  };
+}
+
 export async function startMcpServer(): Promise<void> {
   const server = new McpServer({
     name: 'pmx-canvas',
@@ -241,6 +261,12 @@ export async function startMcpServer(): Promise<void> {
       width: z.number().optional().describe('Width in pixels (default: 720)'),
       height: z.number().optional().describe('Height in pixels (default: 600)'),
       strictSize: z.boolean().optional().describe('Keep explicit width/height fixed and scroll overflowing content instead of browser auto-fitting'),
+      toolName: z.string().optional().describe('Trace node tool or operation label'),
+      category: z.string().optional().describe('Trace node category: mcp, file, subagent, or other'),
+      status: z.string().optional().describe('Trace node status: running, success, or failed'),
+      duration: z.string().optional().describe('Trace node duration badge text'),
+      resultSummary: z.string().optional().describe('Trace node result summary'),
+      error: z.string().optional().describe('Trace node error message'),
     },
     async (input) => {
       const c = await ensureCanvas();
@@ -283,11 +309,13 @@ export async function startMcpServer(): Promise<void> {
       toolName: z.string().describe('Tool name on the external MCP server'),
       serverName: z.string().optional().describe('Optional display name for the external MCP server'),
       toolArguments: z.record(z.string(), z.unknown()).optional().describe('Arguments passed to the external tool call'),
+      nodeId: z.string().optional().describe('Existing mcp-app node ID to update in place instead of creating a new node.'),
       title: z.string().optional().describe('Optional canvas node title override'),
       x: z.number().optional().describe('X position (auto-placed if omitted)'),
       y: z.number().optional().describe('Y position (auto-placed if omitted)'),
       width: z.number().optional().describe('Width in pixels (default: 720)'),
       height: z.number().optional().describe('Height in pixels (default: 500)'),
+      timeoutMs: z.number().optional().describe('Optional MCP request timeout in milliseconds for cold external app servers'),
       transport: z.union([
         z.object({
           type: z.literal('stdio'),
@@ -311,11 +339,13 @@ export async function startMcpServer(): Promise<void> {
           toolName: input.toolName,
           ...(typeof input.serverName === 'string' ? { serverName: input.serverName } : {}),
           ...(input.toolArguments ? { toolArguments: input.toolArguments } : {}),
+          ...(typeof input.nodeId === 'string' ? { nodeId: input.nodeId } : {}),
           ...(typeof input.title === 'string' ? { title: input.title } : {}),
           ...(typeof input.x === 'number' ? { x: input.x } : {}),
           ...(typeof input.y === 'number' ? { y: input.y } : {}),
           ...(typeof input.width === 'number' ? { width: input.width } : {}),
           ...(typeof input.height === 'number' ? { height: input.height } : {}),
+          ...(typeof input.timeoutMs === 'number' ? { timeoutMs: input.timeoutMs } : {}),
         });
         return {
           content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
@@ -337,27 +367,37 @@ export async function startMcpServer(): Promise<void> {
         z.string().describe('JSON array string of Excalidraw elements'),
         z.array(z.record(z.string(), z.unknown())).describe('Array of Excalidraw elements'),
       ]).describe('Excalidraw elements to render. See https://github.com/excalidraw/excalidraw-mcp for the element format.'),
+      nodeId: z.string().optional().describe('Existing Excalidraw mcp-app node ID to update in place instead of creating a new node.'),
       title: z.string().optional().describe('Optional canvas node title override'),
       x: z.number().optional().describe('X position (auto-placed if omitted)'),
       y: z.number().optional().describe('Y position (auto-placed if omitted)'),
       width: z.number().optional().describe('Width in pixels (default: 720)'),
       height: z.number().optional().describe('Height in pixels (default: 500)'),
+      timeoutMs: z.number().optional().describe('Optional MCP request timeout in milliseconds for Excalidraw cold starts. Client-side MCP hosts may still enforce their own total request timeout.'),
     },
-    async (input) => {
+    async (input, extra) => {
       const c = await ensureCanvas();
       try {
         const result = await c.addDiagram({
           elements: input.elements,
+          ...(typeof input.nodeId === 'string' ? { nodeId: input.nodeId } : {}),
           ...(typeof input.title === 'string' ? { title: input.title } : {}),
           ...(typeof input.x === 'number' ? { x: input.x } : {}),
           ...(typeof input.y === 'number' ? { y: input.y } : {}),
           ...(typeof input.width === 'number' ? { width: input.width } : {}),
           ...(typeof input.height === 'number' ? { height: input.height } : {}),
+          ...(typeof input.timeoutMs === 'number' ? { timeoutMs: input.timeoutMs } : {}),
         });
         return {
           content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
         };
       } catch (error) {
+        if (extra.signal.aborted) {
+          return {
+            content: [{ type: 'text', text: 'canvas_add_diagram was cancelled by the MCP client before Excalidraw finished. Retry with a higher client request timeout and pass timeoutMs to PMX Canvas for the downstream Excalidraw call.' }],
+            isError: true,
+          };
+        }
         return {
           content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }],
           isError: true,
@@ -463,7 +503,7 @@ export async function startMcpServer(): Promise<void> {
   // ── canvas_build_web_artifact ───────────────────────────────
   server.tool(
     'canvas_build_web_artifact',
-    'Build a bundled single-file HTML web artifact from React/Tailwind source files using the bundled web-artifacts-builder skill scripts. MCP callers pass source content in appTsx (the CLI app-file flag reads a file before calling this path). Builds commonly take 45-60s on cold workspaces; use a long client timeout. Optionally opens the generated artifact as an embedded node on the canvas. Read canvas://skills/web-artifacts-builder for the full workflow, stack, and anti-slop design guidelines before calling.',
+    'Build a bundled single-file HTML web artifact from React/Tailwind source files using the bundled web-artifacts-builder skill scripts. MCP callers pass source content in appTsx (the CLI app-file flag reads a file before calling this path). Builds can exceed default 60s MCP client timeouts on cold workspaces; set a long client timeout or retry with the same projectPath/outputPath if the client times out. Optionally opens the generated artifact as an embedded node on the canvas. Read canvas://skills/web-artifacts-builder for the full workflow, stack, and anti-slop design guidelines before calling.',
     {
       title: z.string().describe('Artifact title used for default project and output paths'),
       appTsx: z.string().describe('Contents for src/App.tsx'),
@@ -514,6 +554,7 @@ export async function startMcpServer(): Promise<void> {
               bytes: result.fileSize,
               projectPath: result.projectPath,
               openedInCanvas: result.openedInCanvas,
+              completedAt: result.completedAt,
               // `id` only present when a canvas node was actually created.
               // See the matching block in src/server/server.ts handleCanvasBuildWebArtifact.
               ...(typeof result.nodeId === 'string' ? { id: result.nodeId } : {}),
@@ -1453,7 +1494,7 @@ export async function startMcpServer(): Promise<void> {
 
   server.tool(
     'canvas_batch',
-    'Run a batch of canvas operations with optional assigned references. Supports node.add, node.update, graph.add, edge.add, group.create, group.add, group.remove, pin.set/add/remove, snapshot.save, and arrange.',
+    'Run a non-atomic batch of canvas operations with optional assigned references. Use assign to name a result, then reference it later as "$name" for the created node id or "$name.id" for a specific result field. On failure, earlier successful operations remain applied and the response includes ok:false, failedIndex, error, results, and refs. Supports node.add, node.update, graph.add, edge.add, group.create, group.add, group.remove, pin.set/add/remove, snapshot.save, and arrange.',
     {
       operations: z.array(z.object({
         op: z.string().describe('Operation name, e.g. "node.add" or "edge.add"'),
@@ -1568,8 +1609,9 @@ export async function startMcpServer(): Promise<void> {
       if (!result.ok) {
         return { content: [{ type: 'text', text: JSON.stringify({ ok: false, error: 'Snapshot not found' }) }] };
       }
+      const layout = await c.getLayout();
       return {
-        content: [{ type: 'text', text: JSON.stringify({ ok: true, layout: serializeCanvasLayout(await c.getLayout()) }) }],
+        content: [{ type: 'text', text: JSON.stringify({ ok: true, restored: input.id, summary: buildSnapshotRestoreSummary(layout) }, null, 2) }],
       };
     },
   );

package/src/server/canvas-operations.ts

@@ -76,6 +76,12 @@ interface CanvasAddNodeInput {
   title?: string;
   content?: string;
   data?: Record<string, unknown>;
+  toolName?: string;
+  category?: string;
+  status?: string;
+  duration?: string;
+  resultSummary?: string;
+  error?: string;
   x?: number;
   y?: number;
   width?: number;
@@ -109,6 +115,7 @@ interface CanvasNodeLookupInput {
 }
 
 const MAX_CONTEXT_PINS = 20;
+const TRACE_DATA_FIELDS = ['toolName', 'category', 'status', 'duration', 'resultSummary', 'error'] as const;
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -757,10 +764,23 @@ function buildWebpageNodeData(input: CanvasAddNodeInput): Record<string, unknown
   };
 }
 
+function normalizeTraceNodeData(input: CanvasAddNodeInput): Record<string, unknown> {
+  const data: Record<string, unknown> = { ...(input.data ?? {}) };
+  for (const field of TRACE_DATA_FIELDS) {
+    const value = input[field];
+    if (typeof value === 'string') data[field] = value;
+  }
+  if (input.title) data.title = input.title;
+  if (input.content) data.content = input.content;
+  if (input.strictSize) data.strictSize = true;
+  return data;
+}
+
 function buildNodeData(input: CanvasAddNodeInput): Record<string, unknown> {
   if (input.type === 'file') return buildFileNodeData(input);
   if (input.type === 'image') return buildImageNodeData(input);
   if (input.type === 'webpage') return buildWebpageNodeData(input);
+  if (input.type === 'trace') return normalizeTraceNodeData(input);
   return {
     ...(input.data ?? {}),
     ...(input.title ? { title: input.title } : {}),
@@ -769,6 +789,21 @@ function buildNodeData(input: CanvasAddNodeInput): Record<string, unknown> {
   };
 }
 
+export function mergeTraceNodeDataFields(
+  base: Record<string, unknown>,
+  input: Record<string, unknown>,
+): Record<string, unknown> {
+  const next: Record<string, unknown> = { ...base };
+  for (const field of TRACE_DATA_FIELDS) {
+    if (typeof input[field] === 'string') next[field] = input[field];
+  }
+  return next;
+}
+
+export function hasTraceNodeDataFields(input: Record<string, unknown>): boolean {
+  return TRACE_DATA_FIELDS.some((field) => typeof input[field] === 'string');
+}
+
 export function scheduleCodeGraphRecompute(onComplete?: () => void): void {
   if (codeGraphTimer) clearTimeout(codeGraphTimer);
   codeGraphTimer = setTimeout(() => {
@@ -1373,6 +1408,7 @@ function resolveBatchRefs(value: unknown, refs: Record<string, unknown>): unknow
   if (typeof value === 'string' && value.startsWith('$')) {
     const path = value.slice(1).split('.');
     let current: unknown = refs[path[0] ?? ''];
+    if (path.length === 1 && isPlainRecord(current) && typeof current.id === 'string') return current.id;
     for (const segment of path.slice(1)) {
       if (!isPlainRecord(current) && !Array.isArray(current)) return undefined;
       current = (current as Record<string, unknown>)[segment];

package/src/server/canvas-schema.ts

@@ -140,11 +140,18 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     fields: [
       { name: 'title', type: 'string', required: false, description: 'Optional title.' },
       { name: 'content', type: 'string', required: false, description: 'Trace summary.' },
+      { name: 'toolName', type: 'string', required: false, description: 'Tool or operation label shown in the trace pill; defaults to title.' },
+      { name: 'category', type: 'string', required: false, description: 'Trace category color key: mcp, file, subagent, or other.' },
+      { name: 'status', type: 'string', required: false, description: 'Trace status: running, success, or failed.' },
+      { name: 'duration', type: 'string', required: false, description: 'Optional duration badge text.' },
+      { name: 'resultSummary', type: 'string', required: false, description: 'Short trace result summary; defaults to content.' },
+      { name: 'error', type: 'string', required: false, description: 'Short error message shown in failed traces.' },
     ],
     example: {
       type: 'trace',
       title: 'Execution Trace',
       content: 'Canvas actions and tool events.',
+      status: 'success',
     },
   },
   {
@@ -378,12 +385,16 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
       { name: 'openInCanvas', type: 'boolean', required: false, description: 'Open the built artifact on the canvas (default true).' },
       { name: 'includeLogs', type: 'boolean', required: false, description: 'Include raw build stdout/stderr in the response (default false).' },
       { name: 'deps', type: 'string[]', required: false, description: 'Optional npm dependencies to add before bundling, e.g. recharts.', aliases: ['deps'] },
+      { name: 'timeoutMs', type: 'number', required: false, description: 'Build command timeout in milliseconds. This controls subprocess timeout, not the MCP client request timeout.' },
     ],
     example: {
       title: 'Dashboard Artifact',
       appTsx: 'export default function App() { return <main>Artifact</main>; }',
       indexCss: 'body { background: #123456; color: white; }',
     },
+    notes: [
+      'Cold builds can exceed default 60s MCP client timeouts; configure a longer MCP call timeout or retry with the same projectPath/outputPath if the first call times out.',
+    ],
   },
 ];
 

package/src/server/diagram-presets.ts

@@ -43,11 +43,13 @@ export const EXCALIDRAW_MCP_TRANSPORT: ExternalMcpTransportConfig = {
 
 export interface DiagramPresetOpenInput {
   elements: unknown;
+  nodeId?: string;
   title?: string;
   x?: number;
   y?: number;
   width?: number;
   height?: number;
+  timeoutMs?: number;
 }
 
 export interface ExcalidrawOpenMcpAppInput {
@@ -55,11 +57,13 @@ export interface ExcalidrawOpenMcpAppInput {
   toolName: string;
   serverName: string;
   toolArguments: { elements: string };
+  nodeId?: string;
   title?: string;
   x?: number;
   y?: number;
   width?: number;
   height?: number;
+  timeoutMs?: number;
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -111,6 +115,21 @@ function finiteNumber(value: unknown): number | null {
   return typeof value === 'number' && Number.isFinite(value) ? value : null;
 }
 
+function positiveFiniteNumber(value: unknown): number | null {
+  const num = finiteNumber(value);
+  return num !== null && num > 0 ? num : null;
+}
+
+function labelFromBoundText(element: Record<string, unknown>): Record<string, unknown> | null {
+  const text = typeof element.text === 'string' ? element.text : '';
+  if (text.trim().length === 0) return null;
+  const fontSize = positiveFiniteNumber(element.fontSize);
+  return {
+    text,
+    ...(fontSize ? { fontSize } : {}),
+  };
+}
+
 function elementHasCameraUpdate(elements: Array<Record<string, unknown>>): boolean {
   return elements.some((element) => element.type === 'cameraUpdate');
 }
@@ -134,61 +153,38 @@ function normalizeExcalidrawBoundText(elements: Array<Record<string, unknown>>):
   }
 
   let changed = false;
-  const boundElementIdsByContainer = new Map<string, Set<string>>();
-  const labelByContainer = new Map<string, Record<string, unknown>>();
-  const textIdsConvertedToLabels = new Set<string>();
+  const labelsByContainer = new Map<string, Record<string, unknown>>();
 
   for (const element of elements) {
     if (element.type !== 'text' || typeof element.id !== 'string' || typeof element.containerId !== 'string') continue;
     const container = elementsById.get(element.containerId);
-    if (!container) continue;
-    const ids = boundElementIdsByContainer.get(element.containerId) ?? new Set<string>();
-    ids.add(element.id);
-    boundElementIdsByContainer.set(element.containerId, ids);
-    const text = typeof element.text === 'string' ? element.text.trim() : '';
-    if (!isRecord(container.label) && text.length > 0) {
-      labelByContainer.set(element.containerId, {
-        text,
-        ...(typeof element.fontSize === 'number' && Number.isFinite(element.fontSize) ? { fontSize: element.fontSize } : {}),
-      });
-      textIdsConvertedToLabels.add(element.id);
-    }
+    if (!container || (container.type !== 'rectangle' && container.type !== 'ellipse' && container.type !== 'diamond')) continue;
+    const label = labelFromBoundText(element);
+    if (!label) continue;
+    labelsByContainer.set(element.containerId, label);
   }
 
-  const normalized = elements.flatMap<Record<string, unknown>>((element) => {
-    if (typeof element.id === 'string' && textIdsConvertedToLabels.has(element.id)) {
-      changed = true;
-      return [];
+  const normalized: Array<Record<string, unknown>> = [];
+  for (const element of elements) {
+    if (element.type === 'text' && typeof element.containerId === 'string') {
+      if (labelsByContainer.has(element.containerId)) {
+        changed = true;
+        continue;
+      }
+    }
+
+    if (typeof element.id !== 'string' || !labelsByContainer.has(element.id)) {
+      normalized.push(element);
+      continue;
     }
-    if (typeof element.id !== 'string') return element;
-    const boundTextIds = boundElementIdsByContainer.get(element.id);
-    const label = labelByContainer.get(element.id);
-    if ((!boundTextIds || boundTextIds.size === 0) && !label) return element;
-
-    const existing = Array.isArray(element.boundElements)
-      ? element.boundElements.filter(isRecord)
-      : [];
-    const remainingExisting = existing.filter((boundElement) => {
-      return !(boundElement.type === 'text' && typeof boundElement.id === 'string' && textIdsConvertedToLabels.has(boundElement.id));
-    });
-    const existingTextIds = new Set(
-      remainingExisting
-        .filter((boundElement) => boundElement.type === 'text' && typeof boundElement.id === 'string')
-        .map((boundElement) => boundElement.id as string),
-    );
-    const missing = [...(boundTextIds ?? [])]
-      .filter((id) => !textIdsConvertedToLabels.has(id) && !existingTextIds.has(id));
-    if (missing.length === 0 && !label && remainingExisting.length === existing.length) return element;
 
     changed = true;
-    return {
-      ...element,
-      ...(label ? { label } : {}),
-      ...(remainingExisting.length > 0 || missing.length > 0
-        ? { boundElements: [...remainingExisting, ...missing.map((id) => ({ type: 'text', id }))] }
-        : {}),
-    };
-  });
+    const { boundElements: _boundElements, ...container } = element;
+    normalized.push({
+      ...container,
+      label: labelsByContainer.get(element.id),
+    });
+  }
 
   return changed ? normalized : elements;
 }
@@ -355,10 +351,12 @@ export function buildExcalidrawOpenMcpAppInput(input: DiagramPresetOpenInput): E
     serverName: EXCALIDRAW_SERVER_NAME,
     toolArguments: { elements },
   };
+  if (typeof input.nodeId === 'string' && input.nodeId.trim().length > 0) out.nodeId = input.nodeId.trim();
   if (typeof input.title === 'string' && input.title.trim().length > 0) out.title = input.title.trim();
   if (typeof input.x === 'number' && Number.isFinite(input.x)) out.x = input.x;
   if (typeof input.y === 'number' && Number.isFinite(input.y)) out.y = input.y;
   if (typeof input.width === 'number' && Number.isFinite(input.width)) out.width = input.width;
   if (typeof input.height === 'number' && Number.isFinite(input.height)) out.height = input.height;
+  if (typeof input.timeoutMs === 'number' && Number.isFinite(input.timeoutMs) && input.timeoutMs > 0) out.timeoutMs = input.timeoutMs;
   return out;
 }

package/src/server/index.ts

@@ -33,6 +33,8 @@ import {
   ungroupCanvasNodes,
   validateCanvasNodePatch,
   hasStructuredNodeUpdateFields,
+  hasTraceNodeDataFields,
+  mergeTraceNodeDataFields,
 } from './canvas-operations.js';
 import { validateCanvasLayout } from './canvas-validation.js';
 import { describeCanvasSchema, validateStructuredCanvasPayload } from './canvas-schema.js';
@@ -158,6 +160,12 @@ export class PmxCanvas extends EventEmitter {
     type: CanvasNodeState['type'];
     title?: string;
     content?: string;
+    toolName?: string;
+    category?: string;
+    status?: string;
+    duration?: string;
+    resultSummary?: string;
+    error?: string;
     x?: number;
     y?: number;
     width?: number;
@@ -243,9 +251,10 @@ export class PmxCanvas extends EventEmitter {
       patch.title !== undefined ||
       patch.content !== undefined ||
       typeof patch.arrangeLocked === 'boolean' ||
-      typeof patch.strictSize === 'boolean'
+      typeof patch.strictSize === 'boolean' ||
+      (existing.type === 'trace' && hasTraceNodeDataFields(patch))
     ) {
-      resolvedPatch.data = {
+      const nextData = {
         ...existing.data,
         ...(patch.data && typeof patch.data === 'object' && !Array.isArray(patch.data) ? patch.data : {}),
         ...(typeof patch.title === 'string' ? { title: patch.title } : {}),
@@ -253,6 +262,9 @@ export class PmxCanvas extends EventEmitter {
         ...(typeof patch.arrangeLocked === 'boolean' ? { arrangeLocked: patch.arrangeLocked } : {}),
         ...(typeof patch.strictSize === 'boolean' ? { strictSize: patch.strictSize } : {}),
       };
+      resolvedPatch.data = existing.type === 'trace'
+        ? mergeTraceNodeDataFields(nextData, patch)
+        : nextData;
     }
 
     const error = validateCanvasNodePatch({
@@ -520,21 +532,36 @@ export class PmxCanvas extends EventEmitter {
     transport: ExternalMcpTransportConfig;
     toolName: string;
     toolArguments?: Record<string, unknown>;
+    nodeId?: string;
     serverName?: string;
     title?: string;
     x?: number;
     y?: number;
     width?: number;
     height?: number;
+    timeoutMs?: number;
   }): Promise<{ ok: true; id?: string; nodeId: string | null; toolCallId: string; sessionId: string; resourceUri: string }> {
+    const targetNode = input.nodeId ? canvasState.getNode(input.nodeId) : undefined;
+    if (input.nodeId && !targetNode) {
+      throw new Error(`Node "${input.nodeId}" not found.`);
+    }
+    if (targetNode && (targetNode.type !== 'mcp-app' || targetNode.data.mode !== 'ext-app')) {
+      throw new Error(`Node "${input.nodeId}" is not an external app node.`);
+    }
+
     const opened = await openExternalMcpApp({
       transport: input.transport,
       toolName: input.toolName,
       ...(input.toolArguments ? { toolArguments: input.toolArguments } : {}),
       ...(input.serverName ? { serverName: input.serverName } : {}),
+      ...(typeof input.timeoutMs === 'number' ? { timeoutMs: input.timeoutMs } : {}),
     });
     const toolCallId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
-    const nodeIdSeed = `ext-app-${toolCallId}`;
+    const previousSessionId = targetNode?.data.appSessionId;
+    if (typeof previousSessionId === 'string' && previousSessionId.trim().length > 0) {
+      closeMcpAppSession(previousSessionId);
+    }
+    const nodeIdSeed = input.nodeId ?? `ext-app-${toolCallId}`;
     const toolResult = isExcalidrawCreateView(opened.serverName, opened.toolName)
       ? ensureExcalidrawCheckpointId(opened.toolResult, nodeIdSeed)
       : opened.toolResult;
@@ -566,7 +593,7 @@ export class PmxCanvas extends EventEmitter {
       success: toolResult.isError !== true,
       result: toolResult,
     });
-    const nodeId = this.findCanvasExtAppNodeId(toolCallId);
+    const nodeId = input.nodeId ?? this.findCanvasExtAppNodeId(toolCallId);
     return {
       ok: true,
       ...(nodeId ? { id: nodeId } : {}),

package/src/server/mcp-app-runtime.ts

@@ -12,6 +12,7 @@ import type {
   TextResourceContents,
   Tool,
 } from '@modelcontextprotocol/sdk/types.js';
+import type { RequestOptions } from '@modelcontextprotocol/sdk/shared/protocol.js';
 import {
   EXTENSION_ID,
   RESOURCE_MIME_TYPE,
@@ -47,6 +48,7 @@ export interface OpenMcpAppInput {
   toolName: string;
   toolArguments?: Record<string, unknown>;
   serverName?: string;
+  timeoutMs?: number;
 }
 
 export interface OpenMcpAppResult {
@@ -184,6 +186,12 @@ function normalizeServerName(raw: string | undefined, transport: ExternalMcpTran
   return trimmed.length > 0 ? trimmed : defaultServerName(transport);
 }
 
+function requestOptions(timeoutMs: number | undefined): RequestOptions | undefined {
+  return typeof timeoutMs === 'number' && Number.isFinite(timeoutMs) && timeoutMs > 0
+    ? { timeout: timeoutMs }
+    : undefined;
+}
+
 function buildTransport(config: ExternalMcpTransportConfig): RuntimeTransport {
   if (config.type === 'http') {
     return new StreamableHTTPClientTransport(new URL(config.url), {
@@ -209,15 +217,16 @@ function buildTransport(config: ExternalMcpTransportConfig): RuntimeTransport {
 async function createSession(
   transportConfig: ExternalMcpTransportConfig,
   serverName?: string,
+  timeoutMs?: number,
 ): Promise<McpAppSession> {
   const transport = buildTransport(transportConfig);
   const client = new Client(
     { name: 'pmx-canvas-app-host', version: '0.1.0' },
     { capabilities: clientCapabilities },
   );
-  await client.connect(transport);
+  await client.connect(transport, requestOptions(timeoutMs));
 
-  const toolList = await client.listTools();
+  const toolList = await client.listTools(undefined, requestOptions(timeoutMs));
   const session: McpAppSession = {
     id: randomId('mcp-app-session'),
     serverName: normalizeServerName(serverName, transportConfig),
@@ -350,7 +359,8 @@ function prepareResourceHtml(html: string, meta: McpUiResourceMeta | undefined):
 }
 
 export async function openMcpApp(input: OpenMcpAppInput): Promise<OpenMcpAppResult> {
-  const session = await createSession(input.transport, input.serverName);
+  const options = requestOptions(input.timeoutMs);
+  const session = await createSession(input.transport, input.serverName, input.timeoutMs);
   try {
     const tool = await findTool(session, input.toolName);
     const resourceUri = getToolUiResourceUri(tool);
@@ -362,9 +372,9 @@ export async function openMcpApp(input: OpenMcpAppInput): Promise<OpenMcpAppResu
     const rawToolResult = await session.client.callTool({
       name: tool.name,
       arguments: toolInput,
-    });
+    }, undefined, options);
     const toolResult = normalizeExtAppToolResult({ result: rawToolResult });
-    const readResult = await session.client.readResource({ uri: resourceUri });
+    const readResult = await session.client.readResource({ uri: resourceUri }, options);
     const resourceMeta = resourceMetaFromReadResult(readResult);
     const html = prepareResourceHtml(htmlContentFromReadResult(readResult, resourceUri), resourceMeta);