What can you do with this server?

The joulescope-mcp server enables AI agents to interact with a JouleScope JS220 precision energy analyzer over USB, providing tools for measurement, device configuration, power management, and low-level hardware access. Device Discovery & Inspection * list_devices: Enumerate connected JouleScope devices with serial numbers and firmware versions * device_info: Retrieve retained driver topic values and metadata for a specific device * read_gpi: Read general-purpose input pin state as a 32-bit value Measurements * measure_energy: Run timed measurements and return total charge (mAh), energy (mWh), average current/power, and per-interval sample arrays * capture_statistics: Frequency-based wrapper around measure_energy — specify frequency_hz instead of interval_s * record_jls: Save raw current, voltage, and power samples to a JLS v2 file for offline analysis Device Configuration & Power Control * configure_frontend: Set current/voltage range modes (auto, manual, off) and specific range selections * target_power_status: Report DUT power path state * set_target_power: Connect or disconnect power to the device under test * cycle_target_power: Power-cycle the DUT with configurable hold-off and settle times Low-Level Driver Access * list_topics: Browse the full JouleScope driver PubSub topic tree with values and metadata * query_topic: Read the value of any specific driver topic * publish_topic: Write a value to any driver topic for advanced control (destructive-capable; use with care) Typical Agent Workflows * Firmware power optimization loops: baseline → apply change → re-measure → compare results * Automated power cycling under agent control * Waveform capture to JLS files for visual analysis Safety guardrails enforce minimum intervals, maximum durations, and maximum interval counts on measurements.

How do I use joulescope-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@joulescope-mcp Measure energy for 15 seconds with 0.5 second intervals" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

joulescope-mcp

by juanqui

Overview Schema Related Servers Score Discussions

Python

Local

JouleScope JS220 MCP Server

joulescope-mcp is a Model Context Protocol (MCP) server for the JouleScope JS220 precision energy analyzer. It exposes agent-friendly tools for measuring current, voltage, power, charge, and energy, plus lower-level access to the JouleScope driver PubSub topic tree.

The primary tool is measure_energy: provide a duration and accumulation interval, and it returns total charge and energy plus one sample per interval. For example, duration_s=15 and interval_s=0.5 returns 30 interval samples along with totals such as total_charge_mAh.

Quick Start

Install directly from GitHub with uvx:

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

If you prefer SSH, use the same Git install shape with the SSH URL:

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

Then ask your MCP client:

Measure JouleScope power for 15 seconds with 500 ms intervals. Include voltage.

Expected result shape, with compact sample arrays shortened for display:

{
  "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]
}

Related MCP server: InstrMCP

Requirements

Python 3.11 or newer
JouleScope JS220 connected over USB
uv for the recommended uvx install path
An MCP client that can run stdio servers

The Python package installs pyjoulescope_driver>=2.1.0 and pyjls>=0.17. On Linux, configure JouleScope udev rules as documented by JouleScope before running the server.

uvx is an alias for uv tool run; it runs Python command-line tools in an isolated environment without a permanent install.

Install Options

Option 1: GitHub with `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"
      ]
    }
  }
}

Use this for normal installs.

Option 2: GitHub over SSH with `uvx`

Use this if you prefer SSH or need GitHub SSH authentication:

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

Option 3: Local Checkout

Use this while developing or when you want to pin the MCP server to a local clone:

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

Verify that the driver can see the JS220:

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

Local checkout MCP JSON:

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

Use an absolute path. Several MCP clients launch servers with a limited PATH; if uv or uvx is not found, replace "command": "uvx" or "command": "uv" with the full executable path from which uvx or which uv.

Client Configuration

Most MCP clients use one of two JSON shapes:

mcpServers: Claude Desktop, Claude Code project config, Cursor, Windsurf, Cline, and many other clients
servers: VS Code / GitHub Copilot MCP config

Choose one install command:

Current situation	Use this command in client configs
Normal GitHub install	`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`
Local development checkout	`uv --directory /absolute/path/to/joulescope-mcp run joulescope-mcp`

The snippets below show the normal GitHub install path.

GitHub replacement:

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

Local checkout replacement:

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

Configure only one always-on client for a physical JS220. Many desktop clients auto-start configured MCP servers, and the JS220 should not be shared between multiple MCP server processes.

Timeout Configuration

measure_energy is a blocking hardware measurement. A 15 second measurement takes at least 15 seconds, plus JS220 startup and cleanup time. Configure MCP clients for a 5 minute tool timeout when they expose a timeout setting.

Recommended values:

Tool call timeout: 300 seconds / 300,000 ms
Server startup timeout: 60 seconds / 60,000 ms

If a client does not document a timeout setting, keep synchronous measurements short enough for that client or use a client with configurable MCP tool timeouts. A future async measurement API can avoid long single tool calls, but the current measure_energy call is synchronous by design.

Claude Code

Recommended global install:

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

Launch Claude Code with 5 minute MCP tool calls and a 60 second server startup timeout:

MCP_TIMEOUT=60000 MCP_TOOL_TIMEOUT=300000 claude

Project .mcp.json:

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

Inside Claude Code, run /mcp to inspect server status. MCP_TIMEOUT and MCP_TOOL_TIMEOUT are Claude Code process environment variables, not per-server env values.

Claude Desktop

Edit:

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"
      ]
    }
  }
}

Restart Claude Desktop after editing the file. Claude Desktop does not document a portable per-server timeout field in claude_desktop_config.json; if your launch environment supports MCP timeout environment variables, set MCP_TOOL_TIMEOUT=300000 before starting Claude Desktop.

Codex

Recommended global install:

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

Direct ~/.codex/config.toml entry:

[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

The codex mcp add command creates the server entry. Edit ~/.codex/config.toml afterward to add startup_timeout_sec and tool_timeout_sec.

Cursor

Global config:

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

Project config:

.cursor/mcp.json

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

Cursor also supports adding MCP servers from Settings. After changing the config, restart Cursor or refresh MCP tools from the MCP settings panel. Cursor does not currently document a portable mcp.json timeout field; if your Cursor build exposes a request/tool timeout in Settings, set it to 300 seconds.

VS Code / GitHub Copilot Agent Mode

Workspace config:

.vscode/mcp.json

User config:

Run MCP: Open User Configuration from the Command Palette.

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

Command-line install:

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

VS Code's MCP configuration reference does not document a per-server tool timeout field. Do not add unsupported timeout keys to .vscode/mcp.json; use shorter synchronous measurements if your Copilot host times out long calls.

Windsurf

Edit:

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 has a total enabled-tool limit. If you use many MCP servers, disable tools you do not need. Windsurf's public MCP docs do not document a portable timeout field in mcp_config.json; if your Windsurf build exposes a request/tool timeout setting, set it to 300 seconds.

Cline

CLI install:

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

Manual config:

CLI default: ~/.cline/data/settings/cline_mcp_settings.json
VS Code extension: open the MCP Servers panel, then choose Configure MCP Servers

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

Run as HTTP

Most local MCP clients should use stdio. If you need streamable HTTP:

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

Troubleshooting

Client cannot find uvx: use the absolute path from which uvx.
No JouleScope found: run your configured server command directly in a terminal to check startup errors, then run uvx --from pyjoulescope-driver pyjoulescope_driver scan to verify the official driver can see the JS220.
Permission denied on Linux: install JouleScope udev rules and reconnect the JS220.
Multiple clients fight over the device: run only one MCP client/server process against a JS220 at a time.
GitHub install fails: verify git clone https://github.com/juanqui/joulescope-mcp works first.
Tools changed but client still shows old tools: restart the client or reset/reload MCP tools.

Quick local health check:

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

Agent Workflow

For firmware or application power optimization, keep the measurement setup stable:

Run a baseline measurement with measure_energy.
Apply one firmware or software change.
Run the same measure_energy duration and interval again.
Compare total_charge_mAh, total_energy_mWh, average_current_mA, and the interval samples.
Repeat the measurement when differences are close to normal run-to-run variance.

Example request:

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

The response includes:

total_charge_mAh: total charge over the measurement window
total_energy_mWh: total energy over the measurement window
average_current_mA: average current over the actual captured duration
average_power_mW: average power over the actual captured duration
actual_interval_s: average actual interval captured by the JS220
sample_charge_mAh: compact per-interval charge list when compact=true
sample_energy_mWh: compact per-interval energy list when compact=true
sample_voltage_avg_v, sample_voltage_min_v, sample_voltage_max_v: compact per-interval voltage lists when compact=true and include_voltage=true
samples: full per-interval statistics when compact=false

If duration_s is not an exact multiple of interval_s, the server rounds up to the next full interval and reports both requested_duration_s and actual_duration_s.

Tools

`list_devices`

Lists connected JouleScope devices. For JS220 devices, it attempts to include hardware, firmware, and FPGA versions.

`device_info`

Returns retained driver topic values for a selected device. Set include_metadata=true to include topic metadata returned by the driver.

`measure_energy`

Measures charge and energy using JS220 sensor-side statistics.

Parameters:

duration_s: requested measurement duration in seconds
interval_s: accumulation interval in seconds
device_path: optional explicit device path, such as u/js220/005920
configure_auto_range: defaults to true; configures current and voltage range modes to auto
compact: returns compact charge and energy arrays and omits full samples
include_voltage: when used with compact, also returns per-interval voltage arrays

Implementation detail: the JS220 publishes per-interval current.integral in coulombs and power.integral in joules. The server sums those integrals, then also converts charge to mAh and energy to mWh.

`capture_statistics`

Frequency-based wrapper around measure_energy. Use when you want frequency_hz instead of interval_s.

`configure_frontend`

Sets current and voltage range modes and optional range selections. Use auto for normal measurements.

`target_power_status`

Reports whether the JS220 target/DUT power path is connected. For JS220, DUT power is controlled through s/i/range/mode: off disconnects Current+ from Current-, while auto or manual connects the target path for measurement.

`set_target_power`

Connects or disconnects power to the DUT through the JS220 current path.

Parameters:

power_on: true to connect target power, false to disconnect it
on_mode: auto by default, or manual
settle_ms: optional wait after changing state

`cycle_target_power`

Power-cycles the DUT by setting target power off, waiting, then restoring target power.

Parameters:

off_ms: hold-off time in milliseconds
on_mode: auto by default, or manual
settle_ms: optional wait after restoring power

`record_jls`

Records raw samples to a JLS v2 file using the JouleScope driver's Record API. This is useful for later waveform analysis in the JouleScope UI or JLS tooling. Existing files are rejected unless overwrite=true.

`read_gpi`

Reads JS220 general-purpose input state and returns a 32-bit value plus decoded pins.

`list_topics`

Lists retained driver topics, values, and optional metadata. This is the discovery tool for advanced JS220 capabilities.

`query_topic`

Queries one driver topic. Relative topics are resolved under the selected device, so c/fw/version becomes u/js220/<serial>/c/fw/version.

`publish_topic`

Publishes a value to a driver topic. This exposes advanced JS220 features and can change device behavior. Prefer typed tools when available.

Resources and Prompts

Resources:

joulescope://devices: JSON device list
joulescope://driver: server and driver version information

Prompt:

power_optimization_session: template for measurement-driven power optimization loops

Safety and Limits

The server opens a short-lived JouleScope driver connection per tool call and serializes device access inside one server process. Blocking measurements have guardrails:

Minimum interval: 0.5 ms
Maximum duration: 3600 seconds
Maximum returned intervals: 10,000
Statistics collection times out if the JS220 does not publish the expected samples

set_target_power, cycle_target_power, record_jls, and publish_topic are marked as write/destructive-capable MCP tools. cycle_target_power intentionally interrupts the DUT. Agents should use it only when an interruption is part of the requested test.

Development

Set up a local checkout:

uv sync --extra dev

Run tests:

uv run python -m pytest

Run linting:

uv run python -m ruff check .

Build the package:

uv run python -m build

Hardware smoke test:

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

Repeatable hardware smoke script:

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

Design

See docs/design.md for the MCP design, measurement semantics, tool rationale, and verification strategy. See docs/testing.md for repeatable software, MCP, and hardware checks. See docs/adversarial-reviews.md for the implementation and README review logs.

References

JouleScope downloads and documentation: https://www.joulescope.com/pages/downloads
JouleScope driver documentation: https://joulescope-driver.readthedocs.io/
JouleScope driver source: https://github.com/jetperch/joulescope_driver
JouleScope dut_power.py example: https://github.com/jetperch/pyjoulescope_examples/blob/main/bin/dut_power.py
MCP Python SDK: https://github.com/modelcontextprotocol/python-sdk
uvx tool execution: https://docs.astral.sh/uv/concepts/tools/

Client configuration references used for the examples above:

Client	References
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, plus local verification with `codex mcp add --help` and `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

Popular MCP setup examples reviewed:

GitHub MCP Server installation guides: https://github.com/github/github-mcp-server/tree/main/docs/installation-guides
Context7 MCP installation guide: https://context7.mintlify.dev/docs/installation
MCP local server quickstart: https://modelcontextprotocol.io/docs/develop/connect-local-servers
OpenAI Docs MCP client examples: https://developers.openai.com/learn/docs-mcp

License

Apache License 2.0. See LICENSE.

Available Tools

10 tools

capture_statisticsCapture statisticsB

Read-only

Capture JS220 statistics at frequency_hz for duration_s. This is a frequency-based wrapper around measure_energy.

ParametersJSON Schema

Name	Required	Description	Default
`duration_s`	No
`frequency_hz`	No
`device_path`	No
`configure_auto_range`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds context as a wrapper, but doesn't reveal additional behavioral details like what the output contains or whether it affects device state.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences, front-loaded with the primary action, and omits any redundant or irrelevant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values are covered. However, the description fails to document two of the four parameters and does not clarify what 'JS220 statistics' entails, leaving some gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must explain all parameters. It explains frequency_hz and duration_s (sampling rate and time), but provides no information about device_path or configure_auto_range, leaving them ambiguous.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool captures JS220 statistics with parameters duration_s and frequency_hz, and identifies itself as a wrapper around measure_energy, which differentiates it from that sibling. However, it doesn't explicitly distinguish it from other siblings like record_jls.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when frequency-based statistics are needed, referencing measure_energy as an alternative, but it lacks explicit guidelines on when not to use this tool or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

configure_frontendConfigure JS220 frontendB

Idempotent

Configure JS220 current and voltage range modes. Use auto for normal agent measurements.

ParametersJSON Schema

Name	Required	Default
`device_path`	No
`current_range_mode`	No	auto
`voltage_range_mode`	No	auto
`current_range`	No
`voltage_range`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate not read-only, not destructive, and idempotent. The description adds that it configures modes and suggests auto for normal use, but does not detail side effects, prerequisites, or behavior of other parameters.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence without fluff. However, it could include more information about the undocumented parameters without violating conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 5 parameters, 0% schema coverage, and a modest description, the tool is incomplete. The description only covers two parameters, and the presence of an output schema does not absolve the need to explain inputs.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explains current_range_mode and voltage_range_mode but ignores device_path, current_range, and voltage_range, leaving their purpose and acceptable values undefined.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool configures JS220 current and voltage range modes, using the verb 'configure' and specifying the resource. It uniquely identifies its purpose among siblings, as no other sibling tool performs configuration.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description advises 'Use auto for normal agent measurements,' providing context for a common use case, but lacks when-not to use or guidance for manual/off modes. No comparison to alternatives is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

device_infoGet device infoA

Read-only

Return retained device topics and optional metadata for one JouleScope.

ParametersJSON Schema

Name	Required	Description	Default
`device_path`	No
`include_metadata`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false. Description consistently says 'Return', confirming read-only operation. However, no additional behavioral details (e.g., behavior on missing device, response size) are added beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, concise and front-loaded. Every word is meaningful. Could add slight context without excessive length, but current length is efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists, so return values are covered. However, tool complexity is low, but gaps remain: behavior when device_path is null (uses default?), what metadata entails, and relation to sibling tools. Adequate but not fully complete for a seamless agent usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% for both parameters. Description only mentions 'retained device topics' (linked to device_path) and 'optional metadata' (linked to include_metadata). It does not explain format of device_path, default behavior when null, or what metadata includes. Insufficient compensation for missing schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it returns retained device topics and optional metadata for a single device (JouleScope). Verb 'Return' is specific, and 'for one JouleScope' distinguishes from sibling tools like list_devices (plural) or list_topics (general).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description implies usage when needing a specific device's topics, but does not explicitly state when not to use it or mention alternative tools like list_devices or list_topics. Lacks usage exclusions or selection criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_devicesList JouleScope devicesA

Read-only

List connected JouleScope devices, including JS220 serial and firmware details when available.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only and non-destructive behavior. The description adds that it returns serial and firmware details when available, providing useful behavioral context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, 15 words, front-loaded with the action. No redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no parameters and an output schema present, the description fully specifies the tool's behavior. It covers what is listed and what details are included.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters (baseline 4). The description does not need to add parameter info since the schema is empty and coverage is 100%.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('List connected JouleScope devices') and includes specific details about available information (JS220 serial and firmware). It effectively distinguishes from siblings like device_info which targets individual devices.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. However, the simple nature of listing all devices makes the usage implied; agents can infer it for broad device enumeration.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_topicsList topicsA

Read-only

List retained JouleScope driver topics with current values and optional metadata.

ParametersJSON Schema

Name	Required	Description	Default
`device_path`	No
`include_metadata`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.6/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true and destructiveHint=false, so behavior is safe. Description adds that it lists 'retained' topics with current values and optional metadata, but does not disclose any further behavioral traits (e.g., pagination, error conditions, or effect of parameters). Adequate but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence of 10 words, front-loaded with verb and noun, no filler. Every word adds value. Perfectly concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists to explain return values, so description need not cover that. However, with 2 optional parameters and no explanation of their roles, the description is not fully complete. For a simple list tool it's adequate but misses opportunity to clarify device_path filtering.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so description must compensate. It only hints at include_metadata via 'optional metadata', but device_path is completely unexplained. With two optional parameters, this leaves significant ambiguity about how to filter or scope the list.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'List' and the resource 'retained JouleScope driver topics with current values and optional metadata', specifying scope and content. It distinguishes from sibling tools like query_topic (likely single topic) and publish_topic (write operation).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives like query_topic or device_info. The description implies listing all topics, but does not state when to avoid it or prerequisites. Minimal usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

measure_energyMeasure energy over timeA

Read-only

Measure JS220 charge and energy over duration_s using interval_s accumulation. Returns total charge/energy plus one sample per interval, including mAh and mWh.

ParametersJSON Schema

Name	Required	Description	Default
`duration_s`	Yes
`interval_s`	Yes
`device_path`	No
`configure_auto_range`	No
`compact`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds behavioral context beyond annotations by detailing the accumulation over intervals and the return format (total plus samples with mAh/mWh), while annotations already indicate read-only and non-destructive behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence that efficiently conveys the tool's purpose and output, with no extraneous words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is fairly complete given the presence of an output schema and annotations; it covers the core functionality and return values, though it leaves the optional parameters unexplained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description explains the role of duration_s and interval_s but does not clarify the optional parameters device_path, configure_auto_range, or compact. Given 0% schema coverage, this partially compensates for the missing parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool measures JS220 charge and energy over a specified duration using interval accumulation, which is specific and distinct from sibling tools like capture_statistics or record_jls.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide any guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusions, leaving the agent to infer usage from the tool name and context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

publish_topicPublish topicB

Destructive

Publish a value to a JouleScope driver topic. This exposes advanced JS220 capabilities; only use when you know the topic semantics.

ParametersJSON Schema

Name	Required	Description	Default
`topic`	Yes
`value`	Yes
`device_path`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate destructiveHint=true; the description adds 'advanced JS220 capabilities' which implies caution, but adds little beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the action, no unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite an output schema, the description lacks details on parameter usage, acceptable values, or behavior, leaving the agent underinformed for a potentially destructive operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description provides no information about the parameters (topic, value, device_path) beyond their names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action 'Publish a value' and the resource 'JouleScope driver topic', distinguishing it from siblings like list_topics and query_topic.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description advises to use only when topic semantics are known, but does not explicitly state when not to use or name alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

query_topicQuery topicA

Read-only

Query a JouleScope driver topic. Provide a relative topic such as c/fw/version or an absolute device topic.

ParametersJSON Schema

Name	Required	Description	Default
`topic`	Yes
`device_path`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and destructiveHint. Description adds no extra behavioral details beyond 'query', which is consistent. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences, front-loaded with action, no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Sufficient for a simple read query with good annotations and output schema. Could enhance by explaining when to provide device_path, but not essential.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Description adds meaning for 'topic' (relative/absolute device topic) beyond schema, but does not describe 'device_path' parameter. Schema coverage is 0%, so description partially compensates but is incomplete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it queries a JouleScope driver topic, with examples of relative and absolute topics. Distinguishes from sibling tools like list_topics (lists) and publish_topic (writes).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies usage via topic type examples but lacks explicit guidance on when to use this tool versus siblings or when to choose relative vs absolute. No when-not criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_gpiRead GPIB

Read-only

Read JS220 general-purpose input pin state as a 32-bit value and decoded pins.

ParametersJSON Schema

Name	Required	Description	Default
`device_path`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the description's claim of reading is consistent. No additional behavioral context (e.g., permissions, rate limits, side effects) is provided beyond what annotations convey. The idempotentHint=false is not explained.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no wasted words. However, it could be more structured to front-load the most critical information, but given its brevity, it is efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While an output schema exists (so return values need not be detailed), the description lacks parameter explanations and usage context. For a tool with one undocumented optional parameter, this is incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter, device_path, has no description in the schema (0% coverage). The description does not clarify its purpose, format, or effect, leaving the agent without guidance on how to use it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the action (Read), the resource (JS220 general-purpose input pin state), and the output (32-bit value and decoded pins). It distinguishes from sibling tools which cover statistics, configuration, measurements, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives like measure_energy or device_info. No exclusions or prerequisites mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

record_jlsRecord JLSB

Destructive

Record raw JS220 samples to a JLS v2 file for later waveform analysis.

ParametersJSON Schema

Name	Required	Default
`output_path`	Yes
`duration_s`	Yes
`device_path`	No
`frequency_hz`	No
`signals`	No	current,voltage,power
`note`	No
`overwrite`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description adds context beyond annotations by specifying the data type (raw JS220 samples) and file format (JLS v2). However, it does not disclose behavioral traits like file creation side effects, potential data loss, or permission requirements. Annotations already indicate destructiveHint=true, so description partially complements but lacks depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded with the action and purpose. No redundant or irrelevant information. Every word adds value, achieving high efficiency.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 7 parameters, no schema descriptions, and an output schema (not described), the description is insufficient for an agent to correctly invoke the tool. It lacks detail on parameter roles, defaults, and expected behavior, making the tool cryptic without additional context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, yet the description provides no information about any of the 7 parameters (e.g., output_path, duration_s, signals, overwrite). The agent cannot infer parameter meaning or usage from the description alone, leaving the schema's bare types as the only clue.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the action (record), the resource (raw JS220 samples), the output format (JLS v2 file), and the purpose (for later waveform analysis). It effectively distinguishes from sibling tools which deal with statistics, configuration, device info, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. No mention of prerequisites, context, or exclusions. The description merely states what the tool does, not when or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0

Disambiguation5/5

Each tool has a distinct purpose: listing, configuring, measuring, reading GPI, recording, and low-level topic operations. The two measurement tools are clearly differentiated by their descriptions.

Naming Consistency4/5

All tools use snake_case, with most following a verb_noun pattern (e.g., list_devices, measure_energy). The exception is 'device_info', which is noun_noun, but the meaning is clear.

Tool Count5/5

10 tools cover the essential operations for a JouleScope device: discovery, configuration, measurement, data recording, and low-level access. No unnecessary tools.

Completeness5/5

The tool set provides a full lifecycle: listing devices, getting info, measuring energy (two methods), configuring frontend, reading GPI, recording raw data, and arbitrary topic query/publish. No obvious gaps.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Backtest360 A
com.backtest360
MCP server exposing the Backtest360 engine API as tools for AI agents.
Finance Research & Data
202
Energy AT IT
com.energyatit.app
Protocol-native energy infrastructure orchestration for AI data centers. Provides 46 MCP tools across 8 grid protocols (IEC-61850, DNP3, Modbus, OCPP, OpenADR, IEEE 2030.5, IEC 60870-5-104, ICCP) with 5 core API primitives: connect, dispatch, settle, comply, and intel. Enables AI agents to programmatically interact with substations, grid interfaces, and energy assets for real-time workload-grid coordination.
Cloud Platforms Agent Orchestration Virtualization
2
strata
ai.klavis
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Agent Orchestration Autonomous Agents Developer Tools
25,748
jumpcloud-genaiOAuth
com.jumpcloud
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
Cloud Platforms Security Developer Tools
2

Related MCP Servers

Enapter MCP Serverofficial
Energy Monitoring Cloud Platforms
Enapter
A
license
Not graded
quality
B
maintenance
MCP server providing tools for AI-agents to interact with Enapter EMS.
Updated 2 months ago (2026-07-16 18:02 UTC)
Apache 2.0
InstrMCP
Code Execution Research & Data
caidish
A
license
Not graded
quality
B
maintenance
MCP server for quantum device physics laboratory instrumentation control, enabling LLMs to interact with physics instruments and measurement systems through QCodes and JupyterLab.
Updated 24 days ago (2026-08-11 07:13 UTC)
34
MIT
scpi-mcp
Embedded system Research & Data
armchairdeity
A
license
A
quality
A
maintenance
An MCP server that enables AI agents to operate an oscilloscope through high-level tools like signal capture and measurement, abstracting vendor-specific SCPI commands.
Updated 2 months ago (2026-07-16 23:01 UTC)
18
2
MIT
ppk2-mcp
Embedded system Developer Tools
Ultrahuman-tech
A
license
Not graded
quality
D
maintenance
MCP server for Nordic Semiconductor's Power Profiler Kit II (PPK2), enabling current measurement and device control via 12 tools from Claude.
Updated 7 months ago (2026-02-19 09:58 UTC)
1
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/juanqui/joulescope-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

JouleScope JS220 MCP Server

Quick Start

Requirements

Install Options

Option 1: GitHub with uvx

Option 2: GitHub over SSH with uvx

Option 3: Local Checkout

Client Configuration

Timeout Configuration

Claude Code

Claude Desktop

Codex

Cursor

VS Code / GitHub Copilot Agent Mode

Windsurf

Cline

Run as HTTP

Troubleshooting

Agent Workflow

Tools

list_devices

device_info

measure_energy

capture_statistics

configure_frontend

target_power_status

set_target_power

cycle_target_power

record_jls

read_gpi

list_topics

query_topic

publish_topic

Resources and Prompts

Safety and Limits

Development

Design

References

License

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Enapter MCP Serverofficial

Latest Blog Posts

MCP directory API

Option 1: GitHub with `uvx`

Option 2: GitHub over SSH with `uvx`

`list_devices`

`device_info`

`measure_energy`

`capture_statistics`

`configure_frontend`

`target_power_status`

`set_target_power`

`cycle_target_power`

`record_jls`

`read_gpi`

`list_topics`

`query_topic`

`publish_topic`