@fruggr/zendesk-mcp-server 2.21.0 → 2.22.0

package/README.md

@@ -7,10 +7,19 @@
 [![Node.js](https://img.shields.io/node/v/@fruggr/zendesk-mcp-server?logo=nodedotjs&logoColor=white&color=339933)](https://nodejs.org)
 
 A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that
-puts Zendesk inside your AI assistant. It finds answers in the Help Center;
-drafts, updates and translates articles while keeping the languages in sync; and
-handles Support tickets end to end, comments, triage and image attachments
-included. It all happens in plain language, without switching apps.
+puts Zendesk inside your AI assistant, for **both sides of the conversation**.
+
+**For agents**: it finds answers in the Help Center; drafts, updates and
+translates articles while keeping the languages in sync; and handles Support
+tickets end to end, comments, triage and image attachments included.
+
+**For your customers**: it opens the same door the Help Center's "Submit a
+request" form does. They pick the kind of request, get walked through the
+questions that form actually asks, attach a screenshot, then follow the
+ticket — read the replies, answer back, close it when it's resolved. See
+[End-user mode](#end-user-mode).
+
+It all happens in plain language, without switching apps.
 
 It does roughly what the
 [Zendesk agent for Microsoft 365 Copilot](https://support.zendesk.com/hc/en-us/articles/9958331458458-Using-the-Zendesk-agent-in-Microsoft-365-Copilot)
@@ -39,6 +48,9 @@ then calls the right tools on your behalf.
 - Draft and maintain knowledge-base articles. You can write a new one, or revise
   a large one a single section at a time, so the whole HTML body never has to
   round-trip through the model.
+- Submit and follow a request as a customer, not an agent. Choose between the
+  kinds of request the vendor offers, answer only the questions that form asks,
+  and then track it: what was replied, what you replied, and whether it's done.
 
 ## Why this server
 
@@ -51,6 +63,10 @@ differently.
   touches exactly what that person is allowed to, the same scoping you get by
   signing into Zendesk directly. Static API tokens are deliberately not
   supported ([why](#what-this-server-does-not-do)).
+- Two audiences, one server. Because auth is per-user rather than a shared admin
+  key, the same install serves your agents and your customers — the end-user
+  surface is a namespace you switch on, speaking the API path Zendesk reserves
+  for requesters. Most Zendesk MCP servers are agent-only by construction.
 - Section-based article editing. For large Help Center articles, read and
   rewrite one section at a time (parsed by `h1`/`h2`/`h3` headings) instead of
   shuffling the full HTML body through the assistant. On a targeted edit that
@@ -201,9 +217,10 @@ job: **[docs/http-deployment.md](docs/http-deployment.md)**.
 
 ## Tool surface
 
-Tools are grouped into four namespaces: **Tickets**, **Help Center**, **Users &
-Organizations** and **Search**. The server registers them in one of three modes,
-so you can trade granularity against context budget:
+Tools are grouped into namespaces: **Tickets**, **Help Center**, **Users &
+Organizations**, **Search**, and **Requests** — the end-user surface, which is
+opt-in and covered under [End-user mode](#end-user-mode). The server registers
+them in one of three modes, so you can trade granularity against context budget:
 
 - **`all`**: every operation as its own tool, for clients with good tool selection;
 - **`namespace`** (default): one proxy tool per namespace, a balanced middle ground;
@@ -214,10 +231,81 @@ Proxies take `{ "operation": "<tool_name>", "params": { … } }` and validate
 filter tools *before* the proxies are built, so each proxy describes only the
 operations that survive.
 
+There's one way to pick the inventory (`--namespace` / `--tool`), `--mode`
+packages it, and `--read-only` narrows it. When the combination isn't obvious,
+don't guess — `--print-tools` has the server answer what it would expose, with
+no credentials needed.
+
 Every tool with its description and its `read`/`write` mode:
 **[docs/mcp-tools-reference.md](docs/mcp-tools-reference.md)**. The flags and
 worked examples: **[docs/configuration.md](docs/configuration.md)**.
 
+## End-user mode
+
+The audience for everything above is a Zendesk **agent**. This section is about
+the other one: your **customers**.
+
+On the web, a customer opens a ticket through the Help Center's "Submit a
+request" form — they pick a kind of request, fill in the fields that kind asks
+for, attach a file, and later come back to read the replies. End-user mode is
+that same journey, in their assistant.
+
+### Who it's for
+
+A vendor pointing their customers at an MCP server, so support happens where
+those customers already work. They install it themselves, sign in with their
+own Help Center account, and never see anything that isn't theirs.
+
+### Turning it on
+
+The end-user tools live in the `requests` namespace, and it is **opt-in**: an
+agent install shouldn't inherit tools built for someone else, and one of them
+(marking a request solved) doesn't work under an agent token at all — Zendesk
+accepts it and silently does nothing. `help_center` is worth serving alongside
+it, since a customer who can search the knowledge base often doesn't need to
+open a ticket in the first place.
+
+The flags, and how to have the server print what a combination exposes:
+**[docs/configuration.md](docs/configuration.md)**.
+
+### The journey it supports
+
+- **See what kinds of request are available.** The forms the vendor offers, by
+  their customer-facing names.
+- **Learn what one of them asks.** The questions on that form, which are
+  required, and for dropdowns the exact choices — so the assistant can gather
+  them in conversation instead of guessing at a payload.
+- **Submit it**, with attachments.
+- **Follow it.** List their requests, read one with its whole conversation
+  (each reply attributed, and support agents marked as such), reply back, and
+  mark it solved when it is.
+
+### What it asks of the Zendesk account
+
+Nothing the agent side doesn't already need, plus one thing: at least one
+ticket form marked visible to end users, because that is what a customer picks
+between. Sign-in is interactive, through a browser, by design — there is no
+scripted or headless path to an end-user token, which is the same protection
+that stops anyone else signing in as your customer.
+
+The prerequisites in full: **[docs/configuration.md](docs/configuration.md)**.
+The step-by-step walkthrough, written for someone who doesn't work in a
+terminal: **[docs/end-user-onboarding.md](docs/end-user-onboarding.md)**.
+
+### What a customer can't do — and shouldn't
+
+A customer can do less than an agent. That's the point, not a gap:
+
+- **Only their own tickets.** Enforced by Zendesk, not by us.
+- **No internal notes**, in either direction. Agent-only notes never appear in
+  what this surface returns — Zendesk filters them out of the requester's view
+  of a ticket entirely.
+- **No priority or type.** Zendesk drops both when a customer sets them;
+  triage stays with the agents.
+- **Closing a ticket only once an agent has picked it up.** Until then Zendesk
+  won't let the requester solve it, so the tool says so rather than pretending.
+- **No search across the ticket base**, no user lookups, no views, no macros.
+
 ## Help Center context
 
 Beyond tools, the server hands the LLM the structure of *your* Help Center: the

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`;
@@ -696,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"),
@@ -705,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`
@@ -756,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),
@@ -805,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([
@@ -823,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({
@@ -862,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({
@@ -870,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)
 	});
@@ -1387,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) : []);
@@ -1621,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;
@@ -1898,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) => {
@@ -1913,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) => {
@@ -3181,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"]}`];
@@ -3543,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",
@@ -3881,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,
@@ -3913,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,
@@ -4346,6 +4936,7 @@ const createUserTools = (ctx) => {
 //#region src/tools/index.ts
 const createAllTools = (ctx) => [
 	...createTicketTools(ctx),
+	...createRequestTools(ctx),
 	...createSearchTools(ctx),
 	...createHelpCenterTools(ctx),
 	...createUserTools(ctx)
@@ -4354,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();
@@ -4383,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 {
@@ -4403,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;
@@ -4500,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":
@@ -4621,6 +5194,10 @@ const TOOL_MODULES = [
 		file: "tickets.ts",
 		factory: "createTicketTools"
 	},
+	{
+		file: "requests.ts",
+		factory: "createRequestTools"
+	},
 	{
 		file: "search.ts",
 		factory: "createSearchTools"
@@ -4753,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",
@@ -5144,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;
@@ -5205,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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fruggr/zendesk-mcp-server",
-  "version": "2.21.0",
+  "version": "2.22.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",
@@ -69,13 +69,13 @@
   "engines": {
     "node": ">=20"
   },
-  "packageManager": "pnpm@11.25.0+sha512.5cde925b4f075f725eb71fbae18a42ffe784524789f19b61c731cb8721ec28aaee160e01a8d5af4fedb2a42cdbf300efe23db356b0d4a17b4d63e11f8ab7c956",
+  "packageManager": "pnpm@12.4.2+sha512.08adc6613180275c7c9edada39dcf08c9c61ad4e7eaf330a4f3461f102b0f907423454d117f98e72d47fef0616070644d7bffc973a6a57f5090a6d7c368b07c9",
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.0",
     "cheerio": "1.2.0",
     "hast-util-to-html": "9.0.5",
     "hast-util-to-mdast": "10.1.2",
-    "open": "11.0.1",
+    "open": "11.0.2",
     "rehype-parse": "9.0.1",
     "rehype-raw": "7.0.0",
     "rehype-remark": "10.0.1",
@@ -85,7 +85,7 @@
     "remark-rehype": "11.1.2",
     "remark-stringify": "11.0.0",
     "unified": "11.0.5",
-    "zod": "4.5.4"
+    "zod": "4.6.2"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.12",