Webby MCP Server

Instructions

Implementation Reference

• src/accessibility/axe.ts:44-126 (handler)

  The core handler function `analyzeAxe` that launches a headless Chromium browser using Playwright, navigates to the URL, injects the axe-core library, runs WCAG-specific accessibility tests, processes violations by impact level, and returns structured results including counts and detailed issues.

  export async function analyzeAxe(
    url: string,
    options: AxeOptions = {}
  ): Promise<AxeResult> {
    let browser: Browser | null = null;
    let page: Page | null = null;
  
    try {
      // Launch browser
      browser = await chromium.launch({ headless: true });
      page = await browser.newPage();
  
      // Navigate to page
      await page.goto(url, { timeout: options.timeout || 60000, waitUntil: 'networkidle' });
  
      // Inject axe-core
      await page.addScriptTag({
        url: 'https://cdnjs.cloudflare.com/ajax/libs/axe-core/4.10.2/axe.min.js',
      });
  
      // Run axe analysis
      const wcagLevel = options.wcagLevel || 'wcag2aa';
      const results = await page.evaluate((level) => {
        return (window as any).axe.run({
          runOnly: {
            type: 'tag',
            values: [level],
          },
        });
      }, wcagLevel);
  
      await browser.close();
  
      // Count violations by severity
      const critical = results.violations.filter((v: any) => v.impact === 'critical').length;
      const serious = results.violations.filter((v: any) => v.impact === 'serious').length;
      const moderate = results.violations.filter((v: any) => v.impact === 'moderate').length;
      const minor = results.violations.filter((v: any) => v.impact === 'minor').length;
  
      // Format violations
      const issues: AxeViolation[] = results.violations.map((v: any) => ({
        id: v.id,
        impact: v.impact,
        description: v.description,
        helpUrl: v.helpUrl,
        nodes: v.nodes.length,
      }));
  
      return {
        tool: 'axe',
        success: true,
        url,
        wcagLevel,
        violations: results.violations.length,
        critical,
        serious,
        moderate,
        minor,
        passes: results.passes.length,
        incomplete: results.incomplete.length,
        issues,
      };
    } catch (error) {
      if (browser) {
        await browser.close();
      }
      return {
        tool: 'axe',
        success: false,
        url,
        wcagLevel: options.wcagLevel || 'wcag2aa',
        violations: 0,
        critical: 0,
        serious: 0,
        moderate: 0,
        minor: 0,
        passes: 0,
        incomplete: 0,
        issues: [],
        error: error instanceof Error ? error.message : String(error),
      };
    }
  }

• index.ts:188-199 (registration)

  MCP tool registration defining the tool name, description, and input schema for the validate_accessibility_axe tool.

  {
    name: 'validate_accessibility_axe',
    description: 'Analyze website accessibility using Axe. Free, open-source, finds ~57% of WCAG issues with zero false positives.',
    inputSchema: {
      type: 'object',
      properties: {
        url: { type: 'string' },
        wcagLevel: { type: 'string', description: 'WCAG level (wcag2a, wcag2aa, wcag2aaa, wcag21aa, wcag22aa)' },
      },
      required: ['url'],
    },
  },

• index.ts:61-64 (schema)

  Zod validation schema for the tool's input arguments, ensuring URL is valid and wcagLevel is optional string.

  const AxeArgsSchema = z.object({
    url: z.string().url(),
    wcagLevel: z.string().optional(),
  });

• index.ts:362-368 (handler)

  Dispatcher case in the main MCP callToolRequest handler that validates arguments and delegates to the analyzeAxe implementation.

  case 'validate_accessibility_axe': {
    const validatedArgs = AxeArgsSchema.parse(args);
    const result = await analyzeAxe(validatedArgs.url, {
      wcagLevel: validatedArgs.wcagLevel,
    });
    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
  }