dsh-plugin-zai-mcp

Readme

# dsh-plugin-zai-mcp

**All four z.ai GLM Coding Plan MCP servers as native [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH) tools** — vision, web reader, web search, and zread — bridged through the in-box [`@deepseek-ai/dsh-mcp-client`](https://www.npmjs.com/package/@deepseek-ai/dsh-mcp-client).

If DSH already reaches z.ai models for you, the plugin works **zero-config**: it reuses the GLM coding-plan key from DSH's managed credentials store.

## What you get

| server | transport | tools |
|---|---|---|
| `zai-vision` | stdio — `npx -y @z_ai/mcp-server@latest` | `analyze_image`, `analyze_video`, `ui_to_artifact`, `extract_text_from_screenshot`, `diagnose_error_screenshot`, `understand_technical_diagram`, `analyze_data_visualization`, `ui_diff_check` |
| `zai-web-reader` | streamable-http | `webReader` |
| `zai-web-search` | streamable-http | `web_search_prime` |
| `zai-zread` | streamable-http | `search_doc`, `get_repo_structure`, `read_file` |

13 tools total, each published as `mcp__<serverName>__<toolName>`. Tool calls consume your [GLM Coding Plan](https://docs.bigmodel.cn/cn/coding-plan/overview) quota.

Official specs: [视觉理解 MCP](https://docs.bigmodel.cn/cn/coding-plan/mcp/vision-mcp-server) · [联网搜索 MCP](https://docs.bigmodel.cn/cn/coding-plan/mcp/search-mcp-server) · [网页读取 MCP](https://docs.bigmodel.cn/cn/coding-plan/mcp/reader-mcp-server) · [开源仓库 MCP](https://docs.bigmodel.cn/cn/coding-plan/mcp/zread-mcp-server)

## Requirements

- DSH with the in-box `@deepseek-ai/dsh-mcp-client`
- Node.js ≥ 18 on PATH for the vision server
- Outbound HTTPS to `open.bigmodel.cn`
- A GLM Coding Plan API key

## Install

The package declares a `dsh.bundle` manifest, so it installs like any other profile plugin: a package dependency plus one line in `dsh.profile.bundles` — no hand-edited `cordis.patch.yml`.

### A. Package install

One command:

```sh
# from a Git source
dsh plugin --profile web add "github:nekomona/dsh-plugin-zai-mcp"

# or from a local checkout
dsh plugin --profile web add "link:D:/path/to/dsh-zai-mcp"
```

The CLI appends the bundle line itself. Restart DSH, done. Uninstall and update are symmetric:

```sh
dsh plugin --profile web remove dsh-plugin-zai-mcp
dsh plugin --profile web add "github:nekomona/dsh-plugin-zai-mcp"   # update
```

There is no build step, so git installs never need a `prepare` build or pnpm build authorization.

**DSH Desktop app**: use the script from method C, or run the app's bundled pnpm inside the profile directory:

```powershell
& "$env:APPDATA\dsh-desktop\harness\.desktop-bin\pnpm.cmd" add "github:nekomona/dsh-plugin-zai-mcp"
# then append "dsh-plugin-zai-mcp" to dsh.profile.bundles in
# %APPDATA%\dsh-desktop\harness\profiles\web\package.json
```

### B. DSH plugin marketplace

Search for `dsh-plugin-zai-mcp` and install. You will be prompted for `Z_AI_API_KEY`.

### C. From a checkout of this repo

```powershell
pwsh scripts/install.ps1 -ProfileName web
```
```sh
sh scripts/install.sh web
```

The script links the checkout with pnpm, appends the bundle line, and removes any pre-0.2 patch entry. It never writes patch entries.

## API key

Resolution order at plugin start:

1. `config.apiKey`
2. `Z_AI_API_KEY`, then `ZAI_CODING_CN_API_KEY` — in the launch environment or `~/.dsh/.env`
3. the same names in DSH's managed credentials store, `~/.dsh/.credentials.yaml`

So on a host where the GLM coding provider is already configured, nothing to do. Otherwise:

```
# ~/.dsh/.env
Z_AI_API_KEY=your-coding-plan-key
```

Get a key at [bigmodel.cn → Coding Plan](https://bigmodel.cn/coding-plan/personal/overview). Team-plan keys are not interchangeable with regular bigmodel.cn keys — use the team key.

The key is passed to the vision child via its `env` and sent as an `Authorization: Bearer` header to the remote endpoints. The plugin never writes it to disk or logs it.

## Configuration

Zero-config by default. To customize, give the entry a `config`:

```yaml
- insert:
    - id: dsh-plugin-zai-mcp
      name: dsh-plugin-zai-mcp
      config:
        mode: ZHIPU                  # ZHIPU | ZAI
        keyWaitMs: 5000
        vision:
          enabled: true
          quiet: true
          command: npx               # override for an absolute npx.cmd path
          args: ['-y', '@z_ai/mcp-server@latest']
          toolCallTimeoutMs: 60000
        webReader: { enabled: true }
        webSearch: { enabled: false }
        zread: { enabled: true }
        apiKeyEnvNames: [Z_AI_API_KEY, ZAI_CODING_CN_API_KEY]
```

| field | default | meaning |
|---|---|---|
| `apiKey` | `''` | hard-coded key |
| `apiKeyEnvNames` | `[Z_AI_API_KEY, ZAI_CODING_CN_API_KEY]` | names probed, in order |
| `mode` | `ZHIPU` | vision child platform: `ZHIPU` = bigmodel.cn, `ZAI` = z.ai international |
| `keyWaitMs` | `5000` | startup wait for the credentials provider — DSH mounts plugins concurrently and it may commit slightly later |
| `vision.quiet` | `true` | silence the child's stderr via the wrapper |
| `<server>.enabled` | `true` | per-server kill switch |
| `<server>.url` | official endpoint | endpoint override |
| `<server>.toolCallTimeoutMs` | `60000` | per-tool-call timeout |

## How it works

- One `@deepseek-ai/dsh-mcp-client` child per server; tools follow this plugin's lifecycle, so an HMR reload disposes and re-bridges cleanly.
- **Fail-soft**: an unreachable endpoint or missing key degrades to per-call tool errors. A keyless vision child is never spawned — the server exits without `Z_AI_API_KEY` and would crash-loop through npx. One failing bridge never fails the others or the host boot.
- **Quiet console**: the vision server logs every line to stderr unconditionally and the MCP SDK inherits child stderr, so `lib/vision-stdio.mjs` wraps the child and drops only its stderr, leaving the MCP channel untouched. The server's own log stays at `~/.zai/zai-mcp-<date>.log` (override with `ZAI_MCP_LOG_PATH`).
- The plugin logs one debug line on success and warns only when no key resolves or a bridge fails.

## Troubleshooting

- **Vision tools missing** — check the key resolved; verify the server manually: `Z_AI_API_KEY=… npx -y @z_ai/mcp-server@latest`. An old cached npx version can be cleared with `npm cache clean` — the default args pin `@latest`.
- **Windows spawn** — the wrapper routes through `cmd.exe /d /s /c` for `.cmd` shims; with a non-standard Node install, point `vision.command` at `npx.cmd` directly.
- **Auth errors** — key wrong, not a coding-plan key, out of quota, or a platform mismatch: `mode` must match where the key works. See the [MCP 额度说明](https://docs.bigmodel.cn/cn/coding-plan/overview).
- **zread can't read a repo** — only public repos indexed by [zread.ai](https://zread.ai) are supported.
- **Local media for vision** — reference images by path; videos MP4/MOV/M4V, local files capped at 8 MB by the z.ai server.

## Disclosure

- **Cloud dependency**: all four servers are z.ai / Zhipu services. Searches, URLs, repo names, and images/videos passed to these tools are sent to those services. Applies to: z.ai / Zhipu (CN).
- **API key storage**: read from DSH's environment layers and managed credentials store only; never written to disk or logs by this plugin.
- **Quota**: tool calls consume GLM Coding Plan quota.

Also declared machine-readably in the `disclosure` field of `package.json`, which the marketplace ingests for its "disclosed" badge.

## Development

```sh
npm install        # dev-only peer closure for the tests
npm test           # schema + apply() unit tests, no network
npm run test:live  # bridges the four live servers: handshake + tools/list
                   # only, no quota-consuming tool calls
```

Package layout follows the [DSH plugin marketplace standard](https://github.com/bradeGithub/DSH-Plugins-Marketplace): `dsh` capability declaration, pre-built `lib/`, host interface packages in `peerDependencies` only.

For development against a running DSH, wire the checkout with the `link:` install from method A: edits to `lib/` take effect on the next DSH restart. Keep the repo's `node_modules/` present for the peer imports to resolve.

## License

[MIT](LICENSE)