@gmag11/nodered-mcp-server 1.0.1

package/src/renderer/ir-builder.js

@@ -0,0 +1,161 @@
+/**
+ * Intermediate Representation (IR) Builder
+ *
+ * Transforms raw Node-RED flows into a normalized intermediate representation
+ * that all format builders (SVG, HTML, Mermaid) consume.
+ *
+ * @module renderer/ir-builder
+ */
+
+/**
+ * @typedef {object} IRNode
+ * @property {string} id - Node ID
+ * @property {string} type - Node type (e.g., 'inject', 'function')
+ * @property {string} [name] - Node display name
+ * @property {number} x - X position
+ * @property {number} y - Y position
+ * @property {number} w - Node width
+ * @property {number} h - Node height
+ * @property {number} [inputs] - Number of input ports
+ * @property {number} [outputs] - Number of output ports
+ * @property {boolean} [d] - Whether node is disabled
+ * @property {boolean} [dirty] - Whether node has un-deployed changes
+ * @property {string} [z] - Parent flow ID
+ * @property {string} [g] - Parent group ID
+ * @property {object[]} [wires] - Outgoing wire connections
+ */
+
+/**
+ * @typedef {object} IRLink
+ * @property {IRNode} source - Source node
+ * @property {number} sourcePort - Source output port index
+ * @property {IRNode} target - Target node
+ */
+
+/**
+ * @typedef {object} IRGroup
+ * @property {string} id - Group ID
+ * @property {string} [name] - Group label
+ * @property {number} x - X position
+ * @property {number} y - Y position
+ * @property {number} w - Width
+ * @property {number} h - Height
+ * @property {object} [style] - Group style (fill, stroke, color, etc.)
+ * @property {string[]} nodes - Member node IDs
+ */
+
+/**
+ * @typedef {object} IR
+ * @property {IRNode[]} nodes - All flow nodes
+ * @property {IRGroup[]} groups - All group nodes
+ * @property {IRLink[]} links - All wire connections
+ * @property {Set<string>} dirtyNodeIds - IDs of dirty (un-deployed) nodes
+ */
+
+/**
+ * Default node dimensions if not specified.
+ */
+const DEFAULT_W = 100;
+const DEFAULT_H = 30;
+
+/**
+ * Build the intermediate representation from raw flows data.
+ *
+ * @param {object[]} flows - Raw Node-RED flows array
+ * @param {object} options
+ * @param {string} [options.flowId] - Filter to a single flow
+ * @param {boolean} [options.highlightDirty=true] - Mark dirty nodes
+ * @param {Set<string>} [options.dirtyNodeIds] - Dirty node IDs
+ * @param {Set<string>} [options.dirtyFlowIds] - Dirty flow IDs
+ * @returns {IR}
+ * @throws {Error} If flowId is provided but not found
+ */
+export function buildIR(flows, options = {}) {
+  const {
+    flowId,
+    highlightDirty = true,
+    dirtyNodeIds = new Set(),
+  } = options;
+
+  let filteredFlows = flows;
+
+  // Filter by flow if requested
+  if (flowId) {
+    filteredFlows = flows.filter(
+      (n) => n.z === flowId || n.id === flowId
+    );
+    if (filteredFlows.length === 0 && !flows.some((n) => n.id === flowId)) {
+      throw new Error(`Flow not found: ${flowId}`);
+    }
+  }
+
+  // Separate nodes, groups, and junctions
+  const allFlowNodes = filteredFlows.filter(
+    (n) => n.type !== 'group' && n.type !== 'tab' && n.type !== 'junction'
+  );
+  const groups = filteredFlows.filter((n) => n.type === 'group');
+  const junctions = filteredFlows.filter((n) => n.type === 'junction');
+
+  // Build node ID set for this flow
+  const nodeIdSet = new Set(allFlowNodes.map((n) => n.id));
+
+  // Convert to IR nodes
+  const nodes = allFlowNodes.map((n) => {
+    const numWires = Array.isArray(n.wires) ? n.wires.length : 0;
+    return {
+      id: n.id,
+      type: n.type,
+      name: n.name || n.type,
+      x: n.x || 0,
+      y: n.y || 0,
+      w: n.w || DEFAULT_W,
+      h: n.h || DEFAULT_H,
+      inputs: n.inputs ?? 0,
+      outputs: n.outputs ?? numWires,
+      d: n.d === true,
+      dirty: highlightDirty ? dirtyNodeIds.has(n.id) : false,
+      z: n.z,
+      g: n.g,
+      wires: n.wires || [],
+    };
+  });
+
+  // Convert groups
+  const irGroups = groups.map((g) => ({
+    id: g.id,
+    name: g.name || 'Group',
+    x: g.x || 0,
+    y: g.y || 0,
+    w: g.w || 40,
+    h: g.h || 40,
+    style: g.style || {},
+    nodes: (g.nodes || []).filter((mid) => nodeIdSet.has(mid)),
+  }));
+
+  // Build links
+  const links = [];
+  for (const node of nodes) {
+    if (!node.wires || node.wires.length === 0) continue;
+    node.wires.forEach((targets, portIndex) => {
+      if (!Array.isArray(targets)) return;
+      for (const targetId of targets) {
+        const targetNode = nodes.find((n) => n.id === targetId);
+        if (targetNode) {
+          links.push({
+            source: node,
+            sourcePort: portIndex,
+            target: targetNode,
+          });
+        }
+      }
+    });
+  }
+
+  return {
+    nodes,
+    groups: irGroups,
+    links,
+    junctions,
+    dirtyNodeIds,
+  };
+}

package/src/renderer/layout.js

@@ -0,0 +1,126 @@
+/**
+ * Layout Utilities
+ *
+ * Computes bounding boxes, auto-fit viewport dimensions, and scale factors
+ * for rendering the staging workspace.
+ *
+ * @module renderer/layout
+ */
+
+/**
+ * Default canvas dimensions (matching Node-RED's virtual canvas).
+ */
+const CANVAS_WIDTH = 8000;
+const CANVAS_HEIGHT = 8000;
+
+/**
+ * Default viewport padding around nodes (in workspace units).
+ */
+const VIEWPORT_PADDING = 60;
+
+/**
+ * Compute the bounding box of a set of nodes and groups.
+ *
+ * @param {import('./ir-builder.js').IRNode[]} nodes - Flow nodes
+ * @param {import('./ir-builder.js').IRGroup[]} groups - Group nodes
+ * @returns {{ minX: number, minY: number, maxX: number, maxY: number, width: number, height: number }}
+ */
+export function computeBoundingBox(nodes, groups = []) {
+  if (nodes.length === 0 && groups.length === 0) {
+    return { minX: 0, minY: 0, maxX: 400, maxY: 200, width: 400, height: 200 };
+  }
+
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+
+  for (const node of nodes) {
+    const left = node.x - node.w / 2;
+    const right = node.x + node.w / 2;
+    const top = node.y - node.h / 2;
+    const bottom = node.y + node.h / 2;
+
+    if (left < minX) minX = left;
+    if (right > maxX) maxX = right;
+    if (top < minY) minY = top;
+    if (bottom > maxY) maxY = bottom;
+  }
+
+  // Include group boundaries
+  for (const group of groups) {
+    if (group.x < minX) minX = group.x;
+    if (group.y < minY) minY = group.y;
+    if (group.x + group.w > maxX) maxX = group.x + group.w;
+    if (group.y + group.h > maxY) maxY = group.y + group.h;
+  }
+
+  // Add padding
+  minX -= VIEWPORT_PADDING;
+  minY -= VIEWPORT_PADDING;
+  maxX += VIEWPORT_PADDING;
+  maxY += VIEWPORT_PADDING;
+
+  return {
+    minX,
+    minY,
+    maxX,
+    maxY,
+    width: maxX - minX,
+    height: maxY - minY,
+  };
+}
+
+/**
+ * Calculate the scale factor to fit content within a viewport.
+ *
+ * @param {number} contentWidth - Width of content in workspace units
+ * @param {number} contentHeight - Height of content in workspace units
+ * @param {number} viewportWidth - Available viewport width in pixels
+ * @param {number} viewportHeight - Available viewport height in pixels
+ * @param {number} [maxScale=1.5] - Maximum allowed scale factor
+ * @param {number} [minScale=0.1] - Minimum allowed scale factor
+ * @returns {number} Scale factor (1.0 = 100%)
+ */
+export function calculateScaleFactor(
+  contentWidth,
+  contentHeight,
+  viewportWidth,
+  viewportHeight,
+  maxScale = 1.5,
+  minScale = 0.1
+) {
+  if (contentWidth <= 0 || contentHeight <= 0) return 1;
+
+  const scaleX = viewportWidth / contentWidth;
+  const scaleY = viewportHeight / contentHeight;
+  const fitScale = Math.min(scaleX, scaleY);
+
+  return Math.max(minScale, Math.min(maxScale, fitScale));
+}
+
+/**
+ * Calculate the SVG viewBox string to fit the content within the given dimensions.
+ *
+ * @param {import('./ir-builder.js').IRNode[]} nodes - Flow nodes
+ * @param {import('./ir-builder.js').IRGroup[]} groups - Group nodes
+ * @param {number} [targetWidth=800] - Target SVG width
+ * @param {number} [targetHeight=600] - Target SVG height
+ * @returns {{ viewBox: string, width: number, height: number }}
+ */
+export function calculateViewBox(nodes, groups = [], targetWidth = 800, targetHeight = 600) {
+  const bb = computeBoundingBox(nodes, groups);
+  const scale = calculateScaleFactor(bb.width, bb.height, targetWidth, targetHeight);
+
+  // Apply scale to get actual SVG dimensions
+  const svgWidth = Math.max(targetWidth, Math.ceil(bb.width * scale));
+  const svgHeight = Math.max(targetHeight, Math.ceil(bb.height * scale));
+
+  return {
+    viewBox: `${bb.minX} ${bb.minY} ${bb.width} ${bb.height}`,
+    width: svgWidth,
+    height: svgHeight,
+  };
+}
+
+export { CANVAS_WIDTH, CANVAS_HEIGHT, VIEWPORT_PADDING };

package/src/renderer/mermaid-builder.js

@@ -0,0 +1,109 @@
+/**
+ * Mermaid Builder
+ *
+ * Generates Mermaid flowchart TD diagrams from the intermediate representation.
+ * Consolidates and enhances the existing `generateMermaidDiagram()` logic
+ * from src/tools/get-flow-diagram.js with dirty highlighting support.
+ *
+ * @module renderer/mermaid-builder
+ */
+
+import { getMermaidClass } from './colors.js';
+
+/**
+ * Escape a string for use as a Mermaid node label.
+ *
+ * @param {string} label
+ * @returns {string}
+ */
+function escapeMermaidLabel(label) {
+  return `"${label.replace(/"/g, '#quot;')}"`;
+}
+
+/**
+ * Build a Mermaid flowchart TD diagram string from the IR.
+ *
+ * @param {import('./ir-builder.js').IR} ir - Intermediate representation
+ * @returns {string} Mermaid diagram string
+ */
+export function buildMermaid(ir) {
+  const { nodes, groups, links } = ir;
+
+  if (nodes.length === 0 && groups.length === 0) {
+    return 'flowchart TD\n  %% Empty flow — no nodes to display';
+  }
+
+  const lines = ['flowchart TD'];
+  const hasDirty = nodes.some((n) => n.dirty);
+  const hasDisabled = nodes.some((n) => n.d);
+
+  // Build member-to-group lookup
+  const memberGroupMap = new Map();
+  for (const g of groups) {
+    for (const mid of g.nodes) {
+      memberGroupMap.set(mid, g);
+    }
+  }
+
+  // Identify grouped vs ungrouped nodes
+  const groupedIds = new Set();
+  for (const n of nodes) {
+    if (memberGroupMap.has(n.id)) {
+      groupedIds.add(n.id);
+    }
+  }
+  const ungroupedIds = new Set(nodes.map((n) => n.id).filter((id) => !groupedIds.has(id)));
+
+  const nodeIds = new Set(nodes.map((n) => n.id));
+
+  // Render ungrouped nodes
+  for (const node of nodes) {
+    if (!ungroupedIds.has(node.id)) continue;
+    const label = escapeMermaidLabel(node.name);
+    const classTag = getMermaidClass(node);
+    lines.push(`  ${node.id}[${label}]${classTag}`);
+  }
+
+  // Render groups as subgraphs
+  for (const g of groups) {
+    const gMembers = (g.nodes || []).filter((mid) => nodeIds.has(mid));
+    const gLabel = escapeMermaidLabel(g.name || 'Group');
+    lines.push(`  subgraph ${g.id}[${gLabel}]`);
+    for (const mid of gMembers) {
+      const member = nodes.find((n) => n.id === mid);
+      if (!member) continue;
+      const mLabel = escapeMermaidLabel(member.name);
+      const mClass = getMermaidClass(member);
+      lines.push(`    ${mid}[${mLabel}]${mClass}`);
+    }
+    lines.push('  end');
+  }
+
+  // Edge definitions
+  for (const link of links) {
+    const { source, sourcePort, target } = link;
+    if (!nodeIds.has(target.id)) continue;
+    const edgeLabel = source.outputs > 1 ? `|out${sourcePort + 1}|` : '';
+    lines.push(`  ${source.id} -->${edgeLabel} ${target.id}`);
+  }
+
+  // Group style definitions
+  for (const g of groups) {
+    if (g.style && Object.keys(g.style).length > 0) {
+      const styleProps = Object.entries(g.style)
+        .map(([k, v]) => `${k}:${v}`)
+        .join(',');
+      lines.push(`  style ${g.id} ${styleProps}`);
+    }
+  }
+
+  // Class definitions
+  if (hasDirty) {
+    lines.push('  classDef dirty stroke:#ff8c00,stroke-width:3px');
+  }
+  if (hasDisabled) {
+    lines.push('  classDef disabled stroke-dasharray:5 5,stroke:#999,color:#999');
+  }
+
+  return lines.join('\n');
+}

package/src/renderer/svg-builder.js

@@ -0,0 +1,228 @@
+/**
+ * SVG Builder
+ *
+ * Generates server-side SVG strings from the intermediate representation.
+ * Produces a static SVG suitable for embedding in chat responses.
+ *
+ * @module renderer/svg-builder
+ */
+
+import { generateLinkPath } from './geometry.js';
+import { computeBoundingBox, calculateViewBox } from './layout.js';
+import {
+  getNodeColor,
+  getNodeStyle,
+  DEFAULT_COLOR,
+  DISABLED_STYLE,
+} from './colors.js';
+
+/**
+ * Build an SVG string from the intermediate representation.
+ *
+ * @param {import('./ir-builder.js').IR} ir - Intermediate representation
+ * @returns {string} Complete SVG document as a string
+ */
+export function buildSVG(ir) {
+  const { nodes, groups, links } = ir;
+  const { viewBox, width, height } = calculateViewBox(nodes, groups);
+  const hasDirtyNodes = nodes.some((n) => n.dirty);
+
+  const parts = [];
+
+  // SVG header
+  parts.push(
+    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${viewBox}" width="${width}" height="${height}">`
+  );
+
+  // Defs
+  parts.push('  <defs>');
+  parts.push(
+    `    <pattern id="grid" width="20" height="20" patternUnits="userSpaceOnUse">`
+  );
+  parts.push(
+    `      <path d="M 20 0 L 0 0 0 20" fill="none" stroke="#e0e0e0" stroke-width="0.5"/>`
+  );
+  parts.push(`    </pattern>`);
+  parts.push('  </defs>');
+
+  // Grid background
+  parts.push(
+    `  <rect width="100%" height="100%" fill="url(#grid)" class="nr-grid"/>`
+  );
+
+  // Groups layer
+  for (const g of groups) {
+    parts.push(...buildGroupSVG(g));
+  }
+
+  // Links layer
+  for (const link of links) {
+    parts.push(...buildLinkSVG(link));
+  }
+
+  // Nodes layer
+  for (const node of nodes) {
+    parts.push(...buildNodeSVG(node));
+  }
+
+  // Legend for dirty highlighting
+  if (hasDirtyNodes) {
+    parts.push(...buildLegend(nodes));
+  }
+
+  // SVG footer
+  parts.push('</svg>');
+
+  return parts.join('\n');
+}
+
+/**
+ * Build SVG elements for a group.
+ *
+ * @param {import('./ir-builder.js').IRGroup} g - Group
+ * @returns {string[]} SVG lines
+ */
+function buildGroupSVG(g) {
+  const lines = [];
+  const label = escapeXml(g.name);
+  const fillColor = g.style?.fill || 'none';
+  const strokeColor = g.style?.stroke || '#999';
+  const strokeOpacity = g.style?.['stroke-opacity'] ?? 0.5;
+
+  lines.push(
+    `  <g class="nr-group" id="${g.id}">`
+  );
+  lines.push(
+    `    <rect x="${g.x}" y="${g.y}" width="${g.w}" height="${g.h}" rx="4" ry="4" fill="${fillColor}" fill-opacity="${g.style?.['fill-opacity'] ?? 0.1}" stroke="${strokeColor}" stroke-opacity="${strokeOpacity}" stroke-dasharray="5,3"/>`
+  );
+  lines.push(
+    `    <text x="${g.x + 5}" y="${g.y + 15}" font-size="10" fill="${g.style?.color || '#999'}" font-family="sans-serif">${label}</text>`
+  );
+  lines.push(`  </g>`);
+  return lines;
+}
+
+/**
+ * Build SVG elements for a wire/link.
+ *
+ * @param {import('./ir-builder.js').IRLink} link - Link
+ * @returns {string[]} SVG lines
+ */
+function buildLinkSVG(link) {
+  const { source, sourcePort, target } = link;
+
+  // Calculate port Y positions
+  const numOutputs = source.outputs || 1;
+  const portY = -((numOutputs - 1) / 2) * 13 + 13 * sourcePort;
+
+  const x1 = source.x + source.w / 2;
+  const y1 = source.y + portY;
+  const x2 = target.x - target.w / 2;
+  const y2 = target.y;
+
+  const pathD = generateLinkPath(x1, y1, x2, y2, 1);
+
+  return [
+    `  <path class="nr-link" d="${pathD}" fill="none" stroke="#999" stroke-width="1.5"/>`,
+  ];
+}
+
+/**
+ * Build SVG elements for a node.
+ *
+ * @param {import('./ir-builder.js').IRNode} node - Node
+ * @returns {string[]} SVG lines
+ */
+function buildNodeSVG(node) {
+  const lines = [];
+  const color = getNodeColor(node.type);
+  const style = getNodeStyle(node, color);
+  const label = escapeXml(truncateLabel(node.name, 15));
+  const x = node.x - node.w / 2;
+  const y = node.y - node.h / 2;
+
+  lines.push(`  <g class="nr-node-group" id="${node.id}">`);
+
+  // Main node rectangle
+  lines.push(
+    `    <rect class="nr-node" x="${x}" y="${y}" width="${node.w}" height="${node.h}" rx="5" ry="5" style="${style}"/>`
+  );
+
+  // Dirty highlight overlay
+  if (node.dirty) {
+    lines.push(
+      `    <rect class="nr-node-dirty-glow" x="${x - 2}" y="${y - 2}" width="${node.w + 4}" height="${node.h + 4}" rx="6" ry="6" fill="none" stroke="#ff8c00" stroke-width="2.5"/>`
+    );
+  }
+
+  // Node label
+  lines.push(
+    `    <text x="${node.x}" y="${node.y + 5}" text-anchor="middle" font-size="10" fill="#333" font-family="sans-serif">${label}</text>`
+  );
+
+  // Input port indicator
+  if (node.inputs > 0) {
+    lines.push(
+      `    <rect class="nr-port" x="${x - 4}" y="${y + node.h / 2 - 4}" width="8" height="8" rx="2" fill="#999"/>`
+    );
+  }
+
+  // Output port indicators
+  const numOutputs = node.outputs || 0;
+  for (let i = 0; i < numOutputs; i++) {
+    const portY = y + node.h / 2 - ((numOutputs - 1) / 2) * 13 + 13 * i - 4;
+    lines.push(
+      `    <rect class="nr-port" x="${x + node.w - 4}" y="${portY}" width="8" height="8" rx="2" fill="#999"/>`
+    );
+  }
+
+  lines.push(`  </g>`);
+  return lines;
+}
+
+/**
+ * Build a legend explaining the dirty highlight.
+ *
+ * @param {import('./ir-builder.js').IRNode[]} nodes - All nodes (to find bounding box top-right)
+ * @returns {string[]} SVG lines
+ */
+function buildLegend(nodes) {
+  const bb = computeBoundingBox(nodes);
+  const legendX = bb.maxX - 180;
+  const legendY = bb.minY + 10;
+
+  return [
+    `  <g class="nr-legend" transform="translate(${legendX}, ${legendY})">`,
+    `    <rect x="0" y="0" width="170" height="28" rx="4" fill="white" fill-opacity="0.9" stroke="#ccc"/>`,
+    `    <rect x="8" y="8" width="16" height="12" rx="2" fill="${DEFAULT_COLOR}" stroke="#ff8c00" stroke-width="2"/>`,
+    `    <text x="30" y="18" font-size="10" fill="#666" font-family="sans-serif">= Un-deployed changes</text>`,
+    `  </g>`,
+  ];
+}
+
+/**
+ * Escape a string for safe inclusion in XML/SVG.
+ *
+ * @param {string} str
+ * @returns {string}
+ */
+function escapeXml(str) {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+/**
+ * Truncate a label to a maximum length, adding ellipsis if needed.
+ *
+ * @param {string} label
+ * @param {number} maxLen
+ * @returns {string}
+ */
+function truncateLabel(label, maxLen) {
+  if (label.length <= maxLen) return label;
+  return label.substring(0, maxLen - 1) + '…';
+}