Joulescope MCP

🔌 JouleScope JS220 MCP 服務器

joulescope-mcp 是面向 JouleScope JS220 精密能量分析儀的 Model Context Protocol (MCP) 服務器。它提供了對智能體友好的工具，用於測量電流、電壓、功率、電荷與能量，並支持對 JouleScope 驅動 PubSub 主題樹的底層訪問。

核心工具是 measure_energy：傳入測量時長與累積間隔，即可返回總電荷、總能量，以及每個間隔的一個採樣點。例如，duration_s=15 與 interval_s=0.5 會返回 30 個間隔採樣及 total_charge_mAh 等總計值。

---

🚀 快速開始

直接通過 uvx 從 GitHub 安裝：

{
  "mcpServers": {
    "joulescope-js220": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/juanqui/joulescope-mcp",
        "joulescope-mcp"
      ]
    }
  }
}

如果你偏好 SSH，可使用相同形態的 Git 安裝方式，僅替換為 SSH URL：

{
  "mcpServers": {
    "joulescope-js220": {
      "command": "uvx",
      "args": [
        "--from",
        "git+ssh://git@github.com/juanqui/joulescope-mcp.git",
        "joulescope-mcp"
      ]
    }
  }
}

然後向你的 MCP 客戶端發出請求：

測量 JouleScope 功率 15 秒，間隔 500 毫秒，包含電壓。

預期的返回結構如下（緊湊採樣數組為便於展示已截斷）：

{
  "total_charge_mAh": 0.0051,
  "total_energy_mWh": 0.019,
  "average_current_mA": 1.23,
  "average_voltage_v": 3.70,
  "interval_count": 30,
  "sample_charge_mAh": [0.00015, 0.00015, 0.00015]
}

---

📦 環境要求

• Python 3.11 或更高版本
• 通過 USB 連接的 JouleScope JS220
• 用於推薦的 uvx 安裝路徑的 uv
• 能夠運行 stdio 服務器的 MCP 客戶端

該 Python 包會安裝 pyjoulescope_driver>=2.1.0 和 pyjls>=0.17。在 Linux 上，請在運行服務器前按照 JouleScope 官方文檔配置 JouleScope udev 規則。

💡 使用建議

uvx 是 uv tool run 的別名；它會在隔離環境中運行 Python 命令行工具，無需永久安裝。

---

🛠️ 安裝選項

方案 1：通過 uvx 從 GitHub 安裝

uvx --from git+https://github.com/juanqui/joulescope-mcp joulescope-mcp

MCP JSON：

{
  "mcpServers": {
    "joulescope-js220": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/juanqui/joulescope-mcp",
        "joulescope-mcp"
      ]
    }
  }
}

常規安裝使用此方案。

方案 2：通過 SSH 從 GitHub 安裝（使用 uvx）

如果你偏好 SSH 或需要 GitHub SSH 認證，請使用此方案：

uvx --from git+ssh://git@github.com/juanqui/joulescope-mcp.git joulescope-mcp

方案 3：本地檢出

在開發過程中，或需要將 MCP 服務器固定到本地克隆時使用：

git clone git@github.com:juanqui/joulescope-mcp.git
cd joulescope-mcp
uv sync --extra dev
uv run joulescope-mcp

驗證驅動能夠識別 JS220：

uv run python -m pyjoulescope_driver scan
uv run python -m pyjoulescope_driver statistics --frequency 2 --duration 1

本地檢出的 MCP JSON：

{
  "mcpServers": {
    "joulescope-js220": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/joulescope-mcp",
        "run",
        "joulescope-mcp"
      ]
    }
  }
}

⚠️ 重要提示

請使用絕對路徑。部分 MCP 客戶端啟動服務器時 PATH 受限；如果找不到 uv 或 uvx，請將 "command": "uvx" 或 "command": "uv" 替換為 which uvx 或 which uv 輸出的完整可執行文件路徑。

---

🔗 客戶端配置

大多數 MCP 客戶端使用以下兩種 JSON 結構之一：

• mcpServers：Claude Desktop、Claude Code 項目配置、Cursor、Windsurf、Cline 等眾多客戶端
• servers：VS Code / GitHub Copilot MCP 配置

選擇一條安裝命令：

當前場景	在客戶端配置中使用此命令
常規 GitHub 安裝	uvx --from git+https://github.com/juanqui/joulescope-mcp joulescope-mcp
通過 SSH 的 GitHub 安裝	uvx --from git+ssh://git@github.com/juanqui/joulescope-mcp.git joulescope-mcp
本地開發檢出	uv --directory /absolute/path/to/joulescope-mcp run joulescope-mcp

以下代碼片段展示常規 GitHub 安裝路徑。

GitHub 替換：

{
  "command": "uvx",
  "args": [
    "--from",
    "git+https://github.com/juanqui/joulescope-mcp",
    "joulescope-mcp"
  ]
}

本地檢出替換：

{
  "command": "uv",
  "args": [
    "--directory",
    "/absolute/path/to/joulescope-mcp",
    "run",
    "joulescope-mcp"
  ]
}

⚠️ 重要提示

對於同一臺物理 JS220，僅配置一個常駐客戶端。許多桌面客戶端會自動啟動已配置的 MCP 服務器，而 JS220 不應在多個 MCP 服務器進程間共享。

---

⏱️ 超時配置

measure_energy 是阻塞式硬件測量。15 秒的測量至少耗時 15 秒，再加上 JS220 啟動與清理時間。當 MCP 客戶端提供超時設置時，請配置為 5 分鐘的工具超時。

推薦值：

• 工具調用超時：300 秒 / 300,000 毫秒
• 服務器啟動超時：60 秒 / 60,000 毫秒

如果某個客戶端未提供超時設置，請讓同步測量時長足夠短以適應客戶端，或改用支持可配置 MCP 工具超時的客戶端。未來的異步測量 API 可以避免長時間的單次工具調用，但當前 measure_energy 調用按設計是同步的。

Claude Code

推薦的全局安裝：

claude mcp add joulescope-js220 -- uvx --from git+https://github.com/juanqui/joulescope-mcp joulescope-mcp
claude mcp list

啟動 Claude Code，設置 5 分鐘 MCP 工具調用與 60 秒服務器啟動超時：

MCP_TIMEOUT=60000 MCP_TOOL_TIMEOUT=300000 claude

項目 .mcp.json：

{
  "mcpServers": {
    "joulescope-js220": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/juanqui/joulescope-mcp",
        "joulescope-mcp"
      ]
    }
  }
}

在 Claude Code 中運行 /mcp 查看服務器狀態。MCP_TIMEOUT 和 MCP_TOOL_TIMEOUT 是 Claude Code 進程級環境變量，而非單個服務器的 env 值。

Claude Desktop

編輯：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "joulescope-js220": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/juanqui/joulescope-mcp",
        "joulescope-mcp"
      ]
    }
  }
}

編輯文件後重啟 Claude Desktop。Claude Desktop 未在 claude_desktop_config.json 中提供可移植的單服務器超時字段；若你的啟動環境支持 MCP 超時環境變量，請在啟動 Claude Desktop 前設置 MCP_TOOL_TIMEOUT=300000。

Codex

推薦的全局安裝：

codex mcp add joulescope-js220 -- uvx --from git+https://github.com/juanqui/joulescope-mcp joulescope-mcp
codex mcp list

直接編輯 ~/.codex/config.toml 條目：

[mcp_servers.joulescope-js220]
command = "uvx"
args = ["--from", "git+https://github.com/juanqui/joulescope-mcp", "joulescope-mcp"]
startup_timeout_sec = 60
tool_timeout_sec = 300

codex mcp add 命令會創建服務器條目。隨後編輯 ~/.codex/config.toml 以添加 startup_timeout_sec 和 tool_timeout_sec。

Cursor

全局配置：

• macOS/Linux：~/.cursor/mcp.json
• Windows：%USERPROFILE%\.cursor\mcp.json

項目配置：

• .cursor/mcp.json

{
  "mcpServers": {
    "joulescope-js220": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/juanqui/joulescope-mcp",
        "joulescope-mcp"
      ]
    }
  }
}

Cursor 也支持從設置中添加 MCP 服務器。修改配置後，請重啟 Cursor 或從 MCP 設置面板刷新 MCP 工具。Cursor 目前未提供可移植的 mcp.json 超時字段；若你的 Cursor 版本在設置中提供請求/工具超時，請設為 300 秒。

VS Code / GitHub Copilot Agent Mode

工作區配置：

• .vscode/mcp.json

用戶配置：

• 從命令面板運行 MCP: Open User Configuration。

{
  "servers": {
    "joulescope-js220": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/juanqui/joulescope-mcp",
        "joulescope-mcp"
      ]
    }
  }
}

命令行安裝：

code --add-mcp '{"name":"joulescope-js220","type":"stdio","command":"uvx","args":["--from","git+https://github.com/juanqui/joulescope-mcp","joulescope-mcp"]}'

VS Code 的 MCP 配置參考未提供單服務器工具超時字段。請勿向 .vscode/mcp.json 添加不支持的超時鍵；若你的 Copilot 主機對長時間調用超時，請改用較短的同步測量。

Windsurf

編輯：

• macOS/Linux：~/.codeium/windsurf/mcp_config.json
• Windows：%USERPROFILE%\.codeium\windsurf\mcp_config.json

{
  "mcpServers": {
    "joulescope-js220": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/juanqui/joulescope-mcp",
        "joulescope-mcp"
      ]
    }
  }
}

Windsurf Cascade 有啟用工具總數限制。如果你使用多個 MCP 服務器，請禁用不需要的工具。Windsurf 公開的 MCP 文檔未提供 mcp_config.json 中可移植的超時字段；若你的 Windsurf 版本提供請求/工具超時設置，請設為 300 秒。

Cline

CLI 安裝：

cline mcp add joulescope-js220 -- uvx --from git+https://github.com/juanqui/joulescope-mcp joulescope-mcp

手動配置：

• CLI 默認路徑：~/.cline/data/settings/cline_mcp_settings.json
• VS Code 擴展：打開 MCP Servers 面板，然後選擇 Configure MCP Servers

{
  "mcpServers": {
    "joulescope-js220": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/juanqui/joulescope-mcp",
        "joulescope-mcp"
      ],
      "timeout": 300,
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

---

🌐 以 HTTP 方式運行

大多數本地 MCP 客戶端應使用 stdio。如果需要可流式 HTTP：

uvx --from git+https://github.com/juanqui/joulescope-mcp joulescope-mcp --transport streamable-http --mount-path /mcp

---

🧰 故障排除

• 客戶端找不到 uvx：使用 which uvx 輸出的絕對路徑。
• 未發現 JouleScope：在終端中直接運行你配置的服務器命令以檢查啟動錯誤，然後運行 uvx --from pyjoulescope-driver pyjoulescope_driver scan 驗證官方驅動能否識別 JS220。
• Linux 上權限被拒絕：安裝 JouleScope udev 規則並重新連接 JS220。
• 多個客戶端爭用設備：同一時間僅對一個 JS220 運行一個 MCP 客戶端/服務器進程。
• GitHub 安裝失敗：先確認 git clone https://github.com/juanqui/joulescope-mcp 可用。
• 工具已變更但客戶端仍顯示舊工具：重啟客戶端或重置/重新加載 MCP 工具。

快速本地健康檢查：

uv run python scripts/hardware_smoke.py --duration-s 2 --interval-s 0.5

---

🤖 Agent 工作流

進行固件或應用功耗優化時，請保持測量設置穩定：

1. 使用 measure_energy 運行基線測量。
2. 應用一項固件或軟件更改。
3. 使用相同的 measure_energy 時長與間隔再次測量。
4. 比較 total_charge_mAh、total_energy_mWh、average_current_mA 及間隔採樣。
5. 當差異接近正常的運行間波動時，重複測量。

示例請求：

{
  "duration_s": 15,
  "interval_s": 0.5,
  "compact": true
}

響應包含：

• total_charge_mAh：測量窗口內的總電荷
• total_energy_mWh：測量窗口內的總能量
• average_current_mA：實際捕獲時長內的平均電流
• average_power_mW：實際捕獲時長內的平均功率
• actual_interval_s：JS220 捕獲的平均實際間隔
• sample_charge_mAh：當 compact=true 時的緊湊逐間隔電荷列表
• sample_energy_mWh：當 compact=true 時的緊湊逐間隔能量列表
• sample_voltage_avg_v、sample_voltage_min_v、sample_voltage_max_v：當 compact=true 且 include_voltage=true 時的緊湊逐間隔電壓列表
• samples：當 compact=false 時的完整逐間隔統計

如果 duration_s 不是 interval_s 的整數倍，服務器會向上取整到下一個完整間隔，並同時報告 requested_duration_s 與 actual_duration_s。

---

🧩 工具

list_devices

列出已連接的 JouleScope 設備。對於 JS220 設備，會嘗試包含硬件、固件和 FPGA 版本。

device_info

返回所選設備的保留驅動主題值。設置 include_metadata=true 以包含驅動返回的主題元數據。

measure_energy

使用 JS220 傳感器側統計測量電荷與能量。

參數：

• duration_s：請求的測量時長（秒）
• interval_s：累積間隔（秒）
• device_path：可選的顯式設備路徑，如 u/js220/005920
• configure_auto_range：默認為 true；將電流和電壓量程模式配置為 auto
• compact：返回緊湊的電荷與能量數組，並省略完整採樣
• include_voltage：與 compact 一起使用時，還會返回逐間隔電壓數組

實現細節：JS220 每隔一個間隔發佈以庫侖為單位的 current.integral 與以焦耳為單位的 power.integral。服務器對這些積分求和，並將電荷轉換為 mAh、能量轉換為 mWh。

capture_statistics

基於頻率的 measure_energy 封裝。當你希望使用 frequency_hz 而非 interval_s 時使用。

configure_frontend

設置電流和電壓量程模式及可選的量程選擇。常規測量請使用 auto。

target_power_status

報告 JS220 目標/DUT 電源路徑是否已連接。對於 JS220，DUT 電源通過 s/i/range/mode 控制：off 斷開 Current+ 與 Current-，而 auto 或 manual 連接目標路徑以進行測量。

set_target_power

通過 JS220 電流路徑連接或斷開 DUT 電源。

參數：

• power_on：為 true 時連接目標電源，為 false 時斷開
• on_mode：默認 auto，或 manual
• settle_ms：狀態改變後的可選等待時間

cycle_target_power

通過先關閉目標電源、等待、再恢復目標電源來對 DUT 進行斷電重啟（power-cycle）。

參數：

• off_ms：斷電保持時間（毫秒）
• on_mode：默認 auto，或 manual
• settle_ms：恢復電源後的可選等待時間

record_jls

使用 JouleScope 驅動的 Record API 將原始採樣記錄為 JLS v2 文件。這對後續在 JouleScope UI 或 JLS 工具中進行波形分析很有用。除非 overwrite=true，否則會拒絕已存在的文件。

read_gpi

讀取 JS220 通用輸入（GPI）狀態，返回 32 位值及解碼後的引腳。

list_topics

列出保留的驅動主題、值及可選元數據。這是探索高級 JS220 功能的發現工具。

query_topic

查詢單個驅動主題。相對主題會在所選設備下解析，因此 c/fw/version 會變為 u/js220/<serial>/c/fw/version。

publish_topic

向驅動主題發佈值。這會暴露高級 JS220 功能，並可能改變設備行為。在可用時優先使用類型化工具。

---

📚 資源與提示詞

資源：

• joulescope://devices：JSON 設備列表
• joulescope://driver：服務器與驅動版本信息

提示詞：

• power_optimization_session：面向測量驅動功耗優化循環的模板

---

🛡️ 安全與限制

服務器在每次工具調用時打開一個短生命週期的 JouleScope 驅動連接，並在單個服務器進程內串行化設備訪問。阻塞式測量具有以下保護限制：

• 最小間隔：0.5 毫秒
• 最大時長：3600 秒
• 最多返回間隔數：10,000
• 如果 JS220 未發佈預期採樣，統計收集會超時

set_target_power、cycle_target_power、record_jls 和 publish_topic 被標記為具有寫入/破壞性能力的 MCP 工具。cycle_target_power 會有意中斷 DUT。智能體僅在中斷屬於所請求測試的一部分時才應使用它。

---

🧑💻 開發

配置本地檢出：

uv sync --extra dev

運行測試：

uv run python -m pytest

運行代碼檢查：

uv run python -m ruff check .

構建包：

uv run python -m build

硬件冒煙測試：

uv run python -m pyjoulescope_driver scan
uv run python -m pyjoulescope_driver statistics --frequency 2 --duration 1
uv run python - <<'PY'
from joulescope_mcp.service import Js220Service
r = Js220Service().measure_energy(duration_s=2, interval_s=0.5)
print(r["total_charge_mAh"], r["average_current_mA"], [s["charge_mAh"] for s in r["samples"]])
PY

可重複的硬件冒煙腳本：

uv run python scripts/hardware_smoke.py --duration-s 2 --interval-s 0.5

---

🏗️ 設計

• 參見 docs/design.md 瞭解 MCP 設計、測量語義、工具設計理由及驗證策略。
• 參見 docs/testing.md 瞭解可重複的軟件、MCP 和硬件檢查。
• 參見 docs/adversarial-reviews.md 瞭解實現與 README 的評審日誌。

---

📖 參考

• JouleScope 下載與文檔：https://www.joulescope.com/pages/downloads
• JouleScope 驅動文檔：https://joulescope-driver.readthedocs.io/
• JouleScope 驅動源碼：https://github.com/jetperch/joulescope_driver
• JouleScope dut_power.py 示例：https://github.com/jetperch/pyjoulescope_examples/blob/main/bin/dut_power.py
• MCP Python SDK：https://github.com/modelcontextprotocol/python-sdk
• uvx 工具執行：https://docs.astral.sh/uv/concepts/tools/

上述示例所使用的客戶端配置參考：

客戶端	參考
Claude Code	Claude Code MCP docs，Claude Code support FAQ
Claude Desktop	MCP local server quickstart，Anthropic custom connectors note
Codex	OpenAI Docs MCP Codex quickstart，Codex MCP interface notes，以及使用 codex mcp add --help 和 codex mcp list 進行本地驗證
Cursor	Cursor MCP configuration docs，Cursor CLI MCP docs
VS Code / GitHub Copilot	Add and manage MCP servers in VS Code，VS Code MCP configuration reference
Windsurf	Windsurf MCP integration docs，Windsurf MCP client guide from Grafana
Cline	Cline CLI configuration，Cline MCP overview

已查閱的常見 MCP 配置示例：

• GitHub MCP Server 安裝指南：https://github.com/github/github-mcp-server/tree/main/docs/installation-guides
• Context7 MCP 安裝指南：https://context7.mintlify.dev/docs/installation
• MCP 本地服務器快速上手：https://modelcontextprotocol.io/docs/develop/connect-local-servers
• OpenAI Docs MCP 客戶端示例：https://developers.openai.com/learn/docs-mcp

---

📄 許可證

Apache License 2.0。參見 LICENSE。