@tuongaz/seeflow 0.1.41 → 0.1.47

package/src/mcp.ts

@@ -8,14 +8,18 @@ import { type ZodTypeAny, z } from 'zod';
 import { zodToJsonSchema } from 'zod-to-json-schema';
 import {
   ConnectorPatchBodySchema,
+  ConnectorsBulkBodySchema,
   CreateProjectBodySchema,
   NodePatchBodySchema,
+  NodesBulkBodySchema,
   type OperationsDeps,
   PositionBodySchema,
   RegisterBodySchema,
   ReorderBodySchema,
   addConnectorImpl,
+  addConnectorsBulkImpl,
   addNodeImpl,
+  addNodesBulkImpl,
   createProjectImpl,
   deleteConnectorImpl,
   deleteFlowImpl,
@@ -55,16 +59,25 @@ export interface McpTool {
 // default. The MCP `tools/list` response carries `inputSchema` inline, so
 // stripping the wrapper keeps the wire payload tidy without losing any of
 // the actual shape constraints.
+//
+// MCP clients validate that every `inputSchema.type === "object"`. Plain
+// `z.object(...)` schemas already produce that, but `z.discriminatedUnion`
+// emits `{anyOf: [...]}` with no top-level `type` — so we force it on.
+// Every tool argument is an object envelope, so this is always correct.
 const inputSchemaFromZod = (schema: ZodTypeAny): Record<string, unknown> => {
   const json = zodToJsonSchema(schema, { $refStrategy: 'none' }) as Record<string, unknown>;
   const { $schema: _$schema, ...rest } = json;
-  return rest;
+  return rest.type === 'object' ? rest : { type: 'object', ...rest };
 };
 
 const okResult = (value: unknown): CallToolResult => ({
   content: [{ type: 'text', text: JSON.stringify(value) }],
 });
 
+// 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.
+// Renaming requires updating api.ts + ~18 test assertions in lockstep — a
+// separate refactor from this MCP review.
 const errorResult = (text: string): CallToolResult => ({
   isError: true,
   content: [{ type: 'text', text }],
@@ -73,14 +86,14 @@ const errorResult = (text: string): CallToolResult => ({
 // 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 DEMO_ID_INPUT_SCHEMA = {
+const FLOW_ID_INPUT_SCHEMA = {
   type: 'object',
   properties: { flowId: { type: 'string', minLength: 1 } },
   required: ['flowId'],
   additionalProperties: false,
 } as const;
 
-const requireDemoId = (args: unknown): { flowId: string } | { error: string } => {
+const requireFlowId = (args: unknown): { flowId: string } | { error: string } => {
   if (!args || typeof args !== 'object' || Array.isArray(args)) {
     return { error: 'Invalid arguments: expected an object with flowId' };
   }
@@ -92,7 +105,7 @@ const requireDemoId = (args: unknown): { flowId: string } | { error: string } =>
 };
 
 // {flowId, nodeId} body shape shared by move + reorder + delete inputs.
-const DemoNodeIdBaseSchema = z.object({
+const FlowNodeIdBaseSchema = z.object({
   flowId: z.string().min(1),
   nodeId: z.string().min(1),
 });
@@ -105,11 +118,19 @@ const AddNodeInputSchema = z.object({
   node: z.record(z.unknown()),
 });
 
-const DeleteNodeInputSchema = DemoNodeIdBaseSchema;
+// add_nodes input: { flowId, nodes: [...] }. Same loose per-item shape as
+// add_node — ResolvedFlowSchema runs once over the whole batch server-side
+// after the merge. Min/max bounds come from NodesBulkBodySchema so the
+// 100-item cap shows up in the JSON Schema the agent introspects.
+const AddNodesInputSchema = NodesBulkBodySchema.extend({
+  flowId: z.string().min(1),
+});
+
+const DeleteNodeInputSchema = FlowNodeIdBaseSchema;
 
 // move_node input: { flowId, nodeId } extended with PositionBodySchema's
 // { x, y } fields so agents see one flat schema.
-const MoveNodeInputSchema = DemoNodeIdBaseSchema.extend({
+const MoveNodeInputSchema = FlowNodeIdBaseSchema.extend({
   x: PositionBodySchema.shape.x,
   y: PositionBodySchema.shape.y,
 });
@@ -118,11 +139,11 @@ const MoveNodeInputSchema = DemoNodeIdBaseSchema.extend({
 // discriminated union extended with flowId/nodeId. Keeps the discriminator
 // on `op` so the emitted JSON Schema is an oneOf the agent can introspect.
 const ReorderNodeInputSchema = z.discriminatedUnion('op', [
-  DemoNodeIdBaseSchema.extend({ op: z.literal('forward') }),
-  DemoNodeIdBaseSchema.extend({ op: z.literal('backward') }),
-  DemoNodeIdBaseSchema.extend({ op: z.literal('toFront') }),
-  DemoNodeIdBaseSchema.extend({ op: z.literal('toBack') }),
-  DemoNodeIdBaseSchema.extend({
+  FlowNodeIdBaseSchema.extend({ op: z.literal('forward') }),
+  FlowNodeIdBaseSchema.extend({ op: z.literal('backward') }),
+  FlowNodeIdBaseSchema.extend({ op: z.literal('toFront') }),
+  FlowNodeIdBaseSchema.extend({ op: z.literal('toBack') }),
+  FlowNodeIdBaseSchema.extend({
     op: z.literal('toIndex'),
     index: z.number().int().nonnegative(),
   }),
@@ -147,6 +168,11 @@ const AddConnectorInputSchema = z.object({
   connector: z.record(z.unknown()),
 });
 
+// add_connectors input: { flowId, connectors: [...] }. Mirrors add_nodes.
+const AddConnectorsInputSchema = ConnectorsBulkBodySchema.extend({
+  flowId: z.string().min(1),
+});
+
 // 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
@@ -164,7 +190,7 @@ const DeleteConnectorInputSchema = z.object({
 const buildTools = (deps: OperationsDeps): McpTool[] => [
   {
     name: 'seeflow_list_flows',
-    description: 'List every demo registered with the studio.',
+    description: 'List every flow registered with the studio.',
     inputSchema: { type: 'object', properties: {}, additionalProperties: false },
     handler: async () => {
       const result = listDemosImpl(deps);
@@ -200,10 +226,10 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
   },
   {
     name: 'seeflow_get_flow',
-    description: 'Get the full demo definition and on-disk state for a flowId.',
-    inputSchema: DEMO_ID_INPUT_SCHEMA,
+    description: 'Get the full flow definition and on-disk state for a flowId.',
+    inputSchema: FLOW_ID_INPUT_SCHEMA,
     handler: async (args) => {
-      const v = requireDemoId(args);
+      const v = requireFlowId(args);
       if ('error' in v) return errorResult(v.error);
       const result = await getFlowImpl(deps, v.flowId);
       switch (result.kind) {
@@ -218,7 +244,7 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
   },
   {
     name: 'seeflow_register_flow',
-    description: 'Register an existing demo file on disk with the studio.',
+    description: 'Register an existing flow file on disk with the studio.',
     inputSchema: inputSchemaFromZod(RegisterBodySchema),
     handler: async (args) => {
       const parsed = RegisterBodySchema.safeParse(args);
@@ -244,10 +270,10 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
   },
   {
     name: 'seeflow_delete_flow',
-    description: 'Unregister a demo from the studio (the on-disk file is left untouched).',
-    inputSchema: DEMO_ID_INPUT_SCHEMA,
+    description: 'Unregister a flow from the studio (the on-disk file is left untouched).',
+    inputSchema: FLOW_ID_INPUT_SCHEMA,
     handler: async (args) => {
-      const v = requireDemoId(args);
+      const v = requireFlowId(args);
       if ('error' in v) return errorResult(v.error);
       const result = deleteFlowImpl(deps, v.flowId);
       switch (result.kind) {
@@ -286,7 +312,8 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
   },
   {
     name: 'seeflow_add_node',
-    description: 'Append a new node to a demo (cascade-safe; id auto-generated when omitted).',
+    description:
+      'Append a new node to a flow (cascade-safe; id auto-generated when omitted). Text content fields (detail on every node; html on htmlNode) are auto-externalized to <project>/.seeflow/nodes/<id>/ and stored as file:// refs in flow.json; reads inline the resolved content transparently.',
     inputSchema: inputSchemaFromZod(AddNodeInputSchema),
     handler: async (args) => {
       const parsed = AddNodeInputSchema.safeParse(args);
@@ -311,6 +338,38 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
       }
     },
   },
+  {
+    name: 'seeflow_add_nodes',
+    description:
+      'Append 1–100 nodes to a flow in a single transactional write. Either every node lands or nothing does — if any item fails schema validation the whole batch is rejected. Use this instead of multiple seeflow_add_node calls when seeding a flow; it avoids per-item round-trips. Same per-item shape and externalization rules as seeflow_add_node.',
+    inputSchema: inputSchemaFromZod(AddNodesInputSchema),
+    handler: async (args) => {
+      const parsed = AddNodesInputSchema.safeParse(args);
+      if (!parsed.success) {
+        return errorResult(`Invalid add_nodes arguments: ${JSON.stringify(parsed.error.issues)}`);
+      }
+      const { flowId, nodes } = parsed.data;
+      const result = await addNodesBulkImpl(deps, flowId, { nodes });
+      switch (result.kind) {
+        case 'ok':
+          return okResult({ ok: true, nodes: result.data.nodes });
+        case 'flowNotFound':
+          return errorResult('unknown demo');
+        case 'fileNotFound':
+          return errorResult(`Flow file not found: ${result.path}`);
+        case 'badJson':
+          return errorResult(`Flow file is not valid JSON: ${result.message}`);
+        case 'badSchema':
+          return errorResult(`Flow failed schema validation: ${JSON.stringify(result.issues)}`);
+        case 'duplicateIdInBatch':
+          return errorResult(`Duplicate id in batch: ${result.id}`);
+        case 'idAlreadyExists':
+          return errorResult(`Node id already exists: ${result.id}`);
+        case 'writeFailed':
+          return errorResult(`Failed to write demo file: ${result.message}`);
+      }
+    },
+  },
   {
     name: 'seeflow_delete_node',
     description: 'Delete a node and cascade-remove every connector touching it.',
@@ -372,7 +431,7 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
   {
     name: 'seeflow_patch_node',
     description:
-      'Update fields on an existing node (position, name, description, detail, colors, border, font, shape, dimensions).',
+      'Update fields on an existing node (position, name, description, detail, icon, colors, border, font, shape, dimensions, autoSize, plus iconNode-only color/strokeWidth/alt). Setting detail (every node) or html (htmlNode) writes the content to <project>/.seeflow/nodes/<id>/{detail.md|view.html}; the file:// ref on the node persists. Empty-string detail empties the file but keeps the ref.',
     inputSchema: inputSchemaFromZod(PatchNodeInputSchema),
     handler: async (args) => {
       const parsed = PatchNodeInputSchema.safeParse(args);
@@ -402,7 +461,7 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
   {
     name: 'seeflow_reorder_node',
     description:
-      'Reorder a node within demo.nodes[] (forward / backward / toFront / toBack / toIndex).',
+      'Reorder a node within flow.nodes[] (forward / backward / toFront / toBack / toIndex).',
     inputSchema: inputSchemaFromZod(ReorderNodeInputSchema),
     handler: async (args) => {
       const parsed = ReorderNodeInputSchema.safeParse(args);
@@ -465,10 +524,44 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
       }
     },
   },
+  {
+    name: 'seeflow_add_connectors',
+    description:
+      'Append 1–100 connectors to a flow in a single transactional write. Either every connector lands or nothing does — a dangling source/target on any item rolls back the whole batch. Use after seeflow_add_nodes when seeding a flow.',
+    inputSchema: inputSchemaFromZod(AddConnectorsInputSchema),
+    handler: async (args) => {
+      const parsed = AddConnectorsInputSchema.safeParse(args);
+      if (!parsed.success) {
+        return errorResult(
+          `Invalid add_connectors arguments: ${JSON.stringify(parsed.error.issues)}`,
+        );
+      }
+      const { flowId, connectors } = parsed.data;
+      const result = await addConnectorsBulkImpl(deps, flowId, { connectors });
+      switch (result.kind) {
+        case 'ok':
+          return okResult({ ok: true, connectors: result.data.connectors });
+        case 'flowNotFound':
+          return errorResult('unknown demo');
+        case 'fileNotFound':
+          return errorResult(`Flow file not found: ${result.path}`);
+        case 'badJson':
+          return errorResult(`Flow file is not valid JSON: ${result.message}`);
+        case 'badSchema':
+          return errorResult(`Flow failed schema validation: ${JSON.stringify(result.issues)}`);
+        case 'duplicateIdInBatch':
+          return errorResult(`Duplicate id in batch: ${result.id}`);
+        case 'idAlreadyExists':
+          return errorResult(`Connector id already exists: ${result.id}`);
+        case 'writeFailed':
+          return errorResult(`Failed to write demo file: ${result.message}`);
+      }
+    },
+  },
   {
     name: 'seeflow_patch_connector',
     description:
-      'Update fields on an existing connector (label, style, color, kind, per-kind payload, reconnect endpoints).',
+      'Update fields on an existing connector (label, style, color, direction, path, borderSize, fontSize, kind, per-kind payload, reconnect endpoints + handles + pins).',
     inputSchema: inputSchemaFromZod(PatchConnectorInputSchema),
     handler: async (args) => {
       const parsed = PatchConnectorInputSchema.safeParse(args);

package/src/merge.ts

@@ -52,7 +52,7 @@ const NODE_DATA_FLOW_KEYS = new Set([
   'shape',
   'path',
   'alt',
-  'htmlPath',
+  'html',
 ]);
 
 const NODE_STYLE_KEYS = new Set([

package/src/node-files.ts

@@ -0,0 +1,48 @@
+import { mkdirSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { writeFileAtomic } from './atomic-write.ts';
+
+// Spec for fields that the studio externalizes to disk under
+// `<project>/.seeflow/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.
+export interface ExternalizedFieldSpec {
+  field: string;
+  fileName: string;
+  nodeTypes?: readonly string[];
+}
+
+export const EXTERNALIZED_NODE_FIELDS: readonly ExternalizedFieldSpec[] = [
+  { field: 'detail', fileName: 'detail.md' },
+  { field: 'html', fileName: 'view.html', nodeTypes: ['htmlNode'] },
+];
+
+export const externalizedFieldsForNodeType = (
+  nodeType: unknown,
+): readonly ExternalizedFieldSpec[] => {
+  if (typeof nodeType !== 'string') return EXTERNALIZED_NODE_FIELDS.filter((e) => !e.nodeTypes);
+  return EXTERNALIZED_NODE_FIELDS.filter((e) => !e.nodeTypes || e.nodeTypes.includes(nodeType));
+};
+
+export type ExternalizedFieldName = (typeof EXTERNALIZED_NODE_FIELDS)[number]['field'];
+
+export const nodeFileRelPath = (nodeId: string, fileName: string): string =>
+  `nodes/${nodeId}/${fileName}`;
+
+// Node-relative ref: the resolver knows the enclosing node id from the flow.json
+// shape (nodes[i].id), so the on-disk string only needs the filename. Kept as a
+// 2-arg helper so call sites don't change shape and the spec stays explicit
+// 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, '.seeflow', 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, '.seeflow', 'nodes', nodeId), { recursive: true, force: true });
+}