@fruggr/zendesk-mcp-server 2.22.1 → 2.22.3

package/README.md

@@ -152,6 +152,8 @@ waiting for sign-in, so authenticate in the browser and then retry the request.
 The token is persisted to an owner-only file and reused across restarts, so you
 don't authenticate again every time your MCP client respawns the server (path
 and overrides: [`ZENDESK_TOKEN_FILE`](docs/configuration.md#zendesk_token_file)).
+Several instances can run side by side — a read-write one and a `--read-only`
+one, say — without trading credentials.
 
 ### MCP client wiring
 

package/dist/index.js

@@ -176,9 +176,11 @@ const requestedScope = (readOnly) => readOnly ? READ_SCOPE : READ_WRITE_SCOPE;
 const supportedScopes = (readOnly) => scopeTokens(requestedScope(readOnly));
 /**
 * Whether a grant still covers what this process needs: a flat subset test.
-* Coverage, not equality, so a broader token stays usable and two servers
-* sharing a token file converge. A non-string `granted` is a pre-#283 record,
-* i.e. `read write`. No scope hierarchy: granular scopes (#284) replace this.
+* Coverage, not equality, so a token Zendesk granted wider than requested stays
+* usable. A non-string `granted` is a pre-#283 record, i.e. `read write` — only
+* reachable now through a `ZENDESK_TOKEN_FILE` aimed at one by hand, since the
+* default layout no longer names those files. No scope hierarchy: granular
+* scopes (#284) replace this.
 */
 const grantCovers = (granted, requested) => {
 	if (typeof granted !== "string") return true;
@@ -199,11 +201,13 @@ const detectWsl = () => {
 };
 /**
 * Build an actionable error for a callback port that's already taken. The raw
-* Node `EADDRINUSE` is opaque to both the user and the LLM; this spells out the
-* fix (set a free port + register the matching redirect URL in Zendesk). The
-* `(EADDRINUSE)` marker and `code` are kept for diagnostics/tests.
+* Node `EADDRINUSE` is opaque to both the user and the LLM. The port is also
+* the mutex between instances, so retrying once the other sign-in ends comes
+* first and the free-port escape hatch second
+* (`docs/decisions/token-file-keying.md`). The `(EADDRINUSE)` marker and `code`
+* are kept for diagnostics/tests.
 */
-const callbackPortInUseError = (port, cause) => Object.assign(/* @__PURE__ */ new Error(`Cannot start the Zendesk OAuth sign-in: local callback port ${port} is already in use by another process. Set ZENDESK_OAUTH_CALLBACK_PORT (or --callback-port) to a free port, then register http://localhost:<port>/callback as a redirect URL in your Zendesk OAuth client. (EADDRINUSE)`), {
+const callbackPortInUseError = (port, cause) => Object.assign(/* @__PURE__ */ new Error(`Cannot start the Zendesk OAuth sign-in: local callback port ${port} is already in use. Another instance of this server is most likely signing in right now: finish that browser window, then retry. If an unrelated program holds the port, set ZENDESK_OAUTH_CALLBACK_PORT (or --callback-port) to a free port, then register http://localhost:<port>/callback as a redirect URL in your Zendesk OAuth client. (EADDRINUSE)`), {
 	code: "EADDRINUSE",
 	cause
 });
@@ -483,18 +487,31 @@ const configDir = () => {
 	const base = process.env["XDG_CONFIG_HOME"] ?? join(homedir(), ".config");
 	return join(base, ...segments);
 };
-const safeName = (subdomain) => subdomain.replace(/[^a-z0-9-]/gi, "_");
+const safeName = (part) => part.replace(/[^a-z0-9-]/gi, "_");
+const READABLE_BUDGET = 120;
+const keyDigest = (key) => createHash("sha256").update(JSON.stringify([
+	key.subdomain,
+	key.oauthClientId,
+	key.scope
+])).digest("hex").slice(0, 8);
 /**
-* Path to the token file for a subdomain. Each subdomain gets its **own** file
-* (`<subdomain>.json`, a single record) so concurrent processes for different
-* subdomains never read-modify-write a shared file — no merge, no clobber.
-* `ZENDESK_TOKEN_FILE` overrides with an explicit path (a single file; use the
-* default layout for multi-subdomain installs).
+* Path to the token file for one credential. Keyed on the whole `TokenKey`, so
+* a read-only server, a read-write one and one on another OAuth client each get
+* their own record instead of clobbering a shared file. Why that triple, and
+* why no migration from the old subdomain-only layout:
+* `docs/decisions/token-file-keying.md`.
+* `ZENDESK_TOKEN_FILE` overrides with an explicit path — the way to separate
+* two Zendesk accounts that share a subdomain, client and scope.
 */
-const resolveTokenPath = (subdomain) => {
+const resolveTokenPath = (key) => {
 	const override = process.env["ZENDESK_TOKEN_FILE"];
 	if (override) return override;
-	return join(configDir(), `${safeName(subdomain)}.json`);
+	const readable = [
+		key.subdomain,
+		key.oauthClientId,
+		key.scope
+	].map(safeName).join("--").slice(0, READABLE_BUDGET);
+	return join(configDir(), `${readable}--${keyDigest(key)}.json`);
 };
 const writeFileAtomic = (path, record) => {
 	const dir = dirname(path);
@@ -539,8 +556,12 @@ const createAuthRequiredError = (authorizeUrl) => Object.assign(/* @__PURE__ */
 });
 const expiryFrom = (expiresIn) => typeof expiresIn === "number" ? Date.now() + expiresIn * 1e3 : void 0;
 const createTokenStore = (config, logger = silentLogger) => {
-	const tokenPath = resolveTokenPath(config.subdomain);
 	const requested = requestedScope(config.readOnly);
+	const tokenPath = resolveTokenPath({
+		subdomain: config.subdomain,
+		oauthClientId: config.oauthClientId,
+		scope: requested
+	});
 	let token = loadToken(tokenPath);
 	if (token) {
 		if (grantCovers(token.scope, requested)) logger.debug("oauth_token_loaded_from_disk");
@@ -1388,17 +1409,24 @@ const formatMacro = (macro) => {
 		...actions.map(formatMacroAction)
 	].filter(Boolean).join("\n");
 };
-const minutesUntil = (iso) => {
+const minutesUntil = (iso, now) => {
 	const t = Date.parse(iso);
-	return Number.isNaN(t) ? null : Math.round((t - Date.now()) / 6e4);
+	return Number.isNaN(t) ? null : Math.round((t - now) / 6e4);
 };
-const formatSlaMetric = (m) => {
+const STAGES_WITHOUT_LIVE_DEADLINE = /* @__PURE__ */ new Set([
+	"paused",
+	"achieved",
+	"fulfilled"
+]);
+const hasRunningStage = (m) => !STAGES_WITHOUT_LIVE_DEADLINE.has(m.stage);
+const hasPendingDeadline = (m) => hasRunningStage(m) && typeof m.breach_at === "string";
+const formatSlaMetric = (m, now) => {
 	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}`);
+		const remaining = minutesUntil(due, now);
+		if (!hasRunningStage(m) || 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`);
 	}
@@ -1406,10 +1434,14 @@ const formatSlaMetric = (m) => {
 };
 const formatSlaBlock = (entry) => {
 	if (!entry?.policy_metrics || entry.policy_metrics.length === 0) return "";
+	const now = Date.now();
 	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));
+	const soonest = entry.policy_metrics.filter(hasPendingDeadline).map((m) => ({
+		due: m.breach_at,
+		at: Date.parse(m.breach_at)
+	})).filter((d) => !Number.isNaN(d.at) && d.at > now).reduce((best, d) => best && best.at <= d.at ? best : d, void 0);
+	if (soonest) lines.push(`- **Next breach**: ${soonest.due}`);
+	for (const m of entry.policy_metrics) lines.push(formatSlaMetric(m, now));
 	return `\n\n${lines.join("\n")}`;
 };
 const withName = (id, names) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fruggr/zendesk-mcp-server",
-  "version": "2.22.1",
+  "version": "2.22.3",
   "mcpName": "io.github.fruggr/zendesk-mcp-server",
   "description": "Deep Zendesk MCP server for your AI assistant: search, draft, update and translate Help Center articles and manage Support tickets end to end — comments, triage and image attachments.",
   "type": "module",