zwcad-mcp 0.2.2 → 0.2.4

package/README.md

@@ -2,10 +2,11 @@
 
 中望CAD（ZWCAD）MCP 服务，让大模型通过 [MCP 协议](https://modelcontextprotocol.io)直接操控中望CAD 平台与中望机械CAD，完成绘图、标注、图层/块/样式管理，以及图框、标题栏、明细表（BOM）等机械操作。
 
-**共计 41 个工具**：平台 26 个（不依赖机械环境）+ 机械 11 个（需中望机械CAD）+ 诊断 2 个 + 启动器侧 2 个。
+**共计 40 个工具**：平台 26 个（不依赖机械环境）+ 机械 11 个（需中望机械CAD）+ 诊断 2 个 + 启动器侧 1 个。
 
-> 启动器侧的两个工具（`zwcad_wait_ready`、`zwcad_launcher_diagnose`）在 Python 运行时尚未就绪时也可用，
-> 用于等待初始化完成、以及在首次安装失败时自助排查。
+> 启动器侧的 `zwcad_wait_ready` 在 Python 运行时尚未就绪时也可用，用于等待初始化完成。
+> 诊断统一走 `zwcad_diagnose`：Python 已就绪时返回完整诊断，
+> 未就绪时自动降级为启动器视角（含错误日志与环境信息）并标注未检测项。
 
 ## 为什么需要 Node 启动器
 

package/lib/proxy.js

@@ -72,26 +72,6 @@ const PROXY_TOOLS = [
       additionalProperties: false,
     },
   },
-  {
-    name: 'zwcad_launcher_diagnose',
-    description:
-      '诊断启动器与 Python 运行时的状态，并返回最近的错误记录。\n\n' +
-      '与 zwcad_diagnose 的区别：本工具由 JS 启动器实现，**在 Python 尚未就绪时也可用**，' +
-      '因此是排查「首次安装失败 / 一直停在初始化」的首选；' +
-      'zwcad_diagnose 依赖 Python 侧，只能在其就绪后调用。\n\n' +
-      '返回内容包括：运行时状态、Python 解释器路径与版本、虚拟环境状态、' +
-      '最近若干条错误日志（含事件名与诊断细节）。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        limit: {
-          type: 'number',
-          description: '返回最近多少条错误日志，默认 10，上限 50。',
-        },
-      },
-      additionalProperties: false,
-    },
-  },
 ];
 
 /**
@@ -406,6 +386,15 @@ function createProxy(opts) {
         handleProxyTool(msg);
         return;
       }
+
+      // zwcad_diagnose 是 Python 侧的主诊断工具，但它本身跑在 Python 里。
+      // Python 未就绪时它必然报「正在初始化」，而这恰恰是最需要诊断的时刻。
+      // 所以这里做一次兜底：未就绪时直接由代理层给出启动器视角的诊断，
+      // 让 AI 只需认准「一个诊断入口」。
+      if (toolName === 'zwcad_diagnose' && !childReady) {
+        handleDiagnoseFallback(msg);
+        return;
+      }
     }
 
     // tools/list 永远由本地静态清单应答，不受 childReady 影响。
@@ -514,14 +503,14 @@ function createProxy(opts) {
       } else if (r.state === 'failed') {
         text =
           `服务初始化失败：${r.error}\n\n` +
-          `下一步：调用 zwcad_launcher_diagnose 获取完整的错误记录与运行环境信息，` +
+          `下一步：调用 zwcad_diagnose 获取完整的错误记录与运行环境信息，` +
           `据此判断原因并告知用户具体怎么修。\n\n` +
           `常见原因：未安装 Python 3.10+、网络无法访问 PyPI、磁盘空间不足。`;
       } else {
         text =
           `已等待 ${seconds} 秒，初始化仍未完成，仍在安装依赖。\n\n` +
           `下一步：可再调用一次本工具继续等待；若累计超过 2 分钟仍无进展，` +
-          `调用 zwcad_launcher_diagnose 查看错误记录。`;
+          `调用 zwcad_diagnose 查看错误记录。`;
       }
 
       writeJson({
@@ -535,19 +524,6 @@ function createProxy(opts) {
       return;
     }
 
-    if (name === 'zwcad_launcher_diagnose') {
-      let limit = Number(args.limit);
-      if (!Number.isFinite(limit) || limit <= 0) limit = 10;
-      limit = Math.min(limit, 50);
-
-      writeJson({
-        jsonrpc: '2.0',
-        id: msg.id,
-        result: { content: [{ type: 'text', text: buildDiagnosisReport(limit) }] },
-      });
-      return;
-    }
-
     writeJson({
       jsonrpc: '2.0',
       id: msg.id,
@@ -558,6 +534,42 @@ function createProxy(opts) {
     });
   }
 
+  /**
+   * Python 未就绪时，zwcad_diagnose 的兜底应答。
+   *
+   * 设计要点：对 AI 来说诊断入口始终是 zwcad_diagnose，不必记两个工具名。
+   * 这里返回启动器视角的诊断，并**明确标注哪些项目因 Python 未就绪而无法检测**，
+   * 避免 AI 把「未检测」误读成「正常」或「故障」。
+   */
+  function handleDiagnoseFallback(msg) {
+    const report = buildDiagnosisReport(10);
+
+    const header =
+      '## 诊断来源\n' +
+      'Python 运行时尚未就绪，本次为**启动器视角**的诊断，' +
+      '无法检测 ZWCAD 连接状态、机械类型库等 Python 侧项目。\n' +
+      '待初始化完成后再次调用本工具，可获得完整诊断。\n\n';
+
+    const footer =
+      '\n\n## 本次未检测的项目\n' +
+      '- ZWCAD 是否已启动、是否打开了 DWG\n' +
+      '- 机械扩展（ZwmToolKit）类型库加载状态\n' +
+      '- 平台/机械 COM 连接可用性\n\n' +
+      '这些需要 Python 运行时就绪后才能探测。在此之前，' +
+      '如需了解 ZWCAD 侧的情况，请直接查看用户屏幕上是否打开了图纸。';
+
+    writeJson({
+      jsonrpc: '2.0',
+      id: msg.id,
+      result: {
+        content: [{ type: 'text', text: header + report + footer }],
+        // 这不是工具失败，而是「部分信息暂时不可得」，用 isError 会让 AI
+        // 误判为故障，所以按正常结果返回，把局限性写在正文里。
+        isError: false,
+      },
+    });
+  }
+
   /**
    * 生成诊断报告。
    *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zwcad-mcp",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "中望CAD（ZWCAD）MCP 服务：用自然语言驱动 ZWCAD 二维平台与中望机械 CAD，完成绘图、标注、图层管理与机械图框/BOM 操作",
   "license": "MIT",
   "type": "commonjs",

package/tools.json

@@ -1300,7 +1300,7 @@
  },
  {
   "name": "zwcad_diagnose",
-  "description": "诊断平台和机械后端，并给出不修改系统的排障建议。",
+  "description": "诊断 MCP 服务的运行状态，并按需给出修复建议。\n\n分两种情形，工具名不变：\n- Python 运行时已就绪：返回完整诊断（平台 COM 可用性、活动图纸、机械扩展与 ZwmToolKit 类型库状态）。\n- Python 运行时未就绪：自动降级为启动器视角，返回运行时状态、Python 解释器路径与版本、最近错误记录（含 pip 镜像源、依赖清单、耗时），并明确标注哪些项目本次未检测。\n\n因此排查任何问题都从这里开始，无需另找工具。",
   "inputSchema": {
    "properties": {
     "probe_cad": {
@@ -1320,4 +1320,4 @@
    }
   }
  }
-]
+]