scopebench-mcp

# scopebench-mcp MCP 服务器 + AI 代理技能，用于 AI 控制的示波器。 `scopebench-mcp` 是一个专注于连接示波器、配置通道/时基/触发、采集波形和屏幕证据，并以结构化 JSON 和文件路径返回给 AI 的框架。首个目标是 RIGOL DHO800 系列，已用 DHO804D 验证。 ## 当前焦点 - 供应商：RIGOL - 初始系列：DHO800 / DHO900 风格的 SCPI 示波器 - 已验证设备：RIGOL DHO804D - 首批传输方式： - USB VISA / USBTMC - LAN TCP SCPI，已在 DHO804D 上验证，可通过 USB 辅助 LAN 应用进行直接静态以太网连接 ## 为什么使用 MCP + 技能 MCP 是执行层，负责硬件访问、SCPI 传输、设置、波形采集和文件输出。 技能是 AI 的操作指南，解释了何时使用屏幕波形与内存波形，如何选择保守的默认值，如何避免在聊天中读取巨大的捕获数据，以及如何总结波形证据。 预期流程： ```text AI 代理 -> scopebench-mcp 技能：如何有效使用工具 -> scopebench-mcp MCP 服务器：实际工具调用 -> 示波器（通过 USB 或 LAN） ``` ## 仓库布局 ```text docs/ 公共项目说明、路线图、硬件说明和供应商参考链接 src/scopebench_mcp/ 驱动程序、传输、捕获和 MCP 服务器代码 skill/scopebench-mcp/ 代码/AI 技能草稿 examples/ 示例命令流程和捕获报告 captures/ 本地波形数据、元数据和屏幕/预览图像，被 git 忽略 scripts/ 临时开发/测试辅助脚本 ``` ## 客户端和平台兼容性 stdio MCP 服务器可以在 Codex、Cursor、Claude Code、Qoder 和 CodeBuddy 中配置。规范的 `SKILL.md` 内容也可以移植到支持 Agent Skills 的客户端，但每个客户端都使用自己的发现目录。 目前验证的 USB 传输仅限于 Windows，因为它使用 `visa64.dll`。LAN TCP SCPI 是预期的 macOS/Linux 路径，但 macOS 硬件验证尚未完成。有关客户端矩阵和确切边界，请参见 `docs/client_platform_compatibility.md`。 ## 快速入门 中文快速说明： - 安装包名为 `scopebench-mcp`，不要安装 PyPI 上无关的 `scope-mcp`。 - Python 导入包名为 `scopebench_mcp`。 - CLI 命令为 `scopebench-mcp`。 - 技能名称和 MCP 服务器名称也是 `scopebench-mcp`。 - 使用硬件前，用户仍需负责探头接地、电压范围、隔离和上电安全确认；AI 只负责仪器控制、数据读取和分析。 ### 安装 公共 Python 发行版名称为 `scopebench-mcp`。早期工作名称 `scope-mcp` 被无关项目在 PyPI 上使用，因此 **不要** 运行 `pip install scope-mcp` 以获取此项目。 将轮包从匹配的 GitHub 发行版包安装到专用虚拟环境中： ```powershell py -m venv .venv .venv\Scripts\python -m pip install ".\scopebench_mcp-0.3.1-py3-none-any.whl[mcp]" ``` 对于可选的 LAN WebControl 面板捕获，安装 WebControl 额外组件和浏览器： ```powershell .venv\Scripts\python -m pip install ".\scopebench_mcp-0.3.1-py3-none-any.whl[mcp,webcontrol]" .venv\Scripts\playwright install chromium ``` 轮包包含与仓库相同的规范 Agent 技能。将它导出到客户端识别的确切技能目录；目标目录必须不存在： ```powershell .venv\Scripts\scopebench-mcp-skill "C:\path\to\client-skills\scopebench-mcp" ``` 重启客户端或打开新的对话，以注册 MCP 服务器和技能。有关支持的客户端目录，请参见 `docs/client_platform_compatibility.md`，有关完整的最终用户流程，请参见 `INSTALL.md`。 完整的发行版包包含： ```text scopebench-mcp-v0.3.1/ scopebench_mcp-0.3.1-py3-none-any.whl skill/scopebench-mcp/SKILL.md INSTALL.md SHA256SUMS ``` 对于源代码开发，以可编辑模式安装项目： ```powershell python -m pip install -e ".[mcp]" ``` 如果需要浏览器渲染的面板捕获，请包含 WebControl 额外组件： ```powershell python -m pip install -e ".[mcp,webcontrol]" playwright install chromium ``` Playwright 管理的浏览器修订版是特定于版本的。从与启动 `scopebench-mcp` 的相同 Python 环境运行安装命令；另一个虚拟环境制作的 Chromium 下载可能不匹配。或者，通过传递 `browser_channel="msedge"` 或 `browser_channel="chrome"` 使用已安装的支持的浏览器。 Windows 用户也可以通过传递 `browser_channel="msedge"` 使用已安装的 Microsoft Edge 浏览器。 运行无硬件测试： ```powershell python -m unittest discover -s tests ``` ### 启动 MCP 服务器 运行 MCP 服务器： ```powershell scopebench-mcp ``` 在 Windows 上，可编辑安装通常将 `scopebench-mcp.exe` 放在 Python `Scripts` 目录中。如果 MCP 客户端找不到 `scopebench-mcp`，请将该 `Scripts` 目录添加到 `PATH` 中或在 MCP 客户端配置中使用完整路径。 最小的 MCP 客户端配置： ```json { "mcpServers": { "scopebench-mcp": { "command": "scopebench-mcp", "args": [] } } } ``` 有关 Windows 说明和完整路径变体的详细信息，请参见 `examples/mcp_client_config.json`。 ### USB/VISA 烟雾测试 对于已验证的 DHO804D 路径，将 PC 连接到后部 USB 设备端口，并确认您的 VISA 运行时可以看到仪器： ```powershell python src\scopebench_mcp\drivers\rigol_dho804d_visa.py list python src\scopebench_mcp\drivers\rigol_dho804d_visa.py idn ``` 预期的已验证身份： ```text RIGOL TECHNOLOGIES,DHO804D,YOUR_SCOPE_SERIAL,00.01.05 ``` 兼容性 CLI 保持相同的默认行为，并且还接受可选的串行检查： ```powershell python src\scopebench_mcp\drivers\rigol_dho804d_visa.py --serial YOUR_SCOPE_SERIAL idn ``` ### 常见的 MCP 工具流程 初始的 MCP 工具是： - `scope_list` - `scope_webcontrol_status` - `scope_webcontrol_capture` - `scope_webcontrol_input` - `scope_identify` - `scope_status` - `scope_network_status` - `scope_configure_channel` - `scope_configure_timebase` - `scope_configure_trigger` - `scope_configure_pulse_trigger` - `scope_configure_acquisition` - `scope_measure` - `scope_measure_statistics` - `scope_measure_timing` - `scope_cursor_measure` - `scope_configure_lan_static` - `scope_autoscale` - `scope_control` - `scope_capture_single` - `scope_capture_pulse` - `scope_acquire_screen` - `scope_acquire_memory` - `scope_screenshot` 对于 USB/VISA 目标，`scope_list` 在可用时返回解析的资源元数据，包括供应商 ID、产品 ID 和 USB 序列号。MCP 工具接受可选的 `serial` 参数。当提供 `serial` 时，仅使用资源字符串作为地址，并使用 `*IDN?` 作为最终身份检查。 对于 LAN 目标，`scope_webcontrol_status(host="<scope_ip>")` 执行只读、有界的 `HTTP GET /` 探测示波器提供的 WebControl 页面。它单独报告 HTTP 可达性和 RIGOL/WebControl 页面检测。它不打开控制 WebSocket 或发送指针/触摸输入。 `scope_webcontrol_capture(host="<scope_ip>")` 打开发现的 `control.html` 页面，在无头浏览器中等待解码的 H.264 关键帧，仅捕获 `1024 x 600` 远程面板画布，并保存 `remote_panel.png` 和 `metadata.json`。它不运行自动设置或更改触发/采集状态；图像反映示波器的当前显示。 `scope_webcontrol_input(...)` 发送一个 `click`、触摸 `tap` 或 `drag` 到面板像素坐标。它需要 `confirm_input=True` 和一个非空的 `expected_effect`，拒绝检测到的画布外的坐标，并保存 `before_panel.png`、`after_panel.png` 和 `metadata.json`。原始坐标依赖于型号、固件和布局。优先使用 SCPI 进行正常控制，并在用户输入后尽可能使用 SCPI 回读。 典型的工作流程： 1. `scope_list` 2. `scope_identify(serial="...")` 3. 如果以太网已连接但地址未知，则 `scope_network_status(serial="...", verify_lan=True)`；仅当返回的身份匹配时，切换到仅 LAN。 4. `scope_status(channel=1, serial="...")` 5. 对于当前会话授权覆盖的安全低电压台阶信号，`scope_autoscale(confirm_physical_setup=True, serial="...")`，然后检查其返回的状态。否则，通过以下三个工具故意配置。 6. `scope_configure_channel(channel=1, probe_ratio=10, scale_v_per_div=0.1, coupling="DC", offset_v=-0.2, serial="...")` 7. `scope_configure_timebase(scale_s_per_div=0.001, offset_s=0.002, serial="...")` 8. `scope_configure_trigger(source_channel=1, level_v=0.14, slope="positive", serial="...")` 9. `scope_configure_pulse_trigger(condition="greater_than", source_channel=1, polarity="positive", width_s=3e-6, level_v=0.14, serial="...")` 当异常脉冲宽度是感兴趣的事件时使用。使用 `lower_width_s` 和 `upper_width_s` 仅适用于 `condition="between"`。 10. `scope_measure(channels=[1, 2], measurements=["frequency", "vpp", "rms"], serial="...")` 获取来自多个通道的简明独立值；保持 `channel=1` 以获取原始单通道响应。 11. `scope_measure_statistics(action="start", channel=1, measurement="vpp", sample_count=1000, serial="...")`，然后在稍后使用 `action="read"` 获取有界的仪器侧最小/最大/平均/标准差/计数快照。显式使用 `reset` 和 `stop`。 12. `scope_measure_timing(source_channel_a=1, source_channel_b=2, measurements=["rr_delay", "rr_phase"], serial="...")` 获取仪器侧边缘延迟和相位。 13. `scope_cursor_measure(mode="manual", axis="time", source_channel=1, cursor_a=-0.0005, cursor_b=0.0005, settle_s=0.5, serial="...")` 获取显式光标位置和结构化增量，等待显示计算完成。 14. `scope_autoscale(confirm_physical_setup=True, serial="...")` 也可用于重置显示起始点，当当前会话授权覆盖它时。 15. `scope_control(action="run" | "stop" | "single", wait_s=0.5, serial="...")` 当需要显式采集状态时。 16. `scope_capture_single(channel=1, points=1000, trigger_timeout_s=10, run_after_capture=True, serial="...")` 当必须捕获当前配置触发器的一个事件并带有有界等待和证据时。传递 `channels=[1, 2]` 而不是仅当必须来自同一冻结事件的多个显示通道。 17. `scope_capture_pulse(condition="greater_than", source_channel=1, width_s=3e-6, level_v=0.14, points=1000, trigger_timeout_s=10, serial="...")` 配置脉冲宽度触发器并启用相同的有界 SINGLE 状态机在一个连接中。仅当需要更深的 RAW 证据时添加显式 `memory_points`、`memory_max_points` 和块/持续时间/磁盘限制。 18. `scope_screenshot(serial="...", screenshot_method="display_png")` 进行快速视觉检查。 19. `scope_acquire_screen(channel=1, points=1000, serial="...", screenshot_method="display_png")` 获取波形证据。 20. `scope_acquire_memory(channel=1, points=250000, chunk_points=100000, max_points=250000, stop_before_capture=True, serial="...")` 仅当需要停止内存详细信息并且接受停止采集时。 可调用的 `scope_measure` 模式枚举其规范的测量名称：`frequency`、`freq`、`period`、`vpp`、`vmax`、`max`、`vmin`、`min`、`mean`、`average`、`rms`、`duty`、`positive_duty`、`negative_duty`、`rise_time` 和 `fall_time`。使用这些名称而不是猜测更长的别名，如 `minimum` 或 `maximum`。 对于 `scope_acquire_screen` 和 SINGLE 捕获的屏幕波形部分，`points` 是请求的上限。DHO800 NORMAL 波形读取支持最多 1000 个点，因此驱动程序将 SCPI 读取窗口限制为 1000 个点而不丢弃原始请求。比较 `requested_points` 与返回的 `points` 或多通道 `alignment.points`；保存的 CSV 文件始终包含实际设备有效载荷。 `scope_measure_statistics` 在一个 MCP 调用内永远不会等待 `sample_count` 采集。`start` 配置一个测量，启用统计并全局重置历史；`read` 立即返回当前、最小、最大、平均、标准差和累积计数；`reset` 也清除所有活动统计；`stop` 禁用统计显示。状态对仪器是全局的，因此与其他前面板或远程用户协调。 捕获工具将大证据保存到文件中并返回路径和简洁的 JSON。当提供偏移量时，通道和时基配置工具返回结构化请求和实际位置回读。将设备回读视为权威，因为有效范围取决于比例和采集状态。`scope_capture_single` 默认情况下在成功事件后停止仪器。设置 `run_after_capture=True` 仅当应恢复采集时；该工具轮询并报告结果的非 STOP 回读。触发超时发送 `:STOP`，不保存波形并停止仪器。 ### LAN 状态 LAN TCP SCPI 实现为手动 `host`/`port` 传输。在验证的 DHO804D 上，直接静态以太网在写入 LAN 设置并发送 `:LAN:APPLy` 后，使用端口 `5555` 的原始 TCP SCPI 工作。端口 `5025` 拒绝测试仪上的连接。 推荐的 DHO804D 启动路径是： 1. 使用 USB/VISA 作为已知良好的控制通道。 2. 调用 `scope_network_status(serial="...", verify_lan=True)` 读取现有的 IP、掩码、网关、模式和 MAC，而不更改设置。 3. 如果其 LAN 验证可达且序列号匹配，请使用返回的 `host` 并使用传输 `"lan"` 和端口 `5555`。 4. 仅当实际需要更改网络时，请调用 `scope_configure_lan_static(..., confirm_network_change=True)`，并使用预期的静态 IP、掩码、网关和可选的 DNS，然后重复仅读状态/身份检查。 5. 对于故障排除，请使用绑定 ping 或 ARP/邻居证据验证预期的主机接口；不要将开放端口视为仪器身份。 建立 LAN 可达性后，可选调用： ```text scope_webcontrol_status(host="<scope_ip>", web_port=80) scope_webcontrol_capture(host="<scope_ip>", web_port=80) scope_webcontrol_input(host="<scope_ip>", action="tap", x=772, y=105, expected_effect="Close the visible menu", confirm_input=True) ``` 状态工具仅发现仪器提供的 HTTP 接口。捕获工具接收浏览器视频画布但不发送指针/触摸输入。输入工具是单独的 gated 操作，记录视觉证据但不将图像差异视为语义成功的证明。 在 Windows 上，无绑定 socket-connect 结果可能会令人误导，当 VPN、代理或隧道适配器处于活动状态时。绑定探测绑定到以太网源地址或检查 ARP/MAC 可达性，然后再将 LAN 结果视为真实。 ## MVP 定义 首个公开版本应使以下操作对 AI 代理来说变得容易： - 发现已连接的 RIGOL 示波器。 - 确定型号、序列号、固件和传输方式。 - 读取通道、时基、触发、采集和波形设置的狀態。 - 配置通道比例、偏移、耦合、探头比例和显示。 - 配置时基和触发。 - 读取仪器侧的简洁测量值，如频率、Vpp、平均值、RMS 和占空比。 - 以明确确认的起始点运行自动缩放，然后读取返回的设置。 - 显式运行、停止或单次采集，并读取返回的状态。 - 获取小屏幕波形，并返回汇总统计数据以及保存的数据、本地预览和实际屏幕图像文件（当支持时）。 - 可选地获取有界停止的内存波形证据，而不返回原始数组到聊天/工具输出中。 - 将所有结果作为适合 AI 代理的结构化 JSON 返回。 ## v0 版本的非目标 - 完全的多厂商抽象。 - 图形用户界面应用程序。 - 自动电路诊断。 - 控制电源供应器、测量仪或逻辑分析仪。 - 自动解决物理接线或电气安全问题。 ## 安全立场 AI 可以控制示波器和分析数据，但用户仍然负责物理探测、接地、电压范围、隔离和硬件供电。在每次代理/MCP 会话中的首次硬件访问时，工作流程应提供一次简洁的安全提醒，并确认物理设置和授权测试范围。该授权在批准的工作流程中保持有效；仅在会话重启或线路、探头、电压/隔离风险、网络配置或预期的远程面板操作发生实质性更改时再次提示。高压和非隔离工作始终需要明确的特定于示波器的确认。 ## 状态 这是从最初的 DHO804D 验证工作中创建的早期独立项目种子。已在单个 DHO804D 上通过 USB/VISA 验证了身份、状态、配置工具、屏幕波形捕获和直接屏幕图像捕获。LAN TCP 支持已在该 DHO804D 上通过直接静态以太网和原始 SCPI 在端口 `5555` 上进行验证，之前需要通过 USB 辅助 LAN 配置和 `:LAN:APPLy`。 本项目与 RIGOL 无关。RIGOL 是其所有者的商标。 ## 项目记忆 当前项目意图、规划、已验证资产和未来方向记录在： - `docs/README.md` 中用于文档索引。 - `docs/project_brief_zh.md` 中用于中文项目简介。 - `docs/roadmap.md` 中用于实现顺序。 - `docs/development_plan.md` 中用于技术决策和实现任务。 - `docs/mcp_tool_design.md` 中用于 MCP 工具草案。 - `docs/client_platform_compatibility.md` 中用于 MCP 客户端、技能和主机平台支持。 - `docs/open_source_release_strategy.md` 中用于私有开发/公开发布策略和 Apache-2.0 决定。