@lincolnminto/zendesk-mcp-server 2.23.0 → 2.24.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 (2) hide show
  1. package/dist/index.js +74 -15
  2. package/package.json +1 -1
package/dist/index.js CHANGED
@@ -4,7 +4,7 @@ import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync }
4
4
  import { createServer } from "node:http";
5
5
  import { homedir, release } from "node:os";
6
6
  import open from "open";
7
- import { dirname, join } from "node:path";
7
+ import { basename, dirname, extname, isAbsolute, join } from "node:path";
8
8
  import { fileURLToPath, pathToFileURL } from "node:url";
9
9
  import { parseArgs } from "node:util";
10
10
  import * as z from "zod/v4";
@@ -20,6 +20,7 @@ import remarkParse from "remark-parse";
20
20
  import remarkRehype from "remark-rehype";
21
21
  import remarkStringify from "remark-stringify";
22
22
  import { unified } from "unified";
23
+ import { readFile, stat } from "node:fs/promises";
23
24
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
24
25
  import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
25
26
  //#region src/auth/api-token.ts
@@ -130,6 +131,7 @@ const positiveIntEnv = (name, fallback) => {
130
131
  const CHARACTER_LIMIT = positiveIntEnv("ZENDESK_CHARACTER_LIMIT", 25e3);
131
132
  const ARTICLE_RESOURCES_SCAN_MAX_PAGES = positiveIntEnv("ZENDESK_ARTICLE_RESOURCES_SCAN_MAX_PAGES", 20);
132
133
  const MAX_ATTACHMENT_BYTES = positiveIntEnv("ZENDESK_MAX_ATTACHMENT_BYTES", 5242880);
134
+ const MAX_UPLOAD_BYTES = positiveIntEnv("ZENDESK_MAX_UPLOAD_BYTES", 52428800);
133
135
  const MAX_EMBEDDED_IMAGE_COUNT = positiveIntEnv("ZENDESK_MAX_EMBEDDED_IMAGES", 10);
134
136
  const MAX_COMMENT_PAGES = positiveIntEnv("ZENDESK_MAX_COMMENT_PAGES", 10);
135
137
  const REORDER_CONFIRM_THRESHOLD = positiveIntEnv("ZENDESK_REORDER_CONFIRM_THRESHOLD", 20);
@@ -3220,6 +3222,47 @@ const createTicketRelationTools = (ctx) => {
3220
3222
  //#endregion
3221
3223
  //#region src/tools/tickets.ts
3222
3224
  const MAX_ATTACHMENT_MB = Number.parseFloat((MAX_ATTACHMENT_BYTES / 1048576).toFixed(2));
3225
+ const CONTENT_TYPE_BY_EXTENSION = /* @__PURE__ */ new Map([
3226
+ [".png", "image/png"],
3227
+ [".jpg", "image/jpeg"],
3228
+ [".jpeg", "image/jpeg"],
3229
+ [".gif", "image/gif"],
3230
+ [".webp", "image/webp"],
3231
+ [".pdf", "application/pdf"],
3232
+ [".txt", "text/plain"],
3233
+ [".log", "text/plain"],
3234
+ [".csv", "text/csv"],
3235
+ [".json", "application/json"],
3236
+ [".xml", "application/xml"],
3237
+ [".html", "text/html"],
3238
+ [".md", "text/markdown"],
3239
+ [".sql", "application/sql"],
3240
+ [".zip", "application/zip"]
3241
+ ]);
3242
+ const contentTypeOf = (filePath) => CONTENT_TYPE_BY_EXTENSION.get(extname(filePath).toLowerCase()) ?? "application/octet-stream";
3243
+ const readLocalFile = async (filePath) => {
3244
+ if (!isAbsolute(filePath)) return { problem: "not an absolute path; pass the full path to the file" };
3245
+ try {
3246
+ const stats = await stat(filePath);
3247
+ if (!stats.isFile()) return { problem: "not a regular file" };
3248
+ if (stats.size > MAX_UPLOAD_BYTES) return { problem: `${stats.size} bytes, over the ${MAX_UPLOAD_BYTES}-byte limit per file (ZENDESK_MAX_UPLOAD_BYTES)` };
3249
+ const data = await readFile(filePath);
3250
+ return { file: {
3251
+ file_name: basename(filePath),
3252
+ data,
3253
+ content_type: contentTypeOf(filePath)
3254
+ } };
3255
+ } catch (error) {
3256
+ const code = error.code;
3257
+ return { problem: code === "ENOENT" ? "file not found" : `cannot be read (${code})` };
3258
+ }
3259
+ };
3260
+ const readLocalFiles = async (paths) => {
3261
+ const results = await Promise.all(paths.map(readLocalFile));
3262
+ const problems = results.flatMap((result, i) => "problem" in result ? [`- ${paths[i]}: ${result.problem}`] : []);
3263
+ if (problems.length > 0) throw new Error(`attachment_paths rejected; nothing was uploaded or posted:\n${problems.join("\n")}`);
3264
+ return results.flatMap((result) => "file" in result ? [result.file] : []);
3265
+ };
3223
3266
  const formatReference = (attachment) => `**${attachment.file_name}** (id ${attachment.id}, ${attachment.content_type}, ${attachment.size} bytes) — ${attachment.content_url}`;
3224
3267
  const buildEmbeddedImageBlocks = async (subdomain, token, attachment, reference) => {
3225
3268
  const { data, contentType } = await fetchZendeskBinary(subdomain, token, attachment.content_url);
@@ -3491,16 +3534,26 @@ const formatMacroPreviewDiff = (ticketId, macroId, before, result) => {
3491
3534
  return lines.join("\n");
3492
3535
  };
3493
3536
  const createTicketTools = (ctx) => {
3494
- const { subdomain, getToken } = ctx;
3537
+ const { subdomain, getToken, localFileAccess } = ctx;
3495
3538
  const attachmentSchema = z.object({
3496
3539
  file_name: z.string().min(1).describe("File name, e.g. \"app.log\" or \"screenshot.png\"."),
3497
3540
  file_base64: z.string().min(1).base64().describe("File content encoded as base64."),
3498
3541
  content_type: z.string().min(1).default("application/octet-stream").describe("MIME type, e.g. \"text/plain\", \"image/png\", \"application/pdf\".")
3499
3542
  });
3543
+ const attachmentPathsSchema = (target) => z.array(z.string().min(1).describe("Absolute path, e.g. \"/home/me/logs/app.log\".")).optional().describe(`Absolute paths of files to attach to this ${target}, read by the server from the machine it runs on (stdio only; refused over HTTP). Prefer this over attachments for any file already on disk: the call carries no base64. File name = the basename; content type inferred from the extension (unknown: application/octet-stream); at most ZENDESK_MAX_UPLOAD_BYTES per file (default 50 MiB). Every path is checked first: a missing, non-regular or oversize file fails the call with nothing uploaded or posted. Combinable with attachments, which upload first.`);
3544
+ const collectFiles = async (attachments = [], attachmentPaths = []) => {
3545
+ if (attachmentPaths.length > 0 && !localFileAccess) throw new Error("attachment_paths is not available over the HTTP transport: the paths would be read on the server host, not on your machine. Send the files with attachments (base64) instead.");
3546
+ const fromDisk = await readLocalFiles(attachmentPaths);
3547
+ return [...attachments.map((file) => ({
3548
+ file_name: file.file_name,
3549
+ data: Buffer.from(file.file_base64, "base64"),
3550
+ content_type: file.content_type
3551
+ })), ...fromDisk];
3552
+ };
3500
3553
  const uploadAttachments = async (token, files) => {
3501
3554
  let uploadToken;
3502
3555
  for (const file of files) {
3503
- const { upload } = await zendeskUpload(subdomain, token, file.file_name, Buffer.from(file.file_base64, "base64"), file.content_type, uploadToken);
3556
+ const { upload } = await zendeskUpload(subdomain, token, file.file_name, file.data, file.content_type, uploadToken);
3504
3557
  uploadToken = upload.token;
3505
3558
  }
3506
3559
  return uploadToken;
@@ -3805,11 +3858,12 @@ const createTicketTools = (ctx) => {
3805
3858
  namespace: "tickets",
3806
3859
  readOnly: false,
3807
3860
  title: "Add Private Note",
3808
- description: "Add an internal note (not visible to requester) to a ticket, optionally with file attachments (uploaded via the Zendesk Uploads API and carried on the note). The note is appended to the ticket thread; use add_public_comment instead when the reply should be visible to the requester.",
3861
+ description: "Add an internal note (not visible to requester) to a ticket, optionally with file attachments (uploaded via the Zendesk Uploads API and carried on the note). The note is appended to the ticket thread; use add_public_comment instead when the reply should be visible to the requester. Attach a file already on disk by its absolute path in attachment_paths (the server reads it, so no base64 goes in the call) rather than in attachments; if any path is unusable the call fails before anything is uploaded or posted. Returns a confirmation with the number of files attached.",
3809
3862
  inputSchema: z.object({
3810
3863
  ticket_id: z.number().int().describe("Ticket ID — the numeric id of the ticket to annotate. Obtain it from search_tickets or list_tickets."),
3811
3864
  body: z.string().min(1).describe("Note text (internal, agent-only). Plain text or HTML; not shown to the requester."),
3812
- attachments: z.array(attachmentSchema).optional().describe("Files to attach to this note (base64-encoded content).")
3865
+ attachments: z.array(attachmentSchema).optional().describe("Files to attach to this note (base64-encoded content). For a file already on disk, use attachment_paths instead."),
3866
+ attachment_paths: attachmentPathsSchema("note")
3813
3867
  }),
3814
3868
  annotations: {
3815
3869
  readOnlyHint: false,
@@ -3818,9 +3872,10 @@ const createTicketTools = (ctx) => {
3818
3872
  openWorldHint: true
3819
3873
  },
3820
3874
  handler: async (params) => {
3821
- const { ticket_id, body, attachments } = params;
3875
+ const { ticket_id, body, attachments, attachment_paths } = params;
3876
+ const files = await collectFiles(attachments, attachment_paths);
3822
3877
  const token = await getToken();
3823
- const uploads = attachments?.length ? [await uploadAttachments(token, attachments)] : void 0;
3878
+ const uploads = files.length > 0 ? [await uploadAttachments(token, files)] : void 0;
3824
3879
  await zendeskPut(subdomain, token, `/tickets/${ticket_id}`, { ticket: { comment: {
3825
3880
  body,
3826
3881
  public: false,
@@ -3828,7 +3883,7 @@ const createTicketTools = (ctx) => {
3828
3883
  } } });
3829
3884
  return { content: [{
3830
3885
  type: "text",
3831
- text: `Private note added to ticket #${ticket_id}${formatAttachmentSuffix(attachments?.length)}.`
3886
+ text: `Private note added to ticket #${ticket_id}${formatAttachmentSuffix(files.length)}.`
3832
3887
  }] };
3833
3888
  }
3834
3889
  },
@@ -3837,11 +3892,12 @@ const createTicketTools = (ctx) => {
3837
3892
  namespace: "tickets",
3838
3893
  readOnly: false,
3839
3894
  title: "Add Public Comment",
3840
- description: "Add a public comment (visible to requester) to a ticket, optionally with file attachments (uploaded via the Zendesk Uploads API and carried on the comment). The comment is appended to the ticket thread and emails the requester; use add_private_note instead for an internal, agent-only note.",
3895
+ description: "Add a public comment (visible to requester) to a ticket, optionally with file attachments (uploaded via the Zendesk Uploads API and carried on the comment). The comment is appended to the ticket thread and emails the requester; use add_private_note instead for an internal, agent-only note. Attach a file already on disk by its absolute path in attachment_paths (the server reads it, so no base64 goes in the call) rather than in attachments; if any path is unusable the call fails before anything is uploaded or posted. Returns a confirmation with the number of files attached.",
3841
3896
  inputSchema: z.object({
3842
3897
  ticket_id: z.number().int().describe("Ticket ID — the numeric id of the ticket to reply on. Obtain it from search_tickets or list_tickets."),
3843
3898
  body: z.string().min(1).describe("Comment text sent to the requester. Plain text or HTML; visible in the ticket."),
3844
- attachments: z.array(attachmentSchema).optional().describe("Files to attach to this comment (base64-encoded content).")
3899
+ attachments: z.array(attachmentSchema).optional().describe("Files to attach to this comment (base64-encoded content). For a file already on disk, use attachment_paths instead."),
3900
+ attachment_paths: attachmentPathsSchema("comment")
3845
3901
  }),
3846
3902
  annotations: {
3847
3903
  readOnlyHint: false,
@@ -3850,9 +3906,10 @@ const createTicketTools = (ctx) => {
3850
3906
  openWorldHint: true
3851
3907
  },
3852
3908
  handler: async (params) => {
3853
- const { ticket_id, body, attachments } = params;
3909
+ const { ticket_id, body, attachments, attachment_paths } = params;
3910
+ const files = await collectFiles(attachments, attachment_paths);
3854
3911
  const token = await getToken();
3855
- const uploads = attachments?.length ? [await uploadAttachments(token, attachments)] : void 0;
3912
+ const uploads = files.length > 0 ? [await uploadAttachments(token, files)] : void 0;
3856
3913
  await zendeskPut(subdomain, token, `/tickets/${ticket_id}`, { ticket: { comment: {
3857
3914
  body,
3858
3915
  public: true,
@@ -3860,7 +3917,7 @@ const createTicketTools = (ctx) => {
3860
3917
  } } });
3861
3918
  return { content: [{
3862
3919
  type: "text",
3863
- text: `Public comment added to ticket #${ticket_id}${formatAttachmentSuffix(attachments?.length)}.`
3920
+ text: `Public comment added to ticket #${ticket_id}${formatAttachmentSuffix(files.length)}.`
3864
3921
  }] };
3865
3922
  }
3866
3923
  },
@@ -4537,7 +4594,8 @@ const createMcpServer = (config, getToken, logger = silentLogger, onUnauthorized
4537
4594
  const server = createServerShell(config, logger);
4538
4595
  const tools = createAllTools({
4539
4596
  subdomain: config.subdomain,
4540
- getToken
4597
+ getToken,
4598
+ localFileAccess: config.transport === "stdio"
4541
4599
  });
4542
4600
  registerToolset(server, {
4543
4601
  config,
@@ -4608,7 +4666,8 @@ const createReloadableServer = (config, getToken, logger = silentLogger, onUnaut
4608
4666
  const server = createServerShell(config, logger);
4609
4667
  const ctx = {
4610
4668
  subdomain: config.subdomain,
4611
- getToken
4669
+ getToken,
4670
+ localFileAccess: config.transport === "stdio"
4612
4671
  };
4613
4672
  const params = {
4614
4673
  config,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lincolnminto/zendesk-mcp-server",
3
- "version": "2.23.0",
3
+ "version": "2.24.0",
4
4
  "mcpName": "io.github.lincolnminto/zendesk-mcp-server",
5
5
  "description": "Deep Zendesk MCP server for your AI assistant: search, draft, update and translate Help Center articles and manage Support tickets end to end — comments, triage and image attachments.",
6
6
  "type": "module",