@fruggr/zendesk-mcp-server 2.9.0 → 2.11.0

package/dist/index.js

@@ -909,6 +909,24 @@ const formatTicketField = (field) => {
 		...options.map((o) => `  - ${o.name} → ${o.value}`)
 	].filter(Boolean).join("\n");
 };
+const formatFieldValue = (value) => Array.isArray(value) ? value.map(formatFieldValue).join(", ") : formatConditionValue(value);
+const MACRO_VALUE_PREVIEW = 120;
+const formatMacroActionValue = (value) => {
+	const oneLine = formatFieldValue(value).replace(/\s+/g, " ").trim();
+	return oneLine.length > MACRO_VALUE_PREVIEW ? `${oneLine.slice(0, MACRO_VALUE_PREVIEW)}…` : oneLine;
+};
+const formatMacroAction = (action) => `  - ${action.field} → ${formatMacroActionValue(action.value)}`;
+const formatMacro = (macro) => {
+	const scope = macro.restriction?.type ? "restricted" : "shared";
+	const actions = macro.actions ?? [];
+	return [
+		`## ${macro.title} (id ${macro.id})`,
+		`- **${macro.active ? "active" : "inactive"}** | **Scope**: ${scope}`,
+		macro.description ? `- **Description**: ${macro.description}` : "",
+		actions.length > 0 ? "- **Actions**:" : "- **Actions**: none",
+		...actions.map(formatMacroAction)
+	].filter(Boolean).join("\n");
+};
 const minutesUntil = (iso) => {
 	const t = Date.parse(iso);
 	return Number.isNaN(t) ? null : Math.round((t - Date.now()) / 6e4);
@@ -982,6 +1000,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})`;
@@ -1010,6 +1033,11 @@ const extractPaginationMeta = (response, itemCount) => ({
 	after_cursor: response.meta?.after_cursor ?? null,
 	count: response.count ?? itemCount
 });
+const extractOffsetPaginationMeta = (response, itemCount, perPage, page) => response.count != null ? extractSearchPaginationMeta(response, perPage, page) : {
+	count: itemCount,
+	has_more: false,
+	after_cursor: null
+};
 const extractSearchPaginationMeta = (response, perPage, page) => {
 	const count = response.count ?? 0;
 	const has_more = count > page * perPage;
@@ -2091,6 +2119,124 @@ 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 DIFF_SKIP_KEYS = /* @__PURE__ */ new Set([
+	"comment",
+	"fields",
+	"custom_fields",
+	"id",
+	"url",
+	"created_at",
+	"updated_at",
+	"generated_timestamp",
+	"encoded_id"
+]);
+const valuesEqual = (a, b) => a === b || JSON.stringify(a) === JSON.stringify(b);
+const shownValue = (v) => {
+	const s = formatFieldValue(v);
+	return s === "" ? "(empty)" : s;
+};
+const diffLine = (label, before, after) => {
+	const b = shownValue(before);
+	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 ?? {};
+	const comment = after.comment ?? result?.comment;
+	const changes = [];
+	for (const [key, afterVal] of Object.entries(after)) {
+		if (DIFF_SKIP_KEYS.has(key)) continue;
+		const beforeVal = beforeObj[key];
+		if (valuesEqual(beforeVal, afterVal)) continue;
+		if (key === "tags") {
+			const tagLine = formatTagDiff(beforeVal, afterVal);
+			if (tagLine) changes.push(tagLine);
+			continue;
+		}
+		if (afterVal !== null && typeof afterVal === "object" && !Array.isArray(afterVal)) continue;
+		const line = diffLine(key, beforeVal, afterVal);
+		if (line) changes.push(line);
+	}
+	const afterFields = [after.fields ?? after.custom_fields ?? []].flat();
+	const beforeById = new Map((before?.custom_fields ?? []).map((f) => [f.id, f.value]));
+	for (const f of afterFields) {
+		const line = diffLine(`custom field ${f.id}`, beforeById.get(f.id), f.value);
+		if (line) changes.push(line);
+	}
+	const lines = [
+		`# Macro #${macroId} preview on ticket #${ticketId} (diff — nothing saved yet)`,
+		"",
+		"## Field changes",
+		...changes.length > 0 ? changes : ["- none"]
+	];
+	if (comment?.body) {
+		const visibility = comment.public === false ? "internal note" : "public comment";
+		lines.push("", `## Reply (${visibility})`, "", comment.body);
+	} else lines.push("", "## Reply", "- none");
+	lines.push("", "## To apply these changes", "Nothing has been committed. Persist the field changes with `update_ticket` (or `manage_tags` for incremental tag edits), and post the reply with `add_public_comment` (public) or `add_private_note` (internal). Edit the reply text first if needed.");
+	return lines.join("\n");
+};
 const createTicketTools = (ctx) => {
 	const { subdomain, getToken } = ctx;
 	const attachmentSchema = z.object({
@@ -2491,11 +2637,7 @@ const createTicketTools = (ctx) => {
 				const policies = response.sla_policies ?? [];
 				return { content: [{
 					type: "text",
-					text: formatList(policies, formatSlaPolicy, response.count != null ? extractSearchPaginationMeta(response, per_page, page) : {
-						count: policies.length,
-						has_more: false,
-						after_cursor: null
-					})
+					text: formatList(policies, formatSlaPolicy, extractOffsetPaginationMeta(response, policies.length, per_page, page))
 				}] };
 			}
 		},
@@ -2525,6 +2667,141 @@ const createTicketTools = (ctx) => {
 					text: formatList(fields, formatTicketField, extractPaginationMeta(response, fields.length))
 				}] };
 			}
+		},
+		{
+			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",
+			readOnly: true,
+			title: "List Zendesk Macros",
+			description: "List the active macros available to the authenticated user. A macro bundles a canned reply and/or a set of field changes (status, priority, assignee, group, tags, custom fields) an agent applies to a ticket in one gesture; this returns each macro id, title, description, availability scope, and its ordered list of actions, offset-paginated. Results are scoped by per-user OAuth to what the current user can see, so no shared admin key is needed. Pass a macro id from here to preview_macro_diff to preview its effect on a specific ticket.",
+			inputSchema: z.object({
+				per_page: z.number().int().min(1).max(100).default(100).describe(PER_PAGE_DESC),
+				page: z.number().int().min(1).default(1).describe(PAGE_DESC)
+			}),
+			annotations: {
+				readOnlyHint: true,
+				destructiveHint: false,
+				idempotentHint: true,
+				openWorldHint: true
+			},
+			handler: async (params) => {
+				const { per_page, page } = params;
+				const token = await getToken();
+				const response = await zendeskGet(subdomain, token, "/macros/active", buildOffsetParams(per_page, page));
+				const macros = response.macros ?? [];
+				return { content: [{
+					type: "text",
+					text: formatList(macros, formatMacro, extractOffsetPaginationMeta(response, macros.length, per_page, page))
+				}] };
+			}
+		},
+		{
+			name: "preview_macro_diff",
+			namespace: "tickets",
+			readOnly: false,
+			title: "Preview a Macro Diff on a Ticket",
+			description: "Preview the exact changes a macro would make to a specific ticket, as a before → after diff, WITHOUT saving anything. Orchestrates two reads — the ticket's current state and Zendesk's macro-apply preview (which returns the whole resulting ticket) — and returns only the fields the macro actually changes (status, priority, assignee, group, tags, custom fields) plus the canned reply with its public/internal flag; unchanged and identity fields are omitted. Nothing is committed: to apply it, follow up with update_ticket for the field changes and add_public_comment or add_private_note for the reply. This deliberate two-step keeps the mutation explicit and reviewable rather than hidden. Find macro ids via list_macros and the ticket id via search_tickets or list_tickets.",
+			inputSchema: z.object({
+				ticket_id: z.number().int().describe("Ticket ID — the numeric id of the ticket to preview the macro against. Obtain it from search_tickets or list_tickets."),
+				macro_id: z.number().int().describe("Macro ID — the numeric id of the macro to preview. Obtain it from list_macros.")
+			}),
+			annotations: {
+				readOnlyHint: false,
+				destructiveHint: false,
+				idempotentHint: true,
+				openWorldHint: true
+			},
+			handler: async (params) => {
+				const { ticket_id, macro_id } = params;
+				const token = await getToken();
+				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))
+				}] };
+			}
 		}
 	];
 };