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