@fruggr/zendesk-mcp-server 2.12.2 → 2.14.0

package/dist/index.js

@@ -112,11 +112,12 @@ const positiveIntEnv = (name, fallback) => {
 	const raw = process.env[name];
 	if (raw === void 0 || raw.trim() === "") return fallback;
 	const parsed = Number(raw);
-	return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+	return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback;
 };
 const MAX_ATTACHMENT_BYTES = positiveIntEnv("ZENDESK_MAX_ATTACHMENT_BYTES", 5 * 1024 * 1024);
 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);
 const getBaseUrl = (subdomain) => `https://${subdomain}.zendesk.com/api/v2`;
 const getHelpCenterBaseUrl = (subdomain) => `https://${subdomain}.zendesk.com/api/v2/help_center`;
 const getOAuthUrls = (subdomain) => ({
@@ -1305,6 +1306,81 @@ const groupByNamespace = (tools) => {
 	return grouped;
 };
 //#endregion
+//#region src/utils/article-order.ts
+const hasPositionInversion = (order) => {
+	for (let i = 0; i < order.length - 1; i += 1) {
+		const here = order[i];
+		const next = order[i + 1];
+		if (here && next && here.position > next.position) return true;
+	}
+	return false;
+};
+const arrangeDesiredOrder = (effective, movedId, target, referenceId) => {
+	const moved = effective.find((a) => a.id === movedId);
+	if (!moved) throw new Error(`Article ${movedId} is not in the section.`);
+	const rest = effective.filter((a) => a.id !== movedId);
+	let slot;
+	if (target === "top") slot = 0;
+	else if (target === "bottom") slot = rest.length;
+	else {
+		const refIndex = rest.findIndex((a) => a.id === referenceId);
+		if (refIndex === -1) throw new Error(`Reference article ${referenceId} is not in the section.`);
+		slot = target === "before" ? refIndex : refIndex + 1;
+	}
+	return [
+		...rest.slice(0, slot),
+		moved,
+		...rest.slice(slot)
+	];
+};
+const computePositionWrites = (desired, movedId, normalize) => {
+	const writes = [];
+	if (normalize) {
+		desired.forEach((a, index) => {
+			if (a.position !== index) writes.push({
+				id: a.id,
+				position: index
+			});
+		});
+		return writes;
+	}
+	const movedIndex = desired.findIndex((a) => a.id === movedId);
+	const moved = desired[movedIndex];
+	if (!moved) return writes;
+	if (movedIndex === desired.length - 1) {
+		const maxOthers = desired.slice(0, movedIndex).reduce((max, a) => Math.max(max, a.position), -1);
+		if (moved.position > maxOthers) return writes;
+		writes.push({
+			id: moved.id,
+			position: maxOthers + 1
+		});
+		return writes;
+	}
+	const left = desired[movedIndex - 1];
+	let running = left ? left.position : -1;
+	for (let i = movedIndex; i < desired.length; i += 1) {
+		const article = desired[i];
+		if (!article) break;
+		if (i !== movedIndex && article.position > running) break;
+		const target = running + 1;
+		if (article.position !== target) writes.push({
+			id: article.id,
+			position: target
+		});
+		running = target;
+	}
+	return writes;
+};
+const isPlacedAsRequested = (effectiveAfter, movedId, target, referenceId) => {
+	const movedIndex = effectiveAfter.findIndex((a) => a.id === movedId);
+	if (movedIndex === -1) return false;
+	if (target === "top") return movedIndex === 0;
+	if (target === "bottom") return movedIndex === effectiveAfter.length - 1;
+	const refIndex = effectiveAfter.findIndex((a) => a.id === referenceId);
+	if (refIndex === -1) return false;
+	return target === "before" ? movedIndex < refIndex : movedIndex > refIndex;
+};
+//#endregion
 //#region src/utils/article-sections.ts
 const HEADING_LEVELS = /* @__PURE__ */ new Set([
 	"h1",
@@ -1402,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 [
@@ -1411,8 +1488,24 @@ 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 createHelpCenterTools = (ctx) => {
 	const { subdomain, getToken } = ctx;
+	const fetchSectionOrder = async (sectionId, locale, token) => {
+		const order = [];
+		let cursor;
+		do {
+			const response = await helpCenterGet(subdomain, token, `/${locale}/sections/${sectionId}/articles`, buildCursorParams(100, cursor));
+			const articles = response.articles ?? [];
+			for (const article of articles) order.push({
+				id: article.id,
+				position: article.position
+			});
+			const meta = extractPaginationMeta(response, articles.length);
+			cursor = meta.has_more && meta.after_cursor ? meta.after_cursor : void 0;
+		} while (cursor);
+		return order;
+	};
 	return [
 		{
 			name: "search_articles",
@@ -1468,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(", ")}`)
@@ -1575,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);
@@ -1602,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)
 				}] };
 			}
 		},
@@ -1769,6 +1860,81 @@ const createHelpCenterTools = (ctx) => {
 				}] };
 			}
 		},
+		{
+			name: "reorder_article",
+			namespace: "help_center",
+			readOnly: false,
+			title: "Reorder Help Center Article",
+			description: "Reorder an article within its current section by moving it relative to its siblings (top, bottom, or before/after another article), and return whether the new order was applied. This is the reliable way to satisfy \"put this article first/last\" requests: it writes the minimal set of article positions needed to make the order deterministic, because Zendesk leaves newly created articles tied at position 0 where a plain position update is silently ambiguous. It does NOT move the article to a different section — use update_article with section_id for that. Zendesk exposes no way to read whether a section is manually or automatically sorted, so when the section is sorted automatically (by date or alphabetically) the position writes are ignored; this tool detects that after the fact and returns guidance to switch the section to manual ordering in Guide. A move may reposition several neighbouring articles; when that count exceeds a configurable safety threshold the call is refused unless confirm is set to true.",
+			inputSchema: z.object({
+				article_id: z.number().int().describe("Article ID — the numeric id of the article to move within its section. Obtain it from list_articles or search_articles."),
+				target: z.enum([
+					"top",
+					"bottom",
+					"before",
+					"after"
+				]).describe("Where to move the article relative to its section siblings: \"top\" (becomes first), \"bottom\" (becomes last), or \"before\"/\"after\" a specific reference article. \"before\" and \"after\" require reference_article_id."),
+				reference_article_id: z.number().int().optional().describe("The sibling article to position next to when target is \"before\" or \"after\" (numeric id from list_articles). Must belong to the same section and differ from article_id; leave it unset for \"top\" or \"bottom\"."),
+				normalize: z.boolean().default(false).describe("When true, also renumber every article in the section to contiguous positions (0, 1, 2, …) so the stored positions stay tidy. Defaults to false, which writes the fewest positions possible and lets gaps remain. Either way the confirmation threshold still applies."),
+				confirm: z.boolean().default(false).describe("Safety guard for large reorders. When the move would rewrite more article positions than the configured threshold (ZENDESK_REORDER_CONFIRM_THRESHOLD, default 20), the tool refuses and reports the count until you pass true here. Has no effect on small reorders.")
+			}),
+			annotations: {
+				readOnlyHint: false,
+				destructiveHint: true,
+				idempotentHint: true,
+				openWorldHint: true
+			},
+			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.");
+				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}.`);
+				}
+				const targetLabel = needsReference ? `${target} article #${reference_article_id}` : target;
+				const writes = computePositionWrites(arrangeDesiredOrder(effective, article_id, target, reference_article_id), 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.`
+				}] };
+				if (hasPositionInversion(effective)) return { content: [{
+					type: "text",
+					text: autoSortNotice(sectionId)
+				}] };
+				if (writes.length > REORDER_CONFIRM_THRESHOLD && confirm !== true) return { content: [{
+					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: [{
+					type: "text",
+					text: autoSortNotice(sectionId, applied)
+				}] };
+				return { content: [{
+					type: "text",
+					text: `Article #${article_id} moved to ${targetLabel} in section #${sectionId} (${applied} article${applied === 1 ? "" : "s"} repositioned).`
+				}] };
+			}
+		},
 		{
 			name: "archive_article",
 			namespace: "help_center",
@@ -1953,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");
@@ -2048,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)."),
@@ -2063,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(`| --- | --- | --- | --- | --- |`);
@@ -2078,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: [{
@@ -2090,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")
 				}] };