@gmag11/nodered-mcp-server 1.0.1

package/src/tools/constants.js

@@ -0,0 +1,45 @@
+/**
+ * Shared description fragments used across multiple tool definitions.
+ *
+ * Centralizing these avoids copy-paste drift when the staging model,
+ * deploy workflow, or common warnings need updating.
+ */
+
+/** Appended to tool descriptions for tools that stage changes locally. */
+export const STAGING_WARNING =
+  '⚠️ STAGING: Changes are NOT live until you call `deploy`. Check the `staging` field in the response.';
+
+/** Used by tools that require an explicit deploy call. */
+export const DEPLOY_REQUIRED =
+  'Changes are NOT deployed to Node-RED until you call the `deploy` tool.';
+
+// ── MCP Annotation constants ──────────────────────────────────────
+// Tool modules import these to include in their definition exports.
+
+export const ANN_READONLY = {
+  readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true,
+};
+export const ANN_MUTATION = {
+  readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false,
+};
+export const ANN_DESTRUCTIVE = {
+  readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false,
+};
+export const ANN_DEPLOY = {
+  readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false,
+};
+export const ANN_INJECT = {
+  readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true,
+};
+export const ANN_READ_DEBUG = {
+  readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true,
+};
+export const ANN_INSTALL = {
+  readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true,
+};
+export const ANN_UNINSTALL = {
+  readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true,
+};
+export const ANN_REFRESH = {
+  readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false,
+};

package/src/tools/create-flow.js

@@ -0,0 +1,87 @@
+/**
+ * MCP tool: create-flow
+ *
+ * Creates a new Node-RED flow tab with the given label and optional properties.
+ * Stages the change locally — call `deploy` to push to Node-RED.
+ */
+
+import { randomUUID } from 'crypto';
+
+import { formatSuccess } from './response-utils.js';
+import { ANN_MUTATION } from './constants.js';
+import { CreateFlowResponseSchema } from '../schemas/responses.js';
+/**
+ * Assemble the POST /flow request body.
+ *
+ * @param {string} label
+ * @param {boolean|undefined} disabled
+ * @param {string|undefined} info
+ * @param {Array<{name: string, value: string, type: string}>|undefined} env
+ * @returns {object}
+ */
+export function buildCreateFlowPayload(label, disabled, info, env) {
+  return {
+    label,
+    disabled: disabled ?? false,
+    info: info ?? '',
+    env: env ?? [],
+    nodes: [],
+  };
+}
+
+/**
+ * Apply a create-flow mutation to the flows array.
+ *
+ * Creates a new tab node with the given properties and appends it to the
+ * flows array. No HTTP — pure data transformation.
+ *
+ * @param {object} rawResponse - Wrapper with `flows` array
+ * @param {string} label - Display label for the new flow tab
+ * @param {boolean} [disabled=false]
+ * @param {string} [info='']
+ * @param {Array} [env=[]]
+ * @returns {{ updatedFlows: object[], currentState: object }}
+ */
+export function applyCreateFlow(rawResponse, label, disabled = false, info = '', env = []) {
+  const flows = rawResponse.flows ?? rawResponse;
+
+  const newTab = {
+    id: randomUUID(),
+    type: 'tab',
+    label,
+    disabled,
+    info,
+    env,
+  };
+
+  const updatedFlows = [...flows, newTab];
+
+  return { updatedFlows, currentState: newTab };
+}
+
+/**
+ * Handler for the create-flow MCP tool.
+ *
+ * @param {import('../staging-store.js').StagingStore} staging
+ * @param {object} params
+ * @param {string} params.label
+ * @param {boolean} [params.disabled]
+ * @param {string} [params.info]
+ * @param {Array<{name: string, value: string, type: string}>} [params.env]
+ * @returns {Promise<{ content: Array<{ type: string, text: string }> }>}
+ */
+export async function handleCreateFlow(staging, params) {
+  const { currentState } = await staging.applyMutation((rawResponse) => {
+    return applyCreateFlow(rawResponse, params.label, params.disabled, params.info, params.env);
+  });
+
+      const data = { flowId: currentState.id, currentState, staging: staging.getStagingSummary() };
+    return formatSuccess(data);
+}
+
+export const createFlowDefinition = {
+  name: 'create-flow',
+  annotations: ANN_MUTATION,
+  outputSchema: CreateFlowResponseSchema,
+  handler: handleCreateFlow,
+};

package/src/tools/create-node.js

@@ -0,0 +1,126 @@
+/**
+ * MCP tool: create-node
+ *
+ * Creates a new node of any installed palette type in a specified Node-RED flow.
+ * Generates a UUID for the node ID, assembles the node object, appends it to the
+ * flows, and deploys. Returns nodeId and currentState.
+ *
+ * ⚠️ INJECT NODE GOTCHA: The inject node in Node-RED 5.x requires ALL fields
+ * (repeat, crontab, once, onceDelay, topic, props) to be explicitly set in
+ * `properties`, even if their value is the default empty/false. Omitting any
+ * of these fields causes the Node-RED editor to display a red-triangle error
+ * on the node, even though the inject works functionally. See
+ * nodered-node-reference skill for the complete field set.
+ *
+ * Credential handling (via normalizeCredentials from flow-utils.js):
+ * When creating configuration nodes (e.g. mqtt-broker, http-proxy),
+ * credential fields like `username`, `password`, `key`, `token`, etc.
+ * are automatically nested under a `credentials` sub-object to match
+ * Node-RED's credential storage model.
+ */
+
+import { randomUUID } from 'crypto';
+import { normalizeCredentials } from './flow-utils.js';
+
+import { formatSuccess } from './response-utils.js';
+import { ANN_MUTATION } from './constants.js';
+import { CreateNodeResponseSchema } from '../schemas/responses.js';
+/**
+ * Build a new node object with structural fields set and properties merged in.
+ * Strips `id`, `z`, and `wires` from `properties` if the caller accidentally
+ * includes them — the tool controls those fields.
+ *
+ * @param {string} type - Palette node type (e.g. "function", "debug")
+ * @param {string} flowId - ID of the flow (tab or subflow) to place the node in
+ * @param {object} properties - Optional extra fields to merge onto the node
+ * @param {number} x - X position (default 300)
+ * @param {number} y - Y position (default 200)
+ * @returns {object} New node object
+ */
+export function buildNewNode(type, flowId, properties, x, y) {
+  // Strip structural fields the caller must not override
+  const { id: _id, z: _z, wires: _wires, ...safeProperties } = properties;
+
+  // Normalize credentials: move credential fields like username, password,
+  // key, token, etc. into a `credentials` sub-object for config nodes.
+  // Pass null for node since this is a new node (no existing credentials).
+  const normalizedProperties = normalizeCredentials(safeProperties, null);
+
+  // Nodes that have no output ports by default get wires: [].
+  // All other nodes default to 1 output port: wires: [[]].
+  const zeroOutputTypes = new Set(['debug', 'comment']);
+  const defaultWires = zeroOutputTypes.has(type) ? [] : [[]];
+
+  return {
+    id: randomUUID(),
+    type,
+    z: flowId,
+    x,
+    y,
+    wires: defaultWires,
+    ...normalizedProperties,
+  };
+}
+
+/**
+ * Apply the create-node operation to the flows array.
+ *
+ * @param {object} rawResponse - Raw GET /flows response (must contain `flows` array)
+ * @param {string} type - Palette node type
+ * @param {string} flowId - ID of the target flow tab or subflow
+ * @param {object} properties - Extra properties to merge onto the node
+ * @param {number} x - X position
+ * @param {number} y - Y position
+ * @returns {{ updatedFlows: object[], currentState: object }}
+ */
+export function applyCreateNode(rawResponse, type, flowId, properties, x, y) {
+  const flows = rawResponse.flows ?? rawResponse;
+
+  // Verify the target flow exists
+  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.`);
+  }
+
+  // Reject locked flows
+  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.`);
+  }
+
+  const newNode = buildNewNode(type, flowId, properties, x, y);
+  const updatedFlows = [...flows, newNode];
+
+  return { updatedFlows, currentState: newNode };
+}
+
+/**
+ * Handler for the create-node MCP tool.
+ *
+ * @param {ReturnType<import('../nodered/client.js').createNodeRedClient>} client
+ * @param {object} params
+ * @param {string} params.type
+ * @param {string} params.flowId
+ * @param {object} [params.properties={}]
+ * @param {number} [params.x=300]
+ * @param {number} [params.y=200]
+ * @returns {Promise<{ content: Array<{ type: string, text: string }> }>}
+ */
+export async function handleCreateNode(staging, client, params) {
+  const { type, flowId, properties = {}, x = 300, y = 200 } = params;
+
+  const { currentState } = await staging.applyMutation((rawResponse) => {
+    return applyCreateNode(rawResponse, type, flowId, properties, x, y);
+  });
+
+      const data = { nodeId: currentState.id, currentState, staging: staging.getStagingSummary() };
+    return formatSuccess(data);
+}
+
+export const createNodeDefinition = {
+  name: 'create-node',
+  annotations: ANN_MUTATION,
+  outputSchema: CreateNodeResponseSchema,
+  handler: handleCreateNode,
+};

package/src/tools/create-subflow-instance.js

@@ -0,0 +1,123 @@
+/**
+ * MCP tool: create-subflow-instance
+ *
+ * Creates a new instance of an existing subflow inside a flow tab.
+ * Auto-sizes output wires to match the subflow's output port count.
+ * Validates that both the subflow and the target flow exist.
+ */
+
+import { randomUUID } from 'crypto';
+
+import { formatSuccess } from './response-utils.js';
+import { ANN_MUTATION } from './constants.js';
+import { CreateSubflowInstanceResponseSchema } from '../schemas/responses.js';
+/**
+ * Build a subflow instance node object.
+ *
+ * @param {string} subflowId - ID of the subflow definition
+ * @param {string} flowId - ID of the target flow tab
+ * @param {string|undefined} name - Display name for the instance
+ * @param {Array<{name: string, value: string, type: string}>|undefined} env - Env vars
+ * @param {number} outputCount - Number of output ports (from subflow.out.length)
+ * @param {number} x - X position
+ * @param {number} y - Y position
+ * @returns {object} New instance node
+ */
+export function buildSubflowInstance(subflowId, flowId, name, env, outputCount, x, y) {
+  // Auto-size wires: one empty array per output port
+  const wires = Array.from({ length: outputCount }, () => []);
+
+  return {
+    id: randomUUID(),
+    type: `subflow:${subflowId}`,
+    z: flowId,
+    name: name || '',
+    env: env || [],
+    x,
+    y,
+    wires,
+  };
+}
+
+/**
+ * Apply the create-subflow-instance operation to the flows array.
+ *
+ * @param {object} rawResponse - Raw GET /flows response
+ * @param {string} subflowId - ID of the subflow definition
+ * @param {string} flowId - ID of the target flow tab
+ * @param {string|undefined} name - Display name
+ * @param {Array<{name: string, value: string, type: string}>|undefined} env - Env vars
+ * @param {number} x - X position
+ * @param {number} y - Y position
+ * @returns {{ updatedFlows: object[], currentState: object }}
+ * @throws {Error} If subflow or flow does not exist, or flow is locked
+ */
+export function applyCreateSubflowInstance(rawResponse, subflowId, flowId, name, env, x, y) {
+  const flows = rawResponse.flows ?? rawResponse;
+
+  // Validate subflow exists
+  const subflow = flows.find(
+    (n) => n.type === 'subflow' && n.id === subflowId,
+  );
+  if (!subflow) {
+    throw new Error(`Subflow '${subflowId}' not found. Use get-subflows to list available subflow definitions.`);
+  }
+
+  // Validate target flow tab exists
+  const targetFlow = flows.find(
+    (n) => n.type === 'tab' && n.id === flowId,
+  );
+  if (!targetFlow) {
+    throw new Error(`Flow '${flowId}' not found. Use get-flows to list available flow tabs.`);
+  }
+
+  // Reject locked flows
+  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.`);
+  }
+
+  const outputCount = Array.isArray(subflow.out) ? subflow.out.length : 0;
+  const newNode = buildSubflowInstance(subflowId, flowId, name, env, outputCount, x, y);
+  const updatedFlows = [...flows, newNode];
+
+  return { updatedFlows, currentState: newNode };
+}
+
+/**
+ * Handler for the create-subflow-instance MCP tool.
+ *
+ * @param {ReturnType<import('../nodered/client.js').createNodeRedClient>} client
+ * @param {object} params
+ * @param {string} params.subflowId
+ * @param {string} params.flowId
+ * @param {string} [params.name]
+ * @param {Array<{name: string, value: string, type: string}>} [params.env]
+ * @param {number} [params.x=200]
+ * @param {number} [params.y=200]
+ * @returns {Promise<{ content: Array<{ type: string, text: string }> }>}
+ */
+export async function handleCreateSubflowInstance(staging, client, params) {
+  const { subflowId, flowId, name, env, x = 200, y = 200 } = params;
+
+  const { currentState } = await staging.applyMutation((rawResponse) => {
+    return applyCreateSubflowInstance(
+      rawResponse,
+      subflowId,
+      flowId,
+      name,
+      env,
+      x,
+      y,
+    );
+  });
+
+      const data = { nodeId: currentState.id, currentState, staging: staging.getStagingSummary() };
+    return formatSuccess(data);
+}
+
+export const createSubflowInstanceDefinition = {
+  name: 'create-subflow-instance',
+  annotations: ANN_MUTATION,
+  outputSchema: CreateSubflowInstanceResponseSchema,
+  handler: handleCreateSubflowInstance,
+};

package/src/tools/create-subflow.js

@@ -0,0 +1,101 @@
+/**
+ * MCP tool: create-subflow
+ *
+ * Creates a new empty subflow definition (type: "subflow").
+ * The subflow can then be populated with internal nodes using
+ * create-node (with flowId = subflowId) and connect-nodes.
+ * Ports are defined via update-subflow.
+ */
+
+import { randomUUID } from 'crypto';
+
+import { formatSuccess } from './response-utils.js';
+import { ANN_MUTATION } from './constants.js';
+import { CreateSubflowResponseSchema } from '../schemas/responses.js';
+/**
+ * Build a new subflow definition node.
+ *
+ * @param {string} name - Subflow display name
+ * @param {string|undefined} info - Markdown description
+ * @param {string|undefined} category - Palette category
+ * @param {string|undefined} color - Palette color
+ * @param {string|undefined} icon - Palette icon
+ * @param {object[]|undefined} inPorts - Input port definitions
+ * @param {object[]|undefined} outPorts - Output port definitions
+ * @returns {object} New subflow node
+ */
+export function buildSubflowDefinition(name, info, category, color, icon, inPorts, outPorts) {
+  const node = {
+    id: randomUUID(),
+    type: 'subflow',
+    name,
+    info: info || '',
+    in: inPorts || [],
+    out: outPorts || [],
+  };
+
+  // Add optional palette metadata only if provided
+  if (category) node.category = category;
+  if (color) node.color = color;
+  if (icon) node.icon = icon;
+
+  return node;
+}
+
+/**
+ * Apply the create-subflow operation to the flows array.
+ *
+ * @param {object} rawResponse - Raw GET /flows response
+ * @param {string} name - Subflow name
+ * @param {string|undefined} info - Description
+ * @param {string|undefined} category - Palette category
+ * @param {string|undefined} color - Palette color
+ * @param {string|undefined} icon - Palette icon
+ * @param {object[]|undefined} inPorts - Input port definitions
+ * @param {object[]|undefined} outPorts - Output port definitions
+ * @returns {{ updatedFlows: object[], currentState: object }}
+ */
+export function applyCreateSubflow(rawResponse, name, info, category, color, icon, inPorts, outPorts) {
+  const flows = rawResponse.flows ?? rawResponse;
+
+  const newNode = buildSubflowDefinition(name, info, category, color, icon, inPorts, outPorts);
+  const updatedFlows = [...flows, newNode];
+
+  return { updatedFlows, currentState: newNode };
+}
+
+/**
+ * Handler for the create-subflow MCP tool.
+ *
+ * @param {ReturnType<import('../nodered/client.js').createNodeRedClient>} client
+ * @param {object} params
+ * @param {string} params.name
+ * @param {string} [params.info]
+ * @param {string} [params.category]
+ * @param {string} [params.color]
+ * @param {string} [params.icon]
+ * @param {object[]} [params.in]
+ * @param {object[]} [params.out]
+ * @returns {Promise<{ content: Array<{ type: string, text: string }> }>}
+ */
+export async function handleCreateSubflow(staging, client, params) {
+  const { name, info, category, color, icon } = params;
+  const inPorts = params.in;
+  const outPorts = params.out;
+
+  const { currentState } = await staging.applyMutation((rawResponse) => {
+    return applyCreateSubflow(
+      rawResponse, name, info, category, color, icon, inPorts, outPorts,
+    );
+  });
+
+      const data = { subflowId: currentState.id, currentState, staging: staging.getStagingSummary() };
+    return formatSuccess(data);
+}
+
+export const createSubflowDefinition = {
+  name: 'create-subflow',
+  annotations: ANN_MUTATION,
+  outputSchema: CreateSubflowResponseSchema,
+  handler: handleCreateSubflow,
+};

package/src/tools/delete-context.js

@@ -0,0 +1,60 @@
+/**
+ * MCP tool: delete-context
+ *
+ * Deletes a context variable from a node, flow, or global scope in Node-RED
+ * via the Admin API (DELETE /context/{scope}/{id}/{var_name}).
+ *
+ * Note: In-memory context values are lost when Node-RED restarts anyway,
+ * but this tool explicitly removes a key from any configured store.
+ */
+import { formatSuccess } from './response-utils.js';
+
+
+import { ANN_DESTRUCTIVE } from './constants.js';
+import { DeleteContextResponseSchema } from '../schemas/responses.js';
+/**
+ * Build the API path for a context DELETE request.
+ *
+ * @param {string} scope - 'node' | 'flow' | 'global'
+ * @param {string|undefined} id - Node or flow UUID (required for node/flow scopes)
+ * @param {string} key - The context variable name to delete
+ * @returns {string} The API path
+ */
+export function buildDeleteContextPath(scope, id, key) {
+  const base = scope === 'global' ? '/context/global' : `/context/${scope}/${id}`;
+  return `${base}/${encodeURIComponent(key)}`;
+}
+
+/**
+ * Handler for the delete-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 delete
+ * @returns {Promise<{ content: Array<{ type: string, text: string }> }>}
+ */
+export async function handleDeleteContext(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 = buildDeleteContextPath(scope, id, key);
+  await client.request('DELETE', path);
+
+  const result = { scope, key, deleted: true };
+  if (id) result.id = id;
+
+  return formatSuccess(result);
+}
+
+export const deleteContextDefinition = {
+  name: 'delete-context',
+  annotations: ANN_DESTRUCTIVE,
+  outputSchema: DeleteContextResponseSchema,
+  handler: handleDeleteContext,
+};

package/src/tools/delete-flow.js

@@ -0,0 +1,81 @@
+/**
+ * MCP tool: delete-flow
+ *
+ * Deletes an existing Node-RED flow tab by ID along with all its child nodes.
+ * Stages the change locally — call `deploy` to push to Node-RED.
+ * Returns the full previous state (including nodes) before deletion.
+ * Refuses to delete a locked flow.
+ */
+
+import { formatSuccess } from './response-utils.js';
+
+import { ANN_DESTRUCTIVE } from './constants.js';
+import { DeleteFlowResponseSchema } from '../schemas/responses.js';
+/**
+ * Apply a delete-flow mutation to the flows array.
+ *
+ * Removes the flow tab and all nodes with `z === flowId`.
+ * No HTTP — pure data transformation.
+ *
+ * @param {object} rawResponse - Wrapper with `flows` array
+ * @param {string} flowId - ID of the flow tab to delete
+ * @returns {{ updatedFlows: object[], previousState: object|null }}
+ * @throws {Error} If flow not found, is the last remaining flow, or is locked
+ */
+export function applyDeleteFlow(rawResponse, flowId) {
+  const flows = rawResponse.flows ?? rawResponse;
+
+  const tabIndex = flows.findIndex((n) => n.type === 'tab' && n.id === flowId);
+  if (tabIndex === -1) {
+    throw new Error(`Flow '${flowId}' not found. Use get-flows to list available flow tabs.`);
+  }
+
+  const tab = flows[tabIndex];
+
+  if (tab.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.`);
+  }
+
+  // Guard: Node-RED requires at least one flow tab to exist
+  const tabCount = flows.filter((n) => n.type === 'tab').length;
+  if (tabCount <= 1) {
+    throw new Error(
+      'Cannot delete the last flow — at least one flow tab must exist. Use get-flows to confirm how many tabs remain, or create-flow to add a new tab before deleting this one.'
+    );
+  }
+
+  // Collect all child nodes
+  const children = flows.filter((n) => n.z === flowId);
+  const removedIds = new Set([flowId, ...children.map((n) => n.id)]);
+
+  const previousState = { tab, nodes: children };
+  const updatedFlows = flows.filter((n) => !removedIds.has(n.id));
+
+  return { updatedFlows, previousState };
+}
+
+/**
+ * Handler for the delete-flow MCP tool.
+ *
+ * @param {import('../staging-store.js').StagingStore} staging
+ * @param {object} params
+ * @param {string} params.flowId
+ * @returns {Promise<{ content: Array<{ type: string, text: string }> }>}
+ */
+export async function handleDeleteFlow(staging, params) {
+  const { flowId } = params;
+
+  const { previousState } = await staging.applyMutation((rawResponse) => {
+    return applyDeleteFlow(rawResponse, flowId);
+  });
+
+      const data = { flowId, previousState, staging: staging.getStagingSummary() };
+    return formatSuccess(data);
+}
+
+export const deleteFlowDefinition = {
+  name: 'delete-flow',
+  annotations: ANN_DESTRUCTIVE,
+  outputSchema: DeleteFlowResponseSchema,
+  handler: handleDeleteFlow,
+};