embeddedci-mcp 0.1.0__tar.gz

embeddedci_mcp-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+
+# Build artifacts
+build/
+dist/
+
+# Virtualenvs
+.venv/
+venv/

embeddedci_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: embeddedci-mcp
+Version: 0.1.0
+Summary: MCP server exposing the EmbeddedCI BenchPod SDK as tools for AI agents
+Project-URL: Homepage, https://embeddedci.com
+Project-URL: Repository, https://github.com/embeddedci-com/embeddedci-python
+Project-URL: Issues, https://github.com/embeddedci-com/embeddedci-python/issues
+Author: EmbeddedCI
+License: Apache-2.0
+Keywords: agent,benchpod,embedded,hardware-in-the-loop,mcp,swd
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: embeddedci>=0.1
+Requires-Dist: mcp[cli]>=1.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# embeddedci-mcp
+
+An [MCP](https://modelcontextprotocol.io) server that exposes the
+[`embeddedci`](https://github.com/embeddedci-com/embeddedci-python/tree/main/packages/embeddedci)
+BenchPod SDK as tools, so an AI agent can drive a real hardware-in-the-loop bench:
+power a target board, flash it over SWD, capture its UART, and emulate/decode an
+I2C sensor.
+
+It's a thin consumer of the SDK — every tool maps directly to a
+`embeddedci.benchpod.BenchPod` method.
+
+## Install
+
+```bash
+pip install embeddedci-mcp        # pulls embeddedci from PyPI
+# or run without installing:
+uvx embeddedci-mcp --help
+```
+
+For local development from this repo, see the
+[workspace README](https://github.com/embeddedci-com/embeddedci-python#development).
+
+## Run
+
+```bash
+# stdio (launched by an MCP client as a subprocess — the usual case):
+embeddedci-mcp --transport stdio
+
+# streamable HTTP (for a remote bench):
+embeddedci-mcp --transport http --host 0.0.0.0 --port 8000
+
+# preset a default connection so the `connect` tool needs no argument:
+embeddedci-mcp --connection /dev/tty.usbserial-0001
+embeddedci-mcp --connection 192.168.1.213        # wifi/TCP, default port 8080
+```
+
+The connection can also come from the `BENCHPOD_CONNECTION` environment variable.
+
+## Client configuration
+
+### Claude Desktop / Cursor (`mcp.json` / `claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "benchpod": {
+      "command": "uvx",
+      "args": ["embeddedci-mcp"],
+      "env": { "BENCHPOD_CONNECTION": "192.168.1.213" }
+    }
+  }
+}
+```
+
+Use `"command": "embeddedci-mcp"` instead if it's installed on `PATH`.
+
+### Claude Code
+
+```bash
+claude mcp add benchpod -- uvx embeddedci-mcp
+```
+
+## Tools
+
+| Group | Tools |
+| --- | --- |
+| Lifecycle / status | `connect`, `disconnect`, `ping`, `status` |
+| Power | `power_on`, `power_off`, `target_power`, `target_status` |
+| Flash | `flash` |
+| UART | `capture_uart`, `power_cycle_and_capture` |
+| I2C sensor | `enable_i2c_sensor`, `set_i2c_sensor`, `disable_i2c_sensor`, `i2c_sensor_status`, `i2c_sensor_regs`, `i2c_sensor_la_decoded`, `i2c_read_register` |
+| Pull-ups | `enable_pullup`, `disable_pullup`, `pullup_status` |
+| Low-level | `command`, `gpio_set`, `capture_adc`, `signal_generate`, `measure` |
+
+Device/firmware failures come back as `{"ok": false, "error": ..., "error_type": ...}`
+rather than raising, so the agent can reason about them.
+
+### Resources
+
+- `benchpod://wiring` — the default LA channel → DUT signal pin map and eFuse table.
+- `benchpod://help` — the canonical HIL workflow order.
+
+## Example agent flow
+
+1. `connect("192.168.1.213")`
+2. `flash(swclk=11, swdio=12, nreset=3, target="target/stm32f4x.cfg", file="app.elf", target_power=1)`
+3. `enable_pullup([1, 2])` then `enable_i2c_sensor(sda=2, scl=1, temperature_c=22.5, pressure_pa=101000)`
+4. `power_cycle_and_capture(rx=5, tx=4, delay=1.5, duration=6.0, until_regex="APP_OK")`
+5. `i2c_sensor_status()` / `i2c_read_register(address=0x76, register=0xD0)` to confirm the DUT probed the sensor.
+
+## Publishing to the MCP Registry
+
+`server.json` is starter metadata for the
+[Official MCP Registry](https://registry.modelcontextprotocol.io) (currently in
+preview). Ship the package to PyPI first (that's what makes `uvx embeddedci-mcp`
+work), then publish the registry entry once the name is stable:
+
+```bash
+mcp-publisher publish      # GitHub-authenticated; reads server.json
+```

embeddedci_mcp-0.1.0/README.md

@@ -0,0 +1,100 @@
+# embeddedci-mcp
+
+An [MCP](https://modelcontextprotocol.io) server that exposes the
+[`embeddedci`](https://github.com/embeddedci-com/embeddedci-python/tree/main/packages/embeddedci)
+BenchPod SDK as tools, so an AI agent can drive a real hardware-in-the-loop bench:
+power a target board, flash it over SWD, capture its UART, and emulate/decode an
+I2C sensor.
+
+It's a thin consumer of the SDK — every tool maps directly to a
+`embeddedci.benchpod.BenchPod` method.
+
+## Install
+
+```bash
+pip install embeddedci-mcp        # pulls embeddedci from PyPI
+# or run without installing:
+uvx embeddedci-mcp --help
+```
+
+For local development from this repo, see the
+[workspace README](https://github.com/embeddedci-com/embeddedci-python#development).
+
+## Run
+
+```bash
+# stdio (launched by an MCP client as a subprocess — the usual case):
+embeddedci-mcp --transport stdio
+
+# streamable HTTP (for a remote bench):
+embeddedci-mcp --transport http --host 0.0.0.0 --port 8000
+
+# preset a default connection so the `connect` tool needs no argument:
+embeddedci-mcp --connection /dev/tty.usbserial-0001
+embeddedci-mcp --connection 192.168.1.213        # wifi/TCP, default port 8080
+```
+
+The connection can also come from the `BENCHPOD_CONNECTION` environment variable.
+
+## Client configuration
+
+### Claude Desktop / Cursor (`mcp.json` / `claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "benchpod": {
+      "command": "uvx",
+      "args": ["embeddedci-mcp"],
+      "env": { "BENCHPOD_CONNECTION": "192.168.1.213" }
+    }
+  }
+}
+```
+
+Use `"command": "embeddedci-mcp"` instead if it's installed on `PATH`.
+
+### Claude Code
+
+```bash
+claude mcp add benchpod -- uvx embeddedci-mcp
+```
+
+## Tools
+
+| Group | Tools |
+| --- | --- |
+| Lifecycle / status | `connect`, `disconnect`, `ping`, `status` |
+| Power | `power_on`, `power_off`, `target_power`, `target_status` |
+| Flash | `flash` |
+| UART | `capture_uart`, `power_cycle_and_capture` |
+| I2C sensor | `enable_i2c_sensor`, `set_i2c_sensor`, `disable_i2c_sensor`, `i2c_sensor_status`, `i2c_sensor_regs`, `i2c_sensor_la_decoded`, `i2c_read_register` |
+| Pull-ups | `enable_pullup`, `disable_pullup`, `pullup_status` |
+| Low-level | `command`, `gpio_set`, `capture_adc`, `signal_generate`, `measure` |
+
+Device/firmware failures come back as `{"ok": false, "error": ..., "error_type": ...}`
+rather than raising, so the agent can reason about them.
+
+### Resources
+
+- `benchpod://wiring` — the default LA channel → DUT signal pin map and eFuse table.
+- `benchpod://help` — the canonical HIL workflow order.
+
+## Example agent flow
+
+1. `connect("192.168.1.213")`
+2. `flash(swclk=11, swdio=12, nreset=3, target="target/stm32f4x.cfg", file="app.elf", target_power=1)`
+3. `enable_pullup([1, 2])` then `enable_i2c_sensor(sda=2, scl=1, temperature_c=22.5, pressure_pa=101000)`
+4. `power_cycle_and_capture(rx=5, tx=4, delay=1.5, duration=6.0, until_regex="APP_OK")`
+5. `i2c_sensor_status()` / `i2c_read_register(address=0x76, register=0xD0)` to confirm the DUT probed the sensor.
+
+## Publishing to the MCP Registry
+
+`server.json` is starter metadata for the
+[Official MCP Registry](https://registry.modelcontextprotocol.io) (currently in
+preview). Ship the package to PyPI first (that's what makes `uvx embeddedci-mcp`
+work), then publish the registry entry once the name is stable:
+
+```bash
+mcp-publisher publish      # GitHub-authenticated; reads server.json
+```

embeddedci_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "embeddedci-mcp"
+version = "0.1.0"
+description = "MCP server exposing the EmbeddedCI BenchPod SDK as tools for AI agents"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "EmbeddedCI" }]
+keywords = ["embedded", "hardware-in-the-loop", "mcp", "benchpod", "swd", "agent"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "embeddedci>=0.1",
+    "mcp[cli]>=1.9",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[project.scripts]
+embeddedci-mcp = "embeddedci_mcp.__main__:main"
+
+[project.urls]
+Homepage = "https://embeddedci.com"
+Repository = "https://github.com/embeddedci-com/embeddedci-python"
+Issues = "https://github.com/embeddedci-com/embeddedci-python/issues"
+
+# Inside the workspace, resolve embeddedci from the sibling source tree (see the
+# repo-root pyproject.toml [tool.uv.workspace]). On PyPI this is ignored and the
+# published embeddedci is used.
+[tool.uv.sources]
+embeddedci = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/embeddedci_mcp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

embeddedci_mcp-0.1.0/server.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
+  "name": "io.github.embeddedci-com/embeddedci-mcp",
+  "description": "Drive an EmbeddedCI BenchPod hardware-in-the-loop tester: power, flash over SWD, capture UART, and emulate/decode an I2C sensor on a real target board.",
+  "version": "0.1.0",
+  "repository": {
+    "url": "https://github.com/embeddedci-com/embeddedci-python",
+    "source": "github",
+    "subfolder": "packages/embeddedci-mcp"
+  },
+  "packages": [
+    {
+      "registry_type": "pypi",
+      "registry_base_url": "https://pypi.org",
+      "identifier": "embeddedci-mcp",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "runtime_arguments": [
+        {
+          "type": "named",
+          "name": "--connection",
+          "description": "Default BenchPod connection: host[:port], a serial device path, or 'serial'.",
+          "is_required": false,
+          "format": "string"
+        }
+      ],
+      "environment_variables": [
+        {
+          "name": "BENCHPOD_CONNECTION",
+          "description": "Fallback BenchPod connection when --connection / the connect tool is not given one.",
+          "is_required": false
+        }
+      ]
+    }
+  ]
+}

embeddedci_mcp-0.1.0/src/embeddedci_mcp/__init__.py

@@ -0,0 +1,15 @@
+"""embeddedci-mcp — an MCP server exposing the EmbeddedCI BenchPod SDK as tools."""
+
+from .server import mcp
+from .session import SESSION, Session
+
+__all__ = ["mcp", "SESSION", "Session", "main"]
+
+__version__ = "0.1.0"
+
+
+def main(argv=None) -> None:
+    """Console-script entry point (see ``__main__.main``)."""
+    from .__main__ import main as _main
+
+    _main(argv)

embeddedci_mcp-0.1.0/src/embeddedci_mcp/__main__.py

@@ -0,0 +1,57 @@
+"""Command-line entry point for the BenchPod MCP server.
+
+Run over stdio (the default; launched as a subprocess by an MCP client such as
+Claude Desktop / Cursor / Claude Code) or as an HTTP server for a remote bench::
+
+    embeddedci-mcp --transport stdio
+    embeddedci-mcp --transport http --host 0.0.0.0 --port 8000 --connection serial
+"""
+
+from __future__ import annotations
+
+import argparse
+from typing import Optional, Sequence
+
+from .server import mcp
+from .session import SESSION
+
+
+def main(argv: Optional[Sequence[str]] = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="embeddedci-mcp",
+        description="MCP server exposing the EmbeddedCI BenchPod SDK as agent tools.",
+    )
+    parser.add_argument(
+        "--transport", choices=["stdio", "http"], default="stdio",
+        help="MCP transport: 'stdio' (default, local subprocess) or 'http' "
+             "(streamable HTTP for a remote bench).",
+    )
+    parser.add_argument(
+        "--host", default="127.0.0.1",
+        help="Bind host for --transport http (default: 127.0.0.1).",
+    )
+    parser.add_argument(
+        "--port", type=int, default=8000,
+        help="Bind port for --transport http (default: 8000).",
+    )
+    parser.add_argument(
+        "--connection", default=None,
+        help="Default BenchPod connection used by the `connect` tool when called "
+             "with no argument: host[:port], a serial device path, or 'serial'. "
+             "Falls back to the BENCHPOD_CONNECTION environment variable.",
+    )
+    args = parser.parse_args(argv)
+
+    if args.connection:
+        SESSION.default_connection = args.connection
+
+    if args.transport == "http":
+        mcp.settings.host = args.host
+        mcp.settings.port = args.port
+        mcp.run(transport="streamable-http")
+    else:
+        mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

embeddedci_mcp-0.1.0/src/embeddedci_mcp/server.py

@@ -0,0 +1,506 @@
+"""The MCP server: every BenchPod capability mapped to an MCP tool.
+
+Each tool is a thin adapter — coerce JSON-friendly arguments, call the matching
+:class:`~embeddedci.benchpod.BenchPod` method, and return a JSON-serializable
+result. Device/firmware failures (the :class:`BenchPodError` family) are turned
+into structured ``{"ok": false, "error": ..., "error_type": ...}`` results so an
+agent can reason about them instead of seeing a raw traceback.
+
+No protocol, flash, or decode logic lives here; it all comes from the
+``embeddedci`` SDK. This module only exposes it.
+"""
+
+from __future__ import annotations
+
+import functools
+import re
+from typing import Any, Dict, List, Optional, Union
+
+from mcp.server.fastmcp import FastMCP
+
+from embeddedci.benchpod import i2c
+from embeddedci.benchpod.errors import BenchPodError
+
+from .session import SESSION
+
+mcp = FastMCP("embeddedci-benchpod")
+
+
+# -- helpers ----------------------------------------------------------------
+
+def _safe(fn):
+    """Wrap a tool so SDK errors become structured results, not tracebacks.
+
+    ``functools.wraps`` preserves the wrapped function's signature and
+    annotations, so FastMCP still derives the correct input schema.
+    """
+
+    @functools.wraps(fn)
+    def wrapper(*args, **kwargs):
+        try:
+            return fn(*args, **kwargs)
+        except BenchPodError as exc:
+            return {"ok": False, "error": str(exc), "error_type": type(exc).__name__}
+
+    return wrapper
+
+
+def _tail(text: str, limit: int = 4000) -> str:
+    """Keep only the last ``limit`` chars (flash logs can be huge)."""
+    if not text:
+        return text
+    return text if len(text) <= limit else "…(truncated)…\n" + text[-limit:]
+
+
+def _flash_result(result) -> dict:
+    return {
+        "ok": result.ok,
+        "returncode": result.returncode,
+        "target_unreachable": result.target_unreachable,
+        "stalled": result.stalled,
+        "stdout_tail": _tail(result.stdout),
+        "stderr_tail": _tail(result.stderr),
+    }
+
+
+def _summarize_samples(data, head: int = 32) -> dict:
+    data = list(data)
+    out: dict = {"count": len(data), "head": data[:head], "truncated": len(data) > head}
+    if data:
+        out["min"] = min(data)
+        out["max"] = max(data)
+    return out
+
+
+def _compile_until(until_regex: Optional[str]):
+    return re.compile(until_regex) if until_regex else None
+
+
+# -- lifecycle / status -----------------------------------------------------
+
+@mcp.tool()
+@_safe
+def connect(connection: Optional[str] = None) -> dict:
+    """Open a BenchPod connection and return its status.
+
+    ``connection`` is a host[:port] (wifi/TCP, default port 8080), a serial
+    device path (e.g. ``/dev/tty.usbserial-0001``), or ``"serial"`` to
+    auto-detect. When omitted, the server's ``--connection`` default or the
+    ``BENCHPOD_CONNECTION`` environment variable is used. Re-connecting closes
+    any previous connection first.
+    """
+    from embeddedci.benchpod.connection import resolve_connection
+
+    spec = resolve_connection(connection or SESSION.default_connection)
+    pod = SESSION.connect(connection)
+    info: dict = {
+        "connected": True,
+        "kind": spec.kind,
+        "target": spec.addr or spec.device or "(auto-detect)",
+    }
+    try:
+        info["status"] = pod.status()
+    except BenchPodError as exc:  # connected, but status round-trip failed
+        info["status_error"] = str(exc)
+    return info
+
+
+@mcp.tool()
+@_safe
+def disconnect() -> dict:
+    """Close the current BenchPod connection (safe if none is open)."""
+    SESSION.disconnect()
+    return {"connected": False}
+
+
+@mcp.tool()
+@_safe
+def ping() -> dict:
+    """Confirm the pod is reachable."""
+    return {"ping": SESSION.require().ping()}
+
+
+@mcp.tool()
+@_safe
+def status() -> Any:
+    """Return firmware/connection status (dict over TCP, text over serial)."""
+    return SESSION.require().status()
+
+
+# -- power ------------------------------------------------------------------
+
+@mcp.tool()
+@_safe
+def power_on(efuse: int = 1, delay: Optional[float] = None) -> dict:
+    """Power the target on via an eFuse (1 = internal 5V, 2 = external).
+
+    ``delay`` (seconds) schedules the power-on pod-side and returns immediately —
+    use it to power-on *during* a UART capture so the boot banner lands in-window.
+    """
+    SESSION.require().power_on(efuse, delay=delay)
+    return {"ok": True, "efuse": efuse, "on": True, "delay": delay}
+
+
+@mcp.tool()
+@_safe
+def power_off(efuse: int = 1, delay: Optional[float] = None) -> dict:
+    """Power the target off via an eFuse (1 = internal 5V, 2 = external)."""
+    SESSION.require().power_off(efuse, delay=delay)
+    return {"ok": True, "efuse": efuse, "on": False, "delay": delay}
+
+
+@mcp.tool()
+@_safe
+def target_power(efuse: int, on: bool, delay: Optional[float] = None) -> dict:
+    """Enable or disable a target-power eFuse explicitly."""
+    SESSION.require().target_power(efuse, on=on, delay=delay)
+    return {"ok": True, "efuse": efuse, "on": on, "delay": delay}
+
+
+@mcp.tool()
+@_safe
+def target_status() -> Any:
+    """Read the eFuse enabled/fault/valid state (RP2350B)."""
+    return SESSION.require().command({"cmd": "target_status"})
+
+
+# -- flash ------------------------------------------------------------------
+
+@mcp.tool()
+@_safe
+def flash(
+    swclk: int,
+    swdio: int,
+    nreset: Optional[int] = None,
+    target: str = "",
+    file: str = "",
+    load_address: str = "",
+    target_power: Optional[int] = None,
+    verify: bool = True,
+    reset: bool = True,
+    connect_under_reset: Optional[bool] = None,
+    clear_reset_events: bool = True,
+    extra_configs: Optional[List[str]] = None,
+    extra_args: Optional[List[str]] = None,
+    timeout: float = 300.0,
+    connect_attempts: int = 5,
+) -> dict:
+    """Flash an SWD target via the OpenOCD remote_bitbang bridge.
+
+    ``swclk``/``swdio``/``nreset`` are LA channels (1-12). ``target`` is an
+    OpenOCD target cfg (e.g. ``target/stm32f4x.cfg``); ``file`` is the firmware
+    image. ``target_power`` (1/2) powers the target before flashing. Returns a
+    structured result with ``ok`` plus ``stdout_tail``/``stderr_tail`` — inspect
+    ``target_unreachable``/``stalled`` to diagnose failures. Over a serial
+    bit-bang link, set ``verify=false`` (the long verify phase is flaky there).
+    """
+    result = SESSION.require().flash(
+        swclk=swclk, swdio=swdio, nreset=nreset,
+        target=target, file=file, load_address=load_address,
+        target_power=target_power, verify=verify, reset=reset,
+        connect_under_reset=connect_under_reset,
+        clear_reset_events=clear_reset_events,
+        extra_configs=tuple(extra_configs or ()),
+        extra_args=tuple(extra_args or ()),
+        timeout=timeout, connect_attempts=connect_attempts,
+        check=False,
+    )
+    return _flash_result(result)
+
+
+# -- UART capture -----------------------------------------------------------
+
+@mcp.tool()
+@_safe
+def capture_uart(
+    rx: int,
+    tx: int,
+    duration: float,
+    baud: int = 115200,
+    until_regex: Optional[str] = None,
+) -> dict:
+    """Capture the DUT's UART output for ``duration`` seconds.
+
+    ``rx`` is the LA channel the pod samples (wire the DUT's TX here); ``tx`` is
+    driven (the DUT's RX). ``until_regex`` (a Python regex) stops the capture
+    early on first match. Returns ``{text, lines, matched}``.
+    """
+    cap = SESSION.require().capture_uart(
+        rx=rx, tx=tx, baud=baud, duration=duration,
+        until=_compile_until(until_regex),
+    )
+    return {"text": cap.text, "lines": cap.lines, "matched": cap.matched}
+
+
+@mcp.tool()
+@_safe
+def power_cycle_and_capture(
+    rx: int,
+    tx: int,
+    efuse: int = 1,
+    delay: float = 1.0,
+    duration: float = 4.0,
+    baud: int = 115200,
+    until_regex: Optional[str] = None,
+    off_settle: float = 0.3,
+) -> dict:
+    """Power-cycle the target while capturing its boot output.
+
+    Powers ``efuse`` off, schedules a power-on ``delay`` seconds out (pod-side
+    timer), then captures UART for ``duration`` seconds so the boot banner lands
+    inside the window. ``duration`` should comfortably exceed ``delay``.
+    """
+    cap = SESSION.require().power_cycle_and_capture(
+        rx=rx, tx=tx, efuse=efuse, delay=delay, duration=duration, baud=baud,
+        until=_compile_until(until_regex), off_settle=off_settle,
+    )
+    return {"text": cap.text, "lines": cap.lines, "matched": cap.matched}
+
+
+# -- emulated I2C sensor ----------------------------------------------------
+
+@mcp.tool()
+@_safe
+def enable_i2c_sensor(
+    sda: int,
+    scl: int,
+    sensor: str = "bmp280",
+    address: int = 0x76,
+    temperature_c: Optional[float] = None,
+    pressure_pa: Optional[float] = None,
+) -> dict:
+    """Make the pod emulate an I2C sensor (e.g. BMP280) on ``sda``/``scl``.
+
+    The pod becomes an I2C slave the DUT's master can read. Enable pull-ups on
+    the SDA/SCL LA channels first (``enable_pullup``) so the open-drain bus idles
+    high. Optionally seed ``temperature_c``/``pressure_pa``.
+    """
+    return SESSION.require().enable_i2c_sensor(
+        sensor, sda=sda, scl=scl, address=address,
+        temperature_c=temperature_c, pressure_pa=pressure_pa,
+    )
+
+
+@mcp.tool()
+@_safe
+def set_i2c_sensor(temperature_c: Optional[float] = None,
+                   pressure_pa: Optional[float] = None) -> dict:
+    """Update the emulated sensor's reported values (at least one required)."""
+    return SESSION.require().set_i2c_sensor(
+        temperature_c=temperature_c, pressure_pa=pressure_pa
+    )
+
+
+@mcp.tool()
+@_safe
+def disable_i2c_sensor() -> dict:
+    """Disarm the emulated sensor (safe if none is active)."""
+    SESSION.require().disable_i2c_sensor()
+    return {"ok": True}
+
+
+@mcp.tool()
+@_safe
+def i2c_sensor_status() -> dict:
+    """Return sensor + I2C-bus activity counters (transactions, writes, …)."""
+    return SESSION.require().i2c_sensor_status()
+
+
+@mcp.tool()
+@_safe
+def i2c_sensor_regs(start: int = 0, length: int = 256) -> dict:
+    """Read the emulated sensor's register image."""
+    regs = SESSION.require().i2c_sensor_regs(start, length)
+    return {"start": start, "length": len(regs), "bytes": regs}
+
+
+@mcp.tool()
+@_safe
+def i2c_sensor_la_decoded(samples: int = 1024,
+                          sample_rate_mhz: Optional[float] = None) -> dict:
+    """Capture the I2C bus and decode it into a human-readable trace.
+
+    Returns a one-line-per-transaction ``trace`` (e.g.
+    ``S 0x76W+ 0xD0+ Sr 0x76R+ 0x58- P``), the transaction count, and the set of
+    addresses seen — not the raw sample array.
+    """
+    txns = SESSION.require().i2c_sensor_la_decoded(samples, sample_rate_mhz)
+    addrs = sorted({m.address for t in txns for m in t.messages if m.address is not None})
+    return {
+        "trace": i2c.format_transactions(txns),
+        "transactions": len(txns),
+        "addresses": [f"0x{a:02X}" for a in addrs],
+    }
+
+
+@mcp.tool()
+@_safe
+def i2c_read_register(
+    address: int,
+    register: int,
+    samples: int = 4096,
+    sample_rate_mhz: float = 0.5,
+) -> dict:
+    """Capture the I2C bus and return the bytes the DUT read from ``register``.
+
+    Decodes the live waveform and looks for a register-pointer write to
+    ``address`` followed by a read. Returns ``{value, addressed, trace}``;
+    ``value`` is ``null`` if that read pattern wasn't captured in the window.
+    """
+    txns = SESSION.require().i2c_sensor_la_decoded(samples, sample_rate_mhz)
+    return {
+        "value": i2c.read_register(txns, address, register),
+        "addressed": i2c.addressed(txns, address),
+        "trace": i2c.format_transactions(txns),
+    }
+
+
+# -- LA pin pull-ups (LA1-8) ------------------------------------------------
+
+@mcp.tool()
+@_safe
+def enable_pullup(las: List[int]) -> dict:
+    """Enable the fixed pull-up on one or more LA channels (LA1-8 only)."""
+    pod = SESSION.require()
+    pod.enable_pullup(*las)
+    return pod.pullup_status()
+
+
+@mcp.tool()
+@_safe
+def disable_pullup(las: List[int]) -> dict:
+    """Disable the pull-up on one or more LA channels (LA1-8 only)."""
+    pod = SESSION.require()
+    pod.disable_pullup(*las)
+    return pod.pullup_status()
+
+
+@mcp.tool()
+@_safe
+def pullup_status() -> dict:
+    """Return ``{"la_pullup_mask": <bitmask>}`` (bit la-1 set = pull-up on)."""
+    return SESSION.require().pullup_status()
+
+
+# -- low-level pass-throughs (TCP / serial-json) ----------------------------
+
+@mcp.tool()
+@_safe
+def command(request: Dict[str, Any]) -> Any:
+    """Send a raw JSON command to the pod (escape hatch).
+
+    ``request`` must include a ``cmd`` key, e.g. ``{"cmd": "status"}``. Use this
+    for firmware commands not covered by a dedicated tool.
+    """
+    return SESSION.require().command(request)
+
+
+@mcp.tool()
+@_safe
+def gpio_set(la: int, state: Union[int, str]) -> Any:
+    """Drive an LA channel: ``state`` 1 = high, 0 = low, ``"z"`` = high-Z."""
+    return SESSION.require().gpio_set(la, state)
+
+
+@mcp.tool()
+@_safe
+def capture_adc(samples: int = 256, sample_rate_mhz: Optional[float] = None) -> dict:
+    """Capture ADC samples; returns count/min/max and the first 32 values."""
+    data = SESSION.require().capture(samples, sample_rate_mhz=sample_rate_mhz)
+    return _summarize_samples(data)
+
+
+@mcp.tool()
+@_safe
+def signal_generate(
+    waveform: str,
+    freq: float,
+    amplitude: float,
+    offset: float = 0.0,
+    duration_ms: Optional[int] = None,
+    sample_rate_mhz: Optional[float] = None,
+) -> Any:
+    """Generate a DAC waveform (sine/square/sawtooth/…) on the analog output."""
+    req: dict = {"cmd": "generate", "waveform": waveform,
+                 "freq": freq, "amplitude": amplitude, "offset": offset}
+    if duration_ms is not None:
+        req["duration_ms"] = duration_ms
+    if sample_rate_mhz is not None:
+        req["sample_rate_mhz"] = sample_rate_mhz
+    return SESSION.require().command(req)
+
+
+@mcp.tool()
+@_safe
+def measure(
+    waveform: str,
+    freq: float,
+    amplitude: float,
+    offset: float = 0.0,
+    samples: int = 256,
+    sample_rate_mhz: Optional[float] = None,
+) -> dict:
+    """Drive the DAC and capture the ADC loopback; returns a sample summary."""
+    pod = SESSION.require()
+    fn = getattr(pod.transport, "samples", None)
+    if fn is None:
+        raise BenchPodError("measure is only available on the TCP transport")
+    req: dict = {"cmd": "measure", "waveform": waveform, "freq": freq,
+                 "amplitude": amplitude, "offset": offset, "samples": samples}
+    if sample_rate_mhz is not None:
+        req["sample_rate_mhz"] = sample_rate_mhz
+    return _summarize_samples(fn(req))
+
+
+# -- resources (read-only context for the agent) ----------------------------
+
+_WIRING = """\
+BenchPod LA channel wiring (defaults from the BMP280 HIL example).
+The pod's logic-analyzer channels (LA1-12) are wired to the DUT:
+
+  DUT signal                         Pod LA channel   eFuse / notes
+  ---------------------------------  --------------   -----------------------
+  SWCLK  (SWD clock)                 LA11
+  SWDIO  (SWD data)                  LA12
+  NRST   (optional reset)            LA3
+  UART: DUT TX  -> pod samples       LA5              (capture_uart rx)
+  UART: DUT RX  <- pod drives        LA4              (capture_uart tx)
+  I2C SDA                            LA2              4.7k pull-up (LA1/2)
+  I2C SCL                            LA1              4.7k pull-up (LA1/2)
+  Target 5V power                    eFuse 1          1=internal 5V, 2=external
+
+Pull-ups exist only on LA1-8 (LA1/2=4.7k, LA3/4=2.2k, LA5-8=10k); enable them on
+the I2C SDA/SCL channels so the open-drain bus idles high before arming the
+emulated sensor. These are bench defaults — confirm against the actual wiring.
+"""
+
+_HELP = """\
+This server drives an EmbeddedCI BenchPod (hardware-in-the-loop tester) so you
+can power, flash, and probe a real target board.
+
+Typical workflow:
+  1. connect(connection)            — open the pod (host[:port], /dev/tty*, or 'serial')
+  2. flash(swclk, swdio, nreset,    — program the DUT over SWD
+           target, file, ...)         (over serial bit-bang use verify=false)
+  3. enable_pullup([sda, scl])      — for I2C work, idle the bus high
+     enable_i2c_sensor(sda, scl)    — have the pod emulate a sensor
+  4. power_cycle_and_capture(rx, tx,— reboot the DUT and capture its boot log
+           delay, duration, until_regex)
+  5. i2c_sensor_status() /          — confirm the DUT actually probed the bus
+     i2c_read_register(addr, reg)
+
+Errors come back as {"ok": false, "error": ..., "error_type": ...} rather than
+raising. See the benchpod://wiring resource for the LA channel pin map.
+"""
+
+
+@mcp.resource("benchpod://wiring")
+def wiring() -> str:
+    """Default LA channel → DUT signal pin map and eFuse table."""
+    return _WIRING
+
+
+@mcp.resource("benchpod://help")
+def help_() -> str:
+    """How to drive a HIL run with these tools (canonical workflow order)."""
+    return _HELP

embeddedci_mcp-0.1.0/src/embeddedci_mcp/session.py

@@ -0,0 +1,66 @@
+"""A single, process-wide BenchPod connection shared across MCP tool calls.
+
+The MCP server process is long-lived, but each tool invocation is independent.
+We hold the connected :class:`~embeddedci.benchpod.BenchPod` in one module-level
+:class:`Session` so an agent can ``connect`` once and then ``flash``/``capture``/…
+against the same device. Tools call :meth:`Session.require` to get the live pod
+(or a clear "connect first" error).
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from embeddedci.benchpod import BenchPod
+from embeddedci.benchpod.errors import BenchPodError
+
+
+class NotConnectedError(BenchPodError):
+    """Raised when a tool needs the device but ``connect`` was never called."""
+
+
+class Session:
+    """Holds at most one open BenchPod connection."""
+
+    def __init__(self) -> None:
+        self._pod: Optional[BenchPod] = None
+        #: Default connection used by ``connect`` when called with no argument
+        #: (set from the ``--connection`` CLI flag). ``None`` falls back to the
+        #: ``BENCHPOD_CONNECTION`` environment variable.
+        self.default_connection: Optional[str] = None
+        self.timeout: float = 30.0
+
+    @property
+    def connected(self) -> bool:
+        return self._pod is not None
+
+    def connect(self, connection: Optional[str] = None,
+                *, timeout: Optional[float] = None) -> BenchPod:
+        """Open (or re-open) the device, closing any prior connection first."""
+        self.disconnect()
+        conn = connection or self.default_connection
+        self._pod = BenchPod(
+            conn, timeout=self.timeout if timeout is None else timeout
+        )
+        return self._pod
+
+    def require(self) -> BenchPod:
+        """Return the live pod, or raise if not connected."""
+        if self._pod is None:
+            raise NotConnectedError(
+                "not connected to a BenchPod — call the `connect` tool first"
+            )
+        return self._pod
+
+    def disconnect(self) -> None:
+        """Close the device if one is open (idempotent)."""
+        if self._pod is not None:
+            try:
+                self._pod.close()
+            except Exception:
+                pass
+            self._pod = None
+
+
+#: The one shared session for this server process.
+SESSION = Session()

embeddedci_mcp-0.1.0/tests/conftest.py

@@ -0,0 +1,137 @@
+"""Test fixtures: a fake Transport injected into a real BenchPod.
+
+The MCP tools call ``embeddedci.benchpod.BenchPod`` methods; we exercise them
+with no hardware by giving BenchPod a :class:`FakeTransport` (which implements
+the Transport ABC plus the JSON ``command``/``samples`` extras) and a
+:class:`FakeRawLink` for UART/SWD byte streams.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import pytest
+
+from embeddedci.benchpod import BenchPod
+from embeddedci.benchpod.transport.base import Transport
+
+from embeddedci_mcp.session import SESSION
+
+
+class FakeRawLink:
+    """A bounded byte stream: yields ``data`` once, then EOF (``b""``)."""
+
+    def __init__(self, data: bytes = b"") -> None:
+        self._buf = bytearray(data)
+        self.written = bytearray()
+        self.closed = False
+
+    def read(self, n: int) -> bytes:
+        if self.closed or not self._buf:
+            return b""
+        chunk = bytes(self._buf[:n])
+        del self._buf[:n]
+        return chunk
+
+    def write(self, data: bytes) -> int:
+        self.written += data
+        return len(data)
+
+    def close(self) -> None:
+        self.closed = True
+
+
+class FakeTransport(Transport):
+    """In-memory pod that answers the high-level + JSON-command surface."""
+
+    def __init__(self) -> None:
+        self.power: dict[int, bool] = {}
+        self.calls: list[tuple] = []
+        self.uart_data = b"boot\r\nAPP_OK\r\n"
+        self._sensor: dict[str, Any] = {"active": False}
+        self._regs = list(range(256))
+
+    # -- Transport ABC --
+    def status(self) -> Any:
+        return {"version": "fake-1.0",
+                "caps": ["signal", "gpio", "power", "swd", "i2c_sensor", "uart"]}
+
+    def ping(self) -> Any:
+        return "pong"
+
+    def target_power(self, efuse: int, on: bool, delay_ms: int = 0) -> None:
+        self.power[efuse] = on
+        self.calls.append(("target_power", efuse, on, delay_ms))
+
+    def swd_start(self, swclk: int, swdio: int, nreset: Optional[int]):
+        return FakeRawLink()
+
+    def uart_proxy_start(self, rx: int, tx: int, baud: int):
+        return FakeRawLink(self.uart_data)
+
+    def close(self) -> None:
+        self.calls.append(("close",))
+
+    # -- JSON command extras (TCP / serial-json) --
+    def command(self, req: dict) -> Any:
+        cmd = req.get("cmd")
+        self.calls.append(("command", cmd))
+        if cmd in ("status", "ping"):
+            return self.status() if cmd == "status" else "pong"
+        if cmd == "sensor_start":
+            self._sensor = {"active": True, "type": req["type"], "addr": req["addr"],
+                            "transactions": 0}
+            return {"type": req["type"], "addr": req["addr"]}
+        if cmd == "sensor_set":
+            return {"type": "bmp280"}
+        if cmd == "sensor_stop":
+            self._sensor = {"active": False}
+            return None
+        if cmd == "sensor_status":
+            return {"active": self._sensor.get("active", False), "transactions": 3}
+        if cmd == "pullup":
+            return {"la": req["la"],
+                    "pullup": 1 if req.get("state") == "on" else 0, "ohms": "4.7k"}
+        if cmd == "pullup_status":
+            return {"la_pullup_mask": 3}
+        if cmd == "target_status":
+            return {"efuse1": {"enabled": 1, "fault": 0, "valid": 1}}
+        if cmd == "gpio_set":
+            return {"la": req["la"], "state": req["state"]}
+        if cmd == "generate":
+            return None
+        return None
+
+    def samples(self, req: dict) -> list:
+        cmd = req.get("cmd")
+        self.calls.append(("samples", cmd))
+        if cmd == "sensor_regs":
+            return self._regs[: req.get("len", 256)]
+        if cmd == "sensor_la":
+            return []
+        if cmd == "measure":
+            return [10, 20, 30, 40]
+        if cmd == "capture":
+            return list(range(req.get("samples", 4)))
+        return []
+
+
+@pytest.fixture(autouse=True)
+def _reset_session():
+    """Each test starts with a clean, disconnected session."""
+    SESSION.disconnect()
+    SESSION.default_connection = None
+    yield
+    SESSION.disconnect()
+
+
+@pytest.fixture
+def fake_transport() -> FakeTransport:
+    return FakeTransport()
+
+
+@pytest.fixture
+def connected(fake_transport: FakeTransport) -> FakeTransport:
+    """A session connected to a BenchPod backed by the fake transport."""
+    SESSION._pod = BenchPod(transport=fake_transport)
+    return fake_transport

embeddedci_mcp-0.1.0/tests/test_tools.py

@@ -0,0 +1,192 @@
+"""Exercise the MCP tools without hardware (fake transport injected)."""
+
+from __future__ import annotations
+
+import asyncio
+
+from embeddedci.benchpod import BenchPod
+from embeddedci.benchpod.connection import ConnSpec
+from embeddedci.benchpod.flash import FlashResult
+
+import embeddedci.benchpod.connection as conn_mod
+import embeddedci_mcp.session as session_mod
+from embeddedci_mcp import server
+from embeddedci_mcp.session import SESSION
+
+
+# -- not connected ----------------------------------------------------------
+
+def test_tool_before_connect_returns_structured_error():
+    result = server.ping()
+    assert result["ok"] is False
+    assert result["error_type"] == "NotConnectedError"
+    assert "connect" in result["error"].lower()
+
+
+# -- connect ----------------------------------------------------------------
+
+def test_connect_reports_status(monkeypatch, fake_transport):
+    monkeypatch.setattr(
+        session_mod, "BenchPod",
+        lambda conn, timeout=30.0: BenchPod(transport=fake_transport),
+    )
+    monkeypatch.setattr(
+        conn_mod, "resolve_connection",
+        lambda c: ConnSpec(kind="tcp", addr="1.2.3.4:8080"),
+    )
+    result = server.connect("1.2.3.4")
+    assert result["connected"] is True
+    assert result["kind"] == "tcp"
+    assert result["target"] == "1.2.3.4:8080"
+    assert result["status"]["version"] == "fake-1.0"
+    assert SESSION.connected
+
+
+def test_disconnect(connected):
+    assert SESSION.connected
+    assert server.disconnect() == {"connected": False}
+    assert not SESSION.connected
+    # idempotent: disconnecting again is safe
+    assert server.disconnect() == {"connected": False}
+
+
+# -- status / ping ----------------------------------------------------------
+
+def test_ping(connected):
+    assert server.ping() == {"ping": "pong"}
+
+
+def test_status(connected):
+    assert server.status()["version"] == "fake-1.0"
+
+
+# -- power ------------------------------------------------------------------
+
+def test_power_on_off(connected):
+    on = server.power_on(efuse=1)
+    assert on["ok"] is True and on["on"] is True
+    assert connected.power[1] is True
+
+    off = server.power_off(efuse=1)
+    assert off["on"] is False
+    assert connected.power[1] is False
+
+
+def test_target_power_explicit(connected):
+    assert server.target_power(efuse=2, on=True, delay=0.5)["efuse"] == 2
+    assert connected.power[2] is True
+
+
+def test_target_status(connected):
+    assert server.target_status()["efuse1"]["enabled"] == 1
+
+
+# -- flash ------------------------------------------------------------------
+
+def test_flash_serializes_result(connected, monkeypatch):
+    monkeypatch.setattr(
+        SESSION._pod, "flash",
+        lambda **kw: FlashResult(ok=True, returncode=0,
+                                 stdout="Programming Finished", stderr=""),
+    )
+    result = server.flash(swclk=11, swdio=12, nreset=3,
+                          target="target/stm32f4x.cfg", file="fw.elf")
+    assert result["ok"] is True
+    assert result["returncode"] == 0
+    assert "Programming Finished" in result["stdout_tail"]
+    assert result["target_unreachable"] is False
+
+
+# -- UART -------------------------------------------------------------------
+
+def test_capture_uart_matches(connected):
+    result = server.capture_uart(rx=5, tx=4, duration=1.0, until_regex="APP_OK")
+    assert result["matched"] is True
+    assert "APP_OK" in result["text"]
+    assert "APP_OK" in result["lines"]
+
+
+def test_power_cycle_and_capture(connected):
+    result = server.power_cycle_and_capture(
+        rx=5, tx=4, efuse=1, delay=0.0, duration=1.0, until_regex="APP_OK",
+        off_settle=0.0,
+    )
+    assert result["matched"] is True
+    # power was cycled off then scheduled back on
+    assert ("target_power", 1, False, 0) in connected.calls
+
+
+# -- I2C sensor -------------------------------------------------------------
+
+def test_i2c_sensor_lifecycle(connected):
+    started = server.enable_i2c_sensor(sda=2, scl=1, temperature_c=22.5,
+                                       pressure_pa=101000)
+    assert started["type"] == "bmp280"
+    status = server.i2c_sensor_status()
+    assert status["active"] is True
+    assert status["transactions"] == 3
+    assert server.disable_i2c_sensor() == {"ok": True}
+
+
+def test_i2c_sensor_regs_summary(connected):
+    regs = server.i2c_sensor_regs(start=0, length=8)
+    assert regs["length"] == 8
+    assert regs["bytes"] == list(range(8))
+
+
+# -- pull-ups ---------------------------------------------------------------
+
+def test_pullups(connected):
+    assert server.enable_pullup([1, 2])["la_pullup_mask"] == 3
+    assert server.disable_pullup([1, 2])["la_pullup_mask"] == 3
+    assert server.pullup_status()["la_pullup_mask"] == 3
+
+
+# -- low-level --------------------------------------------------------------
+
+def test_command_escape_hatch(connected):
+    assert server.command({"cmd": "status"})["version"] == "fake-1.0"
+
+
+def test_capture_adc_summary(connected):
+    summary = server.capture_adc(samples=4)
+    assert summary["count"] == 4
+    assert summary["head"] == [0, 1, 2, 3]
+    assert summary["min"] == 0 and summary["max"] == 3
+
+
+def test_measure_summary(connected):
+    summary = server.measure(waveform="sine", freq=1000, amplitude=1.0, samples=4)
+    assert summary["count"] == 4
+    assert summary["max"] == 40
+
+
+# -- tool / resource registration ------------------------------------------
+
+def test_all_tools_registered():
+    tools = asyncio.run(server.mcp.list_tools())
+    names = {t.name for t in tools}
+    expected = {
+        "connect", "disconnect", "ping", "status",
+        "power_on", "power_off", "target_power", "target_status",
+        "flash", "capture_uart", "power_cycle_and_capture",
+        "enable_i2c_sensor", "set_i2c_sensor", "disable_i2c_sensor",
+        "i2c_sensor_status", "i2c_sensor_regs", "i2c_sensor_la_decoded",
+        "i2c_read_register",
+        "enable_pullup", "disable_pullup", "pullup_status",
+        "command", "gpio_set", "capture_adc", "signal_generate", "measure",
+    }
+    assert expected <= names
+
+    # the flash tool's schema exposes its key parameters
+    flash = next(t for t in tools if t.name == "flash")
+    props = flash.inputSchema["properties"]
+    for param in ("swclk", "swdio", "nreset", "target", "file", "verify"):
+        assert param in props
+
+
+def test_resources_registered():
+    resources = asyncio.run(server.mcp.list_resources())
+    uris = {str(r.uri) for r in resources}
+    assert "benchpod://wiring" in uris
+    assert "benchpod://help" in uris