# Reported issues for zendesk-mcp-server

Pod holds 19 of 58 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [zendesk-mcp-server](/mcp/zendesk-mcp-server).

## Most discussed

### find_translation_gaps: try the `translations` sideload to drop the per-node fan-out

### Context

`find_translation_gaps` (added in #225, closes #224) audits the category → section tree for a target locale and reports every node with no translation or an unpublished draft. It gets the draft state by calling `GET /{sections|categories}/{id}/translations` **once per node**, in waves of 5, bounded by `ZENDESK_TRANSLATION_GAP_SCAN_MAX_NODES` (default 60). On a 58-node tenant that is ~61 requests for one audit, and past the cap the report has to admit it left nodes unchecked.

That d

[Read the thread](https://github.com/fruggr/zendesk-mcp-server/issues/226) · 2026-08-11 · closed · 4 comments

### Exit on stdin close in stdio mode

Running in stdio mode behind `npx`, the server never receives `SIGTERM`. The `npm exec` and `sh -c` links in the chain do not relay signals, so the only sign that the client is gone is EOF on stdin.

Today the process still exits, but only because nothing keeps the event loop alive once stdin closes. That is circumstantial, not by design: adding an HTTP keep-alive agent, a refresh timer or a persistent cache would turn it into a process that outlives every session.

Suggestion: listen for stdin 

[Read the thread](https://github.com/fruggr/zendesk-mcp-server/issues/246) · 2026-08-20 · closed · 3 comments

### Can't pull a specific Help Center article as an MCP resource (for @-mention / context)

## What

Help Center articles can only be reached through tools (`search_articles`, `get_article`, section tools). There's no **MCP resource** to reference a specific article, so clients that let users attach/@-mention resources can't pin an article as context.

## Why / the problem

The server already ships one pull-only resource (`zendesk-hc://topology`), which proves the pattern is valuable. Extending it to articles would let a user surface search results, then **pin the relevant article as a

[Read the thread](https://github.com/fruggr/zendesk-mcp-server/issues/126) · 2026-07-04 · closed · 3 comments

### Ticket field definitions are not readable — custom-field writes are blind

## What

There is no way to read **ticket field definitions** — the list of ticket fields (system + custom), their ids, types, and the valid option values for dropdown/multiselect fields.

## Why / the problem

`create_ticket` and `update_ticket` already accept `custom_fields` as `{ id, value }` pairs, but nothing lets the model **discover** those ids or the values a field will accept. Today the descriptions punt with "field ids come from your Zendesk admin settings" — i.e. the assistant writes 

[Read the thread](https://github.com/fruggr/zendesk-mcp-server/issues/119) · 2026-07-04 · closed · 3 comments

### Support markdown-inline images in comment bodies for get_ticket_attachments

## Context

Follow-up from #13 (merged). During manual testing, @florentleveque identified an edge case not covered by `get_ticket_attachments`: images referenced **inline in the comment body** as markdown `![alt](url)` are not enrolled in the comment's `attachments` array returned by the Zendesk API, so they are invisible to the new tool.

## Current behavior

`get_ticket_attachments` collects images via `comment.attachments[]`. Images that authors embed directly in the message body (drag-and-d

[Read the thread](https://github.com/fruggr/zendesk-mcp-server/issues/15) · 2026-05-18 · closed · 3 comments

### No section or category translation tools: articles get published in a target locale under sections that only exist in the source locale

### Problem

Translations are only reachable at the article level. `list_article_translations` takes an `article_id` and nothing else, and `create_article_translation` / `update_article_translation` are article-scoped too. Sections and categories have no translation tool at all.

Reading is partly possible as a side effect: `list_sections` and `list_categories` accept a `locale`, and the filtered listing only returns the ones that have a translation in that locale. That is enough to spot a gap, 

[Read the thread](https://github.com/fruggr/zendesk-mcp-server/issues/224) · 2026-08-11 · closed · 2 comments

### docs: document the SSE keep-alive and proxy-buffering behaviour of the HTTP transport

## Summary

Since `@modelcontextprotocol/sdk` 1.30.0 the Streamable HTTP transport keeps its SSE streams alive on its own: it writes periodic comment frames and asks intermediaries not to buffer the stream. Our `node:http` transport is a thin wrapper around the SDK's, so we inherit all of it — and `docs/http-deployment.md` says nothing about it, even though the doc's whole audience is people running the server behind a reverse proxy.

This is documentation only; no behaviour change is proposed.

[Read the thread](https://github.com/fruggr/zendesk-mcp-server/issues/207) · 2026-08-04 · closed · 2 comments

### Logging a field with a circular reference crashes the caller

## What happens

Passing a value containing a circular reference to any logger method throws `RangeError: Maximum call stack size exceeded` out of the call that emitted the log.

```ts
const log = createLogger('debug');
const circular: Record<string, unknown> = {};
circular['self'] = circular;

log.info('evt', { circular }); // throws
```

```
RangeError: Maximum call stack size exceeded
 ❯ isSensitive src/utils/logger.ts:54:39
 ❯ redactValue src/utils/logger.ts:64:18
 ❯ redactValue src/utils/lo

[Read the thread](https://github.com/fruggr/zendesk-mcp-server/issues/198) · 2026-08-02 · closed · 2 comments

## Most recent

### Migrate to MCP SDK v2, shipped through a dedicated `beta` release channel

## Summary

Execute the migration from `@modelcontextprotocol/sdk@1.x` to the v2 package split
(`@modelcontextprotocol/core` / `server` / `client` / `node`), and — because of what
this change touches — ship it **through a pre-release channel with a real beta period
of several days to weeks**, not straight to `@latest`.

This issue is the *migration*, deliberately separate from #213, which is the
*evaluation* and explicitly leaves the migration out of its own scope. #213's written
recommendation 

[Read the thread](https://github.com/fruggr/zendesk-mcp-server/issues/231) · 2026-08-12 · open · 0 comments

### Publish the mutation score to the Stryker dashboard, so the rollout is measurable over time

Sub-task of #208, and **first** — not because it raises a score, but because nothing else in the rollout is currently measurable over time.

## The gap

#197 shipped reporting that keeps nothing. The HTML report goes out as a CI artifact (30 days for the baseline job, 7 for PRs) and then vanishes; the cached `stryker-incremental.json` is current state, overwritten on every push to `main`, not a history. So "where was `src/auth` a month ago" has no answer today, and #208's table is a snapshot mai

[Read the thread](https://github.com/fruggr/zendesk-mcp-server/issues/214) · 2026-08-04 · closed · 1 comment

### Evaluate the MCP SDK v2 migration — Renovate is structurally blind to it

## Summary

The MCP TypeScript SDK has moved to a **v2 published under new package names**. We depend on `@modelcontextprotocol/sdk`, whose latest release is `1.30.0` — the final version of the v1 line. **No automation will ever tell us about v2**, because it is a package split, not a version bump.

This issue is an **evaluation**, not a decision to migrate. Its output is a written recommendation (migrate now / later / never, and in what order), not code.

## Why Renovate will never propose it

[Read the thread](https://github.com/fruggr/zendesk-mcp-server/issues/213) · 2026-08-04 · closed · 1 comment

### Bring src/tools/** into the mutation scope

Sub-task of #208, and the only one that is **blocked** rather than merely unstarted. `src/tools/**` has never been measured because it is excluded from `mutate` in `stryker.config.mjs`.

## Why it is out

Stryker's `StringLiteral` mutator empties every string, and this directory is mostly `.describe()` calls — the per-parameter descriptions the MCP tool surface is built from and that `AGENTS.md` requires for the Glama quality bar. Each one yields a survivor that says nothing about test quality, 

[Read the thread](https://github.com/fruggr/zendesk-mcp-server/issues/212) · 2026-08-04 · open · 1 comment

### Raise the mutation score of src/client

Sub-task of #208. `src/client/zendesk-api.ts` is the single HTTP path every tool goes through, so an unasserted branch here is a bug surface for the whole tool set.

## Measured

Full-scope baseline on `main` ([run 14](https://github.com/fruggr/zendesk-mcp-server/actions/runs/30934244169), commit `31df70c`, 2026-08-04): **68.04 % total / 71.74 % covered** — 66 killed, 26 survived, 5 never reached, out of 97 mutants.

Escaped, by mutator:

| Mutator | Count |
| --- | ---: |
| ConditionalExpressio

[Read the thread](https://github.com/fruggr/zendesk-mcp-server/issues/210) · 2026-08-04 · closed · 1 comment

### Raise the mutation score of src/auth

Sub-task of #208. **The worst-scoring area, and the one where it matters most:** this is the OAuth 2.1 / PKCE code that holds the only credential path the server has.

## Measured

Full-scope baseline on `main` ([run 14](https://github.com/fruggr/zendesk-mcp-server/actions/runs/30934244169), commit `31df70c`, 2026-08-04): `src/auth` scores **58.68 % total / 62.12 % covered** — 223 killed, 136 survived, 21 never reached.

**157 escaped mutants, more than the rest of the scope put together** (the 

[Read the thread](https://github.com/fruggr/zendesk-mcp-server/issues/209) · 2026-08-04 · open · 1 comment

### Proxy dispatch leaks raw ZodError JSON: type errors are unreadable in the default namespace mode

## Summary

On the proxy dispatch path, `createStrictParamsParser` handles the unknown-key case with a crafted message but falls through to `throw result.error` (`src/utils/validation.ts:38`) for every other validation failure. That raw `ZodError` reaches the client as its `.message`, which for Zod is a **JSON dump of the issue array**.

This affects `namespace` (the **default**) and `single` modes. In `all` mode the SDK owns the parse, and SDK 1.30.0 just improved that formatting — so the two m

[Read the thread](https://github.com/fruggr/zendesk-mcp-server/issues/206) · 2026-08-04 · open · 0 comments

### Cap attachment payloads: an oversized JSON-RPC message now kills the whole stdio session

## Summary

`@modelcontextprotocol/sdk` 1.30.0 introduces a **10 MB cap on the stdio `ReadBuffer`** (`STDIO_DEFAULT_MAX_BUFFER_SIZE = 10485760`). A message exceeding it does not merely fail the call: the transport emits an error and **closes**, tearing down the MCP session.

Our tool surface can produce such messages in **both directions**, because neither the inbound attachment upload nor the outbound embedded-image response has a total-size budget.

## Evidence

Measured on `StdioServerTranspo

[Read the thread](https://github.com/fruggr/zendesk-mcp-server/issues/205) · 2026-08-04 · open · 0 comments

### pnpm check does not lint the root config files

## What

`pnpm check` and the lefthook pre-commit hook are both scoped to `src/ tests/ scripts/`:

```json
"check": "node scripts/biome.mjs check --error-on-warnings src/ tests/ scripts/",
```

So **no file at the repo root is ever linted by the repo's own gate** — including `vitest.config.ts`, `tsdown.config.ts`, `biome.json` itself, and `server.json`.

## How it surfaced

In #197, `stryker.config.mjs` was added at the root and tripped `style/noDefaultExport` — which native Stryker ESM configs 

[Read the thread](https://github.com/fruggr/zendesk-mcp-server/issues/202) · 2026-08-03 · closed · 1 comment

### Harden the shared Zendesk HTTP client: retry transient failures + contextual network errors

## Problem

Every tool goes through `executeRequest` in `src/client/zendesk-api.ts`. Two rough edges surfaced during the #170 functional validation (run on a slow Android/Termux link with several requests in flight):

1. **Opaque network errors.** When `fetch` itself throws (connection reset, DNS, timeout — the `await fetch(...)` path, before any HTTP status), the caller (and the LLM / MCP client) sees a bare `fetch failed` with nothing naming which operation / article / page failed. HTTP *respo

[Read the thread](https://github.com/fruggr/zendesk-mcp-server/issues/193) · 2026-07-30 · closed · 2 comments

### CLI parser silently ignores value-taking flags with a missing or empty value

## Problem

Every value-taking flag branch in `parseCliArgs` (`src/config.ts`) is guarded by `arg === '--flag' && next`. When the value is missing or empty, the guard is falsy and the flag is **silently dropped** instead of failing at startup. This affects all value-taking flags equally: `--mode`, `--namespace`, `--tool`, `--log-level`, `--transport`, `--host`, `--port`, `--public-url`, `--cors-origin`, `--callback-port` and (once #173 lands) `--hc-resource-scheme`.

Two concrete failure shapes:

[Read the thread](https://github.com/fruggr/zendesk-mcp-server/issues/174) · 2026-07-20 · closed · 1 comment

The remaining reports are on [the project's issue tracker](https://github.com/fruggr/zendesk-mcp-server/issues).