@fruggr/zendesk-mcp-server 2.16.1 → 2.17.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 +159 -288
- package/dist/index.js +327 -32
- package/package.json +11 -6
package/README.md
CHANGED
|
@@ -5,209 +5,104 @@
|
|
|
5
5
|
[](https://www.npmjs.com/package/@fruggr/zendesk-mcp-server)
|
|
6
6
|
[](LICENSE)
|
|
7
7
|
[](https://nodejs.org)
|
|
8
|
-
[](https://renovatebot.com)
|
|
9
|
-
[](https://github.com/semantic-release/semantic-release)
|
|
10
8
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
**without switching apps**.
|
|
9
|
+
A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that
|
|
10
|
+
puts Zendesk inside your AI assistant. It finds answers in the Help Center;
|
|
11
|
+
drafts, updates and translates articles while keeping the languages in sync; and
|
|
12
|
+
handles Support tickets end to end, comments, triage and image attachments
|
|
13
|
+
included. It all happens in plain language, without switching apps.
|
|
17
14
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
15
|
+
It does roughly what the
|
|
16
|
+
[Zendesk agent for Microsoft 365 Copilot](https://support.zendesk.com/hc/en-us/articles/9958331458458-Using-the-Zendesk-agent-in-Microsoft-365-Copilot)
|
|
17
|
+
does, minus the tie to one vendor: it drops into any MCP client (Claude Desktop,
|
|
18
|
+
Claude Code, Cursor, VS Code, and the rest). And it always acts with each user's
|
|
19
|
+
own Zendesk permissions, never a shared admin key.
|
|
22
20
|
|
|
23
21
|
## What your assistant can do
|
|
24
22
|
|
|
25
|
-
Ask in natural language; the assistant
|
|
26
|
-
the right tools on your behalf
|
|
23
|
+
Ask in natural language; the assistant works out the context and the intent,
|
|
24
|
+
then calls the right tools on your behalf.
|
|
27
25
|
|
|
28
|
-
-
|
|
29
|
-
"what's the time-off policy?" surfaces the right article, by meaning
|
|
30
|
-
|
|
31
|
-
-
|
|
26
|
+
- Find answers in the Help Center. "How do I request a software license?" or
|
|
27
|
+
"what's the time-off policy?" surfaces the right article, matched by meaning
|
|
28
|
+
rather than by keyword.
|
|
29
|
+
- Create, view and update tickets without leaving the conversation: open a
|
|
32
30
|
ticket, check its status, add a public reply or an internal note, change the
|
|
33
|
-
priority or assignee,
|
|
34
|
-
-
|
|
35
|
-
the full comment thread and
|
|
36
|
-
-
|
|
37
|
-
captures
|
|
38
|
-
so it can describe them or act on what they show.
|
|
39
|
-
-
|
|
40
|
-
|
|
41
|
-
-
|
|
42
|
-
a large one
|
|
31
|
+
priority or the assignee, mark it solved.
|
|
32
|
+
- Summarize a ticket for a report or a quick decision. The assistant pulls the
|
|
33
|
+
details and the full comment thread and gives you the gist in a sentence.
|
|
34
|
+
- Read the screenshots and photos attached to a ticket. Error dialogs, UI
|
|
35
|
+
captures and product photos are handed to your assistant's own model as
|
|
36
|
+
images, so it can describe them or act on what they show.
|
|
37
|
+
- Search and triage your queue in plain language: "show me my open tickets about
|
|
38
|
+
billing from this week."
|
|
39
|
+
- Draft and maintain knowledge-base articles. You can write a new one, or revise
|
|
40
|
+
a large one a single section at a time, so the whole HTML body never has to
|
|
43
41
|
round-trip through the model.
|
|
44
42
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
Non-image attachments come back as text references. The per-image size cap and the
|
|
82
|
-
number of embedded images are **configurable** — see
|
|
83
|
-
[`ZENDESK_MAX_ATTACHMENT_BYTES`](docs/configuration.md#zendesk_max_attachment_bytes)
|
|
84
|
-
and [`ZENDESK_MAX_EMBEDDED_IMAGES`](docs/configuration.md#zendesk_max_embedded_images).
|
|
85
|
-
|
|
86
|
-
## When to use this server
|
|
87
|
-
|
|
88
|
-
**Reach for it when:**
|
|
89
|
-
|
|
90
|
-
- You want an LLM to read or triage **Zendesk tickets** and **Help Center articles** on behalf of a real user, with that user's own permissions — not a shared admin key.
|
|
91
|
-
- You're editing **large Help Center articles** and want section-scoped reads/rewrites instead of round-tripping the full HTML body through the model.
|
|
92
|
-
- You need to **cap the tool surface** — read-only assistants, a single namespace, or one unified tool to fit a tight context budget.
|
|
93
|
-
- You run a **stdio MCP client** (Claude Desktop, Claude Code, Cursor, VS Code, Cline, …) and want a `npx`-installable server with no extra infrastructure, **or** you want to **deploy it as a private remote MCP server** that web/native clients reach over HTTP — each MCP client still carries its own user's OAuth token.
|
|
94
|
-
|
|
95
|
-
**Look elsewhere when:**
|
|
96
|
-
|
|
97
|
-
- You need Zendesk products outside Support & Guide (e.g. Talk, Explore analytics, Sell) — those endpoints aren't covered.
|
|
98
|
-
- You need a single shared service account, or static API-token auth — this server doesn't support either, by design (see [What this server does *not* do](#what-this-server-does-not-do)).
|
|
43
|
+
## Why this server
|
|
44
|
+
|
|
45
|
+
Most Zendesk integrations run on a shared admin API key, which hands every user
|
|
46
|
+
full access to every ticket, and bolt on a fixed set of tools. This one is built
|
|
47
|
+
differently.
|
|
48
|
+
|
|
49
|
+
- Per-user authentication, OAuth only. Both transports use OAuth 2.1 PKCE: each
|
|
50
|
+
user signs in with their own Zendesk credentials, so the assistant sees and
|
|
51
|
+
touches exactly what that person is allowed to, the same scoping you get by
|
|
52
|
+
signing into Zendesk directly. Static API tokens are deliberately not
|
|
53
|
+
supported ([why](#what-this-server-does-not-do)).
|
|
54
|
+
- Section-based article editing. For large Help Center articles, read and
|
|
55
|
+
rewrite one section at a time (parsed by `h1`/`h2`/`h3` headings) instead of
|
|
56
|
+
shuffling the full HTML body through the assistant. On a targeted edit that
|
|
57
|
+
cuts tokens by a factor of 10 to 100.
|
|
58
|
+
- Native multimodal attachments. Ticket images come back as native MCP image
|
|
59
|
+
content, so the client's own model (Claude, GPT, Gemini, whichever) sees the
|
|
60
|
+
pixels directly. No server-side vision model, no extra API key, and nothing
|
|
61
|
+
tying you to one provider. Non-image attachments come back as text references,
|
|
62
|
+
and both image caps are configurable.
|
|
63
|
+
- A tool surface you can cap. Expose every operation as its own tool, group them
|
|
64
|
+
into namespace proxies, or collapse everything into a single unified tool. You
|
|
65
|
+
can also filter by namespace or down to read-only operations, so each context
|
|
66
|
+
loads only the surface it needs (see [Tool surface](#tool-surface)).
|
|
67
|
+
- Two deployment shapes, same auth story. Run it on your laptop as a stdio MCP
|
|
68
|
+
server, or deploy it as a private remote MCP server reached over HTTP, with one
|
|
69
|
+
Zendesk session per request and each client carrying its own user's token.
|
|
70
|
+
- A lean stack: the official `@modelcontextprotocol/sdk` plus `zod`, speaking to
|
|
71
|
+
the Zendesk Support and Help Center (Guide) APIs.
|
|
72
|
+
|
|
73
|
+
Look elsewhere when:
|
|
74
|
+
|
|
75
|
+
- You need Zendesk products outside Support and Guide (Talk, Explore analytics,
|
|
76
|
+
Sell). Those endpoints aren't covered.
|
|
77
|
+
- You need a single shared service account, or static API-token auth. This
|
|
78
|
+
server supports neither, by design (see below).
|
|
99
79
|
|
|
100
80
|
## What this server does *not* do
|
|
101
81
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
| Mode | Tools exposed | Best for |
|
|
121
|
-
|------|--------------|----------|
|
|
122
|
-
| **`all`** | Every operation as its own tool (`get_ticket`, `search_articles`, ...) | Clients with good tool selection, full granularity |
|
|
123
|
-
| **`namespace`** (default) | One proxy tool per namespace (`zendesk_tickets`, `zendesk_help_center`, `zendesk_users`) | Balanced context usage, grouped operations |
|
|
124
|
-
| **`single`** | A single proxy tool (`zendesk`) | Minimal context footprint, single entry point |
|
|
125
|
-
|
|
126
|
-
In `namespace` and `single` modes, the proxy tool accepts `{ "operation": "<tool_name>", "params": { ... } }` and dispatches to the appropriate handler after validating params through the original Zod schema. Proxy descriptions include only the first sentence of each sub-operation to stay compact; the full schema is applied when the operation is actually called.
|
|
127
|
-
|
|
128
|
-
> **Tip:** The `single` mode is particularly useful for models with limited tool slots — one tool handles every operation.
|
|
129
|
-
|
|
130
|
-
### Scoping the surface
|
|
131
|
-
|
|
132
|
-
`--namespace` and `--read-only` apply to every mode (including the default `namespace` mode) — they filter tools **before** the proxies are built, so the description of each proxy reflects only the operations that survive the filters. Combine them to register a focused surface:
|
|
133
|
-
|
|
134
|
-
```bash
|
|
135
|
-
# Only the Help Center proxy, only read-only operations
|
|
136
|
-
zendesk-mcp-server acme --namespace help_center --read-only
|
|
137
|
-
|
|
138
|
-
# Only the Tickets proxy (read + write)
|
|
139
|
-
zendesk-mcp-server acme --namespace tickets
|
|
140
|
-
```
|
|
141
|
-
|
|
142
|
-
`--namespace` is repeatable. `--tool` is also available for cherry-picking individual operations but forces `--mode all`.
|
|
143
|
-
|
|
144
|
-
## Available tools
|
|
145
|
-
|
|
146
|
-
The tools are grouped into four namespaces — **Tickets**, **Help Center**,
|
|
147
|
-
**Users & Organizations**, and **Search** — each of which you can enable
|
|
148
|
-
selectively with `--namespace` (see [Tool modes](#tool-modes)).
|
|
149
|
-
|
|
150
|
-
The full tool-by-tool reference — every tool with its description and its
|
|
151
|
-
`read`/`write` mode — lives in
|
|
152
|
-
**[docs/mcp-tools-reference.md](docs/mcp-tools-reference.md)**.
|
|
153
|
-
|
|
154
|
-
## Help Center context (instructions + resources)
|
|
155
|
-
|
|
156
|
-
Beyond tools, the server hands an LLM the structural context it needs to work
|
|
157
|
-
against *your* Help Center — so it stops guessing locales or fuzzy-matching
|
|
158
|
-
section names and uses real IDs instead. This is delivered through MCP-native
|
|
159
|
-
channels (all active only when the `help_center` namespace is), each fetched
|
|
160
|
-
**with the caller's own token** so it respects that user's read permissions:
|
|
161
|
-
|
|
162
|
-
- **`instructions`** (sent on `initialize`): a short, static blob auto-loaded by
|
|
163
|
-
compliant clients. It names the subdomain and points at the topology resource.
|
|
164
|
-
- **`zendesk-hc://topology`** (a pull-only [MCP resource](https://modelcontextprotocol.io/docs/concepts/resources)):
|
|
165
|
-
read on demand, it returns Markdown describing the active locales (and the
|
|
166
|
-
default), the category → section tree with IDs, the visibility user segments,
|
|
167
|
-
the permission groups, and the calling user's role. Listing the permission
|
|
168
|
-
groups and user segments needs Guide-admin / Help Center manager rights; with a
|
|
169
|
-
content-editor token those two sections are marked *unavailable* (not empty) and
|
|
170
|
-
the rest still renders — reuse those IDs from an existing article (`get_article`)
|
|
171
|
-
instead. On a very large Help Center the section tree is summarized (per-category,
|
|
172
|
-
with a pointer to `list_sections`) to stay concise.
|
|
173
|
-
- **`zendesk-hc://article/{id}`** (pull-only [MCP resources](https://modelcontextprotocol.io/docs/concepts/resources)):
|
|
174
|
-
two distinct capabilities. **Read-by-id** — any article id can be read on demand,
|
|
175
|
-
returned as Markdown (a cheap single fetch, no preloading). **Promoted pre-listing** —
|
|
176
|
-
the resource's listing surfaces the promoted (*featured*) articles so a user can
|
|
177
|
-
pin one in clients that support resource pinning / @-mention, and the companion
|
|
178
|
-
`list_promoted_articles` tool returns the same set. Clients that don't support
|
|
179
|
-
resources ignore these silently.
|
|
180
|
-
<br>**Cost:** only the *pre-listing* costs requests — finding promoted articles has
|
|
181
|
-
no server-side filter, so it scans article pages (one Zendesk API request per page,
|
|
182
|
-
capped). The resource listing is cached briefly per session (repeated `resources/list`
|
|
183
|
-
calls coalesce); the `list_promoted_articles` tool performs a fresh scan on every
|
|
184
|
-
call. It runs only on a client's `resources/list` or a tool call, never at connect,
|
|
185
|
-
and consumes no LLM context until an article is pinned/read. Read-by-id costs one
|
|
186
|
-
fetch, only when a specific article is opened. See
|
|
187
|
-
[`ZENDESK_ARTICLE_RESOURCES_SCAN_MAX_PAGES`](docs/configuration.md#zendesk_article_resources_scan_max_pages).
|
|
188
|
-
|
|
189
|
-
The `instructions` blob and the topology resource are toggled together with
|
|
190
|
-
`--no-topology`. The **promoted pre-listing** is toggled independently with
|
|
191
|
-
`--no-promoted-articles` — which turns off the resource `list` scan **and** the
|
|
192
|
-
`list_promoted_articles` tool, so the server makes zero preloading requests;
|
|
193
|
-
**reading a known article by id stays available** (it never preloads). Clients that
|
|
194
|
-
don't consume `instructions` or `resources` simply ignore them — the feature
|
|
195
|
-
degrades silently. The `zendesk-hc://` URI scheme is the default; a deployer can
|
|
196
|
-
brand it with
|
|
197
|
-
[`--hc-resource-scheme` / `HC_RESOURCE_SCHEME`](docs/configuration.md#hc_resource_scheme)
|
|
198
|
-
(e.g. `wiki` → `wiki://topology`, `wiki://article/{id}`).
|
|
199
|
-
|
|
200
|
-
## Prerequisites
|
|
201
|
-
|
|
202
|
-
- **Node.js** >= 20 (runtime — declared in `package.json#engines.node`)
|
|
203
|
-
- A **Zendesk** instance (Support or Suite)
|
|
204
|
-
|
|
205
|
-
> Contributors and maintainers run the toolchain on a newer Node + pnpm —
|
|
206
|
-
> see [Development](#development).
|
|
82
|
+
There is no API-token authentication. The server speaks OAuth 2.1 PKCE and
|
|
83
|
+
nothing else: no `ZENDESK_EMAIL` + `ZENDESK_API_TOKEN` (Basic auth) mode, in any
|
|
84
|
+
transport. That is deliberate, for two reasons.
|
|
85
|
+
|
|
86
|
+
1. **API tokens are insufficiently secure.** A Zendesk API token is a
|
|
87
|
+
long-lived, static, shared secret that carries the full rights of the user
|
|
88
|
+
who issued it. There is no per-user scoping, no short expiry, and no per-user
|
|
89
|
+
consent or revocation. OAuth 2.1 PKCE issues per-user, revocable tokens
|
|
90
|
+
instead.
|
|
91
|
+
2. **API tokens don't scale.** A single static credential can't attribute
|
|
92
|
+
actions to individual users, and it can't be revoked granularly. It also
|
|
93
|
+
makes a multi-user remote deployment unsafe: over HTTP it would expose the
|
|
94
|
+
issuing user's rights to every caller.
|
|
95
|
+
|
|
96
|
+
If you specifically need an API-token or service-account mode (headless CI with
|
|
97
|
+
a shared account, say), use one of the other Zendesk MCP servers that support
|
|
98
|
+
it. A few are listed under
|
|
99
|
+
[Inspiration & related projects](#inspiration--related-projects).
|
|
207
100
|
|
|
208
101
|
## Quick start: local (stdio)
|
|
209
102
|
|
|
210
|
-
The default
|
|
103
|
+
The default shape: one developer, one Zendesk account, OAuth 2.1 PKCE in the
|
|
104
|
+
browser. You need **Node.js >= 20** and a **Zendesk** instance (Support or
|
|
105
|
+
Suite).
|
|
211
106
|
|
|
212
107
|
### Install
|
|
213
108
|
|
|
@@ -220,7 +115,7 @@ npm install -g @fruggr/zendesk-mcp-server
|
|
|
220
115
|
zendesk-mcp-server <your-subdomain>
|
|
221
116
|
```
|
|
222
117
|
|
|
223
|
-
|
|
118
|
+
Signing in needs a Zendesk OAuth client, so register one first (next section).
|
|
224
119
|
|
|
225
120
|
### Zendesk OAuth setup
|
|
226
121
|
|
|
@@ -231,34 +126,12 @@ zendesk-mcp-server <your-subdomain>
|
|
|
231
126
|
`ZENDESK_OAUTH_CALLBACK_PORT` / `--callback-port` if you override it; Zendesk
|
|
232
127
|
accepts several redirect URLs, one per line)
|
|
233
128
|
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
On the first tool call, the server starts the sign-in flow: it opens a browser
|
|
241
|
-
window **and** returns a tool message containing the authorize URL. The call
|
|
242
|
-
does not block waiting for sign-in — authenticate in the browser (or open the
|
|
243
|
-
URL manually if it didn't open), then retry the request.
|
|
244
|
-
|
|
245
|
-
Once authenticated, the token is **persisted to disk** (one owner-only `0600`
|
|
246
|
-
file per subdomain in your OS config dir —
|
|
247
|
-
`%APPDATA%\fruggr\zendesk-mcp-server\<subdomain>.json` on Windows,
|
|
248
|
-
`${XDG_CONFIG_HOME:-~/.config}/fruggr/zendesk-mcp-server/<subdomain>.json`
|
|
249
|
-
elsewhere; override the path with `ZENDESK_TOKEN_FILE`). It is reused across restarts, so you don't
|
|
250
|
-
re-authenticate every time the MCP client respawns the server. If the Zendesk
|
|
251
|
-
OAuth client has token expiration enabled, the stored refresh token is used to
|
|
252
|
-
renew access silently — **proactively** (the token is refreshed before use when
|
|
253
|
-
it's expired, near expiry, or of unknown age, so the first request after an
|
|
254
|
-
overnight gap never hits a visible auth error) and **periodically** in the
|
|
255
|
-
background so a long-lived, idle session never serves a stale token. Only an
|
|
256
|
-
expired/invalid refresh token triggers a new browser sign-in.
|
|
257
|
-
|
|
258
|
-
> **Port conflict?** If port `27439` is already in use the first tool call returns
|
|
259
|
-
> a clear error telling you to set `ZENDESK_OAUTH_CALLBACK_PORT` (or
|
|
260
|
-
> `--callback-port`) to a free port — remember to register the matching
|
|
261
|
-
> `http://localhost:<port>/callback` redirect URL in your Zendesk OAuth client.
|
|
129
|
+
On the first tool call the server starts the sign-in flow: it opens a browser
|
|
130
|
+
window and returns the authorize URL in a tool message. The call does not block
|
|
131
|
+
waiting for sign-in, so authenticate in the browser and then retry the request.
|
|
132
|
+
The token is persisted to an owner-only file and reused across restarts, so you
|
|
133
|
+
don't authenticate again every time your MCP client respawns the server (path
|
|
134
|
+
and overrides: [`ZENDESK_TOKEN_FILE`](docs/configuration.md#zendesk_token_file)).
|
|
262
135
|
|
|
263
136
|
### MCP client wiring
|
|
264
137
|
|
|
@@ -307,91 +180,87 @@ Add to your `.vscode/mcp.json`:
|
|
|
307
180
|
|
|
308
181
|
</details>
|
|
309
182
|
|
|
183
|
+
Something not working? See [Troubleshooting](docs/troubleshooting.md).
|
|
184
|
+
|
|
310
185
|
## Quick start: remote (HTTP)
|
|
311
186
|
|
|
312
|
-
>
|
|
313
|
-
> end-to-end against a real Zendesk tenant from every MCP client
|
|
187
|
+
> **Experimental.** The HTTP transport ships, but it has not yet been exercised
|
|
188
|
+
> end-to-end against a real Zendesk tenant from every MCP client. Local stdio is
|
|
314
189
|
> the supported path.
|
|
315
190
|
|
|
316
|
-
You can also deploy a private remote MCP server for **one** Zendesk account,
|
|
317
|
-
every MCP client presents its **own** user's OAuth bearer in
|
|
318
|
-
server never sees a shared admin key
|
|
319
|
-
behind a reverse proxy, per-platform config,
|
|
320
|
-
wiring, CORS and
|
|
321
|
-
**[docs/http-deployment.md](docs/http-deployment.md)**.
|
|
191
|
+
You can also deploy a private remote MCP server for **one** Zendesk account,
|
|
192
|
+
where every MCP client presents its **own** user's OAuth bearer in
|
|
193
|
+
`Authorization:` and the server never sees a shared admin key. The full guide
|
|
194
|
+
covers OAuth setup, `--public-url` behind a reverse proxy, per-platform config,
|
|
195
|
+
the discovery endpoints, MCP client wiring, CORS and what stays the operator's
|
|
196
|
+
job: **[docs/http-deployment.md](docs/http-deployment.md)**.
|
|
322
197
|
|
|
323
|
-
##
|
|
198
|
+
## Tool surface
|
|
324
199
|
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
**[docs/configuration.md](docs/configuration.md)** — with a per-variable anchor so
|
|
329
|
-
you can deep-link a specific setting.
|
|
200
|
+
Tools are grouped into four namespaces: **Tickets**, **Help Center**, **Users &
|
|
201
|
+
Organizations** and **Search**. The server registers them in one of three modes,
|
|
202
|
+
so you can trade granularity against context budget:
|
|
330
203
|
|
|
331
|
-
|
|
204
|
+
- **`all`**: every operation as its own tool, for clients with good tool selection;
|
|
205
|
+
- **`namespace`** (default): one proxy tool per namespace, a balanced middle ground;
|
|
206
|
+
- **`single`**: a single `zendesk` tool, for models with limited tool slots.
|
|
332
207
|
|
|
333
|
-
|
|
208
|
+
Proxies take `{ "operation": "<tool_name>", "params": { … } }` and validate
|
|
209
|
+
`params` through the original schema. `--namespace`, `--tool` and `--read-only`
|
|
210
|
+
filter tools *before* the proxies are built, so each proxy describes only the
|
|
211
|
+
operations that survive.
|
|
334
212
|
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
with `LOG_LEVEL=debug` for the full OAuth flow trace.
|
|
213
|
+
Every tool with its description and its `read`/`write` mode:
|
|
214
|
+
**[docs/mcp-tools-reference.md](docs/mcp-tools-reference.md)**. The flags and
|
|
215
|
+
worked examples: **[docs/configuration.md](docs/configuration.md)**.
|
|
339
216
|
|
|
340
|
-
##
|
|
217
|
+
## Help Center context
|
|
341
218
|
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
219
|
+
Beyond tools, the server hands the LLM the structure of *your* Help Center: the
|
|
220
|
+
active locales, the category → section tree with IDs, the visibility segments
|
|
221
|
+
and the permission groups. With those in hand it uses real IDs instead of
|
|
222
|
+
guessing or fuzzy-matching names. It all arrives through MCP-native channels,
|
|
223
|
+
namely the `instructions` blob sent on `initialize` plus pull-only resources for
|
|
224
|
+
the topology and for reading (or pinning) individual articles. The resources are
|
|
225
|
+
fetched with the caller's own token, and clients that don't support resources
|
|
226
|
+
ignore them silently.
|
|
345
227
|
|
|
346
|
-
|
|
228
|
+
What's exposed, what the promoted-article pre-listing costs in requests, and how
|
|
229
|
+
to turn each piece off: **[docs/help-center-context.md](docs/help-center-context.md)**.
|
|
347
230
|
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
-
|
|
231
|
+
## Configuration
|
|
232
|
+
|
|
233
|
+
The complete reference for the CLI flags (`--mode`, `--namespace`,
|
|
234
|
+
`--read-only`, `--transport`, `--public-url`, and so on) and the environment
|
|
235
|
+
variables (`ZENDESK_SUBDOMAIN`, `ZENDESK_TOKEN_FILE`, `PUBLIC_URL`, the
|
|
236
|
+
attachment-vision caps) lives in
|
|
237
|
+
**[docs/configuration.md](docs/configuration.md)**. Every variable has its own
|
|
238
|
+
anchor, so you can deep-link a specific setting.
|
|
352
239
|
|
|
353
|
-
##
|
|
240
|
+
## Troubleshooting
|
|
354
241
|
|
|
355
|
-
|
|
242
|
+
Browser not opening during OAuth login, the callback port already in use, having
|
|
243
|
+
to re-authenticate every time, and `Permission denied` on the Guide-admin
|
|
244
|
+
endpoints are covered in **[docs/troubleshooting.md](docs/troubleshooting.md)**.
|
|
245
|
+
Restart with `LOG_LEVEL=debug` for the full OAuth flow trace.
|
|
356
246
|
|
|
357
|
-
|
|
358
|
-
|---|---|
|
|
359
|
-
| `fix:`, `perf:` | patch |
|
|
360
|
-
| `feat:` | minor |
|
|
361
|
-
| `feat!:`, `fix!:`, or a `BREAKING CHANGE:` footer | major |
|
|
362
|
-
| `docs:`, `chore:`, `refactor:`, `test:`, `ci:`, `style:`, `build:` | no release |
|
|
247
|
+
## Development
|
|
363
248
|
|
|
364
|
-
|
|
249
|
+
Setting up the repo, the toolchain, dev mode and how to test a PR branch are
|
|
250
|
+
covered in **[CONTRIBUTING.md](CONTRIBUTING.md#development-setup)**. Architecture
|
|
251
|
+
and code-style conventions live in [`AGENTS.md`](AGENTS.md).
|
|
365
252
|
|
|
366
|
-
|
|
367
|
-
No — and the server doesn't support one. The OAuth 2.1 PKCE flow means each user
|
|
368
|
-
authenticates with their own credentials and the server acts with exactly their
|
|
369
|
-
permissions. Static API tokens are intentionally unsupported (see
|
|
370
|
-
[What this server does *not* do](#what-this-server-does-not-do)).
|
|
253
|
+
## FAQ
|
|
371
254
|
|
|
372
255
|
**Which Zendesk products are supported?**
|
|
373
256
|
Zendesk Support (tickets, users, organizations) and the Help Center / Guide
|
|
374
257
|
(articles, sections, categories, translations, labels, content tags, segments,
|
|
375
|
-
attachments). Talk, Explore
|
|
376
|
-
|
|
377
|
-
**How do I keep the model's context small?**
|
|
378
|
-
Use `--mode single` (one `zendesk` tool) or `--mode namespace` (three proxies),
|
|
379
|
-
and `--read-only` to drop write operations. For big articles, the section-based
|
|
380
|
-
tools (`get_article_outline`, `get_article_section`, `update_article_section`)
|
|
381
|
-
let the model touch one section at a time instead of the whole HTML body.
|
|
382
|
-
|
|
383
|
-
**Can I restrict it to read-only?**
|
|
384
|
-
Yes — pass `--read-only` and every write tool is filtered out before the proxies
|
|
385
|
-
are built, in any mode.
|
|
258
|
+
attachments). Talk, Explore and Sell are out of scope.
|
|
386
259
|
|
|
387
|
-
**
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
**The OAuth browser window didn't open. What now?**
|
|
392
|
-
The authorization URL is also printed to stderr — open it manually. Restart with
|
|
393
|
-
`LOG_LEVEL=debug` for the full flow trace. See
|
|
394
|
-
[Troubleshooting](#troubleshooting).
|
|
260
|
+
**Do I need a Zendesk admin API key?**
|
|
261
|
+
No, and the server doesn't support one. Each user authenticates with their own
|
|
262
|
+
credentials and the server acts with exactly their permissions
|
|
263
|
+
([why](#what-this-server-does-not-do)).
|
|
395
264
|
|
|
396
265
|
**Is it safe to run via `npx`?**
|
|
397
266
|
Releases are published from CI via npm Trusted Publishing (OIDC), so each version
|
|
@@ -401,18 +270,20 @@ are ever logged by the server.
|
|
|
401
270
|
|
|
402
271
|
## Contributing
|
|
403
272
|
|
|
404
|
-
Pull requests are welcome
|
|
273
|
+
Pull requests are welcome, AI-assisted ones included, as long as the human
|
|
274
|
+
author has read and validated every line. The guide, the author checklist and the
|
|
275
|
+
review workflow are in **[CONTRIBUTING.md](CONTRIBUTING.md)**.
|
|
405
276
|
|
|
406
|
-
|
|
277
|
+
Versions follow [SemVer](https://semver.org/) and are released automatically from
|
|
278
|
+
[Conventional Commits](https://www.conventionalcommits.org/); the history is in
|
|
279
|
+
[`CHANGELOG.md`](CHANGELOG.md).
|
|
407
280
|
|
|
408
|
-
|
|
409
|
-
2. Practice TDD: write the failing test first, then implement.
|
|
410
|
-
3. Use [Conventional Commits](https://www.conventionalcommits.org/) — they drive the next version bump via semantic-release.
|
|
411
|
-
4. Make `pnpm check`, `pnpm typecheck`, and `pnpm test` pass locally.
|
|
412
|
-
5. Run a Claude Code review on your diff before pushing.
|
|
413
|
-
6. Open a PR.
|
|
281
|
+
## Inspiration & related projects
|
|
414
282
|
|
|
415
|
-
|
|
283
|
+
This project was built with reference to:
|
|
284
|
+
- The official [Zendesk API documentation](https://developer.zendesk.com/api-reference/)
|
|
285
|
+
- [mattcoatsworth/zendesk-mcp-server](https://github.com/mattcoatsworth/zendesk-mcp-server)
|
|
286
|
+
- [koundinya/zd-mcp-server](https://github.com/koundinya/zd-mcp-server)
|
|
416
287
|
|
|
417
288
|
## License
|
|
418
289
|
|
package/dist/index.js
CHANGED
|
@@ -125,7 +125,8 @@ const positiveIntEnv = (name, fallback) => {
|
|
|
125
125
|
return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback;
|
|
126
126
|
};
|
|
127
127
|
const ARTICLE_RESOURCES_SCAN_MAX_PAGES = positiveIntEnv("ZENDESK_ARTICLE_RESOURCES_SCAN_MAX_PAGES", 20);
|
|
128
|
-
const
|
|
128
|
+
const TRANSLATION_GAP_SCAN_MAX_NODES = positiveIntEnv("ZENDESK_TRANSLATION_GAP_SCAN_MAX_NODES", 60);
|
|
129
|
+
const MAX_ATTACHMENT_BYTES = positiveIntEnv("ZENDESK_MAX_ATTACHMENT_BYTES", 5242880);
|
|
129
130
|
const MAX_EMBEDDED_IMAGE_COUNT = positiveIntEnv("ZENDESK_MAX_EMBEDDED_IMAGES", 10);
|
|
130
131
|
const MAX_COMMENT_PAGES = positiveIntEnv("ZENDESK_MAX_COMMENT_PAGES", 10);
|
|
131
132
|
const REORDER_CONFIRM_THRESHOLD = positiveIntEnv("ZENDESK_REORDER_CONFIRM_THRESHOLD", 20);
|
|
@@ -137,7 +138,7 @@ const getOAuthUrls = (subdomain) => ({
|
|
|
137
138
|
});
|
|
138
139
|
//#endregion
|
|
139
140
|
//#region src/auth/browser-oauth.ts
|
|
140
|
-
const AUTH_TIMEOUT_MS =
|
|
141
|
+
const AUTH_TIMEOUT_MS = 3e5;
|
|
141
142
|
/** Best-effort WSL detection: WSL kernels carry "microsoft" in /proc/version. */
|
|
142
143
|
const detectWsl = () => {
|
|
143
144
|
if (process.platform !== "linux") return false;
|
|
@@ -427,8 +428,12 @@ const appDirSegments = () => {
|
|
|
427
428
|
};
|
|
428
429
|
const configDir = () => {
|
|
429
430
|
const segments = appDirSegments();
|
|
430
|
-
if (isWindows)
|
|
431
|
-
|
|
431
|
+
if (isWindows) {
|
|
432
|
+
const base = process.env["APPDATA"] ?? join(homedir(), "AppData", "Roaming");
|
|
433
|
+
return join(base, ...segments);
|
|
434
|
+
}
|
|
435
|
+
const base = process.env["XDG_CONFIG_HOME"] ?? join(homedir(), ".config");
|
|
436
|
+
return join(base, ...segments);
|
|
432
437
|
};
|
|
433
438
|
const safeName = (subdomain) => subdomain.replace(/[^a-z0-9-]/gi, "_");
|
|
434
439
|
/**
|
|
@@ -479,7 +484,7 @@ const clearToken = (path, logger = silentLogger) => {
|
|
|
479
484
|
//#endregion
|
|
480
485
|
//#region src/auth/token-store.ts
|
|
481
486
|
const EXPIRY_SKEW_MS = 6e4;
|
|
482
|
-
const SCHEDULED_REFRESH_MS =
|
|
487
|
+
const SCHEDULED_REFRESH_MS = 144e5;
|
|
483
488
|
const createAuthRequiredError = (authorizeUrl) => Object.assign(/* @__PURE__ */ new Error("Zendesk authentication required. A browser window should have opened for you to sign in. If it did not, open this URL in your browser, then retry your request:\n" + authorizeUrl), {
|
|
484
489
|
name: "AuthRequiredError",
|
|
485
490
|
authorizeUrl
|
|
@@ -1259,6 +1264,13 @@ const formatTranslation = (translation) => [
|
|
|
1259
1264
|
"",
|
|
1260
1265
|
translation.body
|
|
1261
1266
|
].join("\n");
|
|
1267
|
+
const formatNodeTranslationSummary = (translation) => [
|
|
1268
|
+
`## Translation: ${translation.locale} (${translation.id})`,
|
|
1269
|
+
`- **Name**: ${translation.title}`,
|
|
1270
|
+
`- **Description**: ${translation.body ? "set" : "empty"}`,
|
|
1271
|
+
`- **Draft**: ${translation.draft}`,
|
|
1272
|
+
`- **Updated**: ${translation.updated_at}`
|
|
1273
|
+
].join("\n");
|
|
1262
1274
|
const formatCategory = (category) => `- **${category.name}** (${category.id}) — ${category.description || "No description"}`;
|
|
1263
1275
|
const formatSection = (section) => `- **${section.name}** (${section.id}) — Category: ${section.category_id} — ${section.description || "No description"}`;
|
|
1264
1276
|
const formatView = (view, count) => {
|
|
@@ -1359,12 +1371,14 @@ const fetchPromotedArticles = async (subdomain, token, maxPages = ARTICLE_RESOUR
|
|
|
1359
1371
|
* character limit. Reuses the same formatting as the `get_article` tool.
|
|
1360
1372
|
*/
|
|
1361
1373
|
const fetchArticleMarkdown = async (subdomain, token, id, locale) => {
|
|
1362
|
-
const
|
|
1363
|
-
|
|
1374
|
+
const path = locale ? `/${locale}/articles/${id}` : `/articles/${id}`;
|
|
1375
|
+
const { article } = await helpCenterGet(subdomain, token, path);
|
|
1376
|
+
const text = [
|
|
1364
1377
|
formatArticleSummary(article),
|
|
1365
1378
|
"",
|
|
1366
1379
|
htmlToMarkdown(article.body)
|
|
1367
|
-
].join("\n")
|
|
1380
|
+
].join("\n");
|
|
1381
|
+
return truncateIfNeeded(text);
|
|
1368
1382
|
};
|
|
1369
1383
|
/**
|
|
1370
1384
|
* Build an article-resources provider. `listPromoted` holds a memoized-promise
|
|
@@ -1592,7 +1606,7 @@ const renderAdminSection = (items, denied, deniedNote) => {
|
|
|
1592
1606
|
};
|
|
1593
1607
|
/** Render the topology as a compact Markdown document for the LLM context. */
|
|
1594
1608
|
const formatTopology = (data) => {
|
|
1595
|
-
|
|
1609
|
+
const text = [
|
|
1596
1610
|
`# Zendesk Help Center topology — ${data.subdomain}`,
|
|
1597
1611
|
"",
|
|
1598
1612
|
`**Your access**: ${data.currentUser.name} (id ${data.currentUser.id}), role "${data.currentUser.role}".`,
|
|
@@ -1609,7 +1623,8 @@ const formatTopology = (data) => {
|
|
|
1609
1623
|
"",
|
|
1610
1624
|
"## Permission groups",
|
|
1611
1625
|
...renderAdminSection(data.permissionGroups.map(formatPermissionGroup), data.permissionGroupsDenied, "_Unavailable: listing permission groups requires Guide-admin / Help Center manager rights, which this token lacks (HTTP 403). To create or edit an article, reuse the permission_group_id of an existing article (get_article)._")
|
|
1612
|
-
].join("\n")
|
|
1626
|
+
].join("\n");
|
|
1627
|
+
return truncateIfNeeded(text);
|
|
1613
1628
|
};
|
|
1614
1629
|
/**
|
|
1615
1630
|
* Build a topology provider holding a memoized-promise cache (TTL
|
|
@@ -1737,6 +1752,117 @@ const isPlacedAsRequested = (effectiveAfter, movedId, target, referenceId) => {
|
|
|
1737
1752
|
//#region src/tools/help-center.ts
|
|
1738
1753
|
const ARTICLE_ID_DESC = "Article ID — the numeric id of the Help Center article. Obtain it from list_articles or search_articles.";
|
|
1739
1754
|
const listTranslations = (subdomain, token, articleId) => helpCenterGet(subdomain, token, `/articles/${articleId}/translations`).then((res) => res.translations);
|
|
1755
|
+
const NODE_LABEL = {
|
|
1756
|
+
sections: "section",
|
|
1757
|
+
categories: "category"
|
|
1758
|
+
};
|
|
1759
|
+
const listNodeTranslations = (subdomain, token, kind, nodeId, locale) => helpCenterGet(subdomain, token, `/${kind}/${nodeId}/translations`, locale ? { locales: locale.toLowerCase() } : void 0).then((res) => res.translations ?? []);
|
|
1760
|
+
const findTranslation = (translations, locale) => {
|
|
1761
|
+
const wanted = locale.toLowerCase();
|
|
1762
|
+
return translations.find((t) => t.locale.toLowerCase() === wanted);
|
|
1763
|
+
};
|
|
1764
|
+
/**
|
|
1765
|
+
* Create-or-update a section/category translation in one call. The POST-vs-PUT
|
|
1766
|
+
* probe spares the caller a listing round-trip, or the 400 a duplicate POST
|
|
1767
|
+
* returns. Only the fields passed are sent on update, so omitting `description`
|
|
1768
|
+
* never blanks it and omitting `draft` never (un)publishes by accident.
|
|
1769
|
+
*/
|
|
1770
|
+
const upsertNodeTranslation = async (subdomain, token, kind, nodeId, input) => {
|
|
1771
|
+
const { locale, name, description, draft } = input;
|
|
1772
|
+
const existing = findTranslation(await listNodeTranslations(subdomain, token, kind, nodeId, locale), locale);
|
|
1773
|
+
if (!existing) {
|
|
1774
|
+
if (name === void 0) throw new Error(`${NODE_LABEL[kind]} #${nodeId} has no "${locale}" translation yet, so one has to be created and "name" is required. Pass the localized name, or call list_${NODE_LABEL[kind]}_translations to see which locales already exist.`);
|
|
1775
|
+
const { translation } = await helpCenterPost(subdomain, token, `/${kind}/${nodeId}/translations`, { translation: {
|
|
1776
|
+
locale,
|
|
1777
|
+
title: name,
|
|
1778
|
+
body: description ?? "",
|
|
1779
|
+
draft: draft ?? false
|
|
1780
|
+
} });
|
|
1781
|
+
return {
|
|
1782
|
+
translation,
|
|
1783
|
+
created: true
|
|
1784
|
+
};
|
|
1785
|
+
}
|
|
1786
|
+
const updates = {};
|
|
1787
|
+
if (name !== void 0) updates["title"] = name;
|
|
1788
|
+
if (description !== void 0) updates["body"] = description;
|
|
1789
|
+
if (draft !== void 0) updates["draft"] = draft;
|
|
1790
|
+
if (Object.keys(updates).length === 0) throw new Error(`Nothing to write: ${NODE_LABEL[kind]} #${nodeId} already has a "${existing.locale}" translation, so pass at least one of "name", "description" or "draft" to change it (draft: false publishes it).`);
|
|
1791
|
+
const { translation } = await helpCenterPut(subdomain, token, `/${kind}/${nodeId}/translations/${existing.locale}`, { translation: updates });
|
|
1792
|
+
return {
|
|
1793
|
+
translation,
|
|
1794
|
+
created: false
|
|
1795
|
+
};
|
|
1796
|
+
};
|
|
1797
|
+
const nodeTranslationWriteText = (kind, nodeId, translation, created) => [
|
|
1798
|
+
`Translation ${created ? "created" : "updated"} for ${NODE_LABEL[kind]} #${nodeId} in "${translation.locale}" (${translation.draft ? "draft, not visible to end users" : "published"}).`,
|
|
1799
|
+
"",
|
|
1800
|
+
formatNodeTranslationSummary(translation)
|
|
1801
|
+
].join("\n");
|
|
1802
|
+
const GAP_REASON_TEXT = {
|
|
1803
|
+
missing: "no translation",
|
|
1804
|
+
draft: "draft translation (not published)"
|
|
1805
|
+
};
|
|
1806
|
+
const classifyGap = (node, translations, locale) => {
|
|
1807
|
+
const translation = findTranslation(translations, locale);
|
|
1808
|
+
if (!translation) return {
|
|
1809
|
+
id: node.id,
|
|
1810
|
+
name: node.name,
|
|
1811
|
+
reason: "missing"
|
|
1812
|
+
};
|
|
1813
|
+
return translation.draft ? {
|
|
1814
|
+
id: node.id,
|
|
1815
|
+
name: node.name,
|
|
1816
|
+
reason: "draft"
|
|
1817
|
+
} : null;
|
|
1818
|
+
};
|
|
1819
|
+
const renderGapLines = (heading, gaps, scanned, found) => {
|
|
1820
|
+
const header = `## ${heading} (${scanned} scanned)`;
|
|
1821
|
+
if (gaps.length > 0) return [header, ...gaps.map((gap) => `- **${gap.name}** (${gap.id}) — ${GAP_REASON_TEXT[gap.reason]}`)];
|
|
1822
|
+
if (scanned === 0) return [header, found === 0 ? "_(none to scan at this level)_" : `_(none scanned — the ${TRANSLATION_GAP_SCAN_MAX_NODES}-node cap was spent before this level; ${found} left unchecked, see the note below)_`];
|
|
1823
|
+
return [header, "_(none — every one scanned has a published translation)_"];
|
|
1824
|
+
};
|
|
1825
|
+
const GAP_SCAN_WAVE_SIZE = 5;
|
|
1826
|
+
const probeInWaves = async (nodes, probe) => {
|
|
1827
|
+
const gaps = [];
|
|
1828
|
+
for (let i = 0; i < nodes.length; i += GAP_SCAN_WAVE_SIZE) {
|
|
1829
|
+
const wave = await Promise.all(nodes.slice(i, i + GAP_SCAN_WAVE_SIZE).map(probe));
|
|
1830
|
+
for (const gap of wave) if (gap !== null) gaps.push(gap);
|
|
1831
|
+
}
|
|
1832
|
+
return gaps;
|
|
1833
|
+
};
|
|
1834
|
+
const fetchGapCategories = async (subdomain, token, categoryId) => {
|
|
1835
|
+
if (categoryId !== void 0) {
|
|
1836
|
+
const { category } = await helpCenterGet(subdomain, token, `/categories/${categoryId}`);
|
|
1837
|
+
return {
|
|
1838
|
+
categories: [category],
|
|
1839
|
+
hasMore: false
|
|
1840
|
+
};
|
|
1841
|
+
}
|
|
1842
|
+
const response = await helpCenterGet(subdomain, token, "/categories", buildCursorParams(100, void 0));
|
|
1843
|
+
const categories = response.categories ?? [];
|
|
1844
|
+
return {
|
|
1845
|
+
categories,
|
|
1846
|
+
hasMore: extractPaginationMeta(response, categories.length).has_more
|
|
1847
|
+
};
|
|
1848
|
+
};
|
|
1849
|
+
const renderGapReport = (report) => {
|
|
1850
|
+
const { locale, categoryGaps, sectionGaps, scanned, found } = report;
|
|
1851
|
+
const gapCount = categoryGaps.length + sectionGaps.length;
|
|
1852
|
+
const capped = scanned.categories < found.categories || scanned.sections < found.sections;
|
|
1853
|
+
return truncateIfNeeded([
|
|
1854
|
+
`# Translation gaps — "${locale}"`,
|
|
1855
|
+
"",
|
|
1856
|
+
...report.activeLocales.some((l) => l.toLowerCase() === locale.toLowerCase()) ? [] : [`> ⚠ "${locale}" is not an active locale of this Help Center (active: ${report.activeLocales.join(", ")}), so everything below reads as untranslated. Check the spelling, or activate the language in Guide first.`, ""],
|
|
1857
|
+
...renderGapLines("Categories", categoryGaps, scanned.categories, found.categories),
|
|
1858
|
+
"",
|
|
1859
|
+
...renderGapLines("Sections", sectionGaps, scanned.sections, found.sections),
|
|
1860
|
+
"",
|
|
1861
|
+
gapCount === 0 ? `No gaps: all ${scanned.categories} category/ies and ${scanned.sections} section(s) scanned have a published "${locale}" translation.` : `${gapCount} node(s) need a published "${locale}" translation. Fix a category with set_category_translation and a section with set_section_translation, passing draft: false to publish.`,
|
|
1862
|
+
...capped ? ["", `_Note: the scan stopped at its ${TRANSLATION_GAP_SCAN_MAX_NODES}-node cap, covering ${scanned.categories}/${found.categories} categories and ${scanned.sections}/${found.sections} sections. The rest were not checked — narrow the scan with category_id, or raise ZENDESK_TRANSLATION_GAP_SCAN_MAX_NODES._`] : [],
|
|
1863
|
+
...report.listingIncomplete ? ["", `_Note: this Help Center has more than 100 categories or sections, so only the first page of each was considered. Narrow the scan with category_id to audit the rest._`] : []
|
|
1864
|
+
].join("\n"));
|
|
1865
|
+
};
|
|
1740
1866
|
const largeArticleHint = (body, sectionCount) => {
|
|
1741
1867
|
if (body.length < 3e3 && sectionCount < 4) return null;
|
|
1742
1868
|
return [
|
|
@@ -1894,9 +2020,10 @@ const createHelpCenterTools = (ctx) => {
|
|
|
1894
2020
|
const path = locale ? `/${locale}/articles/${article_id}` : `/articles/${article_id}`;
|
|
1895
2021
|
const { article } = await helpCenterGet(subdomain, token, path);
|
|
1896
2022
|
const translations = await listTranslations(subdomain, token, article_id);
|
|
2023
|
+
const text = (largeArticleHint(article.body, parseSections(article.body).length) ?? "") + formatArticle(article) + `\n\n**Available translations**: ${translations.map((t) => t.locale).join(", ")}`;
|
|
1897
2024
|
return { content: [{
|
|
1898
2025
|
type: "text",
|
|
1899
|
-
text: truncateIfNeeded(
|
|
2026
|
+
text: truncateIfNeeded(text)
|
|
1900
2027
|
}] };
|
|
1901
2028
|
}
|
|
1902
2029
|
},
|
|
@@ -2002,9 +2129,10 @@ const createHelpCenterTools = (ctx) => {
|
|
|
2002
2129
|
return `${formatArticleSummary(article)}\n- **Translations**: ${locales}`;
|
|
2003
2130
|
}));
|
|
2004
2131
|
const meta = extractPaginationMeta(response, articles.length);
|
|
2132
|
+
const text = [meta.count ? `Results: ${meta.count}${meta.has_more ? ` | More available (cursor: ${meta.after_cursor})` : ""}` : "", ...formatted].filter(Boolean).join("\n\n");
|
|
2005
2133
|
return { content: [{
|
|
2006
2134
|
type: "text",
|
|
2007
|
-
text: truncateIfNeeded(
|
|
2135
|
+
text: truncateIfNeeded(text)
|
|
2008
2136
|
}] };
|
|
2009
2137
|
}
|
|
2010
2138
|
},
|
|
@@ -2027,9 +2155,10 @@ const createHelpCenterTools = (ctx) => {
|
|
|
2027
2155
|
const header = `Promoted (featured) articles: ${articles.length}`;
|
|
2028
2156
|
const body = articles.length ? articles.map(formatArticleSummary).join("\n\n") : "_No promoted articles found._";
|
|
2029
2157
|
const cost = `${pagesScanned} Zendesk API request${pagesScanned === 1 ? "" : "s"}`;
|
|
2158
|
+
const note = scanCostNote(truncated, pagesScanned, cost);
|
|
2030
2159
|
return { content: [{
|
|
2031
2160
|
type: "text",
|
|
2032
|
-
text: truncateIfNeeded(`${header}\n\n${body}${
|
|
2161
|
+
text: truncateIfNeeded(`${header}\n\n${body}${note}`)
|
|
2033
2162
|
}] };
|
|
2034
2163
|
}
|
|
2035
2164
|
},
|
|
@@ -2049,9 +2178,10 @@ const createHelpCenterTools = (ctx) => {
|
|
|
2049
2178
|
handler: async (params) => {
|
|
2050
2179
|
const { article_id } = params;
|
|
2051
2180
|
const token = await getToken();
|
|
2181
|
+
const translations = await listTranslations(subdomain, token, article_id);
|
|
2052
2182
|
return { content: [{
|
|
2053
2183
|
type: "text",
|
|
2054
|
-
text: formatList(
|
|
2184
|
+
text: formatList(translations, formatTranslationSummary)
|
|
2055
2185
|
}] };
|
|
2056
2186
|
}
|
|
2057
2187
|
},
|
|
@@ -2118,6 +2248,160 @@ const createHelpCenterTools = (ctx) => {
|
|
|
2118
2248
|
}] };
|
|
2119
2249
|
}
|
|
2120
2250
|
},
|
|
2251
|
+
{
|
|
2252
|
+
name: "list_section_translations",
|
|
2253
|
+
namespace: "help_center",
|
|
2254
|
+
readOnly: true,
|
|
2255
|
+
title: "List Section Translations",
|
|
2256
|
+
description: "List the translations of a Help Center section: for each locale, the localized name, whether a description is set, and whether the translation is published or still a draft. Reach for this when a section looks wrong in a locale, because list_sections with that locale cannot settle it: a section with no translation is omitted from it, while a section whose translation is an unpublished draft may still be listed there under the draft name — so appearing in that listing does not mean published, and the draft flag here is what decides. Fix either case with set_section_translation; to sweep every category and section at once, use find_translation_gaps.",
|
|
2257
|
+
inputSchema: z.object({ section_id: z.number().int().describe("Section ID — the numeric id of the Help Center section. Obtain it from list_sections or the zendesk-hc://topology resource.") }),
|
|
2258
|
+
annotations: {
|
|
2259
|
+
readOnlyHint: true,
|
|
2260
|
+
destructiveHint: false,
|
|
2261
|
+
idempotentHint: true,
|
|
2262
|
+
openWorldHint: true
|
|
2263
|
+
},
|
|
2264
|
+
handler: async (params) => {
|
|
2265
|
+
const { section_id } = params;
|
|
2266
|
+
const token = await getToken();
|
|
2267
|
+
const translations = await listNodeTranslations(subdomain, token, "sections", section_id);
|
|
2268
|
+
return { content: [{
|
|
2269
|
+
type: "text",
|
|
2270
|
+
text: formatList(translations, formatNodeTranslationSummary)
|
|
2271
|
+
}] };
|
|
2272
|
+
}
|
|
2273
|
+
},
|
|
2274
|
+
{
|
|
2275
|
+
name: "list_category_translations",
|
|
2276
|
+
namespace: "help_center",
|
|
2277
|
+
readOnly: true,
|
|
2278
|
+
title: "List Category Translations",
|
|
2279
|
+
description: "List the translations of a Help Center category: for each locale, the localized name, whether a description is set, and whether the translation is published or still a draft. Reach for this when a category looks wrong in a locale, because list_categories with that locale cannot settle it: a category with no translation is omitted from it, while a category whose translation is an unpublished draft may still be listed there under the draft name — so appearing in that listing does not mean published, and the draft flag here is what decides. Fix either case with set_category_translation; to sweep every category and section at once, use find_translation_gaps.",
|
|
2280
|
+
inputSchema: z.object({ category_id: z.number().int().describe("Category ID — the numeric id of the Help Center category. Obtain it from list_categories or the zendesk-hc://topology resource.") }),
|
|
2281
|
+
annotations: {
|
|
2282
|
+
readOnlyHint: true,
|
|
2283
|
+
destructiveHint: false,
|
|
2284
|
+
idempotentHint: true,
|
|
2285
|
+
openWorldHint: true
|
|
2286
|
+
},
|
|
2287
|
+
handler: async (params) => {
|
|
2288
|
+
const { category_id } = params;
|
|
2289
|
+
const token = await getToken();
|
|
2290
|
+
const translations = await listNodeTranslations(subdomain, token, "categories", category_id);
|
|
2291
|
+
return { content: [{
|
|
2292
|
+
type: "text",
|
|
2293
|
+
text: formatList(translations, formatNodeTranslationSummary)
|
|
2294
|
+
}] };
|
|
2295
|
+
}
|
|
2296
|
+
},
|
|
2297
|
+
{
|
|
2298
|
+
name: "find_translation_gaps",
|
|
2299
|
+
namespace: "help_center",
|
|
2300
|
+
readOnly: true,
|
|
2301
|
+
title: "Find Help Center Translation Gaps",
|
|
2302
|
+
description: "Audit the Help Center tree for a target locale and report every category and section that has no translation, or one that is still an unpublished draft. Use it before or after translating articles: an article published in a second locale is unreachable while its parent section only exists in the source locale. Listing sections in that locale cannot answer this — a node with no translation is simply absent, without saying why, and a node whose translation is an unpublished draft may still be listed under its draft name — so this audit reads the draft flag on each node instead of trusting that listing. Costs one extra request per node scanned, capped (the report says so when the cap bites) — pass category_id to narrow it. Fix what it reports with set_section_translation / set_category_translation.",
|
|
2303
|
+
inputSchema: z.object({
|
|
2304
|
+
locale: z.string().describe("Locale to audit, e.g. \"fr\" or \"de\" — usually a non-default active locale of the Help Center (zendesk-hc://topology lists them). A locale that is not active is reported as a warning, since every node would then look untranslated."),
|
|
2305
|
+
category_id: z.number().int().optional().describe("Restrict the audit to this category and the sections it contains (id from list_categories). Omit to sweep the whole tree, which costs one request per category and per section.")
|
|
2306
|
+
}),
|
|
2307
|
+
annotations: {
|
|
2308
|
+
readOnlyHint: true,
|
|
2309
|
+
destructiveHint: false,
|
|
2310
|
+
idempotentHint: true,
|
|
2311
|
+
openWorldHint: true
|
|
2312
|
+
},
|
|
2313
|
+
handler: async (params) => {
|
|
2314
|
+
const { locale, category_id } = params;
|
|
2315
|
+
const token = await getToken();
|
|
2316
|
+
const [locales, categoryScope, sectionsRes] = await Promise.all([
|
|
2317
|
+
helpCenterGet(subdomain, token, "/locales"),
|
|
2318
|
+
fetchGapCategories(subdomain, token, category_id),
|
|
2319
|
+
helpCenterGet(subdomain, token, sectionListPath(category_id, void 0), buildCursorParams(100, void 0))
|
|
2320
|
+
]);
|
|
2321
|
+
const allCategories = categoryScope.categories;
|
|
2322
|
+
const allSections = sectionsRes.sections ?? [];
|
|
2323
|
+
const categories = allCategories.slice(0, TRANSLATION_GAP_SCAN_MAX_NODES);
|
|
2324
|
+
const sections = allSections.slice(0, Math.max(0, TRANSLATION_GAP_SCAN_MAX_NODES - categories.length));
|
|
2325
|
+
const categoryGaps = await probeInWaves(categories, async (category) => classifyGap(category, await listNodeTranslations(subdomain, token, "categories", category.id, locale), locale));
|
|
2326
|
+
const sectionGaps = await probeInWaves(sections, async (section) => classifyGap(section, await listNodeTranslations(subdomain, token, "sections", section.id, locale), locale));
|
|
2327
|
+
return { content: [{
|
|
2328
|
+
type: "text",
|
|
2329
|
+
text: renderGapReport({
|
|
2330
|
+
locale,
|
|
2331
|
+
activeLocales: locales.locales ?? [],
|
|
2332
|
+
categoryGaps,
|
|
2333
|
+
sectionGaps,
|
|
2334
|
+
scanned: {
|
|
2335
|
+
categories: categories.length,
|
|
2336
|
+
sections: sections.length
|
|
2337
|
+
},
|
|
2338
|
+
found: {
|
|
2339
|
+
categories: allCategories.length,
|
|
2340
|
+
sections: allSections.length
|
|
2341
|
+
},
|
|
2342
|
+
listingIncomplete: categoryScope.hasMore || extractPaginationMeta(sectionsRes, allSections.length).has_more
|
|
2343
|
+
})
|
|
2344
|
+
}] };
|
|
2345
|
+
}
|
|
2346
|
+
},
|
|
2347
|
+
{
|
|
2348
|
+
name: "set_section_translation",
|
|
2349
|
+
namespace: "help_center",
|
|
2350
|
+
readOnly: false,
|
|
2351
|
+
title: "Create or Update a Section Translation",
|
|
2352
|
+
description: "Create or update the translation of a Help Center section in one locale, and return the resulting translation (locale, localized name, draft state). Creates the translation when the locale has none and updates it otherwise, so no listing call is needed first; only the fields you pass are written, which makes \"publish this draft\" a single draft: false. Use it to make a section reachable in a locale where its articles are already translated — a gap find_translation_gaps reports and list_sections cannot explain.",
|
|
2353
|
+
inputSchema: z.object({
|
|
2354
|
+
section_id: z.number().int().describe("Section ID — the numeric id of the section whose translation to write. Obtain it from list_sections, find_translation_gaps or the zendesk-hc://topology resource."),
|
|
2355
|
+
locale: z.string().describe("Locale to write, e.g. \"fr\" or \"de\". Must be an active locale of the Help Center (zendesk-hc://topology lists them); list_section_translations shows which ones the section already has."),
|
|
2356
|
+
name: z.string().min(1).optional().describe("Localized section name for this locale (sent as the API's translation `title`). Required when the locale has no translation yet; omit on an existing one to leave its name untouched, for instance when only publishing a draft."),
|
|
2357
|
+
description: z.string().optional().describe("Localized section description for this locale (sent as the API's translation `body`). Omit to leave an existing description untouched; pass an empty string to clear it."),
|
|
2358
|
+
draft: z.boolean().optional().describe("Publication state: false publishes the translation, making the section visible to end users in this locale; true keeps (or puts) it back as a draft. Defaults to false when creating; omit on an existing translation to leave its state unchanged.")
|
|
2359
|
+
}),
|
|
2360
|
+
annotations: {
|
|
2361
|
+
readOnlyHint: false,
|
|
2362
|
+
destructiveHint: true,
|
|
2363
|
+
idempotentHint: true,
|
|
2364
|
+
openWorldHint: true
|
|
2365
|
+
},
|
|
2366
|
+
handler: async (params) => {
|
|
2367
|
+
const { section_id, ...input } = params;
|
|
2368
|
+
const token = await getToken();
|
|
2369
|
+
const { translation, created } = await upsertNodeTranslation(subdomain, token, "sections", section_id, input);
|
|
2370
|
+
return { content: [{
|
|
2371
|
+
type: "text",
|
|
2372
|
+
text: nodeTranslationWriteText("sections", section_id, translation, created)
|
|
2373
|
+
}] };
|
|
2374
|
+
}
|
|
2375
|
+
},
|
|
2376
|
+
{
|
|
2377
|
+
name: "set_category_translation",
|
|
2378
|
+
namespace: "help_center",
|
|
2379
|
+
readOnly: false,
|
|
2380
|
+
title: "Create or Update a Category Translation",
|
|
2381
|
+
description: "Create or update the translation of a Help Center category in one locale, and return the resulting translation (locale, localized name, draft state). Creates the translation when the locale has none and updates it otherwise, so no listing call is needed first; only the fields you pass are written, which makes \"publish this draft\" a single draft: false. Use it to make a category reachable in a locale where its sections or articles are already translated — a gap find_translation_gaps reports and list_categories cannot explain.",
|
|
2382
|
+
inputSchema: z.object({
|
|
2383
|
+
category_id: z.number().int().describe("Category ID — the numeric id of the category whose translation to write. Obtain it from list_categories, find_translation_gaps or the zendesk-hc://topology resource."),
|
|
2384
|
+
locale: z.string().describe("Locale to write, e.g. \"fr\" or \"de\". Must be an active locale of the Help Center (zendesk-hc://topology lists them); list_category_translations shows which ones the category already has."),
|
|
2385
|
+
name: z.string().min(1).optional().describe("Localized category name for this locale (sent as the API's translation `title`). Required when the locale has no translation yet; omit on an existing one to leave its name untouched, for instance when only publishing a draft."),
|
|
2386
|
+
description: z.string().optional().describe("Localized category description for this locale (sent as the API's translation `body`). Omit to leave an existing description untouched; pass an empty string to clear it."),
|
|
2387
|
+
draft: z.boolean().optional().describe("Publication state: false publishes the translation, making the category visible to end users in this locale; true keeps (or puts) it back as a draft. Defaults to false when creating; omit on an existing translation to leave its state unchanged.")
|
|
2388
|
+
}),
|
|
2389
|
+
annotations: {
|
|
2390
|
+
readOnlyHint: false,
|
|
2391
|
+
destructiveHint: true,
|
|
2392
|
+
idempotentHint: true,
|
|
2393
|
+
openWorldHint: true
|
|
2394
|
+
},
|
|
2395
|
+
handler: async (params) => {
|
|
2396
|
+
const { category_id, ...input } = params;
|
|
2397
|
+
const token = await getToken();
|
|
2398
|
+
const { translation, created } = await upsertNodeTranslation(subdomain, token, "categories", category_id, input);
|
|
2399
|
+
return { content: [{
|
|
2400
|
+
type: "text",
|
|
2401
|
+
text: nodeTranslationWriteText("categories", category_id, translation, created)
|
|
2402
|
+
}] };
|
|
2403
|
+
}
|
|
2404
|
+
},
|
|
2121
2405
|
{
|
|
2122
2406
|
name: "list_permission_groups",
|
|
2123
2407
|
namespace: "help_center",
|
|
@@ -2250,7 +2534,8 @@ const createHelpCenterTools = (ctx) => {
|
|
|
2250
2534
|
const effective = await fetchSectionOrder(sectionId, locale, token);
|
|
2251
2535
|
if (reference_article_id !== void 0) await assertReferenceInSection(effective, reference_article_id, article_id, sectionId, token);
|
|
2252
2536
|
const targetLabel = needsReference ? `${target} article #${reference_article_id}` : target;
|
|
2253
|
-
const
|
|
2537
|
+
const desired = arrangeDesiredOrder(effective, article_id, target, reference_article_id);
|
|
2538
|
+
const writes = computePositionWrites(desired, article_id, normalize);
|
|
2254
2539
|
if (writes.length === 0) return { content: [{
|
|
2255
2540
|
type: "text",
|
|
2256
2541
|
text: `Article #${article_id} is already positioned ${targetLabel} in section #${sectionId}. No changes made.`
|
|
@@ -2264,7 +2549,8 @@ const createHelpCenterTools = (ctx) => {
|
|
|
2264
2549
|
text: `Reordering article #${article_id} to ${targetLabel} would reposition ${writes.length} articles in section #${sectionId}, above the safety threshold of ${REORDER_CONFIRM_THRESHOLD}. Re-run with confirm: true to proceed.`
|
|
2265
2550
|
}] };
|
|
2266
2551
|
const applied = await applyPositionWrites(writes, article_id, token);
|
|
2267
|
-
|
|
2552
|
+
const after = await fetchSectionOrder(sectionId, locale, token);
|
|
2553
|
+
if (!isPlacedAsRequested(after, article_id, target, reference_article_id)) return { content: [{
|
|
2268
2554
|
type: "text",
|
|
2269
2555
|
text: autoSortNotice(sectionId, applied)
|
|
2270
2556
|
}] };
|
|
@@ -2375,9 +2661,10 @@ const createHelpCenterTools = (ctx) => {
|
|
|
2375
2661
|
},
|
|
2376
2662
|
handler: async () => {
|
|
2377
2663
|
const token = await getToken();
|
|
2664
|
+
const response = await helpCenterGet(subdomain, token, "/articles/labels");
|
|
2378
2665
|
return { content: [{
|
|
2379
2666
|
type: "text",
|
|
2380
|
-
text: formatList(
|
|
2667
|
+
text: formatList(response.labels ?? [], formatLabel)
|
|
2381
2668
|
}] };
|
|
2382
2669
|
}
|
|
2383
2670
|
},
|
|
@@ -2503,14 +2790,15 @@ const createHelpCenterTools = (ctx) => {
|
|
|
2503
2790
|
const section = sections[section_index];
|
|
2504
2791
|
if (!section) throw new Error(`Section index ${section_index} not found. Article has ${sections.length} section(s) (0-${Math.max(0, sections.length - 1)}).`);
|
|
2505
2792
|
const content = format === "markdown" ? htmlToMarkdown(section.html) : section.html;
|
|
2793
|
+
const text = [
|
|
2794
|
+
section.headingTag ? `## [${section.index}] ${section.headingTag}: ${section.heading}` : `## [${section.index}] ${section.heading}`,
|
|
2795
|
+
`_Locale: ${locale} | Words: ${section.wordCount} | Format: ${format}_`,
|
|
2796
|
+
"",
|
|
2797
|
+
content
|
|
2798
|
+
].join("\n");
|
|
2506
2799
|
return { content: [{
|
|
2507
2800
|
type: "text",
|
|
2508
|
-
text: truncateIfNeeded(
|
|
2509
|
-
section.headingTag ? `## [${section.index}] ${section.headingTag}: ${section.heading}` : `## [${section.index}] ${section.heading}`,
|
|
2510
|
-
`_Locale: ${locale} | Words: ${section.wordCount} | Format: ${format}_`,
|
|
2511
|
-
"",
|
|
2512
|
-
content
|
|
2513
|
-
].join("\n"))
|
|
2801
|
+
text: truncateIfNeeded(text)
|
|
2514
2802
|
}] };
|
|
2515
2803
|
}
|
|
2516
2804
|
},
|
|
@@ -2674,16 +2962,18 @@ const createSearchTools = (ctx) => {
|
|
|
2674
2962
|
});
|
|
2675
2963
|
const results = response.results ?? [];
|
|
2676
2964
|
const meta = extractSearchPaginationMeta(response, per_page, page);
|
|
2965
|
+
const header = `Total: ${meta.count} | Page ${page} (${results.length} results)${meta.has_more ? ` | Next page: ${meta.after_cursor}` : ""}`;
|
|
2966
|
+
const body = results.map(formatSearchResult).join("\n\n");
|
|
2677
2967
|
return { content: [{
|
|
2678
2968
|
type: "text",
|
|
2679
|
-
text: truncateIfNeeded([
|
|
2969
|
+
text: truncateIfNeeded([header, body].filter(Boolean).join("\n\n"))
|
|
2680
2970
|
}] };
|
|
2681
2971
|
}
|
|
2682
2972
|
}];
|
|
2683
2973
|
};
|
|
2684
2974
|
//#endregion
|
|
2685
2975
|
//#region src/tools/tickets.ts
|
|
2686
|
-
const MAX_ATTACHMENT_MB = Number.parseFloat((MAX_ATTACHMENT_BYTES /
|
|
2976
|
+
const MAX_ATTACHMENT_MB = Number.parseFloat((MAX_ATTACHMENT_BYTES / 1048576).toFixed(2));
|
|
2687
2977
|
const formatReference = (attachment) => `**${attachment.file_name}** (id ${attachment.id}, ${attachment.content_type}, ${attachment.size} bytes) — ${attachment.content_url}`;
|
|
2688
2978
|
const buildEmbeddedImageBlocks = async (subdomain, token, attachment, reference) => {
|
|
2689
2979
|
const { data, contentType } = await fetchZendeskBinary(subdomain, token, attachment.content_url);
|
|
@@ -3302,9 +3592,10 @@ const createTicketTools = (ctx) => {
|
|
|
3302
3592
|
const { problem_id } = params;
|
|
3303
3593
|
const token = await getToken();
|
|
3304
3594
|
const incidents = (await zendeskGet(subdomain, token, `/tickets/${problem_id}/incidents`)).tickets ?? [];
|
|
3595
|
+
const text = incidents.length > 0 ? `# Incidents linked to problem #${problem_id}\n\n${incidents.map(formatTicket).join("\n\n")}` : `No incidents linked to problem #${problem_id}.`;
|
|
3305
3596
|
return { content: [{
|
|
3306
3597
|
type: "text",
|
|
3307
|
-
text: truncateIfNeeded(
|
|
3598
|
+
text: truncateIfNeeded(text)
|
|
3308
3599
|
}] };
|
|
3309
3600
|
}
|
|
3310
3601
|
},
|
|
@@ -3370,9 +3661,10 @@ const createTicketTools = (ctx) => {
|
|
|
3370
3661
|
throw error;
|
|
3371
3662
|
}
|
|
3372
3663
|
const policies = response.sla_policies ?? [];
|
|
3664
|
+
const meta = extractOffsetPaginationMeta(response, policies.length, per_page, page);
|
|
3373
3665
|
return { content: [{
|
|
3374
3666
|
type: "text",
|
|
3375
|
-
text: formatList(policies, formatSlaPolicy,
|
|
3667
|
+
text: formatList(policies, formatSlaPolicy, meta)
|
|
3376
3668
|
}] };
|
|
3377
3669
|
}
|
|
3378
3670
|
},
|
|
@@ -3506,9 +3798,10 @@ const createTicketTools = (ctx) => {
|
|
|
3506
3798
|
const token = await getToken();
|
|
3507
3799
|
const response = await zendeskGet(subdomain, token, "/macros/active", buildOffsetParams(per_page, page));
|
|
3508
3800
|
const macros = response.macros ?? [];
|
|
3801
|
+
const meta = extractOffsetPaginationMeta(response, macros.length, per_page, page);
|
|
3509
3802
|
return { content: [{
|
|
3510
3803
|
type: "text",
|
|
3511
|
-
text: formatList(macros, formatMacro,
|
|
3804
|
+
text: formatList(macros, formatMacro, meta)
|
|
3512
3805
|
}] };
|
|
3513
3806
|
}
|
|
3514
3807
|
},
|
|
@@ -3944,7 +4237,8 @@ const startStdioTransport = async (server, logger = silentLogger) => {
|
|
|
3944
4237
|
};
|
|
3945
4238
|
//#endregion
|
|
3946
4239
|
//#region src/dev/reload.ts
|
|
3947
|
-
const
|
|
4240
|
+
const thisDir = dirname(fileURLToPath(import.meta.url));
|
|
4241
|
+
const toolsDir = join(thisDir, "..", "tools");
|
|
3948
4242
|
const TOOL_MODULES = [
|
|
3949
4243
|
{
|
|
3950
4244
|
file: "tickets.ts",
|
|
@@ -4287,8 +4581,8 @@ const respondBodyError = (req, res, failure) => {
|
|
|
4287
4581
|
if (failure.status === 413) if (res.writableFinished) req.destroy();
|
|
4288
4582
|
else res.once("finish", () => req.destroy());
|
|
4289
4583
|
};
|
|
4290
|
-
const SESSION_IDLE_TIMEOUT_MS =
|
|
4291
|
-
const SESSION_SWEEP_INTERVAL_MS =
|
|
4584
|
+
const SESSION_IDLE_TIMEOUT_MS = 18e5;
|
|
4585
|
+
const SESSION_SWEEP_INTERVAL_MS = 6e4;
|
|
4292
4586
|
const startHttpTransport = async (config, logger = silentLogger, options = {}) => {
|
|
4293
4587
|
const metadata = buildOAuthMetadata(config, logger);
|
|
4294
4588
|
const sessions = /* @__PURE__ */ new Map();
|
|
@@ -4442,7 +4736,8 @@ const main = async () => {
|
|
|
4442
4736
|
await startDevServer(config, tokenStore.getToken, logger, tokenStore.invalidate);
|
|
4443
4737
|
return;
|
|
4444
4738
|
}
|
|
4445
|
-
|
|
4739
|
+
const server = createMcpServer(config, tokenStore.getToken, logger, tokenStore.invalidate);
|
|
4740
|
+
await startStdioTransport(server, logger);
|
|
4446
4741
|
return;
|
|
4447
4742
|
}
|
|
4448
4743
|
if (config.dev) logger.warn("dev_mode_ignored_http");
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fruggr/zendesk-mcp-server",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.17.0",
|
|
4
4
|
"mcpName": "io.github.fruggr/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",
|
|
@@ -20,11 +20,14 @@
|
|
|
20
20
|
"dev": "tsx watch src/index.ts",
|
|
21
21
|
"prepare": "npm run build && (lefthook install || true)",
|
|
22
22
|
"prepublishOnly": "npm run build",
|
|
23
|
-
"check": "node scripts/biome.mjs check --error-on-warnings
|
|
24
|
-
"check:fix": "node scripts/biome.mjs check --write
|
|
23
|
+
"check": "node scripts/biome.mjs check --error-on-warnings .",
|
|
24
|
+
"check:fix": "node scripts/biome.mjs check --write .",
|
|
25
25
|
"test": "vitest run",
|
|
26
26
|
"test:watch": "vitest watch",
|
|
27
27
|
"test:coverage": "vitest run --coverage",
|
|
28
|
+
"test:mutation": "stryker run",
|
|
29
|
+
"test:mutation:diff": "node scripts/mutation-scope.mjs diff",
|
|
30
|
+
"test:mutation:summary": "node scripts/mutation-scope.mjs summary",
|
|
28
31
|
"test:smoke": "pnpm build && node scripts/smoke-test.mjs",
|
|
29
32
|
"mcp:live": "tsx scripts/mcp-live.ts"
|
|
30
33
|
},
|
|
@@ -66,9 +69,9 @@
|
|
|
66
69
|
"engines": {
|
|
67
70
|
"node": ">=20"
|
|
68
71
|
},
|
|
69
|
-
"packageManager": "pnpm@11.
|
|
72
|
+
"packageManager": "pnpm@11.20.0+sha512.9a6f330a95b66446ea088faf1521405a8a01f07fde7124cc9958dfed52d4bb436737e65b08f85f37b46fcba375092558ac51262b816844b22f63406ed166bfee",
|
|
70
73
|
"dependencies": {
|
|
71
|
-
"@modelcontextprotocol/sdk": "1.
|
|
74
|
+
"@modelcontextprotocol/sdk": "1.30.0",
|
|
72
75
|
"cheerio": "1.2.0",
|
|
73
76
|
"hast-util-to-html": "9.0.5",
|
|
74
77
|
"hast-util-to-mdast": "10.1.2",
|
|
@@ -85,13 +88,15 @@
|
|
|
85
88
|
"zod": "4.4.3"
|
|
86
89
|
},
|
|
87
90
|
"devDependencies": {
|
|
88
|
-
"@biomejs/biome": "2.5.
|
|
91
|
+
"@biomejs/biome": "2.5.7",
|
|
89
92
|
"@semantic-release/changelog": "^6.0.3",
|
|
90
93
|
"@semantic-release/exec": "^7.1.0",
|
|
91
94
|
"@semantic-release/git": "^10.0.1",
|
|
92
95
|
"@semantic-release/github": "^12.0.6",
|
|
93
96
|
"@semantic-release/npm": "^13.1.5",
|
|
94
97
|
"@semantic-release/release-notes-generator": "^14.1.1",
|
|
98
|
+
"@stryker-mutator/core": "^9.6.1",
|
|
99
|
+
"@stryker-mutator/vitest-runner": "^9.6.1",
|
|
95
100
|
"@tsconfig/node20": "^20.1.9",
|
|
96
101
|
"@tsconfig/strictest": "^2.0.8",
|
|
97
102
|
"@types/hast": "^3.0.4",
|