FlowZap MCP Server

Instructions

Implementation Reference

• src/tools/diffAndApply.ts:490-520 (handler)

  The handleDiff function is the main entry point for the flowzap_diff tool. It validates input (ensuring both oldCode and newCode are strings), calls diffCode to compute the diff, and returns a JSON response with structured changes (added/removed/updated nodes and edges) and a human-readable summary.

  export function handleDiff(oldCode: unknown, newCode: unknown): string {
    if (typeof oldCode !== "string" || typeof newCode !== "string") {
      return JSON.stringify({
        success: false,
        error: "Both oldCode and newCode must be strings",
      });
    }
  
    try {
      const diff = diffCode(oldCode, newCode);
      
      return JSON.stringify({
        success: true,
        changes: {
          nodesAdded: diff.nodesAdded.map((n) => ({ id: n.id, label: n.label, lane: n.laneId })),
          nodesRemoved: diff.nodesRemoved.map((n) => ({ id: n.id, label: n.label, lane: n.laneId })),
          nodesUpdated: diff.nodesUpdated,
          edgesAdded: diff.edgesAdded.map((e) => ({ from: e.from, to: e.to, label: e.label })),
          edgesRemoved: diff.edgesRemoved.map((e) => ({ from: e.from, to: e.to, label: e.label })),
          lanesAdded: diff.lanesAdded,
          lanesRemoved: diff.lanesRemoved,
        },
        summary: diff.summary,
      }, null, 2);
    } catch (error) {
      return JSON.stringify({
        success: false,
        error: `Failed to diff code: ${error instanceof Error ? error.message : String(error)}`,
      });
    }
  }

• src/tools/diffAndApply.ts:135-238 (handler)

  The diffCode function implements the core diff logic for FlowZap Code. It parses both code versions into graph structures, compares nodes (detecting additions, removals, and label/shape/lane updates), compares edges, compares lanes, and generates a structured DiffResult with a summary of all changes.

  export function diffCode(oldCode: string, newCode: string): DiffResult {
    const oldGraph = parseToGraph(oldCode);
    const newGraph = parseToGraph(newCode);
  
    // Build maps for comparison
    const oldNodes = new Map(oldGraph.nodes.map((n) => [n.id, n]));
    const newNodes = new Map(newGraph.nodes.map((n) => [n.id, n]));
    const oldEdges = new Map(oldGraph.edges.map((e) => [`${e.from}->${e.to}`, e]));
    const newEdges = new Map(newGraph.edges.map((e) => [`${e.from}->${e.to}`, e]));
    const oldLanes = new Set(oldGraph.lanes.map((l) => l.id));
    const newLanes = new Set(newGraph.lanes.map((l) => l.id));
  
    // Find added/removed nodes
    const nodesAdded: GraphNode[] = [];
    const nodesRemoved: GraphNode[] = [];
    const nodesUpdated: Array<{ id: string; changes: Record<string, { old: string; new: string }> }> = [];
  
    for (const [id, node] of newNodes) {
      if (!oldNodes.has(id)) {
        nodesAdded.push(node);
      } else {
        // Check for updates
        const oldNode = oldNodes.get(id)!;
        const changes: Record<string, { old: string; new: string }> = {};
        
        if (oldNode.label !== node.label) {
          changes.label = { old: oldNode.label, new: node.label };
        }
        if (oldNode.shape !== node.shape) {
          changes.shape = { old: oldNode.shape, new: node.shape };
        }
        if (oldNode.laneId !== node.laneId) {
          changes.laneId = { old: oldNode.laneId, new: node.laneId };
        }
        
        if (Object.keys(changes).length > 0) {
          nodesUpdated.push({ id, changes });
        }
      }
    }
  
    for (const [id, node] of oldNodes) {
      if (!newNodes.has(id)) {
        nodesRemoved.push(node);
      }
    }
  
    // Find added/removed edges
    const edgesAdded: GraphEdge[] = [];
    const edgesRemoved: GraphEdge[] = [];
  
    for (const [key, edge] of newEdges) {
      if (!oldEdges.has(key)) {
        edgesAdded.push(edge);
      }
    }
  
    for (const [key, edge] of oldEdges) {
      if (!newEdges.has(key)) {
        edgesRemoved.push(edge);
      }
    }
  
    // Find added/removed lanes
    const lanesAdded = Array.from(newLanes).filter((l) => !oldLanes.has(l));
    const lanesRemoved = Array.from(oldLanes).filter((l) => !newLanes.has(l));
  
    // Generate summary
    const parts: string[] = [];
    if (nodesAdded.length > 0) {
      parts.push(`Added ${nodesAdded.length} node(s): ${nodesAdded.map((n) => `"${n.label}"`).join(", ")}`);
    }
    if (nodesRemoved.length > 0) {
      parts.push(`Removed ${nodesRemoved.length} node(s): ${nodesRemoved.map((n) => `"${n.label}"`).join(", ")}`);
    }
    if (nodesUpdated.length > 0) {
      parts.push(`Updated ${nodesUpdated.length} node(s)`);
    }
    if (edgesAdded.length > 0) {
      parts.push(`Added ${edgesAdded.length} connection(s)`);
    }
    if (edgesRemoved.length > 0) {
      parts.push(`Removed ${edgesRemoved.length} connection(s)`);
    }
    if (lanesAdded.length > 0) {
      parts.push(`Added lane(s): ${lanesAdded.join(", ")}`);
    }
    if (lanesRemoved.length > 0) {
      parts.push(`Removed lane(s): ${lanesRemoved.join(", ")}`);
    }
  
    const summary = parts.length > 0 ? parts.join(". ") : "No changes detected";
  
    return {
      nodesAdded,
      nodesRemoved,
      nodesUpdated,
      edgesAdded,
      edgesRemoved,
      lanesAdded,
      lanesRemoved,
      summary,
    };
  }

• src/tools/diffAndApply.ts:45-63 (schema)

  The diffTool schema definition defines the tool's name, description, and input validation schema. It requires two string parameters: oldCode (original FlowZap Code) and newCode (updated FlowZap Code).

  export const diffTool: Tool = {
    name: "flowzap_diff",
    description:
      "Compare two versions of FlowZap Code and get a structured diff showing what changed (nodes/edges added, removed, updated). Use this to explain changes to users.",
    inputSchema: {
      type: "object" as const,
      properties: {
        oldCode: {
          type: "string",
          description: "Original FlowZap Code",
        },
        newCode: {
          type: "string",
          description: "Updated FlowZap Code",
        },
      },
      required: ["oldCode", "newCode"],
    },
  };

• src/tools/diffAndApply.ts:12-21 (schema)

  The DiffResult interface defines the TypeScript type for the diff output structure, including arrays for added/removed/updated nodes and edges, added/removed lanes, and a summary string.

  export interface DiffResult {
    nodesAdded: GraphNode[];
    nodesRemoved: GraphNode[];
    nodesUpdated: Array<{ id: string; changes: Record<string, { old: string; new: string }> }>;
    edgesAdded: GraphEdge[];
    edgesRemoved: GraphEdge[];
    lanesAdded: string[];
    lanesRemoved: string[];
    summary: string;
  }

• src/index.ts:502-506 (registration)

  The switch case statement in the CallToolRequestSchema handler that routes 'flowzap_diff' tool calls to the handleDiff function, extracting oldCode and newCode from the arguments.

  case "flowzap_diff": {
    const { oldCode, newCode } = args as { oldCode?: unknown; newCode?: unknown };
    const result = handleDiff(oldCode, newCode);
    return { content: [{ type: "text", text: result }] };
  }