@atlisp/mcp 1.0.17 → 1.0.18

package/README.md

@@ -1,21 +1,18 @@
 # @lisp MCP Server
 
-MCP (Model Context Protocol) Server for @lisp on CAD - 为 CAD 环境提供 @lisp 包管理服务的 MCP 服务器。
-
-同时为 AI AGENT 操控 cad 提供调用工具和通道。
+MCP (Model Context Protocol) Server for @lisp on CAD - 为 CAD 环境提供 @lisp 包管理服务的 MCP 服务器，同时为 AI AGENT 操控 CAD 提供调用工具和通道。
 
 ## 功能特性
 
 - 连接 AutoCAD/ZWCAD/GStarCAD/BricsCAD
-- 执行 AutoLISP 代码
-- 获取 CAD 平台信息
-- 通过 MCP 协议提供标准化接口
+- 执行 AutoLISP 代码，支持绘图、查询、标注
+- AI Agent 可通过 MCP 协议控制 CAD 绘图
 - 管理 @lisp 包（列出、搜索、安装）
-- 自动检测 CAD 状态（忙碌/空闲）
-- CAD 无文档时自动处理
+- CAD 未运行自动启动
 
+---
 
-## 安装
+## 一、安装
 
 ### Windows (PowerShell)
 
@@ -23,71 +20,44 @@ MCP (Model Context Protocol) Server for @lisp on CAD - 为 CAD 环境提供 @lis
 iwr -useb https://atlisp.cn/install.ps1 | iex
 ```
 
-### macOS / Linux
+安装脚本会自动：
+- 安装 Node.js（如未安装）
+- 全局安装 `@atlisp/mcp` 包
+- 创建命令 `atlisp-mcp`
 
-```bash
-npm i -g @atlisp/mcp
+### 验证安装
+
+```powershell
+atlisp-mcp --version
 ```
 
-## 使用方法
+---
 
-### Agent MCP 配置
+## 二、配置 AI Agent (WorkBuddy / Claude Desktop)
 
-#### OpenHands / OpenDeepResearcher
+### WorkBuddy 配置
 
-在配置中添加:
+在 `~/.workbuddy/.mcp.json` 中添加:
 
 ```json
 {
-  "mcp_servers": {
+  "mcpServers": {
     "atlisp-mcp": {
-      "command": "atlisp-mcp",
-      "args": [],
-      "env": {
-        "TRANSPORT": "stdio"
-      }
+      "url": "http://localhost:8110/mcp"
     }
   }
 }
 ```
 
-#### OpenClaude
-
-在配置文件中添加:
-
-```yaml
-mcp_servers:
-  atlisp-mcp:
-    command: atlisp-mcp
-    env:
-      TRANSPORT: stdio
-```
-
-#### Hermes (Claude 独立版)
+### Claude Desktop 配置
 
-在 Hermes 设置中找到 MCP Server 配置，添加:
-
-```json
-{
-  "name": "atlisp-mcp",
-  "command": "atlisp-mcp",
-  "args": [],
-  "env": {
-    "TRANSPORT": "stdio"
-  }
-}
-```
-
-#### Cline / Cursor / Windsurf
-
-在这些 IDE 的 MCP 设置中添加:
+在 `~/AppData/Roaming/Claude/claude_desktop_config.json` 中添加:
 
 ```json
 {
   "mcpServers": {
     "atlisp-mcp": {
       "command": "atlisp-mcp",
-      "args": [],
       "env": {
         "TRANSPORT": "stdio"
       }
@@ -96,144 +66,231 @@ mcp_servers:
 }
 ```
 
-#### 使用 HTTP 模式
-
-如果 agent 不支持 stdio，可以改用 HTTP 模式:
+### 其他 AI Agent (Cline / Cursor / Windsurf)
 
 ```json
 {
   "mcpServers": {
     "atlisp-mcp": {
-      "url": "http://localhost:8110/mcp"
+      "command": "atlisp-mcp",
+      "args": [],
+      "env": {
+        "TRANSPORT": "stdio"
+      }
     }
   }
 }
 ```
 
-### 启动服务器
+---
+
+## 三、启动服务
+
+### HTTP 模式（默认，端口 8110）
 
-**同时支持HTTP 和studio模式**：
 ```bash
 atlisp-mcp
 ```
-### 环境变量
 
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `TRANSPORT` | `http` | 传输模式：`http` 或 `stdio` |
-| `PORT` | `8110` | HTTP 模式监听端口 |
-| `HOST` | `0.0.0.0` | HTTP 模式监听地址 |
-| `MESSAGE_TIMEOUT` | `60000` | 消息超时（毫秒） |
-| `BUSY_RETRIES` | `10` | CAD 忙碌时重试次数 |
-| `BUSY_DELAY` | `500` | CAD 忙碌重试间隔（毫秒） |
-| `MCP_API_KEY` | (无) | API Key 认证（可选） |
+服务启动后输出:
+```
+@lisp MCP Server 启动 - http://0.0.0.0:8110 - Streamable HTTP
+```
 
-### 运行测试
+### stdio 模式（AI Agent 直接调用）
 
 ```bash
-npm test
+atlisp-mcp
+# 环境变量
+TRANSPORT=stdio
 ```
 
-测试覆盖 54 个用例，包括：
-- 工具定义完整性
-- 连接/断开 CAD
-- 执行 LISP 代码
-- 包管理操作
-- 错误处理
-
-## API
-
 ### 健康检查
 
 ```bash
 curl http://localhost:8110/health
 ```
 
-返回：
+返回 `{"status":"ok","cad":"connected"}` 表示服务正常。
+
+---
+
+## 四、连接 CAD
+
+### 前置条件
+
+- Windows 系统
+- CAD 软件已安装（AutoCAD / ZWCAD / GStarCAD / BricsCAD）
+- CAD 已启动（或配置为自动启动）
+
+### 连接方式
+
+使用 MCP 工具 `connect_cad` 连接 CAD：
+
 ```json
-{"status":"ok","cad":"connected"}
+{
+  "name": "connect_cad",
+  "arguments": {}
+}
 ```
 
-### MCP 端点
+**自动行为**:
+- 如果 CAD 已运行，连接现有实例
+- 如果 CAD 未运行，通过 COM 自动创建新实例
 
-HTTP 模式：`POST http://localhost:8110/mcp`
+连接成功返回: `已连接到 AutoCAD 2021`
 
-## 可用工具
+---
 
-| 工具名称 | 描述 | 参数 |
-|---------|------|------|
-| `connect_cad` | 连接到 CAD | 无 |
-| `eval_lisp` | 在 CAD 中执行 AutoLISP 代码（不返回结果） | `code`: 字符串 |
-| `eval_lisp_with_result` | 在 CAD 中执行 AutoLISP 代码并返回结果 | `code`: 字符串 |
-| `get_cad_info` | 获取当前 CAD 信息 | 无 |
-| `list_packages` | 列出已安装的 @lisp 包 | 无 |
-| `search_packages` | 搜索 @lisp 包 | `query`: 搜索关键词 |
-| `install_package` | 安装 @lisp 包到 CAD | `packageName`: 包名称 |
-| `get_platform_info` | 获取 CAD 平台信息 | 无 |
-| `get_file_extensions` | 获取指定平台的文件扩展名 | `platform`: 平台名称 |
-| `get_install_code` | 获取 @lisp 安装代码 | 无 |
-| `at_command` | 执行 @lisp 命令 | `command`: 命令 |
-| `new_document` | 在 CAD 中新建空白文档 | 无 |
-| `install_atlisp` | 在 CAD 中安装 @lisp | 无 |
+## 五、绘图示例
+
+### 1. 画直线
 
-## 支持的平台
+```json
+{
+  "name": "eval_lisp",
+  "arguments": {
+    "code": "(command \"_.LINE\" \"0,0\" \"100,100\" \"\")"
+  }
+}
+```
 
-- **AutoCAD** (文件扩展名: `.fas`, `.vlx`)
-- **ZWCAD** (文件扩展名: `.zelx`, `.vls`)
-- **GStarCAD** (文件扩展名: `.des`)
-- **BricsCAD** (文件扩展名: `.des`)
+### 2. 画矩形
 
-## 工作原理
+```json
+{
+  "name": "eval_lisp",
+  "arguments": {
+    "code": "(command \"_.RECTANG\" \"0,0\" \"100,100\")"
+  }
+}
+```
 
-1. MCP Server 通过 `edge-js` 调用 .NET 代码
-2. .NET 代码通过 COM 互操作连接 CAD 应用程序
-3. 支持获取活动 CAD 实例或启动新实例
-4. 通过 `SendCommand` 方法向 CAD 发送 LISP 代码
-5. 执行命令前自动检测 CAD 状态（IsQuiescent）
-6. CAD 忙碌时自动等待（最多 10 次重试）
-7. CAD 无打开文档时返回错误
+### 3. 画圆
 
-## 示例
+```json
+{
+  "name": "eval_lisp",
+  "arguments": {
+    "code": "(command \"_.CIRCLE\" \"50,50\" \"25\")"
+  }
+}
+```
 
-### 连接 CAD
+### 4. 写文字
 
-```bash
-curl -X POST http://localhost:8110/mcp \
-  -H "Content-Type: application/json" \
-  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"connect_cad","arguments":{}}}'
+```json
+{
+  "name": "eval_lisp",
+  "arguments": {
+    "code": "(entmake (list (cons 0 \"TEXT\") (cons 10 (list 0 0 0)) (cons 40 5) (cons 1 \"标题\")))"
+  }
+}
 ```
 
-### 执行 LISP 代码
+### 5. 获取查询结果
 
-```bash
-curl -X POST http://localhost:8110/mcp \
-  -H "Content-Type: application/json" \
-  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"eval_lisp","arguments":{"code":"(getvar \"acadver\")"}}}'
+```json
+{
+  "name": "eval_lisp_with_result",
+  "arguments": {
+    "code": "(getvar \"acadver\")"
+  }
+}
 ```
 
-### 搜索包
+返回 CAD 版本号，如 "AC1027"
 
-```bash
-curl -X POST http://localhost:8110/mcp \
-  -H "Content-Type: application/json" \
-  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_packages","arguments":{"query":"base"}}}'
+### 6. 统计图形数量
+
+```json
+{
+  "name": "eval_lisp_with_result",
+  "arguments": {
+    "code": "(sslength (ssget \"_X\"))"
+  }
+}
 ```
 
-### 新建文档
+### 7. 切换 CAD 到前台
 
-```bash
-curl -X POST http://localhost:8110/mcp \
-  -H "Content-Type: application/json" \
-  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"new_document","arguments":{}}}'
+当 CAD 在后台运行时，唤醒到前台:
+
+```json
+{
+  "name": "bring_to_front",
+  "arguments": {}
+}
 ```
 
-## 注意事项
+---
+
+## 六、可用工具列表
+
+| 工具名称 | 描述 | 参数 |
+|---------|------|------|
+| `connect_cad` | 连接到 CAD | 无 |
+| `eval_lisp` | 执行 LISP 代码（无返回值） | `code`: LISP 代码 |
+| `eval_lisp_with_result` | 执行 LISP 并返回结果 | `code`: LISP 代码 |
+| `get_cad_info` | 获取 CAD 信息 | 无 |
+| `list_packages` | 列出已安装的包 | 无 |
+| `search_packages` | 搜索包 | `query`: 关键词 |
+| `install_package` | 安装包 | `packageName`: 包名 |
+| `get_platform_info` | 获取平台信息 | 无 |
+| `get_file_extensions` | 获取文件扩展名 | `platform`: 平台名 |
+| `get_install_code` | 获取安装代码 | 无 |
+| `at_command` | 执行 @lisp 命令 | `command`: 命令 |
+| `new_document` | 新建空白文档 | 无 |
+| `bring_to_front` | 切换 CAD 到前台 | 无 |
+| `install_atlisp` | 安装 @lisp | 无 |
+| `get_function_usage` | 获取函数用法 | `name`: 函数名 |
+| `list_functions` | 列出所有函数 | 无 |
+
+---
+
+## 七、环境变量
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `TRANSPORT` | `http` | 传输模式：`http` 或 `stdio` |
+| `PORT` | `8110` | HTTP 模式监听端口 |
+| `HOST` | `0.0.0.0` | HTTP 模式监听地址 |
+| `MESSAGE_TIMEOUT` | `60000` | 消息超时（毫秒） |
+| `MCP_API_KEY` | (无) | API Key 认证（可选） |
+
+---
+
+## 八、支持平台
+
+- **AutoCAD** (扩展名: `.fas`, `.vlx`)
+- **ZWCAD** (扩展名: `.zelx`, `.vls`)
+- **GStarCAD** (扩展名: `.des`)
+- **BricsCAD** (扩展名: `.des`)
+
+---
+
+## 九、工作原理
+
+1. MCP Server 通过 `edge-js` 调用 .NET 代码
+2. .NET 通过 COM 互操作连接 CAD 应用程序
+3. 支持获取运行中的 CAD 或自动启动
+4. 通过 `SendCommand` 向 CAD 发送 LISP 代码
+5. 执行前自动检测 CAD 状态（IsQuiescent）
+6. CAD 忙碌时自动等待（最多 10 次重试）
+
+---
+
+## 十、故障排除
+
+| 问题 | 解决方案 |
+|------|---------|
+| 连接失败 | 确保 CAD 已启动并启用 COM 接口 |
+| 工具调用超时 | CAD 可能繁忙，稍后重试 |
+| 中文乱码 | 使用 `vl-princ-to-string` 处理 |
+| 括号错误 | MCP Server 会自动检查并提示 |
 
-- 仅支持 Windows 平台（依赖 COM 互操作）
-- 需要安装对应的 CAD 软件
-- CAD 必须正在运行或可被启动
-- 某些操作可能需要以管理员权限运行
+---
 
 ## 许可证
 
-ISC
+ISC

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@atlisp/mcp",
-    "version": "1.0.17",
+    "version": "1.0.18",
     "description": "MCP Server for @lisp on CAD",
     "type": "module",
     "bin": {

package/src/cli.js

@@ -2,6 +2,7 @@
 import { spawn } from 'child_process';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { SERVER_VERSION } from './constants.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const serverPath = path.join(__dirname, 'atlisp-mcp.js');
@@ -10,7 +11,10 @@ const args = process.argv.slice(2);
 const env = { ...process.env };
 
 for (let i = 0; i < args.length; i++) {
-  if (args[i] === '--transport' && args[i + 1]) {
+  if (args[i] === '--version' || args[i] === '-v') {
+    console.log(`atlisp-mcp v${SERVER_VERSION}`);
+    process.exit(0);
+  } else if (args[i] === '--transport' && args[i + 1]) {
     env.TRANSPORT = args[i + 1];
     i++;
   } else if (args[i] === '--port' && args[i + 1]) {
@@ -23,11 +27,12 @@ for (let i = 0; i < args.length; i++) {
     env.TRANSPORT = 'stdio';
   } else if (args[i] === '--help' || args[i] === '-h') {
     console.log(`
-@lisp MCP Server
+@lisp MCP Server v${SERVER_VERSION}
 
 Usage: atlisp-mcp [options]
 
 Options:
+  -v, --version         Show version number
   --transport <type>   Transport type: http or stdio (default: http)
   --port <port>        HTTP port (default: 8110)
   --host <host>        HTTP host (default: 0.0.0.0)

package/src/constants.js

@@ -7,7 +7,7 @@ export const FILE_EXTENSIONS = {
 
 export const PROTOCOL_VERSION = '2024-11-05';
 export const SERVER_NAME = 'atlisp-mcp-server';
-export const SERVER_VERSION = '1.0.17';
+export const SERVER_VERSION = '1.0.18';
 
 export const MOCK_PACKAGES = [
     { name: 'base', description: '基础函数库', version: '1.0.0' },