@fruggr/zendesk-mcp-server 2.17.2 → 2.19.0

package/dist/index.js

@@ -281,7 +281,6 @@ const startBrowserAuth = (config, logger = silentLogger) => {
 		});
 		const requestedPort = config.callbackPort ?? 27439;
 		const onStartError = (err) => {
-			clearTimeout(authTimeout);
 			const code = err.code;
 			logger.error("oauth_callback_listen_failed", {
 				port: requestedPort,
@@ -812,26 +811,195 @@ const loadConfig = (argv = process.argv.slice(2)) => {
 	});
 };
 //#endregion
+//#region src/client/retry.ts
+const MAX_ATTEMPTS = 3;
+const BASE_DELAY_MS = 250;
+const MAX_DELAY_MS = 4e3;
+const REQUEST_TIMEOUT_MS = 3e4;
+const TRANSFER_TIMEOUT_MS = 12e4;
+/**
+* A deadline for one attempt. The abort surfaces as a `TimeoutError` whose `code`
+* is numeric, not a syscall string, so it classifies as `unknown`: a GET is
+* retried, a write is not — the request may have arrived before the deadline.
+*/
+const deadlineSignal = (timeoutMs) => AbortSignal.timeout(timeoutMs);
+const MAX_RETRY_AFTER_MS = 5e3;
+const POLICIES = {
+	GET: {
+		network: "any",
+		serverErrors: true
+	},
+	DELETE: {
+		network: "pre-send",
+		serverErrors: false
+	},
+	POST: {
+		network: "pre-send",
+		serverErrors: false
+	},
+	PUT: {
+		network: "pre-send",
+		serverErrors: false
+	}
+};
+const DELAY_SECONDS = /^\d+$/;
+const HTTP_DATE_START = /^[A-Za-z]/;
+const NON_ASCII = /[^ -~]/g;
+const TOKEN_SEGMENT = /\/token\/[^/]+/;
+const URL_IN_TEXT = /[a-z][a-z0-9+.-]*:\/\/\S+/gi;
+const PRE_SEND_CODES = /* @__PURE__ */ new Set([
+	"ENOTFOUND",
+	"EAI_AGAIN",
+	"ECONNREFUSED",
+	"UND_ERR_CONNECT_TIMEOUT"
+]);
+const defaultRetryDeps = {
+	sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+	random: Math.random
+};
+/** Non-ASCII bytes break `node:http` headers, so client error text stays ASCII. */
+const toAscii = (text) => text.replace(NON_ASCII, "?");
+/**
+* Identifies the request without leaking a credential: uploads carry an upload
+* token in the query string, and an attachment `content_url` carries a download
+* token as a path segment (`/attachments/token/<token>/`).
+*/
+const describeTarget = (url) => {
+	const { origin, pathname } = new URL(url);
+	return `${origin}${pathname.replace(TOKEN_SEGMENT, "/token/[redacted]")}`;
+};
+/** First `code` in the cause chain, inspecting 5 levels so a cycle cannot hang. */
+const errorCode = (err) => {
+	let current = err;
+	for (let depth = 0; depth < 5 && current !== null && typeof current === "object"; depth += 1) {
+		const { code, cause } = current;
+		if (typeof code === "string") return code;
+		current = cause;
+	}
+};
+const classifyNetworkError = (err) => PRE_SEND_CODES.has(errorCode(err)) ? "pre-send" : "unknown";
+const UNINFORMATIVE_NAMES = /* @__PURE__ */ new Set(["Error", "TypeError"]);
+/**
+* The client refuses to replay a write that may have landed — but the caller is
+* an LLM whose reflex on a failed tool call is to try again, which would undo
+* that. So a failed write says whether it may have taken effect. ASCII only,
+* same rule as the rest of the message.
+*/
+const MAY_HAVE_APPLIED_NOTE = "The write may already have been applied. Check the current state before retrying, or you may duplicate it.";
+const NEVER_SENT_NOTE = "The request never reached Zendesk, so nothing was applied. Retrying is safe.";
+const REFUSED_NOTE = "Zendesk refused the request, so nothing was applied. Retrying is safe.";
+/** Only a write can be duplicated by a replay, so only a write carries a note. */
+const writeNote = (method, note) => method === "GET" ? "" : ` ${note}`;
+/**
+* A cause message can quote the URL it failed on — Node's `fetch` refuses a URL
+* carrying credentials by printing the whole thing, query string included — which
+* would smuggle back exactly what `describeTarget` drops. Same treatment for both,
+* so one function owns what a URL may look like in our output.
+*/
+const redactUrls = (text) => text.replace(URL_IN_TEXT, (found) => {
+	try {
+		return new URL(found).origin === "null" ? "[url]" : describeTarget(found);
+	} catch {
+		return "[url]";
+	}
+});
+const failureDetail = (cause) => {
+	if (!(cause instanceof Error)) return redactUrls(String(cause));
+	const message = redactUrls(cause.message);
+	const code = errorCode(cause);
+	if (code !== void 0) return `${code}: ${message}`;
+	return UNINFORMATIVE_NAMES.has(cause.name) ? message : `${cause.name}: ${message}`;
+};
+const networkErrorMessage = (method, target, attempts, cause) => {
+	const base = `Network error on ${method} ${target} after ${attempts === 1 ? "1 attempt" : `${attempts} attempts`}: ${failureDetail(cause)}`;
+	const note = classifyNetworkError(cause) === "pre-send" ? NEVER_SENT_NOTE : MAY_HAVE_APPLIED_NOTE;
+	return toAscii(method === "GET" ? base : `${base}.${writeNote(method, note)}`);
+};
+const createZendeskNetworkError = (method, target, attempts, cause) => Object.assign(new Error(networkErrorMessage(method, target, attempts, cause), { cause }), {
+	name: "ZendeskNetworkError",
+	method,
+	target,
+	attempts
+});
+/** Exponential backoff with equal jitter: half the window fixed, half random. */
+const computeBackoffMs = (attempt, random) => {
+	const window = Math.min(BASE_DELAY_MS * 2 ** (attempt - 1), MAX_DELAY_MS);
+	return Math.round(window / 2 + window * random() / 2);
+};
+/** `Retry-After` in ms — delay-seconds or HTTP-date. */
+const parseRetryAfter = (header, now = Date.now()) => {
+	if (header === null) return void 0;
+	const value = header.trim();
+	if (DELAY_SECONDS.test(value)) return Number(value) * 1e3;
+	if (!HTTP_DATE_START.test(value)) return void 0;
+	const date = Date.parse(value);
+	if (Number.isNaN(date)) return void 0;
+	return Math.max(0, date - now);
+};
+/**
+* How long to wait before replaying this response, or undefined to accept it.
+* `Retry-After` wins over backoff wherever it appears — Zendesk sends it on a 503
+* during maintenance as well as on a 429 — and a value past the cap means the
+* response is surfaced rather than parking the call for that long.
+*/
+const retryDelayFor = (response, policy, attempt, random) => {
+	if (!(response.status === 429 || response.status >= 500 && policy.serverErrors)) return void 0;
+	const retryAfter = parseRetryAfter(response.headers.get("retry-after"));
+	if (retryAfter === void 0) return computeBackoffMs(attempt, random);
+	return retryAfter > MAX_RETRY_AFTER_MS ? void 0 : retryAfter;
+};
+/**
+* Runs `attempt` until it succeeds, hits a terminal outcome, or spends the
+* attempt budget. Returns the last response for the caller to inspect (a
+* non-ok status is still the caller's to turn into a `ZendeskApiError`), and
+* throws `ZendeskNetworkError` when no response was ever obtained.
+*/
+const fetchWithRetry = async (attempt, method, target, deps = defaultRetryDeps) => {
+	const policy = POLICIES[method];
+	for (let tries = 1;; tries += 1) {
+		const last = tries >= MAX_ATTEMPTS;
+		let response;
+		try {
+			response = await attempt();
+		} catch (err) {
+			const replayable = policy.network === "any" || classifyNetworkError(err) === policy.network;
+			if (last || !replayable) throw createZendeskNetworkError(method, target, tries, err);
+			await deps.sleep(computeBackoffMs(tries, deps.random));
+			continue;
+		}
+		if (last) return response;
+		const delayMs = retryDelayFor(response, policy, tries, deps.random);
+		if (delayMs === void 0) return response;
+		await response.text().catch(() => void 0);
+		await deps.sleep(delayMs);
+	}
+};
+//#endregion
 //#region src/client/zendesk-api.ts
 var ZendeskApiError = class ZendeskApiError extends Error {
 	status;
 	statusText;
 	body;
-	constructor(status, statusText, body) {
-		super(ZendeskApiError.buildMessage(status, statusText, body));
+	method;
+	constructor(status, statusText, body, method) {
+		super(ZendeskApiError.buildMessage(status, statusText, body, method));
 		this.status = status;
 		this.statusText = statusText;
 		this.body = body;
+		this.method = method;
 		this.name = "ZendeskApiError";
 	}
-	static buildMessage(status, statusText, body) {
+	static buildMessage(status, statusText, body, method) {
 		switch (status) {
 			case 401: return "Authentication failed. Your Zendesk token may be expired or invalid. Re-authenticate to get a new token.";
 			case 403: return "Permission denied. Your Zendesk account does not have access to this resource.";
 			case 404: return `Resource not found. Please verify the ID is correct. (${statusText})`;
 			case 422: return `Validation error: ${body}`;
-			case 429: return "Rate limit exceeded. Please wait before making more requests.";
-			default: return `Zendesk API error ${status}: ${statusText}. ${body}`;
+			case 429: return `Rate limit exceeded. Please wait before making more requests.${writeNote(method, REFUSED_NOTE)}`;
+			default: {
+				const message = `Zendesk API error ${status}: ${statusText}. ${body}`;
+				return status >= 500 ? `${message}${writeNote(method, MAY_HAVE_APPLIED_NOTE)}` : message;
+			}
 		}
 	}
 };
@@ -841,6 +1009,11 @@ const buildUrl = (base, path, params) => {
 	if (params) for (const [key, value] of Object.entries(params)) url.searchParams.set(key, value);
 	return url.toString();
 };
+const performFetch = (method, url, init, timeoutMs = REQUEST_TIMEOUT_MS) => fetchWithRetry(() => fetch(url, {
+	...init,
+	method,
+	signal: deadlineSignal(timeoutMs)
+}), method, describeTarget(url));
 const executeRequest = async (url, token, options = {}) => {
 	const { method = "GET", body } = options;
 	const headers = {
@@ -848,15 +1021,12 @@ const executeRequest = async (url, token, options = {}) => {
 		Accept: "application/json"
 	};
 	if (body) headers["Content-Type"] = "application/json";
-	const init = {
-		method,
-		headers
-	};
+	const init = { headers };
 	if (body) init.body = JSON.stringify(body);
-	const response = await fetch(url, init);
+	const response = await performFetch(method, url, init);
 	if (!response.ok) {
 		const responseBody = await response.text();
-		throw new ZendeskApiError(response.status, response.statusText, responseBody);
+		throw new ZendeskApiError(response.status, response.statusText, responseBody, method);
 	}
 	if (response.status === 204) return {};
 	return response.json();
@@ -905,10 +1075,10 @@ const fetchZendeskBinary = async (subdomain, token, contentUrl) => {
 	const expectedHost = `${subdomain}.zendesk.com`;
 	const headers = {};
 	if (new URL(contentUrl).hostname === expectedHost) headers["Authorization"] = buildAuthHeader(token);
-	const response = await fetch(contentUrl, { headers });
+	const response = await performFetch("GET", contentUrl, { headers }, TRANSFER_TIMEOUT_MS);
 	if (!response.ok) {
 		const body = await response.text();
-		throw new ZendeskApiError(response.status, response.statusText, body);
+		throw new ZendeskApiError(response.status, response.statusText, body, "GET");
 	}
 	const contentType = response.headers.get("content-type") ?? "application/octet-stream";
 	const arrayBuffer = await response.arrayBuffer();
@@ -921,30 +1091,28 @@ const zendeskUpload = async (subdomain, token, filename, data, contentType, uplo
 	const params = { filename };
 	if (uploadToken) params["token"] = uploadToken;
 	const url = buildUrl(getBaseUrl(subdomain), "/uploads", params);
-	const response = await fetch(url, {
-		method: "POST",
+	const response = await performFetch("POST", url, {
 		headers: {
 			Authorization: buildAuthHeader(token),
 			"Content-Type": contentType
 		},
 		body: data
-	});
+	}, TRANSFER_TIMEOUT_MS);
 	if (!response.ok) {
 		const responseBody = await response.text();
-		throw new ZendeskApiError(response.status, response.statusText, responseBody);
+		throw new ZendeskApiError(response.status, response.statusText, responseBody, "POST");
 	}
 	return response.json();
 };
 const helpCenterUpload = async (subdomain, token, path, formData) => {
 	const url = buildUrl(getHelpCenterBaseUrl(subdomain), path);
-	const response = await fetch(url, {
-		method: "POST",
+	const response = await performFetch("POST", url, {
 		headers: { Authorization: buildAuthHeader(token) },
 		body: formData
-	});
+	}, TRANSFER_TIMEOUT_MS);
 	if (!response.ok) {
 		const responseBody = await response.text();
-		throw new ZendeskApiError(response.status, response.statusText, responseBody);
+		throw new ZendeskApiError(response.status, response.statusText, responseBody, "POST");
 	}
 	return response.json();
 };
@@ -4375,6 +4543,10 @@ const registerReloadTool = (server, reload, logger = silentLogger) => {
 * `reload_tools` tool that hot-reloads edited tool code on demand. stdio only —
 * HTTP builds a per-session server per request, so there is no long-lived
 * server to hot-swap.
+*
+* Returns the running server so the caller can close it on shutdown: dev mode
+* runs over the same stdio transport as normal mode and must exit the same way
+* when the client disconnects.
 */
 /* v8 ignore start -- runtime bootstrap: binds the reload tool to a real stdio
 transport; the reload machinery it wires up is covered by dev-reload.test.ts */
@@ -4383,6 +4555,7 @@ const startDevServer = async (config, getToken, logger = silentLogger, onUnautho
 	registerReloadTool(server, reload, logger);
 	await startStdioTransport(server, logger);
 	logger.info("dev_mode_enabled");
+	return server;
 };
 /* v8 ignore stop */
 //#endregion
@@ -4593,8 +4766,10 @@ const readJsonBody = (req, maxBodyBytes) => new Promise((resolve) => {
 const respondBodyError = (req, res, failure) => {
 	const headers = failure.status === 413 ? { Connection: "close" } : {};
 	sendJsonRpcError(res, failure.status, failure.rpcCode, failure.message, headers);
-	if (failure.status === 413) if (res.writableFinished) req.destroy();
-	else res.once("finish", () => req.destroy());
+	if (failure.status === 413) {
+		if (res.writableFinished) req.destroy();
+		else res.once("finish", () => req.destroy());
+	}
 };
 const SESSION_IDLE_TIMEOUT_MS = 18e5;
 const SESSION_SWEEP_INTERVAL_MS = 6e4;
@@ -4736,27 +4911,125 @@ const startHttpTransport = async (config, logger = silentLogger, options = {}) =
 	};
 };
 //#endregion
+//#region src/utils/shutdown.ts
+/**
+* How long a shutdown may take before the watchdog forces the exit.
+*
+* Generous enough for `server.close()` and an HTTP session drain, short enough
+* to stay inside the tightest common supervisor grace — `docker stop` allows 10s
+* and Kubernetes 30s before their own SIGKILL (systemd is far laxer at 90s). A
+* process killed by its supervisor is exactly the unclean exit this removes.
+*/
+const SHUTDOWN_GRACE_MS = 3e3;
+/**
+* Adapt a `process` to a {@link ShutdownRuntime}. Takes the process as an
+* argument rather than closing over the global so the adapter itself is
+* testable — otherwise the one part of this module that touches the real
+* process would be the one part no test can reach.
+*/
+const createRuntime = (proc) => ({
+	on: (event, listener) => {
+		proc.on(event, listener);
+	},
+	stdin: { on: (event, listener) => {
+		proc.stdin.on(event, listener);
+	} },
+	exit: (code) => {
+		proc.exit(code);
+	},
+	setTimer: (fn, ms) => {
+		const timer = setTimeout(fn, ms);
+		return {
+			unref: () => void timer.unref(),
+			clear: () => clearTimeout(timer)
+		};
+	}
+});
+const defaultRuntime = createRuntime(process);
+/**
+* Install the process's one shutdown path and return its trigger.
+*
+* Registering a `SIGTERM` handler *removes* Node's default terminate, which
+* makes the exit our responsibility: a cleanup that stalls on an in-flight
+* request would otherwise leave a process SIGTERM cannot kill — the very
+* symptom this exists to remove. Hence the watchdog, which is load-bearing
+* rather than defensive, and the unconditional `exit` on every path.
+*
+* The exit is explicit rather than a drained event loop because the OAuth
+* callback server (`auth/browser-oauth.ts`) is a listening socket that is not
+* `unref()`'d: letting the loop drain would keep a disconnected session alive
+* for up to the 5-minute auth timeout.
+*/
+const installShutdown = (options) => {
+	const { cleanup, logger, watchStdin, graceMs = SHUTDOWN_GRACE_MS } = options;
+	const runtime = options.runtime ?? defaultRuntime;
+	let started = false;
+	let exited = false;
+	const exitOnce = (code) => {
+		if (exited) return;
+		exited = true;
+		runtime.exit(code);
+	};
+	const shutdown = async (reason) => {
+		if (started) return;
+		started = true;
+		logger.info("shutdown_started", { reason });
+		const watchdog = runtime.setTimer(() => {
+			logger.warn("shutdown_forced", { graceMs });
+			exitOnce(0);
+		}, graceMs);
+		watchdog.unref();
+		try {
+			await cleanup();
+			logger.info("shutdown_complete", { reason });
+		} catch (err) {
+			logger.warn("shutdown_cleanup_failed", { error: err instanceof Error ? err.message : String(err) });
+		} finally {
+			watchdog.clear();
+			exitOnce(0);
+		}
+	};
+	runtime.on("SIGINT", () => void shutdown("SIGINT"));
+	runtime.on("SIGTERM", () => void shutdown("SIGTERM"));
+	if (watchStdin) runtime.stdin.on("end", () => void shutdown("stdin_eof"));
+	return shutdown;
+};
+//#endregion
 //#region src/index.ts
 const buildStdioTokenStore = (config, logger) => createTokenStore({
 	subdomain: config.subdomain,
 	oauthClientId: config.oauthClientId,
 	callbackPort: config.callbackPort
 }, logger);
+const connectStdio = async (config, tokenStore, logger) => {
+	if (config.dev) return startDevServer(config, tokenStore.getToken, logger, tokenStore.invalidate);
+	const server = createMcpServer(config, tokenStore.getToken, logger, tokenStore.invalidate);
+	await startStdioTransport(server, logger);
+	return server;
+};
 const main = async () => {
 	const config = loadConfig();
 	const logger = createLogger(config.logLevel);
 	if (config.transport === "stdio") {
 		const tokenStore = buildStdioTokenStore(config, logger);
-		if (config.dev) {
-			await startDevServer(config, tokenStore.getToken, logger, tokenStore.invalidate);
-			return;
-		}
-		const server = createMcpServer(config, tokenStore.getToken, logger, tokenStore.invalidate);
-		await startStdioTransport(server, logger);
+		const server = await connectStdio(config, tokenStore, logger);
+		installShutdown({
+			watchStdin: true,
+			logger,
+			cleanup: async () => {
+				await server.close();
+				tokenStore.dispose();
+			}
+		});
 		return;
 	}
 	if (config.dev) logger.warn("dev_mode_ignored_http");
-	await startHttpTransport(config, logger);
+	const http = await startHttpTransport(config, logger);
+	installShutdown({
+		watchStdin: false,
+		logger,
+		cleanup: http.close
+	});
 };
 main().catch((error) => {
 	console.error("Fatal error:", error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fruggr/zendesk-mcp-server",
-  "version": "2.17.2",
+  "version": "2.19.0",
   "mcpName": "io.github.fruggr/zendesk-mcp-server",
   "description": "Deep Zendesk MCP server for your AI assistant: search, draft, update and translate Help Center articles and manage Support tickets end to end — comments, triage and image attachments.",
   "type": "module",
@@ -69,13 +69,13 @@
   "engines": {
     "node": ">=20"
   },
-  "packageManager": "pnpm@11.20.0+sha512.9a6f330a95b66446ea088faf1521405a8a01f07fde7124cc9958dfed52d4bb436737e65b08f85f37b46fcba375092558ac51262b816844b22f63406ed166bfee",
+  "packageManager": "pnpm@11.22.0+sha512.1ff870c4c6133dfd88fb2afc46dd13d47f09c9794b438c6fdb47ca98caf3bc16381ee0be93a091b8e3824cf01f889f46d7d9e20910fb0be1ab0fb5baa80dd621",
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.0",
     "cheerio": "1.2.0",
     "hast-util-to-html": "9.0.5",
     "hast-util-to-mdast": "10.1.2",
-    "open": "11.0.0",
+    "open": "11.0.1",
     "rehype-parse": "9.0.1",
     "rehype-raw": "7.0.0",
     "rehype-remark": "10.0.1",
@@ -88,15 +88,15 @@
     "zod": "4.4.3"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.7",
-    "@semantic-release/changelog": "^6.0.3",
+    "@biomejs/biome": "2.5.8",
+    "@semantic-release/changelog": "^7.0.0",
     "@semantic-release/exec": "^7.1.0",
-    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/git": "^11.0.0",
     "@semantic-release/github": "^12.0.6",
     "@semantic-release/npm": "^13.1.5",
     "@semantic-release/release-notes-generator": "^14.1.1",
-    "@stryker-mutator/core": "^9.6.1",
-    "@stryker-mutator/vitest-runner": "^9.6.1",
+    "@stryker-mutator/core": "^10.0.0",
+    "@stryker-mutator/vitest-runner": "^10.0.0",
     "@tsconfig/node20": "^20.1.9",
     "@tsconfig/strictest": "^2.0.8",
     "@types/hast": "^3.0.4",