@fruggr/zendesk-mcp-server 2.10.0 → 2.11.0

package/dist/index.js

@@ -1000,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})`;
@@ -2114,6 +2119,59 @@ 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",
@@ -2610,6 +2668,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",