dsh-mcp-connector 0.2.21 → 0.2.22

package/CHANGELOG.md

@@ -4,6 +4,19 @@
 
 ## [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
@@ -359,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

@@ -111,7 +111,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.21`](https://www.npmjs.com/package/dsh-mcp-connector), with [GitHub Release v0.2.21](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.21).
+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

@@ -106,7 +106,7 @@ npm run dev:ui
 
 公共 Registry 每次合并后会生成 `catalog-stats.json`；本仓库的定时工作流每小时同步中英文介绍和统计快照。npm 页面中的静态正文随版本发布更新，上方动态统计徽标则直接读取 Registry，可在不发布新 npm 版本时保持实时数量一致。
 
-当前公开版本为 [`dsh-mcp-connector@0.2.21`](https://www.npmjs.com/package/dsh-mcp-connector)，对应 [GitHub Release v0.2.21](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.21)。
+当前公开版本为 [`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.21",
+  "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",

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 });