nvda-mcp 1.0.0__py3-none-any.whl

nvda_mcp/__init__.py

@@ -0,0 +1 @@
+"""MCP server for the NVDA screen reader."""

nvda_mcp/__main__.py

@@ -0,0 +1,5 @@
+"""Lets ``python -m nvda_mcp`` start the server."""
+
+from .server import main
+
+main()

nvda_mcp/audit.py

@@ -0,0 +1,155 @@
+"""Analyses a recorded walk through an application's keyboard focus order."""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+# Roles a keyboard user must be able to identify by name alone.
+ROLES_NEEDING_NAMES = frozenset(
+    {
+        "button",
+        "link",
+        "check box",
+        "radio button",
+        "combo box",
+        "edit",
+        "menu item",
+        "tab",
+        "toggle button",
+        "slider",
+        "spin button",
+        "split button",
+        "menu button",
+        "tree view item",
+    }
+)
+
+
+def focus_signature(focus: dict[str, Any]) -> tuple:
+    """Identifies a focused control well enough to notice cycles and stuck focus."""
+    return (
+        focus.get("name"),
+        focus.get("role"),
+        focus.get("appName"),
+        tuple(focus.get("location") or ()),
+    )
+
+
+@dataclass
+class AuditStep:
+    index: int
+    focus: dict[str, Any]
+    spoken: str
+    issues: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "step": self.index,
+            "spoken": self.spoken,
+            "name": self.focus.get("name"),
+            "role": self.focus.get("role"),
+            "states": self.focus.get("states", []),
+            "issues": self.issues,
+        }
+
+
+@dataclass
+class AuditReport:
+    key: str
+    app_name: str | None
+    steps: list[AuditStep] = field(default_factory=list)
+    stop_reason: str = ""
+
+    @property
+    def issue_count(self) -> int:
+        return sum(len(step.issues) for step in self.steps)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "key": self.key,
+            "appName": self.app_name,
+            "stopReason": self.stop_reason,
+            "issueCount": self.issue_count,
+            "steps": [step.to_dict() for step in self.steps],
+        }
+
+    def to_markdown(self) -> str:
+        lines = [
+            f"# Focus order audit: {self.app_name or 'unknown app'}",
+            "",
+            f"Pressed **{self.key}** {len(self.steps) - 1} times. Stopped because: {self.stop_reason}.",
+            f"Found **{self.issue_count}** issue(s).",
+            "",
+            "| Step | NVDA said | Role | Name | Issues |",
+            "|---|---|---|---|---|",
+        ]
+        for step in self.steps:
+            cells = [
+                str(step.index),
+                step.spoken or "(nothing)",
+                step.focus.get("role") or "",
+                step.focus.get("name") or "",
+                "; ".join(step.issues),
+            ]
+            lines.append(
+                "| " + " | ".join(cell.replace("|", "\\|").replace("\n", " ") for cell in cells) + " |"
+            )
+        return "\n".join(lines)
+
+
+class FocusOrderAuditor:
+    """Accumulates steps and decides when the walk should stop.
+
+    Feed it the starting focus, then each new focus with what NVDA said;
+    :meth:`add_step` returns a stop reason once the walk is complete.
+    """
+
+    def __init__(self, key: str, start_focus: dict[str, Any], start_spoken: str = "") -> None:
+        self.report = AuditReport(key=key, app_name=start_focus.get("appName"))
+        self._start_signature = focus_signature(start_focus)
+        self._first_step_by_label: dict[tuple, int] = {}
+        self._unmoved_count = 0
+        self._record(AuditStep(0, start_focus, start_spoken))
+
+    def add_step(self, focus: dict[str, Any], spoken: str) -> str | None:
+        step = AuditStep(len(self.report.steps), focus, spoken)
+        previous = self.report.steps[-1]
+        signature = focus_signature(focus)
+        stop_reason = None
+        if focus.get("appName") != self.report.app_name:
+            step.issues.append(f"Focus left the application (now in {focus.get('appName') or 'unknown'})")
+            stop_reason = "focus left the application"
+        elif signature == self._start_signature:
+            stop_reason = "focus returned to where the audit started"
+        elif signature == focus_signature(previous.focus):
+            self._unmoved_count += 1
+            step.issues.append("Focus did not move: possible keyboard trap, or the end of the focus order")
+            if self._unmoved_count >= 2:
+                stop_reason = "focus stopped moving"
+        else:
+            self._unmoved_count = 0
+        if not spoken:
+            step.issues.append("NVDA said nothing when this control got focus")
+        self._record(step)
+        if stop_reason:
+            self.report.stop_reason = stop_reason
+        return stop_reason
+
+    def finish(self, reason: str) -> AuditReport:
+        if not self.report.stop_reason:
+            self.report.stop_reason = reason
+        return self.report
+
+    def _record(self, step: AuditStep) -> None:
+        focus = step.focus
+        role = focus.get("role")
+        name = (focus.get("name") or "").strip()
+        if role in ROLES_NEEDING_NAMES and not name:
+            step.issues.append(f"Unlabeled {role}: it has no accessible name")
+        if name and step.index > 0 and focus_signature(focus) != self._start_signature:
+            label = (name, role)
+            first = self._first_step_by_label.setdefault(label, step.index)
+            if first != step.index and focus_signature(focus) != focus_signature(
+                self.report.steps[first].focus
+            ):
+                step.issues.append(f"Same name and role as step {first}: users cannot tell them apart")
+        self.report.steps.append(step)

nvda_mcp/bridge_client.py

@@ -0,0 +1,122 @@
+"""Client for the loopback bridge run by the NVDA MCP add-on."""
+
+import json
+import os
+from importlib import metadata
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+SUPPORTED_PROTOCOL_VERSION = 3
+DEFAULT_TIMEOUT_SECONDS = 10.0
+
+
+def default_connection_file() -> Path:
+    """The file the add-on writes in NVDA's user configuration directory.
+
+    Set NVDA_MCP_CONNECTION_FILE for portable copies of NVDA, whose configuration lives elsewhere.
+    """
+    override = os.environ.get("NVDA_MCP_CONNECTION_FILE")
+    if override:
+        return Path(override)
+    return Path(os.environ.get("APPDATA", "")) / "nvda" / "nvdaMcp" / "connection.json"
+
+
+class NvdaUnavailableError(Exception):
+    """NVDA, or the add-on's bridge, cannot be reached."""
+
+
+class NvdaBridgeError(Exception):
+    """The add-on received the request but reported a failure."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+
+def server_version() -> str:
+    try:
+        return metadata.version("nvda-mcp")
+    except metadata.PackageNotFoundError:
+        return "unknown"
+
+
+def version_mismatch_message(info: dict[str, Any]) -> str:
+    """Says which of the add-on and the server is older, and how to update it."""
+    addon_protocol = info.get("protocolVersion")
+    addon_version = info.get("addonVersion") or "an older version"
+    mismatch = (
+        f"The NVDA MCP add-on ({addon_version}) and this nvda-mcp server ({server_version()}) do not match: "
+        f"the add-on speaks bridge protocol {addon_protocol}, the server {SUPPORTED_PROTOCOL_VERSION}."
+    )
+    if isinstance(addon_protocol, int) and addon_protocol > SUPPORTED_PROTOCOL_VERSION:
+        return (
+            f"{mismatch} Update the server: in NVDA, open Settings, NVDA MCP category, choose your client, "
+            "press Copy setup command and run what it copies. "
+            "If you installed the server with pip or pipx, upgrade it there instead."
+        )
+    return f"{mismatch} Update the add-on: in NVDA, open Tools, Add-on Store, Updatable add-ons."
+
+
+_NOT_RUNNING_HINT = (
+    "Make sure NVDA is running, the NVDA MCP add-on is installed and enabled "
+    "(NVDA Settings, NVDA MCP category), and NVDA was restarted after installing it."
+)
+
+
+class BridgeClient:
+    """Calls bridge methods. Reads the connection file on every call, so it survives NVDA restarts."""
+
+    def __init__(
+        self, connection_file: Path | None = None, transport: httpx.AsyncBaseTransport | None = None
+    ) -> None:
+        self._connection_file = connection_file or default_connection_file()
+        self._transport = transport
+        self.client_name: str | None = None
+        """The MCP client's name, such as "Claude Code"; sent with every call so NVDA can show it."""
+
+    def _read_connection(self) -> dict[str, Any]:
+        try:
+            info = json.loads(self._connection_file.read_text(encoding="utf-8"))
+        except FileNotFoundError:
+            raise NvdaUnavailableError(
+                f"NVDA is not reachable: {self._connection_file} does not exist. {_NOT_RUNNING_HINT}"
+            )
+        except (OSError, ValueError) as error:
+            raise NvdaUnavailableError(
+                f"Could not read {self._connection_file}: {error}. {_NOT_RUNNING_HINT}"
+            )
+        if info.get("protocolVersion") != SUPPORTED_PROTOCOL_VERSION:
+            raise NvdaUnavailableError(version_mismatch_message(info))
+        return info
+
+    async def call(
+        self, method: str, params: dict[str, Any] | None = None, timeout: float = DEFAULT_TIMEOUT_SECONDS
+    ) -> Any:
+        info = self._read_connection()
+        url = f"http://127.0.0.1:{info['port']}/rpc"
+        headers = {"Authorization": f"Bearer {info['token']}"}
+        params = dict(params or {})
+        if self.client_name:
+            params["clientName"] = self.client_name
+        try:
+            async with httpx.AsyncClient(transport=self._transport, timeout=timeout) as client:
+                response = await client.post(url, json={"method": method, "params": params}, headers=headers)
+        except httpx.TimeoutException:
+            raise NvdaUnavailableError(
+                f"NVDA did not answer {method} within {timeout:g} seconds. It may be busy or frozen; try again shortly."
+            )
+        except httpx.TransportError:
+            raise NvdaUnavailableError(f"NVDA is not reachable on port {info['port']}. {_NOT_RUNNING_HINT}")
+        try:
+            body = response.json()
+        except ValueError:
+            raise NvdaBridgeError(
+                "badResponse", f"The bridge returned HTTP {response.status_code} without JSON."
+            )
+        if not body.get("ok"):
+            error = body.get("error") or {}
+            raise NvdaBridgeError(error.get("code", "unknown"), error.get("message", "Unknown bridge error."))
+        return body["result"]

nvda_mcp/scenario.py

@@ -0,0 +1,83 @@
+"""Records what NVDA says during a scripted scenario and compares it with a saved baseline."""
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+BASELINE_FORMAT_VERSION = 1
+
+
+@dataclass
+class StepRecord:
+    action: str
+    spoken: str
+    focus: str
+
+    def to_dict(self) -> dict[str, str]:
+        return {"action": self.action, "spoken": self.spoken, "focus": self.focus}
+
+
+@dataclass
+class Recording:
+    steps: list[StepRecord] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"version": BASELINE_FORMAT_VERSION, "steps": [step.to_dict() for step in self.steps]}
+
+    def to_markdown(self) -> str:
+        lines = ["| Step | Action | NVDA said | Focus after |", "|---|---|---|---|"]
+        for number, step in enumerate(self.steps, 1):
+            cells = [str(number), step.action, step.spoken or "(nothing)", step.focus]
+            lines.append("| " + " | ".join(_cell(cell) for cell in cells) + " |")
+        return "\n".join(lines)
+
+
+def _cell(text: str) -> str:
+    return text.replace("|", "\\|").replace("\n", " ")
+
+
+def focus_label(focus: dict[str, Any]) -> str:
+    return f"{focus.get('name') or '(no name)'} ({focus.get('role') or '?'})"
+
+
+def load_baseline(path: Path) -> Recording:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    if data.get("version") != BASELINE_FORMAT_VERSION:
+        raise ValueError(f"{path} is not a baseline this version of nvda-mcp can read.")
+    return Recording([StepRecord(**step) for step in data["steps"]])
+
+
+def save_baseline(path: Path, recording: Recording) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(recording.to_dict(), ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+
+def compare(baseline: Recording, recording: Recording, ignore_pattern: str | None = None) -> list[str]:
+    """Differences between a baseline and a new recording, one line each; empty when they match.
+
+    :param ignore_pattern: A regular expression for text that changes from run to run, such as times;
+        matches are ignored in both recordings.
+    """
+    ignore = re.compile(ignore_pattern) if ignore_pattern else None
+
+    def normal(text: str) -> str:
+        return ignore.sub("…", text) if ignore else text
+
+    differences = []
+    if [step.action for step in baseline.steps] != [step.action for step in recording.steps]:
+        message = (
+            "The steps differ from the baseline's, so the runs cannot be compared. "
+            "Run with update_baseline to record a new baseline."
+        )
+        return [message]
+    for number, (old, new) in enumerate(zip(baseline.steps, recording.steps), 1):
+        if normal(old.spoken) != normal(new.spoken):
+            differences.append(
+                f"Step {number} ({new.action}): NVDA said {new.spoken or '(nothing)'!r}, "
+                f"baseline {old.spoken or '(nothing)'!r}"
+            )
+        if normal(old.focus) != normal(new.focus):
+            differences.append(f"Step {number} ({new.action}): focus on {new.focus}, baseline {old.focus}")
+    return differences