npm - @fruggr/zendesk-mcp-server - Versions diffs - 1.0.0 - Mend

@fruggr/zendesk-mcp-server 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/dist/index.js ADDED Viewed

@@ -0,0 +1,2092 @@
+#!/usr/bin/env node
+// src/auth/api-token.ts
+var buildBasicAuthHeader = (email, apiToken) => {
+  const credentials = `${email}/token:${apiToken}`;
+  return `Basic ${Buffer.from(credentials).toString("base64")}`;
+};
+// src/auth/browser-oauth.ts
+import { createHash, randomBytes } from "crypto";
+import { createServer } from "http";
+import open from "open";
+// src/constants.ts
+var CHARACTER_LIMIT = 25e3;
+var DEFAULT_PAGE_SIZE = 100;
+var MAX_PAGE_SIZE = 100;
+var TOKEN_CACHE_TTL_MS = 5 * 60 * 1e3;
+var LARGE_ARTICLE_BODY_CHARS = 3e3;
+var LARGE_ARTICLE_SECTION_COUNT = 4;
+var getBaseUrl = (subdomain) => `https://${subdomain}.zendesk.com/api/v2`;
+var getHelpCenterBaseUrl = (subdomain) => `https://${subdomain}.zendesk.com/api/v2/help_center`;
+var getOAuthUrls = (subdomain) => ({
+  authorizeUrl: `https://${subdomain}.zendesk.com/oauth/authorizations/new`,
+  tokenUrl: `https://${subdomain}.zendesk.com/oauth/tokens`
+});
+// src/auth/browser-oauth.ts
+var DEFAULT_CALLBACK_PORT = 3e3;
+var generateCodeVerifier = () => randomBytes(32).toString("base64url");
+var generateCodeChallenge = (verifier) => createHash("sha256").update(verifier).digest("base64url");
+var authenticateViaBrowser = (config) => {
+  const { subdomain, oauthClientId } = config;
+  const { authorizeUrl, tokenUrl } = getOAuthUrls(subdomain);
+  const codeVerifier = generateCodeVerifier();
+  const codeChallenge = generateCodeChallenge(codeVerifier);
+  return new Promise((resolve, reject) => {
+    let callbackServer;
+    callbackServer = createServer(async (req, res) => {
+      const url = new URL(req.url ?? "/", `http://localhost`);
+      if (url.pathname !== "/callback") {
+        res.writeHead(404);
+        res.end("Not found");
+        return;
+      }
+      const code = url.searchParams.get("code");
+      const error = url.searchParams.get("error");
+      if (error) {
+        const desc = url.searchParams.get("error_description") ?? error;
+        res.writeHead(400, { "Content-Type": "text/html" });
+        res.end(`<html><body><h1>Authentication failed</h1><p>${desc}</p></body></html>`);
+        callbackServer.close();
+        reject(new Error(`OAuth error: ${desc}`));
+        return;
+      }
+      if (!code) {
+        res.writeHead(400, { "Content-Type": "text/html" });
+        res.end("<html><body><h1>Missing authorization code</h1></body></html>");
+        callbackServer.close();
+        reject(new Error("Missing authorization code in callback"));
+        return;
+      }
+      try {
+        const callbackPort = callbackServer.address().port;
+        const tokenBody = new URLSearchParams({
+          grant_type: "authorization_code",
+          code,
+          client_id: oauthClientId,
+          redirect_uri: `http://localhost:${callbackPort}/callback`,
+          code_verifier: codeVerifier
+        });
+        const tokenResponse = await fetch(tokenUrl, {
+          method: "POST",
+          headers: { "Content-Type": "application/x-www-form-urlencoded" },
+          body: tokenBody.toString()
+        });
+        if (!tokenResponse.ok) {
+          const errorBody = await tokenResponse.text();
+          throw new Error(`Token exchange failed (${tokenResponse.status}): ${errorBody}`);
+        }
+        const tokenData = await tokenResponse.json();
+        res.writeHead(200, { "Content-Type": "text/html" });
+        res.end(
+          "<html><body><h1>Authentication successful!</h1><p>You can close this tab and return to Claude Code.</p><script>window.close()</script></body></html>"
+        );
+        callbackServer.close();
+        resolve(tokenData);
+      } catch (err) {
+        res.writeHead(500, { "Content-Type": "text/html" });
+        res.end(
+          `<html><body><h1>Token exchange failed</h1><p>${err instanceof Error ? err.message : String(err)}</p></body></html>`
+        );
+        callbackServer.close();
+        reject(err);
+      }
+    });
+    callbackServer.listen(config.callbackPort ?? DEFAULT_CALLBACK_PORT, () => {
+      const port = callbackServer.address().port;
+      const redirectUri = `http://localhost:${port}/callback`;
+      const params = new URLSearchParams({
+        response_type: "code",
+        client_id: oauthClientId,
+        redirect_uri: redirectUri,
+        scope: "read write",
+        code_challenge: codeChallenge,
+        code_challenge_method: "S256"
+      });
+      const authUrl = `${authorizeUrl}?${params.toString()}`;
+      console.error(`Opening browser for Zendesk authentication...`);
+      console.error(`If the browser doesn't open, visit: ${authUrl}`);
+      open(authUrl).catch(() => {
+      });
+    });
+    setTimeout(
+      () => {
+        callbackServer.close();
+        reject(new Error("OAuth authentication timed out (5 min). Please try again."));
+      },
+      5 * 60 * 1e3
+    ).unref();
+  });
+};
+// src/auth/token-store.ts
+var createTokenStore = (config) => {
+  let token;
+  let authPromise;
+  const setToken = (accessToken, refreshToken) => {
+    token = { accessToken, refreshToken };
+  };
+  const ensureToken = async () => {
+    if (token) return token;
+    if (!authPromise) {
+      authPromise = authenticateViaBrowser({
+        subdomain: config.subdomain,
+        oauthClientId: config.oauthClientId
+      }).then((result) => {
+        const stored = {
+          accessToken: result.access_token,
+          refreshToken: result.refresh_token
+        };
+        token = stored;
+        authPromise = void 0;
+        return stored;
+      }).catch((err) => {
+        authPromise = void 0;
+        throw err;
+      });
+    }
+    return authPromise;
+  };
+  const getToken = async () => {
+    const stored = await ensureToken();
+    return stored.accessToken;
+  };
+  return { getToken, setToken };
+};
+// src/config.ts
+import * as z from "zod/v4";
+var ToolMode = z.enum(["single", "namespace", "all"]);
+var LogLevel = z.enum(["debug", "info", "warn", "error"]);
+var Namespace = z.enum(["tickets", "help_center", "users"]);
+var ConfigSchema = z.object({
+  subdomain: z.string().min(1, "ZENDESK_SUBDOMAIN is required"),
+  oauthClientId: z.string().min(1),
+  zendeskEmail: z.string().optional(),
+  zendeskApiToken: z.string().optional(),
+  logLevel: LogLevel,
+  mode: ToolMode,
+  readOnly: z.boolean(),
+  namespaces: z.array(Namespace).optional(),
+  tools: z.array(z.string()).optional()
+});
+var parseCliArgs = (args) => {
+  const result = {};
+  let positionalIndex = 0;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === void 0) continue;
+    const next = args[i + 1];
+    if (arg === "--mode" && next) {
+      result.mode = next;
+      i++;
+    } else if (arg === "--read-only") {
+      result.readOnly = true;
+    } else if (arg === "--namespace" && next) {
+      result.namespaces = result.namespaces ?? [];
+      result.namespaces.push(next);
+      i++;
+    } else if (arg === "--tool" && next) {
+      result.tools = result.tools ?? [];
+      result.tools.push(next);
+      i++;
+    } else if (arg === "--log-level" && next) {
+      result.logLevel = next;
+      i++;
+    } else if (!arg.startsWith("-") && positionalIndex === 0) {
+      result.subdomain = arg;
+      positionalIndex++;
+    }
+  }
+  return result;
+};
+var loadConfig = (argv = process.argv.slice(2)) => {
+  const cli = parseCliArgs(argv);
+  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";
+  return ConfigSchema.parse({
+    subdomain,
+    oauthClientId,
+    zendeskEmail: process.env["ZENDESK_EMAIL"],
+    zendeskApiToken: process.env["ZENDESK_API_TOKEN"],
+    logLevel: cli.logLevel ?? process.env["LOG_LEVEL"] ?? "info",
+    mode,
+    readOnly: cli.readOnly ?? false,
+    namespaces: cli.namespaces,
+    tools: cli.tools
+  });
+};
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z6 from "zod/v4";
+// src/routing/registry.ts
+var 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;
+});
+var 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;
+};
+// src/tools/help-center.ts
+import * as z2 from "zod/v4";
+// src/client/zendesk-api.ts
+var ZendeskApiError = class _ZendeskApiError extends Error {
+  constructor(status, statusText, body) {
+    super(_ZendeskApiError.buildMessage(status, statusText, body));
+    this.status = status;
+    this.statusText = statusText;
+    this.body = body;
+    this.name = "ZendeskApiError";
+  }
+  status;
+  statusText;
+  body;
+  static buildMessage(status, statusText, body) {
+    switch (status) {
+      case 401:
+        return "Authentication failed. Your Zendesk token may be expired or invalid. Re-authenticate to get a new token.";
+      case 403:
+        return "Permission denied. Your Zendesk account does not have access to this resource.";
+      case 404:
+        return `Resource not found. Please verify the ID is correct. (${statusText})`;
+      case 422:
+        return `Validation error: ${body}`;
+      case 429:
+        return "Rate limit exceeded. Please wait before making more requests.";
+      default:
+        return `Zendesk API error ${status}: ${statusText}. ${body}`;
+    }
+  }
+};
+var buildUrl = (base, path, params) => {
+  const url = new URL(`${base}${path}`);
+  if (params) {
+    for (const [key, value] of Object.entries(params)) {
+      url.searchParams.set(key, value);
+    }
+  }
+  return url.toString();
+};
+var executeRequest = async (url, token, options = {}) => {
+  const { method = "GET", body } = options;
+  const authorization = token.startsWith("Basic ") ? token : `Bearer ${token}`;
+  const headers = {
+    Authorization: authorization,
+    Accept: "application/json"
+  };
+  if (body) {
+    headers["Content-Type"] = "application/json";
+  }
+  const init = { method, headers };
+  if (body) {
+    init.body = JSON.stringify(body);
+  }
+  const response = await fetch(url, init);
+  if (!response.ok) {
+    const responseBody = await response.text();
+    throw new ZendeskApiError(response.status, response.statusText, responseBody);
+  }
+  if (response.status === 204) {
+    return {};
+  }
+  return response.json();
+};
+var zendeskGet = (subdomain, token, path, params) => {
+  const url = buildUrl(getBaseUrl(subdomain), path, params);
+  return executeRequest(url, token);
+};
+var zendeskPost = (subdomain, token, path, body) => {
+  const url = buildUrl(getBaseUrl(subdomain), path);
+  return executeRequest(url, token, { method: "POST", body });
+};
+var zendeskPut = (subdomain, token, path, body) => {
+  const url = buildUrl(getBaseUrl(subdomain), path);
+  return executeRequest(url, token, { method: "PUT", body });
+};
+var helpCenterGet = (subdomain, token, path, params) => {
+  const url = buildUrl(getHelpCenterBaseUrl(subdomain), path, params);
+  return executeRequest(url, token);
+};
+var helpCenterPost = (subdomain, token, path, body) => {
+  const url = buildUrl(getHelpCenterBaseUrl(subdomain), path);
+  return executeRequest(url, token, { method: "POST", body });
+};
+var helpCenterPut = (subdomain, token, path, body) => {
+  const url = buildUrl(getHelpCenterBaseUrl(subdomain), path);
+  return executeRequest(url, token, { method: "PUT", body });
+};
+var helpCenterUpload = async (subdomain, token, path, formData) => {
+  const url = buildUrl(getHelpCenterBaseUrl(subdomain), path);
+  const authorization = token.startsWith("Basic ") ? token : `Bearer ${token}`;
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { Authorization: authorization },
+    body: formData
+  });
+  if (!response.ok) {
+    const responseBody = await response.text();
+    throw new ZendeskApiError(response.status, response.statusText, responseBody);
+  }
+  return response.json();
+};
+// src/utils/article-sections.ts
+import * as cheerio from "cheerio";
+import { toHtml } from "hast-util-to-html";
+import rehypeParse from "rehype-parse";
+import rehypeRaw from "rehype-raw";
+import rehypeRemark from "rehype-remark";
+import rehypeStringify from "rehype-stringify";
+import remarkGfm from "remark-gfm";
+import remarkParse from "remark-parse";
+import remarkRehype from "remark-rehype";
+import remarkStringify from "remark-stringify";
+import { unified } from "unified";
+var HEADING_LEVELS = /* @__PURE__ */ new Set(["h1", "h2", "h3"]);
+var countWords = (text) => {
+  const trimmed = text.trim();
+  if (!trimmed) return 0;
+  return trimmed.split(/\s+/).length;
+};
+var textOf = (html) => {
+  if (!html) return "";
+  const $ = cheerio.load(`<div>${html}</div>`, null, false);
+  return $("div").first().text();
+};
+var parseSections = (html) => {
+  if (!html || !html.trim()) return [];
+  const $ = cheerio.load(html, null, false);
+  const children = $.root().contents().toArray();
+  const introParts = [];
+  const sections = [];
+  let current = null;
+  for (const node of children) {
+    const tagName = node.type === "tag" ? node.name.toLowerCase() : "";
+    if (HEADING_LEVELS.has(tagName)) {
+      const level = Number.parseInt(tagName.slice(1), 10);
+      current = {
+        heading: $(node).text().trim(),
+        headingTag: tagName,
+        level,
+        contentParts: []
+      };
+      sections.push(current);
+      continue;
+    }
+    const outer = $.html(node);
+    if (current) {
+      current.contentParts.push(outer);
+    } else {
+      introParts.push(outer);
+    }
+  }
+  const result = [];
+  if (introParts.length > 0) {
+    const introHtml = introParts.join("");
+    result.push({
+      index: 0,
+      heading: "intro",
+      headingTag: "",
+      level: 0,
+      html: introHtml,
+      wordCount: countWords(textOf(introHtml))
+    });
+  }
+  for (const s of sections) {
+    const sectionHtml = s.contentParts.join("");
+    result.push({
+      index: result.length,
+      heading: s.heading,
+      headingTag: s.headingTag,
+      level: s.level,
+      html: sectionHtml,
+      wordCount: countWords(textOf(sectionHtml))
+    });
+  }
+  return result;
+};
+var replaceSectionContent = (html, sectionIndex, newHtml) => {
+  const sections = parseSections(html);
+  if (sectionIndex < 0 || sectionIndex >= sections.length) {
+    throw new Error(
+      `Section index ${sectionIndex} out of range (valid: 0-${Math.max(0, sections.length - 1)})`
+    );
+  }
+  return sections.map((section, idx) => {
+    const content = idx === sectionIndex ? newHtml : section.html;
+    if (section.level === 0) return content;
+    return `<${section.headingTag}>${section.heading}</${section.headingTag}>${content}`;
+  }).join("");
+};
+var keepAsHtml = (_state, node) => ({
+  type: "html",
+  value: toHtml(node)
+});
+var htmlToMdProcessor = unified().use(rehypeParse, { fragment: true }).use(rehypeRemark, { handlers: { table: keepAsHtml, pre: keepAsHtml } }).use(remarkGfm).use(remarkStringify, { bullet: "-", emphasis: "_", fences: true });
+var mdToHtmlProcessor = unified().use(remarkParse).use(remarkGfm).use(remarkRehype, { allowDangerousHtml: true }).use(rehypeRaw).use(rehypeStringify);
+var htmlToMarkdown = (html) => {
+  if (!html) return "";
+  return String(htmlToMdProcessor.processSync(html));
+};
+var markdownToHtml = (markdown) => {
+  if (!markdown) return "";
+  return String(mdToHtmlProcessor.processSync(markdown));
+};
+// src/utils/formatting.ts
+var truncateIfNeeded = (text) => {
+  if (text.length <= CHARACTER_LIMIT) return text;
+  return `${text.slice(0, CHARACTER_LIMIT)}
+--- Response truncated (${text.length} chars, limit ${CHARACTER_LIMIT}). Use pagination or filters to reduce results. ---`;
+};
+var formatPagination = (meta) => {
+  const parts = [`Results: ${meta.count}`];
+  if (meta.has_more) {
+    parts.push(`More available (cursor: ${meta.after_cursor})`);
+  }
+  return parts.join(" | ");
+};
+var formatTicket = (ticket) => [
+  `## Ticket #${ticket.id}: ${ticket.subject}`,
+  `- **Status**: ${ticket.status} | **Priority**: ${ticket.priority ?? "none"} | **Type**: ${ticket.type ?? "none"}`,
+  `- **Requester**: ${ticket.requester_id} | **Assignee**: ${ticket.assignee_id ?? "unassigned"}`,
+  `- **Tags**: ${ticket.tags.length > 0 ? ticket.tags.join(", ") : "none"}`,
+  `- **Created**: ${ticket.created_at} | **Updated**: ${ticket.updated_at}`,
+  ticket.description ? `
+${ticket.description}` : ""
+].filter(Boolean).join("\n");
+var formatComment = (comment) => [
+  `### ${comment.public ? "Public comment" : "Internal note"} by ${comment.author_id}`,
+  `*${comment.created_at}*`,
+  "",
+  comment.body
+].join("\n");
+var formatUser = (user) => [
+  `## ${user.name} (${user.id})`,
+  `- **Email**: ${user.email}`,
+  `- **Role**: ${user.role}`,
+  user.role_type != null ? `- **Role type**: ${user.role_type}` : "",
+  `- **Active**: ${user.active}`,
+  user.organization_id ? `- **Organization**: ${user.organization_id}` : ""
+].filter(Boolean).join("\n");
+var formatOrganization = (org) => [
+  `## ${org.name} (${org.id})`,
+  org.details ? `- **Details**: ${org.details}` : "",
+  org.domain_names.length > 0 ? `- **Domains**: ${org.domain_names.join(", ")}` : "",
+  org.tags.length > 0 ? `- **Tags**: ${org.tags.join(", ")}` : ""
+].filter(Boolean).join("\n");
+var formatArticleSummary = (article) => [
+  `## ${article.title} (${article.id})`,
+  `- **Locale**: ${article.locale} | **Source locale**: ${article.source_locale}`,
+  `- **Section**: ${article.section_id} | **Draft**: ${article.draft}`,
+  article.label_names.length > 0 ? `- **Labels**: ${article.label_names.join(", ")}` : "",
+  `- **Created**: ${article.created_at} | **Updated**: ${article.updated_at}`
+].filter(Boolean).join("\n");
+var formatArticle = (article) => [formatArticleSummary(article), "", article.body].join("\n");
+var formatTranslationSummary = (translation) => [
+  `## Translation: ${translation.locale} (${translation.id})`,
+  `- **Title**: ${translation.title}`,
+  `- **Draft**: ${translation.draft}`,
+  `- **Updated**: ${translation.updated_at}`
+].join("\n");
+var formatTranslation = (translation) => [formatTranslationSummary(translation), "", translation.body].join("\n");
+var formatCategory = (category) => `- **${category.name}** (${category.id}) \u2014 ${category.description || "No description"}`;
+var formatSection = (section) => `- **${section.name}** (${section.id}) \u2014 Category: ${section.category_id} \u2014 ${section.description || "No description"}`;
+var formatPermissionGroup = (group) => `- **${group.name}** (${group.id})${group.built_in ? " \u2014 Built-in" : ""}`;
+var formatContentTag = (tag) => `- **${tag.name}** (${tag.id})`;
+var formatLabel = (label) => `- **${label.name}** (${label.id})`;
+var formatUserSegment = (segment) => `- **${segment.name}** (${segment.id}) \u2014 ${segment.user_type}${segment.built_in ? " \u2014 Built-in" : ""}`;
+var formatAttachment = (attachment) => `- **${attachment.file_name}** (${attachment.id}) \u2014 ${attachment.content_type} \u2014 ${attachment.size} bytes`;
+var formatList = (items, formatter, meta) => {
+  const header = meta ? formatPagination(meta) : "";
+  const body = items.map(formatter).join("\n\n");
+  const text = [header, body].filter(Boolean).join("\n\n");
+  return truncateIfNeeded(text);
+};
+// src/utils/pagination.ts
+var buildCursorParams = (pageSize, cursor) => {
+  const params = {
+    "page[size]": String(pageSize)
+  };
+  if (cursor) {
+    params["page[after]"] = cursor;
+  }
+  return params;
+};
+var buildOffsetParams = (perPage, page) => {
+  const params = {
+    per_page: String(perPage)
+  };
+  if (page && page > 1) {
+    params["page"] = String(page);
+  }
+  return params;
+};
+var extractPaginationMeta = (response) => ({
+  has_more: response.meta?.has_more ?? response.next_page != null,
+  after_cursor: response.meta?.after_cursor ?? null,
+  count: response.count ?? 0
+});
+var extractSearchPaginationMeta = (response, perPage, page) => {
+  const count = response.count ?? 0;
+  const has_more = count > page * perPage;
+  return {
+    has_more,
+    after_cursor: has_more ? String(page + 1) : null,
+    count
+  };
+};
+// src/tools/help-center.ts
+var largeArticleHint = (body, sectionCount) => {
+  if (body.length < LARGE_ARTICLE_BODY_CHARS && sectionCount < LARGE_ARTICLE_SECTION_COUNT) {
+    return null;
+  }
+  return [
+    `> \u26A0 Large article (${body.length} chars, ${sectionCount} sections).`,
+    "> For targeted edits, prefer get_article_outline + get_article_section +",
+    "> update_article_section to avoid re-sending the full body on each write.",
+    ""
+  ].join("\n");
+};
+var createHelpCenterTools = (ctx) => {
+  const { subdomain, getToken } = ctx;
+  return [
+    {
+      name: "search_articles",
+      namespace: "help_center",
+      readOnly: true,
+      title: "Search Help Center Articles",
+      description: "Full-text search across Help Center articles (metadata only, no body). Use get_article for full content. Supports locale filtering. Returns total count.",
+      inputSchema: z2.object({
+        query: z2.string().min(1).describe("Search query"),
+        locale: z2.string().optional().describe('Filter by locale (e.g., "en-us", "fr")'),
+        per_page: z2.number().int().min(1).max(MAX_PAGE_SIZE).default(DEFAULT_PAGE_SIZE).describe("Results per page"),
+        page: z2.number().int().min(1).default(1).describe("Page number")
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      handler: async (params) => {
+        const { query, locale, per_page, page } = params;
+        const token = await getToken();
+        const p = { query, ...buildOffsetParams(per_page, page) };
+        if (locale) p["locale"] = locale;
+        const response = await helpCenterGet(
+          subdomain,
+          token,
+          "/articles/search",
+          p
+        );
+        return {
+          content: [
+            {
+              type: "text",
+              text: formatList(
+                response.results ?? [],
+                formatArticleSummary,
+                extractSearchPaginationMeta(response, per_page, page)
+              )
+            }
+          ]
+        };
+      }
+    },
+    {
+      name: "get_article",
+      namespace: "help_center",
+      readOnly: true,
+      title: "Get Help Center Article",
+      description: "Retrieve an article by ID with full body content. For large articles, prefer get_article_outline + get_article_section to save tokens. Optionally specify locale for a translated version. Returns body (HTML), metadata, source_locale, and list of available translations.",
+      inputSchema: z2.object({
+        article_id: z2.number().int().describe("Article ID"),
+        locale: z2.string().optional().describe("Locale for translated version")
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      handler: async (params) => {
+        const { article_id, locale } = params;
+        const token = await getToken();
+        const path = locale ? `/${locale}/articles/${article_id}` : `/articles/${article_id}`;
+        const { article } = await helpCenterGet(
+          subdomain,
+          token,
+          path
+        );
+        const { translations } = await helpCenterGet(
+          subdomain,
+          token,
+          `/articles/${article_id}/translations`
+        );
+        const hint = largeArticleHint(article.body, parseSections(article.body).length);
+        const text = (hint ?? "") + formatArticle(article) + `
+**Available translations**: ${translations.map((t) => t.locale).join(", ")}`;
+        return { content: [{ type: "text", text: truncateIfNeeded(text) }] };
+      }
+    },
+    {
+      name: "list_categories",
+      namespace: "help_center",
+      readOnly: true,
+      title: "List Help Center Categories",
+      description: "List all Help Center categories. Optionally filter by locale.",
+      inputSchema: z2.object({
+        locale: z2.string().optional(),
+        page_size: z2.number().int().min(1).max(MAX_PAGE_SIZE).default(DEFAULT_PAGE_SIZE),
+        cursor: z2.string().optional()
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      handler: async (params) => {
+        const { locale, page_size, cursor } = params;
+        const token = await getToken();
+        const path = locale ? `/${locale}/categories` : "/categories";
+        const response = await helpCenterGet(
+          subdomain,
+          token,
+          path,
+          buildCursorParams(page_size, cursor)
+        );
+        return {
+          content: [
+            {
+              type: "text",
+              text: formatList(
+                response.categories ?? [],
+                formatCategory,
+                extractPaginationMeta(response)
+              )
+            }
+          ]
+        };
+      }
+    },
+    {
+      name: "list_sections",
+      namespace: "help_center",
+      readOnly: true,
+      title: "List Help Center Sections",
+      description: "List sections, optionally filtered by category ID and locale.",
+      inputSchema: z2.object({
+        category_id: z2.number().int().optional(),
+        locale: z2.string().optional(),
+        page_size: z2.number().int().min(1).max(MAX_PAGE_SIZE).default(DEFAULT_PAGE_SIZE),
+        cursor: z2.string().optional()
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      handler: async (params) => {
+        const { category_id, locale, page_size, cursor } = params;
+        const token = await getToken();
+        const path = category_id && locale ? `/${locale}/categories/${category_id}/sections` : category_id ? `/categories/${category_id}/sections` : locale ? `/${locale}/sections` : "/sections";
+        const response = await helpCenterGet(
+          subdomain,
+          token,
+          path,
+          buildCursorParams(page_size, cursor)
+        );
+        return {
+          content: [
+            {
+              type: "text",
+              text: formatList(
+                response.sections ?? [],
+                formatSection,
+                extractPaginationMeta(response)
+              )
+            }
+          ]
+        };
+      }
+    },
+    {
+      name: "list_articles",
+      namespace: "help_center",
+      readOnly: true,
+      title: "List Help Center Articles",
+      description: 'List articles (metadata only, no body). Use get_article for full content. Optionally filter by section ID and locale. Supports sort_by ("title", "created_at", "updated_at") and include_translations: true to show available translation locales per article. Note: include_translations must be re-sent on each paginated request.',
+      inputSchema: z2.object({
+        section_id: z2.number().int().optional(),
+        locale: z2.string().optional(),
+        page_size: z2.number().int().min(1).max(MAX_PAGE_SIZE).default(DEFAULT_PAGE_SIZE),
+        cursor: z2.string().optional(),
+        sort_by: z2.enum(["created_at", "updated_at", "position", "title"]).default("position").describe("Sort field"),
+        sort_order: z2.enum(["asc", "desc"]).default("asc").describe("Sort direction"),
+        include_translations: z2.boolean().default(false).describe(
+          "Include available translation locales per article (causes 1 extra API call per article)"
+        )
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      handler: async (params) => {
+        const { section_id, locale, page_size, cursor, sort_by, sort_order, include_translations } = params;
+        const token = await getToken();
+        const path = section_id && locale ? `/${locale}/sections/${section_id}/articles` : section_id ? `/sections/${section_id}/articles` : locale ? `/${locale}/articles` : "/articles";
+        const response = await helpCenterGet(
+          subdomain,
+          token,
+          path,
+          { ...buildCursorParams(page_size, cursor), sort_by, sort_order }
+        );
+        const articles = response.articles ?? [];
+        if (!include_translations) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: formatList(articles, formatArticleSummary, extractPaginationMeta(response))
+              }
+            ]
+          };
+        }
+        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)}
+- **Translations**: ${locales}`;
+          })
+        );
+        const meta = extractPaginationMeta(response);
+        const header = meta.count ? `Results: ${meta.count}${meta.has_more ? ` | More available (cursor: ${meta.after_cursor})` : ""}` : "";
+        const text = [header, ...formatted].filter(Boolean).join("\n\n");
+        return { content: [{ type: "text", text: truncateIfNeeded(text) }] };
+      }
+    },
+    {
+      name: "list_article_translations",
+      namespace: "help_center",
+      readOnly: true,
+      title: "List Article Translations",
+      description: "List all available translations for an article (metadata only, no body: locale, title, draft, updated_at). Use get_article with locale for full translated content.",
+      inputSchema: z2.object({ article_id: z2.number().int().describe("Article ID") }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      handler: async (params) => {
+        const { article_id } = params;
+        const token = await getToken();
+        const { translations } = await helpCenterGet(
+          subdomain,
+          token,
+          `/articles/${article_id}/translations`
+        );
+        return {
+          content: [{ type: "text", text: formatList(translations, formatTranslationSummary) }]
+        };
+      }
+    },
+    {
+      name: "create_article_translation",
+      namespace: "help_center",
+      readOnly: false,
+      title: "Create Article Translation",
+      description: "Create a translation for an existing article in a specific locale.",
+      inputSchema: z2.object({
+        article_id: z2.number().int(),
+        locale: z2.string().describe('Target locale (e.g., "fr", "de")'),
+        title: z2.string().min(1),
+        body: z2.string().min(1).describe("Translated body (HTML)"),
+        draft: z2.boolean().default(false)
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true
+      },
+      handler: async (params) => {
+        const { article_id, locale, title, body, draft } = params;
+        const token = await getToken();
+        const { translation } = await helpCenterPost(
+          subdomain,
+          token,
+          `/articles/${article_id}/translations`,
+          { translation: { locale, title, body, draft } }
+        );
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Translation created for article #${article_id} in "${locale}".
+${formatTranslation(translation)}`
+            }
+          ]
+        };
+      }
+    },
+    {
+      name: "update_article_translation",
+      namespace: "help_center",
+      readOnly: false,
+      title: "Update Article Translation",
+      description: "Update article content (title, body) in a specific locale. For targeted edits on one or a few sections, prefer update_article_section \u2014 this tool replaces the FULL body and re-sends the entire article on each write. Use the article's source_locale (from get_article) for the default language, or another locale for translations.",
+      inputSchema: z2.object({
+        article_id: z2.number().int(),
+        locale: z2.string(),
+        title: z2.string().optional(),
+        body: z2.string().optional(),
+        draft: z2.boolean().optional()
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      handler: async (params) => {
+        const { article_id, locale, ...updates } = params;
+        const token = await getToken();
+        const { translation } = await helpCenterPut(
+          subdomain,
+          token,
+          `/articles/${article_id}/translations/${locale}`,
+          { translation: updates }
+        );
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Translation updated for article #${article_id} in "${locale}".
+${formatTranslation(translation)}`
+            }
+          ]
+        };
+      }
+    },
+    {
+      name: "list_permission_groups",
+      namespace: "help_center",
+      readOnly: true,
+      title: "List Permission Groups",
+      description: "List all Guide permission groups. Use this to find the permission_group_id required when creating articles.",
+      inputSchema: z2.object({}),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      handler: async () => {
+        const token = await getToken();
+        const response = await zendeskGet(subdomain, token, "/guide/permission_groups");
+        return {
+          content: [
+            {
+              type: "text",
+              text: formatList(response.permission_groups ?? [], formatPermissionGroup)
+            }
+          ]
+        };
+      }
+    },
+    {
+      name: "create_article",
+      namespace: "help_center",
+      readOnly: false,
+      title: "Create Help Center Article",
+      description: "Create a new article in a section. The locale becomes the article's source_locale. Requires a permission_group_id (use list_permission_groups to find available IDs). To add content in other locales afterwards, use create_article_translation.",
+      inputSchema: z2.object({
+        section_id: z2.number().int(),
+        title: z2.string().min(1),
+        body: z2.string().min(1).describe("Article body (HTML)"),
+        permission_group_id: z2.number().int().describe("Permission group ID (use list_permission_groups to find it)"),
+        user_segment_id: z2.number().int().optional().describe(
+          "User segment ID for visibility (use list_user_segments to find it). Defaults to everyone."
+        ),
+        author_id: z2.number().int().optional().describe("Author user ID. Defaults to the authenticated user."),
+        content_tag_ids: z2.array(z2.string()).optional().describe("Content tag IDs (use list_content_tags to find them)"),
+        locale: z2.string().optional(),
+        draft: z2.boolean().default(true),
+        promoted: z2.boolean().default(false),
+        label_names: z2.array(z2.string()).optional().describe("Label names for search ranking (use list_labels to see existing labels)")
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true
+      },
+      handler: async (params) => {
+        const { section_id, ...articleData } = params;
+        const token = await getToken();
+        const { article } = await helpCenterPost(
+          subdomain,
+          token,
+          `/sections/${section_id}/articles`,
+          { article: articleData }
+        );
+        return {
+          content: [
+            { type: "text", text: `Article #${article.id} created.
+${formatArticle(article)}` }
+          ]
+        };
+      }
+    },
+    {
+      name: "update_article",
+      namespace: "help_center",
+      readOnly: false,
+      title: "Update Help Center Article",
+      description: "Update article metadata only (draft, promoted, labels, tags, visibility, section, etc.). Does NOT update content (title, body) \u2014 use update_article_translation for that.",
+      inputSchema: z2.object({
+        article_id: z2.number().int(),
+        draft: z2.boolean().optional(),
+        promoted: z2.boolean().optional(),
+        label_names: z2.array(z2.string()).optional().describe("Label names for search ranking"),
+        content_tag_ids: z2.array(z2.string()).optional().describe("Content tag IDs"),
+        user_segment_id: z2.number().int().optional().describe("User segment ID for visibility"),
+        author_id: z2.number().int().optional().describe("Author user ID"),
+        permission_group_id: z2.number().int().optional().describe("Permission group ID"),
+        section_id: z2.number().int().optional()
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      handler: async (params) => {
+        const { article_id, ...updates } = params;
+        const token = await getToken();
+        const { article } = await helpCenterPut(
+          subdomain,
+          token,
+          `/articles/${article_id}`,
+          { article: updates }
+        );
+        return {
+          content: [
+            { type: "text", text: `Article #${article.id} updated.
+${formatArticle(article)}` }
+          ]
+        };
+      }
+    },
+    {
+      name: "list_content_tags",
+      namespace: "help_center",
+      readOnly: true,
+      title: "List Content Tags",
+      description: "List all Guide content tags. Content tags are visible to end users and help them find related articles.",
+      inputSchema: z2.object({}),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      handler: async () => {
+        const token = await getToken();
+        const response = await zendeskGet(
+          subdomain,
+          token,
+          "/guide/content_tags"
+        );
+        return {
+          content: [{ type: "text", text: formatList(response.records ?? [], formatContentTag) }]
+        };
+      }
+    },
+    {
+      name: "create_content_tag",
+      namespace: "help_center",
+      readOnly: false,
+      title: "Create Content Tag",
+      description: "Create a new content tag for Guide articles.",
+      inputSchema: z2.object({
+        name: z2.string().min(1).describe("Content tag name")
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true
+      },
+      handler: async (params) => {
+        const { name } = params;
+        const token = await getToken();
+        const { record: record2 } = await zendeskPost(
+          subdomain,
+          token,
+          "/guide/content_tags",
+          { record: { name } }
+        );
+        return {
+          content: [{ type: "text", text: `Content tag created.
+${formatContentTag(record2)}` }]
+        };
+      }
+    },
+    {
+      name: "list_labels",
+      namespace: "help_center",
+      readOnly: true,
+      title: "List Article Labels",
+      description: "List all article labels. Labels improve Help Center search ranking and are not visible to end users.",
+      inputSchema: z2.object({}),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      handler: async () => {
+        const token = await getToken();
+        const response = await helpCenterGet(
+          subdomain,
+          token,
+          "/articles/labels"
+        );
+        return {
+          content: [{ type: "text", text: formatList(response.labels ?? [], formatLabel) }]
+        };
+      }
+    },
+    {
+      name: "list_user_segments",
+      namespace: "help_center",
+      readOnly: true,
+      title: "List User Segments",
+      description: "List all user segments. User segments control article visibility (who can view). Use the ID when creating or updating articles.",
+      inputSchema: z2.object({}),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      handler: async () => {
+        const token = await getToken();
+        const response = await helpCenterGet(subdomain, token, "/user_segments");
+        return {
+          content: [
+            { type: "text", text: formatList(response.user_segments ?? [], formatUserSegment) }
+          ]
+        };
+      }
+    },
+    {
+      name: "list_article_attachments",
+      namespace: "help_center",
+      readOnly: true,
+      title: "List Article Attachments",
+      description: "List all attachments for an article.",
+      inputSchema: z2.object({
+        article_id: z2.number().int().describe("Article ID")
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      handler: async (params) => {
+        const { article_id } = params;
+        const token = await getToken();
+        const response = await helpCenterGet(subdomain, token, `/articles/${article_id}/attachments`);
+        return {
+          content: [
+            {
+              type: "text",
+              text: formatList(response.article_attachments ?? [], formatAttachment)
+            }
+          ]
+        };
+      }
+    },
+    {
+      name: "get_article_outline",
+      namespace: "help_center",
+      readOnly: true,
+      title: "Get Article Outline",
+      description: "Return a compact outline of an article (list of sections delimited by h1/h2/h3, with word counts) for the given locale (defaults to source_locale). Includes available translations with their outdated status. Use get_article_section to fetch a specific section.",
+      inputSchema: z2.object({
+        article_id: z2.number().int().describe("Article ID"),
+        locale: z2.string().optional().describe("Locale of the body to outline (defaults to article source_locale)")
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      handler: async (params) => {
+        const { article_id, locale } = params;
+        const token = await getToken();
+        const { article } = await helpCenterGet(
+          subdomain,
+          token,
+          `/articles/${article_id}`
+        );
+        const effectiveLocale = locale ?? article.source_locale;
+        const { translation } = await helpCenterGet(
+          subdomain,
+          token,
+          `/articles/${article_id}/translations/${effectiveLocale}`
+        );
+        const { translations } = await helpCenterGet(subdomain, token, `/articles/${article_id}/translations`);
+        const sections = parseSections(translation.body);
+        const outlineLines = sections.length ? sections.map(
+          (s) => `- [${s.index}] ${s.headingTag ? `${s.headingTag}: ` : ""}${s.heading} (${s.wordCount} words)`
+        ).join("\n") : "_(no sections detected)_";
+        const translationsList = translations.map((t) => `- ${t.locale}${t.outdated ? " (outdated)" : ""}`).join("\n");
+        const text = [
+          `# Outline \u2014 Article #${article_id} (${effectiveLocale})`,
+          `**Title**: ${translation.title}`,
+          "",
+          "## Sections",
+          outlineLines,
+          "",
+          "## Available translations",
+          translationsList
+        ].join("\n");
+        return { content: [{ type: "text", text }] };
+      }
+    },
+    {
+      name: "get_article_section",
+      namespace: "help_center",
+      readOnly: true,
+      title: "Get Article Section",
+      description: 'Retrieve the content of a single section of an article in a given locale. Use get_article_outline first to discover section indexes. Default format="html" for round-trip safety. Pass format="markdown" only for human review \u2014 the Markdown representation is lossy on some structures (<pre> with <br>, tables with multi-<p> cells are kept as raw HTML to limit the damage, but do not round-trip markdown content back through update_article_section).',
+      inputSchema: z2.object({
+        article_id: z2.number().int().describe("Article ID"),
+        locale: z2.string().describe('Locale of the body (e.g., "en-us", "fr")'),
+        section_index: z2.number().int().min(0).describe("0-based index of the section (see get_article_outline)"),
+        format: z2.enum(["html", "markdown"]).default("html").describe(
+          'Output format. "html" (default) is round-trip safe. "markdown" is lossy on some HTML structures \u2014 use only for human review, not before update_article_section.'
+        )
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      handler: async (params) => {
+        const { article_id, locale, section_index, format } = params;
+        const token = await getToken();
+        const { translation } = await helpCenterGet(
+          subdomain,
+          token,
+          `/articles/${article_id}/translations/${locale}`
+        );
+        const sections = parseSections(translation.body);
+        const section = sections[section_index];
+        if (!section) {
+          throw new Error(
+            `Section index ${section_index} not found. Article has ${sections.length} section(s) (0-${Math.max(0, sections.length - 1)}).`
+          );
+        }
+        const content = format === "markdown" ? htmlToMarkdown(section.html) : section.html;
+        const headerLine = section.headingTag ? `## [${section.index}] ${section.headingTag}: ${section.heading}` : `## [${section.index}] ${section.heading}`;
+        const text = [
+          headerLine,
+          `_Locale: ${locale} | Words: ${section.wordCount} | Format: ${format}_`,
+          "",
+          content
+        ].join("\n");
+        return { content: [{ type: "text", text: truncateIfNeeded(text) }] };
+      }
+    },
+    {
+      name: "update_article_section",
+      namespace: "help_center",
+      readOnly: false,
+      title: "Update Article Section",
+      description: 'Replace the content of a single section of an article in a given locale, keeping the rest of the body intact. The server fetches the current body, replaces the targeted section, and PUTs the full reconstructed body via the Translations API. Default format="html" for fidelity. Use format="markdown" only when you control the input and know it does not rely on structures that round-trip poorly (code blocks with line breaks, tables with multi-paragraph cells). The section heading is preserved and is NOT part of the replaced content.',
+      inputSchema: z2.object({
+        article_id: z2.number().int().describe("Article ID"),
+        locale: z2.string().describe("Locale of the translation to update"),
+        section_index: z2.number().int().min(0).describe("0-based index of the section to replace (see get_article_outline)"),
+        content: z2.string().describe(
+          'New content for the section (heading excluded). HTML by default, Markdown if format="markdown".'
+        ),
+        format: z2.enum(["html", "markdown"]).default("html").describe(
+          'Input format. "html" (default) is the safe path. "markdown" is converted to HTML server-side but may introduce artifacts on complex content.'
+        )
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      handler: async (params) => {
+        const { article_id, locale, section_index, content, format } = params;
+        const token = await getToken();
+        const { translation } = await helpCenterGet(
+          subdomain,
+          token,
+          `/articles/${article_id}/translations/${locale}`
+        );
+        const newSectionHtml = format === "markdown" ? markdownToHtml(content) : content;
+        const newBody = replaceSectionContent(translation.body, section_index, newSectionHtml);
+        const { translation: updated } = await helpCenterPut(
+          subdomain,
+          token,
+          `/articles/${article_id}/translations/${locale}`,
+          { translation: { body: newBody } }
+        );
+        const updatedSections = parseSections(updated.body);
+        const updatedSection = updatedSections[section_index];
+        const newWordCount = updatedSection?.wordCount ?? 0;
+        const headingLabel = updatedSection?.heading ?? "(intro)";
+        const text = [
+          `Section [${section_index}] "${headingLabel}" updated for article #${article_id} (${locale}).`,
+          `New word count: ${newWordCount}.`
+        ].join("\n");
+        return { content: [{ type: "text", text }] };
+      }
+    },
+    {
+      name: "compare_translations",
+      namespace: "help_center",
+      readOnly: true,
+      title: "Compare Article Translations",
+      description: 'Compare section structure between two locales of the same article, matched by index. Returns a compact table (one row per section) with status: "ok" (both present, source/target word count ratio within 25%), "different" (word count ratio diverges by more than 25% \u2014 size signal only, NOT a semantic divergence: two locales may legitimately differ in verbosity) or "missing" (section absent in target). Useful to spot structurally stale or missing sections; do not interpret "different" as an edit regression on its own.',
+      inputSchema: z2.object({
+        article_id: z2.number().int().describe("Article ID"),
+        source_locale: z2.string().describe("Source (reference) locale"),
+        target_locale: z2.string().describe("Target locale to compare against source")
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      handler: async (params) => {
+        const { article_id, source_locale, target_locale } = params;
+        const token = await getToken();
+        const [sourceRes, targetRes] = await Promise.all([
+          helpCenterGet(
+            subdomain,
+            token,
+            `/articles/${article_id}/translations/${source_locale}`
+          ),
+          helpCenterGet(
+            subdomain,
+            token,
+            `/articles/${article_id}/translations/${target_locale}`
+          )
+        ]);
+        const sourceSections = parseSections(sourceRes.translation.body);
+        const targetSections = parseSections(targetRes.translation.body);
+        const maxLen = Math.max(sourceSections.length, targetSections.length);
+        const rows = [];
+        rows.push(`| Idx | Heading | Status | Source words | Target words |`);
+        rows.push(`| --- | --- | --- | --- | --- |`);
+        for (let i = 0; i < maxLen; i += 1) {
+          const src = sourceSections[i];
+          const tgt = targetSections[i];
+          const heading = src?.heading ?? tgt?.heading ?? "";
+          const sourceWords = src?.wordCount ?? 0;
+          const targetWords = tgt?.wordCount ?? 0;
+          let status;
+          if (!tgt) status = "missing";
+          else if (!src) status = "different";
+          else {
+            const denom = Math.max(sourceWords, 1);
+            const diffRatio = Math.abs(sourceWords - targetWords) / denom;
+            status = diffRatio > 0.25 ? "different" : "ok";
+          }
+          rows.push(`| ${i} | ${heading} | ${status} | ${sourceWords} | ${targetWords} |`);
+        }
+        const text = [
+          `# Translation diff \u2014 Article #${article_id} (${source_locale} \u2192 ${target_locale})`,
+          "",
+          ...rows
+        ].join("\n");
+        return { content: [{ type: "text", text }] };
+      }
+    },
+    {
+      name: "create_article_attachment",
+      namespace: "help_center",
+      readOnly: false,
+      title: "Create Article Attachment",
+      description: "Upload an attachment to an article. Provide file content as base64-encoded string.",
+      inputSchema: z2.object({
+        article_id: z2.number().int().describe("Article ID"),
+        file_name: z2.string().min(1).describe('File name (e.g., "screenshot.png")'),
+        file_base64: z2.string().min(1).describe("File content encoded as base64"),
+        content_type: z2.string().default("application/octet-stream").describe('MIME type (e.g., "image/png", "application/pdf")')
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true
+      },
+      handler: async (params) => {
+        const { article_id, file_name, file_base64, content_type } = params;
+        const token = await getToken();
+        const buffer = Buffer.from(file_base64, "base64");
+        const blob = new Blob([buffer], { type: content_type });
+        const formData = new FormData();
+        formData.append("file", blob, file_name);
+        const { article_attachment } = await helpCenterUpload(subdomain, token, `/articles/${article_id}/attachments`, formData);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Attachment created for article #${article_id}.
+${formatAttachment(article_attachment)}`
+            }
+          ]
+        };
+      }
+    }
+  ];
+};
+// src/tools/search.ts
+import * as z3 from "zod/v4";
+var formatSearchResult = (result) => {
+  const lines = [`## [${result["result_type"]}] #${result["id"]}`];
+  if (result["subject"]) lines.push(`**Subject**: ${result["subject"]}`);
+  if (result["name"]) lines.push(`**Name**: ${result["name"]}`);
+  if (result["title"]) lines.push(`**Title**: ${result["title"]}`);
+  if (result["email"]) lines.push(`**Email**: ${result["email"]}`);
+  if (result["status"]) lines.push(`**Status**: ${result["status"]}`);
+  if (result["description"]) {
+    const desc = String(result["description"]);
+    lines.push(desc.length > 200 ? `${desc.slice(0, 200)}...` : desc);
+  }
+  return lines.join("\n");
+};
+var createSearchTools = (ctx) => {
+  const { subdomain, getToken } = ctx;
+  return [
+    {
+      name: "search",
+      namespace: "tickets",
+      readOnly: true,
+      title: "Zendesk Unified Search",
+      description: 'Search across tickets, users, and organizations. Supports filters like "type:ticket status:open", "type:user role:agent". Returns total count and paginated results (100 per page). Organization results include name and ID only \u2014 use get_organization for full details (tags, domains, details).',
+      inputSchema: z3.object({
+        query: z3.string().min(1).describe("Zendesk search query"),
+        per_page: z3.number().int().min(1).max(MAX_PAGE_SIZE).default(DEFAULT_PAGE_SIZE).describe("Results per page (max 100)"),
+        page: z3.number().int().min(1).default(1).describe("Page number (1-based)")
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      handler: async (params) => {
+        const { query, per_page, page } = params;
+        const token = await getToken();
+        const response = await zendeskGet(
+          subdomain,
+          token,
+          "/search",
+          {
+            query,
+            ...buildOffsetParams(per_page, page)
+          }
+        );
+        const results = response.results ?? [];
+        const meta = extractSearchPaginationMeta(response, per_page, page);
+        const header = `Total: ${meta.count} | Page ${page} (${results.length} results)${meta.has_more ? ` | Next page: ${meta.after_cursor}` : ""}`;
+        const body = results.map(formatSearchResult).join("\n\n");
+        return {
+          content: [
+            { type: "text", text: truncateIfNeeded([header, body].filter(Boolean).join("\n\n")) }
+          ]
+        };
+      }
+    }
+  ];
+};
+// src/tools/tickets.ts
+import * as z4 from "zod/v4";
+var createTicketTools = (ctx) => {
+  const { subdomain, getToken } = ctx;
+  return [
+    {
+      name: "get_ticket",
+      namespace: "tickets",
+      readOnly: true,
+      title: "Get Zendesk Ticket",
+      description: "Retrieve a Zendesk ticket by ID, including its comments if requested. Returns ticket details (subject, status, priority, assignee, tags, description) and optionally all comments/internal notes.",
+      inputSchema: z4.object({
+        ticket_id: z4.number().int().describe("Ticket ID"),
+        include_comments: z4.boolean().default(false).describe("Include ticket comments")
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      handler: async (params) => {
+        const { ticket_id, include_comments } = params;
+        const token = await getToken();
+        const { ticket } = await zendeskGet(
+          subdomain,
+          token,
+          `/tickets/${ticket_id}`
+        );
+        let text = formatTicket(ticket);
+        if (include_comments) {
+          const { comments } = await zendeskGet(
+            subdomain,
+            token,
+            `/tickets/${ticket_id}/comments`
+          );
+          text += `
+---
+# Comments
+${comments.map(formatComment).join("\n\n")}`;
+        }
+        return { content: [{ type: "text", text: truncateIfNeeded(text) }] };
+      }
+    },
+    {
+      name: "search_tickets",
+      namespace: "tickets",
+      readOnly: true,
+      title: "Search Zendesk Tickets",
+      description: 'Search tickets using Zendesk query syntax (e.g., "status:open assignee:me", "priority:urgent type:incident"). Returns total count.',
+      inputSchema: z4.object({
+        query: z4.string().min(1).describe("Zendesk search query string"),
+        per_page: z4.number().int().min(1).max(MAX_PAGE_SIZE).default(DEFAULT_PAGE_SIZE).describe("Results per page"),
+        page: z4.number().int().min(1).default(1).describe("Page number")
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      handler: async (params) => {
+        const { query, per_page, page } = params;
+        const token = await getToken();
+        const response = await zendeskGet(
+          subdomain,
+          token,
+          "/search",
+          {
+            query: `type:ticket ${query}`,
+            ...buildOffsetParams(per_page, page)
+          }
+        );
+        return {
+          content: [
+            {
+              type: "text",
+              text: formatList(
+                response.results ?? [],
+                formatTicket,
+                extractSearchPaginationMeta(response, per_page, page)
+              )
+            }
+          ]
+        };
+      }
+    },
+    {
+      name: "create_ticket",
+      namespace: "tickets",
+      readOnly: false,
+      title: "Create Zendesk Ticket",
+      description: "Create a new Zendesk support ticket with subject, description, and optional priority/type/assignee/tags.",
+      inputSchema: z4.object({
+        subject: z4.string().min(1).describe("Ticket subject"),
+        description: z4.string().min(1).describe("Ticket description"),
+        priority: z4.enum(["urgent", "high", "normal", "low"]).optional(),
+        type: z4.enum(["problem", "incident", "question", "task"]).optional(),
+        assignee_id: z4.number().int().optional(),
+        group_id: z4.number().int().optional(),
+        tags: z4.array(z4.string()).optional(),
+        custom_fields: z4.array(z4.object({ id: z4.number().int(), value: z4.unknown() })).optional()
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true
+      },
+      handler: async (params) => {
+        const { subject, description, ...rest } = params;
+        const token = await getToken();
+        const { ticket } = await zendeskPost(
+          subdomain,
+          token,
+          "/tickets",
+          {
+            ticket: { subject, comment: { body: description }, ...rest }
+          }
+        );
+        return {
+          content: [
+            { type: "text", text: `Ticket #${ticket.id} created.
+${formatTicket(ticket)}` }
+          ]
+        };
+      }
+    },
+    {
+      name: "update_ticket",
+      namespace: "tickets",
+      readOnly: false,
+      title: "Update Zendesk Ticket",
+      description: "Update an existing ticket (status, priority, type, assignee, group, subject, tags, custom fields).",
+      inputSchema: z4.object({
+        ticket_id: z4.number().int().describe("Ticket ID"),
+        status: z4.enum(["new", "open", "pending", "hold", "solved", "closed"]).optional(),
+        priority: z4.enum(["urgent", "high", "normal", "low"]).optional(),
+        type: z4.enum(["problem", "incident", "question", "task"]).optional(),
+        assignee_id: z4.number().int().optional(),
+        group_id: z4.number().int().optional(),
+        subject: z4.string().optional(),
+        tags: z4.array(z4.string()).optional(),
+        custom_fields: z4.array(z4.object({ id: z4.number().int(), value: z4.unknown() })).optional()
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      handler: async (params) => {
+        const { ticket_id, ...updates } = params;
+        const token = await getToken();
+        const { ticket } = await zendeskPut(
+          subdomain,
+          token,
+          `/tickets/${ticket_id}`,
+          { ticket: updates }
+        );
+        return {
+          content: [
+            { type: "text", text: `Ticket #${ticket.id} updated.
+${formatTicket(ticket)}` }
+          ]
+        };
+      }
+    },
+    {
+      name: "add_private_note",
+      namespace: "tickets",
+      readOnly: false,
+      title: "Add Private Note",
+      description: "Add an internal note (not visible to requester) to a ticket.",
+      inputSchema: z4.object({
+        ticket_id: z4.number().int().describe("Ticket ID"),
+        body: z4.string().min(1).describe("Note content")
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true
+      },
+      handler: async (params) => {
+        const { ticket_id, body } = params;
+        const token = await getToken();
+        await zendeskPut(subdomain, token, `/tickets/${ticket_id}`, {
+          ticket: { comment: { body, public: false } }
+        });
+        return { content: [{ type: "text", text: `Private note added to ticket #${ticket_id}.` }] };
+      }
+    },
+    {
+      name: "add_public_comment",
+      namespace: "tickets",
+      readOnly: false,
+      title: "Add Public Comment",
+      description: "Add a public comment (visible to requester) to a ticket.",
+      inputSchema: z4.object({
+        ticket_id: z4.number().int().describe("Ticket ID"),
+        body: z4.string().min(1).describe("Comment content")
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true
+      },
+      handler: async (params) => {
+        const { ticket_id, body } = params;
+        const token = await getToken();
+        await zendeskPut(subdomain, token, `/tickets/${ticket_id}`, {
+          ticket: { comment: { body, public: true } }
+        });
+        return {
+          content: [{ type: "text", text: `Public comment added to ticket #${ticket_id}.` }]
+        };
+      }
+    },
+    {
+      name: "list_tickets",
+      namespace: "tickets",
+      readOnly: true,
+      title: "List Zendesk Tickets",
+      description: "List tickets with cursor-based pagination, sorted by most recently updated.",
+      inputSchema: z4.object({
+        page_size: z4.number().int().min(1).max(MAX_PAGE_SIZE).default(DEFAULT_PAGE_SIZE),
+        cursor: z4.string().optional().describe("Pagination cursor")
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      handler: async (params) => {
+        const { page_size, cursor } = params;
+        const token = await getToken();
+        const response = await zendeskGet(
+          subdomain,
+          token,
+          "/tickets",
+          buildCursorParams(page_size, cursor)
+        );
+        return {
+          content: [
+            {
+              type: "text",
+              text: formatList(
+                response.tickets ?? [],
+                formatTicket,
+                extractPaginationMeta(response)
+              )
+            }
+          ]
+        };
+      }
+    },
+    {
+      name: "get_linked_incidents",
+      namespace: "tickets",
+      readOnly: true,
+      title: "Get Linked Incidents",
+      description: "Get all incident tickets linked to a problem ticket.",
+      inputSchema: z4.object({
+        problem_id: z4.number().int().describe("Problem ticket ID")
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      handler: async (params) => {
+        const { problem_id } = params;
+        const token = await getToken();
+        const response = await zendeskGet(
+          subdomain,
+          token,
+          `/tickets/${problem_id}/incidents`
+        );
+        const incidents = response.tickets ?? [];
+        const text = incidents.length > 0 ? `# Incidents linked to problem #${problem_id}
+${incidents.map(formatTicket).join("\n\n")}` : `No incidents linked to problem #${problem_id}.`;
+        return { content: [{ type: "text", text: truncateIfNeeded(text) }] };
+      }
+    },
+    {
+      name: "manage_tags",
+      namespace: "tickets",
+      readOnly: false,
+      title: "Manage Ticket Tags",
+      description: "Add or remove tags on a ticket.",
+      inputSchema: z4.object({
+        ticket_id: z4.number().int().describe("Ticket ID"),
+        add: z4.array(z4.string()).optional().describe("Tags to add"),
+        remove: z4.array(z4.string()).optional().describe("Tags to remove")
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      handler: async (params) => {
+        const { ticket_id, add, remove } = params;
+        const token = await getToken();
+        const { ticket } = await zendeskGet(
+          subdomain,
+          token,
+          `/tickets/${ticket_id}`
+        );
+        const tags = new Set(ticket.tags);
+        add?.forEach((t) => {
+          tags.add(t);
+        });
+        remove?.forEach((t) => {
+          tags.delete(t);
+        });
+        const { ticket: updated } = await zendeskPut(
+          subdomain,
+          token,
+          `/tickets/${ticket_id}`,
+          { ticket: { tags: [...tags] } }
+        );
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Tags updated on ticket #${ticket_id}. Current: ${updated.tags.join(", ") || "none"}`
+            }
+          ]
+        };
+      }
+    }
+  ];
+};
+// src/tools/users.ts
+import * as z5 from "zod/v4";
+var createUserTools = (ctx) => {
+  const { subdomain, getToken } = ctx;
+  return [
+    {
+      name: "get_current_user",
+      namespace: "users",
+      readOnly: true,
+      title: "Get Current Zendesk User",
+      description: "Get the currently authenticated Zendesk user. Useful to verify identity and permissions.",
+      inputSchema: z5.object({}),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      handler: async () => {
+        const token = await getToken();
+        const { user } = await zendeskGet(subdomain, token, "/users/me");
+        return { content: [{ type: "text", text: formatUser(user) }] };
+      }
+    },
+    {
+      name: "search_users",
+      namespace: "users",
+      readOnly: true,
+      title: "Search Zendesk Users",
+      description: "Search for users by name, email, or other criteria using Zendesk search query syntax. Returns total count.",
+      inputSchema: z5.object({
+        query: z5.string().min(1).describe("Search query"),
+        per_page: z5.number().int().min(1).max(MAX_PAGE_SIZE).default(DEFAULT_PAGE_SIZE).describe("Results per page"),
+        page: z5.number().int().min(1).default(1).describe("Page number")
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      handler: async (params) => {
+        const { query, per_page, page } = params;
+        const token = await getToken();
+        const response = await zendeskGet(
+          subdomain,
+          token,
+          "/search",
+          {
+            query: `type:user ${query}`,
+            ...buildOffsetParams(per_page, page)
+          }
+        );
+        return {
+          content: [
+            {
+              type: "text",
+              text: formatList(
+                response.results ?? [],
+                formatUser,
+                extractSearchPaginationMeta(response, per_page, page)
+              )
+            }
+          ]
+        };
+      }
+    },
+    {
+      name: "get_user",
+      namespace: "users",
+      readOnly: true,
+      title: "Get Zendesk User",
+      description: "Retrieve a user by ID.",
+      inputSchema: z5.object({ user_id: z5.number().int().describe("User ID") }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      handler: async (params) => {
+        const { user_id } = params;
+        const token = await getToken();
+        const { user } = await zendeskGet(
+          subdomain,
+          token,
+          `/users/${user_id}`
+        );
+        return { content: [{ type: "text", text: formatUser(user) }] };
+      }
+    },
+    {
+      name: "get_organization",
+      namespace: "users",
+      readOnly: true,
+      title: "Get Zendesk Organization",
+      description: "Retrieve an organization by ID.",
+      inputSchema: z5.object({ organization_id: z5.number().int().describe("Organization ID") }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      handler: async (params) => {
+        const { organization_id } = params;
+        const token = await getToken();
+        const { organization } = await zendeskGet(
+          subdomain,
+          token,
+          `/organizations/${organization_id}`
+        );
+        return { content: [{ type: "text", text: formatOrganization(organization) }] };
+      }
+    },
+    {
+      name: "list_organizations",
+      namespace: "users",
+      readOnly: true,
+      title: "List Zendesk Organizations",
+      description: "List all organizations with pagination.",
+      inputSchema: z5.object({
+        page_size: z5.number().int().min(1).max(MAX_PAGE_SIZE).default(DEFAULT_PAGE_SIZE),
+        cursor: z5.string().optional()
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      handler: async (params) => {
+        const { page_size, cursor } = params;
+        const token = await getToken();
+        const response = await zendeskGet(
+          subdomain,
+          token,
+          "/organizations",
+          buildCursorParams(page_size, cursor)
+        );
+        return {
+          content: [
+            {
+              type: "text",
+              text: formatList(
+                response.organizations ?? [],
+                formatOrganization,
+                extractPaginationMeta(response)
+              )
+            }
+          ]
+        };
+      }
+    }
+  ];
+};
+// src/tools/index.ts
+var createAllTools = (ctx) => [
+  ...createTicketTools(ctx),
+  ...createSearchTools(ctx),
+  ...createHelpCenterTools(ctx),
+  ...createUserTools(ctx)
+];
+// src/server.ts
+var NAMESPACE_LABELS = {
+  tickets: { toolName: "zendesk_tickets", title: "Zendesk Tickets" },
+  help_center: { toolName: "zendesk_help_center", title: "Zendesk Help Center" },
+  users: { toolName: "zendesk_users", title: "Zendesk Users" }
+};
+var summarizeDescription = (description) => {
+  const idx = description.indexOf(". ");
+  if (idx === -1) return description;
+  return description.slice(0, idx + 1);
+};
+var buildOperationList = (tools) => tools.map(
+  (t) => `- **${t.name}**: ${summarizeDescription(t.description)}${t.readOnly ? "" : " (write)"}`
+).join("\n");
+var registerProxyTool = (server, toolName, title, tools, handlerMap) => {
+  const operationNames = tools.map((t) => t.name);
+  const operationList = buildOperationList(tools);
+  server.registerTool(
+    toolName,
+    {
+      title,
+      description: `${title}. Specify the operation and its parameters.
+Available operations:
+${operationList}`,
+      inputSchema: z6.object({
+        operation: z6.string().describe(`One of: ${operationNames.join(", ")}`),
+        params: z6.record(z6.string(), z6.unknown()).default({}).describe("Operation parameters")
+      })
+    },
+    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);
+    }
+  );
+};
+var createMcpServer = (config, getToken) => {
+  const server = new McpServer({
+    name: "@digital4better/zendesk-mcp-server",
+    version: "0.1.0"
+  });
+  const allTools = createAllTools({ subdomain: config.subdomain, getToken });
+  const filteredTools = filterTools(allTools, {
+    readOnly: config.readOnly,
+    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,
+            annotations: tool.annotations
+          },
+          async (params) => tool.handler(params)
+        );
+      }
+      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);
+        }
+      }
+      break;
+    }
+    case "single": {
+      registerProxyTool(server, "zendesk", "Zendesk", filteredTools, handlerMap);
+      break;
+    }
+  }
+  console.error(`Registered ${filteredTools.length} tools in ${config.mode} mode`);
+  return server;
+};
+// src/transports/stdio.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+var startStdioTransport = async (server) => {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("Zendesk MCP server running via stdio");
+};
+// src/index.ts
+var main = async () => {
+  const config = loadConfig();
+  if (config.zendeskEmail && config.zendeskApiToken) {
+    const staticToken = buildBasicAuthHeader(config.zendeskEmail, config.zendeskApiToken);
+    const getToken = () => staticToken;
+    const server = createMcpServer(config, getToken);
+    await startStdioTransport(server);
+  } else {
+    const tokenStore = createTokenStore({
+      subdomain: config.subdomain,
+      oauthClientId: config.oauthClientId
+    });
+    const server = createMcpServer(config, tokenStore.getToken);
+    await startStdioTransport(server);
+  }
+};
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});
+//# sourceMappingURL=index.js.map