analyze_color

Instructions

Implementation Reference

• src/tools/analyze-color.ts:41-159 (handler)

  Primary handler function executing the core logic: input validation, color parsing, analysis delegation to ColorAnalyzer, summary generation, recommendations, and response formatting.

  export async function analyzeColor(
    params: AnalyzeColorParams
  ): Promise<ToolResponse | ErrorResponse> {
    const startTime = Date.now();
  
    try {
      // Validate input parameters using Joi schema
      const validation = validateInput(analyzeColorSchema, params);
      if (!validation.isValid) {
        logger.warn('Color analysis validation failed', {
          tool: 'analyze_color',
          executionTime: Date.now() - startTime,
        });
        return createValidationErrorResponse(
          'analyze_color',
          validation.error!,
          Date.now() - startTime
        );
      }
  
      const validatedParams = validation.value!;
  
      // Parse colors
      const color = new UnifiedColor(validatedParams.color);
      let compareColor: UnifiedColor | undefined;
  
      if (validatedParams.compare_color) {
        compareColor = new UnifiedColor(validatedParams.compare_color);
      }
  
      const analysisTypes = validatedParams.analysis_types;
  
      // Perform analysis
      const analysis = ColorAnalyzer.analyzeColor(
        color,
        analysisTypes,
        compareColor
      );
  
      // Calculate overall score and generate summary
      const summary = generateAnalysisSummary(analysis);
  
      // Prepare response data
      const responseData: AnalyzeColorResponse = {
        color: params.color,
        analysis,
        summary,
      };
  
      if (compareColor && analysis.distance) {
        responseData.comparison = {
          compare_color: params.compare_color!,
          distance: analysis.distance,
        };
      }
  
      const executionTime = Date.now() - startTime;
  
      // Generate accessibility notes
      const accessibilityNotes: string[] = [];
      if (!analysis.accessibility.wcag_aa_normal) {
        accessibilityNotes.push(
          'Does not meet WCAG AA standards for normal text'
        );
      }
      if (!analysis.accessibility.color_blind_safe) {
        accessibilityNotes.push('May be difficult for color-blind users');
      }
      if (analysis.contrast.best_contrast < 3.0) {
        accessibilityNotes.push('Very low contrast - avoid using for text');
      }
  
      // Generate recommendations
      const recommendations: string[] = [
        ...analysis.accessibility.recommendations,
      ];
  
      if (analysis.brightness.brightness_category === 'very_dark') {
        recommendations.push(
          'Consider using white or light text on this background'
        );
      } else if (analysis.brightness.brightness_category === 'very_light') {
        recommendations.push('Consider using dark text on this background');
      }
  
      if (analysis.temperature.temperature === 'warm') {
        recommendations.push(
          'This warm color works well for energetic, friendly designs'
        );
      } else if (analysis.temperature.temperature === 'cool') {
        recommendations.push(
          'This cool color works well for professional, calming designs'
        );
      }
  
      return createSuccessResponse('analyze_color', responseData, executionTime, {
        colorSpaceUsed: 'sRGB',
        accessibilityNotes: accessibilityNotes,
        recommendations: recommendations.slice(0, 5), // Limit to top 5 recommendations
      });
    } catch (error) {
      const executionTime = Date.now() - startTime;
      return createErrorResponse(
        'analyze_color',
        'ANALYSIS_ERROR',
        `Failed to analyze color: ${error instanceof Error ? error.message : 'Unknown error'}`,
        executionTime,
        {
          details: {
            color: params.color,
          },
          suggestions: [
            'Check that the color format is supported',
            'Try a different color format',
          ],
        }
      );
    }
  }

• src/validation/schemas.ts:133-154 (schema)

  Joi validation schema defining input parameters for analyze_color tool: color (required), analysis_types (array), compare_color (optional), include_recommendations (boolean).

  export const analyzeColorSchema = Joi.object({
    color: colorSchema,
    analysis_types: Joi.array()
      .items(
        Joi.string().valid(
          'brightness',
          'contrast',
          'temperature',
          'accessibility',
          'all'
        )
      )
      .min(1)
      .max(10) // Prevent excessive analysis types
      .default(['all'])
      .messages({
        'array.min': 'At least one analysis type must be specified',
        'array.max': 'Too many analysis types (max 10)',
      }),
    compare_color: colorSchema.optional(),
    include_recommendations: Joi.boolean().default(true),
  }).required();

• src/tools/index.ts:104-104 (registration)

  Central registration of the analyze_color tool into the ToolRegistry singleton, making it available for MCP execution.

  toolRegistry.registerTool(analyzeColorTool);

• src/tools/analyze-color.ts:217-224 (registration)

  Tool definition object with name, description, parameters schema, and handler wrapper that invokes the main analyzeColor function.

  export const analyzeColorTool = {
    name: 'analyze_color',
    description:
      'Analyze color properties including brightness, temperature, contrast, accessibility, and optionally compare with another color',
    parameters: analyzeColorSchema.describe(),
    handler: async (params: unknown) =>
      analyzeColor(params as AnalyzeColorParams),
  };

• src/color/color-analysis.ts:62-80 (helper)

  Core static method in ColorAnalyzer class that orchestrates detailed analysis of brightness, temperature, contrast, accessibility, and optional distance comparison.

  static analyzeColor(
    color: UnifiedColor,
    _analysisTypes: string[] = ['all'],
    compareColor?: UnifiedColor
  ): ColorAnalysisResult {
    const result: ColorAnalysisResult = {
      brightness: this.analyzeBrightness(color),
      temperature: this.analyzeTemperature(color),
      contrast: this.analyzeContrast(color),
      accessibility: this.analyzeAccessibility(color),
    };
  
    // Add distance analysis if comparison color provided
    if (compareColor) {
      result.distance = this.analyzeDistance(color, compareColor);
    }
  
    return result;
  }