enginehall 2.0.0__py3-none-any.whl

pcba/mcp/protocol.py

@@ -0,0 +1,224 @@
+"""The MCP protocol both engine servers speak: newline-delimited JSON-RPC 2.0 over stdio.
+
+No SDK, so the protocol is ours to get right; it lives here once instead of in each server.
+
+Dual-era, as the 2026-07-28 revision allows:
+
+- **Modern** clients (Claude Code since 2.1.29x) probe with `server/discover` and send the
+  protocol version and client capabilities in every request's `_meta`. They get stateless
+  answers carrying `resultType` and the server's identity in `_meta`.
+- **Legacy** clients (`initialize` handshake, 2025-11-25 and earlier) are still most other
+  hosts. `initialize` negotiates one of the legacy versions for the life of the process.
+
+A tool is `name -> (function, spec)`. The spec holds the MCP tool fields (`title`,
+`description`, `inputSchema`, `annotations`); the server keeps a reference to the caller's
+dict, so a registry patched at runtime is what gets served.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import traceback
+from dataclasses import dataclass
+from typing import Any, Callable, Mapping
+
+MODERN_VERSIONS = ("2026-07-28",)
+# Answered by `initialize`; the first one is offered when a client asks for a version we lack.
+LEGACY_VERSIONS = ("2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05")
+
+META_VERSION = "io.modelcontextprotocol/protocolVersion"
+META_SERVER_INFO = "io.modelcontextprotocol/serverInfo"
+
+PARSE_ERROR = -32700
+INVALID_REQUEST = -32600
+METHOD_NOT_FOUND = -32601
+INVALID_PARAMS = -32602
+INTERNAL_ERROR = -32603
+UNSUPPORTED_PROTOCOL_VERSION = -32022
+
+# The tool list is fixed for the life of a server process.
+LIST_TTL_MS = 3_600_000
+
+Tools = Mapping[str, "tuple[Callable[..., Any], dict]"]
+
+
+def result(request_id: Any, payload: dict) -> dict:
+    return {"jsonrpc": "2.0", "id": request_id, "result": payload}
+
+
+def error(request_id: Any, code: int, message: str, data: Any = None) -> dict:
+    body: dict[str, Any] = {"code": code, "message": message}
+    if data is not None:
+        body["data"] = data
+    return {"jsonrpc": "2.0", "id": request_id, "error": body}
+
+
+def is_error_payload(payload: Any) -> bool:
+    """A tool that answers `{"error": ...}` and nothing else has failed, whether it raised or
+    returned that payload: a client reading only `isError` must not take a miss for success."""
+    return isinstance(payload, dict) and set(payload) == {"error"}
+
+
+def tool_annotations(*, read_only: bool, destructive: bool = False, idempotent: bool = False) -> dict:
+    """MCP behaviour hints for a local tool (never an open world).
+
+    Hints are advisory for clients; the server enforces its own rules regardless. The tool's
+    `title` is copied in when the list is served.
+    """
+    if read_only:
+        return {"readOnlyHint": True, "openWorldHint": False}
+    return {
+        "readOnlyHint": False,
+        "destructiveHint": destructive,
+        "idempotentHint": idempotent,
+        "openWorldHint": False,
+    }
+
+
+READ_ONLY = tool_annotations(read_only=True)
+
+
+def _listed(name: str, spec: dict) -> dict:
+    tool = {"name": name, **spec}
+    if "annotations" in spec:
+        tool["annotations"] = {"title": spec["title"], **spec["annotations"]}
+    return tool
+
+
+@dataclass
+class Server:
+    name: str
+    title: str
+    version: str
+    description: str
+    instructions: str
+    tools: Tools
+    # Exceptions a tool raises for bad input or an unavailable resource. They become a tool
+    # result with `isError`, so the agent can correct itself; anything else is a bug and
+    # becomes a JSON-RPC internal error.
+    in_band: tuple[type[BaseException], ...] = (OSError, TypeError, ValueError)
+    describe_error: Callable[[BaseException], Any] = str
+    website_url: str = "https://enginehall.com"
+    # Optional server-specific semantics and attachments; the structured payload stays intact.
+    tool_is_error: Callable[[str, Any], bool] | None = None
+    tool_content: Callable[[str, Any], list[dict]] | None = None
+
+    # --- identity --------------------------------------------------------------------------
+
+    def info(self) -> dict:
+        return {
+            "name": self.name,
+            "title": self.title,
+            "version": self.version,
+            "description": self.description,
+            "websiteUrl": self.website_url,
+        }
+
+    def _complete(self, request_id: Any, payload: dict, modern: bool) -> dict:
+        payload = {"resultType": "complete", **payload}
+        if modern:
+            payload["_meta"] = {META_SERVER_INFO: self.info()}
+        return result(request_id, payload)
+
+    # --- dispatch --------------------------------------------------------------------------
+
+    def handle(self, message: Any) -> dict | None:
+        if not isinstance(message, dict):
+            return error(None, INVALID_REQUEST, "invalid request: expected a JSON object")
+        method = message.get("method")
+        request_id = message.get("id")
+        params = message.get("params")
+        if "id" not in message:
+            return None  # A notification: never answered, whatever its method.
+        params = {} if params is None else params
+        if not isinstance(params, dict):
+            return error(request_id, INVALID_PARAMS, "invalid params: expected a JSON object")
+
+        meta = params.get("_meta")
+        version = meta.get(META_VERSION) if isinstance(meta, dict) else None
+        modern = version is not None
+        if modern and version not in MODERN_VERSIONS:
+            return error(
+                request_id,
+                UNSUPPORTED_PROTOCOL_VERSION,
+                "Unsupported protocol version",
+                {"supported": list(MODERN_VERSIONS), "requested": version},
+            )
+
+        if method == "server/discover":
+            return self._complete(request_id, {
+                "supportedVersions": list(MODERN_VERSIONS),
+                "capabilities": {"tools": {}},
+                "instructions": self.instructions,
+                "ttlMs": LIST_TTL_MS,
+                "cacheScope": "public",
+            }, modern=True)
+
+        if method == "initialize":
+            wanted = params.get("protocolVersion")
+            return result(request_id, {
+                "protocolVersion": wanted if wanted in LEGACY_VERSIONS else LEGACY_VERSIONS[0],
+                "capabilities": {"tools": {}},
+                "serverInfo": self.info(),
+                "instructions": self.instructions,
+            })
+
+        if method == "ping":  # Legacy only; removed in 2026-07-28, harmless to keep.
+            return result(request_id, {})
+
+        if method == "tools/list":
+            return self._complete(request_id, {
+                "tools": [_listed(name, spec) for name, (_fn, spec) in self.tools.items()],
+                "ttlMs": LIST_TTL_MS,
+                "cacheScope": "public",
+            }, modern)
+
+        if method == "tools/call":
+            name = params.get("name")
+            if not isinstance(name, str) or name not in self.tools:
+                return error(request_id, INVALID_PARAMS, f"unknown tool: {name}")
+            arguments = params.get("arguments")
+            arguments = {} if arguments is None else arguments
+            if not isinstance(arguments, dict):
+                return error(request_id, INVALID_PARAMS, "tool arguments must be a JSON object")
+            function, _spec = self.tools[name]
+            try:
+                payload = function(**arguments)
+                is_error = (self.tool_is_error(name, payload) if self.tool_is_error else
+                            is_error_payload(payload))
+            except self.in_band as exc:
+                payload, is_error = {"error": self.describe_error(exc)}, True
+            content = [{"type": "text", "text": json.dumps(payload, indent=2)}]
+            if self.tool_content:
+                content.extend(self.tool_content(name, payload))
+            return self._complete(request_id, {
+                "content": content,
+                "structuredContent": payload,
+                "isError": is_error,
+            }, modern)
+
+        return error(request_id, METHOD_NOT_FOUND, f"method not found: {method}")
+
+    def serve(self, stdin=None, stdout=None) -> None:
+        """Run the stdio loop until EOF."""
+        stdin = stdin or sys.stdin
+        stdout = stdout or sys.stdout
+        for line in stdin:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                message = json.loads(line)
+            except json.JSONDecodeError:
+                response = error(None, PARSE_ERROR, "parse error")
+            else:
+                try:
+                    response = self.handle(message)
+                except Exception:  # noqa: BLE001 - a crashed tool must not kill the server
+                    traceback.print_exc(file=sys.stderr)
+                    request_id = message.get("id") if isinstance(message, dict) else None
+                    response = error(request_id, INTERNAL_ERROR, "internal error")
+            if response is not None:
+                stdout.write(json.dumps(response) + "\n")
+                stdout.flush()

pcba/mcp/server.py

@@ -0,0 +1,332 @@
+"""MCP server — the same engine the CLI drives, exposed to agents.
+
+Zero dependencies: newline-delimited JSON-RPC 2.0 over stdio is small enough to implement
+directly, and `pip install enginehall` then gives an agent integration with no extras and no
+version-skew against an SDK. The protocol itself lives in `pcba.mcp.protocol`, shared with
+`enginehall altium mcp`.
+
+Six tools, not twenty. Each one has to earn its place by being something an agent genuinely
+cannot do by reading files itself — which is exactly the tools that parse a binary container
+or query ST's database. Tool surface is a maintenance liability, so it grows on demand.
+
+Every tool returns structured JSON, not prose. The model's job is to explain findings, never
+to detect them.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Callable
+
+from pcba import __version__, review
+from pcba.changes import ChangeSetError
+from pcba.mcp.protocol import READ_ONLY, Server
+from pcba.parsers import altium
+from pcba.parsers import ioc as ioc_parser
+from pcba.parsers.altium.records import SchDocError
+from pcba.parsers.ioc import IocError
+
+# Findings are unbounded in principle; a runaway review must not blow up an agent's context.
+MAX_FINDINGS = 100
+
+
+def _project(
+    path: str,
+    part: str | None = None,
+    ioc: str | None = None,
+    target: str | None = None,
+    schematic_component: str | None = None,
+    schematic_dir: str | None = None,
+    kicad_project: str | None = None,
+):
+    return review.load_project(
+        path, part=part, ioc=ioc, target=target, schematic_component=schematic_component,
+        schematic_dir=schematic_dir, kicad_project=kicad_project, tools=False,
+    )
+
+
+# --- tools -----------------------------------------------------------------------------
+
+
+def tool_project_inspect(
+    path: str = ".",
+    part: str | None = None,
+    target: str | None = None,
+    schematic_component: str | None = None,
+    ioc: str | None = None,
+    schematic_dir: str | None = None,
+    kicad_project: str | None = None,
+) -> dict:
+    found, project = _project(
+        path, part, ioc=ioc, target=target, schematic_component=schematic_component,
+        schematic_dir=schematic_dir, kicad_project=kicad_project,
+    )
+    return review.summary(found, project)
+
+
+def tool_review_run(
+    path: str = ".",
+    part: str | None = None,
+    ioc: str | None = None,
+    baseline: str | None = None,
+    changed_only: str | None = None,
+    target: str | None = None,
+    schematic_component: str | None = None,
+    required_rules: list[str] | None = None,
+    schematic_dir: str | None = None,
+    kicad_project: str | None = None,
+) -> dict:
+    result = review.run(
+        path,
+        part=part,
+        ioc=ioc,
+        schematic_dir=schematic_dir,
+        kicad_project=kicad_project,
+        baseline=baseline,
+        changed_only=changed_only,
+        target=target,
+        schematic_component=schematic_component,
+        required_rules=tuple(required_rules or ()),
+    )
+    payload = json.loads(result.render("json", findings=result.findings[:MAX_FINDINGS]))
+    if len(result.findings) > MAX_FINDINGS:
+        payload["truncated"] = {
+            "shown": MAX_FINDINGS,
+            "total": len(result.findings),
+            "note": "Use pcba_review_get_finding for specifics, or run `enginehall review` locally.",
+        }
+    return payload
+
+
+def tool_review_get_finding(
+    finding_id: str,
+    path: str = ".",
+    part: str | None = None,
+    ioc: str | None = None,
+    target: str | None = None,
+    schematic_component: str | None = None,
+    schematic_dir: str | None = None,
+    kicad_project: str | None = None,
+) -> dict:
+    result = review.run(
+        path, part=part, ioc=ioc, target=target, schematic_component=schematic_component,
+        schematic_dir=schematic_dir, kicad_project=kicad_project,
+    )
+    for finding in result.findings:
+        if finding.id == finding_id:
+            return finding.to_dict()
+    return {"error": f"no finding with id {finding_id!r} in the current review"}
+
+
+def tool_altium_pinmap(
+    dir: str, part: str | None = None, schematic_component: str | None = None
+) -> dict:
+    directory = Path(dir)
+    resolved = part or altium.detect_part(directory)
+    if not resolved:
+        return {"error": f"could not detect an MCU part under {directory}; pass `part`"}
+    return altium.to_dict(altium.extract(directory, resolved, component=schematic_component))
+
+
+def tool_cubemx_inspect(ioc: str) -> dict:
+    values = ioc_parser.parse_ioc(Path(ioc))
+    return {
+        "part": ioc_parser.part_name(values),
+        "pins": ioc_parser.collect_pins(values),
+        "peripherals": ioc_parser.peripherals(values),
+        "clocks": ioc_parser.clocks(values),
+    }
+
+
+def tool_cubemx_validate(ioc: str, manifest: str) -> dict:
+    values = ioc_parser.parse_ioc(Path(ioc))
+    errors = ioc_parser.validate(values, ioc_parser.load_manifest(Path(manifest)))
+    return {"passed": not errors, "errors": errors}
+
+
+TOOLS: dict[str, tuple[Callable, dict]] = {
+    "pcba_project_inspect": (
+        tool_project_inspect,
+        {
+            "title": "Inspect project",
+            "annotations": READ_ONLY,
+            "description": (
+                "Identify an embedded project's artifacts: schematic directory or KiCad project, "
+                "MCU configuration, firmware trees, MCU part. Also reports which review rules "
+                "can and cannot run. Call this first."
+            ),
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string", "description": "Project root (default: .)"},
+                    "part": {"type": "string", "description": "MCU part; default auto-detect"},
+                    "target": {"type": "string", "description": "Configured target name"},
+                    "schematic_component": {"type": "string", "description": "MCU designator when several MCUs exist"},
+                    "ioc": {
+                        "type": "string",
+                        "description": "Path to a specific .ioc; relative to the project root",
+                    },
+                    "schematic_dir": {
+                        "type": "string",
+                        "description": "Directory of .SchDoc sheets; relative to the project root",
+                    },
+                    "kicad_project": {
+                        "type": "string",
+                        "description": "KiCad project (.kicad_pro or its folder); relative to the project root",
+                    },
+                },
+            },
+        },
+    ),
+    "pcba_review_run": (
+        tool_review_run,
+        {
+            "title": "Run review",
+            "annotations": READ_ONLY,
+            "description": (
+                "Run every rule and return findings where the schematic, the MCU "
+                "configuration and the firmware disagree, plus the KiCad schematic, component, "
+                "board and simulation checks on a KiCad project. Each finding carries evidence, "
+                "a location, a rule id and how it was detected. Check `coverage.rules` and "
+                "`coverage.skipped` — an empty findings list does not mean everything was checked."
+            ),
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string", "description": "Project root (default: .)"},
+                    "part": {"type": "string", "description": "MCU part; default auto-detect"},
+                    "ioc": {
+                        "type": "string",
+                        "description": "Path to a specific .ioc; relative to the project root",
+                    },
+                    "schematic_dir": {
+                        "type": "string",
+                        "description": "Directory of .SchDoc sheets; relative to the project root",
+                    },
+                    "kicad_project": {
+                        "type": "string",
+                        "description": "KiCad project (.kicad_pro or its folder); relative to the project root",
+                    },
+                    "baseline": {
+                        "type": "string",
+                        "description": "Versioned finding-suppression file",
+                    },
+                    "changed_only": {
+                        "type": "string",
+                        "description": "Git ref; return findings touching changed files only",
+                    },
+                    "target": {"type": "string", "description": "Configured target name"},
+                    "schematic_component": {"type": "string", "description": "MCU designator when several MCUs exist"},
+                    "required_rules": {"type": "array", "items": {"type": "string"}},
+                },
+            },
+        },
+    ),
+    "pcba_review_get_finding": (
+        tool_review_get_finding,
+        {
+            "title": "Get finding",
+            "annotations": READ_ONLY,
+            "description": "Full detail for one finding id from pcba_review_run.",
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "finding_id": {"type": "string"},
+                    "path": {"type": "string"},
+                    "part": {"type": "string"},
+                    "ioc": {"type": "string", "description": "Same explicit .ioc as the review"},
+                    "schematic_dir": {"type": "string", "description": "Same schematic directory as the review"},
+                    "kicad_project": {"type": "string", "description": "Same KiCad project as the review"},
+                    "target": {"type": "string", "description": "Same target as the review"},
+                    "schematic_component": {"type": "string", "description": "MCU designator used by the review"},
+                },
+                "required": ["finding_id"],
+            },
+        },
+    ),
+    "pcba_altium_pinmap": (
+        tool_altium_pinmap,
+        {
+            "title": "Altium MCU pin map",
+            "annotations": READ_ONLY,
+            "description": (
+                "Extract an MCU pin -> net map from binary Altium .SchDoc sheets, resolved "
+                "from wire geometry rather than net-label text. Pins are keyed by package pin "
+                "(pad), each with its port pin and name. Also reports mislabelled "
+                "nets and suspected open circuits. Use this instead of trying to read a "
+                ".SchDoc directly — it is an OLE2 binary container."
+            ),
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "dir": {"type": "string", "description": "Directory of .SchDoc sheets"},
+                    "part": {"type": "string", "description": "MCU part; default auto-detect"},
+                    "schematic_component": {"type": "string", "description": "MCU designator when several MCUs exist"},
+                },
+                "required": ["dir"],
+            },
+        },
+    ),
+    "pcba_cubemx_inspect": (
+        tool_cubemx_inspect,
+        {
+            "title": "Inspect CubeMX .ioc",
+            "annotations": READ_ONLY,
+            "description": (
+                "Read an STM32CubeMX .ioc: pins, signals, labels, enabled peripherals and "
+                "clock-tree values."
+            ),
+            "inputSchema": {
+                "type": "object",
+                "properties": {"ioc": {"type": "string"}},
+                "required": ["ioc"],
+            },
+        },
+    ),
+    "pcba_cubemx_validate": (
+        tool_cubemx_validate,
+        {
+            "title": "Validate CubeMX .ioc",
+            "annotations": READ_ONLY,
+            "description": (
+                "Check an .ioc against a manifest of values a regeneration must not change "
+                "(expected keys, peripherals, GPIO labels, CAN bit timing)."
+            ),
+            "inputSchema": {
+                "type": "object",
+                "properties": {"ioc": {"type": "string"}, "manifest": {"type": "string"}},
+                "required": ["ioc", "manifest"],
+            },
+        },
+    ),
+}
+
+
+# --- server ----------------------------------------------------------------------------
+
+SERVER = Server(
+    name="enginehall",
+    title="EngineHall review",
+    version=__version__,
+    description=(
+        "Checks that an Altium schematic, an STM32CubeMX configuration and firmware agree. "
+        "Local and read-only."
+    ),
+    instructions=(
+        "Start with pcba_project_inspect: it finds the schematic, the .ioc, the firmware roots "
+        "and the MCU, and says which rules can run. pcba_review_run returns deterministic "
+        "findings with evidence and a location; explain and prioritize them, never invent "
+        "findings of your own. An empty findings list means nothing only together with "
+        "coverage: read coverage.skipped and the uncompared signals before saying a project "
+        "is clean, and never call a review a sign-off. Read binary .SchDoc files through "
+        "pcba_altium_pinmap, not as text."
+    ),
+    tools=TOOLS,
+    # Tool failures are reported in-band so the agent can react, rather than as a protocol error
+    # that just kills the call. Configuration and baseline errors are ValueErrors.
+    in_band=(IocError, SchDocError, ChangeSetError, OSError, TypeError, ValueError),
+)
+
+handle = SERVER.handle
+serve = SERVER.serve

pcba/model/__init__.py

@@ -0,0 +1,38 @@
+"""The normalized model and the finding schema."""
+
+from pcba.model.finding import Detector, Domain, Evidence, Finding, Location, Severity
+from pcba.model.pinmap import (
+    FirmwareIndex,
+    FirmwareReference,
+    McuConfig,
+    Pin,
+    PinAssignment,
+    Project,
+    Resolution,
+    SchematicPinMap,
+    is_port_pin,
+    is_power_pin,
+    natural_key,
+    port_sort_key,
+)
+
+__all__ = [
+    "Detector",
+    "Domain",
+    "Evidence",
+    "Finding",
+    "FirmwareIndex",
+    "FirmwareReference",
+    "Location",
+    "McuConfig",
+    "Pin",
+    "PinAssignment",
+    "Project",
+    "Resolution",
+    "SchematicPinMap",
+    "Severity",
+    "is_port_pin",
+    "is_power_pin",
+    "natural_key",
+    "port_sort_key",
+]