@fruggr/zendesk-mcp-server 2.0.1 → 2.1.0

package/README.md

@@ -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`)
@@ -418,6 +439,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

@@ -566,6 +566,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 +604,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 +662,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 +781,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 +1133,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;
@@ -2294,10 +2442,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 +2480,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