feat(server): add element shaping utility for dynamic detail control

Author: ashtonchew

packages/server/src/__tests__/test-helpers.ts

@@ -25,23 +25,38 @@ export async function cleanupTestFiles(): Promise<void> {
 }
 
 export function createMockElement(): TargetedElement {
+  const text = 'Test Element';
   return {
     selector: 'div.test-element',
     tagName: 'DIV',
     id: 'test-id',
     classes: ['test-class'],
-    innerText: 'Test Element',
+    innerText: text,
+    textContent: text,
+    textDetail: 'full',
+    textVariants: {
+      visible: text,
+      full: text,
+    },
     attributes: { 'data-test': 'true' },
     position: {
       x: 100, y: 200, width: 300, height: 50,
     },
+    cssLevel: 1,
     cssProperties: {
       display: 'block',
       position: 'relative',
       fontSize: '16px',
       color: 'rgb(0, 0, 0)',
       backgroundColor: 'rgb(255, 255, 255)',
     },
+    cssComputed: {
+      display: 'block',
+      position: 'relative',
+      fontSize: '16px',
+      color: 'rgb(0, 0, 0)',
+      backgroundColor: 'rgb(255, 255, 255)',
+    },
     timestamp: Date.now(),
     url: 'https://example.com',
     tabId: 123,

packages/server/src/mcp-handler.ts

@@ -5,7 +5,14 @@ import {
   ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 import { version } from 'process';
+import { CSS_DETAIL_OPTIONS, TEXT_DETAIL_OPTIONS } from '@mcp-pointer/shared/detail';
 import type PointerWebSocketServer from './websocket-server';
+import {
+  normalizeDetailParameters,
+  shapeElementForDetail,
+  type DetailParameters,
+  type NormalizedDetailParameters,
+} from './utils/element-detail';
 
 enum MCPToolName {
   GET_POINTED_ELEMENT = 'get-pointed-element',
@@ -47,10 +54,21 @@ export default class MCPHandler {
       tools: [
         {
           name: MCPToolName.GET_POINTED_ELEMENT,
-          description: 'Get information about the currently pointed/shown DOM element from the browser extension, in order to let you see a specific element the user is showing you on his/her the browser.',
+          description: 'Get information about the currently pointed/shown DOM element. Control returned payload size with optional textDetail (full|visible|none) and cssLevel (0-3).',
           inputSchema: {
             type: 'object',
-            properties: {},
+            properties: {
+              textDetail: {
+                type: 'string',
+                enum: [...TEXT_DETAIL_OPTIONS],
+                description: 'Controls how much text is returned. full (default) includes hidden text fallback, visible uses only rendered text, none omits text fields.',
+              },
+              cssLevel: {
+                type: 'integer',
+                enum: [...CSS_DETAIL_OPTIONS],
+                description: 'Controls CSS payload detail. 0 omits CSS, 1 includes layout basics, 2 adds box model, 3 returns the full computed style.',
+              },
+            },
             required: [],
           },
         },
@@ -60,13 +78,16 @@ export default class MCPHandler {
 
   private async handleCallTool(request: any) {
     if (request.params.name === MCPToolName.GET_POINTED_ELEMENT) {
-      return this.getTargetedElement();
+      const normalized = normalizeDetailParameters(
+        request.params.arguments as DetailParameters | undefined,
+      );
+      return this.getTargetedElement(normalized);
     }
 
     throw new Error(`Unknown tool: ${request.params.name}`);
   }
 
-  private getTargetedElement() {
+  private getTargetedElement(details: NormalizedDetailParameters) {
     const element = this.wsServer.getCurrentElement();
 
     if (!element) {
@@ -81,11 +102,13 @@ export default class MCPHandler {
       };
     }
 
+    const shapedElement = shapeElementForDetail(element, details.textDetail, details.cssLevel);
+
     return {
       content: [
         {
           type: 'text',
-          text: JSON.stringify(element, null, 2),
+          text: JSON.stringify(shapedElement, null, 2),
         },
       ],
     };