Waveform MCP

🚀 波形MCP服务器

这是一个MCP（模型上下文协议）服务器，借助 wellen 库来读取和分析波形文件（VCD/FST格式）。它能有效处理波形文件，为用户提供便捷的波形数据读取和分析功能。

✨ 主要特性

• 可打开VCD（值变更转储）和FST（快速信号跟踪）格式的波形文件。
• 能列出波形中所有带分层路径的信号。
• 可在特定时间索引（单个或多个）读取信号值。
• 能够获取信号元数据（类型、宽度、索引范围）。
• 能在指定时间范围内查找信号事件（变化）。
• 可结合时间尺度信息格式化时间值（例如，"10ns"、"5000ps"）。
• 支持可流式传输的HTTP服务器，方便远程访问。

📦 安装指南

# 克隆仓库
git clone https://github.com/jiegec/waveform-mcp
cd waveform-mcp

# 构建服务器
cargo build --release

构建好的二进制文件位于 target/release/waveform-mcp。它使用标准输入输出进行传输，请相应地配置你的MCP客户端。

💻 使用示例

基础用法

服务器提供了6个MCP工具：

1. open_waveform - 打开波形文件

   • file_path：.vcd或.fst文件的路径
   • alias：波形的可选别名（默认为文件名）

   示例响应：

   Waveform opened successfully with alias: waveform.vcd
   

2. list_signals - 列出已打开波形中的所有信号

   • waveform_id：波形的ID或别名
   • name_pattern：可选的子字符串，用于按名称过滤信号（不区分大小写）
   • hierarchy_prefix：可选的前缀，用于按分层路径过滤信号
   • recursive：可选标志，用于包含子分层中的信号（默认：false）
   • limit：可选的最大返回信号数量（默认：100）

   示例响应：

   Found 3 signals:
   top.clock
   top.reset
   top.data
   

3. read_signal - 在特定时间索引读取信号值

   • waveform_id：波形的ID或别名
   • signal_path：信号的分层路径（例如，"top.module.signal"）
   • time_index：可选的单个读取时间索引
   • time_indices：可选的时间索引数组，用于读取多个值

   示例响应：

   Time index 0 (0ns): 0
   Time index 10 (10ns): 1
   Time index 20 (20ns): 1
   

4. get_signal_info - 获取信号的元数据

   • waveform_id：波形的ID或别名
   • signal_path：信号的分层路径

   示例响应：

   Signal: top.data
   Type: Wire
   Width: 8 bits
   Index: [7:0]
   

5. find_signal_events - 在时间范围内查找所有信号变化

   • waveform_id：波形的ID或别名
   • signal_path：信号的分层路径
   • start_time_index：可选的时间范围起始（默认：0）
   • end_time_index：可选的时间范围结束（默认：最后一个时间索引）
   • limit：可选的最大返回事件数量（默认：无限制）

   示例响应：

   Found 3 events for signal 'top.clock' (time range: 0 to 20):
   Time index 0 (0ns): 0
   Time index 10 (10ns): 1
   Time index 20 (20ns): 0
   

6. find_conditional_events - 查找满足条件的事件

   • waveform_id：波形的ID或别名
   • condition：要计算的条件表达式
   • start_time_index：可选的时间范围起始（默认：0）
   • end_time_index：可选的时间范围结束（默认：最后一个时间索引）
   • limit：可选的最大返回事件数量（默认：100）

   示例响应：

   Found 2 events for condition '!$past(TOP.signal) && TOP.signal' (time range: 0 to 50):
   Time index 5 (50ns): top.signal = 8'h0A
   Time index 15 (150ns): top.signal = 8'hFF
   

   支持的条件语法：

   • 信号路径（例如，TOP.signal）
   • 按位运算符：~（非）、&（与）、|（或）、^（异或）
   • 布尔运算符：&&（与）、||（或）、!（非）
   • 比较运算符：==、!=
   • 用于分组的括号：(condition)
   • $past(signal) - 读取前一个时间索引的信号值
   • Verilog风格的字面量：4'b0101（二进制）、3'd2（十进制）、5'h1A（十六进制）
   • 位提取：signal[bit] 用于单个位，signal[msb:lsb] 用于范围

   运算符优先级（从高到低）：

   1. ~、!（按位非、逻辑非）
   2. ==、!=（相等/不相等）
   3. &（按位与）
   4. ^（按位异或）
   5. |（按位或）
   6. &&（逻辑与）
   7. ||（逻辑或）

   示例：

   • 查找signal1和signal2同时为真的情况：TOP.signal1 && TOP.signal2
   • 查找计数器等于特定值的情况：TOP.counter == 4'd10
   • 查找上升沿：!$past(TOP.signal) && TOP.signal
   • 查找下降沿：$past(TOP.signal) && !TOP.signal
   • 查找握手周期（当valid和ready都置位时）：TOP.valid && TOP.ready
   • 复杂条件：(TOP.valid && TOP.data != 8'hFF) || TOP.error
   • 按位运算：TOP.flags & 4'b0001（检查第0位是否置位）
   • 按位非：~TOP.mask（反转所有位）

📚 详细文档

开发

构建

cargo build
cargo build --release

测试

cargo test

运行

# 使用标准输入输出传输运行服务器（默认）
cargo run

# 以HTTP模式运行服务器
cargo run -- --http

# 以HTTP模式运行服务器并使用自定义绑定地址
cargo run -- --http --bind-address 0.0.0.0:8000

服务器支持两种传输模式：

• 标准输入输出模式（默认）：使用标准输入输出进行MCP通信。
• HTTP模式：使用可流式传输的HTTP服务器，通过 /mcp 端点进行远程访问。

在HTTP模式下运行时，服务器监听指定的绑定地址（默认：127.0.0.1:8000）。HTTP模式允许在多个HTTP会话之间共享波形存储，从而实现对波形文件的远程分析。

📄 许可证

MIT