@fruggr/zendesk-mcp-server 2.23.0 → 2.24.0

package/README.md

@@ -83,7 +83,7 @@ differently.
 - Two deployment shapes, same auth story. Run it on your laptop as a stdio MCP
   server, or deploy it as a private remote MCP server reached over HTTP, with one
   Zendesk session per request and each client carrying its own user's token.
-- A lean stack: the official `@modelcontextprotocol/sdk` plus `zod`, speaking to
+- A lean stack: the official MCP TypeScript SDK (`@modelcontextprotocol/server`) plus `zod`, speaking to
   the Zendesk Support and Help Center (Guide) APIs.
 
 Look elsewhere when:
@@ -139,7 +139,7 @@ Signing in needs a Zendesk OAuth client, so register one first (next section).
 2. Create a **public** client:
    - **Identifier**: `<your-subdomain>_zendesk` (or set `ZENDESK_OAUTH_CLIENT_ID`)
    - **Redirect URL**: `http://localhost:27439/callback` (change the port to match
-     `ZENDESK_OAUTH_CALLBACK_PORT` / `--callback-port` if you override it; Zendesk
+     `OAUTH_CALLBACK_PORT` / `--callback-port` if you override it; Zendesk
      accepts several redirect URLs, one per line)
 
 If the client restricts its **allowed scopes**, it needs `read` — plus `write`
@@ -151,7 +151,7 @@ window and returns the authorize URL in a tool message. The call does not block
 waiting for sign-in, so authenticate in the browser and then retry the request.
 The token is persisted to an owner-only file and reused across restarts, so you
 don't authenticate again every time your MCP client respawns the server (path
-and overrides: [`ZENDESK_TOKEN_FILE`](docs/configuration.md#zendesk_token_file)).
+and overrides: [`OAUTH_TOKEN_FILE`](docs/configuration.md#oauth_token_file)).
 Several instances can run side by side — a read-write one and a `--read-only`
 one, say — without trading credentials.
 
@@ -326,7 +326,7 @@ to turn each piece off: **[docs/help-center-context.md](docs/help-center-context
 
 The complete reference for the CLI flags (`--mode`, `--namespace`,
 `--read-only`, `--transport`, `--public-url`, and so on) and the environment
-variables (`ZENDESK_SUBDOMAIN`, `ZENDESK_TOKEN_FILE`, `PUBLIC_URL`, the
+variables (`ZENDESK_SUBDOMAIN`, `OAUTH_TOKEN_FILE`, `PUBLIC_URL`, the
 attachment-vision caps) lives in
 **[docs/configuration.md](docs/configuration.md)**. Every variable has its own
 anchor, so you can deep-link a specific setting.

package/dist/index.js

@@ -9,7 +9,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { parseArgs } from "node:util";
 import * as z from "zod/v4";
-import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/server";
 import * as cheerio from "cheerio";
 import { toHtml } from "hast-util-to-html";
 import rehypeParse from "rehype-parse";
@@ -21,8 +21,8 @@ import remarkParse from "remark-parse";
 import remarkRehype from "remark-rehype";
 import remarkStringify from "remark-stringify";
 import { unified } from "unified";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import { NodeStreamableHTTPServerTransport } from "@modelcontextprotocol/node";
 //#region src/utils/logger.ts
 const SEVERITY = {
 	debug: 0,
@@ -118,25 +118,74 @@ const createLogger = (level) => {
 	};
 };
 //#endregion
+//#region src/utils/env.ts
+const LEGACY_NAMES = /* @__PURE__ */ new Map([
+	["OAUTH_TOKEN_FILE", "ZENDESK_TOKEN_FILE"],
+	["OAUTH_CALLBACK_PORT", "ZENDESK_OAUTH_CALLBACK_PORT"],
+	["LISTEN_HOST", "HOST"],
+	["RESPONSE_CHARACTER_LIMIT", "ZENDESK_CHARACTER_LIMIT"],
+	["RESPONSE_MAX_BYTES", "ZENDESK_MAX_RESPONSE_BYTES"],
+	["ATTACHMENT_MAX_BYTES", "ZENDESK_MAX_ATTACHMENT_BYTES"],
+	["EMBEDDED_IMAGES_MAX", "ZENDESK_MAX_EMBEDDED_IMAGES"],
+	["COMMENT_MAX_PAGES", "ZENDESK_MAX_COMMENT_PAGES"],
+	["TICKET_FIELD_SCAN_MAX_PAGES", "ZENDESK_TICKET_FIELD_SCAN_MAX_PAGES"],
+	["ARTICLE_RESOURCES_SCAN_MAX_PAGES", "ZENDESK_ARTICLE_RESOURCES_SCAN_MAX_PAGES"],
+	["REORDER_CONFIRM_THRESHOLD", "ZENDESK_REORDER_CONFIRM_THRESHOLD"]
+]);
+const warned = /* @__PURE__ */ new Set();
+const warnDeprecated = (legacy, current) => {
+	if (warned.has(legacy)) return;
+	warned.add(legacy);
+	try {
+		console.error(`[zendesk-mcp] [warn] deprecated_env_var name=${legacy} replacement=${current} removal=3.0.0`);
+	} catch {}
+};
+/**
+* Reads `name`, falling back to the legacy name it replaced. `name` in the result
+* is the variable the value came from, so an error about it names what the
+* operator actually set.
+*/
+const readEnv = (name) => {
+	const value = process.env[name];
+	const legacy = LEGACY_NAMES.get(name);
+	if (legacy === void 0) return {
+		name,
+		value
+	};
+	const legacyValue = process.env[legacy];
+	if (legacyValue === void 0) return {
+		name,
+		value
+	};
+	warnDeprecated(legacy, name);
+	return value === void 0 ? {
+		name: legacy,
+		value: legacyValue
+	} : {
+		name,
+		value
+	};
+};
+//#endregion
 //#region src/constants.ts
 const positiveIntEnv = (name, fallback) => {
-	const raw = process.env[name];
+	const raw = readEnv(name).value;
 	if (raw === void 0 || raw.trim() === "") return fallback;
 	const parsed = Number(raw);
 	return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback;
 };
-const CHARACTER_LIMIT = positiveIntEnv("ZENDESK_CHARACTER_LIMIT", 25e3);
-const ARTICLE_RESOURCES_SCAN_MAX_PAGES = positiveIntEnv("ZENDESK_ARTICLE_RESOURCES_SCAN_MAX_PAGES", 20);
-const MAX_ATTACHMENT_BYTES = positiveIntEnv("ZENDESK_MAX_ATTACHMENT_BYTES", 5242880);
-const MAX_EMBEDDED_IMAGE_COUNT = positiveIntEnv("ZENDESK_MAX_EMBEDDED_IMAGES", 10);
+const CHARACTER_LIMIT = positiveIntEnv("RESPONSE_CHARACTER_LIMIT", 25e3);
+const ARTICLE_RESOURCES_SCAN_MAX_PAGES = positiveIntEnv("ARTICLE_RESOURCES_SCAN_MAX_PAGES", 20);
+const MAX_ATTACHMENT_BYTES = positiveIntEnv("ATTACHMENT_MAX_BYTES", 5242880);
+const MAX_EMBEDDED_IMAGE_COUNT = positiveIntEnv("EMBEDDED_IMAGES_MAX", 10);
 const STDIO_MAX_MESSAGE_BYTES = 10485760;
 const MESSAGE_CONTENT_BUDGET_BYTES = 10420224;
-const MAX_RESPONSE_BYTES = Math.min(positiveIntEnv("ZENDESK_MAX_RESPONSE_BYTES", MESSAGE_CONTENT_BUDGET_BYTES), MESSAGE_CONTENT_BUDGET_BYTES);
+const MAX_RESPONSE_BYTES = Math.min(positiveIntEnv("RESPONSE_MAX_BYTES", MESSAGE_CONTENT_BUDGET_BYTES), MESSAGE_CONTENT_BUDGET_BYTES);
 const MAX_BASE64_INPUT_CHARS = MESSAGE_CONTENT_BUDGET_BYTES;
 const MAX_BASE64_INPUT_MB = Number.parseFloat((MAX_BASE64_INPUT_CHARS / 4 * 3 / 1048576).toFixed(2));
-const MAX_COMMENT_PAGES = positiveIntEnv("ZENDESK_MAX_COMMENT_PAGES", 10);
-const TICKET_FIELD_SCAN_MAX_PAGES = positiveIntEnv("ZENDESK_TICKET_FIELD_SCAN_MAX_PAGES", 10);
-const REORDER_CONFIRM_THRESHOLD = positiveIntEnv("ZENDESK_REORDER_CONFIRM_THRESHOLD", 20);
+const MAX_COMMENT_PAGES = positiveIntEnv("COMMENT_MAX_PAGES", 10);
+const TICKET_FIELD_SCAN_MAX_PAGES = positiveIntEnv("TICKET_FIELD_SCAN_MAX_PAGES", 10);
+const REORDER_CONFIRM_THRESHOLD = positiveIntEnv("REORDER_CONFIRM_THRESHOLD", 20);
 const getBaseUrl = (subdomain) => `https://${subdomain}.zendesk.com/api/v2`;
 const getHelpCenterBaseUrl = (subdomain) => `https://${subdomain}.zendesk.com/api/v2/help_center`;
 const getOAuthUrls = (subdomain) => ({
@@ -178,7 +227,7 @@ const supportedScopes = (readOnly) => scopeTokens(requestedScope(readOnly));
 * Whether a grant still covers what this process needs: a flat subset test.
 * Coverage, not equality, so a token Zendesk granted wider than requested stays
 * usable. A non-string `granted` is a pre-#283 record, i.e. `read write` — only
-* reachable now through a `ZENDESK_TOKEN_FILE` aimed at one by hand, since the
+* reachable now through a `OAUTH_TOKEN_FILE` aimed at one by hand, since the
 * default layout no longer names those files. No scope hierarchy: granular
 * scopes (#284) replace this.
 */
@@ -207,7 +256,7 @@ const detectWsl = () => {
 * (`docs/decisions/token-file-keying.md`). The `(EADDRINUSE)` marker and `code`
 * are kept for diagnostics/tests.
 */
-const callbackPortInUseError = (port, cause) => Object.assign(/* @__PURE__ */ new Error(`Cannot start the Zendesk OAuth sign-in: local callback port ${port} is already in use. Another instance of this server is most likely signing in right now: finish that browser window, then retry. If an unrelated program holds the port, set ZENDESK_OAUTH_CALLBACK_PORT (or --callback-port) to a free port, then register http://localhost:<port>/callback as a redirect URL in your Zendesk OAuth client. (EADDRINUSE)`), {
+const callbackPortInUseError = (port, cause) => Object.assign(/* @__PURE__ */ new Error(`Cannot start the Zendesk OAuth sign-in: local callback port ${port} is already in use. Another instance of this server is most likely signing in right now: finish that browser window, then retry. If an unrelated program holds the port, set OAUTH_CALLBACK_PORT (or --callback-port) to a free port, then register http://localhost:<port>/callback as a redirect URL in your Zendesk OAuth client. (EADDRINUSE)`), {
 	code: "EADDRINUSE",
 	cause
 });
@@ -500,11 +549,12 @@ const keyDigest = (key) => createHash("sha256").update(JSON.stringify([
 * their own record instead of clobbering a shared file. Why that triple, and
 * why no migration from the old subdomain-only layout:
 * `docs/decisions/token-file-keying.md`.
-* `ZENDESK_TOKEN_FILE` overrides with an explicit path — the way to separate
+* `OAUTH_TOKEN_FILE` overrides with an explicit path — the way to separate
 * two Zendesk accounts that share a subdomain, client and scope.
 */
 const resolveTokenPath = (key) => {
-	const override = process.env["ZENDESK_TOKEN_FILE"];
+	const { name, value: override } = readEnv("OAUTH_TOKEN_FILE");
+	if (override === "") throw new Error(`Empty ${name}. Set it to a value, or unset it entirely.`);
 	if (override) return override;
 	const readable = [
 		key.subdomain,
@@ -828,11 +878,15 @@ const parsePort = (raw, label) => {
 	if (!DIGITS_ONLY.test(raw)) throw new Error(`Invalid ${label} value. Expected an integer 0-65535.`);
 	return Number(raw);
 };
-const parsePortEnv = (raw, label) => raw === void 0 ? void 0 : parsePort(raw, label);
-const requireNonEmptyEnv = (name) => {
-	const raw = process.env[name];
-	if (raw === "") throw new Error(`Empty ${name}. Set it to a value, or unset it entirely.`);
-	return raw;
+const readNonEmptyEnv = (name) => {
+	const env = readEnv(name);
+	if (env.value === "") throw new Error(`Empty ${env.name}. Set it to a value, or unset it entirely.`);
+	return env;
+};
+const requireNonEmptyEnv = (name) => readNonEmptyEnv(name).value;
+const portEnv = (name) => {
+	const env = readNonEmptyEnv(name);
+	return env.value === void 0 ? void 0 : parsePort(env.value, env.name);
 };
 const CLI_OPTIONS = {
 	mode: { type: "string" },
@@ -906,8 +960,8 @@ const resolveTransportSettings = (cli) => {
 	const corsFromEnv = (process.env["CORS_ORIGIN"] ?? "").split(",").map((s) => s.trim()).filter((s) => s.length > 0);
 	return {
 		transport: cli.transport ?? requireNonEmptyEnv("TRANSPORT") ?? "stdio",
-		host: cli.host ?? requireNonEmptyEnv("HOST") ?? "0.0.0.0",
-		port: cli.port ?? parsePortEnv(requireNonEmptyEnv("PORT"), "PORT") ?? 3e3,
+		host: cli.host ?? requireNonEmptyEnv("LISTEN_HOST") ?? "0.0.0.0",
+		port: cli.port ?? portEnv("PORT") ?? 3e3,
 		publicUrl: cli.publicUrl ?? requireNonEmptyEnv("PUBLIC_URL"),
 		corsOrigins: [...cli.corsOrigins ?? [], ...corsFromEnv]
 	};
@@ -918,7 +972,7 @@ const loadConfig = (argv = process.argv.slice(2)) => {
 	const oauthClientId = requireNonEmptyEnv("ZENDESK_OAUTH_CLIENT_ID") ?? `${subdomain}_zendesk`;
 	const mode = cli.tools?.length ? "all" : cli.mode ?? "namespace";
 	const namespaces = cli.namespaces ?? (cli.tools?.length ? [...Namespace.options] : void 0);
-	const callbackPort = cli.callbackPort ?? parsePortEnv(requireNonEmptyEnv("ZENDESK_OAUTH_CALLBACK_PORT"), "ZENDESK_OAUTH_CALLBACK_PORT");
+	const callbackPort = cli.callbackPort ?? portEnv("OAUTH_CALLBACK_PORT");
 	const hcResourceScheme = cli.hcResourceScheme ?? requireNonEmptyEnv("HC_RESOURCE_SCHEME");
 	return ConfigSchema.parse({
 		subdomain,
@@ -2297,7 +2351,7 @@ const localePrefix = (locale) => locale ? `/${locale}` : "";
 const articleListPath = (sectionId, locale) => `${localePrefix(locale)}${sectionId ? `/sections/${sectionId}` : ""}/articles`;
 const sectionListPath = (categoryId, locale) => `${localePrefix(locale)}${categoryId ? `/categories/${categoryId}` : ""}/sections`;
 const scanCostNote = (truncated, pagesScanned, cost) => {
-	if (truncated) return `\n\n_Note: the scan hit its ${ARTICLE_RESOURCES_SCAN_MAX_PAGES}-page cap (${cost}), so promoted articles deeper in the catalog may be missing. This call is costly on this Help Center — avoid repeating it; raise ZENDESK_ARTICLE_RESOURCES_SCAN_MAX_PAGES to widen coverage._`;
+	if (truncated) return `\n\n_Note: the scan hit its ${ARTICLE_RESOURCES_SCAN_MAX_PAGES}-page cap (${cost}), so promoted articles deeper in the catalog may be missing. This call is costly on this Help Center — avoid repeating it; raise ARTICLE_RESOURCES_SCAN_MAX_PAGES to widen coverage._`;
 	if (pagesScanned > 1) return `\n\n_Note: this scan cost ${cost}; this tool performs a fresh scan every call (no caching), so avoid calling it again right away._`;
 	return "";
 };
@@ -2522,7 +2576,7 @@ const createHelpCenterTools = (ctx) => {
 			namespace: "help_center",
 			readOnly: true,
 			title: "List Promoted Help Center Articles",
-			description: "List the promoted (\"featured\") Help Center articles — the small, editorially-curated set surfaced at the top of their sections. Returns metadata only (no body); use get_article for full content. COST: the Help Center API has no server-side promoted filter, so this scans article pages (one Zendesk API request per page, up to ZENDESK_ARTICLE_RESOURCES_SCAN_MAX_PAGES, default 20) and filters client-side — potentially costly on a large Help Center. Each call performs a fresh, uncached scan, so avoid calling it repeatedly. On a very large Help Center some promoted articles may be omitted, and both the omission and the number of pages scanned are flagged in the output. Lists the default locale. To promote or unpromote an article, use update_article with `promoted` (requires Help Center admin / Guide admin rights).",
+			description: "List the promoted (\"featured\") Help Center articles — the small, editorially-curated set surfaced at the top of their sections. Returns metadata only (no body); use get_article for full content. COST: the Help Center API has no server-side promoted filter, so this scans article pages (one Zendesk API request per page, up to ARTICLE_RESOURCES_SCAN_MAX_PAGES, default 20) and filters client-side — potentially costly on a large Help Center. Each call performs a fresh, uncached scan, so avoid calling it repeatedly. On a very large Help Center some promoted articles may be omitted, and both the omission and the number of pages scanned are flagged in the output. Lists the default locale. To promote or unpromote an article, use update_article with `promoted` (requires Help Center admin / Guide admin rights).",
 			inputSchema: z.object({}),
 			annotations: {
 				readOnlyHint: true,
@@ -2900,7 +2954,7 @@ const createHelpCenterTools = (ctx) => {
 				]).describe("Where to move the article relative to its section siblings: \"top\" (becomes first), \"bottom\" (becomes last), or \"before\"/\"after\" a specific reference article. \"before\" and \"after\" require reference_article_id."),
 				reference_article_id: z.number().int().optional().describe("The sibling article to position next to when target is \"before\" or \"after\" (numeric id from list_articles). Must belong to the same section and differ from article_id; leave it unset for \"top\" or \"bottom\"."),
 				normalize: z.boolean().default(false).describe("When true, also renumber every article in the section to contiguous positions (0, 1, 2, …) so the stored positions stay tidy. Defaults to false, which writes the fewest positions possible and lets gaps remain. Either way the confirmation threshold still applies."),
-				confirm: z.boolean().default(false).describe("Safety guard for large reorders. When the move would rewrite more article positions than the configured threshold (ZENDESK_REORDER_CONFIRM_THRESHOLD, default 20), the tool refuses and reports the count until you pass true here. Has no effect on small reorders.")
+				confirm: z.boolean().default(false).describe("Safety guard for large reorders. When the move would rewrite more article positions than the configured threshold (REORDER_CONFIRM_THRESHOLD, default 20), the tool refuses and reports the count until you pass true here. Has no effect on small reorders.")
 			}),
 			annotations: {
 				readOnlyHint: false,
@@ -3383,7 +3437,7 @@ const END_USER_FORM_PARAMS = {
 * form invisible or a required field unenforced, and the caller then gets a
 * confidently wrong "no such form" or an opaque Zendesk 422.
 */
-const fetchAllPages = async ({ subdomain, token, tool, path, extract, params = {}, maxPages = TICKET_FIELD_SCAN_MAX_PAGES, capEnvVar = "ZENDESK_TICKET_FIELD_SCAN_MAX_PAGES", onPage, forbiddenHint }) => {
+const fetchAllPages = async ({ subdomain, token, tool, path, extract, params = {}, maxPages = TICKET_FIELD_SCAN_MAX_PAGES, capEnvVar = "TICKET_FIELD_SCAN_MAX_PAGES", onPage, forbiddenHint }) => {
 	const items = [];
 	let page = 1;
 	while (true) {
@@ -3440,7 +3494,7 @@ const fetchAllRequestComments = async (subdomain, token, requestId) => {
 			extract: (response) => response.comments,
 			params: { include: "users" },
 			maxPages: MAX_COMMENT_PAGES,
-			capEnvVar: "ZENDESK_MAX_COMMENT_PAGES",
+			capEnvVar: "COMMENT_MAX_PAGES",
 			forbiddenHint: OTHER_USERS_REQUEST_HINT,
 			onPage: (response) => {
 				for (const user of response.users ?? []) authors.set(user.id, user);
@@ -5116,10 +5170,10 @@ const registerProxyTool = (server, toolName, title, tools, readOnlyMode, onUnaut
 	return server.registerTool(toolName, {
 		title,
 		description: `${prefix}${title}. Specify the operation and its parameters.\n\nAvailable operations:\n${operationList}`,
-		inputSchema: {
+		inputSchema: z.object({
 			operation: z.string().describe(`One of: ${operationNames.join(", ")}`),
 			params: z.record(z.string(), z.unknown()).default({}).describe("Operation parameters")
-		},
+		}),
 		annotations
 	}, async (args) => dispatch(args));
 };
@@ -5738,7 +5792,7 @@ const startHttpTransport = async (config, logger = silentLogger, options = {}) =
 		}
 		const auth = { bearer };
 		const server = createMcpServer(config, () => auth.bearer, logger);
-		const transport = new StreamableHTTPServerTransport({
+		const transport = new NodeStreamableHTTPServerTransport({
 			sessionIdGenerator: () => randomUUID(),
 			onsessioninitialized: (newId) => {
 				sessions.set(newId, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fruggr/zendesk-mcp-server",
-  "version": "2.23.0",
+  "version": "2.24.0",
   "mcpName": "io.github.fruggr/zendesk-mcp-server",
   "description": "Deep Zendesk MCP server for your AI assistant: search, draft, update and translate Help Center articles and manage Support tickets end to end — comments, triage and image attachments.",
   "type": "module",
@@ -70,9 +70,10 @@
   "engines": {
     "node": ">=20"
   },
-  "packageManager": "pnpm@12.4.2+sha512.08adc6613180275c7c9edada39dcf08c9c61ad4e7eaf330a4f3461f102b0f907423454d117f98e72d47fef0616070644d7bffc973a6a57f5090a6d7c368b07c9",
+  "packageManager": "pnpm@12.5.1+sha512.e3f305bc784a2bc89f5ad3b6138889470fae8d2af5f36b61216ec91c2c3d64089775f9de38aac331044ea40f245cb0d5666392dfdf65824e1907ef6a2c62de5f",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.30.0",
+    "@modelcontextprotocol/node": "2.0.0",
+    "@modelcontextprotocol/server": "2.0.0",
     "cheerio": "1.2.0",
     "hast-util-to-html": "9.0.5",
     "hast-util-to-mdast": "10.1.2",
@@ -90,6 +91,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.13",
+    "@modelcontextprotocol/client": "2.0.0",
     "@semantic-release/changelog": "^7.0.0",
     "@semantic-release/exec": "^7.1.0",
     "@semantic-release/git": "^11.0.0",