check_color_contrast

Validate color contrast ratios between foreground and background to ensure compliance with WCAG accessibility standards, supporting various color formats and font attributes.

Instructions

Check if a foreground and background color combination meets WCAG contrast requirements

Input Schema

TableJSON Schema

Name	Required	Description
`background`	Yes	Background color in various formats (e.g., "#FFFFFF", "#FFF", "rgb(255,255,255)", "hsv(0,0%,100%)")
`fontSize`	No	Font size in pixels
`foreground`	Yes	Foreground color in various formats (e.g., "#000000", "#000", "rgb(0,0,0)", "hsv(0,0%,0%)")
`isBold`	No	Whether the text is bold

Implementation Reference

src/index.ts:447-599 (handler)

The primary handler function for the 'check_color_contrast' tool. It destructures input arguments, parses foreground and background colors using helper functions, calculates the contrast ratio using the WCAG formula, launches a Puppeteer browser to create a test HTML page with the specified styles, runs Axe specifically on the 'color-contrast' rule, extracts results, determines WCAG AA/AAA compliance based on font size and boldness, and returns a detailed JSON response with normalized colors, ratios, and pass/fail status.

async checkColorContrast(args: any) {
  const { foreground, background, fontSize = 16, isBold = false } = args;

  if (!foreground || !background) {
    throw new McpError(
      ErrorCode.InvalidParams,
      'Missing required parameters: foreground and background colors'
    );
  }

  let browser;
  try {
    // Parse colors to RGB values
    let fgRgb, bgRgb;
    
    try {
      fgRgb = this.parseColor(foreground);
      bgRgb = this.parseColor(background);
    } catch (error) {
      throw new McpError(
        ErrorCode.InvalidParams,
        `Color parsing error: ${error instanceof Error ? error.message : String(error)}`
      );
    }
    
    // Convert to hex for Axe engine (as that's what it uses internally)
    const fgHex = this.rgbToHex(fgRgb);
    const bgHex = this.rgbToHex(bgRgb);
    
    // Calculate contrast ratio directly
    const directContrastRatio = this.calculateContrastRatio(fgRgb, bgRgb);

    browser = await puppeteer.launch({
      headless: true,
      args: ['--no-sandbox', '--disable-setuid-sandbox']
    });
    
    const page = await browser.newPage();
    
    // Create a simple HTML page with the specified colors
    const html = `
      <!DOCTYPE html>
      <html>
        <head>
          <style>
            .test-element {
              color: ${fgHex};
              background-color: ${bgHex};
              font-size: ${fontSize}px;
              font-weight: ${isBold ? 'bold' : 'normal'};
              padding: 20px;
            }
          </style>
        </head>
        <body>
          <div class="test-element">Test Text</div>
        </body>
      </html>
    `;
    
    await page.setContent(html);
    
    // Run only the color-contrast rule
    const axe = new AxePuppeteer(page)
      .options({
        runOnly: {
          type: 'rule',
          values: ['color-contrast']
        }
      });
    
    const result = await axe.analyze();
    
    // Check if there are any violations
    const passes = result.violations.length === 0;
    
    // Extract contrast ratio from failure summary text
    let contrastRatio: number | null = directContrastRatio; // Use our calculated ratio as default
    let extractionMethod = 'direct-calculation';
    
    if (result.violations.length > 0 && result.violations[0].nodes.length > 0) {
      const failureSummary = result.violations[0].nodes[0].failureSummary || '';
      
      // Extract contrast ratio from failure summary using regex
      const match = failureSummary.match(/contrast ratio of ([0-9.]+)/);
      if (match && match[1]) {
        contrastRatio = parseFloat(match[1]);
        extractionMethod = 'axe-calculation';
      }
      
      // Additional inspection of violation data
      if (contrastRatio === null) {
        // Log all properties of the first node to see if contrast data is available elsewhere
        const node = result.violations[0].nodes[0];
        
        if (node.any && node.any.length > 0) {
          if (node.any[0].data) {
            if (node.any[0].data.contrastRatio) {
              contrastRatio = node.any[0].data.contrastRatio;
              extractionMethod = 'axe-violation-data';
            }
          }
        }
      }
    } else if (result.passes.length > 0 && result.passes[0].nodes.length > 0) {
      // Try to extract from pass data
      const node = result.passes[0].nodes[0];
      if (node.any && node.any.length > 0 && node.any[0].data && node.any[0].data.contrastRatio) {
        contrastRatio = node.any[0].data.contrastRatio;
        extractionMethod = 'axe-pass-data';
      }
    }
    
    // Determine required contrast ratios based on font size
    const isLargeText = (fontSize >= 18) || (fontSize >= 14 && isBold);
    const requiredRatioAA = isLargeText ? 3.0 : 4.5;
    const requiredRatioAAA = isLargeText ? 4.5 : 7.0;
    
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            originalInput: {
              foreground: foreground,
              background: background,
            },
            normalizedColors: {
              foregroundHex: fgHex,
              backgroundHex: bgHex,
              foregroundRgb: `rgb(${fgRgb.r}, ${fgRgb.g}, ${fgRgb.b})`,
              backgroundRgb: `rgb(${bgRgb.r}, ${bgRgb.g}, ${bgRgb.b})`,
            },
            fontSize,
            isBold,
            contrastRatio,
            calculationMethod: extractionMethod,
            isLargeText,
            passesWCAG2AA: contrastRatio !== null ? contrastRatio >= requiredRatioAA : passes,
            requiredRatioForAA: requiredRatioAA,
            requiredRatioForAAA: requiredRatioAAA,
            passesWCAG2AAA: contrastRatio !== null ? contrastRatio >= requiredRatioAAA : null,
            helpUrl: "https://dequeuniversity.com/rules/axe/4.10/color-contrast"
          }, null, 2),
        },
      ],
    };
  } finally {
    if (browser) {
      await browser.close();
    }
  }
}

src/index.ts:103-126 (schema)

The input schema (inputSchema) for the 'check_color_contrast' tool, defining properties for foreground and background colors (strings supporting multiple formats), optional fontSize (number, default 16), and isBold (boolean, default false), with foreground and background required.

inputSchema: {
  type: 'object',
  properties: {
    foreground: {
      type: 'string',
      description: 'Foreground color in various formats (e.g., "#000000", "#000", "rgb(0,0,0)", "hsv(0,0%,0%)")',
    },
    background: {
      type: 'string',
      description: 'Background color in various formats (e.g., "#FFFFFF", "#FFF", "rgb(255,255,255)", "hsv(0,0%,100%)")',
    },
    fontSize: {
      type: 'number',
      description: 'Font size in pixels',
      default: 16
    },
    isBold: {
      type: 'boolean',
      description: 'Whether the text is bold',
      default: false
    }
  },
  required: ['foreground', 'background'],
},

src/index.ts:100-127 (registration)

Registration of the 'check_color_contrast' tool in the MCP server's listTools response, including the tool name, description, and full inputSchema.

{
  name: 'check_color_contrast',
  description: 'Check if a foreground and background color combination meets WCAG contrast requirements',
  inputSchema: {
    type: 'object',
    properties: {
      foreground: {
        type: 'string',
        description: 'Foreground color in various formats (e.g., "#000000", "#000", "rgb(0,0,0)", "hsv(0,0%,0%)")',
      },
      background: {
        type: 'string',
        description: 'Background color in various formats (e.g., "#FFFFFF", "#FFF", "rgb(255,255,255)", "hsv(0,0%,100%)")',
      },
      fontSize: {
        type: 'number',
        description: 'Font size in pixels',
        default: 16
      },
      isBold: {
        type: 'boolean',
        description: 'Whether the text is bold',
        default: false
      }
    },
    required: ['foreground', 'background'],
  },
},

src/index.ts:168-169 (registration)
Dispatch registration in the CallToolRequestSchema handler's switch statement, routing 'check_color_contrast' calls to the checkColorContrast method.
```
case 'check_color_contrast':
  return await this.checkColorContrast(request.params.arguments);
```

src/index.ts:428-445 (helper)

Core helper function that calculates the WCAG contrast ratio between two RGB colors using the standard luminance formula and relative luminance calculation.

private calculateContrastRatio(color1: { r: number, g: number, b: number }, color2: { r: number, g: number, b: number }): number {
  // Calculate luminance for a color
  const luminance = (rgb: { r: number, g: number, b: number }) => {
    const a = [rgb.r, rgb.g, rgb.b].map(v => {
      v /= 255;
      return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
    });
    return a[0] * 0.2126 + a[1] * 0.7152 + a[2] * 0.0722;
  };
  
  const l1 = luminance(color1);
  const l2 = luminance(color2);
  
  // Calculate contrast ratio
  const ratio = (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);
  
  return parseFloat(ratio.toFixed(2));
}

A11y MCP Server