@fruggr/zendesk-mcp-server 2.16.0 → 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 +701 -299
- package/package.json +11 -7
- package/dist/index.d.ts +0 -2
- package/dist/index.js.map +0 -1
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
|
|