dsvlab-mcp — DS-VLAB 电路测试 MCP 服务器

让 AI(MCP 客户端)程序化控制 DS-VLAB v2.0 多思计组原理虚拟实验室中的电路:加载电路、上电、施加输入、单步/连续运行、读取引脚与存储、批量跑真值表,实现自动化测试。

架构

AI 客户端 ─stdio─► dsvlab-mcp(本服务) ─Playwright─► Edge/Chromium(加载 index.html)
                                                    │ page.evaluate()
                                                    ▼
                                          window.mycircuit / cDispatch
                                          / recovercircuit()(原系统全局)

• 不改动原项目任何源码(18 个 component、dispatch、circuitdiagram、fileoperation 一律不动)。

• 全部新文件集中在 mcp/dsvlab-mcp/。

• 复用原项目 tools/circuit-validator-core.js(UMD)做加载前校验。

• 默认用系统自带的 Edge(channel: 'msedge'),无需下载 Chromium。

Related MCP server: EDA Tools MCP Server

安装

cd mcp/dsvlab-mcp
npm install
npm run build          # tsc 编译到 dist/
# 可选:跑集成测试(会用 Edge headless 加载 example_bus_demo.txt)
npm test

不需要 npx playwright install —— 默认走系统 Edge。若想用 Playwright 自带 Chromium,设环境变量 DSVLAB_CHANNEL=chromium 后执行 npx playwright install chromium。

配置(MCP 客户端)

ZCode / Claude Desktop

把 files/config.sample.json 的内容并入客户端的 MCP 配置(按本机实际路径调整):

{
  "mcpServers": {
    "dsvlab": {
      "command": "node",
      "args": ["C:/.../dsvlab2.0/mcp/dsvlab-mcp/dist/index.js"],
      "env": {
        "DSVLAB_INDEX": "C:/.../dsvlab2.0/index.html",
        "DSVLAB_CHANNEL": "msedge",
        "DSVLAB_HEADLESS": "0"
      }
    }
  }
}

环境变量

浏览器是 lazy 启动:MCP 服务连上后不立即弹窗,第一次调用工具时才启动。

工具清单(共 27 个)

防护补丁:浏览器启动时自动注入,防止组合反馈环导致 runCircuit 死循环卡死主线程(原型 input 加 WeakMap+run token 计数,单拍每元件超 200 次 input 饿死)。卡死时工具调用超时(8s)自动重启浏览器并重放会话(电路 txt 优先从磁盘重读 + memory 写操作去重最终态 + 电源状态)。get_guard_status 返回触发次数/元件/第几次 runCircuit;run_steps 返回 triggeredAt 定位第几步触发。

边界:阈值是 per-component 的,多个独立反馈环各自饿死互不影响;但若两个环共享某元件(如三态门同时被两环驱动),该元件计数会叠加,可能比预期更快触发 guard。课设电路一般不会出现。

电路

画电路(辅助生成,配合 docs/AI画电路手册.md 流程)

电源

仿真

读取

批量测试

使用示例(AI 视角)

1. load_circuit(text=<电路txt全文>)        → 加载并校验
2. power_on()
3. set_switch(id="CP8", value=0)           → 使能 74LS245
4. for each 输入组合: set_switch + step + read_pin
   或直接: run_truth_table(switch_ids=["CP0",...], outputs=[{id,pin}])
5. assert_pins(expected=[{id,pin,value},...])

关键技术点

1. 桥接层(src/inject.ts):注入到页面的一段 window.__bridge 脚本,把对原系统 cDispatch/mycircuit/recovercircuit 的调用集中封装,Node 侧通过 page.evaluate 一次性调用,返回可序列化 JSON。减少跨进程往返。

2. 调用对照(均已查源码确认):

   • 加载:recovercircuit('demo', mycircuit, txt)(fileoperation.js:136)

   • 上电/断电:cDispatch.powerOn()/powerOff()(dispatch.js:93/99)

   • 单步:cDispatch.runCircuit()(dispatch.js:75)

   • 触发源器件:cDispatch.sourceTrigger(c|id)(dispatch.js:86)

   • 读引脚:comp.pinValue[pinNo](0低/1高/2高阻)

3. pinValue 三态:0 低 / 1 高 / 2 高阻未驱动,断言要区分。

4. Switch 初值坑:原系统 new Array([0]) 产生 [[0]],pinValue[0] 实际是数组 [0],[0]==0 成立但 [0]===0 不成立。故 setSwitch 用宽松比较 !=,与原系统一律 == 的语义一致。

5. memory 限制:RAM6116/EPROM 的 memory 硬编码在源码(js/component/ram6116.js 等),不随电路 txt 保存;运行时 component.memory 可读写,但刷新页面会重置回源码值。

6. 异步脉冲:ContinuousPulse/SinglePulse 用 setTimeout 自驱动(默认 800ms);run(duration) 用真实等待,stop() 清 timer。测试时 set_pulse_width(50) 加速。

7. MCP 用 stdio:禁用 console.log(破坏协议流),用 console.error。

8. TS + zod + MCP SDK 的 TS2589:zod ZodRawShape 与 SDK 泛型组合会触发 "Type instantiation excessively deep"。本项目统一用 server.registerTool<any, any> + handler (args:any, _extra:any): Promise<any> 规避。

调试

# MCP Inspector:浏览器里查看所有工具、手动调用
npx @modelcontextprotocol/inspector node dist/index.js

# 跑集成测试
npm test

已知限制

• 不改原项目源码,因此 RAM/EPROM memory 初值仍需改 js/component/*.js(本工具只在运行时改 component.memory,刷新即失)。

• run(duration) 基于真实时钟等待,大批量时序测试较慢;组合逻辑用 step/run_truth_table 即可。

• 单步无 GUI 按钮,step = cDispatch.runCircuit()(跑空就绪队列)。

集成测试结果

tests/integration.test.ts 用 files/examples/example_bus_demo.txt(8 开关 → 74LS245 → 8 LED)端到端验证:

• ✅ 加载 18 个元件

• ✅ -E=0 使能时 A→B 透传,8 个 LED 全亮

• ✅ -E=1 禁能时 B 侧高阻,LED 不亮