@fruggr/zendesk-mcp-server 2.17.1 → 2.17.2

package/dist/index.js

@@ -126,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);
@@ -1802,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)"
@@ -1819,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}"`,
 		"",
@@ -1861,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"));
 };
@@ -2302,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,
@@ -2319,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.1",
+  "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",