@fruggr/zendesk-mcp-server 2.13.0 → 2.14.0

package/dist/index.js

@@ -1478,6 +1478,7 @@ const markdownToHtml = (markdown) => {
 //#endregion
 //#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 largeArticleHint = (body, sectionCount) => {
 	if (body.length < 3e3 && sectionCount < 4) return null;
 	return [
@@ -1560,7 +1561,7 @@ const createHelpCenterTools = (ctx) => {
 				const token = await getToken();
 				const path = locale ? `/${locale}/articles/${article_id}` : `/articles/${article_id}`;
 				const { article } = await helpCenterGet(subdomain, token, path);
-				const { translations } = await helpCenterGet(subdomain, token, `/articles/${article_id}/translations`);
+				const translations = await listTranslations(subdomain, token, article_id);
 				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(", ")}`)
@@ -1667,8 +1668,7 @@ const createHelpCenterTools = (ctx) => {
 					text: formatList(articles, formatArticleSummary, extractPaginationMeta(response, articles.length))
 				}] };
 				const formatted = await Promise.all(articles.map(async (article) => {
-					const { translations } = await helpCenterGet(subdomain, token, `/articles/${article.id}/translations`);
-					const locales = translations.map((t) => t.locale).join(", ");
+					const locales = (await listTranslations(subdomain, token, article.id)).map((t) => t.locale).join(", ");
 					return `${formatArticleSummary(article)}\n- **Translations**: ${locales}`;
 				}));
 				const meta = extractPaginationMeta(response, articles.length);
@@ -1694,10 +1694,9 @@ const createHelpCenterTools = (ctx) => {
 			handler: async (params) => {
 				const { article_id } = params;
 				const token = await getToken();
-				const { translations } = await helpCenterGet(subdomain, token, `/articles/${article_id}/translations`);
 				return { content: [{
 					type: "text",
-					text: formatList(translations, formatTranslationSummary)
+					text: formatList(await listTranslations(subdomain, token, article_id), formatTranslationSummary)
 				}] };
 			}
 		},
@@ -2120,7 +2119,7 @@ const createHelpCenterTools = (ctx) => {
 				const { article } = await helpCenterGet(subdomain, token, `/articles/${article_id}`);
 				const effectiveLocale = locale ?? article.source_locale;
 				const { translation } = await helpCenterGet(subdomain, token, `/articles/${article_id}/translations/${effectiveLocale}`);
-				const { translations } = await helpCenterGet(subdomain, token, `/articles/${article_id}/translations`);
+				const translations = await listTranslations(subdomain, token, article_id);
 				const sections = parseSections(translation.body);
 				const outlineLines = sections.length ? sections.map((s) => `- [${s.index}] ${s.headingTag ? `${s.headingTag}: ` : ""}${s.heading} (${s.wordCount} words)`).join("\n") : "_(no sections detected)_";
 				const translationsList = translations.map((t) => `- ${t.locale}${t.outdated ? " (outdated)" : ""}`).join("\n");
@@ -2215,7 +2214,7 @@ const createHelpCenterTools = (ctx) => {
 			namespace: "help_center",
 			readOnly: true,
 			title: "Compare Article Translations",
-			description: "Compare section structure between two locales of the same article, matched by index. Returns a compact table (one row per section) with status: \"ok\" (both present, source/target word count ratio within 25%), \"different\" (word count ratio diverges by more than 25% — size signal only, NOT a semantic divergence: two locales may legitimately differ in verbosity) or \"missing\" (section absent in target). Useful to spot structurally stale or missing sections; do not interpret \"different\" as an edit regression on its own.",
+			description: "Compare two locales of the same article to decide whether the target translation needs work, reporting independent signals instead of one ambiguous verdict. (1) Header — a \"Freshness\" verdict for the target, derived from the two translations' updated_at timestamps: if the source was edited after the target it is \"likely behind, review recommended\" (with the day gap), otherwise \"up to date\". This is the primary staleness signal and is always available. (2) Zendesk's own per-translation \"outdated\" flag for the target (\"yes\"/\"no\"/\"unknown\"), shown as a secondary overlay: it is only set through Guide's native \"mark out of date\" workflow and NOT by API edits, so a \"no\" does not by itself mean current — prefer Freshness. (3) A global structure check (section count and heading-tag sequence); on mismatch the header warns the per-index rows may be misaligned. (4) A per-section table matched by index, status \"ok\" (present in both), \"missing\" (present in source, absent in target) or \"extra\" (present in target, absent in source). (5) Per-section source/target word counts, INFORMATIONAL ONLY: a length difference between languages is normal and is deliberately NOT flagged as a divergence — do not read a word-count gap as an edit regression or staleness. Read-only; performs three Help Center GET calls (both translations plus the translations list for the outdated flag).",
 			inputSchema: z.object({
 				article_id: z.number().int().describe(ARTICLE_ID_DESC),
 				source_locale: z.string().describe("Reference locale to diff against, e.g. \"en-us\". Usually the article source_locale (from get_article)."),
@@ -2230,10 +2229,32 @@ const createHelpCenterTools = (ctx) => {
 			handler: async (params) => {
 				const { article_id, source_locale, target_locale } = params;
 				const token = await getToken();
-				const [sourceRes, targetRes] = await Promise.all([helpCenterGet(subdomain, token, `/articles/${article_id}/translations/${source_locale}`), helpCenterGet(subdomain, token, `/articles/${article_id}/translations/${target_locale}`)]);
+				const [sourceRes, targetRes, translations] = await Promise.all([
+					helpCenterGet(subdomain, token, `/articles/${article_id}/translations/${source_locale}`),
+					helpCenterGet(subdomain, token, `/articles/${article_id}/translations/${target_locale}`),
+					listTranslations(subdomain, token, article_id)
+				]);
 				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(`| --- | --- | --- | --- | --- |`);
@@ -2245,11 +2266,8 @@ const createHelpCenterTools = (ctx) => {
 					const targetWords = tgt?.wordCount ?? 0;
 					let status;
 					if (!tgt) status = "missing";
-					else if (!src) status = "different";
-					else {
-						const denom = Math.max(sourceWords, 1);
-						status = Math.abs(sourceWords - targetWords) / denom > .25 ? "different" : "ok";
-					}
+					else if (!src) status = "extra";
+					else status = "ok";
 					rows.push(`| ${i} | ${heading} | ${status} | ${sourceWords} | ${targetWords} |`);
 				}
 				return { content: [{
@@ -2257,6 +2275,14 @@ const createHelpCenterTools = (ctx) => {
 					text: [
 						`# Translation diff — Article #${article_id} (${source_locale} → ${target_locale})`,
 						"",
+						freshnessLine,
+						outdatedLine,
+						structureLine,
+						`- **Updated**: source ${sourceUpdated} | target ${targetUpdated}`,
+						`- **Target draft**: ${targetRes.translation.draft ? "yes" : "no"}`,
+						"",
+						"_Word counts are informational: a length difference between languages is normal, not a divergence._",
+						"",
 						...rows
 					].join("\n")
 				}] };