@fruggr/zendesk-mcp-server 2.16.1 → 2.17.1

package/dist/index.js

@@ -6,6 +6,7 @@ import { homedir, release } from "node:os";
 import open from "open";
 import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { parseArgs } from "node:util";
 import * as z from "zod/v4";
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as cheerio from "cheerio";
@@ -125,7 +126,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);
@@ -137,7 +139,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;
@@ -427,8 +429,12 @@ const appDirSegments = () => {
 };
 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, "_");
 /**
@@ -479,7 +485,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
@@ -701,97 +707,99 @@ const parsePort = (raw, label) => {
 	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 parsePortEnv = (raw, label) => raw === void 0 ? void 0 : parsePort(raw, label);
+const requireNonEmptyEnv = (name) => {
+	const raw = process.env[name];
+	if (raw === "") throw new Error(`Empty ${name}. Set it to a value, or unset it entirely.`);
+	return raw;
+};
+const CLI_OPTIONS = {
+	mode: { type: "string" },
+	namespace: {
+		type: "string",
+		multiple: true
+	},
+	tool: {
+		type: "string",
+		multiple: true
+	},
+	"log-level": { type: "string" },
+	"hc-resource-scheme": { type: "string" },
+	transport: { type: "string" },
+	host: { type: "string" },
+	port: { type: "string" },
+	"public-url": { type: "string" },
+	"cors-origin": {
+		type: "string",
+		multiple: true
+	},
+	"callback-port": { type: "string" },
+	"read-only": { type: "boolean" },
+	"no-topology": { type: "boolean" },
+	"no-promoted-articles": { type: "boolean" },
+	dev: { type: "boolean" }
+};
+new Set(Object.entries(CLI_OPTIONS).filter(([, spec]) => spec.type === "string").map(([name]) => `--${name}`));
+const FIELD_BY_FLAG = /* @__PURE__ */ new Map([
+	["mode", "mode"],
+	["namespace", "namespaces"],
+	["tool", "tools"],
+	["log-level", "logLevel"],
+	["hc-resource-scheme", "hcResourceScheme"],
+	["transport", "transport"],
+	["host", "host"],
+	["public-url", "publicUrl"],
+	["cors-origin", "corsOrigins"]
 ]);
-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 STANDALONE_EFFECTS = /* @__PURE__ */ new Map([
+	["read-only", { readOnly: true }],
+	["no-topology", { topology: false }],
+	["no-promoted-articles", { promotedArticles: false }],
+	["dev", { dev: true }]
 ]);
 const parseCliArgs = (args) => {
-	const result = {};
-	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 (valued && next) {
-			valued(result, next);
-			i++;
+	const { values, positionals } = parseArgs({
+		args,
+		options: CLI_OPTIONS,
+		allowPositionals: true
+	});
+	if (positionals.length > 1) throw new Error(`Expected one positional argument (the subdomain), got ${positionals.length}. A repeatable flag has to be repeated (--namespace tickets --namespace help_center); it does not take a space-separated list.`);
+	const result = { subdomain: positionals[0] };
+	for (const [flag, value] of Object.entries(values)) {
+		if (Array.isArray(value) ? value.includes("") : value === "") throw new Error(`Empty value for --${flag}. Provide a value, or omit the flag.`);
+		const effect = STANDALONE_EFFECTS.get(flag);
+		if (effect) {
+			Object.assign(result, effect);
 			continue;
 		}
-		if (!arg.startsWith("-") && result.subdomain === void 0) result.subdomain = arg;
+		const field = FIELD_BY_FLAG.get(flag);
+		if (field) Object.assign(result, { [field]: value });
 	}
+	if (values.port !== void 0) result.port = parsePort(values.port, "--port");
+	if (values["callback-port"] !== void 0) result.callbackPort = parsePort(values["callback-port"], "--callback-port");
 	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"],
+		transport: cli.transport ?? requireNonEmptyEnv("TRANSPORT") ?? "stdio",
+		host: cli.host ?? requireNonEmptyEnv("HOST") ?? "0.0.0.0",
+		port: cli.port ?? parsePortEnv(requireNonEmptyEnv("PORT"), "PORT") ?? 3e3,
+		publicUrl: cli.publicUrl ?? requireNonEmptyEnv("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 subdomain = cli.subdomain ?? requireNonEmptyEnv("ZENDESK_SUBDOMAIN") ?? "";
+	const oauthClientId = requireNonEmptyEnv("ZENDESK_OAUTH_CLIENT_ID") ?? `${subdomain}_zendesk`;
 	const mode = cli.tools?.length ? "all" : cli.mode ?? "namespace";
-	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);
+	const callbackPort = cli.callbackPort ?? parsePortEnv(requireNonEmptyEnv("ZENDESK_OAUTH_CALLBACK_PORT"), "ZENDESK_OAUTH_CALLBACK_PORT");
+	const hcResourceScheme = cli.hcResourceScheme ?? requireNonEmptyEnv("HC_RESOURCE_SCHEME");
 	return ConfigSchema.parse({
 		subdomain,
 		oauthClientId,
-		logLevel: cli.logLevel ?? process.env["LOG_LEVEL"] ?? "info",
+		logLevel: cli.logLevel ?? requireNonEmptyEnv("LOG_LEVEL") ?? "info",
 		mode,
 		readOnly: cli.readOnly ?? false,
 		namespaces: cli.namespaces,
@@ -1259,6 +1267,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) => {
@@ -1359,12 +1374,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
@@ -1592,7 +1609,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}".`,
@@ -1609,7 +1626,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
@@ -1737,6 +1755,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 [
@@ -1894,9 +2023,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)
 				}] };
 			}
 		},
@@ -2002,9 +2132,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)
 				}] };
 			}
 		},
@@ -2027,9 +2158,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}${scanCostNote(truncated, pagesScanned, cost)}`)
+					text: truncateIfNeeded(`${header}\n\n${body}${note}`)
 				}] };
 			}
 		},
@@ -2049,9 +2181,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)
 				}] };
 			}
 		},
@@ -2118,6 +2251,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",
@@ -2250,7 +2537,8 @@ const createHelpCenterTools = (ctx) => {
 				const effective = await fetchSectionOrder(sectionId, locale, token);
 				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.`
@@ -2264,7 +2552,8 @@ const createHelpCenterTools = (ctx) => {
 					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.`
 				}] };
 				const applied = await applyPositionWrites(writes, article_id, token);
-				if (!isPlacedAsRequested(await fetchSectionOrder(sectionId, locale, token), article_id, target, reference_article_id)) return { content: [{
+				const after = await fetchSectionOrder(sectionId, locale, token);
+				if (!isPlacedAsRequested(after, article_id, target, reference_article_id)) return { content: [{
 					type: "text",
 					text: autoSortNotice(sectionId, applied)
 				}] };
@@ -2375,9 +2664,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)
 				}] };
 			}
 		},
@@ -2503,14 +2793,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)
 				}] };
 			}
 		},
@@ -2674,16 +2965,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 / (1024 * 1024)).toFixed(2));
+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);
@@ -3302,9 +3595,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)
 				}] };
 			}
 		},
@@ -3370,9 +3664,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)
 				}] };
 			}
 		},
@@ -3506,9 +3801,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)
 				}] };
 			}
 		},
@@ -3944,7 +4240,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",
@@ -4287,8 +4584,8 @@ 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();
@@ -4442,7 +4739,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");