dsh-mcp-connector 0.2.57 → 0.2.58

package/CHANGELOG.md

@@ -4,6 +4,14 @@
 
 ## [Unreleased]
 
+## [0.2.58] - 2026-09-22
+
+### Documentation
+
+- 优化中英文首屏及外部目录介绍，明确 MCP 管理面板、授权配置和服务商权限边界。
+- 新增 JSON 迁移、OAuth 诊断和工具搜索恢复三篇任务教程，并验证教程随 npm 包发布。
+- 更新外部市场分发核验记录，区分上架、元数据同步、安装和真实调用验收。
+
 ## [0.2.57] - 2026-09-22
 
 ### Fixed

package/README.en.md

@@ -1,9 +1,11 @@
 # Connect, Find, and Troubleshoot MCP Servers in DeepSeek Harness
 
-> 100+ MCP connectors for DeepSeek Harness, one place to connect MCP servers, search tools across connections, and troubleshoot connections.
+> MCP Connector for DeepSeek Harness: one panel to connect MCP servers, manage authorization, search tools across connections, and troubleshoot failures; browse 100+ connectors in a continuously updated catalog.
 
 Connect MCP servers from a continuously updated catalog. Search tools across enabled connections in the current scope, inspect readable parameters, source metadata, and the last successful cache time, then check a connection or rediscover its tools when discovery fails. Supports OAuth 2.0 PKCE, API keys, Streamable HTTP/stdio, and `mcpServers` JSON import.
 
+OAuth availability depends on each provider's client-registration policy and account permissions. Verify a saved connection, discovered/registered tools, and a successful business call as separate outcomes.
+
 > Here, “skill extension” means extending an agent through MCP tools and prompts; this package does not present itself as a standalone DSH Skill.
 
 [简体中文](README.md)
@@ -36,6 +38,10 @@ dsh plugin --profile web add dsh-mcp-connector
 
 Fully restart DeepSeek Harness Desktop or `dsh web` after installation or upgrade, then open **MCP Connector** in the primary sidebar, or open it directly from **Settings → Plugins → Plugin Configuration → MCP Connector**.
 
+For a first successful use, confirm the connection and scope in Installed, find the expected tool and source in Tools, then complete one provider-permitted read-only call through the normal DSH Host approval flow. Cached visibility alone does not prove that a service is currently callable.
+
+Task guides (Chinese): [migrate `mcpServers` JSON](docs/tutorials/JSON-MIGRATION.md) · [diagnose OAuth](docs/tutorials/OAUTH-DIAGNOSTICS.md) · [find and recover tools](docs/tutorials/TOOL-SEARCH-RECOVERY.md).
+
 ![43-second MCP Connector walkthrough](https://raw.githubusercontent.com/duhu2000/dsh-mcp-connector/main/docs/demo.gif)
 
 If the plugin helps you connect an MCP server faster, consider [starring the repository](https://github.com/duhu2000/dsh-mcp-connector/stargazers), [submitting a connector](https://github.com/duhu2000/dsh-mcp-connector-registry/blob/main/docs/ONBOARDING.md), or [contributing a fix](CONTRIBUTING.md).
@@ -125,6 +131,7 @@ The detailed [Chinese user guide](docs/USER-GUIDE.md) covers category browsing,
 ## Guides and ecosystem
 
 - [User guide: installation, authorization, diagnostics, compatibility, and troubleshooting](docs/USER-GUIDE.md)
+- [Task guides: JSON migration, OAuth diagnostics, and cross-connection tool recovery](docs/USER-GUIDE.md#按任务开始)
 - [Connection scopes: project/global inheritance, copy, move, and rollback](docs/CONNECTION-SCOPES.md)
 - [Connection, Server, and Tool governance](docs/TOOL-GOVERNANCE.md)
 - [Tool trial: official API evidence and safety design](docs/TOOL-TRIAL-DESIGN.md)
@@ -190,7 +197,7 @@ npm run dev:ui
 
 Every Registry merge regenerates `catalog-stats.json`; an hourly workflow in this repository synchronizes the Chinese and English product copy plus a local stats snapshot. The static npm README updates with package releases, while the live badges above read the Registry directly and therefore stay current without another npm release.
 
-The current public version is [`dsh-mcp-connector@0.2.57`](https://www.npmjs.com/package/dsh-mcp-connector), with [GitHub Release v0.2.57](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.57).
+The current public version is [`dsh-mcp-connector@0.2.58`](https://www.npmjs.com/package/dsh-mcp-connector), with [GitHub Release v0.2.58](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.58).
 
 See [CHANGELOG.md](CHANGELOG.md) for version history and [docs/DESKTOP-E2E.md](docs/DESKTOP-E2E.md) for the Desktop release checklist.
 

package/README.md

@@ -1,9 +1,11 @@
 # MCP连接器：在 DeepSeek Harness 接入、查找和排障 MCP Server
 
-> DeepSeek Harness 的超百个 MCP连接器，一个入口完成 MCP Server 接入、跨连接工具查找与连接排障。
+> DeepSeek Harness 的 MCP 接入与管理面板：超百个 MCP连接器，一个入口完成 MCP Server 授权配置、跨连接工具搜索与连接排障。
 
 从持续更新的连接器目录接入 MCP Server；跨当前范围内已启用连接查找工具，查看易读参数、来源和最后成功缓存时间，并在发现异常时检查连接或重新发现工具。支持 OAuth 2.0 PKCE、API Key、Streamable HTTP/stdio 与 `mcpServers` JSON 导入。
 
+OAuth 是否可用取决于服务商的客户端注册、账号权限与授权政策；连接已保存、工具已发现和业务调用成功应分别验证。
+
 > 注：“技能扩展”指通过 MCP 工具和 Prompt 扩展智能体能力，本包不会伪装成独立 DSH Skill。
 
 [English](README.en.md)
@@ -36,6 +38,10 @@ dsh plugin --profile web add dsh-mcp-connector
 
 安装或升级后完全重启 DeepSeek Harness Desktop 或 `dsh web`，然后打开左侧「🧩 MCP连接器」；也可从“设置 → 插件 → 插件配置 → MCP连接器”直接打开。
 
+首次使用建议依次确认：连接已保存且范围正确 → “工具”页能找到预期工具与来源 → 在正常 DSH 会话中通过 Host 审批链完成一次服务商许可的只读调用。缓存可见不等于当前服务可调用。
+
+按任务阅读：[迁移现有 `mcpServers` JSON](docs/tutorials/JSON-MIGRATION.md) · [OAuth 授权诊断](docs/tutorials/OAUTH-DIAGNOSTICS.md) · [跨连接找工具与恢复](docs/tutorials/TOOL-SEARCH-RECOVERY.md)。
+
 ![MCP 连接器 43 秒演示](https://raw.githubusercontent.com/duhu2000/dsh-mcp-connector/main/docs/demo.gif)
 
 如果它帮你更快地接入 MCP Server，欢迎 [GitHub 点个 Star](https://github.com/duhu2000/dsh-mcp-connector/stargazers)、[提交新的连接器](https://github.com/duhu2000/dsh-mcp-connector-registry/blob/main/docs/ONBOARDING.md)或[参与贡献](CONTRIBUTING.md)。
@@ -126,6 +132,7 @@ bash <(curl -fsSL https://raw.githubusercontent.com/duhu2000/dsh-mcp-connector/m
 ## 中文教程与生态入口
 
 - [用户手册：安装、授权、诊断、兼容性与故障排查](docs/USER-GUIDE.md)
+- [任务教程：JSON 迁移、OAuth 诊断、跨连接找工具与恢复](docs/USER-GUIDE.md#按任务开始)
 - [配置备份：脱敏导出、快照与恢复边界](docs/CONFIG-BACKUP.md)
 - [连接作用域：project/global 继承、复制、移动与回滚](docs/CONNECTION-SCOPES.md)
 - [连接、Server 与 Tool 治理](docs/TOOL-GOVERNANCE.md)
@@ -185,7 +192,7 @@ npm run dev:ui
 
 公共 Registry 每次合并后会生成 `catalog-stats.json`；本仓库的定时工作流每小时同步中英文介绍和统计快照。npm 页面中的静态正文随版本发布更新，上方动态统计徽标则直接读取 Registry，可在不发布新 npm 版本时保持实时数量一致。
 
-当前公开版本为 [`dsh-mcp-connector@0.2.57`](https://www.npmjs.com/package/dsh-mcp-connector)，对应 [GitHub Release v0.2.57](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.57)。
+当前公开版本为 [`dsh-mcp-connector@0.2.58`](https://www.npmjs.com/package/dsh-mcp-connector)，对应 [GitHub Release v0.2.58](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.58)。
 
 版本能力与变更记录见 [CHANGELOG.md](CHANGELOG.md)。
 Desktop 发版回归见 [docs/DESKTOP-E2E.md](docs/DESKTOP-E2E.md)。

package/docs/USER-GUIDE.md

@@ -2,6 +2,14 @@
 
 本手册面向安装和使用 `dsh-mcp-connector` 的 DeepSeek Harness（DSH）用户。服务商或 MCP 原作者如需提交市场卡片，请改看独立 Registry 的[第三方连接器上架指南](https://github.com/duhu2000/dsh-mcp-connector-registry/blob/main/docs/ONBOARDING.md)。
 
+## 按任务开始
+
+- 已有其他客户端配置：从[迁移 `mcpServers` JSON](tutorials/JSON-MIGRATION.md)开始，逐项验证配置保存、工具发现/注册和只读调用。
+- OAuth 卡在注册、授权或刷新：看[OAuth 连接诊断](tutorials/OAUTH-DIAGNOSTICS.md)，先按阶段与稳定代码排查，不反复提交未获授权的账号。
+- 已连接多个服务却找不到工具：看[跨连接找工具与发现失败恢复](tutorials/TOOL-SEARCH-RECOVERY.md)。缓存可查不等于当前可调用。
+
+这三篇是操作教程，不代表对所有服务商完成了真实业务调用验收；正式调用仍受服务商权限、费用与 DSH Host 审批约束。
+
 ## 1. 安装、升级与重启
 
 要求：DSH Desktop 或 `web` profile，Node.js 20 或更高版本。

package/docs/tutorials/JSON-MIGRATION.md

@@ -0,0 +1,55 @@
+# 把已有 `mcpServers` JSON 迁移到 MCP连接器
+
+适用场景：你已经有其他客户端的 `mcpServers` 配置，希望在 DeepSeek Harness 中统一管理，而不是逐个重新录入。本文只演示受信任的 HTTP/stdio MCP Server；不会把普通 API 或 CLI 自动变成 MCP Server。
+
+## 迁移前：先确认什么
+
+1. 安装 `dsh-mcp-connector`，完全退出并重启 DSH Desktop 或 `dsh web`；确认当前使用的 profile 与安装插件的 profile 一致（例如 Web 使用 `web`，Desktop 使用其对应 profile）。
+2. 核对原配置的每个 Server：远端 URL 是否为 MCP Streamable HTTP 端点；本地 `command`、`args` 和运行时是否可信且可在 **DSH 所在机器** 启动。
+3. 对每个连接决定“当前项目”或“所有项目（全局）”。全局仅指当前 DSH profile，并非跨 profile 共享。
+4. 在本机保存原配置的安全备份。不要把含 Token、API Key、Cookie 或本机路径的原文发到 Issue、聊天或公开仓库。
+
+## 导入一个最小示例
+
+打开左侧“🧩 MCP连接器”（或“设置 → 插件 → 插件配置 → MCP连接器 → 打开 MCP连接器”），点击“＋ 添加连接 → 导入 JSON”，在本机粘贴：
+
+```json
+{
+  "mcpServers": {
+    "example-http": {
+      "type": "streamable-http",
+      "url": "https://example.com/mcp",
+      "headers": { "Authorization": "Bearer REPLACE_LOCALLY" }
+    },
+    "example-local": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/replace/with/trusted/server.js"],
+      "env": { "EXAMPLE_MODE": "readonly" }
+    }
+  }
+}
+```
+
+以上地址、路径和凭据都是占位示例，不能直接连接。请在本机替换为服务商文档给出的值；如没有可信的本地服务，可删除 `example-local`。历史 `sse` 会被归一为 Streamable HTTP，不代表任何旧 SSE 地址都兼容。外部 URL 默认应使用 HTTPS；对私有 IP 明文 HTTP 的显式风险确认及限制见[用户手册](../USER-GUIDE.md#61-导入-mcpservers-json)。
+
+提交前确认目标范围，提交后在“已安装”查看连接。导入和启动失败时先看诊断；不要仅凭“列表里出现配置”判断可用。自定义 HTTP 会在保存前校验 MCP `initialize`；stdio 会等待 Host 首次初始化和工具同步。
+
+## 首次成功使用的三个验收点
+
+| 验收点 | 在哪里看 | 通过条件 |
+|---|---|---|
+| 配置已保存 | “已安装”页 | 目标连接存在，名称与项目/全局范围正确 |
+| 工具已发现并注册 | “工具”页与 DSH Host | 当前范围内出现预期工具和来源；必要时检查 `mcp__<serverName>__*` 注册状态 |
+| 业务调用成功 | 正常 DSH 会话 | 经 Host 的权限/审批链调用一个服务商允许的只读工具，并得到可辨认结果 |
+
+前两项不能替代第三项；工具缓存可查也不证明服务此刻能调用。涉及付费、写入、删除等操作时，不要用它们做首次验收。
+
+## 迁移后的维护与回退
+
+- 在“已安装 → 编辑配置”可修改**自定义或 JSON 导入**连接的标准化单连接 JSON，并保存重连。这里不会恢复原 JSON 的排版/注释，也不能改 connection key 或 `serverName`。敏感值以 `<KEEP_EXISTING>` 表示本机保留，不要把真实值复制到聊天。
+- “配置备份”可导出脱敏 JSON，迁移到另一设备前需在目标设备重填占位符；OAuth Grant 不能携带，须从市场重新授权。
+- 当前 profile 的本机快照可预览和恢复连接变更，但可能含凭据，不能作为可公开分享的备份；服务端已撤销的 OAuth Grant 不能靠快照恢复。
+- 如果原客户端仍在管理同一 `serverName`，先确认是否会双重连接或工具名冲突，再决定停用旧配置。不要在确认新路径通过第三个验收点之前删除原配置。
+
+更多细节见[用户手册：JSON 导入](../USER-GUIDE.md#61-导入-mcpservers-json)、[配置备份与恢复](../CONFIG-BACKUP.md)和[连接作用域](../CONNECTION-SCOPES.md)。

package/docs/tutorials/OAUTH-DIAGNOSTICS.md

@@ -0,0 +1,36 @@
+# OAuth 连接没有成功时，先定位哪一层失败
+
+适用场景：市场卡片要求 OAuth 2.0 PKCE，但按钮显示“自动重试中”“需重新授权”或连接异常。OAuth 接入能力依赖服务商公开元数据、客户端注册、账号权限与网络条件；插件支持 OAuth 流程，不等于每个市场连接器都已对任意账号开放。
+
+## 先看状态，而不是反复点击授权
+
+1. 在“市场”或“已安装”找到对应连接，记录服务商名称、插件版本和按钮状态，不记录 Token/授权码。
+2. 展开详情中的诊断，记录 `stage`、稳定 `code`、`checkedAt` 与建议动作。`状态未知` 只表示缺少当前进程的观察证据，既不是成功也不是失败。
+3. 若为“自动重试中”，先检查网络与服务商状态，等待有界退避；临时刷新失败不必立刻重新授权。
+4. 若明确为“需重新授权”，再从卡片发起新授权。不要向未获授权的企业账号反复尝试登录，也不要把真实凭据交给第三方排障者。
+
+## 按失败阶段处理
+
+| 观察到的阶段或代码 | 首先核对 | 不应推断 |
+|---|---|---|
+| OAuth 元数据/动态客户端注册；HTTP 403 | 服务商是否允许公开注册、是否需要预登记客户端或企业资格 | 浏览器没弹出就认定插件损坏；重复点击可绕过服务商政策 |
+| `auth` / `refresh` | 账号权限、授权范围、Grant 是否失效、服务商撤销状态 | 所有 refresh 错误都意味着永久失效 |
+| `dns` / `tls` / `timeout` / `http` | DNS、代理、证书、VPN/专线、白名单、服务端状态 | 授权已成功就说明 MCP 端点也可用 |
+| `protocol` | URL 是否为兼容的 MCP Streamable HTTP 端点 | 普通网页登录地址或 REST API 地址可直接替代 MCP URL |
+| `host-tools-pending` / `host-status-unavailable` | DSH Host 是否完成工具注册、版本是否能观测状态 | “已保存”就等于工具可调用 |
+
+只有页面明确显示“客户端注册被拒绝、尚未进入浏览器授权”时，才将问题定位到服务商注册政策；这不是用户 OAuth 登录失败。服务商可能要求登记客户端，不能靠重复尝试用户登录绕过。
+
+## 验证恢复，而不是只看授权回调
+
+1. 完成浏览器授权后回到 DSH，检查连接诊断与最近观察时间。多 Server 卡片如有一个异常，整体可能显示“部分异常”。
+2. 在当前工作区打开“工具”，确认对应连接/服务的工具被发现；若未选择 Workspace，只会显示全局连接。最后成功缓存可帮助定位，但不代表当前可调用。
+3. 在正常 DSH 会话里，以服务商许可的**只读**任务验证一次正式调用。工具执行、权限和审批由 DSH Host 管理；页面里的“检查连接/重新发现工具”不会执行目标工具。
+
+授权成功、工具注册成功和业务调用成功是三个不同结果。只有全部完成，才可说“首次使用通过”。不要用含真实业务数据、付费或有副作用的调用做公开演示。
+
+## 安全反馈模板
+
+在 [GitHub Issue](https://github.com/duhu2000/dsh-mcp-connector/issues) 提供：DSH 版本、插件版本、连接器名称、操作系统、脱敏的阶段/code、时间、复现步骤，以及“浏览器是否进入授权”“工具是否注册”“只读调用是否成功”三个独立结论。不要上传 Token、API Key、Cookie、授权码、完整 Header、用户信息或本机路径。
+
+完整状态语义见[用户手册：连接诊断](../USER-GUIDE.md#74-如何理解连接诊断)。

package/docs/tutorials/TOOL-SEARCH-RECOVERY.md

@@ -0,0 +1,32 @@
+# 跨连接找工具，并在发现失败后恢复
+
+适用场景：你已连接多个 MCP Server，想按任务找工具、看参数；或某条连接的最近发现失败，但仍需要判断工具曾经有哪些。本文不演示执行真实业务工具。
+
+## 先定位正确的工具
+
+1. 在 DSH 选中目标 Workspace，再打开“🧩 MCP连接器 → 工具”。未选 Workspace 时仅能看到全局连接；项目连接不会越界显示。
+2. 输入工具名或描述中的关键词。精确工具名优先；同名结果仍需核对连接、服务和来源。
+3. 使用“连接”“服务”“发现状态”筛选。若结果为空，先清除筛选，再确认连接已启用、范围正确且至少成功发现过一次。
+4. 点击“参数详情”：先看类型、必填、枚举和可展开的嵌套摘要；复杂规则可打开“原始 Schema（安全缓存）”。它仍经过安全裁剪和容量限制，不是服务端完整原文。
+
+工具页搜索的是**当前范围内已启用连接的最后成功安全缓存**，不是整个市场中未安装连接器的工具。搜索/筛选不请求目标服务，也不执行目标工具。
+
+## 最近发现失败时怎么做
+
+1. 看结果上的连接器/连接/服务来源、最近发现状态和“最后成功缓存时间”。超过 24 小时的缓存会标记陈旧；缓存能看不代表服务当前可调用。
+2. 展开“连接状态与故障处理”，先阅读失败阶段、稳定 code 和建议。`状态未知` 不等于连接成功。
+3. 根据建议使用“检查连接”或“重新发现工具”。前者检查单连接健康；后者重新获取该连接的工具元数据，二者都不是目标工具试运行，也不保证自动修复。
+4. 若遇 429/限流，等待显示的重试时间，不要连续点击。工具页手动动作不能绕过有效限流；鉴权失败需更新凭据或重新授权。
+5. 修复后再次观察发现状态与时间；最后再通过正常 DSH 会话调用一个获准的只读工具，确认真实业务路径。
+
+后台发现最多并行处理两条连接。健康连接是**五分钟后到期**，不是精确每五分钟或永久实时轮询；普通失败指数退避，鉴权失败暂停自动重试。页面状态通知不等于持续健康探针。
+
+## 可复核的首次成功标准
+
+| 层次 | 你应看到什么 |
+|---|---|
+| 连接 | “已安装”中对应连接存在，范围与启停状态正确 |
+| 发现/注册 | 工具页出现预期工具、来源和最近成功时间；必要时核对 Host 工具注册 |
+| 调用 | 正常会话中通过 Host 审批链完成一个服务商许可的只读调用并得到预期结果 |
+
+不要用缓存搜索结果代替调用验收，也不要在公开反馈中粘贴真实参数、结果或凭据。进一步诊断见[用户手册：工具工作台](../USER-GUIDE.md#51-工具工作台统一查找工具)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mcp-connector",
-  "version": "0.2.57",
+  "version": "0.2.58",
   "description": "DeepSeek Harness MCP Connector: connect servers, search tools across active connections, and troubleshoot discovery. Includes a continuously updated catalog; supports OAuth 2.0 PKCE, API keys, Streamable HTTP/stdio, and mcpServers JSON import.",
   "type": "module",
   "main": "lib/index.js",
@@ -28,6 +28,7 @@
     "docs/STDIO-SUPPORT.md",
     "docs/CLI-PROVIDERS.md",
     "docs/USER-GUIDE.md",
+    "docs/tutorials",
     "docs/screenshots",
     "cordis.patch.yml",
     "README.md",