@gmag11/nodered-mcp-server 1.0.1

package/src/tools/read-debug-messages.js

@@ -0,0 +1,155 @@
+/**
+ * MCP tool: read-debug-messages
+ *
+ * Reads buffered Node-RED debug messages from the CommsClient ring buffer
+ * with optional filtering by node ID, node name, keyword, and time range.
+ * Supports both head (first-N) and tail (last-N) retrieval modes.
+ */
+
+import { formatSuccess } from './response-utils.js';
+
+import { ANN_READ_DEBUG } from './constants.js';
+import { DebugMessagesResponseSchema } from '../schemas/responses.js';
+/** Default limit when neither `last` nor `limit` is provided. */
+const DEFAULT_LIMIT = 50;
+
+/**
+ * Apply filters to an array of debug messages.
+ *
+ * This is a pure function — it does not mutate the input array.
+ *
+ * Filters are applied in order:
+ *  1. `after` / `before` — inclusive timestamp bounds
+ *  2. `nodeId` — exact match on message.id
+ *  3. `nodeName` — case-insensitive substring match on message.name
+ *  4. `keyword` — case-insensitive substring match against stringified message.msg
+ *
+ * After filtering:
+ *  - If `last` is set, return the last N matching messages (chronological order)
+ *  - Otherwise, return the first `limit` matches (default: 50)
+ *
+ * @param {object[]} messages - Array of debug message objects
+ * @param {object} filters
+ * @param {string} [filters.nodeId] - Exact match on message.id
+ * @param {string} [filters.nodeName] - Case-insensitive substring on message.name
+ * @param {string} [filters.keyword] - Case-insensitive substring in stringified msg
+ * @param {number} [filters.after] - Inclusive lower timestamp bound (ms)
+ * @param {number} [filters.before] - Inclusive upper timestamp bound (ms)
+ * @param {number} [filters.last] - Return last N (mutually exclusive with limit)
+ * @param {number} [filters.limit] - Return first N (default 50; mutually exclusive with last)
+ * @returns {{ messages: object[], total: number } | { error: string }}
+ */
+export function filterMessages(messages, {
+  nodeId,
+  nodeName,
+  keyword,
+  after,
+  before,
+  last,
+  limit,
+} = {}) {
+  // Validate: last and limit are mutually exclusive
+  if (last !== undefined && limit !== undefined) {
+    return {
+      error: 'last and limit are mutually exclusive — use one or the other. Use last to get the most recent N messages (tail mode), or limit to get the first N matches (head mode, default 50).',
+    };
+  }
+
+  // Apply filters
+  let result = messages;
+
+  // Time range: after (inclusive lower bound)
+  if (after !== undefined && after !== null) {
+    result = result.filter((m) => m.timestamp >= after);
+  }
+
+  // Time range: before (inclusive upper bound)
+  if (before !== undefined && before !== null) {
+    result = result.filter((m) => m.timestamp <= before);
+  }
+
+  // Exact nodeId match
+  if (nodeId !== undefined && nodeId !== null && nodeId !== '') {
+    result = result.filter((m) => m.id === nodeId);
+  }
+
+  // nodeName substring (case-insensitive)
+  if (nodeName !== undefined && nodeName !== null && nodeName !== '') {
+    const lowerName = nodeName.toLowerCase();
+    result = result.filter((m) => {
+      if (!m.name) return false;
+      return String(m.name).toLowerCase().includes(lowerName);
+    });
+  }
+
+  // keyword substring in stringified msg (case-insensitive)
+  if (keyword !== undefined && keyword !== null && keyword !== '') {
+    const lowerKeyword = keyword.toLowerCase();
+    result = result.filter((m) => {
+      if (m.msg === null || m.msg === undefined) return false;
+      return JSON.stringify(m.msg).toLowerCase().includes(lowerKeyword);
+    });
+  }
+
+  const total = result.length;
+
+  // Apply last-N or first-N slicing
+  if (last !== undefined && last !== null) {
+    // Return the last `last` messages in chronological order
+    result = result.slice(Math.max(0, result.length - last));
+  } else {
+    // Return the first `limit` messages (default 50)
+    const effectiveLimit = (limit !== undefined && limit !== null) ? limit : DEFAULT_LIMIT;
+    result = result.slice(0, effectiveLimit);
+  }
+
+  return { messages: result, total };
+}
+
+/**
+ * Create a handler for the read-debug-messages MCP tool.
+ *
+ * @param {import('../nodered/comms-client.js').CommsClient} commsClient
+ * @returns {(params: object) => Promise<{ content: Array<{ type: string, text: string }> }>}
+ */
+export function handleReadDebugMessages(commsClient) {
+  return async (params) => {
+    const { nodeId, nodeName, keyword, after, before, last, limit } = params;
+
+    // Read from the ring buffer
+    const allMessages = commsClient.getMessages();
+
+    // Apply filters
+    const result = filterMessages(allMessages, {
+      nodeId,
+      nodeName,
+      keyword,
+      after,
+      before,
+      last,
+      limit,
+    });
+
+    // Handle filter-level error (e.g. last + limit conflict)
+    if (result.error) {
+          const data = {
+              error: result.error,
+            };
+    return formatSuccess(data);
+    }
+
+        const data = {
+            messages: result.messages,
+            total: result.total,
+            bufferSize: commsClient.bufferSize,
+          };
+    return formatSuccess(data);
+  };
+}
+
+export const readDebugMessagesDefinition = {
+  name: 'read-debug-messages',
+  annotations: ANN_READ_DEBUG,
+  outputSchema: DebugMessagesResponseSchema,
+  handler: handleReadDebugMessages,
+};

package/src/tools/refresh-staging.js

@@ -0,0 +1,62 @@
+import { ANN_REFRESH } from './constants.js';
+import { RefreshStagingResponseSchema } from '../schemas/responses.js';
+/**
+ * MCP tool: refresh-staging
+ *
+ * Discards ALL un-deployed staged changes and re-fetches the latest flow
+ * state from the Node-RED Admin API (GET /flows).
+ *
+ * Use this when flows have been modified externally (e.g., via the
+ * Node-RED editor UI) and the MCP staging state is out of sync.
+ *
+ * ⚠️ WARNING: All un-deployed staged edits will be lost. Use
+ * get-staging-status first to review what would be discarded.
+ */
+
+/**
+ * Handler for the refresh-staging MCP tool.
+ *
+ * @param {import('../staging-store.js').StagingStore} staging
+ * @returns {() => Promise<{ content: Array<{ type: string, text: string }> }>}
+ */
+export function handleRefreshStaging(staging) {
+  return async () => {
+    // Capture state before invalidation so we can report what was discarded
+    const previousSummary = staging.getStagingSummary();
+
+    // Discard all staged changes and re-fetch from Node-RED
+    staging.invalidate();
+    await staging.ensureLoaded();
+
+    // Capture state after re-fetch
+    const newSummary = staging.getStagingSummary();
+
+    const responseData = {
+      success: true,
+      warning:
+        'All un-deployed staged changes have been discarded. ' +
+        'The staging state now reflects the current Node-RED backend.',
+      previousPendingChanges: previousSummary.pendingChanges,
+      previousDirtyNodeIds: previousSummary.dirtyNodeIds,
+      previousDirtyFlowIds: previousSummary.dirtyFlowIds,
+      staging: newSummary,
+    };
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(responseData, null, 2),
+        },
+      ],
+      structuredContent: responseData,
+    };
+  };
+}
+
+export const refreshStagingDefinition = {
+  name: 'refresh-staging',
+  annotations: ANN_REFRESH,
+  outputSchema: RefreshStagingResponseSchema,
+  handler: handleRefreshStaging,
+};

package/src/tools/remove-nodes-from-group.js

@@ -0,0 +1,162 @@
+import { ANN_MUTATION } from './constants.js';
+import { RemoveNodesFromGroupResponseSchema } from '../schemas/responses.js';
+/**
+ * MCP tool: remove-nodes-from-group
+ *
+ * Detaches nodes from a Node-RED group. Optionally repositions detached
+ * nodes outside the group's bounding rectangle. If no specific node IDs
+ * are provided, all members are removed.
+ */
+
+/**
+ * Apply the remove-nodes-from-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 remove nodes from
+ * @param {object} [options]
+ * @param {string[]} [options.nodeIds] - Specific node IDs to remove; if omitted, all members are removed
+ * @param {boolean} [options.reposition=false] - Whether to reposition removed nodes outside group bounds
+ * @returns {{ updatedFlows: object[], groupId: string, removedNodeIds: string[], remainingNodeIds: string[], repositionedNodes: Array<{ nodeId: string, x: number, y: number }> }}
+ */
+export function applyRemoveNodesFromGroup(rawResponse, groupId, options = {}) {
+  const { nodeIds, reposition = false } = 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.`);
+    }
+  }
+
+  // Determine which nodes to remove
+  const currentMembers = new Set(group.nodes || []);
+  const toRemove = nodeIds
+    ? nodeIds.filter((nid) => currentMembers.has(nid))
+    : [...currentMembers];
+
+  // Track warnings for nodes not in group
+  const warnings = [];
+  if (nodeIds) {
+    const notMembers = nodeIds.filter((nid) => !currentMembers.has(nid));
+    for (const nid of notMembers) {
+      warnings.push(`Node '${nid}' is not a member of group '${groupId}' — skipped`);
+    }
+  }
+
+  // Compute reposition target for removed nodes
+  const repositionTarget = reposition
+    ? { x: (group.x ?? 0) + (group.w ?? 100) + 40, startY: (group.y ?? 0) }
+    : null;
+
+  let updatedFlows = [...flows];
+  const removedList = [];
+  const repositionedList = [];
+
+  for (let i = 0; i < toRemove.length; i++) {
+    const nid = toRemove[i];
+    const nodeIndex = updatedFlows.findIndex((n) => n.id === nid);
+    if (nodeIndex === -1) continue;
+
+    const node = updatedFlows[nodeIndex];
+
+    // Remove g property
+    const { g: _g, ...rest } = node;
+    const updatedNode = { ...rest };
+    if (_g !== undefined) {
+      // Only delete if it matched this group
+    }
+
+    // Reposition if requested
+    if (repositionTarget) {
+      updatedNode.x = repositionTarget.x;
+      updatedNode.y = repositionTarget.startY + i * 40;
+      repositionedList.push({
+        nodeId: nid,
+        x: updatedNode.x,
+        y: updatedNode.y,
+      });
+    }
+
+    updatedFlows[nodeIndex] = updatedNode;
+    removedList.push(nid);
+  }
+
+  // Update group's nodes array
+  const remainingMembers = (group.nodes || []).filter(
+    (nid) => !toRemove.includes(nid),
+  );
+  updatedFlows[groupIndex] = {
+    ...group,
+    nodes: remainingMembers,
+  };
+
+  return {
+    updatedFlows,
+    groupId,
+    removedNodeIds: removedList,
+    remainingNodeIds: remainingMembers,
+    repositionedNodes: repositionedList,
+    warnings: warnings.length > 0 ? warnings : undefined,
+  };
+}
+
+/**
+ * Handler for the remove-nodes-from-group MCP tool.
+ *
+ * @param {ReturnType<import('../nodered/client.js').createNodeRedClient>} client
+ * @param {object} params
+ * @param {string} params.groupId
+ * @param {string[]} [params.nodeIds]
+ * @param {boolean} [params.reposition=false]
+ * @returns {Promise<{ content: Array<{ type: string, text: string }> }>}
+ */
+export async function handleRemoveNodesFromGroup(staging, client, params) {
+  const { groupId, nodeIds, reposition } = params;
+
+  const result = await staging.applyMutation((rawResponse) => {
+    return applyRemoveNodesFromGroup(rawResponse, groupId, {
+      nodeIds,
+      reposition,
+    });
+  });
+
+  const responseData = {
+    groupId: result.groupId,
+    removedNodeIds: result.removedNodeIds,
+    remainingNodeIds: result.remainingNodeIds,
+    repositionedNodes: result.repositionedNodes,
+    warnings: result.warnings,
+    staging: staging.getStagingSummary(),
+  };
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(responseData, null, 2),
+      },
+    ],
+    structuredContent: responseData,
+  };
+}
+
+export const removeNodesFromGroupDefinition = {
+  name: 'remove-nodes-from-group',
+  annotations: ANN_MUTATION,
+  outputSchema: RemoveNodesFromGroupResponseSchema,
+  handler: handleRemoveNodesFromGroup,
+};

package/src/tools/render-staging.js

@@ -0,0 +1,69 @@
+/**
+ * MCP tool: render-staging
+ *
+ * Renders the current staging workspace in SVG, HTML, or Mermaid format.
+ * Supports flow filtering, dirty highlighting, and interactive HTML output.
+ */
+
+import { ANN_READONLY } from './constants.js';
+import { renderStaging } from '../renderer/index.js';
+
+/**
+ * Handler for the render-staging MCP tool.
+ *
+ * @param {import('../staging-store.js').StagingStore} staging
+ * @returns {(params: object) => Promise<{ content: Array<{ type: string, text: string }> }>}
+ */
+export function handleRenderStaging(staging) {
+  return async (params) => {
+    const {
+      format = 'svg',
+      flowId,
+      highlightDirty = true,
+    } = params;
+
+    const flows = await staging.getFlows();
+    const summary = staging.getStagingSummary();
+    const dirtyNodeIds = new Set(summary.dirtyNodeIds);
+    const dirtyFlowIds = new Set(summary.dirtyFlowIds);
+
+    const result = renderStaging(flows, {
+      format,
+      flowId,
+      highlightDirty,
+      dirtyNodeIds,
+      dirtyFlowIds,
+    });
+
+    switch (format) {
+      case 'svg':
+        return {
+          content: [{ type: 'text', text: result.svg }],
+          structuredContent: { format, flowId: flowId || null, highlightDirty },
+        };
+      case 'html':
+        return {
+          content: [{ type: 'text', text: result.html }],
+          structuredContent: { format, flowId: flowId || null, highlightDirty },
+        };
+      case 'mermaid':
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `\`\`\`mermaid\n${result.mermaid}\n\`\`\``,
+            },
+          ],
+          structuredContent: { format, flowId: flowId || null, highlightDirty },
+        };
+      default:
+        throw new Error(`Unknown format: ${format}. Use one of: "svg" (static diagram), "html" (interactive page), or "mermaid" (topology diagram).`);
+    }
+  };
+}
+
+export const renderStagingDefinition = {
+  name: 'render-staging',
+  annotations: ANN_READONLY,
+  handler: handleRenderStaging,
+};

package/src/tools/response-utils.js

@@ -0,0 +1,42 @@
+/**
+ * Shared response formatting utilities for MCP tool handlers.
+ *
+ * Provides consistent success/error response shapes across all tools.
+ */
+
+/**
+ * Format a successful tool response.
+ *
+ * structuredContent is only included when `data` is a plain object (record),
+ * because the MCP SDK requires structuredContent to be a record, not an array.
+ *
+ * @param {any} data - The response data to serialize
+ * @returns {{ content: Array<{ type: string, text: string }>, structuredContent?: object }}
+ */
+export function formatSuccess(data) {
+  const response = {
+    content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+  };
+  // MCP SDK requires structuredContent to be a record (object); arrays are rejected
+  if (data !== null && typeof data === 'object' && !Array.isArray(data)) {
+    response.structuredContent = data;
+  }
+  return response;
+}
+
+/**
+ * Format an error response for a tool.
+ *
+ * @param {string} message - User-facing error message
+ * @param {object} [details] - Optional additional details
+ * @returns {{ content: Array<{ type: string, text: string }>, isError: boolean }}
+ */
+export function formatError(message, details) {
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify({ error: message, ...(details && { details }) }, null, 2),
+    }],
+    isError: true,
+  };
+}

package/src/tools/search-nodes.js

@@ -0,0 +1,134 @@
+/**
+ * MCP tool: search-nodes
+ *
+ * Deep-searches all nodes across all flows (or a single flow via flowId) with a
+ * single query string. Serializes each node with JSON.stringify and matches
+ * against the full string. Supports plain text (case-insensitive substring) and
+ * regex modes.
+ */
+import { formatSuccess } from './response-utils.js';
+
+
+import { ANN_READONLY } from './constants.js';
+import { NodeBasicSchema } from '../schemas/responses.js';
+import { z } from 'zod';
+/**
+ * Search regular nodes across all flows and return enriched results.
+ *
+ * Only regular nodes (those with a `z` property, excluding tabs and subflow
+ * definitions) are searched. Each result includes flow context.
+ *
+ * @param {object[]} allNodes - Raw nodes from GET /flows
+ * @param {object} options
+ * @param {string} options.query - The search term
+ * @param {boolean} [options.regex=false] - Treat query as a regex pattern
+ * @param {string} [options.flowId] - Limit search to nodes in this flow
+ * @param {number} [options.limit=50] - Max results to return
+ * @returns {{ results: object[], total: number, truncated: boolean }}
+ * @throws {Error} If regex is true and the pattern is invalid
+ */
+export function searchNodes(allNodes, { query, regex = false, flowId, limit = 50 }) {
+  // --- Build flow index: flowId → { id, label } for tabs ---
+  const flowIndex = new Map();
+  for (const node of allNodes) {
+    if (node.type === 'tab') {
+      flowIndex.set(node.id, { id: node.id, label: node.label || '' });
+    }
+  }
+
+  // --- Filter to searchable nodes ---
+  // Regular nodes have a `z` property; exclude tabs and subflow definitions
+  let candidates = allNodes.filter(
+    (n) => n.z !== undefined && n.type !== 'tab' && n.type !== 'subflow',
+  );
+
+  // Optional flow scoping
+  if (flowId) {
+    candidates = candidates.filter((n) => n.z === flowId);
+  }
+
+  // --- Deep search ---
+  const results = [];
+  let total = 0;
+
+  for (const node of candidates) {
+    const serialized = JSON.stringify(node);
+
+    let matches = false;
+    if (regex) {
+      // Regex mode: compile and test
+      let pattern;
+      try {
+        pattern = new RegExp(query);
+      } catch {
+        throw new Error(`Invalid regex pattern: ${query}. Provide a valid JavaScript regular expression, e.g. "debug" for plain text or "/debug\\d+/" for regex.`);
+      }
+      matches = pattern.test(serialized);
+    } else {
+      // Plain text mode: case-insensitive substring
+      matches = serialized.toLowerCase().includes(query.toLowerCase());
+    }
+
+    if (matches) {
+      total++;
+      if (results.length < limit) {
+        const flowInfo = flowIndex.get(node.z);
+        results.push({
+          flowId: node.z,
+          flowLabel: flowInfo ? flowInfo.label : '',
+          nodeId: node.id,
+          type: node.type,
+          name: node.name || '',
+          x: node.x,
+          y: node.y,
+        });
+      }
+    }
+  }
+
+  return {
+    results,
+    total,
+    truncated: total > limit,
+  };
+}
+
+/**
+ * Handler for the search-nodes MCP tool.
+ *
+ * @param {ReturnType<import('../nodered/client.js').createNodeRedClient>} client
+ * @param {object} params - Validated input parameters
+ * @returns {Promise<{ content: Array<{ type: string, text: string }> }>}
+ */
+export async function handleSearchNodes(staging, params) {
+  const { query, regex, flowId, limit } = params;
+
+  // Validate query
+  if (!query || query.trim() === '') {
+    throw new Error('The "query" parameter is required and must be non-empty. Provide a search term to match against node properties (case-insensitive substring).');
+  }
+
+  // Fetch all flows
+  const allNodes = await staging.getFlows();
+
+  // Validate flowId if provided
+  if (flowId) {
+    const flowExists = allNodes.some(
+      (n) => (n.type === 'tab' || n.type === 'subflow') && n.id === flowId,
+    );
+    if (!flowExists) {
+      throw new Error(`Flow not found: no tab or subflow with id "${flowId}". Use get-flows to list available flow tabs and subflows.`);
+    }
+  }
+
+  const result = searchNodes(allNodes, { query, regex, flowId, limit });
+
+  return formatSuccess(result);
+}
+
+export const searchNodesDefinition = {
+  name: 'search-nodes',
+  annotations: ANN_READONLY,
+  outputSchema: z.array(NodeBasicSchema),
+  handler: handleSearchNodes,
+};

package/src/tools/uninstall-node.js

@@ -0,0 +1,31 @@
+/**
+ * MCP tool: uninstall-node
+ *
+ * Uninstalls a Node-RED node module from the running instance via the Admin API's
+ * DELETE /nodes/:module endpoint. The module identifier comes from the palette
+ * listing (get-palette-nodes). Returns a confirmation object on success.
+ */
+
+import { formatSuccess } from './response-utils.js';
+
+import { ANN_UNINSTALL } from './constants.js';
+import { UninstallNodeResponseSchema } from '../schemas/responses.js';
+/**
+ * Handle the uninstall-node MCP tool invocation.
+ *
+ * @param {ReturnType<import('../nodered/client.js').createNodeRedClient>} client
+ * @param {{ module: string }} params
+ * @returns {Promise<{ content: Array<{ type: string, text: string }> }>}
+ */
+export async function handleUninstallNode(client, { module: moduleName }) {
+  await client.request('DELETE', `/nodes/${encodeURIComponent(moduleName)}`);
+      const data = { uninstalled: true, module: moduleName };
+    return formatSuccess(data);
+}
+
+export const uninstallNodeDefinition = {
+  name: 'uninstall-node',
+  annotations: ANN_UNINSTALL,
+  outputSchema: UninstallNodeResponseSchema,
+  handler: handleUninstallNode,
+};