dsh-plugin-zai-mcp

All four z.ai GLM Coding Plan MCP servers as native DeepSeek Harness (DSH) tools — vision, web reader, web search, and zread — bridged through the in-box @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 quota.

Official specs: 视觉理解 MCP · 联网搜索 MCP · 网页读取 MCP · 开源仓库 MCP

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:

# 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:

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:

& "$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

pwsh scripts/install.ps1 -ProfileName web

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. 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:

- 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 额度说明.
• zread can't read a repo — only public repos indexed by 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

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: 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