@fruggr/zendesk-mcp-server 2.10.0 → 2.12.0

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,
@@ -960,6 +970,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}`,
@@ -1000,6 +1093,11 @@ const formatTranslation = (translation) => [
 ].join("\n");
 const formatCategory = (category) => `- **${category.name}** (${category.id}) — ${category.description || "No description"}`;
 const formatSection = (section) => `- **${section.name}** (${section.id}) — Category: ${section.category_id} — ${section.description || "No description"}`;
+const formatView = (view, count) => {
+	const countText = count ? ` — ${count.pretty} ticket(s)${count.fresh ? "" : " (count updating)"}` : "";
+	const description = view.description ? ` — ${view.description}` : "";
+	return `- **${view.title}** (id ${view.id})${countText}${description}`;
+};
 const formatPermissionGroup = (group) => `- **${group.name}** (${group.id})${group.built_in ? " — Built-in" : ""}`;
 const formatContentTag = (tag) => `- **${tag.name}** (${tag.id})`;
 const formatLabel = (label) => `- **${label.name}** (${label.id})`;
@@ -2114,6 +2212,97 @@ const fetchTicketSla = async (subdomain, token, ticket) => {
 		return;
 	}
 };
+const VIEW_COUNT_BATCH = 20;
+const chunk = (items, size) => {
+	const groups = [];
+	for (let i = 0; i < items.length; i += size) groups.push(items.slice(i, i + size));
+	return groups;
+};
+const fetchViewCounts = async (subdomain, token, viewIds) => {
+	const counts = /* @__PURE__ */ new Map();
+	for (const group of chunk(viewIds, VIEW_COUNT_BATCH)) try {
+		const { view_counts } = await zendeskGet(subdomain, token, "/views/count_many", { ids: group.join(",") });
+		for (const c of view_counts ?? []) counts.set(c.view_id, c);
+	} catch {}
+	return counts;
+};
+const resolveViewId = async (subdomain, token, view) => {
+	if (typeof view === "number") return { id: view };
+	const target = view.trim().toLowerCase();
+	const available = [];
+	let cursor;
+	do {
+		const response = await zendeskGet(subdomain, token, "/views", {
+			active: "true",
+			...buildCursorParams(100, cursor)
+		});
+		const views = response.views ?? [];
+		const match = views.find((v) => v.title.trim().toLowerCase() === target);
+		if (match) return { id: match.id };
+		available.push(...views.map((v) => v.title));
+		cursor = response.meta?.has_more ? response.meta.after_cursor ?? void 0 : void 0;
+	} while (cursor);
+	return { available };
+};
+const extractRowTicketId = (row) => {
+	if (typeof row.ticket?.id === "number") return row.ticket.id;
+	for (const key of ["id", "ticket_id"]) if (typeof row[key] === "number") return row[key];
+};
+const executeView = async (subdomain, token, viewId, opts) => {
+	const params = buildCursorParams(opts.page_size, opts.cursor);
+	if (opts.sort_by) params["sort_by"] = opts.sort_by;
+	if (opts.sort_order) params["sort_order"] = opts.sort_order;
+	const response = await zendeskGet(subdomain, token, `/views/${viewId}/execute`, params);
+	const rows = response.rows ?? [];
+	return {
+		rows,
+		meta: extractPaginationMeta(response, rows.length)
+	};
+};
+const hydrateViewTickets = async (subdomain, token, ids) => {
+	if (ids.length === 0) return [];
+	const { tickets } = await zendeskGet(subdomain, token, "/tickets/show_many", { ids: ids.join(",") });
+	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",
@@ -2135,13 +2324,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 ?? {};
@@ -2201,7 +2383,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.")
@@ -2227,6 +2409,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",
@@ -2610,6 +2837,88 @@ const createTicketTools = (ctx) => {
 				}] };
 			}
 		},
+		{
+			name: "list_views",
+			namespace: "tickets",
+			readOnly: true,
+			title: "List Zendesk Views",
+			description: "List the agent's active Zendesk views — the saved ticket queues (\"Unassigned tickets\", \"My open tickets\", \"Breaching today\") the agent sees in the Zendesk UI — each with its current ticket count so you can tell at a glance where the workload sits. Views are per-agent scoped, so per-user auth returns exactly the queues this agent can see, with no shared key. Counts come from Zendesk's cache and can lag by up to about an hour (shown as \"(count updating)\" while a fresh value is still being computed); pass a view's title or id to get_view_tickets to read the tickets inside it.",
+			inputSchema: z.object({
+				page_size: z.number().int().min(1).max(100).default(100).describe("Views per page (1-100, default 100)."),
+				cursor: z.string().optional().describe("Pagination cursor from a previous response; omit for the first page.")
+			}),
+			annotations: {
+				readOnlyHint: true,
+				destructiveHint: false,
+				idempotentHint: true,
+				openWorldHint: true
+			},
+			handler: async (params) => {
+				const { page_size, cursor } = params;
+				const token = await getToken();
+				const response = await zendeskGet(subdomain, token, "/views", {
+					active: "true",
+					...buildCursorParams(page_size, cursor)
+				});
+				const views = response.views ?? [];
+				const counts = await fetchViewCounts(subdomain, token, views.map((v) => v.id));
+				return { content: [{
+					type: "text",
+					text: formatList(views, (view) => formatView(view, counts.get(view.id)), extractPaginationMeta(response, views.length))
+				}] };
+			}
+		},
+		{
+			name: "get_view_tickets",
+			namespace: "tickets",
+			readOnly: true,
+			title: "Get Tickets In A View",
+			description: "Read the tickets inside a Zendesk view, in the view's own configured sort order — the same order the agent sees in the Zendesk UI — which is the natural way to work a named queue like \"Unassigned tickets\" or \"Breaching today\". Accepts the view by title or by numeric id (discover both with list_views); a title is matched case-insensitively against the agent's active views, and on no match the available titles are returned so you can retry in one step. Tickets come back with the same fields as list_tickets and are cursor-paginated; there is no live SLA block here (use search_tickets when you need per-ticket SLA state), and sort_by/sort_order override the view's order when you want a different cut.",
+			inputSchema: z.object({
+				view: z.union([z.string().min(1), z.number().int().positive()]).describe("The view to read: its exact title as shown in Zendesk (e.g. \"Unassigned tickets\") or its numeric id from list_views. A title is matched case-insensitively against your active views; on no match the tool returns the available titles instead of erroring, so you can retry with a correct one."),
+				sort_by: z.string().optional().describe("Optional column to sort by, overriding the view's own sort. Must be one of the view's columns (e.g. \"status\", \"priority\", \"updated_at\", or a custom field id); \"subject\" and \"submitter\" are not sortable. Omit to keep the view's configured order."),
+				sort_order: z.enum(["asc", "desc"]).optional().describe("Sort direction applied to sort_by: \"asc\" (oldest/lowest first) or \"desc\" (newest/highest first). Only meaningful together with sort_by; omit to keep the view's configured direction."),
+				page_size: z.number().int().min(1).max(100).default(100).describe("Tickets per page (1-100, default 100)."),
+				cursor: z.string().optional().describe("Pagination cursor from a previous response; omit for the first page.")
+			}),
+			annotations: {
+				readOnlyHint: true,
+				destructiveHint: false,
+				idempotentHint: true,
+				openWorldHint: true
+			},
+			handler: async (params) => {
+				const { view, sort_by, sort_order, page_size, cursor } = params;
+				const token = await getToken();
+				const resolved = await resolveViewId(subdomain, token, view);
+				if ("available" in resolved) return { content: [{
+					type: "text",
+					text: resolved.available.length > 0 ? `No active view matches "${view}". Available views: ${resolved.available.join(", ")}.` : `No active view matches "${view}", and no active views were found for this agent.`
+				}] };
+				let rows;
+				let meta;
+				try {
+					({rows, meta} = await executeView(subdomain, token, resolved.id, {
+						sort_by,
+						sort_order,
+						page_size,
+						cursor
+					}));
+				} catch (error) {
+					if (error instanceof ZendeskApiError && error.status === 403) throw new Error(`Access denied to view ${resolved.id} (HTTP 403). Zendesk views can be restricted to specific groups, and this agent is not allowed to read this one. Call list_views to see the queues available to this agent.`, { cause: error });
+					throw error;
+				}
+				const ids = rows.map(extractRowTicketId).filter((id) => typeof id === "number");
+				const tickets = await hydrateViewTickets(subdomain, token, ids);
+				return { content: [{
+					type: "text",
+					text: formatList(tickets, formatTicket, {
+						...meta,
+						count: tickets.length
+					})
+				}] };
+			}
+		},
 		{
 			name: "list_macros",
 			namespace: "tickets",
@@ -2907,7 +3216,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: {
@@ -2917,7 +3226,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({
@@ -2928,54 +3244,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. Read before creating or editing content.",
+				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",
@@ -3321,29 +3814,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) => {