@fruggr/zendesk-mcp-server 2.1.0 → 2.3.0

package/README.md

@@ -7,20 +7,55 @@
 [![Renovate enabled](https://img.shields.io/badge/renovate-enabled-brightgreen?logo=renovatebot&logoColor=white)](https://renovatebot.com)
 [![semantic-release](https://img.shields.io/badge/semantic--release-e10079?logo=semantic-release&logoColor=white)](https://github.com/semantic-release/semantic-release)
 
-A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that connects LLMs to the **Zendesk Support & Help Center APIs** — with per-user OAuth 2.1 PKCE authentication and fine-grained tool visibility controls. Runs locally over **stdio** or as a private **remote MCP server** over HTTP.
-
-## Why this server?
-
-Most Zendesk integrations use a shared admin API key, giving every user full access to every ticket. This server takes a different approach:
-
-- **Per-user authentication, OAuth-only** — In both transports, auth is OAuth 2.1 PKCE: each user authenticates with their own Zendesk credentials, so the LLM sees exactly what the user is allowed to see. Static API tokens are deliberately **not** supported (see [below](#what-this-server-does-not-do)).
+**Bring Zendesk Support & the Help Center into your AI assistant.** A
+[Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that lets
+your assistant search articles, answer questions, and create, track and update
+tickets in plain language — **without switching apps**.
+
+Think of it as the [Zendesk agent for Microsoft 365 Copilot](https://support.zendesk.com/hc/en-us/articles/9958331458458-Using-the-Zendesk-agent-in-Microsoft-365-Copilot),
+but **vendor-neutral** — it drops into any MCP client (Claude Desktop, Claude
+Code, Cursor, VS Code, …) instead of being tied to one assistant — and it always
+acts with **each user's own Zendesk permissions**, never a shared admin key.
+
+## What your assistant can do
+
+Ask in natural language; the assistant figures out context and intent, then calls
+the right tools on your behalf:
+
+- **Find answers in the Help Center** — "how do I request a software license?" or
+  "what's the time-off policy?" surfaces the right article, by meaning, not just
+  keywords.
+- **Create, view and update tickets without leaving the conversation** — open a
+  ticket, check its status, add a public reply or an internal note, change the
+  priority or assignee, or mark it solved.
+- **Summarize a ticket for reporting or a quick decision** — pull the details and
+  the full comment thread and get the gist in a sentence.
+- **Search and triage your queue in plain language** — "show me my open tickets
+  about billing from this week."
+- **Draft and maintain knowledge-base articles** — write a new article, or revise
+  a large one **one section at a time** so the whole HTML body never has to
+  round-trip through the model.
+
+Because it runs on the **user's own OAuth session**, the assistant only ever sees
+and touches what that person is allowed to — the same scoping you'd get signing
+into Zendesk directly.
+
+## How it's different
+
+Most Zendesk integrations use a shared admin API key, giving every user full
+access to every ticket, and bolt on a fixed set of tools. This server is built
+differently:
+
+- **Per-user authentication, OAuth-only** — In both transports, auth is OAuth 2.1 PKCE: each user authenticates with their own Zendesk credentials, so the assistant sees exactly what the user is allowed to see. Static API tokens are deliberately **not** supported (see [below](#what-this-server-does-not-do)).
 - **Two deployment shapes, same auth story** — Run it on your laptop as a stdio MCP server (Claude Desktop / Claude Code / VS Code) or deploy it as a private remote MCP server with one user, one Zendesk session per HTTP request.
 - **Context-friendly tool modes** — Expose every operation as its own tool, group them into namespace proxies, or collapse to a single unified tool. Tools are segmented into namespaces you can selectively enable, so each context loads only the surface it needs.
-- **Section-based article editing** — For large Help Center articles, read and rewrite one section at a time (parsed by h1/h2/h3 headings) instead of shuffling the full HTML body through the LLM. Reduces tokens by 10–100× on targeted edits.
+- **Section-based article editing** — For large Help Center articles, read and rewrite one section at a time (parsed by h1/h2/h3 headings) instead of shuffling the full HTML body through the assistant. Reduces tokens by 10–100× on targeted edits.
 - **Read-only mode** — Restrict the server to read operations only, ideal for assistants that should never modify data.
 - **Lean stack** — Built on the official `@modelcontextprotocol/sdk` plus `zod`.
 
-> Built and maintained by [Digital4better](https://digital4better.com) for the [Fruggr](https://www.fruggr.io) project.
+Under the hood it speaks to the **Zendesk Support & Help Center (Guide) APIs**,
+runs locally over **stdio** or as a private **remote MCP server** over HTTP, and
+ships fine-grained tool-visibility controls — the specifics are below.
 
 ## When to use this server
 
@@ -87,11 +122,12 @@ zendesk-mcp-server acme --namespace tickets
 
 | Tool | Description | Mode |
 |------|-------------|------|
-| `get_ticket` | Retrieve a ticket by ID with optional comments | read |
+| `get_ticket` | Retrieve a ticket by ID with optional comments and its live SLA state (resolved via a scoped search) | read |
 | `get_ticket_attachments` | Download ticket attachments (images as base64, others as references) | read |
-| `search_tickets` | Search tickets using Zendesk query syntax | read |
+| `search_tickets` | Search tickets using Zendesk query syntax, with per-result SLA state | read |
 | `list_tickets` | List tickets with cursor-based pagination | read |
 | `get_linked_incidents` | Get incidents linked to a problem ticket | read |
+| `list_sla_policies` | List SLA policies with filter conditions and per-priority targets (requires an admin token, or a custom role with the SLA-management permission) | read |
 | `create_ticket` | Create a new ticket with subject, description, priority, tags... | write |
 | `update_ticket` | Update ticket status, priority, assignee, tags, custom fields | write |
 | `add_private_note` | Add an internal note (not visible to requester) | write |
@@ -224,8 +260,11 @@ file per subdomain in your OS config dir —
 elsewhere; override the path with `ZENDESK_TOKEN_FILE`). It is reused across restarts, so you don't
 re-authenticate every time the MCP client respawns the server. If the Zendesk
 OAuth client has token expiration enabled, the stored refresh token is used to
-renew access silently; only an expired/invalid refresh token triggers a new
-browser sign-in.
+renew access silently — **proactively** (the token is refreshed before use when
+it's expired, near expiry, or of unknown age, so the first request after an
+overnight gap never hits a visible auth error) and **periodically** in the
+background so a long-lived, idle session never serves a stale token. Only an
+expired/invalid refresh token triggers a new browser sign-in.
 
 > **Port conflict?** If port `27439` is already in use the first tool call returns
 > a clear error telling you to set `ZENDESK_OAUTH_CALLBACK_PORT` (or
@@ -648,3 +687,7 @@ Every PR is reviewed automatically by [CodeRabbit](https://www.coderabbit.ai) in
 ## License
 
 [MIT](LICENSE)
+
+---
+
+> Built and maintained by [Digital4better](https://digital4better.com) for the [Fruggr](https://www.fruggr.io) project.

package/dist/index.js

@@ -221,7 +221,7 @@ const startBrowserAuth = (config, logger = silentLogger) => {
 				const tokenData = await tokenResponse.json();
 				logger.info("oauth_authenticated");
 				res.writeHead(200, { "Content-Type": "text/html" });
-				res.end("<html><body><h1>Authentication successful!</h1><p>You can close this tab and return to Claude Code.</p><p>This tab will auto-close in <span id=\"t\">10</span>s.</p><script>let n=10;const el=document.getElementById(\"t\");const i=setInterval(()=>{n--;el.textContent=n;if(n<=0){clearInterval(i);window.close();}},1000);<\/script></body></html>");
+				res.end("<html><body><h1>Authentication successful!</h1><p>You can close this tab and return to your AI assistant.</p><p>This tab will auto-close in <span id=\"t\">10</span>s.</p><script>let n=10;const el=document.getElementById(\"t\");const i=setInterval(()=>{n--;el.textContent=n;if(n<=0){clearInterval(i);window.close();}},1000);<\/script></body></html>");
 				clearTimeout(authTimeout);
 				callbackServer.close();
 				resolveToken(tokenData);
@@ -432,6 +432,7 @@ const clearToken = (path, logger = silentLogger) => {
 //#endregion
 //#region src/auth/token-store.ts
 const EXPIRY_SKEW_MS = 6e4;
+const SCHEDULED_REFRESH_MS = 14400 * 1e3;
 const createAuthRequiredError = (authorizeUrl) => Object.assign(/* @__PURE__ */ new Error("Zendesk authentication required. A browser window should have opened for you to sign in. If it did not, open this URL in your browser, then retry your request:\n" + authorizeUrl), {
 	name: "AuthRequiredError",
 	authorizeUrl
@@ -444,16 +445,18 @@ const createTokenStore = (config, logger = silentLogger) => {
 	let authorizeUrl;
 	let starting;
 	let refreshing;
+	let probedUnknownExpiry = false;
 	const persist = (t) => saveToken(tokenPath, t, logger);
 	const setToken = (accessToken, refreshToken) => {
 		token = {
 			accessToken,
 			refreshToken
 		};
+		probedUnknownExpiry = false;
 		persist(token);
 	};
-	const isExpired = (t) => typeof t.expiresAt === "number" && Date.now() >= t.expiresAt - EXPIRY_SKEW_MS;
-	const tryRefresh = async (current) => {
+	const needsRefresh = (t) => typeof t.expiresAt === "number" ? Date.now() >= t.expiresAt - EXPIRY_SKEW_MS : t.refreshToken !== void 0 && !probedUnknownExpiry;
+	const tryRefresh = async (current, { dropOnFailure = true } = {}) => {
 		if (!current.refreshToken) return void 0;
 		try {
 			const result = await refreshAccessToken({
@@ -466,13 +469,16 @@ const createTokenStore = (config, logger = silentLogger) => {
 				refreshToken: result.refresh_token ?? current.refreshToken,
 				expiresAt: expiryFrom(result.expires_in)
 			};
+			probedUnknownExpiry = true;
 			persist(token);
 			logger.info("oauth_token_refreshed_cached");
 			return token.accessToken;
 		} catch (err) {
 			logger.warn("oauth_token_refresh_failed", { error: err instanceof Error ? err.message : String(err) });
-			token = void 0;
-			clearToken(tokenPath, logger);
+			if (dropOnFailure) {
+				token = void 0;
+				clearToken(tokenPath, logger);
+			}
 			return;
 		}
 	};
@@ -490,6 +496,7 @@ const createTokenStore = (config, logger = silentLogger) => {
 					refreshToken: result.refresh_token,
 					expiresAt: expiryFrom(result.expires_in)
 				};
+				probedUnknownExpiry = true;
 				persist(token);
 				logger.info("oauth_token_cached");
 			}).catch((err) => {
@@ -505,7 +512,8 @@ const createTokenStore = (config, logger = silentLogger) => {
 		});
 	};
 	const getToken = async () => {
-		if (token && !isExpired(token)) {
+		if (refreshing) await refreshing;
+		if (token && !needsRefresh(token)) {
 			logger.debug("oauth_token_cache_hit");
 			return token.accessToken;
 		}
@@ -533,10 +541,18 @@ const createTokenStore = (config, logger = silentLogger) => {
 		}
 		logger.info("oauth_token_invalidated");
 	};
+	const scheduledRefresh = setInterval(() => {
+		if (token?.refreshToken && !refreshing) refreshing = tryRefresh(token, { dropOnFailure: false }).finally(() => {
+			refreshing = void 0;
+		});
+	}, SCHEDULED_REFRESH_MS);
+	scheduledRefresh.unref?.();
+	const dispose = () => clearInterval(scheduledRefresh);
 	return {
 		getToken,
 		setToken,
-		invalidate
+		invalidate,
+		dispose
 	};
 };
 //#endregion
@@ -830,6 +846,43 @@ const formatTicket = (ticket) => [
 	`- **Created**: ${ticket.created_at} | **Updated**: ${ticket.updated_at}`,
 	ticket.description ? `\n${ticket.description}` : ""
 ].filter(Boolean).join("\n");
+const formatConditionValue = (value) => value === null || value === void 0 ? "" : typeof value === "object" ? JSON.stringify(value) : String(value);
+const formatSlaPolicy = (policy) => {
+	const conditions = [...policy.filter.all.map((c) => `all: ${c.field} ${c.operator} ${formatConditionValue(c.value)}`.trim()), ...policy.filter.any.map((c) => `any: ${c.field} ${c.operator} ${formatConditionValue(c.value)}`.trim())];
+	const targets = policy.policy_metrics.map((m) => `  - ${m.priority} / ${m.metric}: ${m.target} min${m.business_hours ? " (business)" : ""}`);
+	return [
+		`## SLA policy: ${policy.title} (${policy.id})`,
+		policy.description ? `- **Description**: ${policy.description}` : "",
+		`- **Position**: ${policy.position}`,
+		conditions.length > 0 ? `- **Conditions**: ${conditions.join("; ")}` : "",
+		targets.length > 0 ? "- **Targets**:" : "",
+		...targets
+	].filter(Boolean).join("\n");
+};
+const minutesUntil = (iso) => {
+	const t = Date.parse(iso);
+	return Number.isNaN(t) ? null : Math.round((t - Date.now()) / 6e4);
+};
+const formatSlaMetric = (m) => {
+	const stage = m.stage ?? "unknown";
+	const due = m.breach_at ?? null;
+	const parts = [`- **${m.metric}** — ${stage}`];
+	if (due) {
+		const remaining = minutesUntil(due);
+		if (stage === "paused" || stage === "achieved" || stage === "fulfilled" || remaining == null) parts.push(`due ${due}`);
+		else if (remaining < 0) parts.push(`due ${due} — breached (${Math.abs(remaining)} min overdue)`);
+		else parts.push(`due ${due} — ${remaining} min remaining`);
+	}
+	return parts.join("; ");
+};
+const formatSlaBlock = (entry) => {
+	if (!entry?.policy_metrics || entry.policy_metrics.length === 0) return "";
+	const lines = ["### SLA"];
+	const futureBreaches = entry.policy_metrics.map((m) => m.breach_at).map((d) => d ? Date.parse(d) : NaN).filter((t) => !Number.isNaN(t) && t > Date.now());
+	if (futureBreaches.length > 0) lines.push(`- **Next breach**: ${new Date(Math.min(...futureBreaches)).toISOString()}`);
+	for (const m of entry.policy_metrics) lines.push(formatSlaMetric(m));
+	return `\n\n${lines.join("\n")}`;
+};
 const formatComment = (comment) => {
 	const lines = [`### ${comment.public ? "Public comment" : "Internal note"} by ${comment.author_id}`, `*${comment.created_at}*`];
 	if (comment.attachments?.length) {
@@ -1891,6 +1944,25 @@ const collectAttachmentBlocks = async (subdomain, token, attachments) => {
 	}
 	return blocks;
 };
+const fetchTicketSla = async (subdomain, token, ticket) => {
+	const day = ticket.created_at.slice(0, 10);
+	if (!/^\d{4}-\d{2}-\d{2}$/.test(day)) return void 0;
+	const shiftDay = (offset) => {
+		const d = /* @__PURE__ */ new Date(`${day}T00:00:00Z`);
+		d.setUTCDate(d.getUTCDate() + offset);
+		return d.toISOString().slice(0, 10);
+	};
+	try {
+		const { results } = await zendeskGet(subdomain, token, "/search", {
+			query: `type:ticket requester:${ticket.requester_id} created>${shiftDay(-1)} created<${shiftDay(1)}`,
+			include: "tickets(slas)",
+			...buildOffsetParams(100, 1)
+		});
+		return (results ?? []).find((r) => r.id === ticket.id)?.slas;
+	} catch {
+		return;
+	}
+};
 const createTicketTools = (ctx) => {
 	const { subdomain, getToken } = ctx;
 	return [
@@ -1899,7 +1971,7 @@ const createTicketTools = (ctx) => {
 			namespace: "tickets",
 			readOnly: true,
 			title: "Get Zendesk Ticket",
-			description: "Retrieve a Zendesk ticket by ID, including its comments if requested. Returns ticket details (subject, status, priority, assignee, tags, description) and optionally all comments/internal notes.",
+			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.",
 			inputSchema: z.object({
 				ticket_id: z.number().int().describe("Ticket ID"),
 				include_comments: z.boolean().default(false).describe("Include ticket comments")
@@ -1914,7 +1986,7 @@ const createTicketTools = (ctx) => {
 				const { ticket_id, include_comments } = params;
 				const token = await getToken();
 				const { ticket } = await zendeskGet(subdomain, token, `/tickets/${ticket_id}`);
-				let text = formatTicket(ticket);
+				let text = formatTicket(ticket) + formatSlaBlock(await fetchTicketSla(subdomain, token, ticket));
 				if (include_comments) {
 					const { comments } = await zendeskGet(subdomain, token, `/tickets/${ticket_id}/comments`);
 					text += `\n\n---\n# Comments\n\n${comments.map(formatComment).join("\n\n")}`;
@@ -1970,7 +2042,7 @@ const createTicketTools = (ctx) => {
 			namespace: "tickets",
 			readOnly: true,
 			title: "Search Zendesk Tickets",
-			description: "Search tickets using Zendesk query syntax (e.g., \"status:open assignee:me\", \"priority:urgent type:incident\"). Returns total count.",
+			description: "Search tickets using Zendesk query syntax, returning each result with its live SLA state (per-metric stage and breach countdown) when an SLA policy applies. Examples: \"status:open assignee:me\", \"priority:urgent type:incident\". Returns total count, so queue triage like \"breaching today\" works without a per-ticket fetch.",
 			inputSchema: z.object({
 				query: z.string().min(1).describe("Zendesk search query string"),
 				per_page: z.number().int().min(1).max(100).default(100).describe("Results per page"),
@@ -1986,11 +2058,13 @@ const createTicketTools = (ctx) => {
 				const { query, per_page, page } = params;
 				const response = await zendeskGet(subdomain, await getToken(), "/search", {
 					query: `type:ticket ${query}`,
+					include: "tickets(slas)",
 					...buildOffsetParams(per_page, page)
 				});
+				const formatTicketWithSla = (ticket) => formatTicket(ticket) + formatSlaBlock(ticket.slas);
 				return { content: [{
 					type: "text",
-					text: formatList(response.results ?? [], formatTicket, extractSearchPaginationMeta(response, per_page, page))
+					text: formatList(response.results ?? [], formatTicketWithSla, extractSearchPaginationMeta(response, per_page, page))
 				}] };
 			}
 		},
@@ -2231,6 +2305,43 @@ const createTicketTools = (ctx) => {
 					text: `Tags updated on ticket #${ticket_id}. Current: ${updated.tags.join(", ") || "none"}`
 				}] };
 			}
+		},
+		{
+			name: "list_sla_policies",
+			namespace: "tickets",
+			readOnly: true,
+			title: "List SLA Policies",
+			description: "List the configured SLA policies with their filter conditions and per-priority reply/resolution targets. Use this to explain why a given target applies to a ticket and to reconstruct deadlines deterministically instead of hard-coding the policy matrix. Requires an admin token (or a custom role granted the SLA-management permission); a standard agent token gets 403 here, though it can still read live per-ticket SLA via get_ticket / search_tickets.",
+			inputSchema: z.object({
+				per_page: z.number().int().min(1).max(100).default(100).describe("Results per page"),
+				page: z.number().int().min(1).default(1).describe("Page number")
+			}),
+			annotations: {
+				readOnlyHint: true,
+				destructiveHint: false,
+				idempotentHint: true,
+				openWorldHint: true
+			},
+			handler: async (params) => {
+				const { per_page, page } = params;
+				const token = await getToken();
+				let response;
+				try {
+					response = await zendeskGet(subdomain, token, "/slas/policies", buildOffsetParams(per_page, page));
+				} catch (error) {
+					if (error instanceof ZendeskApiError && error.status === 403) throw new Error("list_sla_policies reads SLA policy *configuration* (GET /slas/policies), which Zendesk restricts to admins (or a custom role granted the SLA-management permission). The current token lacks that permission (HTTP 403). This does not affect live SLA on tickets: per-metric SLA stage and breach countdown are available to any agent via get_ticket and search_tickets -- use those for triage and prioritization.");
+					throw error;
+				}
+				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
+					})
+				}] };
+			}
 		}
 	];
 };
@@ -2376,6 +2487,13 @@ const createAllTools = (ctx) => [
 * refreshes/re-authenticates instead of replaying a revoked token. The callback
 * is omitted only where there is nothing to invalidate (e.g. HTTP per-session
 * bearer, owned by the client).
+*
+* Client-visible behaviour on an in-flight revocation: the 401 is a *backstop*,
+* not a transparent retry. The current call still surfaces the error; recovery
+* happens on the *next* call, whose `getToken` sees the invalidated token and
+* silently refreshes (or falls back to browser re-auth if the refresh token is
+* also dead). Proactive refresh keeps this path rare — it only fires when a
+* token is revoked between the pre-call refresh check and the request.
 */
 const runHandler = async (def, params, onUnauthorized) => {
 	try {