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。