@lincolnminto/zendesk-mcp-server 2.20.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 (3) hide show
  1. package/README.md +4 -0
  2. package/dist/index.js +119 -15
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -194,6 +194,10 @@ Add to your `.vscode/mcp.json`:
194
194
 
195
195
  </details>
196
196
 
197
+ > Using the stdio API-token escape hatch instead of OAuth? Add `ZENDESK_EMAIL` /
198
+ > `ZENDESK_API_TOKEN` via `env` in the config above — worked examples per client:
199
+ > [docs/api-token-stdio.md#mcp-client-configuration](docs/api-token-stdio.md#mcp-client-configuration).
200
+
197
201
  Something not working? See [Troubleshooting](docs/troubleshooting.md).
198
202
 
199
203
  ## Quick start: remote (HTTP)
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);
@@ -3178,8 +3180,89 @@ const createSearchTools = (ctx) => {
3178
3180
  }];
3179
3181
  };
3180
3182
  //#endregion
3183
+ //#region src/tools/ticket-relations.ts
3184
+ const formatTicketRelations = (ticket) => {
3185
+ const source = ticket.via?.source;
3186
+ const followUpOf = source?.rel === "follow_up" ? source.from : void 0;
3187
+ const followups = ticket.followup_ids ?? [];
3188
+ const lines = [
3189
+ followUpOf?.ticket_id ? `- **Follow-up of**: #${followUpOf.ticket_id}${followUpOf.subject ? ` (${followUpOf.subject})` : ""} — the closed ticket this one continues` : "",
3190
+ followups.length > 0 ? `- **Follow-ups**: ${followups.map((id) => `#${id}`).join(", ")} — tickets created from this one after it closed` : "",
3191
+ ticket.problem_id ? `- **Problem**: #${ticket.problem_id} — the problem ticket this incident is linked to` : "",
3192
+ ticket.type === "problem" ? `- **Incidents**: this is a problem ticket; list the incidents linked to it with get_linked_incidents (problem_id: ${ticket.id})` : ""
3193
+ ].filter(Boolean);
3194
+ return [`# Relationships of ticket #${ticket.id}`, ...lines.length > 0 ? lines : ["No related tickets: not a follow-up, no follow-ups created from it, not linked to a problem."]].join("\n");
3195
+ };
3196
+ const createTicketRelationTools = (ctx) => {
3197
+ const { subdomain, getToken } = ctx;
3198
+ return [{
3199
+ name: "get_ticket_relations",
3200
+ namespace: "tickets",
3201
+ readOnly: true,
3202
+ title: "Get Zendesk Ticket Relations",
3203
+ description: "List the tickets a Zendesk ticket is linked to (the closed ticket it is a follow-up of, the follow-ups created from it, and for an incident its problem ticket) as ticket ids, one line per relationship present. A closed ticket cannot be reopened, so when the customer replies to one Zendesk opens a new follow-up ticket instead and a single issue ends up split across tickets; use this to walk that chain in either direction, then read each ticket with get_ticket. Follow-ups are listed on the original only once it is closed (Zendesk hides them before), and the source ticket subject is shown when Zendesk provides it. For a problem ticket it points to get_linked_incidents, which lists the incidents linked to it; a ticket with none of these relationships returns a line saying so. Merges and side-conversation child tickets are not covered. Read-only: one ticket fetch, nothing is changed; an unknown ticket id returns a not-found error.",
3204
+ inputSchema: z.object({ ticket_id: z.number().int().describe("Ticket ID — the numeric id of the ticket whose related tickets to list. Obtain it from search_tickets, list_tickets, or a previous get_ticket_relations result to follow the chain.") }),
3205
+ annotations: {
3206
+ readOnlyHint: true,
3207
+ destructiveHint: false,
3208
+ idempotentHint: true,
3209
+ openWorldHint: true
3210
+ },
3211
+ handler: async (params) => {
3212
+ const { ticket_id } = params;
3213
+ const token = await getToken();
3214
+ const { ticket } = await zendeskGet(subdomain, token, `/tickets/${ticket_id}`);
3215
+ return { content: [{
3216
+ type: "text",
3217
+ text: formatTicketRelations(ticket)
3218
+ }] };
3219
+ }
3220
+ }];
3221
+ };
3222
+ //#endregion
3181
3223
  //#region src/tools/tickets.ts
3182
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
+ };
3183
3266
  const formatReference = (attachment) => `**${attachment.file_name}** (id ${attachment.id}, ${attachment.content_type}, ${attachment.size} bytes) — ${attachment.content_url}`;
3184
3267
  const buildEmbeddedImageBlocks = async (subdomain, token, attachment, reference) => {
3185
3268
  const { data, contentType } = await fetchZendeskBinary(subdomain, token, attachment.content_url);
@@ -3451,16 +3534,26 @@ const formatMacroPreviewDiff = (ticketId, macroId, before, result) => {
3451
3534
  return lines.join("\n");
3452
3535
  };
3453
3536
  const createTicketTools = (ctx) => {
3454
- const { subdomain, getToken } = ctx;
3537
+ const { subdomain, getToken, localFileAccess } = ctx;
3455
3538
  const attachmentSchema = z.object({
3456
3539
  file_name: z.string().min(1).describe("File name, e.g. \"app.log\" or \"screenshot.png\"."),
3457
3540
  file_base64: z.string().min(1).base64().describe("File content encoded as base64."),
3458
3541
  content_type: z.string().min(1).default("application/octet-stream").describe("MIME type, e.g. \"text/plain\", \"image/png\", \"application/pdf\".")
3459
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
+ };
3460
3553
  const uploadAttachments = async (token, files) => {
3461
3554
  let uploadToken;
3462
3555
  for (const file of files) {
3463
- 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);
3464
3557
  uploadToken = upload.token;
3465
3558
  }
3466
3559
  return uploadToken;
@@ -3765,11 +3858,12 @@ const createTicketTools = (ctx) => {
3765
3858
  namespace: "tickets",
3766
3859
  readOnly: false,
3767
3860
  title: "Add Private Note",
3768
- 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.",
3769
3862
  inputSchema: z.object({
3770
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."),
3771
3864
  body: z.string().min(1).describe("Note text (internal, agent-only). Plain text or HTML; not shown to the requester."),
3772
- 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")
3773
3867
  }),
3774
3868
  annotations: {
3775
3869
  readOnlyHint: false,
@@ -3778,9 +3872,10 @@ const createTicketTools = (ctx) => {
3778
3872
  openWorldHint: true
3779
3873
  },
3780
3874
  handler: async (params) => {
3781
- const { ticket_id, body, attachments } = params;
3875
+ const { ticket_id, body, attachments, attachment_paths } = params;
3876
+ const files = await collectFiles(attachments, attachment_paths);
3782
3877
  const token = await getToken();
3783
- const uploads = attachments?.length ? [await uploadAttachments(token, attachments)] : void 0;
3878
+ const uploads = files.length > 0 ? [await uploadAttachments(token, files)] : void 0;
3784
3879
  await zendeskPut(subdomain, token, `/tickets/${ticket_id}`, { ticket: { comment: {
3785
3880
  body,
3786
3881
  public: false,
@@ -3788,7 +3883,7 @@ const createTicketTools = (ctx) => {
3788
3883
  } } });
3789
3884
  return { content: [{
3790
3885
  type: "text",
3791
- text: `Private note added to ticket #${ticket_id}${formatAttachmentSuffix(attachments?.length)}.`
3886
+ text: `Private note added to ticket #${ticket_id}${formatAttachmentSuffix(files.length)}.`
3792
3887
  }] };
3793
3888
  }
3794
3889
  },
@@ -3797,11 +3892,12 @@ const createTicketTools = (ctx) => {
3797
3892
  namespace: "tickets",
3798
3893
  readOnly: false,
3799
3894
  title: "Add Public Comment",
3800
- 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.",
3801
3896
  inputSchema: z.object({
3802
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."),
3803
3898
  body: z.string().min(1).describe("Comment text sent to the requester. Plain text or HTML; visible in the ticket."),
3804
- 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")
3805
3901
  }),
3806
3902
  annotations: {
3807
3903
  readOnlyHint: false,
@@ -3810,9 +3906,10 @@ const createTicketTools = (ctx) => {
3810
3906
  openWorldHint: true
3811
3907
  },
3812
3908
  handler: async (params) => {
3813
- const { ticket_id, body, attachments } = params;
3909
+ const { ticket_id, body, attachments, attachment_paths } = params;
3910
+ const files = await collectFiles(attachments, attachment_paths);
3814
3911
  const token = await getToken();
3815
- const uploads = attachments?.length ? [await uploadAttachments(token, attachments)] : void 0;
3912
+ const uploads = files.length > 0 ? [await uploadAttachments(token, files)] : void 0;
3816
3913
  await zendeskPut(subdomain, token, `/tickets/${ticket_id}`, { ticket: { comment: {
3817
3914
  body,
3818
3915
  public: true,
@@ -3820,7 +3917,7 @@ const createTicketTools = (ctx) => {
3820
3917
  } } });
3821
3918
  return { content: [{
3822
3919
  type: "text",
3823
- text: `Public comment added to ticket #${ticket_id}${formatAttachmentSuffix(attachments?.length)}.`
3920
+ text: `Public comment added to ticket #${ticket_id}${formatAttachmentSuffix(files.length)}.`
3824
3921
  }] };
3825
3922
  }
3826
3923
  },
@@ -4245,6 +4342,7 @@ const createUserTools = (ctx) => {
4245
4342
  //#region src/tools/index.ts
4246
4343
  const createAllTools = (ctx) => [
4247
4344
  ...createTicketTools(ctx),
4345
+ ...createTicketRelationTools(ctx),
4248
4346
  ...createSearchTools(ctx),
4249
4347
  ...createHelpCenterTools(ctx),
4250
4348
  ...createUserTools(ctx)
@@ -4496,7 +4594,8 @@ const createMcpServer = (config, getToken, logger = silentLogger, onUnauthorized
4496
4594
  const server = createServerShell(config, logger);
4497
4595
  const tools = createAllTools({
4498
4596
  subdomain: config.subdomain,
4499
- getToken
4597
+ getToken,
4598
+ localFileAccess: config.transport === "stdio"
4500
4599
  });
4501
4600
  registerToolset(server, {
4502
4601
  config,
@@ -4522,6 +4621,10 @@ const TOOL_MODULES = [
4522
4621
  file: "tickets.ts",
4523
4622
  factory: "createTicketTools"
4524
4623
  },
4624
+ {
4625
+ file: "ticket-relations.ts",
4626
+ factory: "createTicketRelationTools"
4627
+ },
4525
4628
  {
4526
4629
  file: "search.ts",
4527
4630
  factory: "createSearchTools"
@@ -4563,7 +4666,8 @@ const createReloadableServer = (config, getToken, logger = silentLogger, onUnaut
4563
4666
  const server = createServerShell(config, logger);
4564
4667
  const ctx = {
4565
4668
  subdomain: config.subdomain,
4566
- getToken
4669
+ getToken,
4670
+ localFileAccess: config.transport === "stdio"
4567
4671
  };
4568
4672
  const params = {
4569
4673
  config,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lincolnminto/zendesk-mcp-server",
3
- "version": "2.20.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",