@real-a11y-dev/mcp 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Real A11y
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# @real-a11y-dev/mcp
+
+> A Model Context Protocol (MCP) server that exposes the Real A11y semantic
+> accessibility tree — and its audits — to AI agents.
+
+Unlike a general browser-automation MCP (which hands an agent the browser's raw
+accessibility snapshot so it can _click things_), this server is **audit-first**:
+its flagship tool tells an agent what a real screen reader would announce as
+_broken_. The tree-inspection tools are perception primitives layered on top.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `open_page` | Navigate to a URL and prepare it for queries (call first). `waitUntil` / `settleMs` settle dynamic pages; `device` (e.g. `"iPhone 13"`) audits the **mobile/tablet** layout. |
+| `audit_page` | **Flagship.** Return every accessibility violation — unlabeled controls, images missing alt, heading gaps, unlabeled dialogs, broken landmarks — as structured findings (grouped, each with a CSS locator + severity). |
+| `inspect_page` | Findings **plus** semantic tree, heading outline, and tab order — all from **one** extraction, so they can't disagree. Prefer on dynamic pages. |
+| `get_semantic_tree` | Deterministic role + accessible-name outline of the page. |
+| `get_heading_outline` | Heading structure (h1..h6) in document order. |
+| `get_tab_order` | Focusable elements in keyboard Tab order. |
+| `list_elements` | Every element of one category (`link`/`button`/`form`/`landmark`/`image`/`heading`) as role + name + locator. |
+| `get_native_tree` | Chromium's own accessibility tree (Blink, via CDP) — the authoritative browser tree. |
+| `compare_trees` | Diff custom vs. native and report role/name divergences — a fidelity oracle. |
+| `close_browser` | Tear down the session. |
+
+### Consistency & determinism
+
+- **`inspect_page`** derives all four views from a single extraction, so a report
+  can't be internally inconsistent (e.g. an audit finding referencing a node the
+  tree doesn't show) on a page that changes between separate calls.
+- **`open_page`'s `waitUntil` / `settleMs`** let dynamic pages (SPAs, consent
+  dialogs) reach a stable state before extraction, so results don't vary run to
+  run. Use `waitUntil: "networkidle"` and/or a `settleMs` buffer for heavy SPAs.
+- **`open_page`'s `device` / `viewport`** emulate a phone or tablet, so you audit
+  the tree users on that device actually get — a responsive site can differ
+  substantially from desktop (hamburger nav, hidden content, touch-only
+  controls). Open the same URL at desktop and `device: "iPhone 13"` to diff them.
+
+## How it works
+
+It reuses the exact pieces the testing package already ships:
+
+1. Playwright drives a real browser (a real browser is required — the engine
+   depends on layout/`getComputedStyle` to decide AT exposure).
+2. The pre-built IIFE page-bundle from `@real-a11y-dev/testing` is evaluated in
+   the page via `page.evaluate()`, setting `globalThis.__realA11y__`. (It is run
+   this way rather than `addScriptTag` so it works on pages served under a
+   Trusted Types CSP — `require-trusted-types-for 'script'` — which blocks the
+   `<script>` injection `addScriptTag` uses.)
+3. Each tool then routes through `page.evaluate()` and calls the shared
+   `collectFindings` / serialize helpers.
+
+## Install & run
+
+Playwright is a peer dependency and a Chromium binary is required:
+
+```bash
+npx playwright install chromium
+```
+
+Wire it into an MCP client — no install step needed, `npx -y` fetches the
+package on first run (use the package name, not the bare `real-a11y-mcp` bin,
+since the client launches it from an arbitrary working directory):
+
+```json
+{
+  "mcpServers": {
+    "real-a11y": { "command": "npx", "args": ["-y", "@real-a11y-dev/mcp"] }
+  }
+}
+```
+
+To pin the version instead, add it to your project (`pnpm add -D
+@real-a11y-dev/mcp playwright`) and point `command`/`args` at the local install.
+
+> **Scoping.** Every audit/inspection tool takes an optional `rootSelector`
+> (default `body`) to confine extraction to one region — e.g. audit just a
+> `<main>` or a specific component — which also keeps output within the agent's
+> context budget. The two native-tree tools (`get_native_tree`, `compare_trees`)
+> always read the whole document.
+
+### Environment
+
+| Var | Effect |
+| --- | --- |
+| `REAL_A11Y_MCP_CDP` | Attach to a running Chrome over CDP (e.g. `http://localhost:9222`) instead of launching one — audit pages behind a login you're already signed into. |
+| `REAL_A11Y_MCP_HEADFUL` | `1` launches a visible browser instead of headless. |
+| `REAL_A11Y_MCP_ALLOW_FILE` | `1` permits auditing `file://` URLs. Off by default: an LLM-driven server that can open `file:///…/.env` and read the DOM back is a local-file exfiltration primitive. |
+| `REAL_A11Y_MCP_STORAGE_STATE` | Path to a Playwright storage-state file — audit pages behind a login as that saved session. Create it out-of-band (e.g. `real-a11y login`); it's never a tool parameter, so session tokens never enter the agent's context. The server refuses to start if the file is missing or malformed. |
+| `REAL_A11Y_MCP_ALLOWED_ORIGINS` | Comma-separated origins that auditing is restricted to when a storage state is loaded (origin pinning). **Strongly recommended** alongside `STORAGE_STATE`: without it, a redirect could audit an unintended site with your session. |
+
+Auth material is always operator-configured, never a tool parameter — the agent
+just benefits from a session you set up. Use a dedicated low-privilege test
+account, and keep the storage-state file out of version control.
+
+## Status
+
+Beta, published on npm. Part of the `@real-a11y-dev` family (`core`, `testing`,
+`validate`, …); API and tool surface may still change before 1.0.

package/dist/browser.d.ts

@@ -0,0 +1,201 @@
+import { Finding } from '@real-a11y-dev/testing';
+
+/**
+ * Browser session for the MCP server.
+ *
+ * Mirrors the architecture of `@real-a11y-dev/testing/playwright`: drive a real
+ * browser with Playwright, inject the pre-built IIFE page-bundle (which sets
+ * `window.__realA11y__`), and route each a11y query through `page.evaluate()`.
+ *
+ * A real browser is required — the extraction engine depends on
+ * `getComputedStyle`/layout to decide what is exposed to assistive tech, which
+ * a serverside jsdom cannot faithfully reproduce.
+ */
+
+/**
+ * Reject non-web URLs before navigating. `file://` is a local-file exfiltration
+ * primitive for an LLM-driven server (open `file:///…/.env`, then read the DOM
+ * back), so it's blocked unless `REAL_A11Y_MCP_ALLOW_FILE=1`. `data:` is allowed
+ * (it's caller-supplied inline content, not a filesystem read).
+ */
+declare function assertOpenableUrl(url: string): void;
+interface BrowserSessionOptions {
+    /** Launch headless (default true). Ignored when `cdpEndpoint` is set. */
+    headless?: boolean;
+    /**
+     * Attach to a user's already-running Chrome over the DevTools protocol
+     * instead of launching a fresh browser (e.g. "http://localhost:9222").
+     */
+    cdpEndpoint?: string;
+    /**
+     * Network proxy for the launched browser. Chromium does not honor
+     * `HTTP_PROXY`/`HTTPS_PROXY` env vars on its own, so callers on corporate
+     * networks must pass one explicitly. Ignored when `cdpEndpoint` is set (the
+     * running browser already has its own network config).
+     */
+    proxy?: {
+        server: string;
+        bypass?: string;
+        username?: string;
+        password?: string;
+    };
+    /**
+     * Path to a Playwright storage-state JSON (cookies + origin storage), loaded
+     * into every **launched** context so pages open already authenticated. The
+     * user creates it out-of-band (e.g. the CLI's `login` helper); this is never
+     * an agent-supplied parameter. Applied at the single `newContext()` site, so
+     * it survives device-emulation context rebuilds. Rejected together with
+     * `cdpEndpoint` (a CDP connection reuses the running browser's own session).
+     */
+    storageState?: string;
+    /**
+     * When set (non-empty), extraction is refused unless the page's **final**
+     * origin (after redirects) is in this allowlist. This is the control that
+     * stops a redirect from an intended target to a different origin from
+     * silently auditing an authenticated page the operator never asked for.
+     * Empty/absent ⇒ no origin restriction (anonymous audits follow redirects
+     * freely — logged-out content isn't sensitive). Origins are compared as
+     * `new URL(...).origin` strings.
+     */
+    allowedOrigins?: string[];
+}
+/** Navigation / settle options for {@link A11ySession.open}. */
+interface OpenOptions {
+    /**
+     * Playwright navigation wait state. `"networkidle"` waits until the network
+     * has been quiet for 500ms — the most reliable "the SPA finished rendering"
+     * signal, at the cost of latency. Default `"load"`.
+     */
+    waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit";
+    /**
+     * Extra fixed settle time (ms) after the wait state, to let late-firing JS
+     * (async content, consent dialogs) reach a stable state before extraction.
+     * Default 0.
+     */
+    settleMs?: number;
+    /**
+     * Emulate a device by Playwright device name — e.g. `"iPhone 13"`,
+     * `"Pixel 7"`, `"iPad Pro 11"`. Sets viewport, user-agent, touch, and device
+     * scale so the extracted tree reflects the **mobile/tablet** layout, not
+     * desktop. Changing device between calls rebuilds the browser context.
+     * Not supported over a `cdpEndpoint` (reuses the running browser's context).
+     */
+    device?: string;
+    /**
+     * Explicit viewport override, e.g. `{ width: 375, height: 812 }`. Layered on
+     * top of `device` when both are given.
+     */
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /** Navigation timeout in ms. Default is Playwright's 30s. */
+    timeoutMs?: number;
+}
+/** Options for a single-extraction {@link A11ySession.snapshot}. */
+interface SnapshotOptions {
+    /** Rules to run for `findings`. Omit to run all. */
+    rules?: string[];
+    /** Include generic container nodes in `tree`. Default false. */
+    includeGeneric?: boolean;
+}
+/**
+ * All four views derived from **one** extraction — so they can never disagree.
+ * The fix for cross-call drift: `findings`, `tree`, `outline`, and `tabOrder`
+ * are computed from a single a11y tree snapshot, not four separate extractions.
+ */
+interface PageSnapshot {
+    findings: Finding[];
+    tree: string;
+    outline: string;
+    tabOrder: string;
+}
+/**
+ * The session surface the MCP server depends on. Implemented by
+ * {@link BrowserSession} in production and faked in unit tests, so the server
+ * wiring can be exercised without launching a browser.
+ */
+interface A11ySession {
+    open(url: string, options?: OpenOptions): Promise<{
+        title: string;
+        url: string;
+    }>;
+    call<T>(fn: string, rootSelector: string, args?: unknown[]): Promise<T>;
+    snapshot(rootSelector: string, options?: SnapshotOptions): Promise<PageSnapshot>;
+    /** The browser's own (native) accessibility tree via CDP — Chromium only. */
+    nativeAX(): Promise<{
+        tree: string;
+        pairs: string[];
+    }>;
+    close(): Promise<void>;
+}
+declare class BrowserSession implements A11ySession {
+    private readonly opts;
+    private browser?;
+    private context?;
+    private page?;
+    /** Signature of the current context's emulation, to detect device changes. */
+    private emulationKey;
+    /** Over CDP: whether we created `page` (so `close()` only closes our tab). */
+    private ownsPage;
+    /** Serializes every operation so concurrent tool calls can't race the page. */
+    private queue;
+    constructor(opts?: BrowserSessionOptions);
+    /** Origins allowed for extraction, or null when unrestricted. */
+    private get allowedOrigins();
+    /**
+     * Run `fn` after any in-flight operation. MCP clients dispatch tool calls
+     * concurrently, but all tools share one mutable `page`, so we single-flight.
+     */
+    private run;
+    /** Navigate to `url`, settle, then confirm the bundle initialized. */
+    open(url: string, options?: OpenOptions): Promise<{
+        title: string;
+        url: string;
+    }>;
+    /**
+     * Run a named export from the injected bundle against a root selector.
+     * Re-injects first if a navigation wiped the global.
+     */
+    call<T>(fn: string, rootSelector: string, args?: unknown[]): Promise<T>;
+    /**
+     * Extract the a11y tree **once** and derive all four views from it inside a
+     * single `page.evaluate`, so findings / tree / outline / tab order always
+     * describe the same instant — no cross-call drift on a moving page.
+     */
+    snapshot(rootSelector: string, options?: SnapshotOptions): Promise<PageSnapshot>;
+    /**
+     * Chromium's own accessibility tree, straight from Blink via the CDP
+     * `Accessibility` domain — the authoritative computation, not our
+     * reimplementation. Used to cross-check custom-engine fidelity.
+     */
+    nativeAX(): Promise<{
+        tree: string;
+        pairs: string[];
+    }>;
+    /**
+     * Capture the current context's storage state (cookies + origin storage) —
+     * the "save" step behind the CLI's `login` helper. Returns the plain object;
+     * the caller owns serialization + file writing (permissions, atomicity).
+     * `indexedDB` is caller-gated: it's a no-op on Playwright < 1.51, so the CLI
+     * passes it only when the resolved version supports it.
+     */
+    captureStorageState(options?: {
+        indexedDB?: boolean;
+    }): Promise<unknown>;
+    close(): Promise<void>;
+    hasPage(): boolean;
+    private requirePage;
+    /** Refuse extraction when the final URL's origin isn't allowlisted. */
+    private assertAllowedOrigin;
+    private ensurePage;
+    /** Evaluate the bundle in the page (CSP / Trusted-Types-safe via CDP). */
+    private injectBundle;
+    /** (Re)inject the bundle if a navigation wiped the global. */
+    private ensureInjected;
+    /** Confirm the bundle initialized; throw a clear error if not. */
+    private verifyReady;
+    private isReady;
+}
+
+export { type A11ySession, BrowserSession, type BrowserSessionOptions, type OpenOptions, type PageSnapshot, type SnapshotOptions, assertOpenableUrl };

package/dist/browser.js

@@ -0,0 +1,3 @@
+export { BrowserSession, assertOpenableUrl } from './chunk-EXVRX5JP.js';
+//# sourceMappingURL=browser.js.map
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"browser.js"}