@tuongaz/seeflow 0.1.42 → 0.1.51

package/src/mcp.ts

@@ -12,26 +12,11 @@ import {
   CreateProjectBodySchema,
   NodePatchBodySchema,
   NodesBulkBodySchema,
-  type OperationsDeps,
+  type Operations,
   PositionBodySchema,
   RegisterBodySchema,
   ReorderBodySchema,
-  addConnectorImpl,
-  addConnectorsBulkImpl,
-  addNodeImpl,
-  addNodesBulkImpl,
-  createProjectImpl,
-  deleteConnectorImpl,
-  deleteFlowImpl,
-  deleteNodeImpl,
-  getFlowImpl,
-  listDemosImpl,
-  moveNodeImpl,
-  patchConnectorImpl,
-  patchNodeImpl,
-  registerFlowImpl,
-  reorderNodeImpl,
-  validateImpl,
+  createOperations,
 } from './operations.ts';
 import type { Registry } from './registry.ts';
 import type { FlowWatcher } from './watcher.ts';
@@ -187,13 +172,25 @@ const DeleteConnectorInputSchema = z.object({
   connectorId: z.string().min(1),
 });
 
-const buildTools = (deps: OperationsDeps): McpTool[] => [
+const buildTools = (ops: Operations): McpTool[] => [
   {
     name: 'seeflow_list_flows',
     description: 'List every flow registered with the studio.',
     inputSchema: { type: 'object', properties: {}, additionalProperties: false },
     handler: async () => {
-      const result = listDemosImpl(deps);
+      const result = ops.listFlows();
+      return okResult(result.data);
+    },
+  },
+  {
+    name: 'seeflow_list_flows_summary',
+    description:
+      'List registered flows as { id, name, description } only. Use this for ' +
+      'cheap discovery before drilling into a specific flow with ' +
+      'seeflow_get_flow_graph or seeflow_get_node.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    handler: async () => {
+      const result = ops.listFlowsSummary();
       return okResult(result.data);
     },
   },
@@ -217,7 +214,7 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
       if (!body || !('flow' in body)) {
         return errorResult('Body must include `flow`');
       }
-      const result = validateImpl({
+      const result = ops.validate({
         flow: body.flow,
         style: body.style as unknown,
       });
@@ -231,7 +228,28 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
     handler: async (args) => {
       const v = requireFlowId(args);
       if ('error' in v) return errorResult(v.error);
-      const result = await getFlowImpl(deps, v.flowId);
+      const result = await ops.getFlow(v.flowId);
+      switch (result.kind) {
+        case 'ok':
+          return okResult(result.data);
+        case 'notFound':
+          return errorResult('not found');
+        case 'fileNotFound':
+          return errorResult(`Flow file not found: ${result.path}`);
+      }
+    },
+  },
+  {
+    name: 'seeflow_get_flow_graph',
+    description:
+      "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,
+    handler: async (args) => {
+      const v = requireFlowId(args);
+      if ('error' in v) return errorResult(v.error);
+      const result = await ops.getFlowGraph(v.flowId);
       switch (result.kind) {
         case 'ok':
           return okResult(result.data);
@@ -239,6 +257,56 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
           return errorResult('not found');
         case 'fileNotFound':
           return errorResult(`Flow file not found: ${result.path}`);
+        case 'badJson':
+          return errorResult(`Flow file is not valid JSON: ${result.detail}`);
+        case 'badSchema':
+          return errorResult(
+            `Flow file failed schema validation: ${JSON.stringify(result.issues)}`,
+          );
+      }
+    },
+  },
+  {
+    name: 'seeflow_get_node',
+    description:
+      'Get a single node from a flow with its file-backed content (detail.md, ' +
+      'view.html) inlined. Use after seeflow_get_flow_graph to drill into one node.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        flowId: { type: 'string', minLength: 1 },
+        nodeId: { type: 'string', minLength: 1 },
+      },
+      required: ['flowId', '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');
+      }
+      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);
+      switch (result.kind) {
+        case 'ok':
+          return okResult(result.data);
+        case 'notFound':
+          return errorResult('not found');
+        case 'fileNotFound':
+          return errorResult(`Flow file not found: ${result.path}`);
+        case 'unknownNode':
+          return errorResult(`Unknown nodeId: ${nodeId}`);
+        case 'badJson':
+          return errorResult(`Flow file is not valid JSON: ${result.detail}`);
+        case 'badSchema':
+          return errorResult(
+            `Flow file failed schema validation: ${JSON.stringify(result.issues)}`,
+          );
       }
     },
   },
@@ -251,7 +319,7 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
       if (!parsed.success) {
         return errorResult(`Invalid register body: ${JSON.stringify(parsed.error.issues)}`);
       }
-      const result = await registerFlowImpl(deps, parsed.data);
+      const result = await ops.registerFlow(parsed.data);
       switch (result.kind) {
         case 'ok':
           return okResult(result.data);
@@ -275,7 +343,7 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
     handler: async (args) => {
       const v = requireFlowId(args);
       if ('error' in v) return errorResult(v.error);
-      const result = deleteFlowImpl(deps, v.flowId);
+      const result = ops.deleteFlow(v.flowId);
       switch (result.kind) {
         case 'ok':
           return okResult({ ok: true });
@@ -293,7 +361,7 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
       if (!parsed.success) {
         return errorResult(`Invalid create project body: ${JSON.stringify(parsed.error.issues)}`);
       }
-      const result = await createProjectImpl(deps, parsed.data);
+      const result = await ops.createProject(parsed.data);
       switch (result.kind) {
         case 'ok':
           return okResult(result.data);
@@ -321,7 +389,7 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
         return errorResult(`Invalid add_node arguments: ${JSON.stringify(parsed.error.issues)}`);
       }
       const { flowId, node } = parsed.data;
-      const result = await addNodeImpl(deps, flowId, node);
+      const result = await ops.addNode(flowId, node);
       switch (result.kind) {
         case 'ok':
           return okResult({ ok: true, id: result.data.id, node: result.data.node });
@@ -349,7 +417,7 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
         return errorResult(`Invalid add_nodes arguments: ${JSON.stringify(parsed.error.issues)}`);
       }
       const { flowId, nodes } = parsed.data;
-      const result = await addNodesBulkImpl(deps, flowId, { nodes });
+      const result = await ops.addNodesBulk(flowId, { nodes });
       switch (result.kind) {
         case 'ok':
           return okResult({ ok: true, nodes: result.data.nodes });
@@ -380,7 +448,7 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
         return errorResult(`Invalid delete_node arguments: ${JSON.stringify(parsed.error.issues)}`);
       }
       const { flowId, nodeId } = parsed.data;
-      const result = await deleteNodeImpl(deps, flowId, nodeId);
+      const result = await ops.deleteNode(flowId, nodeId);
       switch (result.kind) {
         case 'ok':
           return okResult({ ok: true });
@@ -409,7 +477,7 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
         return errorResult(`Invalid move_node arguments: ${JSON.stringify(parsed.error.issues)}`);
       }
       const { flowId, nodeId, x, y } = parsed.data;
-      const result = await moveNodeImpl(deps, flowId, nodeId, { x, y });
+      const result = await ops.moveNode(flowId, nodeId, { x, y });
       switch (result.kind) {
         case 'ok':
           return okResult({ ok: true, position: result.data.position });
@@ -439,7 +507,7 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
         return errorResult(`Invalid patch_node arguments: ${JSON.stringify(parsed.error.issues)}`);
       }
       const { flowId, nodeId, ...updates } = parsed.data;
-      const result = await patchNodeImpl(deps, flowId, nodeId, updates);
+      const result = await ops.patchNode(flowId, nodeId, updates);
       switch (result.kind) {
         case 'ok':
           return okResult({ ok: true });
@@ -475,7 +543,7 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
       // 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 reorderNodeImpl(deps, flowId, nodeId, reorderBody);
+      const result = await ops.reorderNode(flowId, nodeId, reorderBody);
       switch (result.kind) {
         case 'ok':
           return okResult({ ok: true });
@@ -507,7 +575,7 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
         );
       }
       const { flowId, connector } = parsed.data;
-      const result = await addConnectorImpl(deps, flowId, connector);
+      const result = await ops.addConnector(flowId, connector);
       switch (result.kind) {
         case 'ok':
           return okResult({ ok: true, id: result.data.id });
@@ -537,7 +605,7 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
         );
       }
       const { flowId, connectors } = parsed.data;
-      const result = await addConnectorsBulkImpl(deps, flowId, { connectors });
+      const result = await ops.addConnectorsBulk(flowId, { connectors });
       switch (result.kind) {
         case 'ok':
           return okResult({ ok: true, connectors: result.data.connectors });
@@ -571,7 +639,7 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
         );
       }
       const { flowId, connectorId, ...updates } = parsed.data;
-      const result = await patchConnectorImpl(deps, flowId, connectorId, updates);
+      const result = await ops.patchConnector(flowId, connectorId, updates);
       switch (result.kind) {
         case 'ok':
           return okResult({ ok: true });
@@ -602,7 +670,7 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
         );
       }
       const { flowId, connectorId } = parsed.data;
-      const result = await deleteConnectorImpl(deps, flowId, connectorId);
+      const result = await ops.deleteConnector(flowId, connectorId);
       switch (result.kind) {
         case 'ok':
           return okResult({ ok: true });
@@ -630,11 +698,12 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
  * mcp-shim.ts) — every request builds its own server in stateless mode.
  */
 export function createMcpServer(options: CreateMcpServerOptions): Server {
-  const tools = buildTools({
+  const ops = createOperations({
     registry: options.registry,
     watcher: options.watcher,
     projectBaseDir: options.projectBaseDir,
   });
+  const tools = buildTools(ops);
 
   const server = new Server({ name: 'seeflow', version: '0.1.0' }, { capabilities: { tools: {} } });
 

package/src/merge.ts

@@ -31,6 +31,7 @@ export function mergeFlowAndStyle(flow: Flow, style: Style): ResolvedFlow {
   return {
     version: flow.version,
     name: flow.name,
+    ...(flow.description !== undefined ? { description: flow.description } : {}),
     ...(flow.resetAction ? { resetAction: flow.resetAction } : {}),
     nodes: mergedNodes,
     connectors: mergedConnectors,
@@ -111,6 +112,7 @@ const CONNECTOR_STYLE_KEYS = new Set([
 export function splitFlow(resolved: {
   version: number;
   name: string;
+  description?: string;
   resetAction?: unknown;
   nodes: Array<Record<string, unknown>>;
   connectors: Array<Record<string, unknown>>;
@@ -179,6 +181,7 @@ export function splitFlow(resolved: {
     nodes: flowNodes,
     connectors: flowConnectors,
   };
+  if (resolved.description !== undefined) flow.description = resolved.description;
   if (resolved.resetAction !== undefined) flow.resetAction = resolved.resetAction;
 
   const style: Record<string, unknown> = {};

package/src/node-files.ts

@@ -29,8 +29,11 @@ export type ExternalizedFieldName = (typeof EXTERNALIZED_NODE_FIELDS)[number]['f
 export const nodeFileRelPath = (nodeId: string, fileName: string): string =>
   `nodes/${nodeId}/${fileName}`;
 
-export const nodeFileRef = (nodeId: string, fileName: string): string =>
-  `file://${nodeFileRelPath(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));