@fruggr/zendesk-mcp-server 2.11.0 → 2.12.1

package/dist/index.js

@@ -5,7 +5,7 @@ import { createServer } from "node:http";
 import { homedir, release } from "node:os";
 import open from "open";
 import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import * as z from "zod/v4";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as cheerio from "cheerio";
@@ -19,8 +19,8 @@ import remarkParse from "remark-parse";
 import remarkRehype from "remark-rehype";
 import remarkStringify from "remark-stringify";
 import { unified } from "unified";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 //#region src/utils/logger.ts
 const SEVERITY = {
 	debug: 0,
@@ -600,6 +600,14 @@ const ConfigSchema = z.object({
 	* `help_center` namespace itself is active.
 	*/
 	topology: z.boolean().default(true),
+	/**
+	* Dev-only (stdio): expose the `reload_tools` tool, which re-imports the tool
+	* modules from source and re-registers them on the live session on demand, so
+	* tool code edited during a dev cycle takes effect without a restart. CLI-only
+	* and off by default — it has no place in a deployed server. Fuller notes in
+	* the "Dev mode" section of docs/configuration.md.
+	*/
+	dev: z.boolean().default(false),
 	transport: Transport,
 	host: z.string().min(1),
 	port: z.number().int().min(0).max(65535),
@@ -631,6 +639,7 @@ const parseCliArgs = (args) => {
 			i++;
 		} else if (arg === "--read-only") result.readOnly = true;
 		else if (arg === "--no-topology") result.topology = false;
+		else if (arg === "--dev") result.dev = true;
 		else if (arg === "--namespace" && next) {
 			result.namespaces = result.namespaces ?? [];
 			result.namespaces.push(next);
@@ -689,6 +698,7 @@ const loadConfig = (argv = process.argv.slice(2)) => {
 		namespaces: cli.namespaces,
 		tools: cli.tools,
 		topology: cli.topology ?? true,
+		dev: cli.dev ?? false,
 		transport,
 		host,
 		port,
@@ -858,11 +868,14 @@ const buildInstructions = (config) => {
 	return [
 		`This MCP server is connected to the Zendesk Help Center of "${config.subdomain}".`,
 		"",
-		`Before creating or editing Help Center content, read the resource ${TOPOLOGY_RESOURCE_URI}.`,
-		"It describes the active locales (and the default one), the category → section tree with IDs,",
+		`When creating or editing Help Center content, the resource ${TOPOLOGY_RESOURCE_URI} is useful context:`,
+		"it lists the active locales (and the default one), the category → section tree with IDs,",
 		"the visibility user segments, the permission groups, and your current role.",
-		"Prefer the IDs from that resource (section_id, permission_group_id, user_segment_id, locale)",
-		"over guessing from names."
+		"Prefer its IDs (section_id, permission_group_id, user_segment_id, locale) over guessing from names.",
+		"",
+		"It degrades gracefully: without Guide-admin / Help Center manager rights the permission-groups and",
+		"user-segments sections are marked unavailable (not empty). In that case reuse a permission_group_id",
+		"or user_segment_id from an existing article (get_article) instead."
 	].join("\n");
 };
 //#endregion
@@ -960,6 +973,89 @@ const formatComment = (comment) => {
 	lines.push("", comment.body);
 	return lines.join("\n");
 };
+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 AUDIT_ENTITY_FIELDS = {
+	assignee_id: "user",
+	requester_id: "user",
+	submitter_id: "user",
+	group_id: "group"
+};
+const AUDIT_CREATE_FIELDS = /* @__PURE__ */ new Set([
+	"status",
+	"priority",
+	"type",
+	"assignee_id",
+	"group_id",
+	"subject",
+	"tags"
+]);
+const AUDIT_FIELD_LABELS = {
+	assignee_id: "assignee",
+	requester_id: "requester",
+	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];
+	if (entity === "user") return withName(value, names.users);
+	if (entity === "group") return withName(value, names.groups);
+	if (typeof value === "object" && !Array.isArray(value) && "minutes" in value) {
+		const { minutes } = value;
+		if (typeof minutes === "number") return `${minutes} min`;
+	}
+	return formatFieldValue(value);
+};
+const renderCreateEvent = (event, names) => {
+	const field = event.field_name;
+	if (!field || !AUDIT_CREATE_FIELDS.has(field)) return null;
+	if (field === "tags") {
+		const tags = Array.isArray(event.value) ? event.value.map(String) : [];
+		return tags.length > 0 ? `- **tags**: ${tags.join(", ")}` : null;
+	}
+	const value = renderAuditValue(field, event.value, names);
+	return value === "" ? null : `- **${AUDIT_FIELD_LABELS[field] ?? field}**: ${value}`;
+};
+const renderChangeEvent = (event, names) => {
+	const field = event.field_name;
+	if (!field) return null;
+	if (field === "tags") return formatTagDiff(event.previous_value, event.value);
+	const after = renderAuditValue(field, event.value, names);
+	const before = renderAuditValue(field, event.previous_value, names);
+	if (before === after) return null;
+	return `- **${AUDIT_FIELD_LABELS[field] ?? field}**: ${before || "(none)"} → ${after || "(none)"}`;
+};
+const renderAuditEvent = (event, names) => {
+	switch (event.type) {
+		case "Create": return renderCreateEvent(event, names);
+		case "Change": return renderChangeEvent(event, names);
+		case "Comment":
+		case "VoiceComment": return `- ${event.public === false ? "Internal note" : "Public comment"} added`;
+		case "CommentPrivacyChange": return "- Comment visibility changed";
+		case "FollowersChange": return "- Followers changed";
+		case "EmailCcChange": return "- Email CCs changed";
+		case "SatisfactionRating": return "- Satisfaction rating recorded";
+		default: return null;
+	}
+};
+const formatAudit = (audit, names) => {
+	const lines = audit.events.map((e) => renderAuditEvent(e, names)).filter((l) => l !== null);
+	if (lines.length === 0) return null;
+	const channel = audit.via?.channel ? ` via ${audit.via.channel}` : "";
+	return [`### ${audit.created_at} — ${withName(audit.author_id, names.users)}${channel}`, ...lines].join("\n");
+};
 const formatUser = (user) => [
 	`## ${user.name} (${user.id})`,
 	`- **Email**: ${user.email}`,
@@ -978,6 +1074,7 @@ const formatArticleSummary = (article) => [
 	`## ${article.title} (${article.id})`,
 	`- **Locale**: ${article.locale} | **Source locale**: ${article.source_locale}`,
 	`- **Section**: ${article.section_id} | **Draft**: ${article.draft}`,
+	`- **Permission group**: ${article.permission_group_id} | **User segment**: ${article.user_segment_id ?? "everyone (no segment)"}`,
 	typeof article.position === "number" ? `- **Position**: ${article.position}` : "",
 	article.label_names.length > 0 ? `- **Labels**: ${article.label_names.join(", ")}` : "",
 	`- **Created**: ${article.created_at} | **Updated**: ${article.updated_at}`
@@ -1050,6 +1147,28 @@ const extractSearchPaginationMeta = (response, perPage, page) => {
 //#endregion
 //#region src/guidance/topology.ts
 /**
+* Resolve an admin-gated fetch to a sentinel on HTTP 403 instead of rejecting.
+* Enumerating permission groups and user segments requires Guide-admin / Help
+* Center manager rights — a tier above per-article editing — so a content-editor
+* token gets 403 there while the rest of the topology is readable (#161). Any
+* other failure rethrows; crucially a 401 still propagates so the stale token
+* gets invalidated (see `onUnauthorized` in `createTopologyProvider`).
+*/
+const tolerate403 = async (promise, fallback) => {
+	try {
+		return {
+			value: await promise,
+			denied: false
+		};
+	} catch (error) {
+		if (error instanceof ZendeskApiError && error.status === 403) return {
+			value: fallback,
+			denied: true
+		};
+		throw error;
+	}
+};
+/**
 * Fetch the structural topology with the CALLER'S token, so the result respects
 * that user's read permissions (no privileged shared credential). Categories
 * and sections are each capped at one max-size page; `sectionsHasMore` /
@@ -1057,12 +1176,12 @@ const extractSearchPaginationMeta = (response, perPage, page) => {
 */
 const fetchTopology = async (subdomain, token) => {
 	const pageParams = { "page[size]": String(100) };
-	const [locales, categoriesRes, sectionsRes, segmentsRes, permsRes, meRes] = await Promise.all([
+	const [locales, categoriesRes, sectionsRes, segments, perms, meRes] = await Promise.all([
 		helpCenterGet(subdomain, token, "/locales"),
 		helpCenterGet(subdomain, token, "/categories", pageParams),
 		helpCenterGet(subdomain, token, "/sections", pageParams),
-		helpCenterGet(subdomain, token, "/user_segments"),
-		zendeskGet(subdomain, token, "/guide/permission_groups"),
+		tolerate403(helpCenterGet(subdomain, token, "/user_segments"), { user_segments: [] }),
+		tolerate403(zendeskGet(subdomain, token, "/guide/permission_groups"), { permission_groups: [] }),
 		zendeskGet(subdomain, token, "/users/me")
 	]);
 	const categories = categoriesRes.categories ?? [];
@@ -1074,8 +1193,10 @@ const fetchTopology = async (subdomain, token) => {
 		sections,
 		sectionsHasMore: extractPaginationMeta(sectionsRes, sections.length).has_more,
 		categoriesHasMore: extractPaginationMeta(categoriesRes, categories.length).has_more,
-		userSegments: segmentsRes.user_segments ?? [],
-		permissionGroups: permsRes.permission_groups ?? [],
+		userSegments: segments.value.user_segments ?? [],
+		userSegmentsDenied: segments.denied,
+		permissionGroups: perms.value.permission_groups ?? [],
+		permissionGroupsDenied: perms.denied,
 		currentUser: meRes.user
 	};
 };
@@ -1106,6 +1227,15 @@ const renderTree = (data) => {
 	}
 	return lines.length ? lines : ["_(no categories)_"];
 };
+/**
+* Render an admin-gated section as one of three states so the LLM never mistakes
+* "you can't see this" for "there are none": the formatted list, `_(none)_` when
+* genuinely empty, or `deniedNote` when the token was forbidden (403).
+*/
+const renderAdminSection = (items, denied, deniedNote) => {
+	if (denied) return [deniedNote];
+	return items.length ? items : ["_(none)_"];
+};
 /** Render the topology as a compact Markdown document for the LLM context. */
 const formatTopology = (data) => {
 	return truncateIfNeeded([
@@ -1121,10 +1251,10 @@ const formatTopology = (data) => {
 		...renderTree(data),
 		"",
 		"## Visibility (user segments)",
-		...data.userSegments.length ? data.userSegments.map(formatUserSegment) : ["_(none)_"],
+		...renderAdminSection(data.userSegments.map(formatUserSegment), data.userSegmentsDenied, "_Unavailable: listing user segments requires Guide-admin / Help Center manager rights, which this token lacks (HTTP 403). To set visibility, reuse the user_segment_id of an existing article (get_article), or omit it to default to everyone._"),
 		"",
 		"## Permission groups",
-		...data.permissionGroups.length ? data.permissionGroups.map(formatPermissionGroup) : ["_(none)_"]
+		...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"));
 };
 /**
@@ -1557,9 +1687,16 @@ const createHelpCenterTools = (ctx) => {
 			},
 			handler: async () => {
 				const token = await getToken();
+				let response;
+				try {
+					response = await zendeskGet(subdomain, token, "/guide/permission_groups");
+				} catch (error) {
+					if (error instanceof ZendeskApiError && error.status === 403) throw new Error("list_permission_groups reads Guide permission groups (GET /guide/permission_groups), which Zendesk restricts to Guide admins / Help Center managers. The current token lacks that role (HTTP 403). To obtain a permission_group_id without it, read an existing article with get_article and reuse its permission_group_id.", { cause: error });
+					throw error;
+				}
 				return { content: [{
 					type: "text",
-					text: formatList((await zendeskGet(subdomain, token, "/guide/permission_groups")).permission_groups ?? [], formatPermissionGroup)
+					text: formatList(response.permission_groups ?? [], formatPermissionGroup)
 				}] };
 			}
 		},
@@ -1573,8 +1710,8 @@ const createHelpCenterTools = (ctx) => {
 				section_id: z.number().int().describe("Section that will contain the article (numeric id from list_sections)."),
 				title: z.string().min(1).describe("Title of the new article, in its source locale."),
 				body: z.string().min(1).describe("Article body as HTML (this becomes the source-locale content)."),
-				permission_group_id: z.number().int().describe("Permission group ID (use list_permission_groups to find it)"),
-				user_segment_id: z.number().int().optional().describe("User segment ID for visibility (use list_user_segments to find it). Defaults to everyone."),
+				permission_group_id: z.number().int().describe("Permission group ID (use list_permission_groups to find it; if that is forbidden because the token is not a Guide admin, reuse the permission_group_id of an existing article from get_article)."),
+				user_segment_id: z.number().int().optional().describe("User segment ID for visibility (use list_user_segments to find it; if that is forbidden because the token is not a Guide admin, reuse the user_segment_id of an existing article from get_article). Defaults to everyone."),
 				author_id: z.number().int().optional().describe("Author user ID. Defaults to the authenticated user."),
 				content_tag_ids: z.array(z.string()).optional().describe("Content tag IDs (use list_content_tags to find them)"),
 				locale: z.string().optional().describe("Source locale for the article, e.g. \"en-us\" or \"fr\". Defaults to the Help Center's default locale; becomes the article's source_locale."),
@@ -1610,9 +1747,9 @@ const createHelpCenterTools = (ctx) => {
 				promoted: z.boolean().optional().describe("Set true to promote (feature) the article in its section, or false to unpromote it."),
 				label_names: z.array(z.string()).optional().describe("Label names for search ranking (use list_labels to see existing labels)."),
 				content_tag_ids: z.array(z.string()).optional().describe("Content tag ids to attach (use list_content_tags to find them)."),
-				user_segment_id: z.number().int().optional().describe("User segment that controls who can see the article (id from list_user_segments)."),
+				user_segment_id: z.number().int().optional().describe("User segment that controls who can see the article (id from list_user_segments; if that is forbidden because the token is not a Guide admin, reuse the user_segment_id of an existing article from get_article)."),
 				author_id: z.number().int().optional().describe("User id of the article author (from search_users)."),
-				permission_group_id: z.number().int().optional().describe("Guide permission group controlling who can edit (id from list_permission_groups)."),
+				permission_group_id: z.number().int().optional().describe("Guide permission group controlling who can edit (id from list_permission_groups; if that is forbidden because the token is not a Guide admin, reuse the permission_group_id of an existing article from get_article)."),
 				section_id: z.number().int().optional().describe("Move the article to this section (numeric id from list_sections)."),
 				position: z.number().int().min(0).optional().describe("Sort position within the section (manual ordering only; 0 = first/top). New articles default to position 0. To move an article to the END of its section, set this to one more than the highest current position: read the highest position P from list_articles with sort_by=\"position\", sort_order=\"desc\", then set position = P + 1.")
 			}),
@@ -1754,9 +1891,16 @@ const createHelpCenterTools = (ctx) => {
 			},
 			handler: async () => {
 				const token = await getToken();
+				let response;
+				try {
+					response = await helpCenterGet(subdomain, token, "/user_segments");
+				} catch (error) {
+					if (error instanceof ZendeskApiError && error.status === 403) throw new Error("list_user_segments reads Help Center user segments (GET /help_center/user_segments), which Zendesk restricts to Guide admins / Help Center managers. The current token lacks that role (HTTP 403). To set an article's visibility without it, reuse the user_segment_id of an existing article (get_article), or omit user_segment_id when creating/updating to default to everyone.", { cause: error });
+					throw error;
+				}
 				return { content: [{
 					type: "text",
-					text: formatList((await helpCenterGet(subdomain, token, "/user_segments")).user_segments ?? [], formatUserSegment)
+					text: formatList(response.user_segments ?? [], formatUserSegment)
 				}] };
 			}
 		},
@@ -2172,6 +2316,44 @@ const hydrateViewTickets = async (subdomain, token, ids) => {
 	const byId = new Map((tickets ?? []).map((t) => [t.id, t]));
 	return ids.map((id) => byId.get(id)).filter((t) => t !== void 0);
 };
+const collectAuditIds = (audits) => {
+	const userIds = /* @__PURE__ */ new Set();
+	const groupIds = /* @__PURE__ */ new Set();
+	const addId = (set, raw) => {
+		const n = Number(raw);
+		if (Number.isInteger(n) && n > 0) set.add(n);
+	};
+	for (const audit of audits) {
+		addId(userIds, audit.author_id);
+		for (const event of audit.events) {
+			if (event.type !== "Change" && event.type !== "Create") continue;
+			const entity = event.field_name ? AUDIT_ENTITY_FIELDS[event.field_name] : void 0;
+			if (!entity) continue;
+			const set = entity === "user" ? userIds : groupIds;
+			addId(set, event.value);
+			addId(set, event.previous_value);
+		}
+	}
+	return {
+		userIds: [...userIds],
+		groupIds: [...groupIds]
+	};
+};
+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)]);
+	return {
+		users,
+		groups
+	};
+};
 const DIFF_SKIP_KEYS = /* @__PURE__ */ new Set([
 	"comment",
 	"fields",
@@ -2193,13 +2375,6 @@ const diffLine = (label, before, after) => {
 	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 ?? {};
@@ -2259,7 +2434,7 @@ 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.",
+			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.",
 			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.")
@@ -2285,6 +2460,51 @@ const createTicketTools = (ctx) => {
 				}] };
 			}
 		},
+		{
+			name: "get_ticket_history",
+			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.",
+			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."),
+				cursor: z.string().optional().describe("Pagination cursor from a previous response; omit for the first page. The timeline is ordered oldest-first, so paging forward moves toward the most recent changes.")
+			}),
+			annotations: {
+				readOnlyHint: true,
+				destructiveHint: false,
+				idempotentHint: true,
+				openWorldHint: true
+			},
+			handler: async (params) => {
+				const { ticket_id, page_size, cursor } = params;
+				const token = await getToken();
+				let response;
+				try {
+					response = await zendeskGet(subdomain, token, `/tickets/${ticket_id}/audits`, buildCursorParams(page_size, cursor));
+				} catch (error) {
+					if (error instanceof ZendeskApiError && error.status === 403) throw new Error("get_ticket_history reads the Ticket Audits API (GET /tickets/{id}/audits), which Zendesk gates behind the global 'read' OAuth scope. The current token lacks it (HTTP 403) -- a narrower scope such as tickets:read can read tickets and comments but not their audit history. Re-authenticate with the global read scope to use this tool.", { cause: error });
+					throw error;
+				}
+				const audits = response.audits ?? [];
+				const meta = extractPaginationMeta(response, audits.length);
+				const { userIds, groupIds } = collectAuditIds(audits);
+				const names = await resolveAuditNames(subdomain, token, userIds, groupIds);
+				const blocks = audits.map((audit) => formatAudit(audit, names)).filter((block) => block !== null);
+				if (blocks.length === 0) return { content: [{
+					type: "text",
+					text: meta.has_more ? `No changes to show on this page of ticket #${ticket_id}'s history (system events only). More available (cursor: ${meta.after_cursor}).` : `No change history to show for ticket #${ticket_id}.`
+				}] };
+				return { content: [{
+					type: "text",
+					text: `# Change history for ticket #${ticket_id}\n\n${formatList(blocks, (block) => block, {
+						...meta,
+						count: blocks.length
+					})}`
+				}] };
+			}
+		},
 		{
 			name: "get_ticket_attachments",
 			namespace: "tickets",
@@ -3047,7 +3267,7 @@ const registerProxyTool = (server, toolName, title, tools, readOnlyMode, onUnaut
 	const annotations = aggregateAnnotations(tools);
 	const prefix = readOnlyMode ? "[RO] " : "";
 	const dispatch = buildProxyDispatch(tools, onUnauthorized);
-	server.registerTool(toolName, {
+	return server.registerTool(toolName, {
 		title,
 		description: `${prefix}${title}. Specify the operation and its parameters.\n\nAvailable operations:\n${operationList}`,
 		inputSchema: {
@@ -3057,7 +3277,14 @@ const registerProxyTool = (server, toolName, title, tools, readOnlyMode, onUnaut
 		annotations
 	}, async (args) => dispatch(args));
 };
-const createMcpServer = (config, getToken, logger = silentLogger, onUnauthorized) => {
+/**
+* Build the bare `McpServer` — identity, capabilities, `instructions` and the
+* logging sink — with no tools or resources registered yet. Split out from
+* `createMcpServer` so the dev reload (`dev/reload.ts`) can keep this
+* long-lived shell (and its transport/session) alive while swapping the toolset
+* underneath it via `registerToolset`.
+*/
+const createServerShell = (config, logger = silentLogger) => {
 	const pkg = readPackageInfo();
 	const instructions = buildInstructions(config);
 	const server = new McpServer({
@@ -3068,54 +3295,231 @@ const createMcpServer = (config, getToken, logger = silentLogger, onUnauthorized
 		...instructions ? { instructions } : {}
 	});
 	logger.attachServer(server);
-	const filteredTools = filterTools(createAllTools({
-		subdomain: config.subdomain,
-		getToken
-	}), {
+	return server;
+};
+/**
+* Registers one generation of the toolset (mode/filters applied) plus the
+* optional topology resource onto an existing server, and returns a handle
+* whose `dispose()` removes exactly what this call added. When the SDK server
+* is already connected, each `registerTool`/`remove` emits `list_changed`, so a
+* dispose-then-register cycle hot-swaps the exposed tools in place — this is the
+* mechanism the dev reload (`dev/reload.ts`) uses to reflect edited tool code
+* without dropping the transport. `tools` is passed in (not built here) so the
+* reload path can hand over freshly re-imported definitions.
+*/
+const registerToolset = (server, { config, getToken, onUnauthorized, logger = silentLogger }, tools) => {
+	const registered = [];
+	const dispose = () => {
+		for (const handle of registered) handle.remove();
+	};
+	const filteredTools = filterTools(tools, {
 		readOnly: config.readOnly,
 		namespaces: config.namespaces,
 		tools: config.tools
 	});
-	switch (config.mode) {
-		case "all":
-			for (const tool of filteredTools) server.registerTool(tool.name, {
-				title: tool.title,
-				description: tool.description,
-				inputSchema: tool.inputSchema.strict(),
-				annotations: tool.annotations
-			}, async (params) => runHandler(tool, params, onUnauthorized));
-			break;
-		case "namespace": {
-			const grouped = groupByNamespace(filteredTools);
-			for (const [namespace, tools] of grouped) {
-				const label = NAMESPACE_LABELS[namespace];
-				if (label) registerProxyTool(server, label.toolName, label.title, tools, config.readOnly, onUnauthorized);
+	try {
+		switch (config.mode) {
+			case "all":
+				for (const tool of filteredTools) registered.push(server.registerTool(tool.name, {
+					title: tool.title,
+					description: tool.description,
+					inputSchema: tool.inputSchema.strict(),
+					annotations: tool.annotations
+				}, async (params) => runHandler(tool, params, onUnauthorized)));
+				break;
+			case "namespace": {
+				const grouped = groupByNamespace(filteredTools);
+				for (const [namespace, nsTools] of grouped) {
+					const label = NAMESPACE_LABELS[namespace];
+					if (label) registered.push(registerProxyTool(server, label.toolName, label.title, nsTools, config.readOnly, onUnauthorized));
+				}
+				break;
 			}
-			break;
+			case "single":
+				registered.push(registerProxyTool(server, "zendesk", "Zendesk", filteredTools, config.readOnly, onUnauthorized));
+				break;
 		}
-		case "single":
-			registerProxyTool(server, "zendesk", "Zendesk", filteredTools, config.readOnly, onUnauthorized);
-			break;
-	}
-	if (helpCenterContextEnabled(config)) {
-		const topology = createTopologyProvider(getToken, config.subdomain, onUnauthorized);
-		server.registerResource("help-center-topology", TOPOLOGY_RESOURCE_URI, {
-			title: "Zendesk Help Center topology",
-			description: "Active locales, category → section tree, visibility segments, permission groups, and your role. Read before creating or editing content.",
-			mimeType: "text/markdown"
-		}, async (uri) => ({ contents: [{
-			uri: uri.toString(),
-			mimeType: "text/markdown",
-			text: await topology.read()
-		}] }));
+		if (helpCenterContextEnabled(config)) {
+			const topology = createTopologyProvider(getToken, config.subdomain, onUnauthorized);
+			registered.push(server.registerResource("help-center-topology", TOPOLOGY_RESOURCE_URI, {
+				title: "Zendesk Help Center topology",
+				description: "Active locales, category → section tree, visibility segments, permission groups, and your role. Useful context when creating or editing content; admin-only sections (permission groups, user segments) are marked unavailable rather than empty when your role lacks Guide-admin rights.",
+				mimeType: "text/markdown"
+			}, async (uri) => ({ contents: [{
+				uri: uri.toString(),
+				mimeType: "text/markdown",
+				text: await topology.read()
+			}] })));
+		}
+	} catch (err) {
+		dispose();
+		throw err;
 	}
 	logger.info("tools_registered", {
 		count: filteredTools.length,
 		mode: config.mode
 	});
+	return {
+		count: filteredTools.length,
+		dispose
+	};
+};
+const createMcpServer = (config, getToken, logger = silentLogger, onUnauthorized) => {
+	const server = createServerShell(config, logger);
+	const tools = createAllTools({
+		subdomain: config.subdomain,
+		getToken
+	});
+	registerToolset(server, {
+		config,
+		getToken,
+		onUnauthorized,
+		logger
+	}, tools);
 	return server;
 };
 //#endregion
+//#region src/transports/stdio.ts
+const startStdioTransport = async (server, logger = silentLogger) => {
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+	logger.info("stdio_transport_ready");
+};
+//#endregion
+//#region src/dev/reload.ts
+const toolsDir = join(dirname(fileURLToPath(import.meta.url)), "..", "tools");
+const TOOL_MODULES = [
+	{
+		file: "tickets.ts",
+		factory: "createTicketTools"
+	},
+	{
+		file: "search.ts",
+		factory: "createSearchTools"
+	},
+	{
+		file: "help-center.ts",
+		factory: "createHelpCenterTools"
+	},
+	{
+		file: "users.ts",
+		factory: "createUserTools"
+	}
+];
+/**
+* Re-import every leaf tool-factory module with a fresh cache-busting query so
+* the running process sees edited tool code, then recompose the definitions
+* exactly as `createAllTools` does. A per-call `randomUUID()` nonce keeps the
+* import specifier unique (Node caches modules by specifier, so a repeated
+* query would serve stale code) without any shared module state.
+*/
+const loadFreshTools = async (ctx) => {
+	const nonce = randomUUID();
+	return (await Promise.all(TOOL_MODULES.map(async ({ file, factory }) => {
+		const create = (await import(`${pathToFileURL(join(toolsDir, file)).href}?v=${nonce}`))[factory];
+		/* v8 ignore next 2 -- defensive guard: only hit if a factory export is renamed */
+		if (!create) throw new Error(`Tool module ${file} has no export ${factory}`);
+		return create(ctx);
+	}))).flat();
+};
+/**
+* A server shell plus a `reload()` that swaps in freshly re-imported tool code
+* over the live session and returns the new tool count. Split from
+* `startDevServer` so the reconciliation can be exercised without a transport:
+* the initial toolset is registered from the static import (fast, and reload
+* only matters after an edit); `reload()` disposes the current generation and
+* registers a fresh one.
+*/
+const createReloadableServer = (config, getToken, logger = silentLogger, onUnauthorized, loadTools = loadFreshTools) => {
+	const server = createServerShell(config, logger);
+	const ctx = {
+		subdomain: config.subdomain,
+		getToken
+	};
+	const params = {
+		config,
+		getToken,
+		onUnauthorized,
+		logger
+	};
+	let currentTools = createAllTools(ctx);
+	let current = registerToolset(server, params, currentTools);
+	const reload = async () => {
+		const tools = await loadTools(ctx);
+		current.dispose();
+		try {
+			current = registerToolset(server, params, tools);
+			currentTools = tools;
+		} catch (err) {
+			try {
+				current = registerToolset(server, params, currentTools);
+			} catch (rollbackErr) {
+				logger.error("tools_rollback_failed", { error: rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr) });
+			}
+			throw err;
+		}
+		return current.count;
+	};
+	return {
+		server,
+		reload
+	};
+};
+/**
+* Register the dev-only `reload_tools` meta-tool on the server. It stays
+* registered across reloads (it is NOT part of the disposable toolset
+* generation), so it can always be called again. Its handler triggers a reload
+* and reports the outcome; a failed reload surfaces as a tool error while the
+* previous generation stays live.
+*/
+const registerReloadTool = (server, reload, logger = silentLogger) => {
+	server.registerTool("reload_tools", {
+		title: "Reload tools from source (dev)",
+		description: "Dev only. Re-imports the Zendesk tool modules from source and re-registers them on this live session, so tool code you just edited takes effect without restarting the server or reconnecting the client. Call it once at the end of an edit cycle, before testing your changes; the refreshed tool list is announced via tools/list_changed. Only the tool modules (tickets, search, help_center, users) are reloaded — edits to shared infrastructure (HTTP client, shared definitions, server wiring) still require a full restart. Takes no arguments and makes no Zendesk API calls.",
+		inputSchema: z.object({}).strict(),
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	}, async () => {
+		try {
+			const count = await reload();
+			logger.info("tools_reloaded", { count });
+			return { content: [{
+				type: "text",
+				text: `Reloaded ${count} tool(s) from source. The updated tool list is now live (tools/list_changed sent).`
+			}] };
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			logger.error("tools_reload_failed", { error: message });
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `Reload failed; the previously loaded tools are still live. Fix the error and call reload_tools again: ${message}`
+				}]
+			};
+		}
+	});
+};
+/**
+* Start the stdio server in dev mode: the normal toolset plus a persistent
+* `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.
+*/
+/* 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 */
+const startDevServer = async (config, getToken, logger = silentLogger, onUnauthorized) => {
+	const { server, reload } = createReloadableServer(config, getToken, logger, onUnauthorized);
+	registerReloadTool(server, reload, logger);
+	await startStdioTransport(server, logger);
+	logger.info("dev_mode_enabled");
+};
+/* v8 ignore stop */
+//#endregion
 //#region src/transports/http.ts
 const WILDCARD_HOSTS = /* @__PURE__ */ new Set([
 	"0.0.0.0",
@@ -3461,29 +3865,25 @@ const startHttpTransport = async (config, logger = silentLogger, options = {}) =
 	};
 };
 //#endregion
-//#region src/transports/stdio.ts
-const startStdioTransport = async (server, logger = silentLogger) => {
-	const transport = new StdioServerTransport();
-	await server.connect(transport);
-	logger.info("stdio_transport_ready");
-};
-//#endregion
 //#region src/index.ts
-const buildStdioServer = (config, logger) => {
-	const tokenStore = createTokenStore({
-		subdomain: config.subdomain,
-		oauthClientId: config.oauthClientId,
-		callbackPort: config.callbackPort
-	}, logger);
-	return createMcpServer(config, tokenStore.getToken, logger, tokenStore.invalidate);
-};
+const buildStdioTokenStore = (config, logger) => createTokenStore({
+	subdomain: config.subdomain,
+	oauthClientId: config.oauthClientId,
+	callbackPort: config.callbackPort
+}, logger);
 const main = async () => {
 	const config = loadConfig();
 	const logger = createLogger(config.logLevel);
 	if (config.transport === "stdio") {
-		await startStdioTransport(buildStdioServer(config, logger), logger);
+		const tokenStore = buildStdioTokenStore(config, logger);
+		if (config.dev) {
+			await startDevServer(config, tokenStore.getToken, logger, tokenStore.invalidate);
+			return;
+		}
+		await startStdioTransport(createMcpServer(config, tokenStore.getToken, logger, tokenStore.invalidate), logger);
 		return;
 	}
+	if (config.dev) logger.warn("dev_mode_ignored_http");
 	await startHttpTransport(config, logger);
 };
 main().catch((error) => {