a11y-mcp

Instructions

Implementation Reference

• src/index.js:186-259 (handler)

  The main handler function for the 'get_summary' tool. It validates the input URL, launches a Puppeteer browser, loads the page, runs Axe accessibility checker, computes a summary including total issues, breakdown by severity, top 5 issues, and test counts, then returns it as JSON text content.

  async getSummary(args) {
    if (!args.url) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'URL is required'
      );
    }
  
    try {
      const browser = await puppeteer.launch({
        headless: 'new',
        args: ['--no-sandbox', '--disable-setuid-sandbox'],
      });
      const page = await browser.newPage();
      
      // Set a reasonable viewport
      await page.setViewport({ width: 1280, height: 800 });
      
      // Navigate to the page
      await page.goto(args.url, { waitUntil: 'networkidle2', timeout: 30000 });
      
      // Run axe on the page
      const results = await new AxePuppeteer(page).analyze();
      
      // Close the browser
      await browser.close();
      
      // Create a summary
      const summary = {
        url: args.url,
        timestamp: new Date().toISOString(),
        totalIssues: results.violations.length,
        issuesBySeverity: {
          critical: results.violations.filter(v => v.impact === 'critical').length,
          serious: results.violations.filter(v => v.impact === 'serious').length,
          moderate: results.violations.filter(v => v.impact === 'moderate').length,
          minor: results.violations.filter(v => v.impact === 'minor').length,
        },
        topIssues: results.violations
          .sort((a, b) => {
            const impactOrder = { critical: 0, serious: 1, moderate: 2, minor: 3 };
            return impactOrder[a.impact] - impactOrder[b.impact];
          })
          .slice(0, 5)
          .map(violation => ({
            id: violation.id,
            impact: violation.impact,
            description: violation.description,
            helpUrl: violation.helpUrl,
          })),
        passedTests: results.passes.length,
        incompleteTests: results.incomplete.length,
      };
      
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(summary, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error getting summary: ${error.message}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.js:69-78 (schema)

  Input schema definition for the 'get_summary' tool, specifying an object with a required 'url' string property.

  inputSchema: {
    type: 'object',
    properties: {
      url: {
        type: 'string',
        description: 'URL of the webpage to audit',
      },
    },
    required: ['url'],
  },

• src/index.js:66-79 (registration)

  Tool registration in the ListToolsRequestHandler response, defining name, description, and input schema for 'get_summary'.

  {
    name: 'get_summary',
    description: 'Get a summary of accessibility issues for a webpage',
    inputSchema: {
      type: 'object',
      properties: {
        url: {
          type: 'string',
          description: 'URL of the webpage to audit',
        },
      },
      required: ['url'],
    },
  },

• src/index.js:87-88 (registration)

  Dispatch registration in the CallToolRequestHandler switch statement, routing calls to the getSummary method.

  case 'get_summary':
    return this.getSummary(request.params.arguments);