@fruggr/zendesk-mcp-server 2.12.2 → 2.13.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",
@@ -1411,8 +1487,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",
@@ -1769,6 +1861,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",