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; }