PlayMCP Browser Automation Server

Instructions

Implementation Reference

• src/controllers/playwright.ts:519-602 (handler)

  The primary handler function that implements the getElementHierarchy tool logic by evaluating JavaScript in the browser to traverse and build the DOM element hierarchy.
  async getElementHierarchy( selector: string = 'body', maxDepth: number = 3, includeText: boolean = false, includeAttributes: boolean = false ): Promise<any> { try { if (!this.isInitialized()) { throw new Error('Browser not initialized'); } this.log('Getting element hierarchy', { selector, maxDepth, includeText, includeAttributes }); const hierarchy = await this.state.page?.evaluate((args: { selector: string, maxDepth: number, includeText: boolean, includeAttributes: boolean }) => { const { selector, maxDepth, includeText, includeAttributes } = args; function getElementInfo(element: Element) { const info: any = { tagName: element.tagName.toLowerCase(), id: element.id || undefined, className: element.className || undefined, children: [] }; if (includeText && element.textContent) { // Get only direct text content, not from children const directText = Array.from(element.childNodes) .filter(node => node.nodeType === Node.TEXT_NODE) .map(node => node.textContent?.trim()) .filter(text => text) .join(' '); if (directText) { info.text = directText; } } if (includeAttributes && element.attributes.length > 0) { info.attributes = {}; for (let i = 0; i < element.attributes.length; i++) { const attr = element.attributes[i]; if (attr.name !== 'id' && attr.name !== 'class') { info.attributes[attr.name] = attr.value; } } } return info; } function traverseElement(element: Element, currentDepth: number): any { const elementInfo = getElementInfo(element); if (currentDepth < maxDepth || maxDepth === -1) { const children = Array.from(element.children); elementInfo.children = children.map(child => traverseElement(child, currentDepth + 1) ); } else if (element.children.length > 0) { elementInfo.childrenCount = element.children.length; } return elementInfo; } const rootElement = document.querySelector(selector); if (!rootElement) { throw new Error(`Element not found: ${selector}`); } return traverseElement(rootElement, 0); }, { selector, maxDepth, includeText, includeAttributes }); this.log('Element hierarchy retrieved'); return hierarchy; } catch (error: any) { console.error('Get element hierarchy error:', error); throw new BrowserError('Failed to get element hierarchy', 'Check if the selector exists'); } }
• src/server.ts:233-258 (schema)

  The Tool object definition including name, description, and detailed inputSchema for parameter validation in the MCP protocol.
  const GET_ELEMENT_HIERARCHY_TOOL: Tool = { name: "getElementHierarchy", description: "Get the hierarchical structure of page elements with parent-child relationships", inputSchema: { type: "object", properties: { selector: { type: "string", description: "CSS selector for root element (default: 'body')" }, maxDepth: { type: "number", description: "Maximum depth to traverse (-1 for unlimited, default: 3)" }, includeText: { type: "boolean", description: "Include text content of elements (default: false)" }, includeAttributes: { type: "boolean", description: "Include element attributes (default: false)" } }, required: [] } };
• src/server.ts:533-533 (registration)

  Registration of the getElementHierarchy tool in the main tools object passed to the MCP server capabilities.
  getElementHierarchy: GET_ELEMENT_HIERARCHY_TOOL,
• src/server.ts:760-770 (registration)

  MCP server request handler (switch case) that dispatches calls to the controller's getElementHierarchy method and formats the response.
  case 'getElementHierarchy': { const hierarchy = await playwrightController.getElementHierarchy( args.selector as string || 'body', args.maxDepth as number || 3, args.includeText as boolean || false, args.includeAttributes as boolean || false ); return { content: [{ type: "text", text: JSON.stringify(hierarchy, null, 2) }] }; }