a11y-mcp

Instructions

Implementation Reference

• src/index.js:98-184 (handler)

  The handler function for 'audit_webpage' tool. Launches Puppeteer browser, navigates to the provided URL, runs Axe accessibility audit with optional tags, formats violations with node details (optionally including HTML), and returns JSON results.

  async auditWebpage(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 axeOptions = {};
      if (args.tags && args.tags.length > 0) {
        axeOptions.runOnly = {
          type: 'tag',
          values: args.tags,
        };
      }
      
      const results = await new AxePuppeteer(page).options(axeOptions).analyze();
      
      // Close the browser
      await browser.close();
      
      // Format the results
      const formattedResults = {
        url: args.url,
        timestamp: new Date().toISOString(),
        violations: results.violations.map(violation => {
          const formattedViolation = {
            id: violation.id,
            impact: violation.impact,
            description: violation.description,
            helpUrl: violation.helpUrl,
            nodes: violation.nodes.map(node => {
              const formattedNode = {
                impact: node.impact,
                target: node.target,
                failureSummary: node.failureSummary,
              };
              
              if (args.includeHtml) {
                formattedNode.html = node.html;
              }
              
              return formattedNode;
            }),
          };
          
          return formattedViolation;
        }),
        passes: results.passes.length,
        incomplete: results.incomplete.length,
        inapplicable: results.inapplicable.length,
      };
      
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(formattedResults, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error auditing webpage: ${error.message}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.js:43-64 (schema)

  Input schema for the 'audit_webpage' tool defining required 'url' and optional 'includeHtml' and 'tags' parameters.

  inputSchema: {
    type: 'object',
    properties: {
      url: {
        type: 'string',
        description: 'URL of the webpage to audit',
      },
      includeHtml: {
        type: 'boolean',
        description: 'Whether to include HTML snippets in the results',
        default: false,
      },
      tags: {
        type: 'array',
        items: {
          type: 'string',
        },
        description: 'Specific accessibility tags to check (e.g., wcag2a, wcag2aa, wcag21a, best-practice)',
      },
    },
    required: ['url'],
  },

• src/index.js:40-65 (registration)

  Registration of the 'audit_webpage' tool in the ListTools response, including name, description, and input schema.

  {
    name: 'audit_webpage',
    description: 'Perform an accessibility audit on a webpage',
    inputSchema: {
      type: 'object',
      properties: {
        url: {
          type: 'string',
          description: 'URL of the webpage to audit',
        },
        includeHtml: {
          type: 'boolean',
          description: 'Whether to include HTML snippets in the results',
          default: false,
        },
        tags: {
          type: 'array',
          items: {
            type: 'string',
          },
          description: 'Specific accessibility tags to check (e.g., wcag2a, wcag2aa, wcag21a, best-practice)',
        },
      },
      required: ['url'],
    },
  },

• src/index.js:85-86 (registration)

  Dispatch case in the CallToolRequestSchema handler that routes 'audit_webpage' calls to the auditWebpage method.

  case 'audit_webpage':
    return this.auditWebpage(request.params.arguments);