Add accessibility audit API and MCP tool

Expose accessibility auditing across the stack: add IPage.RunAccessibilityAuditAsync and a Page.RunAccessibilityAuditAsync implementation, and register a new MCP tool (audit_accessibility) in AccessibilityTools. Wire the tool into McpServerHost so it is advertised to clients. Enhance PageSnapshotService to build a reverse ref->backend-node map and add GetRefForNodeId so audit results can be tied to element refs. Add unit, integration, and wire tests for the tool and update test fakes to support audit results and failures. Small test/interface adjustments to accommodate the new API.

Author: TorreyBetts

src/Motus.Abstractions/IPage.cs

@@ -177,6 +177,16 @@ public interface IPage : IAsyncDisposable
     /// <returns>A snapshot of the accessibility tree.</returns>
     Task<AccessibilitySnapshot> AccessibilitySnapshotAsync(CancellationToken ct = default);
 
+    /// <summary>
+    /// Runs the built-in WCAG accessibility rules against the page's accessibility
+    /// tree and returns the violations found. Each violation carries a rule id,
+    /// severity, message, and, where the offending element is addressable, the
+    /// backend DOM node identifier that <see cref="LocatorByBackendNodeId"/> can target.
+    /// </summary>
+    /// <param name="ct">A token to cancel the operation.</param>
+    /// <returns>The audit result, including the violations and pass count.</returns>
+    Task<AccessibilityAuditResult> RunAccessibilityAuditAsync(CancellationToken ct = default);
+
     // --- Locators ---
 
     /// <summary>

src/Motus.Mcp/McpServerHost.cs

@@ -68,6 +68,7 @@ internal static async Task RunAsync(
         mcpBuilder.WithTools<PageTools>(McpJsonUtilities.DefaultOptions);
         mcpBuilder.WithTools<NetworkTools>(McpJsonUtilities.DefaultOptions);
         mcpBuilder.WithTools<ConsoleTools>(McpJsonUtilities.DefaultOptions);
+        mcpBuilder.WithTools<AccessibilityTools>(McpJsonUtilities.DefaultOptions);
 
         using var host = builder.Build();
 

src/Motus.Mcp/Snapshot/PageSnapshotService.cs

@@ -11,6 +11,7 @@ public sealed class PageSnapshotService
 {
     private readonly IPage _page;
     private IReadOnlyDictionary<string, long>? _refToBackendNodeId;
+    private IReadOnlyDictionary<long, string>? _backendNodeIdToRef;
 
     public PageSnapshotService(IPage page)
     {
@@ -70,10 +71,21 @@ public async Task<string> TakeSnapshotAsync(string? rootRef, int? maxDepth, Canc
         }
 
         _refToBackendNodeId = serialized.RefToBackendNodeId;
+        _backendNodeIdToRef = BuildReverseMap(serialized.RefToBackendNodeId);
         LastSnapshot = serialized.Text;
         return serialized.Text;
     }
 
+    private static Dictionary<long, string> BuildReverseMap(IReadOnlyDictionary<string, long> forward)
+    {
+        // The forward map is 1:1 (each ref maps to a distinct backend node), so a
+        // straight inversion is unambiguous.
+        var reverse = new Dictionary<long, string>(forward.Count);
+        foreach (var (refId, backendNodeId) in forward)
+            reverse[backendNodeId] = refId;
+        return reverse;
+    }
+
     /// <summary>
     /// Resolves a ref from the current snapshot to a locator. The element is
     /// resolved lazily when an action runs on the returned locator; if it has since
@@ -91,4 +103,15 @@ public ILocator ResolveRef(string refId)
 
         return _page.LocatorByBackendNodeId(backendNodeId);
     }
+
+    /// <summary>
+    /// Returns the ref the current snapshot assigned to the given backend DOM node,
+    /// or null when no snapshot has been taken or the node was not assigned a ref
+    /// (for example, a node the snapshot does not address).
+    /// </summary>
+    public string? GetRefForNodeId(long backendNodeId)
+        => _backendNodeIdToRef is not null
+            && _backendNodeIdToRef.TryGetValue(backendNodeId, out var refId)
+            ? refId
+            : null;
 }

src/Motus.Mcp/Tools/AccessibilityTools.cs

@@ -0,0 +1,103 @@
+using System.ComponentModel;
+using System.Text.Json;
+using System.Text.Json.Nodes;
+using ModelContextProtocol.Protocol;
+using ModelContextProtocol.Server;
+using Motus.Abstractions;
+
+namespace Motus.Mcp;
+
+/// <summary>
+/// Checks the active page against the built-in WCAG accessibility rules and reports
+/// the violations found, each tied to a ref where the offending element can be
+/// addressed by other tools.
+/// </summary>
+[McpServerToolType]
+public sealed class AccessibilityTools
+{
+    [McpServerTool(Name = "audit_accessibility", Title = "Audit accessibility", Destructive = false, ReadOnly = true)]
+    [Description("Runs WCAG 2.1 A and AA accessibility checks against the active page and returns the "
+        + "violations found, each with a rule id, severity, message, and (when the element is addressable) "
+        + "a ref usable with click, type, and other tools. A fresh snapshot is taken as part of the audit, "
+        + "so refs from an earlier snapshot are replaced.")]
+    public static async Task<CallToolResult> AuditAccessibilityAsync(
+        [Description("Only return violations at or above this severity: error, warning, or info. "
+            + "Omit to return all severities.")] string? min_severity,
+        ActivePageService pageService,
+        CancellationToken cancellationToken)
+    {
+        AccessibilityViolationSeverity? threshold = null;
+        if (!string.IsNullOrWhiteSpace(min_severity))
+        {
+            if (!Enum.TryParse(min_severity, ignoreCase: true, out AccessibilityViolationSeverity parsed))
+                return ToolResultHelper.Error(
+                    $"Unknown severity '{min_severity}'. Use error, warning, or info.");
+            threshold = parsed;
+        }
+
+        try
+        {
+            var page = await pageService.GetOrCreateActivePageAsync(cancellationToken).ConfigureAwait(false);
+
+            // A fresh snapshot refreshes the ref map so element-level violations can be
+            // tied back to a ref the other tools accept.
+            var snapshots = pageService.GetSnapshotService(page);
+            await snapshots.TakeSnapshotAsync(cancellationToken).ConfigureAwait(false);
+
+            var result = await page.RunAccessibilityAuditAsync(cancellationToken).ConfigureAwait(false);
+
+            // Severity is ordered Error, Warning, Info, so "at or above" a threshold is
+            // a lower-or-equal ordinal.
+            var violations = threshold is { } min
+                ? result.Violations.Where(v => (int)v.Severity <= (int)min).ToList()
+                : result.Violations.ToList();
+
+            if (violations.Count == 0)
+            {
+                var none = threshold is { } onlyAbove
+                    ? $"No accessibility violations found at or above {onlyAbove.ToString().ToLowerInvariant()} severity."
+                    : "No accessibility violations found.";
+                return ToolResultHelper.Text(Append(none, result.DiagnosticMessage));
+            }
+
+            var array = new JsonArray();
+            foreach (var violation in violations)
+            {
+                var refId = violation.BackendDOMNodeId is long nodeId
+                    ? snapshots.GetRefForNodeId(nodeId)
+                    : null;
+
+                array.Add(new JsonObject
+                {
+                    ["ruleId"] = violation.RuleId,
+                    ["severity"] = violation.Severity.ToString(),
+                    ["message"] = violation.Message,
+                    ["nodeRole"] = violation.NodeRole,
+                    ["nodeName"] = violation.NodeName,
+                    ["ref"] = refId,
+                });
+            }
+
+            var payload = new JsonObject
+            {
+                ["violationCount"] = violations.Count,
+                ["violations"] = array,
+            };
+
+            // Build the structured value through the node API and parse it, rather than
+            // reflection-serializing a type, so the trim and AOT analyzers stay satisfied.
+            var element = JsonDocument.Parse(payload.ToJsonString()).RootElement.Clone();
+            var summary = Append(
+                $"Found {violations.Count} accessibility violation(s).",
+                result.DiagnosticMessage);
+            return ToolResultHelper.Structured(element, summary);
+        }
+        catch (Exception ex)
+        {
+            return ToolResultHelper.Error($"Accessibility audit failed: {ex.Message}");
+        }
+    }
+
+    private static string Append(string text, string? diagnostic)
+        => string.IsNullOrEmpty(diagnostic) ? text : $"{text} {diagnostic}";
+}

src/Motus/Page/Page.Accessibility.cs

@@ -24,6 +24,13 @@ public async Task<AccessibilitySnapshot> AccessibilitySnapshotAsync(Cancellation
             DiagnosticMessage: treeResult.DiagnosticMessage);
     }
 
+    /// <summary>
+    /// Runs the accessibility rules registered on this page's context against the
+    /// page's accessibility tree and returns the violations found.
+    /// </summary>
+    public Task<AccessibilityAuditResult> RunAccessibilityAuditAsync(CancellationToken ct = default)
+        => RunAccessibilityAuditAsync(_context.AccessibilityRules.Snapshot(), ct);
+
     /// <summary>
     /// Runs the registered accessibility rules against this page's accessibility tree.
     /// Pre-fetches computed styles, duplicate IDs, and document language for rules that need them.

tests/Motus.Mcp.Tests/Snapshot/PageSnapshotServiceTests.cs

@@ -53,6 +53,37 @@ public async Task TakeSnapshot_StoresLastSnapshotText()
         StringAssert.Contains(text, "- button \"Go\" [ref=e1]");
     }
 
+    [TestMethod]
+    public void GetRefForNodeId_BeforeSnapshot_ReturnsNull()
+    {
+        var service = new PageSnapshotService(new FakeAccessibilityPage(EmptySnapshot()));
+
+        Assert.IsNull(service.GetRefForNodeId(5));
+    }
+
+    [TestMethod]
+    public async Task GetRefForNodeId_AfterSnapshot_ReturnsRefForKnownNode_AndNullOtherwise()
+    {
+        var snapshot = new AccessibilitySnapshot(
+            Roots:
+            [
+                new AccessibilityNode("1", "img", "", null, null,
+                    new Dictionary<string, string?>(), [], BackendDOMNodeId: 5),
+                new AccessibilityNode("2", "button", "Go", null, null,
+                    new Dictionary<string, string?>(), [], BackendDOMNodeId: 7),
+            ],
+            IgnoredCount: 0,
+            DiagnosticMessage: null);
+
+        var service = new PageSnapshotService(new FakeAccessibilityPage(snapshot));
+        await service.TakeSnapshotAsync();
+
+        // Refs are assigned in document order, so the inverse maps each id back to its ref.
+        Assert.AreEqual("e1", service.GetRefForNodeId(5));
+        Assert.AreEqual("e2", service.GetRefForNodeId(7));
+        Assert.IsNull(service.GetRefForNodeId(999));
+    }
+
     private static AccessibilitySnapshot EmptySnapshot()
         => new([], IgnoredCount: 0, DiagnosticMessage: null);
 
@@ -65,6 +96,9 @@ private sealed class FakeAccessibilityPage(AccessibilitySnapshot snapshot) : IPa
         public Task<AccessibilitySnapshot> AccessibilitySnapshotAsync(CancellationToken ct = default)
             => Task.FromResult(snapshot);
 
+        public Task<AccessibilityAuditResult> RunAccessibilityAuditAsync(CancellationToken ct = default)
+            => throw new NotImplementedException();
+
         public ILocator LocatorByBackendNodeId(long backendNodeId) => throw new NotImplementedException();
 
         public ValueTask DisposeAsync() => ValueTask.CompletedTask;

tests/Motus.Mcp.Tests/Tools/AccessibilityIntegrationTests.cs

@@ -0,0 +1,118 @@
+using System.Linq;
+using System.Text.Json;
+using ModelContextProtocol.Protocol;
+using Motus.Mcp;
+
+namespace Motus.Mcp.Tests.Tools;
+
+/// <summary>
+/// Drives the accessibility tool through a real browser: auditing a page seeded with
+/// known defects, confirming the violations come back with refs for the addressable
+/// ones, and that the severity filter narrows the result.
+/// </summary>
+[TestClass]
+[TestCategory("Integration")]
+public class AccessibilityIntegrationTests
+{
+    // A page with an image missing alt text, an empty button, an unlabeled input, and
+    // (being a data: document) no lang attribute. Each trips a built-in rule.
+    private const string DefectivePage =
+        "data:text/html,<title>A11y</title><img src=x><button></button><input>";
+
+    private BrowserSessionManager? _sessions;
+    private ActivePageService? _pages;
+
+    [TestInitialize]
+    public void Setup()
+    {
+        var executablePath = ResolveInstalledBrowser();
+        if (executablePath is null)
+            Assert.Inconclusive("No installed browser found; skipping integration test.");
+
+        _sessions = new BrowserSessionManager(new McpServerLaunchOptions
+        {
+            Headless = true,
+            ExecutablePath = executablePath,
+        });
+        _pages = new ActivePageService(_sessions);
+    }
+
+    [TestCleanup]
+    public async Task Cleanup()
+    {
+        if (_pages is not null)
+            await _pages.DisposeAsync();
+        if (_sessions is not null)
+            await _sessions.DisposeAsync();
+    }
+
+    [TestMethod]
+    public async Task AuditDefectivePage_OnARealBrowser()
+    {
+        var pages = _pages!;
+        var ct = CancellationToken.None;
+
+        AssertOk(await CoreTools.NavigateAsync(DefectivePage, pages, ct), "navigate");
+
+        var all = await AccessibilityTools.AuditAccessibilityAsync(null, pages, ct);
+        AssertOk(all, "audit_accessibility");
+
+        var violations = Violations(all);
+        Assert.IsTrue(violations.Length > 0, "expected at least one violation");
+
+        var rules = violations.Select(v => v.GetProperty("ruleId").GetString()).ToArray();
+        var rulesText = string.Join(", ", rules);
+
+        // A data: document carries no lang attribute, so this page-level rule fires.
+        CollectionAssert.Contains(rules, "a11y-missing-lang", $"rules were: {rulesText}");
+
+        // The empty button and unlabeled input are addressable, so at least one
+        // violation carries a ref back to its element.
+        Assert.IsTrue(
+            violations.Any(v => v.GetProperty("ref").ValueKind != JsonValueKind.Null),
+            $"expected at least one violation to carry a ref; rules were: {rulesText}");
+
+        // Filtering to errors returns a subset, all of which are errors.
+        var errorsOnly = await AccessibilityTools.AuditAccessibilityAsync("error", pages, ct);
+        AssertOk(errorsOnly, "audit_accessibility error filter");
+
+        var errors = Violations(errorsOnly);
+        Assert.IsTrue(errors.Length <= violations.Length);
+        Assert.IsTrue(
+            errors.All(v => v.GetProperty("severity").GetString() == "Error"),
+            "every filtered violation should be an error");
+    }
+
+    private static JsonElement[] Violations(CallToolResult result)
+    {
+        Assert.IsNotNull(result.StructuredContent, "expected structured content");
+        return result.StructuredContent!.Value.GetProperty("violations").EnumerateArray().ToArray();
+    }
+
+    private static void AssertOk(CallToolResult result, string label)
+        => Assert.IsFalse(result.IsError ?? false, $"{label} should succeed: {TextOf(result)}");
+
+    private static string TextOf(CallToolResult result)
+        => result.Content.Count > 0 && result.Content[0] is TextContentBlock t ? t.Text : string.Empty;
+
+    private static string? ResolveInstalledBrowser()
+    {
+        var cacheDir = Path.Combine(
+            Environment.GetFolderPath(Environment.SpecialFolder.UserProfile),
+            ".motus",
+            "browsers");
+
+        foreach (var marker in new[] { ".installed.chromium", ".installed" })
+        {
+            var markerPath = Path.Combine(cacheDir, marker);
+            if (!File.Exists(markerPath))
+                continue;
+
+            var executablePath = File.ReadAllText(markerPath).Trim();
+            if (File.Exists(executablePath))
+                return executablePath;
+        }
+
+        return null;
+    }
+}