@fruggr/zendesk-mcp-server 2.8.0 → 2.10.0

package/README.md

@@ -9,10 +9,10 @@
 [![semantic-release](https://img.shields.io/badge/semantic--release-e10079?logo=semantic-release&logoColor=white)](https://github.com/semantic-release/semantic-release)
 
 **Bring Zendesk deep into your AI assistant.** A
-[Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for a
-two-way integration: find answers in the Help Center, **draft, update and
-translate** articles (keeping languages in sync), and **manage Support tickets**
-end to end — comments, triage and image attachments — all in plain language,
+[Model Context Protocol](https://modelcontextprotocol.io) (MCP) server: find
+answers in the Help Center, **draft, update and translate** articles (keeping
+languages in sync), and **manage Support tickets** end to end — comments, triage
+and image attachments — all in plain language,
 **without switching apps**.
 
 Think of it as the [Zendesk agent for Microsoft 365 Copilot](https://support.zendesk.com/hc/en-us/articles/9958331458458-Using-the-Zendesk-agent-in-Microsoft-365-Copilot),

package/dist/index.js

@@ -261,14 +261,15 @@ const startBrowserAuth = (config, logger = silentLogger) => {
 			});
 			const port = callbackServer.address().port;
 			const redirectUri = `http://localhost:${port}/callback`;
-			const authUrl = `${authorizeBase}?${new URLSearchParams({
+			const params = new URLSearchParams({
 				response_type: "code",
 				client_id: oauthClientId,
 				redirect_uri: redirectUri,
 				scope: "read write",
 				code_challenge: codeChallenge,
 				code_challenge_method: "S256"
-			}).toString()}`;
+			});
+			const authUrl = `${authorizeBase}?${params.toString()}`;
 			logger.debug("oauth_callback_listening", {
 				port,
 				redirectUri
@@ -533,7 +534,8 @@ const createTokenStore = (config, logger = silentLogger) => {
 			if (refreshed) return refreshed;
 		}
 		if (!starting) starting = beginAuth();
-		throw createAuthRequiredError(authorizeUrl ?? await starting);
+		const url = authorizeUrl ?? await starting;
+		throw createAuthRequiredError(url);
 	};
 	const invalidate = () => {
 		if (token?.refreshToken) {
@@ -746,37 +748,44 @@ const executeRequest = async (url, token, options = {}) => {
 	return response.json();
 };
 const zendeskGet = (subdomain, token, path, params) => {
-	return executeRequest(buildUrl(getBaseUrl(subdomain), path, params), token);
+	const url = buildUrl(getBaseUrl(subdomain), path, params);
+	return executeRequest(url, token);
 };
 const zendeskPost = (subdomain, token, path, body) => {
-	return executeRequest(buildUrl(getBaseUrl(subdomain), path), token, {
+	const url = buildUrl(getBaseUrl(subdomain), path);
+	return executeRequest(url, token, {
 		method: "POST",
 		body
 	});
 };
 const zendeskPut = (subdomain, token, path, body) => {
-	return executeRequest(buildUrl(getBaseUrl(subdomain), path), token, {
+	const url = buildUrl(getBaseUrl(subdomain), path);
+	return executeRequest(url, token, {
 		method: "PUT",
 		body
 	});
 };
 const helpCenterGet = (subdomain, token, path, params) => {
-	return executeRequest(buildUrl(getHelpCenterBaseUrl(subdomain), path, params), token);
+	const url = buildUrl(getHelpCenterBaseUrl(subdomain), path, params);
+	return executeRequest(url, token);
 };
 const helpCenterPost = (subdomain, token, path, body) => {
-	return executeRequest(buildUrl(getHelpCenterBaseUrl(subdomain), path), token, {
+	const url = buildUrl(getHelpCenterBaseUrl(subdomain), path);
+	return executeRequest(url, token, {
 		method: "POST",
 		body
 	});
 };
 const helpCenterPut = (subdomain, token, path, body) => {
-	return executeRequest(buildUrl(getHelpCenterBaseUrl(subdomain), path), token, {
+	const url = buildUrl(getHelpCenterBaseUrl(subdomain), path);
+	return executeRequest(url, token, {
 		method: "PUT",
 		body
 	});
 };
 const helpCenterDelete = (subdomain, token, path) => {
-	return executeRequest(buildUrl(getHelpCenterBaseUrl(subdomain), path), token, { method: "DELETE" });
+	const url = buildUrl(getHelpCenterBaseUrl(subdomain), path);
+	return executeRequest(url, token, { method: "DELETE" });
 };
 const fetchZendeskBinary = async (subdomain, token, contentUrl) => {
 	const expectedHost = `${subdomain}.zendesk.com`;
@@ -888,6 +897,36 @@ const formatSlaPolicy = (policy) => {
 		...targets
 	].filter(Boolean).join("\n");
 };
+const formatTicketField = (field) => {
+	const flags = [field.active ? "active" : "inactive", field.required ? "required" : "optional"].join(", ");
+	const options = field.custom_field_options ?? field.system_field_options ?? [];
+	return [
+		`## ${field.title} (id ${field.id})`,
+		`- **Type**: ${field.type} | **${flags}**`,
+		field.description ? `- **Description**: ${field.description}` : "",
+		field.tag ? `- **Tag**: ${field.tag}` : "",
+		options.length > 0 ? "- **Options** (name → value):" : "",
+		...options.map((o) => `  - ${o.name} → ${o.value}`)
+	].filter(Boolean).join("\n");
+};
+const formatFieldValue = (value) => Array.isArray(value) ? value.map(formatFieldValue).join(", ") : formatConditionValue(value);
+const MACRO_VALUE_PREVIEW = 120;
+const formatMacroActionValue = (value) => {
+	const oneLine = formatFieldValue(value).replace(/\s+/g, " ").trim();
+	return oneLine.length > MACRO_VALUE_PREVIEW ? `${oneLine.slice(0, MACRO_VALUE_PREVIEW)}…` : oneLine;
+};
+const formatMacroAction = (action) => `  - ${action.field} → ${formatMacroActionValue(action.value)}`;
+const formatMacro = (macro) => {
+	const scope = macro.restriction?.type ? "restricted" : "shared";
+	const actions = macro.actions ?? [];
+	return [
+		`## ${macro.title} (id ${macro.id})`,
+		`- **${macro.active ? "active" : "inactive"}** | **Scope**: ${scope}`,
+		macro.description ? `- **Description**: ${macro.description}` : "",
+		actions.length > 0 ? "- **Actions**:" : "- **Actions**: none",
+		...actions.map(formatMacroAction)
+	].filter(Boolean).join("\n");
+};
 const minutesUntil = (iso) => {
 	const t = Date.parse(iso);
 	return Number.isNaN(t) ? null : Math.round((t - Date.now()) / 6e4);
@@ -967,7 +1006,8 @@ const formatLabel = (label) => `- **${label.name}** (${label.id})`;
 const formatUserSegment = (segment) => `- **${segment.name}** (${segment.id}) — ${segment.user_type}${segment.built_in ? " — Built-in" : ""}`;
 const formatAttachment = (attachment) => `- **${attachment.file_name}** (${attachment.id}) — ${attachment.content_type} — ${attachment.size} bytes`;
 const formatList = (items, formatter, meta) => {
-	return truncateIfNeeded([meta ? formatPagination(meta) : "", items.map(formatter).join("\n\n")].filter(Boolean).join("\n\n"));
+	const text = [meta ? formatPagination(meta) : "", items.map(formatter).join("\n\n")].filter(Boolean).join("\n\n");
+	return truncateIfNeeded(text);
 };
 //#endregion
 //#region src/utils/pagination.ts
@@ -988,6 +1028,11 @@ const extractPaginationMeta = (response, itemCount) => ({
 	after_cursor: response.meta?.after_cursor ?? null,
 	count: response.count ?? itemCount
 });
+const extractOffsetPaginationMeta = (response, itemCount, perPage, page) => response.count != null ? extractSearchPaginationMeta(response, perPage, page) : {
+	count: itemCount,
+	has_more: false,
+	after_cursor: null
+};
 const extractSearchPaginationMeta = (response, perPage, page) => {
 	const count = response.count ?? 0;
 	const has_more = count > page * perPage;
@@ -1093,7 +1138,8 @@ const createTopologyProvider = (getToken, subdomain, onUnauthorized) => {
 		const now = Date.now();
 		if (cached && now - cached.at < 3e5) return cached.promise;
 		const promise = (async () => {
-			return formatTopology(await fetchTopology(subdomain, await getToken()));
+			const token = await getToken();
+			return formatTopology(await fetchTopology(subdomain, token));
 		})().catch((err) => {
 			cached = void 0;
 			if (onUnauthorized && err instanceof ZendeskApiError && err.status === 401) onUnauthorized();
@@ -1285,7 +1331,8 @@ const createHelpCenterTools = (ctx) => {
 			handler: async (params) => {
 				const { article_id, locale } = params;
 				const token = await getToken();
-				const { article } = await helpCenterGet(subdomain, token, locale ? `/${locale}/articles/${article_id}` : `/articles/${article_id}`);
+				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`);
 				return { content: [{
 					type: "text",
@@ -1312,7 +1359,9 @@ const createHelpCenterTools = (ctx) => {
 			},
 			handler: async (params) => {
 				const { locale, page_size, cursor } = params;
-				const response = await helpCenterGet(subdomain, await getToken(), locale ? `/${locale}/categories` : "/categories", buildCursorParams(page_size, cursor));
+				const token = await getToken();
+				const path = locale ? `/${locale}/categories` : "/categories";
+				const response = await helpCenterGet(subdomain, token, path, buildCursorParams(page_size, cursor));
 				const categories = response.categories ?? [];
 				return { content: [{
 					type: "text",
@@ -1340,7 +1389,9 @@ const createHelpCenterTools = (ctx) => {
 			},
 			handler: async (params) => {
 				const { category_id, locale, page_size, cursor } = params;
-				const response = await helpCenterGet(subdomain, await getToken(), category_id && locale ? `/${locale}/categories/${category_id}/sections` : category_id ? `/categories/${category_id}/sections` : locale ? `/${locale}/sections` : "/sections", buildCursorParams(page_size, cursor));
+				const token = await getToken();
+				const path = category_id && locale ? `/${locale}/categories/${category_id}/sections` : category_id ? `/categories/${category_id}/sections` : locale ? `/${locale}/sections` : "/sections";
+				const response = await helpCenterGet(subdomain, token, path, buildCursorParams(page_size, cursor));
 				const sections = response.sections ?? [];
 				return { content: [{
 					type: "text",
@@ -1377,7 +1428,8 @@ const createHelpCenterTools = (ctx) => {
 			handler: async (params) => {
 				const { section_id, locale, page_size, cursor, sort_by, sort_order, include_translations } = params;
 				const token = await getToken();
-				const response = await helpCenterGet(subdomain, token, section_id && locale ? `/${locale}/sections/${section_id}/articles` : section_id ? `/sections/${section_id}/articles` : locale ? `/${locale}/articles` : "/articles", {
+				const path = section_id && locale ? `/${locale}/sections/${section_id}/articles` : section_id ? `/sections/${section_id}/articles` : locale ? `/${locale}/articles` : "/articles";
+				const response = await helpCenterGet(subdomain, token, path, {
 					...buildCursorParams(page_size, cursor),
 					sort_by,
 					sort_order
@@ -1414,7 +1466,8 @@ const createHelpCenterTools = (ctx) => {
 			},
 			handler: async (params) => {
 				const { article_id } = params;
-				const { translations } = await helpCenterGet(subdomain, await getToken(), `/articles/${article_id}/translations`);
+				const token = await getToken();
+				const { translations } = await helpCenterGet(subdomain, token, `/articles/${article_id}/translations`);
 				return { content: [{
 					type: "text",
 					text: formatList(translations, formatTranslationSummary)
@@ -1442,7 +1495,8 @@ const createHelpCenterTools = (ctx) => {
 			},
 			handler: async (params) => {
 				const { article_id, locale, title, body, draft } = params;
-				const { translation } = await helpCenterPost(subdomain, await getToken(), `/articles/${article_id}/translations`, { translation: {
+				const token = await getToken();
+				const { translation } = await helpCenterPost(subdomain, token, `/articles/${article_id}/translations`, { translation: {
 					locale,
 					title,
 					body,
@@ -1475,7 +1529,8 @@ const createHelpCenterTools = (ctx) => {
 			},
 			handler: async (params) => {
 				const { article_id, locale, ...updates } = params;
-				const { translation } = await helpCenterPut(subdomain, await getToken(), `/articles/${article_id}/translations/${locale}`, { translation: updates });
+				const token = await getToken();
+				const { translation } = await helpCenterPut(subdomain, token, `/articles/${article_id}/translations/${locale}`, { translation: updates });
 				return { content: [{
 					type: "text",
 					text: `Translation updated for article #${article_id} in "${locale}".\n\n${formatTranslation(translation)}`
@@ -1496,9 +1551,10 @@ const createHelpCenterTools = (ctx) => {
 				openWorldHint: true
 			},
 			handler: async () => {
+				const token = await getToken();
 				return { content: [{
 					type: "text",
-					text: formatList((await zendeskGet(subdomain, await getToken(), "/guide/permission_groups")).permission_groups ?? [], formatPermissionGroup)
+					text: formatList((await zendeskGet(subdomain, token, "/guide/permission_groups")).permission_groups ?? [], formatPermissionGroup)
 				}] };
 			}
 		},
@@ -1529,7 +1585,8 @@ const createHelpCenterTools = (ctx) => {
 			},
 			handler: async (params) => {
 				const { section_id, ...articleData } = params;
-				const { article } = await helpCenterPost(subdomain, await getToken(), `/sections/${section_id}/articles`, { article: articleData });
+				const token = await getToken();
+				const { article } = await helpCenterPost(subdomain, token, `/sections/${section_id}/articles`, { article: articleData });
 				return { content: [{
 					type: "text",
 					text: `Article #${article.id} created.\n\n${formatArticle(article)}`
@@ -1562,7 +1619,8 @@ const createHelpCenterTools = (ctx) => {
 			},
 			handler: async (params) => {
 				const { article_id, ...updates } = params;
-				const { article } = await helpCenterPut(subdomain, await getToken(), `/articles/${article_id}`, { article: updates });
+				const token = await getToken();
+				const { article } = await helpCenterPut(subdomain, token, `/articles/${article_id}`, { article: updates });
 				return { content: [{
 					type: "text",
 					text: `Article #${article.id} updated.\n\n${formatArticle(article)}`
@@ -1588,7 +1646,8 @@ const createHelpCenterTools = (ctx) => {
 			handler: async (params) => {
 				const { article_id, confirm } = params;
 				if (confirm !== true) throw new Error("Archiving is guarded: pass confirm: true to archive (soft-delete) this article. No changes were made.");
-				await helpCenterDelete(subdomain, await getToken(), `/articles/${article_id}`);
+				const token = await getToken();
+				await helpCenterDelete(subdomain, token, `/articles/${article_id}`);
 				return { content: [{
 					type: "text",
 					text: `Article #${article_id} archived (soft-deleted). It is removed from the Help Center; restore it from the Guide admin UI if needed.`
@@ -1646,7 +1705,8 @@ const createHelpCenterTools = (ctx) => {
 			},
 			handler: async (params) => {
 				const { name } = params;
-				const { content_tag } = await zendeskPost(subdomain, await getToken(), "/guide/content_tags", { content_tag: { name } });
+				const token = await getToken();
+				const { content_tag } = await zendeskPost(subdomain, token, "/guide/content_tags", { content_tag: { name } });
 				return { content: [{
 					type: "text",
 					text: `Content tag created.\n\n${formatContentTag(content_tag)}`
@@ -1667,9 +1727,10 @@ const createHelpCenterTools = (ctx) => {
 				openWorldHint: true
 			},
 			handler: async () => {
+				const token = await getToken();
 				return { content: [{
 					type: "text",
-					text: formatList((await helpCenterGet(subdomain, await getToken(), "/articles/labels")).labels ?? [], formatLabel)
+					text: formatList((await helpCenterGet(subdomain, token, "/articles/labels")).labels ?? [], formatLabel)
 				}] };
 			}
 		},
@@ -1687,9 +1748,10 @@ const createHelpCenterTools = (ctx) => {
 				openWorldHint: true
 			},
 			handler: async () => {
+				const token = await getToken();
 				return { content: [{
 					type: "text",
-					text: formatList((await helpCenterGet(subdomain, await getToken(), "/user_segments")).user_segments ?? [], formatUserSegment)
+					text: formatList((await helpCenterGet(subdomain, token, "/user_segments")).user_segments ?? [], formatUserSegment)
 				}] };
 			}
 		},
@@ -1708,7 +1770,8 @@ const createHelpCenterTools = (ctx) => {
 			},
 			handler: async (params) => {
 				const { article_id } = params;
-				const attachments = (await helpCenterGet(subdomain, await getToken(), `/articles/${article_id}/attachments`)).article_attachments ?? [];
+				const token = await getToken();
+				const attachments = (await helpCenterGet(subdomain, token, `/articles/${article_id}/attachments`)).article_attachments ?? [];
 				if (attachments.length === 0) return { content: [{
 					type: "text",
 					text: `No attachments found on article #${article_id}.`
@@ -1780,7 +1843,8 @@ const createHelpCenterTools = (ctx) => {
 			},
 			handler: async (params) => {
 				const { article_id, locale, section_index, format } = params;
-				const { translation } = await helpCenterGet(subdomain, await getToken(), `/articles/${article_id}/translations/${locale}`);
+				const token = await getToken();
+				const { translation } = await helpCenterGet(subdomain, token, `/articles/${article_id}/translations/${locale}`);
 				const sections = parseSections(translation.body);
 				const section = sections[section_index];
 				if (!section) throw new Error(`Section index ${section_index} not found. Article has ${sections.length} section(s) (0-${Math.max(0, sections.length - 1)}).`);
@@ -1952,7 +2016,8 @@ const createSearchTools = (ctx) => {
 		},
 		handler: async (params) => {
 			const { query, per_page, page } = params;
-			const response = await zendeskGet(subdomain, await getToken(), "/search", {
+			const token = await getToken();
+			const response = await zendeskGet(subdomain, token, "/search", {
 				query,
 				...buildOffsetParams(per_page, page)
 			});
@@ -2049,6 +2114,71 @@ const fetchTicketSla = async (subdomain, token, ticket) => {
 		return;
 	}
 };
+const DIFF_SKIP_KEYS = /* @__PURE__ */ new Set([
+	"comment",
+	"fields",
+	"custom_fields",
+	"id",
+	"url",
+	"created_at",
+	"updated_at",
+	"generated_timestamp",
+	"encoded_id"
+]);
+const valuesEqual = (a, b) => a === b || JSON.stringify(a) === JSON.stringify(b);
+const shownValue = (v) => {
+	const s = formatFieldValue(v);
+	return s === "" ? "(empty)" : s;
+};
+const diffLine = (label, before, after) => {
+	const b = shownValue(before);
+	const a = shownValue(after);
+	return b === a ? null : `- **${label}**: ${b} → ${a}`;
+};
+const formatTagDiff = (before, after) => {
+	const b = new Set(Array.isArray(before) ? before.map(String) : []);
+	const a = new Set(Array.isArray(after) ? after.map(String) : []);
+	const added = [...a].filter((t) => !b.has(t)).map((t) => `+${t}`);
+	const removed = [...b].filter((t) => !a.has(t)).map((t) => `-${t}`);
+	return added.length + removed.length === 0 ? null : `- **tags**: ${[...added, ...removed].join(", ")}`;
+};
+const formatMacroPreviewDiff = (ticketId, macroId, before, result) => {
+	const after = result?.ticket ?? {};
+	const beforeObj = before ?? {};
+	const comment = after.comment ?? result?.comment;
+	const changes = [];
+	for (const [key, afterVal] of Object.entries(after)) {
+		if (DIFF_SKIP_KEYS.has(key)) continue;
+		const beforeVal = beforeObj[key];
+		if (valuesEqual(beforeVal, afterVal)) continue;
+		if (key === "tags") {
+			const tagLine = formatTagDiff(beforeVal, afterVal);
+			if (tagLine) changes.push(tagLine);
+			continue;
+		}
+		if (afterVal !== null && typeof afterVal === "object" && !Array.isArray(afterVal)) continue;
+		const line = diffLine(key, beforeVal, afterVal);
+		if (line) changes.push(line);
+	}
+	const afterFields = [after.fields ?? after.custom_fields ?? []].flat();
+	const beforeById = new Map((before?.custom_fields ?? []).map((f) => [f.id, f.value]));
+	for (const f of afterFields) {
+		const line = diffLine(`custom field ${f.id}`, beforeById.get(f.id), f.value);
+		if (line) changes.push(line);
+	}
+	const lines = [
+		`# Macro #${macroId} preview on ticket #${ticketId} (diff — nothing saved yet)`,
+		"",
+		"## Field changes",
+		...changes.length > 0 ? changes : ["- none"]
+	];
+	if (comment?.body) {
+		const visibility = comment.public === false ? "internal note" : "public comment";
+		lines.push("", `## Reply (${visibility})`, "", comment.body);
+	} else lines.push("", "## Reply", "- none");
+	lines.push("", "## To apply these changes", "Nothing has been committed. Persist the field changes with `update_ticket` (or `manage_tags` for incremental tag edits), and post the reply with `add_public_comment` (public) or `add_private_note` (internal). Edit the reply text first if needed.");
+	return lines.join("\n");
+};
 const createTicketTools = (ctx) => {
 	const { subdomain, getToken } = ctx;
 	const attachmentSchema = z.object({
@@ -2156,7 +2286,8 @@ const createTicketTools = (ctx) => {
 			},
 			handler: async (params) => {
 				const { query, per_page, page } = params;
-				const response = await zendeskGet(subdomain, await getToken(), "/search", {
+				const token = await getToken();
+				const response = await zendeskGet(subdomain, token, "/search", {
 					query: `type:ticket ${query}`,
 					include: "tickets(slas)",
 					...buildOffsetParams(per_page, page)
@@ -2173,7 +2304,7 @@ const createTicketTools = (ctx) => {
 			namespace: "tickets",
 			readOnly: false,
 			title: "Create Zendesk Ticket",
-			description: "Create a new Zendesk support ticket with subject, description, and optional priority/type/assignee/tags. The description becomes the first public comment of the ticket, and the new ticket id is returned. After creation, use update_ticket to change status or assignee, add_public_comment or add_private_note to reply, and manage_tags to adjust tags. Look up valid assignee_id / group_id and custom field ids via search_users or your Zendesk admin settings.",
+			description: "Create a new Zendesk support ticket with subject, description, and optional priority/type/assignee/tags. The description becomes the first public comment of the ticket, and the new ticket id is returned. After creation, use update_ticket to change status or assignee, add_public_comment or add_private_note to reply, and manage_tags to adjust tags. Look up valid assignee_id / group_id and custom field ids via search_users or your Zendesk admin settings. Discover custom field ids and their accepted option values with list_ticket_fields.",
 			inputSchema: z.object({
 				subject: z.string().min(1).describe("Ticket subject — the short summary line shown in ticket lists and search results."),
 				description: z.string().min(1).describe("Ticket description — the body of the request. It becomes the ticket's first public comment (visible to the requester)."),
@@ -2195,7 +2326,7 @@ const createTicketTools = (ctx) => {
 				custom_fields: z.array(z.object({
 					id: z.number().int(),
 					value: z.unknown()
-				})).optional().describe("Custom field values as { id, value } pairs (field ids come from your Zendesk admin settings).")
+				})).optional().describe("Custom field values as { id, value } pairs (field ids come from your Zendesk admin settings). Call list_ticket_fields first to discover the numeric field ids and, for dropdown/multiselect fields, the exact option values Zendesk accepts.")
 			}),
 			annotations: {
 				readOnlyHint: false,
@@ -2205,7 +2336,8 @@ const createTicketTools = (ctx) => {
 			},
 			handler: async (params) => {
 				const { subject, description, ...rest } = params;
-				const { ticket } = await zendeskPost(subdomain, await getToken(), "/tickets", { ticket: {
+				const token = await getToken();
+				const { ticket } = await zendeskPost(subdomain, token, "/tickets", { ticket: {
 					subject,
 					comment: { body: description },
 					...rest
@@ -2251,7 +2383,7 @@ const createTicketTools = (ctx) => {
 				custom_fields: z.array(z.object({
 					id: z.number().int(),
 					value: z.unknown()
-				})).optional().describe("Custom field values as { id, value } pairs (field ids come from your Zendesk admin settings).")
+				})).optional().describe("Custom field values as { id, value } pairs (field ids come from your Zendesk admin settings). Call list_ticket_fields first to discover the numeric field ids and, for dropdown/multiselect fields, the exact option values Zendesk accepts.")
 			}),
 			annotations: {
 				readOnlyHint: false,
@@ -2261,7 +2393,8 @@ const createTicketTools = (ctx) => {
 			},
 			handler: async (params) => {
 				const { ticket_id, ...updates } = params;
-				const { ticket } = await zendeskPut(subdomain, await getToken(), `/tickets/${ticket_id}`, { ticket: updates });
+				const token = await getToken();
+				const { ticket } = await zendeskPut(subdomain, token, `/tickets/${ticket_id}`, { ticket: updates });
 				return { content: [{
 					type: "text",
 					text: `Ticket #${ticket.id} updated.\n\n${formatTicket(ticket)}`
@@ -2350,7 +2483,8 @@ const createTicketTools = (ctx) => {
 			},
 			handler: async (params) => {
 				const { page_size, cursor } = params;
-				const response = await zendeskGet(subdomain, await getToken(), "/tickets", buildCursorParams(page_size, cursor));
+				const token = await getToken();
+				const response = await zendeskGet(subdomain, token, "/tickets", buildCursorParams(page_size, cursor));
 				const tickets = response.tickets ?? [];
 				return { content: [{
 					type: "text",
@@ -2373,7 +2507,8 @@ const createTicketTools = (ctx) => {
 			},
 			handler: async (params) => {
 				const { problem_id } = params;
-				const incidents = (await zendeskGet(subdomain, await getToken(), `/tickets/${problem_id}/incidents`)).tickets ?? [];
+				const token = await getToken();
+				const incidents = (await zendeskGet(subdomain, token, `/tickets/${problem_id}/incidents`)).tickets ?? [];
 				return { content: [{
 					type: "text",
 					text: truncateIfNeeded(incidents.length > 0 ? `# Incidents linked to problem #${problem_id}\n\n${incidents.map(formatTicket).join("\n\n")}` : `No incidents linked to problem #${problem_id}.`)
@@ -2444,11 +2579,87 @@ const createTicketTools = (ctx) => {
 				const policies = response.sla_policies ?? [];
 				return { content: [{
 					type: "text",
-					text: formatList(policies, formatSlaPolicy, response.count != null ? extractSearchPaginationMeta(response, per_page, page) : {
-						count: policies.length,
-						has_more: false,
-						after_cursor: null
-					})
+					text: formatList(policies, formatSlaPolicy, extractOffsetPaginationMeta(response, policies.length, per_page, page))
+				}] };
+			}
+		},
+		{
+			name: "list_ticket_fields",
+			namespace: "tickets",
+			readOnly: true,
+			title: "List Ticket Fields",
+			description: "List the ticket field definitions configured on this Zendesk (both system fields and custom fields), returning each field's id, type, whether it is active/required, and — for dropdown and multiselect fields — the valid option values. Use this to discover the numeric field ids and accepted option tags that create_ticket and update_ticket expect in their custom_fields argument, so a natural-language intent (\"set severity to High\") maps to the right id and a value Zendesk will accept instead of a blind guess. Read-only reference lookup; cursor-paginated in Zendesk's default field order.",
+			inputSchema: z.object({
+				page_size: z.number().int().min(1).max(100).default(100).describe("Ticket field definitions per page (1-100, default 100)."),
+				cursor: z.string().optional().describe("Pagination cursor from a previous response; omit for the first page.")
+			}),
+			annotations: {
+				readOnlyHint: true,
+				destructiveHint: false,
+				idempotentHint: true,
+				openWorldHint: true
+			},
+			handler: async (params) => {
+				const { page_size, cursor } = params;
+				const token = await getToken();
+				const response = await zendeskGet(subdomain, token, "/ticket_fields", buildCursorParams(page_size, cursor));
+				const fields = response.ticket_fields ?? [];
+				return { content: [{
+					type: "text",
+					text: formatList(fields, formatTicketField, extractPaginationMeta(response, fields.length))
+				}] };
+			}
+		},
+		{
+			name: "list_macros",
+			namespace: "tickets",
+			readOnly: true,
+			title: "List Zendesk Macros",
+			description: "List the active macros available to the authenticated user. A macro bundles a canned reply and/or a set of field changes (status, priority, assignee, group, tags, custom fields) an agent applies to a ticket in one gesture; this returns each macro id, title, description, availability scope, and its ordered list of actions, offset-paginated. Results are scoped by per-user OAuth to what the current user can see, so no shared admin key is needed. Pass a macro id from here to preview_macro_diff to preview its effect on a specific ticket.",
+			inputSchema: z.object({
+				per_page: z.number().int().min(1).max(100).default(100).describe(PER_PAGE_DESC),
+				page: z.number().int().min(1).default(1).describe(PAGE_DESC)
+			}),
+			annotations: {
+				readOnlyHint: true,
+				destructiveHint: false,
+				idempotentHint: true,
+				openWorldHint: true
+			},
+			handler: async (params) => {
+				const { per_page, page } = params;
+				const token = await getToken();
+				const response = await zendeskGet(subdomain, token, "/macros/active", buildOffsetParams(per_page, page));
+				const macros = response.macros ?? [];
+				return { content: [{
+					type: "text",
+					text: formatList(macros, formatMacro, extractOffsetPaginationMeta(response, macros.length, per_page, page))
+				}] };
+			}
+		},
+		{
+			name: "preview_macro_diff",
+			namespace: "tickets",
+			readOnly: false,
+			title: "Preview a Macro Diff on a Ticket",
+			description: "Preview the exact changes a macro would make to a specific ticket, as a before → after diff, WITHOUT saving anything. Orchestrates two reads — the ticket's current state and Zendesk's macro-apply preview (which returns the whole resulting ticket) — and returns only the fields the macro actually changes (status, priority, assignee, group, tags, custom fields) plus the canned reply with its public/internal flag; unchanged and identity fields are omitted. Nothing is committed: to apply it, follow up with update_ticket for the field changes and add_public_comment or add_private_note for the reply. This deliberate two-step keeps the mutation explicit and reviewable rather than hidden. Find macro ids via list_macros and the ticket id via search_tickets or list_tickets.",
+			inputSchema: z.object({
+				ticket_id: z.number().int().describe("Ticket ID — the numeric id of the ticket to preview the macro against. Obtain it from search_tickets or list_tickets."),
+				macro_id: z.number().int().describe("Macro ID — the numeric id of the macro to preview. Obtain it from list_macros.")
+			}),
+			annotations: {
+				readOnlyHint: false,
+				destructiveHint: false,
+				idempotentHint: true,
+				openWorldHint: true
+			},
+			handler: async (params) => {
+				const { ticket_id, macro_id } = params;
+				const token = await getToken();
+				const [{ ticket: before }, { result }] = await Promise.all([zendeskGet(subdomain, token, `/tickets/${ticket_id}`), zendeskGet(subdomain, token, `/tickets/${ticket_id}/macros/${macro_id}/apply`)]);
+				return { content: [{
+					type: "text",
+					text: truncateIfNeeded(formatMacroPreviewDiff(ticket_id, macro_id, before, result))
 				}] };
 			}
 		}
@@ -2473,7 +2684,8 @@ const createUserTools = (ctx) => {
 				openWorldHint: true
 			},
 			handler: async () => {
-				const { user } = await zendeskGet(subdomain, await getToken(), "/users/me");
+				const token = await getToken();
+				const { user } = await zendeskGet(subdomain, token, "/users/me");
 				return { content: [{
 					type: "text",
 					text: formatUser(user)
@@ -2499,7 +2711,8 @@ const createUserTools = (ctx) => {
 			},
 			handler: async (params) => {
 				const { query, per_page, page } = params;
-				const response = await zendeskGet(subdomain, await getToken(), "/search", {
+				const token = await getToken();
+				const response = await zendeskGet(subdomain, token, "/search", {
 					query: `type:user ${query}`,
 					...buildOffsetParams(per_page, page)
 				});
@@ -2524,7 +2737,8 @@ const createUserTools = (ctx) => {
 			},
 			handler: async (params) => {
 				const { user_id } = params;
-				const { user } = await zendeskGet(subdomain, await getToken(), `/users/${user_id}`);
+				const token = await getToken();
+				const { user } = await zendeskGet(subdomain, token, `/users/${user_id}`);
 				return { content: [{
 					type: "text",
 					text: formatUser(user)
@@ -2546,7 +2760,8 @@ const createUserTools = (ctx) => {
 			},
 			handler: async (params) => {
 				const { organization_id } = params;
-				const { organization } = await zendeskGet(subdomain, await getToken(), `/organizations/${organization_id}`);
+				const token = await getToken();
+				const { organization } = await zendeskGet(subdomain, token, `/organizations/${organization_id}`);
 				return { content: [{
 					type: "text",
 					text: formatOrganization(organization)
@@ -2571,7 +2786,8 @@ const createUserTools = (ctx) => {
 			},
 			handler: async (params) => {
 				const { page_size, cursor } = params;
-				const response = await zendeskGet(subdomain, await getToken(), "/organizations", buildCursorParams(page_size, cursor));
+				const token = await getToken();
+				const response = await zendeskGet(subdomain, token, "/organizations", buildCursorParams(page_size, cursor));
 				const organizations = response.organizations ?? [];
 				return { content: [{
 					type: "text",
@@ -2899,7 +3115,8 @@ const sendJsonRpcError = (res, status, code, message, headers = {}) => {
 	}));
 };
 const sendUnauthorized = (res, resource) => {
-	sendJsonRpcError(res, 401, -32e3, MISSING_BEARER_MESSAGE, { "WWW-Authenticate": `Bearer resource_metadata="${resource}/.well-known/oauth-protected-resource", error="invalid_token", error_description="${MISSING_BEARER_MESSAGE}"` });
+	const wwwAuthenticate = `Bearer resource_metadata="${resource}/.well-known/oauth-protected-resource", error="invalid_token", error_description="${MISSING_BEARER_MESSAGE}"`;
+	sendJsonRpcError(res, 401, -32e3, MISSING_BEARER_MESSAGE, { "WWW-Authenticate": wwwAuthenticate });
 };
 const readJsonBody = (req, maxBodyBytes) => new Promise((resolve) => {
 	const chunks = [];