multitool-mcp 0.1.0__tar.gz

multitool_mcp-0.1.0/LICENSE

@@ -0,0 +1,14 @@
+WE Multitool DUT MCP
+Copyright (C) 2026 Wise Electronics
+
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free Software
+Foundation, either version 3 of the License, or (at your option) any later
+version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with
+this program. If not, see <https://www.gnu.org/licenses/gpl-3.0.html>.

multitool_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: multitool-mcp
+Version: 0.1.0
+Summary: MCP server for debugging devices under test through WE Multitool
+Author: Wise Electronics
+License-Expression: GPL-3.0-or-later
+Project-URL: Homepage, https://github.com/we-devices/multitool-mcp
+Project-URL: Repository, https://github.com/we-devices/multitool-mcp.git
+Project-URL: Issues, https://github.com/we-devices/multitool-mcp/issues
+Keywords: mcp,embedded,hardware,debugging,we-multitool
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# WE Multitool DUT MCP
+
+`multitool-mcp` is a dependency-free [Model Context Protocol](https://modelcontextprotocol.io/) server for inspecting and debugging a device under test (DUT) through a Wise Electronics WE Multitool.
+
+It runs over standard input/output and bridges the Multitool's JSON-over-WebSocket API. It exposes bounded MCP tools for GPIO, I2C, SPI, UART, PWM, and GPIO ownership.
+
+## Requirements
+
+- Python 3.11 or later
+- A WE Multitool reachable over WebSocket
+
+## Install
+
+Install from PyPI once published:
+
+```shell
+python -m pip install multitool-mcp
+```
+
+For development from a clone:
+
+```shell
+python -m pip install -e .
+```
+
+## Configure an MCP client
+
+Run the installed command:
+
+```toml
+[mcp_servers.we_multitool_dut]
+command = "multitool-mcp"
+env_vars = ["WE_MULTITOOL_URL", "WE_MULTITOOL_TIMEOUT_SECONDS"]
+startup_timeout_sec = 10
+tool_timeout_sec = 35
+default_tools_approval_mode = "prompt"
+```
+
+By default, the server connects to `ws://we-multitool.local/ws`. Set these environment variables before starting the MCP client to change that:
+
+```shell
+WE_MULTITOOL_URL=ws://10.0.0.1/ws
+WE_MULTITOOL_TIMEOUT_SECONDS=8
+```
+
+On PowerShell:
+
+```powershell
+$env:WE_MULTITOOL_URL = "ws://10.0.0.1/ws"
+$env:WE_MULTITOOL_TIMEOUT_SECONDS = "8"
+```
+
+## Safety and firmware behavior
+
+Read `pins_get` before configuring pins, and verify wiring, voltage, bus role, and DUT limits before driving signals.
+
+- Commands are serialized because firmware responses do not carry request IDs.
+- UART data received while another command awaits a response is buffered.
+- The `gpio_set` firmware command has no acknowledgement; `gpio_write` reports it as dispatched but unverified.
+- The firmware tracks one active WebSocket response socket. Do not use the browser UI and MCP bridge concurrently.
+
+## Development
+
+```shell
+python -m pip install -e ".[test]"
+python -m pytest
+```
+
+The runtime has no third-party dependencies. The optional `test` extra installs pytest.
+
+## License
+
+Licensed under the GNU General Public License, version 3 or later
+(GPL-3.0-or-later). See [LICENSE](LICENSE).

multitool_mcp-0.1.0/README.md

@@ -0,0 +1,74 @@
+# WE Multitool DUT MCP
+
+`multitool-mcp` is a dependency-free [Model Context Protocol](https://modelcontextprotocol.io/) server for inspecting and debugging a device under test (DUT) through a Wise Electronics WE Multitool.
+
+It runs over standard input/output and bridges the Multitool's JSON-over-WebSocket API. It exposes bounded MCP tools for GPIO, I2C, SPI, UART, PWM, and GPIO ownership.
+
+## Requirements
+
+- Python 3.11 or later
+- A WE Multitool reachable over WebSocket
+
+## Install
+
+Install from PyPI once published:
+
+```shell
+python -m pip install multitool-mcp
+```
+
+For development from a clone:
+
+```shell
+python -m pip install -e .
+```
+
+## Configure an MCP client
+
+Run the installed command:
+
+```toml
+[mcp_servers.we_multitool_dut]
+command = "multitool-mcp"
+env_vars = ["WE_MULTITOOL_URL", "WE_MULTITOOL_TIMEOUT_SECONDS"]
+startup_timeout_sec = 10
+tool_timeout_sec = 35
+default_tools_approval_mode = "prompt"
+```
+
+By default, the server connects to `ws://we-multitool.local/ws`. Set these environment variables before starting the MCP client to change that:
+
+```shell
+WE_MULTITOOL_URL=ws://10.0.0.1/ws
+WE_MULTITOOL_TIMEOUT_SECONDS=8
+```
+
+On PowerShell:
+
+```powershell
+$env:WE_MULTITOOL_URL = "ws://10.0.0.1/ws"
+$env:WE_MULTITOOL_TIMEOUT_SECONDS = "8"
+```
+
+## Safety and firmware behavior
+
+Read `pins_get` before configuring pins, and verify wiring, voltage, bus role, and DUT limits before driving signals.
+
+- Commands are serialized because firmware responses do not carry request IDs.
+- UART data received while another command awaits a response is buffered.
+- The `gpio_set` firmware command has no acknowledgement; `gpio_write` reports it as dispatched but unverified.
+- The firmware tracks one active WebSocket response socket. Do not use the browser UI and MCP bridge concurrently.
+
+## Development
+
+```shell
+python -m pip install -e ".[test]"
+python -m pytest
+```
+
+The runtime has no third-party dependencies. The optional `test` extra installs pytest.
+
+## License
+
+Licensed under the GNU General Public License, version 3 or later
+(GPL-3.0-or-later). See [LICENSE](LICENSE).

multitool_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "multitool-mcp"
+version = "0.1.0"
+description = "MCP server for debugging devices under test through WE Multitool"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "GPL-3.0-or-later"
+license-files = ["LICENSE"]
+authors = [{ name = "Wise Electronics" }]
+keywords = ["mcp", "embedded", "hardware", "debugging", "we-multitool"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Software Development :: Debuggers",
+]
+dependencies = []
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[project.scripts]
+multitool-mcp = "dut_mcp.server:main"
+
+[project.urls]
+Homepage = "https://github.com/we-devices/multitool-mcp"
+Repository = "https://github.com/we-devices/multitool-mcp.git"
+Issues = "https://github.com/we-devices/multitool-mcp/issues"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-ra"

multitool_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

multitool_mcp-0.1.0/src/dut_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""MCP bridge for the WE Multitool device-under-test interfaces."""
+
+from .device import DeviceClient, DeviceError
+
+__all__ = ["DeviceClient", "DeviceError"]

multitool_mcp-0.1.0/src/dut_mcp/__main__.py

@@ -0,0 +1,5 @@
+from .server import main
+
+
+if __name__ == "__main__":
+    main()

multitool_mcp-0.1.0/src/dut_mcp/device.py

@@ -0,0 +1,114 @@
+"""Client for the JSON-over-WebSocket protocol implemented by WE Multitool."""
+
+from __future__ import annotations
+
+import base64
+import json
+import socket
+import threading
+import time
+from collections import deque
+from collections.abc import Callable
+from typing import Any
+
+from .websocket import WebSocket, WebSocketError
+
+
+class DeviceError(RuntimeError):
+    pass
+
+
+Message = dict[str, Any]
+Matcher = Callable[[Message], bool]
+
+
+class DeviceClient:
+    """Serializes commands because the firmware protocol has no request IDs."""
+
+    def __init__(self, url: str, timeout: float = 5.0, transport: WebSocket | None = None) -> None:
+        self.url, self.timeout = url, timeout
+        self._ws = transport or WebSocket(url, timeout)
+        self._lock = threading.RLock()
+        self._pending: deque[Message] = deque()
+
+    @property
+    def connected(self) -> bool:
+        return self._ws.connected
+
+    def close(self) -> None:
+        with self._lock:
+            self._ws.close()
+            self._pending.clear()
+
+    def request(self, command: Message, matcher: Matcher, timeout: float | None = None) -> Message:
+        with self._lock:
+            try:
+                self._ws.send_text(json.dumps(command, separators=(",", ":")))
+                deadline = time.monotonic() + (self.timeout if timeout is None else timeout)
+                while True:
+                    remaining = deadline - time.monotonic()
+                    if remaining <= 0:
+                        raise DeviceError(f"Timed out waiting for response to {command['type']}")
+                    message = self._receive(remaining)
+                    if matcher(message):
+                        return message
+                    self._pending.append(message)
+            except (OSError, socket.timeout, WebSocketError) as exc:
+                self._ws.close()
+                raise DeviceError(f"Device communication failed: {exc}") from exc
+
+    def send(self, command: Message) -> None:
+        with self._lock:
+            try:
+                self._ws.send_text(json.dumps(command, separators=(",", ":")))
+            except (OSError, socket.timeout, WebSocketError) as exc:
+                self._ws.close()
+                raise DeviceError(f"Device communication failed: {exc}") from exc
+
+    def read_uart(self, timeout: float, max_bytes: int) -> bytes:
+        with self._lock:
+            output, deadline = bytearray(), time.monotonic() + timeout
+            while len(output) < max_bytes:
+                message = self._take_pending(self._is_uart_data)
+                if message is None:
+                    remaining = deadline - time.monotonic()
+                    if remaining <= 0:
+                        break
+                    try:
+                        if not self._ws.connected:
+                            self._ws.connect()
+                        message = self._receive(remaining)
+                    except socket.timeout:
+                        break
+                    except (OSError, WebSocketError) as exc:
+                        self._ws.close()
+                        raise DeviceError(f"Device communication failed: {exc}") from exc
+                    if not self._is_uart_data(message):
+                        self._pending.append(message)
+                        continue
+                try:
+                    output.extend(base64.b64decode(message["data"], validate=True))
+                except (ValueError, TypeError) as exc:
+                    raise DeviceError("Device returned invalid base64 UART data") from exc
+            return bytes(output[:max_bytes])
+
+    def _receive(self, timeout: float) -> Message:
+        raw = self._ws.receive_text(timeout)
+        try:
+            message = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise DeviceError(f"Device returned invalid JSON: {raw[:200]}") from exc
+        if not isinstance(message, dict):
+            raise DeviceError("Device response is not a JSON object")
+        return message
+
+    def _take_pending(self, matcher: Matcher) -> Message | None:
+        for index, message in enumerate(self._pending):
+            if matcher(message):
+                del self._pending[index]
+                return message
+        return None
+
+    @staticmethod
+    def _is_uart_data(message: Message) -> bool:
+        return message.get("type") == "uart_response" and "error" not in message

multitool_mcp-0.1.0/src/dut_mcp/server.py

@@ -0,0 +1,269 @@
+"""Dependency-free STDIO MCP server for debugging DUTs through WE Multitool."""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import sys
+import traceback
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from .device import DeviceClient, DeviceError
+
+JsonObject = dict[str, Any]
+
+
+def _object_schema(properties: JsonObject, required: list[str] | None = None) -> JsonObject:
+    schema: JsonObject = {"type": "object", "properties": properties, "additionalProperties": False}
+    if required:
+        schema["required"] = required
+    return schema
+
+
+PIN = {"type": "integer", "minimum": 0, "maximum": 63, "description": "ESP32 GPIO number."}
+OPTIONAL_PIN = {"type": "integer", "minimum": -1, "maximum": 63, "description": "ESP32 GPIO number, or -1 when unused."}
+BYTE = {"type": "integer", "minimum": 0, "maximum": 255}
+BYTES = {"type": "array", "items": BYTE, "maxItems": 1024}
+
+
+@dataclass(frozen=True)
+class Tool:
+    name: str
+    description: str
+    schema: JsonObject
+    handler: Callable[[JsonObject], Any]
+    read_only: bool = False
+    idempotent: bool = False
+
+    def definition(self) -> JsonObject:
+        annotations: JsonObject = {"readOnlyHint": self.read_only, "openWorldHint": False}
+        if not self.read_only:
+            annotations.update({"destructiveHint": False, "idempotentHint": self.idempotent})
+        return {"name": self.name, "description": self.description, "inputSchema": self.schema, "annotations": annotations}
+
+
+class DutTools:
+    def __init__(self, client: DeviceClient) -> None:
+        self.client = client
+        self.tools = {tool.name: tool for tool in self._build_tools()}
+
+    @staticmethod
+    def _type(name: str) -> Callable[[JsonObject], bool]:
+        return lambda message: message.get("type") == name
+
+    @staticmethod
+    def _check_error(message: JsonObject) -> JsonObject:
+        if message.get("error") is True or message.get("result_type") == 0:
+            raise DeviceError(str(message.get("data", "Device command failed")))
+        return message
+
+    def _command(self, command: JsonObject, response_type: str) -> JsonObject:
+        return self._check_error(self.client.request(command, self._type(response_type)))
+
+    def _build_tools(self) -> list[Tool]:
+        return [
+            Tool("device_status", "Connect to WE Multitool and return its URL and GPIO ownership map.", _object_schema({}), self.device_status, True),
+            Tool("pins_get", "Read the current GPIO ownership map before assigning pins.", _object_schema({}), self.pins_get, True),
+            Tool("gpio_configure", "Configure a free GPIO as input or output.", _object_schema({"pin": PIN, "direction": {"type": "string", "enum": ["input", "output"]}}, ["pin", "direction"]), self.gpio_configure, False, True),
+            Tool("gpio_read", "Read a GPIO that is configured as input.", _object_schema({"pin": PIN}, ["pin"]), self.gpio_read, True),
+            Tool("gpio_write", "Drive a GPIO configured as output. Firmware dispatches this command without an acknowledgement.", _object_schema({"pin": PIN, "level": {"type": "integer", "enum": [0, 1]}}, ["pin", "level"]), self.gpio_write, False, True),
+            Tool("i2c_configure", "Configure WE Multitool as an I2C master.", _object_schema({"sda_pin": PIN, "scl_pin": PIN, "frequency_hz": {"type": "integer", "minimum": 1000, "maximum": 1000000}}, ["sda_pin", "scl_pin", "frequency_hz"]), self.i2c_configure, False, True),
+            Tool("i2c_scan", "Scan the configured I2C bus and return responding 7-bit addresses.", _object_schema({}), self.i2c_scan, True),
+            Tool("i2c_read", "Read bytes from a register on the configured I2C bus.", _object_schema({"address": {"type": "integer", "minimum": 1, "maximum": 127}, "register": BYTE, "length": {"type": "integer", "minimum": 1, "maximum": 128}}, ["address", "register", "length"]), self.i2c_read, True),
+            Tool("i2c_write", "Write bytes to a register on the configured I2C bus.", _object_schema({"address": {"type": "integer", "minimum": 1, "maximum": 127}, "register": BYTE, "data": BYTES}, ["address", "register", "data"]), self.i2c_write),
+            Tool("spi_configure", "Configure WE Multitool as an SPI master.", _object_schema({"cs_pin": PIN, "sck_pin": PIN, "mosi_pin": PIN, "miso_pin": PIN, "frequency_hz": {"type": "integer", "minimum": 1000}, "mode": {"type": "integer", "minimum": 0, "maximum": 3}}, ["cs_pin", "sck_pin", "mosi_pin", "miso_pin", "frequency_hz", "mode"]), self.spi_configure, False, True),
+            Tool("spi_transfer", "Write bytes and optionally read bytes in one SPI master transaction.", _object_schema({"write_data": BYTES, "read_length": {"type": "integer", "minimum": 0, "maximum": 1024}}, ["write_data", "read_length"]), self.spi_transfer),
+            Tool("uart_configure", "Configure UART2 pins and framing. Use -1 for unused CTS/RTS pins.", _object_schema({"tx_pin": PIN, "rx_pin": PIN, "baudrate": {"type": "integer", "minimum": 300, "maximum": 5000000}, "data_bits": {"type": "integer", "enum": [5, 6, 7, 8]}, "parity": {"type": "string", "enum": ["none", "even", "odd"]}, "stop_bits": {"type": "number", "enum": [1, 1.5, 2]}, "flow_control": {"type": "string", "enum": ["none", "rts", "cts", "cts_rts"]}, "cts_pin": OPTIONAL_PIN, "rts_pin": OPTIONAL_PIN}, ["tx_pin", "rx_pin"]), self.uart_configure, False, True),
+            Tool("uart_write", "Send text, base64, or byte-array data to the configured DUT UART.", _object_schema({"text": {"type": "string"}, "base64_data": {"type": "string"}, "bytes": BYTES}), self.uart_write),
+            Tool("uart_read", "Collect buffered UART bytes from the DUT for a bounded time.", _object_schema({"timeout_ms": {"type": "integer", "minimum": 0, "maximum": 30000}, "max_bytes": {"type": "integer", "minimum": 1, "maximum": 10240}}), self.uart_read, True),
+            Tool("pwm_configure", "Configure PWM on a free pin and channel.", _object_schema({"pin": PIN, "frequency_hz": {"type": "integer", "minimum": 1}, "channel": {"type": "integer", "minimum": 0, "maximum": 7}}, ["pin", "frequency_hz", "channel"]), self.pwm_configure, False, True),
+            Tool("pwm_set", "Set PWM duty cycle in percent on a configured pin.", _object_schema({"pin": PIN, "duty_percent": {"type": "number", "minimum": 0, "maximum": 100}}, ["pin", "duty_percent"]), self.pwm_set, False, True),
+        ]
+
+    def device_status(self, _: JsonObject) -> JsonObject:
+        return {"url": self.client.url, "connected": True, **self.pins_get({})}
+
+    def pins_get(self, _: JsonObject) -> JsonObject:
+        return {"pins": self._command({"type": "pins_get"}, "pins_get").get("pins", [])}
+
+    def gpio_configure(self, args: JsonObject) -> JsonObject:
+        return self._command({"type": "gpio_setup", "pin": args["pin"], "dir": args["direction"]}, "status")
+
+    def gpio_read(self, args: JsonObject) -> JsonObject:
+        return self._command({"type": "gpio_get", "pin": args["pin"]}, "gpio_state")
+
+    def gpio_write(self, args: JsonObject) -> JsonObject:
+        self.client.send({"type": "gpio_set", "pin": args["pin"], "state": args["level"]})
+        return {"dispatched": True, "verified": False, "note": "Current firmware does not acknowledge gpio_set."}
+
+    def i2c_configure(self, args: JsonObject) -> JsonObject:
+        return self._command({"type": "i2c_setup", "mode": "master", "sda": args["sda_pin"], "scl": args["scl_pin"], "freq": args["frequency_hz"]}, "i2c_response")
+
+    def i2c_scan(self, _: JsonObject) -> JsonObject:
+        return {"addresses": self._command({"type": "i2c_detect"}, "i2c_response").get("data", [])}
+
+    def i2c_read(self, args: JsonObject) -> JsonObject:
+        response = self._command({"type": "i2c_read", "addr": args["address"], "reg": args["register"], "len": args["length"]}, "i2c_response")
+        return {"address": args["address"], "register": args["register"], "data": response.get("data", [])}
+
+    def i2c_write(self, args: JsonObject) -> JsonObject:
+        return self._command({"type": "i2c_write", "addr": args["address"], "reg": args["register"], "data": args["data"]}, "i2c_response")
+
+    def spi_configure(self, args: JsonObject) -> JsonObject:
+        return self._command({"type": "spi_setup", "mode": "Master", "conn_mode": args["mode"] + 1, "cs": args["cs_pin"], "sck": args["sck_pin"], "mosi": args["mosi_pin"], "miso": args["miso_pin"], "freq": args["frequency_hz"]}, "spi_response")
+
+    def spi_transfer(self, args: JsonObject) -> JsonObject:
+        return self._command({"type": "spi_write", "word_length": 8, "data": args["write_data"], "data_read": args["read_length"]}, "spi_response")
+
+    def uart_configure(self, args: JsonObject) -> JsonObject:
+        command = {
+            "type": "uart_setup", "tx": args["tx_pin"], "rx": args["rx_pin"],
+            "cts": args.get("cts_pin", -1), "rts": args.get("rts_pin", -1),
+            "baudrate": args.get("baudrate", 115200), "databits": {5: 0, 6: 1, 7: 2, 8: 3}[args.get("data_bits", 8)],
+            "parity": {"none": 0, "even": 2, "odd": 3}[args.get("parity", "none")],
+            "stopbits": {1: 1, 1.5: 2, 2: 3}[args.get("stop_bits", 1)],
+            "flow": {"none": 0, "rts": 1, "cts": 2, "cts_rts": 3}[args.get("flow_control", "none")],
+        }
+        response = self.client.request(command, lambda message: message.get("type") == "uart_response" and "error" in message)
+        return self._check_error(response)
+
+    def uart_write(self, args: JsonObject) -> JsonObject:
+        choices = [key for key in ("text", "base64_data", "bytes") if key in args]
+        if len(choices) != 1:
+            raise DeviceError("Provide exactly one of text, base64_data, or bytes")
+        if choices[0] == "text":
+            data: Any = args["text"]
+        elif choices[0] == "base64_data":
+            try:
+                data = list(base64.b64decode(args["base64_data"], validate=True))
+            except (ValueError, TypeError) as exc:
+                raise DeviceError("base64_data is not valid base64") from exc
+        else:
+            data = args["bytes"]
+        response = self.client.request({"type": "uart_write", "data": data}, lambda message: message.get("type") == "uart_response" and "error" in message)
+        return self._check_error(response)
+
+    def uart_read(self, args: JsonObject) -> JsonObject:
+        data = self.client.read_uart(args.get("timeout_ms", 1000) / 1000, args.get("max_bytes", 4096))
+        return {"length": len(data), "base64_data": base64.b64encode(data).decode("ascii"), "text_utf8": data.decode("utf-8", errors="replace")}
+
+    def pwm_configure(self, args: JsonObject) -> JsonObject:
+        return self._command({"type": "pwm_setup", "pin": args["pin"], "freq": args["frequency_hz"], "channel": args["channel"]}, "pwm_response")
+
+    def pwm_set(self, args: JsonObject) -> JsonObject:
+        return self._command({"type": "pwm_set", "pin": args["pin"], "dutyCycle": args["duty_percent"]}, "pwm_response")
+
+
+class McpServer:
+    PROTOCOL_VERSION = "2025-06-18"
+
+    def __init__(self, tools: DutTools) -> None:
+        self.tools = tools
+
+    def handle(self, request: JsonObject) -> JsonObject | None:
+        if "id" not in request:
+            return None
+        request_id, method = request["id"], request.get("method")
+        try:
+            if method == "initialize":
+                requested = request.get("params", {}).get("protocolVersion")
+                return self._result(request_id, {
+                    "protocolVersion": requested or self.PROTOCOL_VERSION,
+                    "capabilities": {"tools": {"listChanged": False}},
+                    "serverInfo": {"name": "multitool-mcp", "version": "0.1.0"},
+                    "instructions": "Debug DUTs through WE Multitool. Read pins_get before configuring pins. Prefer read-only observations first. Confirm wiring, voltage, bus role, and target limits before changing GPIO/PWM or writing UART/I2C/SPI. Commands are serialized because firmware responses have no request IDs.",
+                })
+            if method == "ping":
+                return self._result(request_id, {})
+            if method == "tools/list":
+                return self._result(request_id, {"tools": [tool.definition() for tool in self.tools.tools.values()]})
+            if method == "tools/call":
+                params = request.get("params", {})
+                name = params.get("name")
+                tool = self.tools.tools.get(name)
+                if tool is None:
+                    return self._error(request_id, -32602, f"Unknown tool: {name}")
+                arguments = params.get("arguments", {})
+                if not isinstance(arguments, dict):
+                    return self._error(request_id, -32602, "Tool arguments must be an object")
+                try:
+                    self._validate(arguments, tool.schema)
+                    value = tool.handler(arguments)
+                    text = json.dumps(value, separators=(",", ":"), ensure_ascii=False)
+                    return self._result(request_id, {"content": [{"type": "text", "text": text}], "structuredContent": value})
+                except (DeviceError, KeyError, ValueError, TypeError) as exc:
+                    return self._result(request_id, {"content": [{"type": "text", "text": str(exc)}], "isError": True})
+            return self._error(request_id, -32601, f"Method not found: {method}")
+        except Exception as exc:
+            traceback.print_exc(file=sys.stderr)
+            return self._error(request_id, -32603, f"Internal error: {exc}")
+
+    @staticmethod
+    def _result(request_id: Any, result: JsonObject) -> JsonObject:
+        return {"jsonrpc": "2.0", "id": request_id, "result": result}
+
+    @staticmethod
+    def _error(request_id: Any, code: int, message: str) -> JsonObject:
+        return {"jsonrpc": "2.0", "id": request_id, "error": {"code": code, "message": message}}
+
+    @classmethod
+    def _validate(cls, value: Any, schema: JsonObject, path: str = "arguments") -> None:
+        expected = schema.get("type")
+        if expected == "object":
+            if not isinstance(value, dict):
+                raise ValueError(f"{path} must be an object")
+            missing = [name for name in schema.get("required", []) if name not in value]
+            if missing:
+                raise ValueError(f"{path} is missing required field(s): {', '.join(missing)}")
+            properties = schema.get("properties", {})
+            if schema.get("additionalProperties") is False:
+                extras = [name for name in value if name not in properties]
+                if extras:
+                    raise ValueError(f"{path} has unknown field(s): {', '.join(extras)}")
+            for name, item in value.items():
+                if name in properties:
+                    cls._validate(item, properties[name], f"{path}.{name}")
+            return
+        if expected == "array":
+            if not isinstance(value, list):
+                raise ValueError(f"{path} must be an array")
+            if len(value) > schema.get("maxItems", len(value)):
+                raise ValueError(f"{path} has too many items")
+            for index, item in enumerate(value):
+                cls._validate(item, schema.get("items", {}), f"{path}[{index}]")
+        elif expected == "integer":
+            if isinstance(value, bool) or not isinstance(value, int):
+                raise ValueError(f"{path} must be an integer")
+        elif expected == "number":
+            if isinstance(value, bool) or not isinstance(value, (int, float)):
+                raise ValueError(f"{path} must be a number")
+        elif expected == "string" and not isinstance(value, str):
+            raise ValueError(f"{path} must be a string")
+        if "enum" in schema and value not in schema["enum"]:
+            raise ValueError(f"{path} must be one of {schema['enum']}")
+        if "minimum" in schema and value < schema["minimum"]:
+            raise ValueError(f"{path} must be at least {schema['minimum']}")
+        if "maximum" in schema and value > schema["maximum"]:
+            raise ValueError(f"{path} must be at most {schema['maximum']}")
+
+
+def main() -> None:
+    url = os.environ.get("WE_MULTITOOL_URL", "ws://we-multitool.local/ws")
+    timeout = float(os.environ.get("WE_MULTITOOL_TIMEOUT_SECONDS", "5"))
+    client = DeviceClient(url, timeout)
+    server = McpServer(DutTools(client))
+    try:
+        for line in sys.stdin:
+            try:
+                request = json.loads(line)
+                if not isinstance(request, dict):
+                    raise ValueError("Request must be a JSON object")
+                response = server.handle(request)
+            except (json.JSONDecodeError, ValueError) as exc:
+                response = McpServer._error(None, -32700, str(exc))
+            if response is not None:
+                print(json.dumps(response, separators=(",", ":"), ensure_ascii=False), flush=True)
+    finally:
+        client.close()

multitool_mcp-0.1.0/src/dut_mcp/websocket.py

@@ -0,0 +1,160 @@
+"""Small RFC 6455 client used to keep the MCP bridge dependency-free."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import os
+import socket
+import ssl
+import struct
+from urllib.parse import urlsplit
+
+
+class WebSocketError(RuntimeError):
+    pass
+
+
+class WebSocket:
+    def __init__(self, url: str, timeout: float = 5.0) -> None:
+        self.url = url
+        self.timeout = timeout
+        self._socket: socket.socket | None = None
+
+    @property
+    def connected(self) -> bool:
+        return self._socket is not None
+
+    def connect(self) -> None:
+        if self._socket is not None:
+            return
+        uri = urlsplit(self.url)
+        if uri.scheme not in {"ws", "wss"} or not uri.hostname:
+            raise WebSocketError("Device URL must use ws:// or wss://")
+        port = uri.port or (443 if uri.scheme == "wss" else 80)
+        raw = socket.create_connection((uri.hostname, port), timeout=self.timeout)
+        if uri.scheme == "wss":
+            raw = ssl.create_default_context().wrap_socket(raw, server_hostname=uri.hostname)
+        raw.settimeout(self.timeout)
+        key = base64.b64encode(os.urandom(16)).decode("ascii")
+        path = uri.path or "/"
+        if uri.query:
+            path += "?" + uri.query
+        host = uri.hostname if uri.port is None else f"{uri.hostname}:{uri.port}"
+        request = (
+            f"GET {path} HTTP/1.1\r\nHost: {host}\r\nUpgrade: websocket\r\n"
+            f"Connection: Upgrade\r\nSec-WebSocket-Key: {key}\r\nSec-WebSocket-Version: 13\r\n\r\n"
+        )
+        try:
+            raw.sendall(request.encode("ascii"))
+            response = self._receive_headers(raw)
+            status = response.split("\r\n", 1)[0]
+            if " 101 " not in status:
+                raise WebSocketError(f"WebSocket upgrade failed: {status}")
+            headers = {}
+            for line in response.split("\r\n")[1:]:
+                if ":" in line:
+                    name, value = line.split(":", 1)
+                    headers[name.strip().lower()] = value.strip()
+            expected = base64.b64encode(hashlib.sha1((key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11").encode("ascii")).digest()).decode("ascii")
+            if headers.get("sec-websocket-accept") != expected:
+                raise WebSocketError("WebSocket server returned an invalid accept key")
+        except Exception:
+            raw.close()
+            raise
+        self._socket = raw
+
+    def close(self) -> None:
+        sock, self._socket = self._socket, None
+        if sock is None:
+            return
+        try:
+            self._send_frame(0x8, b"", sock=sock)
+        except OSError:
+            pass
+        finally:
+            sock.close()
+
+    def send_text(self, text: str) -> None:
+        self.connect()
+        self._send_frame(0x1, text.encode("utf-8"))
+
+    def receive_text(self, timeout: float | None = None) -> str:
+        if self._socket is None:
+            raise WebSocketError("WebSocket is not connected")
+        previous_timeout = self._socket.gettimeout()
+        if timeout is not None:
+            self._socket.settimeout(timeout)
+        try:
+            fragments = bytearray()
+            while True:
+                final, opcode, payload = self._receive_frame()
+                if opcode == 0x8:
+                    self.close()
+                    raise WebSocketError("Device closed the WebSocket connection")
+                if opcode == 0x9:
+                    self._send_frame(0xA, payload)
+                    continue
+                if opcode == 0xA:
+                    continue
+                if opcode not in {0x0, 0x1}:
+                    raise WebSocketError(f"Unsupported WebSocket opcode: {opcode}")
+                fragments.extend(payload)
+                if final:
+                    return fragments.decode("utf-8")
+        finally:
+            if self._socket is not None:
+                self._socket.settimeout(previous_timeout)
+
+    @staticmethod
+    def _receive_headers(sock: socket.socket) -> str:
+        data = bytearray()
+        while b"\r\n\r\n" not in data:
+            chunk = sock.recv(4096)
+            if not chunk:
+                raise WebSocketError("Connection closed during WebSocket upgrade")
+            data.extend(chunk)
+            if len(data) > 65536:
+                raise WebSocketError("WebSocket upgrade headers are too large")
+        return bytes(data).split(b"\r\n\r\n", 1)[0].decode("iso-8859-1")
+
+    def _receive_frame(self) -> tuple[bool, int, bytes]:
+        first, second = self._read_exact(2)
+        final, opcode, masked = bool(first & 0x80), first & 0x0F, bool(second & 0x80)
+        length = second & 0x7F
+        if length == 126:
+            length = struct.unpack("!H", self._read_exact(2))[0]
+        elif length == 127:
+            length = struct.unpack("!Q", self._read_exact(8))[0]
+        mask = self._read_exact(4) if masked else b""
+        payload = self._read_exact(length)
+        if masked:
+            payload = bytes(value ^ mask[index % 4] for index, value in enumerate(payload))
+        return final, opcode, payload
+
+    def _read_exact(self, length: int) -> bytes:
+        assert self._socket is not None
+        data = bytearray()
+        while len(data) < length:
+            chunk = self._socket.recv(length - len(data))
+            if not chunk:
+                raise WebSocketError("Device closed the WebSocket connection")
+            data.extend(chunk)
+        return bytes(data)
+
+    def _send_frame(self, opcode: int, payload: bytes, sock: socket.socket | None = None) -> None:
+        target = sock or self._socket
+        if target is None:
+            raise WebSocketError("WebSocket is not connected")
+        mask, length = os.urandom(4), len(payload)
+        header = bytearray([0x80 | opcode])
+        if length < 126:
+            header.append(0x80 | length)
+        elif length <= 0xFFFF:
+            header.append(0x80 | 126)
+            header.extend(struct.pack("!H", length))
+        else:
+            header.append(0x80 | 127)
+            header.extend(struct.pack("!Q", length))
+        masked = bytes(value ^ mask[index % 4] for index, value in enumerate(payload))
+        target.sendall(bytes(header) + mask + masked)

multitool_mcp-0.1.0/src/multitool_mcp.egg-info/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: multitool-mcp
+Version: 0.1.0
+Summary: MCP server for debugging devices under test through WE Multitool
+Author: Wise Electronics
+License-Expression: GPL-3.0-or-later
+Project-URL: Homepage, https://github.com/we-devices/multitool-mcp
+Project-URL: Repository, https://github.com/we-devices/multitool-mcp.git
+Project-URL: Issues, https://github.com/we-devices/multitool-mcp/issues
+Keywords: mcp,embedded,hardware,debugging,we-multitool
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# WE Multitool DUT MCP
+
+`multitool-mcp` is a dependency-free [Model Context Protocol](https://modelcontextprotocol.io/) server for inspecting and debugging a device under test (DUT) through a Wise Electronics WE Multitool.
+
+It runs over standard input/output and bridges the Multitool's JSON-over-WebSocket API. It exposes bounded MCP tools for GPIO, I2C, SPI, UART, PWM, and GPIO ownership.
+
+## Requirements
+
+- Python 3.11 or later
+- A WE Multitool reachable over WebSocket
+
+## Install
+
+Install from PyPI once published:
+
+```shell
+python -m pip install multitool-mcp
+```
+
+For development from a clone:
+
+```shell
+python -m pip install -e .
+```
+
+## Configure an MCP client
+
+Run the installed command:
+
+```toml
+[mcp_servers.we_multitool_dut]
+command = "multitool-mcp"
+env_vars = ["WE_MULTITOOL_URL", "WE_MULTITOOL_TIMEOUT_SECONDS"]
+startup_timeout_sec = 10
+tool_timeout_sec = 35
+default_tools_approval_mode = "prompt"
+```
+
+By default, the server connects to `ws://we-multitool.local/ws`. Set these environment variables before starting the MCP client to change that:
+
+```shell
+WE_MULTITOOL_URL=ws://10.0.0.1/ws
+WE_MULTITOOL_TIMEOUT_SECONDS=8
+```
+
+On PowerShell:
+
+```powershell
+$env:WE_MULTITOOL_URL = "ws://10.0.0.1/ws"
+$env:WE_MULTITOOL_TIMEOUT_SECONDS = "8"
+```
+
+## Safety and firmware behavior
+
+Read `pins_get` before configuring pins, and verify wiring, voltage, bus role, and DUT limits before driving signals.
+
+- Commands are serialized because firmware responses do not carry request IDs.
+- UART data received while another command awaits a response is buffered.
+- The `gpio_set` firmware command has no acknowledgement; `gpio_write` reports it as dispatched but unverified.
+- The firmware tracks one active WebSocket response socket. Do not use the browser UI and MCP bridge concurrently.
+
+## Development
+
+```shell
+python -m pip install -e ".[test]"
+python -m pytest
+```
+
+The runtime has no third-party dependencies. The optional `test` extra installs pytest.
+
+## License
+
+Licensed under the GNU General Public License, version 3 or later
+(GPL-3.0-or-later). See [LICENSE](LICENSE).

multitool_mcp-0.1.0/src/multitool_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/dut_mcp/__init__.py
+src/dut_mcp/__main__.py
+src/dut_mcp/device.py
+src/dut_mcp/server.py
+src/dut_mcp/websocket.py
+src/multitool_mcp.egg-info/PKG-INFO
+src/multitool_mcp.egg-info/SOURCES.txt
+src/multitool_mcp.egg-info/dependency_links.txt
+src/multitool_mcp.egg-info/entry_points.txt
+src/multitool_mcp.egg-info/requires.txt
+src/multitool_mcp.egg-info/top_level.txt
+tests/test_dut_mcp.py

multitool_mcp-0.1.0/src/multitool_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

multitool_mcp-0.1.0/src/multitool_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+multitool-mcp = dut_mcp.server:main

multitool_mcp-0.1.0/src/multitool_mcp.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[test]
+pytest>=8

multitool_mcp-0.1.0/src/multitool_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+dut_mcp

multitool_mcp-0.1.0/tests/test_dut_mcp.py

@@ -0,0 +1,134 @@
+import base64
+import json
+import socket
+
+from dut_mcp.device import DeviceClient
+from dut_mcp.server import DutTools, McpServer
+from dut_mcp.websocket import WebSocket
+
+
+class FakeTransport:
+    def __init__(self, responses=()):
+        self.responses = list(responses)
+        self.sent = []
+        self.connected = False
+
+    def connect(self):
+        self.connected = True
+
+    def close(self):
+        self.connected = False
+
+    def send_text(self, text):
+        self.connected = True
+        self.sent.append(json.loads(text))
+
+    def receive_text(self, timeout=None):
+        if not self.responses:
+            raise socket.timeout()
+        return json.dumps(self.responses.pop(0))
+
+
+class FakeSocket:
+    def __init__(self, incoming=b""):
+        self.incoming = bytearray(incoming)
+        self.outgoing = b""
+        self.timeout = None
+
+    def recv(self, length):
+        result = bytes(self.incoming[:length])
+        del self.incoming[:length]
+        return result
+
+    def sendall(self, data):
+        self.outgoing += data
+
+    def gettimeout(self):
+        return self.timeout
+
+    def settimeout(self, timeout):
+        self.timeout = timeout
+
+
+def make_server(responses=()):
+    transport = FakeTransport(responses)
+    client = DeviceClient("ws://test/ws", timeout=0.01, transport=transport)
+    return McpServer(DutTools(client)), transport
+
+
+def test_initialize_and_tool_annotations():
+    server, _ = make_server()
+    initialized = server.handle({"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18"}})
+    assert initialized["result"]["protocolVersion"] == "2025-06-18"
+    listed = server.handle({"jsonrpc": "2.0", "id": 2, "method": "tools/list"})
+    tools = {tool["name"]: tool for tool in listed["result"]["tools"]}
+    assert tools["gpio_read"]["annotations"]["readOnlyHint"] is True
+    assert tools["gpio_write"]["annotations"]["readOnlyHint"] is False
+    assert tools["i2c_read"]["inputSchema"]["additionalProperties"] is False
+
+
+def test_i2c_read_translates_wire_contract():
+    server, transport = make_server([
+        {"type": "uart_response", "data": base64.b64encode(b"boot").decode()},
+        {"type": "i2c_response", "result_type": 2, "addr": 0x48, "data": [1, 2]},
+    ])
+    response = server.handle({"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "i2c_read", "arguments": {"address": 0x48, "register": 1, "length": 2}}})
+    assert transport.sent == [{"type": "i2c_read", "addr": 0x48, "reg": 1, "len": 2}]
+    assert response["result"]["structuredContent"]["data"] == [1, 2]
+
+
+def test_uart_rx_is_buffered_while_waiting_for_ack():
+    server, _ = make_server([
+        {"type": "uart_response", "data": base64.b64encode(b"hello").decode()},
+        {"type": "uart_response", "data": "Data has been sent", "error": False},
+    ])
+    write = server.handle({"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "uart_write", "arguments": {"text": "AT\r\n"}}})
+    assert write["result"].get("isError") is not True
+    read = server.handle({"jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": {"name": "uart_read", "arguments": {"timeout_ms": 0, "max_bytes": 20}}})
+    assert read["result"]["structuredContent"]["text_utf8"] == "hello"
+
+
+def test_gpio_write_reports_unverified_dispatch():
+    server, transport = make_server()
+    response = server.handle({"jsonrpc": "2.0", "id": 6, "method": "tools/call", "params": {"name": "gpio_write", "arguments": {"pin": 4, "level": 1}}})
+    assert transport.sent == [{"type": "gpio_set", "pin": 4, "state": 1}]
+    assert response["result"]["structuredContent"]["verified"] is False
+
+
+def test_device_error_becomes_mcp_tool_error():
+    server, _ = make_server([{"type": "i2c_response", "result_type": 0, "data": "not connected"}])
+    response = server.handle({"jsonrpc": "2.0", "id": 7, "method": "tools/call", "params": {"name": "i2c_scan", "arguments": {}}})
+    assert response["result"]["isError"] is True
+    assert "not connected" in response["result"]["content"][0]["text"]
+
+
+def test_uart_write_requires_exactly_one_encoding():
+    server, _ = make_server()
+    response = server.handle({"jsonrpc": "2.0", "id": 8, "method": "tools/call", "params": {"name": "uart_write", "arguments": {"text": "x", "bytes": [1]}}})
+    assert response["result"]["isError"] is True
+
+
+def test_arguments_are_validated_before_device_access():
+    server, transport = make_server()
+    response = server.handle({"jsonrpc": "2.0", "id": 9, "method": "tools/call", "params": {"name": "gpio_write", "arguments": {"pin": -1, "level": 2}}})
+    assert response["result"]["isError"] is True
+    assert transport.sent == []
+
+
+def test_websocket_decodes_server_text_frame():
+    websocket = WebSocket("ws://test/ws")
+    websocket._socket = FakeSocket(b"\x81\x05hello")
+    assert websocket.receive_text() == "hello"
+
+
+def test_websocket_masks_client_text_frame():
+    websocket = WebSocket("ws://test/ws")
+    sock = FakeSocket()
+    websocket._socket = sock
+    websocket.send_text("hello")
+    assert sock.outgoing[0] == 0x81
+    assert sock.outgoing[1] & 0x80
+    length = sock.outgoing[1] & 0x7F
+    mask = sock.outgoing[2:6]
+    encoded = sock.outgoing[6:6 + length]
+    assert bytes(value ^ mask[index % 4] for index, value in enumerate(encoded)) == b"hello"