@fruggr/zendesk-mcp-server 2.22.3 → 2.23.0

package/dist/index.js

@@ -68,7 +68,7 @@ const sanitise = (fields) => {
 };
 const renderValue = (value) => {
 	if (typeof value === "string") return value;
-	if (typeof value === "number" || typeof value === "boolean" || value === null) return String(value);
+	if (typeof value === "number") return String(value);
 	try {
 		return JSON.stringify(value);
 	} catch {
@@ -791,11 +791,7 @@ const ConfigSchema = z.object({
 		abort: true
 	}).refine((scheme) => {
 		const uri = `${scheme}://topology`;
-		try {
-			return new URL(uri).toString() === uri;
-		} catch {
-			return false;
-		}
+		return new URL(uri).toString() === uri;
 	}, { message: "Invalid HC_RESOURCE_SCHEME / --hc-resource-scheme value. WHATWG-special schemes (http, https, ws, wss, ftp, file) do not survive URL normalization and would make the resource unreadable; pick a custom scheme such as \"wiki\"." }).default("zendesk-hc"),
 	/**
 	* Dev-only (stdio): expose the `reload_tools` tool, which re-imports the tool
@@ -1331,8 +1327,7 @@ const htmlToMdProcessor = unified().use(rehypeParse, { fragment: true }).use(reh
 	pre: keepAsHtml
 } }).use(remarkGfm).use(remarkStringify, {
 	bullet: "-",
-	emphasis: "_",
-	fences: true
+	emphasis: "_"
 });
 const mdToHtmlProcessor = unified().use(remarkParse).use(remarkGfm).use(remarkRehype, { allowDangerousHtml: true }).use(rehypeRaw).use(rehypeStringify);
 const htmlToMarkdown = (html) => {
@@ -1450,6 +1445,12 @@ const withName = (id, names) => {
 	const name = names.get(n);
 	return name ? `${name} (${id})` : String(id);
 };
+const formatSubscribersBlock = (ticket, names) => {
+	const line = (label, ids) => `- **${label}**: ${ids.length > 0 ? ids.map((id) => withName(id, names)).join(", ") : "none"}`;
+	const rows = [Array.isArray(ticket.follower_ids) ? line("Followers", ticket.follower_ids) : "", Array.isArray(ticket.email_cc_ids) ? line("Email CCs", ticket.email_cc_ids) : ""].filter(Boolean);
+	if (rows.length === 0) return "";
+	return `\n\n${["### Subscribers", ...rows].join("\n")}`;
+};
 const formatComment = (comment, authors) => {
 	const lines = [`### ${comment.public ? "Public comment" : "Internal note"} (id ${comment.id}) by ${withName(comment.author_id, authors ?? /* @__PURE__ */ new Map())}`, `*${comment.created_at}*`];
 	if (comment.attachments?.length) {
@@ -2042,9 +2043,9 @@ const NAMESPACE_LABELS = {
 //#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];
+	for (let i = 1; i < order.length; i += 1) {
+		const here = order[i - 1];
+		const next = order[i];
 		if (here && next && here.position > next.position) return true;
 	}
 	return false;
@@ -4097,6 +4098,37 @@ const collectAuditIds = (audits) => {
 		groupIds: [...groupIds]
 	};
 };
+const SUBSCRIBER_PARAMS = [{
+	param: "followers",
+	field: "follower_ids"
+}, {
+	param: "email_ccs",
+	field: "email_cc_ids"
+}];
+const toSubscriberActions = (edit) => {
+	if (!edit) return void 0;
+	const removed = new Set(edit.remove);
+	const actions = [...[...new Set(edit.add)].filter((id) => !removed.has(id)).map((id) => ({
+		user_id: id,
+		action: "put"
+	})), ...[...removed].map((id) => ({
+		user_id: id,
+		action: "delete"
+	}))];
+	return actions.length > 0 ? actions : void 0;
+};
+const unappliedActions = (actions, ids) => {
+	const present = Array.isArray(ids) ? new Set(ids) : void 0;
+	return actions.filter(({ user_id, action }) => {
+		if (action === "put") return !present?.has(user_id);
+		return present === void 0 || present.has(user_id);
+	});
+};
+const formatSubscriberOutcome = (sent, after) => {
+	const unconfirmed = SUBSCRIBER_PARAMS.flatMap(({ param, field }) => unappliedActions(sent[param] ?? [], after[field]).map(({ user_id, action }) => `${param} ${action === "put" ? "add" : "remove"} ${user_id}`));
+	if (unconfirmed.length === 0) return "";
+	return `\n\nUnconfirmed: ${unconfirmed.join(", ")}. Zendesk applies followers and email CCs silently: an id it does not know is ignored, and both are ignored entirely when the account's "CCs and followers" setting is off. Check that each id exists with get_user, and the account setting with a Zendesk admin.`;
+};
 const resolveEntityNames = async (subdomain, token, path, key, ids) => {
 	const map = /* @__PURE__ */ new Map();
 	for (const batch of chunk(ids, 100)) try {
@@ -4113,13 +4145,14 @@ const resolveAuditNames = async (subdomain, token, userIds, groupIds) => {
 		groups
 	};
 };
-const resolveCommentAuthors = async (subdomain, token, comments, sideloaded = []) => {
-	const authors = new Map(sideloaded.map((user) => [user.id, user.name]));
-	const missing = [...new Set(comments.map((comment) => comment.author_id))].filter((id) => id > 0 && !authors.has(id));
-	if (missing.length === 0) return authors;
-	for (const [id, name] of await resolveUserNames(subdomain, token, missing)) authors.set(id, name);
-	return authors;
+const resolveUserDisplayNames = async (subdomain, token, ids, sideloaded = []) => {
+	const names = new Map(sideloaded.map((user) => [user.id, user.name]));
+	const missing = [...new Set(ids)].filter((id) => id > 0 && !names.has(id));
+	if (missing.length === 0) return names;
+	for (const [id, name] of await resolveUserNames(subdomain, token, missing)) names.set(id, name);
+	return names;
 };
+const collectSubscriberIds = (ticket) => [...ticket.follower_ids ?? [], ...ticket.email_cc_ids ?? []];
 const DIFF_SKIP_KEYS = /* @__PURE__ */ new Set([
 	"comment",
 	"fields",
@@ -4189,13 +4222,17 @@ const formatMacroPreviewDiff = (ticketId, macroId, before, result) => {
 };
 const createTicketTools = (ctx) => {
 	const { subdomain, getToken } = ctx;
+	const subscriberIdList = (description, max) => {
+		const ids = z.array(z.number().int().positive());
+		return (max === void 0 ? ids : ids.max(max)).optional().describe(description);
+	};
 	return [
 		{
 			name: "get_ticket",
 			namespace: "tickets",
 			readOnly: true,
 			title: "Get Zendesk Ticket",
-			description: "Retrieve a Zendesk ticket by ID, including its live SLA state (per-metric stage and breach countdown) when an SLA policy applies, plus its comments if requested. Returns ticket details (subject, status, priority, assignee, tags, description) and optionally all comments/internal notes. The per-ticket Show endpoint exposes no SLA, so the SLA block is resolved via a scoped search and may be absent for a very high-volume requester or a just-updated ticket; SLA targets and policy conditions live in list_sla_policies. This returns the ticket as it stands now; for the history of changes behind that state (who changed what, and when), use get_ticket_history. The comment thread is appended in one block — the first page of comments Zendesk returns, cut past the response character limit — so on a long ticket read it with list_ticket_comments, which pages the comments and returns the newest first.",
+			description: "Retrieve a Zendesk ticket by ID, including its live SLA state (per-metric stage and breach countdown) when an SLA policy applies, plus its comments if requested. Returns ticket details (subject, status, priority, assignee, tags, description) and optionally all comments/internal notes. It also lists the followers and email CCs on the ticket, resolved to names, which is how you tell who a ticket update actually reaches: followers are notified of updates including internal notes, email CCs take part in the public correspondence, and being the requester makes someone neither. Both lists come back empty on an account where the \"CCs and followers\" setting is not enabled in Zendesk. The per-ticket Show endpoint exposes no SLA, so the SLA block is resolved via a scoped search and may be absent for a very high-volume requester or a just-updated ticket; SLA targets and policy conditions live in list_sla_policies. This returns the ticket as it stands now; for the history of changes behind that state (who changed what, and when), use get_ticket_history. The comment thread is appended in one block — the first page of comments Zendesk returns, cut past the response character limit — so on a long ticket read it with list_ticket_comments, which pages the comments and returns the newest first.",
 			inputSchema: z.object({
 				ticket_id: z.number().int().describe("Ticket ID — the numeric id of the ticket to fetch. Obtain it from search_tickets or list_tickets."),
 				include_comments: z.boolean().default(false).describe("When true, appends the full public comment and internal note thread to the response. Defaults to false to keep the payload small; enable it when you need the conversation, not just the ticket fields. On a long thread prefer list_ticket_comments — this flag appends one unpaginated block, so comments past Zendesk's first page are absent and the rest is cut at the response character limit.")
@@ -4210,15 +4247,14 @@ const createTicketTools = (ctx) => {
 				const { ticket_id, include_comments } = params;
 				const token = await getToken();
 				const { ticket } = await zendeskGet(subdomain, token, `/tickets/${ticket_id}`);
-				let text = formatTicket(ticket) + formatSlaBlock(await fetchTicketSla(subdomain, token, ticket));
-				if (include_comments) {
-					const { comments, users } = await zendeskGet(subdomain, token, `/tickets/${ticket_id}/comments`, {
-						include: "users",
-						include_inline_images: "true"
-					});
-					const authors = await resolveCommentAuthors(subdomain, token, comments ?? [], users);
-					text += `\n\n---\n# Comments\n\n${(comments ?? []).map((comment) => formatComment(comment, authors)).join("\n\n")}`;
-				}
+				const [sla, thread] = await Promise.all([fetchTicketSla(subdomain, token, ticket), include_comments ? zendeskGet(subdomain, token, `/tickets/${ticket_id}/comments`, {
+					include: "users",
+					include_inline_images: "true"
+				}) : void 0]);
+				const comments = thread?.comments ?? [];
+				const names = await resolveUserDisplayNames(subdomain, token, [...collectSubscriberIds(ticket), ...comments.map((comment) => comment.author_id)], thread?.users);
+				const commentsBlock = thread ? `\n\n---\n# Comments\n\n${comments.map((comment) => formatComment(comment, names)).join("\n\n")}` : "";
+				const text = formatTicket(ticket) + formatSlaBlock(sla) + formatSubscribersBlock(ticket, names) + commentsBlock;
 				const advice = include_comments ? `get_ticket appends the thread as one unpaginated block; read it page by page with list_ticket_comments (ticket_id: ${ticket_id}, sort_order: "desc") to get the newest comments first.` : "get_ticket takes no pagination or filter parameters, so this response cannot be narrowed from the call.";
 				return { content: [{
 					type: "text",
@@ -4305,7 +4341,7 @@ const createTicketTools = (ctx) => {
 					type: "text",
 					text: `${meta.has_more ? `No comments on this page of ticket #${ticket_id}. More available (cursor: ${meta.after_cursor}).` : `No comments to show for ticket #${ticket_id}.`}${offsetNote}`
 				}] };
-				const authors = await resolveCommentAuthors(subdomain, token, comments, response.users);
+				const authors = await resolveUserDisplayNames(subdomain, token, comments.map((comment) => comment.author_id), response.users);
 				const body = comments.map((comment) => formatComment(comment, authors)).join("\n\n");
 				const text = `${[
 					`# Comments on ticket #${ticket_id} (${commentPageOrder(comments, sort_order)})`,
@@ -4435,7 +4471,7 @@ const createTicketTools = (ctx) => {
 			namespace: "tickets",
 			readOnly: false,
 			title: "Update Zendesk Ticket",
-			description: "Update an existing ticket (status, priority, type, assignee, group, subject, tags, custom fields). Only the fields you pass are changed, and the updated ticket is returned. Setting tags here replaces the whole tag set — use manage_tags to add or remove individual tags without overwriting the rest. This tool does not post replies: use add_public_comment or add_private_note for that. Find the ticket id via search_tickets or list_tickets.",
+			description: "Update an existing ticket (status, priority, type, assignee, group, subject, tags, custom fields, followers, email CCs). Only the fields you pass are changed, and the updated ticket is returned. Followers and email CCs are incremental instead of replacing: pass { add, remove } lists of user ids, and the response reports who is subscribed afterwards. Zendesk applies those two silently, so a requested change it did not apply comes back listed as unconfirmed rather than raised as an error. Setting tags here replaces the whole tag set — use manage_tags to add or remove individual tags without overwriting the rest. This tool does not post replies: use add_public_comment or add_private_note for that. Find 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 update. Obtain it from search_tickets or list_tickets."),
 				status: z.enum([
@@ -4465,7 +4501,15 @@ 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). Call list_ticket_fields first to discover the numeric field ids and, for dropdown/multiselect fields, the exact option values Zendesk accepts.")
+				})).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."),
+				followers: z.object({
+					add: subscriberIdList("User ids to start following the ticket. Omit to only remove."),
+					remove: subscriberIdList("User ids to stop following the ticket. Omit to only add.")
+				}).strict().optional().describe("Agents to add to or remove from the ticket's follower list, as numeric user ids: { add: [123], remove: [456] }. Followers are notified of ticket updates, internal notes included, so this controls who hears about the ticket. Numeric ids only, no email addresses: resolve the person with search_users first and confirm the match before writing, because a name query can return several users and removing the wrong id succeeds silently. Adding someone already following, or removing someone who is not, is a no-op. An id listed in both add and remove is removed. Omit to leave followers untouched."),
+				email_ccs: z.object({
+					add: subscriberIdList("User ids to CC on the ticket, at most 48. Omit to only remove.", 48),
+					remove: subscriberIdList("User ids to drop from the CC list. Omit to only add.")
+				}).strict().optional().describe("End users or agents to add to or remove from the ticket's email CC list, as numeric user ids: { add: [123], remove: [456] }. CCs receive the ticket's public correspondence, subject to your account's triggers. Numeric ids only, no email addresses: resolve the person with search_users first and confirm the match, because a name query can return several users. Zendesk caps a ticket at 48 email CCs and this tool cannot know how many are already set, so going over shows up as an unconfirmed entry in the response rather than a validation error. An id listed in both add and remove is removed. Omit to leave CCs untouched.")
 			}),
 			annotations: {
 				readOnlyHint: false,
@@ -4474,12 +4518,25 @@ const createTicketTools = (ctx) => {
 				openWorldHint: true
 			},
 			handler: async (params) => {
-				const { ticket_id, ...updates } = params;
+				const { ticket_id, followers, email_ccs, ...updates } = params;
 				const token = await getToken();
-				const { ticket } = await zendeskPut(subdomain, token, `/tickets/${ticket_id}`, { ticket: updates });
+				const sent = {};
+				const followerActions = toSubscriberActions(followers);
+				const ccActions = toSubscriberActions(email_ccs);
+				if (followerActions) sent.followers = followerActions;
+				if (ccActions) sent.email_ccs = ccActions;
+				const { ticket } = await zendeskPut(subdomain, token, `/tickets/${ticket_id}`, { ticket: {
+					...updates,
+					...sent
+				} });
+				let text = `Ticket #${ticket.id} updated.\n\n${formatTicket(ticket)}`;
+				if (followerActions || ccActions) {
+					const names = await resolveUserDisplayNames(subdomain, token, collectSubscriberIds(ticket));
+					text += formatSubscribersBlock(ticket, names) + formatSubscriberOutcome(sent, ticket);
+				}
 				return { content: [{
 					type: "text",
-					text: `Ticket #${ticket.id} updated.\n\n${formatTicket(ticket)}`
+					text
 				}] };
 			}
 		},
@@ -4994,7 +5051,7 @@ const createStrictParamsParser = (schema) => {
 	return (params) => {
 		const result = strict.safeParse(params);
 		if (result.success) return result.data;
-		const unknownKeys = result.error.issues.filter((issue) => issue.code === "unrecognized_keys").flatMap((issue) => issue.keys ?? []);
+		const unknownKeys = result.error.issues.flatMap((issue) => issue.code === "unrecognized_keys" ? issue.keys : []);
 		if (unknownKeys.length > 0) throw new Error(`Unknown parameter(s): ${unknownKeys.join(", ")}. Valid parameters: ${validKeys || "(none)"}.`);
 		throw result.error;
 	};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fruggr/zendesk-mcp-server",
-  "version": "2.22.3",
+  "version": "2.23.0",
   "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",
@@ -76,7 +76,7 @@
     "cheerio": "1.2.0",
     "hast-util-to-html": "9.0.5",
     "hast-util-to-mdast": "10.1.2",
-    "open": "11.0.2",
+    "open": "11.0.4",
     "rehype-parse": "9.0.1",
     "rehype-raw": "7.0.0",
     "rehype-remark": "10.0.1",
@@ -86,10 +86,10 @@
     "remark-rehype": "11.1.2",
     "remark-stringify": "11.0.0",
     "unified": "11.0.5",
-    "zod": "4.6.2"
+    "zod": "4.6.5"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.12",
+    "@biomejs/biome": "2.5.13",
     "@semantic-release/changelog": "^7.0.0",
     "@semantic-release/exec": "^7.1.0",
     "@semantic-release/git": "^11.0.0",