cli

Author: OrKoN

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 src/formatters/SnapshotFormatter.tssrc/formatters/snapshotFormatter.ts renamed to src/formatters/SnapshotFormatter.ts

@@ -6,20 +6,21 @@
 import type {TextSnapshot, TextSnapshotNode} from '../McpContext.js';
 
 export class SnapshotFormatter {
-  constructor(public snapshot?: TextSnapshot) {}
+  #snapshot: TextSnapshot;
+
+  constructor(snapshot: TextSnapshot) {
+    this.#snapshot = snapshot;
+  }
 
   toString(): string {
-    if (!this.snapshot) {
-      return '';
-    }
     const chunks: string[] = [];
-    const root = this.snapshot.root;
+    const root = this.#snapshot.root;
 
     // Top-level content of the snapshot.
     if (
-      this.snapshot.verbose &&
-      this.snapshot.hasSelectedElement &&
-      !this.snapshot.selectedElementUid
+      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`);
@@ -30,19 +31,16 @@ Get a verbose snapshot to include all elements if you are interested in the sele
   }
 
   toJSON(): object {
-    if (!this.snapshot) {
-      return {};
-    }
-    return this.#nodeToJSON(this.snapshot.root);
+    return this.#nodeToJSON(this.#snapshot.root);
   }
 
-  #formatNode(node: TextSnapshotNode, depth: number): string {
+  #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
+      (node.id === this.#snapshot.selectedElementUid
         ? ' [selected in the DevTools Elements panel]'
         : '') +
       '\n';
@@ -57,9 +55,7 @@ Get a verbose snapshot to include all elements if you are interested in the sele
   #nodeToJSON(node: TextSnapshotNode): object {
     const rawAttrs = this.#getAttributesMap(node);
     const children = node.children.map(child => this.#nodeToJSON(child));
-    const result: Record<string, unknown> = {
-      ...rawAttrs,
-    };
+    const result: Record<string, unknown> = structuredClone(rawAttrs);
     if (children.length > 0) {
       result.children = children;
     }

src/main.ts

@@ -153,10 +153,22 @@ function registerTool(tool: ToolDefinition): void {
           response,
           context,
         );
-        const {content} = await response.handle(tool.name, context);
-        return {
+        const {content, structuredContent} = await response.handle(
+          tool.name,
+          context,
+        );
+        const result: CallToolResult & {
+          structuredContent?: Record<string, unknown>;
+        } = {
           content,
         };
+        if (args.experimentalStructuredContent) {
+          result.structuredContent = structuredContent as Record<
+            string,
+            unknown
+          >;
+        }
+        return result;
       } catch (err) {
         logger(`${tool.name} error:`, err, err?.stack);
         let errorText = err && 'message' in err ? err.message : String(err);

tests/McpResponse.test.js.snapshot

@@ -166,7 +166,7 @@ Saved snapshot to <file>
 
 exports[`McpResponse > saves snapshot to file and returns structured content 2`] = `
 {
-  "snapshotFilePath": "/var/folders/hq/m1wr43z9665g5pghys7gkc2w00r23k/T/test-screenshot.png"
+  "snapshotFilePath": "<file>"
 }
 `;
 

tests/McpResponse.test.ts

@@ -18,6 +18,7 @@ import {
   getTextContent,
   html,
   stabilizeResponseOutput,
+  stabilizeStructuredContent,
   withMcpContext,
 } from './utils.js';
 
@@ -122,7 +123,13 @@ describe('McpResponse', () => {
         t.assert.snapshot?.(
           stabilizeResponseOutput(getTextContent(content[0])),
         );
-        t.assert.snapshot?.(JSON.stringify(structuredContent, null, 2));
+        t.assert.snapshot?.(
+          JSON.stringify(
+            stabilizeStructuredContent(structuredContent),
+            null,
+            2,
+          ),
+        );
       });
       const content = await readFile(filePath, 'utf-8');
       t.assert.snapshot?.(stabilizeResponseOutput(content));

tests/utils.ts

@@ -188,6 +188,27 @@ export function html(
 </html>`;
 }
 
+export function stabilizeStructuredContent(content: unknown): unknown {
+  if (typeof content === 'string') {
+    return stabilizeResponseOutput(content);
+  }
+  if (Array.isArray(content)) {
+    return content.map(item => stabilizeStructuredContent(item));
+  }
+  if (typeof content === 'object' && content !== null) {
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(content)) {
+      if (key === 'snapshotFilePath' && typeof value === 'string') {
+        result[key] = '<file>';
+      } else {
+        result[key] = stabilizeStructuredContent(value);
+      }
+    }
+    return result;
+  }
+  return content;
+}
+
 export function stabilizeResponseOutput(text: unknown) {
   if (typeof text !== 'string') {
     throw new Error('Input must be string');