Waveform MCP

🚀 Waveform MCP Server

wellenライブラリを使用して、波形ファイル（VCD/FST形式）を読み取り、分析するためのMCP（Model Context Protocol）サーバーです。

✨ 主な機能

• VCD（Value Change Dump）およびFST（Fast Signal Trace）波形ファイルを開く
• 波形内のすべての信号を階層パス付きでリストする
• 特定の時間インデックス（単一または複数）で信号値を読み取る
• 信号のメタデータ（タイプ、幅、インデックス範囲）を取得する
• 時間範囲内で信号イベント（変更）を見つける
• タイムスケール情報を使用して時間値をフォーマットする（例：「10ns」、「5000ps」）
• リモートアクセス用のストリーミング可能なHTTPサーバーをサポートする

🛠️ ツール

サーバーは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）
   • ビット単位演算子: ~（NOT）、&（AND）、|（OR）、^（XOR）
   • 論理演算子: &&（AND）、||（OR）、!（NOT）
   • 比較演算子: ==、!=
   • グループ化用の括弧: (condition)
   • $past(signal) - 前の時間インデックスから信号値を読み取る
   • Verilogスタイルのリテラル: 4'b0101（2進数）、3'd2（10進数）、5'h1A（16進数）
   • ビット抽出: 単一ビットの場合はsignal[bit]、範囲の場合はsignal[msb:lsb]

   演算子の優先順位（高から低）:

   1. ~, !（ビット単位NOT、論理NOT）
   2. ==, !=（等価/不等価）
   3. &（ビット単位AND）
   4. ^（ビット単位XOR）
   5. |（ビット単位OR）
   6. &&（論理AND）
   7. ||（論理OR）

   例:

   • signal1 AND 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がセットされているか確認）
   • ビット単位NOT: ~TOP.mask（すべてのビットを反転）

📦 インストール

# リポジトリをクローンする
git clone https://github.com/jiegec/waveform-mcp
cd waveform-mcp

# サーバーをビルドする
cargo build --release

ビルドされたバイナリはtarget/release/waveform-mcpにあります。これはSTDIOをトランスポートとして使用します。MCPクライアントを適切に構成してください。

🔧 開発

ビルド

cargo build
cargo build --release

テスト

cargo test

実行

# 標準入出力トランスポートでサーバーを実行する（デフォルト）
cargo run

# HTTPモードでサーバーを実行する
cargo run -- --http

# カスタムバインドアドレスでHTTPモードでサーバーを実行する
cargo run -- --http --bind-address 0.0.0.0:8000

サーバーは2つのトランスポートモードをサポートしています。

• Stdioモード（デフォルト）: MCP通信に標準入出力を使用する
• HTTPモード: /mcpエンドポイントでリモートアクセス用のストリーミング可能なHTTPサーバーを使用する

HTTPモードで実行する場合、サーバーは指定されたバインドアドレス（デフォルト: 127.0.0.1:8000）で待機します。HTTPモードでは、波形ストアを複数のHTTPセッション間で共有でき、波形ファイルのリモート分析が可能になります。

📄 ライセンス

MIT