n8n-mcp-community 0.1.0

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,48 @@
+# Third-party notices
+
+Project-authored code is licensed under MIT. Dependencies retain their own
+licenses; `package-lock.json` is the exact dependency record and
+`npm run licenses:check` validates every installed package path.
+
+The npm runtime tarball does not bundle dependencies. The following packages
+are development-only transitive dependencies of ESLint or the MCPB build CLI.
+Their published npm tarballs declare an SPDX license but omit a top-level
+LICENSE or NOTICE file. They are exact-pinned in the lockfile, are not present
+in the runtime package or MCPB, and are accepted only at the listed version,
+license, repository, and integrity hash:
+
+| Package                 | License      | Upstream repository                                                                             |
+| ----------------------- | ------------ | ----------------------------------------------------------------------------------------------- |
+| `@humanfs/types@0.15.0` | Apache-2.0   | [humanwhocodes/humanfs](https://github.com/humanwhocodes/humanfs)                               |
+| `esrecurse@4.3.0`       | BSD-2-Clause | [estools/esrecurse](https://github.com/estools/esrecurse)                                       |
+| `flora-colossus@2.0.0`  | MIT          | [MarshallOfSound/flora-colossus](https://github.com/MarshallOfSound/flora-colossus/tree/v2.0.0) |
+| `imurmurhash@0.1.4`     | MIT          | [jensyt/imurmurhash-js](https://github.com/jensyt/imurmurhash-js)                               |
+| `keyv@4.5.4`            | MIT          | [jaredwray/keyv](https://github.com/jaredwray/keyv)                                             |
+| `natural-compare@1.4.0` | MIT          | [litejs/natural-compare-lite](https://github.com/litejs/natural-compare-lite)                   |
+
+Their exact SHA-512 integrity values are enforced in
+`scripts/verify-dependency-licenses.mjs`. Any version, license, integrity, role,
+or notice-file change fails the gate and requires a new review. A package with a
+missing notice file can never use this exception when it is a runtime dependency
+or bundled into a release artifact.
+
+Complete license texts are available from the linked upstream repositories and
+the SPDX identifiers above. The final MCPB must independently preserve the
+license and notice files for every dependency it actually bundles.
+
+`minimatch@10.2.5` is another development-only ESLint dependency and is licensed
+under the permissive Blue Oak Model License 1.0.0. Its installed package includes
+the license file; the official license text and required notice link are
+<https://blueoakcouncil.org/license/1.0.0>. It is not bundled in the npm runtime
+tarball.
+
+Two development-only MCPB build dependencies offer alternative licenses. This
+project selects the permissive alternative shown below. The gate pins the exact
+version, declared expression, selected license, repository, and integrity hash;
+both installed packages include the selected license text and neither is bundled
+in the npm runtime tarball or MCPB.
+
+| Package            | Declared expression       | Selected license |
+| ------------------ | ------------------------- | ---------------- |
+| `node-forge@1.4.0` | `BSD-3-Clause OR GPL-2.0` | BSD-3-Clause     |
+| `type-fest@0.21.3` | `MIT OR CC0-1.0`          | MIT              |

package/dist/config.js

@@ -0,0 +1,76 @@
+export class ConfigurationError extends Error {
+    code = "configuration_error";
+    reason;
+    /** Name of the offending environment variable. Never its value. */
+    setting;
+    constructor(reason, setting, message) {
+        super(message);
+        this.name = "ConfigurationError";
+        this.reason = reason;
+        this.setting = setting;
+    }
+}
+function parseBoolean(value, name) {
+    if (value === undefined || value === "0")
+        return false;
+    if (value === "1")
+        return true;
+    throw new ConfigurationError("insecure_http_flag_invalid", name, `${name} must be 0 or 1.`);
+}
+function parseMode(value) {
+    const mode = value ?? "read-only";
+    if (mode === "read-only" || mode === "write" || mode === "unsafe")
+        return mode;
+    throw new ConfigurationError("mode_invalid", "N8N_MCP_MODE", "N8N_MCP_MODE must be read-only, write, or unsafe.");
+}
+export function readStartupConfig(env = process.env) {
+    return {
+        mode: parseMode(env.N8N_MCP_MODE),
+        allowInsecureHttp: parseBoolean(env.N8N_ALLOW_INSECURE_HTTP, "N8N_ALLOW_INSECURE_HTTP"),
+    };
+}
+function isLoopback(hostname) {
+    const normalized = hostname.toLowerCase();
+    return normalized === "localhost" || normalized === "127.0.0.1" || normalized === "[::1]";
+}
+function isLegalHeaderValue(value) {
+    // Reject any value the fetch/undici layer would refuse as an HTTP header value
+    // (control characters, CR, LF, or non-Latin-1 code points) so an invalid API key
+    // fails at config load with a constant message instead of surfacing a TypeError
+    // whose text can embed the raw key on every tool call.
+    return /^[\t\x20-\x7e\x80-\xff]*$/.test(value);
+}
+export function readN8nConnection(startup, env = process.env) {
+    const rawUrl = env.N8N_API_URL?.trim();
+    const apiKey = env.N8N_API_KEY?.trim();
+    if (!rawUrl) {
+        throw new ConfigurationError("api_url_missing", "N8N_API_URL", "N8N_API_URL is required for tools that connect to n8n.");
+    }
+    if (!apiKey) {
+        throw new ConfigurationError("api_key_missing", "N8N_API_KEY", "N8N_API_KEY is required for tools that connect to n8n.");
+    }
+    if (!isLegalHeaderValue(apiKey)) {
+        throw new ConfigurationError("api_key_invalid", "N8N_API_KEY", "N8N_API_KEY must be a valid HTTP header value.");
+    }
+    let apiUrl;
+    try {
+        apiUrl = new URL(rawUrl);
+    }
+    catch {
+        throw new ConfigurationError("api_url_invalid", "N8N_API_URL", "N8N_API_URL must be a valid absolute URL.");
+    }
+    if (apiUrl.protocol !== "http:" && apiUrl.protocol !== "https:") {
+        throw new ConfigurationError("api_url_scheme_unsupported", "N8N_API_URL", "N8N_API_URL must use HTTP or HTTPS.");
+    }
+    if (apiUrl.username || apiUrl.password) {
+        throw new ConfigurationError("api_url_embedded_credentials", "N8N_API_URL", "N8N_API_URL must not contain embedded credentials.");
+    }
+    if (apiUrl.search || apiUrl.hash) {
+        throw new ConfigurationError("api_url_query_or_fragment", "N8N_API_URL", "N8N_API_URL must not contain a query string or fragment.");
+    }
+    if (apiUrl.protocol === "http:" && !isLoopback(apiUrl.hostname) && !startup.allowInsecureHttp) {
+        throw new ConfigurationError("api_url_insecure_http", "N8N_API_URL", "Plaintext HTTP is allowed only for loopback URLs unless N8N_ALLOW_INSECURE_HTTP=1.");
+    }
+    apiUrl.pathname = apiUrl.pathname.replace(/\/+$/, "");
+    return { apiUrl, apiKey };
+}

package/dist/content/node-docs.js

@@ -0,0 +1,47 @@
+import { OFFICIAL_N8N_DOCUMENTATION_URLS } from "./official-urls.js";
+export const NODE_DOCUMENTATION = Object.freeze({
+    webhook: Object.freeze({
+        type: "n8n-nodes-base.webhook",
+        title: "Webhook node",
+        summary: "Starts a workflow when its test or production webhook receives an HTTP request.",
+        guidance: Object.freeze([
+            "Use a unique path and the narrowest required HTTP method.",
+            "Configure authentication when the caller is not already protected by a trusted gateway.",
+            "Use Respond to Webhook when the response must depend on downstream workflow data.",
+        ]),
+        officialUrl: OFFICIAL_N8N_DOCUMENTATION_URLS.webhook,
+    }),
+    code: Object.freeze({
+        type: "n8n-nodes-base.code",
+        title: "Code node",
+        summary: "Runs bounded custom JavaScript or Python logic inside an n8n workflow.",
+        guidance: Object.freeze([
+            "Prefer standard nodes when they express the same operation clearly.",
+            "Treat input items as untrusted and return the item structure expected by downstream nodes.",
+            "Do not embed credentials or secrets in source code.",
+        ]),
+        officialUrl: OFFICIAL_N8N_DOCUMENTATION_URLS.code,
+    }),
+    "http-request": Object.freeze({
+        type: "n8n-nodes-base.httpRequest",
+        title: "HTTP Request node",
+        summary: "Calls an HTTP API from a workflow using configured credentials, headers, query parameters, and body data.",
+        guidance: Object.freeze([
+            "Use stored n8n credentials instead of literal authorization values.",
+            "Set explicit timeouts and retry only operations that are safe to repeat.",
+            "Validate and minimize response data before passing it downstream.",
+        ]),
+        officialUrl: OFFICIAL_N8N_DOCUMENTATION_URLS.httpRequest,
+    }),
+    if: Object.freeze({
+        type: "n8n-nodes-base.if",
+        title: "If node",
+        summary: "Routes each input item to a true or false output based on configured conditions.",
+        guidance: Object.freeze([
+            "Choose explicit type-aware operators and handle missing values intentionally.",
+            "Keep condition groups small enough to review and test.",
+            "Name the node after the business decision it represents.",
+        ]),
+        officialUrl: OFFICIAL_N8N_DOCUMENTATION_URLS.if,
+    }),
+});

package/dist/content/official-urls.js

@@ -0,0 +1,11 @@
+export const OFFICIAL_N8N_DOCUMENTATION_URLS = Object.freeze({
+    webhook: "https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.webhook/",
+    code: "https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.code/",
+    httpRequest: "https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.httprequest/",
+    if: "https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.if/",
+    splitInBatches: "https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.splitinbatches/",
+});
+const OFFICIAL_N8N_DOCUMENTATION_URL_SET = new Set(Object.values(OFFICIAL_N8N_DOCUMENTATION_URLS));
+export function isOfficialN8nDocumentationUrl(value) {
+    return OFFICIAL_N8N_DOCUMENTATION_URL_SET.has(value);
+}

package/dist/doctor.js

@@ -0,0 +1,88 @@
+import { N8nApiError } from "./n8n/client.js";
+export function buildDoctorReport(startup, connection, nodeVersion = process.versions.node) {
+    const parsedMajor = Number(nodeVersion.split(".")[0]);
+    const major = Number.isInteger(parsedMajor) ? parsedMajor : null;
+    const supported = major !== null && major >= 22;
+    return {
+        status: supported ? "pass" : "fail",
+        networkAccess: false,
+        node: { major, supported },
+        configuration: {
+            mode: startup.mode,
+            apiUrlConfigured: true,
+            apiKeyConfigured: connection.apiKey.length > 0,
+            transport: connection.apiUrl.protocol === "https:" ? "https" : "http",
+            insecureHttpExplicitlyAllowed: startup.allowInsecureHttp,
+        },
+    };
+}
+/** Documented support floor. Named in reports; never asserted as the remote version. */
+export const DOCUMENTED_N8N_FLOOR = "n8n Community 2.30.5";
+/**
+ * Bounded, value-free Public API reads whose joint availability distinguishes a
+ * supported-floor instance from a below-floor one. `GET /workflows` exists on every
+ * Public-API-enabled n8n release and acts as a reachability control; `GET /credentials`
+ * is available only from the documented 2.30.5 floor onward (docs/compatibility.md), so
+ * its absence on a reachable instance is a below-floor indicator. Each read fetches a
+ * single page of size 1 and inspects only availability — never any workflow, credential,
+ * or other value.
+ */
+const FLOOR_PROBE_ENDPOINTS = [
+    { endpoint: "GET /workflows", path: "/workflows", role: "control" },
+    { endpoint: "GET /credentials", path: "/credentials", role: "floor_marker" },
+];
+async function probeEndpointAvailability(client, path) {
+    try {
+        await client.request({ path, query: { limit: "1" } });
+        return "available";
+    }
+    catch (error) {
+        if (error instanceof N8nApiError && error.status === 404)
+            return "not_found";
+        return "error";
+    }
+}
+function deriveFloorDiagnosis(control, markerNotFound, markerError) {
+    // No usable reachability control means nothing can be concluded about the floor.
+    if (control !== "available")
+        return "inconclusive";
+    // A reachable instance missing a floor-marker namespace (404) is a below-floor signal.
+    if (markerNotFound)
+        return "below_floor_indicators";
+    // A marker that failed for a non-404 reason (403 key scope, 5xx) is not a version signal.
+    if (markerError)
+        return "inconclusive";
+    return "floor_compatible";
+}
+/**
+ * Bounded, read-only floor-compatibility probe against the operator-configured instance.
+ * Contacts a fixed set of cheap Public API reads (one page of size 1 each, existing client
+ * timeouts) and reports only per-endpoint availability plus an overall diagnosis. It never
+ * reads response data, never queries or claims a remote version, and never contacts anything
+ * other than the configured instance.
+ */
+export async function probeFloorCompatibility(client) {
+    const endpoints = [];
+    let control = "error";
+    let markerNotFound = false;
+    let markerError = false;
+    for (const target of FLOOR_PROBE_ENDPOINTS) {
+        const availability = await probeEndpointAvailability(client, target.path);
+        endpoints.push({ endpoint: target.endpoint, availability });
+        if (target.role === "control") {
+            control = availability;
+        }
+        else if (availability === "not_found") {
+            markerNotFound = true;
+        }
+        else if (availability !== "available") {
+            markerError = true;
+        }
+    }
+    return {
+        diagnosis: deriveFloorDiagnosis(control, markerNotFound, markerError),
+        documentedFloor: DOCUMENTED_N8N_FLOOR,
+        remoteVersionDetected: false,
+        endpoints,
+    };
+}

package/dist/index.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+import { writeSync } from "node:fs";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ConfigurationError, readN8nConnection, readStartupConfig } from "./config.js";
+import { createServer } from "./server.js";
+import { buildDoctorReport, probeFloorCompatibility } from "./doctor.js";
+import { N8nClient } from "./n8n/client.js";
+import { PACKAGE_VERSION } from "./version.js";
+const HELP = `n8n-mcp-community ${PACKAGE_VERSION}
+
+Usage:
+  n8n-mcp-community            Start the MCP stdio server
+  n8n-mcp-community doctor     Validate configuration offline; set
+                               N8N_MCP_DOCTOR_PROBE=1 to add a bounded
+                               floor-compatibility probe
+  n8n-mcp-community --version  Print the package version
+  n8n-mcp-community --help     Show this help
+
+The server defaults to N8N_MCP_MODE=read-only. Connected tools require
+N8N_API_URL and N8N_API_KEY. Never pass secrets as command-line arguments.`;
+async function runDoctor() {
+    const startup = readStartupConfig();
+    const connection = readN8nConnection(startup);
+    const report = buildDoctorReport(startup, connection);
+    if (process.env.N8N_MCP_DOCTOR_PROBE === "1") {
+        const compatibility = await probeFloorCompatibility(new N8nClient(connection));
+        console.log(JSON.stringify({ ...report, networkAccess: true, compatibility }, null, 2));
+    }
+    else {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    if (report.status === "fail")
+        process.exitCode = 1;
+}
+async function main(args = process.argv.slice(2)) {
+    if (args.length === 1 && (args[0] === "--help" || args[0] === "-h")) {
+        console.log(HELP);
+        return;
+    }
+    if (args.length === 1 && (args[0] === "--version" || args[0] === "-v")) {
+        console.log(PACKAGE_VERSION);
+        return;
+    }
+    if (args.length === 1 && args[0] === "doctor") {
+        await runDoctor();
+        return;
+    }
+    if (args.length > 0) {
+        throw new Error("Unknown command or option. Use --help.");
+    }
+    const server = createServer();
+    await server.connect(new StdioServerTransport());
+}
+function isBrokenPipe(error) {
+    if (error === null || typeof error !== "object" || !("code" in error))
+        return false;
+    const code = error.code;
+    return code === "EPIPE" || code === "ERR_STREAM_DESTROYED";
+}
+let fatalHandled = false;
+/**
+ * Emit exactly one constant, secret-free structured line on stderr and exit with a
+ * controlled code. stdout is the MCP protocol channel, so it is never written here.
+ * `writeSync` guarantees the line is flushed before `process.exit` tears the process
+ * down, and the guard makes repeated stream failures collapse to a single line.
+ */
+function reportFatal(event, exitCode) {
+    if (fatalHandled)
+        return;
+    fatalHandled = true;
+    try {
+        writeSync(2, `${JSON.stringify({ event })}\n`);
+    }
+    catch {
+        // stderr itself is unavailable; there is nothing else we can safely do.
+    }
+    process.exit(exitCode);
+}
+/**
+ * Install process-level guards so a broken stdout pipe (the client's read end
+ * disappearing mid-session) or any other unhandled stream/async failure produces a
+ * controlled, single-line shutdown instead of a raw Node stack trace on stderr.
+ */
+function installProcessGuards() {
+    // A broken stdout pipe means the MCP peer is gone; shut down cleanly (exit 0).
+    process.stdout.on("error", (error) => {
+        reportFatal("transport_closed", isBrokenPipe(error) ? 0 : 1);
+    });
+    process.on("uncaughtException", (error) => {
+        if (isBrokenPipe(error))
+            reportFatal("transport_closed", 0);
+        else
+            reportFatal("uncaught_exception", 1);
+    });
+    process.on("unhandledRejection", (reason) => {
+        if (isBrokenPipe(reason))
+            reportFatal("transport_closed", 0);
+        else
+            reportFatal("unhandled_rejection", 1);
+    });
+}
+installProcessGuards();
+main().catch((error) => {
+    if (error instanceof ConfigurationError) {
+        console.error(JSON.stringify({
+            event: "startup_failed",
+            code: error.code,
+            reason: error.reason,
+            setting: error.setting,
+        }));
+        process.exitCode = 1;
+        return;
+    }
+    const code = error && typeof error === "object" && "code" in error && typeof error.code === "string"
+        ? error.code
+        : "startup_error";
+    console.error(JSON.stringify({ event: "startup_failed", code }));
+    process.exitCode = 1;
+});