@fruggr/zendesk-mcp-server 2.17.0 → 2.17.2

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,6 @@ 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 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);
@@ -706,97 +706,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,
@@ -1799,6 +1801,7 @@ const nodeTranslationWriteText = (kind, nodeId, translation, created) => [
 	"",
 	formatNodeTranslationSummary(translation)
 ].join("\n");
+const TRANSLATIONS_SIDELOAD = "translations";
 const GAP_REASON_TEXT = {
 	missing: "no translation",
 	draft: "draft translation (not published)"
@@ -1816,40 +1819,49 @@ const classifyGap = (node, translations, locale) => {
 		reason: "draft"
 	} : null;
 };
+/**
+* Split a listing into the nodes that can be classified and the rest. A node
+* whose `translations` key is absent was answered without the sideload, and
+* reading that as "no translation" would report an entire Help Center as one big
+* gap — so it counts as unclassified and the report says how many.
+*/
+const withSideloadedTranslations = (nodes) => nodes.filter((node) => Array.isArray(node.translations));
 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)_`];
+	if (scanned === 0) return [header, found === 0 ? "_(none to scan at this level)_" : `_(none classified — the listing answered without the sideload for all ${found}, 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}`);
+		const { category } = await helpCenterGet(subdomain, token, `/categories/${categoryId}`, { include: TRANSLATIONS_SIDELOAD });
 		return {
 			categories: [category],
 			hasMore: false
 		};
 	}
-	const response = await helpCenterGet(subdomain, token, "/categories", buildCursorParams(100, void 0));
+	const response = await helpCenterGet(subdomain, token, "/categories", {
+		...buildCursorParams(100, void 0),
+		include: TRANSLATIONS_SIDELOAD
+	});
 	const categories = response.categories ?? [];
 	return {
 		categories,
 		hasMore: extractPaginationMeta(response, categories.length).has_more
 	};
 };
+const renderGapVerdict = (report, gapCount, unclassified) => {
+	const { locale, scanned } = report;
+	if (gapCount > 0) return `${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.`;
+	if (scanned.categories + scanned.sections === 0 && unclassified > 0) return `Nothing could be classified, so this audit says nothing about "${locale}" either way. See the note below.`;
+	const allClear = `No gaps: all ${scanned.categories} category/ies and ${scanned.sections} section(s) scanned have a published "${locale}" translation.`;
+	return unclassified > 0 ? `${allClear} This is not a clean bill of health for the whole tree: ${unclassified} other node(s) could not be classified — see the note below.` : allClear;
+};
 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;
+	const totalFound = found.categories + found.sections;
+	const unclassified = totalFound - (scanned.categories + scanned.sections);
 	return truncateIfNeeded([
 		`# Translation gaps — "${locale}"`,
 		"",
@@ -1858,8 +1870,8 @@ const renderGapReport = (report) => {
 		"",
 		...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._`] : [],
+		renderGapVerdict(report, gapCount, unclassified),
+		...unclassified > 0 ? ["", `_Note: ${unclassified} of ${totalFound} node(s) came back without the \`translations\` sideload, so their state is unknown and none of them is reported above (covered: ${scanned.categories}/${found.categories} categories, ${scanned.sections}/${found.sections} sections). Read one of them with list_category_translations / list_section_translations, which query the node directly._`] : [],
 		...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"));
 };
@@ -2299,10 +2311,10 @@ const createHelpCenterTools = (ctx) => {
 			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.",
+			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 two listings and covers up to 100 categories and 100 sections; past that only the first page of each level is audited, and the report says so — 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.")
+				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 two listings and covers up to 100 categories and 100 sections.")
 			}),
 			annotations: {
 				readOnlyHint: true,
@@ -2316,14 +2328,17 @@ const createHelpCenterTools = (ctx) => {
 				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))
+					helpCenterGet(subdomain, token, sectionListPath(category_id, void 0), {
+						...buildCursorParams(100, void 0),
+						include: TRANSLATIONS_SIDELOAD
+					})
 				]);
 				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));
+				const categories = withSideloadedTranslations(allCategories);
+				const sections = withSideloadedTranslations(allSections);
+				const categoryGaps = categories.flatMap((category) => classifyGap(category, category.translations, locale) ?? []);
+				const sectionGaps = sections.flatMap((section) => classifyGap(section, section.translations, locale) ?? []);
 				return { content: [{
 					type: "text",
 					text: renderGapReport({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fruggr/zendesk-mcp-server",
-  "version": "2.17.0",
+  "version": "2.17.2",
   "mcpName": "io.github.fruggr/zendesk-mcp-server",
   "description": "Deep Zendesk MCP server for your AI assistant: search, draft, update and translate Help Center articles and manage Support tickets end to end — comments, triage and image attachments.",
   "type": "module",