luatools-mcp-adapter

将 LuaTools 内置的 Skill HTTP/WebSocket API 封装为 stdio MCP Server，供 Cursor、Claude Desktop 等 MCP 客户端调用。

前置条件

• Node.js >= 18
• 已启动 LuaTools，并开启 Skill 服务（默认 http://127.0.0.1:38380）

验证 Skill 服务是否可用：

curl.exe http://127.0.0.1:38380/skill/health
curl.exe -X POST http://127.0.0.1:38380/skill/action -H "Content-Type: application/json" -d "{\"action\":\"project.list\",\"params\":{}}"

安装与运行

npm install
npm start

或直接运行：node ./bin/server.js

Cursor 配置

在 Cursor 的 MCP 配置（如 ~/.cursor/mcp.json 或项目设置）中添加：

{
  "mcpServers": {
    "luatools": {
      "command": "node",
      "args": [
        "C:/code/cursor/luatools-mcp-adapter-node/bin/server.js"
      ],
      "env": {
        "LUATOOLS_MCP_BASE_URL": "http://127.0.0.1:38380",
        "LUATOOLS_MCP_TIMEOUT_MS": "30000"
      }
    }
  }
}

使用 npx 时：

{
  "mcpServers": {
    "luatools": {
      "command": "npx",
      "args": ["-y", "luatools-mcp-adapter"],
      "env": {
        "LUATOOLS_MCP_BASE_URL": "http://127.0.0.1:38380"
      }
    }
  }
}

环境变量

| 变量 | 说明 | 默认 | |------|------|------| | LUATOOLS_MCP_BASE_URL | Skill HTTP 服务地址 | http://127.0.0.1:38380 | | LUATOOLS_MCP_TIMEOUT_MS | 请求超时（毫秒） | 30000 | | LUATOOLS_MCP_EVENTS_URL | Skill WebSocket 事件地址 | 自动由 BASE_URL 推导为 ws://127.0.0.1:38380/skill/events |

已映射工具

基础与通用

• health：检查 Skill 服务健康状态
• capabilities：查询支持的动作列表
• skill_action：通用 action 透传调用

刷机与工程

• flash_firmware：烧录固件包到设备
• flash_status：获取刷机状态（优先走 GET /skill/flash/status，不支持时自动回退 flash.status）
• project_flash：烧录项目（script/all）
• project_list：列出可用项目
• project_details：获取项目详情
• project_create：创建项目
• project_update：更新项目配置
• project_delete：删除项目配置
• project_export：导出项目为 .luatos
• project_import：导入 .luatos 项目包
• project_combine：组合工厂包/升级包
• project_syntax_check：检查项目 Lua 语法

固件与日志

• combine_firmware：合并底包与脚本 bin
• log_list：列出日志目录文件
• log_tail：读取日志文件尾部

串口与追踪

• serial_list：列出可用串口
• serial_select：选择串口
• serial_open：打开串口
• serial_close：关闭串口
• serial_status：获取串口状态
• serial_mode：设置串口模式（usb/4g/host）
• serial_baudrate：设置串口波特率
• trace_start：启动日志打印
• trace_stop：停止日志打印
• trace_status：查询日志打印状态
• device_reboot：重启设备

事件流

• events_tail：连接 ws://.../skill/events，在给定时间窗口内收集事件并返回
  • 参数：max_events、duration_ms、types（可选 type 过滤）

架构说明

• 本适配器不直接操作设备或串口，仅作为 MCP 客户端与 LuaTools Skill API 之间的桥接。
• 所有操作通过 LuaTools 的 /skill/* 接口执行，需在本地运行 LuaTools 并开启 Skill 服务。
• API 文档见 C:/code/cursor/luatools_py3/SKILL_API.md。

打包与发布

本地打包为 .tgz

npm install
npm pack

生成 luatools-mcp-adapter-<version>.tgz 后，可本地安装测试：

npm i -g ./luatools-mcp-adapter-*.tgz
luatools-mcp-adapter

发布到 npm

npm login
npm publish --access public

License

与 LuaTools 保持一致。