dsh-mcp-manager-plus 0.4.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/CHANGELOG.md ADDED
@@ -0,0 +1,50 @@
1
+ # Changelog
2
+
3
+ 本插件的全部重要变更都记录在这里。格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/),
4
+ 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
5
+
6
+ 0.3.1 之前的开发发生在公开仓库建立之前,历史没有保留。
7
+
8
+ ## [0.4.0] - 2026-09-17
9
+
10
+ ### Added
11
+
12
+ - **多语言界面(中文 / English)**:页面头部新增语言切换器(自动 / 中文 / English)
13
+ - 「自动」跟随 harness 界面语言;locale 服务不可达时按浏览器语言探测,兜底中文
14
+ - 用户的选择持久化到 localStorage,刷新后依然有效
15
+ - **宿主端文案双语化**:每次 API 请求携带 `?lang=` 参数,服务名校验、重名/占用、
16
+ 导入汇总(如 `Recognized Codex configuration; Added github`)、重启提示、403/404
17
+ 等约 30 条消息跟随所选语言;不带参数时默认中文,旧行为不变
18
+ - 测试:新增 `lang=en` 英文响应与默认中文回归两个用例(总数 106 → 108)
19
+
20
+ ## [0.3.1] - 2026-09-17
21
+
22
+ 首个公开发布版本。
23
+
24
+ ### Added
25
+
26
+ - **「MCP 管理」设置页**:在 DeepSeek Harness 设置界面侧边栏新增管理页面
27
+ - 列表:展示配置文件中的 MCP 服务器、部署内置服务器与 Computer Use / Browser Use
28
+ 等内置能力
29
+ - 展开:查看服务器当前注册到模型的全部工具及描述
30
+ - 启用 / 停用:写入补丁层 `disabled` 覆盖,约 1 秒热生效,无需重启 dsh
31
+ - 编辑:**表单**与 **JSON** 双模式随时切换;JSON 模式打开即预填当前配置,
32
+ 改服务名即为重命名(保留行 id 与启停覆盖);一次粘贴多个服务器会被拒绝并列出名字
33
+ - 重启:就地销毁并重新初始化连接,用于连接中断后恢复
34
+ - 删除:从配置文件移除服务器及其全部覆盖行
35
+ - **一键导入**:粘贴 14 种主流工具的 MCP 配置自动识别——Claude Code、Cursor、
36
+ Windsurf、Qoder、Cherry Studio、CodeBuddy、TRAE、ZCode、DeepSeek Harness、
37
+ VS Code(`servers`)、Codex(**TOML**)、OpenCode(`mcp` + command 数组)、
38
+ Continue(数组形式)、Pi;兼容 TOML、JSON 注释与尾逗号、`type:"sse"`、
39
+ `serverUrl`、`http_headers` 等差异,单条失败不影响整段粘贴
40
+ - **侧边栏图标**:注册时即把导航行图标换成与外壳一致的链条图标
41
+ (MutationObserver 预标记 + 页面挂载兜底),无需先点进页面
42
+ - **安全约定**:API 仅响应 loopback;写前整体校验、拒绝非法补丁文档;
43
+ 注释与无关条目逐字节保留;凭据形值(`KEY|PASSWORD|SECRET|TOKEN`)读取即掩码;
44
+ 部署内置行只读
45
+ - **测试**:7 个套件共 106 项(`node:test`,零依赖),覆盖补丁层解析、14 格式导入、
46
+ JSON 编辑、宿主路由、bundle 加载、profile 组合与真实 profile 只读验证;
47
+ 另附 e2e 导入、往返校验、图标预览等辅助脚本
48
+
49
+ [0.4.0]: https://github.com/appthin/dsh-mcp-manager-plus/compare/v0.3.1...v0.4.0
50
+ [0.3.1]: https://github.com/appthin/dsh-mcp-manager-plus/tree/v0.3.1
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 dsh-mcp-manager-plus contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.en.md ADDED
@@ -0,0 +1,271 @@
1
+ # dsh-mcp-manager-plus
2
+
3
+ English | [中文](README.md) | [Changelog](CHANGELOG.md)
4
+
5
+ An MCP server manager plugin for DeepSeek Harness: it adds an "MCP" page to the
6
+ settings sidebar, where you can inspect, enable/disable, edit, restart, delete
7
+ and add MCP servers.
8
+
9
+ Why this plugin exists:
10
+
11
+ - To manage MCP servers in DeepSeek Harness without ever opening a config file.
12
+ - Most MCP-related plugins on the plugin market target older DSH releases and
13
+ simply do not work on current ones, so I had to write my own.
14
+
15
+ If this plugin stops working on a newer DSH release, please open an issue.
16
+
17
+ ## Screenshots
18
+
19
+ **Settings → MCP**: the server list, connection state and enable/disable toggles.
20
+
21
+ ![MCP manager main page](screenshot1.jpg)
22
+
23
+ **Expand a server**: every tool the server currently registers with the model,
24
+ with descriptions.
25
+
26
+ ![Expanded tool list](screenshot5.jpg)
27
+
28
+ **Add**: paste an MCP configuration from any tool — the format is detected
29
+ automatically (Codex's TOML and JSON-with-comments included).
30
+
31
+ ![Paste-to-import dialog](screenshot2.jpg)
32
+
33
+ **Edit · form mode**: edit field by field; switch to JSON mode at any time from
34
+ the dialog header.
35
+
36
+ ![Form-mode editor](screenshot3.jpg)
37
+
38
+ **Edit · JSON mode**: opens pre-filled with the server's current configuration;
39
+ paste a whole replacement block, and renaming is just changing the name.
40
+
41
+ ![JSON-mode editor](screenshot4.jpg)
42
+
43
+ ## Installation
44
+
45
+ **Requirements:** DSH >= 0.1.5-rc.1 (developed and tested on 0.1.6-alpha.1).
46
+ DSH itself needs Node.js >= 24.2.0 and Git >= 2.31.0.
47
+
48
+ ### Option 1: one-click install from the plugin market
49
+
50
+ If you have [dshmarket](https://github.com/dsh-market/dsh-market) installed,
51
+ open **Settings → Plugin market**, search for `dsh-mcp-manager-plus`, and click
52
+ install.
53
+
54
+ ### Option 2: command line
55
+
56
+ Pick any one of the three sources (`--profile web` installs into the `web`
57
+ profile; substitute your own profile name as needed):
58
+
59
+ ```sh
60
+ # npm package (available once published)
61
+ dsh plugin --profile web add dsh-mcp-manager-plus
62
+
63
+ # GitHub repository
64
+ dsh plugin --profile web add https://github.com/appthin/dsh-mcp-manager-plus.git
65
+
66
+ # Local directory (clone this repository first; installed as a link, so edits
67
+ # take effect immediately — handy for development)
68
+ dsh plugin --profile web add <the cloned repository directory>
69
+ ```
70
+
71
+ Restart dsh (or wait for the profile hot-reload); the page appears under
72
+ **Settings → MCP**.
73
+
74
+ ### Verify
75
+
76
+ Open dsh web and go to **Settings → MCP** (the chain-link icon in the sidebar).
77
+ If the page does not show up, check in this order:
78
+
79
+ 1. Switch to the latest Chrome/Edge — plugin bundles can fail to load on
80
+ Chromium kernels older than 122;
81
+ 2. Confirm it is installed into the profile you are actually running
82
+ (`dsh plugin --profile web ls` lists the profile contents);
83
+ 3. If the browser console shows errors, [open an issue](../../issues/new) with
84
+ the message attached.
85
+
86
+ ### Update & uninstall
87
+
88
+ ```sh
89
+ dsh plugin --profile web ls # list installed plugins
90
+ dsh plugin --profile web add dsh-mcp-manager-plus # update (re-adding installs the latest)
91
+ dsh plugin --profile web remove dsh-mcp-manager-plus # uninstall
92
+ ```
93
+
94
+ With the plugin market installed, updates can also be done with one click on
95
+ its page. Uninstalling keeps the MCP server rows this plugin wrote into the
96
+ profile patch layer — that is your configuration data and will not be deleted.
97
+
98
+ ## Features
99
+
100
+ | Capability | Description |
101
+ | --- | --- |
102
+ | List | Shows the MCP servers from the config file |
103
+ | Expand | Open a row to see every tool the server registers with the model, with descriptions |
104
+ | Enable / disable | Writes a `disabled` override into the patch layer; takes effect hot in ~1 s, no dsh restart |
105
+ | Edit | Two switchable modes: **form** (field by field) or **JSON** (one large textarea), see below |
106
+ | Restart | Destroys and re-initializes the server's connection in place (config unchanged); for recovering from dropped connections |
107
+ | Delete | Removes the server and all of its override rows from the config file |
108
+ | Add | Paste an MCP configuration from **any mainstream tool**; the format is detected, and multiple servers per paste are supported (see table below) |
109
+ | Bilingual | Chinese / English. Defaults to the harness UI language (falling back to the browser's language when unavailable); switch anytime from the page header — the choice is remembered, and host-side messages follow along |
110
+
111
+ ## The two edit modes
112
+
113
+ When editing an existing server, the dialog header carries a **segmented
114
+ switch** (with icons and a sliding indicator, `radiogroup` semantics, arrow-key
115
+ navigable) to flip between modes at any time:
116
+
117
+ - **Form mode**: edit field by field (server name, transport, command, args,
118
+ env, cwd, URL, headers).
119
+ - **JSON mode**: one large textarea that **opens pre-filled with the server's
120
+ current configuration** (not an empty box or an example), so you can paste a
121
+ whole replacement block — especially handy for configs copied from elsewhere.
122
+ A collapsible format guide above the box lists the supported tools and their
123
+ container keys, shared with the "Add" dialog.
124
+
125
+ Both modes write to the same row, therefore:
126
+
127
+ - **Renaming in JSON mode renames the row**: it keeps the original `id` and its
128
+ enable/disable overrides instead of creating a duplicate;
129
+ - JSON mode supports every import format (Codex's TOML included), since format
130
+ parsing is independent of add-vs-edit;
131
+ - A paste containing **multiple** servers is rejected with their names listed,
132
+ avoiding the "which one actually got saved?" ambiguity;
133
+ - Switching back to form mode reads the row from disk, so half-edited JSON
134
+ never leaks across modes.
135
+
136
+ > JSON mode exists only for **existing** servers: saving JSON means "update the
137
+ > named row", which needs a row name. New servers go through "Add", which is
138
+ > already JSON mode.
139
+
140
+ The container-key table in the format guide (`FORMAT_ROWS`) must agree with the
141
+ parser or the guide would lie — a test in `test/client.test.mjs` cross-checks
142
+ both: every key in the table must actually parse, and all 14 tool names the
143
+ parser supports must appear in the table.
144
+
145
+ ## Supported import formats
146
+
147
+ Paste as-is; the plugin recognizes container keys, field names and file syntax:
148
+
149
+ | Tool | Container key | stdio | Remote | Notes |
150
+ | --- | --- | --- | --- | --- |
151
+ | Claude Code · Cursor · Windsurf · Qoder · Cherry Studio · CodeBuddy · TRAE · ZCode | `mcpServers` | `command`/`args` | `url`/`headers` | the standard format |
152
+ | DeepSeek Harness (this plugin itself) | `mcpServers` | `command`/`args` | `url`/`headers` | native format |
153
+ | VS Code | **`servers`** | `command`/`args` | `type:"http"` + `url` | different outer key |
154
+ | Codex | `mcp_servers` | `command`/`args` | `url` | **TOML**, not JSON |
155
+ | OpenCode | `mcp` | `type:"local"`, **command is an array** | `type:"remote"` + `url` | most divergent shape |
156
+ | Continue | `mcpServers` **array** | `command`/`args` | — | name lives inside each entry |
157
+ | Pi | `mcpServers` + `settings` | `command`/`args` | `transport:"streamable-http"` | `settings` is ignored |
158
+
159
+ These variations are also handled:
160
+
161
+ - **TOML input**: Codex's `config.toml` can be pasted directly (including
162
+ nested `[…​.env]` tables and inline comments).
163
+ - **JSON comments and trailing commas**: docs for several tools carry `//`,
164
+ `/* */` and trailing commas — all parse fine.
165
+ - **`type:"sse"`** maps onto this plugin's streamable-http transport.
166
+ - **`serverUrl`** (Windsurf's remote spelling), **`http_headers`** (Codex) and
167
+ **command arrays** (OpenCode) are all filed correctly.
168
+ - **Unknown fields** such as `enabled`, `lifecycle` or `description` never fail
169
+ an import; they are just not written to the config.
170
+
171
+ The import reports the detected source, e.g. `已识别 Codex 配置;新增 xxx`
172
+ ("Codex configuration detected; added xxx"). A single failing entry is skipped
173
+ and listed with its reason, so one bad block does not waste the whole paste.
174
+
175
+ ## Where the config lives
176
+
177
+ The plugin's single source of truth is the current profile's user patch layer:
178
+
179
+ ```
180
+ $DSH_HOME/profiles/<profile>/cordis.patch.yml
181
+ ```
182
+
183
+ Adding an MCP server appends one loader patch entry to that file:
184
+
185
+ ```yaml
186
+ - insert:
187
+ - id: mcp-github
188
+ name: '@deepseek-ai/dsh-mcp-client'
189
+ config:
190
+ serverName: github
191
+ transport: stdio
192
+ command: npx
193
+ args: ["-y", "@modelcontextprotocol/server-github"]
194
+ env:
195
+ GITHUB_TOKEN: "…"
196
+ ```
197
+
198
+ Disabling writes a sibling override row instead:
199
+
200
+ ```yaml
201
+ - id: mcp-github
202
+ disabled: true
203
+ ```
204
+
205
+ Because the profile runs with `patchReload: live`, the loader re-orchestrates
206
+ the plugin tree within about a second of each save, so config changes are both
207
+ **persistent and hot-effective** — the plugin never mutates the running loader
208
+ tree; it only writes the file, then the browser briefly polls to observe the
209
+ converged state.
210
+
211
+ ## Security model
212
+
213
+ - **Loopback only.** The API lives on the same loopback web server; non-loopback
214
+ origins get a 403.
215
+ - **Validate before writing.** Every candidate file is re-parsed as a
216
+ top-level loader patch array; a parse failure refuses the write, so one bad
217
+ edit cannot break the next boot.
218
+ - **Nothing outside its jurisdiction.** The file is hand-written by users:
219
+ comments, unrelated entries and unknown fields survive a rewrite untouched —
220
+ only the one modified block is rewritten.
221
+ - **Secrets stay local.** Values whose keys look like
222
+ `KEY|PASSWORD|SECRET|TOKEN` are masked on read, and unmasked again when the
223
+ browser echoes them back; real secrets never appear on the page.
224
+ - **Bundle-provided servers are read-only.** Rows contributed by the bundle
225
+ layer can be enabled/disabled but not edited or deleted.
226
+
227
+ ## Development
228
+
229
+ ```sh
230
+ node test/run.mjs # all seven suites (106 assertions)
231
+ ```
232
+
233
+ | Suite | Coverage |
234
+ | --- | --- |
235
+ | `test/patch.test.mjs` | patch-layer segmentation, parsing, validation, generation and byte-exact round-trips |
236
+ | `test/import.test.mjs` | config formats of 14 tools, the TOML subset, JSON comments and trailing commas |
237
+ | `test/editjson.test.mjs` | JSON-mode editing: in-place updates, renames keeping id and overrides, multi-server rejection |
238
+ | `test/host.test.mjs` | every host-side HTTP route, driving the real `apply()` through a fake Cordis context |
239
+ | `test/client.test.mjs` | whether the shell can load the browser bundle and register the settings page, mode switch included |
240
+ | `test/compose.test.mjs` | composing a real profile from the bundle layer, confirming this plugin's rows mount |
241
+ | `test/live.test.mjs` | read-only run against the real profile, confirming live configs read correctly with secrets masked |
242
+
243
+ The tests use no test framework — just Node's built-in `node:test` — and reuse
244
+ the `js-yaml` from the profile (the same parse path as the runtime).
245
+
246
+ ### Layout
247
+
248
+ | File | Purpose |
249
+ | --- | --- |
250
+ | `lib/index.js` | host side: HTTP API, inventory projection, write operations |
251
+ | `lib/import.js` | import parsing: each tool's config format → this plugin's server shape |
252
+ | `lib/patch.js` | patch-layer read/write: segmentation, parsing, validation, generation |
253
+ | `lib/client.js` | browser side: the settings page UI (hand-written lazy-CJS bundle, no build step) |
254
+ | `cordis.patch.yml` | the bundle patch inserting this plugin into the profile's layer stack |
255
+
256
+ ### Helper scripts
257
+
258
+ | Script | Purpose |
259
+ | --- | --- |
260
+ | `node tools/e2e-import.mjs` | boots a real host and POSTs each of the 14 tool formats to `/import`, then validates the written patch rows |
261
+ | `node tools/roundtrip-json.mjs` | verifies the JSON editor's pre-filled config round-trips byte-for-byte (confirming unchanged content drops no fields) |
262
+ | `node tools/check-client-bundle.mjs` | loads the client bundle the way the shell does and checks the registration result and nav-icon CSS |
263
+ | `node tools/check-segmented.mjs` | checks the segmented switch's slider geometry (inset, half-width, offset) against the track assumptions |
264
+ | `node tools/preview-edit-modes.mjs` | renders both edit-dialog modes with the real components into `edit-modes-preview.html` |
265
+ | `node tools/check-nav-icon.mjs` | checks that the nav icon's mask payload is a drawable 16×16 template |
266
+ | `node tools/gen-icon-preview.cjs` | extracts icons from the dsh web bundle into the `icon-options.html` comparison page |
267
+ | `node tools/dump-icon.cjs <IconName>` | prints an icon's SVG path for hand-written overrides |
268
+
269
+ ## License
270
+
271
+ MIT
package/README.md ADDED
@@ -0,0 +1,235 @@
1
+ # dsh-mcp-manager-plus
2
+
3
+ [English](README.en.md) | 中文 | [更新日志](CHANGELOG.md)
4
+
5
+ MCP 服务器管理插件:在 DeepSeek Harness 设置界面的左侧边栏新增「MCP 管理」页面,
6
+ 可直接查看、启用/停用、编辑、重启、删除与添加 MCP 服务器。
7
+
8
+ 为什么要开发这个插件?
9
+ - 为了方便管理 DeepSeek Harness 中的 MCP 服务器,无需打开配置文件。
10
+ - 插件市场中的其他MCP插件大多都是支持以前旧版本的DSH,安装在新版DSH上根本没法使用,我不得不自己写一个。
11
+
12
+ 如果你发现本插件在新版DSH上无法正常工作,请提交一个 issue。
13
+
14
+ ## 截图
15
+
16
+ **设置 → MCP 管理**:服务器列表、连接状态与启停开关。
17
+
18
+ ![MCP 管理主页面](screenshot1.jpg)
19
+
20
+ **展开服务器**:查看该服务器当前注册到模型的全部工具及描述。
21
+
22
+ ![展开查看工具列表](screenshot5.jpg)
23
+
24
+ **添加**:直接粘贴任意工具的 MCP 配置,自动识别格式(含 Codex 的 TOML 与带注释的 JSON)。
25
+
26
+ ![粘贴导入配置](screenshot2.jpg)
27
+
28
+ **编辑 · 表单模式**:逐字段修改,弹窗顶部可随时切换到 JSON 模式。
29
+
30
+ ![表单模式编辑](screenshot3.jpg)
31
+
32
+ **编辑 · JSON 模式**:打开即预填该服务器当前配置,可整段粘贴替换;改服务名即为重命名。
33
+
34
+ ![JSON 模式编辑](screenshot4.jpg)
35
+
36
+ ## 安装说明
37
+
38
+ **版本要求:** DSH >= 0.1.5-rc.1(在 0.1.6-alpha.1 上开发并测试)。DSH 自身依赖 Node.js >= 24.2.0 与 Git >= 2.31.0。
39
+
40
+ ### 方式一:插件市场一键安装
41
+
42
+ 已安装 [dshmarket](https://github.com/dsh-market/dsh-market) 的话,打开 **设置 → 插件市场**,
43
+ 搜索 `dsh-mcp-manager-plus`,点一下安装即可。
44
+
45
+ ### 方式二:命令行安装
46
+
47
+ 三种来源任选其一(`--profile web` 表示装进 `web` profile,其他 profile 同理替换):
48
+
49
+ ```sh
50
+ # npm 包(发布后可用)
51
+ dsh plugin --profile web add dsh-mcp-manager-plus
52
+
53
+ # GitHub 仓库
54
+ dsh plugin --profile web add https://github.com/appthin/dsh-mcp-manager-plus.git
55
+
56
+ # 本地目录(先把仓库 clone 到本地;以 link 方式安装,改动即时生效,适合开发调试)
57
+ dsh plugin --profile web add <clone 下来的本仓库目录>
58
+ ```
59
+
60
+ 随后重启 dsh(或等待 profile 热重载),在「设置 → MCP 管理」即可看到页面。
61
+
62
+ ### 验证
63
+
64
+ 打开 dsh web,进入 **设置 → MCP 管理**(侧边栏链条图标的那一项)。
65
+ 页面没有出现时的排查顺序:
66
+
67
+ 1. 换最新版 Chrome/Edge —— 部分插件的 bundle 在 Chromium 122 以下的内核会加载失败;
68
+ 2. 确认装进了正在使用的 profile(`dsh plugin --profile web ls` 查看清单);
69
+ 3. 浏览器控制台有报错时,附上报错内容[提交 issue](../../issues/new)。
70
+
71
+ ### 更新与卸载
72
+
73
+ ```sh
74
+ dsh plugin --profile web ls # 查看已装插件
75
+ dsh plugin --profile web add dsh-mcp-manager-plus # 更新(重新 add 即覆盖为最新版)
76
+ dsh plugin --profile web remove dsh-mcp-manager-plus # 卸载
77
+ ```
78
+
79
+ 装有插件市场时,更新也可以在市场页一键完成。卸载后 profile 补丁层里由本插件写入的
80
+ MCP 服务器行会原样保留——它们是你的配置数据,不会被连带删除。
81
+
82
+ ## 功能
83
+
84
+ | 能力 | 说明 |
85
+ | --- | --- |
86
+ | 列表 | 展示配置文件中的 MCP 服务器 |
87
+ | 展开 | 点开一行查看该服务器当前注册到模型的所有工具及其描述 |
88
+ | 启用 / 停用 | 写入补丁层的 `disabled` 覆盖,约 1 秒内热生效,无需重启 dsh |
89
+ | 编辑 | 两种模式可随时切换:**表单**(逐字段)或 **JSON**(大输入框),见下节 |
90
+ | 重启 | 就地销毁并重新初始化该服务器的连接(配置不变),用于连接中断后恢复 |
91
+ | 删除 | 从配置文件中移除该服务器及其所有覆盖行 |
92
+ | 添加 | 粘贴**任意主流工具**的 MCP 配置即可,自动识别格式,支持一次导入多个(见下表) |
93
+ | 多语言 | 中文 / English。默认跟随界面语言(取不到时按浏览器语言探测),页面右上角可随时切换并记住选择;宿主端的错误与提示文案同样跟随 |
94
+
95
+ ## 编辑时的两种模式
96
+
97
+ 编辑已有服务器时,弹窗标题右侧有一个**分段开关**(带图标、带滑动指示块,`radiogroup` 语义,
98
+ 支持左右方向键),随时可来回切换:
99
+
100
+ - **表单模式**:逐字段编辑(服务名、连接方式、命令、参数、环境变量、工作目录、URL、请求头)。
101
+ - **JSON 模式**:一个大输入框,**打开时已填入该服务器当前的配置**(而不是空框或示例),
102
+ 可以直接整段替换粘贴 —— 粘贴别处复制来的配置片段尤其方便。
103
+ 框上方有一份**可折叠的格式说明**,列出支持哪些工具、各自的容器键是什么,
104
+ 与「添加」弹窗共用同一个组件。
105
+
106
+ 两种模式最终都写入同一行,因此:
107
+
108
+ - JSON 里**改服务名即为重命名**,该行会保留原来的 `id` 与启用/停用覆盖,不会多出一个副本;
109
+ - JSON 模式同样支持全部导入格式(含 Codex 的 TOML),因为格式解析与编辑/新增无关;
110
+ - 一次粘贴里出现**多个**服务器时会被拒绝并列出名字,避免「到底保存了哪个」的歧义;
111
+ - 切回表单模式时以磁盘上的行为准,不会带过去 JSON 框里改了一半的内容。
112
+
113
+ > 只有**已存在**的服务器才有 JSON 模式:JSON 保存是「更新指定的一行」,需要一个行名。
114
+ > 新增走「添加」按钮,它本来就是 JSON 模式。
115
+
116
+ 格式说明里的容器键表(`FORMAT_ROWS`)与解析器必须一致,否则说明就是错的 ——
117
+ `test/client.test.mjs` 有一条测试把两边对起来验:表里每个键都真的能被解析,
118
+ 解析器支持的 14 个工具名也都必须出现在表里。
119
+
120
+ ## 支持导入的配置格式
121
+
122
+ 粘贴时不需要改写,插件会识别容器键、字段名与文件语法:
123
+
124
+ | 工具 | 容器键 | stdio | 远程 | 备注 |
125
+ | --- | --- | --- | --- | --- |
126
+ | Claude Code · Cursor · Windsurf · Qoder · Cherry Studio · CodeBuddy · TRAE · ZCode | `mcpServers` | `command`/`args` | `url`/`headers` | 标准格式 |
127
+ | DeepSeek Harness(本插件自身) | `mcpServers` | `command`/`args` | `url`/`headers` | 原生格式 |
128
+ | VS Code | **`servers`** | `command`/`args` | `type:"http"` + `url` | 外层键不同 |
129
+ | Codex | `mcp_servers` | `command`/`args` | `url` | **TOML**,不是 JSON |
130
+ | OpenCode | `mcp` | `type:"local"`,**command 是数组** | `type:"remote"` + `url` | 结构差异最大 |
131
+ | Continue | `mcpServers` **数组** | `command`/`args` | — | 名字在条目里 |
132
+ | Pi | `mcpServers` + `settings` | `command`/`args` | `transport:"streamable-http"` | `settings` 会被忽略 |
133
+
134
+ 另外还兼容这些差异:
135
+
136
+ - **TOML 输入**:Codex 的 `config.toml` 直接粘贴即可(含嵌套的 `[…​.env]` 表与行内注释)。
137
+ - **JSON 注释与尾逗号**:多个工具的文档示例带 `//`、`/* */` 和尾逗号,均可解析。
138
+ - **`type:"sse"`**:映射到本插件的 streamable-http 传输。
139
+ - **`serverUrl`**(Windsurf 的远程写法)、**`http_headers`**(Codex)、**command 数组**(OpenCode)
140
+ 都会被正确归位。
141
+ - **未知字段**:如 `enabled`、`lifecycle`、`description` 等不会导致导入失败,只是不写入配置。
142
+
143
+ 导入时会报出识别到的来源,例如 `已识别 Codex 配置;新增 xxx`;单条失败只跳过该条,
144
+ 并把它和失败原因一并列出,不会让整段粘贴白费。
145
+
146
+ ## 配置写在哪里
147
+
148
+ 插件的「唯一真相」是当前 profile 的用户补丁层:
149
+
150
+ ```
151
+ $DSH_HOME/profiles/<profile>/cordis.patch.yml
152
+ ```
153
+
154
+ 新增一个 MCP 服务器就是向该文件追加一行 loader patch entry:
155
+
156
+ ```yaml
157
+ - insert:
158
+ - id: mcp-github
159
+ name: '@deepseek-ai/dsh-mcp-client'
160
+ config:
161
+ serverName: github
162
+ transport: stdio
163
+ command: npx
164
+ args: ["-y", "@modelcontextprotocol/server-github"]
165
+ env:
166
+ GITHUB_TOKEN: "…"
167
+ ```
168
+
169
+ 停用则是同级的 `disabled` 覆盖行:
170
+
171
+ ```yaml
172
+ - id: mcp-github
173
+ disabled: true
174
+ ```
175
+
176
+ 因为 profile 使用 `patchReload: live`,保存后 loader 会在约 1 秒内重新编排插件树,
177
+ 所以配置改动**既是持久化的,也是热生效的** —— 插件本身不改动运行中的 loader 树,
178
+ 只写文件,然后由浏览器端短暂轮询观察收敛后的实际状态。
179
+
180
+ ## 安全约定
181
+
182
+ - **只响应本机请求。** API 挂在同一个 loopback web server 上,非 loopback 来源直接 403。
183
+ - **写入前必校验。** 每份候选文件都会重新解析为「顶层 loader patch 数组」,
184
+ 解析失败则拒绝写入,因此一次错误编辑不会让下次启动失败。
185
+ - **不碰不归它管的内容。** 文件是用户手写的:注释、无关条目、未知字段在改写后原样保留,
186
+ 只重写被改动的那一个块。
187
+ - **凭据不外传。** 形如 `KEY|PASSWORD|SECRET|TOKEN` 的配置值在读取时被掩码,
188
+ 浏览器回传掩码时再从原值还原,真实密钥不会出现在页面里。
189
+ - **部署内置的服务器只读。** 由 bundle 层提供的行可以停用/启用,但不能编辑或删除。
190
+
191
+ ## 开发
192
+
193
+ ```sh
194
+ node test/run.mjs # 全部七个测试套件(共 106 项)
195
+ ```
196
+
197
+ | 套件 | 覆盖范围 |
198
+ | --- | --- |
199
+ | `test/patch.test.mjs` | 补丁层分段、解析、校验、生成与逐字节往返 |
200
+ | `test/import.test.mjs` | 14 种工具的配置格式、TOML 子集、JSON 注释与尾逗号 |
201
+ | `test/editjson.test.mjs` | JSON 模式编辑:原地更新、重命名保留 id 与覆盖、多条拒绝 |
202
+ | `test/host.test.mjs` | 宿主端全部 HTTP 路由,用假的 Cordis 上下文驱动真实 `apply()` |
203
+ | `test/client.test.mjs` | 浏览器 bundle 能否被 shell 加载并注册设置页,含模式开关 |
204
+ | `test/compose.test.mjs` | 用真实的 bundle 层组合 profile,确认本插件的行能挂载 |
205
+ | `test/live.test.mjs` | 只读地跑真实 profile,确认线上配置能被正确读出且凭据已掩码 |
206
+
207
+ 测试不依赖任何测试框架,只用 Node 内置的 `node:test`,并复用 profile 中已有的
208
+ `js-yaml`(与运行时同一条解析路径)。
209
+
210
+ ### 结构
211
+
212
+ | 文件 | 作用 |
213
+ | --- | --- |
214
+ | `lib/index.js` | 宿主端:HTTP API、清单投影、写操作 |
215
+ | `lib/import.js` | 导入解析:各工具配置格式 → 本插件的服务器形状 |
216
+ | `lib/patch.js` | 补丁层读写:分段、解析、校验、生成 |
217
+ | `lib/client.js` | 浏览器端:设置页面 UI(手写 lazy-CJS bundle,无构建步骤) |
218
+ | `cordis.patch.yml` | bundle 补丁,把本插件插入 profile 的层栈 |
219
+
220
+ ### 辅助脚本
221
+
222
+ | 脚本 | 作用 |
223
+ | --- | --- |
224
+ | `node tools/e2e-import.mjs` | 起真实宿主端,把 14 种工具的配置逐个 POST 到 `/import`,再校验写出的补丁行 |
225
+ | `node tools/roundtrip-json.mjs` | 校验 JSON 模式预填的配置能原样往返(不改任何内容点确认不会丢字段) |
226
+ | `node tools/check-client-bundle.mjs` | 按 shell 的方式加载客户端 bundle,检查注册结果与导航图标 CSS |
227
+ | `node tools/check-segmented.mjs` | 校验分段开关的滑块几何(内缩、半宽、位移)与轨道假设一致 |
228
+ | `node tools/preview-edit-modes.mjs` | 用真实组件渲染编辑弹窗的两种模式,生成 `edit-modes-preview.html` |
229
+ | `node tools/check-nav-icon.mjs` | 校验导航图标的 mask 载荷是合法可绘制的 16×16 模板 |
230
+ | `node tools/gen-icon-preview.cjs` | 从 dsh 前端 bundle 提取图标,生成 `icon-options.html` 对照页 |
231
+ | `node tools/dump-icon.cjs <IconName>` | 打印某个内置图标的 SVG 路径,便于手写覆盖 |
232
+
233
+ ## License
234
+
235
+ MIT
@@ -0,0 +1,8 @@
1
+ # dsh-mcp-manager-plus bundle patch: inserts this plugin into a profile's
2
+ # layer stack. The host half (lib/index.js) serves the management API on the
3
+ # loopback web server; the `dsh.client` declaration in package.json makes the
4
+ # web app load lib/client.js as the browser half, which registers the
5
+ # "MCP 管理" page in the settings sidebar.
6
+ - insert:
7
+ - id: mcp-manager-plus
8
+ name: dsh-mcp-manager-plus