@gmag11/nodered-mcp-server 1.0.1

package/src/skills/loader.js

@@ -0,0 +1,84 @@
+/**
+ * Skill Loader — reads and caches skill content from `resources/skills/* /SKILL.md` files.
+ *
+ * Each skill directory contains a SKILL.md file with YAML frontmatter (name, description, etc.)
+ * followed by Markdown body content.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+
+/**
+ * Extract the first sentence from a description string for use as a use-case hint.
+ *
+ * Splits on ". " (period + space) boundaries and returns the first sentence.
+ * Falls back to the full description if it's a single sentence.
+ *
+ * @param {string} description
+ * @returns {string}
+ */
+function firstSentence(description) {
+  if (!description) return '';
+  const idx = description.indexOf('. ');
+  if (idx === -1) return description;
+  return description.slice(0, idx + 1); // include the period
+}
+
+/**
+ * Load all skills from the resources skills directory.
+ *
+ * Scans `resources/skills/* /SKILL.md`, parses YAML frontmatter, and returns a Map
+ * keyed by skill name.
+ *
+ * @param {string} basePath — project root directory (resolved by caller)
+ * @returns {Map<string, { name: string, description: string, content: string, path: string, category: string, useCase: string }>}
+ */
+export function loadSkills(basePath) {
+  const skillsDir = path.join(basePath, 'resources', 'skills');
+  const skills = new Map();
+
+  // Handle missing skills directory gracefully — return empty map
+  if (!fs.existsSync(skillsDir)) {
+    return skills;
+  }
+
+  if (!fs.statSync(skillsDir).isDirectory()) {
+    return skills;
+  }
+
+  const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+
+    const skillFile = path.join(skillsDir, entry.name, 'SKILL.md');
+
+    // Skip directories without a SKILL.md
+    if (!fs.existsSync(skillFile)) continue;
+
+    try {
+      const raw = fs.readFileSync(skillFile, 'utf-8');
+      const parsed = matter(raw);
+
+      const skillName = parsed.data.name || entry.name;
+      const description = parsed.data.description || '';
+      const content = parsed.content.trim();
+      const category = parsed.data.category || entry.name;
+      const useCase = firstSentence(description);
+
+      skills.set(skillName, {
+        name: skillName,
+        description,
+        content,
+        path: skillFile,
+        category,
+        useCase,
+      });
+    } catch {
+      // Skip files that cannot be read or parsed
+    }
+  }
+
+  return skills;
+}

package/src/staging-store.js

@@ -0,0 +1,258 @@
+/**
+ * In-Memory Staging Store for Node-RED MCP Server.
+ *
+ * Holds a mutable copy of the Node-RED flows, enabling write tools to stage
+ * changes locally and deploy explicitly. Mirrors the Node-RED editor's
+ * "workspace + explicit deploy" model.
+ *
+ * Key features:
+ * - Lazy-loads flows from Node-RED on first access
+ * - Tracks dirty nodes and flows for granular deploys
+ * - Provides deploy with three modes: full, flows, nodes
+ * - Supports invalidation and summary for LLM context
+ */
+
+export class StagingStore {
+  /** @type {ReturnType<import('./nodered/client.js').createNodeRedClient>} */
+  #client;
+
+  /** @type {object[]} */
+  #flows = [];
+
+  /** @type {string|null} */
+  #rev = null;
+
+  /** @type {Set<string>} */
+  #dirtyNodeIds = new Set();
+
+  /** @type {Set<string>} */
+  #dirtyFlowIds = new Set();
+
+  /** @type {boolean} */
+  #isLoaded = false;
+
+  /** @type {Array<(...args: any[]) => void>} */
+  #listeners = [];
+
+  /**
+   * @param {ReturnType<import('./nodered/client.js').createNodeRedClient>} client
+   */
+  constructor(client) {
+    this.#client = client;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Public API
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Ensure flows are loaded from Node-RED (lazy-load on first access).
+   * Idempotent — no-op if already loaded.
+   *
+   * @returns {Promise<void>}
+   */
+  async ensureLoaded() {
+    if (this.#isLoaded) return;
+
+    const rawResponse = await this.#client.request('GET', '/flows');
+    this.#rev = rawResponse?.rev ?? null;
+    this.#flows = rawResponse?.flows ?? [];
+    this.#isLoaded = true;
+  }
+
+  /**
+   * Return the current staged flows array.
+   * Triggers lazy-load if not yet loaded.
+   *
+   * @returns {Promise<object[]>} The staged flows array
+   */
+  async getFlows() {
+    await this.ensureLoaded();
+    return this.#flows;
+  }
+
+  /**
+   * Apply a pure mutation function to the staged flows and track dirty state.
+   *
+   * The mutation function receives a `{ flows }` wrapper (matching the shape
+   * of `rawResponse` from GET /flows) and must return an object containing at
+   * least `updatedFlows`. Extra properties are passed through to the caller.
+   *
+   * After applying the mutation, dirty tracking auto-detects added, removed,
+   * and modified nodes by comparing before/after snapshots.
+   *
+   * @template T
+   * @param {(rawResponse: { flows: object[] }) => { updatedFlows: object[], [key: string]: any }} fn - Pure mutation function
+   * @returns {Promise<T>} The result from fn, excluding `updatedFlows`
+   */
+  async applyMutation(fn) {
+    await this.ensureLoaded();
+
+    // Snapshot before mutation: id -> node
+    const beforeMap = new Map();
+    for (const node of this.#flows) {
+      beforeMap.set(node.id, node);
+    }
+
+    // Apply mutation — fn receives { flows } like the old rawResponse
+    const result = fn({ flows: this.#flows });
+    const { updatedFlows, ...output } = result;
+
+    // Snapshot after mutation
+    const afterMap = new Map();
+    for (const node of updatedFlows) {
+      afterMap.set(node.id, node);
+    }
+
+    // Track dirty: added or modified nodes
+    for (const [id, node] of afterMap) {
+      const before = beforeMap.get(id);
+      if (!before || JSON.stringify(before) !== JSON.stringify(node)) {
+        this.#dirtyNodeIds.add(id);
+        if (node.z) this.#dirtyFlowIds.add(node.z);
+        // Flow tab creation/modification also dirties the flow itself
+        if (node.type === 'tab' || node.type === 'subflow') {
+          this.#dirtyFlowIds.add(node.id);
+        }
+      }
+    }
+
+    // Track dirty: removed nodes
+    for (const [id, node] of beforeMap) {
+      if (!afterMap.has(id)) {
+        this.#dirtyNodeIds.add(id);
+        if (node.z) this.#dirtyFlowIds.add(node.z);
+        if (node.type === 'tab' || node.type === 'subflow') {
+          this.#dirtyFlowIds.add(node.id);
+        }
+      }
+    }
+
+    // Update internal state
+    this.#flows = updatedFlows;
+
+    // Emit change event for live visualization
+    this.#emit('staging:changed', {
+      dirtyNodeIds: this.#dirtyNodeIds,
+      dirtyFlowIds: this.#dirtyFlowIds,
+    });
+
+    return output;
+  }
+
+  /**
+   * Deploy the staged flows to Node-RED.
+   *
+   * Sends the full flows array via POST /flows with the specified deploy type.
+   * On success, re-fetches flows from Node-RED to sync rev and state, then
+   * clears dirty tracking. On 409 version_mismatch, throws without retrying.
+   *
+   * @param {string} [deployType='nodes'] - Node-RED-Deployment-Type header value: 'full', 'flows', or 'nodes'
+   * @returns {Promise<void>}
+   * @throws {Error} On deploy failure including version_mismatch (409)
+   */
+  async deploy(deployType = 'nodes') {
+    await this.ensureLoaded();
+
+    const flowsPayload = { rev: this.#rev, flows: this.#flows };
+
+    await this.#client.putFlows(flowsPayload, deployType);
+
+    // Re-fetch to sync rev and state
+    await this.invalidate();
+    await this.ensureLoaded();
+
+    // Clear dirty tracking — post-deploy everything is clean
+    this.#dirtyNodeIds.clear();
+    this.#dirtyFlowIds.clear();
+
+    // Emit change event after deploy (dirty sets are now empty)
+    this.#emit('staging:changed', {
+      dirtyNodeIds: this.#dirtyNodeIds,
+      dirtyFlowIds: this.#dirtyFlowIds,
+    });
+  }
+
+  /**
+   * Check whether there are pending (undeployed) changes.
+   *
+   * @returns {boolean} True if either dirty set is non-empty
+   */
+  hasPendingChanges() {
+    return this.#dirtyNodeIds.size > 0 || this.#dirtyFlowIds.size > 0;
+  }
+
+  /**
+   * Return the set of dirty node IDs.
+   *
+   * @returns {Set<string>}
+   */
+  getDirtyNodeIds() {
+    return this.#dirtyNodeIds;
+  }
+
+  /**
+   * Return the set of dirty flow IDs.
+   *
+   * @returns {Set<string>}
+   */
+  getDirtyFlowIds() {
+    return this.#dirtyFlowIds;
+  }
+
+  /**
+   * Subscribe to staging events.
+   *
+   * @param {string} event - Event name (currently only 'staging:changed')
+   * @param {(data: { dirtyNodeIds: Set<string>, dirtyFlowIds: Set<string> }) => void} callback
+   */
+  on(event, callback) {
+    this.#listeners.push({ event, callback });
+  }
+
+  /**
+   * Emit an event to all matching listeners.
+   *
+   * @param {string} event
+   * @param {object} data
+   */
+  #emit(event, data) {
+    for (const l of this.#listeners) {
+      if (l.event === event) {
+        try { l.callback(data); } catch { /* ignore listener errors */ }
+      }
+    }
+  }
+
+  /**
+   * Return a staging summary object for inclusion in tool responses.
+   *
+   * @returns {{ pendingChanges: number, dirtyNodeIds: string[], dirtyFlowIds: string[], deployed: boolean }}
+   */
+  getStagingSummary() {
+    return {
+      pendingChanges: this.#dirtyNodeIds.size,
+      dirtyNodeIds: [...this.#dirtyNodeIds],
+      dirtyFlowIds: [...this.#dirtyFlowIds],
+      deployed: !this.hasPendingChanges(),
+    };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Invalidate the staging cache. Next getFlows() or applyMutation() call
+   * will re-fetch from Node-RED. Also clears dirty tracking.
+   *
+   * @returns {Promise<void>}
+   */
+  async invalidate() {
+    this.#flows = [];
+    this.#rev = null;
+    this.#isLoaded = false;
+    this.#dirtyNodeIds.clear();
+    this.#dirtyFlowIds.clear();
+  }
+}

package/src/tools/add-nodes-to-group.js

@@ -0,0 +1,216 @@
+/**
+ * MCP tool: add-nodes-to-group
+ *
+ * Assigns a list of nodes to a Node-RED group. If the group does not
+ * exist, it is created with a computed bounding rectangle enclosing all
+ * member nodes. Nodes already in another group are automatically
+ * reassigned (their previous group membership is removed).
+ */
+
+import { randomUUID } from 'crypto';
+import { computeBoundingBox } from './flow-utils.js';
+
+import { ANN_MUTATION } from './constants.js';
+import { AddNodesToGroupResponseSchema } from '../schemas/responses.js';
+/** Default group style, matching Node-RED's defaults. */
+const DEFAULT_GROUP_STYLE = {
+  label: true,
+  fill: '#ffff7f',
+  'fill-opacity': '0.5',
+  stroke: '#000000',
+  'label-position': 'nw',
+  color: '#000000',
+};
+
+/**
+ * Apply the add-nodes-to-group operation to the flows array.
+ *
+ * @param {object} rawResponse - Raw GET /flows response (must contain `flows` array)
+ * @param {string} flowId - ID of the flow tab where nodes reside
+ * @param {string[]} nodeIds - IDs of nodes to add to the group
+ * @param {object} [options]
+ * @param {string} [options.groupId] - Existing group ID; if omitted, a new group is created
+ * @param {string} [options.groupName] - Name for new groups (ignored if groupId is provided)
+ * @param {object} [options.style] - Style overrides for new groups (merged onto defaults)
+ * @returns {{ updatedFlows: object[], groupId: string, groupName: string, nodeIds: string[], boundingBox: { x: number, y: number, w: number, h: number }, created: boolean }}
+ */
+export function applyAddNodesToGroup(rawResponse, flowId, nodeIds, options = {}) {
+  const { groupId, groupName, style } = options;
+  const flows = rawResponse.flows ?? rawResponse;
+
+  // Validate flow exists and is not locked
+  const targetFlow = flows.find(
+    (n) => (n.type === 'tab' || n.type === 'subflow') && n.id === flowId,
+  );
+  if (!targetFlow) {
+    throw new Error(`Flow '${flowId}' not found. Use get-flows to list available flow tabs and subflows.`);
+  }
+  if (targetFlow.locked) {
+    throw new Error(`Flow '${flowId}' is locked. This flow is locked (read-only). Use get-flow-nodes to inspect its nodes without modifying them.`);
+  }
+
+  // Resolve all target nodes, validating existence and flow membership
+  const nodes = [];
+  for (const nid of nodeIds) {
+    const node = flows.find((n) => n.id === nid);
+    if (!node) {
+      throw new Error(`Node '${nid}' not found. Use search-nodes with the node name or get-flow-nodes to list nodes in the flow.`);
+    }
+    if (node.z !== flowId) {
+      throw new Error(`All nodes must belong to flow '${flowId}'. Use get-flow-nodes to verify which flow each node belongs to.`);
+    }
+    nodes.push(node);
+  }
+
+  let targetGroupId;
+  let created = false;
+  let updatedFlows = [...flows];
+
+  if (groupId) {
+    // ── Existing group ──────────────────────────────────────
+    const groupIndex = updatedFlows.findIndex(
+      (n) => n.type === 'group' && n.id === groupId,
+    );
+    if (groupIndex === -1) {
+      throw new Error(`Group '${groupId}' not found. Use get-flow-nodes to list groups in the flow, or search-nodes with type: "group" to find it.`);
+    }
+    targetGroupId = groupId;
+  } else {
+    // ── Create new group ─────────────────────────────────────
+    targetGroupId = randomUUID();
+    created = true;
+
+    const box = computeBoundingBox(nodes, 20);
+    const mergedStyle = { ...DEFAULT_GROUP_STYLE, ...style };
+
+    // Default name: use provided name, or first node's name, or "Group"
+    const defaultName = groupName || nodes[0]?.name || 'Group';
+
+    const newGroup = {
+      id: targetGroupId,
+      type: 'group',
+      z: flowId,
+      name: defaultName,
+      style: mergedStyle,
+      nodes: [],
+      x: box.x,
+      y: box.y,
+      w: box.w,
+      h: box.h,
+    };
+
+    updatedFlows = [...updatedFlows, newGroup];
+  }
+
+  // ── Assign nodes to the group ────────────────────────────
+  const groupIndex = updatedFlows.findIndex(
+    (n) => n.type === 'group' && n.id === targetGroupId,
+  );
+  const group = updatedFlows[groupIndex];
+  const groupNodes = new Set(group.nodes || []);
+
+  for (const node of nodes) {
+    const nodeIndex = updatedFlows.findIndex((n) => n.id === node.id);
+
+    // If node already belongs to a different group, remove it from that group
+    if (node.g && node.g !== targetGroupId) {
+      const prevGroupIndex = updatedFlows.findIndex(
+        (n) => n.type === 'group' && n.id === node.g,
+      );
+      if (prevGroupIndex !== -1) {
+        const prevGroup = updatedFlows[prevGroupIndex];
+        updatedFlows[prevGroupIndex] = {
+          ...prevGroup,
+          nodes: (prevGroup.nodes || []).filter((nid) => nid !== node.id),
+        };
+      }
+    }
+
+    // Set g on the node (idempotent)
+    updatedFlows[nodeIndex] = { ...node, g: targetGroupId };
+
+    // Add to group's nodes list (idempotent)
+    groupNodes.add(node.id);
+  }
+
+  // Update group's nodes array
+  updatedFlows[groupIndex] = {
+    ...updatedFlows[groupIndex],
+    nodes: [...groupNodes],
+  };
+
+  // Re-compute bounding box for the final group
+  const finalGroup = updatedFlows[groupIndex];
+  const allMemberNodes = (finalGroup.nodes || [])
+    .map((nid) => updatedFlows.find((n) => n.id === nid))
+    .filter(Boolean);
+  const boundingBox = computeBoundingBox(allMemberNodes, 20);
+
+  // Update bounding box on the group
+  updatedFlows[groupIndex] = {
+    ...updatedFlows[groupIndex],
+    x: boundingBox.x,
+    y: boundingBox.y,
+    w: boundingBox.w,
+    h: boundingBox.h,
+  };
+
+  return {
+    updatedFlows,
+    groupId: targetGroupId,
+    groupName: updatedFlows[groupIndex].name,
+    nodeIds: [...groupNodes],
+    boundingBox,
+    created,
+  };
+}
+
+/**
+ * Handler for the add-nodes-to-group MCP tool.
+ *
+ * @param {ReturnType<import('../nodered/client.js').createNodeRedClient>} client
+ * @param {object} params
+ * @param {string} params.flowId
+ * @param {string[]} params.nodeIds
+ * @param {string} [params.groupId]
+ * @param {string} [params.groupName]
+ * @param {object} [params.style]
+ * @returns {Promise<{ content: Array<{ type: string, text: string }> }>}
+ */
+export async function handleAddNodesToGroup(staging, client, params) {
+  const { flowId, nodeIds, groupId, groupName, style } = params;
+
+  const result = await staging.applyMutation((rawResponse) => {
+    return applyAddNodesToGroup(rawResponse, flowId, nodeIds, {
+      groupId,
+      groupName,
+      style,
+    });
+  });
+
+  const responseData = {
+    groupId: result.groupId,
+    groupName: result.groupName,
+    nodeIds: result.nodeIds,
+    boundingBox: result.boundingBox,
+    created: result.created,
+    staging: staging.getStagingSummary(),
+  };
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(responseData, null, 2),
+      },
+    ],
+    structuredContent: responseData,
+  };
+}
+
+export const addNodesToGroupDefinition = {
+  name: 'add-nodes-to-group',
+  annotations: ANN_MUTATION,
+  outputSchema: AddNodesToGroupResponseSchema,
+  handler: handleAddNodesToGroup,
+};

package/src/tools/connect-nodes.js

@@ -0,0 +1,115 @@
+/**
+ * MCP tool: connect-nodes
+ *
+ * Adds a wire from a node's output port to a target node.
+ * Supports single-wire mode (outputPort + toNodeId) and batch mode (connections array).
+ * Idempotent — no-op if the wire already exists.
+ * Refuses to wire nodes in locked flows.
+ */
+
+import { formatSuccess } from './response-utils.js';
+
+import { ANN_MUTATION } from './constants.js';
+import { WireChangeResponseSchema } from '../schemas/responses.js';
+/**
+ * Apply a wire connection in the flows array.
+ *
+ * In single-wire mode, provide outputPort and toNodeId.
+ * In batch mode, provide connections (array of { outputPort, toNodeId });
+ * outputPort and toNodeId are ignored when connections is provided.
+ *
+ * @param {object} rawResponse - Raw GET /flows response (must contain `flows` array)
+ * @param {string} fromNodeId - ID of the source node
+ * @param {number} [outputPort=0] - Output port index (0-based) — ignored in batch mode
+ * @param {string} [toNodeId] - ID of the target node — ignored in batch mode
+ * @param {Array<{ outputPort: number, toNodeId: string }>} [connections] - Batch connections
+ * @returns {{ updatedFlows: object[], previousWires: string[][], currentWires: string[][] }}
+ */
+export function applyConnect(rawResponse, fromNodeId, outputPort = 0, toNodeId, connections) {
+  const flows = rawResponse.flows ?? rawResponse;
+
+  // Find source node
+  const fromIndex = flows.findIndex((n) => n.id === fromNodeId);
+  if (fromIndex === -1) {
+    throw new Error(`Node '${fromNodeId}' not found. Use search-nodes with the node name or get-flow-nodes to list nodes in the parent flow.`);
+  }
+
+  const fromNode = flows[fromIndex];
+
+  // Check parent flow lock
+  const parentFlowId = fromNode.z;
+  if (parentFlowId) {
+    const parentFlow = flows.find(
+      (n) => (n.type === 'tab' || n.type === 'subflow') && n.id === parentFlowId,
+    );
+    if (parentFlow?.locked) {
+      throw new Error(`Flow '${parentFlowId}' is locked. This flow is locked (read-only). Use get-flow-nodes to inspect its nodes without modifying them.`);
+    }
+  }
+
+  // Determine entries: batch mode takes precedence
+  const entries = connections ?? [{ outputPort, toNodeId }];
+
+  // Validate all target nodes exist BEFORE any mutation (atomicity)
+  for (const entry of entries) {
+    const targetExists = flows.some((n) => n.id === entry.toNodeId);
+    if (!targetExists) {
+      throw new Error(`Node '${entry.toNodeId}' not found. Use search-nodes with the node name or get-flow-nodes to list nodes in the parent flow.`);
+    }
+  }
+
+  const previousWires = (fromNode.wires ?? []).map((port) => [...port]);
+
+  // Deep-copy the wires array so we can mutate safely
+  const newWires = (fromNode.wires ?? []).map((port) => [...port]);
+
+  // Apply each connection idempotently
+  for (const entry of entries) {
+    const port = entry.outputPort;
+
+    // Pad wires array to accommodate the requested output port
+    while (newWires.length <= port) {
+      newWires.push([]);
+    }
+
+    // Add connection idempotently
+    if (!newWires[port].includes(entry.toNodeId)) {
+      newWires[port].push(entry.toNodeId);
+    }
+  }
+
+  const currentWires = newWires;
+  const updatedNode = { ...fromNode, wires: currentWires };
+  const updatedFlows = flows.map((n, i) => (i === fromIndex ? updatedNode : n));
+
+  return { updatedFlows, previousWires, currentWires };
+}
+
+/**
+ * Handler for the connect-nodes MCP tool.
+ *
+ * @param {ReturnType<import('../nodered/client.js').createNodeRedClient>} client
+ * @param {object} params
+ * @param {string} params.fromNodeId
+ * @param {number} [params.outputPort=0]
+ * @param {string} [params.toNodeId]
+ * @param {Array<{ outputPort: number, toNodeId: string }>} [params.connections]
+ * @returns {Promise<{ content: Array<{ type: string, text: string }> }>}
+ */
+export async function handleConnectNodes(staging, client, params) {
+  const { fromNodeId, outputPort = 0, toNodeId, connections } = params;
+
+  const { previousWires, currentWires } = await staging.applyMutation((rawResponse) => {
+    return applyConnect(rawResponse, fromNodeId, outputPort, toNodeId, connections);
+  });
+
+      const data = { fromNodeId, previousWires, currentWires, staging: staging.getStagingSummary() };
+    return formatSuccess(data);
+}
+
+export const connectNodesDefinition = {
+  name: 'connect-nodes',
+  annotations: ANN_MUTATION,
+  outputSchema: WireChangeResponseSchema,
+  handler: handleConnectNodes,
+};