wokwi-mcp-testing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Wokwi MCP Testing

Wokwi MCP 测试

Overview

概述

Test ESP32 firmware in the Wokwi simulator through MCP tools. Verify boot and hardware state via serial logs and pin reads. The host cannot reach the sim's virtual network — there is no HTTP bridge.

通过MCP工具在Wokwi仿真器中测试ESP32固件。通过串口日志和引脚读取来验证启动过程和硬件状态。主机无法连接到仿真的虚拟网络——此处没有HTTP桥接。

When to Use

适用场景

Verify firmware boots (serial log shows WiFi IP, "HTTP server started")
Check failsafe / initial pin state (pin read at boot)
Debug "sim won't start" or Wokwi MCP tool errors
Answer "does the web UI work on the sim?" — see mock-server technique below

验证固件是否正常启动（串口日志显示WiFi IP、"HTTP server started"）
检查故障安全/初始引脚状态（启动时读取引脚值）
调试“仿真无法启动”或Wokwi MCP工具报错问题
验证“Web UI在仿真中是否可用”——参考下文的mock-server技巧

Gotchas (learned the hard way)

注意事项（经验总结）

1. Token:

user.tok

is a LICENSE, not a CI token

1. 令牌：

user.tok

是许可证，而非CI令牌

~/.wokwi/user.tok

→ sim start fails:

Invalid character in header content [Authorization]

Real token comes from https://wokwi.com/dashboard/ci (read at runtime via env var, or in
```
.mcp.json
```
command line)
```
.mcp.json
```
now embeds the real token → gitignore it (otherwise the secret gets committed)
Never print token contents to output or write them into repo files

~/.wokwi/user.tok

→ 仿真启动失败：

Invalid character in header content [Authorization]

真实令牌来自https://wokwi.com/dashboard/ci（可在运行时通过环境变量读取，或在`.mcp.json`命令行中配置）
```
.mcp.json
```
现在会嵌入真实令牌 → 将其加入.gitignore（否则密钥会被提交到仓库）
切勿将令牌内容打印到输出或写入仓库文件

2. Editing

.mcp.json

mid-session kills the MCP connection

2. 会话中编辑

.mcp.json

会中断MCP连接

After the file changes, Wokwi tools return
```
No such tool available
```
Fix: restart the Claude Code session — MCP reloads
```
.mcp.json
```
cleanly
Do not restart the wokwi-cli service yourself; report the need instead

文件修改后，Wokwi工具会返回
```
No such tool available
```
修复方法：重启Claude Code会话——MCP会重新加载干净的
```
.mcp.json
```
请勿自行重启wokwi-cli服务，如需重启请反馈需求

3. No HTTP bridge — host cannot reach the sim's web server

3. 无HTTP桥接——主机无法连接到仿真的Web服务器

Sim device gets an IP like
```
10.13.37.2
```
on Wokwi's virtual network (e.g.
```
Wokwi-GUEST
```
)
```
curl http://10.13.37.2/
```
from the host → always UNREACHABLE
The Wokwi MCP has no fetch/HTTP tool — you cannot drive
```
/on
```
```
/off
```
```
/toggle
```
from the host
Verify web logic another way: serial logs, pin reads, or a mock server (below)

仿真设备在Wokwi的虚拟网络（如
```
Wokwi-GUEST
```
）中会获得类似
```
10.13.37.2
```
的IP
在主机执行
```
curl http://10.13.37.2/
```
→ 始终无法访问
Wokwi MCP没有HTTP请求工具——无法从主机调用
```
/on
```
```
/off
```
```
/toggle
```
等接口
通过其他方式验证Web逻辑：串口日志、引脚读取，或使用下文的mock服务器

4. Screenshot with partId returns a tiny placeholder

4. 指定partId截图仅返回微小占位图

```
wokwi_take_screenshot
```
of a part returns ~16x16 px, useless for visual state
Don't rely on it to show an LED on/off

对某个部件执行
```
wokwi_take_screenshot
```
会返回约16x16像素的图片，无法用于查看视觉状态
不要依赖此功能查看LED的亮灭状态

Verification Workflow

验证流程

Start sim →
```
wokwi_start_simulation
```
(returns "started")

Wait ~4s →

wokwi_read_serial

— expect

WiFi connected, IP: 10.13.37.2

and

HTTP server started

Failsafe check →
```
wokwi_read_pin
```
on the LED pin — expect
```
false
```
(off at boot)
To prove the web UI logic → replicate
```
htmlPage()
```
+ routes in a Python mock server, drive it with BrowserClaw (same HTML + routes as firmware = logic verified)
For a live LED toggle the user can see → VS Code Wokwi extension: start sim, open browser to the sim IP, click the buttons

启动仿真 → 执行
```
wokwi_start_simulation
```
（返回"started"）

等待约4秒 → 执行

wokwi_read_serial

—— 预期输出

WiFi connected, IP: 10.13.37.2

和

HTTP server started

故障安全检查 → 读取LED引脚的
```
wokwi_read_pin
```
值 —— 预期为
```
false
```
（启动时关闭）
验证Web UI逻辑 → 在Python mock服务器中复现
```
htmlPage()
```
及路由，使用BrowserClaw驱动（与固件相同的HTML+路由即可验证逻辑）
让用户直观看到LED切换 → 使用VS Code Wokwi扩展：启动仿真，在浏览器中打开仿真IP，点击按钮

Common Mistakes

常见错误

Mistake	Fix
Used `~/.wokwi/user.tok` as token	Get a CI token from https://wokwi.com/dashboard/ci
Edited `.mcp.json` then wondered why tools died	Restart the Claude Code session
Tried to `curl` the sim IP from host	Not possible — use serial/pin reads or the mock server
Committed `.mcp.json` containing the token	Add `.mcp.json` to `.gitignore`

错误操作	修复方法
使用 `~/.wokwi/user.tok` 作为令牌	从https://wokwi.com/dashboard/ci获取CI令牌
编辑 `.mcp.json` 后疑惑工具为何失效	重启Claude Code会话
尝试从主机 `curl` 仿真IP	无法实现——使用串口/引脚读取或mock服务器
提交了包含令牌的 `.mcp.json`	将 `.mcp.json` 加入 `.gitignore`

wokwi-mcp-testing

Original

Translation

Wokwi MCP Testing

Wokwi MCP 测试

Overview

概述

When to Use

适用场景

Gotchas (learned the hard way)

注意事项（经验总结）

1. Token:
`user.tok`
is a LICENSE, not a CI token

1. 令牌：
`user.tok`
是许可证，而非CI令牌

2. Editing
`.mcp.json`
mid-session kills the MCP connection

2. 会话中编辑
`.mcp.json`
会中断MCP连接

3. No HTTP bridge — host cannot reach the sim's web server

3. 无HTTP桥接——主机无法连接到仿真的Web服务器

4. Screenshot with partId returns a tiny placeholder

4. 指定partId截图仅返回微小占位图

Verification Workflow

验证流程

Common Mistakes

常见错误

wokwi-mcp-testing

Original

Translation

Wokwi MCP Testing

Wokwi MCP 测试

Overview

概述

When to Use

适用场景

Gotchas (learned the hard way)

注意事项（经验总结）

1. Token: user.tok is a LICENSE, not a CI token

1. 令牌：user.tok是许可证，而非CI令牌

2. Editing .mcp.json mid-session kills the MCP connection

2. 会话中编辑.mcp.json会中断MCP连接

3. No HTTP bridge — host cannot reach the sim's web server

3. 无HTTP桥接——主机无法连接到仿真的Web服务器

4. Screenshot with partId returns a tiny placeholder

4. 指定partId截图仅返回微小占位图

Verification Workflow

验证流程

Common Mistakes

常见错误

1. Token:
`user.tok`
is a LICENSE, not a CI token

1. 令牌：
`user.tok`
是许可证，而非CI令牌

2. Editing
`.mcp.json`
mid-session kills the MCP connection

2. 会话中编辑
`.mcp.json`
会中断MCP连接