@fruggr/zendesk-mcp-server 2.20.2 → 2.22.0

package/dist/index.js

@@ -135,6 +135,7 @@ const MAX_RESPONSE_BYTES = Math.min(positiveIntEnv("ZENDESK_MAX_RESPONSE_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 TICKET_FIELD_SCAN_MAX_PAGES = positiveIntEnv("ZENDESK_TICKET_FIELD_SCAN_MAX_PAGES", 10);
 const REORDER_CONFIRM_THRESHOLD = positiveIntEnv("ZENDESK_REORDER_CONFIRM_THRESHOLD", 20);
 const getBaseUrl = (subdomain) => `https://${subdomain}.zendesk.com/api/v2`;
 const getHelpCenterBaseUrl = (subdomain) => `https://${subdomain}.zendesk.com/api/v2/help_center`;
@@ -143,6 +144,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. */
@@ -185,7 +228,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);
@@ -308,7 +351,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"
 			});
@@ -497,8 +540,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;
@@ -507,12 +560,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 {
@@ -524,7 +585,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);
@@ -544,14 +606,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);
@@ -593,7 +657,8 @@ const createTokenStore = (config, logger = silentLogger) => {
 			token = {
 				accessToken: token.accessToken,
 				refreshToken: token.refreshToken,
-				expiresAt: 0
+				expiresAt: 0,
+				scope: token.scope
 			};
 			persist(token);
 		} else {
@@ -632,8 +697,24 @@ const LogLevel = z.enum([
 const Namespace = z.enum([
 	"tickets",
 	"help_center",
-	"users"
+	"users",
+	"requests"
 ]);
+/**
+* Namespaces exposed when the operator passes no `--namespace` flag.
+*
+* Deliberately NOT every member of the enum: the end-user `requests` surface
+* is opt-in, because under an agent token part of it silently misbehaves
+* rather than failing -- `solved: true` returns 200 and changes nothing, and
+* `required_in_portal` validation is not applied to agents. Registering it for
+* every agent install would ship an operation that reports success on a no-op.
+* Secondarily, an agent's tool list and context budget stay unchanged.
+*/
+const DEFAULT_NAMESPACES = [
+	"tickets",
+	"help_center",
+	"users"
+];
 const Transport = z.enum(["stdio", "http"]);
 const ConfigSchema = z.object({
 	subdomain: z.string().min(1, "ZENDESK_SUBDOMAIN is required"),
@@ -641,7 +722,18 @@ const ConfigSchema = z.object({
 	logLevel: LogLevel,
 	mode: ToolMode,
 	readOnly: z.boolean(),
-	namespaces: z.array(Namespace).optional(),
+	/**
+	* Active namespaces, defaulting to DEFAULT_NAMESPACES rather than everything.
+	*
+	* The default lives HERE, not in `loadConfig`: the integration harness builds
+	* its Config through `ConfigSchema.parse` and never calls `loadConfig`, so a
+	* default applied there would leave `requests` visible to every scenario and
+	* absent in production.
+	*
+	* `.min(1)` rejects an explicit `[]`, which `filterTools` reads as no filter
+	* at all (it guards on `?.length`) and would expose the opt-in namespace.
+	*/
+	namespaces: z.array(Namespace).min(1).default([...DEFAULT_NAMESPACES]),
 	tools: z.array(z.string()).optional(),
 	/**
 	* Whether to expose the Help Center structural context (the `instructions`
@@ -692,6 +784,14 @@ const ConfigSchema = z.object({
 	* the "Dev mode" section of docs/configuration.md.
 	*/
 	dev: z.boolean().default(false),
+	/**
+	* Print the tool surface the current flags resolve to, then exit without
+	* starting a server or touching the network. `--print-tools` exists because
+	* the surface is shaped by three independent knobs (`--namespace` / `--tool`
+	* pick the inventory, `--mode` packages it, `--read-only` narrows it) and
+	* their combination is easier to read off a listing than to predict.
+	*/
+	printTools: z.boolean().default(false),
 	transport: Transport,
 	host: z.string().min(1),
 	port: z.number().int().min(0).max(65535),
@@ -741,7 +841,8 @@ const CLI_OPTIONS = {
 	"read-only": { type: "boolean" },
 	"no-topology": { type: "boolean" },
 	"no-promoted-articles": { type: "boolean" },
-	dev: { type: "boolean" }
+	dev: { type: "boolean" },
+	"print-tools": { type: "boolean" }
 };
 new Set(Object.entries(CLI_OPTIONS).filter(([, spec]) => spec.type === "string").map(([name]) => `--${name}`));
 const FIELD_BY_FLAG = /* @__PURE__ */ new Map([
@@ -759,7 +860,8 @@ const STANDALONE_EFFECTS = /* @__PURE__ */ new Map([
 	["read-only", { readOnly: true }],
 	["no-topology", { topology: false }],
 	["no-promoted-articles", { promotedArticles: false }],
-	["dev", { dev: true }]
+	["dev", { dev: true }],
+	["print-tools", { printTools: true }]
 ]);
 const parseCliArgs = (args) => {
 	const { values, positionals } = parseArgs({
@@ -798,6 +900,7 @@ const loadConfig = (argv = process.argv.slice(2)) => {
 	const subdomain = cli.subdomain ?? requireNonEmptyEnv("ZENDESK_SUBDOMAIN") ?? "";
 	const oauthClientId = requireNonEmptyEnv("ZENDESK_OAUTH_CLIENT_ID") ?? `${subdomain}_zendesk`;
 	const mode = cli.tools?.length ? "all" : cli.mode ?? "namespace";
+	const namespaces = cli.namespaces ?? (cli.tools?.length ? [...Namespace.options] : void 0);
 	const callbackPort = cli.callbackPort ?? parsePortEnv(requireNonEmptyEnv("ZENDESK_OAUTH_CALLBACK_PORT"), "ZENDESK_OAUTH_CALLBACK_PORT");
 	const hcResourceScheme = cli.hcResourceScheme ?? requireNonEmptyEnv("HC_RESOURCE_SCHEME");
 	return ConfigSchema.parse({
@@ -806,12 +909,13 @@ const loadConfig = (argv = process.argv.slice(2)) => {
 		logLevel: cli.logLevel ?? requireNonEmptyEnv("LOG_LEVEL") ?? "info",
 		mode,
 		readOnly: cli.readOnly ?? false,
-		namespaces: cli.namespaces,
+		namespaces,
 		tools: cli.tools,
 		topology: cli.topology ?? true,
 		promotedArticles: cli.promotedArticles ?? true,
 		hcResourceScheme,
 		dev: cli.dev ?? false,
+		printTools: cli.printTools ?? false,
 		callbackPort,
 		...resolveTransportSettings(cli)
 	});
@@ -1323,6 +1427,25 @@ const formatComment = (comment, authors) => {
 	lines.push("", comment.body);
 	return lines.join("\n");
 };
+const formatRequest = (request) => [
+	`## Request #${request.id}: ${request.subject}`,
+	`- **Status**: ${request.status}${request.type ? ` | **Type**: ${request.type}` : ""}${request.priority ? ` | **Priority**: ${request.priority}` : ""}`,
+	request.ticket_form_id ? `- **Form**: ${request.ticket_form_id}` : "",
+	`- **Can you mark it solved**: ${request.can_be_solved_by_me ? "yes" : "no"}`,
+	request.via?.channel ? `- **Submitted via**: ${request.via.channel}` : "",
+	`- **Created**: ${request.created_at} | **Updated**: ${request.updated_at}`,
+	request.description ? `\n${request.description}` : ""
+].filter(Boolean).join("\n");
+const formatRequestComment = (comment, authors) => {
+	const author = authors.get(comment.author_id);
+	const lines = [`### Comment by ${author ? `${author.name}${author.agent ? " (support agent)" : ""}` : `user ${comment.author_id}`}`, `*${comment.created_at}*`];
+	if (comment.attachments?.length) {
+		const summary = comment.attachments.map((a) => `${a.file_name} (#${a.id}, ${a.content_type}) — ${a.content_url}`).join(", ");
+		lines.push(`Attachments: ${summary}`);
+	}
+	lines.push("", comment.body);
+	return lines.join("\n");
+};
 const formatTagDiff = (before, after) => {
 	const b = new Set(Array.isArray(before) ? before.map(String) : []);
 	const a = new Set(Array.isArray(after) ? after.map(String) : []);
@@ -1557,15 +1680,13 @@ const fetchArticleMarkdown = async (subdomain, token, id, locale) => {
 	return truncateIfNeeded(text, "This resource takes no parameters; read a long article one part at a time with get_article_outline then get_article_section.");
 };
 /**
-* Build an article-resources provider. `listPromoted` holds a memoized-promise
-* cache (TTL `ARTICLE_RESOURCES_TTL_MS`) to coalesce the repeated `resources/list`
-* calls a client makes; `readArticle` is a one-shot fetch (not cached). As with
+* Build an article-resources provider. `listPromoted` memoizes its promise (TTL
+* `ARTICLE_RESOURCES_TTL_MS`) to coalesce the repeated `resources/list` calls a
+* client makes; `readArticle` is a one-shot fetch. As with
 * `createTopologyProvider`, the cache is PER SESSION and must NOT be hoisted to
-* module scope — in HTTP mode this provider is instantiated per session, so a
-* shared cache would leak one caller's data to another. `getToken` is resolved
-* lazily at call time (never at construction) so connecting never triggers the
-* OAuth/PKCE flow. A 401 notifies `onUnauthorized` (stdio OAuth) to drop the
-* stale token, mirroring the topology provider and the tool dispatch path.
+* module scope — in HTTP mode a shared one would leak a caller's data to
+* another. `getToken` resolves lazily, so connecting never triggers the OAuth
+* flow, and a 401 notifies `onUnauthorized` to drop the stale token.
 */
 const createArticleResourcesProvider = (getToken, subdomain, onUnauthorized) => {
 	let cached;
@@ -1834,10 +1955,19 @@ const createTopologyProvider = (getToken, subdomain, onUnauthorized) => {
 };
 //#endregion
 //#region src/routing/registry.ts
+/**
+* The single authority on which tools a config exposes.
+*
+* Every filter lives here rather than at the call sites, because there is more
+* than one consumer -- `registerToolset` registers them and `renderToolSurface`
+* prints them -- and a filter applied in only one of the two makes
+* `--print-tools` lie about the running server.
+*/
 const filterTools = (allTools, options) => allTools.filter((tool) => {
 	if (options.readOnly && !tool.readOnly) return false;
 	if (options.namespaces?.length && !options.namespaces.includes(tool.namespace)) return false;
 	if (options.tools?.length && !options.tools.includes(tool.name)) return false;
+	if (options.promotedArticles === false && tool.name === "list_promoted_articles") return false;
 	return true;
 });
 const groupByNamespace = (tools) => {
@@ -1849,6 +1979,34 @@ const groupByNamespace = (tools) => {
 	}
 	return grouped;
 };
+/**
+* Proxy tool name and title per namespace, used by `namespace` mode.
+*
+* Typed `Record<Namespace, …>` rather than `Record<string, …>` so the compiler
+* rejects this literal outright when a namespace is added to the enum without
+* a label here. That matters because the consumer looks the label up and skips
+* the namespace when it is missing: an incomplete map would silently expose no
+* proxy for a whole namespace, with every existing test still green. Making it
+* a type error is stronger than any test could be.
+*/
+const NAMESPACE_LABELS = {
+	tickets: {
+		toolName: "zendesk_tickets",
+		title: "Zendesk Tickets"
+	},
+	help_center: {
+		toolName: "zendesk_help_center",
+		title: "Zendesk Help Center"
+	},
+	users: {
+		toolName: "zendesk_users",
+		title: "Zendesk Users"
+	},
+	requests: {
+		toolName: "zendesk_requests",
+		title: "Zendesk Requests"
+	}
+};
 //#endregion
 //#region src/utils/article-order.ts
 const hasPositionInversion = (order) => {
@@ -3117,6 +3275,526 @@ const createHelpCenterTools = (ctx) => {
 	];
 };
 //#endregion
+//#region src/tools/attachments.ts
+/**
+* File-attachment input, shared by every tool that can carry files on a comment.
+*
+* Lives here rather than inside a tool factory because both audiences need it:
+* an agent attaching a screenshot to a public reply, and an end user attaching a
+* log to their own request. The Uploads API (`POST /api/v2/uploads.json`) is
+* documented as allowed for end users, so the same code path serves both.
+*/
+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).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\".")
+});
+/**
+* The optional `attachments` array parameter, capped as a whole.
+*
+* The per-file cap in `attachmentSchema` bounds one attachment; this bounds a
+* call, because `attachments` is a list and every file rides in the same
+* message (#205).
+*/
+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);
+/**
+* Upload each file via the Zendesk Uploads API, aggregating them under a single
+* upload token (the token from the first upload is passed to the next), and
+* return that token for use in a comment's `uploads` array. Sequential of
+* necessity: each call needs the previous token.
+*/
+const uploadAttachments = async (subdomain, token, files) => {
+	let uploadToken;
+	for (const file of files) {
+		const { upload } = await zendeskUpload(subdomain, token, file.file_name, Buffer.from(file.file_base64, "base64"), file.content_type, uploadToken);
+		uploadToken = upload.token;
+	}
+	return uploadToken;
+};
+const formatAttachmentSuffix = (count) => count ? ` with ${count} attachment(s)` : "";
+//#endregion
+//#region src/tools/requests.ts
+const forbidden = (tool, endpoint, error, hint) => new Error(`${tool} reads the end-user Requests surface (${endpoint}), which Zendesk serves to a signed-in requester. The current token was refused (HTTP 403). Either the Help Center is closed to this account, or this token is not a Help-Center-enabled user.${hint ? ` ${hint}` : ""} For the agent-side equivalents use create_ticket, get_ticket, list_tickets or add_public_comment (namespace: tickets).`, { cause: error });
+const OTHER_USERS_REQUEST_HINT = "A request id that belongs to another user is refused the same way, so check the id is one of your own.";
+/** Run `fetch`, rewriting a 403 into guidance naming the end-user surface. */
+const withForbiddenGuidance = async (tool, endpoint, fetch, hint) => {
+	try {
+		return await fetch();
+	} catch (error) {
+		if (error instanceof ZendeskApiError && error.status === 403) throw forbidden(tool, endpoint, error, hint);
+		throw error;
+	}
+};
+const END_USER_FORM_PARAMS = {
+	active: "true",
+	end_user_visible: "true",
+	fallback_to_default: "true"
+};
+/**
+* Walk an offset-paginated listing to the end, following `next_page` and
+* nothing else.
+*
+* `next_page` is the only trustworthy end-of-list signal on these endpoints:
+* `count` can be the pre-filter total, and a short page can still be followed
+* by another. Hitting the cap throws rather than returning a partial list --
+* for both callers a missing entry is worse than an error, because it makes a
+* form invisible or a required field unenforced, and the caller then gets a
+* confidently wrong "no such form" or an opaque Zendesk 422.
+*/
+const fetchAllPages = async ({ subdomain, token, tool, path, extract, params = {}, maxPages = TICKET_FIELD_SCAN_MAX_PAGES, capEnvVar = "ZENDESK_TICKET_FIELD_SCAN_MAX_PAGES", onPage, forbiddenHint }) => {
+	const items = [];
+	let page = 1;
+	while (true) {
+		const response = await withForbiddenGuidance(tool, `GET ${path}`, () => zendeskGet(subdomain, token, path, {
+			...params,
+			...buildOffsetParams(100, page)
+		}), forbiddenHint);
+		items.push(...extract(response) ?? []);
+		onPage?.(response);
+		if (!response.next_page) return items;
+		if (page >= maxPages) throw new Error(`${tool} could not read all of ${path}: the account exposes more than ${maxPages} pages of it. Continuing from a partial list would hide entries and produce a confidently wrong answer, so this stops here. Raise ${capEnvVar} and retry.`);
+		page += 1;
+	}
+};
+const fetchEndUserForms = async (subdomain, token, tool) => fetchAllPages({
+	subdomain,
+	token,
+	tool,
+	path: "/ticket_forms",
+	extract: (response) => response.ticket_forms,
+	params: END_USER_FORM_PARAMS,
+	forbiddenHint: "This endpoint can also be unavailable on a Zendesk plan without multiple ticket forms."
+});
+/**
+* Every ticket field the caller can see, paged defensively.
+*
+* `GET /ticket_fields` cannot be trusted to say when it is done. Under an
+* end-user token its `count` is the UNFILTERED total (27 while returning 8
+* objects with `next_page: null`), and in cursor mode `page[size]` is applied
+* before the visibility filter, so a short page is not the last page. So this
+* follows `next_page` and nothing else, bounded by a page cap.
+*
+* The per-field lookup would be the obvious alternative and is not available:
+* `GET /ticket_fields/{id}` answers 403 for an end user. The list is the only
+* way in.
+*/
+const fetchVisibleTicketFields = async (subdomain, token, tool) => {
+	return (await fetchAllPages({
+		subdomain,
+		token,
+		tool,
+		path: "/ticket_fields",
+		extract: (response) => response.ticket_fields
+	})).filter((field) => field.visible_in_portal !== false);
+};
+const fetchAllRequestComments = async (subdomain, token, requestId) => {
+	const authors = /* @__PURE__ */ new Map();
+	return {
+		comments: await fetchAllPages({
+			subdomain,
+			token,
+			tool: "get_request",
+			path: `/requests/${requestId}/comments`,
+			extract: (response) => response.comments,
+			params: { include: "users" },
+			maxPages: MAX_COMMENT_PAGES,
+			capEnvVar: "ZENDESK_MAX_COMMENT_PAGES",
+			forbiddenHint: OTHER_USERS_REQUEST_HINT,
+			onPage: (response) => {
+				for (const user of response.users ?? []) authors.set(user.id, user);
+			}
+		}),
+		authors
+	};
+};
+const SYSTEM_FIELD_TYPES = /* @__PURE__ */ new Set([
+	"subject",
+	"description",
+	"status",
+	"tickettype",
+	"priority",
+	"group",
+	"assignee",
+	"tags",
+	"custom_status"
+]);
+const isCustomField = (field) => !SYSTEM_FIELD_TYPES.has(field.type);
+const formSummary = (form) => [`- **${form.display_name || form.name}** (form id ${form.id})${form.default ? " — default" : ""}`, form.display_name && form.display_name !== form.name ? `  - Internal name: ${form.name}` : ""].filter(Boolean).join("\n");
+const fieldSpec = (field) => {
+	const options = field.custom_field_options ?? field.system_field_options ?? [];
+	return [
+		`### ${field.title_in_portal || field.title} (field id ${field.id})`,
+		`- **Type**: ${field.type} | **${field.required_in_portal ? "required" : "optional"}**`,
+		field.description ? `- **Help text**: ${field.description}` : "",
+		options.length > 0 ? "- **Accepted values** (label → value to send):" : "",
+		...options.map((option) => `  - ${option.name} → ${option.value}`)
+	].filter(Boolean).join("\n");
+};
+const fieldRef = (id, byId) => {
+	const field = byId.get(id);
+	return field ? `${field.title_in_portal || field.title} (field id ${id})` : `field ${id}`;
+};
+/**
+* Whether a conditional child field is required *of a submitter*, in words.
+*
+* `is_required` alone is not the answer: `required_on_statuses` narrows it to
+* particular statuses, and saying "then required" for a field required only
+* "when open" sends the assistant hunting for an answer Zendesk will not ask
+* for. A new request starts at `new`, so that is the status read for -- but a
+* trigger can move it off `new` at once, hence wording that says when the field
+* becomes required rather than that it never will.
+*/
+const childRequirement = (child) => {
+	if (!child.is_required) return "";
+	const scope = child.required_on_statuses;
+	if (!scope || scope.type === "ALL_STATUSES") return " (then required)";
+	if (scope.type === "NO_STATUSES") return "";
+	const statuses = scope.statuses ?? [];
+	if (statuses.length === 0) return " (then required)";
+	return statuses.includes("new") ? " (then required)" : ` (then required once the request is ${statuses.join(" or ")}, not to submit it)`;
+};
+const conditionSpec = (condition, byId) => {
+	const children = (condition.child_fields ?? []).map((child) => `${fieldRef(child.id, byId)}${childRequirement(child)}`).join(", ");
+	return `- When ${fieldRef(condition.parent_field_id, byId)} is \`${String(condition.value)}\`: ${children || "no additional fields"}`;
+};
+const renderFormSpec = (form, fields) => {
+	const byId = new Map(fields.map((field) => [field.id, field]));
+	const formFields = form.ticket_field_ids.map((id) => byId.get(id)).filter((field) => field !== void 0).filter(isCustomField);
+	const required = formFields.filter((field) => field.required_in_portal);
+	const conditions = form.end_user_conditions ?? [];
+	return [
+		`# ${form.display_name || form.name} (form id ${form.id})`,
+		"",
+		"Always needed: a subject and a description (the `subject` and `body` parameters",
+		"of create_request). The fields below are what this form asks for on top of those.",
+		"",
+		required.length > 0 ? `**Required**: ${required.map((f) => f.title_in_portal || f.title).join(", ")}` : "**Required**: nothing beyond the subject and description.",
+		conditions.length > 0 ? [
+			"",
+			"## Conditional fields",
+			"Some fields appear, or become required, only for certain answers. Ask for them once",
+			"the controlling answer is known rather than up front:",
+			...conditions.map((condition) => conditionSpec(condition, byId))
+		].join("\n") : "",
+		"",
+		"## Fields",
+		"",
+		formFields.length > 0 ? formFields.map(fieldSpec).join("\n\n") : "This form exposes no custom fields; send subject and body only."
+	].filter(Boolean).join("\n");
+};
+const isEmptyAnswer = (value) => value === null || value === "" || Array.isArray(value) && value.length === 0;
+const optionValues = (field) => field.custom_field_options?.length ? new Set(field.custom_field_options.map((option) => option.value)) : null;
+/**
+* Refuse a submission the API would accept and quietly mangle. Three ways it
+* does: an unknown `ticket_form_id` gets 201 on the DEFAULT form; a missing
+* `required_in_portal` field is enforced against end users only, so an agent
+* token gets 201 with an empty subject; and an option value the form does not
+* offer is dropped, leaving 201 and an empty field.
+*
+* Only UNCONDITIONALLY required fields are enforced -- one required through
+* `end_user_conditions` depends on answers we may not have, and Zendesk's 422
+* is the backstop.
+*/
+const validateSubmission = (form, fields, provided) => {
+	const byId = new Map(fields.map((field) => [field.id, field]));
+	const formFieldIds = new Set(form.ticket_field_ids);
+	const offForm = provided.filter((entry) => {
+		const field = byId.get(entry.id);
+		return !formFieldIds.has(entry.id) || !field || !isCustomField(field);
+	});
+	if (offForm.length > 0) throw new Error(`This form does not take those fields: ${offForm.map((entry) => entry.id).join(", ")}. Zendesk would accept the submission and drop them. Call get_request_form for the ids it does take; the subject and the description are this tool's own parameters, not custom_fields entries.`);
+	const answered = provided.filter((entry) => !isEmptyAnswer(entry.value));
+	const providedIds = new Set(answered.map((e) => e.id));
+	const missing = form.ticket_field_ids.map((id) => byId.get(id)).filter((field) => field?.required_in_portal === true).filter(isCustomField).filter((field) => !providedIds.has(field.id));
+	if (missing.length > 0) {
+		const list = missing.map((field) => `${field.title_in_portal || field.title} (field id ${field.id})`).join(", ");
+		throw new Error(`This form requires values the submission does not carry: ${list}. Ask for them, then resend with those ids in custom_fields. Call get_request_form for their accepted values.`);
+	}
+	const rejected = answered.flatMap((entry) => {
+		const field = byId.get(entry.id);
+		const accepted = field && optionValues(field);
+		if (!field || !accepted) return [];
+		const unknown = (Array.isArray(entry.value) ? entry.value : [entry.value]).filter((value) => typeof value !== "string" || !accepted.has(value));
+		return unknown.length > 0 ? [`${field.title_in_portal || field.title} (field id ${field.id}) got ${unknown.map((value) => JSON.stringify(value)).join(", ")}, accepts ${[...accepted].map((value) => JSON.stringify(value)).join(", ")}`] : [];
+	});
+	if (rejected.length > 0) throw new Error(`This form does not offer those answers: ${rejected.join("; ")}. Zendesk would accept the submission and drop them, leaving the request without the answers it asked for, so this is refused instead. Call get_request_form for the exact values to send.`);
+};
+const REQUEST_STATUS = z.enum([
+	"new",
+	"open",
+	"pending",
+	"hold",
+	"solved",
+	"closed"
+]);
+const createRequestTools = (ctx) => {
+	const { subdomain, getToken } = ctx;
+	const resolveForm = async (tool, token, formId) => {
+		const [forms, fields] = await Promise.all([fetchEndUserForms(subdomain, token, tool), fetchVisibleTicketFields(subdomain, token, tool)]);
+		if (forms.length === 0) throw new Error(`No request form is available to this user on ${subdomain}.zendesk.com. The Help Center may be closed, or no form is marked visible to end users. An agent can still open a ticket with create_ticket (namespace: tickets).`);
+		const form = formId === void 0 ? forms.find((f) => f.default) ?? (forms.length === 1 ? forms[0] : void 0) : forms.find((f) => f.id === formId);
+		if (!form) {
+			const available = forms.map((f) => `${f.display_name || f.name} (${f.id})`).join(", ");
+			throw new Error(formId === void 0 ? `No default request form on ${subdomain}.zendesk.com. Pick one explicitly: ${available}.` : `No request form with id ${formId} is available to you. Available: ${available}. Sending an unknown id would make Zendesk silently substitute the default form, so this is refused rather than guessed.`);
+		}
+		return {
+			form,
+			fields
+		};
+	};
+	return [
+		{
+			name: "list_request_forms",
+			namespace: "requests",
+			readOnly: true,
+			title: "List Request Forms",
+			description: "List the kinds of request you can submit to this Zendesk — the forms a customer picks between on the Help Center, such as \"Report a bug\" or \"Feature request\". Returns each form's customer-facing name, its numeric id, and which one is the account default. Call this first when opening a request so the user chooses the right kind, then get_request_form to learn what that form asks for. Only forms that are active and visible to end users are listed; an account with a single form returns just that one. This is the end-user view: agents picking a form for someone else want list_ticket_fields and create_ticket instead.",
+			inputSchema: z.object({}),
+			annotations: {
+				readOnlyHint: true,
+				destructiveHint: false,
+				idempotentHint: true,
+				openWorldHint: true
+			},
+			handler: async () => {
+				const token = await getToken();
+				const forms = await fetchEndUserForms(subdomain, token, "list_request_forms");
+				if (forms.length === 0) return { content: [{
+					type: "text",
+					text: "No request form is available to you on this Zendesk. The Help Center may be closed, or no form is marked visible to end users."
+				}] };
+				const text = [
+					`${forms.length} kind(s) of request available:`,
+					"",
+					forms.map(formSummary).join("\n"),
+					"",
+					"Call get_request_form with a form id to see the questions it asks."
+				].join("\n");
+				return { content: [{
+					type: "text",
+					text: truncateIfNeeded(text, "list_request_forms takes no parameters, so this listing cannot be narrowed from the call; read one form in full with get_request_form.")
+				}] };
+			}
+		},
+		{
+			name: "get_request_form",
+			namespace: "requests",
+			readOnly: true,
+			title: "Get Request Form",
+			description: "Read what one request form actually asks for, so the user can be walked through it question by question. Returns the fields on that form in the order the portal shows them, each with its customer-facing label, whether it is required, and for dropdowns the exact values Zendesk accepts — plus any conditional rules (\"if Type is Bug, Version becomes required\"). Joins the form definition with the field definitions, because the form itself carries only field ids. Use it after list_request_forms and before create_request; omit form_id to describe the account default form. Conditional fields are reported as rules rather than resolved, since which ones apply depends on answers not yet given.",
+			inputSchema: z.object({ form_id: z.number().int().optional().describe("Form id whose questions to read, as returned by list_request_forms. Omit to describe the account default form.") }),
+			annotations: {
+				readOnlyHint: true,
+				destructiveHint: false,
+				idempotentHint: true,
+				openWorldHint: true
+			},
+			handler: async (params) => {
+				const { form_id } = params;
+				const token = await getToken();
+				const { form, fields } = await resolveForm("get_request_form", token, form_id);
+				return { content: [{
+					type: "text",
+					text: truncateIfNeeded(renderFormSpec(form, fields), "get_request_form takes only form_id, so this description cannot be narrowed from the call; the fields it lists are the ones this form asks for.")
+				}] };
+			}
+		},
+		{
+			name: "create_request",
+			namespace: "requests",
+			readOnly: false,
+			title: "Submit a Request",
+			description: "Submit a new support request as the signed-in user — the MCP equivalent of the Help Center's \"Submit a request\" form. Returns the created request with its number, which the user can then follow with list_requests and get_request. The submission is checked before sending: an unknown form id, a missing field the form marks required, or a dropdown answer the form does not offer is refused here rather than sent, because Zendesk would answer 201 having silently substituted the default form, accepted an empty subject or dropped the unrecognised value. Call get_request_form first to learn which fields to gather. Priority and type cannot be set by an end user — Zendesk drops them — so triage is left to the agents. This posts as the authenticated user; an agent opening a ticket on someone else's behalf wants create_ticket instead.",
+			inputSchema: z.object({
+				subject: z.string().min(1).describe("One-line summary of the request, shown as the ticket title to the support agents who pick it up."),
+				body: z.string().min(1).describe("The request itself: what happened, what was expected, and any steps to reproduce. Becomes the first public comment on the ticket."),
+				form_id: z.number().int().optional().describe("Form id chosen from list_request_forms, deciding which questions apply. Omit to use the account default form."),
+				custom_fields: z.array(z.object({
+					id: z.number().int(),
+					value: z.unknown()
+				})).optional().describe("Answers to the form's own questions, as { id, value } pairs. Take both the ids and the accepted values from get_request_form; an id this form does not carry, or a value a dropdown does not offer, is refused here because Zendesk would drop it without an error. Option values are the tag strings, never numbers."),
+				attachments: attachmentsParam("Files to attach to the request, such as a screenshot or a log, with their content base64-encoded.")
+			}),
+			annotations: {
+				readOnlyHint: false,
+				destructiveHint: false,
+				idempotentHint: false,
+				openWorldHint: true
+			},
+			handler: async (params) => {
+				const { subject, body, form_id, custom_fields, attachments } = params;
+				const token = await getToken();
+				const { form, fields } = await resolveForm("create_request", token, form_id);
+				validateSubmission(form, fields, custom_fields ?? []);
+				const uploads = attachments?.length ? [await uploadAttachments(subdomain, token, attachments)] : void 0;
+				const { request } = await withForbiddenGuidance("create_request", "POST /requests", () => zendeskPost(subdomain, token, "/requests", { request: {
+					subject,
+					ticket_form_id: form.id,
+					comment: {
+						body,
+						...uploads && { uploads }
+					},
+					...custom_fields && { custom_fields }
+				} }));
+				const suffix = formatAttachmentSuffix(attachments?.length);
+				return { content: [{
+					type: "text",
+					text: `Request #${request.id} submitted${suffix}.\n\n${formatRequest(request)}`
+				}] };
+			}
+		},
+		{
+			name: "list_requests",
+			namespace: "requests",
+			readOnly: true,
+			title: "List My Requests",
+			description: "List the requests the signed-in user submitted, newest activity first by default. Returns each request with its number, subject, status and whether the user can mark it solved; pass a query to search their own requests by free text instead of listing all of them. Scoped to the caller by Zendesk itself — it can never return anyone else's tickets — which is why an agent calling this sees only requests they raised, not their queue. Use get_request to read one with its full conversation. Agents wanting a queue want list_tickets, search_tickets or get_view_tickets instead.",
+			inputSchema: z.object({
+				query: z.string().min(1).optional().describe("Free text to match against the caller's own requests. When given, the search endpoint is used instead of the plain listing; omit it to list everything."),
+				status: z.array(REQUEST_STATUS).min(1).optional().describe("Restrict to these ticket states, e.g. [\"open\",\"pending\"] for anything still being worked. Validated here because Zendesk silently returns every request when it does not recognise a status."),
+				sort_by: z.enum(["created_at", "updated_at"]).default("updated_at").describe("Which timestamp orders the results: updated_at surfaces recent activity, created_at the newest submissions."),
+				sort_order: z.enum(["asc", "desc"]).default("desc").describe("Direction of that ordering; desc puts the most recent first, which is what a user following their tickets wants."),
+				per_page: z.number().int().min(1).max(100).default(100).describe(PER_PAGE_DESC),
+				page: z.number().int().min(1).default(1).describe(PAGE_DESC)
+			}),
+			annotations: {
+				readOnlyHint: true,
+				destructiveHint: false,
+				idempotentHint: true,
+				openWorldHint: true
+			},
+			handler: async (params) => {
+				const { query, status, sort_by, sort_order, per_page, page } = params;
+				const token = await getToken();
+				const path = query ? "/requests/search" : "/requests";
+				const response = await withForbiddenGuidance("list_requests", `GET ${path}`, () => zendeskGet(subdomain, token, path, {
+					...query && { query },
+					...status?.length && { status: status.join(",") },
+					sort_by,
+					sort_order,
+					...buildOffsetParams(per_page, page)
+				}));
+				const requests = response.requests ?? [];
+				const meta = extractOffsetPaginationMeta(response, requests.length, per_page, page);
+				if (requests.length === 0) return { content: [{
+					type: "text",
+					text: query ? `No request of yours matches "${query}".` : "You have not submitted any request matching this filter."
+				}] };
+				return { content: [{
+					type: "text",
+					text: `${query ? `Searched your requests for "${query}".` : "Your requests."}\n\n${formatList(requests, formatRequest, meta)}`
+				}] };
+			}
+		},
+		{
+			name: "get_request",
+			namespace: "requests",
+			readOnly: true,
+			title: "Get My Request",
+			description: "Read one of the signed-in user's own requests, optionally with the whole conversation on it. Returns the request's status, the form it was submitted on, whether the user may mark it solved, and — with include_comments — every public message on it, each labelled with its author and marked when that author is a support agent. Internal agent notes are never returned on this path, so nothing agent-private can leak through it. A request belonging to someone else answers \"permission denied\" rather than \"not found\", so a denial here does not tell you whether that id exists. Find the number with list_requests; agents reading a ticket they do not own want get_ticket instead.",
+			inputSchema: z.object({
+				request_id: z.number().int().describe("Number of the request to read, as shown by list_requests or returned when it was submitted."),
+				include_comments: z.boolean().default(false).describe("When true, appends the full public conversation — agent replies and the user's own messages. Defaults to false so a status check stays cheap.")
+			}),
+			annotations: {
+				readOnlyHint: true,
+				destructiveHint: false,
+				idempotentHint: true,
+				openWorldHint: true
+			},
+			handler: async (params) => {
+				const { request_id, include_comments } = params;
+				const token = await getToken();
+				const { request } = await withForbiddenGuidance("get_request", `GET /requests/${request_id}`, () => zendeskGet(subdomain, token, `/requests/${request_id}`), OTHER_USERS_REQUEST_HINT);
+				let text = formatRequest(request);
+				if (include_comments) {
+					const { comments, authors } = await fetchAllRequestComments(subdomain, token, request_id);
+					const thread = comments.map((c) => formatRequestComment(c, authors)).join("\n\n");
+					text += `\n\n---\n# Conversation\n\n${thread}`;
+				}
+				const advice = include_comments ? `get_request appends the whole conversation as one unpaginated block; call it again with include_comments false to read request #${request_id}'s status and description alone.` : "get_request takes no pagination or filter parameters, so this response cannot be narrowed from the call.";
+				return { content: [{
+					type: "text",
+					text: truncateIfNeeded(text, advice)
+				}] };
+			}
+		},
+		{
+			name: "add_request_comment",
+			namespace: "requests",
+			readOnly: false,
+			title: "Reply on My Request",
+			description: "Reply on one of the signed-in user's own requests, optionally attaching files. Returns confirmation with the request's status after the reply, which matters because replying on a request that was already solved REOPENS it — Zendesk moves it back to open, and the user should know that is what their message did. The comment is always public: end users cannot post internal notes, and Zendesk silently ignores any attempt to mark one private. A closed request rejects new comments outright. Agents replying to a requester want add_public_comment, or add_private_note for an internal note.",
+			inputSchema: z.object({
+				request_id: z.number().int().describe("Number of the request to reply on, as shown by list_requests."),
+				body: z.string().min(1).describe("The message to send. Visible to the support agents on the ticket and included in their email notification."),
+				attachments: attachmentsParam("Files to attach to this reply, such as a screenshot or a log, with their content base64-encoded.")
+			}),
+			annotations: {
+				readOnlyHint: false,
+				destructiveHint: false,
+				idempotentHint: false,
+				openWorldHint: true
+			},
+			handler: async (params) => {
+				const { request_id, body, attachments } = params;
+				const token = await getToken();
+				const uploads = attachments?.length ? [await uploadAttachments(subdomain, token, attachments)] : void 0;
+				const { request } = await withForbiddenGuidance("add_request_comment", `PUT /requests/${request_id}`, () => zendeskPut(subdomain, token, `/requests/${request_id}`, { request: { comment: {
+					body,
+					...uploads && { uploads }
+				} } }), OTHER_USERS_REQUEST_HINT);
+				return { content: [{
+					type: "text",
+					text: `Reply added to request #${request_id}${formatAttachmentSuffix(attachments?.length)}. It is now **${request.status}**.`
+				}] };
+			}
+		},
+		{
+			name: "mark_request_solved",
+			namespace: "requests",
+			readOnly: false,
+			title: "Mark My Request Solved",
+			description: "Close one of the signed-in user's own requests, for when they consider it resolved. Returns the request's status read back from Zendesk, not merely an acknowledgement: this operation is refused unless the request is actually solvable by its requester, because Zendesk answers 200 and changes nothing when it is not, which would otherwise be reported as success. A request is only solvable once an agent has been assigned to it, so a brand-new or unassigned one cannot be closed this way — leave it, or reply with add_request_comment to say it is no longer needed. Marking an already-solved request solved again is a no-op. Agents closing a ticket want update_ticket with status solved.",
+			inputSchema: z.object({ request_id: z.number().int().describe("Number of the request to close. Check get_request first: its \"can you mark it solved\" line has to say yes.") }),
+			annotations: {
+				readOnlyHint: false,
+				destructiveHint: true,
+				idempotentHint: true,
+				openWorldHint: true
+			},
+			handler: async (params) => {
+				const { request_id } = params;
+				const token = await getToken();
+				const endpoint = `/requests/${request_id}`;
+				const { request: before } = await withForbiddenGuidance("mark_request_solved", `GET ${endpoint}`, () => zendeskGet(subdomain, token, endpoint), OTHER_USERS_REQUEST_HINT);
+				if (before.status === "solved" || before.status === "closed") return { content: [{
+					type: "text",
+					text: `Request #${request_id} is already **${before.status}**. Nothing to do.`
+				}] };
+				if (!before.can_be_solved_by_me) return { content: [{
+					type: "text",
+					text: `Request #${request_id} cannot be marked solved by you: Zendesk only allows that once an agent has been assigned to it. It is currently **${before.status}**. Sending it anyway would return success and change nothing, so it was not sent. Use add_request_comment to tell the agents it is resolved on your side.`
+				}] };
+				const { request: after } = await withForbiddenGuidance("mark_request_solved", `PUT ${endpoint}`, () => zendeskPut(subdomain, token, endpoint, { request: { solved: true } }), OTHER_USERS_REQUEST_HINT);
+				return { content: [{
+					type: "text",
+					text: after.status === "solved" ? `Request #${request_id} is now **solved**.` : `Zendesk accepted the update but request #${request_id} is still **${after.status}**, so it was not solved. Two causes produce this silently: the token belongs to an agent rather than to the requester -- Zendesk answers 200 and ignores \`solved\` for them -- or the assignment changed between the check and the update. Re-read it with get_request.`
+				}] };
+			}
+		}
+	];
+};
+//#endregion
 //#region src/tools/search.ts
 const formatSearchResult = (result) => {
 	const lines = [`## [${result["result_type"]}] #${result["id"]}`];
@@ -3479,30 +4157,6 @@ const formatMacroPreviewDiff = (ticketId, macroId, before, result) => {
 };
 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).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) {
-			const { upload } = await zendeskUpload(subdomain, token, file.file_name, Buffer.from(file.file_base64, "base64"), file.content_type, uploadToken);
-			uploadToken = upload.token;
-		}
-		return uploadToken;
-	};
-	const formatAttachmentSuffix = (count) => count ? ` with ${count} attachment(s)` : "";
 	return [
 		{
 			name: "get_ticket",
@@ -3817,7 +4471,7 @@ const createTicketTools = (ctx) => {
 			handler: async (params) => {
 				const { ticket_id, body, attachments } = params;
 				const token = await getToken();
-				const uploads = attachments?.length ? [await uploadAttachments(token, attachments)] : void 0;
+				const uploads = attachments?.length ? [await uploadAttachments(subdomain, token, attachments)] : void 0;
 				await zendeskPut(subdomain, token, `/tickets/${ticket_id}`, { ticket: { comment: {
 					body,
 					public: false,
@@ -3849,7 +4503,7 @@ const createTicketTools = (ctx) => {
 			handler: async (params) => {
 				const { ticket_id, body, attachments } = params;
 				const token = await getToken();
-				const uploads = attachments?.length ? [await uploadAttachments(token, attachments)] : void 0;
+				const uploads = attachments?.length ? [await uploadAttachments(subdomain, token, attachments)] : void 0;
 				await zendeskPut(subdomain, token, `/tickets/${ticket_id}`, { ticket: { comment: {
 					body,
 					public: true,
@@ -4282,6 +4936,7 @@ const createUserTools = (ctx) => {
 //#region src/tools/index.ts
 const createAllTools = (ctx) => [
 	...createTicketTools(ctx),
+	...createRequestTools(ctx),
 	...createSearchTools(ctx),
 	...createHelpCenterTools(ctx),
 	...createUserTools(ctx)
@@ -4290,19 +4945,16 @@ const createAllTools = (ctx) => [
 //#region src/utils/validation.ts
 /**
 * Build a strict params parser for a tool's input schema, computing the strict
-* schema and the valid-key list once (at proxy-dispatch construction) rather
-* than per call.
+* schema and the valid-key list once at construction rather than per call.
 *
 * Zod objects default to `strip`, which silently drops unknown keys. That hid
 * #100: a caller passing `per_page` to list_tickets (whose parameter is
-* `page_size`) had the key dropped, so `page_size` fell back to its default and
-* a large unpaginated page came back. The returned parser rejects unknown keys
-* and rewrites the raw Zod error into a message that names the offending keys
-* and lists the valid parameters so a mistyped/misremembered name fails loudly.
+* `page_size`) had the key dropped, so a large unpaginated page came back. The
+* parser rejects unknown keys and names both the offending ones and the valid
+* parameters, so a misremembered name fails loudly.
 *
-* Used on the proxy dispatch path (namespace/single modes), where this code
-* owns the parse. In `all` mode the SDK validates against the strict schema we
-* register and produces its own (also explicit) "Unrecognized key" message.
+* Used on the proxy dispatch path (namespace/single modes); in `all` mode the
+* SDK validates against the strict schema we register.
 */
 const createStrictParamsParser = (schema) => {
 	const strict = schema.strict();
@@ -4319,17 +4971,15 @@ const createStrictParamsParser = (schema) => {
 //#region src/server.ts
 /**
 * Invoke a tool handler, notifying `onUnauthorized` when Zendesk rejects the
-* token (401). This lets the OAuth store drop the dead token so the next call
-* 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).
+* token (401), so the OAuth store drops the dead token instead of replaying it.
+* The callback is omitted only where there is nothing to invalidate (the 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.
+* The 401 is a *backstop*, not a transparent retry: the current call still
+* surfaces the error, and recovery happens on the *next* one, whose `getToken`
+* refreshes silently (or falls back to browser re-auth). Proactive refresh keeps
+* this rare — it fires only for a token revoked between the pre-call check and
+* the request.
 */
 const runHandler = async (def, params, onUnauthorized) => {
 	try {
@@ -4339,20 +4989,6 @@ const runHandler = async (def, params, onUnauthorized) => {
 		throw err;
 	}
 };
-const NAMESPACE_LABELS = {
-	tickets: {
-		toolName: "zendesk_tickets",
-		title: "Zendesk Tickets"
-	},
-	help_center: {
-		toolName: "zendesk_help_center",
-		title: "Zendesk Help Center"
-	},
-	users: {
-		toolName: "zendesk_users",
-		title: "Zendesk Users"
-	}
-};
 const summarizeDescription = (description) => {
 	const idx = description.indexOf(". ");
 	if (idx === -1) return description;
@@ -4436,8 +5072,9 @@ const registerToolset = (server, { config, getToken, onUnauthorized, logger = si
 	const filteredTools = filterTools(tools, {
 		readOnly: config.readOnly,
 		namespaces: config.namespaces,
-		tools: config.tools
-	}).filter((t) => config.promotedArticles !== false || t.name !== "list_promoted_articles");
+		tools: config.tools,
+		promotedArticles: config.promotedArticles
+	});
 	try {
 		switch (config.mode) {
 			case "all":
@@ -4557,6 +5194,10 @@ const TOOL_MODULES = [
 		file: "tickets.ts",
 		factory: "createTicketTools"
 	},
+	{
+		file: "requests.ts",
+		factory: "createRequestTools"
+	},
 	{
 		file: "search.ts",
 		factory: "createSearchTools"
@@ -4689,6 +5330,70 @@ const startDevServer = async (config, getToken, logger = silentLogger, onUnautho
 };
 /* v8 ignore stop */
 //#endregion
+//#region src/routing/print.ts
+const toolLine = (tool, indent) => `${indent}${tool.name}${tool.readOnly ? "" : " (write)"}`;
+const renderHeader = (config) => [
+	`Mode: ${config.mode}`,
+	`Namespaces: ${config.namespaces.join(", ")}`,
+	`Read-only: ${config.readOnly ? "yes" : "no"}`,
+	...config.tools?.length ? [`Tool filter: ${config.tools.join(", ")}`] : []
+].join(" | ");
+const renderAllMode = (tools) => [`${tools.length} tool(s) exposed individually:`, ...tools.map((tool) => toolLine(tool, "  "))];
+const renderNamespaceMode = (tools) => {
+	const grouped = groupByNamespace(tools);
+	const lines = [`${grouped.size} proxy tool(s) exposed:`];
+	for (const [namespace, nsTools] of grouped) {
+		lines.push(`  ${NAMESPACE_LABELS[namespace]?.toolName ?? namespace}`);
+		lines.push(...nsTools.map((tool) => toolLine(tool, "    - ")));
+	}
+	return lines;
+};
+const renderSingleMode = (tools) => [
+	`1 proxy tool exposed, wrapping ${tools.length} operation(s):`,
+	"  zendesk",
+	...tools.map((tool) => toolLine(tool, "    - "))
+];
+const renderBody = (config, tools) => {
+	switch (config.mode) {
+		case "all": return renderAllMode(tools);
+		case "namespace": return renderNamespaceMode(tools);
+		case "single": return renderSingleMode(tools);
+		default: {
+			const unhandled = config.mode;
+			throw new Error(`Unsupported tool mode: ${String(unhandled)}`);
+		}
+	}
+};
+/**
+* Render the tool surface `config` resolves to, as `registerToolset` would
+* expose it, without starting a server or issuing a request -- the combination
+* of `--namespace`/`--tool`, `--mode` and `--read-only` is easier read than
+* predicted.
+*
+* It mirrors `registerToolset`'s `switch (config.mode)` rather than calling it,
+* which would need a live `McpServer`; tests pin this output against the names
+* the integration harness sees over the wire.
+*
+* Read-only is stated in the header, not as a `[RO]` name prefix: the server
+* puts that marker in a proxy's description, so `[RO] zendesk_tickets` would
+* name a tool no client sees.
+*/
+const renderToolSurface = (config, tools) => {
+	const filtered = filterTools(tools, {
+		readOnly: config.readOnly,
+		namespaces: config.namespaces,
+		tools: config.tools,
+		promotedArticles: config.promotedArticles
+	});
+	const header = renderHeader(config);
+	if (filtered.length === 0) return `${header}\n\nNo tools exposed. Check --namespace / --tool / --read-only.`;
+	return [
+		header,
+		"",
+		...renderBody(config, filtered)
+	].join("\n");
+};
+//#endregion
 //#region src/transports/http.ts
 const WILDCARD_HOSTS = /* @__PURE__ */ new Set([
 	"0.0.0.0",
@@ -4791,12 +5496,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,
@@ -4806,7 +5512,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()
 		}
 	};
 };
@@ -5079,16 +5785,15 @@ const defaultRuntime = createRuntime(process);
 /**
 * Install the process's one shutdown path and return its trigger.
 *
-* Registering a `SIGTERM` handler *removes* Node's default terminate, which
-* makes the exit our responsibility: a cleanup that stalls on an in-flight
-* request would otherwise leave a process SIGTERM cannot kill — the very
-* symptom this exists to remove. Hence the watchdog, which is load-bearing
-* rather than defensive, and the unconditional `exit` on every path.
+* Registering a `SIGTERM` handler *removes* Node's default terminate, making
+* the exit our responsibility: a cleanup stalled on an in-flight request would
+* leave a process SIGTERM cannot kill — the symptom this exists to remove.
+* Hence the watchdog and the unconditional `exit` on every path.
 *
 * The exit is explicit rather than a drained event loop because the OAuth
 * callback server (`auth/browser-oauth.ts`) is a listening socket that is not
-* `unref()`'d: letting the loop drain would keep a disconnected session alive
-* for up to the 5-minute auth timeout.
+* `unref()`'d: draining would keep a disconnected session alive for the
+* 5-minute auth timeout.
 */
 const installShutdown = (options) => {
 	const { cleanup, logger, watchStdin, graceMs = SHUTDOWN_GRACE_MS } = options;
@@ -5129,7 +5834,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);
@@ -5139,6 +5845,14 @@ const connectStdio = async (config, tokenStore, logger) => {
 };
 const main = async () => {
 	const config = loadConfig();
+	if (config.printTools) {
+		const tools = createAllTools({
+			subdomain: config.subdomain,
+			getToken: () => ""
+		});
+		console.log(renderToolSurface(config, tools));
+		return;
+	}
 	const logger = createLogger(config.logLevel);
 	if (config.transport === "stdio") {
 		const tokenStore = buildStdioTokenStore(config, logger);