npm - @fruggr/zendesk-mcp-server - Versions diffs - 2.15.0 → 2.16.1 - Mend

@fruggr/zendesk-mcp-server 2.15.0 → 2.16.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/dist/index.js CHANGED Viewed

@@ -7,7 +7,7 @@ import open from "open";
 import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import * as z from "zod/v4";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as cheerio from "cheerio";
 import { toHtml } from "hast-util-to-html";
 import rehypeParse from "rehype-parse";
@@ -47,14 +47,22 @@ const REDACTED_KEYS = /* @__PURE__ */ new Set([
 	"bearer"
 ]);
 const isSensitive = (key) => REDACTED_KEYS.has(key.toLowerCase().replace(/[_-]/g, ""));
-const redactValue = (value) => {
-	if (Array.isArray(value)) return value.map(redactValue);
-	if (value && typeof value === "object") {
-		const out = {};
-		for (const [key, val] of Object.entries(value)) out[key] = isSensitive(key) ? "[REDACTED]" : redactValue(val);
-		return out;
+const redactValue = (value, path = /* @__PURE__ */ new WeakSet()) => {
+	if (typeof value === "function") return "[function]";
+	if (!value || typeof value !== "object") return value;
+	if (path.has(value)) return "[circular]";
+	path.add(value);
+	const out = Array.isArray(value) ? value.map((item) => redactValue(item, path)) : Object.fromEntries(Object.entries(value).map(([key, val]) => [key, isSensitive(key) ? "[REDACTED]" : redactValue(val, path)]));
+	path.delete(value);
+	return out;
+};
+const sanitise = (fields) => {
+	if (!fields) return {};
+	try {
+		return redactValue(fields);
+	} catch {
+		return { fields: "[unredactable]" };
 	}
-	return value;
 };
 const renderValue = (value) => {
 	if (typeof value === "string") return value;
@@ -82,8 +90,10 @@ const createLogger = (level) => {
 	let server;
 	const emit = (lvl, event, fields) => {
 		if (SEVERITY[lvl] < min) return;
-		const safe = fields ? redactValue(fields) : {};
-		console.error(formatLine(lvl, event, safe));
+		const safe = sanitise(fields);
+		try {
+			console.error(formatLine(lvl, event, safe));
+		} catch {}
 		if (server) try {
 			server.sendLoggingMessage({
 				level: MCP_LEVEL[lvl],
@@ -114,6 +124,7 @@ const positiveIntEnv = (name, fallback) => {
 	const parsed = Number(raw);
 	return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback;
 };
+const ARTICLE_RESOURCES_SCAN_MAX_PAGES = positiveIntEnv("ZENDESK_ARTICLE_RESOURCES_SCAN_MAX_PAGES", 20);
 const MAX_ATTACHMENT_BYTES = positiveIntEnv("ZENDESK_MAX_ATTACHMENT_BYTES", 5 * 1024 * 1024);
 const MAX_EMBEDDED_IMAGE_COUNT = positiveIntEnv("ZENDESK_MAX_EMBEDDED_IMAGES", 10);
 const MAX_COMMENT_PAGES = positiveIntEnv("ZENDESK_MAX_COMMENT_PAGES", 10);
@@ -153,6 +164,8 @@ const callbackPortInUseError = (port, cause) => Object.assign(/* @__PURE__ */ ne
 * browser response; without escaping these are a reflected-XSS sink.
 */
 const escapeHtml = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+const errorPage = (title, detail) => `<html><body><h1>${escapeHtml(title)}</h1>${detail === void 0 ? "" : `<p>${escapeHtml(detail)}</p>`}</body></html>`;
+const SUCCESS_PAGE = "<html><body><h1>Authentication successful!</h1><p>You can close this tab and return to your AI assistant.</p><p>This tab will auto-close in <span id=\"t\">10</span>s.</p><script>let n=10;const el=document.getElementById(\"t\");const i=setInterval(()=>{n--;el.textContent=n;if(n<=0){clearInterval(i);window.close();}},1000);<\/script></body></html>";
 const generateCodeVerifier = () => randomBytes(32).toString("base64url");
 const generateCodeChallenge = (verifier) => createHash("sha256").update(verifier).digest("base64url");
 /**
@@ -178,69 +191,92 @@ const startBrowserAuth = (config, logger = silentLogger) => {
 		});
 		let authTimeout;
 		let callbackServer;
-		callbackServer = createServer(async (req, res) => {
-			const url = new URL(req.url ?? "/", `http://localhost`);
-			if (url.pathname !== "/callback") {
-				res.writeHead(404);
-				res.end("Not found");
-				return;
+		const exchangeCodeForToken = async (code) => {
+			const callbackPort = callbackServer.address().port;
+			const tokenBody = new URLSearchParams({
+				grant_type: "authorization_code",
+				code,
+				client_id: oauthClientId,
+				redirect_uri: `http://localhost:${callbackPort}/callback`,
+				code_verifier: codeVerifier
+			});
+			const tokenResponse = await fetch(tokenUrl, {
+				method: "POST",
+				headers: { "Content-Type": "application/x-www-form-urlencoded" },
+				body: tokenBody.toString()
+			});
+			logger.debug("oauth_token_exchange", { status: tokenResponse.status });
+			if (!tokenResponse.ok) {
+				const errorBody = await tokenResponse.text();
+				throw new Error(`Token exchange failed (${tokenResponse.status}): ${errorBody}`);
 			}
-			const code = url.searchParams.get("code");
+			return await tokenResponse.json();
+		};
+		const finishRequest = (res, { status, html, outcome }) => {
+			res.writeHead(status, { "Content-Type": "text/html" });
+			res.end(html);
+			clearTimeout(authTimeout);
+			callbackServer.close();
+			if (outcome.ok) resolveToken(outcome.token);
+			else rejectToken(outcome.error);
+		};
+		const resolveCallback = async (url) => {
 			const error = url.searchParams.get("error");
+			const code = url.searchParams.get("code");
 			logger.debug("oauth_callback_received", {
 				hasCode: Boolean(code),
 				hasError: Boolean(error)
 			});
 			if (error) {
 				const desc = url.searchParams.get("error_description") ?? error;
-				res.writeHead(400, { "Content-Type": "text/html" });
-				res.end(`<html><body><h1>Authentication failed</h1><p>${escapeHtml(desc)}</p></body></html>`);
-				clearTimeout(authTimeout);
-				callbackServer.close();
-				rejectToken(/* @__PURE__ */ new Error(`OAuth error: ${desc}`));
-				return;
-			}
-			if (!code) {
-				res.writeHead(400, { "Content-Type": "text/html" });
-				res.end("<html><body><h1>Missing authorization code</h1></body></html>");
-				clearTimeout(authTimeout);
-				callbackServer.close();
-				rejectToken(/* @__PURE__ */ new Error("Missing authorization code in callback"));
-				return;
+				return {
+					status: 400,
+					html: errorPage("Authentication failed", desc),
+					outcome: {
+						ok: false,
+						error: /* @__PURE__ */ new Error(`OAuth error: ${desc}`)
+					}
+				};
 			}
-			try {
-				const callbackPort = callbackServer.address().port;
-				const tokenBody = new URLSearchParams({
-					grant_type: "authorization_code",
-					code,
-					client_id: oauthClientId,
-					redirect_uri: `http://localhost:${callbackPort}/callback`,
-					code_verifier: codeVerifier
-				});
-				const tokenResponse = await fetch(tokenUrl, {
-					method: "POST",
-					headers: { "Content-Type": "application/x-www-form-urlencoded" },
-					body: tokenBody.toString()
-				});
-				logger.debug("oauth_token_exchange", { status: tokenResponse.status });
-				if (!tokenResponse.ok) {
-					const errorBody = await tokenResponse.text();
-					throw new Error(`Token exchange failed (${tokenResponse.status}): ${errorBody}`);
+			if (!code) return {
+				status: 400,
+				html: errorPage("Missing authorization code"),
+				outcome: {
+					ok: false,
+					error: /* @__PURE__ */ new Error("Missing authorization code in callback")
 				}
-				const tokenData = await tokenResponse.json();
+			};
+			try {
+				const token = await exchangeCodeForToken(code);
 				logger.info("oauth_authenticated");
-				res.writeHead(200, { "Content-Type": "text/html" });
-				res.end("<html><body><h1>Authentication successful!</h1><p>You can close this tab and return to your AI assistant.</p><p>This tab will auto-close in <span id=\"t\">10</span>s.</p><script>let n=10;const el=document.getElementById(\"t\");const i=setInterval(()=>{n--;el.textContent=n;if(n<=0){clearInterval(i);window.close();}},1000);<\/script></body></html>");
-				clearTimeout(authTimeout);
-				callbackServer.close();
-				resolveToken(tokenData);
+				return {
+					status: 200,
+					html: SUCCESS_PAGE,
+					outcome: {
+						ok: true,
+						token
+					}
+				};
 			} catch (err) {
-				res.writeHead(500, { "Content-Type": "text/html" });
-				res.end(`<html><body><h1>Token exchange failed</h1><p>${escapeHtml(err instanceof Error ? err.message : String(err))}</p></body></html>`);
-				clearTimeout(authTimeout);
-				callbackServer.close();
-				rejectToken(err);
+				const detail = err instanceof Error ? err.message : String(err);
+				return {
+					status: 500,
+					html: errorPage("Token exchange failed", detail),
+					outcome: {
+						ok: false,
+						error: err
+					}
+				};
+			}
+		};
+		callbackServer = createServer(async (req, res) => {
+			const url = new URL(req.url ?? "/", `http://localhost`);
+			if (url.pathname !== "/callback") {
+				res.writeHead(404);
+				res.end("Not found");
+				return;
 			}
+			finishRequest(res, await resolveCallback(url));
 		});
 		const requestedPort = config.callbackPort ?? 27439;
 		const onStartError = (err) => {
@@ -383,9 +419,10 @@ const isWindows = process.platform === "win32";
 * (`@fruggr/zendesk-mcp-server` → `fruggr` + `zendesk-mcp-server`) so the path is
 * vendor-namespaced and can't collide with another `zendesk-mcp-server`.
 */
+const SCOPED_PACKAGE_NAME = /^@([^/]+)\/(.+)$/;
 const appDirSegments = () => {
 	const { name } = readPackageInfo();
-	const scoped = /^@([^/]+)\/(.+)$/.exec(name);
+	const scoped = SCOPED_PACKAGE_NAME.exec(name);
 	return scoped?.[1] && scoped[2] ? [scoped[1], scoped[2]] : [name];
 };
 const configDir = () => {
@@ -521,20 +558,23 @@ const createTokenStore = (config, logger = silentLogger) => {
 			throw err;
 		});
 	};
+	const refreshIfPossible = async () => {
+		const current = token;
+		if (!current?.refreshToken) return void 0;
+		if (refreshing === void 0) refreshing = tryRefresh(current).finally(() => {
+			refreshing = void 0;
+		});
+		return refreshing;
+	};
 	const getToken = async () => {
-		if (refreshing) await refreshing;
+		if (refreshing !== void 0) await refreshing;
 		if (token && !needsRefresh(token)) {
 			logger.debug("oauth_token_cache_hit");
 			return token.accessToken;
 		}
-		if (token?.refreshToken) {
-			if (!refreshing) refreshing = tryRefresh(token).finally(() => {
-				refreshing = void 0;
-			});
-			const refreshed = await refreshing;
-			if (refreshed) return refreshed;
-		}
-		if (!starting) starting = beginAuth();
+		const refreshed = await refreshIfPossible();
+		if (refreshed) return refreshed;
+		if (starting === void 0) starting = beginAuth();
 		const url = authorizeUrl ?? await starting;
 		throw createAuthRequiredError(url);
 	};
@@ -603,6 +643,18 @@ const ConfigSchema = z.object({
 	*/
 	topology: z.boolean().default(true),
 	/**
+	* Whether to PRE-LIST the promoted ("featured") Help Center articles: the
+	* `<scheme>://article/{id}` resource's `list` callback (which scans `/articles`
+	* to enumerate the promoted set for `resources/list`) AND the
+	* `list_promoted_articles` tool. On by default; an operator disables the
+	* pre-listing with `--no-promoted-articles` (e.g. on a very large Help Center
+	* where scanning is costly) so the server issues zero preloading requests. This
+	* does NOT disable reading a known article by id (`<scheme>://article/{id}` stays
+	* registered) — that is cheap and on-demand. Only ever active when the
+	* `help_center` namespace itself is active.
+	*/
+	promotedArticles: z.boolean().default(true),
+	/**
 	* URI scheme of the Help Center MCP resources (today the topology resource,
 	* `<scheme>://topology`). Defaults to `zendesk-hc`; a deployer can brand it
 	* (`--hc-resource-scheme wiki` / `HC_RESOURCE_SCHEME=wiki`). Strictly a bare
@@ -644,75 +696,96 @@ const ConfigSchema = z.object({
 	corsOrigins: z.array(z.string().url().transform((value) => new URL(value).origin).refine((origin) => origin !== "null", { message: "CORS origin must be an http(s) URL with a host" })).default([]),
 	callbackPort: z.number().int().min(1).max(65535).optional()
 });
+const DIGITS_ONLY = /^\d+$/;
 const parsePort = (raw, label) => {
-	if (!/^\d+$/.test(raw)) throw new Error(`Invalid ${label} value. Expected an integer 0-65535.`);
+	if (!DIGITS_ONLY.test(raw)) throw new Error(`Invalid ${label} value. Expected an integer 0-65535.`);
 	return Number(raw);
 };
 const parsePortEnv = (raw, label) => raw === void 0 || raw === "" ? void 0 : parsePort(raw, label);
+const appendTo = (key) => (result, value) => {
+	const list = result[key] ?? [];
+	list.push(value);
+	result[key] = list;
+};
+const STANDALONE_FLAGS = /* @__PURE__ */ new Map([
+	["--read-only", (result) => {
+		result.readOnly = true;
+	}],
+	["--no-topology", (result) => {
+		result.topology = false;
+	}],
+	["--no-promoted-articles", (result) => {
+		result.promotedArticles = false;
+	}],
+	["--dev", (result) => {
+		result.dev = true;
+	}]
+]);
+const VALUED_FLAGS = /* @__PURE__ */ new Map([
+	["--mode", (result, value) => {
+		result.mode = value;
+	}],
+	["--hc-resource-scheme", (result, value) => {
+		result.hcResourceScheme = value;
+	}],
+	["--log-level", (result, value) => {
+		result.logLevel = value;
+	}],
+	["--transport", (result, value) => {
+		result.transport = value;
+	}],
+	["--host", (result, value) => {
+		result.host = value;
+	}],
+	["--public-url", (result, value) => {
+		result.publicUrl = value;
+	}],
+	["--port", (result, value) => {
+		result.port = parsePort(value, "--port");
+	}],
+	["--callback-port", (result, value) => {
+		result.callbackPort = parsePort(value, "--callback-port");
+	}],
+	["--namespace", appendTo("namespaces")],
+	["--tool", appendTo("tools")],
+	["--cors-origin", appendTo("corsOrigins")]
+]);
 const parseCliArgs = (args) => {
 	const result = {};
-	let positionalIndex = 0;
 	for (let i = 0; i < args.length; i++) {
 		const arg = args[i];
 		if (arg === void 0) continue;
+		const standalone = STANDALONE_FLAGS.get(arg);
+		if (standalone) {
+			standalone(result);
+			continue;
+		}
+		const valued = VALUED_FLAGS.get(arg);
 		const next = args[i + 1];
-		if (arg === "--mode" && next) {
-			result.mode = next;
-			i++;
-		} else if (arg === "--read-only") result.readOnly = true;
-		else if (arg === "--no-topology") result.topology = false;
-		else if (arg === "--hc-resource-scheme" && next) {
-			result.hcResourceScheme = next;
-			i++;
-		} else if (arg === "--dev") result.dev = true;
-		else if (arg === "--namespace" && next) {
-			result.namespaces = result.namespaces ?? [];
-			result.namespaces.push(next);
-			i++;
-		} else if (arg === "--tool" && next) {
-			result.tools = result.tools ?? [];
-			result.tools.push(next);
-			i++;
-		} else if (arg === "--log-level" && next) {
-			result.logLevel = next;
-			i++;
-		} else if (arg === "--transport" && next) {
-			result.transport = next;
-			i++;
-		} else if (arg === "--host" && next) {
-			result.host = next;
-			i++;
-		} else if (arg === "--port" && next) {
-			result.port = parsePort(next, "--port");
-			i++;
-		} else if (arg === "--public-url" && next) {
-			result.publicUrl = next;
-			i++;
-		} else if (arg === "--cors-origin" && next) {
-			result.corsOrigins = result.corsOrigins ?? [];
-			result.corsOrigins.push(next);
-			i++;
-		} else if (arg === "--callback-port" && next) {
-			result.callbackPort = parsePort(next, "--callback-port");
+		if (valued && next) {
+			valued(result, next);
 			i++;
-		} else if (!arg.startsWith("-") && positionalIndex === 0) {
-			result.subdomain = arg;
-			positionalIndex++;
+			continue;
 		}
+		if (!arg.startsWith("-") && result.subdomain === void 0) result.subdomain = arg;
 	}
 	return result;
 };
+const resolveTransportSettings = (cli) => {
+	const corsFromEnv = (process.env["CORS_ORIGIN"] ?? "").split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+	return {
+		transport: cli.transport ?? process.env["TRANSPORT"] ?? "stdio",
+		host: cli.host ?? process.env["HOST"] ?? "0.0.0.0",
+		port: cli.port ?? parsePortEnv(process.env["PORT"], "PORT") ?? 3e3,
+		publicUrl: cli.publicUrl ?? process.env["PUBLIC_URL"],
+		corsOrigins: [...cli.corsOrigins ?? [], ...corsFromEnv]
+	};
+};
 const loadConfig = (argv = process.argv.slice(2)) => {
 	const cli = parseCliArgs(argv);
 	const subdomain = cli.subdomain ?? process.env["ZENDESK_SUBDOMAIN"] ?? "";
 	const oauthClientId = process.env["ZENDESK_OAUTH_CLIENT_ID"] ?? (subdomain ? `${subdomain}_zendesk` : "");
 	const mode = cli.tools?.length ? "all" : cli.mode ?? "namespace";
-	const transport = cli.transport ?? process.env["TRANSPORT"] ?? "stdio";
-	const host = cli.host ?? process.env["HOST"] ?? "0.0.0.0";
-	const port = cli.port ?? parsePortEnv(process.env["PORT"], "PORT") ?? 3e3;
-	const publicUrl = cli.publicUrl ?? process.env["PUBLIC_URL"];
-	const corsFromEnv = (process.env["CORS_ORIGIN"] ?? "").split(",").map((s) => s.trim()).filter((s) => s.length > 0);
-	const corsOrigins = [...cli.corsOrigins ?? [], ...corsFromEnv];
 	const callbackPort = cli.callbackPort ?? parsePortEnv(process.env["ZENDESK_OAUTH_CALLBACK_PORT"], "ZENDESK_OAUTH_CALLBACK_PORT");
 	const hcResourceScheme = cli.hcResourceScheme ?? (process.env["HC_RESOURCE_SCHEME"] || void 0);
 	return ConfigSchema.parse({
@@ -724,14 +797,11 @@ const loadConfig = (argv = process.argv.slice(2)) => {
 		namespaces: cli.namespaces,
 		tools: cli.tools,
 		topology: cli.topology ?? true,
+		promotedArticles: cli.promotedArticles ?? true,
 		hcResourceScheme,
 		dev: cli.dev ?? false,
-		transport,
-		host,
-		port,
-		publicUrl,
-		corsOrigins,
-		callbackPort
+		callbackPort,
+		...resolveTransportSettings(cli)
 	});
 };
 //#endregion
@@ -872,44 +942,100 @@ const helpCenterUpload = async (subdomain, token, path, formData) => {
 	return response.json();
 };
 //#endregion
-//#region src/guidance/instructions.ts
-/**
-* URI of the dynamic Help Center topology resource. Single source of truth for
-* every place that cites it (resource registration, `instructions` blob): the
-* scheme comes from the config (`--hc-resource-scheme`, default `zendesk-hc`),
-* the path is fixed. Any future Help Center resource should build its URI the
-* same way so the whole surface follows the configured scheme.
-*/
-const topologyResourceUri = (config) => `${config.hcResourceScheme}://topology`;
-/**
-* Whether the Help Center structural context (init instructions + the
-* topology resource, default `zendesk-hc://topology`) should be exposed. True only when the
-* feature is enabled (`--no-topology` not set) AND the `help_center` namespace
-* is active (no `--namespace` filter, or one that includes it). Shared by the
-* instructions builder and the resource registration in `server.ts` so both
-* gates stay in sync.
-*/
-const helpCenterContextEnabled = (config) => config.topology && (!config.namespaces?.length || config.namespaces.includes("help_center"));
-/**
-* The static `instructions` blob sent on `initialize`. Deliberately short and
-* I/O-free: it must not trigger the lazy OAuth/PKCE flow just to connect, and
-* it stays within a tight token budget. The rich, dynamic topology lives in the
-* pull-only topology resource (default `zendesk-hc://topology`) referenced here.
-*/
-const buildInstructions = (config) => {
-	if (!helpCenterContextEnabled(config)) return void 0;
-	return [
-		`This MCP server is connected to the Zendesk Help Center of "${config.subdomain}".`,
-		"",
-		`When creating or editing Help Center content, the resource ${topologyResourceUri(config)} is useful context:`,
-		"it lists the active locales (and the default one), the category → section tree with IDs,",
-		"the visibility user segments, the permission groups, and your current role.",
-		"Prefer its IDs (section_id, permission_group_id, user_segment_id, locale) over guessing from names.",
-		"",
-		"It degrades gracefully: without Guide-admin / Help Center manager rights the permission-groups and",
-		"user-segments sections are marked unavailable (not empty). In that case reuse a permission_group_id",
-		"or user_segment_id from an existing article (get_article) instead."
-	].join("\n");
+//#region src/utils/article-sections.ts
+const HEADING_LEVELS = /* @__PURE__ */ new Set([
+	"h1",
+	"h2",
+	"h3"
+]);
+const WHITESPACE_RUN = /\s+/;
+const countWords = (text) => {
+	const trimmed = text.trim();
+	if (!trimmed) return 0;
+	return trimmed.split(WHITESPACE_RUN).length;
+};
+const textOf = (html) => {
+	if (!html) return "";
+	return cheerio.load(`<div>${html}</div>`, null, false)("div").first().text();
+};
+const parseSections = (html) => {
+	if (!html?.trim()) return [];
+	const $ = cheerio.load(html, null, false);
+	const children = $.root().contents().toArray();
+	const introParts = [];
+	const sections = [];
+	let current = null;
+	for (const node of children) {
+		const tagName = node.type === "tag" ? node.name.toLowerCase() : "";
+		if (HEADING_LEVELS.has(tagName)) {
+			const level = Number.parseInt(tagName.slice(1), 10);
+			current = {
+				heading: $(node).text().trim(),
+				headingTag: tagName,
+				level,
+				contentParts: []
+			};
+			sections.push(current);
+			continue;
+		}
+		const outer = $.html(node);
+		if (current) current.contentParts.push(outer);
+		else introParts.push(outer);
+	}
+	const result = [];
+	if (introParts.length > 0) {
+		const introHtml = introParts.join("");
+		result.push({
+			index: 0,
+			heading: "intro",
+			headingTag: "",
+			level: 0,
+			html: introHtml,
+			wordCount: countWords(textOf(introHtml))
+		});
+	}
+	for (const s of sections) {
+		const sectionHtml = s.contentParts.join("");
+		result.push({
+			index: result.length,
+			heading: s.heading,
+			headingTag: s.headingTag,
+			level: s.level,
+			html: sectionHtml,
+			wordCount: countWords(textOf(sectionHtml))
+		});
+	}
+	return result;
+};
+const replaceSectionContent = (html, sectionIndex, newHtml) => {
+	const sections = parseSections(html);
+	if (sectionIndex < 0 || sectionIndex >= sections.length) throw new Error(`Section index ${sectionIndex} out of range (valid: 0-${Math.max(0, sections.length - 1)})`);
+	return sections.map((section, idx) => {
+		const content = idx === sectionIndex ? newHtml : section.html;
+		if (section.level === 0) return content;
+		return `<${section.headingTag}>${section.heading}</${section.headingTag}>${content}`;
+	}).join("");
+};
+const keepAsHtml = (_state, node) => ({
+	type: "html",
+	value: toHtml(node)
+});
+const htmlToMdProcessor = unified().use(rehypeParse, { fragment: true }).use(rehypeRemark, { handlers: {
+	table: keepAsHtml,
+	pre: keepAsHtml
+} }).use(remarkGfm).use(remarkStringify, {
+	bullet: "-",
+	emphasis: "_",
+	fences: true
+});
+const mdToHtmlProcessor = unified().use(remarkParse).use(remarkGfm).use(remarkRehype, { allowDangerousHtml: true }).use(rehypeRaw).use(rehypeStringify);
+const htmlToMarkdown = (html) => {
+	if (!html) return "";
+	return String(htmlToMdProcessor.processSync(html));
+};
+const markdownToHtml = (markdown) => {
+	if (!markdown) return "";
+	return String(mdToHtmlProcessor.processSync(markdown));
 };
 //#endregion
 //#region src/utils/formatting.ts
@@ -930,7 +1056,11 @@ const formatTicket = (ticket) => [
 	`- **Created**: ${ticket.created_at} | **Updated**: ${ticket.updated_at}`,
 	ticket.description ? `\n${ticket.description}` : ""
 ].filter(Boolean).join("\n");
-const formatConditionValue = (value) => value === null || value === void 0 ? "" : typeof value === "object" ? JSON.stringify(value) : String(value);
+const formatConditionValue = (value) => {
+	if (value === null || value === void 0) return "";
+	if (typeof value === "object") return JSON.stringify(value);
+	return String(value);
+};
 const formatSlaPolicy = (policy) => {
 	const conditions = [...policy.filter.all.map((c) => `all: ${c.field} ${c.operator} ${formatConditionValue(c.value)}`.trim()), ...policy.filter.any.map((c) => `any: ${c.field} ${c.operator} ${formatConditionValue(c.value)}`.trim())];
 	const targets = policy.policy_metrics.map((m) => `  - ${m.priority} / ${m.metric}: ${m.target} min${m.business_hours ? " (business)" : ""}`);
@@ -1107,6 +1237,7 @@ const formatArticleSummary = (article) => [
 	`## ${article.title} (${article.id})`,
 	`- **Locale**: ${article.locale} | **Source locale**: ${article.source_locale}`,
 	`- **Section**: ${article.section_id} | **Draft**: ${article.draft}`,
+	article.promoted ? "- **Promoted**: featured in its section — changing this requires Help Center admin (Guide admin) rights; set via update_article `promoted`." : "",
 	`- **Permission group**: ${article.permission_group_id} | **User segment**: ${article.user_segment_id ?? "everyone (no segment)"}`,
 	typeof article.position === "number" ? `- **Position**: ${article.position}` : "",
 	article.label_names.length > 0 ? `- **Labels**: ${article.label_names.join(", ")}` : "",
@@ -1178,6 +1309,195 @@ const extractSearchPaginationMeta = (response, perPage, page) => {
 	};
 };
 //#endregion
+//#region src/guidance/article-resources.ts
+/**
+* Name of the companion tool that lists promoted articles. Shared between the
+* tool definition (`help-center.ts`) and the `--no-promoted-articles` opt-out
+* filter (`server.ts`) so the two can never drift: renaming the tool here keeps
+* the filter dropping it, preserving the "zero preloading requests when off"
+* invariant.
+*/
+const LIST_PROMOTED_ARTICLES_TOOL = "list_promoted_articles";
+/**
+* Scan the Help Center for promoted ("featured") articles with the CALLER'S
+* token, so the result respects that user's read permissions. The API exposes no
+* server-side `promoted` filter (only label_names / sort), so we page through
+* `/articles` and filter `promoted` client-side, bounded by `maxPages` to keep
+* the scan tractable on a large Help Center. `truncated` signals the cap was hit.
+*
+* Returns the FULL promoted articles so callers that need rich metadata (the
+* `list_promoted_articles` tool) get everything; the resource provider maps these
+* down to lean refs before caching so the per-session cache doesn't retain bodies.
+*/
+const fetchPromotedArticles = async (subdomain, token, maxPages = ARTICLE_RESOURCES_SCAN_MAX_PAGES) => {
+	const promoted = [];
+	let cursor;
+	let pages = 0;
+	let truncated = false;
+	do {
+		const response = await helpCenterGet(subdomain, token, "/articles", buildCursorParams(100, cursor));
+		const articles = response.articles ?? [];
+		for (const article of articles) if (article.promoted) promoted.push(article);
+		pages += 1;
+		const meta = extractPaginationMeta(response, articles.length);
+		cursor = meta.has_more ? meta.after_cursor ?? void 0 : void 0;
+		if (cursor && pages >= maxPages) {
+			truncated = true;
+			break;
+		}
+	} while (cursor);
+	return {
+		articles: promoted,
+		truncated,
+		pagesScanned: pages
+	};
+};
+/**
+* Fetch a single article by id (optionally a translated locale) with the
+* caller's token and render it as Markdown: the shared metadata summary plus the
+* body converted from HTML (rather than a raw HTML dump), capped by the response
+* character limit. Reuses the same formatting as the `get_article` tool.
+*/
+const fetchArticleMarkdown = async (subdomain, token, id, locale) => {
+	const { article } = await helpCenterGet(subdomain, token, locale ? `/${locale}/articles/${id}` : `/articles/${id}`);
+	return truncateIfNeeded([
+		formatArticleSummary(article),
+		"",
+		htmlToMarkdown(article.body)
+	].join("\n"));
+};
+/**
+* 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
+* `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.
+*/
+const createArticleResourcesProvider = (getToken, subdomain, onUnauthorized) => {
+	let cached;
+	const notifyIfUnauthorized = (err) => {
+		if (onUnauthorized && err instanceof ZendeskApiError && err.status === 401) onUnauthorized();
+	};
+	return {
+		listPromoted() {
+			const now = Date.now();
+			if (cached && now - cached.at < 3e5) return cached.promise;
+			const promise = (async () => {
+				const token = await getToken();
+				const { articles, truncated } = await fetchPromotedArticles(subdomain, token);
+				return {
+					refs: articles.map((a) => ({
+						id: a.id,
+						title: a.title
+					})),
+					truncated
+				};
+			})().catch((err) => {
+				cached = void 0;
+				notifyIfUnauthorized(err);
+				throw err;
+			});
+			cached = {
+				at: now,
+				promise
+			};
+			return promise;
+		},
+		async readArticle(id) {
+			try {
+				const token = await getToken();
+				return await fetchArticleMarkdown(subdomain, token, id);
+			} catch (err) {
+				notifyIfUnauthorized(err);
+				throw err;
+			}
+		}
+	};
+};
+//#endregion
+//#region src/guidance/instructions.ts
+/**
+* URI of the dynamic Help Center topology resource. Single source of truth for
+* every place that cites it (resource registration, `instructions` blob): the
+* scheme comes from the config (`--hc-resource-scheme`, default `zendesk-hc`),
+* the path is fixed. Any future Help Center resource should build its URI the
+* same way so the whole surface follows the configured scheme.
+*/
+const topologyResourceUri = (config) => `${config.hcResourceScheme}://topology`;
+/**
+* URI template of the pull-only Help Center article resources, built from the
+* configured scheme exactly like `topologyResourceUri` (`--hc-resource-scheme`,
+* default `zendesk-hc` → `zendesk-hc://article/{id}`). The template's `list`
+* callback enumerates the promoted ("featured") articles (so clients can surface
+* them for pinning), while any article id can be read on demand.
+*/
+const articleResourceUriTemplate = (config) => `${config.hcResourceScheme}://article/{id}`;
+/**
+* Build the concrete resource URI for a single article id, under the configured
+* scheme. Shares the scheme with the template above so the listed URIs always
+* match the template the read callback is registered under.
+*/
+const articleResourceUri = (config, id) => `${config.hcResourceScheme}://article/${id}`;
+/**
+* Whether the `help_center` namespace is active: no `--namespace` filter, or one
+* that includes it. The shared second half of the two Help Center feature gates
+* below, so the namespace semantics live in one place.
+*/
+const helpCenterNamespaceActive = (config) => !config.namespaces?.length || config.namespaces.includes("help_center");
+/**
+* Whether the Help Center structural context (init instructions + the
+* topology resource, default `zendesk-hc://topology`) should be exposed. True only when the
+* feature is enabled (`--no-topology` not set) AND the `help_center` namespace
+* is active. Shared by the instructions builder and the resource registration in
+* `server.ts` so both gates stay in sync.
+*/
+const helpCenterContextEnabled = (config) => config.topology && helpCenterNamespaceActive(config);
+/**
+* Whether the read-by-id article resource (`<scheme>://article/{id}`) should be
+* registered. Available whenever the `help_center` namespace is active — reading
+* one article is a cheap, on-demand single fetch with NO preloading, so it is
+* deliberately NOT gated by the promoted-listing flag: `--no-promoted-articles`
+* turns off the costly pre-listing (below), never the ability to address a known
+* article id. Not tied to `--no-topology` either (topology is a separate feature).
+*/
+const articleResourceEnabled = (config) => helpCenterNamespaceActive(config);
+/**
+* Whether the promoted-article PRE-LISTING is exposed: the resource `list`
+* callback's scan (which enumerates the promoted articles for `resources/list`)
+* AND the `list_promoted_articles` tool. This is the costly, fan-out part (a capped
+* scan of `/articles`, no server-side promoted filter), so it gets its own flag —
+* `--no-promoted-articles` turns it off so the server issues zero preloading
+* requests, while read-by-id (above) stays available. `!== false` (not truthiness)
+* so an omitted flag on a hand-built Config stays default-on, matching the tool
+* filter in `server.ts`.
+*/
+const promotedArticlesEnabled = (config) => config.promotedArticles !== false && helpCenterNamespaceActive(config);
+/**
+* The static `instructions` blob sent on `initialize`. Deliberately short and
+* I/O-free: it must not trigger the lazy OAuth/PKCE flow just to connect, and
+* it stays within a tight token budget. The rich, dynamic topology lives in the
+* pull-only topology resource (default `zendesk-hc://topology`) referenced here.
+*/
+const buildInstructions = (config) => {
+	if (!helpCenterContextEnabled(config)) return void 0;
+	return [
+		`This MCP server is connected to the Zendesk Help Center of "${config.subdomain}".`,
+		"",
+		`When creating or editing Help Center content, the resource ${topologyResourceUri(config)} is useful context:`,
+		"it lists the active locales (and the default one), the category → section tree with IDs,",
+		"the visibility user segments, the permission groups, and your current role.",
+		"Prefer its IDs (section_id, permission_group_id, user_segment_id, locale) over guessing from names.",
+		"",
+		"It degrades gracefully: without Guide-admin / Help Center manager rights the permission-groups and",
+		"user-segments sections are marked unavailable (not empty). In that case reuse a permission_group_id",
+		"or user_segment_id from an existing article (get_article) instead."
+	].join("\n");
+};
+//#endregion
 //#region src/guidance/topology.ts
 /**
 * Resolve an admin-gated fetch to a sentinel on HTTP 403 instead of rejecting.
@@ -1233,20 +1553,20 @@ const fetchTopology = async (subdomain, token) => {
 		currentUser: meRes.user
 	};
 };
-const renderTree = (data) => {
-	if (data.categoriesHasMore || data.sectionsHasMore) {
-		const reasons = [];
-		if (data.categoriesHasMore) reasons.push(`more than 100 categories`);
-		if (data.sectionsHasMore) reasons.push(`more than 100 sections`);
-		return [
-			`Large Help Center (${reasons.join(" and ")}) — the full tree is omitted to stay concise.`,
-			data.categoriesHasMore ? "Categories (partial list):" : "Categories:",
-			...data.categories.map(formatCategory),
-			"",
-			...data.categoriesHasMore ? ["Use the `list_categories` tool to enumerate all categories."] : [],
-			"Use the `list_sections` tool (filtered by `category_id`) to enumerate sections under a category."
-		];
-	}
+const renderOversizedTreeNotice = (data) => {
+	const reasons = [];
+	if (data.categoriesHasMore) reasons.push(`more than 100 categories`);
+	if (data.sectionsHasMore) reasons.push(`more than 100 sections`);
+	return [
+		`Large Help Center (${reasons.join(" and ")}) — the full tree is omitted to stay concise.`,
+		data.categoriesHasMore ? "Categories (partial list):" : "Categories:",
+		...data.categories.map(formatCategory),
+		"",
+		...data.categoriesHasMore ? ["Use the `list_categories` tool to enumerate all categories."] : [],
+		"Use the `list_sections` tool (filtered by `category_id`) to enumerate sections under a category."
+	];
+};
+const renderCategoryTree = (data) => {
 	const byCategory = /* @__PURE__ */ new Map();
 	for (const section of data.sections) {
 		const list = byCategory.get(section.category_id) ?? [];
@@ -1260,6 +1580,7 @@ const renderTree = (data) => {
 	}
 	return lines.length ? lines : ["_(no categories)_"];
 };
+const renderTree = (data) => data.categoriesHasMore || data.sectionsHasMore ? renderOversizedTreeNotice(data) : renderCategoryTree(data);
 /**
 * Render an admin-gated section as one of three states so the LLM never mistakes
 * "you can't see this" for "there are none": the formatted list, `_(none)_` when
@@ -1413,101 +1734,6 @@ const isPlacedAsRequested = (effectiveAfter, movedId, target, referenceId) => {
 	return target === "before" ? movedIndex < refIndex : movedIndex > refIndex;
 };
 //#endregion
-//#region src/utils/article-sections.ts
-const HEADING_LEVELS = /* @__PURE__ */ new Set([
-	"h1",
-	"h2",
-	"h3"
-]);
-const countWords = (text) => {
-	const trimmed = text.trim();
-	if (!trimmed) return 0;
-	return trimmed.split(/\s+/).length;
-};
-const textOf = (html) => {
-	if (!html) return "";
-	return cheerio.load(`<div>${html}</div>`, null, false)("div").first().text();
-};
-const parseSections = (html) => {
-	if (!html?.trim()) return [];
-	const $ = cheerio.load(html, null, false);
-	const children = $.root().contents().toArray();
-	const introParts = [];
-	const sections = [];
-	let current = null;
-	for (const node of children) {
-		const tagName = node.type === "tag" ? node.name.toLowerCase() : "";
-		if (HEADING_LEVELS.has(tagName)) {
-			const level = Number.parseInt(tagName.slice(1), 10);
-			current = {
-				heading: $(node).text().trim(),
-				headingTag: tagName,
-				level,
-				contentParts: []
-			};
-			sections.push(current);
-			continue;
-		}
-		const outer = $.html(node);
-		if (current) current.contentParts.push(outer);
-		else introParts.push(outer);
-	}
-	const result = [];
-	if (introParts.length > 0) {
-		const introHtml = introParts.join("");
-		result.push({
-			index: 0,
-			heading: "intro",
-			headingTag: "",
-			level: 0,
-			html: introHtml,
-			wordCount: countWords(textOf(introHtml))
-		});
-	}
-	for (const s of sections) {
-		const sectionHtml = s.contentParts.join("");
-		result.push({
-			index: result.length,
-			heading: s.heading,
-			headingTag: s.headingTag,
-			level: s.level,
-			html: sectionHtml,
-			wordCount: countWords(textOf(sectionHtml))
-		});
-	}
-	return result;
-};
-const replaceSectionContent = (html, sectionIndex, newHtml) => {
-	const sections = parseSections(html);
-	if (sectionIndex < 0 || sectionIndex >= sections.length) throw new Error(`Section index ${sectionIndex} out of range (valid: 0-${Math.max(0, sections.length - 1)})`);
-	return sections.map((section, idx) => {
-		const content = idx === sectionIndex ? newHtml : section.html;
-		if (section.level === 0) return content;
-		return `<${section.headingTag}>${section.heading}</${section.headingTag}>${content}`;
-	}).join("");
-};
-const keepAsHtml = (_state, node) => ({
-	type: "html",
-	value: toHtml(node)
-});
-const htmlToMdProcessor = unified().use(rehypeParse, { fragment: true }).use(rehypeRemark, { handlers: {
-	table: keepAsHtml,
-	pre: keepAsHtml
-} }).use(remarkGfm).use(remarkStringify, {
-	bullet: "-",
-	emphasis: "_",
-	fences: true
-});
-const mdToHtmlProcessor = unified().use(remarkParse).use(remarkGfm).use(remarkRehype, { allowDangerousHtml: true }).use(rehypeRaw).use(rehypeStringify);
-const htmlToMarkdown = (html) => {
-	if (!html) return "";
-	return String(htmlToMdProcessor.processSync(html));
-};
-const markdownToHtml = (markdown) => {
-	if (!markdown) return "";
-	return String(mdToHtmlProcessor.processSync(markdown));
-};
-//#endregion
 //#region src/tools/help-center.ts
 const ARTICLE_ID_DESC = "Article ID — the numeric id of the Help Center article. Obtain it from list_articles or search_articles.";
 const listTranslations = (subdomain, token, articleId) => helpCenterGet(subdomain, token, `/articles/${articleId}/translations`).then((res) => res.translations);
@@ -1521,6 +1747,60 @@ const largeArticleHint = (body, sectionCount) => {
 	].join("\n");
 };
 const autoSortNotice = (sectionId, applied) => [applied === void 0 ? `Section #${sectionId} looks like it is sorted automatically, so a manual reorder would have no visible effect.` : `Wrote ${applied} article position(s), but the display order of section #${sectionId} did not change — the section is sorted automatically, so positions are ignored.`, "To order its articles manually: in Guide, open the section, choose \"Edit section\", set \"Order articles by\" to Manual, then re-run this tool."].join(" ");
+const renderFreshnessLine = (sourceUpdatedAt, targetUpdatedAt, targetLocale) => {
+	const srcMs = Date.parse(sourceUpdatedAt);
+	const tgtMs = Date.parse(targetUpdatedAt);
+	const label = `- **Freshness (target ${targetLocale})**`;
+	if (!Number.isFinite(srcMs) || !Number.isFinite(tgtMs)) return `${label}: unknown (could not compare edit timestamps).`;
+	if (srcMs <= tgtMs) return `${label}: up to date (source has not been edited since this translation).`;
+	const days = Math.floor((srcMs - tgtMs) / 864e5);
+	return `${label}: source was edited ${days >= 1 ? `${days} day(s)` : "less than a day"} after this translation → likely behind, review recommended.`;
+};
+const renderOutdatedLine = (translations, targetLocale) => {
+	const targetLocaleKey = targetLocale.toLowerCase();
+	const entry = translations.find((t) => t.locale.toLowerCase() === targetLocaleKey);
+	const label = `- **Zendesk outdated flag (target ${targetLocale})**`;
+	if (entry?.outdated === void 0) return `${label}: unknown.`;
+	if (entry.outdated) return `${label}: yes — explicitly marked out of date in Guide.`;
+	return `${label}: no (only set via Guide's own edit workflow; "no" does not by itself mean current — rely on Freshness above).`;
+};
+const renderStructureLine = (sourceSections, targetSections) => {
+	const sourceTags = sourceSections.map((s) => s.headingTag).join(",");
+	const targetTags = targetSections.map((s) => s.headingTag).join(",");
+	return sourceSections.length === targetSections.length && sourceTags === targetTags ? `- **Structure**: ${sourceSections.length} sections in both locales — aligned.` : `- **Structure**: ${sourceSections.length} source vs ${targetSections.length} target sections — MISMATCH; the per-index rows below may be misaligned.`;
+};
+const sectionRowStatus = (source, target) => {
+	if (!target) return "missing";
+	if (!source) return "extra";
+	return "ok";
+};
+const renderSectionRows = (sourceSections, targetSections) => {
+	const rows = ["| Idx | Heading | Status | Source words | Target words |", "| --- | --- | --- | --- | --- |"];
+	const maxLen = Math.max(sourceSections.length, targetSections.length);
+	for (let i = 0; i < maxLen; i += 1) {
+		const src = sourceSections[i];
+		const tgt = targetSections[i];
+		const heading = src?.heading ?? tgt?.heading ?? "";
+		const status = sectionRowStatus(src, tgt);
+		rows.push(`| ${i} | ${heading} | ${status} | ${src?.wordCount ?? 0} | ${tgt?.wordCount ?? 0} |`);
+	}
+	return rows;
+};
+const localePrefix = (locale) => locale ? `/${locale}` : "";
+const articleListPath = (sectionId, locale) => `${localePrefix(locale)}${sectionId ? `/sections/${sectionId}` : ""}/articles`;
+const sectionListPath = (categoryId, locale) => `${localePrefix(locale)}${categoryId ? `/categories/${categoryId}` : ""}/sections`;
+const scanCostNote = (truncated, pagesScanned, cost) => {
+	if (truncated) return `\n\n_Note: the scan hit its ${ARTICLE_RESOURCES_SCAN_MAX_PAGES}-page cap (${cost}), so promoted articles deeper in the catalog may be missing. This call is costly on this Help Center — avoid repeating it; raise ZENDESK_ARTICLE_RESOURCES_SCAN_MAX_PAGES to widen coverage._`;
+	if (pagesScanned > 1) return `\n\n_Note: this scan cost ${cost}; this tool performs a fresh scan every call (no caching), so avoid calling it again right away._`;
+	return "";
+};
+const needsReferenceArticle = (target) => target === "before" || target === "after";
+const assertReorderParamsCoherent = (articleId, target, referenceArticleId) => {
+	const needsReference = needsReferenceArticle(target);
+	if (needsReference && referenceArticleId === void 0) throw new Error(`target "${target}" requires reference_article_id (the article to move ${target}).`);
+	if (!needsReference && referenceArticleId !== void 0) throw new Error(`reference_article_id must be omitted when target is "${target}" (it only applies to "before"/"after").`);
+	if (referenceArticleId !== void 0 && referenceArticleId === articleId) throw new Error("reference_article_id must differ from article_id.");
+};
 const createHelpCenterTools = (ctx) => {
 	const { subdomain, getToken } = ctx;
 	const fetchSectionOrder = async (sectionId, locale, token) => {
@@ -1538,6 +1818,26 @@ const createHelpCenterTools = (ctx) => {
 		} while (cursor);
 		return order;
 	};
+	const assertReferenceInSection = async (effective, referenceArticleId, articleId, sectionId, token) => {
+		if (effective.some((a) => a.id === referenceArticleId)) return;
+		let detail = "was not found";
+		try {
+			const { article: ref } = await helpCenterGet(subdomain, token, `/articles/${referenceArticleId}`);
+			detail = `is in section #${ref.section_id}, not section #${sectionId}`;
+		} catch {}
+		throw new Error(`Reference article #${referenceArticleId} ${detail}. It must be in the same section (#${sectionId}) as article #${articleId}.`);
+	};
+	const applyPositionWrites = async (writes, articleId, token) => {
+		let applied = 0;
+		for (const write of writes) try {
+			await helpCenterPut(subdomain, token, `/articles/${write.id}`, { article: { position: write.position } });
+			applied += 1;
+		} catch (error) {
+			const reason = error instanceof Error ? error.message : String(error);
+			throw new Error(`Reorder of article #${articleId} failed after ${applied}/${writes.length} position write(s) (on article #${write.id}): ${reason} Positions are written absolutely, so re-running the identical call is safe and resumes where it stopped.`, { cause: error });
+		}
+		return applied;
+	};
 	return [
 		{
 			name: "search_articles",
@@ -1620,7 +1920,7 @@ const createHelpCenterTools = (ctx) => {
 			handler: async (params) => {
 				const { locale, page_size, cursor } = params;
 				const token = await getToken();
-				const path = locale ? `/${locale}/categories` : "/categories";
+				const path = `${localePrefix(locale)}/categories`;
 				const response = await helpCenterGet(subdomain, token, path, buildCursorParams(page_size, cursor));
 				const categories = response.categories ?? [];
 				return { content: [{
@@ -1650,8 +1950,7 @@ const createHelpCenterTools = (ctx) => {
 			handler: async (params) => {
 				const { category_id, locale, page_size, cursor } = params;
 				const token = await getToken();
-				const path = category_id && locale ? `/${locale}/categories/${category_id}/sections` : category_id ? `/categories/${category_id}/sections` : locale ? `/${locale}/sections` : "/sections";
-				const response = await helpCenterGet(subdomain, token, path, buildCursorParams(page_size, cursor));
+				const response = await helpCenterGet(subdomain, token, sectionListPath(category_id, locale), buildCursorParams(page_size, cursor));
 				const sections = response.sections ?? [];
 				return { content: [{
 					type: "text",
@@ -1688,8 +1987,7 @@ const createHelpCenterTools = (ctx) => {
 			handler: async (params) => {
 				const { section_id, locale, page_size, cursor, sort_by, sort_order, include_translations } = params;
 				const token = await getToken();
-				const path = section_id && locale ? `/${locale}/sections/${section_id}/articles` : section_id ? `/sections/${section_id}/articles` : locale ? `/${locale}/articles` : "/articles";
-				const response = await helpCenterGet(subdomain, token, path, {
+				const response = await helpCenterGet(subdomain, token, articleListPath(section_id, locale), {
 					...buildCursorParams(page_size, cursor),
 					sort_by,
 					sort_order
@@ -1710,6 +2008,31 @@ const createHelpCenterTools = (ctx) => {
 				}] };
 			}
 		},
+		{
+			name: LIST_PROMOTED_ARTICLES_TOOL,
+			namespace: "help_center",
+			readOnly: true,
+			title: "List Promoted Help Center Articles",
+			description: "List the promoted (\"featured\") Help Center articles — the small, editorially-curated set surfaced at the top of their sections. Returns metadata only (no body); use get_article for full content. COST: the Help Center API has no server-side promoted filter, so this scans article pages (one Zendesk API request per page, up to ZENDESK_ARTICLE_RESOURCES_SCAN_MAX_PAGES, default 20) and filters client-side — potentially costly on a large Help Center. Each call performs a fresh, uncached scan, so avoid calling it repeatedly. On a very large Help Center some promoted articles may be omitted, and both the omission and the number of pages scanned are flagged in the output. Lists the default locale. To promote or unpromote an article, use update_article with `promoted` (requires Help Center admin / Guide admin rights).",
+			inputSchema: z.object({}),
+			annotations: {
+				readOnlyHint: true,
+				destructiveHint: false,
+				idempotentHint: true,
+				openWorldHint: true
+			},
+			handler: async () => {
+				const token = await getToken();
+				const { articles, truncated, pagesScanned } = await fetchPromotedArticles(subdomain, token);
+				const header = `Promoted (featured) articles: ${articles.length}`;
+				const body = articles.length ? articles.map(formatArticleSummary).join("\n\n") : "_No promoted articles found._";
+				const cost = `${pagesScanned} Zendesk API request${pagesScanned === 1 ? "" : "s"}`;
+				return { content: [{
+					type: "text",
+					text: truncateIfNeeded(`${header}\n\n${body}${scanCostNote(truncated, pagesScanned, cost)}`)
+				}] };
+			}
+		},
 		{
 			name: "list_article_translations",
 			namespace: "help_center",
@@ -1918,23 +2241,14 @@ const createHelpCenterTools = (ctx) => {
 			},
 			handler: async (params) => {
 				const { article_id, target, reference_article_id, normalize = false, confirm = false } = params;
-				const needsReference = target === "before" || target === "after";
-				if (needsReference && reference_article_id === void 0) throw new Error(`target "${target}" requires reference_article_id (the article to move ${target}).`);
-				if (!needsReference && reference_article_id !== void 0) throw new Error(`reference_article_id must be omitted when target is "${target}" (it only applies to "before"/"after").`);
-				if (reference_article_id !== void 0 && reference_article_id === article_id) throw new Error("reference_article_id must differ from article_id.");
+				assertReorderParamsCoherent(article_id, target, reference_article_id);
+				const needsReference = needsReferenceArticle(target);
 				const token = await getToken();
 				const { article } = await helpCenterGet(subdomain, token, `/articles/${article_id}`);
 				const sectionId = article.section_id;
 				const locale = article.source_locale;
 				const effective = await fetchSectionOrder(sectionId, locale, token);
-				if (needsReference && !effective.some((a) => a.id === reference_article_id)) {
-					let detail = "was not found";
-					try {
-						const { article: ref } = await helpCenterGet(subdomain, token, `/articles/${reference_article_id}`);
-						detail = `is in section #${ref.section_id}, not section #${sectionId}`;
-					} catch {}
-					throw new Error(`Reference article #${reference_article_id} ${detail}. It must be in the same section (#${sectionId}) as article #${article_id}.`);
-				}
+				if (reference_article_id !== void 0) await assertReferenceInSection(effective, reference_article_id, article_id, sectionId, token);
 				const targetLabel = needsReference ? `${target} article #${reference_article_id}` : target;
 				const writes = computePositionWrites(arrangeDesiredOrder(effective, article_id, target, reference_article_id), article_id, normalize);
 				if (writes.length === 0) return { content: [{
@@ -1949,14 +2263,7 @@ const createHelpCenterTools = (ctx) => {
 					type: "text",
 					text: `Reordering article #${article_id} to ${targetLabel} would reposition ${writes.length} articles in section #${sectionId}, above the safety threshold of ${REORDER_CONFIRM_THRESHOLD}. Re-run with confirm: true to proceed.`
 				}] };
-				let applied = 0;
-				for (const write of writes) try {
-					await helpCenterPut(subdomain, token, `/articles/${write.id}`, { article: { position: write.position } });
-					applied += 1;
-				} catch (error) {
-					const reason = error instanceof Error ? error.message : String(error);
-					throw new Error(`Reorder of article #${article_id} failed after ${applied}/${writes.length} position write(s) (on article #${write.id}): ${reason} Positions are written absolutely, so re-running the identical call is safe and resumes where it stopped.`, { cause: error });
-				}
+				const applied = await applyPositionWrites(writes, article_id, token);
 				if (!isPlacedAsRequested(await fetchSectionOrder(sectionId, locale, token), article_id, target, reference_article_id)) return { content: [{
 					type: "text",
 					text: autoSortNotice(sectionId, applied)
@@ -2268,40 +2575,10 @@ const createHelpCenterTools = (ctx) => {
 				]);
 				const sourceSections = parseSections(sourceRes.translation.body);
 				const targetSections = parseSections(targetRes.translation.body);
-				const maxLen = Math.max(sourceSections.length, targetSections.length);
-				const sourceUpdated = sourceRes.translation.updated_at;
-				const targetUpdated = targetRes.translation.updated_at;
-				const srcMs = Date.parse(sourceUpdated);
-				const tgtMs = Date.parse(targetUpdated);
-				const comparable = Number.isFinite(srcMs) && Number.isFinite(tgtMs);
-				let freshnessLine;
-				if (comparable && srcMs > tgtMs) {
-					const days = Math.floor((srcMs - tgtMs) / 864e5);
-					freshnessLine = `- **Freshness (target ${target_locale})**: source was edited ${days >= 1 ? `${days} day(s)` : "less than a day"} after this translation → likely behind, review recommended.`;
-				} else if (comparable) freshnessLine = `- **Freshness (target ${target_locale})**: up to date (source has not been edited since this translation).`;
-				else freshnessLine = `- **Freshness (target ${target_locale})**: unknown (could not compare edit timestamps).`;
-				const targetLocaleKey = target_locale.toLowerCase();
-				const targetListEntry = translations.find((t) => t.locale.toLowerCase() === targetLocaleKey);
-				const outdated = targetListEntry?.outdated === void 0 ? "unknown" : targetListEntry.outdated ? "yes" : "no";
-				const outdatedLine = outdated === "yes" ? `- **Zendesk outdated flag (target ${target_locale})**: yes — explicitly marked out of date in Guide.` : outdated === "no" ? `- **Zendesk outdated flag (target ${target_locale})**: no (only set via Guide's own edit workflow; "no" does not by itself mean current — rely on Freshness above).` : `- **Zendesk outdated flag (target ${target_locale})**: unknown.`;
-				const sourceTags = sourceSections.map((s) => s.headingTag).join(",");
-				const targetTags = targetSections.map((s) => s.headingTag).join(",");
-				const structureLine = sourceSections.length === targetSections.length && sourceTags === targetTags ? `- **Structure**: ${sourceSections.length} sections in both locales — aligned.` : `- **Structure**: ${sourceSections.length} source vs ${targetSections.length} target sections — MISMATCH; the per-index rows below may be misaligned.`;
-				const rows = [];
-				rows.push(`| Idx | Heading | Status | Source words | Target words |`);
-				rows.push(`| --- | --- | --- | --- | --- |`);
-				for (let i = 0; i < maxLen; i += 1) {
-					const src = sourceSections[i];
-					const tgt = targetSections[i];
-					const heading = src?.heading ?? tgt?.heading ?? "";
-					const sourceWords = src?.wordCount ?? 0;
-					const targetWords = tgt?.wordCount ?? 0;
-					let status;
-					if (!tgt) status = "missing";
-					else if (!src) status = "extra";
-					else status = "ok";
-					rows.push(`| ${i} | ${heading} | ${status} | ${sourceWords} | ${targetWords} |`);
-				}
+				const freshnessLine = renderFreshnessLine(sourceRes.translation.updated_at, targetRes.translation.updated_at, target_locale);
+				const outdatedLine = renderOutdatedLine(translations, target_locale);
+				const structureLine = renderStructureLine(sourceSections, targetSections);
+				const rows = renderSectionRows(sourceSections, targetSections);
 				return { content: [{
 					type: "text",
 					text: [
@@ -2310,7 +2587,7 @@ const createHelpCenterTools = (ctx) => {
 						freshnessLine,
 						outdatedLine,
 						structureLine,
-						`- **Updated**: source ${sourceUpdated} | target ${targetUpdated}`,
+						`- **Updated**: source ${sourceRes.translation.updated_at} | target ${targetRes.translation.updated_at}`,
 						`- **Target draft**: ${targetRes.translation.draft ? "yes" : "no"}`,
 						"",
 						"_Word counts are informational: a length difference between languages is normal, not a divergence._",
@@ -2406,6 +2683,7 @@ const createSearchTools = (ctx) => {
 };
 //#endregion
 //#region src/tools/tickets.ts
+const MAX_ATTACHMENT_MB = Number.parseFloat((MAX_ATTACHMENT_BYTES / (1024 * 1024)).toFixed(2));
 const formatReference = (attachment) => `**${attachment.file_name}** (id ${attachment.id}, ${attachment.content_type}, ${attachment.size} bytes) — ${attachment.content_url}`;
 const buildEmbeddedImageBlocks = async (subdomain, token, attachment, reference) => {
 	const { data, contentType } = await fetchZendeskBinary(subdomain, token, attachment.content_url);
@@ -2434,6 +2712,16 @@ const fetchAllTicketComments = async (subdomain, token, ticketId) => {
 	}
 	return all;
 };
+const fetchAttachmentsByIds = async (subdomain, token, ids) => {
+	const attachments = [];
+	for (const id of ids) try {
+		const { attachment } = await zendeskGet(subdomain, token, `/attachments/${id}`);
+		attachments.push(attachment);
+	} catch (error) {
+		if (!(error instanceof ZendeskApiError) || error.status !== 404) throw error;
+	}
+	return attachments;
+};
 const collectAttachmentBlocks = async (subdomain, token, attachments) => {
 	const blocks = [];
 	let embeddedCount = 0;
@@ -2447,7 +2735,7 @@ const collectAttachmentBlocks = async (subdomain, token, attachments) => {
 			continue;
 		}
 		let skipReason = null;
-		if (attachment.size > MAX_ATTACHMENT_BYTES) skipReason = `skipped: exceeds ${+(MAX_ATTACHMENT_BYTES / (1024 * 1024)).toFixed(2)} MB per-image limit`;
+		if (attachment.size > MAX_ATTACHMENT_BYTES) skipReason = `skipped: exceeds ${MAX_ATTACHMENT_MB} MB per-image limit`;
 		else if (embeddedCount >= MAX_EMBEDDED_IMAGE_COUNT) skipReason = `skipped: max ${MAX_EMBEDDED_IMAGE_COUNT} embedded images reached`;
 		if (skipReason) {
 			blocks.push({
@@ -2469,9 +2757,10 @@ const collectAttachmentBlocks = async (subdomain, token, attachments) => {
 	}
 	return blocks;
 };
+const ISO_DAY = /^\d{4}-\d{2}-\d{2}$/;
 const fetchTicketSla = async (subdomain, token, ticket) => {
 	const day = ticket.created_at.slice(0, 10);
-	if (!/^\d{4}-\d{2}-\d{2}$/.test(day)) return void 0;
+	if (!ISO_DAY.test(day)) return void 0;
 	const shiftDay = (offset) => {
 		const d = /* @__PURE__ */ new Date(`${day}T00:00:00Z`);
 		d.setUTCDate(d.getUTCDate() + offset);
@@ -2541,23 +2830,24 @@ const hydrateViewTickets = async (subdomain, token, ids) => {
 	const byId = new Map((tickets ?? []).map((t) => [t.id, t]));
 	return ids.map((id) => byId.get(id)).filter((t) => t !== void 0);
 };
+const addPositiveId = (set, raw) => {
+	const n = Number(raw);
+	if (Number.isInteger(n) && n > 0) set.add(n);
+};
+const collectEventIds = (event, userIds, groupIds) => {
+	if (event.type !== "Change" && event.type !== "Create") return;
+	const entity = event.field_name ? AUDIT_ENTITY_FIELDS[event.field_name] : void 0;
+	if (!entity) return;
+	const set = entity === "user" ? userIds : groupIds;
+	addPositiveId(set, event.value);
+	addPositiveId(set, event.previous_value);
+};
 const collectAuditIds = (audits) => {
 	const userIds = /* @__PURE__ */ new Set();
 	const groupIds = /* @__PURE__ */ new Set();
-	const addId = (set, raw) => {
-		const n = Number(raw);
-		if (Number.isInteger(n) && n > 0) set.add(n);
-	};
 	for (const audit of audits) {
-		addId(userIds, audit.author_id);
-		for (const event of audit.events) {
-			if (event.type !== "Change" && event.type !== "Create") continue;
-			const entity = event.field_name ? AUDIT_ENTITY_FIELDS[event.field_name] : void 0;
-			if (!entity) continue;
-			const set = entity === "user" ? userIds : groupIds;
-			addId(set, event.value);
-			addId(set, event.previous_value);
-		}
+		addPositiveId(userIds, audit.author_id);
+		for (const event of audit.events) collectEventIds(event, userIds, groupIds);
 	}
 	return {
 		userIds: [...userIds],
@@ -2600,12 +2890,11 @@ const diffLine = (label, before, after) => {
 	const a = shownValue(after);
 	return b === a ? null : `- **${label}**: ${b} → ${a}`;
 };
-const formatMacroPreviewDiff = (ticketId, macroId, before, result) => {
-	const after = result?.ticket ?? {};
-	const beforeObj = before ?? {};
-	const comment = after.comment ?? result?.comment;
+const asRecord = (value) => value ?? {};
+const diffStandardFields = (before, after) => {
+	const beforeObj = asRecord(before);
 	const changes = [];
-	for (const [key, afterVal] of Object.entries(after)) {
+	for (const [key, afterVal] of Object.entries(asRecord(after))) {
 		if (DIFF_SKIP_KEYS.has(key)) continue;
 		const beforeVal = beforeObj[key];
 		if (valuesEqual(beforeVal, afterVal)) continue;
@@ -2618,12 +2907,22 @@ const formatMacroPreviewDiff = (ticketId, macroId, before, result) => {
 		const line = diffLine(key, beforeVal, afterVal);
 		if (line) changes.push(line);
 	}
-	const afterFields = [after.fields ?? after.custom_fields ?? []].flat();
+	return changes;
+};
+const diffCustomFields = (before, after) => {
+	const afterFields = [after?.fields ?? after?.custom_fields ?? []].flat();
 	const beforeById = new Map((before?.custom_fields ?? []).map((f) => [f.id, f.value]));
+	const changes = [];
 	for (const f of afterFields) {
 		const line = diffLine(`custom field ${f.id}`, beforeById.get(f.id), f.value);
 		if (line) changes.push(line);
 	}
+	return changes;
+};
+const formatMacroPreviewDiff = (ticketId, macroId, before, result) => {
+	const after = result?.ticket ?? {};
+	const comment = after.comment ?? result?.comment;
+	const changes = [...diffStandardFields(before, after), ...diffCustomFields(before, after)];
 	const lines = [
 		`# Macro #${macroId} preview on ticket #${ticketId} (diff — nothing saved yet)`,
 		"",
@@ -2749,16 +3048,7 @@ const createTicketTools = (ctx) => {
 			handler: async (params) => {
 				const { ticket_id, attachment_ids } = params;
 				const token = await getToken();
-				let attachments;
-				if (attachment_ids && attachment_ids.length > 0) {
-					attachments = [];
-					for (const id of attachment_ids) try {
-						const { attachment } = await zendeskGet(subdomain, token, `/attachments/${id}`);
-						attachments.push(attachment);
-					} catch (error) {
-						if (!(error instanceof ZendeskApiError) || error.status !== 404) throw error;
-					}
-				} else attachments = (await fetchAllTicketComments(subdomain, token, ticket_id)).flatMap((c) => c.attachments ?? []);
+				const attachments = attachment_ids && attachment_ids.length > 0 ? await fetchAttachmentsByIds(subdomain, token, attachment_ids) : (await fetchAllTicketComments(subdomain, token, ticket_id)).flatMap((c) => c.attachments ?? []);
 				if (attachments.length === 0) return { content: [{
 					type: "text",
 					text: `No attachments found on ticket #${ticket_id}.`
@@ -3541,7 +3831,7 @@ const registerToolset = (server, { config, getToken, onUnauthorized, logger = si
 		readOnly: config.readOnly,
 		namespaces: config.namespaces,
 		tools: config.tools
-	});
+	}).filter((t) => config.promotedArticles !== false || t.name !== "list_promoted_articles");
 	try {
 		switch (config.mode) {
 			case "all":
@@ -3563,6 +3853,10 @@ const registerToolset = (server, { config, getToken, onUnauthorized, logger = si
 			case "single":
 				registered.push(registerProxyTool(server, "zendesk", "Zendesk", filteredTools, config.readOnly, onUnauthorized));
 				break;
+			default: {
+				const unhandled = config.mode;
+				throw new Error(`Unsupported tool mode: ${String(unhandled)}`);
+			}
 		}
 		if (helpCenterContextEnabled(config)) {
 			const topology = createTopologyProvider(getToken, config.subdomain, onUnauthorized);
@@ -3576,6 +3870,44 @@ const registerToolset = (server, { config, getToken, onUnauthorized, logger = si
 				text: await topology.read()
 			}] })));
 		}
+		if (articleResourceEnabled(config)) {
+			const articles = createArticleResourcesProvider(getToken, config.subdomain, onUnauthorized);
+			const listPromotedEnabled = promotedArticlesEnabled(config);
+			const template = new ResourceTemplate(articleResourceUriTemplate(config), { list: async () => {
+				if (!listPromotedEnabled) return { resources: [] };
+				try {
+					const { refs, truncated } = await articles.listPromoted();
+					if (truncated) logger.warn("article_resources_list_truncated", {
+						max_pages: ARTICLE_RESOURCES_SCAN_MAX_PAGES,
+						listed: refs.length
+					});
+					return { resources: refs.map((ref) => ({
+						uri: articleResourceUri(config, ref.id),
+						name: ref.title,
+						title: ref.title,
+						description: `"${ref.title}" (article ${ref.id}) — promoted Help Center article, as Markdown.`,
+						mimeType: "text/markdown"
+					})) };
+				} catch (err) {
+					logger.warn("article_resources_list_failed", { error: err instanceof Error ? err.message : String(err) });
+					return { resources: [] };
+				}
+			} });
+			registered.push(server.registerResource("help-center-article", template, {
+				title: "Zendesk Help Center article",
+				description: "A Help Center article rendered as Markdown, addressed by id. The list surfaces the promoted (featured) articles so one can be pinned as context; any article id can be read, subject to your Zendesk read permissions.",
+				mimeType: "text/markdown"
+			}, async (uri, variables) => {
+				const raw = Array.isArray(variables["id"]) ? variables["id"][0] : variables["id"];
+				const id = Number(raw);
+				if (!Number.isSafeInteger(id) || id <= 0) throw new Error(`Invalid article id in resource URI: ${uri.toString()}`);
+				return { contents: [{
+					uri: uri.toString(),
+					mimeType: "text/markdown",
+					text: await articles.readArticle(id)
+				}] };
+			}));
+		}
 	} catch (err) {
 		dispose();
 		throw err;
@@ -3751,6 +4083,7 @@ const WILDCARD_HOSTS = /* @__PURE__ */ new Set([
 	"::",
 	"*"
 ]);
+const TRAILING_SLASHES = /\/+$/;
 const DEFAULT_BROWSER_MCP_CLIENT_ORIGINS = [
 	"https://chatgpt.com",
 	"https://chat.openai.com",
@@ -3826,7 +4159,7 @@ const handleCorsPreflight = (req, res, extraOrigins) => {
 	return true;
 };
 const resolveResourceUrl = (config, logger = silentLogger) => {
-	if (config.publicUrl) return config.publicUrl.replace(/\/+$/, "");
+	if (config.publicUrl) return config.publicUrl.replace(TRAILING_SLASHES, "");
 	if (!WILDCARD_HOSTS.has(config.host)) return `http://${config.host}:${config.port}`;
 	logger.warn("public_url_unset", {
 		host: config.host,
@@ -3883,6 +4216,14 @@ const sendJsonRpcError = (res, status, code, message, headers = {}) => {
 		jsonrpc: "2.0"
 	}));
 };
+const failRequest = (res, err) => {
+	const message = err instanceof Error ? err.message : "Internal Server Error";
+	if (!res.headersSent) {
+		sendJsonRpcError(res, 500, -32603, message);
+		return;
+	}
+	if (!res.writableEnded) res.end();
+};
 const sendUnauthorized = (res, resource) => {
 	const wwwAuthenticate = `Bearer resource_metadata="${resource}/.well-known/oauth-protected-resource", error="invalid_token", error_description="${MISSING_BEARER_MESSAGE}"`;
 	sendJsonRpcError(res, 401, -32e3, MISSING_BEARER_MESSAGE, { "WWW-Authenticate": wwwAuthenticate });
@@ -3953,6 +4294,22 @@ const startHttpTransport = async (config, logger = silentLogger, options = {}) =
 	const sessions = /* @__PURE__ */ new Map();
 	const idleTimeoutMs = options.sessionIdleTimeoutMs ?? SESSION_IDLE_TIMEOUT_MS;
 	const maxBodyBytes = options.maxBodyBytes ?? 4194304;
+	const dispatchToSession = async (req, res, sessionId, bearer) => {
+		const session = sessions.get(sessionId);
+		if (!session) return false;
+		session.auth.bearer = bearer;
+		session.lastActivityAt = Date.now();
+		const body = req.method === "POST" ? await readJsonBody(req, maxBodyBytes) : {
+			ok: true,
+			value: void 0
+		};
+		if (!body.ok) {
+			respondBodyError(req, res, body);
+			return true;
+		}
+		await session.transport.handleRequest(req, res, body.value);
+		return true;
+	};
 	const handleMcpRequest = async (req, res) => {
 		const bearer = extractBearer(req);
 		if (!bearer) {
@@ -3960,23 +4317,7 @@ const startHttpTransport = async (config, logger = silentLogger, options = {}) =
 			return;
 		}
 		const sessionId = typeof req.headers["mcp-session-id"] === "string" ? req.headers["mcp-session-id"] : void 0;
-		if (sessionId) {
-			const session = sessions.get(sessionId);
-			if (session) {
-				session.auth.bearer = bearer;
-				session.lastActivityAt = Date.now();
-				const body = req.method === "POST" ? await readJsonBody(req, maxBodyBytes) : {
-					ok: true,
-					value: void 0
-				};
-				if (!body.ok) {
-					respondBodyError(req, res, body);
-					return;
-				}
-				await session.transport.handleRequest(req, res, body.value);
-				return;
-			}
-		}
+		if (sessionId && await dispatchToSession(req, res, sessionId, bearer)) return;
 		if (req.method !== "POST") {
 			sendJsonRpcError(res, 400, -32e3, "No active session; initialize via POST first.");
 			return;
@@ -4008,24 +4349,22 @@ const startHttpTransport = async (config, logger = silentLogger, options = {}) =
 		await server.connect(transport);
 		await transport.handleRequest(req, res, body.value);
 	};
+	const staticGetRoutes = {
+		"/.well-known/oauth-protected-resource": metadata.protectedResource,
+		"/.well-known/oauth-authorization-server": metadata.authorizationServer,
+		"/healthz": {
+			status: "ok",
+			subdomain: config.subdomain
+		}
+	};
 	const requestListener = async (req, res) => {
 		try {
 			if (handleCorsPreflight(req, res, config.corsOrigins)) return;
 			applyCorsHeaders(req, res, config.corsOrigins);
 			const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
-			if (url.pathname === "/.well-known/oauth-protected-resource" && req.method === "GET") {
-				sendJson(res, 200, metadata.protectedResource);
-				return;
-			}
-			if (url.pathname === "/.well-known/oauth-authorization-server" && req.method === "GET") {
-				sendJson(res, 200, metadata.authorizationServer);
-				return;
-			}
-			if (url.pathname === "/healthz" && req.method === "GET") {
-				sendJson(res, 200, {
-					status: "ok",
-					subdomain: config.subdomain
-				});
+			const staticRoute = req.method === "GET" ? staticGetRoutes[url.pathname] : void 0;
+			if (staticRoute) {
+				sendJson(res, 200, staticRoute);
 				return;
 			}
 			if (url.pathname === "/mcp") {
@@ -4038,9 +4377,7 @@ const startHttpTransport = async (config, logger = silentLogger, options = {}) =
 				path: url.pathname
 			}));
 		} catch (err) {
-			const message = err instanceof Error ? err.message : "Internal Server Error";
-			if (!res.headersSent) sendJsonRpcError(res, 500, -32603, message);
-			else if (!res.writableEnded) res.end();
+			failRequest(res, err);
 		}
 	};
 	const httpServer = createServer((req, res) => {
@@ -4117,5 +4454,3 @@ main().catch((error) => {
 });
 //#endregion
 export {};
-//# sourceMappingURL=index.js.map