Web Accessibility MCP Server

Instructions

Implementation Reference

• src/index.ts:387-506 (handler)

  The core handler function for the 'check_accessibility' tool. It validates input, launches a headless Puppeteer browser, navigates to the URL, waits for load, injects axe-core library, runs the accessibility audit, extracts violations with details (impact, description, help, nodes), and returns structured JSON results or error.

  private async handleAccessibilityCheck(request: any) {
    if (!request.params.arguments || typeof request.params.arguments.url !== 'string') {
      throw new McpError(
        ErrorCode.InvalidParams,
        'URL parameter is required'
      );
    }
  
    const args: AnalyzeUrlArgs = {
      url: request.params.arguments.url,
      waitForSelector: typeof request.params.arguments.waitForSelector === 'string' 
        ? request.params.arguments.waitForSelector 
        : undefined,
      userAgent: typeof request.params.arguments.userAgent === 'string'
        ? request.params.arguments.userAgent
        : 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'
    };
    
    try {
      const browser = await puppeteer.launch({
        headless: true,
        args: [
          '--no-sandbox',
          '--disable-setuid-sandbox',
          '--disable-dev-shm-usage',
          '--disable-accelerated-2d-canvas',
          '--disable-gpu',
          '--window-size=1920,1080',
          '--dns-prefetch-disable'
        ]
      });
      
      const page = await browser.newPage();
      await page.setViewport({ width: 1920, height: 1080 });
      await page.setUserAgent(args.userAgent || 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36');
      
      console.error(`[Debug] Navigating to ${args.url}`);
      const urlToUse = args.url.replace(/^(https?:\/\/)?(www\.)?/, 'https://www.');
      console.error(`[Debug] Modified URL: ${urlToUse}`);
      const response = await page.goto(urlToUse, { 
        waitUntil: 'domcontentloaded',
        timeout: 30000
      });
      
      console.error(`[Debug] Page loaded with status: ${response?.status()}`);
      
      await page.waitForSelector('body', { timeout: 30000 });
      await new Promise(resolve => setTimeout(resolve, 5000));
  
      await page.evaluate(axe.source);
      const results = await page.evaluate(() => {
        return new Promise((resolve) => {
          // @ts-ignore
          window.axe.run((err: any, results: any) => {
            if (err) {
              resolve({ error: err });
            }
            resolve(results);
          });
        });
      }) as {
        violations: Array<{
          impact: string;
          description: string;
          help: string;
          helpUrl: string;
          nodes: Array<{
            html: string;
            failureSummary: string;
          }>;
        }>;
        passes: unknown[];
        inapplicable: unknown[];
        incomplete: unknown[];
      };
  
      await browser.close();
  
      if ('error' in results) {
        throw new Error(String(results.error));
      }
  
      const violations = results.violations.map(violation => ({
        impact: violation.impact,
        description: violation.description,
        help: violation.help,
        helpUrl: violation.helpUrl,
        nodes: violation.nodes.map((node: any) => ({
          html: node.html,
          failureSummary: node.failureSummary,
        })),
      }));
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              url: args.url,
              timestamp: new Date().toISOString(),
              violations,
              passes: results.passes.length,
              inapplicable: results.inapplicable.length,
              incomplete: results.incomplete.length,
            }, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error analyzing URL: ${error instanceof Error ? error.message : String(error)}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:111-128 (schema)

  Input schema definition for the check_accessibility tool, specifying required 'url' and optional parameters for waitForSelector and userAgent.

  inputSchema: {
    type: 'object',
    properties: {
      url: {
        type: 'string',
        description: 'URL to analyze',
      },
      waitForSelector: {
        type: 'string',
        description: 'Optional CSS selector to wait for before analysis',
      },
      userAgent: {
        type: 'string',
        description: 'Optional user agent string to use for the request',
      },
    },
    required: ['url'],
  },

• src/index.ts:108-130 (registration)

  Registration of the check_accessibility tool in the ListTools response, including name, description, and schema.

  {
    name: 'check_accessibility',
    description: 'Check web accessibility of a given URL using axe-core',
    inputSchema: {
      type: 'object',
      properties: {
        url: {
          type: 'string',
          description: 'URL to analyze',
        },
        waitForSelector: {
          type: 'string',
          description: 'Optional CSS selector to wait for before analysis',
        },
        userAgent: {
          type: 'string',
          description: 'Optional user agent string to use for the request',
        },
      },
      required: ['url'],
    },
  },
  {

• src/index.ts:161-162 (registration)

  Dispatch/registration in the CallToolRequestSchema handler that routes calls to check_accessibility to the handleAccessibilityCheck method.

  if (request.params.name === 'check_accessibility') {
    return this.handleAccessibilityCheck(request);

• src/index.ts:67-71 (helper)

  TypeScript interface defining the arguments for URL analysis used in the handler.

  interface AnalyzeUrlArgs {
    url: string;
    waitForSelector?: string;
    userAgent?: string;
  }