npm - @fruggr/zendesk-mcp-server - Versions diffs - 2.16.0 → 2.17.0 - Mend

@fruggr/zendesk-mcp-server 2.16.0 → 2.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/dist/index.js CHANGED Viewed

@@ -47,14 +47,22 @@ const REDACTED_KEYS = /* @__PURE__ */ new Set([
 	"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;
+const redactValue = (value, path = /* @__PURE__ */ new WeakSet()) => {
+	if (typeof value === "function") return "[function]";
+	if (!value || typeof value !== "object") return value;
+	if (path.has(value)) return "[circular]";
+	path.add(value);
+	const out = Array.isArray(value) ? value.map((item) => redactValue(item, path)) : Object.fromEntries(Object.entries(value).map(([key, val]) => [key, isSensitive(key) ? "[REDACTED]" : redactValue(val, path)]));
+	path.delete(value);
+	return out;
+};
+const sanitise = (fields) => {
+	if (!fields) return {};
+	try {
+		return redactValue(fields);
+	} catch {
+		return { fields: "[unredactable]" };
 	}
-	return value;
 };
 const renderValue = (value) => {
 	if (typeof value === "string") return value;
@@ -82,8 +90,10 @@ const createLogger = (level) => {
 	let server;
 	const emit = (lvl, event, fields) => {
 		if (SEVERITY[lvl] < min) return;
-		const safe = fields ? redactValue(fields) : {};
-		console.error(formatLine(lvl, event, safe));
+		const safe = sanitise(fields);
+		try {
+			console.error(formatLine(lvl, event, safe));
+		} catch {}
 		if (server) try {
 			server.sendLoggingMessage({
 				level: MCP_LEVEL[lvl],
@@ -115,7 +125,8 @@ const positiveIntEnv = (name, fallback) => {
 	return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback;
 };
 const ARTICLE_RESOURCES_SCAN_MAX_PAGES = positiveIntEnv("ZENDESK_ARTICLE_RESOURCES_SCAN_MAX_PAGES", 20);
-const MAX_ATTACHMENT_BYTES = positiveIntEnv("ZENDESK_MAX_ATTACHMENT_BYTES", 5 * 1024 * 1024);
+const TRANSLATION_GAP_SCAN_MAX_NODES = positiveIntEnv("ZENDESK_TRANSLATION_GAP_SCAN_MAX_NODES", 60);
+const MAX_ATTACHMENT_BYTES = positiveIntEnv("ZENDESK_MAX_ATTACHMENT_BYTES", 5242880);
 const MAX_EMBEDDED_IMAGE_COUNT = positiveIntEnv("ZENDESK_MAX_EMBEDDED_IMAGES", 10);
 const MAX_COMMENT_PAGES = positiveIntEnv("ZENDESK_MAX_COMMENT_PAGES", 10);
 const REORDER_CONFIRM_THRESHOLD = positiveIntEnv("ZENDESK_REORDER_CONFIRM_THRESHOLD", 20);
@@ -127,7 +138,7 @@ const getOAuthUrls = (subdomain) => ({
 });
 //#endregion
 //#region src/auth/browser-oauth.ts
-const AUTH_TIMEOUT_MS = 300 * 1e3;
+const AUTH_TIMEOUT_MS = 3e5;
 /** Best-effort WSL detection: WSL kernels carry "microsoft" in /proc/version. */
 const detectWsl = () => {
 	if (process.platform !== "linux") return false;
@@ -154,6 +165,8 @@ const callbackPortInUseError = (port, cause) => Object.assign(/* @__PURE__ */ ne
 * 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 errorPage = (title, detail) => `<html><body><h1>${escapeHtml(title)}</h1>${detail === void 0 ? "" : `<p>${escapeHtml(detail)}</p>`}</body></html>`;
+const SUCCESS_PAGE = "<html><body><h1>Authentication successful!</h1><p>You can close this tab and return to your AI assistant.</p><p>This tab will auto-close in <span id=\"t\">10</span>s.</p><script>let n=10;const el=document.getElementById(\"t\");const i=setInterval(()=>{n--;el.textContent=n;if(n<=0){clearInterval(i);window.close();}},1000);<\/script></body></html>";
 const generateCodeVerifier = () => randomBytes(32).toString("base64url");
 const generateCodeChallenge = (verifier) => createHash("sha256").update(verifier).digest("base64url");
 /**
@@ -179,69 +192,92 @@ const startBrowserAuth = (config, logger = silentLogger) => {
 		});
 		let authTimeout;
 		let callbackServer;
-		callbackServer = createServer(async (req, res) => {
-			const url = new URL(req.url ?? "/", `http://localhost`);
-			if (url.pathname !== "/callback") {
-				res.writeHead(404);
-				res.end("Not found");
-				return;
+		const exchangeCodeForToken = async (code) => {
+			const callbackPort = callbackServer.address().port;
+			const tokenBody = new URLSearchParams({
+				grant_type: "authorization_code",
+				code,
+				client_id: oauthClientId,
+				redirect_uri: `http://localhost:${callbackPort}/callback`,
+				code_verifier: codeVerifier
+			});
+			const tokenResponse = await fetch(tokenUrl, {
+				method: "POST",
+				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 code = url.searchParams.get("code");
+			return await tokenResponse.json();
+		};
+		const finishRequest = (res, { status, html, outcome }) => {
+			res.writeHead(status, { "Content-Type": "text/html" });
+			res.end(html);
+			clearTimeout(authTimeout);
+			callbackServer.close();
+			if (outcome.ok) resolveToken(outcome.token);
+			else rejectToken(outcome.error);
+		};
+		const resolveCallback = async (url) => {
 			const error = url.searchParams.get("error");
+			const code = url.searchParams.get("code");
 			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>${escapeHtml(desc)}</p></body></html>`);
-				clearTimeout(authTimeout);
-				callbackServer.close();
-				rejectToken(/* @__PURE__ */ new Error(`OAuth error: ${desc}`));
-				return;
-			}
-			if (!code) {
-				res.writeHead(400, { "Content-Type": "text/html" });
-				res.end("<html><body><h1>Missing authorization code</h1></body></html>");
-				clearTimeout(authTimeout);
-				callbackServer.close();
-				rejectToken(/* @__PURE__ */ new Error("Missing authorization code in callback"));
-				return;
+				return {
+					status: 400,
+					html: errorPage("Authentication failed", desc),
+					outcome: {
+						ok: false,
+						error: /* @__PURE__ */ new Error(`OAuth error: ${desc}`)
+					}
+				};
 			}
-			try {
-				const callbackPort = callbackServer.address().port;
-				const tokenBody = new URLSearchParams({
-					grant_type: "authorization_code",
-					code,
-					client_id: oauthClientId,
-					redirect_uri: `http://localhost:${callbackPort}/callback`,
-					code_verifier: codeVerifier
-				});
-				const tokenResponse = await fetch(tokenUrl, {
-					method: "POST",
-					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}`);
+			if (!code) return {
+				status: 400,
+				html: errorPage("Missing authorization code"),
+				outcome: {
+					ok: false,
+					error: /* @__PURE__ */ new Error("Missing authorization code in callback")
 				}
-				const tokenData = await tokenResponse.json();
+			};
+			try {
+				const token = await exchangeCodeForToken(code);
 				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 your AI assistant.</p><p>This tab will auto-close in <span id=\"t\">10</span>s.</p><script>let n=10;const el=document.getElementById(\"t\");const i=setInterval(()=>{n--;el.textContent=n;if(n<=0){clearInterval(i);window.close();}},1000);<\/script></body></html>");
-				clearTimeout(authTimeout);
-				callbackServer.close();
-				resolveToken(tokenData);
+				return {
+					status: 200,
+					html: SUCCESS_PAGE,
+					outcome: {
+						ok: true,
+						token
+					}
+				};
 			} catch (err) {
-				res.writeHead(500, { "Content-Type": "text/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();
-				rejectToken(err);
+				const detail = err instanceof Error ? err.message : String(err);
+				return {
+					status: 500,
+					html: errorPage("Token exchange failed", detail),
+					outcome: {
+						ok: false,
+						error: err
+					}
+				};
+			}
+		};
+		callbackServer = createServer(async (req, res) => {
+			const url = new URL(req.url ?? "/", `http://localhost`);
+			if (url.pathname !== "/callback") {
+				res.writeHead(404);
+				res.end("Not found");
+				return;
 			}
+			finishRequest(res, await resolveCallback(url));
 		});
 		const requestedPort = config.callbackPort ?? 27439;
 		const onStartError = (err) => {
@@ -384,15 +420,20 @@ const isWindows = process.platform === "win32";
 * (`@fruggr/zendesk-mcp-server` → `fruggr` + `zendesk-mcp-server`) so the path is
 * vendor-namespaced and can't collide with another `zendesk-mcp-server`.
 */
+const SCOPED_PACKAGE_NAME = /^@([^/]+)\/(.+)$/;
 const appDirSegments = () => {
 	const { name } = readPackageInfo();
-	const scoped = /^@([^/]+)\/(.+)$/.exec(name);
+	const scoped = SCOPED_PACKAGE_NAME.exec(name);
 	return scoped?.[1] && scoped[2] ? [scoped[1], scoped[2]] : [name];
 };
 const configDir = () => {
 	const segments = appDirSegments();
-	if (isWindows) return join(process.env["APPDATA"] ?? join(homedir(), "AppData", "Roaming"), ...segments);
-	return join(process.env["XDG_CONFIG_HOME"] ?? join(homedir(), ".config"), ...segments);
+	if (isWindows) {
+		const base = process.env["APPDATA"] ?? join(homedir(), "AppData", "Roaming");
+		return join(base, ...segments);
+	}
+	const base = process.env["XDG_CONFIG_HOME"] ?? join(homedir(), ".config");
+	return join(base, ...segments);
 };
 const safeName = (subdomain) => subdomain.replace(/[^a-z0-9-]/gi, "_");
 /**
@@ -443,7 +484,7 @@ const clearToken = (path, logger = silentLogger) => {
 //#endregion
 //#region src/auth/token-store.ts
 const EXPIRY_SKEW_MS = 6e4;
-const SCHEDULED_REFRESH_MS = 14400 * 1e3;
+const SCHEDULED_REFRESH_MS = 144e5;
 const createAuthRequiredError = (authorizeUrl) => Object.assign(/* @__PURE__ */ new Error("Zendesk authentication required. A browser window should have opened for you to sign in. If it did not, open this URL in your browser, then retry your request:\n" + authorizeUrl), {
 	name: "AuthRequiredError",
 	authorizeUrl
@@ -522,20 +563,23 @@ const createTokenStore = (config, logger = silentLogger) => {
 			throw err;
 		});
 	};
+	const refreshIfPossible = async () => {
+		const current = token;
+		if (!current?.refreshToken) return void 0;
+		if (refreshing === void 0) refreshing = tryRefresh(current).finally(() => {
+			refreshing = void 0;
+		});
+		return refreshing;
+	};
 	const getToken = async () => {
-		if (refreshing) await refreshing;
+		if (refreshing !== void 0) await refreshing;
 		if (token && !needsRefresh(token)) {
 			logger.debug("oauth_token_cache_hit");
 			return token.accessToken;
 		}
-		if (token?.refreshToken) {
-			if (!refreshing) refreshing = tryRefresh(token).finally(() => {
-				refreshing = void 0;
-			});
-			const refreshed = await refreshing;
-			if (refreshed) return refreshed;
-		}
-		if (!starting) starting = beginAuth();
+		const refreshed = await refreshIfPossible();
+		if (refreshed) return refreshed;
+		if (starting === void 0) starting = beginAuth();
 		const url = authorizeUrl ?? await starting;
 		throw createAuthRequiredError(url);
 	};
@@ -657,76 +701,96 @@ const ConfigSchema = z.object({
 	corsOrigins: z.array(z.string().url().transform((value) => new URL(value).origin).refine((origin) => origin !== "null", { message: "CORS origin must be an http(s) URL with a host" })).default([]),
 	callbackPort: z.number().int().min(1).max(65535).optional()
 });
+const DIGITS_ONLY = /^\d+$/;
 const parsePort = (raw, label) => {
-	if (!/^\d+$/.test(raw)) throw new Error(`Invalid ${label} value. Expected an integer 0-65535.`);
+	if (!DIGITS_ONLY.test(raw)) throw new Error(`Invalid ${label} value. Expected an integer 0-65535.`);
 	return Number(raw);
 };
 const parsePortEnv = (raw, label) => raw === void 0 || raw === "" ? void 0 : parsePort(raw, label);
+const appendTo = (key) => (result, value) => {
+	const list = result[key] ?? [];
+	list.push(value);
+	result[key] = list;
+};
+const STANDALONE_FLAGS = /* @__PURE__ */ new Map([
+	["--read-only", (result) => {
+		result.readOnly = true;
+	}],
+	["--no-topology", (result) => {
+		result.topology = false;
+	}],
+	["--no-promoted-articles", (result) => {
+		result.promotedArticles = false;
+	}],
+	["--dev", (result) => {
+		result.dev = true;
+	}]
+]);
+const VALUED_FLAGS = /* @__PURE__ */ new Map([
+	["--mode", (result, value) => {
+		result.mode = value;
+	}],
+	["--hc-resource-scheme", (result, value) => {
+		result.hcResourceScheme = value;
+	}],
+	["--log-level", (result, value) => {
+		result.logLevel = value;
+	}],
+	["--transport", (result, value) => {
+		result.transport = value;
+	}],
+	["--host", (result, value) => {
+		result.host = value;
+	}],
+	["--public-url", (result, value) => {
+		result.publicUrl = value;
+	}],
+	["--port", (result, value) => {
+		result.port = parsePort(value, "--port");
+	}],
+	["--callback-port", (result, value) => {
+		result.callbackPort = parsePort(value, "--callback-port");
+	}],
+	["--namespace", appendTo("namespaces")],
+	["--tool", appendTo("tools")],
+	["--cors-origin", appendTo("corsOrigins")]
+]);
 const parseCliArgs = (args) => {
 	const result = {};
-	let positionalIndex = 0;
 	for (let i = 0; i < args.length; i++) {
 		const arg = args[i];
 		if (arg === void 0) continue;
+		const standalone = STANDALONE_FLAGS.get(arg);
+		if (standalone) {
+			standalone(result);
+			continue;
+		}
+		const valued = VALUED_FLAGS.get(arg);
 		const next = args[i + 1];
-		if (arg === "--mode" && next) {
-			result.mode = next;
-			i++;
-		} else if (arg === "--read-only") result.readOnly = true;
-		else if (arg === "--no-topology") result.topology = false;
-		else if (arg === "--no-promoted-articles") result.promotedArticles = false;
-		else if (arg === "--hc-resource-scheme" && next) {
-			result.hcResourceScheme = next;
-			i++;
-		} else if (arg === "--dev") result.dev = true;
-		else if (arg === "--namespace" && next) {
-			result.namespaces = result.namespaces ?? [];
-			result.namespaces.push(next);
-			i++;
-		} else if (arg === "--tool" && next) {
-			result.tools = result.tools ?? [];
-			result.tools.push(next);
-			i++;
-		} else if (arg === "--log-level" && next) {
-			result.logLevel = next;
+		if (valued && next) {
+			valued(result, next);
 			i++;
-		} else if (arg === "--transport" && next) {
-			result.transport = next;
-			i++;
-		} else if (arg === "--host" && next) {
-			result.host = next;
-			i++;
-		} else if (arg === "--port" && next) {
-			result.port = parsePort(next, "--port");
-			i++;
-		} else if (arg === "--public-url" && next) {
-			result.publicUrl = next;
-			i++;
-		} else if (arg === "--cors-origin" && next) {
-			result.corsOrigins = result.corsOrigins ?? [];
-			result.corsOrigins.push(next);
-			i++;
-		} else if (arg === "--callback-port" && next) {
-			result.callbackPort = parsePort(next, "--callback-port");
-			i++;
-		} else if (!arg.startsWith("-") && positionalIndex === 0) {
-			result.subdomain = arg;
-			positionalIndex++;
+			continue;
 		}
+		if (!arg.startsWith("-") && result.subdomain === void 0) result.subdomain = arg;
 	}
 	return result;
 };
+const resolveTransportSettings = (cli) => {
+	const corsFromEnv = (process.env["CORS_ORIGIN"] ?? "").split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+	return {
+		transport: cli.transport ?? process.env["TRANSPORT"] ?? "stdio",
+		host: cli.host ?? process.env["HOST"] ?? "0.0.0.0",
+		port: cli.port ?? parsePortEnv(process.env["PORT"], "PORT") ?? 3e3,
+		publicUrl: cli.publicUrl ?? process.env["PUBLIC_URL"],
+		corsOrigins: [...cli.corsOrigins ?? [], ...corsFromEnv]
+	};
+};
 const loadConfig = (argv = process.argv.slice(2)) => {
 	const cli = parseCliArgs(argv);
 	const subdomain = cli.subdomain ?? process.env["ZENDESK_SUBDOMAIN"] ?? "";
 	const oauthClientId = process.env["ZENDESK_OAUTH_CLIENT_ID"] ?? (subdomain ? `${subdomain}_zendesk` : "");
 	const mode = cli.tools?.length ? "all" : cli.mode ?? "namespace";
-	const transport = cli.transport ?? process.env["TRANSPORT"] ?? "stdio";
-	const host = cli.host ?? process.env["HOST"] ?? "0.0.0.0";
-	const port = cli.port ?? parsePortEnv(process.env["PORT"], "PORT") ?? 3e3;
-	const publicUrl = cli.publicUrl ?? process.env["PUBLIC_URL"];
-	const corsFromEnv = (process.env["CORS_ORIGIN"] ?? "").split(",").map((s) => s.trim()).filter((s) => s.length > 0);
-	const corsOrigins = [...cli.corsOrigins ?? [], ...corsFromEnv];
 	const callbackPort = cli.callbackPort ?? parsePortEnv(process.env["ZENDESK_OAUTH_CALLBACK_PORT"], "ZENDESK_OAUTH_CALLBACK_PORT");
 	const hcResourceScheme = cli.hcResourceScheme ?? (process.env["HC_RESOURCE_SCHEME"] || void 0);
 	return ConfigSchema.parse({
@@ -741,12 +805,8 @@ const loadConfig = (argv = process.argv.slice(2)) => {
 		promotedArticles: cli.promotedArticles ?? true,
 		hcResourceScheme,
 		dev: cli.dev ?? false,
-		transport,
-		host,
-		port,
-		publicUrl,
-		corsOrigins,
-		callbackPort
+		callbackPort,
+		...resolveTransportSettings(cli)
 	});
 };
 //#endregion
@@ -893,10 +953,11 @@ const HEADING_LEVELS = /* @__PURE__ */ new Set([
 	"h2",
 	"h3"
 ]);
+const WHITESPACE_RUN = /\s+/;
 const countWords = (text) => {
 	const trimmed = text.trim();
 	if (!trimmed) return 0;
-	return trimmed.split(/\s+/).length;
+	return trimmed.split(WHITESPACE_RUN).length;
 };
 const textOf = (html) => {
 	if (!html) return "";
@@ -1000,7 +1061,11 @@ const formatTicket = (ticket) => [
 	`- **Created**: ${ticket.created_at} | **Updated**: ${ticket.updated_at}`,
 	ticket.description ? `\n${ticket.description}` : ""
 ].filter(Boolean).join("\n");
-const formatConditionValue = (value) => value === null || value === void 0 ? "" : typeof value === "object" ? JSON.stringify(value) : String(value);
+const formatConditionValue = (value) => {
+	if (value === null || value === void 0) return "";
+	if (typeof value === "object") return JSON.stringify(value);
+	return String(value);
+};
 const formatSlaPolicy = (policy) => {
 	const conditions = [...policy.filter.all.map((c) => `all: ${c.field} ${c.operator} ${formatConditionValue(c.value)}`.trim()), ...policy.filter.any.map((c) => `any: ${c.field} ${c.operator} ${formatConditionValue(c.value)}`.trim())];
 	const targets = policy.policy_metrics.map((m) => `  - ${m.priority} / ${m.metric}: ${m.target} min${m.business_hours ? " (business)" : ""}`);
@@ -1199,6 +1264,13 @@ const formatTranslation = (translation) => [
 	"",
 	translation.body
 ].join("\n");
+const formatNodeTranslationSummary = (translation) => [
+	`## Translation: ${translation.locale} (${translation.id})`,
+	`- **Name**: ${translation.title}`,
+	`- **Description**: ${translation.body ? "set" : "empty"}`,
+	`- **Draft**: ${translation.draft}`,
+	`- **Updated**: ${translation.updated_at}`
+].join("\n");
 const formatCategory = (category) => `- **${category.name}** (${category.id}) — ${category.description || "No description"}`;
 const formatSection = (section) => `- **${section.name}** (${section.id}) — Category: ${section.category_id} — ${section.description || "No description"}`;
 const formatView = (view, count) => {
@@ -1299,12 +1371,14 @@ const fetchPromotedArticles = async (subdomain, token, maxPages = ARTICLE_RESOUR
 * character limit. Reuses the same formatting as the `get_article` tool.
 */
 const fetchArticleMarkdown = async (subdomain, token, id, locale) => {
-	const { article } = await helpCenterGet(subdomain, token, locale ? `/${locale}/articles/${id}` : `/articles/${id}`);
-	return truncateIfNeeded([
+	const path = locale ? `/${locale}/articles/${id}` : `/articles/${id}`;
+	const { article } = await helpCenterGet(subdomain, token, path);
+	const text = [
 		formatArticleSummary(article),
 		"",
 		htmlToMarkdown(article.body)
-	].join("\n"));
+	].join("\n");
+	return truncateIfNeeded(text);
 };
 /**
 * Build an article-resources provider. `listPromoted` holds a memoized-promise
@@ -1493,20 +1567,20 @@ const fetchTopology = async (subdomain, token) => {
 		currentUser: meRes.user
 	};
 };
-const renderTree = (data) => {
-	if (data.categoriesHasMore || data.sectionsHasMore) {
-		const reasons = [];
-		if (data.categoriesHasMore) reasons.push(`more than 100 categories`);
-		if (data.sectionsHasMore) reasons.push(`more than 100 sections`);
-		return [
-			`Large Help Center (${reasons.join(" and ")}) — the full tree is omitted to stay concise.`,
-			data.categoriesHasMore ? "Categories (partial list):" : "Categories:",
-			...data.categories.map(formatCategory),
-			"",
-			...data.categoriesHasMore ? ["Use the `list_categories` tool to enumerate all categories."] : [],
-			"Use the `list_sections` tool (filtered by `category_id`) to enumerate sections under a category."
-		];
-	}
+const renderOversizedTreeNotice = (data) => {
+	const reasons = [];
+	if (data.categoriesHasMore) reasons.push(`more than 100 categories`);
+	if (data.sectionsHasMore) reasons.push(`more than 100 sections`);
+	return [
+		`Large Help Center (${reasons.join(" and ")}) — the full tree is omitted to stay concise.`,
+		data.categoriesHasMore ? "Categories (partial list):" : "Categories:",
+		...data.categories.map(formatCategory),
+		"",
+		...data.categoriesHasMore ? ["Use the `list_categories` tool to enumerate all categories."] : [],
+		"Use the `list_sections` tool (filtered by `category_id`) to enumerate sections under a category."
+	];
+};
+const renderCategoryTree = (data) => {
 	const byCategory = /* @__PURE__ */ new Map();
 	for (const section of data.sections) {
 		const list = byCategory.get(section.category_id) ?? [];
@@ -1520,6 +1594,7 @@ const renderTree = (data) => {
 	}
 	return lines.length ? lines : ["_(no categories)_"];
 };
+const renderTree = (data) => data.categoriesHasMore || data.sectionsHasMore ? renderOversizedTreeNotice(data) : renderCategoryTree(data);
 /**
 * Render an admin-gated section as one of three states so the LLM never mistakes
 * "you can't see this" for "there are none": the formatted list, `_(none)_` when
@@ -1531,7 +1606,7 @@ const renderAdminSection = (items, denied, deniedNote) => {
 };
 /** Render the topology as a compact Markdown document for the LLM context. */
 const formatTopology = (data) => {
-	return truncateIfNeeded([
+	const text = [
 		`# Zendesk Help Center topology — ${data.subdomain}`,
 		"",
 		`**Your access**: ${data.currentUser.name} (id ${data.currentUser.id}), role "${data.currentUser.role}".`,
@@ -1548,7 +1623,8 @@ const formatTopology = (data) => {
 		"",
 		"## Permission groups",
 		...renderAdminSection(data.permissionGroups.map(formatPermissionGroup), data.permissionGroupsDenied, "_Unavailable: listing permission groups requires Guide-admin / Help Center manager rights, which this token lacks (HTTP 403). To create or edit an article, reuse the permission_group_id of an existing article (get_article)._")
-	].join("\n"));
+	].join("\n");
+	return truncateIfNeeded(text);
 };
 /**
 * Build a topology provider holding a memoized-promise cache (TTL
@@ -1676,6 +1752,117 @@ const isPlacedAsRequested = (effectiveAfter, movedId, target, referenceId) => {
 //#region src/tools/help-center.ts
 const ARTICLE_ID_DESC = "Article ID — the numeric id of the Help Center article. Obtain it from list_articles or search_articles.";
 const listTranslations = (subdomain, token, articleId) => helpCenterGet(subdomain, token, `/articles/${articleId}/translations`).then((res) => res.translations);
+const NODE_LABEL = {
+	sections: "section",
+	categories: "category"
+};
+const listNodeTranslations = (subdomain, token, kind, nodeId, locale) => helpCenterGet(subdomain, token, `/${kind}/${nodeId}/translations`, locale ? { locales: locale.toLowerCase() } : void 0).then((res) => res.translations ?? []);
+const findTranslation = (translations, locale) => {
+	const wanted = locale.toLowerCase();
+	return translations.find((t) => t.locale.toLowerCase() === wanted);
+};
+/**
+* Create-or-update a section/category translation in one call. The POST-vs-PUT
+* probe spares the caller a listing round-trip, or the 400 a duplicate POST
+* returns. Only the fields passed are sent on update, so omitting `description`
+* never blanks it and omitting `draft` never (un)publishes by accident.
+*/
+const upsertNodeTranslation = async (subdomain, token, kind, nodeId, input) => {
+	const { locale, name, description, draft } = input;
+	const existing = findTranslation(await listNodeTranslations(subdomain, token, kind, nodeId, locale), locale);
+	if (!existing) {
+		if (name === void 0) throw new Error(`${NODE_LABEL[kind]} #${nodeId} has no "${locale}" translation yet, so one has to be created and "name" is required. Pass the localized name, or call list_${NODE_LABEL[kind]}_translations to see which locales already exist.`);
+		const { translation } = await helpCenterPost(subdomain, token, `/${kind}/${nodeId}/translations`, { translation: {
+			locale,
+			title: name,
+			body: description ?? "",
+			draft: draft ?? false
+		} });
+		return {
+			translation,
+			created: true
+		};
+	}
+	const updates = {};
+	if (name !== void 0) updates["title"] = name;
+	if (description !== void 0) updates["body"] = description;
+	if (draft !== void 0) updates["draft"] = draft;
+	if (Object.keys(updates).length === 0) throw new Error(`Nothing to write: ${NODE_LABEL[kind]} #${nodeId} already has a "${existing.locale}" translation, so pass at least one of "name", "description" or "draft" to change it (draft: false publishes it).`);
+	const { translation } = await helpCenterPut(subdomain, token, `/${kind}/${nodeId}/translations/${existing.locale}`, { translation: updates });
+	return {
+		translation,
+		created: false
+	};
+};
+const nodeTranslationWriteText = (kind, nodeId, translation, created) => [
+	`Translation ${created ? "created" : "updated"} for ${NODE_LABEL[kind]} #${nodeId} in "${translation.locale}" (${translation.draft ? "draft, not visible to end users" : "published"}).`,
+	"",
+	formatNodeTranslationSummary(translation)
+].join("\n");
+const GAP_REASON_TEXT = {
+	missing: "no translation",
+	draft: "draft translation (not published)"
+};
+const classifyGap = (node, translations, locale) => {
+	const translation = findTranslation(translations, locale);
+	if (!translation) return {
+		id: node.id,
+		name: node.name,
+		reason: "missing"
+	};
+	return translation.draft ? {
+		id: node.id,
+		name: node.name,
+		reason: "draft"
+	} : null;
+};
+const renderGapLines = (heading, gaps, scanned, found) => {
+	const header = `## ${heading} (${scanned} scanned)`;
+	if (gaps.length > 0) return [header, ...gaps.map((gap) => `- **${gap.name}** (${gap.id}) — ${GAP_REASON_TEXT[gap.reason]}`)];
+	if (scanned === 0) return [header, found === 0 ? "_(none to scan at this level)_" : `_(none scanned — the ${TRANSLATION_GAP_SCAN_MAX_NODES}-node cap was spent before this level; ${found} left unchecked, see the note below)_`];
+	return [header, "_(none — every one scanned has a published translation)_"];
+};
+const GAP_SCAN_WAVE_SIZE = 5;
+const probeInWaves = async (nodes, probe) => {
+	const gaps = [];
+	for (let i = 0; i < nodes.length; i += GAP_SCAN_WAVE_SIZE) {
+		const wave = await Promise.all(nodes.slice(i, i + GAP_SCAN_WAVE_SIZE).map(probe));
+		for (const gap of wave) if (gap !== null) gaps.push(gap);
+	}
+	return gaps;
+};
+const fetchGapCategories = async (subdomain, token, categoryId) => {
+	if (categoryId !== void 0) {
+		const { category } = await helpCenterGet(subdomain, token, `/categories/${categoryId}`);
+		return {
+			categories: [category],
+			hasMore: false
+		};
+	}
+	const response = await helpCenterGet(subdomain, token, "/categories", buildCursorParams(100, void 0));
+	const categories = response.categories ?? [];
+	return {
+		categories,
+		hasMore: extractPaginationMeta(response, categories.length).has_more
+	};
+};
+const renderGapReport = (report) => {
+	const { locale, categoryGaps, sectionGaps, scanned, found } = report;
+	const gapCount = categoryGaps.length + sectionGaps.length;
+	const capped = scanned.categories < found.categories || scanned.sections < found.sections;
+	return truncateIfNeeded([
+		`# Translation gaps — "${locale}"`,
+		"",
+		...report.activeLocales.some((l) => l.toLowerCase() === locale.toLowerCase()) ? [] : [`> ⚠ "${locale}" is not an active locale of this Help Center (active: ${report.activeLocales.join(", ")}), so everything below reads as untranslated. Check the spelling, or activate the language in Guide first.`, ""],
+		...renderGapLines("Categories", categoryGaps, scanned.categories, found.categories),
+		"",
+		...renderGapLines("Sections", sectionGaps, scanned.sections, found.sections),
+		"",
+		gapCount === 0 ? `No gaps: all ${scanned.categories} category/ies and ${scanned.sections} section(s) scanned have a published "${locale}" translation.` : `${gapCount} node(s) need a published "${locale}" translation. Fix a category with set_category_translation and a section with set_section_translation, passing draft: false to publish.`,
+		...capped ? ["", `_Note: the scan stopped at its ${TRANSLATION_GAP_SCAN_MAX_NODES}-node cap, covering ${scanned.categories}/${found.categories} categories and ${scanned.sections}/${found.sections} sections. The rest were not checked — narrow the scan with category_id, or raise ZENDESK_TRANSLATION_GAP_SCAN_MAX_NODES._`] : [],
+		...report.listingIncomplete ? ["", `_Note: this Help Center has more than 100 categories or sections, so only the first page of each was considered. Narrow the scan with category_id to audit the rest._`] : []
+	].join("\n"));
+};
 const largeArticleHint = (body, sectionCount) => {
 	if (body.length < 3e3 && sectionCount < 4) return null;
 	return [
@@ -1686,6 +1873,60 @@ const largeArticleHint = (body, sectionCount) => {
 	].join("\n");
 };
 const autoSortNotice = (sectionId, applied) => [applied === void 0 ? `Section #${sectionId} looks like it is sorted automatically, so a manual reorder would have no visible effect.` : `Wrote ${applied} article position(s), but the display order of section #${sectionId} did not change — the section is sorted automatically, so positions are ignored.`, "To order its articles manually: in Guide, open the section, choose \"Edit section\", set \"Order articles by\" to Manual, then re-run this tool."].join(" ");
+const renderFreshnessLine = (sourceUpdatedAt, targetUpdatedAt, targetLocale) => {
+	const srcMs = Date.parse(sourceUpdatedAt);
+	const tgtMs = Date.parse(targetUpdatedAt);
+	const label = `- **Freshness (target ${targetLocale})**`;
+	if (!Number.isFinite(srcMs) || !Number.isFinite(tgtMs)) return `${label}: unknown (could not compare edit timestamps).`;
+	if (srcMs <= tgtMs) return `${label}: up to date (source has not been edited since this translation).`;
+	const days = Math.floor((srcMs - tgtMs) / 864e5);
+	return `${label}: source was edited ${days >= 1 ? `${days} day(s)` : "less than a day"} after this translation → likely behind, review recommended.`;
+};
+const renderOutdatedLine = (translations, targetLocale) => {
+	const targetLocaleKey = targetLocale.toLowerCase();
+	const entry = translations.find((t) => t.locale.toLowerCase() === targetLocaleKey);
+	const label = `- **Zendesk outdated flag (target ${targetLocale})**`;
+	if (entry?.outdated === void 0) return `${label}: unknown.`;
+	if (entry.outdated) return `${label}: yes — explicitly marked out of date in Guide.`;
+	return `${label}: no (only set via Guide's own edit workflow; "no" does not by itself mean current — rely on Freshness above).`;
+};
+const renderStructureLine = (sourceSections, targetSections) => {
+	const sourceTags = sourceSections.map((s) => s.headingTag).join(",");
+	const targetTags = targetSections.map((s) => s.headingTag).join(",");
+	return sourceSections.length === targetSections.length && sourceTags === targetTags ? `- **Structure**: ${sourceSections.length} sections in both locales — aligned.` : `- **Structure**: ${sourceSections.length} source vs ${targetSections.length} target sections — MISMATCH; the per-index rows below may be misaligned.`;
+};
+const sectionRowStatus = (source, target) => {
+	if (!target) return "missing";
+	if (!source) return "extra";
+	return "ok";
+};
+const renderSectionRows = (sourceSections, targetSections) => {
+	const rows = ["| Idx | Heading | Status | Source words | Target words |", "| --- | --- | --- | --- | --- |"];
+	const maxLen = Math.max(sourceSections.length, targetSections.length);
+	for (let i = 0; i < maxLen; i += 1) {
+		const src = sourceSections[i];
+		const tgt = targetSections[i];
+		const heading = src?.heading ?? tgt?.heading ?? "";
+		const status = sectionRowStatus(src, tgt);
+		rows.push(`| ${i} | ${heading} | ${status} | ${src?.wordCount ?? 0} | ${tgt?.wordCount ?? 0} |`);
+	}
+	return rows;
+};
+const localePrefix = (locale) => locale ? `/${locale}` : "";
+const articleListPath = (sectionId, locale) => `${localePrefix(locale)}${sectionId ? `/sections/${sectionId}` : ""}/articles`;
+const sectionListPath = (categoryId, locale) => `${localePrefix(locale)}${categoryId ? `/categories/${categoryId}` : ""}/sections`;
+const scanCostNote = (truncated, pagesScanned, cost) => {
+	if (truncated) return `\n\n_Note: the scan hit its ${ARTICLE_RESOURCES_SCAN_MAX_PAGES}-page cap (${cost}), so promoted articles deeper in the catalog may be missing. This call is costly on this Help Center — avoid repeating it; raise ZENDESK_ARTICLE_RESOURCES_SCAN_MAX_PAGES to widen coverage._`;
+	if (pagesScanned > 1) return `\n\n_Note: this scan cost ${cost}; this tool performs a fresh scan every call (no caching), so avoid calling it again right away._`;
+	return "";
+};
+const needsReferenceArticle = (target) => target === "before" || target === "after";
+const assertReorderParamsCoherent = (articleId, target, referenceArticleId) => {
+	const needsReference = needsReferenceArticle(target);
+	if (needsReference && referenceArticleId === void 0) throw new Error(`target "${target}" requires reference_article_id (the article to move ${target}).`);
+	if (!needsReference && referenceArticleId !== void 0) throw new Error(`reference_article_id must be omitted when target is "${target}" (it only applies to "before"/"after").`);
+	if (referenceArticleId !== void 0 && referenceArticleId === articleId) throw new Error("reference_article_id must differ from article_id.");
+};
 const createHelpCenterTools = (ctx) => {
 	const { subdomain, getToken } = ctx;
 	const fetchSectionOrder = async (sectionId, locale, token) => {
@@ -1703,6 +1944,26 @@ const createHelpCenterTools = (ctx) => {
 		} while (cursor);
 		return order;
 	};
+	const assertReferenceInSection = async (effective, referenceArticleId, articleId, sectionId, token) => {
+		if (effective.some((a) => a.id === referenceArticleId)) return;
+		let detail = "was not found";
+		try {
+			const { article: ref } = await helpCenterGet(subdomain, token, `/articles/${referenceArticleId}`);
+			detail = `is in section #${ref.section_id}, not section #${sectionId}`;
+		} catch {}
+		throw new Error(`Reference article #${referenceArticleId} ${detail}. It must be in the same section (#${sectionId}) as article #${articleId}.`);
+	};
+	const applyPositionWrites = async (writes, articleId, token) => {
+		let applied = 0;
+		for (const write of writes) try {
+			await helpCenterPut(subdomain, token, `/articles/${write.id}`, { article: { position: write.position } });
+			applied += 1;
+		} catch (error) {
+			const reason = error instanceof Error ? error.message : String(error);
+			throw new Error(`Reorder of article #${articleId} failed after ${applied}/${writes.length} position write(s) (on article #${write.id}): ${reason} Positions are written absolutely, so re-running the identical call is safe and resumes where it stopped.`, { cause: error });
+		}
+		return applied;
+	};
 	return [
 		{
 			name: "search_articles",
@@ -1759,9 +2020,10 @@ const createHelpCenterTools = (ctx) => {
 				const path = locale ? `/${locale}/articles/${article_id}` : `/articles/${article_id}`;
 				const { article } = await helpCenterGet(subdomain, token, path);
 				const translations = await listTranslations(subdomain, token, article_id);
+				const text = (largeArticleHint(article.body, parseSections(article.body).length) ?? "") + formatArticle(article) + `\n\n**Available translations**: ${translations.map((t) => t.locale).join(", ")}`;
 				return { content: [{
 					type: "text",
-					text: truncateIfNeeded((largeArticleHint(article.body, parseSections(article.body).length) ?? "") + formatArticle(article) + `\n\n**Available translations**: ${translations.map((t) => t.locale).join(", ")}`)
+					text: truncateIfNeeded(text)
 				}] };
 			}
 		},
@@ -1785,7 +2047,7 @@ const createHelpCenterTools = (ctx) => {
 			handler: async (params) => {
 				const { locale, page_size, cursor } = params;
 				const token = await getToken();
-				const path = locale ? `/${locale}/categories` : "/categories";
+				const path = `${localePrefix(locale)}/categories`;
 				const response = await helpCenterGet(subdomain, token, path, buildCursorParams(page_size, cursor));
 				const categories = response.categories ?? [];
 				return { content: [{
@@ -1815,8 +2077,7 @@ const createHelpCenterTools = (ctx) => {
 			handler: async (params) => {
 				const { category_id, locale, page_size, cursor } = params;
 				const token = await getToken();
-				const path = category_id && locale ? `/${locale}/categories/${category_id}/sections` : category_id ? `/categories/${category_id}/sections` : locale ? `/${locale}/sections` : "/sections";
-				const response = await helpCenterGet(subdomain, token, path, buildCursorParams(page_size, cursor));
+				const response = await helpCenterGet(subdomain, token, sectionListPath(category_id, locale), buildCursorParams(page_size, cursor));
 				const sections = response.sections ?? [];
 				return { content: [{
 					type: "text",
@@ -1853,8 +2114,7 @@ const createHelpCenterTools = (ctx) => {
 			handler: async (params) => {
 				const { section_id, locale, page_size, cursor, sort_by, sort_order, include_translations } = params;
 				const token = await getToken();
-				const path = section_id && locale ? `/${locale}/sections/${section_id}/articles` : section_id ? `/sections/${section_id}/articles` : locale ? `/${locale}/articles` : "/articles";
-				const response = await helpCenterGet(subdomain, token, path, {
+				const response = await helpCenterGet(subdomain, token, articleListPath(section_id, locale), {
 					...buildCursorParams(page_size, cursor),
 					sort_by,
 					sort_order
@@ -1869,9 +2129,10 @@ const createHelpCenterTools = (ctx) => {
 					return `${formatArticleSummary(article)}\n- **Translations**: ${locales}`;
 				}));
 				const meta = extractPaginationMeta(response, articles.length);
+				const text = [meta.count ? `Results: ${meta.count}${meta.has_more ? ` | More available (cursor: ${meta.after_cursor})` : ""}` : "", ...formatted].filter(Boolean).join("\n\n");
 				return { content: [{
 					type: "text",
-					text: truncateIfNeeded([meta.count ? `Results: ${meta.count}${meta.has_more ? ` | More available (cursor: ${meta.after_cursor})` : ""}` : "", ...formatted].filter(Boolean).join("\n\n"))
+					text: truncateIfNeeded(text)
 				}] };
 			}
 		},
@@ -1894,9 +2155,10 @@ const createHelpCenterTools = (ctx) => {
 				const header = `Promoted (featured) articles: ${articles.length}`;
 				const body = articles.length ? articles.map(formatArticleSummary).join("\n\n") : "_No promoted articles found._";
 				const cost = `${pagesScanned} Zendesk API request${pagesScanned === 1 ? "" : "s"}`;
+				const note = scanCostNote(truncated, pagesScanned, cost);
 				return { content: [{
 					type: "text",
-					text: truncateIfNeeded(`${header}\n\n${body}${truncated ? `\n\n_Note: the scan hit its ${ARTICLE_RESOURCES_SCAN_MAX_PAGES}-page cap (${cost}), so promoted articles deeper in the catalog may be missing. This call is costly on this Help Center — avoid repeating it; raise ZENDESK_ARTICLE_RESOURCES_SCAN_MAX_PAGES to widen coverage._` : pagesScanned > 1 ? `\n\n_Note: this scan cost ${cost}; this tool performs a fresh scan every call (no caching), so avoid calling it again right away._` : ""}`)
+					text: truncateIfNeeded(`${header}\n\n${body}${note}`)
 				}] };
 			}
 		},
@@ -1916,9 +2178,10 @@ const createHelpCenterTools = (ctx) => {
 			handler: async (params) => {
 				const { article_id } = params;
 				const token = await getToken();
+				const translations = await listTranslations(subdomain, token, article_id);
 				return { content: [{
 					type: "text",
-					text: formatList(await listTranslations(subdomain, token, article_id), formatTranslationSummary)
+					text: formatList(translations, formatTranslationSummary)
 				}] };
 			}
 		},
@@ -1985,6 +2248,160 @@ const createHelpCenterTools = (ctx) => {
 				}] };
 			}
 		},
+		{
+			name: "list_section_translations",
+			namespace: "help_center",
+			readOnly: true,
+			title: "List Section Translations",
+			description: "List the translations of a Help Center section: for each locale, the localized name, whether a description is set, and whether the translation is published or still a draft. Reach for this when a section looks wrong in a locale, because list_sections with that locale cannot settle it: a section with no translation is omitted from it, while a section whose translation is an unpublished draft may still be listed there under the draft name — so appearing in that listing does not mean published, and the draft flag here is what decides. Fix either case with set_section_translation; to sweep every category and section at once, use find_translation_gaps.",
+			inputSchema: z.object({ section_id: z.number().int().describe("Section ID — the numeric id of the Help Center section. Obtain it from list_sections or the zendesk-hc://topology resource.") }),
+			annotations: {
+				readOnlyHint: true,
+				destructiveHint: false,
+				idempotentHint: true,
+				openWorldHint: true
+			},
+			handler: async (params) => {
+				const { section_id } = params;
+				const token = await getToken();
+				const translations = await listNodeTranslations(subdomain, token, "sections", section_id);
+				return { content: [{
+					type: "text",
+					text: formatList(translations, formatNodeTranslationSummary)
+				}] };
+			}
+		},
+		{
+			name: "list_category_translations",
+			namespace: "help_center",
+			readOnly: true,
+			title: "List Category Translations",
+			description: "List the translations of a Help Center category: for each locale, the localized name, whether a description is set, and whether the translation is published or still a draft. Reach for this when a category looks wrong in a locale, because list_categories with that locale cannot settle it: a category with no translation is omitted from it, while a category whose translation is an unpublished draft may still be listed there under the draft name — so appearing in that listing does not mean published, and the draft flag here is what decides. Fix either case with set_category_translation; to sweep every category and section at once, use find_translation_gaps.",
+			inputSchema: z.object({ category_id: z.number().int().describe("Category ID — the numeric id of the Help Center category. Obtain it from list_categories or the zendesk-hc://topology resource.") }),
+			annotations: {
+				readOnlyHint: true,
+				destructiveHint: false,
+				idempotentHint: true,
+				openWorldHint: true
+			},
+			handler: async (params) => {
+				const { category_id } = params;
+				const token = await getToken();
+				const translations = await listNodeTranslations(subdomain, token, "categories", category_id);
+				return { content: [{
+					type: "text",
+					text: formatList(translations, formatNodeTranslationSummary)
+				}] };
+			}
+		},
+		{
+			name: "find_translation_gaps",
+			namespace: "help_center",
+			readOnly: true,
+			title: "Find Help Center Translation Gaps",
+			description: "Audit the Help Center tree for a target locale and report every category and section that has no translation, or one that is still an unpublished draft. Use it before or after translating articles: an article published in a second locale is unreachable while its parent section only exists in the source locale. Listing sections in that locale cannot answer this — a node with no translation is simply absent, without saying why, and a node whose translation is an unpublished draft may still be listed under its draft name — so this audit reads the draft flag on each node instead of trusting that listing. Costs one extra request per node scanned, capped (the report says so when the cap bites) — pass category_id to narrow it. Fix what it reports with set_section_translation / set_category_translation.",
+			inputSchema: z.object({
+				locale: z.string().describe("Locale to audit, e.g. \"fr\" or \"de\" — usually a non-default active locale of the Help Center (zendesk-hc://topology lists them). A locale that is not active is reported as a warning, since every node would then look untranslated."),
+				category_id: z.number().int().optional().describe("Restrict the audit to this category and the sections it contains (id from list_categories). Omit to sweep the whole tree, which costs one request per category and per section.")
+			}),
+			annotations: {
+				readOnlyHint: true,
+				destructiveHint: false,
+				idempotentHint: true,
+				openWorldHint: true
+			},
+			handler: async (params) => {
+				const { locale, category_id } = params;
+				const token = await getToken();
+				const [locales, categoryScope, sectionsRes] = await Promise.all([
+					helpCenterGet(subdomain, token, "/locales"),
+					fetchGapCategories(subdomain, token, category_id),
+					helpCenterGet(subdomain, token, sectionListPath(category_id, void 0), buildCursorParams(100, void 0))
+				]);
+				const allCategories = categoryScope.categories;
+				const allSections = sectionsRes.sections ?? [];
+				const categories = allCategories.slice(0, TRANSLATION_GAP_SCAN_MAX_NODES);
+				const sections = allSections.slice(0, Math.max(0, TRANSLATION_GAP_SCAN_MAX_NODES - categories.length));
+				const categoryGaps = await probeInWaves(categories, async (category) => classifyGap(category, await listNodeTranslations(subdomain, token, "categories", category.id, locale), locale));
+				const sectionGaps = await probeInWaves(sections, async (section) => classifyGap(section, await listNodeTranslations(subdomain, token, "sections", section.id, locale), locale));
+				return { content: [{
+					type: "text",
+					text: renderGapReport({
+						locale,
+						activeLocales: locales.locales ?? [],
+						categoryGaps,
+						sectionGaps,
+						scanned: {
+							categories: categories.length,
+							sections: sections.length
+						},
+						found: {
+							categories: allCategories.length,
+							sections: allSections.length
+						},
+						listingIncomplete: categoryScope.hasMore || extractPaginationMeta(sectionsRes, allSections.length).has_more
+					})
+				}] };
+			}
+		},
+		{
+			name: "set_section_translation",
+			namespace: "help_center",
+			readOnly: false,
+			title: "Create or Update a Section Translation",
+			description: "Create or update the translation of a Help Center section in one locale, and return the resulting translation (locale, localized name, draft state). Creates the translation when the locale has none and updates it otherwise, so no listing call is needed first; only the fields you pass are written, which makes \"publish this draft\" a single draft: false. Use it to make a section reachable in a locale where its articles are already translated — a gap find_translation_gaps reports and list_sections cannot explain.",
+			inputSchema: z.object({
+				section_id: z.number().int().describe("Section ID — the numeric id of the section whose translation to write. Obtain it from list_sections, find_translation_gaps or the zendesk-hc://topology resource."),
+				locale: z.string().describe("Locale to write, e.g. \"fr\" or \"de\". Must be an active locale of the Help Center (zendesk-hc://topology lists them); list_section_translations shows which ones the section already has."),
+				name: z.string().min(1).optional().describe("Localized section name for this locale (sent as the API's translation `title`). Required when the locale has no translation yet; omit on an existing one to leave its name untouched, for instance when only publishing a draft."),
+				description: z.string().optional().describe("Localized section description for this locale (sent as the API's translation `body`). Omit to leave an existing description untouched; pass an empty string to clear it."),
+				draft: z.boolean().optional().describe("Publication state: false publishes the translation, making the section visible to end users in this locale; true keeps (or puts) it back as a draft. Defaults to false when creating; omit on an existing translation to leave its state unchanged.")
+			}),
+			annotations: {
+				readOnlyHint: false,
+				destructiveHint: true,
+				idempotentHint: true,
+				openWorldHint: true
+			},
+			handler: async (params) => {
+				const { section_id, ...input } = params;
+				const token = await getToken();
+				const { translation, created } = await upsertNodeTranslation(subdomain, token, "sections", section_id, input);
+				return { content: [{
+					type: "text",
+					text: nodeTranslationWriteText("sections", section_id, translation, created)
+				}] };
+			}
+		},
+		{
+			name: "set_category_translation",
+			namespace: "help_center",
+			readOnly: false,
+			title: "Create or Update a Category Translation",
+			description: "Create or update the translation of a Help Center category in one locale, and return the resulting translation (locale, localized name, draft state). Creates the translation when the locale has none and updates it otherwise, so no listing call is needed first; only the fields you pass are written, which makes \"publish this draft\" a single draft: false. Use it to make a category reachable in a locale where its sections or articles are already translated — a gap find_translation_gaps reports and list_categories cannot explain.",
+			inputSchema: z.object({
+				category_id: z.number().int().describe("Category ID — the numeric id of the category whose translation to write. Obtain it from list_categories, find_translation_gaps or the zendesk-hc://topology resource."),
+				locale: z.string().describe("Locale to write, e.g. \"fr\" or \"de\". Must be an active locale of the Help Center (zendesk-hc://topology lists them); list_category_translations shows which ones the category already has."),
+				name: z.string().min(1).optional().describe("Localized category name for this locale (sent as the API's translation `title`). Required when the locale has no translation yet; omit on an existing one to leave its name untouched, for instance when only publishing a draft."),
+				description: z.string().optional().describe("Localized category description for this locale (sent as the API's translation `body`). Omit to leave an existing description untouched; pass an empty string to clear it."),
+				draft: z.boolean().optional().describe("Publication state: false publishes the translation, making the category visible to end users in this locale; true keeps (or puts) it back as a draft. Defaults to false when creating; omit on an existing translation to leave its state unchanged.")
+			}),
+			annotations: {
+				readOnlyHint: false,
+				destructiveHint: true,
+				idempotentHint: true,
+				openWorldHint: true
+			},
+			handler: async (params) => {
+				const { category_id, ...input } = params;
+				const token = await getToken();
+				const { translation, created } = await upsertNodeTranslation(subdomain, token, "categories", category_id, input);
+				return { content: [{
+					type: "text",
+					text: nodeTranslationWriteText("categories", category_id, translation, created)
+				}] };
+			}
+		},
 		{
 			name: "list_permission_groups",
 			namespace: "help_center",
@@ -2108,25 +2525,17 @@ const createHelpCenterTools = (ctx) => {
 			},
 			handler: async (params) => {
 				const { article_id, target, reference_article_id, normalize = false, confirm = false } = params;
-				const needsReference = target === "before" || target === "after";
-				if (needsReference && reference_article_id === void 0) throw new Error(`target "${target}" requires reference_article_id (the article to move ${target}).`);
-				if (!needsReference && reference_article_id !== void 0) throw new Error(`reference_article_id must be omitted when target is "${target}" (it only applies to "before"/"after").`);
-				if (reference_article_id !== void 0 && reference_article_id === article_id) throw new Error("reference_article_id must differ from article_id.");
+				assertReorderParamsCoherent(article_id, target, reference_article_id);
+				const needsReference = needsReferenceArticle(target);
 				const token = await getToken();
 				const { article } = await helpCenterGet(subdomain, token, `/articles/${article_id}`);
 				const sectionId = article.section_id;
 				const locale = article.source_locale;
 				const effective = await fetchSectionOrder(sectionId, locale, token);
-				if (needsReference && !effective.some((a) => a.id === reference_article_id)) {
-					let detail = "was not found";
-					try {
-						const { article: ref } = await helpCenterGet(subdomain, token, `/articles/${reference_article_id}`);
-						detail = `is in section #${ref.section_id}, not section #${sectionId}`;
-					} catch {}
-					throw new Error(`Reference article #${reference_article_id} ${detail}. It must be in the same section (#${sectionId}) as article #${article_id}.`);
-				}
+				if (reference_article_id !== void 0) await assertReferenceInSection(effective, reference_article_id, article_id, sectionId, token);
 				const targetLabel = needsReference ? `${target} article #${reference_article_id}` : target;
-				const writes = computePositionWrites(arrangeDesiredOrder(effective, article_id, target, reference_article_id), article_id, normalize);
+				const desired = arrangeDesiredOrder(effective, article_id, target, reference_article_id);
+				const writes = computePositionWrites(desired, article_id, normalize);
 				if (writes.length === 0) return { content: [{
 					type: "text",
 					text: `Article #${article_id} is already positioned ${targetLabel} in section #${sectionId}. No changes made.`
@@ -2139,15 +2548,9 @@ const createHelpCenterTools = (ctx) => {
 					type: "text",
 					text: `Reordering article #${article_id} to ${targetLabel} would reposition ${writes.length} articles in section #${sectionId}, above the safety threshold of ${REORDER_CONFIRM_THRESHOLD}. Re-run with confirm: true to proceed.`
 				}] };
-				let applied = 0;
-				for (const write of writes) try {
-					await helpCenterPut(subdomain, token, `/articles/${write.id}`, { article: { position: write.position } });
-					applied += 1;
-				} catch (error) {
-					const reason = error instanceof Error ? error.message : String(error);
-					throw new Error(`Reorder of article #${article_id} failed after ${applied}/${writes.length} position write(s) (on article #${write.id}): ${reason} Positions are written absolutely, so re-running the identical call is safe and resumes where it stopped.`, { cause: error });
-				}
-				if (!isPlacedAsRequested(await fetchSectionOrder(sectionId, locale, token), article_id, target, reference_article_id)) return { content: [{
+				const applied = await applyPositionWrites(writes, article_id, token);
+				const after = await fetchSectionOrder(sectionId, locale, token);
+				if (!isPlacedAsRequested(after, article_id, target, reference_article_id)) return { content: [{
 					type: "text",
 					text: autoSortNotice(sectionId, applied)
 				}] };
@@ -2258,9 +2661,10 @@ const createHelpCenterTools = (ctx) => {
 			},
 			handler: async () => {
 				const token = await getToken();
+				const response = await helpCenterGet(subdomain, token, "/articles/labels");
 				return { content: [{
 					type: "text",
-					text: formatList((await helpCenterGet(subdomain, token, "/articles/labels")).labels ?? [], formatLabel)
+					text: formatList(response.labels ?? [], formatLabel)
 				}] };
 			}
 		},
@@ -2386,14 +2790,15 @@ const createHelpCenterTools = (ctx) => {
 				const section = sections[section_index];
 				if (!section) throw new Error(`Section index ${section_index} not found. Article has ${sections.length} section(s) (0-${Math.max(0, sections.length - 1)}).`);
 				const content = format === "markdown" ? htmlToMarkdown(section.html) : section.html;
+				const text = [
+					section.headingTag ? `## [${section.index}] ${section.headingTag}: ${section.heading}` : `## [${section.index}] ${section.heading}`,
+					`_Locale: ${locale} | Words: ${section.wordCount} | Format: ${format}_`,
+					"",
+					content
+				].join("\n");
 				return { content: [{
 					type: "text",
-					text: truncateIfNeeded([
-						section.headingTag ? `## [${section.index}] ${section.headingTag}: ${section.heading}` : `## [${section.index}] ${section.heading}`,
-						`_Locale: ${locale} | Words: ${section.wordCount} | Format: ${format}_`,
-						"",
-						content
-					].join("\n"))
+					text: truncateIfNeeded(text)
 				}] };
 			}
 		},
@@ -2458,40 +2863,10 @@ const createHelpCenterTools = (ctx) => {
 				]);
 				const sourceSections = parseSections(sourceRes.translation.body);
 				const targetSections = parseSections(targetRes.translation.body);
-				const maxLen = Math.max(sourceSections.length, targetSections.length);
-				const sourceUpdated = sourceRes.translation.updated_at;
-				const targetUpdated = targetRes.translation.updated_at;
-				const srcMs = Date.parse(sourceUpdated);
-				const tgtMs = Date.parse(targetUpdated);
-				const comparable = Number.isFinite(srcMs) && Number.isFinite(tgtMs);
-				let freshnessLine;
-				if (comparable && srcMs > tgtMs) {
-					const days = Math.floor((srcMs - tgtMs) / 864e5);
-					freshnessLine = `- **Freshness (target ${target_locale})**: source was edited ${days >= 1 ? `${days} day(s)` : "less than a day"} after this translation → likely behind, review recommended.`;
-				} else if (comparable) freshnessLine = `- **Freshness (target ${target_locale})**: up to date (source has not been edited since this translation).`;
-				else freshnessLine = `- **Freshness (target ${target_locale})**: unknown (could not compare edit timestamps).`;
-				const targetLocaleKey = target_locale.toLowerCase();
-				const targetListEntry = translations.find((t) => t.locale.toLowerCase() === targetLocaleKey);
-				const outdated = targetListEntry?.outdated === void 0 ? "unknown" : targetListEntry.outdated ? "yes" : "no";
-				const outdatedLine = outdated === "yes" ? `- **Zendesk outdated flag (target ${target_locale})**: yes — explicitly marked out of date in Guide.` : outdated === "no" ? `- **Zendesk outdated flag (target ${target_locale})**: no (only set via Guide's own edit workflow; "no" does not by itself mean current — rely on Freshness above).` : `- **Zendesk outdated flag (target ${target_locale})**: unknown.`;
-				const sourceTags = sourceSections.map((s) => s.headingTag).join(",");
-				const targetTags = targetSections.map((s) => s.headingTag).join(",");
-				const structureLine = sourceSections.length === targetSections.length && sourceTags === targetTags ? `- **Structure**: ${sourceSections.length} sections in both locales — aligned.` : `- **Structure**: ${sourceSections.length} source vs ${targetSections.length} target sections — MISMATCH; the per-index rows below may be misaligned.`;
-				const rows = [];
-				rows.push(`| Idx | Heading | Status | Source words | Target words |`);
-				rows.push(`| --- | --- | --- | --- | --- |`);
-				for (let i = 0; i < maxLen; i += 1) {
-					const src = sourceSections[i];
-					const tgt = targetSections[i];
-					const heading = src?.heading ?? tgt?.heading ?? "";
-					const sourceWords = src?.wordCount ?? 0;
-					const targetWords = tgt?.wordCount ?? 0;
-					let status;
-					if (!tgt) status = "missing";
-					else if (!src) status = "extra";
-					else status = "ok";
-					rows.push(`| ${i} | ${heading} | ${status} | ${sourceWords} | ${targetWords} |`);
-				}
+				const freshnessLine = renderFreshnessLine(sourceRes.translation.updated_at, targetRes.translation.updated_at, target_locale);
+				const outdatedLine = renderOutdatedLine(translations, target_locale);
+				const structureLine = renderStructureLine(sourceSections, targetSections);
+				const rows = renderSectionRows(sourceSections, targetSections);
 				return { content: [{
 					type: "text",
 					text: [
@@ -2500,7 +2875,7 @@ const createHelpCenterTools = (ctx) => {
 						freshnessLine,
 						outdatedLine,
 						structureLine,
-						`- **Updated**: source ${sourceUpdated} | target ${targetUpdated}`,
+						`- **Updated**: source ${sourceRes.translation.updated_at} | target ${targetRes.translation.updated_at}`,
 						`- **Target draft**: ${targetRes.translation.draft ? "yes" : "no"}`,
 						"",
 						"_Word counts are informational: a length difference between languages is normal, not a divergence._",
@@ -2587,15 +2962,18 @@ const createSearchTools = (ctx) => {
 			});
 			const results = response.results ?? [];
 			const meta = extractSearchPaginationMeta(response, per_page, page);
+			const header = `Total: ${meta.count} | Page ${page} (${results.length} results)${meta.has_more ? ` | Next page: ${meta.after_cursor}` : ""}`;
+			const body = results.map(formatSearchResult).join("\n\n");
 			return { content: [{
 				type: "text",
-				text: truncateIfNeeded([`Total: ${meta.count} | Page ${page} (${results.length} results)${meta.has_more ? ` | Next page: ${meta.after_cursor}` : ""}`, results.map(formatSearchResult).join("\n\n")].filter(Boolean).join("\n\n"))
+				text: truncateIfNeeded([header, body].filter(Boolean).join("\n\n"))
 			}] };
 		}
 	}];
 };
 //#endregion
 //#region src/tools/tickets.ts
+const MAX_ATTACHMENT_MB = Number.parseFloat((MAX_ATTACHMENT_BYTES / 1048576).toFixed(2));
 const formatReference = (attachment) => `**${attachment.file_name}** (id ${attachment.id}, ${attachment.content_type}, ${attachment.size} bytes) — ${attachment.content_url}`;
 const buildEmbeddedImageBlocks = async (subdomain, token, attachment, reference) => {
 	const { data, contentType } = await fetchZendeskBinary(subdomain, token, attachment.content_url);
@@ -2624,6 +3002,16 @@ const fetchAllTicketComments = async (subdomain, token, ticketId) => {
 	}
 	return all;
 };
+const fetchAttachmentsByIds = async (subdomain, token, ids) => {
+	const attachments = [];
+	for (const id of ids) try {
+		const { attachment } = await zendeskGet(subdomain, token, `/attachments/${id}`);
+		attachments.push(attachment);
+	} catch (error) {
+		if (!(error instanceof ZendeskApiError) || error.status !== 404) throw error;
+	}
+	return attachments;
+};
 const collectAttachmentBlocks = async (subdomain, token, attachments) => {
 	const blocks = [];
 	let embeddedCount = 0;
@@ -2637,7 +3025,7 @@ const collectAttachmentBlocks = async (subdomain, token, attachments) => {
 			continue;
 		}
 		let skipReason = null;
-		if (attachment.size > MAX_ATTACHMENT_BYTES) skipReason = `skipped: exceeds ${+(MAX_ATTACHMENT_BYTES / (1024 * 1024)).toFixed(2)} MB per-image limit`;
+		if (attachment.size > MAX_ATTACHMENT_BYTES) skipReason = `skipped: exceeds ${MAX_ATTACHMENT_MB} MB per-image limit`;
 		else if (embeddedCount >= MAX_EMBEDDED_IMAGE_COUNT) skipReason = `skipped: max ${MAX_EMBEDDED_IMAGE_COUNT} embedded images reached`;
 		if (skipReason) {
 			blocks.push({
@@ -2659,9 +3047,10 @@ const collectAttachmentBlocks = async (subdomain, token, attachments) => {
 	}
 	return blocks;
 };
+const ISO_DAY = /^\d{4}-\d{2}-\d{2}$/;
 const fetchTicketSla = async (subdomain, token, ticket) => {
 	const day = ticket.created_at.slice(0, 10);
-	if (!/^\d{4}-\d{2}-\d{2}$/.test(day)) return void 0;
+	if (!ISO_DAY.test(day)) return void 0;
 	const shiftDay = (offset) => {
 		const d = /* @__PURE__ */ new Date(`${day}T00:00:00Z`);
 		d.setUTCDate(d.getUTCDate() + offset);
@@ -2731,23 +3120,24 @@ const hydrateViewTickets = async (subdomain, token, ids) => {
 	const byId = new Map((tickets ?? []).map((t) => [t.id, t]));
 	return ids.map((id) => byId.get(id)).filter((t) => t !== void 0);
 };
+const addPositiveId = (set, raw) => {
+	const n = Number(raw);
+	if (Number.isInteger(n) && n > 0) set.add(n);
+};
+const collectEventIds = (event, userIds, groupIds) => {
+	if (event.type !== "Change" && event.type !== "Create") return;
+	const entity = event.field_name ? AUDIT_ENTITY_FIELDS[event.field_name] : void 0;
+	if (!entity) return;
+	const set = entity === "user" ? userIds : groupIds;
+	addPositiveId(set, event.value);
+	addPositiveId(set, event.previous_value);
+};
 const collectAuditIds = (audits) => {
 	const userIds = /* @__PURE__ */ new Set();
 	const groupIds = /* @__PURE__ */ new Set();
-	const addId = (set, raw) => {
-		const n = Number(raw);
-		if (Number.isInteger(n) && n > 0) set.add(n);
-	};
 	for (const audit of audits) {
-		addId(userIds, audit.author_id);
-		for (const event of audit.events) {
-			if (event.type !== "Change" && event.type !== "Create") continue;
-			const entity = event.field_name ? AUDIT_ENTITY_FIELDS[event.field_name] : void 0;
-			if (!entity) continue;
-			const set = entity === "user" ? userIds : groupIds;
-			addId(set, event.value);
-			addId(set, event.previous_value);
-		}
+		addPositiveId(userIds, audit.author_id);
+		for (const event of audit.events) collectEventIds(event, userIds, groupIds);
 	}
 	return {
 		userIds: [...userIds],
@@ -2790,12 +3180,11 @@ const diffLine = (label, before, after) => {
 	const a = shownValue(after);
 	return b === a ? null : `- **${label}**: ${b} → ${a}`;
 };
-const formatMacroPreviewDiff = (ticketId, macroId, before, result) => {
-	const after = result?.ticket ?? {};
-	const beforeObj = before ?? {};
-	const comment = after.comment ?? result?.comment;
+const asRecord = (value) => value ?? {};
+const diffStandardFields = (before, after) => {
+	const beforeObj = asRecord(before);
 	const changes = [];
-	for (const [key, afterVal] of Object.entries(after)) {
+	for (const [key, afterVal] of Object.entries(asRecord(after))) {
 		if (DIFF_SKIP_KEYS.has(key)) continue;
 		const beforeVal = beforeObj[key];
 		if (valuesEqual(beforeVal, afterVal)) continue;
@@ -2808,12 +3197,22 @@ const formatMacroPreviewDiff = (ticketId, macroId, before, result) => {
 		const line = diffLine(key, beforeVal, afterVal);
 		if (line) changes.push(line);
 	}
-	const afterFields = [after.fields ?? after.custom_fields ?? []].flat();
+	return changes;
+};
+const diffCustomFields = (before, after) => {
+	const afterFields = [after?.fields ?? after?.custom_fields ?? []].flat();
 	const beforeById = new Map((before?.custom_fields ?? []).map((f) => [f.id, f.value]));
+	const changes = [];
 	for (const f of afterFields) {
 		const line = diffLine(`custom field ${f.id}`, beforeById.get(f.id), f.value);
 		if (line) changes.push(line);
 	}
+	return changes;
+};
+const formatMacroPreviewDiff = (ticketId, macroId, before, result) => {
+	const after = result?.ticket ?? {};
+	const comment = after.comment ?? result?.comment;
+	const changes = [...diffStandardFields(before, after), ...diffCustomFields(before, after)];
 	const lines = [
 		`# Macro #${macroId} preview on ticket #${ticketId} (diff — nothing saved yet)`,
 		"",
@@ -2939,16 +3338,7 @@ const createTicketTools = (ctx) => {
 			handler: async (params) => {
 				const { ticket_id, attachment_ids } = params;
 				const token = await getToken();
-				let attachments;
-				if (attachment_ids && attachment_ids.length > 0) {
-					attachments = [];
-					for (const id of attachment_ids) try {
-						const { attachment } = await zendeskGet(subdomain, token, `/attachments/${id}`);
-						attachments.push(attachment);
-					} catch (error) {
-						if (!(error instanceof ZendeskApiError) || error.status !== 404) throw error;
-					}
-				} else attachments = (await fetchAllTicketComments(subdomain, token, ticket_id)).flatMap((c) => c.attachments ?? []);
+				const attachments = attachment_ids && attachment_ids.length > 0 ? await fetchAttachmentsByIds(subdomain, token, attachment_ids) : (await fetchAllTicketComments(subdomain, token, ticket_id)).flatMap((c) => c.attachments ?? []);
 				if (attachments.length === 0) return { content: [{
 					type: "text",
 					text: `No attachments found on ticket #${ticket_id}.`
@@ -3202,9 +3592,10 @@ const createTicketTools = (ctx) => {
 				const { problem_id } = params;
 				const token = await getToken();
 				const incidents = (await zendeskGet(subdomain, token, `/tickets/${problem_id}/incidents`)).tickets ?? [];
+				const text = incidents.length > 0 ? `# Incidents linked to problem #${problem_id}\n\n${incidents.map(formatTicket).join("\n\n")}` : `No incidents linked to problem #${problem_id}.`;
 				return { content: [{
 					type: "text",
-					text: truncateIfNeeded(incidents.length > 0 ? `# Incidents linked to problem #${problem_id}\n\n${incidents.map(formatTicket).join("\n\n")}` : `No incidents linked to problem #${problem_id}.`)
+					text: truncateIfNeeded(text)
 				}] };
 			}
 		},
@@ -3270,9 +3661,10 @@ const createTicketTools = (ctx) => {
 					throw error;
 				}
 				const policies = response.sla_policies ?? [];
+				const meta = extractOffsetPaginationMeta(response, policies.length, per_page, page);
 				return { content: [{
 					type: "text",
-					text: formatList(policies, formatSlaPolicy, extractOffsetPaginationMeta(response, policies.length, per_page, page))
+					text: formatList(policies, formatSlaPolicy, meta)
 				}] };
 			}
 		},
@@ -3406,9 +3798,10 @@ const createTicketTools = (ctx) => {
 				const token = await getToken();
 				const response = await zendeskGet(subdomain, token, "/macros/active", buildOffsetParams(per_page, page));
 				const macros = response.macros ?? [];
+				const meta = extractOffsetPaginationMeta(response, macros.length, per_page, page);
 				return { content: [{
 					type: "text",
-					text: formatList(macros, formatMacro, extractOffsetPaginationMeta(response, macros.length, per_page, page))
+					text: formatList(macros, formatMacro, meta)
 				}] };
 			}
 		},
@@ -3753,6 +4146,10 @@ const registerToolset = (server, { config, getToken, onUnauthorized, logger = si
 			case "single":
 				registered.push(registerProxyTool(server, "zendesk", "Zendesk", filteredTools, config.readOnly, onUnauthorized));
 				break;
+			default: {
+				const unhandled = config.mode;
+				throw new Error(`Unsupported tool mode: ${String(unhandled)}`);
+			}
 		}
 		if (helpCenterContextEnabled(config)) {
 			const topology = createTopologyProvider(getToken, config.subdomain, onUnauthorized);
@@ -3840,7 +4237,8 @@ const startStdioTransport = async (server, logger = silentLogger) => {
 };
 //#endregion
 //#region src/dev/reload.ts
-const toolsDir = join(dirname(fileURLToPath(import.meta.url)), "..", "tools");
+const thisDir = dirname(fileURLToPath(import.meta.url));
+const toolsDir = join(thisDir, "..", "tools");
 const TOOL_MODULES = [
 	{
 		file: "tickets.ts",
@@ -3979,6 +4377,7 @@ const WILDCARD_HOSTS = /* @__PURE__ */ new Set([
 	"::",
 	"*"
 ]);
+const TRAILING_SLASHES = /\/+$/;
 const DEFAULT_BROWSER_MCP_CLIENT_ORIGINS = [
 	"https://chatgpt.com",
 	"https://chat.openai.com",
@@ -4054,7 +4453,7 @@ const handleCorsPreflight = (req, res, extraOrigins) => {
 	return true;
 };
 const resolveResourceUrl = (config, logger = silentLogger) => {
-	if (config.publicUrl) return config.publicUrl.replace(/\/+$/, "");
+	if (config.publicUrl) return config.publicUrl.replace(TRAILING_SLASHES, "");
 	if (!WILDCARD_HOSTS.has(config.host)) return `http://${config.host}:${config.port}`;
 	logger.warn("public_url_unset", {
 		host: config.host,
@@ -4111,6 +4510,14 @@ const sendJsonRpcError = (res, status, code, message, headers = {}) => {
 		jsonrpc: "2.0"
 	}));
 };
+const failRequest = (res, err) => {
+	const message = err instanceof Error ? err.message : "Internal Server Error";
+	if (!res.headersSent) {
+		sendJsonRpcError(res, 500, -32603, message);
+		return;
+	}
+	if (!res.writableEnded) res.end();
+};
 const sendUnauthorized = (res, resource) => {
 	const wwwAuthenticate = `Bearer resource_metadata="${resource}/.well-known/oauth-protected-resource", error="invalid_token", error_description="${MISSING_BEARER_MESSAGE}"`;
 	sendJsonRpcError(res, 401, -32e3, MISSING_BEARER_MESSAGE, { "WWW-Authenticate": wwwAuthenticate });
@@ -4174,13 +4581,29 @@ const respondBodyError = (req, res, failure) => {
 	if (failure.status === 413) if (res.writableFinished) req.destroy();
 	else res.once("finish", () => req.destroy());
 };
-const SESSION_IDLE_TIMEOUT_MS = 1800 * 1e3;
-const SESSION_SWEEP_INTERVAL_MS = 60 * 1e3;
+const SESSION_IDLE_TIMEOUT_MS = 18e5;
+const SESSION_SWEEP_INTERVAL_MS = 6e4;
 const startHttpTransport = async (config, logger = silentLogger, options = {}) => {
 	const metadata = buildOAuthMetadata(config, logger);
 	const sessions = /* @__PURE__ */ new Map();
 	const idleTimeoutMs = options.sessionIdleTimeoutMs ?? SESSION_IDLE_TIMEOUT_MS;
 	const maxBodyBytes = options.maxBodyBytes ?? 4194304;
+	const dispatchToSession = async (req, res, sessionId, bearer) => {
+		const session = sessions.get(sessionId);
+		if (!session) return false;
+		session.auth.bearer = bearer;
+		session.lastActivityAt = Date.now();
+		const body = req.method === "POST" ? await readJsonBody(req, maxBodyBytes) : {
+			ok: true,
+			value: void 0
+		};
+		if (!body.ok) {
+			respondBodyError(req, res, body);
+			return true;
+		}
+		await session.transport.handleRequest(req, res, body.value);
+		return true;
+	};
 	const handleMcpRequest = async (req, res) => {
 		const bearer = extractBearer(req);
 		if (!bearer) {
@@ -4188,23 +4611,7 @@ const startHttpTransport = async (config, logger = silentLogger, options = {}) =
 			return;
 		}
 		const sessionId = typeof req.headers["mcp-session-id"] === "string" ? req.headers["mcp-session-id"] : void 0;
-		if (sessionId) {
-			const session = sessions.get(sessionId);
-			if (session) {
-				session.auth.bearer = bearer;
-				session.lastActivityAt = Date.now();
-				const body = req.method === "POST" ? await readJsonBody(req, maxBodyBytes) : {
-					ok: true,
-					value: void 0
-				};
-				if (!body.ok) {
-					respondBodyError(req, res, body);
-					return;
-				}
-				await session.transport.handleRequest(req, res, body.value);
-				return;
-			}
-		}
+		if (sessionId && await dispatchToSession(req, res, sessionId, bearer)) return;
 		if (req.method !== "POST") {
 			sendJsonRpcError(res, 400, -32e3, "No active session; initialize via POST first.");
 			return;
@@ -4236,24 +4643,22 @@ const startHttpTransport = async (config, logger = silentLogger, options = {}) =
 		await server.connect(transport);
 		await transport.handleRequest(req, res, body.value);
 	};
+	const staticGetRoutes = {
+		"/.well-known/oauth-protected-resource": metadata.protectedResource,
+		"/.well-known/oauth-authorization-server": metadata.authorizationServer,
+		"/healthz": {
+			status: "ok",
+			subdomain: config.subdomain
+		}
+	};
 	const requestListener = async (req, res) => {
 		try {
 			if (handleCorsPreflight(req, res, config.corsOrigins)) return;
 			applyCorsHeaders(req, res, config.corsOrigins);
 			const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
-			if (url.pathname === "/.well-known/oauth-protected-resource" && req.method === "GET") {
-				sendJson(res, 200, metadata.protectedResource);
-				return;
-			}
-			if (url.pathname === "/.well-known/oauth-authorization-server" && req.method === "GET") {
-				sendJson(res, 200, metadata.authorizationServer);
-				return;
-			}
-			if (url.pathname === "/healthz" && req.method === "GET") {
-				sendJson(res, 200, {
-					status: "ok",
-					subdomain: config.subdomain
-				});
+			const staticRoute = req.method === "GET" ? staticGetRoutes[url.pathname] : void 0;
+			if (staticRoute) {
+				sendJson(res, 200, staticRoute);
 				return;
 			}
 			if (url.pathname === "/mcp") {
@@ -4266,9 +4671,7 @@ const startHttpTransport = async (config, logger = silentLogger, options = {}) =
 				path: url.pathname
 			}));
 		} catch (err) {
-			const message = err instanceof Error ? err.message : "Internal Server Error";
-			if (!res.headersSent) sendJsonRpcError(res, 500, -32603, message);
-			else if (!res.writableEnded) res.end();
+			failRequest(res, err);
 		}
 	};
 	const httpServer = createServer((req, res) => {
@@ -4333,7 +4736,8 @@ const main = async () => {
 			await startDevServer(config, tokenStore.getToken, logger, tokenStore.invalidate);
 			return;
 		}
-		await startStdioTransport(createMcpServer(config, tokenStore.getToken, logger, tokenStore.invalidate), logger);
+		const server = createMcpServer(config, tokenStore.getToken, logger, tokenStore.invalidate);
+		await startStdioTransport(server, logger);
 		return;
 	}
 	if (config.dev) logger.warn("dev_mode_ignored_http");
@@ -4345,5 +4749,3 @@ main().catch((error) => {
 });
 //#endregion
 export {};
-//# sourceMappingURL=index.js.map