MCP Color Server

Instructions

Implementation Reference

• src/tools/check-contrast.ts:54-261 (handler)

  Core handler function that executes the check_contrast tool logic: validates parameters, parses colors, computes contrast ratio using ColorAnalyzer, generates recommendations and alternative color combinations, and returns formatted response.
  export async function checkContrast( params: CheckContrastParams ): Promise<ToolResponse | ErrorResponse> { const startTime = Date.now(); try { // Validate required parameters if (!params.foreground) { return createErrorResponse( 'check_contrast', 'MISSING_PARAMETER', 'Foreground color parameter is required', Date.now() - startTime, { details: { parameter: 'foreground' }, suggestions: ['Provide a foreground color in any supported format'], } ); } if (!params.background) { return createErrorResponse( 'check_contrast', 'MISSING_PARAMETER', 'Background color parameter is required', Date.now() - startTime, { details: { parameter: 'background' }, suggestions: ['Provide a background color in any supported format'], } ); } // Validate color inputs const fgValidation = validateColorInput(params.foreground); if (!fgValidation.isValid) { return createErrorResponse( 'check_contrast', 'INVALID_FOREGROUND_COLOR', `Invalid foreground color format: ${params.foreground}`, Date.now() - startTime, { details: { provided: params.foreground, error: fgValidation.error }, suggestions: [ 'Use a valid color format like #FF0000 or rgb(255, 0, 0)', ], } ); } const bgValidation = validateColorInput(params.background); if (!bgValidation.isValid) { return createErrorResponse( 'check_contrast', 'INVALID_BACKGROUND_COLOR', `Invalid background color format: ${params.background}`, Date.now() - startTime, { details: { provided: params.background, error: bgValidation.error }, suggestions: [ 'Use a valid color format like #FFFFFF or rgb(255, 255, 255)', ], } ); } // Parse colors const foregroundColor = new UnifiedColor(params.foreground); const backgroundColor = new UnifiedColor(params.background); // Set defaults const textSize = params.text_size || 'normal'; const standard = params.standard || 'WCAG_AA'; // Check contrast const contrastResult = ColorAnalyzer.checkContrast( foregroundColor, backgroundColor, textSize, standard ); // Generate recommendations const recommendations: string[] = []; if (!contrastResult.passes) { recommendations.push( 'This color combination does not meet accessibility standards' ); if (contrastResult.ratio < 3.0) { recommendations.push( 'Consider using colors with more contrast difference' ); } // Suggest adjustments if ( foregroundColor.metadata?.brightness && backgroundColor.metadata?.brightness ) { const fgBrightness = foregroundColor.metadata.brightness; const bgBrightness = backgroundColor.metadata.brightness; if (Math.abs(fgBrightness - bgBrightness) < 100) { if (fgBrightness > 127) { recommendations.push('Try using a darker foreground color'); } else { recommendations.push('Try using a lighter foreground color'); } if (bgBrightness > 127) { recommendations.push('Try using a darker background color'); } else { recommendations.push('Try using a lighter background color'); } } } } else { if (contrastResult.wcag_aaa) { recommendations.push('Excellent contrast - meets AAA standards'); } else { recommendations.push('Good contrast - meets AA standards'); } } // Generate alternative combinations const alternativeCombinations = await generateAlternatives( foregroundColor, backgroundColor, textSize, contrastResult.ratio, standard ); // Prepare response const responseData: CheckContrastResponse = { foreground: params.foreground, background: params.background, contrast_ratio: contrastResult.ratio, text_size: textSize, standard, compliance: (() => { const compliance: CheckContrastResponse['compliance'] = { wcag_aa: contrastResult.wcag_aa, wcag_aaa: contrastResult.wcag_aaa, passes: contrastResult.passes, }; if (standard === 'APCA') { compliance.apca_passes = contrastResult.passes; } return compliance; })(), recommendations, alternative_combinations: alternativeCombinations, }; if (contrastResult.apca_score !== undefined) { responseData.apca_score = contrastResult.apca_score; } const executionTime = Date.now() - startTime; // Generate accessibility notes const accessibilityNotes: string[] = []; if (!contrastResult.wcag_aa) { accessibilityNotes.push( `Contrast ratio ${contrastResult.ratio}:1 does not meet WCAG AA standards` ); } if (contrastResult.wcag_aaa) { accessibilityNotes.push( `Excellent contrast ratio ${contrastResult.ratio}:1 meets WCAG AAA standards` ); } return createSuccessResponse( 'check_contrast', responseData, executionTime, { colorSpaceUsed: 'sRGB', accessibilityNotes: accessibilityNotes, recommendations: recommendations.slice(0, 5), } ); } catch (error) { const executionTime = Date.now() - startTime; return createErrorResponse( 'check_contrast', 'CONTRAST_CHECK_ERROR', `Failed to check contrast: ${error instanceof Error ? error.message : 'Unknown error'}`, executionTime, { details: { foreground: params.foreground, background: params.background, }, suggestions: [ 'Check that both colors are in valid formats', 'Try different color formats', ], } ); } }
• src/tools/check-contrast.ts:12-49 (schema)

  TypeScript interfaces defining input parameters and output response structure for the check_contrast tool.
  export interface CheckContrastParams { foreground: string; background: string; text_size?: 'normal' | 'large'; standard?: 'WCAG_AA' | 'WCAG_AAA' | 'APCA'; } export interface CheckContrastResponse { foreground: string; background: string; contrast_ratio: number; apca_score?: number; text_size: 'normal' | 'large'; standard: string; compliance: { wcag_aa: boolean; wcag_aaa: boolean; apca_passes?: boolean; passes: boolean; }; recommendations: string[]; alternative_combinations?: | { foreground_adjustments: Array<{ color: string; contrast_ratio: number; apca_score?: number; passes: boolean; }>; background_adjustments: Array<{ color: string; contrast_ratio: number; apca_score?: number; passes: boolean; }>; } | undefined; }
• src/tools/index.ts:60-105 (registration)

  Import of checkContrastTool and registration with the central ToolRegistry singleton.
  import { checkContrastTool } from './check-contrast'; // Import and register accessibility tools import { simulateColorblindnessTool } from './simulate-colorblindness'; import { optimizeForAccessibilityTool } from './optimize-for-accessibility'; // Import and register palette generation tools import { generateHarmonyPaletteTool } from './generate-harmony-palette'; // Import and register gradient generation tools import { generateLinearGradientTool } from './generate-linear-gradient'; import { generateRadialGradientTool } from './generate-radial-gradient'; // Import and register visualization tools import { createPaletteHtmlTool } from './create-palette-html'; import { createColorWheelHtmlTool } from './create-color-wheel-html'; import { createGradientHtmlTool } from './create-gradient-html'; import { createThemePreviewHtmlTool } from './create-theme-preview-html'; // Import and register PNG generation tools import { createPalettePngTool } from './create-palette-png'; import { createGradientPngTool } from './create-gradient-png'; import { createColorComparisonPngTool } from './create-color-comparison-png'; // Import and register theme generation tools import { generateThemeTool } from './generate-theme'; import { generateSemanticColorsTool } from './generate-semantic-colors'; // Import color utility tools import { mixColorsTool } from './mix-colors'; import { generateColorVariationsTool } from './generate-color-variations'; import { sortColorsTool } from './sort-colors'; import { analyzeColorCollectionTool } from './analyze-color-collection'; // Import export format tools import { exportCssTool } from './export-css'; import { exportScssTool } from './export-scss'; import { exportTailwindTool } from './export-tailwind'; import { exportJsonTool } from './export-json'; // Register conversion tools toolRegistry.registerTool(convertColorTool); // Register analysis tools toolRegistry.registerTool(analyzeColorTool); toolRegistry.registerTool(checkContrastTool);
• src/tools/check-contrast.ts:377-409 (registration)

  Tool definition object with name, description, parameters schema, and handler wrapper that is exported for registration.
  export const checkContrastTool = { name: 'check_contrast', description: 'Check color contrast compliance with WCAG accessibility standards', parameters: { type: 'object', properties: { foreground: { type: 'string', description: 'Foreground color (typically text color)', }, background: { type: 'string', description: 'Background color', }, text_size: { type: 'string', enum: ['normal', 'large'], description: 'Text size category for WCAG compliance', default: 'normal', }, standard: { type: 'string', enum: ['WCAG_AA', 'WCAG_AAA', 'APCA'], description: 'Accessibility standard to check against', default: 'WCAG_AA', }, }, required: ['foreground', 'background'], }, handler: async (params: unknown) => checkContrast(params as CheckContrastParams), };
• src/color/color-analysis.ts:407-463 (helper)

  Core helper function in ColorAnalyzer that performs the actual contrast ratio calculation between two colors using WCAG formula and APCA support.
  static checkContrast( foreground: UnifiedColor, background: UnifiedColor, textSize: 'normal' | 'large' = 'normal', standard: 'WCAG_AA' | 'WCAG_AAA' | 'APCA' = 'WCAG_AA' ): { ratio: number; wcag_aa: boolean; wcag_aaa: boolean; apca_score?: number; passes: boolean; } { const fgLuminance = this.calculateRelativeLuminance(foreground.rgb); const bgLuminance = this.calculateRelativeLuminance(background.rgb); const ratio = (Math.max(fgLuminance, bgLuminance) + 0.05) / (Math.min(fgLuminance, bgLuminance) + 0.05); const aaThreshold = textSize === 'large' ? 3.0 : 4.5; const aaaThreshold = textSize === 'large' ? 4.5 : 7.0; const wcagAA = ratio >= aaThreshold; const wcagAAA = ratio >= aaaThreshold; let passes = wcagAA; let apcaScore: number | undefined; // Calculate APCA score if requested if (standard === 'APCA') { apcaScore = this.calculateAPCA(foreground, background); // APCA passing criteria (simplified - actual APCA has more complex rules) const apcaThreshold = textSize === 'large' ? 60 : 75; passes = Math.abs(apcaScore) >= apcaThreshold; } else if (standard === 'WCAG_AAA') { passes = wcagAAA; } const result: { ratio: number; wcag_aa: boolean; wcag_aaa: boolean; apca_score?: number; passes: boolean; } = { ratio: Math.round(ratio * 100) / 100, wcag_aa: wcagAA, wcag_aaa: wcagAAA, passes, }; if (apcaScore !== undefined) { result.apca_score = apcaScore; } return result; }