@fruggr/zendesk-mcp-server 2.15.0 → 2.16.0

package/README.md

@@ -155,28 +155,47 @@ The full tool-by-tool reference — every tool with its description and its
 
 Beyond tools, the server hands an LLM the structural context it needs to work
 against *your* Help Center — so it stops guessing locales or fuzzy-matching
-section names and uses real IDs instead. This is delivered through two
-MCP-native channels (both active only when the `help_center` namespace is, and
-disabled together with `--no-topology`):
+section names and uses real IDs instead. This is delivered through MCP-native
+channels (all active only when the `help_center` namespace is), each fetched
+**with the caller's own token** so it respects that user's read permissions:
 
 - **`instructions`** (sent on `initialize`): a short, static blob auto-loaded by
   compliant clients. It names the subdomain and points at the topology resource.
 - **`zendesk-hc://topology`** (a pull-only [MCP resource](https://modelcontextprotocol.io/docs/concepts/resources)):
   read on demand, it returns Markdown describing the active locales (and the
   default), the category → section tree with IDs, the visibility user segments,
-  the permission groups, and the calling user's role. It is fetched **with the
-  caller's own token**, so it respects that user's read permissions. Listing the
-  permission groups and user segments needs Guide-admin / Help Center manager
-  rights; with a content-editor token those two sections are marked *unavailable*
-  (not empty) and the rest still renders — reuse those IDs from an existing
-  article (`get_article`) instead. On a very large Help Center the section tree is
-  summarized (per-category, with a pointer to `list_sections`) to stay concise.
-
-Clients that don't consume `instructions` or `resources` simply ignore them —
-the feature degrades silently. Use `--no-topology` to turn both off server-wide.
-The `zendesk-hc://` URI scheme is the default; a deployer can brand it with
+  the permission groups, and the calling user's role. Listing the permission
+  groups and user segments needs Guide-admin / Help Center manager rights; with a
+  content-editor token those two sections are marked *unavailable* (not empty) and
+  the rest still renders — reuse those IDs from an existing article (`get_article`)
+  instead. On a very large Help Center the section tree is summarized (per-category,
+  with a pointer to `list_sections`) to stay concise.
+- **`zendesk-hc://article/{id}`** (pull-only [MCP resources](https://modelcontextprotocol.io/docs/concepts/resources)):
+  two distinct capabilities. **Read-by-id** — any article id can be read on demand,
+  returned as Markdown (a cheap single fetch, no preloading). **Promoted pre-listing** —
+  the resource's listing surfaces the promoted (*featured*) articles so a user can
+  pin one in clients that support resource pinning / @-mention, and the companion
+  `list_promoted_articles` tool returns the same set. Clients that don't support
+  resources ignore these silently.
+  <br>**Cost:** only the *pre-listing* costs requests — finding promoted articles has
+  no server-side filter, so it scans article pages (one Zendesk API request per page,
+  capped). The resource listing is cached briefly per session (repeated `resources/list`
+  calls coalesce); the `list_promoted_articles` tool performs a fresh scan on every
+  call. It runs only on a client's `resources/list` or a tool call, never at connect,
+  and consumes no LLM context until an article is pinned/read. Read-by-id costs one
+  fetch, only when a specific article is opened. See
+  [`ZENDESK_ARTICLE_RESOURCES_SCAN_MAX_PAGES`](docs/configuration.md#zendesk_article_resources_scan_max_pages).
+
+The `instructions` blob and the topology resource are toggled together with
+`--no-topology`. The **promoted pre-listing** is toggled independently with
+`--no-promoted-articles` — which turns off the resource `list` scan **and** the
+`list_promoted_articles` tool, so the server makes zero preloading requests;
+**reading a known article by id stays available** (it never preloads). Clients that
+don't consume `instructions` or `resources` simply ignore them — the feature
+degrades silently. The `zendesk-hc://` URI scheme is the default; a deployer can
+brand it with
 [`--hc-resource-scheme` / `HC_RESOURCE_SCHEME`](docs/configuration.md#hc_resource_scheme)
-(e.g. `wiki` → `wiki://topology`).
+(e.g. `wiki` → `wiki://topology`, `wiki://article/{id}`).
 
 ## Prerequisites
 

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);
@@ -603,6 +604,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
@@ -661,6 +674,7 @@ const parseCliArgs = (args) => {
 			i++;
 		} else if (arg === "--read-only") result.readOnly = true;
 		else if (arg === "--no-topology") result.topology = false;
+		else if (arg === "--no-promoted-articles") result.promotedArticles = false;
 		else if (arg === "--hc-resource-scheme" && next) {
 			result.hcResourceScheme = next;
 			i++;
@@ -724,6 +738,7 @@ 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,
@@ -872,44 +887,99 @@ 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 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
@@ -1107,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(", ")}` : "",
@@ -1178,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.
@@ -1413,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);
@@ -1710,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",
@@ -3541,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":
@@ -3576,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;