@fruggr/zendesk-mcp-server 2.20.1 → 2.21.0

package/README.md

@@ -126,6 +126,10 @@ Signing in needs a Zendesk OAuth client, so register one first (next section).
      `ZENDESK_OAUTH_CALLBACK_PORT` / `--callback-port` if you override it; Zendesk
      accepts several redirect URLs, one per line)
 
+If the client restricts its **allowed scopes**, it needs `read` — plus `write`
+unless the server runs with [`--read-only`](docs/configuration.md), which asks
+Zendesk for the `read` scope alone.
+
 On the first tool call the server starts the sign-in flow: it opens a browser
 window and returns the authorize URL in a tool message. The call does not block
 waiting for sign-in, so authenticate in the browser and then retry the request.

package/dist/index.js

@@ -129,6 +129,11 @@ const CHARACTER_LIMIT = positiveIntEnv("ZENDESK_CHARACTER_LIMIT", 25e3);
 const ARTICLE_RESOURCES_SCAN_MAX_PAGES = positiveIntEnv("ZENDESK_ARTICLE_RESOURCES_SCAN_MAX_PAGES", 20);
 const MAX_ATTACHMENT_BYTES = positiveIntEnv("ZENDESK_MAX_ATTACHMENT_BYTES", 5242880);
 const MAX_EMBEDDED_IMAGE_COUNT = positiveIntEnv("ZENDESK_MAX_EMBEDDED_IMAGES", 10);
+const STDIO_MAX_MESSAGE_BYTES = 10485760;
+const MESSAGE_CONTENT_BUDGET_BYTES = 10420224;
+const MAX_RESPONSE_BYTES = Math.min(positiveIntEnv("ZENDESK_MAX_RESPONSE_BYTES", MESSAGE_CONTENT_BUDGET_BYTES), MESSAGE_CONTENT_BUDGET_BYTES);
+const MAX_BASE64_INPUT_CHARS = MESSAGE_CONTENT_BUDGET_BYTES;
+const MAX_BASE64_INPUT_MB = Number.parseFloat((MAX_BASE64_INPUT_CHARS / 4 * 3 / 1048576).toFixed(2));
 const MAX_COMMENT_PAGES = positiveIntEnv("ZENDESK_MAX_COMMENT_PAGES", 10);
 const REORDER_CONFIRM_THRESHOLD = positiveIntEnv("ZENDESK_REORDER_CONFIRM_THRESHOLD", 20);
 const getBaseUrl = (subdomain) => `https://${subdomain}.zendesk.com/api/v2`;
@@ -138,6 +143,48 @@ const getOAuthUrls = (subdomain) => ({
 	tokenUrl: `https://${subdomain}.zendesk.com/oauth/tokens`
 });
 //#endregion
+//#region src/auth/oauth-scopes.ts
+/**
+* The OAuth scope the server asks Zendesk for, and the one predicate that
+* decides whether a cached token's grant is still good enough.
+*
+* Both scope strings live here rather than in `constants.ts` on purpose: they
+* are behavioural strings whose mutants must be killed by assertions
+* (`docs/decisions/mutation-testing.md`, "OAuth parameters and scopes"), and
+* `src/auth/**` is inside the mutation scope while `constants.ts` is not.
+* Keeping them next to the predicate that consumes them keeps both under the
+* same gate.
+*/
+const READ_SCOPE = "read";
+const READ_WRITE_SCOPE = "read write";
+const WHITESPACE = /\s+/;
+const scopeTokens = (scope) => scope.split(WHITESPACE).filter((s) => s.length > 0);
+/**
+* The scope to request for a given tool surface. `--read-only` already filters
+* every write tool out of the surface, so asking Zendesk for `write` on top of
+* that would be requesting an authority the server cannot even exercise — and
+* an OAuth client whose allowed scopes stop at `read` rejects the whole
+* authorize request with `invalid_scope`, minting no token at all (#283).
+*/
+const requestedScope = (readOnly) => readOnly ? READ_SCOPE : READ_WRITE_SCOPE;
+/**
+* The same decision as a list, for the RFC 9728 / RFC 8414 `scopes_supported`
+* metadata. Derived from `requestedScope` so what the HTTP transport advertises
+* provably cannot drift from what the stdio flow requests.
+*/
+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.
+*/
+const grantCovers = (granted, requested) => {
+	if (typeof granted !== "string") return true;
+	const held = new Set(scopeTokens(granted));
+	return scopeTokens(requested).every((token) => held.has(token));
+};
+//#endregion
 //#region src/auth/browser-oauth.ts
 const AUTH_TIMEOUT_MS = 3e5;
 /** Best-effort WSL detection: WSL kernels carry "microsoft" in /proc/version. */
@@ -180,7 +227,7 @@ const generateCodeChallenge = (verifier) => createHash("sha256").update(verifier
 * open for up to the 5-minute timeout.
 */
 const startBrowserAuth = (config, logger = silentLogger) => {
-	const { subdomain, oauthClientId } = config;
+	const { subdomain, oauthClientId, readOnly } = config;
 	const { authorizeUrl: authorizeBase, tokenUrl } = getOAuthUrls(subdomain);
 	const codeVerifier = generateCodeVerifier();
 	const codeChallenge = generateCodeChallenge(codeVerifier);
@@ -303,7 +350,7 @@ const startBrowserAuth = (config, logger = silentLogger) => {
 				response_type: "code",
 				client_id: oauthClientId,
 				redirect_uri: redirectUri,
-				scope: "read write",
+				scope: requestedScope(readOnly),
 				code_challenge: codeChallenge,
 				code_challenge_method: "S256"
 			});
@@ -492,8 +539,18 @@ 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);
 	let token = loadToken(tokenPath);
-	if (token) logger.debug("oauth_token_loaded_from_disk");
+	if (token) {
+		if (grantCovers(token.scope, requested)) logger.debug("oauth_token_loaded_from_disk");
+		else {
+			logger.warn("oauth_token_scope_insufficient", {
+				requested,
+				granted: token.scope
+			});
+			token = void 0;
+		}
+	}
 	let authorizeUrl;
 	let starting;
 	let refreshing;
@@ -502,12 +559,20 @@ const createTokenStore = (config, logger = silentLogger) => {
 	const setToken = (accessToken, refreshToken) => {
 		token = {
 			accessToken,
-			refreshToken
+			refreshToken,
+			scope: requested
 		};
 		probedUnknownExpiry = false;
 		persist(token);
 	};
 	const needsRefresh = (t) => typeof t.expiresAt === "number" ? Date.now() >= t.expiresAt - EXPIRY_SKEW_MS : t.refreshToken !== void 0 && !probedUnknownExpiry;
+	const noteGrant = (granted) => {
+		if (!grantCovers(granted, requested)) logger.warn("oauth_token_grant_narrowed", {
+			requested,
+			granted
+		});
+		return granted;
+	};
 	const tryRefresh = async (current, { dropOnFailure = true } = {}) => {
 		if (!current.refreshToken) return void 0;
 		try {
@@ -519,7 +584,8 @@ const createTokenStore = (config, logger = silentLogger) => {
 			token = {
 				accessToken: result.access_token,
 				refreshToken: result.refresh_token ?? current.refreshToken,
-				expiresAt: expiryFrom(result.expires_in)
+				expiresAt: expiryFrom(result.expires_in),
+				scope: noteGrant(result.scope || current.scope)
 			};
 			probedUnknownExpiry = true;
 			persist(token);
@@ -539,14 +605,16 @@ const createTokenStore = (config, logger = silentLogger) => {
 		return startBrowserAuth({
 			subdomain: config.subdomain,
 			oauthClientId: config.oauthClientId,
-			callbackPort: config.callbackPort
+			callbackPort: config.callbackPort,
+			readOnly: config.readOnly
 		}, logger).then((started) => {
 			authorizeUrl = started.authorizeUrl;
 			started.tokenPromise.then((result) => {
 				token = {
 					accessToken: result.access_token,
 					refreshToken: result.refresh_token,
-					expiresAt: expiryFrom(result.expires_in)
+					expiresAt: expiryFrom(result.expires_in),
+					scope: noteGrant(result.scope || requested)
 				};
 				probedUnknownExpiry = true;
 				persist(token);
@@ -588,7 +656,8 @@ const createTokenStore = (config, logger = silentLogger) => {
 			token = {
 				accessToken: token.accessToken,
 				refreshToken: token.refreshToken,
-				expiresAt: 0
+				expiresAt: 0,
+				scope: token.scope
 			};
 			persist(token);
 		} else {
@@ -3083,7 +3152,10 @@ const createHelpCenterTools = (ctx) => {
 			inputSchema: z.object({
 				article_id: z.number().int().describe(ARTICLE_ID_DESC),
 				file_name: z.string().min(1).describe("Name to store the file under, including its extension (e.g. \"screenshot.png\"); used as the download name."),
-				file_base64: z.string().min(1).describe("The file's raw bytes as a base64-encoded string; the server decodes them before upload."),
+				file_base64: z.string().min(1).max(MAX_BASE64_INPUT_CHARS, {
+					abort: true,
+					error: (issue) => `File too large: ${issue.input.length} base64 characters, limit ${MAX_BASE64_INPUT_CHARS}. Downscale the file, split it, or host it elsewhere and link to it.`
+				}).describe(`The file's raw bytes as a base64-encoded string; the server decodes them before upload. At most ${MAX_BASE64_INPUT_CHARS} characters (about ${MAX_BASE64_INPUT_MB} MB of file); the HTTP transport additionally caps request bodies at 4 MB.`),
 				content_type: z.string().default("application/octet-stream").describe("MIME type of the file, e.g. \"image/png\" or \"application/pdf\". Defaults to application/octet-stream when omitted.")
 			}),
 			annotations: {
@@ -3163,6 +3235,28 @@ const createSearchTools = (ctx) => {
 //#endregion
 //#region src/tools/tickets.ts
 const MAX_ATTACHMENT_MB = Number.parseFloat((MAX_ATTACHMENT_BYTES / 1048576).toFixed(2));
+const MAX_RESPONSE_MB = Number.parseFloat((MAX_RESPONSE_BYTES / 1048576).toFixed(2));
+const blockCost = (block) => block.type === "image" ? Buffer.byteLength(JSON.stringify({
+	...block,
+	data: ""
+}), "utf8") + block.data.length + 1 : Buffer.byteLength(JSON.stringify(block), "utf8") + 1;
+const embeddedCost = (attachment, reference) => blockCost({
+	type: "image",
+	data: "",
+	mimeType: attachment.content_type
+}) + 4 * Math.ceil(attachment.size / 3) + blockCost({
+	type: "text",
+	text: reference
+});
+const BUDGET_REACHED = `skipped: response budget of ${MAX_RESPONSE_MB} MB reached`;
+const referenceBlock = (reference, skipReason) => ({
+	type: "text",
+	text: skipReason ? `${reference} — ${skipReason}` : reference
+});
+const truncationNotice = (omitted) => ({
+	type: "text",
+	text: `${omitted} further attachments omitted: response budget of ${MAX_RESPONSE_MB} MB reached`
+});
 const formatReference = (attachment) => `**${attachment.file_name}** (id ${attachment.id}, ${attachment.content_type}, ${attachment.size} bytes) — ${attachment.content_url}`;
 const buildEmbeddedImageBlocks = async (subdomain, token, attachment, reference) => {
 	const { data, contentType } = await fetchZendeskBinary(subdomain, token, attachment.content_url);
@@ -3211,38 +3305,52 @@ const fetchAttachmentsByIds = async (subdomain, token, ids) => {
 	}
 	return attachments;
 };
-const collectAttachmentBlocks = async (subdomain, token, attachments) => {
+const imageSkipReason = (attachment, embeddedCount, reference, fits) => {
+	if (attachment.size > MAX_ATTACHMENT_BYTES) return `skipped: exceeds ${MAX_ATTACHMENT_MB} MB per-image limit`;
+	if (embeddedCount >= MAX_EMBEDDED_IMAGE_COUNT) return `skipped: max ${MAX_EMBEDDED_IMAGE_COUNT} embedded images reached`;
+	if (!fits(embeddedCost(attachment, reference))) return BUDGET_REACHED;
+	return null;
+};
+const overflowFallback = (produced, reference, fits) => {
+	if (!produced.some((block) => block.type === "image")) return null;
+	const fallback = referenceBlock(reference, BUDGET_REACHED);
+	return fits(blockCost(fallback)) ? fallback : null;
+};
+const embedOrExplain = async (subdomain, token, attachment, reference) => {
+	try {
+		return await buildEmbeddedImageBlocks(subdomain, token, attachment, reference);
+	} catch (error) {
+		return [{
+			type: "text",
+			text: `${reference} — ${error instanceof ZendeskApiError ? `download failed: ${error.status} ${error.statusText}` : "download failed"}`
+		}];
+	}
+};
+const collectAttachmentBlocks = async (subdomain, token, attachments, consumedBytes = 0) => {
 	const blocks = [];
 	let embeddedCount = 0;
-	for (const attachment of attachments) {
+	let responseBytes = consumedBytes;
+	const noticeReserve = blockCost(truncationNotice(attachments.length));
+	const fits = (cost) => responseBytes + cost + noticeReserve <= MAX_RESPONSE_BYTES;
+	for (const [index, attachment] of attachments.entries()) {
 		const reference = formatReference(attachment);
-		if (!attachment.content_type.startsWith("image/")) {
-			blocks.push({
-				type: "text",
-				text: reference
-			});
-			continue;
-		}
-		let skipReason = null;
-		if (attachment.size > MAX_ATTACHMENT_BYTES) skipReason = `skipped: exceeds ${MAX_ATTACHMENT_MB} MB per-image limit`;
-		else if (embeddedCount >= MAX_EMBEDDED_IMAGE_COUNT) skipReason = `skipped: max ${MAX_EMBEDDED_IMAGE_COUNT} embedded images reached`;
-		if (skipReason) {
-			blocks.push({
-				type: "text",
-				text: `${reference} — ${skipReason}`
-			});
-			continue;
-		}
-		try {
-			blocks.push(...await buildEmbeddedImageBlocks(subdomain, token, attachment, reference));
-			embeddedCount += 1;
-		} catch (error) {
-			const reason = error instanceof ZendeskApiError ? `download failed: ${error.status} ${error.statusText}` : "download failed";
-			blocks.push({
-				type: "text",
-				text: `${reference} — ${reason}`
-			});
+		const isImage = attachment.content_type.startsWith("image/");
+		const skipReason = isImage ? imageSkipReason(attachment, embeddedCount, reference, fits) : null;
+		const produced = isImage && !skipReason ? await embedOrExplain(subdomain, token, attachment, reference) : [referenceBlock(reference, skipReason)];
+		const cost = produced.reduce((total, block) => total + blockCost(block), 0);
+		if (!fits(cost)) {
+			const fallback = overflowFallback(produced, reference, fits);
+			if (fallback) {
+				blocks.push(fallback);
+				responseBytes += blockCost(fallback);
+				continue;
+			}
+			blocks.push(truncationNotice(attachments.length - index));
+			break;
 		}
+		blocks.push(...produced);
+		responseBytes += cost;
+		if (produced.some((block) => block.type === "image")) embeddedCount += 1;
 	}
 	return blocks;
 };
@@ -3437,9 +3545,19 @@ const createTicketTools = (ctx) => {
 	const { subdomain, getToken } = ctx;
 	const attachmentSchema = z.object({
 		file_name: z.string().min(1).describe("File name, e.g. \"app.log\" or \"screenshot.png\"."),
-		file_base64: z.string().min(1).base64().describe("File content encoded as base64."),
+		file_base64: z.string().min(1).max(MAX_BASE64_INPUT_CHARS, {
+			abort: true,
+			error: (issue) => `Attachment too large: ${issue.input.length} base64 characters, limit ${MAX_BASE64_INPUT_CHARS}. Downscale the file, split the upload, or link to it instead of uploading.`
+		}).base64().describe(`File content encoded as base64. At most ${MAX_BASE64_INPUT_CHARS} characters (about ${MAX_BASE64_INPUT_MB} MB of file), and the attachments of one call must stay under that total; the HTTP transport additionally caps request bodies at 4 MB.`),
 		content_type: z.string().min(1).default("application/octet-stream").describe("MIME type, e.g. \"text/plain\", \"image/png\", \"application/pdf\".")
 	});
+	const attachmentsParam = (description) => z.array(attachmentSchema).superRefine((files, refinement) => {
+		const total = files.reduce((sum, file) => sum + file.file_base64.length, 0);
+		if (total > 10420224) refinement.addIssue({
+			code: "custom",
+			message: `Attachments too large: ${total} base64 characters in total, limit ${MAX_BASE64_INPUT_CHARS}. Send fewer files per call.`
+		});
+	}).optional().describe(description);
 	const uploadAttachments = async (token, files) => {
 		let uploadToken;
 		for (const file of files) {
@@ -3602,11 +3720,11 @@ const createTicketTools = (ctx) => {
 					type: "text",
 					text: `No attachments found on ticket #${ticket_id}.`
 				}] };
-				const blocks = await collectAttachmentBlocks(subdomain, token, attachments);
-				return { content: [{
+				const header = {
 					type: "text",
 					text: `# Attachments for ticket #${ticket_id} (${attachments.length} total)`
-				}, ...blocks] };
+				};
+				return { content: [header, ...await collectAttachmentBlocks(subdomain, token, attachments, blockCost(header) + 1)] };
 			}
 		},
 		{
@@ -3752,7 +3870,7 @@ const createTicketTools = (ctx) => {
 			inputSchema: z.object({
 				ticket_id: z.number().int().describe("Ticket ID — the numeric id of the ticket to annotate. Obtain it from search_tickets or list_tickets."),
 				body: z.string().min(1).describe("Note text (internal, agent-only). Plain text or HTML; not shown to the requester."),
-				attachments: z.array(attachmentSchema).optional().describe("Files to attach to this note (base64-encoded content).")
+				attachments: attachmentsParam("Files to attach to this note (base64-encoded content).")
 			}),
 			annotations: {
 				readOnlyHint: false,
@@ -3784,7 +3902,7 @@ const createTicketTools = (ctx) => {
 			inputSchema: z.object({
 				ticket_id: z.number().int().describe("Ticket ID — the numeric id of the ticket to reply on. Obtain it from search_tickets or list_tickets."),
 				body: z.string().min(1).describe("Comment text sent to the requester. Plain text or HTML; visible in the ticket."),
-				attachments: z.array(attachmentSchema).optional().describe("Files to attach to this comment (base64-encoded content).")
+				attachments: attachmentsParam("Files to attach to this comment (base64-encoded content).")
 			}),
 			annotations: {
 				readOnlyHint: false,
@@ -4490,7 +4608,7 @@ const createMcpServer = (config, getToken, logger = silentLogger, onUnauthorized
 //#endregion
 //#region src/transports/stdio.ts
 const startStdioTransport = async (server, logger = silentLogger) => {
-	const transport = new StdioServerTransport();
+	const transport = new StdioServerTransport(void 0, void 0, { maxBufferSize: STDIO_MAX_MESSAGE_BYTES });
 	await server.connect(transport);
 	logger.info("stdio_transport_ready");
 };
@@ -4737,12 +4855,13 @@ const buildOAuthMetadata = (config, logger = silentLogger) => {
 	const { authorizeUrl, tokenUrl } = getOAuthUrls(config.subdomain);
 	const issuer = `https://${config.subdomain}.zendesk.com`;
 	const resource = resolveResourceUrl(config, logger);
+	const scopes = () => supportedScopes(config.readOnly);
 	return {
 		protectedResource: {
 			authorization_servers: [issuer],
 			resource,
 			bearer_methods_supported: ["header"],
-			scopes_supported: ["read", "write"]
+			scopes_supported: scopes()
 		},
 		authorizationServer: {
 			issuer,
@@ -4752,7 +4871,7 @@ const buildOAuthMetadata = (config, logger = silentLogger) => {
 			grant_types_supported: ["authorization_code", "refresh_token"],
 			code_challenge_methods_supported: ["S256"],
 			token_endpoint_auth_methods_supported: ["none"],
-			scopes_supported: ["read", "write"]
+			scopes_supported: scopes()
 		}
 	};
 };
@@ -5075,7 +5194,8 @@ const installShutdown = (options) => {
 const buildStdioTokenStore = (config, logger) => createTokenStore({
 	subdomain: config.subdomain,
 	oauthClientId: config.oauthClientId,
-	callbackPort: config.callbackPort
+	callbackPort: config.callbackPort,
+	readOnly: config.readOnly
 }, logger);
 const connectStdio = async (config, tokenStore, logger) => {
 	if (config.dev) return startDevServer(config, tokenStore.getToken, logger, tokenStore.invalidate);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fruggr/zendesk-mcp-server",
-  "version": "2.20.1",
+  "version": "2.21.0",
   "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",