A11y MCP Server

Instructions

Implementation Reference

• src/index.ts:46-65 (registration)

  Registration of the 'test_accessibility' tool in the MCP ListTools handler, defining its name, description, and input schema.

  {
    name: 'test_accessibility',
    description: 'Test a webpage for accessibility issues using Axe-core',
    inputSchema: {
      type: 'object',
      properties: {
        url: {
          type: 'string',
          description: 'URL of the webpage to test',
        },
        tags: {
          type: 'array',
          items: { type: 'string' },
          description: 'Optional array of accessibility tags to test (e.g., "wcag2a", "wcag2aa", "wcag21a")',
          default: ['wcag2aa']
        }
      },
      required: ['url'],
    },
  },

• src/index.ts:193-238 (handler)

  The main handler function for 'test_accessibility' tool. Launches Puppeteer browser, navigates to the provided URL, runs Axe accessibility analysis (optionally filtered by tags), formats results, and returns as MCP content.

  async testAccessibility(args: any) {
    const { url, tags } = args;
  
    if (!url) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Missing required parameter: url'
      );
    }
  
    let browser;
    try {
      browser = await puppeteer.launch({
        headless: true,
        args: ['--no-sandbox', '--disable-setuid-sandbox']
      });
      const page = await browser.newPage();
      
      // Set a reasonable viewport
      await page.setViewport({ width: 1280, height: 800 });
      
      await page.goto(url, { waitUntil: 'networkidle0', timeout: 0 });
      
      // Run axe analysis
      const axe = new AxePuppeteer(page);
      
      if (tags && tags.length > 0) {
        axe.withTags(tags);
      }
      
      const result = await axe.analyze();
      
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(this.formatResults(result), null, 2),
          },
        ],
      };
    } finally {
      if (browser) {
        await browser.close();
      }
    }
  }

• src/index.ts:772-798 (helper)

  Helper function used by the test_accessibility handler to format AxeResults into a structured JSON response with violations, passes, and metadata.

  private formatResults(result: AxeResults) {
    return {
      violations: result.violations.map((violation: Result) => ({
        id: violation.id,
        impact: violation.impact || 'unknown',
        description: violation.description,
        help: violation.help,
        helpUrl: violation.helpUrl,
        affectedNodes: violation.nodes.map((node: NodeResult) => ({
          html: node.html,
          target: node.target,
          failureSummary: node.failureSummary || ''
        }))
      })),
      passes: result.passes.length,
      incomplete: result.incomplete.length,
      inapplicable: result.inapplicable.length,
      timestamp: result.timestamp,
      url: result.url,
      testEngine: {
        name: result.testEngine.name,
        version: result.testEngine.version
      },
      testRunner: result.testRunner,
      testEnvironment: result.testEnvironment,
    };
  }