@gmag11/nodered-mcp-server 1.0.1

package/src/tools/delete-group.js

@@ -0,0 +1,116 @@
+import { ANN_DESTRUCTIVE } from './constants.js';
+import { DeleteGroupResponseSchema } from '../schemas/responses.js';
+/**
+ * MCP tool: delete-group
+ *
+ * Permanently removes a Node-RED group. By default, all member nodes are
+ * also deleted. Set `deleteMembers: false` to strip group membership and
+ * keep the nodes.
+ */
+
+/**
+ * Apply the delete-group operation to the flows array.
+ *
+ * @param {object} rawResponse - Raw GET /flows response (must contain `flows` array)
+ * @param {string} groupId - ID of the group to delete
+ * @param {object} [options]
+ * @param {boolean} [options.deleteMembers=true] - Whether to also delete member nodes
+ * @returns {{ updatedFlows: object[], previousState: { group: object, members: object[] } }}
+ */
+export function applyDeleteGroup(rawResponse, groupId, options = {}) {
+  const { deleteMembers = true } = options;
+  const flows = rawResponse.flows ?? rawResponse;
+
+  // Find the group
+  const groupIndex = flows.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 parent flow, or search-nodes with type: "group" to find it.`);
+  }
+
+  const group = flows[groupIndex];
+
+  // Check parent flow lock
+  if (group.z) {
+    const parentFlow = flows.find(
+      (n) => (n.type === 'tab' || n.type === 'subflow') && n.id === group.z,
+    );
+    if (parentFlow?.locked) {
+      throw new Error(`Flow '${group.z}' is locked. This flow is locked (read-only). Use get-flow-nodes to inspect its nodes without modifying them.`);
+    }
+  }
+
+  // Collect member nodes for previousState
+  const memberIds = group.nodes || [];
+  const members = flows.filter(
+    (n) => memberIds.includes(n.id),
+  );
+  const previousState = {
+    group: { ...group },
+    members: members.map((m) => ({ ...m })),
+  };
+
+  let updatedFlows = [...flows];
+
+  if (deleteMembers && memberIds.length > 0) {
+    // Delete all member nodes
+    updatedFlows = updatedFlows.filter(
+      (n) => !memberIds.includes(n.id),
+    );
+  } else if (!deleteMembers && memberIds.length > 0) {
+    // Strip g from all members, keep the nodes
+    updatedFlows = updatedFlows.map((n) => {
+      if (memberIds.includes(n.id)) {
+        const { g: _g, ...rest } = n;
+        return rest;
+      }
+      return n;
+    });
+  }
+
+  // Delete the group node itself
+  updatedFlows = updatedFlows.filter((n) => n.id !== groupId);
+
+  return { updatedFlows, previousState };
+}
+
+/**
+ * Handler for the delete-group MCP tool.
+ *
+ * @param {ReturnType<import('../nodered/client.js').createNodeRedClient>} client
+ * @param {object} params
+ * @param {string} params.groupId
+ * @param {boolean} [params.deleteMembers=true]
+ * @returns {Promise<{ content: Array<{ type: string, text: string }> }>}
+ */
+export async function handleDeleteGroup(staging, client, params) {
+  const { groupId, deleteMembers } = params;
+
+  const result = await staging.applyMutation((rawResponse) => {
+    return applyDeleteGroup(rawResponse, groupId, { deleteMembers });
+  });
+
+  const responseData = {
+    groupId,
+    previousState: result.previousState,
+    staging: staging.getStagingSummary(),
+  };
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(responseData, null, 2),
+      },
+    ],
+    structuredContent: responseData,
+  };
+}
+
+export const deleteGroupDefinition = {
+  name: 'delete-group',
+  annotations: ANN_DESTRUCTIVE,
+  outputSchema: DeleteGroupResponseSchema,
+  handler: handleDeleteGroup,
+};

package/src/tools/delete-node.js

@@ -0,0 +1,73 @@
+/**
+ * MCP tool: delete-node
+ *
+ * Removes an existing node from a Node-RED flow by nodeId.
+ * Node-RED automatically cleans up dangling wire references on deploy.
+ * Refuses to delete nodes in locked flows.
+ */
+
+import { formatSuccess } from './response-utils.js';
+
+import { ANN_DESTRUCTIVE } from './constants.js';
+import { DeleteNodeResponseSchema } from '../schemas/responses.js';
+/**
+ * Apply the delete-node operation to the flows array.
+ *
+ * @param {object} rawResponse - Raw GET /flows response (must contain `flows` array)
+ * @param {string} nodeId - ID of the node to remove
+ * @returns {{ updatedFlows: object[], previousState: object }}
+ */
+export function applyDeleteNode(rawResponse, nodeId) {
+  const flows = rawResponse.flows ?? rawResponse;
+
+  // Find the node to delete
+  const nodeIndex = flows.findIndex((n) => n.id === nodeId);
+  if (nodeIndex === -1) {
+    throw new Error(`Node '${nodeId}' not found. Use search-nodes with the node name or get-flow-nodes to list nodes in the parent flow.`);
+  }
+
+  const node = flows[nodeIndex];
+
+  // Check parent flow lock
+  const parentFlowId = node.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.`);
+    }
+  }
+
+  const previousState = { ...node };
+  const updatedFlows = flows.filter((n) => n.id !== nodeId);
+
+  return { updatedFlows, previousState };
+}
+
+/**
+ * Handler for the delete-node MCP tool.
+ *
+ * @param {ReturnType<import('../nodered/client.js').createNodeRedClient>} client
+ * @param {object} params
+ * @param {string} params.nodeId
+ * @returns {Promise<{ content: Array<{ type: string, text: string }> }>}
+ */
+
+export async function handleDeleteNode(staging, client, params) {
+  const { nodeId } = params;
+
+  const { previousState } = await staging.applyMutation((rawResponse) => {
+    return applyDeleteNode(rawResponse, nodeId);
+  });
+
+      const data = { nodeId, previousState, staging: staging.getStagingSummary() };
+    return formatSuccess(data);
+}
+
+export const deleteNodeDefinition = {
+  name: 'delete-node',
+  annotations: ANN_DESTRUCTIVE,
+  outputSchema: DeleteNodeResponseSchema,
+  handler: handleDeleteNode,
+};

package/src/tools/delete-subflow.js

@@ -0,0 +1,103 @@
+/**
+ * MCP tool: delete-subflow
+ *
+ * Deletes a subflow definition, its internal nodes, and optionally
+ * its instances. Returns previousState for undo support.
+ * Refuses to delete a locked subflow.
+ */
+
+import { formatSuccess } from './response-utils.js';
+
+import { ANN_DESTRUCTIVE } from './constants.js';
+import { DeleteSubflowResponseSchema } from '../schemas/responses.js';
+/**
+ * Collect the full previous state of a subflow before deletion.
+ *
+ * @param {object[]} flows - All nodes from the flows array
+ * @param {string} subflowId - ID of the subflow to collect
+ * @returns {{ definition: object|undefined, internalNodes: object[], instances: object[] }}
+ * @throws {Error} If subflowId does not match any type: "subflow" node
+ */
+export function collectSubflowState(flows, subflowId) {
+  const definition = flows.find(
+    (n) => n.type === 'subflow' && n.id === subflowId,
+  );
+
+  if (!definition) {
+    throw new Error(`Subflow '${subflowId}' not found. Use get-subflows to list available subflow definitions.`);
+  }
+
+  if (definition.locked) {
+    throw new Error(`Subflow '${subflowId}' is locked. This subflow is locked (read-only). Use get-subflow-detail to inspect it without modifying.`);
+  }
+
+  const internalNodes = flows.filter(
+    (n) => n.z === subflowId,
+  );
+
+  const instanceType = `subflow:${subflowId}`;
+  const instances = flows.filter(
+    (n) => n.type === instanceType,
+  );
+
+  return { definition, internalNodes, instances };
+}
+
+/**
+ * Remove a subflow and related nodes from the flows array.
+ *
+ * @param {object[]} flows - All nodes from the flows array
+ * @param {string} subflowId - ID of the subflow to delete
+ * @param {boolean} deleteInstances - Whether to also delete instances
+ * @returns {{ updatedFlows: object[], previousState: object }}
+ * @throws {Error} If subflow not found or is locked
+ */
+export function applyDeleteSubflow(flows, subflowId, deleteInstances) {
+  const previousState = collectSubflowState(flows, subflowId);
+
+  // Build set of IDs to remove
+  const idsToRemove = new Set();
+  idsToRemove.add(subflowId);
+
+  for (const node of previousState.internalNodes) {
+    idsToRemove.add(node.id);
+  }
+
+  if (deleteInstances) {
+    for (const node of previousState.instances) {
+      idsToRemove.add(node.id);
+    }
+  }
+
+  const updatedFlows = flows.filter((n) => !idsToRemove.has(n.id));
+
+  return { updatedFlows, previousState };
+}
+
+/**
+ * Handler for the delete-subflow MCP tool.
+ *
+ * @param {ReturnType<import('../nodered/client.js').createNodeRedClient>} client
+ * @param {object} params
+ * @param {string} params.subflowId
+ * @param {boolean} [params.deleteInstances=true]
+ * @returns {Promise<{ content: Array<{ type: string, text: string }> }>}
+ */
+export async function handleDeleteSubflow(staging, client, params) {
+  const { subflowId, deleteInstances = true } = params;
+
+  const { previousState } = await staging.applyMutation((rawResponse) => {
+    const flows = rawResponse.flows || [];
+    return applyDeleteSubflow(flows, subflowId, deleteInstances);
+  });
+
+      const data = { subflowId, previousState, staging: staging.getStagingSummary() };
+    return formatSuccess(data);
+}
+
+export const deleteSubflowDefinition = {
+  name: 'delete-subflow',
+  annotations: ANN_DESTRUCTIVE,
+  outputSchema: DeleteSubflowResponseSchema,
+  handler: handleDeleteSubflow,
+};

package/src/tools/deploy.js

@@ -0,0 +1,94 @@
+import { ANN_DEPLOY } from './constants.js';
+import { DeployResponseSchema } from '../schemas/responses.js';
+/**
+ * MCP tool: deploy
+ *
+ * Sends all staged (undeployed) flow changes to the Node-RED runtime.
+ * Supports three deploy types: full, flows, and nodes.
+ *
+ * By default, deploys only modified nodes (`nodes` deploy) which is the
+ * least disruptive — only changed nodes are restarted.
+ *
+ * After a successful deploy, the staging store syncs with the Node-RED
+ * backend to obtain the latest rev and state.
+ */
+
+/**
+ * Handler for the deploy MCP tool.
+ *
+ * @param {import('../staging-store.js').StagingStore} staging
+ * @returns {(params: { deployType?: string }) => Promise<{ content: Array<{ type: string, text: string }> }>}
+ */
+export function handleDeploy(staging) {
+  return async (params) => {
+    const { deployType = 'nodes' } = params || {};
+
+    // Validate deploy type
+    const validTypes = ['full', 'flows', 'nodes'];
+    if (!validTypes.includes(deployType)) {
+      throw new Error(
+        `Invalid deploy type "${deployType}". Use one of: ${validTypes.join(', ')}`,
+      );
+    }
+
+    const summaryBefore = staging.getStagingSummary();
+
+    if (!staging.hasPendingChanges()) {
+      const noPendingData = {
+        success: true,
+        message: 'No pending changes to deploy.',
+        staging: summaryBefore,
+      };
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(noPendingData, null, 2),
+          },
+        ],
+        structuredContent: noPendingData,
+      };
+    }
+
+    try {
+      await staging.deploy(deployType);
+    } catch (err) {
+      const msg = err.message || '';
+      if (msg.includes('version_mismatch') || msg.includes('409')) {
+        throw new Error(
+          'Deploy failed: version mismatch. The flows have been modified externally ' +
+          '(e.g., via the Node-RED editor). Your staged changes have been discarded. ' +
+          'Call refresh-staging to sync with the latest server state, then re-apply your changes and deploy again.',
+        );
+      }
+      throw err;
+    }
+
+    const summaryAfter = staging.getStagingSummary();
+
+    const deployData = {
+      success: true,
+      deployType,
+      previousPendingChanges: summaryBefore.pendingChanges,
+      staging: summaryAfter,
+    };
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(deployData, null, 2),
+        },
+      ],
+      structuredContent: deployData,
+    };
+  };
+}
+
+export const deployDefinition = {
+  name: 'deploy',
+  annotations: ANN_DEPLOY,
+  outputSchema: DeployResponseSchema,
+  handler: handleDeploy,
+};

package/src/tools/disconnect-nodes.js

@@ -0,0 +1,158 @@
+/**
+ * MCP tool: disconnect-nodes
+ *
+ * Removes wires from a node's output ports.
+ * Supports three modes:
+ *   1. Single: remove one specific wire (outputPort + toNodeId)
+ *   2. Clear-port: remove all wires from an output port (clearPort=true, toNodeId omitted)
+ *   3. Batch: remove multiple wires via connections array
+ * Errors if a wire does not exist.  Refuses to mutate nodes in locked flows.
+ */
+
+import { formatSuccess } from './response-utils.js';
+
+import { ANN_MUTATION } from './constants.js';
+import { WireChangeResponseSchema } from '../schemas/responses.js';
+/**
+ * Apply wire removal in the flows array.
+ *
+ * @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 to disconnect — ignored in batch/clear-port mode
+ * @param {boolean} [clearPort=false] - If true and toNodeId is absent, clear all wires from outputPort
+ * @param {Array<{ outputPort: number, toNodeId: string }>} [connections] - Batch removal entries
+ * @returns {{ updatedFlows: object[], previousWires: string[][], currentWires: string[][] }}
+ */
+export function applyDisconnect(rawResponse, fromNodeId, outputPort = 0, toNodeId, clearPort = false, 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.`);
+    }
+  }
+
+  const previousWires = (fromNode.wires ?? []).map((port) => [...port]);
+
+  // Determine mode: batch > clear-port > single
+  if (connections) {
+    // --- Batch mode ---
+    // Validate all wires exist before removing any (atomicity)
+    for (const entry of connections) {
+      const port = entry.outputPort;
+      const portWires = previousWires[port] ?? [];
+      if (!portWires.includes(entry.toNodeId)) {
+        throw new Error(
+          `Wire from '${fromNodeId}'[${port}] to '${entry.toNodeId}' does not exist. Use get-node-detail to inspect the current wiring of the source node.`,
+        );
+      }
+    }
+
+    // Build new wires — deep copy and remove all target wires
+    const newWires = previousWires.map((port) => [...port]);
+    for (const entry of connections) {
+      const port = entry.outputPort;
+      if (newWires[port]) {
+        newWires[port] = newWires[port].filter((id) => id !== entry.toNodeId);
+      }
+    }
+
+    const currentWires = newWires;
+    const updatedNode = { ...fromNode, wires: currentWires };
+    const updatedFlows = flows.map((n, i) => (i === fromIndex ? updatedNode : n));
+
+    return { updatedFlows, previousWires, currentWires };
+  }
+
+  if (clearPort && !toNodeId) {
+    // --- Clear-port mode ---
+    const newWires = previousWires.map((port, i) => {
+      if (i === outputPort) {
+        return [];
+      }
+      return [...port];
+    });
+
+    const currentWires = newWires;
+    const updatedNode = { ...fromNode, wires: currentWires };
+    const updatedFlows = flows.map((n, i) => (i === fromIndex ? updatedNode : n));
+
+    return { updatedFlows, previousWires, currentWires };
+  }
+
+  // --- Single-wire mode ---
+  // Check the wire actually exists
+  const portConnections = previousWires[outputPort];
+  if (!portConnections || !portConnections.includes(toNodeId)) {
+    throw new Error(
+      `Wire from '${fromNodeId}'[${outputPort}] to '${toNodeId}' does not exist. Use get-node-detail to inspect the current wiring of the source node.`,
+    );
+  }
+
+  // Build new wires — deep copy and remove the target
+  const newWires = previousWires.map((port, i) => {
+    if (i === outputPort) {
+      return port.filter((id) => id !== toNodeId);
+    }
+    return [...port];
+  });
+
+  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 disconnect-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 {boolean} [params.clearPort=false]
+ * @param {Array<{ outputPort: number, toNodeId: string }>} [params.connections]
+ * @returns {Promise<{ content: Array<{ type: string, text: string }> }>}
+ */
+export async function handleDisconnectNodes(staging, client, params) {
+  const { fromNodeId, outputPort = 0, toNodeId, clearPort = false, connections } = params;
+
+  const { previousWires, currentWires } = await staging.applyMutation(
+    (rawResponse) => {
+      return applyDisconnect(
+        rawResponse,
+        fromNodeId,
+        outputPort,
+        toNodeId,
+        clearPort,
+        connections,
+      );
+    }
+  );
+
+      const data = { fromNodeId, previousWires, currentWires, staging: staging.getStagingSummary() };
+    return formatSuccess(data);
+}
+
+export const disconnectNodesDefinition = {
+  name: 'disconnect-nodes',
+  annotations: ANN_MUTATION,
+  outputSchema: WireChangeResponseSchema,
+  handler: handleDisconnectNodes,
+};