nodered-mcp-full 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,7 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0 (2026-11-06)
4
+ - 10 tools: get_settings, list_flows, get_flow, get_node, patch_node, deploy_flows, call_endpoint, list_backups, restore_backup, list_node_types
5
+ - Safe writes: confirm flag + automatic pre-deploy backups with rotation + one-command restore
6
+ - env-driven: URL, Bearer token, custom CA, insecure TLS, read-only mode, timeout, response cap, extra headers
7
+ - Tested end-to-end against a production Node-RED behind a Caddy reverse proxy with local CA
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Simone Bonizzardi
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,90 @@
1
- # Temporary Holding Version
1
+ # nodered-mcp-full
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![CI](https://github.com/SimoneB79/nodered-mcp-full/actions/workflows/ci.yml/badge.svg)](https://github.com/SimoneB79/nodered-mcp-full/actions/workflows/ci.yml)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
5
+ [![npm](https://img.shields.io/badge/npm-nodered--mcp--full-red.svg)](https://www.npmjs.com/package/nodered-mcp-full)
6
+
7
+ **Full-featured MCP (Model Context Protocol) server for Node-RED** — gives AI agents complete, safe access to any Node-RED instance through its Admin API: read flows, nodes and settings; deploy patches and full flow sets with automatic backups; call custom HTTP endpoints; restore in one command.
8
+
9
+ Built for real-world setups:
10
+
11
+ - direct `http://localhost:1880`
12
+ - behind a **reverse proxy** (Caddy, nginx, Traefik) with private-CA or self-signed HTTPS
13
+ - with **adminAuth / OAuth bearer token**
14
+ - **read-only** deployments you do not want touched
15
+ - **production-grade writes**: every deploy requires an explicit `confirm: true`, takes an automatic pre-deploy backup (with rotation), and deploys the complete flow set — the only deploy type that is safe with config nodes
16
+
17
+ ## Tools
18
+
19
+ | Tool | Description |
20
+ |------|-------------|
21
+ | `get_settings` | Runtime settings: version, palette editability, contextStorage — check limits first |
22
+ | `list_flows` | All tabs with node counts and disabled flags |
23
+ | `get_flow` | Nodes of one tab (by id), or the whole flow document |
24
+ | `get_node` | Single node by id (full config, function code, wiring) |
25
+ | `patch_node` | Merge fields into one node (func, wires, x/y, ...) — auto backup, needs `confirm:true` |
26
+ | `deploy_flows` | Deploy a complete flow array — auto backup, needs `confirm:true` |
27
+ | `call_endpoint` | GET any HTTP endpoint served by your flows (custom diagnostics, APIs) |
28
+ | `list_backups` | List automatic pre-deploy backups |
29
+ | `restore_backup` | Restore a backup in one command — needs `confirm:true` |
30
+ | `list_node_types` | Installed palette modules and node types |
31
+
32
+ ## Configuration (environment variables)
33
+
34
+ | Variable | Default | Description |
35
+ |----------|---------|-------------|
36
+ | `NODE_RED_URL` | `http://localhost:1880` | Base URL of the editor/admin API (no trailing slash) |
37
+ | `NODE_RED_TOKEN` | — | Static bearer token (if you manage tokens yourself) |
38
+ | `NODE_RED_USER` / `NODE_RED_PASS` | — | **Recommended with adminAuth**: the server logs in automatically (`POST /auth/token`), caches and renews the token |
39
+ | `NODE_RED_CA_FILE` | — | Path to a CA certificate file for HTTPS behind a private reverse proxy |
40
+ | `NODE_RED_INSECURE_TLS` | `false` | Skip TLS verification (self-signed, testing only) |
41
+ | `NODE_RED_READ_ONLY` | `false` | Disable every write tool |
42
+ | `NODE_RED_BACKUP_DIR` | tmp dir | Where pre-deploy backups are stored |
43
+ | `NODE_RED_BACKUP_KEEP` | `20` | Backup rotation count |
44
+ | `NODE_RED_TIMEOUT_MS` | `20000` | HTTP timeout |
45
+ | `NODE_RED_MAX_RESPONSE_CHARS` | `300000` | Response size guard before truncation |
46
+ | `NODE_RED_HEADERS` | `{}` | Extra JSON headers (e.g. `{"X-Proxy-Auth": "..."}`) |
47
+
48
+ ## Usage
49
+
50
+ ### Any MCP client (stdio)
51
+
52
+ ```json
53
+ {
54
+ "mcpServers": {
55
+ "nodered": {
56
+ "command": "npx",
57
+ "args": ["-y", "nodered-mcp-full"],
58
+ "env": { "NODE_RED_URL": "http://localhost:1880" }
59
+ }
60
+ }
61
+ }
62
+ ```
63
+
64
+ See [`examples/`](examples/) for Claude Desktop, Cursor and the mcp-proxy pattern (multiple servers behind one SSE endpoint).
65
+
66
+ ### Docker (standalone)
67
+
68
+ ```bash
69
+ docker compose up -d # uses docker-compose.yml example
70
+ ```
71
+
72
+ ## Security notes
73
+
74
+ - The Node-RED Admin API controls everything: expose this server only on trusted networks.
75
+ - Prefer HTTPS with a real or private CA (`NODE_RED_CA_FILE`) and `NODE_RED_TOKEN`.
76
+ - For instances you do not want modified, set `NODE_RED_READ_ONLY=true`.
77
+ - Writes are always guarded by `confirm: true` + automatic backup + restore.
78
+
79
+ ## Development & tests
80
+
81
+ ```bash
82
+ npm install
83
+ npm test # end-to-end suite: spawns the server against a mock Node-RED Admin API
84
+ ```
85
+
86
+ CI runs the suite on Node 18/20/22 (`.github/workflows/ci.yml`).
87
+
88
+ ## License
89
+
90
+ MIT — Simone Bonizzardi
package/index.js ADDED
@@ -0,0 +1,244 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * nodered-mcp — MCP server for the Node-RED Admin API
4
+ *
5
+ * Generic, environment-driven. Works with:
6
+ * - direct Node-RED (http/https)
7
+ * - Node-RED behind a reverse proxy (Caddy/nginx/traefik) with custom CA
8
+ * - Node-RED with adminAuth enabled (Bearer token)
9
+ * - read-only deployments
10
+ *
11
+ * All writes require an explicit confirm flag and take an automatic backup first.
12
+ */
13
+ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
14
+ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
15
+ import { z } from "zod";
16
+ import http from "node:http";
17
+ import https from "node:https";
18
+ import fs from "node:fs";
19
+ import path from "node:path";
20
+ import os from "node:os";
21
+
22
+ // ---------------- environment ----------------
23
+ const URL_BASE = (process.env.NODE_RED_URL || "http://localhost:1880").replace(/\/+$/, "");
24
+ const TOKEN = process.env.NODE_RED_TOKEN || "";
25
+ const AUTH_USER = process.env.NODE_RED_USER || "";
26
+ const AUTH_PASS = process.env.NODE_RED_PASS || "";
27
+ const CA_FILE = process.env.NODE_RED_CA_FILE || "";
28
+ const INSECURE_TLS = process.env.NODE_RED_INSECURE_TLS === "true";
29
+ const READ_ONLY = process.env.NODE_RED_READ_ONLY === "true";
30
+ const BACKUP_DIR = process.env.NODE_RED_BACKUP_DIR || path.join(os.tmpdir(), "nodered-mcp-backups");
31
+ const BACKUP_KEEP = parseInt(process.env.NODE_RED_BACKUP_KEEP || "20", 10);
32
+ const TIMEOUT_MS = parseInt(process.env.NODE_RED_TIMEOUT_MS || "20000", 10);
33
+ const MAX_RESPONSE_CHARS = parseInt(process.env.NODE_RED_MAX_RESPONSE_CHARS || "300000", 10);
34
+ let EXTRA_HEADERS = {};
35
+ try { EXTRA_HEADERS = JSON.parse(process.env.NODE_RED_HEADERS || "{}"); } catch { /* ignore */ }
36
+
37
+ let ca = null;
38
+ if (CA_FILE) {
39
+ try { ca = fs.readFileSync(CA_FILE); }
40
+ catch (e) { console.error("nodered-mcp: cannot read NODE_RED_CA_FILE: " + CA_FILE); process.exit(1); }
41
+ }
42
+
43
+ // ---------------- auth token (auto login + cache) ----------------
44
+ let cachedToken = null, tokenExp = 0;
45
+ async function getToken(force) {
46
+ if (!AUTH_USER) return TOKEN;
47
+ const now = Date.now();
48
+ if (!force && cachedToken && now < tokenExp - 60000) return cachedToken;
49
+ return new Promise((resolve, reject) => {
50
+ let u;
51
+ try { u = new URL(URL_BASE + "/auth/token"); } catch (e) { reject(e); return; }
52
+ const mod = u.protocol === "https:" ? https : http;
53
+ const form = new URLSearchParams({ client_id: "node-red-editor", grant_type: "password", scope: "*", username: AUTH_USER, password: AUTH_PASS }).toString();
54
+ const req = mod.request({ hostname: u.hostname, port: u.port || (u.protocol === "https:" ? 443 : 80), path: u.pathname, method: "POST", headers: Object.assign({}, EXTRA_HEADERS, { "Content-Type": "application/x-www-form-urlencoded", "Content-Length": Buffer.byteLength(form) }), ca: ca || undefined, rejectUnauthorized: !INSECURE_TLS }, (res) => {
55
+ let data = ""; res.setEncoding("utf8");
56
+ res.on("data", c => data += c);
57
+ res.on("end", () => {
58
+ if (res.statusCode !== 200) { reject(new Error("auth login failed HTTP " + res.statusCode)); return; }
59
+ try { const j = JSON.parse(data); cachedToken = j.access_token; tokenExp = now + (j.expires_in || 604800) * 1000; resolve(cachedToken); }
60
+ catch (e) { reject(new Error("auth login: bad response")); }
61
+ });
62
+ });
63
+ req.setTimeout(TIMEOUT_MS, () => req.destroy(new Error("auth login timeout")));
64
+ req.on("error", reject);
65
+ req.write(form); req.end();
66
+ });
67
+ }
68
+
69
+ // ---------------- http client ----------------
70
+ async function request(method, urlPath, body, extraHeaders) {
71
+ const tk = await getToken(false);
72
+ return new Promise((resolve, reject) => {
73
+ let u;
74
+ try { u = new URL(URL_BASE + urlPath); }
75
+ catch (e) { reject(new Error("invalid path or base URL")); return; }
76
+ const mod = u.protocol === "https:" ? https : http;
77
+ const headers = Object.assign({}, EXTRA_HEADERS, extraHeaders || {}, { Accept: "application/json" });
78
+ if (tk) headers.Authorization = "Bearer " + tk;
79
+ let payload;
80
+ if (body !== undefined) { payload = JSON.stringify(body); headers["Content-Type"] = "application/json"; headers["Content-Length"] = Buffer.byteLength(payload); }
81
+ const req = mod.request({
82
+ hostname: u.hostname,
83
+ port: u.port || (u.protocol === "https:" ? 443 : 80),
84
+ path: u.pathname + u.search,
85
+ method,
86
+ headers,
87
+ ca: ca || undefined,
88
+ rejectUnauthorized: !INSECURE_TLS,
89
+ }, (res) => {
90
+ let data = "";
91
+ res.setEncoding("utf8");
92
+ res.on("data", (c) => { data += c; });
93
+ res.on("end", () => resolve({ status: res.statusCode, body: data }));
94
+ });
95
+ req.setTimeout(TIMEOUT_MS, () => req.destroy(new Error("request timeout after " + TIMEOUT_MS + "ms")));
96
+ req.on("error", reject);
97
+ if (payload) req.write(payload);
98
+ req.end();
99
+ });
100
+ }
101
+
102
+ async function apiGet(p) {
103
+ let r = await request("GET", p);
104
+ if (r.status === 401 && AUTH_USER) { await getToken(true); r = await request("GET", p); }
105
+ if (r.status !== 200) throw new Error("GET " + p + " -> HTTP " + r.status + ": " + r.body.slice(0, 400));
106
+ return r.body;
107
+ }
108
+ async function apiGetJson(p) { return JSON.parse(await apiGet(p)); }
109
+
110
+ function clip(text, what) {
111
+ if (text.length <= MAX_RESPONSE_CHARS) return text;
112
+ return text.slice(0, MAX_RESPONSE_CHARS) + "\n...[truncated " + what + "; raise NODE_RED_MAX_RESPONSE_CHARS if needed]";
113
+ }
114
+ function txt(obj) { return clip(typeof obj === "string" ? obj : JSON.stringify(obj, null, 1), "response"); }
115
+
116
+ // ---------------- backups ----------------
117
+ function listBackupFiles() {
118
+ try { return fs.readdirSync(BACKUP_DIR).filter(f => f.startsWith("flows-") && f.endsWith(".json")).sort(); }
119
+ catch { return []; }
120
+ }
121
+ function rotateBackups() {
122
+ const files = listBackupFiles();
123
+ while (files.length > BACKUP_KEEP) {
124
+ const f = files.shift();
125
+ try { fs.unlinkSync(path.join(BACKUP_DIR, f)); } catch { /* ignore */ }
126
+ }
127
+ }
128
+ async function backupFlows(label) {
129
+ const body = await apiGet("/flows");
130
+ fs.mkdirSync(BACKUP_DIR, { recursive: true });
131
+ const ts = new Date().toISOString().replace(/[:.]/g, "-");
132
+ const name = "flows-" + ts + (label ? "-" + label : "") + ".json";
133
+ fs.writeFileSync(path.join(BACKUP_DIR, name), body);
134
+ rotateBackups();
135
+ return name;
136
+ }
137
+
138
+ // ---------------- deploy (full, the safe way) ----------------
139
+ async function deployFlows(flows) {
140
+ const backup = await backupFlows("pre-deploy");
141
+ let r = await request("POST", "/flows", flows, { "Node-RED-Deployment-Type": "flows" });
142
+ if (r.status === 401 && AUTH_USER) { await getToken(true); r = await request("POST", "/flows", flows, { "Node-RED-Deployment-Type": "flows" }); }
143
+ if (r.status !== 204 && r.status !== 200) {
144
+ throw new Error("deploy failed HTTP " + r.status + " (backup kept: " + backup + "): " + r.body.slice(0, 400));
145
+ }
146
+ return { ok: true, http: r.status, backup: backup, nodes: Array.isArray(flows) ? flows.length : "n/a" };
147
+ }
148
+
149
+ function readOnlyError() { return "NODE_RED_READ_ONLY=true: write tools are disabled on this instance."; }
150
+
151
+ // ---------------- server ----------------
152
+ const server = new McpServer({ name: "nodered-mcp", version: "0.1.0" });
153
+ const log = (msg) => console.error("[nodered-mcp] " + msg);
154
+ log("target " + URL_BASE + (TOKEN ? " (token)" : "") + (READ_ONLY ? " READ-ONLY" : ""));
155
+
156
+ server.tool("get_settings", "Node-RED runtime settings (version, palette editability, contextStorage) — check limits before advanced work", {}, async () => {
157
+ const s = await apiGetJson("/settings");
158
+ return { content: [{ type: "text", text: txt({ version: s.version, paletteEditable: s.paletteEditable ?? null, contextStorage: s.contextStorage ?? null, httpAdminRoot: s.httpAdminRoot ?? null }) }] };
159
+ });
160
+
161
+ server.tool("list_flows", "List flow tabs with node counts and disabled flags", {}, async () => {
162
+ const flows = await apiGetJson("/flows");
163
+ const tabs = flows.filter(n => n.type === "tab");
164
+ const out = tabs.map(t => {
165
+ const nodes = flows.filter(n => n.z === t.id);
166
+ return { id: t.id, label: t.label, disabled: t.disabled || false, nodes: nodes.length, subflows: nodes.filter(n => n.type === "subflow").length };
167
+ });
168
+ return { content: [{ type: "text", text: txt(out) }] };
169
+ });
170
+
171
+ server.tool("get_flow", "Get nodes of one flow tab (by tab id) or the whole flow document", { tab_id: z.string().optional(), full: z.boolean().optional() }, async ({ tab_id, full }) => {
172
+ const flows = await apiGetJson("/flows");
173
+ if (full || !tab_id) return { content: [{ type: "text", text: txt(flows) }] };
174
+ const nodes = flows.filter(n => n.z === tab_id);
175
+ return { content: [{ type: "text", text: txt(nodes) }] };
176
+ });
177
+
178
+ server.tool("get_node", "Get a single node by id (exact config, function code, wiring)", { node_id: z.string() }, async ({ node_id }) => {
179
+ const flows = await apiGetJson("/flows");
180
+ const n = flows.find(x => x.id === node_id);
181
+ if (!n) throw new Error("node not found: " + node_id);
182
+ return { content: [{ type: "text", text: txt(n) }] };
183
+ });
184
+
185
+ server.tool("patch_node", "Patch one node by id (merge fields: func, wires, name, x, y, ...). Requires confirm:true. Takes automatic backup and deploys the full flow set.", {
186
+ node_id: z.string(),
187
+ patch: z.record(z.unknown()),
188
+ confirm: z.boolean()
189
+ }, async ({ node_id, patch, confirm }) => {
190
+ if (READ_ONLY) throw new Error(readOnlyError());
191
+ if (!confirm) throw new Error("pass confirm:true to apply this patch");
192
+ const flows = await apiGetJson("/flows");
193
+ const i = flows.findIndex(x => x.id === node_id);
194
+ if (i < 0) throw new Error("node not found: " + node_id);
195
+ flows[i] = Object.assign({}, flows[i], patch);
196
+ const res = await deployFlows(flows);
197
+ return { content: [{ type: "text", text: txt(Object.assign({ patched: node_id, fields: Object.keys(patch) }, res)) }] };
198
+ });
199
+
200
+ server.tool("deploy_flows", "Deploy a FULL flow array (the only safe deploy type). Validates it is an array, takes automatic backup first. Requires confirm:true.", {
201
+ flows: z.array(z.unknown()),
202
+ confirm: z.boolean(),
203
+ backup_label: z.string().optional()
204
+ }, async ({ flows, confirm, backup_label }) => {
205
+ if (READ_ONLY) throw new Error(readOnlyError());
206
+ if (!confirm) throw new Error("pass confirm:true to deploy");
207
+ if (!Array.isArray(flows)) throw new Error("flows must be an array (the complete flow document)");
208
+ const res = await deployFlows(flows);
209
+ return { content: [{ type: "text", text: txt(res) }] };
210
+ });
211
+
212
+ server.tool("call_endpoint", "GET an HTTP endpoint served by Node-RED flows (e.g. custom diagnostic nodes). Path must start with /.", {
213
+ path: z.string(),
214
+ }, async ({ path: p }) => {
215
+ if (!p.startsWith("/")) throw new Error("path must start with /");
216
+ const body = await apiGet(p);
217
+ return { content: [{ type: "text", text: txt(body) }] };
218
+ });
219
+
220
+ server.tool("list_backups", "List automatic pre-deploy backups available for restore", {}, async () => {
221
+ return { content: [{ type: "text", text: txt(listBackupFiles()) }] };
222
+ });
223
+
224
+ server.tool("restore_backup", "Restore a backup file (name from list_backups). Requires confirm:true.", {
225
+ file: z.string(),
226
+ confirm: z.boolean()
227
+ }, async ({ file, confirm }) => {
228
+ if (READ_ONLY) throw new Error(readOnlyError());
229
+ if (!confirm) throw new Error("pass confirm:true to restore");
230
+ const safe = path.basename(file);
231
+ const full = path.join(BACKUP_DIR, safe);
232
+ if (!fs.existsSync(full)) throw new Error("backup not found: " + safe);
233
+ const flows = JSON.parse(fs.readFileSync(full, "utf8"));
234
+ const res = await deployFlows(flows);
235
+ return { content: [{ type: "text", text: txt(Object.assign({ restored: safe }, res)) }] };
236
+ });
237
+
238
+ server.tool("list_node_types", "List installed palette modules and node types", {}, async () => {
239
+ const nodes = await apiGetJson("/nodes");
240
+ return { content: [{ type: "text", text: txt(nodes.map(m => ({ module: m.module, version: m.version, types: m.types, local: m.local, disabled: m.disabled }))) }] };
241
+ });
242
+
243
+ await server.connect(new StdioServerTransport());
244
+ log("ready: 10 tools");
package/package.json CHANGED
@@ -1,6 +1,46 @@
1
1
  {
2
2
  "name": "nodered-mcp-full",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.2.0",
4
+ "description": "Full-featured MCP server for Node-RED: complete admin-API access for AI agents — read AND safe write (confirm + automatic backups + restore), env-driven for any setup: direct, reverse proxy with custom CA, adminAuth token, read-only mode.",
5
+ "type": "module",
6
+ "bin": {
7
+ "nodered-mcp-full": "index.js"
8
+ },
9
+ "main": "index.js",
10
+ "keywords": [
11
+ "mcp",
12
+ "node-red",
13
+ "model-context-protocol",
14
+ "flows",
15
+ "automation",
16
+ "ai",
17
+ "claude",
18
+ "openclaw"
19
+ ],
20
+ "license": "MIT",
21
+ "engines": {
22
+ "node": ">=18"
23
+ },
24
+ "dependencies": {
25
+ "@modelcontextprotocol/sdk": "^1.0.0",
26
+ "zod": "^3.23.0"
27
+ },
28
+ "scripts": {
29
+ "test": "node test/e2e.mjs"
30
+ },
31
+ "repository": {
32
+ "type": "git",
33
+ "url": "git+https://github.com/SimoneB79/nodered-mcp-full.git"
34
+ },
35
+ "homepage": "https://github.com/SimoneB79/nodered-mcp-full#readme",
36
+ "bugs": {
37
+ "url": "https://github.com/SimoneB79/nodered-mcp-full/issues"
38
+ },
39
+ "author": "Simone Bonizzardi",
40
+ "files": [
41
+ "index.js",
42
+ "README.md",
43
+ "LICENSE",
44
+ "CHANGELOG.md"
45
+ ]
6
46
  }