AccessLint MCP Server

MCP (Model Context Protocol) server providing accessibility analysis tools for WCAG 2.1 conformance.

Overview

This MCP server provides programmatic tools for color contrast analysis according to WCAG 2.1 standards. It's designed to be used with Claude Desktop and as part of the AccessLint marketplace plugin for Claude Code.

Installation

For Claude Desktop

Install and configure the MCP server in your Claude Desktop configuration:

{
  "mcpServers": {
    "accesslint": {
      "command": "npx",
      "args": ["-y", "@accesslint/mcp"]
    }
  }
}

Or install globally:

npm install -g @accesslint/mcp

Then configure with:

{
  "mcpServers": {
    "accesslint": {
      "command": "accesslint-mcp"
    }
  }
}

For Claude Code

This MCP server is automatically included when you install the AccessLint plugin from the marketplace:

# In Claude Code, the plugin includes this MCP server
# No separate installation needed

Tools

calculate_contrast_ratio

Calculate the WCAG contrast ratio between two colors.

Parameters:

• foreground (string, required): Foreground color in hex (#RGB, #RRGGBB), rgb(r,g,b), or rgba(r,g,b,a) format
• background (string, required): Background color in the same formats

Returns:

{
  "foreground": "#7c8aff",
  "background": "#ffffff",
  "ratio": 2.8
}

Example:

calculate_contrast_ratio({
  foreground: "#7c8aff",
  background: "#ffffff"
})

analyze_color_pair

Analyze a color pair for WCAG conformance with detailed pass/fail information.

Parameters:

• foreground (string, required): Foreground color
• background (string, required): Background color
• contentType (enum, optional): Type of content being checked
  • "normal-text" (default): Regular text content (requires 4.5:1 for AA)
  • "large-text": Large text 18pt+ or 14pt+ bold (requires 3:1 for AA)
  • "ui-component": UI component boundaries, icons (requires 3:1 for AA)
• level (enum, optional): WCAG conformance level
  • "AA" (default): Level AA conformance
  • "AAA": Level AAA conformance

Returns:

{
  "foreground": "#7c8aff",
  "background": "#ffffff",
  "ratio": 2.8,
  "passes": {
    "normalText": false,
    "largeText": false,
    "uiComponent": false
  },
  "requirement": {
    "level": "AA",
    "contentType": "normal-text",
    "minimumRatio": 4.5,
    "guideline": "1.4.3 Contrast (Minimum)"
  },
  "meetsRequirement": false
}

Example:

analyze_color_pair({
  foreground: "#4c5dcc",
  background: "#ffffff",
  contentType: "normal-text",
  level: "AA"
})

suggest_accessible_color

Get accessible color alternatives that meet WCAG requirements while preserving design intent.

Parameters:

• foreground (string, required): Current foreground color
• background (string, required): Current background color
• targetRatio (number, required): Target contrast ratio (e.g., 4.5 for normal text, 3.0 for large text)
• preserve (enum, optional): Which color to preserve
  • "both" (default): Suggest adjustments to either foreground or background
  • "foreground": Only suggest background color changes
  • "background": Only suggest foreground color changes

Returns:

{
  "original": {
    "foreground": "#7c8aff",
    "background": "#ffffff"
  },
  "targetRatio": 4.5,
  "suggestions": [
    {
      "color": "#4c5dcc",
      "ratio": 4.6,
      "adjustedProperty": "foreground"
    },
    {
      "color": "#e8ebff",
      "ratio": 4.52,
      "adjustedProperty": "background"
    }
  ]
}

Example:

suggest_accessible_color({
  foreground: "#7c8aff",
  background: "#ffffff",
  targetRatio: 4.5,
  preserve: "both"
})

WCAG Contrast Requirements

Text Content (WCAG 1.4.3 Contrast Minimum)

• Normal text: 4.5:1 minimum for Level AA
• Large text (18pt+ or 14pt+ bold): 3:1 minimum for Level AA

Important: Text in UI components (buttons, inputs, etc.) must meet TEXT contrast requirements, not UI component thresholds.

UI Components (WCAG 1.4.11 Non-text Contrast)

• Visual boundaries (borders, outlines): 3:1 minimum for Level AA
• Component states (focus, hover, selected): 3:1 minimum for Level AA
• Icons without text: 3:1 minimum for Level AA

Usage in Agents

The AccessLint reviewer and refactor agents have access to these tools via the MCP protocol. Tools are automatically prefixed with mcp__accesslint__ when used in agent contexts.

Example in reviewer agent:

// Analyze colors found in component
const analysis = await mcp__accesslint__analyze_color_pair({
  foreground: "#7c8aff",
  background: "#ffffff",
  contentType: "normal-text"
});

if (!analysis.meetsRequirement) {
  // Get accessible alternatives
  const suggestions = await mcp__accesslint__suggest_accessible_color({
    foreground: "#7c8aff",
    background: "#ffffff",
    targetRatio: 4.5
  });

  // Report findings...
}

Development

Build

npm run build

Compiles TypeScript to JavaScript in the dist/ directory.

Watch Mode

npm run watch

Automatically recompile on file changes during development.

Project Structure

mcp-server/
├── src/
│   ├── index.ts          # MCP server entry point
│   ├── color-utils.ts    # Color parsing and conversion
│   └── wcag-contrast.ts  # WCAG contrast analysis logic
├── dist/                 # Compiled JavaScript (committed to git)
├── package.json
└── tsconfig.json

Configuration

This MCP server is automatically configured when the AccessLint plugin is installed. The configuration in plugins/accesslint/.mcp.json tells Claude Code how to start the server:

{
  "mcpServers": {
    "accesslint": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp-server/dist/index.js"]
    }
  }
}

Technical Details

Color Formats Supported

• Hex: #RGB, #RRGGBB (e.g., #f00, #ff0000)
• RGB: rgb(r, g, b) (e.g., rgb(255, 0, 0))
• RGBA: rgba(r, g, b, a) (alpha channel is ignored for contrast calculations)

Contrast Calculation

Implements the official WCAG 2.1 relative luminance and contrast ratio formulas:

1. Convert to sRGB: RGB values normalized to 0-1 range
2. Apply gamma correction: Account for non-linear perception
3. Calculate relative luminance: L = 0.2126 * R + 0.7152 * G + 0.0722 * B
4. Compute contrast ratio: (L1 + 0.05) / (L2 + 0.05) where L1 is lighter

Color Adjustment Algorithm

When suggesting accessible colors, the algorithm:

1. Converts colors to HSL (Hue, Saturation, Lightness)
2. Preserves hue and saturation to maintain design intent
3. Uses binary search to find optimal lightness value
4. Returns the adjustment closest to original that meets target ratio

License

MIT

Author

AccessLint