@gmag11/nodered-mcp-server 1.0.1

package/src/nodered/auth.js

@@ -0,0 +1,158 @@
+/**
+ * Node-RED authentication module.
+ *
+ * Supports three modes:
+ * - none: no authentication required
+ * - credentials: username/password → Bearer token
+ * - apikey: static API key used directly as Bearer token
+ */
+
+/**
+ * Detect the authentication mode of a Node-RED instance.
+ *
+ * If NODERED_API_KEY is set, returns 'apikey' immediately without probing.
+ * Otherwise calls GET /auth/login to determine the mode.
+ *
+ * @param {string} baseUrl - Node-RED instance URL
+ * @param {string} [apiKey] - Static API key (skips detection if provided)
+ * @returns {Promise<'none'|'credentials'|'apikey'>}
+ */
+export async function detectAuthMode(baseUrl, apiKey) {
+  if (apiKey) {
+    return 'apikey';
+  }
+
+  const res = await fetch(`${baseUrl}/auth/login`);
+  if (!res.ok) {
+    throw new Error(`Failed to detect auth mode: GET /auth/login returned ${res.status}. Check that the Node-RED instance is running and accessible at the configured baseUrl.`);
+  }
+
+  const body = await res.json();
+
+  // Empty object means no authentication configured
+  if (!body.type) {
+    return 'none';
+  }
+
+  if (body.type === 'credentials') {
+    return 'credentials';
+  }
+
+  throw new Error(
+    `Unsupported Node-RED auth type: "${body.type}". ` +
+    `Set NODERED_API_KEY in your environment to authenticate with a static token, or configure credentials via NODERED_USERNAME and NODERED_PASSWORD.`
+  );
+}
+
+/**
+ * Obtain an access token from Node-RED using the credentials grant.
+ *
+ * @param {string} baseUrl - Node-RED instance URL
+ * @param {string} username
+ * @param {string} password
+ * @returns {Promise<string>} The access_token
+ */
+export async function getToken(baseUrl, username, password) {
+  const res = await fetch(`${baseUrl}/auth/token`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({
+      client_id: 'node-red-admin',
+      grant_type: 'password',
+      scope: '*',
+      username,
+      password,
+    }),
+  });
+
+  if (!res.ok) {
+    throw new Error(`Failed to obtain Node-RED token: POST /auth/token returned ${res.status}. Check that NODERED_USERNAME and NODERED_PASSWORD are correct and that the credentials auth is enabled in Node-RED.`);
+  }
+
+  const body = await res.json();
+  return body.access_token;
+}
+
+/**
+ * Manages authentication state for a single Node-RED instance.
+ */
+export class AuthManager {
+  #baseUrl;
+  #username;
+  #password;
+  #apiKey;
+  #token = null;
+  #mode = null;
+
+  /**
+   * @param {object} config
+   * @param {string} config.baseUrl - Node-RED instance URL
+   * @param {string} [config.username]
+   * @param {string} [config.password]
+   * @param {string} [config.apiKey]
+   */
+  constructor({ baseUrl, username, password, apiKey }) {
+    this.#baseUrl = baseUrl;
+    this.#username = username;
+    this.#password = password;
+    this.#apiKey = apiKey;
+  }
+
+  /**
+   * Initialize the auth manager: detect mode and acquire token if needed.
+   * Must be called once before using getAuthHeader().
+   */
+  async init() {
+    this.#mode = await detectAuthMode(this.#baseUrl, this.#apiKey);
+
+    if (this.#mode === 'credentials') {
+      if (!this.#username || !this.#password) {
+        throw new Error(
+          'Node-RED requires credentials authentication but NODERED_USERNAME and/or NODERED_PASSWORD are not set. Set these environment variables to authenticate, or use NODERED_API_KEY for static token auth.'
+        );
+      }
+      this.#token = await getToken(this.#baseUrl, this.#username, this.#password);
+    } else if (this.#mode === 'apikey') {
+      this.#token = this.#apiKey;
+    }
+  }
+
+  /**
+   * Returns the current auth mode.
+   * @returns {'none'|'credentials'|'apikey'|null}
+   */
+  get mode() {
+    return this.#mode;
+  }
+
+  /**
+   * Returns the Authorization header value, or null if no auth is needed.
+   * @returns {string|null}
+   */
+  getAuthHeader() {
+    if (this.#mode === 'none' || !this.#token) {
+      return null;
+    }
+    return `Bearer ${this.#token}`;
+  }
+
+  /**
+   * Invalidate the current token and re-authenticate.
+   * Only applicable for credentials mode.
+   * @returns {Promise<void>}
+   */
+  async reauthenticate() {
+    if (this.#mode !== 'credentials') {
+      return;
+    }
+    this.#token = null;
+    this.#token = await getToken(this.#baseUrl, this.#username, this.#password);
+  }
+
+  /**
+   * Invalidate the current token (e.g., after a 401).
+   */
+  invalidateToken() {
+    this.#token = null;
+  }
+}

package/src/nodered/client.js

@@ -0,0 +1,199 @@
+/**
+ * Generic HTTP client for the Node-RED Admin API.
+ *
+ * Wraps native fetch with:
+ * - Automatic Node-RED-API-Version: v2 header
+ * - Authorization header via AuthManager
+ * - 401 retry (re-authenticate once then retry)
+ * - Descriptive errors for non-2xx responses
+ */
+
+/**
+ * Create a Node-RED API client bound to an AuthManager.
+ *
+ * @param {string} baseUrl - Node-RED instance URL
+ * @param {import('./auth.js').AuthManager} authManager
+ * @returns {{ request: (method: string, path: string, body?: any, extraHeaders?: object) => Promise<any>, requestText: (method: string, path: string) => Promise<string>, putFlows: (flowsPayload: any, deployType?: string) => Promise<any>, post: (path: string, body?: any) => Promise<any> }}
+ */
+export function createNodeRedClient(baseUrl, authManager) {
+  /**
+   * Make a request to the Node-RED Admin API.
+   *
+   * @param {string} method - HTTP method (GET, POST, PUT, DELETE)
+   * @param {string} path - API path (e.g., '/flows')
+   * @param {any} [body] - Request body (will be JSON-serialized)
+   * @returns {Promise<any>} Parsed JSON response, or raw text if the response is not valid JSON
+   */
+  async function request(method, path, body, extraHeaders) {
+    const url = `${baseUrl}${path}`;
+
+    const res = await doFetch(method, url, body, extraHeaders);
+
+    // Handle 401: invalidate token, re-authenticate, retry once
+    if (res.status === 401) {
+      await authManager.reauthenticate();
+      const retryRes = await doFetch(method, url, body, extraHeaders);
+
+      if (!retryRes.ok) {
+        const retryBody = await safeReadBody(retryRes);
+        throw new Error(
+          `Node-RED API error after re-auth: ${method} ${path} returned ${retryRes.status}` +
+          (retryBody ? ` — ${retryBody}` : '') +
+          '. Check your Node-RED credentials, instance URL, and that the Node-RED server is running.'
+        );
+      }
+
+      return retryRes.status === 204 ? null : parseResponseBody(retryRes);
+    }
+
+    if (!res.ok) {
+      const errorBody = await safeReadBody(res);
+      throw new Error(
+        `Node-RED API error: ${method} ${path} returned ${res.status}` +
+          (errorBody ? ` — ${errorBody}` : '') +
+          '. Check your Node-RED connection and credentials. If the error persists, try refresh-staging to ensure you are working with the latest server state.'
+      );
+    }
+
+    return res.status === 204 ? null : parseResponseBody(res);
+  }
+
+  /**
+   * Read the response body and parse as JSON. If JSON parsing fails,
+   * return the raw text (some Node-RED endpoints return plain text).
+   *
+   * @param {Response} res - Fetch Response object
+   * @returns {Promise<any>} Parsed JSON or raw text
+   */
+  async function parseResponseBody(res) {
+    const text = await res.text();
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+
+  /**
+   * Internal fetch helper that builds the correct headers.
+   */
+  async function doFetch(method, url, body, extraHeaders) {
+    console.error(`[NodeRed-MCP] → ${method} ${url}`);
+
+    const headers = {
+      'Node-RED-API-Version': 'v2',
+      'Accept': 'application/json',
+    };
+
+    const authHeader = authManager.getAuthHeader();
+    if (authHeader) {
+      headers['Authorization'] = authHeader;
+    }
+
+    if (body !== undefined) {
+      headers['Content-Type'] = 'application/json';
+    }
+
+    if (extraHeaders) {
+      Object.assign(headers, extraHeaders);
+    }
+
+    return fetch(url, {
+      method,
+      headers,
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    }).then(res => {
+      console.error(`[NodeRed-MCP] ← ${res.status} ${method} ${url}`);
+      return res;
+    });
+  }
+
+  /**
+   * Deploy the full flows payload to Node-RED using PUT /flows.
+   *
+   * @param {object} flowsPayload - The flows payload (must include `rev` from GET /flows)
+   * @param {string} [deployType='flows'] - Value for the `Node-RED-Deployment-Type` header
+   * @returns {Promise<any>} Parsed JSON response
+   */
+  async function putFlows(flowsPayload, deployType = 'flows') {
+    return request('POST', '/flows', flowsPayload, {
+      'Node-RED-Deployment-Type': deployType,
+    });
+  }
+
+  /**
+   * Make a request to the Node-RED Admin API and return the raw response body as text.
+   * Useful for endpoints that return HTML (e.g. GET /nodes with Accept: text/html).
+   *
+   * @param {string} method - HTTP method (GET, POST, PUT, DELETE)
+   * @param {string} path - API path (e.g., '/nodes')
+   * @returns {Promise<string>} Raw response body as a string
+   */
+  async function requestText(method, path) {
+    const url = `${baseUrl}${path}`;
+    const headers = {
+      'Node-RED-API-Version': 'v2',
+    };
+
+    const authHeader = authManager.getAuthHeader();
+    if (authHeader) {
+      headers['Authorization'] = authHeader;
+    }
+
+    let res = await fetch(url, { method, headers });
+
+    if (res.status === 401) {
+      await authManager.reauthenticate();
+      const authHeader2 = authManager.getAuthHeader();
+      if (authHeader2) {
+        headers['Authorization'] = authHeader2;
+      }
+      res = await fetch(url, { method, headers });
+
+      if (!res.ok) {
+        const retryBody = await safeReadBody(res);
+        throw new Error(
+          `Node-RED API error after re-auth: ${method} ${path} returned ${res.status}` +
+          (retryBody ? ` — ${retryBody}` : '') +
+          '. Check your Node-RED credentials, instance URL, and that the Node-RED server is running.'
+        );
+      }
+    } else if (!res.ok) {
+      const errorBody = await safeReadBody(res);
+      throw new Error(
+        `Node-RED API error: ${method} ${path} returned ${res.status}` +
+        (errorBody ? ` — ${errorBody}` : '') +
+        '. Check your Node-RED connection and credentials. If the error persists, try refresh-staging to ensure you are working with the latest server state.'
+      );
+    }
+
+    return res.text();
+  }
+
+  /**
+   * Make a POST request to the Node-RED Admin API.
+   * Convenience wrapper around request('POST', ...).
+   *
+   * @param {string} path - API path (e.g., '/inject/:nodeId')
+   * @param {any} [body] - Optional request body
+   * @returns {Promise<any>} Parsed JSON response
+   */
+  async function post(path, body) {
+    return request('POST', path, body);
+  }
+
+  return { request, requestText, putFlows, post };
+}
+
+/**
+ * Safely read the response body as text for error messages.
+ * Returns null if the body cannot be read.
+ */
+async function safeReadBody(res) {
+  try {
+    const text = await res.text();
+    return text.length > 200 ? text.slice(0, 200) + '…' : text;
+  } catch {
+    return null;
+  }
+}