@fruggr/zendesk-mcp-server 2.3.0 → 2.4.0

package/README.md

@@ -1,6 +1,7 @@
 # Zendesk MCP Server
 
 [![Glama score](https://glama.ai/mcp/servers/fruggr/zendesk-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/fruggr/zendesk-mcp-server)
+[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.fruggr%2Fzendesk--mcp--server-0a7ea4)](https://registry.modelcontextprotocol.io/?search=io.github.fruggr/zendesk-mcp-server)
 [![npm version](https://img.shields.io/npm/v/@fruggr/zendesk-mcp-server?logo=npm&color=cb3837)](https://www.npmjs.com/package/@fruggr/zendesk-mcp-server)
 [![License: MIT](https://img.shields.io/npm/l/@fruggr/zendesk-mcp-server?color=blue)](LICENSE)
 [![Node.js](https://img.shields.io/node/v/@fruggr/zendesk-mcp-server?logo=nodedotjs&logoColor=white&color=339933)](https://nodejs.org)
@@ -622,7 +623,7 @@ This project was built with reference to:
 
 ## Releases & versioning
 
-Versions follow [SemVer](https://semver.org/) and are calculated **automatically** from commit messages — no one bumps the version by hand. Every merge to `main` triggers [semantic-release](https://github.com/semantic-release/semantic-release), which inspects the new [Conventional Commits](https://www.conventionalcommits.org/) since the previous tag, computes the next version, updates [`CHANGELOG.md`](CHANGELOG.md), publishes to npm, and creates the matching GitHub Release.
+Versions follow [SemVer](https://semver.org/) and are calculated **automatically** from commit messages — no one bumps the version by hand. Every merge to `main` triggers [semantic-release](https://github.com/semantic-release/semantic-release), which inspects the new [Conventional Commits](https://www.conventionalcommits.org/) since the previous tag, computes the next version, updates [`CHANGELOG.md`](CHANGELOG.md), publishes to npm, creates the matching GitHub Release, and mirrors the release into the [official MCP registry](https://registry.modelcontextprotocol.io) as [`io.github.fruggr/zendesk-mcp-server`](https://registry.modelcontextprotocol.io/?search=io.github.fruggr/zendesk-mcp-server) so registry-driven clients discover the new version automatically.
 
 | Commit type | Resulting bump |
 |---|---|

package/dist/index.js

@@ -34,7 +34,7 @@ const MCP_LEVEL = {
 	warn: "warning",
 	error: "error"
 };
-const REDACTED_KEYS = new Set([
+const REDACTED_KEYS = /* @__PURE__ */ new Set([
 	"token",
 	"accesstoken",
 	"refreshtoken",
@@ -952,10 +952,10 @@ const buildOffsetParams = (perPage, page) => {
 	if (page && page > 1) params["page"] = String(page);
 	return params;
 };
-const extractPaginationMeta = (response) => ({
+const extractPaginationMeta = (response, itemCount) => ({
 	has_more: response.meta?.has_more ?? response.next_page != null,
 	after_cursor: response.meta?.after_cursor ?? null,
-	count: response.count ?? 0
+	count: response.count ?? itemCount
 });
 const extractSearchPaginationMeta = (response, perPage, page) => {
 	const count = response.count ?? 0;
@@ -984,13 +984,15 @@ const fetchTopology = async (subdomain, token) => {
 		zendeskGet(subdomain, token, "/guide/permission_groups"),
 		zendeskGet(subdomain, token, "/users/me")
 	]);
+	const categories = categoriesRes.categories ?? [];
+	const sections = sectionsRes.sections ?? [];
 	return {
 		subdomain,
 		locales,
-		categories: categoriesRes.categories ?? [],
-		sections: sectionsRes.sections ?? [],
-		sectionsHasMore: extractPaginationMeta(sectionsRes).has_more,
-		categoriesHasMore: extractPaginationMeta(categoriesRes).has_more,
+		categories,
+		sections,
+		sectionsHasMore: extractPaginationMeta(sectionsRes, sections.length).has_more,
+		categoriesHasMore: extractPaginationMeta(categoriesRes, categories.length).has_more,
 		userSegments: segmentsRes.user_segments ?? [],
 		permissionGroups: permsRes.permission_groups ?? [],
 		currentUser: meRes.user
@@ -1092,7 +1094,7 @@ const groupByNamespace = (tools) => {
 };
 //#endregion
 //#region src/utils/article-sections.ts
-const HEADING_LEVELS = new Set([
+const HEADING_LEVELS = /* @__PURE__ */ new Set([
 	"h1",
 	"h2",
 	"h3"
@@ -1279,9 +1281,10 @@ const createHelpCenterTools = (ctx) => {
 			handler: async (params) => {
 				const { locale, page_size, cursor } = params;
 				const response = await helpCenterGet(subdomain, await getToken(), locale ? `/${locale}/categories` : "/categories", buildCursorParams(page_size, cursor));
+				const categories = response.categories ?? [];
 				return { content: [{
 					type: "text",
-					text: formatList(response.categories ?? [], formatCategory, extractPaginationMeta(response))
+					text: formatList(categories, formatCategory, extractPaginationMeta(response, categories.length))
 				}] };
 			}
 		},
@@ -1306,9 +1309,10 @@ const createHelpCenterTools = (ctx) => {
 			handler: async (params) => {
 				const { category_id, locale, page_size, cursor } = params;
 				const response = await helpCenterGet(subdomain, await getToken(), category_id && locale ? `/${locale}/categories/${category_id}/sections` : category_id ? `/categories/${category_id}/sections` : locale ? `/${locale}/sections` : "/sections", buildCursorParams(page_size, cursor));
+				const sections = response.sections ?? [];
 				return { content: [{
 					type: "text",
-					text: formatList(response.sections ?? [], formatSection, extractPaginationMeta(response))
+					text: formatList(sections, formatSection, extractPaginationMeta(response, sections.length))
 				}] };
 			}
 		},
@@ -1321,8 +1325,8 @@ const createHelpCenterTools = (ctx) => {
 			inputSchema: z.object({
 				section_id: z.number().int().optional(),
 				locale: z.string().optional(),
-				page_size: z.number().int().min(1).max(100).default(100),
-				cursor: z.string().optional(),
+				page_size: z.number().int().min(1).max(100).default(100).describe("Articles per page (1-100, default 100)."),
+				cursor: z.string().optional().describe("Pagination cursor from a previous response; omit for the first page."),
 				sort_by: z.enum([
 					"created_at",
 					"updated_at",
@@ -1349,14 +1353,14 @@ const createHelpCenterTools = (ctx) => {
 				const articles = response.articles ?? [];
 				if (!include_translations) return { content: [{
 					type: "text",
-					text: formatList(articles, formatArticleSummary, extractPaginationMeta(response))
+					text: formatList(articles, formatArticleSummary, extractPaginationMeta(response, articles.length))
 				}] };
 				const formatted = await Promise.all(articles.map(async (article) => {
 					const { translations } = await helpCenterGet(subdomain, token, `/articles/${article.id}/translations`);
 					const locales = translations.map((t) => t.locale).join(", ");
 					return `${formatArticleSummary(article)}\n- **Translations**: ${locales}`;
 				}));
-				const meta = extractPaginationMeta(response);
+				const meta = extractPaginationMeta(response, articles.length);
 				return { content: [{
 					type: "text",
 					text: truncateIfNeeded([meta.count ? `Results: ${meta.count}${meta.has_more ? ` | More available (cursor: ${meta.after_cursor})` : ""}` : "", ...formatted].filter(Boolean).join("\n\n"))
@@ -2229,10 +2233,10 @@ const createTicketTools = (ctx) => {
 			namespace: "tickets",
 			readOnly: true,
 			title: "List Zendesk Tickets",
-			description: "List tickets with cursor-based pagination, sorted by most recently updated.",
+			description: "List tickets with cursor-based pagination, sorted by most recently updated. Page size is controlled by page_size (not per_page, which is the offset-based parameter used by search_tickets); paginate by passing the returned cursor.",
 			inputSchema: z.object({
-				page_size: z.number().int().min(1).max(100).default(100),
-				cursor: z.string().optional().describe("Pagination cursor")
+				page_size: z.number().int().min(1).max(100).default(100).describe("Tickets per page (1-100, default 100)."),
+				cursor: z.string().optional().describe("Pagination cursor from a previous response; omit for the first page.")
 			}),
 			annotations: {
 				readOnlyHint: true,
@@ -2243,9 +2247,10 @@ const createTicketTools = (ctx) => {
 			handler: async (params) => {
 				const { page_size, cursor } = params;
 				const response = await zendeskGet(subdomain, await getToken(), "/tickets", buildCursorParams(page_size, cursor));
+				const tickets = response.tickets ?? [];
 				return { content: [{
 					type: "text",
-					text: formatList(response.tickets ?? [], formatTicket, extractPaginationMeta(response))
+					text: formatList(tickets, formatTicket, extractPaginationMeta(response, tickets.length))
 				}] };
 			}
 		},
@@ -2329,7 +2334,7 @@ const createTicketTools = (ctx) => {
 				try {
 					response = await zendeskGet(subdomain, token, "/slas/policies", buildOffsetParams(per_page, page));
 				} catch (error) {
-					if (error instanceof ZendeskApiError && error.status === 403) throw new Error("list_sla_policies reads SLA policy *configuration* (GET /slas/policies), which Zendesk restricts to admins (or a custom role granted the SLA-management permission). The current token lacks that permission (HTTP 403). This does not affect live SLA on tickets: per-metric SLA stage and breach countdown are available to any agent via get_ticket and search_tickets -- use those for triage and prioritization.");
+					if (error instanceof ZendeskApiError && error.status === 403) throw new Error("list_sla_policies reads SLA policy *configuration* (GET /slas/policies), which Zendesk restricts to admins (or a custom role granted the SLA-management permission). The current token lacks that permission (HTTP 403). This does not affect live SLA on tickets: per-metric SLA stage and breach countdown are available to any agent via get_ticket and search_tickets -- use those for triage and prioritization.", { cause: error });
 					throw error;
 				}
 				const policies = response.sla_policies ?? [];
@@ -2463,9 +2468,10 @@ const createUserTools = (ctx) => {
 			handler: async (params) => {
 				const { page_size, cursor } = params;
 				const response = await zendeskGet(subdomain, await getToken(), "/organizations", buildCursorParams(page_size, cursor));
+				const organizations = response.organizations ?? [];
 				return { content: [{
 					type: "text",
-					text: formatList(response.organizations ?? [], formatOrganization, extractPaginationMeta(response))
+					text: formatList(organizations, formatOrganization, extractPaginationMeta(response, organizations.length))
 				}] };
 			}
 		}
@@ -2480,6 +2486,35 @@ const createAllTools = (ctx) => [
 	...createUserTools(ctx)
 ];
 //#endregion
+//#region src/utils/validation.ts
+/**
+* Build a strict params parser for a tool's input schema, computing the strict
+* schema and the valid-key list once (at proxy-dispatch construction) rather
+* than per call.
+*
+* Zod objects default to `strip`, which silently drops unknown keys. That hid
+* #100: a caller passing `per_page` to list_tickets (whose parameter is
+* `page_size`) had the key dropped, so `page_size` fell back to its default and
+* a large unpaginated page came back. The returned parser rejects unknown keys
+* and rewrites the raw Zod error into a message that names the offending keys
+* and lists the valid parameters so a mistyped/misremembered name fails loudly.
+*
+* Used on the proxy dispatch path (namespace/single modes), where this code
+* owns the parse. In `all` mode the SDK validates against the strict schema we
+* register and produces its own (also explicit) "Unrecognized key" message.
+*/
+const createStrictParamsParser = (schema) => {
+	const strict = schema.strict();
+	const validKeys = Object.keys(schema.shape).sort().join(", ");
+	return (params) => {
+		const result = strict.safeParse(params);
+		if (result.success) return result.data;
+		const unknownKeys = result.error.issues.filter((issue) => issue.code === "unrecognized_keys").flatMap((issue) => issue.keys ?? []);
+		if (unknownKeys.length > 0) throw new Error(`Unknown parameter(s): ${unknownKeys.join(", ")}. Valid parameters: ${validKeys || "(none)"}.`);
+		throw result.error;
+	};
+};
+//#endregion
 //#region src/server.ts
 /**
 * Invoke a tool handler, notifying `onUnauthorized` when Zendesk rejects the
@@ -2531,15 +2566,19 @@ const aggregateAnnotations = (tools) => ({
 });
 const buildProxyDispatch = (tools, onUnauthorized) => {
 	const operationNames = tools.map((t) => t.name);
-	const localHandlers = new Map(tools.map((t) => [t.name, t]));
+	const localHandlers = new Map(tools.map((t) => [t.name, {
+		def: t,
+		parseParams: createStrictParamsParser(t.inputSchema)
+	}]));
 	return async (args) => {
 		const { operation, params } = args;
-		const def = localHandlers.get(operation);
-		if (!def) return { content: [{
+		const entry = localHandlers.get(operation);
+		if (!entry) return { content: [{
 			type: "text",
 			text: `Unknown operation "${operation}". Available: ${operationNames.join(", ")}`
 		}] };
-		return runHandler(def, def.inputSchema.parse(params), onUnauthorized);
+		const validated = entry.parseParams(params);
+		return runHandler(entry.def, validated, onUnauthorized);
 	};
 };
 const registerProxyTool = (server, toolName, title, tools, readOnlyMode, onUnauthorized) => {
@@ -2582,7 +2621,7 @@ const createMcpServer = (config, getToken, logger = silentLogger, onUnauthorized
 			for (const tool of filteredTools) server.registerTool(tool.name, {
 				title: tool.title,
 				description: tool.description,
-				inputSchema: tool.inputSchema.shape,
+				inputSchema: tool.inputSchema.strict(),
 				annotations: tool.annotations
 			}, async (params) => runHandler(tool, params, onUnauthorized));
 			break;
@@ -2618,7 +2657,7 @@ const createMcpServer = (config, getToken, logger = silentLogger, onUnauthorized
 };
 //#endregion
 //#region src/transports/http.ts
-const WILDCARD_HOSTS = new Set([
+const WILDCARD_HOSTS = /* @__PURE__ */ new Set([
 	"0.0.0.0",
 	"::",
 	"*"
@@ -2637,12 +2676,12 @@ const CORS_ALLOWED_METHODS = "GET, POST, DELETE, OPTIONS";
 const CORS_ALLOWED_HEADERS = "Authorization, Content-Type, Accept, mcp-session-id, mcp-protocol-version, last-event-id";
 const CORS_EXPOSE_HEADERS = "mcp-session-id";
 const CORS_MAX_AGE = "600";
-const LOCALHOST_HOSTNAMES = new Set([
+const LOCALHOST_HOSTNAMES = /* @__PURE__ */ new Set([
 	"localhost",
 	"127.0.0.1",
 	"[::1]"
 ]);
-const ALLOWED_PROTOCOLS = new Set(["http:", "https:"]);
+const ALLOWED_PROTOCOLS = /* @__PURE__ */ new Set(["http:", "https:"]);
 /**
 * Returns the origin string to reflect in `Access-Control-Allow-Origin`, or
 * `undefined` if the origin is not allowed.