dsh-zai-web-search-mcp 1.8.4 → 1.9.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 CHANGED
@@ -1,201 +1,227 @@
1
- # zai-web-search-mcp
2
-
3
- [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
4
- [![Platform: DeepSeek Harness](https://img.shields.io/badge/platform-DeepSeek%20Harness%20(dsh)-4B32C3.svg)](#what-this-is)
5
- [![API: Z.ai international](https://img.shields.io/badge/Z.ai-international%20(api.z.ai)-3B82F6.svg)](#important-regions)
6
- [![Made for GLM Coding Plan](https://img.shields.io/badge/plan-GLM%20Coding%20Plan-22C55E.svg)](#what-this-is)
7
- [![CI](https://github.com/FamousMonsterr/zai-web-search-mcp/actions/workflows/ci.yml/badge.svg)](../../actions/workflows/ci.yml)
8
-
9
- **A plugin for the [DeepSeek Harness](https://github.com/deepseek-ai) (dsh) desktop app that plugs your GLM Coding Plan (Z.ai) subscription into the harness:**
10
-
11
- | # | Surface | What you get |
12
- |---|---------|--------------|
13
- | 1 | `web_search` | The built-in web-search tool, powered by the Z.ai `web_search_prime` MCP server |
14
- | 2 | `mcp__zai__web_search_prime` | The same Z.ai server mounted as a standalone MCP tool |
15
- | 3 | Quota chip | A live indicator near the composer: 5-hour & weekly credit windows + MCP calls in the last 30 days (the same data zcode shows) |
16
- | 4 | `web_fetch` + `mcp__zai-reader__webReader` | The built-in fetch tool reads through the Z.ai `web_reader` MCP server (server-side fetch, structured markdown); the same server is also a standalone MCP tool. Revert: `fetchProvider: http` in `cordis.patch.yml` |
17
- | 5 | `mcp__zai-vision__*` | 8 image/video tools (`analyze_image`, `analyze_video`, `extract_text_from_screenshot`, `diagnose_error_screenshot`, `ui_to_artifact`, `understand_technical_diagram`, `analyze_data_visualization`, `ui_diff_check`) from the local vision MCP server (`npx @z_ai/mcp-server`, stdio) — text-only models can analyze images by passing a file path |
18
- | 6 | `mcp__zai-zread__*` | GitHub repository analysis through the Zread MCP server: `search_doc` (docs/issues/PRs search), `get_repo_structure` (directory tree), `read_file` (file contents) |
19
-
20
- > ### ⭐ Star this repo
21
- > If this plugin helped you — **even if you only read the code and never install it** — please press the Star button (top-right). It is free, and it helps other people find the plugin.
22
- >
23
- > Found a bug or have an idea? **AI agents and humans are equally welcome** to open issues and pull requests — see [`AGENTS.md`](AGENTS.md), [`CONTRIBUTING.md`](CONTRIBUTING.md) and the issue/PR templates.
24
-
25
- ## Important: regions
26
-
27
- This plugin targets the **international** Z.ai endpoint `https://api.z.ai` — it is for users **outside mainland China**. Mainland China accounts use the domestic `open.bigmodel.cn` endpoints, which this plugin does **not** support (different URLs and auth; open a feature-request issue if you need it).
28
-
29
- ## What this is (specifically)
30
-
31
- - Built **specifically for DeepSeek Harness (dsh) desktop** (Electron). It uses the public dsh plugin seams only — `ctx.credentials`, `ctx.web`, `ctx.webServer`, `ctx.slots`, `dsh-mcp-client` — so any other host implementing the same dsh/Cordis seams can potentially run it too.
32
- - The API key is **never stored in this repo** and never reaches the browser: the plugin resolves the `ZAI_API_KEY` credential from the Harness store (`~/.dsh/.credentials.yaml`) at runtime.
33
- - Zero npm dependencies; installs as a `link:` bundle into the dsh profile.
34
- - The vision surface spawns the local `@z_ai/mcp-server` through `npx` (stdio) and needs **Node.js >= 22 and `npx` on the PATH** of the dsh host process; a cold npx cache can exceed the MCP negotiation timeout — prewarm once with `Z_AI_API_KEY=<key> npx -y @z_ai/mcp-server@latest`. Every MCP bridge failure is non-fatal: search/reader providers and the quota chip keep working.
35
-
36
- ## Install (on a new computer)
37
-
38
- Requirements: **DeepSeek Harness desktop** installed and started once; **PowerShell 7+** (`pwsh`); a valid **GLM Coding Plan** key.
39
-
40
- ```powershell
41
- git clone https://github.com/FamousMonsterr/zai-web-search-mcp.git
42
- cd zai-web-search-mcp
43
-
44
- $env:ZAI_API_KEY = "<your key>" # optional: skips the manual prompt
45
- pwsh -NoProfile -File install.ps1
46
- ```
47
-
48
- The installer is idempotent: it wires `~/.dsh/profiles/desktop/package.json` (bundle + `link:` dependency), checks/stores `ZAI_API_KEY`, and runs `pnpm install` using the node/pnpm bundled with dsh (nothing else to install). Then **restart DeepSeek Harness**.
49
-
50
- ## Install for any user (npm)
51
-
52
- The DeepSeek Harness plugin manager installs third-party plugins **from the npm registry** (it auto-probes `registry.npmjs.org` / `npmmirror`). A package carrying the `dsh.bundle.patch` field is auto-activated after install — the user needs no manual profile edits:
53
-
54
- > Установи плагин `dsh-zai-web-search-mcp@1.8.1`
55
-
56
- …said to the in-app agent (it runs `install_bundle` with the npm spec), or install via the Plugins page. Then store your own `ZAI_API_KEY` credential (Models/credentials) and restart the app. Note: freshly published npm versions may be held back by the manager's `minimumReleaseAge` policy — the UI then offers the exact `name@version` to pin (that is why the one-liner above pins `@1.8.1`).
57
-
58
- The published package name is **[`dsh-zai-web-search-mcp`](https://www.npmjs.com/package/dsh-zai-web-search-mcp)** (this repo's dev install keeps the `@local/` link name; `scripts/prepare-npm.mjs` builds the publishable variant).
59
-
60
- Ready links:
61
-
62
- - npm package: <https://www.npmjs.com/package/dsh-zai-web-search-mcp> (latest **1.8.1**)
63
- - Install spec for the dsh plugin manager / Plugins page: `dsh-zai-web-search-mcp@1.8.1`
64
- - This repo: <https://github.com/FamousMonsterr/zai-web-search-mcp>
65
- - Showcased in the DeepSeek Harness discussions: [GLM Coding Plan (Z.ai) inside DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness/discussions/12761)
66
-
67
- ### Maintainer: publish a new version
68
-
69
- ```powershell
70
- node scripts/prepare-npm.mjs # -> dist/npm/ (public name, engines.dsh, renamed patch row)
71
- npm publish ./dist/npm # NOTE the leading ./ : without it npm parses "dist/npm" as a GitHub shorthand
72
- ```
73
-
74
- Bump `version` in `package.json` first (and `CLIENT_INFO` in `index.js`), sync the live copy, push the tag-less commit — CI checks syntax and that no secrets are in the tree.
75
-
76
- Publishing auth (npm's 2026 policy): a plain `npm login` web session is **no longer enough to publish** — the registry answers 403 "Two-factor authentication or granular access token with bypass 2fa enabled". Working options:
77
-
78
- - one-time code: `npm publish ./dist/npm --otp=123456` (from your authenticator app), or
79
- - a **granular access token** with "bypass 2FA" (npmjs.com → Access Tokens): pass it via a temporary project `.npmrc` (`//registry.npmjs.org/:_authToken=npm_…`) or `NODE_AUTH_TOKEN`; note that a token stored in the user `~/.npmrc` wins over the env var — force it with the project-level file, and **revoke the token after publishing** if it ever appeared in logs or chats.
80
-
81
- ## Verify
82
-
83
- ```powershell
84
- pwsh -NoProfile -File verify.ps1
85
- ```
86
-
87
- Live-checks all three Z.ai integrations (MCP search, quota windows, 30-day tool usage). The key is read from the credential store and never printed. Expected final line: `ALL CHECKS PASSED`.
88
-
89
- ## Repository documentation
90
-
91
- | File | Purpose |
92
- |------|---------|
93
- | [`AGENTS.md`](AGENTS.md) | Simple-English guide for AI agents (and humans): repo map, golden rules, how to test, how to PR |
94
- | [`CONTRIBUTING.md`](CONTRIBUTING.md) | How to contribute |
95
- | [`SECURITY.md`](SECURITY.md) | How to report vulnerabilities; secret hygiene |
96
- | [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) | Behavior rules |
97
- | [Issue templates](.github/ISSUE_TEMPLATE/) / [PR template](.github/PULL_REQUEST_TEMPLATE.md) | What to include in issues and pull requests |
98
-
99
- ## Layout
100
-
101
- ```
102
- index.js host side: search + reader providers, search/reader/vision MCP bridges, /zai-quota service
103
- client.js UI side: quota chip (React) with the usage popover
104
- cordis.patch.yml dsh patch: mount plugin, select providers "zai-mcp" (search) and "zai-reader" (fetch)
105
- locale/{en,ru,zh}.json, icon.svg
106
- install.ps1 / verify.ps1 human entry points
107
- scripts/install.mjs, verify.mjs actual logic (runs on the dsh-bundled node)
108
- ```
109
-
110
- ## Tested on
111
-
112
- Verified live on **Windows 11 x64** with DeepSeek Harness desktop `0.2.1-rc.5` (plugin v1.5.1/v1.6.0):
113
-
114
- | Check | Result |
115
- |---|---|
116
- | MCP `web_search_prime` (initialize / tools/list / tools/call) | ✅ works, search results returned |
117
- | Quota API (5-hour & weekly windows, plan level) | ✅ works |
118
- | 30-day MCP tool-usage API | ✅ works |
119
- | Host plugin: `/zai-quota` route, credential resolution, web-search provider registration | ✅ works in the Electron host |
120
- | Client module loads and runs in the renderer (`/zai-quota-diag` lifecycle events) | ✅ confirmed |
121
- | Quota chip mounted in the Electron composer | ✅ works (v1.6.0) — chip renders in the composer stats row, popover shows both windows + MCP calls |
122
-
123
- Verified live on **macOS (Apple Silicon)** with DeepSeek Harness desktop `0.2.1-rc.5` (plugin v1.7.0):
124
-
125
- | Check | Result |
126
- |---|---|
127
- | MCP `web_reader` (initialize / tools/list / `webReader` call) | ✅ works — `{title, url, content}` mapped to `web_fetch` |
128
- | `web_fetch` through the `zai-reader` provider in the live host | ✅ end-to-end: built-in tool returns Z.ai markdown |
129
- | Vision MCP bridge (stdio `npx -y @z_ai/mcp-server@latest`, 8 tools) | ✅ connects, tools register |
130
-
131
- Verified live on **Windows 11 x64** with DeepSeek Harness desktop `0.2.2-rc.1` (npm package **v1.8.1**, installed from the registry through the built-in plugin manager):
132
-
133
- | Check | Result |
134
- |---|---|
135
- | `plugin_manager install_bundle dsh-zai-web-search-mcp@1.8.1` | ✅ installs from npm, bundle auto-activates via `dsh.bundle.patch`, no manual profile edits |
136
- | All MCP bridges after the npm install | ✅ 14 tools: `web_search_prime`, `webReader`, 8× vision, 3× zread |
137
- | `/zai-quota` route + built-in `web_search` through `zai-mcp` | ✅ live quota windows; real search results |
138
- | Quota popover in the zcode "Quota remaining" format (issue #2: strings on ru-RU/en-US/zh-CN hosts, adaptive width, label wrap, edge-flip) | ✅ verified live in English and Russian UIs — remaining-share percents, "Nov 9, 22:55" / "9 нояб., 22:55" app-locale dates, Last-refreshed footer |
139
- | Side-by-side with the dev `@local` link | ✅ tested; the duplicate was cleanly removable via `remove_bundle` |
140
-
141
- The web-search and MCP-tool surfaces do not depend on the chip and work regardless.
142
-
143
- ## Screenshots (Windows 11, DeepSeek Harness desktop)
144
-
145
- The quota chip sits in the composer stats row next to the context meter:
146
-
147
- ![Quota chip in the composer stats row](docs/quota-chip-en.png)
148
-
149
- Hovering it opens the usage popover — the 5-hour and weekly credit windows with reset times, plus MCP tool calls in the last 30 days:
150
-
151
- ![Quota popover](docs/quota-popover-en.png)
152
-
153
- > v1.6.0 mount fix: the chip component no longer calls `setState` during render (that triggered React's "Too many re-renders", and the slot's error boundary silently evicted the entry — the chip vanished before its first effect ran). Visibility is now purely derived; registration mirrors the built-in `activity`/`usage` pills exactly (generator factory, `locale`, order 2) with `dsh.client.immediately: true`.
154
-
155
- ## Troubleshooting
156
-
157
- - **Chip not visible** — make sure you run plugin v1.6.0+ (earlier versions had a render-phase `setState` that made the slot error boundary evict the chip silently) and restart the app after `install.ps1`. The quota itself is always available at the host route `/zai-quota` and via `pwsh -NoProfile -File verify.ps1`.
158
- - **HTTP 401/403 from Z.ai** — update `ZAI_API_KEY` in the app's Models/credentials surface, then restart. The search/reader providers pick up the rotated key on the next call; the vision stdio child snapshots the key at spawn, so it needs a plugin reload (app restart) to see the new one.
159
- - **MCP bridge fails at startup** — non-fatal by design: `web_search` and `web_fetch` keep working.
160
- - **Vision tools missing** — the vision bridge needs `npx` and Node >= 22 reachable from the dsh host process PATH; prewarm the npx cache once (`Z_AI_API_KEY=<key> npx -y @z_ai/mcp-server@latest`) and restart the app. Check `node scripts/verify.mjs` (check 5/5).
161
- - **Want the old anonymous fetch back** — in `cordis.patch.yml` set the `web` row's `fetchProvider` back to `http` and restart; `mcp__zai-reader__webReader` stays available as a standalone tool either way.
162
-
163
- ## License
164
-
165
- [MIT](LICENSE) © FamousMonsterr
166
-
167
- ---
168
-
169
- # По-русски
170
-
171
- Плагин для **DeepSeek Harness (dsh) desktop**, подключающий подписку **GLM Coding Plan (Z.ai)**: веб-поиск `web_search` через MCP-сервер `web_search_prime`, чтение страниц `web_fetch` через MCP-сервер `web_reader` (+ инструмент `mcp__zai-reader__webReader`), инструменты `mcp__zai__web_search_prime` и `mcp__zai-vision__*` (изображения/видео; текстовые модели передают путь к файлу — «зрение» работает на стороне Z.ai), анализ GitHub-репозиториев через `mcp__zai-zread__*` (`search_doc`, `read_file`, `get_repo_structure`), а также чип квоты (5-часовое и недельное окна + вызовы MCP за 30 дней) рядом с композером. Чип говорит на языке интерфейса Harness: английский, русский и китайский.
172
-
173
- **Важно: регион.** Плагин работает с международным эндпоинтом `https://api.z.ai` — для пользователей **вне материкового Китая**. Для континентального Китая нужен `open.bigmodel.cn` — он не поддерживается (создайте feature-request, если нужен).
174
-
175
- **Установка:**
176
-
177
- ```powershell
178
- git clone https://github.com/FamousMonsterr/zai-web-search-mcp.git
179
- cd zai-web-search-mcp
180
- $env:ZAI_API_KEY = "<ключ>"; pwsh -NoProfile -File install.ps1
181
- # перезапустить DeepSeek Harness, затем:
182
- pwsh -NoProfile -File verify.ps1
183
- ```
184
-
185
- Ключ хранится только в `~/.dsh/.credentials.yaml` — в репозитории и в коде его нет. Обновление: `git pull` → `install.ps1` → перезапуск приложения. Для vision-инструментов нужен Node.js >= 22 и `npx` в PATH хост-процесса (при холодном кэше npx прогрейте его одной ручной загрузкой). Вернуть старый `web_fetch` — `fetchProvider: http` в `cordis.patch.yml`. Удаление — см. [`CONTRIBUTING.md`](CONTRIBUTING.md) и AGENTS.md.
186
-
187
- **Установка из npm (для любого пользователя, без git):** в чате агента DeepSeek Harness скажите «Установи плагин `dsh-zai-web-search-mcp@1.8.1`» — менеджер плагинов сам скачает пакет из реестра и активирует бандл; затем впишите свой `ZAI_API_KEY` (Models/credentials) и перезапустите приложение. Свежие версии могут придерживаться политикой `minimumReleaseAge` — тогда указывайте точную версию, как в строке выше. Готовые ссылки: [пакет на npm](https://www.npmjs.com/package/dsh-zai-web-search-mcp) · [этот репозиторий](https://github.com/FamousMonsterr/zai-web-search-mcp) · [пост в discussions DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness/discussions/12761).
188
-
189
- **Скриншоты** (Windows 11, DeepSeek Harness desktop) — чип квоты стоит в строке индикаторов композера, рядом со счётчиком контекста:
190
-
191
- ![Чип квоты в строке индикаторов композера](docs/quota-chip.png)
192
-
193
- Наведение открывает поповер «Остаток usage» — 5-часовое и недельное окна кредитов со временем сброса и числом MCP-вызовов за 30 дней:
194
-
195
- ![Поповер квоты](docs/quota-popover.png)
196
-
197
- **Правила для ИИ-агентов** — в [`AGENTS.md`](AGENTS.md) (простой английский): нашли баг или улучшение — открывайте issue/PR по шаблонам, ничего секретного не вставлять, ставить ⭐ звёздочку, даже если просто прочитали репозиторий.
198
-
199
- **Проверено на Windows 11** (dsh `0.2.1-rc.5`, плагин v1.6.0): поиск MCP, оба API квот, хост-маршрут `/zai-quota` и чип квоты в композере — всё работает, скриншоты выше.
200
-
201
- **Также проверено** (dsh `0.2.2-rc.1`, npm-пакет v1.8.1, установка из реестра через встроенный менеджер плагинов): бандл активируется автоматически, все 14 MCP-инструментов на месте, `/zai-quota` и встроенный `web_search` работают; параллельная dev-установка `@local` удаляется начисто через `remove_bundle`.
1
+ # zai-web-search-mcp
2
+
3
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
4
+ [![Platform: DeepSeek Harness](https://img.shields.io/badge/platform-DeepSeek%20Harness%20(dsh)-4B32C3.svg)](#what-this-is)
5
+ [![API: Z.ai international](https://img.shields.io/badge/Z.ai-international%20(api.z.ai)-3B82F6.svg)](#important-regions)
6
+ [![Made for GLM Coding Plan](https://img.shields.io/badge/plan-GLM%20Coding%20Plan-22C55E.svg)](#what-this-is)
7
+ [![CI](https://github.com/FamousMonsterr/zai-web-search-mcp/actions/workflows/ci.yml/badge.svg)](../../actions/workflows/ci.yml)
8
+
9
+ **A plugin for the [DeepSeek Harness](https://github.com/deepseek-ai) (dsh) desktop app that plugs your GLM Coding Plan (Z.ai) subscription into the harness:**
10
+
11
+ | # | Surface | What you get |
12
+ |---|---------|--------------|
13
+ | 1 | `web_search` | The built-in web-search tool, powered by the Z.ai `web_search_prime` MCP server |
14
+ | 2 | `mcp__zai__web_search_prime` | The same Z.ai server mounted as a standalone MCP tool |
15
+ | 3 | Quota chip | A live indicator near the composer: 5-hour & weekly credit windows + MCP calls in the last 30 days (the same data zcode shows) |
16
+ | 4 | `web_fetch` + `mcp__zai-reader__webReader` | The built-in fetch tool reads through the Z.ai `web_reader` MCP server (server-side fetch, structured markdown); the same server is also a standalone MCP tool. Revert: `fetchProvider: http` in `cordis.patch.yml` |
17
+ | 5 | `mcp__zai-vision__*` | 8 image/video tools (`analyze_image`, `analyze_video`, `extract_text_from_screenshot`, `diagnose_error_screenshot`, `ui_to_artifact`, `understand_technical_diagram`, `analyze_data_visualization`, `ui_diff_check`) from the local vision MCP server (`npx @z_ai/mcp-server`, stdio) — text-only models can analyze images by passing a file path |
18
+ | 6 | `mcp__zai-zread__*` | GitHub repository analysis through the Zread MCP server: `search_doc` (docs/issues/PRs search), `get_repo_structure` (directory tree), `read_file` (file contents) |
19
+
20
+ > ### ⭐ Star this repo
21
+ > If this plugin helped you — **even if you only read the code and never install it** — please press the Star button (top-right). It is free, and it helps other people find the plugin.
22
+ >
23
+ > Found a bug or have an idea? **AI agents and humans are equally welcome** to open issues and pull requests — see [`AGENTS.md`](AGENTS.md), [`CONTRIBUTING.md`](CONTRIBUTING.md) and the issue/PR templates.
24
+
25
+ ## Important: regions
26
+
27
+ This plugin targets the **international** Z.ai endpoint `https://api.z.ai` — it is for users **outside mainland China**. Mainland China accounts use the domestic `open.bigmodel.cn` endpoints, which this plugin does **not** support (different URLs and auth; open a feature-request issue if you need it).
28
+
29
+ ## What this is (specifically)
30
+
31
+ - Built **specifically for DeepSeek Harness (dsh) desktop** (Electron). It uses the public dsh plugin seams only — `ctx.credentials`, `ctx.web`, `ctx.webServer`, `ctx.slots`, `dsh-mcp-client` — so any other host implementing the same dsh/Cordis seams can potentially run it too.
32
+ - The API key is **never stored in this repo** and never reaches the browser: the plugin resolves the `ZAI_API_KEY` credential from the Harness store (`~/.dsh/.credentials.yaml`) at runtime.
33
+ - Zero npm dependencies; installs as a `link:` bundle into the dsh profile.
34
+ - The vision surface spawns the local `@z_ai/mcp-server` through `npx` (stdio) and needs **Node.js >= 22 and `npx` on the PATH** of the dsh host process; a cold npx cache can exceed the MCP negotiation timeout — prewarm once with `Z_AI_API_KEY=<key> npx -y @z_ai/mcp-server@latest`. Every MCP bridge failure is non-fatal: search/reader providers and the quota chip keep working.
35
+
36
+ ## Quota adapters (contributions welcome)
37
+
38
+ The quota chip follows the **active default-model provider**: it renders only while a provider has a registered quota adapter, and hides when you switch to any other model. Adapters live in `index.js` (`QUOTA_ADAPTERS`, keyed by the dsh llm provider id) and never expose API keys to the browser — the host serves the parsed snapshot only. Today `zai` (GLM Coding Plan, via the Z.ai monitoring API) is implemented. Adding your service is one entry:
39
+
40
+ ```js
41
+ // provider id = the harness llm provider id ('deepseek-official', pi-ai ids, ...)
42
+ myprovider: {
43
+ label: 'My Service',
44
+ skin: { // the chip wears the provider's identity
45
+ title: 'My Service', // popover badge
46
+ accent: { ring: '#22c55e', fiveHour: '#3b82f6', weekly: '#22c55e', mcp: '#f59e0b' },
47
+ },
48
+ async fetchQuota(getApiKey) {
49
+ return {
50
+ level: 'pro' | null,
51
+ windows: [{ kind, used, limit, remaining, percent, nextResetAt }],
52
+ mcp: { calls } | null,
53
+ }
54
+ },
55
+ }
56
+ ```
57
+
58
+ Switching the default model to a provider without an adapter hides the chip instantly (no network calls); switching back restores it within one poll (≤60 s). Pre-push integration test: `node scripts/test-quota-gate.mjs` (drives the real `apply()` with a mock ctx against the live API — expects `ALL CHECKS PASSED`).
59
+
60
+ PRs adding adapters for other services (DeepSeek balance, Anthropic usage, OpenAI billing, …) are very welcome — follow the `zai` entry, keep the key in the host, and add a verify check if the service offers a cheap status endpoint.
61
+
62
+ ## Install (on a new computer)
63
+
64
+ Requirements: **DeepSeek Harness desktop** installed and started once; **PowerShell 7+** (`pwsh`); a valid **GLM Coding Plan** key.
65
+
66
+ ```powershell
67
+ git clone https://github.com/FamousMonsterr/zai-web-search-mcp.git
68
+ cd zai-web-search-mcp
69
+
70
+ $env:ZAI_API_KEY = "<your key>" # optional: skips the manual prompt
71
+ pwsh -NoProfile -File install.ps1
72
+ ```
73
+
74
+ The installer is idempotent: it wires `~/.dsh/profiles/desktop/package.json` (bundle + `link:` dependency), checks/stores `ZAI_API_KEY`, and runs `pnpm install` using the node/pnpm bundled with dsh (nothing else to install). Then **restart DeepSeek Harness**.
75
+
76
+ ## Install for any user (npm)
77
+
78
+ The DeepSeek Harness plugin manager installs third-party plugins **from the npm registry** (it auto-probes `registry.npmjs.org` / `npmmirror`). A package carrying the `dsh.bundle.patch` field is auto-activated after install — the user needs no manual profile edits:
79
+
80
+ > Установи плагин `dsh-zai-web-search-mcp@1.8.1`
81
+
82
+ …said to the in-app agent (it runs `install_bundle` with the npm spec), or install via the Plugins page. Then store your own `ZAI_API_KEY` credential (Models/credentials) and restart the app. Note: freshly published npm versions may be held back by the manager's `minimumReleaseAge` policy — the UI then offers the exact `name@version` to pin (that is why the one-liner above pins `@1.8.1`).
83
+
84
+ The published package name is **[`dsh-zai-web-search-mcp`](https://www.npmjs.com/package/dsh-zai-web-search-mcp)** (this repo's dev install keeps the `@local/` link name; `scripts/prepare-npm.mjs` builds the publishable variant).
85
+
86
+ Ready links:
87
+
88
+ - npm package: <https://www.npmjs.com/package/dsh-zai-web-search-mcp> (latest **1.8.1**)
89
+ - Install spec for the dsh plugin manager / Plugins page: `dsh-zai-web-search-mcp@1.8.1`
90
+ - This repo: <https://github.com/FamousMonsterr/zai-web-search-mcp>
91
+ - Showcased in the DeepSeek Harness discussions: [GLM Coding Plan (Z.ai) inside DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness/discussions/12761)
92
+
93
+ ### Maintainer: publish a new version
94
+
95
+ ```powershell
96
+ node scripts/prepare-npm.mjs # -> dist/npm/ (public name, engines.dsh, renamed patch row)
97
+ npm publish ./dist/npm # NOTE the leading ./ : without it npm parses "dist/npm" as a GitHub shorthand
98
+ ```
99
+
100
+ Bump `version` in `package.json` first (and `CLIENT_INFO` in `index.js`), sync the live copy, push the tag-less commit — CI checks syntax and that no secrets are in the tree.
101
+
102
+ Publishing auth (npm's 2026 policy): a plain `npm login` web session is **no longer enough to publish** — the registry answers 403 "Two-factor authentication or granular access token with bypass 2fa enabled". Working options:
103
+
104
+ - one-time code: `npm publish ./dist/npm --otp=123456` (from your authenticator app), or
105
+ - a **granular access token** with "bypass 2FA" (npmjs.com → Access Tokens): pass it via a temporary project `.npmrc` (`//registry.npmjs.org/:_authToken=npm_…`) or `NODE_AUTH_TOKEN`; note that a token stored in the user `~/.npmrc` wins over the env var — force it with the project-level file, and **revoke the token after publishing** if it ever appeared in logs or chats.
106
+
107
+ ## Verify
108
+
109
+ ```powershell
110
+ pwsh -NoProfile -File verify.ps1
111
+ ```
112
+
113
+ Live-checks all three Z.ai integrations (MCP search, quota windows, 30-day tool usage). The key is read from the credential store and never printed. Expected final line: `ALL CHECKS PASSED`.
114
+
115
+ ## Repository documentation
116
+
117
+ | File | Purpose |
118
+ |------|---------|
119
+ | [`AGENTS.md`](AGENTS.md) | Simple-English guide for AI agents (and humans): repo map, golden rules, how to test, how to PR |
120
+ | [`CONTRIBUTING.md`](CONTRIBUTING.md) | How to contribute |
121
+ | [`SECURITY.md`](SECURITY.md) | How to report vulnerabilities; secret hygiene |
122
+ | [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) | Behavior rules |
123
+ | [Issue templates](.github/ISSUE_TEMPLATE/) / [PR template](.github/PULL_REQUEST_TEMPLATE.md) | What to include in issues and pull requests |
124
+
125
+ ## Layout
126
+
127
+ ```
128
+ index.js host side: search + reader providers, search/reader/vision MCP bridges, /zai-quota service
129
+ client.js UI side: quota chip (React) with the usage popover
130
+ cordis.patch.yml dsh patch: mount plugin, select providers "zai-mcp" (search) and "zai-reader" (fetch)
131
+ locale/{en,ru,zh}.json, icon.svg
132
+ install.ps1 / verify.ps1 human entry points
133
+ scripts/install.mjs, verify.mjs actual logic (runs on the dsh-bundled node)
134
+ ```
135
+
136
+ ## Tested on
137
+
138
+ Verified live on **Windows 11 x64** with DeepSeek Harness desktop `0.2.1-rc.5` (plugin v1.5.1/v1.6.0):
139
+
140
+ | Check | Result |
141
+ |---|---|
142
+ | MCP `web_search_prime` (initialize / tools/list / tools/call) | ✅ works, search results returned |
143
+ | Quota API (5-hour & weekly windows, plan level) | ✅ works |
144
+ | 30-day MCP tool-usage API | ✅ works |
145
+ | Host plugin: `/zai-quota` route, credential resolution, web-search provider registration | ✅ works in the Electron host |
146
+ | Client module loads and runs in the renderer (`/zai-quota-diag` lifecycle events) | ✅ confirmed |
147
+ | Quota chip mounted in the Electron composer | ✅ works (v1.6.0) — chip renders in the composer stats row, popover shows both windows + MCP calls |
148
+
149
+ Verified live on **macOS (Apple Silicon)** with DeepSeek Harness desktop `0.2.1-rc.5` (plugin v1.7.0):
150
+
151
+ | Check | Result |
152
+ |---|---|
153
+ | MCP `web_reader` (initialize / tools/list / `webReader` call) | ✅ works — `{title, url, content}` mapped to `web_fetch` |
154
+ | `web_fetch` through the `zai-reader` provider in the live host | ✅ end-to-end: built-in tool returns Z.ai markdown |
155
+ | Vision MCP bridge (stdio `npx -y @z_ai/mcp-server@latest`, 8 tools) | ✅ connects, tools register |
156
+
157
+ Verified live on **Windows 11 x64** with DeepSeek Harness desktop `0.2.2-rc.1` (npm package **v1.8.1**, installed from the registry through the built-in plugin manager):
158
+
159
+ | Check | Result |
160
+ |---|---|
161
+ | `plugin_manager install_bundle dsh-zai-web-search-mcp@1.8.1` | ✅ installs from npm, bundle auto-activates via `dsh.bundle.patch`, no manual profile edits |
162
+ | All MCP bridges after the npm install | ✅ 14 tools: `web_search_prime`, `webReader`, 8× vision, 3× zread |
163
+ | `/zai-quota` route + built-in `web_search` through `zai-mcp` | ✅ live quota windows; real search results |
164
+ | Quota popover in the zcode "Quota remaining" format (issue #2: strings on ru-RU/en-US/zh-CN hosts, adaptive width, label wrap, edge-flip) | ✅ verified live in English and Russian UIs — remaining-share percents, "Nov 9, 22:55" / "9 нояб., 22:55" app-locale dates, Last-refreshed footer |
165
+ | Side-by-side with the dev `@local` link | ✅ tested; the duplicate was cleanly removable via `remove_bundle` |
166
+
167
+ The web-search and MCP-tool surfaces do not depend on the chip and work regardless.
168
+
169
+ ## Screenshots (Windows 11, DeepSeek Harness desktop)
170
+
171
+ The quota chip sits in the composer stats row next to the context meter:
172
+
173
+ ![Quota chip in the composer stats row](docs/quota-chip-en.png)
174
+
175
+ Hovering it opens the usage popover — the 5-hour and weekly credit windows with reset times, plus MCP tool calls in the last 30 days:
176
+
177
+ ![Quota popover](docs/quota-popover-en.png)
178
+
179
+ > v1.6.0 mount fix: the chip component no longer calls `setState` during render (that triggered React's "Too many re-renders", and the slot's error boundary silently evicted the entry — the chip vanished before its first effect ran). Visibility is now purely derived; registration mirrors the built-in `activity`/`usage` pills exactly (generator factory, `locale`, order 2) with `dsh.client.immediately: true`.
180
+
181
+ ## Troubleshooting
182
+
183
+ - **Chip not visible** — make sure you run plugin v1.6.0+ (earlier versions had a render-phase `setState` that made the slot error boundary evict the chip silently) and restart the app after `install.ps1`. The quota itself is always available at the host route `/zai-quota` and via `pwsh -NoProfile -File verify.ps1`.
184
+ - **HTTP 401/403 from Z.ai** — update `ZAI_API_KEY` in the app's Models/credentials surface, then restart. The search/reader providers pick up the rotated key on the next call; the vision stdio child snapshots the key at spawn, so it needs a plugin reload (app restart) to see the new one.
185
+ - **MCP bridge fails at startup** — non-fatal by design: `web_search` and `web_fetch` keep working.
186
+ - **Vision tools missing** — the vision bridge needs `npx` and Node >= 22 reachable from the dsh host process PATH; prewarm the npx cache once (`Z_AI_API_KEY=<key> npx -y @z_ai/mcp-server@latest`) and restart the app. Check `node scripts/verify.mjs` (check 5/5).
187
+ - **Want the old anonymous fetch back** — in `cordis.patch.yml` set the `web` row's `fetchProvider` back to `http` and restart; `mcp__zai-reader__webReader` stays available as a standalone tool either way.
188
+
189
+ ## License
190
+
191
+ [MIT](LICENSE) © FamousMonsterr
192
+
193
+ ---
194
+
195
+ # По-русски
196
+
197
+ Плагин для **DeepSeek Harness (dsh) desktop**, подключающий подписку **GLM Coding Plan (Z.ai)**: веб-поиск `web_search` через MCP-сервер `web_search_prime`, чтение страниц `web_fetch` через MCP-сервер `web_reader` (+ инструмент `mcp__zai-reader__webReader`), инструменты `mcp__zai__web_search_prime` и `mcp__zai-vision__*` (изображения/видео; текстовые модели передают путь к файлу — «зрение» работает на стороне Z.ai), анализ GitHub-репозиториев через `mcp__zai-zread__*` (`search_doc`, `read_file`, `get_repo_structure`), а также чип квоты (5-часовое и недельное окна + вызовы MCP за 30 дней) рядом с композером. Чип говорит на языке интерфейса Harness: английский, русский и китайский.
198
+
199
+ **Важно: регион.** Плагин работает с международным эндпоинтом `https://api.z.ai` — для пользователей **вне материкового Китая**. Для континентального Китая нужен `open.bigmodel.cn` — он не поддерживается (создайте feature-request, если нужен).
200
+
201
+ **Установка:**
202
+
203
+ ```powershell
204
+ git clone https://github.com/FamousMonsterr/zai-web-search-mcp.git
205
+ cd zai-web-search-mcp
206
+ $env:ZAI_API_KEY = "<ключ>"; pwsh -NoProfile -File install.ps1
207
+ # перезапустить DeepSeek Harness, затем:
208
+ pwsh -NoProfile -File verify.ps1
209
+ ```
210
+
211
+ Ключ хранится только в `~/.dsh/.credentials.yaml` — в репозитории и в коде его нет. Обновление: `git pull` → `install.ps1` → перезапуск приложения. Для vision-инструментов нужен Node.js >= 22 и `npx` в PATH хост-процесса (при холодном кэше npx прогрейте его одной ручной загрузкой). Вернуть старый `web_fetch` — `fetchProvider: http` в `cordis.patch.yml`. Удаление — см. [`CONTRIBUTING.md`](CONTRIBUTING.md) и AGENTS.md.
212
+
213
+ **Установка из npm (для любого пользователя, без git):** в чате агента DeepSeek Harness скажите «Установи плагин `dsh-zai-web-search-mcp@1.8.1`» — менеджер плагинов сам скачает пакет из реестра и активирует бандл; затем впишите свой `ZAI_API_KEY` (Models/credentials) и перезапустите приложение. Свежие версии могут придерживаться политикой `minimumReleaseAge` — тогда указывайте точную версию, как в строке выше. Готовые ссылки: [пакет на npm](https://www.npmjs.com/package/dsh-zai-web-search-mcp) · [этот репозиторий](https://github.com/FamousMonsterr/zai-web-search-mcp) · [пост в discussions DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness/discussions/12761).
214
+
215
+ **Скриншоты** (Windows 11, DeepSeek Harness desktop) — чип квоты стоит в строке индикаторов композера, рядом со счётчиком контекста:
216
+
217
+ ![Чип квоты в строке индикаторов композера](docs/quota-chip.png)
218
+
219
+ Наведение открывает поповер «Остаток usage» — 5-часовое и недельное окна кредитов со временем сброса и числом MCP-вызовов за 30 дней:
220
+
221
+ ![Поповер квоты](docs/quota-popover.png)
222
+
223
+ **Правила для ИИ-агентов** — в [`AGENTS.md`](AGENTS.md) (простой английский): нашли баг или улучшение — открывайте issue/PR по шаблонам, ничего секретного не вставлять, ставить ⭐ звёздочку, даже если просто прочитали репозиторий.
224
+
225
+ **Проверено на Windows 11** (dsh `0.2.1-rc.5`, плагин v1.6.0): поиск MCP, оба API квот, хост-маршрут `/zai-quota` и чип квоты в композере — всё работает, скриншоты выше.
226
+
227
+ **Также проверено** (dsh `0.2.2-rc.1`, npm-пакет v1.8.1, установка из реестра через встроенный менеджер плагинов): бандл активируется автоматически, все 14 MCP-инструментов на месте, `/zai-quota` и встроенный `web_search` работают; параллельная dev-установка `@local` удаляется начисто через `remove_bundle`.