usb-rea

Overview Schema Source Related Servers Discussions Admin

scaffold_driver

Generates a standalone Python/pyusb driver from a captured USB protocol, creating set/query methods, handshake replay, and image sending for the device.

Instructions

Generate a standalone Python/pyusb driver source for the inferred protocol.

One set_() per command; when the device replies, also query_() methods that send the command/poll (or GET_REPORT), read the reply and return it decoded as a dict (readings named by 'seen' markers come back scaled and modes as words, e.g. {'rpm': 1180, 'temp': 34, 'mode': 'turbo', 'ok': True}). When the capture has a handshake, Device() replays it in open() before any command and checks the fixed reply bytes. A command the app only sent in one mode first calls the mode setter (Device(auto_state=False) raises StateError instead). A capture with an image stream to a screen adds send_image(image), which takes JPEG bytes (or, for a raw stream, a Pillow image or RGB565/RGB888 bytes, optionally a region at x, y), chunks it behind the captured header and returns the device's ack.

Read-only analysis that returns driver source as text (does not write a file or open the device). Same capture/markers/labels inputs as report. Prefer wireshark_dissector when the goal is to keep decoding traffic in Wireshark; use replay_packet only after the human approved a specific packet from this driver.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "capture": "<capture>"
    },
    "name": "scaffold_driver"
  }
}

Input Schema

Name	Required	Description
`device`	No	USB device address to analyse; default = bus address with the most host→device payloads
`labels`	No	Marker-free mode: ';'-separated labels in click order, or a text file path (one label per line)
`capture`	Yes	Path to a usbmon or USBPcap pcap/pcapng file
`markers`	No	Markers JSON path; default <capture>.actions.json. Ignored when labels is set

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv0.2.1Oct 17, 2026

addedInput schema / properties / capture / description

Added value: +"Path to a usbmon or USBPcap pcap/pcapng file"

addedInput schema / properties / device / description

Added value: +"USB device address to analyse; default = bus address with the most host→device payloads"

addedInput schema / properties / labels

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Marker-free mode: ';'-separated labels in click order, or a text file path (one label per line)",
+  "title": "Labels"
+}

addedInput schema / properties / markers / description

Added value: +"Markers JSON path; default <capture>.actions.json. Ignored when labels is set"

First observedv0.2.0Oct 16, 2026

TDQS

A4.6/5.0

Behavior5/5

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

No annotations are provided, so the description carries the full burden. It discloses the read-only nature, returns driver source as text, does not write a file or open the device, and describes the generated driver's behavior in detail (handshake replay, mode setter, send_image, etc.), giving rich context beyond a simple statement.

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 front-loaded with a clear purpose statement and well-organized into functional paragraphs. It is somewhat verbose in detailing the generated driver's features, but each sentence adds useful context, so it is efficient overall.

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?

Given the complexity of generating a driver and the presence of an output schema, the description covers purpose, usage alternatives, behavioral constraints, and output format sufficiently. It explains what the generated driver contains, which is valuable context for an agent.

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?

Schema description coverage is 100%, so all four parameters are fully documented in the schema. The description adds only a minor reference ('Same capture/markers/labels inputs as report'), adding negligible meaning beyond what the schema already provides, so baseline 3 is appropriate.

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?

States a specific verb 'Generate' and resource 'standalone Python/pyusb driver source for the inferred protocol'. It also distinguishes from siblings by naming wireshark_dissector and replay_packet with explicit conditions, so an agent can tell it apart without opening schemas.

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

Usage Guidelines5/5

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

Explicitly says 'Prefer wireshark_dissector when the goal is to keep decoding traffic in Wireshark' and 'use replay_packet only after the human approved a specific packet from this driver', giving clear alternatives and when-to-use conditions. It also clarifies the tool is read-only analysis that does not write a file or open the device.

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

Deploy Server