内容
# JouleScope JS220 MCP 服务器
`joulescope-mcp` 是适用于 JouleScope JS220 精密能源分析仪的模型上下文协议（MCP）服务器。它为测量电流、电压、功率、电荷和能量提供了便捷的工具，以及对 JouleScope 驱动程序 PubSub 主题树的底层访问。
主要工具是 `measure_energy`：提供持续时间和累积间隔，返回总电荷和能量，以及每个间隔的一个样本。例如，`duration_s=15` 和 `interval_s=0.5` 返回 30 个间隔样本，以及 `total_charge_mAh` 等总值。
## 快速入门
直接从 GitHub 使用 `uvx` 安装：
```json
{
"mcpServers": {
"joulescope-js220": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/juanqui/joulescope-mcp",
"joulescope-mcp"
]
}
}
}
```
如果您更喜欢 SSH，请使用相同的 Git 安装方式，并使用 SSH URL：
```json
{
"mcpServers": {
"joulescope-js220": {
"command": "uvx",
"args": [
"--from",
"git+ssh://git@github.com/juanqui/joulescope-mcp.git",
"joulescope-mcp"
]
}
}
}
```
然后询问您的 MCP 客户端：
```text
测量 JouleScope 电源 15 秒，间隔 500 毫秒。包括电压。
```
预期结果格式，紧凑的样本数组缩短以便于显示：
```json
{
"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 或更新版本
- JouleScope JS220 通过 USB 连接
- [`uv`](https://docs.astral.sh/uv/getting-started/installation/) 用于推荐的 `uvx` 安装路径
- 可以运行_stdio 服务器的 MCP 客户端
Python 包安装 `pyjoulescope_driver>=2.1.0` 和 `pyjls>=0.17`。在 Linux 上，配置 JouleScope udev 规则，然后再运行服务器。
`uvx` 是 `uv tool run` 的别名；它在隔离环境中运行 Python 命令行工具，无需永久安装。
## 安装选项
### 选项 1：使用 `uvx` 从 GitHub 安装
```bash
uvx --from git+https://github.com/juanqui/joulescope-mcp joulescope-mcp
```
MCP JSON:
```json
{
"mcpServers": {
"joulescope-js220": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/juanqui/joulescope-mcp",
"joulescope-mcp"
]
}
}
}
```
用于正常安装。
### 选项 2：使用 SSH 从 GitHub 安装
如果您更喜欢 SSH 或需要 GitHub SSH 身份验证，请使用此选项：
```bash
uvx --from git+ssh://git@github.com/juanqui/joulescope-mcp.git joulescope-mcp
```
### 选项 3：本地检出
在开发过程中或您想将 MCP 服务器固定到本地克隆时使用：
```bash
git clone git@github.com:juanqui/joulescope-mcp.git
cd joulescope-mcp
uv sync --extra dev
uv run joulescope-mcp
```
验证驱动程序是否能看到 JS220：
```bash
uv run python -m pyjoulescope_driver scan
uv run python -m pyjoulescope_driver statistics --frequency 2 --duration 1
```
本地检出 MCP JSON:
```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` |
| GitHub over SSH | `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 替换：
```json
{
"command": "uvx",
"args": [
"--from",
"git+https://github.com/juanqui/joulescope-mcp",
"joulescope-mcp"
]
}
```
本地检出替换：
```json
{
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/joulescope-mcp",
"run",
"joulescope-mcp"
]
}
```
为物理 JS220 配置一个始终在线的客户端。许多桌面客户端自动启动已配置的 MCP 服务器，JS220 不应在多个 MCP 服务器进程之间共享。
## 超时配置
`measure_energy` 是阻塞式硬件测量。15 秒的测量至少需要 15 秒，加上 JS220 启动和清理时间。为客户端配置 5 分钟的工具超时，当它们公开超时设置时。
推荐值：
- 工具调用超时：300 秒 / 300,000 毫秒
- 服务器启动超时：60 秒 / 60,000 毫秒
如果客户端未记录超时设置，请保持同步测量足够短，以适应该客户端，或使用具有可配置 MCP 工具超时的客户端。未来的异步测量 API 可以避免长时间的单个工具调用，但当前的 `measure_energy` 调用设计为同步。
### Claude Code
推荐的全局安装：
```bash
claude mcp add joulescope-js220 -- uvx --from git+https://github.com/juanqui/joulescope-mcp joulescope-mcp
claude mcp list
```
启动 Claude Code，MCP 工具调用超时为 5 分钟，服务器启动超时为 60 秒：
```bash
MCP_TIMEOUT=60000 MCP_TOOL_TIMEOUT=300000 claude
```
项目 `.mcp.json`:
```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`
```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
推荐的全局安装：
```bash
codex mcp add joulescope-js220 -- uvx --from git+https://github.com/juanqui/joulescope-mcp joulescope-mcp
codex mcp list
```
直接 `~/.codex/config.toml` 条目:
```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`
```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 代理模式
工作区配置：
- `.vscode/mcp.json`
用户配置：
- 运行 `MCP: Open User Configuration` 命令调出命令面板。
```json
{
"servers": {
"joulescope-js220": {
"type": "stdio",
"command": "uvx",
"args": [
"--from",
"git+https://github.com/juanqui/joulescope-mcp",
"joulescope-mcp"
]
}
}
}
```
命令行安装：
```bash
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`
```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 安装：
```bash
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 服务器面板，然后选择 **配置 MCP 服务器**
```json
{
"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：
```bash
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 工具。
快速本地健康检查：
```bash
uv run python scripts/hardware_smoke.py --duration-s 2 --interval-s 0.5
```
## 代理工作流
对于固件或应用程序电源优化，保持测量设置稳定：
1. 使用 `measure_energy` 运行基线测量。
2. 应用一个固件或软件更改。
3. 再次运行相同的 `measure_energy` 持续时间和间隔。
4. 比较 `total_charge_mAh`、`total_energy_mWh`、`average_current_mA` 和间隔样本。
5. 当差异接近正常运行间差异时重复测量。
示例请求：
```json
{
"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` 时的紧凑间隔电荷列表
- `sample_energy_mWh`：启用 `compact` 和 `include_voltage` 时的紧凑间隔能量列表
- `sample_voltage_avg_v`、`sample_voltage_min_v`、`sample_voltage_max_v`：启用 `compact` 和 `include_voltage` 时的紧凑间隔电压列表
- `samples`：禁用 `compact` 时的完整间隔统计信息
如果 `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`（以焦耳为单位）。服务器对这些积分求和，然后还将电荷转换为毫安时，将能量转换为毫瓦时。
### `capture_statistics`
基于频率的 `measure_energy` 包装器。在需要 `frequency_hz` 而不是 `interval_s` 时使用。
### `configure_frontend`
设置电流和电压范围模式以及可选的范围选择。正常测量时使用 `auto`。
### `target_power_status`
报告 JS220 目标/设备电源路径是否已连接。对于 JS220，设备电源由 `s/i/range/mode` 控制：`off` 断开 Current+ 和 Current- 的连接，而 `auto` 或 `manual` 连接目标路径以进行测量。
### `set_target_power`
通过 JS220 电流路径连接或断开设备电源。
参数：
- `power_on`：`true` 连接目标电源，`false` 断开连接
- `on_mode`：默认为 `auto`，或 `manual`
- `settle_ms`：可选的更改后等待时间
### `cycle_target_power`
通过设置目标电源关闭，等待，然后恢复目标电源来对设备进行电源循环。
参数：
- `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`
查询一个驱动程序主题。相对主题在选定的设备下解析，因此 `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` 故意中断设备。代理应仅在中断是请求测试的一部分时使用它。
## 开发
建立本地检出：
```bash
uv sync --extra dev
```
运行测试：
```bash
uv run python -m pytest
```
运行 linting：
```bash
uv run python -m ruff check .
```
构建软件包：
```bash
uv run python -m build
```
硬件冒烟测试：
```bash
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
```
可重复的硬件冒烟脚本：
```bash
uv run python scripts/hardware_smoke.py --duration-s 2 --interval-s 0.5
```
## 设计
参见 [docs/design.md](docs/design.md) 以获取 MCP 设计、测量语义、工具原理和验证策略。
参见 [docs/testing.md](docs/testing.md) 以获取可重复的软件、MCP 和硬件检查。
参见 [docs/adversarial-reviews.md](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 文档](https://code.claude.com/docs/en/mcp)，[Claude Code 支持常见问题](https://support.claude.com/en/articles/14554922-claude-code-user-faq) |
| Claude Desktop | [MCP 本地服务器快速入门](https://modelcontextprotocol.io/docs/develop/connect-local-servers)，[Anthropic 自定义连接器说明](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) |
| Codex | [OpenAI Docs MCP Codex 快速入门](https://developers.openai.com/learn/docs-mcp)，[Codex MCP 接口说明](https://github.com/openai/codex/blob/main/codex-rs/docs/codex_mcp_interface.md)，另外还包括使用 `codex mcp add --help` 和 `codex mcp list` 进行本地验证 |
| Cursor | [Cursor MCP 配置文档](https://docs.cursor.com/advanced/model-context-protocol)，[Cursor CLI MCP 文档](https://docs.cursor.com/cli/mcp) |
| VS Code / GitHub Copilot | [在 VS Code 中添加和管理 MCP 服务器](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)，[VS Code MCP 配置参考](https://code.visualstudio.com/docs/copilot/reference/mcp-configuration) |
| Windsurf | [Windsurf MCP 集成文档](https://docs.windsurf.com/windsurf/cascade/mcp)，[Windsurf MCP 客户端指南（来自 Grafana）](https://grafana.com/docs/grafana/latest/developer-resources/mcp/clients/windsurf/) |
| Cline | [Cline CLI 配置](https://docs.cline.bot/getting-started/config)，[Cline MCP 概述](https://docs.cline.bot/mcp/mcp-overview) |
流行的 MCP 设置示例：
- GitHub MCP 服务器安装指南：<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](LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器