Wave MCP (Devil Sx)

Wave MCP服务器

此存储库不再维护。 波形数据库不太适合MCP工具——编程工具更适合。看 高级工具使用 了解详情。

MCP服务器，用于查看和解析VCD（值更改转储）和FST（快速信号跟踪）波形文件。

特性

• VCD和FST波形格式的统一接口（从文件扩展名自动检测）
• 带过滤的分层信号列表（模块路径、深度、模式/正则表达式）
• 时间范围查询
• 可配置输出格式（二进制、十六进制、十进制）的信号值提取
• 信号名称的不区分大小写的子字符串匹配
• IEEE 754浮点转换工具（float32、float16、bfloat16）

为什么是皮维伦？

• 统一接口：使用单个解析器处理VCD和FST格式，无需单独 vcdvcd + pylibfst 代码路径
• 演出：VCD加载速度比vcdvcd快~5-10x；FST值查询比pylibfst快约1.8倍
• 简洁：4个MCP工具，而不是8个特定格式的工具

安装

先决条件

• Python 3.12+
• 紫外线 （推荐包管理器）
• 锈 （仅当您的平台没有预制车轮时）：

pywellen为Linux x86_64/ARM64和macOS x86_64/ARM64分发预编译的轮子。 大多数用户 不需要安装Rust.如果您使用的是不受支持的平台或从源代码构建，请安装Rust>=1.73.0：

  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

设置

cd /path/to/wave_mcp

# Install (pywellen only — all MCP server needs)
uv sync

# Install with dev/test dependencies (includes vcdvcd, pylibfst for differential testing)
uv sync --group dev

用法

作为MCP服务器（克劳德桌面）

添加到您的Claude桌面配置(~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "wave-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/wave_mcp", "run", "wave-mcp"]
    }
  }
}

使用MCP检查器进行调试

npx -y @modelcontextprotocol/inspector uv --directory /path/to/wave_mcp run wave-mcp

可用工具

波形工具

浮点转换工具

工作流示例

# 1. Load a waveform file
load_waveform(path="/path/to/waveform.vcd")

# 2. List signals (with optional filtering)
get_signals(module_path="top.cpu", max_depth=1, limit=50)

# 3. Get time range
get_time_range()

# 4. Query signal values
get_signal_values(
    signal_names=["clk", "counter"],
    start_time=0,
    end_time=1000,
    format="hex"
)

文件大小估计

VCD文件大小

VCD是一种基于文本的格式。文件大小取决于信号计数（N）和时间步长计数（T）：

VCD_size (bytes) ~= 10 * T * H(N)

哪里 H(N) = sum(1/k for k=1..N) 近似为N次谐波数 ln(N) + 0.5772.

FST文件大小

FST是一种压缩的二进制格式。典型压缩比与VCD： 8倍至20倍.

FST_size ~= VCD_size / compression_ratio

压缩比随信号活动而变化。低活动信号压缩得更好。

MCP输出令牌消耗

经验法则： 1000个代币~ 750个单词.

get_signals 输出

每条信号线大约有8个字。使用标题行：

get_signal_values 输出

每条值变化线大约有3个单词。对于每个信号有C变化的N个信号：

Words ~= 10 + N * (5 + 3 * min(C, limit))
Tokens ~= Words * 1000 / 750

控制代币消费的建议：

• 使用 limit 参数（默认值：100）用于限制每个信号的值变化
• 缩小时间范围(start_time/end_time)而不是查询完整的波形
• 使用 module_path 和 pattern 过滤器在 get_signals 减少信号计数

测试

# Run all tests
uv run pytest tests/ -v

# Run benchmark (small scale, quick)
BENCHMARK_SCALE=small uv run pytest tests/test_benchmark.py -v -s

# Run benchmark (full scale: KB to 100MB+, ~6 min)
BENCHMARK_SCALE=full uv run pytest tests/test_benchmark.py -v -s

项目结构

wave_mcp/
├── mcp_server.py              # MCP server entry point
├── pyproject.toml              # Project config and dependencies
├── src/
│   ├── parsers/
│   │   ├── __init__.py         # Parser exports and global state
│   │   ├── wellen_parser.py    # Unified parser (pywellen backend)
│   │   ├── vcd_parser.py       # Legacy VCD parser (vcdvcd, for diff testing)
│   │   └── fst_parser.py       # Legacy FST parser (pylibfst, for diff testing)
│   ├── tools/
│   │   ├── __init__.py
│   │   ├── waveform_tools.py   # Unified waveform MCP tools
│   │   └── float_tools.py      # IEEE 754 float conversion tools
│   └── utils/
│       └── format.py           # Value formatting utilities
├── tests/
│   ├── test_waveform_tools.py  # Unified tool integration tests
│   ├── test_differential.py    # Old vs new parser comparison tests
│   ├── test_benchmark.py       # Performance benchmarks
│   └── ...
└── docs/
    └── benchmark_report.md     # Auto-generated benchmark report

支持格式