@gmag11/nodered-mcp-server 1.0.1

package/src/tools/get-context.js

@@ -0,0 +1,76 @@
+/**
+ * MCP tool: get-context
+ *
+ * Reads a context variable from a node, flow, or global scope in Node-RED
+ * via the Admin API. Supports reading a single key or all keys in a scope.
+ *
+ * Note: In-memory context values are lost when Node-RED restarts.
+ */
+import { formatSuccess } from './response-utils.js';
+
+
+import { ANN_READONLY } from './constants.js';
+import { GenericObjectSchema } from '../schemas/responses.js';
+/**
+ * Build the API path for a context GET request.
+ *
+ * @param {string} scope - 'node' | 'flow' | 'global'
+ * @param {string|undefined} id - Node or flow UUID (required for node/flow scopes)
+ * @param {string|undefined} key - Optional context key to read
+ * @returns {string} The API path (with optional ?key= query string)
+ */
+export function buildGetContextPath(scope, id, key) {
+  const base = scope === 'global' ? '/context/global' : `/context/${scope}/${id}`;
+  return key ? `${base}/${encodeURIComponent(key)}` : base;
+}
+
+/**
+ * Transform the raw Node-RED context API response into the tool result shape.
+ *
+ * Single-key query: returns { [key]: value }
+ * All-keys query:   returns { [key]: value, ... } (the raw object as-is)
+ *
+ * @param {string|undefined} key - The requested key (if any)
+ * @param {unknown} rawResponse - Raw value returned by the Node-RED API
+ * @returns {object}
+ */
+export function transformGetContextResponse(key, rawResponse) {
+  if (key) {
+    return { [key]: rawResponse ?? null };
+  }
+
+  // All-keys query: rawResponse is already an object of key-value pairs
+  return rawResponse ?? {};
+}
+
+/**
+ * Handler for the get-context MCP tool.
+ *
+ * @param {ReturnType<import('../nodered/client.js').createNodeRedClient>} client
+ * @param {object} params - Validated input parameters
+ * @param {string} params.scope - 'node' | 'flow' | 'global'
+ * @param {string} [params.id] - Node or flow UUID (required for node/flow scopes)
+ * @param {string} [params.key] - Context key to read (omit to read all keys)
+ * @returns {Promise<{ content: Array<{ type: string, text: string }> }>}
+ */
+export async function handleGetContext(client, params) {
+  const { scope, id, key } = params;
+
+  // Validate: id is required for node and flow scopes
+  if ((scope === 'node' || scope === 'flow') && !id) {
+    throw new Error(`id is required for scope "${scope}". Provide the node or flow UUID to target. For global scope, omit the id parameter.`);
+  }
+
+  const path = buildGetContextPath(scope, id, key);
+  const rawResponse = await client.request('GET', path);
+  const result = transformGetContextResponse(key, rawResponse);
+
+  return formatSuccess(result);
+}
+
+export const getContextDefinition = {
+  name: 'get-context',
+  annotations: ANN_READONLY,
+  outputSchema: GenericObjectSchema,
+  handler: handleGetContext,
+};

package/src/tools/get-flow-diagram.js

@@ -0,0 +1,99 @@
+/**
+ * MCP tool: get-flow-diagram
+ *
+ * Returns a Mermaid flowchart (flowchart TD) representing the topology of nodes
+ * within a specific Node-RED flow, with filtering and pagination support.
+ * Delegates Mermaid generation to the shared renderer module.
+ */
+
+import { ANN_READONLY } from './constants.js';
+import { FlowDiagramResponseSchema } from '../schemas/responses.js';
+import { buildIR } from '../renderer/ir-builder.js';
+import { buildMermaid } from '../renderer/mermaid-builder.js';
+import {
+  getFlowNodes,
+  applyFilters,
+  paginate,
+} from './flow-utils.js';
+
+/**
+ * Transform a raw /flows response into a paginated Mermaid diagram for a given flow.
+ *
+ * @param {object} rawResponse - Response from GET /flows (v2 format: { rev, flows })
+ * @param {string} flowId - ID of the tab or subflow to diagram
+ * @param {object} [options]
+ * @param {boolean} [options.disabledOnly]
+ * @param {string} [options.nodeType]
+ * @param {string} [options.fromNodeId]
+ * @param {'downstream'|'upstream'|'both'} [options.direction='both']
+ * @param {number} [options.offset=0]
+ * @param {number} [options.limit=50]
+ * @returns {{ flowId: string, diagram: string, totalCount: number, offset: number, limit: number, hasMore: boolean }}
+ * @throws {Error} If flowId not found, or fromNodeId not found in flow
+ */
+export function transformFlowDiagram(rawResponse, flowId, options = {}) {
+  const {
+    disabledOnly,
+    nodeType,
+    fromNodeId,
+    direction = 'both',
+    offset = 0,
+    limit = 50,
+  } = options;
+
+  const allNodes = rawResponse.flows || [];
+
+  // Get all nodes belonging to this flow (validates flowId exists)
+  const flowNodes = getFlowNodes(allNodes, flowId);
+
+  // Apply filters
+  const filtered = applyFilters(flowNodes, { disabledOnly, nodeType, fromNodeId, direction });
+
+  // Paginate
+  const page = paginate(filtered, offset, limit);
+
+  // Build IR and delegate Mermaid generation to shared renderer
+  const ir = buildIR(page.items);
+  const diagram = buildMermaid(ir);
+
+  return {
+    flowId,
+    diagram,
+    totalCount: page.totalCount,
+    offset: page.offset,
+    limit: page.limit,
+    hasMore: page.hasMore,
+  };
+}
+
+/**
+ * Handler for the get-flow-diagram 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 handleGetFlowDiagram(staging, params) {
+  const flows = await staging.getFlows();
+  const result = transformFlowDiagram({ flows }, params.flowId, params);
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: `Mermaid diagram for flow "${result.flowId}" (nodes ${result.offset + 1}–${result.offset + (result.totalCount === 0 ? 0 : Math.min(result.limit, result.totalCount - result.offset))} of ${result.totalCount}${result.hasMore ? ', hasMore: true' : ''}):\n\n\`\`\`mermaid\n${result.diagram}\n\`\`\``,
+      },
+    ],
+    structuredContent: {
+      mermaid: result.diagram,
+      nodeCount: result.totalCount,
+    },
+  };
+}
+
+export const getFlowDiagramDefinition = {
+  name: 'get-flow-diagram',
+  annotations: ANN_READONLY,
+  outputSchema: FlowDiagramResponseSchema,
+  handler: handleGetFlowDiagram,
+};

package/src/tools/get-flow-nodes.js

@@ -0,0 +1,116 @@
+/**
+ * MCP tool: get-flow-nodes
+ *
+ * Returns a paginated, filterable list of nodes within a specific Node-RED flow,
+ * with metadata and sanitized configuration (large text fields excluded).
+ */
+
+import {
+  getFlowNodes,
+  sanitizeNodeConfig,
+  applyFilters,
+  paginate,
+} from './flow-utils.js';
+import { formatSuccess } from './response-utils.js';
+
+import { ANN_READONLY } from './constants.js';
+import { FlowNodesResponseSchema } from '../schemas/responses.js';
+/**
+ * Transform a raw /flows response into a paginated list of nodes for a given flow.
+ *
+ * @param {object} rawResponse - Response from GET /flows (v2 format: { rev, flows })
+ * @param {string} flowId - ID of the tab or subflow to inspect
+ * @param {object} [options]
+ * @param {boolean} [options.disabledOnly] - Return only disabled nodes
+ * @param {string} [options.nodeType] - Return only nodes of this type
+ * @param {string} [options.fromNodeId] - Filter to connected subgraph from this node ID
+ * @param {'downstream'|'upstream'|'both'} [options.direction='both'] - Traversal direction
+ * @param {number} [options.offset=0] - Pagination offset
+ * @param {number} [options.limit=50] - Pagination limit
+ * @returns {{ flowId: string, nodes: object[], totalCount: number, offset: number, limit: number, hasMore: boolean }}
+ * @throws {Error} If flowId not found, or fromNodeId not found in flow
+ */
+export function transformFlowNodes(rawResponse, flowId, options = {}) {
+  const {
+    disabledOnly,
+    nodeType,
+    fromNodeId,
+    direction = 'both',
+    offset = 0,
+    limit = 50,
+  } = options;
+
+  const allNodes = rawResponse.flows || [];
+
+  // Get all nodes belonging to this flow (validates flowId exists)
+  const flowNodes = getFlowNodes(allNodes, flowId);
+
+  // Apply filters (subgraph, disabled, type)
+  const filtered = applyFilters(flowNodes, { disabledOnly, nodeType, fromNodeId, direction });
+
+  // Paginate
+  const page = paginate(filtered, offset, limit);
+
+  // Shape each node: top-level metadata + sanitized config
+  const nodes = page.items.map((node) => {
+    // Group nodes have a distinct shape: no wires, but style + member nodes array
+    if (node.type === 'group') {
+      return {
+        id: node.id,
+        type: 'group',
+        name: node.name || '',
+        disabled: node.d === true,
+        g: null,
+        x: node.x,
+        y: node.y,
+        w: node.w,
+        h: node.h,
+        style: node.style || {},
+        nodes: node.nodes || [],
+        config: {}, // no blocklisted fields on group nodes
+      };
+    }
+
+    return {
+      id: node.id,
+      type: node.type,
+      name: node.name || '',
+      disabled: node.d === true,
+      g: node.g || null,
+      x: node.x,
+      y: node.y,
+      wires: node.wires || [],
+      config: sanitizeNodeConfig(node),
+    };
+  });
+
+  return {
+    flowId,
+    nodes,
+    totalCount: page.totalCount,
+    offset: page.offset,
+    limit: page.limit,
+    hasMore: page.hasMore,
+  };
+}
+
+/**
+ * Handler for the get-flow-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 handleGetFlowNodes(staging, params) {
+  const flows = await staging.getFlows();
+  const result = transformFlowNodes({ flows }, params.flowId, params);
+
+  return formatSuccess(result);
+}
+
+export const getFlowNodesDefinition = {
+  name: 'get-flow-nodes',
+  annotations: ANN_READONLY,
+  outputSchema: FlowNodesResponseSchema,
+  handler: handleGetFlowNodes,
+};

package/src/tools/get-flows.js

@@ -0,0 +1,74 @@
+/**
+ * MCP tool: get-flows
+ *
+ * Returns a summarized list of flow tabs from the connected
+ * Node-RED instance, optimized for LLM consumption.
+ * Use get-subflows for subflow definitions.
+ */
+import { formatSuccess } from './response-utils.js';
+
+
+import { ANN_READONLY } from './constants.js';
+import { FlowSummarySchema } from '../schemas/responses.js';
+import { z } from 'zod';
+/**
+ * Transform the raw Node-RED /flows response into an LLM-friendly summary.
+ *
+ * @param {object} rawResponse - Response from GET /flows (v2 format: { rev, flows })
+ * @returns {Array<{ id: string, label: string, type: string, disabled: boolean, nodeCount: number, nodeTypes: string[] }>}
+ */
+export function transformFlows(rawResponse) {
+  const allNodes = rawResponse.flows || [];
+
+  // Identify flows: tabs only (subflows are handled by get-subflows)
+  const flows = allNodes.filter(
+    (node) => node.type === 'tab'
+  );
+
+  // Group child nodes by their parent flow (z property)
+  const childrenByFlow = new Map();
+  for (const node of allNodes) {
+    if (node.z) {
+      if (!childrenByFlow.has(node.z)) {
+        childrenByFlow.set(node.z, []);
+      }
+      childrenByFlow.get(node.z).push(node);
+    }
+  }
+
+  return flows.map((flow) => {
+    const children = childrenByFlow.get(flow.id) || [];
+    const uniqueTypes = [...new Set(children.map((n) => n.type))];
+
+    return {
+      id: flow.id,
+      label: flow.label || flow.name || '',
+      type: flow.type,
+      disabled: flow.disabled || false,
+      locked: flow.locked || false,
+      info: flow.info || '',
+      nodeCount: children.length,
+      nodeTypes: uniqueTypes,
+    };
+  });
+}
+
+/**
+ * Handler for the get-flows MCP tool.
+ *
+ * @param {import('../staging-store.js').StagingStore} staging
+ * @returns {Promise<{ content: Array<{ type: string, text: string }> }>}
+ */
+export async function handleGetFlows(staging) {
+  const flows = await staging.getFlows();
+  const result = transformFlows({ flows });
+
+  return formatSuccess({ flows: result });
+}
+
+export const getFlowsDefinition = {
+  name: 'get-flows',
+  annotations: ANN_READONLY,
+  outputSchema: z.object({ flows: z.array(FlowSummarySchema) }),
+  handler: handleGetFlows,
+};

package/src/tools/get-node-detail.js

@@ -0,0 +1,77 @@
+/**
+ * MCP tool: get-node-detail
+ *
+ * Returns the full detail of a single Node-RED node by its ID, including
+ * large text fields (func, template, etc.) that are excluded from get-flow-nodes.
+ *
+ * Also queries the /credentials/:type/:id endpoint to include credential
+ * metadata: field names and whether each password-type field is set.
+ * Password values are never exposed — only `has_<field>: true/false` is returned.
+ */
+import { formatSuccess } from './response-utils.js';
+
+
+import { ANN_READONLY } from './constants.js';
+import { GenericObjectSchema } from '../schemas/responses.js';
+/**
+ * Find a node by ID in the raw /flows response and return all its fields.
+ *
+ * @param {object} rawResponse - Response from GET /flows (v2 format: { rev, flows })
+ * @param {string} nodeId - ID of the node to retrieve
+ * @returns {object} The full node object
+ * @throws {Error} If no node with the given ID is found
+ */
+export function transformNodeDetail(rawResponse, nodeId) {
+  const allNodes = rawResponse.flows || [];
+  const node = allNodes.find((n) => n.id === nodeId);
+
+  if (!node) {
+    throw new Error(`Node '${nodeId}' not found. Use search-nodes with the node name or get-flow-nodes to list nodes in a flow.`);
+  }
+
+  return node;
+}
+
+/**
+ * Handler for the get-node-detail MCP tool.
+ *
+ * @param {ReturnType<import('../nodered/client.js').createNodeRedClient>} client
+ * @param {object} params - Validated input parameters
+ * @param {string} params.nodeId - ID of the node to retrieve
+ * @returns {Promise<{ content: Array<{ type: string, text: string }> }>}
+ */
+export async function handleGetNodeDetail(staging, client, params) {
+  const flows = await staging.getFlows();
+  const node = transformNodeDetail({ flows }, params.nodeId);
+
+  // Fetch credential metadata if the node type may have credentials.
+  // The /credentials/:type/:id endpoint returns field names and
+  // has_<field>: true/false for password-type fields (never real values).
+  let credentialMetadata = null;
+  try {
+    const credResponse = await client.request(
+      'GET',
+      `/credentials/${encodeURIComponent(node.type)}/${encodeURIComponent(node.id)}`,
+    );
+    if (credResponse && typeof credResponse === 'object' && Object.keys(credResponse).length > 0) {
+      credentialMetadata = credResponse;
+    }
+  } catch {
+    // Node type has no credentials registered, or editor is disabled.
+    // credentialMetadata stays null — the response simply won't include _credentials.
+  }
+
+  // Build the result, adding _credentials metadata when available
+  const result = credentialMetadata
+    ? { ...node, _credentials: credentialMetadata }
+    : node;
+
+  return formatSuccess(result);
+}
+
+export const getNodeDetailDefinition = {
+  name: 'get-node-detail',
+  annotations: ANN_READONLY,
+  outputSchema: GenericObjectSchema,
+  handler: handleGetNodeDetail,
+};

package/src/tools/get-node-type-detail.js

@@ -0,0 +1,92 @@
+/**
+ * MCP tool: get-node-type-detail
+ *
+ * Returns detailed information about a specific node type installed in the
+ * Node-RED palette, including its configuration parameters.
+ */
+import TurndownService from 'turndown';
+import { formatSuccess } from './response-utils.js';
+
+import { ANN_READONLY } from './constants.js';
+import { GenericObjectSchema } from '../schemas/responses.js';
+const turndown = new TurndownService({ headingStyle: 'atx', codeBlockStyle: 'fenced' });
+
+/**
+ * Extract the help HTML for a specific node type from the GET /nodes HTML response.
+ *
+ * The HTML response contains blocks of the form:
+ *   <script type="text/html" data-help-name="<type>">...</script>
+ *
+ * @param {string} html - Full HTML body from GET /nodes with Accept: text/html
+ * @param {string} typeName - The node type name to extract documentation for
+ * @returns {string|null} Inner HTML of the help block, or null if not found
+ */
+export function extractHelpHtml(html, typeName) {
+  // Escape special regex characters in the type name
+  const escaped = typeName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const pattern = new RegExp(
+    `<script[^>]+data-help-name=["']${escaped}["'][^>]*>([\\s\\S]*?)<\\/script>`,
+    'i'
+  );
+  const match = html.match(pattern);
+  return match ? turndown.turndown(match[1].trim()) : null;
+}
+
+/**
+ * Search the raw GET /nodes response for a specific type name and return its node set.
+ *
+ * @param {Array<object>} rawResponse - Array of node set objects from GET /nodes
+ * @param {string} typeName - The node type to look up (e.g. "inject")
+ * @returns {object} The raw node set object from the API
+ * @throws {Error} If the type is not found in any installed node set
+ */
+export function findNodeType(rawResponse, typeName) {
+  for (const nodeSet of rawResponse) {
+    if ((nodeSet.types || []).includes(typeName)) {
+      return nodeSet;
+    }
+  }
+
+  throw new Error(`Node type '${typeName}' not found. Use get-palette-nodes to list all installed node types, or install-node to add a missing package.`);
+}
+
+/**
+ * Handler for the get-node-type-detail MCP tool.
+ *
+ * @param {ReturnType<import('../nodered/client.js').createNodeRedClient>} client
+ * @param {object} params
+ * @param {string} params.type - The node type name to look up
+ * @returns {Promise<{ content: Array<{ type: string, text: string }> }>}
+ */
+export async function handleGetNodeTypeDetail(client, params) {
+  const [rawResponse, helpHtml] = await Promise.all([
+    client.request('GET', '/nodes'),
+    client.requestText('GET', '/nodes'),
+  ]);
+
+  let nodeSet;
+  try {
+    nodeSet = findNodeType(rawResponse, params.type);
+  } catch (err) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: err.message,
+        },
+      ],
+    };
+  }
+
+  const help = extractHelpHtml(helpHtml, params.type);
+  const result = { ...nodeSet, help };
+
+  return formatSuccess(result);
+}
+
+export const getNodeTypeDetailDefinition = {
+  name: 'get-node-type-detail',
+  annotations: ANN_READONLY,
+  outputSchema: GenericObjectSchema,
+  handler: handleGetNodeTypeDetail,
+};

package/src/tools/get-palette-nodes.js

@@ -0,0 +1,63 @@
+/**
+ * MCP tool: get-palette-nodes
+ *
+ * Returns a paginated list of node sets from the Node-RED palette,
+ * exactly as returned by the GET /nodes API.
+ */
+import { formatSuccess } from './response-utils.js';
+
+
+import { ANN_READONLY } from './constants.js';
+import { PaletteNodesResponseSchema } from '../schemas/responses.js';
+const MAX_LIMIT = 200;
+const DEFAULT_LIMIT = 50;
+
+/**
+ * Apply pagination to an array of node sets.
+ *
+ * @param {Array<object>} nodes - Array of node set objects from GET /nodes
+ * @param {number} offset - 0-based pagination offset (default 0)
+ * @param {number} limit - Max items to return (default 50, max 200)
+ * @returns {{ offset: number, limit: number, total: number, nodes: Array<object> }}
+ */
+export function paginateNodes(nodes, offset = 0, limit = DEFAULT_LIMIT) {
+  const clampedLimit = Math.min(Math.max(1, limit), MAX_LIMIT);
+  const total = nodes.length;
+
+  const start = offset;
+  const slice = start >= total ? [] : nodes.slice(start, start + clampedLimit);
+
+  return {
+    offset,
+    limit: clampedLimit,
+    total,
+    nodes: slice,
+  };
+}
+
+/**
+ * Handler for the get-palette-nodes MCP tool.
+ *
+ * @param {ReturnType<import('../nodered/client.js').createNodeRedClient>} client
+ * @param {object} params
+ * @param {number} [params.offset]
+ * @param {number} [params.limit]
+ * @returns {Promise<{ content: Array<{ type: string, text: string }> }>}
+ */
+export async function handleGetPaletteNodes(client, params) {
+  const rawResponse = await client.request('GET', '/nodes');
+  const result = paginateNodes(
+    rawResponse,
+    params.offset ?? 0,
+    params.limit ?? DEFAULT_LIMIT,
+  );
+
+  return formatSuccess(result);
+}
+
+export const getPaletteNodesDefinition = {
+  name: 'get-palette-nodes',
+  annotations: ANN_READONLY,
+  outputSchema: PaletteNodesResponseSchema,
+  handler: handleGetPaletteNodes,
+};

package/src/tools/get-staging-status.js

@@ -0,0 +1,34 @@
+/**
+ * MCP tool: get-staging-status
+ *
+ * Returns the current staging state: pending change count, dirty node IDs,
+ * dirty flow IDs, and whether the staging is deployed (no pending changes).
+ *
+ * Use this to inspect what's pending before deciding to deploy or to
+ * verify that a deploy was successful.
+ */
+import { formatSuccess } from './response-utils.js';
+
+
+import { ANN_READONLY } from './constants.js';
+import { StagingSummarySchema } from '../schemas/responses.js';
+/**
+ * Handler for the get-staging-status MCP tool.
+ *
+ * @param {import('../staging-store.js').StagingStore} staging
+ * @returns {() => Promise<{ content: Array<{ type: string, text: string }> }>}
+ */
+export function handleGetStagingStatus(staging) {
+  return () => {
+    const summary = staging.getStagingSummary();
+
+    return formatSuccess(summary);
+  };
+}
+
+export const getStagingStatusDefinition = {
+  name: 'get-staging-status',
+  annotations: ANN_READONLY,
+  outputSchema: StagingSummarySchema,
+  handler: handleGetStagingStatus,
+};