chore: support structured content (#744)

The idea is to turn formatters into instances and support both text and
JSON formatting. The structured content is output if the experimental
structured content flag is passed. For now, only the snapshots are
returned in a structured way.

Refs #689

Author: OrKoN

GEMINI.md

@@ -0,0 +1,4 @@
+# Instructions
+
+- use `npm run build` to run tsc and test build
+- use `npm run test` to run tests, run all tests to verify correctness

src/McpResponse.ts

@@ -17,7 +17,7 @@ import {
   getShortDescriptionForRequest,
   getStatusFromRequest,
 } from './formatters/networkFormatter.js';
-import {formatSnapshotNode} from './formatters/snapshotFormatter.js';
+import {SnapshotFormatter} from './formatters/SnapshotFormatter.js';
 import type {McpContext} from './McpContext.js';
 import {DevTools} from './third_party/index.js';
 import type {
@@ -181,29 +181,31 @@ export class McpResponse implements Response {
   async handle(
     toolName: string,
     context: McpContext,
-  ): Promise<Array<TextContent | ImageContent>> {
+  ): Promise<{
+    content: Array<TextContent | ImageContent>;
+    structuredContent: object;
+  }> {
     if (this.#includePages) {
       await context.createPagesSnapshot();
     }
 
-    let formattedSnapshot: string | undefined;
+    let snapshot: SnapshotFormatter | string | undefined;
     if (this.#snapshotParams) {
       await context.createTextSnapshot(
         this.#snapshotParams.verbose,
         this.#devToolsData,
       );
-      const snapshot = context.getTextSnapshot();
-      if (snapshot) {
+      const textSnapshot = context.getTextSnapshot();
+      if (textSnapshot) {
+        const formatter = new SnapshotFormatter(textSnapshot);
         if (this.#snapshotParams.filePath) {
           await context.saveFile(
-            new TextEncoder().encode(
-              formatSnapshotNode(snapshot.root, snapshot),
-            ),
+            new TextEncoder().encode(formatter.toString()),
             this.#snapshotParams.filePath,
           );
-          formattedSnapshot = `Saved snapshot to ${this.#snapshotParams.filePath}.`;
+          snapshot = this.#snapshotParams.filePath;
         } else {
-          formattedSnapshot = formatSnapshotNode(snapshot.root, snapshot);
+          snapshot = formatter;
         }
       }
     }
@@ -335,7 +337,7 @@ export class McpResponse implements Response {
       bodies,
       consoleData,
       consoleListData,
-      formattedSnapshot,
+      snapshot,
     });
   }
 
@@ -349,9 +351,9 @@ export class McpResponse implements Response {
       };
       consoleData: ConsoleMessageData | undefined;
       consoleListData: ConsoleMessageData[] | undefined;
-      formattedSnapshot: string | undefined;
+      snapshot: SnapshotFormatter | string | undefined;
     },
-  ): Array<TextContent | ImageContent> {
+  ): {content: Array<TextContent | ImageContent>; structuredContent: object} {
     const response = [`# ${toolName} response`];
     for (const line of this.#textResponseLines) {
       response.push(line);
@@ -393,9 +395,20 @@ Call ${handleDialog.name} to handle it before continuing.`);
       response.push(...parts);
     }
 
-    if (data.formattedSnapshot) {
-      response.push('## Latest page snapshot');
-      response.push(data.formattedSnapshot);
+    const structuredContent: {
+      snapshot?: object;
+      snapshotFilePath?: string;
+    } = {};
+
+    if (data.snapshot) {
+      if (typeof data.snapshot === 'string') {
+        response.push(`Saved snapshot to ${data.snapshot}.`);
+        structuredContent.snapshotFilePath = data.snapshot;
+      } else {
+        response.push('## Latest page snapshot');
+        response.push(data.snapshot.toString());
+        structuredContent.snapshot = data.snapshot.toJSON();
+      }
     }
 
     response.push(...this.#formatNetworkRequestData(context, data.bodies));
@@ -468,7 +481,10 @@ Call ${handleDialog.name} to handle it before continuing.`);
       } as const;
     });
 
-    return [text, ...images];
+    return {
+      content: [text, ...images],
+      structuredContent,
+    };
   }
 
   #dataWithPagination<T>(data: T[], pagination?: PaginationOptions) {

src/cli.ts

@@ -157,6 +157,11 @@ export const cliOptions = {
     describe: 'Whether to enable vision tools',
     hidden: true,
   },
+  experimentalStructuredContent: {
+    type: 'boolean',
+    describe: 'Whether to output structured formatted content.',
+    hidden: true,
+  },
   experimentalIncludeAllPages: {
     type: 'boolean',
     describe:

src/formatters/SnapshotFormatter.ts

@@ -0,0 +1,164 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type {TextSnapshot, TextSnapshotNode} from '../McpContext.js';
+
+export class SnapshotFormatter {
+  #snapshot: TextSnapshot;
+
+  constructor(snapshot: TextSnapshot) {
+    this.#snapshot = snapshot;
+  }
+
+  toString(): string {
+    const chunks: string[] = [];
+    const root = this.#snapshot.root;
+
+    // Top-level content of the snapshot.
+    if (
+      this.#snapshot.verbose &&
+      this.#snapshot.hasSelectedElement &&
+      !this.#snapshot.selectedElementUid
+    ) {
+      chunks.push(`Note: there is a selected element in the DevTools Elements panel but it is not included into the current a11y tree snapshot.
+Get a verbose snapshot to include all elements if you are interested in the selected element.\n\n`);
+    }
+
+    chunks.push(this.#formatNode(root, 0));
+    return chunks.join('');
+  }
+
+  toJSON(): object {
+    return this.#nodeToJSON(this.#snapshot.root);
+  }
+
+  #formatNode(node: TextSnapshotNode, depth = 0): string {
+    const chunks: string[] = [];
+    const attributes = this.#getAttributes(node);
+    const line =
+      ' '.repeat(depth * 2) +
+      attributes.join(' ') +
+      (node.id === this.#snapshot.selectedElementUid
+        ? ' [selected in the DevTools Elements panel]'
+        : '') +
+      '\n';
+    chunks.push(line);
+
+    for (const child of node.children) {
+      chunks.push(this.#formatNode(child, depth + 1));
+    }
+    return chunks.join('');
+  }
+
+  #nodeToJSON(node: TextSnapshotNode): object {
+    const rawAttrs = this.#getAttributesMap(node);
+    const children = node.children.map(child => this.#nodeToJSON(child));
+    const result: Record<string, unknown> = structuredClone(rawAttrs);
+    if (children.length > 0) {
+      result.children = children;
+    }
+    return result;
+  }
+
+  #getAttributes(serializedAXNodeRoot: TextSnapshotNode): string[] {
+    const attributes = [`uid=${serializedAXNodeRoot.id}`];
+
+    if (serializedAXNodeRoot.role) {
+      attributes.push(
+        serializedAXNodeRoot.role === 'none'
+          ? 'ignored'
+          : serializedAXNodeRoot.role,
+      );
+    }
+    if (serializedAXNodeRoot.name) {
+      attributes.push(`"${serializedAXNodeRoot.name}"`);
+    }
+
+    const simpleAttrs = this.#getAttributesMap(
+      serializedAXNodeRoot,
+      /* excludeSpecial */ true,
+    );
+
+    for (const attr of Object.keys(serializedAXNodeRoot).sort()) {
+      if (excludedAttributes.has(attr)) {
+        continue;
+      }
+
+      const mapped = booleanPropertyMap[attr];
+      if (mapped && simpleAttrs[mapped]) {
+        attributes.push(mapped);
+      }
+
+      const val = simpleAttrs[attr];
+      if (val === true) {
+        attributes.push(attr);
+      } else if (typeof val === 'string' || typeof val === 'number') {
+        attributes.push(`${attr}="${val}"`);
+      }
+    }
+
+    return attributes;
+  }
+
+  #getAttributesMap(
+    node: TextSnapshotNode,
+    excludeSpecial = false,
+  ): Record<string, unknown> {
+    const result: Record<string, unknown> = {};
+    if (!excludeSpecial) {
+      result.id = node.id;
+      if (node.role) {
+        result.role = node.role;
+      }
+      if (node.name) {
+        result.name = node.name;
+      }
+    }
+
+    // Re-implementing the exact logic from original function for #getAttributes to be safe:
+    return {
+      ...result,
+      ...this.#extractedAttributes(node),
+    };
+  }
+
+  #extractedAttributes(node: TextSnapshotNode): Record<string, unknown> {
+    const result: Record<string, unknown> = {};
+
+    for (const attr of Object.keys(node).sort()) {
+      if (excludedAttributes.has(attr)) {
+        continue;
+      }
+      const value = (node as unknown as Record<string, unknown>)[attr];
+      if (typeof value === 'boolean') {
+        if (booleanPropertyMap[attr]) {
+          result[booleanPropertyMap[attr]] = true;
+        }
+        if (value) {
+          result[attr] = true;
+        }
+      } else if (typeof value === 'string' || typeof value === 'number') {
+        result[attr] = value;
+      }
+    }
+    return result;
+  }
+}
+
+const booleanPropertyMap: Record<string, string> = {
+  disabled: 'disableable',
+  expanded: 'expandable',
+  focused: 'focusable',
+  selected: 'selectable',
+};
+
+const excludedAttributes = new Set([
+  'id',
+  'role',
+  'name',
+  'elementHandle',
+  'children',
+  'backendNodeId',
+]);