The A11y MCP (Model Context Protocol) server is a specialized tool designed to provide Large Language Models (LLMs) with programmatic access to web accessibility testing Application Programming Interfaces (APIs). Its primary function is to enable LLMs to analyze web content for compliance with Web Content Accessibility Guidelines (WCAG) and identify accessibility impediments.

The core methodology of this server revolves around integrating the Deque Axe-core API with Puppeteer, a headless browser automation library. Puppeteer is utilized to render web pages or HTML snippets in a browser environment, allowing Axe-core to accurately inspect the Document Object Model (DOM) and apply its accessibility rule set. This enables comprehensive analysis of dynamic content and client-side rendered elements, which static HTML parsers might miss.

The server exposes several distinct tools as part of its MCP interface, allowing LLMs to invoke specific accessibility checks:

1. test_accessibility: This tool accepts a public URL as input and, optionally, an array of WCAG tags (e.g., ["wcag2aa"]) to specify the desired compliance level or rule subset. It navigates Puppeteer to the given URL and executes Axe-core's comprehensive audit.
2. test_html_string: Similar to test_accessibility, but designed for analyzing raw HTML content provided as a string. This is useful for testing isolated components or dynamically generated markup before deployment. It also supports optional WCAG tag filtering.
3. get_rules: Provides information about the available accessibility rules within the Axe-core engine, potentially with filtering capabilities. This allows LLMs to understand the scope of checks that can be performed.
4. check_color_contrast: This specialized tool evaluates the WCAG compliance of a foreground and background color combination. It takes hexadecimal color codes for foreground and background as required parameters, with optional fontSize (in pixels, default 16) and isBold (boolean, default false) to accurately calculate the contrast ratio according to WCAG 2.x standards.
5. check_aria_attributes: This tool, inferred from the description "Check if ARIA attributes are used correctly in HTML," takes an HTML string as input and scrutinizes the proper application and usage of Accessible Rich Internet Applications (ARIA) attributes within the provided markup.
6. check_orientation_lock: This tool analyzes an HTML string to detect instances where content might force a specific screen orientation, which can be an accessibility barrier for users with certain needs or device configurations.

The server's response format is a structured JSON object. For accessibility audits (from test_accessibility and test_html_string), the primary output includes a violations array, detailing each detected issue with properties such as id (e.g., "color-contrast"), impact (e.g., "serious"), description, help text, and a helpUrl pointing to more information. Critically, each violation includes an affectedNodes array, providing the html snippet, target CSS selectors, and a failureSummary for specific instances of the violation. The response also includes counts for passes, incomplete, and inapplicable rules, a timestamp, the url tested (or about:blank for HTML strings), and detailed testEngine and testRunner information (e.g., Axe-core version) along with testEnvironment details like user agent, window dimensions, and orientation.

The server leverages @modelcontextprotocol/sdk for MCP communication, puppeteer for browser automation, @axe-core/puppeteer for integrating Axe-core with Puppeteer, and axe-core as the fundamental accessibility testing engine. Installation involves configuring the server within an MCP-enabled LLM application (e.g., Claude Desktop) by specifying a command like npx a11y-mcp-server to initiate the service.