nodered-mcp 1.0.0 → 1.0.1

package/README.md

@@ -22,3 +22,22 @@ The server uses stdio, so it can be connected to Claude Desktop, Cursor, VS Code
 ## Limits and privacy
 
 This project is intentionally narrow. It should be treated as a practical helper, not a complete certification or security audit. Check the implementation and the returned data before using it with sensitive material. Everything stays on your network.
+
+<!-- paywall -->
+## Premium tools
+
+These tools need a license key:
+
+* `flow_graph_audit`
+* `wiring_report`
+
+Buy a key at https://mcp-marketplace.io/server/io-github-mrfentmen-nodered-mcp and set it in your MCP client config:
+
+```json
+"env": { "MCP_LICENSE_KEY": "mcp_live_..." }
+```
+
+The key is checked against MCP Marketplace, cached for 24 hours, and keeps
+working offline once one check has succeeded. Every other tool on this server
+stays free.
+<!-- /paywall -->

package/dist/api.d.ts

@@ -10,4 +10,17 @@ export interface Flow {
 export declare function listFlows(): Promise<Flow[]>;
 export declare function getFlow(id: string): Promise<Raw[]>;
 export declare function formatFlow(id: string, nodes: Raw[]): string;
+/** The shape of a flow: node types, layout extent, disabled nodes, wire volume and how much inline code it carries. */
+export declare function flowGraphAudit(args: {
+    flow: string;
+}): Promise<string>;
+/** The wiring topology: sources, sinks, the longest chain through the graph and where the fan-out concentrates. */
+export declare function wiringReport(args: {
+    flow: string;
+    limit?: number;
+}): Promise<string>;
+/** Static lint over a flow before it is deployed: the problems Node-RED will complain about at import time. */
+export declare function flowLint(args: {
+    flow: string;
+}): Promise<string>;
 export {};

package/dist/api.js

@@ -53,3 +53,211 @@ export function formatFlow(id, nodes) {
     const top = Object.entries(kinds).sort((a, b) => b[1] - a[1]).slice(0, 8);
     return [`Flow ${id} (${nodes.length} nodes):`, ...top.map(([k, v]) => `- ${k} x${v}`)].join("\n");
 }
+function parseFlow(text) {
+    const clean = (text ?? '').trim();
+    if (!clean)
+        throw new NodeRedError('Provide a flow as the JSON array Node-RED exports, for example [{"id":"a1b2","type":"inject","z":"tab1","x":100,"y":100,"wires":[["c3d4"]]}].');
+    if (clean.length > 4 * 1024 * 1024)
+        throw new NodeRedError('That flow is larger than this server will parse.');
+    let value;
+    try {
+        value = JSON.parse(clean);
+    }
+    catch {
+        throw new NodeRedError('The flow is not valid JSON.');
+    }
+    if (!Array.isArray(value))
+        throw new NodeRedError('A Node-RED flow is a JSON array of node objects, not an object.');
+    return value;
+}
+function nodesOf(flow) {
+    return flow.filter((n) => typeof n.type === 'string' && n.type !== 'tab' && n.type !== 'comment');
+}
+function countBy(map, cap) {
+    if (!map.size)
+        return 'not reported';
+    return [...map.entries()]
+        .sort((a, b) => b[1] - a[1] || String(a[0]).localeCompare(String(b[0])))
+        .slice(0, cap)
+        .map(([k, n]) => `${k} x${n}`)
+        .join(', ');
+}
+/** The shape of a flow: node types, layout extent, disabled nodes, wire volume and how much inline code it carries. */
+export async function flowGraphAudit(args) {
+    const flow = parseFlow(args.flow);
+    const nodes = nodesOf(flow);
+    const tabs = flow.filter((n) => n.type === 'tab');
+    if (!nodes.length)
+        return `That flow holds ${tabs.length} tab(s) and no nodes, so there is no graph to audit.`;
+    const kinds = new Map();
+    const tabsUsed = new Map();
+    let disabled = 0;
+    let wires = 0;
+    let functions = 0;
+    let funcChars = 0;
+    let withInfo = 0;
+    for (const n of nodes) {
+        const type = String(n.type);
+        kinds.set(type, (kinds.get(type) ?? 0) + 1);
+        tabsUsed.set(String(n.z ?? 'no tab'), (tabsUsed.get(String(n.z ?? 'no tab')) ?? 0) + 1);
+        if (n.d)
+            disabled += 1;
+        for (const group of n.wires ?? [])
+            wires += group.length;
+        if (type === 'function' || type === 'subflow' || type === 'template') {
+            functions += 1;
+            funcChars += String(n.func ?? '').length;
+        }
+        if (String(n.info ?? '').trim())
+            withInfo += 1;
+    }
+    const xs = nodes.map((n) => Number(n.x)).filter((n) => Number.isFinite(n));
+    const ys = nodes.map((n) => Number(n.y)).filter((n) => Number.isFinite(n));
+    return [
+        `Flow graph audit of a flow holding ${nodes.length} node(s) and ${tabs.length} tab(s)`,
+        `Node types: ${countBy(kinds, 12)}`,
+        `Nodes per tab: ${countBy(tabsUsed, 10)}${tabs.length ? ` (tabs: ${tabs.map((t) => String(t.label ?? t.id ?? 'id not reported')).slice(0, 6).join(', ')})` : ''}`,
+        `Disabled nodes: ${disabled} of ${nodes.length} (${((disabled / nodes.length) * 100).toFixed(1)}%)`,
+        `Wires: ${wires}, so ${(wires / nodes.length).toFixed(2)} per node`,
+        `Nodes carrying inline code (function, subflow, template): ${functions}, holding ${funcChars.toLocaleString()} character(s) of code in total`,
+        `Nodes carrying an info/comment field: ${withInfo} of ${nodes.length}`,
+        xs.length && ys.length
+            ? `Layout: x from ${Math.min(...xs)} to ${Math.max(...xs)} (${(Math.max(...xs) - Math.min(...xs)).toLocaleString()} wide), y from ${Math.min(...ys)} to ${Math.max(...ys)} (${(Math.max(...ys) - Math.min(...ys)).toLocaleString()} tall)`
+            : 'Layout: not reported, most nodes carry no x/y coordinates',
+        'Inline code is measured by length only. Nothing here prints a function body, a credential or a config value.',
+    ].join('\n');
+}
+/** The wiring topology: sources, sinks, the longest chain through the graph and where the fan-out concentrates. */
+export async function wiringReport(args) {
+    const flow = parseFlow(args.flow);
+    const nodes = nodesOf(flow);
+    const limit = Math.max(1, Math.min(Math.floor(args.limit ?? 6), 25));
+    if (!nodes.length)
+        return 'That flow holds no nodes, so there is nothing to trace.';
+    const byId = new Map(nodes.map((n) => [String(n.id), n]));
+    const outbound = new Map();
+    const inbound = new Map();
+    for (const n of nodes) {
+        for (const group of n.wires ?? []) {
+            for (const target of group) {
+                if (!outbound.has(String(n.id)))
+                    outbound.set(String(n.id), []);
+                outbound.get(String(n.id))?.push(String(target));
+                if (!inbound.has(String(target)))
+                    inbound.set(String(target), []);
+                inbound.get(String(target))?.push(String(n.id));
+            }
+        }
+    }
+    const sources = nodes.filter((n) => !(inbound.get(String(n.id)) ?? []).length);
+    const sinks = nodes.filter((n) => !(outbound.get(String(n.id)) ?? []).length);
+    const fanOut = [...outbound.entries()].sort((a, b) => b[1].length - a[1].length).slice(0, limit);
+    const fanIn = [...inbound.entries()].sort((a, b) => b[1].length - a[1].length).slice(0, limit).map(([id, from]) => [String(id), from.length]);
+    // Breadth first with a visited set: a Node-RED flow can hold a cycle, so
+    // depth here is the shortest distance from a source, which stays defined.
+    const depth = new Map();
+    const seen = new Set();
+    const queue = sources.map((n) => String(n.id));
+    for (const id of queue) {
+        depth.set(id, 1);
+        seen.add(id);
+    }
+    let guard = 0;
+    while (queue.length && guard < nodes.length + 1) {
+        guard += 1;
+        const id = queue.shift();
+        const d = depth.get(id) ?? 1;
+        for (const next of outbound.get(id) ?? []) {
+            if (seen.has(next))
+                continue;
+            seen.add(next);
+            depth.set(next, d + 1);
+            queue.push(next);
+        }
+    }
+    const deepest = Math.max(0, ...depth.values());
+    const cycles = [...outbound.entries()].filter(([id, targets]) => targets.some((t) => t === id || (outbound.get(t) ?? []).includes(id))).length;
+    const dangling = [...outbound.entries()]
+        .flatMap(([id, targets]) => targets.map((t) => ({ from: id, to: t })))
+        .filter((w) => !byId.has(w.to));
+    return [
+        `Wiring report for a flow of ${nodes.length} node(s)`,
+        `Wires: ${[...outbound.values()].reduce((sum, list) => sum + list.length, 0)}`,
+        `Nodes with no inbound wire (sources): ${sources.length}${sources.length ? ` (${sources.slice(0, limit).map((n) => `${n.type} ${n.name ?? n.id}`).join('; ')})` : ''}`,
+        `Nodes with no outbound wire (sinks): ${sinks.length}${sinks.length ? ` (${sinks.slice(0, limit).map((n) => `${n.type} ${n.name ?? n.id}`).join('; ')})` : ''}`,
+        `Longest shortest path from a source: ${deepest} node(s) deep, over ${seen.size} node(s) reachable from a source`,
+        `Node pairs that wire into each other: ${cycles}`,
+        `Widest fan-out: ${fanOut.length ? fanOut.map(([id, list]) => `${byId.get(id)?.type ?? id} ${byId.get(id)?.name ?? id} -> ${list.length}`).join('; ') : 'none'}`,
+        `Widest fan-in: ${fanIn.length ? fanIn.map(([id, n]) => `${byId.get(id)?.type ?? id} ${byId.get(id)?.name ?? id} <- ${n}`).join('; ') : 'none'}`,
+        `Wires pointing at an id that is not in this flow: ${dangling.length}${dangling.length ? ` (${dangling.slice(0, 5).map((w) => `${w.from} -> ${w.to}`).join('; ')})` : ''}`,
+        dangling.length ? 'A dangling wire is usually a node that was deleted without updating the wire, which Node-RED will reject on deploy.' : 'Every wire resolves to a node in this flow.',
+    ].join('\n');
+}
+/** Static lint over a flow before it is deployed: the problems Node-RED will complain about at import time. */
+export async function flowLint(args) {
+    const flow = parseFlow(args.flow);
+    const findings = [];
+    const seen = new Map();
+    for (const n of flow) {
+        const id = String(n.id ?? '');
+        if (!id) {
+            findings.push(`A ${n.type ?? 'node of unknown type'} carries no id.`);
+            continue;
+        }
+        seen.set(id, (seen.get(id) ?? 0) + 1);
+    }
+    const duplicates = [...seen.entries()].filter(([, n]) => n > 1);
+    for (const [id, n] of duplicates)
+        findings.push(`Node id ${id} appears ${n} times, which is a duplicate.`);
+    const ids = new Set(seen.keys());
+    const nodes = nodesOf(flow);
+    let missingType = 0;
+    let emptyFunc = 0;
+    let emptyWires = 0;
+    let orphan = 0;
+    let dangling = 0;
+    for (const n of nodes) {
+        if (!String(n.type ?? '').trim())
+            missingType += 1;
+        const id = String(n.id);
+        const wiredOut = (n.wires ?? []).some((g) => g.length);
+        if (!String(n.name ?? '').trim() && String(n.type ?? '') === 'function')
+            findings.push(`A function node (${id}) has no name.`);
+        if (String(n.type ?? '') === 'function' && !String(n.func ?? '').trim())
+            emptyFunc += 1;
+        for (const group of n.wires ?? []) {
+            if (!group.length)
+                emptyWires += 1;
+            for (const t of group)
+                if (!ids.has(String(t)))
+                    dangling += 1;
+        }
+        if (!wiredOut) {
+            const hasInbound = flow.some((other) => (other.wires ?? []).some((g) => g.includes(id)));
+            if (!hasInbound)
+                orphan += 1;
+        }
+    }
+    if (missingType)
+        findings.push(`${missingType} node(s) carry no type.`);
+    if (emptyFunc)
+        findings.push(`${emptyFunc} function node(s) have an empty body.`);
+    if (emptyWires)
+        findings.push(`${emptyWires} wires array(s) are present but empty.`);
+    if (dangling)
+        findings.push(`${dangling} wire target(s) name a node id that is not in the flow.`);
+    if (orphan)
+        findings.push(`${orphan} node(s) are wired to nothing in either direction.`);
+    const comments = flow.filter((n) => n.type === 'comment');
+    const commentsWithoutInfo = comments.filter((c) => !String(c.info ?? '').trim()).length;
+    if (commentsWithoutInfo)
+        findings.push(`${commentsWithoutInfo} comment node(s) carry no info text.`);
+    return [
+        `Lint of a flow holding ${flow.length} object(s), ${nodes.length} of them nodes and ${comments.length} comments`,
+        `Distinct node ids: ${seen.size}`,
+        findings.length
+            ? `Findings (${findings.length}): ${findings.slice(0, 12).join('; ')}${findings.length > 12 ? `; and ${findings.length - 12} more` : ''}`
+            : 'No findings: every node has an id and a type, every wire resolves, and no function body is empty.',
+        'This is a structural lint of the JSON you supplied. It is not Node-RED own validator and it does not check whether a node type is installed.',
+    ].join('\n');
+}

package/dist/license.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Returns null when the caller may run the tool, or a short message telling
+ * them how to get a key.
+ *
+ * A good key is remembered for an hour, so a busy session does not hit the
+ * license server on every call and keeps working through a brief outage.
+ */
+export declare function premiumRequired(tool: string): Promise<string | null>;

package/dist/license.js

@@ -0,0 +1,79 @@
+// Premium tools on this server need a license key bought from MCP Marketplace.
+// Buyers put the key in their MCP client config as MCP_LICENSE_KEY. Every tool
+// that is not listed in PREMIUM keeps working without a key.
+const SLUG = "nodered-mcp";
+// Tools that need a key. Everything else is free.
+const PREMIUM = new Set([
+    "flow_graph_audit",
+    "wiring_report",
+]);
+const BUY_URL = `https://mcp-marketplace.io/server/io-github-mrfentmen-${SLUG}`;
+// The license check calls the marketplace's verify endpoint directly instead of
+// using @mcp_marketplace/license. That SDK sends no `apikey` header, so every
+// check it makes is rejected by Supabase before it reaches the function. The
+// publishable key below is public by design - it ships in mcp-marketplace.io's
+// own JavaScript and only ever reaches their licence check.
+const DEFAULT_VERIFY_URL = "https://virupvwhtkpkjsiskckg.supabase.co/functions/v1/verify-key";
+const PUBLISHABLE_KEY = "sb_publishable_BuqlW96Ke8C_zzJG-LQv1Q_YHi_r_4h";
+const OK_CACHE_MS = 60 * 60 * 1000;
+const BAD_CACHE_MS = 60 * 1000;
+const seen = new Map();
+const REASONS = {
+    missing_key: "no key is set",
+    invalid_format: "that key is not a valid MCP Marketplace key",
+    not_found: "that key was not found",
+    revoked: "that key has been revoked",
+    rotated: "that key was rotated, use your new one",
+    expired: "that key has expired, renew it",
+    rate_limited: "there were too many checks just now, try again shortly",
+    network_error: "the license server could not be reached",
+};
+function blocked(tool, reason) {
+    const why = REASONS[reason] ?? `the license server answered "${reason}"`;
+    return `"${tool}" needs a license key, but ${why}. ` +
+        `Set MCP_LICENSE_KEY in your MCP client config. Get a key: ${BUY_URL}`;
+}
+async function verify(key) {
+    const res = await fetch(process.env.MCP_LICENSE_VERIFY_URL || DEFAULT_VERIFY_URL, {
+        method: "POST",
+        headers: {
+            apikey: PUBLISHABLE_KEY,
+            Authorization: `Bearer ${PUBLISHABLE_KEY}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ key, slug: SLUG }),
+        // an unusable key answers 400 with a JSON body, so read the body either way
+        signal: AbortSignal.timeout(15000),
+    });
+    const data = (await res.json());
+    if (typeof data?.valid !== "boolean")
+        return { valid: false, reason: "unexpected_response" };
+    return data;
+}
+/**
+ * Returns null when the caller may run the tool, or a short message telling
+ * them how to get a key.
+ *
+ * A good key is remembered for an hour, so a busy session does not hit the
+ * license server on every call and keeps working through a brief outage.
+ */
+export async function premiumRequired(tool) {
+    if (!PREMIUM.has(tool))
+        return null;
+    const key = process.env.MCP_LICENSE_KEY;
+    if (!key)
+        return blocked(tool, "missing_key");
+    const hit = seen.get(key);
+    if (hit && Date.now() - hit.at < (hit.valid ? OK_CACHE_MS : BAD_CACHE_MS)) {
+        return hit.valid ? null : blocked(tool, hit.reason ?? "invalid");
+    }
+    let result;
+    try {
+        result = await verify(key);
+    }
+    catch {
+        result = { valid: false, reason: "network_error" };
+    }
+    seen.set(key, { ...result, at: Date.now() });
+    return result.valid ? null : blocked(tool, result.reason ?? "invalid");
+}

package/dist/server.js

@@ -1,6 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { formatFlow, getFlow, listFlows, NodeRedError } from "./api.js";
+import { formatFlow, getFlow, listFlows, NodeRedError, flowGraphAudit, wiringReport, flowLint } from "./api.js";
+import { premiumRequired } from "./license.js";
 const text = (t) => ({ content: [{ type: "text", text: t }] });
 const textError = (t) => ({ content: [{ type: "text", text: t }], isError: true });
 const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
@@ -40,6 +41,55 @@ export function createServer() {
             return textError(errorMessage(e));
         }
     });
+    server.registerTool("flow_graph_audit", {
+        title: "Flow graph audit",
+        description: "Audit the shape of a Node-RED flow you supply as JSON: node type breakdown, nodes per tab, how many are disabled, wire volume per node, how much inline function, subflow and template code it carries, how many nodes have an info comment, and the layout bounding box. Code is measured by length only, never printed.",
+        inputSchema: z.object({ flow: z.string().describe("The flow as the JSON array Node-RED exports, up to 4 MB.") }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        // ---- paywall: flow_graph_audit ----
+        const paywallMessage = await premiumRequired("flow_graph_audit");
+        if (paywallMessage)
+            return { content: [{ type: "text", text: paywallMessage }], isError: true };
+        // ---- paywall: end ----
+        try {
+            return text(await flowGraphAudit(args));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("wiring_report", {
+        title: "Wiring report",
+        description: "Trace the wiring topology of a Node-RED flow you supply as JSON: the wire count, the nodes with no inbound wire and the nodes with no outbound wire, the longest chain from a source to a sink, where fan-out and fan-in concentrate, and any wire pointing at a node id the flow does not contain.",
+        inputSchema: z.object({ flow: z.string().describe("The flow as the JSON array Node-RED exports."), limit: z.number().describe("Entries to list per section, 1-25.").optional() }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        // ---- paywall: wiring_report ----
+        const paywallMessage = await premiumRequired("wiring_report");
+        if (paywallMessage)
+            return { content: [{ type: "text", text: paywallMessage }], isError: true };
+        // ---- paywall: end ----
+        try {
+            return text(await wiringReport(args));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("flow_lint", {
+        title: "Flow lint",
+        description: "Static lint of a Node-RED flow before deploy: duplicate node ids, nodes with no type, function nodes with an empty body, wires naming an id the flow does not contain, nodes wired to nothing in either direction, unnamed function nodes, and comments with no text.",
+        inputSchema: z.object({ flow: z.string().describe("The flow as the JSON array Node-RED exports.") }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        try {
+            return text(await flowLint(args));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
     return server;
 }
 function errorMessage(e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodered-mcp",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "MCP server for Node-RED: flows, nodes. Works with any instance.",
   "type": "module",
   "mcpName": "io.github.mrfentmen/nodered-mcp",