@fruggr/zendesk-mcp-server 1.3.0 → 1.4.1

package/README.md

@@ -1,6 +1,11 @@
 # Zendesk MCP Server
 
-[![npm](https://img.shields.io/npm/v/@fruggr/zendesk-mcp-server)](https://www.npmjs.com/package/@fruggr/zendesk-mcp-server)
+[![Glama score](https://glama.ai/mcp/servers/fruggr/zendesk-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/fruggr/zendesk-mcp-server)
+[![npm version](https://img.shields.io/npm/v/@fruggr/zendesk-mcp-server?logo=npm&color=cb3837)](https://www.npmjs.com/package/@fruggr/zendesk-mcp-server)
+[![License: MIT](https://img.shields.io/npm/l/@fruggr/zendesk-mcp-server?color=blue)](LICENSE)
+[![Node.js](https://img.shields.io/node/v/@fruggr/zendesk-mcp-server?logo=nodedotjs&logoColor=white&color=339933)](https://nodejs.org)
+[![Renovate enabled](https://img.shields.io/badge/renovate-enabled-brightgreen?logo=renovatebot&logoColor=white)](https://renovatebot.com)
+[![semantic-release](https://img.shields.io/badge/semantic--release-e10079?logo=semantic-release&logoColor=white)](https://github.com/semantic-release/semantic-release)
 
 A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that connects LLMs to the **Zendesk Support & Help Center APIs** — with per-user OAuth 2.1 PKCE authentication and fine-grained tool visibility controls.
 
@@ -16,6 +21,21 @@ Most Zendesk integrations use a shared admin API key, giving every user full acc
 
 > Built and maintained by [Digital4better](https://digital4better.com) for the [Fruggr](https://www.fruggr.io) project.
 
+## When to use this server
+
+**Reach for it when:**
+
+- You want an LLM to read or triage **Zendesk tickets** and **Help Center articles** on behalf of a real user, with that user's own permissions — not a shared admin key.
+- You're editing **large Help Center articles** and want section-scoped reads/rewrites instead of round-tripping the full HTML body through the model.
+- You need to **cap the tool surface** — read-only assistants, a single namespace, or one unified tool to fit a tight context budget.
+- You run a **stdio MCP client** (Claude Desktop, Claude Code, Cursor, VS Code, Cline, …) and want a `npx`-installable server with no extra infrastructure.
+
+**Look elsewhere when:**
+
+- You need Zendesk products outside Support & Guide (e.g. Talk, Explore analytics, Sell) — those endpoints aren't covered.
+- You want a hosted/remote HTTP server: this one speaks stdio and runs next to the client.
+- You need a single shared service account for all users — that's the opposite of this server's per-user OAuth model (use API-token auth if you must, but one identity then applies to everyone).
+
 ## Tool modes
 
 The server registers tools in one of three modes, controlled by `--mode`:
@@ -291,10 +311,38 @@ zendesk-mcp-server acme --tool get_ticket --tool search_tickets --tool get_curre
 | `ZENDESK_OAUTH_CLIENT_ID` | no | `<subdomain>_zendesk` | OAuth client identifier |
 | `ZENDESK_EMAIL` | for API token auth | — | Agent email for Basic auth |
 | `ZENDESK_API_TOKEN` | for API token auth | — | Zendesk API token |
-| `LOG_LEVEL` | no | `info` | Log verbosity |
+| `LOG_LEVEL` | no | `info` | Log verbosity (`debug` surfaces the full OAuth flow trace) |
 
 If both `ZENDESK_EMAIL` and `ZENDESK_API_TOKEN` are set, the server uses API token auth. Otherwise, it uses OAuth 2.1 PKCE.
 
+## Troubleshooting
+
+### The browser doesn't open during OAuth login
+
+The OAuth flow opens your default browser on the first tool call. If it doesn't
+open (common in sandboxed or remote desktop environments), the authorization URL
+is still printed to the server's stderr — open it manually.
+
+To collect diagnostics, restart with `LOG_LEVEL=debug`. The server then emits
+structured logs through **two channels**, so they're reachable on any MCP client:
+
+- **stderr** — captured to a log file by every mainstream client.
+- **MCP logging notifications** (`notifications/message`) — surfaced by clients
+  that support the `logging` capability.
+
+When the browser fails to open, look for the `oauth_browser_open_failed` event:
+it reports the underlying error, the platform, and which environment markers are
+present (no secrets, tokens, or env values are ever logged).
+
+Where each client writes the server's stderr:
+
+| Client | Log location |
+|--------|--------------|
+| Claude Desktop (macOS) | `~/Library/Logs/Claude/mcp-server-*.log` |
+| Claude Desktop (Windows) | `%APPDATA%\Claude\logs\mcp-server-*.log` |
+| Claude Code | `claude --debug`, or the session logs |
+| Cursor / VS Code / Cline | the extension's MCP output/log panel |
+
 ## Development
 
 ### Toolchain
@@ -348,6 +396,43 @@ Versions follow [SemVer](https://semver.org/) and are calculated **automatically
 | `feat!:`, `fix!:`, or a `BREAKING CHANGE:` footer | major |
 | `docs:`, `chore:`, `refactor:`, `test:`, `ci:`, `style:`, `build:` | no release |
 
+## FAQ
+
+**Do I need a Zendesk admin API key?**
+No. The default OAuth 2.1 PKCE flow means each user authenticates with their own
+credentials and the server acts with exactly their permissions. API-token auth is
+available for headless/CI use (see [Authentication](#authentication)).
+
+**Which Zendesk products are supported?**
+Zendesk Support (tickets, users, organizations) and the Help Center / Guide
+(articles, sections, categories, translations, labels, content tags, segments,
+attachments). Talk, Explore, and Sell are out of scope.
+
+**How do I keep the model's context small?**
+Use `--mode single` (one `zendesk` tool) or `--mode namespace` (three proxies),
+and `--read-only` to drop write operations. For big articles, the section-based
+tools (`get_article_outline`, `get_article_section`, `update_article_section`)
+let the model touch one section at a time instead of the whole HTML body.
+
+**Can I restrict it to read-only?**
+Yes — pass `--read-only` and every write tool is filtered out before the proxies
+are built, in any mode.
+
+**Which Node.js version do I need?**
+Node.js >= 20 to run the published package (`engines.node`). The dev toolchain
+uses a newer Node — see [Development](#development).
+
+**The OAuth browser window didn't open. What now?**
+The authorization URL is also printed to stderr — open it manually. Restart with
+`LOG_LEVEL=debug` for the full flow trace. See
+[Troubleshooting](#troubleshooting).
+
+**Is it safe to run via `npx`?**
+Releases are published from CI via npm Trusted Publishing (OIDC), so each version
+carries a build provenance attestation you can verify on its
+[npm page](https://www.npmjs.com/package/@fruggr/zendesk-mcp-server). No secrets
+are ever logged by the server.
+
 ## Contributing
 
 Pull requests are welcome — including AI-assisted ones, as long as the human author has read and validated every line.

package/dist/index.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import { createHash, randomBytes } from "node:crypto";
+import { readFileSync } from "node:fs";
 import { createServer } from "node:http";
+import { release } from "node:os";
 import open from "open";
 import * as z from "zod/v4";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -15,6 +17,8 @@ import remarkParse from "remark-parse";
 import remarkRehype from "remark-rehype";
 import remarkStringify from "remark-stringify";
 import { unified } from "unified";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 //#region src/auth/api-token.ts
 /**
@@ -26,6 +30,91 @@ const buildBasicAuthHeader = (email, apiToken) => {
 	return `Basic ${Buffer.from(credentials).toString("base64")}`;
 };
 //#endregion
+//#region src/utils/logger.ts
+const SEVERITY = {
+	debug: 0,
+	info: 1,
+	warn: 2,
+	error: 3
+};
+const MCP_LEVEL = {
+	debug: "debug",
+	info: "info",
+	warn: "warning",
+	error: "error"
+};
+const REDACTED_KEYS = new Set([
+	"token",
+	"accesstoken",
+	"refreshtoken",
+	"code",
+	"codeverifier",
+	"authorization",
+	"password",
+	"secret",
+	"apitoken",
+	"bearer"
+]);
+const isSensitive = (key) => REDACTED_KEYS.has(key.toLowerCase().replace(/[_-]/g, ""));
+const redactValue = (value) => {
+	if (Array.isArray(value)) return value.map(redactValue);
+	if (value && typeof value === "object") {
+		const out = {};
+		for (const [key, val] of Object.entries(value)) out[key] = isSensitive(key) ? "[REDACTED]" : redactValue(val);
+		return out;
+	}
+	return value;
+};
+const renderValue = (value) => {
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean" || value === null) return String(value);
+	try {
+		return JSON.stringify(value);
+	} catch {
+		return "[unserializable]";
+	}
+};
+const formatLine = (level, event, fields) => {
+	const parts = Object.entries(fields).map(([key, value]) => `${key}=${renderValue(value)}`);
+	return `[zendesk-mcp] [${level}] ${event}${parts.length ? ` ${parts.join(" ")}` : ""}`;
+};
+const noop = () => {};
+const silentLogger = {
+	debug: noop,
+	info: noop,
+	warn: noop,
+	error: noop,
+	attachServer: noop
+};
+const createLogger = (level) => {
+	const min = SEVERITY[level];
+	let server;
+	const emit = (lvl, event, fields) => {
+		if (SEVERITY[lvl] < min) return;
+		const safe = fields ? redactValue(fields) : {};
+		console.error(formatLine(lvl, event, safe));
+		if (server) try {
+			server.sendLoggingMessage({
+				level: MCP_LEVEL[lvl],
+				logger: "zendesk-mcp-server",
+				data: {
+					...safe,
+					event
+				}
+			}).catch(noop);
+		} catch {}
+	};
+	return {
+		debug: (event, fields) => emit("debug", event, fields),
+		info: (event, fields) => emit("info", event, fields),
+		warn: (event, fields) => emit("warn", event, fields),
+		error: (event, fields) => emit("error", event, fields),
+		attachServer: (s) => {
+			server = s;
+		}
+	};
+};
+//#endregion
 //#region src/constants.ts
 const CHARACTER_LIMIT = 25e3;
 const MAX_COMMENT_PAGES = Number(process.env["ZENDESK_MAX_COMMENT_PAGES"] ?? 10);
@@ -38,6 +127,23 @@ const getOAuthUrls = (subdomain) => ({
 //#endregion
 //#region src/auth/browser-oauth.ts
 const DEFAULT_CALLBACK_PORT = 3e3;
+const AUTH_TIMEOUT_MS = 300 * 1e3;
+/** Best-effort WSL detection: WSL kernels carry "microsoft" in /proc/version. */
+const detectWsl = () => {
+	if (process.platform !== "linux") return false;
+	try {
+		return readFileSync("/proc/version", "utf8").toLowerCase().includes("microsoft");
+	} catch {
+		return false;
+	}
+};
+/**
+* Escape a string for safe interpolation into HTML text/attribute context.
+* The local callback server echoes attacker-controllable values (the OAuth
+* `error_description` query param, token-exchange error bodies) back into the
+* browser response; without escaping these are a reflected-XSS sink.
+*/
+const escapeHtml = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 const generateCodeVerifier = () => randomBytes(32).toString("base64url");
 const generateCodeChallenge = (verifier) => createHash("sha256").update(verifier).digest("base64url");
 /**
@@ -45,13 +151,14 @@ const generateCodeChallenge = (verifier) => createHash("sha256").update(verifier
 * Starts a temporary HTTP server to receive the callback.
 * Returns the access token on success.
 */
-const authenticateViaBrowser = (config) => {
+const authenticateViaBrowser = (config, logger = silentLogger) => {
 	const { subdomain, oauthClientId } = config;
 	const { authorizeUrl, tokenUrl } = getOAuthUrls(subdomain);
 	const codeVerifier = generateCodeVerifier();
 	const codeChallenge = generateCodeChallenge(codeVerifier);
 	return new Promise((resolve, reject) => {
 		let callbackServer;
+		let authTimeout;
 		callbackServer = createServer(async (req, res) => {
 			const url = new URL(req.url ?? "/", `http://localhost`);
 			if (url.pathname !== "/callback") {
@@ -61,10 +168,15 @@ const authenticateViaBrowser = (config) => {
 			}
 			const code = url.searchParams.get("code");
 			const error = url.searchParams.get("error");
+			logger.debug("oauth_callback_received", {
+				hasCode: Boolean(code),
+				hasError: Boolean(error)
+			});
 			if (error) {
 				const desc = url.searchParams.get("error_description") ?? error;
 				res.writeHead(400, { "Content-Type": "text/html" });
-				res.end(`<html><body><h1>Authentication failed</h1><p>${desc}</p></body></html>`);
+				res.end(`<html><body><h1>Authentication failed</h1><p>${escapeHtml(desc)}</p></body></html>`);
+				clearTimeout(authTimeout);
 				callbackServer.close();
 				reject(/* @__PURE__ */ new Error(`OAuth error: ${desc}`));
 				return;
@@ -72,6 +184,7 @@ const authenticateViaBrowser = (config) => {
 			if (!code) {
 				res.writeHead(400, { "Content-Type": "text/html" });
 				res.end("<html><body><h1>Missing authorization code</h1></body></html>");
+				clearTimeout(authTimeout);
 				callbackServer.close();
 				reject(/* @__PURE__ */ new Error("Missing authorization code in callback"));
 				return;
@@ -90,24 +203,29 @@ const authenticateViaBrowser = (config) => {
 					headers: { "Content-Type": "application/x-www-form-urlencoded" },
 					body: tokenBody.toString()
 				});
+				logger.debug("oauth_token_exchange", { status: tokenResponse.status });
 				if (!tokenResponse.ok) {
 					const errorBody = await tokenResponse.text();
 					throw new Error(`Token exchange failed (${tokenResponse.status}): ${errorBody}`);
 				}
 				const tokenData = await tokenResponse.json();
+				logger.info("oauth_authenticated");
 				res.writeHead(200, { "Content-Type": "text/html" });
 				res.end("<html><body><h1>Authentication successful!</h1><p>You can close this tab and return to Claude Code.</p><script>window.close()<\/script></body></html>");
+				clearTimeout(authTimeout);
 				callbackServer.close();
 				resolve(tokenData);
 			} catch (err) {
 				res.writeHead(500, { "Content-Type": "text/html" });
-				res.end(`<html><body><h1>Token exchange failed</h1><p>${err instanceof Error ? err.message : String(err)}</p></body></html>`);
+				res.end(`<html><body><h1>Token exchange failed</h1><p>${escapeHtml(err instanceof Error ? err.message : String(err))}</p></body></html>`);
+				clearTimeout(authTimeout);
 				callbackServer.close();
 				reject(err);
 			}
 		});
 		callbackServer.listen(config.callbackPort ?? DEFAULT_CALLBACK_PORT, () => {
-			const redirectUri = `http://localhost:${callbackServer.address().port}/callback`;
+			const port = callbackServer.address().port;
+			const redirectUri = `http://localhost:${port}/callback`;
 			const authUrl = `${authorizeUrl}?${new URLSearchParams({
 				response_type: "code",
 				client_id: oauthClientId,
@@ -116,19 +234,42 @@ const authenticateViaBrowser = (config) => {
 				code_challenge: codeChallenge,
 				code_challenge_method: "S256"
 			}).toString()}`;
+			logger.debug("oauth_callback_listening", {
+				port,
+				redirectUri
+			});
+			logger.info("oauth_browser_opening");
+			logger.debug("oauth_authorize_url", { url: authUrl });
 			console.error(`Opening browser for Zendesk authentication...`);
 			console.error(`If the browser doesn't open, visit: ${authUrl}`);
-			open(authUrl).catch(() => {});
+			open(authUrl).then(() => {
+				logger.debug("oauth_browser_opened");
+			}).catch((err) => {
+				logger.error("oauth_browser_open_failed", {
+					error: err instanceof Error ? err.message : String(err),
+					errorCode: err?.code,
+					platform: process.platform,
+					release: release(),
+					isWsl: detectWsl(),
+					hasSystemRoot: Boolean(process.env["SYSTEMROOT"]),
+					hasWindir: Boolean(process.env["WINDIR"]),
+					hasComSpec: Boolean(process.env["ComSpec"]),
+					hasPath: Boolean(process.env["PATH"]),
+					hasDisplay: Boolean(process.env["DISPLAY"])
+				});
+			});
 		});
-		setTimeout(() => {
+		authTimeout = setTimeout(() => {
+			logger.error("oauth_timeout", { timeoutMs: AUTH_TIMEOUT_MS });
 			callbackServer.close();
 			reject(/* @__PURE__ */ new Error("OAuth authentication timed out (5 min). Please try again."));
-		}, 300 * 1e3).unref();
+		}, AUTH_TIMEOUT_MS);
+		authTimeout.unref();
 	});
 };
 //#endregion
 //#region src/auth/token-store.ts
-const createTokenStore = (config) => {
+const createTokenStore = (config, logger = silentLogger) => {
 	let token;
 	let authPromise;
 	const setToken = (accessToken, refreshToken) => {
@@ -138,22 +279,29 @@ const createTokenStore = (config) => {
 		};
 	};
 	const ensureToken = async () => {
-		if (token) return token;
-		if (!authPromise) authPromise = authenticateViaBrowser({
-			subdomain: config.subdomain,
-			oauthClientId: config.oauthClientId
-		}).then((result) => {
-			const stored = {
-				accessToken: result.access_token,
-				refreshToken: result.refresh_token
-			};
-			token = stored;
-			authPromise = void 0;
-			return stored;
-		}).catch((err) => {
-			authPromise = void 0;
-			throw err;
-		});
+		if (token) {
+			logger.debug("oauth_token_cache_hit");
+			return token;
+		}
+		if (!authPromise) {
+			logger.info("oauth_auth_start");
+			authPromise = authenticateViaBrowser({
+				subdomain: config.subdomain,
+				oauthClientId: config.oauthClientId
+			}, logger).then((result) => {
+				const stored = {
+					accessToken: result.access_token,
+					refreshToken: result.refresh_token
+				};
+				token = stored;
+				authPromise = void 0;
+				return stored;
+			}).catch((err) => {
+				authPromise = void 0;
+				logger.warn("oauth_auth_failed", { error: err instanceof Error ? err.message : String(err) });
+				throw err;
+			});
+		}
 		return authPromise;
 	};
 	const getToken = async () => {
@@ -382,7 +530,7 @@ const textOf = (html) => {
 	return cheerio.load(`<div>${html}</div>`, null, false)("div").first().text();
 };
 const parseSections = (html) => {
-	if (!html || !html.trim()) return [];
+	if (!html?.trim()) return [];
 	const $ = cheerio.load(html, null, false);
 	const children = $.root().contents().toArray();
 	const introParts = [];
@@ -1799,6 +1947,45 @@ const createAllTools = (ctx) => [
 	...createUserTools(ctx)
 ];
 //#endregion
+//#region src/utils/package-info.ts
+const FALLBACK = {
+	name: "@fruggr/zendesk-mcp-server",
+	version: "0.0.0"
+};
+/**
+* Read `name`/`version` from the package's own package.json at runtime instead
+* of hardcoding them. Walks up from this module to the nearest package.json,
+* which resolves correctly both when bundled (`dist/index.js` → repo root) and
+* from source/tests (`src/` has no package.json, so the root is found). Reading
+* at runtime (not inlining at build) matters because semantic-release bumps the
+* version into package.json before publishing, after the build step.
+*/
+let cached;
+const readPackageInfo = () => {
+	if (cached) return cached;
+	let dir = dirname(fileURLToPath(import.meta.url));
+	for (let depth = 0; depth < 8; depth++) {
+		try {
+			const raw = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+			if (raw && typeof raw === "object") {
+				const pkg = raw;
+				if (typeof pkg.name === "string" && typeof pkg.version === "string") {
+					cached = {
+						name: pkg.name,
+						version: pkg.version
+					};
+					return cached;
+				}
+			}
+		} catch {}
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	cached = FALLBACK;
+	return cached;
+};
+//#endregion
 //#region src/server.ts
 const NAMESPACE_LABELS = {
 	tickets: {
@@ -1840,11 +2027,13 @@ const registerProxyTool = (server, toolName, title, tools, handlerMap) => {
 		return def.handler(validated);
 	});
 };
-const createMcpServer = (config, getToken) => {
+const createMcpServer = (config, getToken, logger = silentLogger) => {
+	const pkg = readPackageInfo();
 	const server = new McpServer({
-		name: "@digital4better/zendesk-mcp-server",
-		version: "0.1.0"
-	});
+		name: pkg.name,
+		version: pkg.version
+	}, { capabilities: { logging: {} } });
+	logger.attachServer(server);
 	const filteredTools = filterTools(createAllTools({
 		subdomain: config.subdomain,
 		getToken
@@ -1876,28 +2065,32 @@ const createMcpServer = (config, getToken) => {
 			registerProxyTool(server, "zendesk", "Zendesk", filteredTools, handlerMap);
 			break;
 	}
-	console.error(`Registered ${filteredTools.length} tools in ${config.mode} mode`);
+	logger.info("tools_registered", {
+		count: filteredTools.length,
+		mode: config.mode
+	});
 	return server;
 };
 //#endregion
 //#region src/transports/stdio.ts
-const startStdioTransport = async (server) => {
+const startStdioTransport = async (server, logger = silentLogger) => {
 	const transport = new StdioServerTransport();
 	await server.connect(transport);
-	console.error("Zendesk MCP server running via stdio");
+	logger.info("stdio_transport_ready");
 };
 //#endregion
 //#region src/index.ts
 const main = async () => {
 	const config = loadConfig();
+	const logger = createLogger(config.logLevel);
 	if (config.zendeskEmail && config.zendeskApiToken) {
 		const staticToken = buildBasicAuthHeader(config.zendeskEmail, config.zendeskApiToken);
 		const getToken = () => staticToken;
-		await startStdioTransport(createMcpServer(config, getToken));
+		await startStdioTransport(createMcpServer(config, getToken, logger), logger);
 	} else await startStdioTransport(createMcpServer(config, createTokenStore({
 		subdomain: config.subdomain,
 		oauthClientId: config.oauthClientId
-	}).getToken));
+	}, logger).getToken, logger), logger);
 };
 main().catch((error) => {
 	console.error("Fatal error:", error);