Merge pull request #13 from ashtonchew/feature/dynamic-context-control

feat: add dynamic context control for get-pointed-element tool

Author: elieteyssedou

.changeset/remove-legacy-support.md

@@ -0,0 +1,14 @@
+---
+"@mcp-pointer/server": minor
+"@mcp-pointer/shared": minor
+---
+
+**Architecture Cleanup & Improvements**
+
+- **Server**: Store full CSS properties in `cssProperties` instead of filtering to 5 properties
+- **Server**: Remove LEGACY_ELEMENT_SELECTED support - only DOM_ELEMENT_POINTED is now supported
+- **Server**: Delete unused files (`mcp-handler.ts`, `websocket-server.ts`)
+- **Server**: Simplify types - remove StateDataV1 and LegacySharedState
+- **Server**: Dynamic CSS filtering now happens on-the-fly during MCP tool calls based on cssLevel parameter
+
+This enables full CSS details to be accessible without re-pointing to elements, with filtering applied server-side based on tool parameters.

CONTRIBUTING.md

@@ -62,9 +62,16 @@ packages/
 ├── server/              # @mcp-pointer/server - MCP Server (TypeScript)
 │   ├── src/
 │   │   ├── start.ts      # Main server entry point
-│   │   ├── cli.ts        # Command line interface  
-│   │   ├── websocket-server.ts
-│   │   └── mcp-handler.ts
+│   │   ├── cli.ts        # Command line interface
+│   │   ├── message-handler.ts  # Message routing & state building
+│   │   ├── services/
+│   │   │   ├── websocket-service.ts      # WebSocket with leader election
+│   │   │   ├── mcp-service.ts            # MCP protocol handler
+│   │   │   ├── element-processor.ts      # Raw→Processed conversion
+│   │   │   └── shared-state-service.ts   # State persistence
+│   │   └── utils/
+│   │       ├── dom-extractor.ts    # HTML parsing utilities
+│   │       └── element-detail.ts   # Dynamic CSS/text filtering
 │   ├── dist/
 │   │   └── cli.cjs       # Bundled standalone CLI
 │   └── package.json
@@ -73,15 +80,17 @@ packages/
 │   ├── src/
 │   │   ├── background.ts # Service worker
 │   │   ├── content.ts    # Element selection
-│   │   └── element-sender-service.ts
+│   │   └── services/
+│   │       └── element-sender-service.ts  # WebSocket client
 │   ├── dev/              # Development build (with logging)
 │   ├── dist/             # Production build (minified)
 │   └── manifest.json
 │
 └── shared/             # @mcp-pointer/shared - Shared TypeScript types
     ├── src/
-    │   ├── Logger.ts
-    │   └── types.ts
+    │   ├── logger.ts
+    │   ├── types.ts
+    │   └── detail.ts   # CSS/text detail level constants
     └── package.json
 ```
 
@@ -119,9 +128,16 @@ packages/
 ├── server/              # @mcp-pointer/server - MCP Server (TypeScript)
 │   ├── src/
 │   │   ├── start.ts      # Main server entry point
-│   │   ├── cli.ts        # Command line interface  
-│   │   ├── websocket-server.ts
-│   │   └── mcp-handler.ts
+│   │   ├── cli.ts        # Command line interface
+│   │   ├── message-handler.ts  # Message routing & state building
+│   │   ├── services/
+│   │   │   ├── websocket-service.ts      # WebSocket with leader election
+│   │   │   ├── mcp-service.ts            # MCP protocol handler
+│   │   │   ├── element-processor.ts      # Raw→Processed conversion
+│   │   │   └── shared-state-service.ts   # State persistence
+│   │   └── utils/
+│   │       ├── dom-extractor.ts    # HTML parsing utilities
+│   │       └── element-detail.ts   # Dynamic CSS/text filtering
 │   ├── dist/
 │   │   └── cli.cjs       # Bundled standalone CLI
 │   └── package.json
@@ -130,15 +146,17 @@ packages/
 │   ├── src/
 │   │   ├── background.ts # Service worker
 │   │   ├── content.ts    # Element selection
-│   │   └── element-sender-service.ts
+│   │   └── services/
+│   │       └── element-sender-service.ts  # WebSocket client
 │   ├── dev/              # Development build (with logging)
 │   ├── dist/             # Production build (minified)
 │   └── manifest.json
 │
 └── shared/             # @mcp-pointer/shared - Shared TypeScript types
     ├── src/
-    │   ├── Logger.ts
-    │   └── types.ts
+    │   ├── logger.ts
+    │   ├── types.ts
+    │   └── detail.ts   # CSS/text detail level constants
     └── package.json
 ```
 

README.md

@@ -21,6 +21,7 @@ The extension lets you visually select DOM elements in the browser, and the MCP
 
 - 🎯 **`Option+Click` Selection** - Simply hold `Option` (Alt on Windows) and click any element
 - 📋 **Complete Element Data** - Text content, CSS classes, HTML attributes, positioning, and styling
+- 💡 **Dynamic Context Control** - Request visible-only text, suppress text entirely, or dial CSS detail from none → full computed styles per MCP call
 - ⚛️ **React Component Detection** - Component names and source files via Fiber (experimental)
 - 🔗 **WebSocket Connection** - Real-time communication between browser and AI tools
 - 🤖 **MCP Compatible** - Works with Claude Code and other MCP-enabled AI tools
@@ -102,7 +103,9 @@ After configuration, **restart your coding tool** to load the MCP connection.
 Your AI tool will automatically start the MCP server when needed using the `npx -y @mcp-pointer/server@latest start` command.
 
 **Available MCP Tool:**
-- `get-pointed-element` - Get textual information about the currently pointed DOM element from the browser extension
+- `get-pointed-element` – Returns textual information about the currently pointed DOM element. Optional arguments:
+  - `textDetail`: `0 | 1 | 2` (default `2`) controls how much text to include (`0 = none`, `1 = visible text only`, `2 = visible + hidden`).
+  - `cssLevel`: `0 | 1 | 2 | 3` (default `1`) controls styling detail, from no CSS (0) up to full computed styles (3).
 
 ## 🎯 How It Works
 

packages/chrome-extension/CHANGELOG.md

@@ -20,6 +20,10 @@
 
 ## 0.5.0
 
+### Minor Changes
+
+- Added dynamic context control (text detail & css levels)
+
 ### Patch Changes
 
 - Updated dependencies [d91e764]

packages/chrome-extension/src/background.ts

@@ -68,6 +68,8 @@ chrome.runtime.onMessage
 
       sendResponse({ success: true });
     }
+
+    return true; // Keep message channel open for async response
   });
 
 // Handle extension install/update

packages/chrome-extension/src/utils/element.ts

@@ -1,218 +1,9 @@
 // Disable ESLint rule for underscore dangle usage in this file (React internals)
 /* eslint-disable no-underscore-dangle */
 
-import {
-  ComponentInfo, CSSProperties, ElementPosition, TargetedElement, RawPointedDOMElement,
-} from '@mcp-pointer/shared/types';
+import { RawPointedDOMElement } from '@mcp-pointer/shared/types';
 import logger from './logger';
 
-export interface ReactSourceInfo {
-  fileName: string;
-  lineNumber?: number;
-  columnNumber?: number;
-}
-
-/**
- * Get source file information from a DOM element's React component
- */
-export function getSourceFromElement(element: HTMLElement): ReactSourceInfo | null {
-  // Find React Fiber key
-  const fiberKey = Object.keys(element).find((key) => key.startsWith('__reactFiber$')
-    || key.startsWith('__reactInternalInstance$'));
-
-  if (!fiberKey) return null;
-
-  const fiber = (element as any)[fiberKey];
-  if (!fiber) return null;
-
-  // Walk up fiber tree to find component fiber (skip DOM fibers)
-  let componentFiber = fiber;
-  while (componentFiber && typeof componentFiber.type === 'string') {
-    componentFiber = componentFiber.return;
-  }
-
-  if (!componentFiber) return null;
-
-  // Try multiple source locations (React version differences)
-  // React 18: _debugSource
-  if (componentFiber._debugSource) {
-    return {
-      fileName: componentFiber._debugSource.fileName,
-      lineNumber: componentFiber._debugSource.lineNumber,
-      columnNumber: componentFiber._debugSource.columnNumber,
-    };
-  }
-
-  // React 19: _debugInfo (often null)
-  if (componentFiber._debugInfo) {
-    return componentFiber._debugInfo;
-  }
-
-  // Babel plugin: __source on element type
-  if (componentFiber.elementType?.__source) {
-    return {
-      fileName: componentFiber.elementType.__source.fileName,
-      lineNumber: componentFiber.elementType.__source.lineNumber,
-      columnNumber: componentFiber.elementType.__source.columnNumber,
-    };
-  }
-
-  // Alternative: _owner chain
-  if (componentFiber._debugOwner?._debugSource) {
-    return {
-      fileName: componentFiber._debugOwner._debugSource.fileName,
-      lineNumber: componentFiber._debugOwner._debugSource.lineNumber,
-      columnNumber: componentFiber._debugOwner._debugSource.columnNumber,
-    };
-  }
-
-  // Check pendingProps for __source
-  if (componentFiber.pendingProps?.__source) {
-    return {
-      fileName: componentFiber.pendingProps.__source.fileName,
-      lineNumber: componentFiber.pendingProps.__source.lineNumber,
-      columnNumber: componentFiber.pendingProps.__source.columnNumber,
-    };
-  }
-
-  return null;
-}
-
-/**
- * Extract React Fiber information from an element
- */
-export function getReactFiberInfo(element: HTMLElement): ComponentInfo | undefined {
-  try {
-    // Use comprehensive source detection
-    const sourceInfo = getSourceFromElement(element);
-
-    // Also get component name
-    const fiberKey = Object.keys(element).find((key) => key.startsWith('__reactFiber$')
-      || key.startsWith('__reactInternalInstance$'));
-
-    if (fiberKey) {
-      const fiber = (element as any)[fiberKey];
-      if (fiber) {
-        // Find component fiber
-        let componentFiber = fiber;
-        while (componentFiber && typeof componentFiber.type === 'string') {
-          componentFiber = componentFiber.return;
-        }
-
-        if (componentFiber && componentFiber.type && typeof componentFiber.type === 'function') {
-          const componentName = componentFiber.type.displayName
-                               || componentFiber.type.name
-                               || 'Unknown';
-
-          let sourceFile: string | undefined;
-          if (sourceInfo) {
-            const fileName = sourceInfo.fileName.split('/').pop() || sourceInfo.fileName;
-            sourceFile = sourceInfo.lineNumber
-              ? `${fileName}:${sourceInfo.lineNumber}`
-              : fileName;
-          }
-
-          const result = {
-            name: componentName,
-            sourceFile,
-            framework: 'react' as const,
-          };
-
-          logger.debug('🧬 Found React Fiber info:', result);
-          return result;
-        }
-      }
-    }
-
-    return undefined;
-  } catch (error) {
-    logger.error('🚨 Error extracting Fiber info:', error);
-    return undefined;
-  }
-}
-
-/**
- * Extract all attributes from an HTML element
- */
-export function getElementAttributes(element: HTMLElement): Record<string, string> {
-  const attributes: Record<string, string> = {};
-  for (let i = 0; i < element.attributes.length; i += 1) {
-    const attr = element.attributes[i];
-    attributes[attr.name] = attr.value;
-  }
-  return attributes;
-}
-
-/**
- * Generate a CSS selector for an element
- */
-export function generateSelector(element: HTMLElement): string {
-  let selector = element.tagName.toLowerCase();
-  if (element.id) selector += `#${element.id}`;
-  if (element.className) {
-    const classNameStr = typeof element.className === 'string'
-      ? element.className
-      : (element.className as any).baseVal || '';
-    const classes = classNameStr.split(' ').filter((c: string) => c.trim());
-    if (classes.length > 0) selector += `.${classes.join('.')}`;
-  }
-  return selector;
-}
-
-/**
- * Get element position relative to the page
- */
-export function getElementPosition(element: HTMLElement): ElementPosition {
-  const rect = element.getBoundingClientRect();
-  return {
-    x: rect.left + window.scrollX,
-    y: rect.top + window.scrollY,
-    width: rect.width,
-    height: rect.height,
-  };
-}
-
-/**
- * Extract relevant CSS properties from an element
- */
-export function getElementCSSProperties(element: HTMLElement): CSSProperties {
-  const computedStyle = window.getComputedStyle(element);
-  return {
-    display: computedStyle.display,
-    position: computedStyle.position,
-    fontSize: computedStyle.fontSize,
-    color: computedStyle.color,
-    backgroundColor: computedStyle.backgroundColor,
-  };
-}
-
-/**
- * Extract CSS classes from an element as an array
- */
-export function getElementClasses(element: HTMLElement): string[] {
-  if (!element.className) return [];
-  const classNameStr = typeof element.className === 'string'
-    ? element.className
-    : (element.className as any).baseVal || '';
-  return classNameStr.split(' ').filter((c: string) => c.trim());
-}
-
-export function adaptTargetToElement(element: HTMLElement): TargetedElement {
-  return {
-    selector: generateSelector(element),
-    tagName: element.tagName,
-    id: element.id || undefined,
-    classes: getElementClasses(element),
-    innerText: element.innerText || element.textContent || '',
-    attributes: getElementAttributes(element),
-    position: getElementPosition(element),
-    cssProperties: getElementCSSProperties(element),
-    componentInfo: getReactFiberInfo(element),
-    timestamp: Date.now(),
-    url: window.location.href,
-  };
-}
-
 /**
  * Extract raw React Fiber from an element (if present)
  */

packages/chrome-extension/src/utils/types.ts

@@ -20,6 +20,8 @@
 
   Server ready for browser extension updates.
 
+- Added dynamic context control (text detail & css levels)
+
 ### Patch Changes
 
 - 1c9cef4: Replace jsdom with node-html-parser for better bundling