@fruggr/zendesk-mcp-server 1.7.0 → 1.9.0

package/dist/index.js

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
-import { createHash, randomBytes } from "node:crypto";
-import { readFileSync } from "node:fs";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { createServer } from "node:http";
-import { release } from "node:os";
+import { homedir, release } from "node:os";
 import open from "open";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import * as z from "zod/v4";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as cheerio from "cheerio";
@@ -17,8 +19,7 @@ import remarkParse from "remark-parse";
 import remarkRehype from "remark-rehype";
 import remarkStringify from "remark-stringify";
 import { unified } from "unified";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 //#region src/auth/api-token.ts
 /**
@@ -126,7 +127,6 @@ const getOAuthUrls = (subdomain) => ({
 });
 //#endregion
 //#region src/auth/browser-oauth.ts
-const DEFAULT_CALLBACK_PORT = 3e3;
 const AUTH_TIMEOUT_MS = 300 * 1e3;
 /** Best-effort WSL detection: WSL kernels carry "microsoft" in /proc/version. */
 const detectWsl = () => {
@@ -138,6 +138,16 @@ const detectWsl = () => {
 	}
 };
 /**
+* Build an actionable error for a callback port that's already taken. The raw
+* Node `EADDRINUSE` is opaque to both the user and the LLM; this spells out the
+* fix (set a free port + register the matching redirect URL in Zendesk). 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 by another process. 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)`), {
+	code: "EADDRINUSE",
+	cause
+});
+/**
 * Escape a string for safe interpolation into HTML text/attribute context.
 * The local callback server echoes attacker-controllable values (the OAuth
 * `error_description` query param, token-exchange error bodies) back into the
@@ -233,12 +243,18 @@ const startBrowserAuth = (config, logger = silentLogger) => {
 				rejectToken(err);
 			}
 		});
+		const requestedPort = config.callbackPort ?? 27439;
 		const onStartError = (err) => {
 			clearTimeout(authTimeout);
-			rejectStarted(err);
+			const code = err.code;
+			logger.error("oauth_callback_listen_failed", {
+				port: requestedPort,
+				errorCode: code
+			});
+			rejectStarted(code === "EADDRINUSE" ? callbackPortInUseError(requestedPort, err) : err);
 		};
 		callbackServer.once("error", onStartError);
-		callbackServer.listen(config.callbackPort ?? DEFAULT_CALLBACK_PORT, () => {
+		callbackServer.listen(requestedPort, () => {
 			callbackServer.off("error", onStartError);
 			callbackServer.once("error", (err) => {
 				clearTimeout(authTimeout);
@@ -292,34 +308,199 @@ const startBrowserAuth = (config, logger = silentLogger) => {
 		});
 	});
 };
+/**
+* Exchange a refresh token for a fresh access token (and a rotated refresh token)
+* without any browser interaction. Public PKCE clients send no `client_secret`.
+* Zendesk refresh tokens are single-use: the caller MUST persist the new
+* `refresh_token` from the response. Throws on a non-2xx (expired/invalid
+* refresh token) so the caller can fall back to the full browser flow.
+*/
+const refreshAccessToken = async (config, logger = silentLogger) => {
+	const { tokenUrl } = getOAuthUrls(config.subdomain);
+	const body = new URLSearchParams({
+		grant_type: "refresh_token",
+		refresh_token: config.refreshToken,
+		client_id: config.oauthClientId
+	});
+	const response = await fetch(tokenUrl, {
+		method: "POST",
+		headers: { "Content-Type": "application/x-www-form-urlencoded" },
+		body: body.toString()
+	});
+	logger.debug("oauth_token_refresh", { status: response.status });
+	if (!response.ok) {
+		const errorBody = await response.text();
+		throw new Error(`Token refresh failed (${response.status}): ${errorBody}`);
+	}
+	const tokenData = await response.json();
+	logger.info("oauth_token_refreshed");
+	return tokenData;
+};
+//#endregion
+//#region src/utils/package-info.ts
+const FALLBACK = {
+	name: "@fruggr/zendesk-mcp-server",
+	version: "0.0.0"
+};
+/**
+* Read `name`/`version` from the package's own package.json at runtime instead
+* of hardcoding them. Walks up from this module to the nearest package.json,
+* which resolves correctly both when bundled (`dist/index.js` → repo root) and
+* from source/tests (`src/` has no package.json, so the root is found). Reading
+* at runtime (not inlining at build) matters because semantic-release bumps the
+* version into package.json before publishing, after the build step.
+*/
+let cached;
+const readPackageInfo = () => {
+	if (cached) return cached;
+	let dir = dirname(fileURLToPath(import.meta.url));
+	for (let depth = 0; depth < 8; depth++) {
+		try {
+			const raw = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+			if (raw && typeof raw === "object") {
+				const pkg = raw;
+				if (typeof pkg.name === "string" && typeof pkg.version === "string") {
+					cached = {
+						name: pkg.name,
+						version: pkg.version
+					};
+					return cached;
+				}
+			}
+		} catch {}
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	cached = FALLBACK;
+	return cached;
+};
+//#endregion
+//#region src/auth/token-persistence.ts
+const isWindows = process.platform === "win32";
+/**
+* Config-dir segments derived from the *scoped* package name
+* (`@fruggr/zendesk-mcp-server` → `fruggr` + `zendesk-mcp-server`) so the path is
+* vendor-namespaced and can't collide with another `zendesk-mcp-server`.
+*/
+const appDirSegments = () => {
+	const { name } = readPackageInfo();
+	const scoped = /^@([^/]+)\/(.+)$/.exec(name);
+	return scoped?.[1] && scoped[2] ? [scoped[1], scoped[2]] : [name];
+};
+const configDir = () => {
+	const segments = appDirSegments();
+	if (isWindows) return join(process.env["APPDATA"] ?? join(homedir(), "AppData", "Roaming"), ...segments);
+	return join(process.env["XDG_CONFIG_HOME"] ?? join(homedir(), ".config"), ...segments);
+};
+const safeName = (subdomain) => subdomain.replace(/[^a-z0-9-]/gi, "_");
+/**
+* Path to the token file for a subdomain. Each subdomain gets its **own** file
+* (`<subdomain>.json`, a single record) so concurrent processes for different
+* subdomains never read-modify-write a shared file — no merge, no clobber.
+* `ZENDESK_TOKEN_FILE` overrides with an explicit path (a single file; use the
+* default layout for multi-subdomain installs).
+*/
+const resolveTokenPath = (subdomain) => {
+	const override = process.env["ZENDESK_TOKEN_FILE"];
+	if (override) return override;
+	return join(configDir(), `${safeName(subdomain)}.json`);
+};
+const writeFileAtomic = (path, record) => {
+	const dir = dirname(path);
+	mkdirSync(dir, { recursive: true });
+	const tmp = `${path}.${process.pid}.tmp`;
+	writeFileSync(tmp, JSON.stringify(record, null, 2), "utf8");
+	if (!isWindows) chmodSync(tmp, 384);
+	renameSync(tmp, path);
+	if (!isWindows) try {
+		chmodSync(dir, 448);
+	} catch {}
+};
+const loadToken = (path) => {
+	try {
+		const raw = JSON.parse(readFileSync(path, "utf8"));
+		if (raw && typeof raw === "object" && typeof raw.accessToken === "string") return raw;
+	} catch {}
+};
+const saveToken = (path, record, logger = silentLogger) => {
+	try {
+		writeFileAtomic(path, record);
+		logger.debug("token_persisted");
+	} catch (err) {
+		logger.warn("token_persist_failed", { error: err instanceof Error ? err.message : String(err) });
+	}
+};
+const clearToken = (path, logger = silentLogger) => {
+	try {
+		rmSync(path, { force: true });
+		logger.debug("token_cleared");
+	} catch (err) {
+		logger.warn("token_clear_failed", { error: err instanceof Error ? err.message : String(err) });
+	}
+};
 //#endregion
 //#region src/auth/token-store.ts
+const EXPIRY_SKEW_MS = 6e4;
 const createAuthRequiredError = (authorizeUrl) => Object.assign(/* @__PURE__ */ new Error("Zendesk authentication required. A browser window should have opened for you to sign in. If it did not, open this URL in your browser, then retry your request:\n" + authorizeUrl), {
 	name: "AuthRequiredError",
 	authorizeUrl
 });
+const expiryFrom = (expiresIn) => typeof expiresIn === "number" ? Date.now() + expiresIn * 1e3 : void 0;
 const createTokenStore = (config, logger = silentLogger) => {
-	let token;
+	const tokenPath = resolveTokenPath(config.subdomain);
+	let token = loadToken(tokenPath);
+	if (token) logger.debug("oauth_token_loaded_from_disk");
 	let authorizeUrl;
 	let starting;
+	let refreshing;
+	const persist = (t) => saveToken(tokenPath, t, logger);
 	const setToken = (accessToken, refreshToken) => {
 		token = {
 			accessToken,
 			refreshToken
 		};
+		persist(token);
+	};
+	const isExpired = (t) => typeof t.expiresAt === "number" && Date.now() >= t.expiresAt - EXPIRY_SKEW_MS;
+	const tryRefresh = async (current) => {
+		if (!current.refreshToken) return void 0;
+		try {
+			const result = await refreshAccessToken({
+				subdomain: config.subdomain,
+				oauthClientId: config.oauthClientId,
+				refreshToken: current.refreshToken
+			}, logger);
+			token = {
+				accessToken: result.access_token,
+				refreshToken: result.refresh_token ?? current.refreshToken,
+				expiresAt: expiryFrom(result.expires_in)
+			};
+			persist(token);
+			logger.info("oauth_token_refreshed_cached");
+			return token.accessToken;
+		} catch (err) {
+			logger.warn("oauth_token_refresh_failed", { error: err instanceof Error ? err.message : String(err) });
+			token = void 0;
+			clearToken(tokenPath, logger);
+			return;
+		}
 	};
 	const beginAuth = () => {
 		logger.info("oauth_auth_start");
 		return startBrowserAuth({
 			subdomain: config.subdomain,
-			oauthClientId: config.oauthClientId
+			oauthClientId: config.oauthClientId,
+			callbackPort: config.callbackPort
 		}, logger).then((started) => {
 			authorizeUrl = started.authorizeUrl;
 			started.tokenPromise.then((result) => {
 				token = {
 					accessToken: result.access_token,
-					refreshToken: result.refresh_token
+					refreshToken: result.refresh_token,
+					expiresAt: expiryFrom(result.expires_in)
 				};
+				persist(token);
 				logger.info("oauth_token_cached");
 			}).catch((err) => {
 				logger.warn("oauth_auth_failed", { error: err instanceof Error ? err.message : String(err) });
@@ -334,16 +515,38 @@ const createTokenStore = (config, logger = silentLogger) => {
 		});
 	};
 	const getToken = async () => {
-		if (token) {
+		if (token && !isExpired(token)) {
 			logger.debug("oauth_token_cache_hit");
 			return token.accessToken;
 		}
+		if (token?.refreshToken) {
+			if (!refreshing) refreshing = tryRefresh(token).finally(() => {
+				refreshing = void 0;
+			});
+			const refreshed = await refreshing;
+			if (refreshed) return refreshed;
+		}
 		if (!starting) starting = beginAuth();
 		throw createAuthRequiredError(authorizeUrl ?? await starting);
 	};
+	const invalidate = () => {
+		if (token?.refreshToken) {
+			token = {
+				accessToken: token.accessToken,
+				refreshToken: token.refreshToken,
+				expiresAt: 0
+			};
+			persist(token);
+		} else {
+			token = void 0;
+			clearToken(tokenPath, logger);
+		}
+		logger.info("oauth_token_invalidated");
+	};
 	return {
 		getToken,
-		setToken
+		setToken,
+		invalidate
 	};
 };
 //#endregion
@@ -364,6 +567,7 @@ const Namespace = z.enum([
 	"help_center",
 	"users"
 ]);
+const Transport = z.enum(["stdio", "http"]);
 const ConfigSchema = z.object({
 	subdomain: z.string().min(1, "ZENDESK_SUBDOMAIN is required"),
 	oauthClientId: z.string().min(1),
@@ -373,8 +577,26 @@ const ConfigSchema = z.object({
 	mode: ToolMode,
 	readOnly: z.boolean(),
 	namespaces: z.array(Namespace).optional(),
-	tools: z.array(z.string()).optional()
+	tools: z.array(z.string()).optional(),
+	transport: Transport,
+	host: z.string().min(1),
+	port: z.number().int().min(0).max(65535),
+	publicUrl: z.string().url().optional(),
+	/**
+	* Additional browser origins allowed by CORS in HTTP mode. The default
+	* allowlist (the major web MCP clients + localhost-any-port for dev) is
+	* always applied; this list extends it. Native MCP clients (Claude
+	* Desktop, Claude Code CLI, Cursor, VS Code, Zed…) are unaffected
+	* because they send no Origin header.
+	*/
+	corsOrigins: z.array(z.string().url().transform((value) => new URL(value).origin).refine((origin) => origin !== "null", { message: "CORS origin must be an http(s) URL with a host" })).default([]),
+	callbackPort: z.number().int().min(1).max(65535).optional()
 });
+const parsePort = (raw, label) => {
+	if (!/^\d+$/.test(raw)) throw new Error(`Invalid ${label} value. Expected an integer 0-65535.`);
+	return Number(raw);
+};
+const parsePortEnv = (raw, label) => raw === void 0 || raw === "" ? void 0 : parsePort(raw, label);
 const parseCliArgs = (args) => {
 	const result = {};
 	let positionalIndex = 0;
@@ -397,6 +619,25 @@ const parseCliArgs = (args) => {
 		} else if (arg === "--log-level" && next) {
 			result.logLevel = next;
 			i++;
+		} else if (arg === "--transport" && next) {
+			result.transport = next;
+			i++;
+		} else if (arg === "--host" && next) {
+			result.host = next;
+			i++;
+		} else if (arg === "--port" && next) {
+			result.port = parsePort(next, "--port");
+			i++;
+		} else if (arg === "--public-url" && next) {
+			result.publicUrl = next;
+			i++;
+		} else if (arg === "--cors-origin" && next) {
+			result.corsOrigins = result.corsOrigins ?? [];
+			result.corsOrigins.push(next);
+			i++;
+		} else if (arg === "--callback-port" && next) {
+			result.callbackPort = parsePort(next, "--callback-port");
+			i++;
 		} else if (!arg.startsWith("-") && positionalIndex === 0) {
 			result.subdomain = arg;
 			positionalIndex++;
@@ -409,36 +650,35 @@ const loadConfig = (argv = process.argv.slice(2)) => {
 	const subdomain = cli.subdomain ?? process.env["ZENDESK_SUBDOMAIN"] ?? "";
 	const oauthClientId = process.env["ZENDESK_OAUTH_CLIENT_ID"] ?? (subdomain ? `${subdomain}_zendesk` : "");
 	const mode = cli.tools?.length ? "all" : cli.mode ?? "namespace";
+	const transport = cli.transport ?? process.env["TRANSPORT"] ?? "stdio";
+	const host = cli.host ?? process.env["HOST"] ?? "0.0.0.0";
+	const port = cli.port ?? parsePortEnv(process.env["PORT"], "PORT") ?? 3e3;
+	const publicUrl = cli.publicUrl ?? process.env["PUBLIC_URL"];
+	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 zendeskEmail = process.env["ZENDESK_EMAIL"];
+	const zendeskApiToken = process.env["ZENDESK_API_TOKEN"];
+	if (transport === "http" && zendeskEmail && zendeskApiToken) throw new Error("API token authentication (ZENDESK_EMAIL + ZENDESK_API_TOKEN) is not supported in HTTP mode. HTTP mode requires per-user OAuth 2.1 PKCE - unset these variables and configure your MCP client to perform the OAuth flow against Zendesk.");
 	return ConfigSchema.parse({
 		subdomain,
 		oauthClientId,
-		zendeskEmail: process.env["ZENDESK_EMAIL"],
-		zendeskApiToken: process.env["ZENDESK_API_TOKEN"],
+		zendeskEmail,
+		zendeskApiToken,
 		logLevel: cli.logLevel ?? process.env["LOG_LEVEL"] ?? "info",
 		mode,
 		readOnly: cli.readOnly ?? false,
 		namespaces: cli.namespaces,
-		tools: cli.tools
+		tools: cli.tools,
+		transport,
+		host,
+		port,
+		publicUrl,
+		corsOrigins,
+		callbackPort
 	});
 };
 //#endregion
-//#region src/routing/registry.ts
-const filterTools = (allTools, options) => allTools.filter((tool) => {
-	if (options.readOnly && !tool.readOnly) return false;
-	if (options.namespaces?.length && !options.namespaces.includes(tool.namespace)) return false;
-	if (options.tools?.length && !options.tools.includes(tool.name)) return false;
-	return true;
-});
-const groupByNamespace = (tools) => {
-	const grouped = /* @__PURE__ */ new Map();
-	for (const tool of tools) {
-		const existing = grouped.get(tool.namespace) ?? [];
-		existing.push(tool);
-		grouped.set(tool.namespace, existing);
-	}
-	return grouped;
-};
-//#endregion
 //#region src/client/zendesk-api.ts
 var ZendeskApiError = class ZendeskApiError extends Error {
 	status;
@@ -548,6 +788,23 @@ const helpCenterUpload = async (subdomain, token, path, formData) => {
 	return response.json();
 };
 //#endregion
+//#region src/routing/registry.ts
+const filterTools = (allTools, options) => allTools.filter((tool) => {
+	if (options.readOnly && !tool.readOnly) return false;
+	if (options.namespaces?.length && !options.namespaces.includes(tool.namespace)) return false;
+	if (options.tools?.length && !options.tools.includes(tool.name)) return false;
+	return true;
+});
+const groupByNamespace = (tools) => {
+	const grouped = /* @__PURE__ */ new Map();
+	for (const tool of tools) {
+		const existing = grouped.get(tool.namespace) ?? [];
+		existing.push(tool);
+		grouped.set(tool.namespace, existing);
+	}
+	return grouped;
+};
+//#endregion
 //#region src/utils/article-sections.ts
 const HEADING_LEVELS = new Set([
 	"h1",
@@ -1981,46 +2238,21 @@ const createAllTools = (ctx) => [
 	...createUserTools(ctx)
 ];
 //#endregion
-//#region src/utils/package-info.ts
-const FALLBACK = {
-	name: "@fruggr/zendesk-mcp-server",
-	version: "0.0.0"
-};
+//#region src/server.ts
 /**
-* Read `name`/`version` from the package's own package.json at runtime instead
-* of hardcoding them. Walks up from this module to the nearest package.json,
-* which resolves correctly both when bundled (`dist/index.js` → repo root) and
-* from source/tests (`src/` has no package.json, so the root is found). Reading
-* at runtime (not inlining at build) matters because semantic-release bumps the
-* version into package.json before publishing, after the build step.
+* Invoke a tool handler, notifying `onUnauthorized` when Zendesk rejects the
+* token (401). This lets the OAuth store drop the dead token so the next call
+* refreshes/re-authenticates instead of replaying a revoked token. A no-op
+* callback (API-token mode) leaves behavior unchanged.
 */
-let cached;
-const readPackageInfo = () => {
-	if (cached) return cached;
-	let dir = dirname(fileURLToPath(import.meta.url));
-	for (let depth = 0; depth < 8; depth++) {
-		try {
-			const raw = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
-			if (raw && typeof raw === "object") {
-				const pkg = raw;
-				if (typeof pkg.name === "string" && typeof pkg.version === "string") {
-					cached = {
-						name: pkg.name,
-						version: pkg.version
-					};
-					return cached;
-				}
-			}
-		} catch {}
-		const parent = dirname(dir);
-		if (parent === dir) break;
-		dir = parent;
+const runHandler = async (def, params, onUnauthorized) => {
+	try {
+		return await def.handler(params);
+	} catch (err) {
+		if (onUnauthorized && err instanceof ZendeskApiError && err.status === 401) onUnauthorized();
+		throw err;
 	}
-	cached = FALLBACK;
-	return cached;
 };
-//#endregion
-//#region src/server.ts
 const NAMESPACE_LABELS = {
 	tickets: {
 		toolName: "zendesk_tickets",
@@ -2047,30 +2279,36 @@ const aggregateAnnotations = (tools) => ({
 	idempotentHint: tools.every((t) => t.annotations.idempotentHint),
 	openWorldHint: true
 });
-const registerProxyTool = (server, toolName, title, tools, handlerMap, readOnlyMode) => {
+const buildProxyDispatch = (tools, onUnauthorized) => {
+	const operationNames = tools.map((t) => t.name);
+	const localHandlers = new Map(tools.map((t) => [t.name, t]));
+	return async (args) => {
+		const { operation, params } = args;
+		const def = localHandlers.get(operation);
+		if (!def) return { content: [{
+			type: "text",
+			text: `Unknown operation "${operation}". Available: ${operationNames.join(", ")}`
+		}] };
+		return runHandler(def, def.inputSchema.parse(params), onUnauthorized);
+	};
+};
+const registerProxyTool = (server, toolName, title, tools, readOnlyMode, onUnauthorized) => {
 	const operationNames = tools.map((t) => t.name);
 	const operationList = buildOperationList(tools);
 	const annotations = aggregateAnnotations(tools);
 	const prefix = readOnlyMode ? "[RO] " : "";
+	const dispatch = buildProxyDispatch(tools, onUnauthorized);
 	server.registerTool(toolName, {
 		title,
 		description: `${prefix}${title}. Specify the operation and its parameters.\n\nAvailable operations:\n${operationList}`,
-		inputSchema: z.object({
+		inputSchema: {
 			operation: z.string().describe(`One of: ${operationNames.join(", ")}`),
 			params: z.record(z.string(), z.unknown()).default({}).describe("Operation parameters")
-		}),
+		},
 		annotations
-	}, async ({ operation, params }) => {
-		const def = handlerMap.get(operation);
-		if (!def) return { content: [{
-			type: "text",
-			text: `Unknown operation "${operation}". Available: ${operationNames.join(", ")}`
-		}] };
-		const validated = def.inputSchema.parse(params);
-		return def.handler(validated);
-	});
+	}, async (args) => dispatch(args));
 };
-const createMcpServer = (config, getToken, logger = silentLogger) => {
+const createMcpServer = (config, getToken, logger = silentLogger, onUnauthorized) => {
 	const pkg = readPackageInfo();
 	const server = new McpServer({
 		name: pkg.name,
@@ -2085,27 +2323,25 @@ const createMcpServer = (config, getToken, logger = silentLogger) => {
 		namespaces: config.namespaces,
 		tools: config.tools
 	});
-	const handlerMap = /* @__PURE__ */ new Map();
-	for (const tool of filteredTools) handlerMap.set(tool.name, tool);
 	switch (config.mode) {
 		case "all":
 			for (const tool of filteredTools) server.registerTool(tool.name, {
 				title: tool.title,
 				description: tool.description,
-				inputSchema: tool.inputSchema,
+				inputSchema: tool.inputSchema.shape,
 				annotations: tool.annotations
-			}, async (params) => tool.handler(params));
+			}, async (params) => runHandler(tool, params, onUnauthorized));
 			break;
 		case "namespace": {
 			const grouped = groupByNamespace(filteredTools);
 			for (const [namespace, tools] of grouped) {
 				const label = NAMESPACE_LABELS[namespace];
-				if (label) registerProxyTool(server, label.toolName, label.title, tools, handlerMap, config.readOnly);
+				if (label) registerProxyTool(server, label.toolName, label.title, tools, config.readOnly, onUnauthorized);
 			}
 			break;
 		}
 		case "single":
-			registerProxyTool(server, "zendesk", "Zendesk", filteredTools, handlerMap, config.readOnly);
+			registerProxyTool(server, "zendesk", "Zendesk", filteredTools, config.readOnly, onUnauthorized);
 			break;
 	}
 	logger.info("tools_registered", {
@@ -2115,6 +2351,350 @@ const createMcpServer = (config, getToken, logger = silentLogger) => {
 	return server;
 };
 //#endregion
+//#region src/transports/http.ts
+const WILDCARD_HOSTS = new Set([
+	"0.0.0.0",
+	"::",
+	"*"
+]);
+const DEFAULT_BROWSER_MCP_CLIENT_ORIGINS = [
+	"https://chatgpt.com",
+	"https://chat.openai.com",
+	"https://claude.ai",
+	"https://gemini.google.com",
+	"https://copilot.microsoft.com",
+	"https://www.perplexity.ai",
+	"https://chat.mistral.ai",
+	"https://grok.com"
+];
+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([
+	"localhost",
+	"127.0.0.1",
+	"[::1]"
+]);
+const ALLOWED_PROTOCOLS = new Set(["http:", "https:"]);
+/**
+* Returns the origin string to reflect in `Access-Control-Allow-Origin`, or
+* `undefined` if the origin is not allowed.
+*
+* The returned value is **never the raw `Origin` request header**. It comes
+* from one of three sanitization points:
+*
+*   1. An entry of the hardcoded `DEFAULT_BROWSER_MCP_CLIENT_ORIGINS` array.
+*   2. An entry of the operator-configured `extraOrigins` array.
+*   3. A loopback origin rebuilt from validated URL components after the
+*      hostname has been allowlisted against `LOCALHOST_HOSTNAMES`.
+*
+* This shape keeps the dataflow from request header to response header
+* gated by a constant allowlist, which is the pattern CodeQL's
+* `js/cors-misconfiguration-for-credentials` rule recognises as safe when
+* combined with `Access-Control-Allow-Credentials: true`.
+*/
+const resolveAllowedOrigin = (origin, extraOrigins) => {
+	const defaultMatch = DEFAULT_BROWSER_MCP_CLIENT_ORIGINS.find((entry) => entry === origin);
+	if (defaultMatch) return defaultMatch;
+	const extraMatch = extraOrigins?.find((entry) => entry === origin);
+	if (extraMatch) return extraMatch;
+	try {
+		const url = new URL(origin);
+		if (!ALLOWED_PROTOCOLS.has(url.protocol)) return void 0;
+		if (!LOCALHOST_HOSTNAMES.has(url.hostname)) return void 0;
+		const port = url.port || (url.protocol === "https:" ? "443" : "80");
+		return `${url.protocol}//${url.hostname}:${port}`;
+	} catch {
+		return;
+	}
+};
+const applyCorsHeaders = (req, res, extraOrigins) => {
+	const requestOrigin = req.headers["origin"];
+	if (typeof requestOrigin !== "string" || requestOrigin.length === 0) return;
+	const allowedOrigin = resolveAllowedOrigin(requestOrigin, extraOrigins);
+	if (!allowedOrigin) return;
+	res.setHeader("Access-Control-Allow-Origin", allowedOrigin);
+	res.setHeader("Vary", "Origin");
+	res.setHeader("Access-Control-Allow-Credentials", "true");
+	res.setHeader("Access-Control-Expose-Headers", CORS_EXPOSE_HEADERS);
+};
+const handleCorsPreflight = (req, res, extraOrigins) => {
+	if (req.method !== "OPTIONS") return false;
+	applyCorsHeaders(req, res, extraOrigins);
+	if (res.getHeader("Access-Control-Allow-Origin")) {
+		res.setHeader("Access-Control-Allow-Methods", CORS_ALLOWED_METHODS);
+		res.setHeader("Access-Control-Allow-Headers", CORS_ALLOWED_HEADERS);
+		res.setHeader("Access-Control-Max-Age", CORS_MAX_AGE);
+	}
+	res.writeHead(204);
+	res.end();
+	return true;
+};
+const resolveResourceUrl = (config, logger = silentLogger) => {
+	if (config.publicUrl) return config.publicUrl.replace(/\/+$/, "");
+	if (!WILDCARD_HOSTS.has(config.host)) return `http://${config.host}:${config.port}`;
+	logger.warn("public_url_unset", {
+		host: config.host,
+		advertised: `http://${config.host}:${config.port}`,
+		hint: "OAuth discovery will advertise a non-routable resource identifier and spec-compliant MCP clients may refuse the connection. Set PUBLIC_URL (or --public-url) to the URL clients use to reach this server (e.g. https://your-host.example.com)."
+	});
+	return `http://${config.host}:${config.port}`;
+};
+const MISSING_BEARER_MESSAGE = "Missing Authorization: Bearer <zendesk-oauth-token> header. HTTP mode requires per-user OAuth 2.1 PKCE - obtain a token from Zendesk via your MCP client.";
+const extractBearer = (request) => {
+	const header = request.headers["authorization"];
+	if (typeof header !== "string") return void 0;
+	if (!header.toLowerCase().startsWith("bearer ")) return void 0;
+	return header.slice(7).trim();
+};
+const buildOAuthMetadata = (config, logger = silentLogger) => {
+	const { authorizeUrl, tokenUrl } = getOAuthUrls(config.subdomain);
+	const issuer = `https://${config.subdomain}.zendesk.com`;
+	const resource = resolveResourceUrl(config, logger);
+	return {
+		protectedResource: {
+			authorization_servers: [issuer],
+			resource,
+			bearer_methods_supported: ["header"],
+			scopes_supported: ["read", "write"]
+		},
+		authorizationServer: {
+			issuer,
+			authorization_endpoint: authorizeUrl,
+			token_endpoint: tokenUrl,
+			response_types_supported: ["code"],
+			grant_types_supported: ["authorization_code", "refresh_token"],
+			code_challenge_methods_supported: ["S256"],
+			token_endpoint_auth_methods_supported: ["none"],
+			scopes_supported: ["read", "write"]
+		}
+	};
+};
+const sendJson = (res, status, body) => {
+	res.writeHead(status, { "Content-Type": "application/json" });
+	res.end(JSON.stringify(body));
+};
+const sendJsonRpcError = (res, status, code, message, headers = {}) => {
+	res.writeHead(status, {
+		"Content-Type": "application/json",
+		...headers
+	});
+	res.end(JSON.stringify({
+		error: {
+			code,
+			message
+		},
+		id: null,
+		jsonrpc: "2.0"
+	}));
+};
+const sendUnauthorized = (res, resource) => {
+	sendJsonRpcError(res, 401, -32e3, MISSING_BEARER_MESSAGE, { "WWW-Authenticate": `Bearer resource_metadata="${resource}/.well-known/oauth-protected-resource", error="invalid_token", error_description="${MISSING_BEARER_MESSAGE}"` });
+};
+const readJsonBody = (req, maxBodyBytes) => new Promise((resolve) => {
+	const chunks = [];
+	let total = 0;
+	let settled = false;
+	const settle = (result) => {
+		if (settled) return;
+		settled = true;
+		resolve(result);
+	};
+	req.on("data", (chunk) => {
+		total += chunk.length;
+		if (total > maxBodyBytes) {
+			req.removeAllListeners("data");
+			settle({
+				ok: false,
+				status: 413,
+				rpcCode: -32600,
+				message: `Request body exceeds ${maxBodyBytes} bytes.`
+			});
+			return;
+		}
+		chunks.push(chunk);
+	});
+	req.on("end", () => {
+		const raw = Buffer.concat(chunks).toString("utf8");
+		if (!raw) {
+			settle({
+				ok: true,
+				value: void 0
+			});
+			return;
+		}
+		try {
+			settle({
+				ok: true,
+				value: JSON.parse(raw)
+			});
+		} catch {
+			settle({
+				ok: false,
+				status: 400,
+				rpcCode: -32700,
+				message: "Parse error: request body is not valid JSON."
+			});
+		}
+	});
+	req.on("error", () => settle({
+		ok: false,
+		status: 400,
+		rpcCode: -32600,
+		message: "Request body could not be read."
+	}));
+});
+const respondBodyError = (req, res, failure) => {
+	const headers = failure.status === 413 ? { Connection: "close" } : {};
+	sendJsonRpcError(res, failure.status, failure.rpcCode, failure.message, headers);
+	if (failure.status === 413) if (res.writableFinished) req.destroy();
+	else res.once("finish", () => req.destroy());
+};
+const SESSION_IDLE_TIMEOUT_MS = 1800 * 1e3;
+const SESSION_SWEEP_INTERVAL_MS = 60 * 1e3;
+const startHttpTransport = async (config, logger = silentLogger, options = {}) => {
+	const metadata = buildOAuthMetadata(config, logger);
+	const sessions = /* @__PURE__ */ new Map();
+	const idleTimeoutMs = options.sessionIdleTimeoutMs ?? SESSION_IDLE_TIMEOUT_MS;
+	const maxBodyBytes = options.maxBodyBytes ?? 4194304;
+	const handleMcpRequest = async (req, res) => {
+		const bearer = extractBearer(req);
+		if (!bearer) {
+			sendUnauthorized(res, metadata.protectedResource.resource);
+			return;
+		}
+		const sessionId = typeof req.headers["mcp-session-id"] === "string" ? req.headers["mcp-session-id"] : void 0;
+		if (sessionId) {
+			const session = sessions.get(sessionId);
+			if (session) {
+				session.auth.bearer = bearer;
+				session.lastActivityAt = Date.now();
+				const body = req.method === "POST" ? await readJsonBody(req, maxBodyBytes) : {
+					ok: true,
+					value: void 0
+				};
+				if (!body.ok) {
+					respondBodyError(req, res, body);
+					return;
+				}
+				await session.transport.handleRequest(req, res, body.value);
+				return;
+			}
+		}
+		if (req.method !== "POST") {
+			sendJsonRpcError(res, 400, -32e3, "No active session; initialize via POST first.");
+			return;
+		}
+		const body = await readJsonBody(req, maxBodyBytes);
+		if (!body.ok) {
+			respondBodyError(req, res, body);
+			return;
+		}
+		const auth = { bearer };
+		const server = createMcpServer(config, () => auth.bearer, logger);
+		const transport = new StreamableHTTPServerTransport({
+			sessionIdGenerator: () => randomUUID(),
+			onsessioninitialized: (newId) => {
+				sessions.set(newId, {
+					transport,
+					auth,
+					lastActivityAt: Date.now(),
+					close: async () => {
+						await transport.close();
+						await server.close();
+					}
+				});
+			}
+		});
+		transport.onclose = () => {
+			if (transport.sessionId) sessions.delete(transport.sessionId);
+		};
+		await server.connect(transport);
+		await transport.handleRequest(req, res, body.value);
+	};
+	const requestListener = async (req, res) => {
+		try {
+			if (handleCorsPreflight(req, res, config.corsOrigins)) return;
+			applyCorsHeaders(req, res, config.corsOrigins);
+			const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+			if (url.pathname === "/.well-known/oauth-protected-resource" && req.method === "GET") {
+				sendJson(res, 200, metadata.protectedResource);
+				return;
+			}
+			if (url.pathname === "/.well-known/oauth-authorization-server" && req.method === "GET") {
+				sendJson(res, 200, metadata.authorizationServer);
+				return;
+			}
+			if (url.pathname === "/healthz" && req.method === "GET") {
+				sendJson(res, 200, {
+					status: "ok",
+					subdomain: config.subdomain
+				});
+				return;
+			}
+			if (url.pathname === "/mcp") {
+				await handleMcpRequest(req, res);
+				return;
+			}
+			res.writeHead(404, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({
+				error: "Not found",
+				path: url.pathname
+			}));
+		} catch (err) {
+			const message = err instanceof Error ? err.message : "Internal Server Error";
+			if (!res.headersSent) sendJsonRpcError(res, 500, -32603, message);
+			else if (!res.writableEnded) res.end();
+		}
+	};
+	const httpServer = createServer((req, res) => {
+		requestListener(req, res);
+	});
+	await new Promise((resolve, reject) => {
+		httpServer.once("error", reject);
+		httpServer.listen(config.port, config.host, () => {
+			httpServer.off("error", reject);
+			resolve();
+		});
+	});
+	const addr = httpServer.address();
+	const boundPort = typeof addr === "object" && addr !== null ? addr.port : config.port;
+	logger.info("http_transport_ready", {
+		host: config.host,
+		port: boundPort
+	});
+	const sweepIdleSessions = async () => {
+		const cutoff = Date.now() - idleTimeoutMs;
+		for (const [id, session] of sessions) {
+			if (session.lastActivityAt > cutoff) continue;
+			sessions.delete(id);
+			try {
+				await session.close();
+			} catch (err) {
+				logger.warn("session_close_failed", {
+					sessionId: id,
+					error: err instanceof Error ? err.message : String(err)
+				});
+			}
+		}
+	};
+	const sweeper = setInterval(() => void sweepIdleSessions(), options.sweepIntervalMs ?? SESSION_SWEEP_INTERVAL_MS);
+	sweeper.unref();
+	return {
+		port: boundPort,
+		close: async () => {
+			clearInterval(sweeper);
+			await Promise.all([...sessions.values()].map((session) => session.close()));
+			sessions.clear();
+			httpServer.closeAllConnections();
+			await new Promise((resolve, reject) => {
+				httpServer.close((err) => err ? reject(err) : resolve());
+			});
+		}
+	};
+};
+//#endregion
 //#region src/transports/stdio.ts
 const startStdioTransport = async (server, logger = silentLogger) => {
 	const transport = new StdioServerTransport();
@@ -2123,17 +2703,26 @@ const startStdioTransport = async (server, logger = silentLogger) => {
 };
 //#endregion
 //#region src/index.ts
-const main = async () => {
-	const config = loadConfig();
-	const logger = createLogger(config.logLevel);
+const buildStdioServer = (config, logger) => {
 	if (config.zendeskEmail && config.zendeskApiToken) {
 		const staticToken = buildBasicAuthHeader(config.zendeskEmail, config.zendeskApiToken);
-		const getToken = () => staticToken;
-		await startStdioTransport(createMcpServer(config, getToken, logger), logger);
-	} else await startStdioTransport(createMcpServer(config, createTokenStore({
+		return createMcpServer(config, () => staticToken, logger);
+	}
+	const tokenStore = createTokenStore({
 		subdomain: config.subdomain,
-		oauthClientId: config.oauthClientId
-	}, logger).getToken, logger), logger);
+		oauthClientId: config.oauthClientId,
+		callbackPort: config.callbackPort
+	}, logger);
+	return createMcpServer(config, tokenStore.getToken, logger, tokenStore.invalidate);
+};
+const main = async () => {
+	const config = loadConfig();
+	const logger = createLogger(config.logLevel);
+	if (config.transport === "stdio") {
+		await startStdioTransport(buildStdioServer(config, logger), logger);
+		return;
+	}
+	await startHttpTransport(config, logger);
 };
 main().catch((error) => {
 	console.error("Fatal error:", error);