⚡ JouleScope JS220 MCP サーバー
JouleScope JS220 高精度エネルギーアナライザー用の Model Context Protocol (MCP) サーバー
joulescope-mcp は、電流・電圧・電力・電荷・エネルギーを測定するためのエージェントフレンドリーなツールを提供し、さらに JouleScope ドライバの PubSub トピックツリーへの低レベルアクセスも可能にします。
主要ツールは measure_energy です。測定時間と蓄積インターバルを指定すると、合計電荷と合計エネルギー、およびインターバルごとのサンプルを返します。たとえば duration_s=15、interval_s=0.5 を指定すると、30 個のインターバルサンプルと total_charge_mAh などの合計値が返されます。
🚀 クイックスタート
GitHub から uvx で直接インストールします:
{
"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 クライアントに以下のように依頼します:
Measure JouleScope power for 15 seconds with 500 ms intervals. Include voltage.
期待される結果の形式(表示用にサンプル配列を短縮):
{
"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: GitHub から uvx で
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 クライアントは、次の 2 つの JSON 形式のいずれかを使用します:
mcpServers:Claude Desktop、Claude Code プロジェクト設定、Cursor、Windsurf、Cline、およびその他の多くのクライアント
servers:VS Code / GitHub Copilot MCP 設定
インストールコマンドを 1 つ選択してください:
| 現在の状況 |
クライアント設定で使用するコマンド |
| 通常の 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 には、常時起動するクライアントを 1 つだけ設定してください。多くのデスクトップクライアントは設定された MCP サーバーを自動起動するため、JS220 を複数の MCP サーバープロセス間で共有しないでください。
⏱️ タイムアウト設定
measure_energy はブロッキングなハードウェア測定です。15 秒の測定には少なくとも 15 秒、加えて JS220 の起動とクリーンアップ時間が必要です。タイムアウト設定を公開している MCP クライアントでは、ツールタイムアウトを 5 分に設定してください。
推奨値:
- ツール呼び出しタイムアウト:300 秒 / 300,000 ms
- サーバー起動タイムアウト:60 秒 / 60,000 ms
クライアントがタイムアウト設定をドキュメント化していない場合は、そのクライアントで許容できる範囲で同期測定を短く保つか、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
5 分の MCP ツール呼び出しと 60 秒のサーバー起動タイムアウトで Claude Code を起動:
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
プロジェクト設定:
{
"mcpServers": {
"joulescope-js220": {
"type": "stdio",
"command": "uvx",
"args": [
"--from",
"git+https://github.com/juanqui/joulescope-mcp",
"joulescope-mcp"
]
}
}
}
Cursor は Settings から MCP サーバーを追加することもサポートしています。設定変更後は、Cursor を再起動するか、MCP 設定パネルから MCP ツールを更新してください。Cursor は現在 mcp.json のポータブルなタイムアウトフィールドをドキュメント化していません。お使いの Cursor ビルドが Settings でリクエスト/ツールタイムアウトを公開している場合は、300 秒に設定してください。
VS Code / GitHub Copilot エージェントモード
ワークスペース設定:
ユーザー設定:
- コマンドパレットから
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 で Permission denied:JouleScope の udev ルールをインストールし、JS220 を再接続してください。
- 複数のクライアントがデバイスを奪い合う:JS220 に対しては、一度に 1 つの 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
🤖 エージェントワークフロー
ファームウェアやアプリケーションの電力最適化を行う際は、測定セットアップを安定させてください:
measure_energy でベースライン測定を実行します。
- ファームウェアまたはソフトウェアの変更を 1 つ適用します。
- 同じ
measure_energy の duration と interval で再度実行します。
total_charge_mAh、total_energy_mWh、average_current_mA、およびインターバルサンプルを比較します。
- 差分が通常のランごとのばらつきに近い場合は、測定を繰り返します。
リクエスト例:
{
"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 の周波数ベースのラッパーです。interval_s の代わりに frequency_hz を使用したい場合に使用します。
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 の電源を再投入します。
パラメータ:
off_ms:ホールドオフ時間(ミリ秒)
on_mode:デフォルトは auto、または manual
settle_ms:電源復元後のオプションの待機時間
record_jls
JouleScope ドライバの Record API を使用して、生のサンプルを JLS v2 ファイルに記録します。これは、JouleScope UI や JLS ツールで後から波形解析を行うのに役立ちます。既存のファイルは overwrite=true でない限り拒否されます。
read_gpi
JS220 の汎用入力状態を読み取り、32 ビット値とデコードされたピンを返します。
list_topics
保持されたドライバトピック、値、およびオプションのメタデータを一覧表示します。これは高度な JS220 機能のためのディスカバリーツールです。
query_topic
1 つのドライバトピックをクエリします。相対トピックは選択したデバイスの下で解決されるため、c/fw/version は u/js220/<serial>/c/fw/version になります。
publish_topic
ドライバトピックに値を発行します。これにより高度な JS220 機能が公開され、デバイスの動作が変わる可能性があります。利用可能な場合は型付きツールを優先してください。
📚 リソースとプロンプト
リソース:
joulescope://devices:JSON デバイスリスト
joulescope://driver:サーバーおよびドライバのバージョン情報
プロンプト:
power_optimization_session:測定駆動型の電力最適化ループ用テンプレート
🔒 安全性と制限
サーバーはツール呼び出しごとに短命な JouleScope ドライバ接続を開き、1 つのサーバープロセス内でデバイスアクセスを直列化します。ブロッキング測定にはガードレールがあります:
- 最小インターバル:0.5 ms
- 最大測定時間: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
🧩 設計
- MCP 設計、測定セマンティクス、ツールの根拠、検証戦略については docs/design.md を参照してください。
- 再現可能なソフトウェア、MCP、ハードウェアチェックについては docs/testing.md を参照してください。
- 実装と README のレビューログについては docs/adversarial-reviews.md を参照してください。
📖 リファレンス
上記の例で使用したクライアント設定リファレンス:
レビューした主要な MCP セットアップ例:
📄 ライセンス
Apache License 2.0。詳細は LICENSE を参照してください。