@fruggr/zendesk-mcp-server 2.14.2 → 2.15.0

package/README.md

@@ -174,6 +174,9 @@ disabled together with `--no-topology`):
 
 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
+[`--hc-resource-scheme` / `HC_RESOURCE_SCHEME`](docs/configuration.md#hc_resource_scheme)
+(e.g. `wiki` → `wiki://topology`).
 
 ## Prerequisites
 

package/dist/index.js

@@ -595,13 +595,34 @@ const ConfigSchema = z.object({
 	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
+	* blob + the topology resource, default `zendesk-hc://topology`). 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),
 	/**
+	* 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
+	* RFC 3986 scheme — clients parse resource URIs with WHATWG `URL`, so a
+	* non-conformant scheme would surface as a broken resource at runtime;
+	* reject it at config parse time instead. ASCII-only message, value not
+	* echoed (same policy as parsePort below).
+	*/
+	hcResourceScheme: z.string().regex(/^[a-z][a-z0-9+.-]*$/, {
+		message: "Invalid HC_RESOURCE_SCHEME / --hc-resource-scheme value. Expected a bare RFC 3986 scheme: a lowercase letter followed by lowercase letters, digits, \"+\", \"-\" or \".\" (no \"://\").",
+		abort: true
+	}).refine((scheme) => {
+		const uri = `${scheme}://topology`;
+		try {
+			return new URL(uri).toString() === uri;
+		} catch {
+			return false;
+		}
+	}, { message: "Invalid HC_RESOURCE_SCHEME / --hc-resource-scheme value. WHATWG-special schemes (http, https, ws, wss, ftp, file) do not survive URL normalization and would make the resource unreadable; pick a custom scheme such as \"wiki\"." }).default("zendesk-hc"),
+	/**
 	* Dev-only (stdio): expose the `reload_tools` tool, which re-imports the tool
 	* modules from source and re-registers them on the live session on demand, so
 	* tool code edited during a dev cycle takes effect without a restart. CLI-only
@@ -640,7 +661,10 @@ const parseCliArgs = (args) => {
 			i++;
 		} else if (arg === "--read-only") result.readOnly = true;
 		else if (arg === "--no-topology") result.topology = false;
-		else if (arg === "--dev") result.dev = true;
+		else if (arg === "--hc-resource-scheme" && next) {
+			result.hcResourceScheme = next;
+			i++;
+		} else if (arg === "--dev") result.dev = true;
 		else if (arg === "--namespace" && next) {
 			result.namespaces = result.namespaces ?? [];
 			result.namespaces.push(next);
@@ -690,6 +714,7 @@ const loadConfig = (argv = process.argv.slice(2)) => {
 	const corsFromEnv = (process.env["CORS_ORIGIN"] ?? "").split(",").map((s) => s.trim()).filter((s) => s.length > 0);
 	const corsOrigins = [...cli.corsOrigins ?? [], ...corsFromEnv];
 	const callbackPort = cli.callbackPort ?? parsePortEnv(process.env["ZENDESK_OAUTH_CALLBACK_PORT"], "ZENDESK_OAUTH_CALLBACK_PORT");
+	const hcResourceScheme = cli.hcResourceScheme ?? (process.env["HC_RESOURCE_SCHEME"] || void 0);
 	return ConfigSchema.parse({
 		subdomain,
 		oauthClientId,
@@ -699,6 +724,7 @@ const loadConfig = (argv = process.argv.slice(2)) => {
 		namespaces: cli.namespaces,
 		tools: cli.tools,
 		topology: cli.topology ?? true,
+		hcResourceScheme,
 		dev: cli.dev ?? false,
 		transport,
 		host,
@@ -847,11 +873,17 @@ const helpCenterUpload = async (subdomain, token, path, formData) => {
 };
 //#endregion
 //#region src/guidance/instructions.ts
-/** Stable URI of the dynamic Help Center topology resource. */
-const TOPOLOGY_RESOURCE_URI = "zendesk-hc://topology";
+/**
+* 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
-* `zendesk-hc://topology` resource) should be exposed. True only when 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
@@ -862,14 +894,14 @@ const helpCenterContextEnabled = (config) => config.topology && (!config.namespa
 * 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.
+* 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 ${TOPOLOGY_RESOURCE_URI} is useful context:`,
+		`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.",
@@ -3534,7 +3566,7 @@ const registerToolset = (server, { config, getToken, onUnauthorized, logger = si
 		}
 		if (helpCenterContextEnabled(config)) {
 			const topology = createTopologyProvider(getToken, config.subdomain, onUnauthorized);
-			registered.push(server.registerResource("help-center-topology", TOPOLOGY_RESOURCE_URI, {
+			registered.push(server.registerResource("help-center-topology", topologyResourceUri(config), {
 				title: "Zendesk Help Center topology",
 				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"