@fruggr/zendesk-mcp-server 2.12.0 → 2.12.2

package/README.md

@@ -165,9 +165,12 @@ disabled together with `--no-topology`):
   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.
+  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.

package/dist/index.js

@@ -868,11 +868,14 @@ const buildInstructions = (config) => {
 	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,",
+		`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 the IDs from that resource (section_id, permission_group_id, user_segment_id, locale)",
-		"over guessing from names."
+		"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
@@ -1071,6 +1074,7 @@ const formatArticleSummary = (article) => [
 	`## ${article.title} (${article.id})`,
 	`- **Locale**: ${article.locale} | **Source locale**: ${article.source_locale}`,
 	`- **Section**: ${article.section_id} | **Draft**: ${article.draft}`,
+	`- **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(", ")}` : "",
 	`- **Created**: ${article.created_at} | **Updated**: ${article.updated_at}`
@@ -1143,6 +1147,28 @@ const extractSearchPaginationMeta = (response, perPage, page) => {
 //#endregion
 //#region src/guidance/topology.ts
 /**
+* Resolve an admin-gated fetch to a sentinel on HTTP 403 instead of rejecting.
+* Enumerating permission groups and user segments requires Guide-admin / Help
+* Center manager rights — a tier above per-article editing — so a content-editor
+* token gets 403 there while the rest of the topology is readable (#161). Any
+* other failure rethrows; crucially a 401 still propagates so the stale token
+* gets invalidated (see `onUnauthorized` in `createTopologyProvider`).
+*/
+const tolerate403 = async (promise, fallback) => {
+	try {
+		return {
+			value: await promise,
+			denied: false
+		};
+	} catch (error) {
+		if (error instanceof ZendeskApiError && error.status === 403) return {
+			value: fallback,
+			denied: true
+		};
+		throw error;
+	}
+};
+/**
 * 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` /
@@ -1150,12 +1176,12 @@ const extractSearchPaginationMeta = (response, perPage, page) => {
 */
 const fetchTopology = async (subdomain, token) => {
 	const pageParams = { "page[size]": String(100) };
-	const [locales, categoriesRes, sectionsRes, segmentsRes, permsRes, meRes] = await Promise.all([
+	const [locales, categoriesRes, sectionsRes, segments, perms, 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"),
+		tolerate403(helpCenterGet(subdomain, token, "/user_segments"), { user_segments: [] }),
+		tolerate403(zendeskGet(subdomain, token, "/guide/permission_groups"), { permission_groups: [] }),
 		zendeskGet(subdomain, token, "/users/me")
 	]);
 	const categories = categoriesRes.categories ?? [];
@@ -1167,8 +1193,10 @@ const fetchTopology = async (subdomain, token) => {
 		sections,
 		sectionsHasMore: extractPaginationMeta(sectionsRes, sections.length).has_more,
 		categoriesHasMore: extractPaginationMeta(categoriesRes, categories.length).has_more,
-		userSegments: segmentsRes.user_segments ?? [],
-		permissionGroups: permsRes.permission_groups ?? [],
+		userSegments: segments.value.user_segments ?? [],
+		userSegmentsDenied: segments.denied,
+		permissionGroups: perms.value.permission_groups ?? [],
+		permissionGroupsDenied: perms.denied,
 		currentUser: meRes.user
 	};
 };
@@ -1199,6 +1227,15 @@ const renderTree = (data) => {
 	}
 	return lines.length ? lines : ["_(no categories)_"];
 };
+/**
+* Render an admin-gated section as one of three states so the LLM never mistakes
+* "you can't see this" for "there are none": the formatted list, `_(none)_` when
+* genuinely empty, or `deniedNote` when the token was forbidden (403).
+*/
+const renderAdminSection = (items, denied, deniedNote) => {
+	if (denied) return [deniedNote];
+	return items.length ? items : ["_(none)_"];
+};
 /** Render the topology as a compact Markdown document for the LLM context. */
 const formatTopology = (data) => {
 	return truncateIfNeeded([
@@ -1214,10 +1251,10 @@ const formatTopology = (data) => {
 		...renderTree(data),
 		"",
 		"## Visibility (user segments)",
-		...data.userSegments.length ? data.userSegments.map(formatUserSegment) : ["_(none)_"],
+		...renderAdminSection(data.userSegments.map(formatUserSegment), data.userSegmentsDenied, "_Unavailable: listing user segments requires Guide-admin / Help Center manager rights, which this token lacks (HTTP 403). To set visibility, reuse the user_segment_id of an existing article (get_article), or omit it to default to everyone._"),
 		"",
 		"## Permission groups",
-		...data.permissionGroups.length ? data.permissionGroups.map(formatPermissionGroup) : ["_(none)_"]
+		...renderAdminSection(data.permissionGroups.map(formatPermissionGroup), data.permissionGroupsDenied, "_Unavailable: listing permission groups requires Guide-admin / Help Center manager rights, which this token lacks (HTTP 403). To create or edit an article, reuse the permission_group_id of an existing article (get_article)._")
 	].join("\n"));
 };
 /**
@@ -1650,9 +1687,16 @@ const createHelpCenterTools = (ctx) => {
 			},
 			handler: async () => {
 				const token = await getToken();
+				let response;
+				try {
+					response = await zendeskGet(subdomain, token, "/guide/permission_groups");
+				} catch (error) {
+					if (error instanceof ZendeskApiError && error.status === 403) throw new Error("list_permission_groups reads Guide permission groups (GET /guide/permission_groups), which Zendesk restricts to Guide admins / Help Center managers. The current token lacks that role (HTTP 403). To obtain a permission_group_id without it, read an existing article with get_article and reuse its permission_group_id.", { cause: error });
+					throw error;
+				}
 				return { content: [{
 					type: "text",
-					text: formatList((await zendeskGet(subdomain, token, "/guide/permission_groups")).permission_groups ?? [], formatPermissionGroup)
+					text: formatList(response.permission_groups ?? [], formatPermissionGroup)
 				}] };
 			}
 		},
@@ -1666,8 +1710,8 @@ const createHelpCenterTools = (ctx) => {
 				section_id: z.number().int().describe("Section that will contain the article (numeric id from list_sections)."),
 				title: z.string().min(1).describe("Title of the new article, in its source locale."),
 				body: z.string().min(1).describe("Article body as HTML (this becomes the source-locale content)."),
-				permission_group_id: z.number().int().describe("Permission group ID (use list_permission_groups to find it)"),
-				user_segment_id: z.number().int().optional().describe("User segment ID for visibility (use list_user_segments to find it). Defaults to everyone."),
+				permission_group_id: z.number().int().describe("Permission group ID (use list_permission_groups to find it; if that is forbidden because the token is not a Guide admin, reuse the permission_group_id of an existing article from get_article)."),
+				user_segment_id: z.number().int().optional().describe("User segment ID for visibility (use list_user_segments to find it; if that is forbidden because the token is not a Guide admin, reuse the user_segment_id of an existing article from get_article). Defaults to everyone."),
 				author_id: z.number().int().optional().describe("Author user ID. Defaults to the authenticated user."),
 				content_tag_ids: z.array(z.string()).optional().describe("Content tag IDs (use list_content_tags to find them)"),
 				locale: z.string().optional().describe("Source locale for the article, e.g. \"en-us\" or \"fr\". Defaults to the Help Center's default locale; becomes the article's source_locale."),
@@ -1703,9 +1747,9 @@ const createHelpCenterTools = (ctx) => {
 				promoted: z.boolean().optional().describe("Set true to promote (feature) the article in its section, or false to unpromote it."),
 				label_names: z.array(z.string()).optional().describe("Label names for search ranking (use list_labels to see existing labels)."),
 				content_tag_ids: z.array(z.string()).optional().describe("Content tag ids to attach (use list_content_tags to find them)."),
-				user_segment_id: z.number().int().optional().describe("User segment that controls who can see the article (id from list_user_segments)."),
+				user_segment_id: z.number().int().optional().describe("User segment that controls who can see the article (id from list_user_segments; if that is forbidden because the token is not a Guide admin, reuse the user_segment_id of an existing article from get_article)."),
 				author_id: z.number().int().optional().describe("User id of the article author (from search_users)."),
-				permission_group_id: z.number().int().optional().describe("Guide permission group controlling who can edit (id from list_permission_groups)."),
+				permission_group_id: z.number().int().optional().describe("Guide permission group controlling who can edit (id from list_permission_groups; if that is forbidden because the token is not a Guide admin, reuse the permission_group_id of an existing article from get_article)."),
 				section_id: z.number().int().optional().describe("Move the article to this section (numeric id from list_sections)."),
 				position: z.number().int().min(0).optional().describe("Sort position within the section (manual ordering only; 0 = first/top). New articles default to position 0. To move an article to the END of its section, set this to one more than the highest current position: read the highest position P from list_articles with sort_by=\"position\", sort_order=\"desc\", then set position = P + 1.")
 			}),
@@ -1762,7 +1806,7 @@ const createHelpCenterTools = (ctx) => {
 				name_prefix: z.string().min(1).optional().describe("Return only content tags whose name starts with this prefix (prefix match — not a substring or fuzzy search). Use the full name to check whether a specific tag already exists before creating it."),
 				sort_by: z.enum(["name", "id"]).default("name").describe("Field to sort by; \"name\" (the default) lists tags alphabetically."),
 				sort_order: z.enum(["asc", "desc"]).default("asc").describe("Sort direction: ascending or descending."),
-				page_size: z.number().int().min(1).max(100).default(100).describe("Content tags per page (1-100, default 100)."),
+				page_size: z.number().int().min(1).max(30).default(30).describe("Content tags per page (1-30, default 30). The Guide content-tags endpoint caps each page at 30; follow the returned cursor to enumerate the full list."),
 				cursor: z.string().optional().describe("Pagination cursor from a previous response; omit for the first page.")
 			}),
 			annotations: {
@@ -1847,9 +1891,16 @@ const createHelpCenterTools = (ctx) => {
 			},
 			handler: async () => {
 				const token = await getToken();
+				let response;
+				try {
+					response = await helpCenterGet(subdomain, token, "/user_segments");
+				} catch (error) {
+					if (error instanceof ZendeskApiError && error.status === 403) throw new Error("list_user_segments reads Help Center user segments (GET /help_center/user_segments), which Zendesk restricts to Guide admins / Help Center managers. The current token lacks that role (HTTP 403). To set an article's visibility without it, reuse the user_segment_id of an existing article (get_article), or omit user_segment_id when creating/updating to default to everyone.", { cause: error });
+					throw error;
+				}
 				return { content: [{
 					type: "text",
-					text: formatList((await helpCenterGet(subdomain, token, "/user_segments")).user_segments ?? [], formatUserSegment)
+					text: formatList(response.user_segments ?? [], formatUserSegment)
 				}] };
 			}
 		},
@@ -3292,7 +3343,7 @@ const registerToolset = (server, { config, getToken, onUnauthorized, logger = si
 			const topology = createTopologyProvider(getToken, config.subdomain, onUnauthorized);
 			registered.push(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.",
+				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"
 			}, async (uri) => ({ contents: [{
 				uri: uri.toString(),