@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.
- package/README.md +4 -0
- package/dist/index.js +119 -15
- 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,
|
|
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 =
|
|
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(
|
|
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 =
|
|
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(
|
|
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.
|
|
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",
|