zwcad-mcp 0.2.1 → 0.2.2

package/README.md

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

package/lib/proxy.js

@@ -30,7 +30,7 @@
 const fs = require('fs');
 const path = require('path');
 const { spawn } = require('child_process');
-const { logError } = require('./errorlog');
+const { logError, logFilePath } = require('./errorlog');
 
 const PROTOCOL_VERSION = '2024-11-05';
 
@@ -72,6 +72,26 @@ 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,
+    },
+  },
 ];
 
 /**
@@ -494,13 +514,14 @@ function createProxy(opts) {
       } else if (r.state === 'failed') {
         text =
           `服务初始化失败：${r.error}\n\n` +
-          `请让用户执行以下命令查看诊断：\n  npx -y zwcad-mcp --doctor\n\n` +
+          `下一步：调用 zwcad_launcher_diagnose 获取完整的错误记录与运行环境信息，` +
+          `据此判断原因并告知用户具体怎么修。\n\n` +
           `常见原因：未安装 Python 3.10+、网络无法访问 PyPI、磁盘空间不足。`;
       } else {
         text =
           `已等待 ${seconds} 秒，初始化仍未完成，仍在安装依赖。\n\n` +
-          `可以再调用一次本工具继续等待，或告知用户首次安装耗时较长、请稍候。\n` +
-          `若累计超过 2 分钟仍无进展，让用户执行：\n  npx -y zwcad-mcp --doctor`;
+          `下一步：可再调用一次本工具继续等待；若累计超过 2 分钟仍无进展，` +
+          `调用 zwcad_launcher_diagnose 查看错误记录。`;
       }
 
       writeJson({
@@ -514,6 +535,19 @@ 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,
@@ -524,6 +558,103 @@ function createProxy(opts) {
     });
   }
 
+  /**
+   * 生成诊断报告。
+   *
+   * 目标是让 AI 读完就能判断问题出在哪，并把结论用自然语言转述给用户，
+   * 而不是把一坨技术细节甩给用户让他自己去跑命令。
+   */
+  function buildDiagnosisReport(limit) {
+    const lines = [];
+    const stateText =
+      runtimeState === 'ready' && childReady
+        ? '已就绪'
+        : runtimeState === 'failed'
+          ? '失败'
+          : '正在准备';
+
+    lines.push('## 运行时状态');
+    lines.push(`状态：${stateText}`);
+    if (runtimeState === 'failed' && runtimeError) {
+      lines.push(`错误：${runtimeError}`);
+    }
+    if (childReady) {
+      lines.push('Python 侧已完成握手，可以正常接受请求。');
+    }
+
+    lines.push('');
+    lines.push('## 运行环境');
+    lines.push(`Node：${process.version}（${process.platform}/${process.arch}）`);
+    lines.push(`启动器版本：${opts.version || '未知'}`);
+    lines.push(`工作目录：${cwd}`);
+    lines.push(
+      `环境变量：ZWCAD_MCP_PYTHON=${process.env.ZWCAD_MCP_PYTHON || '（未设置）'}，` +
+        `ZWCAD_MCP_PIP_INDEX=${process.env.ZWCAD_MCP_PIP_INDEX || '（未设置）'}`
+    );
+
+    lines.push('');
+    lines.push('## 错误记录');
+    const entries = readRecentErrors(limit);
+    if (entries.length === 0) {
+      lines.push('无错误记录。若问题仍存在，可能是尚在安装中，或故障未落到日志点。');
+    } else {
+      lines.push(`日志文件：${logFilePath()}`);
+      lines.push('');
+      for (const e of entries) {
+        lines.push(`- [${e.time}] **${e.event}**`);
+        if (e.detail) {
+          lines.push('  ' + e.detail.replace(/\n/g, '\n  '));
+        }
+      }
+    }
+
+    lines.push('');
+    lines.push('## 如何判读');
+    lines.push('- `runtime.python.not_found`：本机没有 3.10+ 的 Python。');
+    lines.push('  让用户装 Python（建议 3.13），或设 `ZWCAD_MCP_PYTHON` 指向已有解释器。');
+    lines.push('- `runtime.install.failed`：装依赖失败。看 detail 里的 `pipIndex` 与 `error`，');
+    lines.push('  多为网络问题，让用户设 `ZWCAD_MCP_PIP_INDEX` 为国内镜像后重连。');
+    lines.push('- `python.spawn.failed` / `python.exited`：Python 进程起不来或崩溃，');
+    lines.push('  看 detail 里的 `stderrTail`（Python 自身的异常堆栈）。');
+    lines.push('- 无任何错误记录但仍不可用：多半仍在安装，让其再等或重连。');
+
+    return lines.join('\n');
+  }
+
+  /**
+   * 读取最近 N 条错误日志，转成易读文本。
+   *
+   * 读取失败一律返回空数组——诊断工具自己不能因为读不到日志而报错。
+   */
+  function readRecentErrors(limit) {
+    let raw;
+    try {
+      raw = fs.readFileSync(logFilePath(), 'utf8');
+    } catch {
+      return [];
+    }
+
+    const out = [];
+    const all = raw.trim().split('\n').slice(-limit);
+    for (const line of all) {
+      try {
+        const r = JSON.parse(line);
+        let detail = '';
+        if (r.detail && Object.keys(r.detail).length > 0) {
+          try {
+            detail = JSON.stringify(r.detail, null, 1);
+          } catch {
+            detail = '[无法序列化]';
+          }
+        }
+        out.push({ time: r.time, event: r.event, detail });
+      } catch {
+        /* 跳过损坏行 */
+      }
+    }
+    return out;
+  }
+
   /**
    * 未就绪时的工具调用：返回结构化错误，让 AI 知道该等还是该修环境。
    *

package/package.json

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