MCP Accessibility Bridge

Instructions

Implementation Reference

• src/tools/queryAccessibilityTree.ts:26-67 (handler)

  The queryAccessibilityTreeHandler function implements the core logic: validates that at least role or accessibleName is provided, builds CDP parameters, sends Accessibility.queryAXTree command, filters non-ignored nodes, converts them to summaries using cdpAXNodeToSummary, and returns results.

  export async function queryAccessibilityTreeHandler(args: {
    role?: string;
    accessibleName?: string;
    backendNodeId?: number;
  }): Promise<ReturnType<typeof toolSuccess | typeof toolError>> {
    try {
      const { cdpSession } = browserManager.requireConnection();
  
      if (!args.role && !args.accessibleName) {
        return toolError(
          'At least one of "role" or "accessibleName" must be provided.'
        );
      }
  
      const params: Record<string, unknown> = {};
      if (args.role) params['role'] = args.role;
      if (args.accessibleName) params['accessibleName'] = args.accessibleName;
      if (args.backendNodeId !== undefined) params['backendNodeId'] = args.backendNodeId;
  
      const result = await cdpSession.send(
        'Accessibility.queryAXTree',
        params
      ) as QueryAXTreeResponse;
  
      const nodes = result.nodes ?? [];
      const summaries = nodes
        .filter((n) => !n.ignored)
        .map(cdpAXNodeToSummary);
  
      return toolSuccess({
        query: {
          role: args.role,
          accessibleName: args.accessibleName,
          backendNodeId: args.backendNodeId,
        },
        count: summaries.length,
        nodes: summaries,
      });
    } catch (error) {
      return toolError(error);
    }
  }

• src/tools/queryAccessibilityTree.ts:7-24 (schema)

  The queryAccessibilityTreeSchema defines input validation using Zod with three optional parameters: role (ARIA role string, case-insensitive), accessibleName (partial/exact name match, case-insensitive), and backendNodeId (DOM node ID to narrow search scope).

  export const queryAccessibilityTreeSchema = {
    role: z
      .string()
      .optional()
      .describe(
        'ARIA role to filter by (e.g. "button", "textbox", "link", "heading"). ' +
        'Case-insensitive.'
      ),
    accessibleName: z
      .string()
      .optional()
      .describe('Accessible name to match (partial or exact). Case-insensitive.'),
    backendNodeId: z
      .number()
      .int()
      .optional()
      .describe('DOM backend node ID to start search from (narrows scope).'),
  };

• src/index.ts:76-88 (registration)

  Tool registration with MCP server under the name 'query_accessibility_tree', including title, description explaining it searches by ARIA role/accessible name, and wiring up the schema and handler.

  // ── query_accessibility_tree ─────────────────────────────────────────────────
  server.registerTool(
    'query_accessibility_tree',
    {
      title: 'Query Accessibility Tree',
      description:
        'Search the accessibility tree by ARIA role and/or accessible name. ' +
        'Returns matching nodes with their properties. ' +
        'Example: role="button", accessibleName="Submit" finds all Submit buttons.',
      inputSchema: queryAccessibilityTreeSchema,
    },
    queryAccessibilityTreeHandler
  );

• src/utils/axTree.ts:15-43 (helper)

  The cdpAXNodeToSummary helper function converts raw CDP AX nodes into cleaner AXNodeSummary objects, extracting role, name, description, value, and various boolean properties (focused, disabled, checked, expanded, required, level, backendDOMNodeId).

  export function cdpAXNodeToSummary(node: CdpAXNode): AXNodeSummary {
    const role = (node.role?.value as string) ?? 'unknown';
    const name = (node.name?.value as string) ?? '';
    const description = node.description?.value as string | undefined;
    const value = node.value?.value as string | undefined;
  
    const props = node.properties ?? [];
    const focused = getPropertyValue(props, 'focused') as boolean | undefined;
    const disabled = getPropertyValue(props, 'disabled') as boolean | undefined;
    const checked = getPropertyValue(props, 'checked') as boolean | 'mixed' | undefined;
    const expanded = getPropertyValue(props, 'expanded') as boolean | undefined;
    const required = getPropertyValue(props, 'required') as boolean | undefined;
    const level = getPropertyValue(props, 'level') as number | undefined;
  
    return {
      role,
      name,
      ...(description !== undefined && { description }),
      ...(value !== undefined && { value }),
      ...(focused !== undefined && { focused }),
      ...(disabled !== undefined && { disabled }),
      ...(checked !== undefined && { checked }),
      ...(expanded !== undefined && { expanded }),
      ...(required !== undefined && { required }),
      ...(level !== undefined && { level }),
      ...(node.backendDOMNodeId !== undefined && { backendDOMNodeId: node.backendDOMNodeId }),
      nodeId: node.nodeId,
    };
  }

• src/browser/types.ts:44-83 (schema)

  Type definitions for the tool: QueryAXTreeResponse interface (lines 44-47) defines the CDP response with nodes array; AXNodeSummary interface (lines 68-83) defines the simplified output structure with role, name, and optional properties.

  // Accessibility.queryAXTree response
  export interface QueryAXTreeResponse {
    nodes: CdpAXNode[];
  }
  
  // DOM.describeNode response
  export interface DomDescribeNodeResponse {
    node: {
      nodeId: number;
      backendNodeId: number;
      nodeType: number;
      nodeName: string;
      localName: string;
      nodeValue: string;
      attributes?: string[];
      frameId?: string;
    };
  }
  
  // DOM.getOuterHTML response
  export interface DomGetOuterHtmlResponse {
    outerHTML: string;
  }
  
  // Summarized AX node used in tool responses
  export interface AXNodeSummary {
    role: string;
    name: string;
    description?: string;
    value?: string;
    focused?: boolean;
    disabled?: boolean;
    checked?: boolean | 'mixed';
    expanded?: boolean;
    required?: boolean;
    level?: number;
    backendDOMNodeId?: number;
    nodeId: string;
    children?: AXNodeSummary[];
  }