@fruggr/zendesk-mcp-server 2.18.0 → 2.20.0

package/dist/index.js

@@ -118,13 +118,13 @@ const createLogger = (level) => {
 };
 //#endregion
 //#region src/constants.ts
-const CHARACTER_LIMIT = 25e3;
 const positiveIntEnv = (name, fallback) => {
 	const raw = process.env[name];
 	if (raw === void 0 || raw.trim() === "") return fallback;
 	const parsed = Number(raw);
 	return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback;
 };
+const CHARACTER_LIMIT = positiveIntEnv("ZENDESK_CHARACTER_LIMIT", 25e3);
 const ARTICLE_RESOURCES_SCAN_MAX_PAGES = positiveIntEnv("ZENDESK_ARTICLE_RESOURCES_SCAN_MAX_PAGES", 20);
 const MAX_ATTACHMENT_BYTES = positiveIntEnv("ZENDESK_MAX_ATTACHMENT_BYTES", 5242880);
 const MAX_EMBEDDED_IMAGE_COUNT = positiveIntEnv("ZENDESK_MAX_EMBEDDED_IMAGES", 10);
@@ -281,7 +281,6 @@ const startBrowserAuth = (config, logger = silentLogger) => {
 		});
 		const requestedPort = config.callbackPort ?? 27439;
 		const onStartError = (err) => {
-			clearTimeout(authTimeout);
 			const code = err.code;
 			logger.error("oauth_callback_listen_failed", {
 				port: requestedPort,
@@ -1215,9 +1214,9 @@ const markdownToHtml = (markdown) => {
 };
 //#endregion
 //#region src/utils/formatting.ts
-const truncateIfNeeded = (text) => {
-	if (text.length <= 25e3) return text;
-	return `${text.slice(0, CHARACTER_LIMIT)}\n\n--- Response truncated (${text.length} chars, limit ${CHARACTER_LIMIT}). Use pagination or filters to reduce results. ---`;
+const truncateIfNeeded = (text, advice = "Use pagination or filters to reduce results.") => {
+	if (text.length <= CHARACTER_LIMIT) return text;
+	return `${text.slice(0, CHARACTER_LIMIT)}\n\n--- Response truncated (${text.length} chars, limit ${CHARACTER_LIMIT}). ${advice} ---`;
 };
 const formatPagination = (meta) => {
 	const parts = [`Results: ${meta.count}`];
@@ -1303,8 +1302,14 @@ const formatSlaBlock = (entry) => {
 	for (const m of entry.policy_metrics) lines.push(formatSlaMetric(m));
 	return `\n\n${lines.join("\n")}`;
 };
-const formatComment = (comment) => {
-	const lines = [`### ${comment.public ? "Public comment" : "Internal note"} by ${comment.author_id}`, `*${comment.created_at}*`];
+const withName = (id, names) => {
+	const n = Number(id);
+	if (n === -1) return "System (-1)";
+	const name = names.get(n);
+	return name ? `${name} (${id})` : String(id);
+};
+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) {
 		const summary = comment.attachments.map((a) => `#${a.id} (${a.content_type})`).join(", ");
 		lines.push(`Attachments: ${summary}`);
@@ -1340,12 +1345,6 @@ const AUDIT_FIELD_LABELS = {
 	submitter_id: "submitter",
 	group_id: "group"
 };
-const withName = (id, names) => {
-	const n = Number(id);
-	if (n === -1) return "System (-1)";
-	const name = names.get(n);
-	return name ? `${name} (${id})` : String(id);
-};
 const renderAuditValue = (field, value, names) => {
 	if (value === null || value === void 0 || value === "") return "";
 	const entity = AUDIT_ENTITY_FIELDS[field];
@@ -1454,9 +1453,9 @@ const formatContentTag = (tag) => `- **${tag.name}** (${tag.id})`;
 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) => {
+const formatList = (items, formatter, meta, advice) => {
 	const text = [meta ? formatPagination(meta) : "", items.map(formatter).join("\n\n")].filter(Boolean).join("\n\n");
-	return truncateIfNeeded(text);
+	return truncateIfNeeded(text, advice);
 };
 //#endregion
 //#region src/utils/pagination.ts
@@ -1549,7 +1548,7 @@ const fetchArticleMarkdown = async (subdomain, token, id, locale) => {
 		"",
 		htmlToMarkdown(article.body)
 	].join("\n");
-	return truncateIfNeeded(text);
+	return truncateIfNeeded(text, "This resource takes no parameters; read a long article one part at a time with get_article_outline then get_article_section.");
 };
 /**
 * Build an article-resources provider. `listPromoted` holds a memoized-promise
@@ -1795,7 +1794,7 @@ const formatTopology = (data) => {
 		"## Permission groups",
 		...renderAdminSection(data.permissionGroups.map(formatPermissionGroup), data.permissionGroupsDenied, "_Unavailable: listing permission groups requires Guide-admin / Help Center manager rights, which this token lacks (HTTP 403). To create or edit an article, reuse the permission_group_id of an existing article (get_article)._")
 	].join("\n");
-	return truncateIfNeeded(text);
+	return truncateIfNeeded(text, "This resource takes no parameters; walk the tree with list_categories and list_sections instead.");
 };
 /**
 * Build a topology provider holding a memoized-promise cache (TTL
@@ -2026,6 +2025,10 @@ const renderGapVerdict = (report, gapCount, unclassified) => {
 	const allClear = `No gaps: all ${scanned.categories} category/ies and ${scanned.sections} section(s) scanned have a published "${locale}" translation.`;
 	return unclassified > 0 ? `${allClear} This is not a clean bill of health for the whole tree: ${unclassified} other node(s) could not be classified — see the note below.` : allClear;
 };
+const gapAdvice = (report) => {
+	if (!report.categoryScoped) return "find_translation_gaps takes no pagination parameter; narrow the audit to one branch of the tree with category_id instead.";
+	return report.listingIncomplete ? "find_translation_gaps takes no pagination parameter and this category holds more sections than one page, so the section listing is incomplete: list the rest with list_sections (category_id, following its cursor) and read them with list_section_translations." : "find_translation_gaps takes no pagination parameter, and this audit is already scoped to one category: fix the nodes above with set_category_translation / set_section_translation, then re-run it.";
+};
 const renderGapReport = (report) => {
 	const { locale, categoryGaps, sectionGaps, scanned, found } = report;
 	const gapCount = categoryGaps.length + sectionGaps.length;
@@ -2041,8 +2044,8 @@ const renderGapReport = (report) => {
 		"",
 		renderGapVerdict(report, gapCount, unclassified),
 		...unclassified > 0 ? ["", `_Note: ${unclassified} of ${totalFound} node(s) came back without the \`translations\` sideload, so their state is unknown and none of them is reported above (covered: ${scanned.categories}/${found.categories} categories, ${scanned.sections}/${found.sections} sections). Read one of them with list_category_translations / list_section_translations, which query the node directly._`] : [],
-		...report.listingIncomplete ? ["", `_Note: this Help Center has more than 100 categories or sections, so only the first page of each was considered. Narrow the scan with category_id to audit the rest._`] : []
-	].join("\n"));
+		...report.listingIncomplete ? ["", report.categoryScoped ? `_Note: this category holds more than 100 sections, so only the first page was considered. List the rest with list_sections (category_id, following its cursor) and read them with list_section_translations._` : `_Note: this Help Center has more than 100 categories or sections, so only the first page of each was considered. Narrow the scan with category_id to audit the rest._`] : []
+	].join("\n"), gapAdvice(report));
 };
 const largeArticleHint = (body, sectionCount) => {
 	if (body.length < 3e3 && sectionCount < 4) return null;
@@ -2204,7 +2207,7 @@ const createHelpCenterTools = (ctx) => {
 				const text = (largeArticleHint(article.body, parseSections(article.body).length) ?? "") + formatArticle(article) + `\n\n**Available translations**: ${translations.map((t) => t.locale).join(", ")}`;
 				return { content: [{
 					type: "text",
-					text: truncateIfNeeded(text)
+					text: truncateIfNeeded(text, "get_article takes no pagination parameter; read a long article one part at a time with get_article_outline then get_article_section.")
 				}] };
 			}
 		},
@@ -2339,7 +2342,7 @@ const createHelpCenterTools = (ctx) => {
 				const note = scanCostNote(truncated, pagesScanned, cost);
 				return { content: [{
 					type: "text",
-					text: truncateIfNeeded(`${header}\n\n${body}${note}`)
+					text: truncateIfNeeded(`${header}\n\n${body}${note}`, "list_promoted_articles takes no parameters, so this listing cannot be narrowed from the call; read a single article with get_article.")
 				}] };
 			}
 		},
@@ -2362,7 +2365,7 @@ const createHelpCenterTools = (ctx) => {
 				const translations = await listTranslations(subdomain, token, article_id);
 				return { content: [{
 					type: "text",
-					text: formatList(translations, formatTranslationSummary)
+					text: formatList(translations, formatTranslationSummary, void 0, "list_article_translations takes only article_id, so this listing cannot be narrowed from the call; read one locale in full with get_article.")
 				}] };
 			}
 		},
@@ -2448,7 +2451,7 @@ const createHelpCenterTools = (ctx) => {
 				const translations = await listNodeTranslations(subdomain, token, "sections", section_id);
 				return { content: [{
 					type: "text",
-					text: formatList(translations, formatNodeTranslationSummary)
+					text: formatList(translations, formatNodeTranslationSummary, void 0, "list_section_translations takes only section_id, so this listing cannot be narrowed from the call; write one locale with set_section_translation.")
 				}] };
 			}
 		},
@@ -2471,7 +2474,7 @@ const createHelpCenterTools = (ctx) => {
 				const translations = await listNodeTranslations(subdomain, token, "categories", category_id);
 				return { content: [{
 					type: "text",
-					text: formatList(translations, formatNodeTranslationSummary)
+					text: formatList(translations, formatNodeTranslationSummary, void 0, "list_category_translations takes only category_id, so this listing cannot be narrowed from the call; write one locale with set_category_translation.")
 				}] };
 			}
 		},
@@ -2523,7 +2526,8 @@ const createHelpCenterTools = (ctx) => {
 							categories: allCategories.length,
 							sections: allSections.length
 						},
-						listingIncomplete: categoryScope.hasMore || extractPaginationMeta(sectionsRes, allSections.length).has_more
+						listingIncomplete: categoryScope.hasMore || extractPaginationMeta(sectionsRes, allSections.length).has_more,
+						categoryScoped: category_id !== void 0
 					})
 				}] };
 			}
@@ -2610,7 +2614,7 @@ const createHelpCenterTools = (ctx) => {
 				}
 				return { content: [{
 					type: "text",
-					text: formatList(response.permission_groups ?? [], formatPermissionGroup)
+					text: formatList(response.permission_groups ?? [], formatPermissionGroup, void 0, "list_permission_groups takes no parameters, so this listing cannot be narrowed from the call.")
 				}] };
 			}
 		},
@@ -2848,7 +2852,7 @@ const createHelpCenterTools = (ctx) => {
 				const response = await helpCenterGet(subdomain, token, "/articles/labels");
 				return { content: [{
 					type: "text",
-					text: formatList(response.labels ?? [], formatLabel)
+					text: formatList(response.labels ?? [], formatLabel, void 0, "list_labels takes no parameters, so this listing cannot be narrowed from the call.")
 				}] };
 			}
 		},
@@ -2876,7 +2880,7 @@ const createHelpCenterTools = (ctx) => {
 				}
 				return { content: [{
 					type: "text",
-					text: formatList(response.user_segments ?? [], formatUserSegment)
+					text: formatList(response.user_segments ?? [], formatUserSegment, void 0, "list_user_segments takes no parameters, so this listing cannot be narrowed from the call.")
 				}] };
 			}
 		},
@@ -2903,7 +2907,7 @@ const createHelpCenterTools = (ctx) => {
 				}] };
 				return { content: [{
 					type: "text",
-					text: formatList(attachments, formatAttachment)
+					text: formatList(attachments, formatAttachment, void 0, "list_article_attachments takes only article_id, so this listing cannot be narrowed from the call.")
 				}] };
 			}
 		},
@@ -2982,7 +2986,7 @@ const createHelpCenterTools = (ctx) => {
 				].join("\n");
 				return { content: [{
 					type: "text",
-					text: truncateIfNeeded(text)
+					text: truncateIfNeeded(text, format === "markdown" ? "get_article_section takes no pagination parameter, and this single section already exceeds the limit." : "get_article_section takes no pagination parameter; request this section as format=\"markdown\", which renders the same content more compactly than HTML.")
 				}] };
 			}
 		},
@@ -3186,6 +3190,16 @@ const fetchAllTicketComments = async (subdomain, token, ticketId) => {
 	}
 	return all;
 };
+const commentPageMeta = (response, itemCount) => extractPaginationMeta({
+	...response.meta && { meta: response.meta },
+	...response.count !== void 0 && { count: response.count }
+}, itemCount);
+const offsetPageNote = (response) => response.meta?.after_cursor == null && response.next_page != null ? "\n\n> ⚠ Zendesk paginated this response by offset rather than by cursor, so more comments exist beyond this page and no cursor leads to them. This tool pages by cursor only, and no parameter it accepts reaches the rest: read the remaining comments in Zendesk directly." : "";
+const commentPageOrder = (comments, sortOrder) => {
+	const first = comments[0]?.created_at ?? "";
+	const last = comments.at(-1)?.created_at ?? "";
+	return (first === last ? sortOrder === "desc" : first > last) ? "newest first" : "oldest first";
+};
 const fetchAttachmentsByIds = async (subdomain, token, ids) => {
 	const attachments = [];
 	for (const id of ids) try {
@@ -3328,21 +3342,29 @@ const collectAuditIds = (audits) => {
 		groupIds: [...groupIds]
 	};
 };
+const resolveEntityNames = async (subdomain, token, path, key, ids) => {
+	const map = /* @__PURE__ */ new Map();
+	for (const batch of chunk(ids, 100)) try {
+		const res = await zendeskGet(subdomain, token, path, { ids: batch.join(",") });
+		for (const entity of res[key] ?? []) map.set(entity.id, entity.name);
+	} catch {}
+	return map;
+};
+const resolveUserNames = (subdomain, token, ids) => resolveEntityNames(subdomain, token, "/users/show_many", "users", ids);
 const resolveAuditNames = async (subdomain, token, userIds, groupIds) => {
-	const resolve = async (path, key, ids) => {
-		const map = /* @__PURE__ */ new Map();
-		for (const batch of chunk(ids, 100)) try {
-			const res = await zendeskGet(subdomain, token, path, { ids: batch.join(",") });
-			for (const entity of res[key] ?? []) map.set(entity.id, entity.name);
-		} catch {}
-		return map;
-	};
-	const [users, groups] = await Promise.all([resolve("/users/show_many", "users", userIds), resolve("/groups/show_many", "groups", groupIds)]);
+	const [users, groups] = await Promise.all([resolveUserNames(subdomain, token, userIds), resolveEntityNames(subdomain, token, "/groups/show_many", "groups", groupIds)]);
 	return {
 		users,
 		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 DIFF_SKIP_KEYS = /* @__PURE__ */ new Set([
 	"comment",
 	"fields",
@@ -3432,10 +3454,10 @@ const createTicketTools = (ctx) => {
 			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.",
+			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.",
 			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.")
+				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.")
 			}),
 			annotations: {
 				readOnlyHint: true,
@@ -3449,12 +3471,17 @@ const createTicketTools = (ctx) => {
 				const { ticket } = await zendeskGet(subdomain, token, `/tickets/${ticket_id}`);
 				let text = formatTicket(ticket) + formatSlaBlock(await fetchTicketSla(subdomain, token, ticket));
 				if (include_comments) {
-					const { comments } = await zendeskGet(subdomain, token, `/tickets/${ticket_id}/comments`, { include_inline_images: "true" });
-					text += `\n\n---\n# Comments\n\n${comments.map(formatComment).join("\n\n")}`;
+					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 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",
-					text: truncateIfNeeded(text)
+					text: truncateIfNeeded(text, advice)
 				}] };
 			}
 		},
@@ -3463,7 +3490,7 @@ const createTicketTools = (ctx) => {
 			namespace: "tickets",
 			readOnly: true,
 			title: "Get Zendesk Ticket History",
-			description: "Read a ticket's change history — its audit trail — as a chronological, oldest-first timeline of who changed what and when. Each entry shows the actor (name and id) and the channel, then the field changes that update carried (status, priority, assignee, group, tags, custom fields) as before → after, with assignee/requester/group ids resolved to names. Comments appear as one-line presence markers (public comment vs internal note added), not their text — fetch the bodies with get_ticket(include_comments=true). Purely system-generated notification events (trigger emails, collaborator/CC notifications, pushes) are filtered out — note this filters notification delivery, not CC-list edits, which are shown as changes — and an update carrying only such events produces no entry, so the timeline stays a readable narrative rather than a raw log. Use it to answer \"what happened on this ticket?\", \"why was it reassigned?\" or \"when did it go to pending?\", reading oldest-first so the founding context is not missed. Read-only, and cursor-paginated oldest-first: pass the returned cursor to page a long-lived ticket toward its most recent changes.",
+			description: "Read a ticket's change history — its audit trail — as a chronological, oldest-first timeline of who changed what and when. Each entry shows the actor (name and id) and the channel, then the field changes that update carried (status, priority, assignee, group, tags, custom fields) as before → after, with assignee/requester/group ids resolved to names. Comments appear as one-line presence markers (public comment vs internal note added), not their text — fetch the bodies with list_ticket_comments (or get_ticket(include_comments=true) for a short thread). Purely system-generated notification events (trigger emails, collaborator/CC notifications, pushes) are filtered out — note this filters notification delivery, not CC-list edits, which are shown as changes — and an update carrying only such events produces no entry, so the timeline stays a readable narrative rather than a raw log. Use it to answer \"what happened on this ticket?\", \"why was it reassigned?\" or \"when did it go to pending?\", reading oldest-first so the founding context is not missed. Read-only, and cursor-paginated oldest-first: pass the returned cursor to page a long-lived ticket toward its most recent changes.",
 			inputSchema: z.object({
 				ticket_id: z.number().int().describe("Ticket ID — the numeric id of the ticket whose change history to read. Obtain it from search_tickets or list_tickets."),
 				page_size: z.number().int().min(1).max(100).default(100).describe("Audits (ticket updates) per page (1-100, default 100). Each audit is one update to the ticket and may expand to several change lines; audits carrying only system events are dropped, so a page can render fewer entries than this."),
@@ -3503,6 +3530,53 @@ const createTicketTools = (ctx) => {
 				}] };
 			}
 		},
+		{
+			name: "list_ticket_comments",
+			namespace: "tickets",
+			readOnly: true,
+			title: "List Zendesk Ticket Comments",
+			description: "Read a ticket's conversation — public replies and internal notes with their full bodies — one cursor-paginated page at a time, newest comment first. Each entry carries the comment id, the author resolved to a name, the timestamp, whether it is public or internal, and the ids of any attached files. Prefer this over get_ticket(include_comments=true) whenever a thread is long or you only need the latest exchange: get_ticket appends the thread as one unpaginated block and cuts it past the response character limit, which drops the most recent comments first. Keep sort_order \"desc\" (the default) to read the latest reply first and follow the returned cursor to walk further back in time, or pass \"asc\" to replay the conversation forward from the ticket's opening description. For who changed which field and when — without comment bodies — use get_ticket_history; to download the attached files themselves, pass the attachment ids shown here to get_ticket_attachments.",
+			inputSchema: z.object({
+				ticket_id: z.number().int().describe("Ticket ID — the numeric id of the ticket whose conversation to read. Obtain it from search_tickets or list_tickets."),
+				sort_order: z.enum(["asc", "desc"]).default("desc").describe("Chronological direction of the page. \"desc\" (the default) starts at the most recent comment and walks backward in time, which is what you want to see the latest reply; \"asc\" replays the conversation forward, starting from the ticket's opening description — that first comment therefore lands on the last page under \"desc\"."),
+				page_size: z.number().int().min(1).max(100).default(20).describe("Comments per page (1-100, default 20). The default is deliberately small because comment bodies are long and a bigger page risks being cut short by the response character limit; follow the returned cursor rather than raising it."),
+				cursor: z.string().optional().describe("Pagination cursor from a previous response; omit for the first page. Zendesk issues it for the ordering that response used, so after changing sort_order drop the cursor and start again from the first page.")
+			}),
+			annotations: {
+				readOnlyHint: true,
+				destructiveHint: false,
+				idempotentHint: true,
+				openWorldHint: true
+			},
+			handler: async (params) => {
+				const { ticket_id, sort_order, page_size, cursor } = params;
+				const token = await getToken();
+				const response = await zendeskGet(subdomain, token, `/tickets/${ticket_id}/comments`, {
+					...buildCursorParams(page_size, cursor),
+					sort: sort_order === "desc" ? "-created_at" : "created_at",
+					include: "users",
+					include_inline_images: "true"
+				});
+				const comments = response.comments ?? [];
+				const meta = commentPageMeta(response, comments.length);
+				const offsetNote = offsetPageNote(response);
+				if (comments.length === 0) return { content: [{
+					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 body = comments.map((comment) => formatComment(comment, authors)).join("\n\n");
+				const text = `${[
+					`# Comments on ticket #${ticket_id} (${commentPageOrder(comments, sort_order)})`,
+					formatPagination(meta),
+					body
+				].join("\n\n")}${offsetNote}`;
+				return { content: [{
+					type: "text",
+					text: truncateIfNeeded(text, page_size > 1 ? `The comments cut here are not reachable through the cursor, which points past this whole page: re-issue with a page_size smaller than ${page_size} to read them.` : "This single comment is longer than the response character limit, so no page small enough exists: read it in Zendesk directly.")
+				}] };
+			}
+		},
 		{
 			name: "get_ticket_attachments",
 			namespace: "tickets",
@@ -3511,7 +3585,7 @@ const createTicketTools = (ctx) => {
 			description: "Retrieve ticket attachments. Images are embedded inline; other files are listed as text references.",
 			inputSchema: z.object({
 				ticket_id: z.number().int().describe("Ticket ID — the numeric id of the ticket whose attachments to fetch. Obtain it from search_tickets or list_tickets."),
-				attachment_ids: z.array(z.number().int()).optional().describe("Attachment IDs to fetch directly (e.g. extracted from a previous get_ticket(include_comments=true) call). When provided, skips the comments fetch entirely. When omitted, all attachments of the ticket are returned.")
+				attachment_ids: z.array(z.number().int()).optional().describe("Attachment IDs to fetch directly (e.g. extracted from a previous list_ticket_comments or get_ticket(include_comments=true) call). When provided, skips the comments fetch entirely. When omitted, all attachments of the ticket are returned.")
 			}),
 			annotations: {
 				readOnlyHint: true,
@@ -3779,7 +3853,7 @@ const createTicketTools = (ctx) => {
 				const text = incidents.length > 0 ? `# Incidents linked to problem #${problem_id}\n\n${incidents.map(formatTicket).join("\n\n")}` : `No incidents linked to problem #${problem_id}.`;
 				return { content: [{
 					type: "text",
-					text: truncateIfNeeded(text)
+					text: truncateIfNeeded(text, "get_linked_incidents takes no pagination or filter parameters, so this response cannot be narrowed from the call.")
 				}] };
 			}
 		},
@@ -4011,7 +4085,7 @@ const createTicketTools = (ctx) => {
 				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))
+					text: truncateIfNeeded(formatMacroPreviewDiff(ticket_id, macro_id, before, result), "preview_macro_diff takes no pagination or filter parameters; read the macro on its own with list_macros to see every action it carries.")
 				}] };
 			}
 		}
@@ -4544,6 +4618,10 @@ const registerReloadTool = (server, reload, logger = silentLogger) => {
 * `reload_tools` tool that hot-reloads edited tool code on demand. stdio only —
 * HTTP builds a per-session server per request, so there is no long-lived
 * server to hot-swap.
+*
+* Returns the running server so the caller can close it on shutdown: dev mode
+* runs over the same stdio transport as normal mode and must exit the same way
+* when the client disconnects.
 */
 /* v8 ignore start -- runtime bootstrap: binds the reload tool to a real stdio
 transport; the reload machinery it wires up is covered by dev-reload.test.ts */
@@ -4552,6 +4630,7 @@ const startDevServer = async (config, getToken, logger = silentLogger, onUnautho
 	registerReloadTool(server, reload, logger);
 	await startStdioTransport(server, logger);
 	logger.info("dev_mode_enabled");
+	return server;
 };
 /* v8 ignore stop */
 //#endregion
@@ -4907,27 +4986,125 @@ const startHttpTransport = async (config, logger = silentLogger, options = {}) =
 	};
 };
 //#endregion
+//#region src/utils/shutdown.ts
+/**
+* How long a shutdown may take before the watchdog forces the exit.
+*
+* Generous enough for `server.close()` and an HTTP session drain, short enough
+* to stay inside the tightest common supervisor grace — `docker stop` allows 10s
+* and Kubernetes 30s before their own SIGKILL (systemd is far laxer at 90s). A
+* process killed by its supervisor is exactly the unclean exit this removes.
+*/
+const SHUTDOWN_GRACE_MS = 3e3;
+/**
+* Adapt a `process` to a {@link ShutdownRuntime}. Takes the process as an
+* argument rather than closing over the global so the adapter itself is
+* testable — otherwise the one part of this module that touches the real
+* process would be the one part no test can reach.
+*/
+const createRuntime = (proc) => ({
+	on: (event, listener) => {
+		proc.on(event, listener);
+	},
+	stdin: { on: (event, listener) => {
+		proc.stdin.on(event, listener);
+	} },
+	exit: (code) => {
+		proc.exit(code);
+	},
+	setTimer: (fn, ms) => {
+		const timer = setTimeout(fn, ms);
+		return {
+			unref: () => void timer.unref(),
+			clear: () => clearTimeout(timer)
+		};
+	}
+});
+const defaultRuntime = createRuntime(process);
+/**
+* Install the process's one shutdown path and return its trigger.
+*
+* Registering a `SIGTERM` handler *removes* Node's default terminate, which
+* makes the exit our responsibility: a cleanup that stalls on an in-flight
+* request would otherwise leave a process SIGTERM cannot kill — the very
+* symptom this exists to remove. Hence the watchdog, which is load-bearing
+* rather than defensive, and the unconditional `exit` on every path.
+*
+* The exit is explicit rather than a drained event loop because the OAuth
+* callback server (`auth/browser-oauth.ts`) is a listening socket that is not
+* `unref()`'d: letting the loop drain would keep a disconnected session alive
+* for up to the 5-minute auth timeout.
+*/
+const installShutdown = (options) => {
+	const { cleanup, logger, watchStdin, graceMs = SHUTDOWN_GRACE_MS } = options;
+	const runtime = options.runtime ?? defaultRuntime;
+	let started = false;
+	let exited = false;
+	const exitOnce = (code) => {
+		if (exited) return;
+		exited = true;
+		runtime.exit(code);
+	};
+	const shutdown = async (reason) => {
+		if (started) return;
+		started = true;
+		logger.info("shutdown_started", { reason });
+		const watchdog = runtime.setTimer(() => {
+			logger.warn("shutdown_forced", { graceMs });
+			exitOnce(0);
+		}, graceMs);
+		watchdog.unref();
+		try {
+			await cleanup();
+			logger.info("shutdown_complete", { reason });
+		} catch (err) {
+			logger.warn("shutdown_cleanup_failed", { error: err instanceof Error ? err.message : String(err) });
+		} finally {
+			watchdog.clear();
+			exitOnce(0);
+		}
+	};
+	runtime.on("SIGINT", () => void shutdown("SIGINT"));
+	runtime.on("SIGTERM", () => void shutdown("SIGTERM"));
+	if (watchStdin) runtime.stdin.on("end", () => void shutdown("stdin_eof"));
+	return shutdown;
+};
+//#endregion
 //#region src/index.ts
 const buildStdioTokenStore = (config, logger) => createTokenStore({
 	subdomain: config.subdomain,
 	oauthClientId: config.oauthClientId,
 	callbackPort: config.callbackPort
 }, logger);
+const connectStdio = async (config, tokenStore, logger) => {
+	if (config.dev) return startDevServer(config, tokenStore.getToken, logger, tokenStore.invalidate);
+	const server = createMcpServer(config, tokenStore.getToken, logger, tokenStore.invalidate);
+	await startStdioTransport(server, logger);
+	return server;
+};
 const main = async () => {
 	const config = loadConfig();
 	const logger = createLogger(config.logLevel);
 	if (config.transport === "stdio") {
 		const tokenStore = buildStdioTokenStore(config, logger);
-		if (config.dev) {
-			await startDevServer(config, tokenStore.getToken, logger, tokenStore.invalidate);
-			return;
-		}
-		const server = createMcpServer(config, tokenStore.getToken, logger, tokenStore.invalidate);
-		await startStdioTransport(server, logger);
+		const server = await connectStdio(config, tokenStore, logger);
+		installShutdown({
+			watchStdin: true,
+			logger,
+			cleanup: async () => {
+				await server.close();
+				tokenStore.dispose();
+			}
+		});
 		return;
 	}
 	if (config.dev) logger.warn("dev_mode_ignored_http");
-	await startHttpTransport(config, logger);
+	const http = await startHttpTransport(config, logger);
+	installShutdown({
+		watchStdin: false,
+		logger,
+		cleanup: http.close
+	});
 };
 main().catch((error) => {
 	console.error("Fatal error:", error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fruggr/zendesk-mcp-server",
-  "version": "2.18.0",
+  "version": "2.20.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",
@@ -69,13 +69,13 @@
   "engines": {
     "node": ">=20"
   },
-  "packageManager": "pnpm@11.21.0+sha512.521705bce689924eac72f5a3587122f362689ef6571e55ba80076fd637c11132ecffada26fad4ea79c485bfddbfd3d5a2a5b05805a77e893de71ec8a6cca3bb1",
+  "packageManager": "pnpm@11.25.0+sha512.5cde925b4f075f725eb71fbae18a42ffe784524789f19b61c731cb8721ec28aaee160e01a8d5af4fedb2a42cdbf300efe23db356b0d4a17b4d63e11f8ab7c956",
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.0",
     "cheerio": "1.2.0",
     "hast-util-to-html": "9.0.5",
     "hast-util-to-mdast": "10.1.2",
-    "open": "11.0.0",
+    "open": "11.0.1",
     "rehype-parse": "9.0.1",
     "rehype-raw": "7.0.0",
     "rehype-remark": "10.0.1",
@@ -88,15 +88,15 @@
     "zod": "4.4.3"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.7",
+    "@biomejs/biome": "2.5.11",
     "@semantic-release/changelog": "^7.0.0",
     "@semantic-release/exec": "^7.1.0",
     "@semantic-release/git": "^11.0.0",
     "@semantic-release/github": "^12.0.6",
     "@semantic-release/npm": "^13.1.5",
     "@semantic-release/release-notes-generator": "^14.1.1",
-    "@stryker-mutator/core": "^9.6.1",
-    "@stryker-mutator/vitest-runner": "^9.6.1",
+    "@stryker-mutator/core": "^10.0.0",
+    "@stryker-mutator/vitest-runner": "^10.0.0",
     "@tsconfig/node20": "^20.1.9",
     "@tsconfig/strictest": "^2.0.8",
     "@types/hast": "^3.0.4",