KingstVIS MCP Server

金沙滩 KingstVIS 逻辑分析仪软件的 Model Context Protocol (MCP) 服务器。 通过官方 Socket API（TCP 23367）控制软件完成采集，把采样数据导出成文件并 离线解析/测量——本工程的目标：从逻辑分析仪接口取出数据做离线分析。

• 协议与文件格式逆向笔记：docs/NOTES.md；官方文档原文：docs/socket_api_text.txt 与 sdk/ 内 PDF+示例

• 26 个 MCP 工具：连接/采样配置/触发/采集/导出/离线解析/通道测量/内置解码器脚本管理

• 三种导出格式全部支持解析：.kvdat（逆向的二进制跳变流，最紧凑、自带元数据，推荐归档）、 .csv/.txt（跳变列表，人可读）、.bin（每采样 uint16 LE，通道号=位序号）

• 内置解码器可全脚本控制（逆向 vis.config 的 <analyzers> schema + 插件 SimpleArchive 设置串）：add_analyzer/remove_analyzer 写配置并重启软件， 之后 start → export_decoded 拿到解码表——零 GUI 操作（详见 NOTES.md §5）

• 采样数据只落盘（原生导出 + 派生 .npz），MCP 返回摘要与路径，绝不内联数组

• .npz 统一表示：meta(json) + 每通道 pos_ch<N>(uint64 边沿索引数组)， 采集完成很久之后仍可离线分析（parse_file/measure_channel 无需连接）

快速开始

cd /Users/andylos/mcp_gen/kingstvis
python3 -m venv .venv
.venv/bin/pip install -e . pytest
.venv/bin/python -m pytest tests/            # 离线单元测试（mock VIS + 合成文件）
.venv/bin/python scripts/probe_device.py     # 真机/模拟端到端自检（11 项）

启用 KingstVIS Socket API（一次性）

1. 关闭 KingstVIS，编辑 ~/Library/Application Support/kingst/vis.config （Windows: %LOCALAPPDATA%\kingst\vis.config）

2. <enaSocket>1</enaSocket>（端口默认 23367，可改 <listenPort>）

3. 重启软件并保持运行；首次监听需允许防火墙

KingstVIS 3.6.6 为 x86_64 Qt 程序，Apple Silicon 上经 Rosetta 2 运行正常 （本机已安装至 /Applications/KingstVIS.app 并已启用 Socket）。 无硬件时用 start --simulate（Demo 设备）走通全流程；软件通过 simulate 与真实采样的互斥报错，保证你始终知道数据是真是假。

配置（环境变量）

接入 MCP 客户端

ZCode（.zcode/settings.json）或 Claude Desktop：

{
  "mcpServers": {
    "kingstvis": {
      "command": "/Users/andylos/mcp_gen/kingstvis/.venv/bin/python",
      "args": ["-m", "kingstvis_mcp.server"],
      "cwd": "/Users/andylos/mcp_gen/kingstvis",
      "env": {
        "KINGSTVIS_DATA_DIR": "/Users/andylos/mcp_gen/kingstvis/data"
      }
    }
  }
}

工具总览（26 个）

内置解码器的脚本控制（无 GUI）

官方 Socket API 只能 export-decoded 导出已有解析器的结果，不能添加/配置解析器。 本工程逆向出了 vis.config 的 <analyzers> schema 与插件的 SimpleArchive 设置串 格式（NOTES.md §5），从而补全了链路：

.venv/bin/python scripts/manage_analyzers.py add PWM --channels 0       # 单通道
.venv/bin/python scripts/manage_analyzers.py add I2C --channels 1 0     # SDA SCL
.venv/bin/python scripts/manage_analyzers.py add SPI --channels 0 1 2 3 # CLK MOSI MISO CS
# 或 MCP：  add_analyzer(plugin="I2C", channels=[1, 0])
# 之后照常： start() -> export_decoded(analyzer=slot)

PWM 已端到端验证（解码出逐周期 正/负脉宽、周期、频率、占空比），I2C 在 demo 流量上验证（SDA/SCL 通道顺序确认）；UART/SPI/CAN/DS18B20/1-Wire/USB-PD/Modbus 为 load-ok（可加载运行，个别参数按信号微调）；其余 30+ 插件字段布局已逆向 （manage_analyzers.py fields 查看），传入正确的 parameters 串即可用； UNIO 已知会崩溃、默认拒绝。真机信号上按 NOTES.md §5.4 的字段表微调。

典型工作流

# 一键流水线：冷启动软件->配置解析器->采样->原始导出+解码导出+测量->报告
# （软件未运行会自动拉起；解析器集合变化会自动改配置并重启）
.venv/bin/python scripts/auto_pipeline.py --simulate --channels 0 1 --analyzers PWM:0 PWM:1
.venv/bin/python scripts/auto_pipeline.py --rate 1e6 --depth 1e6 --channels 0 1 \
    --analyzers PWM:0 PWM:1 --trigger 0        # 真机（需硬件在线）

# 或分步（MCP 工具）
set_sample_rate(1000000) -> start() -> export_data("cap.kvdat")

# 之后任意时刻离线分析
parse_file("data/cap.kvdat")
measure_channel("data/cap.npz", channel=0)
list_edges("data/cap.npz", channel=0, kind="rising", limit=100)

协议解码（I2C/SPI/UART/CAN...）：add_analyzer("UART", channel=3) 脚本添加解析器 （自动重启软件），采集后 export_decoded(..., analyzer=0) 导出解码表； 也可用 scripts/manage_analyzers.py 命令行管理。

已知边界

• start 阻塞至采样完成；超大深度×低采样率可能超过 KINGSTVIS_START_TIMEOUT， 需按需调大或用 stop 中止（中止后连接会被重置以避免错位响应）。

• 响应以 0.5s 空闲间隙分帧（协议无终结符，与官方示例行为一致）。

• kvdat 的 trigger_pos = 触发点采样索引（真机已验证：与 get-actual-sample-time 的负起始时间严格对应）。

• 会话中没有解析器时 export-decoded 报 invalid parameter——用 add_analyzer/manage_analyzers.py 先添加（需重启软件生效）。