platformio.mcp 0.1.0__py3-none-any.whl

platformio_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""PlatformIO MCP server: gives AI coding agents hands on real embedded hardware."""
+
+__version__ = "0.1.0"

platformio_mcp/cli.py

@@ -0,0 +1,132 @@
+"""`platformio.mcp` command line: serve (default), install, doctor."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import platform
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from . import __version__
+
+CLIENTS = ("claude-code", "claude-desktop", "cursor", "codex", "windsurf", "print")
+
+
+def server_command(with_platformio: bool, policy: str | None) -> dict:
+    pkg = 'platformio.mcp[platformio]' if with_platformio else "platformio.mcp"
+    entry = {"command": "uvx", "args": [pkg]}
+    if policy:
+        entry["env"] = {"PLATFORMIO_MCP_POLICY": policy}
+    return entry
+
+
+def _merge_json(path: Path, key_path: list[str], entry: dict) -> None:
+    data = {}
+    if path.exists():
+        try:
+            data = json.loads(path.read_text(encoding="utf-8") or "{}")
+        except json.JSONDecodeError as exc:
+            sys.exit(f"{path} is not valid JSON ({exc}); fix it or add the entry by hand:\n{json.dumps(entry, indent=2)}")
+    node = data
+    for key in key_path[:-1]:
+        node = node.setdefault(key, {})
+    node[key_path[-1]] = entry
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+
+
+def claude_desktop_config() -> Path:
+    system = platform.system()
+    if system == "Darwin":
+        return Path.home() / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json"
+    if system == "Windows":
+        return Path(os.environ.get("APPDATA", Path.home() / "AppData" / "Roaming")) / "Claude" / "claude_desktop_config.json"
+    return Path.home() / ".config" / "Claude" / "claude_desktop_config.json"
+
+
+def install(client: str, with_platformio: bool, policy: str | None, scope: str) -> None:
+    entry = server_command(with_platformio, policy)
+    if client == "print":
+        print(json.dumps({"mcpServers": {"platformio": entry}}, indent=2))
+        return
+    if client == "claude-code":
+        claude = shutil.which("claude")
+        if not claude:
+            sys.exit("`claude` CLI not found on PATH. Install Claude Code, or run: uvx platformio.mcp install --print")
+        cmd = [claude, "mcp", "add", "--scope", scope, "--transport", "stdio"]
+        for k, v in entry.get("env", {}).items():
+            cmd += ["--env", f"{k}={v}"]
+        cmd += ["platformio", "--", entry["command"], *entry["args"]]
+        print("$ " + " ".join(cmd))
+        subprocess.run(cmd, check=False)
+        return
+    if client == "claude-desktop":
+        path = claude_desktop_config()
+        _merge_json(path, ["mcpServers", "platformio"], entry)
+        print(f"Added 'platformio' to {path}. Restart Claude Desktop.")
+        return
+    if client == "cursor":
+        path = Path.home() / ".cursor" / "mcp.json" if scope == "user" else Path.cwd() / ".cursor" / "mcp.json"
+        _merge_json(path, ["mcpServers", "platformio"], entry)
+        print(f"Added 'platformio' to {path}. Reload Cursor's MCP settings.")
+        return
+    if client == "windsurf":
+        path = Path.home() / ".codeium" / "windsurf" / "mcp_config.json"
+        _merge_json(path, ["mcpServers", "platformio"], entry)
+        print(f"Added 'platformio' to {path}. Restart Windsurf.")
+        return
+    if client == "codex":
+        path = Path.home() / ".codex" / "config.toml"
+        block = "\n[mcp_servers.platformio]\ncommand = \"uvx\"\nargs = [" + ", ".join(json.dumps(a) for a in entry["args"]) + "]\n"
+        if entry.get("env"):
+            block += "[mcp_servers.platformio.env]\n" + "".join(f'{k} = "{v}"\n' for k, v in entry["env"].items())
+        existing = path.read_text(encoding="utf-8") if path.exists() else ""
+        if "[mcp_servers.platformio]" in existing:
+            print(f"{path} already has [mcp_servers.platformio]; edit it by hand if needed:\n{block}")
+            return
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(existing.rstrip("\n") + "\n" + block, encoding="utf-8")
+        print(f"Appended [mcp_servers.platformio] to {path}. Restart Codex.")
+        return
+    sys.exit(f"unknown client {client}; choose from {', '.join(CLIENTS)}")
+
+
+def doctor() -> None:
+    from .tools.system import pio_system_info
+
+    print(json.dumps(pio_system_info(), indent=2))
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(prog="platformio.mcp", description="MCP server for PlatformIO. With no subcommand it serves over stdio.")
+    parser.add_argument("--version", action="version", version=f"platformio.mcp {__version__}")
+    sub = parser.add_subparsers(dest="cmd")
+    sub.add_parser("serve", help="run the MCP server on stdio (default)")
+    p_install = sub.add_parser("install", help="register this server with an MCP client")
+    p_install.add_argument("--client", choices=CLIENTS, help="which client to configure")
+    for c in CLIENTS:
+        p_install.add_argument(f"--{c}", dest="client", action="store_const", const=c, help=f"shortcut for --client {c}")
+    p_install.add_argument("--with-platformio", action="store_true", help="bundle PlatformIO Core via the [platformio] extra so nothing else needs installing")
+    p_install.add_argument("--policy", choices=("full", "build_only", "read_only"), help="set PLATFORMIO_MCP_POLICY for the server")
+    p_install.add_argument("--scope", choices=("user", "project"), default="user", help="where the client stores the config (claude-code, cursor)")
+    sub.add_parser("doctor", help="print pio_system_info as JSON")
+
+    args = parser.parse_args(argv)
+    if args.cmd == "install":
+        if not args.client:
+            p_install.error("choose a client, e.g. --claude-code, --cursor, --claude-desktop, --codex, --windsurf, or --print")
+        install(args.client, args.with_platformio, args.policy, args.scope)
+    elif args.cmd == "doctor":
+        doctor()
+    else:
+        from .server import serve
+
+        serve()
+
+
+if __name__ == "__main__":
+    main()

platformio_mcp/core.py

@@ -0,0 +1,113 @@
+"""Shared state and helpers used by every tool module."""
+
+from __future__ import annotations
+
+import functools
+import json
+import os
+import re
+from collections.abc import Callable
+from typing import Any
+
+from .monitor import MonitorManager
+from .pio import PioNotFound, PioResult, resolve_project_dir, run_pio
+
+POLICIES = ("full", "build_only", "read_only")
+
+monitors = MonitorManager()
+
+ToolFn = Callable[..., dict[str, Any]]
+
+
+class PolicyError(PermissionError):
+    pass
+
+
+def policy() -> str:
+    value = os.environ.get("PLATFORMIO_MCP_POLICY", "full").strip().lower()
+    return value if value in POLICIES else "full"
+
+
+def check_policy(action: str) -> None:
+    """action is 'build' (compiles, installs packages, edits project) or 'flash' (touches hardware state)."""
+    current = policy()
+    if current == "read_only" and action in ("build", "flash"):
+        raise PolicyError(f"PLATFORMIO_MCP_POLICY=read_only blocks '{action}' actions. Only listing and inspection tools are allowed.")
+    if current == "build_only" and action == "flash":
+        raise PolicyError("PLATFORMIO_MCP_POLICY=build_only blocks flashing, erasing, and writing to devices. Builds and tests without upload still work.")
+
+
+def guard(fn: ToolFn) -> ToolFn:
+    """Turn expected failures into a structured {ok: false} result instead of a protocol error."""
+
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> dict[str, Any]:
+        try:
+            return fn(*args, **kwargs)
+        except PioNotFound as exc:
+            return {"ok": False, "error": "pio_not_found", "summary": str(exc)}
+        except PolicyError as exc:
+            return {"ok": False, "error": "policy_denied", "summary": str(exc), "policy": policy()}
+        except FileNotFoundError as exc:
+            return {"ok": False, "error": "not_found", "summary": str(exc)}
+        except re.error as exc:
+            return {"ok": False, "error": "bad_regex", "summary": f"invalid regular expression '{exc.pattern}': {exc.msg} (position {exc.pos})."}
+        except (KeyError, ValueError, RuntimeError, OSError) as exc:
+            return {"ok": False, "error": type(exc).__name__, "summary": str(exc)}
+        except Exception as exc:  # last resort: a structured failure beats a bare "Error executing tool"
+            return {"ok": False, "error": type(exc).__name__, "summary": f"{type(exc).__name__}: {exc}"}
+
+    return wrapper
+
+
+def run_json(args: list[str], cwd: str | None = None, timeout: float | None = None, tool: str = "pio") -> tuple[PioResult, Any]:
+    """Run a pio command that supports --json-output and parse it."""
+    res = run_pio(args, cwd=cwd, timeout=timeout, tool=tool)
+    if not res.ok:
+        raise RuntimeError(f"`pio {' '.join(args)}` failed (exit {res.returncode}). Output:\n{res.output[-2000:]}")
+    text = res.output.strip()
+    # pio sometimes prints warnings before the JSON payload; find the first bracket/brace.
+    start = min([i for i in (text.find("["), text.find("{")) if i >= 0], default=-1)
+    if start < 0:
+        raise RuntimeError(f"`pio {' '.join(args)}` returned no JSON. Output:\n{text[-1000:]}")
+    try:
+        return res, json.loads(text[start:])
+    except json.JSONDecodeError as exc:
+        raise RuntimeError(f"could not parse JSON from `pio {' '.join(args)}`: {exc}. See {res.log_path}") from exc
+
+
+def project_config(project_dir: str | None) -> dict[str, dict[str, Any]]:
+    """`pio project config --json-output` as {section: {key: value}}."""
+    path = resolve_project_dir(project_dir)
+    _, data = run_json(["project", "config", "--json-output"], cwd=str(path), tool="project-config")
+    out: dict[str, dict[str, Any]] = {}
+    for section, items in data:
+        out[section] = {k: v for k, v in items}
+    return out
+
+
+def env_names(config: dict[str, dict[str, Any]]) -> list[str]:
+    return [s[4:] for s in config if s.startswith("env:")]
+
+
+def default_envs(config: dict[str, dict[str, Any]]) -> list[str]:
+    raw = config.get("platformio", {}).get("default_envs")
+    if not raw:
+        return env_names(config)
+    if isinstance(raw, str):
+        return [e.strip() for e in raw.replace("\n", ",").split(",") if e.strip()]
+    return list(raw)
+
+
+def env_setting(config: dict[str, dict[str, Any]], env: str, key: str, default: Any = None) -> Any:
+    """Look a key up in [env:x], following one level of `extends`, then [env]."""
+    section = config.get(f"env:{env}", {})
+    if key in section:
+        return section[key]
+    bases = section.get("extends") or []
+    if isinstance(bases, str):
+        bases = [b.strip() for b in bases.replace("\n", ",").split(",") if b.strip()]
+    for base in bases:
+        if key in config.get(base, {}):
+            return config[base][key]
+    return config.get("env", {}).get(key, default)

platformio_mcp/monitor.py

@@ -0,0 +1,211 @@
+"""Background serial monitor sessions with a bounded ring buffer and cursor-based reads.
+
+`pio device monitor` refuses to run without an interactive terminal, so sessions talk to the
+port directly with pyserial. Lines are numbered from 0; a cursor is "the next line index I have
+not seen", so `read(cursor=0)` returns everything still in the buffer.
+"""
+
+from __future__ import annotations
+
+import re
+import threading
+import time
+import uuid
+from collections import deque
+from dataclasses import dataclass, field
+from typing import Protocol
+
+
+class ByteSource(Protocol):
+    """What a session needs from a port: pyserial's Serial satisfies it, so do test fakes."""
+
+    def read(self, size: int = 1) -> bytes: ...
+    def write(self, data: bytes) -> int | None: ...
+    def close(self) -> None: ...
+
+
+@dataclass
+class Session:
+    id: str
+    port: str
+    baud: int
+    source: ByteSource
+    max_lines: int = 5000
+    lines: deque[str] = field(init=False)
+    first_index: int = 0  # absolute index of lines[0]
+    next_index: int = 0  # absolute index the next appended line will get
+    partial: str = ""
+    error: str | None = None
+    closed: bool = False
+    started_at: float = field(default_factory=time.time)
+    bytes_received: int = 0
+    lock: threading.Lock = field(default_factory=threading.Lock)
+    changed: threading.Condition = field(init=False)
+    thread: threading.Thread | None = None
+
+    def __post_init__(self) -> None:
+        self.lines = deque(maxlen=self.max_lines)
+        self.changed = threading.Condition(self.lock)
+
+    def _append(self, line: str) -> None:
+        # Must hold self.lock.
+        if len(self.lines) == self.lines.maxlen:
+            self.first_index += 1
+        self.lines.append(line)
+        self.next_index += 1
+
+    def feed(self, data: bytes) -> None:
+        text = data.decode("utf-8", errors="replace")
+        with self.changed:
+            self.bytes_received += len(data)
+            buf = self.partial + text
+            parts = buf.replace("\r\n", "\n").replace("\r", "\n").split("\n")
+            self.partial = parts.pop()
+            for p in parts:
+                self._append(p)
+            self.changed.notify_all()
+
+    def _reader(self) -> None:
+        try:
+            while not self.closed:
+                data = self.source.read(4096)
+                if data:
+                    self.feed(data)
+                else:
+                    time.sleep(0.01)
+        except Exception as exc:  # port unplugged, permission lost, fake exhausted
+            with self.changed:
+                self.error = f"{type(exc).__name__}: {exc}"
+                self.closed = True
+                self.changed.notify_all()
+
+    def start(self) -> None:
+        self.thread = threading.Thread(target=self._reader, name=f"pio-monitor-{self.id}", daemon=True)
+        self.thread.start()
+
+    def read(self, cursor: int = 0, max_lines: int = 200, wait_for: str | None = None, timeout_s: float = 0) -> dict:
+        pattern = re.compile(wait_for) if wait_for else None
+        deadline = time.monotonic() + max(timeout_s, 0)
+        with self.changed:
+            while True:
+                start = max(cursor, self.first_index)
+                available = self.next_index - start
+                new = list(self.lines)[start - self.first_index : start - self.first_index + max(available, 0)] if available > 0 else []
+                matched = None
+                if pattern:
+                    for i, line in enumerate(new):
+                        if pattern.search(line):
+                            matched = start + i
+                            new = new[: i + 1]
+                            break
+                if pattern and matched is None and not self.closed:
+                    remaining = deadline - time.monotonic()
+                    if remaining > 0:
+                        self.changed.wait(timeout=remaining)
+                        continue
+                if not pattern and not new and timeout_s > 0 and not self.closed:
+                    remaining = deadline - time.monotonic()
+                    if remaining > 0:
+                        self.changed.wait(timeout=remaining)
+                        continue
+                truncated = len(new) > max_lines
+                new = new[:max_lines]
+                next_cursor = start + len(new)
+                return {
+                    "session_id": self.id,
+                    "lines": new,
+                    "cursor": next_cursor,
+                    "dropped_before_cursor": max(0, self.first_index - cursor) if cursor < self.first_index else 0,
+                    "more_available": truncated or next_cursor < self.next_index,
+                    "matched": matched is not None,
+                    "matched_line": matched,
+                    "partial_line": self.partial,
+                    "closed": self.closed,
+                    "error": self.error,
+                }
+
+    def write(self, text: str, newline: bool = True) -> int:
+        if self.closed:
+            raise RuntimeError(f"session {self.id} is closed")
+        data = (text + ("\n" if newline else "")).encode("utf-8")
+        self.source.write(data)
+        return len(data)
+
+    def stop(self) -> None:
+        with self.changed:
+            self.closed = True
+            self.changed.notify_all()
+        try:
+            self.source.close()
+        except Exception:
+            pass
+        if self.thread and self.thread is not threading.current_thread():
+            self.thread.join(timeout=2)
+
+    def info(self) -> dict:
+        with self.lock:
+            return {
+                "session_id": self.id,
+                "port": self.port,
+                "baud": self.baud,
+                "lines_buffered": len(self.lines),
+                "next_cursor": self.next_index,
+                "bytes_received": self.bytes_received,
+                "uptime_s": round(time.time() - self.started_at, 1),
+                "closed": self.closed,
+                "error": self.error,
+            }
+
+
+def open_serial(port: str, baud: int) -> ByteSource:
+    import serial  # pyserial
+
+    return serial.Serial(port, baudrate=baud, timeout=0.2)
+
+
+class MonitorManager:
+    def __init__(self, opener=open_serial, max_lines: int = 5000) -> None:
+        self._sessions: dict[str, Session] = {}
+        self._lock = threading.Lock()
+        self._opener = opener
+        self._max_lines = max_lines
+
+    def start(self, port: str, baud: int) -> Session:
+        with self._lock:
+            for s in self._sessions.values():
+                if s.port == port and not s.closed:
+                    raise RuntimeError(f"port {port} is already open in session {s.id}; stop it first")
+            source = self._opener(port, baud)
+            session = Session(id=uuid.uuid4().hex[:8], port=port, baud=baud, source=source, max_lines=self._max_lines)
+            self._sessions[session.id] = session
+            session.start()
+            return session
+
+    def get(self, session_id: str) -> Session:
+        s = self._sessions.get(session_id)
+        if s is None:
+            raise KeyError(f"unknown session {session_id}; call pio_monitor_list")
+        return s
+
+    def stop(self, session_id: str) -> dict:
+        s = self.get(session_id)
+        s.stop()
+        with self._lock:
+            self._sessions.pop(session_id, None)
+        return s.info()
+
+    def stop_all(self) -> None:
+        for sid in list(self._sessions):
+            try:
+                self.stop(sid)
+            except Exception:
+                pass
+
+    def list(self) -> list[dict]:
+        return [s.info() for s in self._sessions.values()]
+
+    def session_on_port(self, port: str) -> Session | None:
+        for s in self._sessions.values():
+            if s.port == port and not s.closed:
+                return s
+        return None

platformio_mcp/parsers.py

@@ -0,0 +1,186 @@
+"""Parsers for the parts of PlatformIO output that have no --json-output."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import asdict, dataclass
+
+DIAG_RE = re.compile(
+    r"^(?P<file>[^\s:][^:\n]*?):(?P<line>\d+):(?:(?P<col>\d+):)?\s*(?P<kind>fatal error|error|warning|note):\s*(?P<msg>.*)$",
+    re.MULTILINE,
+)
+LINKER_RE = re.compile(r"^.*?(undefined reference to .*|symbol\(s\) not found.*|multiple definition of .*|region .* overflowed by .*)$", re.MULTILINE)
+SCONS_ERR_RE = re.compile(r"^\*\*\* \[(?P<target>[^\]]+)\] (?P<msg>.*)$", re.MULTILINE)
+MEM_RE = re.compile(r"^(?P<kind>RAM|Flash):\s+\[[=\s]*\]\s+(?P<pct>[\d.]+)%\s+\(used (?P<used>\d+) bytes from (?P<total>\d+) bytes\)", re.MULTILINE)
+RESULT_RE = re.compile(r"^=+ \[(?P<status>SUCCESS|FAILED|ERROR)\] Took (?P<secs>[\d.]+) seconds =+$", re.MULTILINE)
+ENV_RE = re.compile(r"^Processing (?P<env>\S+) \(", re.MULTILINE)
+PKG_SEARCH_HEAD_RE = re.compile(r"^Found (?P<total>\d+) packages \(page (?P<page>\d+) of (?P<pages>\d+)\)", re.MULTILINE)
+PKG_LINE_RE = re.compile(r"^(?P<indent>[\s│├└─]*)(?P<kind>Platform|Tool|Library)?\s*(?P<spec>[\w.@:/ -]+?) @ (?P<version>[^\s(]+)(?: \((?P<req>[^)]*)\))?\s*$")
+
+
+@dataclass
+class Diagnostic:
+    kind: str
+    file: str
+    line: int
+    column: int | None
+    message: str
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def parse_diagnostics(text: str) -> list[Diagnostic]:
+    """Extract compiler errors/warnings/notes, linker errors, and SCons failure lines."""
+    diags: list[Diagnostic] = []
+    seen: set[tuple] = set()
+    for m in DIAG_RE.finditer(text):
+        key = (m["file"], m["line"], m["col"], m["kind"], m["msg"])
+        if key in seen:
+            continue
+        seen.add(key)
+        diags.append(Diagnostic(kind=m["kind"].replace("fatal ", ""), file=m["file"], line=int(m["line"]), column=int(m["col"]) if m["col"] else None, message=m["msg"].strip()))
+    for m in LINKER_RE.finditer(text):
+        msg = m.group(1).strip()
+        key = ("linker", msg)
+        if key in seen:
+            continue
+        seen.add(key)
+        diags.append(Diagnostic(kind="error", file="<linker>", line=0, column=None, message=msg))
+    for m in SCONS_ERR_RE.finditer(text):
+        key = ("scons", m["target"], m["msg"])
+        if key in seen:
+            continue
+        seen.add(key)
+        diags.append(Diagnostic(kind="error", file=m["target"], line=0, column=None, message=f"build step failed: {m['msg']}"))
+    return diags
+
+
+def parse_memory(text: str) -> dict[str, dict]:
+    """Return {'ram': {...}, 'flash': {...}} from the size report lines, if present."""
+    out: dict[str, dict] = {}
+    for m in MEM_RE.finditer(text):
+        out[m["kind"].lower()] = {"percent": float(m["pct"]), "used_bytes": int(m["used"]), "total_bytes": int(m["total"])}
+    return out
+
+
+def parse_build_result(text: str) -> dict:
+    """Overall status, duration, and environments seen in a `pio run` log."""
+    statuses = [(m["status"], float(m["secs"])) for m in RESULT_RE.finditer(text)]
+    envs = ENV_RE.findall(text)
+    status = "unknown"
+    if statuses:
+        status = "failed" if any(s != "SUCCESS" for s, _ in statuses) else "success"
+    return {"status": status, "environments": envs, "took_s": round(sum(t for _, t in statuses), 2) if statuses else None}
+
+
+def parse_pkg_search(text: str) -> dict:
+    """Parse the human-readable `pio pkg search` output into a list of packages."""
+    head = PKG_SEARCH_HEAD_RE.search(text)
+    packages: list[dict] = []
+    block: list[str] = []
+
+    def flush() -> None:
+        if len(block) >= 2:
+            spec = block[0].strip()
+            meta = [p.strip() for p in block[1].split("•")]
+            packages.append(
+                {
+                    "spec": spec,
+                    "owner": spec.split("/")[0] if "/" in spec else None,
+                    "name": spec.split("/")[-1],
+                    "type": meta[0].lower() if meta else None,
+                    "version": meta[1] if len(meta) > 1 else None,
+                    "published": meta[2].replace("Published on ", "") if len(meta) > 2 else None,
+                    "description": " ".join(l.strip() for l in block[2:]).strip() or None,
+                }
+            )
+        block.clear()
+
+    for line in text.split("\n"):
+        if PKG_SEARCH_HEAD_RE.match(line):
+            continue
+        if not line.strip():
+            flush()
+            continue
+        block.append(line)
+    flush()
+    return {
+        "total": int(head["total"]) if head else len(packages),
+        "page": int(head["page"]) if head else 1,
+        "pages": int(head["pages"]) if head else 1,
+        "packages": packages,
+    }
+
+
+def parse_pkg_list(text: str) -> list[dict]:
+    """Parse `pio pkg list` / `pio pkg outdated` tree output into flat rows."""
+    rows: list[dict] = []
+    env = None
+    for line in text.split("\n"):
+        m = re.match(r"^Resolving (?P<env>\S+) dependencies", line)
+        if m:
+            env = m["env"]
+            continue
+        m = PKG_LINE_RE.match(line)
+        if not m or not m["spec"].strip():
+            continue
+        rows.append({"env": env, "type": (m["kind"] or "Library").lower(), "spec": m["spec"].strip(), "version": m["version"], "required": (m["req"] or "").removeprefix("required: ").strip() or None})
+    return rows
+
+
+def parse_targets(text: str) -> list[dict]:
+    """Parse the table printed by `pio run --list-targets`."""
+    rows: list[dict] = []
+    for line in text.split("\n"):
+        if not line.strip() or line.startswith("Environment") or set(line.strip()) <= {"-", " "}:
+            continue
+        parts = re.split(r"\s{2,}", line.strip())
+        if len(parts) < 3:
+            continue
+        rows.append({"env": parts[0], "group": parts[1], "name": parts[2], "title": parts[3] if len(parts) > 3 else None, "description": parts[4] if len(parts) > 4 else None})
+    return rows
+
+
+def summarize_test_report(report: dict) -> dict:
+    """Reduce the `pio test --json-output-path` report to what an agent needs."""
+    suites = []
+    for s in report.get("test_suites", []):
+        cases = [
+            {
+                "name": c.get("name"),
+                "status": c.get("status"),
+                "message": c.get("message") or c.get("exception"),
+                "file": (c.get("source") or {}).get("file"),
+                "line": (c.get("source") or {}).get("line"),
+            }
+            for c in s.get("test_cases", [])
+        ]
+        suites.append({"env": s.get("env_name"), "test": s.get("test_name"), "status": s.get("status"), "duration_s": round(s.get("duration", 0), 2), "cases": cases})
+    return {
+        "total": report.get("testcase_nums", 0),
+        "failed": report.get("failure_nums", 0),
+        "errored": report.get("error_nums", 0),
+        "skipped": report.get("skipped_nums", 0),
+        "duration_s": round(report.get("duration", 0), 2),
+        "suites": suites,
+    }
+
+
+def summarize_check_report(report: list[dict], project_dir: str | None = None) -> dict:
+    """Group `pio check --json-output` defects by file and severity."""
+    by_severity = {"high": 0, "medium": 0, "low": 0}
+    defects = []
+    tools = []
+    for entry in report:
+        tools.append({"env": entry.get("env"), "tool": entry.get("tool"), "succeeded": entry.get("succeeded"), "duration_s": round(entry.get("duration", 0), 2)})
+        for d in entry.get("defects", []):
+            sev = d.get("severity", "low")
+            by_severity[sev] = by_severity.get(sev, 0) + 1
+            f = d.get("file") or ""
+            if project_dir and f.startswith(project_dir):
+                f = f[len(project_dir) :].lstrip("/\\")
+            defects.append({"severity": sev, "category": d.get("category"), "id": d.get("id"), "message": d.get("message"), "file": f, "line": d.get("line"), "column": d.get("column"), "cwe": d.get("cwe"), "tool": entry.get("tool"), "env": entry.get("env")})
+    order = {"high": 0, "medium": 1, "low": 2}
+    defects.sort(key=lambda d: (order.get(d["severity"], 3), d["file"], d["line"] or 0))
+    return {"defect_count": len(defects), "by_severity": by_severity, "tools": tools, "defects": defects}