feat: Lighthouse audits

Author: OrKoN

package-lock.json

@@ -61,6 +61,7 @@
     "eslint-import-resolver-typescript": "^4.4.4",
     "eslint-plugin-import": "^2.32.0",
     "globals": "^17.0.0",
+    "lighthouse": "^13.0.1",
     "prettier": "^3.6.2",
     "puppeteer": "24.36.0",
     "rollup": "4.56.0",

package.json

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import {readFileSync, writeFileSync} from 'node:fs';
 import {rm} from 'node:fs/promises';
 import {resolve} from 'node:path';
 
@@ -15,6 +16,29 @@ const filesToRemove = [
   'node_modules/chrome-devtools-frontend/front_end/third_party/intl-messageformat/package/package.json',
 ];
 
+/**
+ * Removes the conflicting global HTMLElementEventMap declaration from
+ * @paulirish/trace_engine/models/trace/ModelImpl.d.ts to avoid TS2717 error
+ * when both chrome-devtools-frontend and @paulirish/trace_engine declare
+ * the same property.
+ */
+function removeConflictingGlobalDeclaration(): void {
+  const filePath = resolve(
+    projectRoot,
+    'node_modules/@paulirish/trace_engine/models/trace/ModelImpl.d.ts',
+  );
+  console.log('Removing conflicting global declaration from @paulirish/trace_engine...');
+  const content = readFileSync(filePath, 'utf-8');
+  // Remove the declare global block using regex
+  // Matches: declare global { ... interface HTMLElementEventMap { ... } ... }
+  const newContent = content.replace(
+    /declare global\s*\{\s*interface HTMLElementEventMap\s*\{[^}]*\[ModelUpdateEvent\.eventName\]:\s*ModelUpdateEvent;\s*\}\s*\}/s,
+    '',
+  );
+  writeFileSync(filePath, newContent, 'utf-8');
+  console.log('Successfully removed conflicting global declaration.');
+}
+
 async function main() {
   console.log('Running prepare script to clean up chrome-devtools-frontend...');
   for (const file of filesToRemove) {
@@ -28,6 +52,8 @@ async function main() {
     }
   }
   console.log('Clean up of chrome-devtools-frontend complete.');
+
+  removeConflictingGlobalDeclaration();
 }
 
 void main();

scripts/prepare.ts

@@ -38,4 +38,5 @@ export {
   type ChromeReleaseChannel as BrowsersChromeReleaseChannel,
 } from '@puppeteer/browsers';
 
+export * as Lighthouse from 'lighthouse';
 export * as DevTools from '../../node_modules/chrome-devtools-frontend/mcp/mcp.js';

src/third_party/index.ts

@@ -0,0 +1,49 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {Lighthouse, zod} from '../third_party/index.js';
+
+import {ToolCategory} from './categories.js';
+import {defineTool} from './ToolDefinition.js';
+
+export const lighthouseAudit = defineTool({
+  name: 'lighthouse_audit',
+  description: `Runs a Lighthouse accessibility audit on the currently selected page. This tool analyzes the page for accessibility issues and provides a detailed report with scores and recommendations.`,
+  annotations: {
+    category: ToolCategory.PERFORMANCE,
+    readOnlyHint: true,
+  },
+  schema: {},
+  handler: async (request, response, context) => {
+    const page = context.getSelectedPage();
+    const url = page.url();
+
+    const flags = {
+      onlyCategories: ['accessibility'],
+    };
+
+    const result = await Lighthouse.default(url, flags, undefined, page);
+    const lhr = result!.lhr;
+    const accessibilityCategory = lhr.categories.accessibility;
+
+    const failedAudits = Object.values(lhr.audits).filter(
+      audit => audit.score !== null && audit.score < 1,
+    );
+    const passedAudits = Object.values(lhr.audits).filter(
+      audit => audit.score === 1,
+    );
+
+    const output = {
+      Accessibility: {
+        score: accessibilityCategory?.score ?? null,
+        failedAudits,
+        passedAudits,
+      },
+    };
+
+    response.appendResponseLine(JSON.stringify(output, null, 2));
+  },
+});

src/tools/lighthouse.ts

@@ -8,6 +8,7 @@ import * as consoleTools from './console.js';
 import * as emulationTools from './emulation.js';
 import * as extensionTools from './extensions.js';
 import * as inputTools from './input.js';
+import * as lighthouseTools from './lighthouse.js';
 import * as networkTools from './network.js';
 import * as pagesTools from './pages.js';
 import * as performanceTools from './performance.js';
@@ -21,6 +22,7 @@ const tools = [
   ...Object.values(emulationTools),
   ...Object.values(extensionTools),
   ...Object.values(inputTools),
+  ...Object.values(lighthouseTools),
   ...Object.values(networkTools),
   ...Object.values(pagesTools),
   ...Object.values(performanceTools),

src/tools/tools.ts

@@ -0,0 +1,193 @@
+exports[`lighthouse > lighthouse_audit > runs Lighthouse accessibility audit 1`] = `
+{
+  "Accessibility": {
+    "score": 0.94,
+    "failedAudits": [
+      {
+        "id": "landmark-one-main",
+        "title": "Document does not have a main landmark.",
+        "description": "One main landmark helps screen reader users navigate a web page. [Learn more about landmarks](https://dequeuniversity.com/rules/axe/4.11/landmark-one-main).",
+        "score": 0,
+        "scoreDisplayMode": "binary",
+        "details": {
+          "type": "table",
+          "headings": [
+            {
+              "key": "node",
+              "valueType": "node",
+              "subItemsHeading": {
+                "key": "relatedNode",
+                "valueType": "node"
+              },
+              "label": "Failing Elements"
+            }
+          ],
+          "items": [
+            {
+              "node": {
+                "type": "node",
+                "lhId": "1-0-HTML",
+                "path": "1,HTML",
+                "selector": "html",
+                "boundingRect": {
+                  "top": 0,
+                  "bottom": 34,
+                  "left": 0,
+                  "right": 412,
+                  "width": 412,
+                  "height": 34
+                },
+                "snippet": "<html lang=\\"en\\">",
+                "nodeLabel": "html",
+                "explanation": "Fix all of the following:\\n  Document does not have a main landmark"
+              }
+            }
+          ],
+          "debugData": {
+            "type": "debugdata",
+            "impact": "moderate",
+            "tags": [
+              "cat.semantics",
+              "best-practice"
+            ]
+          }
+        }
+      }
+    ],
+    "passedAudits": [
+      {
+        "id": "aria-hidden-body",
+        "title": "\`[aria-hidden=\\"true\\"]\` is not present on the document \`<body>\`",
+        "description": "Assistive technologies, like screen readers, work inconsistently when \`aria-hidden=\\"true\\"\` is set on the document \`<body>\`. [Learn how \`aria-hidden\` affects the document body](https://dequeuniversity.com/rules/axe/4.11/aria-hidden-body).",
+        "score": 1,
+        "scoreDisplayMode": "binary",
+        "details": {
+          "type": "table",
+          "headings": [
+            {
+              "key": "node",
+              "valueType": "node",
+              "subItemsHeading": {
+                "key": "relatedNode",
+                "valueType": "node"
+              },
+              "label": "Failing Elements"
+            }
+          ],
+          "items": []
+        }
+      },
+      {
+        "id": "color-contrast",
+        "title": "Background and foreground colors have a sufficient contrast ratio",
+        "description": "Low-contrast text is difficult or impossible for many users to read. [Learn how to provide sufficient color contrast](https://dequeuniversity.com/rules/axe/4.11/color-contrast).",
+        "score": 1,
+        "scoreDisplayMode": "binary",
+        "details": {
+          "type": "table",
+          "headings": [
+            {
+              "key": "node",
+              "valueType": "node",
+              "subItemsHeading": {
+                "key": "relatedNode",
+                "valueType": "node"
+              },
+              "label": "Failing Elements"
+            }
+          ],
+          "items": []
+        }
+      },
+      {
+        "id": "document-title",
+        "title": "Document has a \`<title>\` element",
+        "description": "The title gives screen reader users an overview of the page, and search engine users rely on it heavily to determine if a page is relevant to their search. [Learn more about document titles](https://dequeuniversity.com/rules/axe/4.11/document-title).",
+        "score": 1,
+        "scoreDisplayMode": "binary",
+        "details": {
+          "type": "table",
+          "headings": [
+            {
+              "key": "node",
+              "valueType": "node",
+              "subItemsHeading": {
+                "key": "relatedNode",
+                "valueType": "node"
+              },
+              "label": "Failing Elements"
+            }
+          ],
+          "items": []
+        }
+      },
+      {
+        "id": "html-has-lang",
+        "title": "\`<html>\` element has a \`[lang]\` attribute",
+        "description": "If a page doesn't specify a \`lang\` attribute, a screen reader assumes that the page is in the default language that the user chose when setting up the screen reader. If the page isn't actually in the default language, then the screen reader might not announce the page's text correctly. [Learn more about the \`lang\` attribute](https://dequeuniversity.com/rules/axe/4.11/html-has-lang).",
+        "score": 1,
+        "scoreDisplayMode": "binary",
+        "details": {
+          "type": "table",
+          "headings": [
+            {
+              "key": "node",
+              "valueType": "node",
+              "subItemsHeading": {
+                "key": "relatedNode",
+                "valueType": "node"
+              },
+              "label": "Failing Elements"
+            }
+          ],
+          "items": []
+        }
+      },
+      {
+        "id": "html-lang-valid",
+        "title": "\`<html>\` element has a valid value for its \`[lang]\` attribute",
+        "description": "Specifying a valid [BCP 47 language](https://www.w3.org/International/questions/qa-choosing-language-tags#question) helps screen readers announce text properly. [Learn how to use the \`lang\` attribute](https://dequeuniversity.com/rules/axe/4.11/html-lang-valid).",
+        "score": 1,
+        "scoreDisplayMode": "binary",
+        "details": {
+          "type": "table",
+          "headings": [
+            {
+              "key": "node",
+              "valueType": "node",
+              "subItemsHeading": {
+                "key": "relatedNode",
+                "valueType": "node"
+              },
+              "label": "Failing Elements"
+            }
+          ],
+          "items": []
+        }
+      },
+      {
+        "id": "meta-viewport",
+        "title": "\`[user-scalable=\\"no\\"]\` is not used in the \`<meta name=\\"viewport\\">\` element and the \`[maximum-scale]\` attribute is not less than 5.",
+        "description": "Disabling zooming is problematic for users with low vision who rely on screen magnification to properly see the contents of a web page. [Learn more about the viewport meta tag](https://dequeuniversity.com/rules/axe/4.11/meta-viewport).",
+        "score": 1,
+        "scoreDisplayMode": "binary",
+        "details": {
+          "type": "table",
+          "headings": [
+            {
+              "key": "node",
+              "valueType": "node",
+              "subItemsHeading": {
+                "key": "relatedNode",
+                "valueType": "node"
+              },
+              "label": "Failing Elements"
+            }
+          ],
+          "items": []
+        }
+      }
+    ]
+  }
+}
+`;

tests/tools/lighthouse.test.js.snapshot

@@ -0,0 +1,34 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import assert from 'node:assert';
+import {describe, it} from 'node:test';
+
+import {lighthouseAudit} from '../../src/tools/lighthouse.js';
+import {serverHooks} from '../server.js';
+import {html, withMcpContext} from '../utils.js';
+
+describe('lighthouse', () => {
+  const server = serverHooks();
+  describe('lighthouse_audit', () => {
+    it(
+      'runs Lighthouse accessibility audit',
+      async (t) => {
+        server.addHtmlRoute('/test', html`<div>Test</div>`);
+
+        await withMcpContext(async (response, context) => {
+          const page = context.getSelectedPage();
+          await page.goto(server.getRoute('/test'));
+
+          await lighthouseAudit.handler({params: {}}, response, context);
+
+          const responseText = response.responseLines.join('\n');
+          t.assert.snapshot?.(responseText);
+        });
+      },
+    );
+  });
+});