npm - @fruggr/zendesk-mcp-server - Versions diffs - 2.0.1 → 2.2.0 - Mend

@fruggr/zendesk-mcp-server 2.0.1 → 2.2.0

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 (4) hide show

package/README.md CHANGED Viewed

@@ -151,6 +151,27 @@ zendesk-mcp-server acme --namespace tickets
 </details>
+## Help Center context (instructions + resources)
+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`):
+- **`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. 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.
 ## Prerequisites
 - **Node.js** >= 20 (runtime — declared in `package.json#engines.node`)
@@ -203,8 +224,11 @@ file per subdomain in your OS config dir —
 elsewhere; override the path with `ZENDESK_TOKEN_FILE`). It is reused across restarts, so you don't
 re-authenticate every time the MCP client respawns the server. If the Zendesk
 OAuth client has token expiration enabled, the stored refresh token is used to
-renew access silently; only an expired/invalid refresh token triggers a new
-browser sign-in.
+renew access silently — **proactively** (the token is refreshed before use when
+it's expired, near expiry, or of unknown age, so the first request after an
+overnight gap never hits a visible auth error) and **periodically** in the
+background so a long-lived, idle session never serves a stale token. Only an
+expired/invalid refresh token triggers a new browser sign-in.
 > **Port conflict?** If port `27439` is already in use the first tool call returns
 > a clear error telling you to set `ZENDESK_OAUTH_CALLBACK_PORT` (or
@@ -418,6 +442,8 @@ Options:
   --namespace <ns>        Filter by namespace (repeatable): tickets, help_center, users
   --tool <name>           Filter by tool name (repeatable, forces --mode all)
   --read-only             Only expose read operations
+  --no-topology           Disable the Help Center structural context
+                          (instructions + zendesk-hc://topology resource)
   --log-level <level>     debug | info (default) | warn | error
   --transport <t>         stdio (default) | http
   --host <host>           HTTP bind host (default: 0.0.0.0)

package/dist/index.js CHANGED Viewed

@@ -221,7 +221,7 @@ const startBrowserAuth = (config, logger = silentLogger) => {
 				const tokenData = await tokenResponse.json();
 				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 Claude Code.</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>");
+				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);
@@ -432,6 +432,7 @@ const clearToken = (path, logger = silentLogger) => {
 //#endregion
 //#region src/auth/token-store.ts
 const EXPIRY_SKEW_MS = 6e4;
+const SCHEDULED_REFRESH_MS = 14400 * 1e3;
 const createAuthRequiredError = (authorizeUrl) => Object.assign(/* @__PURE__ */ new Error("Zendesk authentication required. A browser window should have opened for you to sign in. If it did not, open this URL in your browser, then retry your request:\n" + authorizeUrl), {
 	name: "AuthRequiredError",
 	authorizeUrl
@@ -444,16 +445,18 @@ const createTokenStore = (config, logger = silentLogger) => {
 	let authorizeUrl;
 	let starting;
 	let refreshing;
+	let probedUnknownExpiry = false;
 	const persist = (t) => saveToken(tokenPath, t, logger);
 	const setToken = (accessToken, refreshToken) => {
 		token = {
 			accessToken,
 			refreshToken
 		};
+		probedUnknownExpiry = false;
 		persist(token);
 	};
-	const isExpired = (t) => typeof t.expiresAt === "number" && Date.now() >= t.expiresAt - EXPIRY_SKEW_MS;
-	const tryRefresh = async (current) => {
+	const needsRefresh = (t) => typeof t.expiresAt === "number" ? Date.now() >= t.expiresAt - EXPIRY_SKEW_MS : t.refreshToken !== void 0 && !probedUnknownExpiry;
+	const tryRefresh = async (current, { dropOnFailure = true } = {}) => {
 		if (!current.refreshToken) return void 0;
 		try {
 			const result = await refreshAccessToken({
@@ -466,13 +469,16 @@ const createTokenStore = (config, logger = silentLogger) => {
 				refreshToken: result.refresh_token ?? current.refreshToken,
 				expiresAt: expiryFrom(result.expires_in)
 			};
+			probedUnknownExpiry = true;
 			persist(token);
 			logger.info("oauth_token_refreshed_cached");
 			return token.accessToken;
 		} catch (err) {
 			logger.warn("oauth_token_refresh_failed", { error: err instanceof Error ? err.message : String(err) });
-			token = void 0;
-			clearToken(tokenPath, logger);
+			if (dropOnFailure) {
+				token = void 0;
+				clearToken(tokenPath, logger);
+			}
 			return;
 		}
 	};
@@ -490,6 +496,7 @@ const createTokenStore = (config, logger = silentLogger) => {
 					refreshToken: result.refresh_token,
 					expiresAt: expiryFrom(result.expires_in)
 				};
+				probedUnknownExpiry = true;
 				persist(token);
 				logger.info("oauth_token_cached");
 			}).catch((err) => {
@@ -505,7 +512,8 @@ const createTokenStore = (config, logger = silentLogger) => {
 		});
 	};
 	const getToken = async () => {
-		if (token && !isExpired(token)) {
+		if (refreshing) await refreshing;
+		if (token && !needsRefresh(token)) {
 			logger.debug("oauth_token_cache_hit");
 			return token.accessToken;
 		}
@@ -533,10 +541,18 @@ const createTokenStore = (config, logger = silentLogger) => {
 		}
 		logger.info("oauth_token_invalidated");
 	};
+	const scheduledRefresh = setInterval(() => {
+		if (token?.refreshToken && !refreshing) refreshing = tryRefresh(token, { dropOnFailure: false }).finally(() => {
+			refreshing = void 0;
+		});
+	}, SCHEDULED_REFRESH_MS);
+	scheduledRefresh.unref?.();
+	const dispose = () => clearInterval(scheduledRefresh);
 	return {
 		getToken,
 		setToken,
-		invalidate
+		invalidate,
+		dispose
 	};
 };
 //#endregion
@@ -566,6 +582,14 @@ const ConfigSchema = z.object({
 	readOnly: z.boolean(),
 	namespaces: z.array(Namespace).optional(),
 	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
+	* 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),
 	transport: Transport,
 	host: z.string().min(1),
 	port: z.number().int().min(0).max(65535),
@@ -596,6 +620,7 @@ const parseCliArgs = (args) => {
 			result.mode = next;
 			i++;
 		} else if (arg === "--read-only") result.readOnly = true;
+		else if (arg === "--no-topology") result.topology = false;
 		else if (arg === "--namespace" && next) {
 			result.namespaces = result.namespaces ?? [];
 			result.namespaces.push(next);
@@ -653,6 +678,7 @@ const loadConfig = (argv = process.argv.slice(2)) => {
 		readOnly: cli.readOnly ?? false,
 		namespaces: cli.namespaces,
 		tools: cli.tools,
+		topology: cli.topology ?? true,
 		transport,
 		host,
 		port,
@@ -771,6 +797,246 @@ 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}".`,
+		"",
+		`Before creating or editing Help Center content, read the resource ${TOPOLOGY_RESOURCE_URI}.`,
+		"It describes 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 the IDs from that resource (section_id, permission_group_id, user_segment_id, locale)",
+		"over guessing from names."
+	].join("\n");
+};
+//#endregion
+//#region src/utils/formatting.ts
+const truncateIfNeeded = (text) => {
+	if (text.length <= 25e3) return text;
+	return `${text.slice(0, CHARACTER_LIMIT)}\n\n--- Response truncated (${text.length} chars, limit ${CHARACTER_LIMIT}). Use pagination or filters to reduce results. ---`;
+};
+const formatPagination = (meta) => {
+	const parts = [`Results: ${meta.count}`];
+	if (meta.has_more) parts.push(`More available (cursor: ${meta.after_cursor})`);
+	return parts.join(" | ");
+};
+const formatTicket = (ticket) => [
+	`## Ticket #${ticket.id}: ${ticket.subject}`,
+	`- **Status**: ${ticket.status} | **Priority**: ${ticket.priority ?? "none"} | **Type**: ${ticket.type ?? "none"}`,
+	`- **Requester**: ${ticket.requester_id} | **Assignee**: ${ticket.assignee_id ?? "unassigned"}`,
+	`- **Tags**: ${ticket.tags.length > 0 ? ticket.tags.join(", ") : "none"}`,
+	`- **Created**: ${ticket.created_at} | **Updated**: ${ticket.updated_at}`,
+	ticket.description ? `\n${ticket.description}` : ""
+].filter(Boolean).join("\n");
+const formatComment = (comment) => {
+	const lines = [`### ${comment.public ? "Public comment" : "Internal note"} by ${comment.author_id}`, `*${comment.created_at}*`];
+	if (comment.attachments?.length) {
+		const summary = comment.attachments.map((a) => `#${a.id} (${a.content_type})`).join(", ");
+		lines.push(`Attachments: ${summary}`);
+	}
+	lines.push("", comment.body);
+	return lines.join("\n");
+};
+const formatUser = (user) => [
+	`## ${user.name} (${user.id})`,
+	`- **Email**: ${user.email}`,
+	`- **Role**: ${user.role}`,
+	user.role_type != null ? `- **Role type**: ${user.role_type}` : "",
+	`- **Active**: ${user.active}`,
+	user.organization_id ? `- **Organization**: ${user.organization_id}` : ""
+].filter(Boolean).join("\n");
+const formatOrganization = (org) => [
+	`## ${org.name} (${org.id})`,
+	org.details ? `- **Details**: ${org.details}` : "",
+	org.domain_names.length > 0 ? `- **Domains**: ${org.domain_names.join(", ")}` : "",
+	org.tags.length > 0 ? `- **Tags**: ${org.tags.join(", ")}` : ""
+].filter(Boolean).join("\n");
+const formatArticleSummary = (article) => [
+	`## ${article.title} (${article.id})`,
+	`- **Locale**: ${article.locale} | **Source locale**: ${article.source_locale}`,
+	`- **Section**: ${article.section_id} | **Draft**: ${article.draft}`,
+	typeof article.position === "number" ? `- **Position**: ${article.position}` : "",
+	article.label_names.length > 0 ? `- **Labels**: ${article.label_names.join(", ")}` : "",
+	`- **Created**: ${article.created_at} | **Updated**: ${article.updated_at}`
+].filter(Boolean).join("\n");
+const formatArticle = (article) => [
+	formatArticleSummary(article),
+	"",
+	article.body
+].join("\n");
+const formatTranslationSummary = (translation) => [
+	`## Translation: ${translation.locale} (${translation.id})`,
+	`- **Title**: ${translation.title}`,
+	`- **Draft**: ${translation.draft}`,
+	`- **Updated**: ${translation.updated_at}`
+].join("\n");
+const formatTranslation = (translation) => [
+	formatTranslationSummary(translation),
+	"",
+	translation.body
+].join("\n");
+const formatCategory = (category) => `- **${category.name}** (${category.id}) — ${category.description || "No description"}`;
+const formatSection = (section) => `- **${section.name}** (${section.id}) — Category: ${section.category_id} — ${section.description || "No description"}`;
+const formatPermissionGroup = (group) => `- **${group.name}** (${group.id})${group.built_in ? " — Built-in" : ""}`;
+const formatContentTag = (tag) => `- **${tag.name}** (${tag.id})`;
+const formatLabel = (label) => `- **${label.name}** (${label.id})`;
+const formatUserSegment = (segment) => `- **${segment.name}** (${segment.id}) — ${segment.user_type}${segment.built_in ? " — Built-in" : ""}`;
+const formatAttachment = (attachment) => `- **${attachment.file_name}** (${attachment.id}) — ${attachment.content_type} — ${attachment.size} bytes`;
+const formatList = (items, formatter, meta) => {
+	return truncateIfNeeded([meta ? formatPagination(meta) : "", items.map(formatter).join("\n\n")].filter(Boolean).join("\n\n"));
+};
+//#endregion
+//#region src/utils/pagination.ts
+const buildCursorParams = (pageSize, cursor) => {
+	const params = { "page[size]": String(pageSize) };
+	if (cursor) params["page[after]"] = cursor;
+	return params;
+};
+const buildOffsetParams = (perPage, page) => {
+	const params = { per_page: String(perPage) };
+	if (page && page > 1) params["page"] = String(page);
+	return params;
+};
+const extractPaginationMeta = (response) => ({
+	has_more: response.meta?.has_more ?? response.next_page != null,
+	after_cursor: response.meta?.after_cursor ?? null,
+	count: response.count ?? 0
+});
+const extractSearchPaginationMeta = (response, perPage, page) => {
+	const count = response.count ?? 0;
+	const has_more = count > page * perPage;
+	return {
+		has_more,
+		after_cursor: has_more ? String(page + 1) : null,
+		count
+	};
+};
+//#endregion
+//#region src/guidance/topology.ts
+/**
+* Fetch the structural topology with the CALLER'S token, so the result respects
+* that user's read permissions (no privileged shared credential). Categories
+* and sections are each capped at one max-size page; `sectionsHasMore` /
+* `categoriesHasMore` signal a Help Center too large to enumerate inline.
+*/
+const fetchTopology = async (subdomain, token) => {
+	const pageParams = { "page[size]": String(100) };
+	const [locales, categoriesRes, sectionsRes, segmentsRes, permsRes, meRes] = await Promise.all([
+		helpCenterGet(subdomain, token, "/locales"),
+		helpCenterGet(subdomain, token, "/categories", pageParams),
+		helpCenterGet(subdomain, token, "/sections", pageParams),
+		helpCenterGet(subdomain, token, "/user_segments"),
+		zendeskGet(subdomain, token, "/guide/permission_groups"),
+		zendeskGet(subdomain, token, "/users/me")
+	]);
+	return {
+		subdomain,
+		locales,
+		categories: categoriesRes.categories ?? [],
+		sections: sectionsRes.sections ?? [],
+		sectionsHasMore: extractPaginationMeta(sectionsRes).has_more,
+		categoriesHasMore: extractPaginationMeta(categoriesRes).has_more,
+		userSegments: segmentsRes.user_segments ?? [],
+		permissionGroups: permsRes.permission_groups ?? [],
+		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 byCategory = /* @__PURE__ */ new Map();
+	for (const section of data.sections) {
+		const list = byCategory.get(section.category_id) ?? [];
+		list.push(section);
+		byCategory.set(section.category_id, list);
+	}
+	const lines = [];
+	for (const category of data.categories) {
+		lines.push(formatCategory(category));
+		for (const section of byCategory.get(category.id) ?? []) lines.push(`  ${formatSection(section)}`);
+	}
+	return lines.length ? lines : ["_(no categories)_"];
+};
+/** Render the topology as a compact Markdown document for the LLM context. */
+const formatTopology = (data) => {
+	return truncateIfNeeded([
+		`# Zendesk Help Center topology — ${data.subdomain}`,
+		"",
+		`**Your access**: ${data.currentUser.name} (id ${data.currentUser.id}), role "${data.currentUser.role}".`,
+		"",
+		"## Locales",
+		`- Default: ${data.locales.default_locale}`,
+		`- Active: ${data.locales.locales.join(", ")}`,
+		"",
+		"## Categories → sections",
+		...renderTree(data),
+		"",
+		"## Visibility (user segments)",
+		...data.userSegments.length ? data.userSegments.map(formatUserSegment) : ["_(none)_"],
+		"",
+		"## Permission groups",
+		...data.permissionGroups.length ? data.permissionGroups.map(formatPermissionGroup) : ["_(none)_"]
+	].join("\n"));
+};
+/**
+* Build a topology provider holding a memoized-promise cache (TTL
+* `TOPOLOGY_TTL_MS`). In HTTP mode `createMcpServer` — and therefore this
+* provider — is instantiated PER SESSION, so this cache is per-session /
+* per-caller: it must NOT be hoisted to module scope, or one tenant's structure
+* would leak to another. The promise (not the value) is cached to coalesce
+* concurrent reads; failures are evicted so the next read retries with a fresh
+* token. A 401 notifies `onUnauthorized` (stdio OAuth only) to invalidate the
+* stale token, mirroring the tool dispatch path in `server.ts`.
+*/
+const createTopologyProvider = (getToken, subdomain, onUnauthorized) => {
+	let cached;
+	return { read() {
+		const now = Date.now();
+		if (cached && now - cached.at < 3e5) return cached.promise;
+		const promise = (async () => {
+			return formatTopology(await fetchTopology(subdomain, await getToken()));
+		})().catch((err) => {
+			cached = void 0;
+			if (onUnauthorized && err instanceof ZendeskApiError && err.status === 401) onUnauthorized();
+			throw err;
+		});
+		cached = {
+			at: now,
+			promise
+		};
+		return promise;
+	} };
+};
+//#endregion
 //#region src/routing/registry.ts
 const filterTools = (allTools, options) => allTools.filter((tool) => {
 	if (options.readOnly && !tool.readOnly) return false;
@@ -883,108 +1149,6 @@ const markdownToHtml = (markdown) => {
 	return String(mdToHtmlProcessor.processSync(markdown));
 };
 //#endregion
-//#region src/utils/formatting.ts
-const truncateIfNeeded = (text) => {
-	if (text.length <= 25e3) return text;
-	return `${text.slice(0, CHARACTER_LIMIT)}\n\n--- Response truncated (${text.length} chars, limit ${CHARACTER_LIMIT}). Use pagination or filters to reduce results. ---`;
-};
-const formatPagination = (meta) => {
-	const parts = [`Results: ${meta.count}`];
-	if (meta.has_more) parts.push(`More available (cursor: ${meta.after_cursor})`);
-	return parts.join(" | ");
-};
-const formatTicket = (ticket) => [
-	`## Ticket #${ticket.id}: ${ticket.subject}`,
-	`- **Status**: ${ticket.status} | **Priority**: ${ticket.priority ?? "none"} | **Type**: ${ticket.type ?? "none"}`,
-	`- **Requester**: ${ticket.requester_id} | **Assignee**: ${ticket.assignee_id ?? "unassigned"}`,
-	`- **Tags**: ${ticket.tags.length > 0 ? ticket.tags.join(", ") : "none"}`,
-	`- **Created**: ${ticket.created_at} | **Updated**: ${ticket.updated_at}`,
-	ticket.description ? `\n${ticket.description}` : ""
-].filter(Boolean).join("\n");
-const formatComment = (comment) => {
-	const lines = [`### ${comment.public ? "Public comment" : "Internal note"} by ${comment.author_id}`, `*${comment.created_at}*`];
-	if (comment.attachments?.length) {
-		const summary = comment.attachments.map((a) => `#${a.id} (${a.content_type})`).join(", ");
-		lines.push(`Attachments: ${summary}`);
-	}
-	lines.push("", comment.body);
-	return lines.join("\n");
-};
-const formatUser = (user) => [
-	`## ${user.name} (${user.id})`,
-	`- **Email**: ${user.email}`,
-	`- **Role**: ${user.role}`,
-	user.role_type != null ? `- **Role type**: ${user.role_type}` : "",
-	`- **Active**: ${user.active}`,
-	user.organization_id ? `- **Organization**: ${user.organization_id}` : ""
-].filter(Boolean).join("\n");
-const formatOrganization = (org) => [
-	`## ${org.name} (${org.id})`,
-	org.details ? `- **Details**: ${org.details}` : "",
-	org.domain_names.length > 0 ? `- **Domains**: ${org.domain_names.join(", ")}` : "",
-	org.tags.length > 0 ? `- **Tags**: ${org.tags.join(", ")}` : ""
-].filter(Boolean).join("\n");
-const formatArticleSummary = (article) => [
-	`## ${article.title} (${article.id})`,
-	`- **Locale**: ${article.locale} | **Source locale**: ${article.source_locale}`,
-	`- **Section**: ${article.section_id} | **Draft**: ${article.draft}`,
-	typeof article.position === "number" ? `- **Position**: ${article.position}` : "",
-	article.label_names.length > 0 ? `- **Labels**: ${article.label_names.join(", ")}` : "",
-	`- **Created**: ${article.created_at} | **Updated**: ${article.updated_at}`
-].filter(Boolean).join("\n");
-const formatArticle = (article) => [
-	formatArticleSummary(article),
-	"",
-	article.body
-].join("\n");
-const formatTranslationSummary = (translation) => [
-	`## Translation: ${translation.locale} (${translation.id})`,
-	`- **Title**: ${translation.title}`,
-	`- **Draft**: ${translation.draft}`,
-	`- **Updated**: ${translation.updated_at}`
-].join("\n");
-const formatTranslation = (translation) => [
-	formatTranslationSummary(translation),
-	"",
-	translation.body
-].join("\n");
-const formatCategory = (category) => `- **${category.name}** (${category.id}) — ${category.description || "No description"}`;
-const formatSection = (section) => `- **${section.name}** (${section.id}) — Category: ${section.category_id} — ${section.description || "No description"}`;
-const formatPermissionGroup = (group) => `- **${group.name}** (${group.id})${group.built_in ? " — Built-in" : ""}`;
-const formatContentTag = (tag) => `- **${tag.name}** (${tag.id})`;
-const formatLabel = (label) => `- **${label.name}** (${label.id})`;
-const formatUserSegment = (segment) => `- **${segment.name}** (${segment.id}) — ${segment.user_type}${segment.built_in ? " — Built-in" : ""}`;
-const formatAttachment = (attachment) => `- **${attachment.file_name}** (${attachment.id}) — ${attachment.content_type} — ${attachment.size} bytes`;
-const formatList = (items, formatter, meta) => {
-	return truncateIfNeeded([meta ? formatPagination(meta) : "", items.map(formatter).join("\n\n")].filter(Boolean).join("\n\n"));
-};
-//#endregion
-//#region src/utils/pagination.ts
-const buildCursorParams = (pageSize, cursor) => {
-	const params = { "page[size]": String(pageSize) };
-	if (cursor) params["page[after]"] = cursor;
-	return params;
-};
-const buildOffsetParams = (perPage, page) => {
-	const params = { per_page: String(perPage) };
-	if (page && page > 1) params["page"] = String(page);
-	return params;
-};
-const extractPaginationMeta = (response) => ({
-	has_more: response.meta?.has_more ?? response.next_page != null,
-	after_cursor: response.meta?.after_cursor ?? null,
-	count: response.count ?? 0
-});
-const extractSearchPaginationMeta = (response, perPage, page) => {
-	const count = response.count ?? 0;
-	const has_more = count > page * perPage;
-	return {
-		has_more,
-		after_cursor: has_more ? String(page + 1) : null,
-		count
-	};
-};
-//#endregion
 //#region src/tools/help-center.ts
 const largeArticleHint = (body, sectionCount) => {
 	if (body.length < 3e3 && sectionCount < 4) return null;
@@ -2228,6 +2392,13 @@ const createAllTools = (ctx) => [
 * refreshes/re-authenticates instead of replaying a revoked token. The callback
 * is omitted only where there is nothing to invalidate (e.g. HTTP per-session
 * bearer, owned by the client).
+*
+* Client-visible behaviour on an in-flight revocation: the 401 is a *backstop*,
+* not a transparent retry. The current call still surfaces the error; recovery
+* happens on the *next* call, whose `getToken` sees the invalidated token and
+* silently refreshes (or falls back to browser re-auth if the refresh token is
+* also dead). Proactive refresh keeps this path rare — it only fires when a
+* token is revoked between the pre-call refresh check and the request.
 */
 const runHandler = async (def, params, onUnauthorized) => {
 	try {
@@ -2294,10 +2465,14 @@ const registerProxyTool = (server, toolName, title, tools, readOnlyMode, onUnaut
 };
 const createMcpServer = (config, getToken, logger = silentLogger, onUnauthorized) => {
 	const pkg = readPackageInfo();
+	const instructions = buildInstructions(config);
 	const server = new McpServer({
 		name: pkg.name,
 		version: pkg.version
-	}, { capabilities: { logging: {} } });
+	}, {
+		capabilities: { logging: {} },
+		...instructions ? { instructions } : {}
+	});
 	logger.attachServer(server);
 	const filteredTools = filterTools(createAllTools({
 		subdomain: config.subdomain,
@@ -2328,6 +2503,18 @@ const createMcpServer = (config, getToken, logger = silentLogger, onUnauthorized
 			registerProxyTool(server, "zendesk", "Zendesk", filteredTools, config.readOnly, onUnauthorized);
 			break;
 	}
+	if (helpCenterContextEnabled(config)) {
+		const topology = createTopologyProvider(getToken, config.subdomain, onUnauthorized);
+		server.registerResource("help-center-topology", TOPOLOGY_RESOURCE_URI, {
+			title: "Zendesk Help Center topology",
+			description: "Active locales, category → section tree, visibility segments, permission groups, and your role. Read before creating or editing content.",
+			mimeType: "text/markdown"
+		}, async (uri) => ({ contents: [{
+			uri: uri.toString(),
+			mimeType: "text/markdown",
+			text: await topology.read()
+		}] }));
+	}
 	logger.info("tools_registered", {
 		count: filteredTools.length,
 		mode: config.mode