logen MCP 服务器

把 logen 探针命令行包装成 MCP 工具：服务器常驻一个 logen.exe shell 子进程会话，探针连接、符号表、通道状态跨工具调用保持，供 AI 做「烧录 → 验证 → 修 Bug → 再验证」的闭环。

MCP 只通过 logen.exe shell 访问 logen。

安装与注册

方式一：npm（使用者）

要求 Windows、Node.js >= 18，且本机可找到 logen.exe（见下节）。在 Claude Code 中一条命令注册：

claude mcp add --scope user logen -- cmd /c npx -y logen-mcp

logen.exe 不在默认位置时显式指定：

claude mcp add --scope user --env LOGEN_EXE=C:\path\to\logen.exe logen -- cmd /c npx -y logen-mcp

其他 stdio MCP 客户端的等价配置：

{
  "mcpServers": {
    "logen": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "logen-mcp"],
      "env": { "LOGEN_EXE": "C:\\path\\to\\logen.exe" }
    }
  }
}

MCP 服务器版本与 logen 桌面程序配套。升级桌面程序后用 npx -y logen-mcp@latest 拉新版（npx 缓存已下载版本，不带 @latest 不会自动更新）。

方式二：从仓库运行（开发）

cd mcp
npm install

项目级注册（仓库根 .mcp.json，本仓库已内置）：

{
  "mcpServers": {
    "logen": {
      "command": "node",
      "args": ["mcp/server.mjs"]
    }
  }
}

或用 Claude Code CLI：

claude mcp add logen -- node <仓库根>/mcp/server.mjs

发布到 npm（维护者）

npm publish 前 prepack（pack-references.mjs）会自动把 skill/references 拷进包内 references/，使 logen_docs 脱离仓库也可用；进包文件以 package.json 的 files 白名单为准，可用 npm pack --dry-run 预览。

logen.exe 定位

按顺序查找：

1. 环境变量 LOGEN_EXE（指向 logen.exe 完整路径）
2. <仓库根>\dist\debug\logen.exe
3. <仓库根>\dist\release\logen.exe
4. %LOCALAPPDATA%\Programs\logen\logen.exe（桌面程序默认安装位置）
5. PATH 中任一含 logen.exe 的目录（安装器会把安装目录加入用户 PATH）

都没有时工具返回错误并提示设置 LOGEN_EXE、安装桌面程序或先运行 scripts\Build-Debug.ps1。

工具一览（渐进式披露：细节用 logen_docs 按需拉取）

| 工具 | 用途 | | --- | --- | | logen_session | 查看、启动、重启或停止常驻 shell 会话；start/restart 会先确认进程可响应命令 | | logen_exec | 按序执行单条或多条命令；错误不会阻止后续命令（但单条超时会重置会话，见行为约定） | | logen_docs | 不传 topic 返回总览与主题清单；传 topic 返回该主题 markdown（仓库布局读 skill\references\，npm 安装读包内 references\ 副本） | | logen_connect | 组合命令：探针唯一时自动选中 → target attach → 给了 file 时 symbol load；attach 失败时提示用 chip list 预校验芯片名 | | logen_read | 同步收流：映射 rtt/serial/winusb receive，始终返回 text 与 bytesHex；maxBytes 上限 65536，timeoutMs=0 非阻塞排空 | | logen_experiment | 执行有序步骤、JSON Pointer 断言、幂等轮询和必执行清理 |

自动试验

logen_experiment 用一轮工具调用完成激励、观测、自动判定和现场恢复。无断言步骤只要求命令返回 {result}；带断言步骤同样隐含要求响应为 {result}——断言路径命中 /error/... 也判该步骤失败。 retry 只能用于无副作用的观测命令（memory read、core status 等；receive 会消费缓冲，不属于幂等命令）。

{
  "name": "状态切换",
  "steps": [
    { "command": "memory write g_start --type u8 --value 1 --verify" },
    {
      "command": "memory read g_state --type u32",
      "assertion": { "path": "/result/values/0", "operator": "equals", "expected": 2 },
      "retry": { "timeoutMs": 2000, "intervalMs": 50 }
    }
  ],
  "cleanup": ["breakpoint clear", "core resume"]
}

支持 exists、equals、notEquals、contains、greaterThan、greaterThanOrEqual、 lessThan 和 lessThanOrEqual。主体失败立即停止后续步骤，但始终按顺序执行 cleanup；任一清理命令失败时试验仍判为失败。 close/detach/breakpoint clear 已幂等化：清理未打开的资源返回 {closed:false}/{detached:false}/{removedCount:0} 且计为成功，可放心把完整清理序列放进 cleanup。

行为约定

• 命令串行执行（同一时刻只有一条 in-flight），与 shell 的请求-响应按序对应。
• 单条命令必须非空且不含换行符，避免一个请求拆成多条 shell 命令。
• 两级超时要区分：
  • shell 内部的 worker 看门狗超时（WORKER_TIMEOUT）只杀 probe-rs worker，shell 进程、符号表与 serial/winusb 通道保留，重新 target attach 即可恢复；
  • MCP 层 exec 超时（SESSION_TIMEOUT，默认 30s）会终止并作废整个 shell 会话，返回 sessionReset: true 及触发超时的 command 与最近无法解析的 stdout 行（recentUnparsedLines）。后续操作必须重新连接目标、重载符号、重开通道。
• exec 超时取三者最大值：显式 timeoutMs、命令内 --timeout-ms + 5s、target flash 的 180s 地板（flash 的 shell 看门狗默认 120s，可用 --timeout-ms 调整，MCP 地板保证 shell 先超时）。
• stream start 产生的异步事件和后台错误缓存在服务器内（上限 500 条），事件格式为 {"event":{"name":"...","source":"...","data":{...}}}，随下一次会 drain 事件的工具调用一并返回（logen_docs、logen_session 的 start/stop/restart、logen_connect 的参数校验与探针选择错误路径不返回事件）；stream 不影响 logen_read。
• logen_exec("exit") 会结束 shell 进程；之后任何工具调用会自动重启会话（连接状态丢失）。管理生命周期请用 logen_session。
• 进程启动失败或意外退出时，错误 details 附最近的 stderr 行（recentStderrLines）。