@thecodesaiyan/tcs-n8n-mcp 1.1.0 → 1.2.0

package/README.md

@@ -23,6 +23,7 @@ An [MCP](https://modelcontextprotocol.io) server that gives AI assistants full c
 - **22 tools** covering the full n8n REST API
 - **Works everywhere** — Claude Code, Claude Desktop, VS Code, Cursor, Windsurf, Cline
 - **Secure by default** — ID validation, sanitised errors, masked secrets, request timeouts
+- **Flexible authentication** — API key (default), Bearer token, or Basic Auth
 - **Zero config** — just provide your n8n API key and go
 - **Lightweight** — under 30KB, no runtime dependencies beyond the MCP SDK and Zod
 
@@ -44,12 +45,31 @@ An [MCP](https://modelcontextprotocol.io) server that gives AI assistants full c
 npx @thecodesaiyan/tcs-n8n-mcp
 ```
 
-Set the required environment variables:
+### Interactive Setup Wizard
+
+The setup wizard walks you through configuration and tests your connection:
+
+```bash
+npx @thecodesaiyan/tcs-n8n-mcp --setup
+```
+
+It will prompt for your n8n URL, auth type, and credentials, then output ready-to-paste config for your MCP client.
+
+### Environment Variables
 
 | Variable | Required | Default | Description |
 |----------|:--------:|---------|-------------|
-| `N8N_API_KEY` | Yes | — | Your n8n API key |
+| `N8N_API_KEY` | Yes | — | Your n8n API key (or password for basic auth) |
 | `N8N_API_URL` | No | `http://localhost:5678` | Base URL of your n8n instance |
+| `N8N_AUTH_TYPE` | No | `apikey` | Authentication method: `apikey`, `bearer`, or `basic` |
+| `N8N_API_USER` | Only for `basic` | — | Username for basic authentication |
+| `N8N_TIMEOUT_MS` | No | `30000` | Request timeout in milliseconds |
+
+#### Authentication Types
+
+- **`apikey`** (default) — Sends `X-N8N-API-KEY` header. This is n8n's standard API authentication.
+- **`bearer`** — Sends `Authorization: Bearer <token>` header.
+- **`basic`** — Sends `Authorization: Basic <base64>` header. Requires `N8N_API_USER` to be set.
 
 ---
 
@@ -58,13 +78,19 @@ Set the required environment variables:
 <details>
 <summary><strong>Claude Code</strong></summary>
 
-#### Option A: CLI command
+#### Option A: Interactive wizard
 
 ```bash
-claude mcp add n8n -- npx -y @thecodesaiyan/tcs-n8n-mcp
+npx @thecodesaiyan/tcs-n8n-mcp --setup
 ```
 
-#### Option B: Manual config
+#### Option B: CLI command
+
+```bash
+claude mcp add n8n -e N8N_API_URL=http://localhost:5678 -e N8N_API_KEY=your-api-key -- npx -y @thecodesaiyan/tcs-n8n-mcp
+```
+
+#### Option C: Manual config
 
 Add to `~/.claude.json`:
 
@@ -275,9 +301,11 @@ Open **MCP Servers** > **Configure** > **Advanced MCP Settings** and add:
 | **ID Validation** | All resource IDs are validated as numeric strings to prevent path traversal attacks |
 | **Error Sanitisation** | API error responses only return HTTP status codes, never raw response bodies |
 | **Secret Masking** | Variable values are hidden in list output to prevent accidental secret exposure |
-| **Request Timeout** | All API calls have a 30-second timeout to prevent hanging connections |
+| **Request Timeout** | All API calls have a configurable timeout (default 30s) to prevent hanging connections |
 | **No Key Logging** | API keys are never logged, echoed, or included in tool output |
 | **Credential Safety** | The credentials tool only returns metadata — secrets are never exposed |
+| **Startup Validation** | Credentials and connectivity are verified on startup before accepting any requests |
+| **Header Injection Prevention** | Basic auth credentials are validated to reject control characters |
 
 ---
 
@@ -301,7 +329,14 @@ npm install
 ### Running locally
 
 ```bash
+# API key auth (default)
 N8N_API_KEY=your-key N8N_API_URL=http://localhost:5678 npm start
+
+# Bearer token auth
+N8N_AUTH_TYPE=bearer N8N_API_KEY=your-token N8N_API_URL=http://localhost:5678 npm start
+
+# Basic auth
+N8N_AUTH_TYPE=basic N8N_API_USER=admin N8N_API_KEY=password N8N_API_URL=http://localhost:5678 npm start
 ```
 
 ### Project Structure
@@ -309,6 +344,7 @@ N8N_API_KEY=your-key N8N_API_URL=http://localhost:5678 npm start
 ```
 src/
   index.ts              Entry point, fetch wrapper, server setup
+  config.ts             Auth type parsing, header building, timeout, connection check
   types.ts              Shared types, interfaces, response helpers
   validation.ts         Zod schemas for input validation
   tools/

package/build/config.js

@@ -0,0 +1,71 @@
+const VALID_AUTH_TYPES = ["apikey", "bearer", "basic"];
+const CONTROL_CHAR_RE = /[\r\n\0]/;
+/**
+ * Parse and validate N8N_AUTH_TYPE.  Defaults to "apikey" when unset.
+ * @throws if the value is not one of the supported types
+ */
+export function parseAuthType(raw) {
+    const value = (raw || "apikey").toLowerCase();
+    if (!VALID_AUTH_TYPES.includes(value)) {
+        throw new Error(`Invalid N8N_AUTH_TYPE "${raw}". Must be one of: ${VALID_AUTH_TYPES.join(", ")}`);
+    }
+    return value;
+}
+/**
+ * Build the authentication headers for n8n API requests.
+ * @throws if authType is "basic" and apiUser is missing or contains control characters
+ */
+export function buildAuthHeaders(authType, apiKey, apiUser) {
+    switch (authType) {
+        case "apikey":
+            return { "X-N8N-API-KEY": apiKey };
+        case "bearer":
+            return { Authorization: `Bearer ${apiKey}` };
+        case "basic": {
+            if (!apiUser) {
+                throw new Error("N8N_API_USER is required when N8N_AUTH_TYPE is 'basic'");
+            }
+            if (CONTROL_CHAR_RE.test(apiUser) || CONTROL_CHAR_RE.test(apiKey)) {
+                throw new Error("Invalid credentials: username and password must not contain control characters");
+            }
+            const encoded = Buffer.from(`${apiUser}:${apiKey}`).toString("base64");
+            return { Authorization: `Basic ${encoded}` };
+        }
+    }
+}
+/**
+ * Parse N8N_TIMEOUT_MS env var into a positive integer.
+ * Returns 30 000 ms for any invalid / missing value.
+ */
+export function parseTimeoutMs(raw) {
+    const value = parseInt(raw || "30000", 10);
+    if (!Number.isFinite(value) || value <= 0) {
+        return 30_000;
+    }
+    return value;
+}
+/**
+ * Probe the n8n API to verify credentials and connectivity.
+ * Returns an object indicating success or failure with an error message.
+ */
+export async function checkConnection(fetchFn) {
+    try {
+        const res = await fetchFn("/workflows?limit=1");
+        if (!res.ok) {
+            return {
+                ok: false,
+                error: `HTTP ${res.status} ${res.statusText || ""}. ` +
+                    "Verify N8N_API_URL and credentials are correct.",
+            };
+        }
+        return { ok: true };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            error: `${e instanceof Error ? e.message : String(e)}. ` +
+                "Verify N8N_API_URL is reachable.",
+        };
+    }
+}
+//# sourceMappingURL=config.js.map

package/build/index.js

@@ -8,68 +8,131 @@ import { registerTagTools } from "./tools/tags.js";
 import { registerVariableTools } from "./tools/variables.js";
 import { registerCredentialTools } from "./tools/credentials.js";
 import { registerUserTools } from "./tools/users.js";
-// --- Interactive setup mode ---
-if (process.argv.includes("--setup")) {
-    runSetup().then(() => process.exit(0)).catch((e) => {
+import { parseAuthType, buildAuthHeaders, parseTimeoutMs, checkConnection } from "./config.js";
+// --- Interactive setup: --setup flag OR missing config in a TTY ---
+if (process.argv.includes("--setup") || (!process.env.N8N_API_KEY && process.stdin.isTTY)) {
+    await runSetup().catch((e) => {
         console.error("Setup failed:", e);
         process.exit(1);
     });
+    process.exit(0);
 }
 async function runSetup() {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     console.log("\n  @thecodesaiyan/tcs-n8n-mcp - Setup Wizard\n");
     const url = (await rl.question("  n8n URL [http://localhost:5678]: ")).trim() || "http://localhost:5678";
-    const apiKey = (await rl.question("  n8n API Key: ")).trim();
+    const authTypeRaw = (await rl.question("  Auth type (apikey/bearer/basic) [apikey]: ")).trim() || "apikey";
+    let authType;
+    try {
+        authType = parseAuthType(authTypeRaw);
+    }
+    catch {
+        console.error(`\n  Invalid auth type "${authTypeRaw}". Must be: apikey, bearer, or basic.\n`);
+        rl.close();
+        process.exit(1);
+    }
+    let apiUser = "";
+    if (authType === "basic") {
+        apiUser = (await rl.question("  n8n Username: ")).trim();
+        if (!apiUser) {
+            console.error("\n  Username is required for basic auth.\n");
+            rl.close();
+            process.exit(1);
+        }
+    }
+    const credentialLabel = authType === "basic" ? "Password" : "API Key";
+    const apiKey = (await rl.question(`  n8n ${credentialLabel}: `)).trim();
     rl.close();
     if (!apiKey) {
-        console.error("\n  API key is required. Generate one in n8n: Settings > API > Create API Key\n");
+        console.error(authType === "basic"
+            ? "\n  Password is required.\n"
+            : "\n  API key is required. Generate one in n8n: Settings > API > Create API Key\n");
         process.exit(1);
     }
     // Test connection
     console.log("\n  Testing connection...");
     const testUrl = `${url.replace(/\/$/, "")}/api/v1/workflows?limit=1`;
+    const testHeaders = buildAuthHeaders(authType, apiKey, apiUser || undefined);
     try {
         const res = await fetch(testUrl, {
-            headers: { "X-N8N-API-KEY": apiKey, "Content-Type": "application/json" },
+            headers: { ...testHeaders, "Content-Type": "application/json" },
             signal: AbortSignal.timeout(10_000),
         });
         if (!res.ok) {
             console.error(`  Connection failed: HTTP ${res.status}`);
-            console.error("  Check your URL and API key, then try again.\n");
+            console.error("  Check your URL and credentials, then try again.\n");
             process.exit(1);
         }
         console.log("  Connected successfully!\n");
     }
     catch (e) {
         console.error(`  Connection failed: ${e instanceof Error ? e.message : e}`);
-        console.error("  Check your URL and API key, then try again.\n");
+        console.error("  Check your URL and credentials, then try again.\n");
         process.exit(1);
     }
-    const pkg = "@thecodesaiyan/tcs-n8n-mcp";
-    const envJson = JSON.stringify({ N8N_API_URL: url, N8N_API_KEY: apiKey });
-    const stdioCfg = {
-        command: "npx",
-        args: ["-y", pkg],
-        env: { N8N_API_URL: url, N8N_API_KEY: apiKey },
+    // Build env config — only include non-default values
+    const env = {
+        N8N_API_URL: url,
+        N8N_API_KEY: apiKey,
     };
+    if (authType !== "apikey") {
+        env.N8N_AUTH_TYPE = authType;
+    }
+    if (authType === "basic") {
+        env.N8N_API_USER = apiUser;
+    }
+    const pkg = "@thecodesaiyan/tcs-n8n-mcp";
+    const isWindows = process.platform === "win32";
+    const stdioCfg = isWindows
+        ? { command: "tcs-n8n-mcp", args: [], env }
+        : { command: "npx", args: ["-y", pkg], env };
+    const envFlags = Object.entries(env)
+        .map(([k, v]) => `-e ${k}=${v}`)
+        .join(" ");
+    if (isWindows) {
+        console.log("  ── Prerequisites (Windows) ──");
+        console.log(`  npm install -g ${pkg}\n`);
+    }
     console.log("  ── Claude Code ──");
-    console.log(`  claude mcp add tcs-n8n-mcp -e N8N_API_URL=${url} -e N8N_API_KEY=${apiKey} -- npx -y ${pkg}\n`);
+    if (isWindows) {
+        console.log(`  claude mcp add tcs-n8n-mcp ${envFlags} -- tcs-n8n-mcp\n`);
+    }
+    else {
+        console.log(`  claude mcp add tcs-n8n-mcp ${envFlags} -- npx -y ${pkg}\n`);
+    }
     console.log("  ── Claude Desktop / Windsurf ──");
     console.log("  Add to your config JSON under \"mcpServers\":\n");
     console.log(`  "tcs-n8n-mcp": ${JSON.stringify(stdioCfg, null, 4)}\n`);
     console.log("  ── Cursor ──");
     console.log("  Add to .cursor/mcp.json under \"mcpServers\":\n");
     console.log(`  "tcs-n8n-mcp": ${JSON.stringify(stdioCfg, null, 4)}\n`);
+    console.log("  Note: The above snippets contain your credentials.");
+    console.log("  Avoid sharing them in public channels or screenshots.\n");
 }
 // --- Normal MCP server mode ---
 const N8N_API_URL = process.env.N8N_API_URL || "http://localhost:5678";
 const N8N_API_KEY = process.env.N8N_API_KEY || "";
+const N8N_API_USER = process.env.N8N_API_USER || "";
 if (!N8N_API_KEY) {
-    console.error("N8N_API_KEY environment variable is required");
+    console.error("N8N_API_KEY environment variable is required.");
+    console.error("Tip: run `npx @thecodesaiyan/tcs-n8n-mcp --setup` for interactive configuration.");
+    process.exit(1);
+}
+let authType;
+try {
+    authType = parseAuthType(process.env.N8N_AUTH_TYPE);
+}
+catch (e) {
+    console.error(e instanceof Error ? e.message : String(e));
+    process.exit(1);
+}
+if (authType === "basic" && !N8N_API_USER) {
+    console.error("N8N_API_USER environment variable is required when N8N_AUTH_TYPE is 'basic'");
     process.exit(1);
 }
+const authHeaders = buildAuthHeaders(authType, N8N_API_KEY, N8N_API_USER || undefined);
 const apiBase = `${N8N_API_URL.replace(/\/$/, "")}/api/v1`;
-const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_TIMEOUT_MS = parseTimeoutMs(process.env.N8N_TIMEOUT_MS);
 const n8nFetch = (path, options = {}) => {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
@@ -77,7 +140,7 @@ const n8nFetch = (path, options = {}) => {
         ...options,
         signal: options.signal ?? controller.signal,
         headers: {
-            "X-N8N-API-KEY": N8N_API_KEY,
+            ...authHeaders,
             "Content-Type": "application/json",
             ...options.headers,
         },
@@ -85,7 +148,7 @@ const n8nFetch = (path, options = {}) => {
 };
 const server = new McpServer({
     name: "@thecodesaiyan/tcs-n8n-mcp",
-    version: "1.1.0",
+    version: "1.2.0",
 });
 // Register all tool modules
 registerWorkflowTools(server, n8nFetch);
@@ -95,9 +158,14 @@ registerVariableTools(server, n8nFetch);
 registerCredentialTools(server, n8nFetch);
 registerUserTools(server, n8nFetch);
 async function main() {
+    const result = await checkConnection(n8nFetch);
+    if (!result.ok) {
+        console.error(`n8n connection check failed: ${result.error}`);
+        process.exit(1);
+    }
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error("@thecodesaiyan/tcs-n8n-mcp v1.1.0 running on stdio (22 tools)");
+    console.error("@thecodesaiyan/tcs-n8n-mcp v1.2.0 running on stdio (22 tools)");
 }
 main().catch((error) => {
     console.error("Fatal error:", error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thecodesaiyan/tcs-n8n-mcp",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "MCP server for n8n workflow automation. Manage workflows, executions, tags, variables, credentials and users via the Model Context Protocol.",
   "type": "module",
   "main": "build/index.js",