@fruggr/zendesk-mcp-server 2.22.2 → 2.23.0

package/README.md

@@ -152,6 +152,8 @@ waiting for sign-in, so authenticate in the browser and then retry the request.
 The token is persisted to an owner-only file and reused across restarts, so you
 don't authenticate again every time your MCP client respawns the server (path
 and overrides: [`ZENDESK_TOKEN_FILE`](docs/configuration.md#zendesk_token_file)).
+Several instances can run side by side — a read-write one and a `--read-only`
+one, say — without trading credentials.
 
 ### MCP client wiring
 

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 {
@@ -176,9 +176,11 @@ const requestedScope = (readOnly) => readOnly ? READ_SCOPE : READ_WRITE_SCOPE;
 const supportedScopes = (readOnly) => scopeTokens(requestedScope(readOnly));
 /**
 * Whether a grant still covers what this process needs: a flat subset test.
-* Coverage, not equality, so a broader token stays usable and two servers
-* sharing a token file converge. A non-string `granted` is a pre-#283 record,
-* i.e. `read write`. No scope hierarchy: granular scopes (#284) replace this.
+* Coverage, not equality, so a token Zendesk granted wider than requested stays
+* usable. A non-string `granted` is a pre-#283 record, i.e. `read write` — only
+* reachable now through a `ZENDESK_TOKEN_FILE` aimed at one by hand, since the
+* default layout no longer names those files. No scope hierarchy: granular
+* scopes (#284) replace this.
 */
 const grantCovers = (granted, requested) => {
 	if (typeof granted !== "string") return true;
@@ -199,11 +201,13 @@ const detectWsl = () => {
 };
 /**
 * Build an actionable error for a callback port that's already taken. The raw
-* Node `EADDRINUSE` is opaque to both the user and the LLM; this spells out the
-* fix (set a free port + register the matching redirect URL in Zendesk). The
-* `(EADDRINUSE)` marker and `code` are kept for diagnostics/tests.
+* Node `EADDRINUSE` is opaque to both the user and the LLM. The port is also
+* the mutex between instances, so retrying once the other sign-in ends comes
+* first and the free-port escape hatch second
+* (`docs/decisions/token-file-keying.md`). The `(EADDRINUSE)` marker and `code`
+* are kept for diagnostics/tests.
 */
-const callbackPortInUseError = (port, cause) => Object.assign(/* @__PURE__ */ new Error(`Cannot start the Zendesk OAuth sign-in: local callback port ${port} is already in use by another process. Set ZENDESK_OAUTH_CALLBACK_PORT (or --callback-port) to a free port, then register http://localhost:<port>/callback as a redirect URL in your Zendesk OAuth client. (EADDRINUSE)`), {
+const callbackPortInUseError = (port, cause) => Object.assign(/* @__PURE__ */ new Error(`Cannot start the Zendesk OAuth sign-in: local callback port ${port} is already in use. Another instance of this server is most likely signing in right now: finish that browser window, then retry. If an unrelated program holds the port, set ZENDESK_OAUTH_CALLBACK_PORT (or --callback-port) to a free port, then register http://localhost:<port>/callback as a redirect URL in your Zendesk OAuth client. (EADDRINUSE)`), {
 	code: "EADDRINUSE",
 	cause
 });
@@ -483,18 +487,31 @@ const configDir = () => {
 	const base = process.env["XDG_CONFIG_HOME"] ?? join(homedir(), ".config");
 	return join(base, ...segments);
 };
-const safeName = (subdomain) => subdomain.replace(/[^a-z0-9-]/gi, "_");
+const safeName = (part) => part.replace(/[^a-z0-9-]/gi, "_");
+const READABLE_BUDGET = 120;
+const keyDigest = (key) => createHash("sha256").update(JSON.stringify([
+	key.subdomain,
+	key.oauthClientId,
+	key.scope
+])).digest("hex").slice(0, 8);
 /**
-* Path to the token file for a subdomain. Each subdomain gets its **own** file
-* (`<subdomain>.json`, a single record) so concurrent processes for different
-* subdomains never read-modify-write a shared file — no merge, no clobber.
-* `ZENDESK_TOKEN_FILE` overrides with an explicit path (a single file; use the
-* default layout for multi-subdomain installs).
+* Path to the token file for one credential. Keyed on the whole `TokenKey`, so
+* a read-only server, a read-write one and one on another OAuth client each get
+* their own record instead of clobbering a shared file. Why that triple, and
+* why no migration from the old subdomain-only layout:
+* `docs/decisions/token-file-keying.md`.
+* `ZENDESK_TOKEN_FILE` overrides with an explicit path — the way to separate
+* two Zendesk accounts that share a subdomain, client and scope.
 */
-const resolveTokenPath = (subdomain) => {
+const resolveTokenPath = (key) => {
 	const override = process.env["ZENDESK_TOKEN_FILE"];
 	if (override) return override;
-	return join(configDir(), `${safeName(subdomain)}.json`);
+	const readable = [
+		key.subdomain,
+		key.oauthClientId,
+		key.scope
+	].map(safeName).join("--").slice(0, READABLE_BUDGET);
+	return join(configDir(), `${readable}--${keyDigest(key)}.json`);
 };
 const writeFileAtomic = (path, record) => {
 	const dir = dirname(path);
@@ -539,8 +556,12 @@ const createAuthRequiredError = (authorizeUrl) => Object.assign(/* @__PURE__ */
 });
 const expiryFrom = (expiresIn) => typeof expiresIn === "number" ? Date.now() + expiresIn * 1e3 : void 0;
 const createTokenStore = (config, logger = silentLogger) => {
-	const tokenPath = resolveTokenPath(config.subdomain);
 	const requested = requestedScope(config.readOnly);
+	const tokenPath = resolveTokenPath({
+		subdomain: config.subdomain,
+		oauthClientId: config.oauthClientId,
+		scope: requested
+	});
 	let token = loadToken(tokenPath);
 	if (token) {
 		if (grantCovers(token.scope, requested)) logger.debug("oauth_token_loaded_from_disk");
@@ -770,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
@@ -1310,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) => {
@@ -1429,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) {
@@ -2021,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;
@@ -4076,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 {
@@ -4092,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",
@@ -4168,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.")
@@ -4189,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",
@@ -4284,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)})`,
@@ -4414,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([
@@ -4444,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,
@@ -4453,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
 				}] };
 			}
 		},
@@ -4973,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.2",
+  "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",