Playwright MCP Server

Instructions

Implementation Reference

• src/server.ts:337-478 (handler)

  Core handler function for 'browser_snapshot' tool. Captures accessibility tree snapshot of the current page or specified element using Playwright's page.evaluate to extract ARIA attributes, roles, names, states, and builds a hierarchical tree structure for LLM-friendly page understanding.
  async (params: any) => { try { const input = z.object({ selector: z.string().optional() }).parse(params); await this.playwright.ensureConnected(); const page = this.playwright.getPage(); // Get the accessibility tree let snapshot; if (input.selector) { // Get accessibility snapshot for specific element const element = await page.locator(input.selector); snapshot = await element.locator('xpath=.').first().evaluate(async (el) => { // Use the browser's accessibility API to get semantic information const computedRole = el.getAttribute('role') || el.tagName.toLowerCase(); const computedName = el.getAttribute('aria-label') || el.getAttribute('aria-labelledby') || el.getAttribute('title') || (el as any).innerText?.trim() || el.getAttribute('alt') || el.getAttribute('placeholder') || ''; return { role: computedRole, name: computedName, value: (el as any).value || el.getAttribute('aria-valuenow') || '', description: el.getAttribute('aria-describedby') || el.getAttribute('title') || '', disabled: el.hasAttribute('disabled') || el.getAttribute('aria-disabled') === 'true', expanded: el.getAttribute('aria-expanded') === 'true', focused: document.activeElement === el, selected: el.getAttribute('aria-selected') === 'true', checked: el.getAttribute('aria-checked') || (el as any).checked, required: el.hasAttribute('required') || el.getAttribute('aria-required') === 'true', readonly: el.hasAttribute('readonly') || el.getAttribute('aria-readonly') === 'true', invalid: el.getAttribute('aria-invalid') || (el as any).validity?.valid === false ? 'true' : undefined, multiline: el.getAttribute('aria-multiline') === 'true', autocomplete: el.getAttribute('autocomplete'), placeholder: el.getAttribute('placeholder'), tagName: el.tagName.toLowerCase(), id: el.id, className: el.className, text: (el as any).innerText?.trim() || '', href: (el as any).href, src: (el as any).src }; }); } else { // Get accessibility snapshot for entire page snapshot = await page.evaluate(() => { function getAccessibilityInfo(element: Element): any { if (!element || element.nodeType !== Node.ELEMENT_NODE) return null; const el = element as HTMLElement; const computedRole = el.getAttribute('role') || el.tagName.toLowerCase(); const computedName = el.getAttribute('aria-label') || el.getAttribute('aria-labelledby') || el.getAttribute('title') || el.innerText?.trim().substring(0, 100) || el.getAttribute('alt') || el.getAttribute('placeholder') || ''; // Skip elements with no meaningful content unless they're interactive const interactiveRoles = ['button', 'link', 'input', 'select', 'textarea', 'checkbox', 'radio']; const isInteractive = interactiveRoles.includes(computedRole) || el.hasAttribute('onclick') || el.hasAttribute('href') || el.tabIndex >= 0; if (!computedName && !isInteractive && !el.getAttribute('aria-label')) { return null; } const info: any = { role: computedRole, name: computedName, tagName: el.tagName.toLowerCase() }; // Add important attributes if (el.id) info.id = el.id; if (el.className) info.className = el.className; if ((el as any).value) info.value = (el as any).value; if (el.getAttribute('aria-describedby')) info.description = el.getAttribute('aria-describedby'); if (el.hasAttribute('disabled') || el.getAttribute('aria-disabled') === 'true') info.disabled = true; if (el.getAttribute('aria-expanded')) info.expanded = el.getAttribute('aria-expanded') === 'true'; if (document.activeElement === el) info.focused = true; if (el.getAttribute('aria-selected')) info.selected = el.getAttribute('aria-selected') === 'true'; if (el.getAttribute('aria-checked') || (el as any).checked !== undefined) { info.checked = el.getAttribute('aria-checked') || (el as any).checked; } if (el.hasAttribute('required') || el.getAttribute('aria-required') === 'true') info.required = true; if (el.hasAttribute('readonly') || el.getAttribute('aria-readonly') === 'true') info.readonly = true; if ((el as any).href) info.href = (el as any).href; if (el.getAttribute('placeholder')) info.placeholder = el.getAttribute('placeholder'); // Generate a simple CSS selector for this element let selector = el.tagName.toLowerCase(); if (el.id) { selector = `#${el.id}`; } else if (el.className) { const classes = el.className.trim().split(/\s+/).slice(0, 2).join('.'); selector = `${selector}.${classes}`; } info.selector = selector; // Get children recursively, but limit depth to avoid huge trees const children: any[] = []; for (let child of Array.from(el.children).slice(0, 20)) { // Limit to first 20 children const childInfo = getAccessibilityInfo(child); if (childInfo) { children.push(childInfo); } } if (children.length > 0) { info.children = children; } return info; } return getAccessibilityInfo(document.body); }); } return { content: [{ type: 'text', text: `Accessibility tree snapshot:\n${JSON.stringify(snapshot, null, 2)}` }] }; } catch (error) { return { content: [{ type: 'text', text: `Browser snapshot failed: ${error instanceof Error ? error.message : String(error)}` }], isError: true }; } }
• src/types.ts:45-47 (schema)

  Zod input schema for the browser_snapshot tool, defining an optional selector parameter.
  export const BrowserSnapshotInputSchema = z.object({ selector: z.string().optional() });
• src/server.ts:328-479 (registration)

  Registration of the 'browser_snapshot' tool with the MCP server, specifying metadata, input schema, and handler function.
  this.server.registerTool( 'browser_snapshot', { title: 'Get Accessibility Tree Snapshot', description: 'Get accessibility tree snapshot for LLM-friendly element identification', inputSchema: { selector: z.string().optional() } }, async (params: any) => { try { const input = z.object({ selector: z.string().optional() }).parse(params); await this.playwright.ensureConnected(); const page = this.playwright.getPage(); // Get the accessibility tree let snapshot; if (input.selector) { // Get accessibility snapshot for specific element const element = await page.locator(input.selector); snapshot = await element.locator('xpath=.').first().evaluate(async (el) => { // Use the browser's accessibility API to get semantic information const computedRole = el.getAttribute('role') || el.tagName.toLowerCase(); const computedName = el.getAttribute('aria-label') || el.getAttribute('aria-labelledby') || el.getAttribute('title') || (el as any).innerText?.trim() || el.getAttribute('alt') || el.getAttribute('placeholder') || ''; return { role: computedRole, name: computedName, value: (el as any).value || el.getAttribute('aria-valuenow') || '', description: el.getAttribute('aria-describedby') || el.getAttribute('title') || '', disabled: el.hasAttribute('disabled') || el.getAttribute('aria-disabled') === 'true', expanded: el.getAttribute('aria-expanded') === 'true', focused: document.activeElement === el, selected: el.getAttribute('aria-selected') === 'true', checked: el.getAttribute('aria-checked') || (el as any).checked, required: el.hasAttribute('required') || el.getAttribute('aria-required') === 'true', readonly: el.hasAttribute('readonly') || el.getAttribute('aria-readonly') === 'true', invalid: el.getAttribute('aria-invalid') || (el as any).validity?.valid === false ? 'true' : undefined, multiline: el.getAttribute('aria-multiline') === 'true', autocomplete: el.getAttribute('autocomplete'), placeholder: el.getAttribute('placeholder'), tagName: el.tagName.toLowerCase(), id: el.id, className: el.className, text: (el as any).innerText?.trim() || '', href: (el as any).href, src: (el as any).src }; }); } else { // Get accessibility snapshot for entire page snapshot = await page.evaluate(() => { function getAccessibilityInfo(element: Element): any { if (!element || element.nodeType !== Node.ELEMENT_NODE) return null; const el = element as HTMLElement; const computedRole = el.getAttribute('role') || el.tagName.toLowerCase(); const computedName = el.getAttribute('aria-label') || el.getAttribute('aria-labelledby') || el.getAttribute('title') || el.innerText?.trim().substring(0, 100) || el.getAttribute('alt') || el.getAttribute('placeholder') || ''; // Skip elements with no meaningful content unless they're interactive const interactiveRoles = ['button', 'link', 'input', 'select', 'textarea', 'checkbox', 'radio']; const isInteractive = interactiveRoles.includes(computedRole) || el.hasAttribute('onclick') || el.hasAttribute('href') || el.tabIndex >= 0; if (!computedName && !isInteractive && !el.getAttribute('aria-label')) { return null; } const info: any = { role: computedRole, name: computedName, tagName: el.tagName.toLowerCase() }; // Add important attributes if (el.id) info.id = el.id; if (el.className) info.className = el.className; if ((el as any).value) info.value = (el as any).value; if (el.getAttribute('aria-describedby')) info.description = el.getAttribute('aria-describedby'); if (el.hasAttribute('disabled') || el.getAttribute('aria-disabled') === 'true') info.disabled = true; if (el.getAttribute('aria-expanded')) info.expanded = el.getAttribute('aria-expanded') === 'true'; if (document.activeElement === el) info.focused = true; if (el.getAttribute('aria-selected')) info.selected = el.getAttribute('aria-selected') === 'true'; if (el.getAttribute('aria-checked') || (el as any).checked !== undefined) { info.checked = el.getAttribute('aria-checked') || (el as any).checked; } if (el.hasAttribute('required') || el.getAttribute('aria-required') === 'true') info.required = true; if (el.hasAttribute('readonly') || el.getAttribute('aria-readonly') === 'true') info.readonly = true; if ((el as any).href) info.href = (el as any).href; if (el.getAttribute('placeholder')) info.placeholder = el.getAttribute('placeholder'); // Generate a simple CSS selector for this element let selector = el.tagName.toLowerCase(); if (el.id) { selector = `#${el.id}`; } else if (el.className) { const classes = el.className.trim().split(/\s+/).slice(0, 2).join('.'); selector = `${selector}.${classes}`; } info.selector = selector; // Get children recursively, but limit depth to avoid huge trees const children: any[] = []; for (let child of Array.from(el.children).slice(0, 20)) { // Limit to first 20 children const childInfo = getAccessibilityInfo(child); if (childInfo) { children.push(childInfo); } } if (children.length > 0) { info.children = children; } return info; } return getAccessibilityInfo(document.body); }); } return { content: [{ type: 'text', text: `Accessibility tree snapshot:\n${JSON.stringify(snapshot, null, 2)}` }] }; } catch (error) { return { content: [{ type: 'text', text: `Browser snapshot failed: ${error instanceof Error ? error.message : String(error)}` }], isError: true }; } } );
• src/types.ts:70-98 (helper)

  Type definition for the accessibility node structure used in the browser_snapshot output tree.
  export interface AccessibilityNode { role: string; name?: string; value?: string; description?: string; keyshortcuts?: string; roledescription?: string; valuetext?: string; disabled?: boolean; expanded?: boolean; focused?: boolean; modal?: boolean; multiline?: boolean; multiselectable?: boolean; readonly?: boolean; required?: boolean; selected?: boolean; checked?: boolean | 'mixed'; pressed?: boolean | 'mixed'; level?: number; valuemin?: number; valuemax?: number; autocomplete?: string; haspopup?: string; invalid?: string; orientation?: string; children?: AccessibilityNode[]; selector?: string; }
• src/types.ts:66-66 (schema)

  TypeScript input type for browser_snapshot derived from the Zod schema.
  export type BrowserSnapshotInput = z.infer<typeof BrowserSnapshotInputSchema>;