RTL Sim-Log MCP Assistant

一個透過 MCP (Model Context Protocol) 讓 AI 助手（Claude）能夠呼叫確定性工具（deterministic tools）來分析 RTL 模擬 / 合成 log 的專案。

專案動機

在實際的 IC 驗證協作經驗中，我發現直接把原始 log 丟給 AI 分析，存在兩個問題：

1. 雜訊淹沒重點：一份 synthesis compile log 動輒數千行，其中大量是重複性的資訊訊息（例如 timing arc disable 訊息可能重複數百次），AI 容易被雜訊干擾或超出 context window。

2. AI 可能給出看似合理但錯誤的建議：曾在與 AI 協作除錯 I2C 訊號問題時，發現 AI 建議將未使用的 I2C 訊號直接 tie-off 為 0——這在硬體上是錯誤的，因為 I2C 是雙向開汲極（open-drain）訊號，需要外部 pull-up 電阻才能正常運作。AI 缺乏這類硬體背景知識，卻仍給出看似合理的建議。

這個專案的核心設計理念是：把「資料處理」與「規則判斷」交給確定性的 Python 工具，把「推理與總結」留給 AI，並透過 MCP 協定讓兩者協作，而不是讓 AI 憑自己的訓練資料去猜測或臆造。

Related MCP server: Xcelium MCP Server

架構

Claude Desktop (MCP Host)
        │
        │ MCP Protocol (stdio / JSON-RPC)
        ▼
MCP Server (Python, mcp SDK)
        │
        ├─ analyze_compile_log      → 解析 synthesis compile log，結構化統計 warning/error
        ├─ lookup_signal_type       → 查詢訊號電氣特性，判斷是否可安全 tie-off
        └─ analyze_regression_result → 解析 regression 結果，統計 PASS/FAIL/FATAL

整個 Server 可透過 Docker 容器化執行，並透過 GitHub Actions 進行自動化測試與建置。

三個工具

1. analyze_compile_log

解析 Synopsys Design Compiler 的 synthesis compile log，將分散在數千行中的警告與錯誤，整理成結構化 JSON 摘要，包含：

• 各類 warning code 統計（VER-, LINT-, ELAB-, OPT- 等）

• Latch 推斷位置（檔案與行號）

• Timing loop 偵測次數

• 致命錯誤清單

• 未連接的 port 清單

實測案例：使用真實的研究所 VLSI 專題 compile log 測試，成功將 320 筆分散的警告訊息整理為 21 類統計摘要，AI 進一步根據結構化結果，觀察到多筆 unconnected port 呈現連續 bit range 的規律，推論出可能是「32-bit instruction bus 只接了部分位元」的功能性問題——這是在乾淨結構化資料基礎上才能做出的語意層級推理。

2. lookup_signal_type

查詢特定訊號的電氣特性類型，判斷該訊號是否可安全 tie-off。這個工具直接對應本專案的核心動機：把「人類已知的硬體限制」固化成確定性規則，而非讓 AI 憑經驗猜測。

• 已知規則（如 I2C SDA/SCL）：明確回傳是否可安全 tie-off 及原因

• 未知訊號：回傳 UNKNOWN，並提示需要人工確認，不會讓系統瞎猜

3. analyze_regression_result

解析 regression 測試結果，統計 PASS / FAIL / FATAL 數量與通過率，並列出失敗案例名稱，方便快速掌握整體驗證狀態。

設計上的關鍵決策

• Deterministic tool 負責處理，LLM 負責 reasoning：所有數字統計、規則判斷都由 Python 完成，確保結果可重現、可驗證；AI 只在乾淨的結構化資料基礎上做總結與建議。

• 找不到答案時明確回報 UNKNOWN，而非讓 AI 猜測：這是防止 AI 幻覺（hallucination）最直接的機制。

• 完整的自動化測試（pytest）：涵蓋核心邏輯與邊界情境（如訊號名稱大小寫、未知訊號、統計數字一致性），確保工具本身的正確性可被驗證，而不只是「看起來能動」。

• 測試資料使用真實 log：測試資料取自研究所 VLSI 專題的真實 Synopsys DC compile log（已去識別化處理），而非人工捏造的範例，因此涵蓋的錯誤模式更貼近實際情境。

環境需求與執行方式

# 安裝依賴
pip install -r requirements.txt

# 執行測試
pytest test_tools.py -v

# 建置 Docker image
docker build -t rtl-mcp-agent .

連接 Claude Desktop

在 claude_desktop_config.json 中加入：

{
  "mcpServers": {
    "rtl-debug-assistant": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/your/local/path:/data",
        "rtl-mcp-agent"
      ]
    }
  }
}

CI/CD

透過 GitHub Actions 自動化：

1. test job：安裝依賴、執行 pytest

2. docker-build job：僅在 test 通過後才執行（fail-fast 原則），確保邏輯正確後才進行容器建置

開發過程中的除錯紀錄（節錄）

在開發過程中，曾發現「不同 log 檔案卻得到相同分析結果」的異常現象。沒有直接假設是工具邏輯錯誤，而是設計了一個「指紋測試」——在測試檔案中插入一個帶有獨特標記的假警告訊息，驗證工具是否真的依照傳入路徑讀取檔案內容。最終確認問題是測試資料本身的巧合（不同檔案中真正會被統計到的錯誤類型剛好相同），而非工具邏輯缺陷。這個過程本身也體現了本專案的核心理念：任何看似合理的結果，在被驗證之前都不該被照單全收。

技術棧

Python 3.11 · MCP SDK · pytest · Docker · GitHub Actions