@fruggr/zendesk-mcp-server 2.14.2 → 2.16.0

package/dist/index.js

@@ -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";
@@ -114,6 +114,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);
@@ -595,13 +596,46 @@ const ConfigSchema = z.object({
 	tools: z.array(z.string()).optional(),
 	/**
 	* Whether to expose the Help Center structural context (the `instructions`
-	* blob + the `zendesk-hc://topology` resource). On by default; an operator
+	* blob + the topology resource, default `zendesk-hc://topology`). On by
+	* default; an operator
 	* disables it server-wide with `--no-topology` (e.g. on a very large Help
 	* Center, or when the context is unwanted). Only ever active when the
 	* `help_center` namespace itself is active.
 	*/
 	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
+	* RFC 3986 scheme — clients parse resource URIs with WHATWG `URL`, so a
+	* non-conformant scheme would surface as a broken resource at runtime;
+	* reject it at config parse time instead. ASCII-only message, value not
+	* echoed (same policy as parsePort below).
+	*/
+	hcResourceScheme: z.string().regex(/^[a-z][a-z0-9+.-]*$/, {
+		message: "Invalid HC_RESOURCE_SCHEME / --hc-resource-scheme value. Expected a bare RFC 3986 scheme: a lowercase letter followed by lowercase letters, digits, \"+\", \"-\" or \".\" (no \"://\").",
+		abort: true
+	}).refine((scheme) => {
+		const uri = `${scheme}://topology`;
+		try {
+			return new URL(uri).toString() === uri;
+		} catch {
+			return false;
+		}
+	}, { message: "Invalid HC_RESOURCE_SCHEME / --hc-resource-scheme value. WHATWG-special schemes (http, https, ws, wss, ftp, file) do not survive URL normalization and would make the resource unreadable; pick a custom scheme such as \"wiki\"." }).default("zendesk-hc"),
+	/**
 	* Dev-only (stdio): expose the `reload_tools` tool, which re-imports the tool
 	* modules from source and re-registers them on the live session on demand, so
 	* tool code edited during a dev cycle takes effect without a restart. CLI-only
@@ -640,7 +674,11 @@ const parseCliArgs = (args) => {
 			i++;
 		} else if (arg === "--read-only") result.readOnly = true;
 		else if (arg === "--no-topology") result.topology = false;
-		else if (arg === "--dev") result.dev = true;
+		else if (arg === "--no-promoted-articles") result.promotedArticles = 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);
@@ -690,6 +728,7 @@ const loadConfig = (argv = process.argv.slice(2)) => {
 	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({
 		subdomain,
 		oauthClientId,
@@ -699,6 +738,8 @@ 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,
@@ -846,38 +887,99 @@ const helpCenterUpload = async (subdomain, token, path, formData) => {
 	return response.json();
 };
 //#endregion
-//#region src/guidance/instructions.ts
-/** Stable URI of the dynamic Help Center topology resource. */
-const TOPOLOGY_RESOURCE_URI = "zendesk-hc://topology";
-/**
-* Whether the Help Center structural context (init instructions + the
-* `zendesk-hc://topology` resource) 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 `zendesk-hc://topology` resource 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 ${TOPOLOGY_RESOURCE_URI} 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 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/utils/formatting.ts
@@ -1075,6 +1177,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(", ")}` : "",
@@ -1146,6 +1249,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.
@@ -1381,101 +1673,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);
@@ -1678,6 +1875,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}${truncated ? `\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._` : pagesScanned > 1 ? `\n\n_Note: this scan cost ${cost}; this tool performs a fresh scan every call (no caching), so avoid calling it again right away._` : ""}`)
+				}] };
+			}
+		},
 		{
 			name: "list_article_translations",
 			namespace: "help_center",
@@ -3509,7 +3731,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":
@@ -3534,7 +3756,7 @@ const registerToolset = (server, { config, getToken, onUnauthorized, logger = si
 		}
 		if (helpCenterContextEnabled(config)) {
 			const topology = createTopologyProvider(getToken, config.subdomain, onUnauthorized);
-			registered.push(server.registerResource("help-center-topology", TOPOLOGY_RESOURCE_URI, {
+			registered.push(server.registerResource("help-center-topology", topologyResourceUri(config), {
 				title: "Zendesk Help Center topology",
 				description: "Active locales, category → section tree, visibility segments, permission groups, and your role. Useful context when creating or editing content; admin-only sections (permission groups, user segments) are marked unavailable rather than empty when your role lacks Guide-admin rights.",
 				mimeType: "text/markdown"
@@ -3544,6 +3766,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;