@tuongaz/seeflow 0.1.77 → 0.1.81

package/src/mcp.ts

@@ -2,10 +2,19 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import {
   CallToolRequestSchema,
   type CallToolResult,
+  ListResourcesRequestSchema,
   ListToolsRequestSchema,
+  ReadResourceRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 import { type ZodTypeAny, z } from 'zod';
 import { zodToJsonSchema } from 'zod-to-json-schema';
+import {
+  CANVAS_RESOURCE_MIME,
+  CANVAS_RESOURCE_URI,
+  type CanvasWidgetState,
+  canvasMeta,
+  readCanvasHtml,
+} from './mcp-ui.ts';
 import {
   ConnectorPatchBodySchema,
   CreateProjectBodySchema,
@@ -27,8 +36,48 @@ import type { FlowWatcher } from './watcher.ts';
 export interface CreateMcpServerOptions {
   registry: Registry;
   watcher?: FlowWatcher;
+  /** Per-process token forwarded to the MCP App iframe via
+   *  `_meta['openai/widgetState'].backendToken` so cross-origin requests
+   *  from the sandboxed (`Origin: null`) iframe can carry it as
+   *  `X-Seeflow-Token`. Same value as the one passed to
+   *  `createApp({ token })`. Wired into canvas-bearing tool handlers; non-
+   *  canvas tools ignore it. */
+  token?: string;
+  /** Reachable loopback URL of the studio HTTP backend (e.g.
+   *  `http://127.0.0.1:54321`). The MCP App iframe uses it as the REST
+   *  base URL to load flow data. When unset, canvas-bearing tools omit
+   *  `_meta` entirely so non-Apps hosts still work (the iframe can't
+   *  reach a backend without both `httpUrl` and `token`). */
+  httpUrl?: string;
 }
 
+/** Subset of `CreateMcpServerOptions` that the canvas-bearing tool
+ *  handlers need at call time. Built once in `createMcpServer` and
+ *  passed into `buildTools` so the closures inside each handler can
+ *  attach `_meta` without re-reading the outer options. */
+interface ToolContext {
+  registry: Registry;
+  token?: string;
+  httpUrl?: string;
+}
+
+// Distributive Omit so the discriminated union arms stay distinct after
+// stripping the host-only `backendUrl` / `backendToken` keys.
+type DistOmit<T, K extends keyof never> = T extends unknown ? Omit<T, K> : never;
+type CanvasWidgetStateInput = DistOmit<CanvasWidgetState, 'backendUrl' | 'backendToken'>;
+
+/** Build the `_meta` block for a canvas-bearing tool result, when both
+ *  `httpUrl` and `token` are configured. Returns `undefined` if either
+ *  is missing (e.g. proxy mode in `mcp-shim.ts`, or tests that bypass
+ *  the shim) so non-Apps callers still get a plain JSON-only result. */
+const canvasMetaFor = (
+  ctx: ToolContext,
+  state: CanvasWidgetStateInput,
+): Record<string, unknown> | undefined => {
+  if (!ctx.httpUrl || !ctx.token) return undefined;
+  return canvasMeta({ ...state, backendUrl: ctx.httpUrl, backendToken: ctx.token });
+};
+
 // Tools are pushed into this in-memory list inside `createMcpServer`. Each
 // tool has a tiny one-sentence description, a JSON Schema for its input
 // (built from existing Zod schemas via zod-to-json-schema where reuse is
@@ -56,9 +105,13 @@ const inputSchemaFromZod = (schema: ZodTypeAny): Record<string, unknown> => {
   return rest.type === 'object' ? rest : { type: 'object', ...rest };
 };
 
-const okResult = (value: unknown): CallToolResult => ({
-  content: [{ type: 'text', text: JSON.stringify(value) }],
-});
+const okResult = (value: unknown, meta?: Record<string, unknown>): CallToolResult => {
+  const result: CallToolResult = {
+    content: [{ type: 'text', text: JSON.stringify(value) }],
+  };
+  if (meta) result._meta = meta;
+  return result;
+};
 
 // Error payloads (e.g. 'unknown demo', 'Failed to write demo file') still say
 // "demo" so the strings match the REST handlers in api.ts byte-for-byte.
@@ -69,55 +122,84 @@ const errorResult = (text: string): CallToolResult => ({
   content: [{ type: 'text', text }],
 });
 
-// Most MCP tools take a single flowId argument. Defined inline as plain
-// JSON Schema (rather than a one-off Zod schema) because there's no REST
-// counterpart to share with.
-const FLOW_ID_INPUT_SCHEMA = {
+// Most flow-scoped MCP tools take { project, flow } to address a registered
+// flow. Defined inline as plain JSON Schema (rather than a one-off Zod
+// schema) because there's no REST counterpart to share with.
+const PROJECT_FLOW_PROPERTIES = {
+  project: {
+    type: 'string',
+    minLength: 1,
+    description: 'Project slug (e.g. `order-pipeline`) addressing a registered project.',
+  },
+  flow: {
+    type: 'string',
+    minLength: 1,
+    description: 'Flow slug within that project (e.g. `main` or `retry`).',
+  },
+} as const;
+
+const FLOW_PROJECT_INPUT_SCHEMA = {
   type: 'object',
-  properties: { flowId: { type: 'string', minLength: 1 } },
-  required: ['flowId'],
+  properties: { ...PROJECT_FLOW_PROPERTIES },
+  required: ['project', 'flow'],
   additionalProperties: false,
 } as const;
 
-const requireFlowId = (args: unknown): { flowId: string } | { error: string } => {
+const requireProjectFlow = (
+  args: unknown,
+): { project: string; flow: string } | { error: string } => {
   if (!args || typeof args !== 'object' || Array.isArray(args)) {
-    return { error: 'Invalid arguments: expected an object with flowId' };
+    return { error: 'Invalid arguments: expected an object with project + flow' };
   }
-  const { flowId } = args as { flowId?: unknown };
-  if (typeof flowId !== 'string' || flowId.length === 0) {
-    return { error: 'Invalid arguments: flowId must be a non-empty string' };
+  const { project, flow } = args as { project?: unknown; flow?: unknown };
+  if (typeof project !== 'string' || project.length === 0) {
+    return { error: 'Invalid arguments: project must be a non-empty string' };
   }
-  return { flowId };
+  if (typeof flow !== 'string' || flow.length === 0) {
+    return { error: 'Invalid arguments: flow must be a non-empty string' };
+  }
+  return { project, flow };
 };
 
-// {flowId, nodeId} body shape shared by move + reorder + delete inputs.
-const FlowNodeIdBaseSchema = z.object({
-  flowId: z.string().min(1),
+// Project + flow slug pair used by every flow-scoped tool input as a Zod
+// envelope. Each field carries its own description so the JSON Schema
+// `tools/list` surfaces is self-documenting.
+const ProjectFlowSchema = z.object({
+  project: z
+    .string()
+    .min(1)
+    .describe('Project slug (e.g. `order-pipeline`) addressing a registered project.'),
+  flow: z.string().min(1).describe('Flow slug within that project (e.g. `main` or `retry`).'),
+});
+
+// {project, flow, nodeId} body shape shared by move + reorder + delete inputs.
+const FlowNodeIdBaseSchema = ProjectFlowSchema.extend({
   nodeId: z.string().min(1),
 });
 
-// add_node input: { flowId, node: <node payload> }. The inner `node` object is
-// loose here (additionalProperties=true via passthrough) because ResolvedFlowSchema
-// runs the full validation server-side after the new node is merged in.
-const AddNodeInputSchema = z.object({
-  flowId: z.string().min(1),
+// add_node input: { project, flow, node: <node payload> }. The inner `node`
+// object is loose here (additionalProperties=true via passthrough) because
+// ResolvedFlowSchema runs the full validation server-side after the new
+// node is merged in.
+const AddNodeInputSchema = ProjectFlowSchema.extend({
   node: z.record(z.unknown()),
 });
 
-// add_bulk input: { flowId, nodes?: [...], connectors?: [...] }. Same loose
-// per-item shape as add_node / add_connector — ResolvedFlowSchema runs once
-// over the whole merged graph server-side after the batch lands. The
+// add_bulk input: { project, flow, nodes?: [...], connectors?: [...] }. Same
+// loose per-item shape as add_node / add_connector — ResolvedFlowSchema runs
+// once over the whole merged graph server-side after the batch lands. The
 // 100-per-kind cap and "at least one non-empty" invariant come from
 // FlowBulkBodyShape + flowBulkNonEmpty (the unrefined object + reusable
 // predicate exported by operations.ts) so the JSON Schema the agent
 // introspects stays a clean object — not an intersection.
 const AddBulkInputSchema = FlowBulkBodyShape.extend({
-  flowId: z.string().min(1),
+  project: ProjectFlowSchema.shape.project,
+  flow: ProjectFlowSchema.shape.flow,
 }).refine(flowBulkNonEmpty, { message: FLOW_BULK_NON_EMPTY_MESSAGE });
 
 const DeleteNodeInputSchema = FlowNodeIdBaseSchema;
 
-// move_node input: { flowId, nodeId } extended with PositionBodySchema's
+// move_node input: { project, flow, nodeId } extended with PositionBodySchema's
 // { x, y } fields so agents see one flat schema.
 const MoveNodeInputSchema = FlowNodeIdBaseSchema.extend({
   x: PositionBodySchema.shape.x,
@@ -125,8 +207,9 @@ const MoveNodeInputSchema = FlowNodeIdBaseSchema.extend({
 });
 
 // reorder_node input: each branch of the existing ReorderBodySchema
-// discriminated union extended with flowId/nodeId. Keeps the discriminator
-// on `op` so the emitted JSON Schema is an oneOf the agent can introspect.
+// discriminated union extended with project/flow/nodeId. Keeps the
+// discriminator on `op` so the emitted JSON Schema is an oneOf the agent
+// can introspect.
 const ReorderNodeInputSchema = z.discriminatedUnion('op', [
   FlowNodeIdBaseSchema.extend({ op: z.literal('forward') }),
   FlowNodeIdBaseSchema.extend({ op: z.literal('backward') }),
@@ -138,40 +221,40 @@ const ReorderNodeInputSchema = z.discriminatedUnion('op', [
   }),
 ]);
 
-// patch_node input: { flowId, nodeId } merged with NodePatchBodySchema's
+// patch_node input: { project, flow, nodeId } merged with NodePatchBodySchema's
 // optional fields. .extend() on the strict body schema preserves strict
 // mode, so unknown top-level keys still trip the Zod parse before any disk
 // IO — matching the REST handler's "Invalid node patch body" 400 path.
 const PatchNodeInputSchema = NodePatchBodySchema.extend({
-  flowId: z.string().min(1),
+  project: ProjectFlowSchema.shape.project,
+  flow: ProjectFlowSchema.shape.flow,
   nodeId: z.string().min(1),
 });
 
-// add_connector input: { flowId, connector: <connector payload> }. The inner
-// `connector` object is loose (additionalProperties=true via z.record) because
-// ResolvedFlowSchema runs the full validation server-side after the new connector is
-// merged in (post-mutation parse catches dangling source/target refs and
-// kind-discriminator violations).
-const AddConnectorInputSchema = z.object({
-  flowId: z.string().min(1),
+// add_connector input: { project, flow, connector: <connector payload> }.
+// The inner `connector` object is loose (additionalProperties=true via
+// z.record) because ResolvedFlowSchema runs the full validation server-side
+// after the new connector is merged in (post-mutation parse catches dangling
+// source/target refs and kind-discriminator violations).
+const AddConnectorInputSchema = ProjectFlowSchema.extend({
   connector: z.record(z.unknown()),
 });
 
-// patch_connector input: { flowId, connectorId } merged with the strict
-// ConnectorPatchBodySchema. .extend() preserves strict mode so unknown
-// top-level keys trip the Zod parse before any IO — matching the REST
-// handler's "Invalid connector patch body" 400 path.
+// patch_connector input: { project, flow, connectorId } merged with the
+// strict ConnectorPatchBodySchema. .extend() preserves strict mode so
+// unknown top-level keys trip the Zod parse before any IO — matching the
+// REST handler's "Invalid connector patch body" 400 path.
 const PatchConnectorInputSchema = ConnectorPatchBodySchema.extend({
-  flowId: z.string().min(1),
+  project: ProjectFlowSchema.shape.project,
+  flow: ProjectFlowSchema.shape.flow,
   connectorId: z.string().min(1),
 });
 
-const DeleteConnectorInputSchema = z.object({
-  flowId: z.string().min(1),
+const DeleteConnectorInputSchema = ProjectFlowSchema.extend({
   connectorId: z.string().min(1),
 });
 
-const buildTools = (ops: Operations): McpTool[] => [
+const buildTools = (ops: Operations, ctx: ToolContext): McpTool[] => [
   {
     name: 'seeflow_list_flows',
     description: 'List every flow registered with the studio.',
@@ -314,15 +397,25 @@ const buildTools = (ops: Operations): McpTool[] => [
   },
   {
     name: 'seeflow_get_flow',
-    description: 'Get the full flow definition and on-disk state for a flowId.',
-    inputSchema: FLOW_ID_INPUT_SCHEMA,
+    description: 'Get the full flow definition and on-disk state for a (project, flow) pair.',
+    inputSchema: FLOW_PROJECT_INPUT_SCHEMA,
     handler: async (args) => {
-      const v = requireFlowId(args);
+      const v = requireProjectFlow(args);
       if ('error' in v) return errorResult(v.error);
-      const result = await ops.getFlow(v.flowId);
+      const flowSlug = `${v.project}/${v.flow}`;
+      const result = await ops.getFlow(flowSlug);
       switch (result.kind) {
-        case 'ok':
-          return okResult(result.data);
+        case 'ok': {
+          const entry = ctx.registry.resolve(flowSlug);
+          const meta = entry
+            ? canvasMetaFor(ctx, {
+                kind: 'navigate',
+                projectSlug: entry.projectSlug,
+                flowSlug: entry.flowSlug,
+              })
+            : undefined;
+          return okResult(result.data, meta);
+        }
         case 'notFound':
           return errorResult('not found');
         case 'fileNotFound':
@@ -336,14 +429,24 @@ const buildTools = (ops: Operations): McpTool[] => [
       "Get a flow's nodes + connectors without inlining per-node file-backed " +
       'content (`detail`, `html`). Cheap topology read — pair with seeflow_get_node ' +
       "when you need a specific node's long-form body.",
-    inputSchema: FLOW_ID_INPUT_SCHEMA,
+    inputSchema: FLOW_PROJECT_INPUT_SCHEMA,
     handler: async (args) => {
-      const v = requireFlowId(args);
+      const v = requireProjectFlow(args);
       if ('error' in v) return errorResult(v.error);
-      const result = await ops.getFlowGraph(v.flowId);
+      const flowSlug = `${v.project}/${v.flow}`;
+      const result = await ops.getFlowGraph(flowSlug);
       switch (result.kind) {
-        case 'ok':
-          return okResult(result.data);
+        case 'ok': {
+          const entry = ctx.registry.resolve(flowSlug);
+          const meta = entry
+            ? canvasMetaFor(ctx, {
+                kind: 'navigate',
+                projectSlug: entry.projectSlug,
+                flowSlug: entry.flowSlug,
+              })
+            : undefined;
+          return okResult(result.data, meta);
+        }
         case 'notFound':
           return errorResult('not found');
         case 'fileNotFound':
@@ -365,27 +468,34 @@ const buildTools = (ops: Operations): McpTool[] => [
     inputSchema: {
       type: 'object',
       properties: {
-        flowId: { type: 'string', minLength: 1 },
+        ...PROJECT_FLOW_PROPERTIES,
         nodeId: { type: 'string', minLength: 1 },
       },
-      required: ['flowId', 'nodeId'],
+      required: ['project', 'flow', 'nodeId'],
       additionalProperties: false,
     },
     handler: async (args) => {
-      if (!args || typeof args !== 'object' || Array.isArray(args)) {
-        return errorResult('Invalid arguments: expected an object with flowId + nodeId');
-      }
-      const { flowId, nodeId } = args as { flowId?: unknown; nodeId?: unknown };
-      if (typeof flowId !== 'string' || flowId.length === 0) {
-        return errorResult('Invalid arguments: flowId must be a non-empty string');
-      }
+      const v = requireProjectFlow(args);
+      if ('error' in v) return errorResult(v.error);
+      const { nodeId } = (args as { nodeId?: unknown }) ?? {};
       if (typeof nodeId !== 'string' || nodeId.length === 0) {
         return errorResult('Invalid arguments: nodeId must be a non-empty string');
       }
-      const result = await ops.getNode(flowId, nodeId);
+      const flowSlug = `${v.project}/${v.flow}`;
+      const result = await ops.getNode(flowSlug, nodeId);
       switch (result.kind) {
-        case 'ok':
-          return okResult(result.data);
+        case 'ok': {
+          const entry = ctx.registry.resolve(flowSlug);
+          const meta = entry
+            ? canvasMetaFor(ctx, {
+                kind: 'navigate',
+                projectSlug: entry.projectSlug,
+                flowSlug: entry.flowSlug,
+                nodeId,
+              })
+            : undefined;
+          return okResult(result.data, meta);
+        }
         case 'notFound':
           return errorResult('not found');
         case 'fileNotFound':
@@ -412,8 +522,18 @@ const buildTools = (ops: Operations): McpTool[] => [
       }
       const result = await ops.registerFlow(parsed.data);
       switch (result.kind) {
-        case 'ok':
-          return okResult(result.data);
+        case 'ok': {
+          const entry = ctx.registry.resolve(result.data.id);
+          const meta = entry
+            ? canvasMetaFor(ctx, {
+                kind: 'create',
+                projectSlug: entry.projectSlug,
+                flowSlug: entry.flowSlug,
+                justCreated: true,
+              })
+            : undefined;
+          return okResult(result.data, meta);
+        }
         case 'fileNotFound':
           return errorResult(`Flow file not found: ${result.path}`);
         case 'badJson':
@@ -428,11 +548,11 @@ const buildTools = (ops: Operations): McpTool[] => [
   {
     name: 'seeflow_delete_flow',
     description: 'Unregister a flow from the studio (the on-disk file is left untouched).',
-    inputSchema: FLOW_ID_INPUT_SCHEMA,
+    inputSchema: FLOW_PROJECT_INPUT_SCHEMA,
     handler: async (args) => {
-      const v = requireFlowId(args);
+      const v = requireProjectFlow(args);
       if ('error' in v) return errorResult(v.error);
-      const result = ops.deleteFlow(v.flowId);
+      const result = ops.deleteFlow(`${v.project}/${v.flow}`);
       switch (result.kind) {
         case 'ok':
           return okResult({ ok: true });
@@ -453,8 +573,13 @@ const buildTools = (ops: Operations): McpTool[] => [
       }
       const result = await ops.createProject(parsed.data);
       switch (result.kind) {
-        case 'ok':
-          return okResult(result.data);
+        case 'ok': {
+          const meta = canvasMetaFor(ctx, {
+            kind: 'create',
+            projectSlug: result.data.slug,
+          });
+          return okResult(result.data, meta);
+        }
         case 'alreadyExists':
           return errorResult(`Project already exists at ${result.path}`);
         case 'scaffoldFailed':
@@ -472,8 +597,8 @@ const buildTools = (ops: Operations): McpTool[] => [
       if (!parsed.success) {
         return errorResult(`Invalid add_node arguments: ${JSON.stringify(parsed.error.issues)}`);
       }
-      const { flowId, node } = parsed.data;
-      const result = await ops.addNode(flowId, node);
+      const { project, flow, node } = parsed.data;
+      const result = await ops.addNode(`${project}/${flow}`, node);
       switch (result.kind) {
         case 'ok':
           return okResult({ ok: true, id: result.data.id, node: result.data.node });
@@ -500,8 +625,8 @@ const buildTools = (ops: Operations): McpTool[] => [
       if (!parsed.success) {
         return errorResult(`Invalid add_bulk arguments: ${JSON.stringify(parsed.error.issues)}`);
       }
-      const { flowId, nodes, connectors } = parsed.data;
-      const result = await ops.addBulk(flowId, { nodes, connectors });
+      const { project, flow, nodes, connectors } = parsed.data;
+      const result = await ops.addBulk(`${project}/${flow}`, { nodes, connectors });
       switch (result.kind) {
         case 'ok':
           return okResult({
@@ -537,8 +662,8 @@ const buildTools = (ops: Operations): McpTool[] => [
       if (!parsed.success) {
         return errorResult(`Invalid delete_node arguments: ${JSON.stringify(parsed.error.issues)}`);
       }
-      const { flowId, nodeId } = parsed.data;
-      const result = await ops.deleteNode(flowId, nodeId);
+      const { project, flow, nodeId } = parsed.data;
+      const result = await ops.deleteNode(`${project}/${flow}`, nodeId);
       switch (result.kind) {
         case 'ok':
           return okResult({ ok: true });
@@ -566,8 +691,8 @@ const buildTools = (ops: Operations): McpTool[] => [
       if (!parsed.success) {
         return errorResult(`Invalid move_node arguments: ${JSON.stringify(parsed.error.issues)}`);
       }
-      const { flowId, nodeId, x, y } = parsed.data;
-      const result = await ops.moveNode(flowId, nodeId, { x, y });
+      const { project, flow, nodeId, x, y } = parsed.data;
+      const result = await ops.moveNode(`${project}/${flow}`, nodeId, { x, y });
       switch (result.kind) {
         case 'ok':
           return okResult({ ok: true, position: result.data.position });
@@ -596,8 +721,8 @@ const buildTools = (ops: Operations): McpTool[] => [
       if (!parsed.success) {
         return errorResult(`Invalid patch_node arguments: ${JSON.stringify(parsed.error.issues)}`);
       }
-      const { flowId, nodeId, ...updates } = parsed.data;
-      const result = await ops.patchNode(flowId, nodeId, updates);
+      const { project, flow, nodeId, ...updates } = parsed.data;
+      const result = await ops.patchNode(`${project}/${flow}`, nodeId, updates);
       switch (result.kind) {
         case 'ok':
           return okResult({ ok: true });
@@ -628,12 +753,12 @@ const buildTools = (ops: Operations): McpTool[] => [
           `Invalid reorder_node arguments: ${JSON.stringify(parsed.error.issues)}`,
         );
       }
-      const { flowId, nodeId, ...body } = parsed.data;
+      const { project, flow, nodeId, ...body } = parsed.data;
       // Delegate the op-specific shape to the existing ReorderBodySchema so
       // reorderNodeImpl receives the same discriminated union the REST route
       // does — keeps a single source of truth for op semantics.
       const reorderBody = ReorderBodySchema.parse(body);
-      const result = await ops.reorderNode(flowId, nodeId, reorderBody);
+      const result = await ops.reorderNode(`${project}/${flow}`, nodeId, reorderBody);
       switch (result.kind) {
         case 'ok':
           return okResult({ ok: true });
@@ -664,8 +789,8 @@ const buildTools = (ops: Operations): McpTool[] => [
           `Invalid add_connector arguments: ${JSON.stringify(parsed.error.issues)}`,
         );
       }
-      const { flowId, connector } = parsed.data;
-      const result = await ops.addConnector(flowId, connector);
+      const { project, flow, connector } = parsed.data;
+      const result = await ops.addConnector(`${project}/${flow}`, connector);
       switch (result.kind) {
         case 'ok':
           return okResult({ ok: true, id: result.data.id });
@@ -694,8 +819,8 @@ const buildTools = (ops: Operations): McpTool[] => [
           `Invalid patch_connector arguments: ${JSON.stringify(parsed.error.issues)}`,
         );
       }
-      const { flowId, connectorId, ...updates } = parsed.data;
-      const result = await ops.patchConnector(flowId, connectorId, updates);
+      const { project, flow, connectorId, ...updates } = parsed.data;
+      const result = await ops.patchConnector(`${project}/${flow}`, connectorId, updates);
       switch (result.kind) {
         case 'ok':
           return okResult({ ok: true });
@@ -725,8 +850,8 @@ const buildTools = (ops: Operations): McpTool[] => [
           `Invalid delete_connector arguments: ${JSON.stringify(parsed.error.issues)}`,
         );
       }
-      const { flowId, connectorId } = parsed.data;
-      const result = await ops.deleteConnector(flowId, connectorId);
+      const { project, flow, connectorId } = parsed.data;
+      const result = await ops.deleteConnector(`${project}/${flow}`, connectorId);
       switch (result.kind) {
         case 'ok':
           return okResult({ ok: true });
@@ -758,9 +883,16 @@ export function createMcpServer(options: CreateMcpServerOptions): Server {
     registry: options.registry,
     watcher: options.watcher,
   });
-  const tools = buildTools(ops);
+  const tools = buildTools(ops, {
+    registry: options.registry,
+    token: options.token,
+    httpUrl: options.httpUrl,
+  });
 
-  const server = new Server({ name: 'seeflow', version: '0.1.0' }, { capabilities: { tools: {} } });
+  const server = new Server(
+    { name: 'seeflow', version: '0.1.0' },
+    { capabilities: { tools: {}, resources: {} } },
+  );
 
   server.setRequestHandler(ListToolsRequestSchema, () => ({
     tools: tools.map(({ name, description, inputSchema }) => ({
@@ -781,5 +913,34 @@ export function createMcpServer(options: CreateMcpServerOptions): Server {
     return tool.handler(request.params.arguments);
   });
 
+  // MCP Apps resource: a single readable HTML bundle the host iframes when a
+  // canvas-bearing tool returns `_meta['openai/outputTemplate'] = CANVAS_RESOURCE_URI`.
+  // Listed unconditionally — the bundle is part of the binary, even on hosts
+  // that don't speak MCP Apps (they just ignore the resource).
+  server.setRequestHandler(ListResourcesRequestSchema, () => ({
+    resources: [
+      {
+        uri: CANVAS_RESOURCE_URI,
+        name: 'SeeFlow Canvas',
+        mimeType: CANVAS_RESOURCE_MIME,
+      },
+    ],
+  }));
+
+  server.setRequestHandler(ReadResourceRequestSchema, (request) => {
+    if (request.params.uri !== CANVAS_RESOURCE_URI) {
+      throw new Error(`Unknown resource: ${request.params.uri}`);
+    }
+    return {
+      contents: [
+        {
+          uri: CANVAS_RESOURCE_URI,
+          mimeType: CANVAS_RESOURCE_MIME,
+          text: readCanvasHtml(),
+        },
+      ],
+    };
+  });
+
   return server;
 }

package/src/node-files.ts

@@ -3,9 +3,12 @@ import { dirname, join } from 'node:path';
 import { writeFileAtomic } from './atomic-write.ts';
 
 // Spec for fields that the studio externalizes to disk under
-// `<project>/nodes/<id>/<fileName>`. `nodeTypes` (when present) scopes the
-// spec entry to specific node types; absent means "applies to every node
-// type". Adding a future text field is one line.
+// `<repoPath>/<flowDir>/nodes/<id>/<fileName>`, where `flowDir` is
+// `dirname(entry.flowPath)`. For manifest-driven projects this resolves to
+// `flows/<flow-id>/nodes/<id>/`; for legacy single-flow fixtures with
+// `flowPath: 'flow.json'` it collapses to the project root. `nodeTypes` (when
+// present) scopes the spec entry to specific node types; absent means
+// "applies to every node type". Adding a future text field is one line.
 export interface ExternalizedFieldSpec {
   field: string;
   fileName: string;
@@ -26,6 +29,10 @@ export const externalizedFieldsForNodeType = (
 
 export type ExternalizedFieldName = (typeof EXTERNALIZED_NODE_FIELDS)[number]['field'];
 
+// Flow-relative on-disk path under the flow folder. Returned with forward
+// slashes so it round-trips through HTTP responses (the upload route ships
+// this back as the `path` field, and the watcher's image-ref resolver treats
+// it as relative to the flow folder).
 export const nodeFileRelPath = (nodeId: string, fileName: string): string =>
   `nodes/${nodeId}/${fileName}`;
 
@@ -35,14 +42,18 @@ export const nodeFileRelPath = (nodeId: string, fileName: string): string =>
 // that the file lives under the given node.
 export const nodeFileRef = (_nodeId: string, fileName: string): string => `file://${fileName}`;
 
-export const nodeFileAbsPath = (repoPath: string, nodeId: string, fileName: string): string =>
-  join(repoPath, nodeFileRelPath(nodeId, fileName));
+export const nodeFileAbsPath = (
+  repoPath: string,
+  flowDir: string,
+  nodeId: string,
+  fileName: string,
+): string => join(repoPath, flowDir, nodeFileRelPath(nodeId, fileName));
 
 export function writeNodeFile(absPath: string, content: string): void {
   mkdirSync(dirname(absPath), { recursive: true });
   writeFileAtomic(absPath, content);
 }
 
-export function removeNodeDir(repoPath: string, nodeId: string): void {
-  rmSync(join(repoPath, 'nodes', nodeId), { recursive: true, force: true });
+export function removeNodeDir(repoPath: string, flowDir: string, nodeId: string): void {
+  rmSync(join(repoPath, flowDir, 'nodes', nodeId), { recursive: true, force: true });
 }