dsh-mcp-connector 0.2.20 → 0.2.22

package/CHANGELOG.md

@@ -4,6 +4,30 @@
 
 ## [Unreleased]
 
+## [0.2.22] - 2026-08-26
+
+### Fixed
+
+- 首次连接改为等待 `dsh-mcp-client` 完成 MCP `initialize` 与首次 `tools/list`；启动失败或超时不再提前保存、增加已安装数量或显示“已连接”。
+- stdio 健康状态与工具详情改用 Host 实际注册的 `mcp__<serverName>__*` 工具；未注册工具保持“已配置”并显示可重试诊断。
+- 手动 HTTP、免鉴权市场连接与 JSON 导入统一在落库前执行连接校验；DNS、网络、鉴权或协议失败时保留原配置且不写入无效记录。
+- 市场 Web 请求增加连接、健康检查与工具加载超时，避免详情页无限停留在“加载中”。
+
+### Verification
+
+- 新增无效 HTTP 不落库、stdio Host 启动失败回滚、Host 工具注册状态和前端有限超时回归测试。
+
+## [0.2.21] - 2026-08-25
+
+### Documentation
+
+- 产品介绍同步为公共 Registry 78 条、去重后市场 82 张卡片；新增 Registry/市场实时数量徽标。
+- 新增每小时 Registry 统计同步工作流，以 `catalog-stats.json` 为权威来源更新中英文 README 与本地快照，避免后续上架造成宣传数量过期。
+
+### Verification
+
+- 插件 100 项自动测试、lint、Registry 统计同步幂等性、npm 发布文件白名单/敏感内容扫描和 `git diff --check` 通过。
+
 ## [0.2.20] - 2026-08-25
 
 ### Changed
@@ -348,7 +372,9 @@
 - 外部 URL 与导入 Header 执行安全校验。
 - iframe 消息校验同源和消息来源。
 
-[Unreleased]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.20...HEAD
+[Unreleased]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.22...HEAD
+[0.2.22]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.21...v0.2.22
+[0.2.21]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.20...v0.2.21
 [0.2.20]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.19...v0.2.20
 [0.2.19]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.18...v0.2.19
 [0.2.18]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.17...v0.2.18

package/README.en.md

@@ -13,6 +13,8 @@ Browse and install MCP connectors from different providers in DeepSeek Harness D
 [![CI](https://github.com/duhu2000/dsh-mcp-connector/actions/workflows/ci.yml/badge.svg)](https://github.com/duhu2000/dsh-mcp-connector/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/dsh-mcp-connector.svg)](https://www.npmjs.com/package/dsh-mcp-connector)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Registry connectors](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fduhu2000%2Fdsh-mcp-connector-registry%2Fmain%2Fcatalog-stats.json&query=%24.registryCount&label=Registry%20connectors&color=5865f2)](https://github.com/duhu2000/dsh-mcp-connector-registry/blob/main/catalog-stats.json)
+[![Marketplace cards](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fduhu2000%2Fdsh-mcp-connector-registry%2Fmain%2Fcatalog-stats.json&query=%24.marketCount&label=Marketplace%20cards&color=16a34a)](https://github.com/duhu2000/dsh-mcp-connector-registry/blob/main/catalog-stats.json)
 
 ## Features
 
@@ -28,7 +30,9 @@ Browse and install MCP connectors from different providers in DeepSeek Harness D
 - A standalone remote Registry, allowing new marketplace cards to appear after refresh without publishing a new npm version.
 - Explicit, non-destructive migration of authorization from the two earlier Qichacha OAuth plugins.
 
-As of August 24, 2026, the public Registry publishes 61 connector descriptors. After merging and deduplicating them with the four bundled Qichacha cards, the Marketplace exposes 65 cards across nine business categories. Recommendations remain limited to the four Qichacha cards, PKULaw, and Wind, for six featured cards in total. The Registry can evolve independently, so the badge shown after a client refresh is the authoritative current count.
+<!-- catalog-stats:start -->
+As of 2026-08-25, the public Registry publishes 78 connector descriptors. After merging and deduplicating them with the 4 bundled Qichacha cards, the Marketplace exposes 82 cards across 9 business categories. Recommendations remain limited to the four Qichacha cards, PKULaw, and Wind, for 6 featured cards in total. The Registry evolves independently; the badge shown after a client refresh and the live badges above are the authoritative current counts.
+<!-- catalog-stats:end -->
 
 ## Interface and demo
 
@@ -105,7 +109,9 @@ npm run dev:ui
 
 `npm run check` performs syntax checks, automated tests, and an npm package allowlist/sensitive-content audit. `npm run market:check` tracks the external DSH marketplace PR and live directory. Tags matching `v*` trigger GitHub Actions; the tag must match `package.json`. npm releases use Trusted Publishing through GitHub OIDC and do not require a long-lived `NPM_TOKEN`.
 
-The current public version is [`dsh-mcp-connector@0.2.20`](https://www.npmjs.com/package/dsh-mcp-connector), with [GitHub Release v0.2.20](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.20).
+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.22`](https://www.npmjs.com/package/dsh-mcp-connector), with [GitHub Release v0.2.22](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.22).
 
 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

@@ -13,6 +13,8 @@
 [![CI](https://github.com/duhu2000/dsh-mcp-connector/actions/workflows/ci.yml/badge.svg)](https://github.com/duhu2000/dsh-mcp-connector/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/dsh-mcp-connector.svg)](https://www.npmjs.com/package/dsh-mcp-connector)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Registry connectors](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fduhu2000%2Fdsh-mcp-connector-registry%2Fmain%2Fcatalog-stats.json&query=%24.registryCount&label=Registry%20connectors&color=5865f2)](https://github.com/duhu2000/dsh-mcp-connector-registry/blob/main/catalog-stats.json)
+[![Marketplace cards](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fduhu2000%2Fdsh-mcp-connector-registry%2Fmain%2Fcatalog-stats.json&query=%24.marketCount&label=Marketplace%20cards&color=16a34a)](https://github.com/duhu2000/dsh-mcp-connector-registry/blob/main/catalog-stats.json)
 
 ## 功能
 
@@ -30,7 +32,9 @@
 - 平滑迁移：显式扫描并复制两个旧企查查 OAuth 插件授权；不删除原插件或原凭据。
 - 对话工具：`mcp_connector_catalog`、`connect`、`configure`、`import_json`、`install_from_url`、`status`、`health_check`、`set_enabled`、`disconnect`、`refresh_catalog`、`publish`、`tools_list`。
 
-截至 2026-08-24，公共 Registry 已发布 61 条连接器描述；与随包的 4 张企查查卡片合并去重后，市场页可浏览 65 张卡片，覆盖企业数据、金融投资、法律合规、开发工具、办公协作、调研分析、设计创意、效率工具和其他 9 类。推荐位严格保留 4 张企查查卡片、北大法宝和 Wind，共 6 张；其他连接器按业务分类展示。Registry 可独立持续更新，实际数量以客户端刷新后的市场页签徽标为准。
+<!-- catalog-stats:start -->
+截至 2026-08-25，公共 Registry 已发布 78 条连接器描述；与随包的 4 张企查查卡片合并去重后，市场页可浏览 82 张卡片，覆盖企业数据、金融投资、法律合规、开发工具、办公协作、调研分析、设计创意、效率工具、其他 9 类。推荐位严格保留 4 张企查查卡片、北大法宝和 Wind，共 6 张；其他连接器按业务分类展示。Registry 可独立持续更新，实际数量以客户端刷新后的市场页签徽标和上方实时统计徽标为准。
+<!-- catalog-stats:end -->
 
 ## 界面与演示
 
@@ -100,7 +104,9 @@ npm run dev:ui
 
 `check` 执行语法检查、自动测试和 npm 发布包白名单校验；`market:check` 检查外部 DSH 市场 PR 与线上目录；`dev:ui` 启动不含真实凭据的本地 mock 市场。CI 使用 `--legacy-peer-deps` 安装显式测试依赖，DSH 运行期 peer 仍由 Host 提供。`v*` Tag 会触发 GitHub Actions；Tag 必须与 `package.json` 版本一致。Release 通过 npm Trusted Publishing (GitHub OIDC) 发布，不依赖长期 `NPM_TOKEN`。
 
-当前公开版本为 [`dsh-mcp-connector@0.2.20`](https://www.npmjs.com/package/dsh-mcp-connector)，对应 [GitHub Release v0.2.20](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.20)。
+公共 Registry 每次合并后会生成 `catalog-stats.json`；本仓库的定时工作流每小时同步中英文介绍和统计快照。npm 页面中的静态正文随版本发布更新，上方动态统计徽标则直接读取 Registry，可在不发布新 npm 版本时保持实时数量一致。
+
+当前公开版本为 [`dsh-mcp-connector@0.2.22`](https://www.npmjs.com/package/dsh-mcp-connector)，对应 [GitHub Release v0.2.22](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.22)。
 
 版本能力与变更记录见 [CHANGELOG.md](CHANGELOG.md)。
 Desktop 发版回归见 [docs/DESKTOP-E2E.md](docs/DESKTOP-E2E.md)。

package/docs/STDIO-SUPPORT.md

@@ -4,6 +4,8 @@
 > 结论：**低成本补齐**——`@deepseek-ai/dsh-mcp-client` 已原生支持 stdio，我们只需在 schema + provisioning 两层「开闸透传」。
 
 > **实施状态（2026-08-23）**：本文方案已经落地。schema、手工配置、JSON 导入、provisioning、Registry Schema、目录安全审计、健康状态、详情提示和自动测试均已完成；下文保留实施前的代码位置与改动建议，作为架构决策记录。
+>
+> **就绪语义加固（2026-08-26）**：用户主动连接时显式启用 `failOnStartupError`，必须等待 Host 完成首次 `initialize + tools/list` 后才持久化；健康检查与详情页改读 Host 实际注册的 `mcp__<serverName>__*` 工具。启动失败、进程退出或超时不再提前显示“已连接”。依赖默认值仍为 `false`，下文对应代码仅作为依赖能力说明。
 > 状态：已完成（v0.2.12）
 
 ---

package/docs/USER-GUIDE.md

@@ -69,7 +69,7 @@ dsh web
 
 Bearer/API Key 连接器会先执行 MCP `initialize` 验证。所有 Server 通过后，凭据才会保存并出现在“已安装”中；验证失败不会写入新凭据。
 
-stdio 市场卡片也可能显示一个或多个凭据字段，例如 API Token、区域或租户标识。卡片目录只声明字段名称及其环境变量映射；提交后，真实值仅保存到 DSH 本机连接记录，并由插件注入该 stdio 进程的 `env`。市场、状态页和日志不会返回这些值。stdio 由 Host 托管，配置成功表示命令已注册；最终工具可用性仍以本机进程启动结果为准。
+stdio 市场卡片也可能显示一个或多个凭据字段，例如 API Token、区域或租户标识。卡片目录只声明字段名称及其环境变量映射；提交后，真实值仅保存到 DSH 本机连接记录，并由插件注入该 stdio 进程的 `env`。市场、状态页和日志不会返回这些值。插件会等待 Host 完成首次 MCP 初始化与工具同步后再保存连接；失败或超时不会增加已安装数量，卡片也不会提前显示“已连接”。
 
 OAuth 一键连接要求服务商支持标准 OAuth 2.1/PKCE 和公开元数据发现。动态客户端注册既支持无需客户端密钥的 `none`，也支持服务商签发密钥的 `client_secret_post` 与 `client_secret_basic`。客户端密钥仅与 OAuth Grant 一同保存在 DSH 本机，用于换取、刷新和撤销 Token；插件不会要求用户把 OAuth Token 或客户端密钥复制到聊天中。
 
@@ -121,7 +121,7 @@ OAuth 一键连接要求服务商支持标准 OAuth 2.1/PKCE 和公开元数据
 - **HTTP**：填写名称、HTTPS MCP URL、可选 Header 和传输方式。
 - **stdio**：填写本机命令、参数、环境变量和可选工作目录。
 
-stdio 进程由 `@deepseek-ai/dsh-mcp-client` 管理，插件只透传 `command`、`args`、`env`、`cwd`。stdio 会以当前用户权限启动本机进程，只运行你信任的软件包和命令。
+stdio 进程由 `@deepseek-ai/dsh-mcp-client` 管理，插件透传 `command`、`args`、`env`、`cwd`，并等待 Host 完成首次 MCP 初始化和工具同步。stdio 会以当前用户权限启动本机进程，只运行你信任的软件包和命令。手动 HTTP 配置也会在保存前执行 `initialize` 校验；验证失败时表单内容仍保留，且不会生成无效连接记录。
 
 ### 6.3 市场卡片 URL
 
@@ -165,7 +165,7 @@ OAuth 断开时，插件会尽力调用服务商的撤销端点；无撤销端
 
 ### stdio 启动失败
 
-先在终端确认命令本身可执行、软件包可信、Node/运行时版本满足要求，并检查 `cwd` 和环境变量。不要把本机凭据写入公开 Registry descriptor。
+页面会在有限时间内结束等待，并区分命令不存在、进程退出、初始化失败或启动超时。先在终端确认命令本身可执行、软件包可信、Node/运行时版本满足要求，并检查 `cwd`、参数和环境变量；随后查看 Host 日志并点击“重新检查”。不要把本机凭据写入公开 Registry descriptor。
 
 ### 如何反馈问题
 

package/lib/constants.js

@@ -27,6 +27,8 @@ export const DEFAULT_CATALOG_FALLBACK_URLS = [
 
 /** 请求 / 刷新默认值 */
 export const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
+/** 首次启动 MCP Server 并完成 initialize + tools/list 的最长等待时间 */
+export const DEFAULT_STARTUP_TIMEOUT_MS = 120_000;
 export const DEFAULT_REFRESH_SKEW_MS = 300_000;
 export const DEFAULT_CATALOG_TTL_MS = 3_600_000;
 

package/lib/index.js

@@ -15,6 +15,7 @@ import {
   DEFAULT_CATALOG_URL,
   DEFAULT_CATALOG_FALLBACK_URLS,
   DEFAULT_REQUEST_TIMEOUT_MS,
+  DEFAULT_STARTUP_TIMEOUT_MS,
   DEFAULT_REFRESH_SKEW_MS,
   DEFAULT_CATALOG_TTL_MS,
 } from './constants.js';
@@ -52,6 +53,8 @@ export const Config = z.object({
   callbackTimeoutMs: z.number().default(300_000),
   /** 网络请求超时（ms） */
   requestTimeoutMs: z.number().default(DEFAULT_REQUEST_TIMEOUT_MS),
+  /** 首次启动并完成 MCP initialize + tools/list 的超时（ms） */
+  startupTimeoutMs: z.number().default(DEFAULT_STARTUP_TIMEOUT_MS),
   /** 提前刷新阈值（ms） */
   refreshSkewMs: z.number().default(DEFAULT_REFRESH_SKEW_MS),
   /** 是否自动打开浏览器（false = 仅打印授权 URL） */
@@ -251,18 +254,123 @@ export async function apply(ctx, config) {
 
   /* ───────────────────────── 连接记录落库 / 挂载 ───────────────────────── */
 
+  function clearRecordHealth(record) {
+    if (record?.connectorId) state.health.delete(record.connectorId);
+  }
+
   async function persistRecord(record) {
-    state.connections.set(record.key, record);
-    if (record.connectorId) state.health.delete(record.connectorId);
+    // 存储成功后才更新内存，避免落盘失败却在当前进程显示为“已安装”。
     if (config.persistSecrets) await connectionStore.put(record);
+    state.connections.set(record.key, record);
+    clearRecordHealth(record);
+  }
+
+  async function restorePersistedRecord(key, original) {
+    const current = state.connections.get(key);
+    if (config.persistSecrets) {
+      if (original) await connectionStore.put(original);
+      else await connectionStore.delete(key);
+    }
+    if (original) state.connections.set(key, original);
+    else state.connections.delete(key);
+    clearRecordHealth(current);
+    clearRecordHealth(original);
+  }
+
+  async function restoreProvisionedEntry(record, original) {
+    if (original) await provision(ctx, config, original, grantMap(), { failOnStartupError: false });
+    else await remove(ctx, config, record);
+  }
+
+  async function provisionUntilReady(record, original, { strictStartup = true } = {}) {
+    if (!strictStartup) {
+      return provision(ctx, config, record, grantMap(), { failOnStartupError: false });
+    }
+    const startupTimeoutMs = Math.max(1_000, Number(config.startupTimeoutMs) || DEFAULT_STARTUP_TIMEOUT_MS);
+    const timeoutError = Object.assign(
+      new Error(`MCP Server 启动与工具同步超过 ${Math.ceil(startupTimeoutMs / 1000)} 秒`),
+      { code: 'ETIMEDOUT' },
+    );
+    let timer;
+    const task = provision(ctx, config, record, grantMap(), { failOnStartupError: true });
+    const deadline = new Promise((_, reject) => {
+      timer = setTimeout(() => reject(timeoutError), startupTimeoutMs);
+      timer.unref?.();
+    });
+    try {
+      return await Promise.race([task, deadline]);
+    } catch (error) {
+      if (error === timeoutError) {
+        // loader 可能仍在等待 SDK 请求；它最终成功时必须恢复旧条目/移除新条目，绝不迟到落库。
+        task.then(
+          () => restoreProvisionedEntry(record, original).catch((rollbackError) => {
+            logger.error(`late startup rollback "${record.key}" failed: ${rollbackError.message}`);
+          }),
+          () => {},
+        );
+      }
+      throw error;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async function rollbackProvisionedRecords(records, originals) {
+    const failures = [];
+    for (const record of [...records].reverse()) {
+      try {
+        await restoreProvisionedEntry(record, originals.get(record.key));
+      } catch (error) {
+        failures.push(error);
+        logger.error(`connection rollback "${record.key}" failed: ${error.message}`);
+      }
+    }
+    return failures;
+  }
+
+  async function commitConnectionRecords(records, { strictStartup = true } = {}) {
+    const originals = new Map(records.map((record) => [record.key, state.connections.get(record.key)]));
+    const staged = records.map((record) => {
+      const existing = originals.get(record.key);
+      return existing ? { ...existing, ...record, updatedAt: Date.now() } : record;
+    });
+    const provisioned = [];
+    let activeRecord;
+    try {
+      for (const record of staged) {
+        activeRecord = record;
+        await provisionUntilReady(record, originals.get(record.key), { strictStartup });
+        provisioned.push(record);
+      }
+    } catch (error) {
+      await rollbackProvisionedRecords(provisioned, originals);
+      const wrapped = new Error(`MCP Server "${activeRecord?.serverName ?? activeRecord?.key ?? 'unknown'}" 未完成启动`, { cause: error });
+      wrapped.connectionRecord = activeRecord;
+      throw wrapped;
+    }
+
+    try {
+      for (const record of staged) await persistRecord(record);
+    } catch (error) {
+      const rollbackErrors = await rollbackProvisionedRecords(provisioned, originals);
+      for (const record of staged) {
+        try {
+          await restorePersistedRecord(record.key, originals.get(record.key));
+        } catch (rollbackError) {
+          rollbackErrors.push(rollbackError);
+          logger.error(`connection storage rollback "${record.key}" failed: ${rollbackError.message}`);
+        }
+      }
+      const wrapped = new Error('连接记录持久化失败，已回滚 Host 条目', { cause: error });
+      wrapped.connectionRecord = activeRecord;
+      wrapped.rollbackErrors = rollbackErrors;
+      throw wrapped;
+    }
+    return staged;
   }
 
-  async function upsertRecord(record) {
-    const existing = state.connections.get(record.key);
-    const merged = existing ? { ...existing, ...record, updatedAt: Date.now() } : record;
-    await persistRecord(merged);
-    await provision(ctx, config, merged, grantMap());
-    return merged;
+  async function upsertRecord(record, options) {
+    return (await commitConnectionRecords([record], options))[0];
   }
 
   function grantFailure(record) {
@@ -278,16 +386,70 @@ export async function apply(ctx, config) {
     return null;
   }
 
+  function registeredStdioTools(record) {
+    if (typeof ctx.tools?.schemas !== 'function') {
+      return { supported: false, tools: [] };
+    }
+    const prefix = `mcp__${record.serverName}__`;
+    try {
+      const tools = ctx.tools.schemas()
+        .filter((schema) => typeof schema?.name === 'string' && schema.name.startsWith(prefix))
+        .map((schema) => ({
+          name: schema.name.slice(prefix.length),
+          publicName: schema.name,
+          title: schema.title || schema.name.slice(prefix.length),
+          description: schema.description || '',
+        }));
+      return { supported: true, tools };
+    } catch (error) {
+      logger.warn(`read registered tools for "${record.serverName}" failed: ${error.message}`);
+      return { supported: true, tools: [], error };
+    }
+  }
+
+  function readinessResults(records, validationResults = []) {
+    return records.map((record, index) => {
+      const validated = validationResults[index];
+      return {
+        ...(validated ?? {}),
+        ok: true,
+        kind: 'connected',
+        serverKey: record.serverKey,
+        serverName: record.serverName,
+        message: record.transport === 'stdio'
+          ? 'Host 已完成 stdio MCP 初始化与首次工具同步'
+          : validated?.message,
+      };
+    });
+  }
+
+  function connectionSetupFailure(error, prefix = '连接失败') {
+    const record = error?.connectionRecord;
+    const classified = classifyConnectionError(error, { transport: record?.transport });
+    return {
+      ok: false,
+      message: `${prefix}：${classified.message}。未保存连接，请修正后重试。`,
+      detail: {
+        kind: classified.kind,
+        serverKey: record?.serverKey,
+        serverName: record?.serverName,
+        ...(classified.exitCode !== undefined ? { exitCode: classified.exitCode } : {}),
+      },
+    };
+  }
+
   function healthSummary(connectorId, records, results, checkedAt = Date.now()) {
     const enabledRecords = records.filter((record) => record.enabled !== false);
-    const availableServers = results.filter((result) => result.ok).length;
-    const failedServers = results.length - availableServers;
+    const availableServers = results.filter((result) => result.ok && result.kind !== 'managed').length;
+    const pendingServers = results.filter((result) => result.ok && result.kind === 'managed').length;
+    const failedServers = results.filter((result) => !result.ok).length;
     const authFailures = results.filter((result) => !result.ok && result.kind === 'auth').length;
     let connectionState = 'configured';
     if (records.length === 0) connectionState = 'disconnected';
     else if (enabledRecords.length === 0) connectionState = 'disabled';
-    else if (failedServers === 0 && availableServers > 0) connectionState = 'healthy';
-    else if (availableServers > 0) connectionState = 'degraded';
+    else if (failedServers === 0 && pendingServers === 0 && availableServers > 0) connectionState = 'healthy';
+    else if (availableServers > 0 && (failedServers > 0 || pendingServers > 0)) connectionState = 'degraded';
+    else if (pendingServers > 0 && failedServers === 0) connectionState = 'configured';
     else if (authFailures > 0) connectionState = 'reauth';
     else if (failedServers > 0) connectionState = 'unavailable';
     const labels = {
@@ -301,6 +463,7 @@ export async function apply(ctx, config) {
       configuredServers: records.length,
       enabledServers: enabledRecords.length,
       availableServers,
+      pendingServers,
       failedServers,
       checkedAt,
       results,
@@ -451,7 +614,7 @@ export async function apply(ctx, config) {
             state.grants.set(grantKey, { grant, timer: undefined, refreshPromise: null, needsReauth: false });
             if (config.persistSecrets) await grantStore.put(grant);
 
-            const created = [];
+            const records = [];
             for (const sk of authz.grantedKeys) {
               const server = connector.servers.find((s) => s.serverKey === sk);
               if (!server) continue;
@@ -470,9 +633,11 @@ export async function apply(ctx, config) {
                 createdAt: Date.now(),
                 updatedAt: Date.now(),
               };
-              await upsertRecord(record);
-              created.push(record.key);
+              records.push(record);
             }
+            const committed = await commitConnectionRecords(records);
+            const created = committed.map((record) => record.key);
+            cacheHealth(connector.id, committed, readinessResults(committed));
             scheduleRefresh(grantKey);
             let retiredGrantCount = 0;
             for (const previousKey of previousGrantKeys) {
@@ -486,7 +651,9 @@ export async function apply(ctx, config) {
           } catch (error) {
             logger.error(`oauth connect failed: ${error.message}`);
             await pruneOrphanGrants();
-            return { ok: false, message: `连接失败: ${error.message}` };
+            return error?.connectionRecord
+              ? connectionSetupFailure(error)
+              : { ok: false, message: `连接失败: ${error.message}` };
           }
         })();
         state.oauthConnects.set(connector.id, promise);
@@ -518,8 +685,15 @@ export async function apply(ctx, config) {
           createdAt: Date.now(),
           updatedAt: Date.now(),
         };
-        await upsertRecord(record);
-        return { ok: true, message: `已连接 "${connector.name}"`, detail: { key: record.key } };
+        const validation = await validateConnectionRecords([record], { timeoutMs: config.requestTimeoutMs });
+        if (!validation.ok) return { ...validation, detail: { connectorId: connector.id, ...validation.detail } };
+        try {
+          const [committed] = await commitConnectionRecords([record]);
+          cacheHealth(connector.id, [committed], readinessResults([committed], validation.detail.results));
+          return { ok: true, message: `已连接 "${connector.name}"`, detail: { key: committed.key } };
+        } catch (error) {
+          return connectionSetupFailure(error);
+        }
       }
 
       // bearer / api-key 型：目录不含密钥，引导自定义配置
@@ -574,12 +748,9 @@ export async function apply(ctx, config) {
           const validation = await validateConnectionRecords(records, { timeoutMs: config.requestTimeoutMs });
           if (!validation.ok) return { ...validation, detail: { connectorId: connector.id, ...validation.detail } };
 
-          const created = [];
-          for (const record of records) {
-            await upsertRecord(record);
-            created.push(record.key);
-          }
-          cacheHealth(connector.id, records, validation.detail.results);
+          const committed = await commitConnectionRecords(records);
+          const created = committed.map((record) => record.key);
+          cacheHealth(connector.id, committed, readinessResults(committed, validation.detail.results));
           return {
             ok: true,
             message: `已配置并连接 "${connector.name}"（${created.length} 个 MCP Server）`,
@@ -587,20 +758,39 @@ export async function apply(ctx, config) {
           };
         }
         const record = buildManualRecord(params);
-        await upsertRecord(record);
-        return { ok: true, message: `已配置并连接 "${record.name}"（serverName=${record.serverName}）`, detail: { key: record.key, serverName: record.serverName } };
+        const validation = await validateConnectionRecords([record], { timeoutMs: config.requestTimeoutMs });
+        if (!validation.ok) return validation;
+        const [committed] = await commitConnectionRecords([record]);
+        cacheHealth(committed.connectorId, [committed], readinessResults([committed], validation.detail.results));
+        return { ok: true, message: `已配置并连接 "${committed.name}"（serverName=${committed.serverName}）`, detail: { key: committed.key, serverName: committed.serverName } };
       } catch (error) {
-        return { ok: false, message: `配置失败: ${error.message}` };
+        return error?.connectionRecord
+          ? connectionSetupFailure(error, '配置失败')
+          : { ok: false, message: `配置失败: ${error.message}` };
       }
     },
 
     async importJson(json) {
       try {
         const { records, skipped } = normalizeJsonImport(json);
-        const keys = [];
-        for (const record of records) {
-          await upsertRecord(record);
-          keys.push(record.key);
+        const validation = await validateConnectionRecords(records, {
+          timeoutMs: config.requestTimeoutMs,
+          concurrency: 4,
+        });
+        if (!validation.ok) return validation;
+        const committed = await commitConnectionRecords(records);
+        const keys = committed.map((record) => record.key);
+        const grouped = new Map();
+        for (const record of committed) {
+          if (!grouped.has(record.connectorId)) grouped.set(record.connectorId, []);
+          grouped.get(record.connectorId).push(record);
+        }
+        for (const [connectorId, connectorRecords] of grouped) {
+          const results = connectorRecords.map((record) => {
+            const index = committed.findIndex((item) => item.key === record.key);
+            return readinessResults([record], [validation.detail.results[index]])[0];
+          });
+          cacheHealth(connectorId, connectorRecords, results);
         }
         const extra = skipped.length ? `；跳过：${skipped.join('、')}` : '';
         return {
@@ -609,7 +799,9 @@ export async function apply(ctx, config) {
           detail: { keys, skipped },
         };
       } catch (error) {
-        return { ok: false, message: `导入失败: ${error.message}` };
+        return error?.connectionRecord
+          ? connectionSetupFailure(error, '导入失败')
+          : { ok: false, message: `导入失败: ${error.message}` };
       }
     },
 
@@ -667,7 +859,9 @@ export async function apply(ctx, config) {
           authMode: record.auth?.mode ?? 'none',
           grant: grantInfo,
           lastError: record.lastError ?? null,
-          connectionState: recordHealth?.ok ? 'healthy' : recordHealth ? health.connectionState : health?.connectionState ?? 'configured',
+          connectionState: recordHealth?.ok && recordHealth.kind !== 'managed'
+            ? 'healthy'
+            : recordHealth ? health.connectionState : health?.connectionState ?? 'configured',
           healthCheckedAt: health?.checkedAt ?? null,
           healthMessage: recordHealth?.message ?? null,
         });
@@ -694,7 +888,29 @@ export async function apply(ctx, config) {
         for (const record of enabledRecords) {
           const failure = grantFailure(record);
           if (failure) immediateResults.push(failure);
-          else checkable.push(record);
+          else if (record.transport === 'stdio') {
+            const registered = registeredStdioTools(record);
+            if (registered.tools.length > 0) {
+              immediateResults.push({
+                ok: true,
+                kind: 'connected',
+                serverKey: record.serverKey,
+                serverName: record.serverName,
+                toolCount: registered.tools.length,
+                message: `Host 已注册 ${registered.tools.length} 个工具`,
+              });
+            } else {
+              immediateResults.push({
+                ok: true,
+                kind: 'managed',
+                serverKey: record.serverKey,
+                serverName: record.serverName,
+                message: registered.supported
+                  ? 'Host 尚未注册该 stdio Server 的工具'
+                  : '当前 Host 无法读取 stdio 工具注册状态',
+              });
+            }
+          } else checkable.push(record);
         }
         let checkedResults = [];
         if (checkable.length > 0) {
@@ -775,11 +991,26 @@ export async function apply(ctx, config) {
     async setEnabled(key, enabled) {
       const record = state.connections.get(key);
       if (!record) return { ok: false, message: `连接 "${key}" 不存在` };
-      record.enabled = !!enabled;
-      await persistRecord(record);
-      if (record.enabled) await provision(ctx, config, record, grantMap());
-      else await disable(ctx, config, record);
-      return { ok: true, message: `已${record.enabled ? '启用' : '停用'} "${record.name}"` };
+      const next = { ...record, enabled: !!enabled, updatedAt: Date.now() };
+      if (next.enabled) {
+        try {
+          const [committed] = await commitConnectionRecords([next]);
+          if (committed.connectorId) cacheHealth(committed.connectorId, [committed], readinessResults([committed]));
+          return { ok: true, message: `已启用 "${committed.name}"` };
+        } catch (error) {
+          return connectionSetupFailure(error, '启用失败');
+        }
+      }
+      await disable(ctx, config, next);
+      try {
+        await persistRecord(next);
+      } catch (error) {
+        await provision(ctx, config, record, grantMap(), { failOnStartupError: false }).catch((rollbackError) => {
+          logger.error(`disable rollback "${record.key}" failed: ${rollbackError.message}`);
+        });
+        throw error;
+      }
+      return { ok: true, message: `已停用 "${next.name}"` };
     },
 
     async disconnect(key, signal) {
@@ -887,19 +1118,30 @@ export async function apply(ctx, config) {
       const servers = [];
       for (const record of records) {
         if (record.transport === 'stdio') {
+          const registered = registeredStdioTools(record);
           const snapshot = (connector.toolsSnapshot ?? []).find((item) =>
             item.serverKey === record.serverKey || item.serverName === record.serverName);
+          const liveTools = registered.tools;
           servers.push({
             serverKey: record.serverKey || record.name,
             serverName: record.serverName,
-            ok: true,
+            ok: liveTools.length > 0,
             managed: true,
-            preview: Boolean(snapshot),
-            tools: (snapshot?.tools ?? []).map((tool) => ({
-              name: tool.name,
-              title: tool.title || tool.name,
-              description: tool.description || '',
-            })),
+            live: liveTools.length > 0,
+            preview: liveTools.length === 0 && Boolean(snapshot),
+            tools: liveTools.length > 0
+              ? liveTools
+              : (snapshot?.tools ?? []).map((tool) => ({
+                  name: tool.name,
+                  title: tool.title || tool.name,
+                  description: tool.description || '',
+                })),
+            ...(liveTools.length === 0 ? {
+              errorKind: registered.supported ? 'startup' : 'host-version',
+              error: registered.supported
+                ? 'Host 尚未注册该 stdio Server 的工具，请检查启动日志后重试'
+                : '当前 DSH Host 不支持读取工具注册状态，请升级 Host 后重试',
+            } : {}),
           });
           continue;
         }
@@ -938,7 +1180,7 @@ export async function apply(ctx, config) {
       const totalTools = servers.reduce((sum, s) => sum + (s.tools?.length || 0), 0);
       const availableServers = servers.filter((server) => server.ok).length;
       const failedServers = servers.length - availableServers;
-      const managedWithoutSnapshot = servers.filter((server) => server.managed && !server.preview).length;
+      const pendingManagedServers = servers.filter((server) => server.managed && !server.ok).length;
       const health = cacheHealth(connectorId, records, servers.map((server) => server.ok
         ? { ok: true, kind: 'connected', serverKey: server.serverKey, serverName: server.serverName }
         : { ok: false, kind: server.errorKind ?? 'network', serverKey: server.serverKey, serverName: server.serverName, message: server.error }));
@@ -948,10 +1190,16 @@ export async function apply(ctx, config) {
         ok: availableServers > 0,
         message: failedServers > 0
           ? `工具加载失败：${failureSummary}${failedServers > 3 ? `；另有 ${failedServers - 3} 个 Server 不可用` : ''}${availableServers > 0 ? `；${availableServers} 个 Server 仍可用` : ''}`
-          : managedWithoutSnapshot > 0
-            ? `共 ${servers.length} 个 server；${managedWithoutSnapshot} 个 stdio Server 的工具由 DSH Host 注册，当前目录无工具快照`
-            : `共 ${servers.length} 个 server，${totalTools} 个工具`,
-        detail: { connectorId, servers, totalTools, availableServers, failedServers, managedWithoutSnapshot, connectionState: health.connectionState },
+          : `共 ${servers.length} 个 server，${totalTools} 个工具`,
+        detail: {
+          connectorId,
+          servers,
+          totalTools,
+          availableServers,
+          failedServers,
+          pendingManagedServers,
+          connectionState: health.connectionState,
+        },
       };
     },
   };

package/lib/mcp-provision.js

@@ -24,7 +24,7 @@ export function authHeaders(record, grants) {
   return headers;
 }
 
-export function buildEntryConfig(record, grants) {
+export function buildEntryConfig(record, grants, { failOnStartupError = false } = {}) {
   if (record.transport === 'stdio') {
     return {
       transport: 'stdio',
@@ -33,7 +33,7 @@ export function buildEntryConfig(record, grants) {
       args: record.args ?? [],
       env: record.env ?? {},
       cwd: record.cwd || process.cwd(),
-      failOnStartupError: false,
+      failOnStartupError,
     };
   }
   return {
@@ -41,7 +41,7 @@ export function buildEntryConfig(record, grants) {
     serverName: record.serverName,
     url: record.url,
     headers: authHeaders(record, grants),
-    failOnStartupError: false,
+    failOnStartupError,
   };
 }
 
@@ -55,9 +55,9 @@ function hasEntry(ctx, id) {
 }
 
 /** 创建或更新一条 mcp-client 条目（幂等；serverName 不变则工具名不变） */
-export async function provision(ctx, config, record, grants) {
+export async function provision(ctx, config, record, grants, { failOnStartupError = false } = {}) {
   const id = entryIdFor(config, record);
-  const entryConfig = buildEntryConfig(record, grants);
+  const entryConfig = buildEntryConfig(record, grants, { failOnStartupError });
   const disabled = record.enabled === false;
   if (hasEntry(ctx, id)) {
     const existing = ctx.loader.resolve(id);

package/lib/mcp-validation.js

@@ -47,17 +47,22 @@ function parseMcpPayload(text, contentType = '') {
 function errorChain(error) {
   const parts = [];
   let current = error;
-  for (let depth = 0; current && depth < 4; depth += 1) {
+  for (let depth = 0; current && depth < 8; depth += 1) {
     parts.push(current.code, current.name, current.message);
     current = current.cause;
   }
   return parts.filter(Boolean).join(' ');
 }
 
-export function classifyConnectionError(error) {
+export function classifyConnectionError(error, { transport } = {}) {
   const text = errorChain(error);
   if (/AbortError|timeout|timed out|ETIMEDOUT/i.test(text)) {
-    return { kind: 'timeout', message: '连接超时，请检查网络、VPN/专线或服务状态' };
+    return {
+      kind: 'timeout',
+      message: transport === 'stdio'
+        ? '本地 MCP Server 启动或工具同步超时，请检查运行环境、命令和 Host 日志'
+        : '连接超时，请检查网络、VPN/专线或服务状态',
+    };
   }
   if (/ENOTFOUND|EAI_AGAIN|getaddrinfo/i.test(text)) {
     return { kind: 'dns', message: '域名解析失败，请检查当前网络 DNS' };
@@ -68,6 +73,23 @@ export function classifyConnectionError(error) {
   if (/ECONNREFUSED/i.test(text)) {
     return { kind: 'refused', message: '目标服务拒绝连接，请检查 MCP URL 和服务状态' };
   }
+  if (/ENOENT|command not found|spawn[^\n]*not found/i.test(text)) {
+    return { kind: 'process-not-found', message: '本地 MCP 启动命令不存在，请先安装所需运行时或检查 command 配置' };
+  }
+  if (/exit(?:ed)?\s+(?:with\s+)?code|process[^\n]*(?:closed|exited)|subprocess[^\n]*(?:closed|exited)/i.test(text)) {
+    const exitCode = text.match(/(?:exit(?:ed)?\s+(?:with\s+)?code|code)\s*[:=]?\s*(-?\d+)/i)?.[1];
+    return {
+      kind: 'process-exit',
+      message: `本地 MCP 进程在初始化期间退出${exitCode !== undefined ? `（退出码 ${exitCode}）` : ''}，请检查命令、参数和 Host 日志`,
+      ...(exitCode !== undefined ? { exitCode: Number(exitCode) } : {}),
+    };
+  }
+  if (/initial (?:connection|tool synchronization)|tool synchronization failed|initialize(?: handshake)? failed/i.test(text)) {
+    return { kind: 'startup', message: 'MCP 初始化或首次工具同步失败，请检查服务配置和 Host 日志' };
+  }
+  if (transport === 'stdio') {
+    return { kind: 'startup', message: '本地 MCP Server 启动或初始化失败，请检查命令、参数、运行环境和 Host 日志' };
+  }
   return { kind: 'network', message: '无法连接 MCP 服务，请检查网络和 MCP URL' };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mcp-connector",
-  "version": "0.2.20",
+  "version": "0.2.22",
   "description": "General-purpose MCP connector, connection manager, plugin extension, and integration marketplace for DeepSeek Harness, initiated and maintained by Qichacha/QCC.",
   "type": "module",
   "main": "lib/index.js",
@@ -33,11 +33,12 @@
   ],
   "scripts": {
     "test": "node --test",
-    "lint": "node --check lib/index.js && node --check lib/web.js && node --check lib/client.js && node --check lib/schema.js && node --check lib/catalog.js && node --check lib/prompts.js && node --check lib/probe.js && node --check lib/mcp-validation.js && node --check lib/mcp-http.js && node --check lib/migration.js && node --check lib/stores.js && node --check lib/oauth.js && node --check lib/callback-server.js && node --check lib/mcp-provision.js && node --check lib/util.js && node --check lib/constants.js && node --check lib/tools.js && node --check lib/connectors/oauth-connector.js && node --check lib/connectors/manual-connector.js && node --check lib/connectors/json-connector.js && node --check scripts/probe-connector.mjs && node --check scripts/build-registry.mjs && node --check scripts/ui-harness.mjs && node --check scripts/check-market-registration.mjs",
+    "lint": "node --check lib/index.js && node --check lib/web.js && node --check lib/client.js && node --check lib/schema.js && node --check lib/catalog.js && node --check lib/prompts.js && node --check lib/probe.js && node --check lib/mcp-validation.js && node --check lib/mcp-http.js && node --check lib/migration.js && node --check lib/stores.js && node --check lib/oauth.js && node --check lib/callback-server.js && node --check lib/mcp-provision.js && node --check lib/util.js && node --check lib/constants.js && node --check lib/tools.js && node --check lib/connectors/oauth-connector.js && node --check lib/connectors/manual-connector.js && node --check lib/connectors/json-connector.js && node --check scripts/probe-connector.mjs && node --check scripts/build-registry.mjs && node --check scripts/ui-harness.mjs && node --check scripts/check-market-registration.mjs && node --check scripts/sync-registry-stats.mjs",
     "registry:build": "node scripts/build-registry.mjs",
     "registry:validate": "node scripts/probe-connector.mjs catalog/catalog.json --validate-only",
     "dev:ui": "node scripts/ui-harness.mjs",
     "market:check": "node scripts/check-market-registration.mjs",
+    "registry:stats:sync": "node scripts/sync-registry-stats.mjs",
     "verify-pack": "node scripts/verify-pack.mjs",
     "check": "npm run lint && npm test && npm run verify-pack",
     "prepublishOnly": "npm run check"

package/ui/index.html

@@ -455,6 +455,16 @@
 <script>
 (function () {
   const API = '/mcp-connector/api';
+  const API_TIMEOUTS = {
+    connect: 145_000,
+    configure: 145_000,
+    importJson: 145_000,
+    installFromUrl: 145_000,
+    setEnabled: 130_000,
+    toolsList: 20_000,
+    healthCheck: 10_000,
+  };
+  const DEFAULT_API_TIMEOUT_MS = 30_000;
   const $ = (sel) => document.querySelector(sel);
   const main = $('#main');
   const toast = $('#toast');
@@ -505,18 +515,31 @@
   let promptRequestTimer = null;
   let initialHealthCheckStarted = false;
 
-  async function call(method, params) {
+  async function call(method, params, { timeoutMs: timeoutOverride } = {}) {
+    const controller = new AbortController();
+    const timeoutMs = timeoutOverride || API_TIMEOUTS[method] || DEFAULT_API_TIMEOUT_MS;
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
       const res = await fetch(API, {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify({ method, params }),
+        signal: controller.signal,
       });
       const data = await res.json();
       if (!res.ok && data.ok !== false) return { ok: false, message: `请求失败（HTTP ${res.status}）` };
       return data;
     } catch (error) {
+      if (controller.signal.aborted) {
+        return {
+          ok: false,
+          message: `请求超时（${Math.ceil(timeoutMs / 1000)} 秒），请检查服务状态和 Host 日志后重试`,
+          detail: { kind: 'timeout' },
+        };
+      }
       return { ok: false, message: `无法连接 MCP 连接器服务：${error?.message || error}` };
+    } finally {
+      clearTimeout(timer);
     }
   }
 
@@ -676,7 +699,7 @@
           return `<div class="tool-item"><div class="tool-name-row"><div class="tool-name">${esc(tool.name || tool.title || '未命名工具')}</div>${deprecated ? '<span class="tool-deprecated">已弃用</span>' : ''}</div><div class="tool-description${description ? '' : ' empty'}">${esc(description || '暂无描述')}</div></div>`;
         }).join('')
         : server.managed
-          ? '<div class="tools-loading">stdio 工具已由 DSH Host 注册；当前市场详情没有目录快照，可直接在对话中调用。</div>'
+          ? '<div class="tools-loading">Host 已完成 stdio 初始化，但该 Server 当前没有可展示的工具。</div>'
           : '<div class="tools-loading">暂无工具</div>';
       return `<div class="tools-server"><div class="tools-server-header">${esc(label)} <span class="count">· 显示 ${tools.length} / ${matched.length} 个</span></div>${items}</div>`;
     }).filter(Boolean);
@@ -1038,7 +1061,8 @@
 
   window.__mcp = {
     async connect(connectorId) {
-      const r = await call('connect', { connectorId });
+      const timeoutMs = marketItems[connectorId]?.authMode === 'oauth2-pkce' ? 310_000 : undefined;
+      const r = await call('connect', { connectorId }, { timeoutMs });
       showToast(r.message, r.ok);
       if (r.ok) {
         await call('healthCheck', { connectorId });
@@ -1320,7 +1344,7 @@
       }
       if (detailFailureState === 'reauth' && detailConnector?.authMode === 'oauth2-pkce') {
         const id = detailConnector.id;
-        const r = await call('connect', { connectorId: id });
+        const r = await call('connect', { connectorId: id }, { timeoutMs: 310_000 });
         showToast(r.message, r.ok);
         if (r.ok) {
           await call('healthCheck', { connectorId: id });