@lincolnminto/zendesk-mcp-server 2.24.0 → 2.25.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +3 -1
  2. package/dist/index.js +41 -11
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -62,7 +62,9 @@ differently.
62
62
  - A tool surface you can cap. Expose every operation as its own tool, group them
63
63
  into namespace proxies, or collapse everything into a single unified tool. You
64
64
  can also filter by namespace or down to read-only operations, so each context
65
- loads only the surface it needs (see [Tool surface](#tool-surface)).
65
+ loads only the surface it needs (see [Tool surface](#tool-surface)). Read-only
66
+ over stdio also signs in with Zendesk's `read` scope, so Zendesk itself refuses
67
+ a write ([how](docs/configuration.md#read-only-all-the-way-to-zendesk)).
66
68
  - Two deployment shapes, same auth story. Run it on your laptop as a stdio MCP
67
69
  server, or deploy it as a private remote MCP server reached over HTTP, with one
68
70
  Zendesk session per request and each client carrying its own user's token.
package/dist/index.js CHANGED
@@ -307,7 +307,7 @@ const startBrowserAuth = (config, logger = silentLogger) => {
307
307
  response_type: "code",
308
308
  client_id: oauthClientId,
309
309
  redirect_uri: redirectUri,
310
- scope: "read write",
310
+ scope: config.scope ?? "read write",
311
311
  code_challenge: codeChallenge,
312
312
  code_challenge_method: "S256"
313
313
  });
@@ -378,6 +378,12 @@ const refreshAccessToken = async (config, logger = silentLogger) => {
378
378
  return tokenData;
379
379
  };
380
380
  //#endregion
381
+ //#region src/auth/oauth-scope.ts
382
+ const requestedScope = (readOnly) => readOnly ? "read" : "read write";
383
+ const READ_ENTRY = /^(?:read|[a-z_]+:read)$/;
384
+ const WHITESPACE = /\s+/;
385
+ const isReadOnlyScope = (scope) => typeof scope === "string" && scope.trim().split(WHITESPACE).every((entry) => READ_ENTRY.test(entry));
386
+ //#endregion
381
387
  //#region src/utils/package-info.ts
382
388
  const FALLBACK = {
383
389
  name: "@lincolnminto/zendesk-mcp-server",
@@ -444,13 +450,16 @@ const safeName = (subdomain) => subdomain.replace(/[^a-z0-9-]/gi, "_");
444
450
  * Path to the token file for a subdomain. Each subdomain gets its **own** file
445
451
  * (`<subdomain>.json`, a single record) so concurrent processes for different
446
452
  * subdomains never read-modify-write a shared file — no merge, no clobber.
453
+ * A read-only server keeps its `read`-scoped token in `<subdomain>.read.json`,
454
+ * so a read-only and a read-write server on the same subdomain never overwrite
455
+ * each other's token and force a sign-in on every switch.
447
456
  * `ZENDESK_TOKEN_FILE` overrides with an explicit path (a single file; use the
448
- * default layout for multi-subdomain installs).
457
+ * default layout for multi-subdomain or mixed read-only installs).
449
458
  */
450
- const resolveTokenPath = (subdomain) => {
459
+ const resolveTokenPath = (subdomain, { readOnly = false } = {}) => {
451
460
  const override = process.env["ZENDESK_TOKEN_FILE"];
452
461
  if (override) return override;
453
- return join(configDir(), `${safeName(subdomain)}.json`);
462
+ return join(configDir(), `${safeName(subdomain)}${readOnly ? ".read" : ""}.json`);
454
463
  };
455
464
  const writeFileAtomic = (path, record) => {
456
465
  const dir = dirname(path);
@@ -495,8 +504,17 @@ const createAuthRequiredError = (authorizeUrl) => Object.assign(/* @__PURE__ */
495
504
  });
496
505
  const expiryFrom = (expiresIn) => typeof expiresIn === "number" ? Date.now() + expiresIn * 1e3 : void 0;
497
506
  const createTokenStore = (config, logger = silentLogger) => {
498
- const tokenPath = resolveTokenPath(config.subdomain);
499
- let token = loadToken(tokenPath);
507
+ const readOnly = config.readOnly ?? false;
508
+ const tokenPath = resolveTokenPath(config.subdomain, { readOnly });
509
+ const loadUsableToken = () => {
510
+ const loaded = loadToken(tokenPath);
511
+ if (loaded && readOnly && !isReadOnlyScope(loaded.scope)) {
512
+ logger.warn("oauth_token_scope_rejected");
513
+ return;
514
+ }
515
+ return loaded;
516
+ };
517
+ let token = loadUsableToken();
500
518
  if (token) logger.debug("oauth_token_loaded_from_disk");
501
519
  let authorizeUrl;
502
520
  let starting;
@@ -520,10 +538,13 @@ const createTokenStore = (config, logger = silentLogger) => {
520
538
  oauthClientId: config.oauthClientId,
521
539
  refreshToken: current.refreshToken
522
540
  }, logger);
541
+ const scope = result.scope ?? current.scope;
542
+ if (readOnly && !isReadOnlyScope(scope)) throw new Error(`Refreshed token scope is broader than read: ${String(scope)}`);
523
543
  token = {
524
544
  accessToken: result.access_token,
525
545
  refreshToken: result.refresh_token ?? current.refreshToken,
526
- expiresAt: expiryFrom(result.expires_in)
546
+ expiresAt: expiryFrom(result.expires_in),
547
+ scope
527
548
  };
528
549
  probedUnknownExpiry = true;
529
550
  persist(token);
@@ -543,14 +564,21 @@ const createTokenStore = (config, logger = silentLogger) => {
543
564
  return startBrowserAuth({
544
565
  subdomain: config.subdomain,
545
566
  oauthClientId: config.oauthClientId,
546
- callbackPort: config.callbackPort
567
+ callbackPort: config.callbackPort,
568
+ scope: requestedScope(readOnly)
547
569
  }, logger).then((started) => {
548
570
  authorizeUrl = started.authorizeUrl;
549
571
  started.tokenPromise.then((result) => {
572
+ const scope = result.scope ?? requestedScope(readOnly);
573
+ if (readOnly && !isReadOnlyScope(scope)) {
574
+ logger.error("oauth_scope_too_broad", { scope });
575
+ return;
576
+ }
550
577
  token = {
551
578
  accessToken: result.access_token,
552
579
  refreshToken: result.refresh_token,
553
- expiresAt: expiryFrom(result.expires_in)
580
+ expiresAt: expiryFrom(result.expires_in),
581
+ scope
554
582
  };
555
583
  probedUnknownExpiry = true;
556
584
  persist(token);
@@ -592,7 +620,8 @@ const createTokenStore = (config, logger = silentLogger) => {
592
620
  token = {
593
621
  accessToken: token.accessToken,
594
622
  refreshToken: token.refreshToken,
595
- expiresAt: 0
623
+ expiresAt: 0,
624
+ scope: token.scope
596
625
  };
597
626
  persist(token);
598
627
  } else {
@@ -5198,7 +5227,8 @@ const installShutdown = (options) => {
5198
5227
  const buildOAuthTokenSource = (config, logger) => createTokenStore({
5199
5228
  subdomain: config.subdomain,
5200
5229
  oauthClientId: config.oauthClientId,
5201
- callbackPort: config.callbackPort
5230
+ callbackPort: config.callbackPort,
5231
+ readOnly: config.readOnly
5202
5232
  }, logger);
5203
5233
  const buildStdioTokenSource = (config, logger) => {
5204
5234
  if (config.zendeskEmail && config.zendeskApiToken) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lincolnminto/zendesk-mcp-server",
3
- "version": "2.24.0",
3
+ "version": "2.25.0",
4
4
  "mcpName": "io.github.lincolnminto/zendesk-mcp-server",
5
5
  "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.",
6
6
  "type": "module",