MCP Color Server

Instructions

Implementation Reference

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

  Registers the generateThemeTool in the central ToolRegistry singleton instance.

  toolRegistry.registerTool(generateThemeTool);

• src/tools/generate-theme.ts:11-36 (schema)

  TypeScript interface defining the input parameters (GenerateThemeParams) for the generate_theme tool.

  export interface GenerateThemeParams {
    theme_type:
      | 'light'
      | 'dark'
      | 'auto'
      | 'high_contrast'
      | 'colorblind_friendly';
    primary_color: string;
    style?: 'material' | 'ios' | 'fluent' | 'custom';
    components?: Array<
      | 'background'
      | 'surface'
      | 'primary'
      | 'secondary'
      | 'accent'
      | 'text'
      | 'border'
      | 'shadow'
      | 'success'
      | 'warning'
      | 'error'
      | 'info'
    >;
    accessibility_level?: 'AA' | 'AAA';
    brand_colors?: string[];
  }

• src/tools/generate-theme.ts:64-90 (schema)

  TypeScript interface defining the detailed response structure (GenerateThemeResponse) returned by the generate_theme tool.

  export interface GenerateThemeResponse {
    theme_type: string;
    style: string;
    primary_color: string;
    variants: {
      light?: ThemeVariant;
      dark?: ThemeVariant;
    };
    accessibility_report: {
      overall_score: number;
      wcag_compliance: 'AA' | 'AAA' | 'FAIL';
      contrast_issues: Array<{
        combination: [string, string];
        contrast_ratio: number;
        required_ratio: number;
        passes: boolean;
      }>;
      recommendations: string[];
    };
    brand_integration?:
      | {
          brand_colors_used: string[];
          harmony_maintained: boolean;
          adjustments_made: string[];
        }
      | undefined;
  }

• src/tools/generate-theme.ts:898-960 (schema)

  The complete tool definition object including MCP JSON schema (parameters), description, and handler wrapper that delegates to the main generateTheme function.

  // Tool definition for MCP registration
  export const generateThemeTool = {
    name: 'generate_theme',
    description:
      'Generate complete design system themes with semantic color mapping',
    parameters: {
      type: 'object',
      properties: {
        theme_type: {
          type: 'string',
          enum: ['light', 'dark', 'auto', 'high_contrast', 'colorblind_friendly'],
          description: 'Type of theme to generate',
        },
        primary_color: {
          type: 'string',
          description: 'Primary brand color for the theme',
        },
        style: {
          type: 'string',
          enum: ['material', 'ios', 'fluent', 'custom'],
          description: 'Design system style',
          default: 'material',
        },
        components: {
          type: 'array',
          items: {
            type: 'string',
            enum: [
              'background',
              'surface',
              'primary',
              'secondary',
              'accent',
              'text',
              'border',
              'shadow',
              'success',
              'warning',
              'error',
              'info',
            ],
          },
          description: 'Components to generate colors for',
        },
        accessibility_level: {
          type: 'string',
          enum: ['AA', 'AAA'],
          description: 'WCAG accessibility level to target',
          default: 'AA',
        },
        brand_colors: {
          type: 'array',
          items: {
            type: 'string',
          },
          description: 'Additional brand colors to incorporate',
        },
      },
      required: ['theme_type', 'primary_color'],
    },
    handler: async (params: unknown) =>
      generateTheme(params as GenerateThemeParams),
  };

• src/tools/generate-theme.ts:95-325 (handler)

  Core handler function that performs input validation, generates theme variants (light/dark/high-contrast/colorblind), computes accessibility reports, integrates brand colors, and constructs the final tool response.

  export async function generateTheme(
    params: GenerateThemeParams
  ): Promise<ToolResponse | ErrorResponse> {
    const startTime = Date.now();
  
    try {
      // Validate required parameters
      if (!params.primary_color) {
        return createErrorResponse(
          'generate_theme',
          'MISSING_PARAMETER',
          'Primary color parameter is required',
          Date.now() - startTime,
          {
            details: { parameter: 'primary_color' },
            suggestions: ['Provide a primary color in any supported format'],
          }
        );
      }
  
      if (!params.theme_type) {
        return createErrorResponse(
          'generate_theme',
          'MISSING_PARAMETER',
          'Theme type parameter is required',
          Date.now() - startTime,
          {
            details: { parameter: 'theme_type' },
            suggestions: [
              'Specify theme type: light, dark, auto, high_contrast, or colorblind_friendly',
            ],
          }
        );
      }
  
      // Validate primary color
      const primaryValidation = validateColorInput(params.primary_color);
      if (!primaryValidation.isValid) {
        return createErrorResponse(
          'generate_theme',
          'INVALID_PRIMARY_COLOR',
          `Invalid primary color format: ${params.primary_color}`,
          Date.now() - startTime,
          {
            details: {
              provided: params.primary_color,
              error: primaryValidation.error,
            },
            suggestions: [
              'Use a valid color format like #2563eb or rgb(37, 99, 235)',
            ],
          }
        );
      }
  
      // Validate brand colors if provided
      const brandColors: UnifiedColor[] = [];
      if (params.brand_colors) {
        for (const brandColor of params.brand_colors) {
          const validation = validateColorInput(brandColor);
          if (!validation.isValid) {
            return createErrorResponse(
              'generate_theme',
              'INVALID_BRAND_COLOR',
              `Invalid brand color format: ${brandColor}`,
              Date.now() - startTime,
              {
                details: { provided: brandColor, error: validation.error },
                suggestions: ['Ensure all brand colors are in valid formats'],
              }
            );
          }
          brandColors.push(new UnifiedColor(brandColor));
        }
      }
  
      // Parse primary color
      const primaryColor = new UnifiedColor(params.primary_color);
  
      // Set defaults
      const style = params.style || 'material';
      const accessibilityLevel = params.accessibility_level || 'AA';
      const components = params.components || [
        'background',
        'surface',
        'primary',
        'secondary',
        'accent',
        'text',
        'border',
        'shadow',
        'success',
        'warning',
        'error',
        'info',
      ];
  
      // Generate theme variants
      const variants: { light?: ThemeVariant; dark?: ThemeVariant } = {};
  
      if (params.theme_type === 'light' || params.theme_type === 'auto') {
        variants.light = await generateLightTheme(
          primaryColor,
          style,
          accessibilityLevel,
          components,
          brandColors
        );
      }
  
      if (params.theme_type === 'dark' || params.theme_type === 'auto') {
        variants.dark = await generateDarkTheme(
          primaryColor,
          style,
          accessibilityLevel,
          components,
          brandColors
        );
      }
  
      if (params.theme_type === 'high_contrast') {
        variants.light = await generateHighContrastTheme(
          primaryColor,
          'light',
          accessibilityLevel,
          components,
          brandColors
        );
        variants.dark = await generateHighContrastTheme(
          primaryColor,
          'dark',
          accessibilityLevel,
          components,
          brandColors
        );
      }
  
      if (params.theme_type === 'colorblind_friendly') {
        variants.light = await generateColorblindFriendlyTheme(
          primaryColor,
          'light',
          accessibilityLevel,
          components,
          brandColors
        );
        variants.dark = await generateColorblindFriendlyTheme(
          primaryColor,
          'dark',
          accessibilityLevel,
          components,
          brandColors
        );
      }
  
      // Generate accessibility report
      const accessibilityReport = await generateAccessibilityReport(
        variants,
        accessibilityLevel
      );
  
      // Generate brand integration report
      const brandIntegration =
        brandColors.length > 0
          ? await generateBrandIntegrationReport(brandColors, variants)
          : undefined;
  
      // Prepare response
      const responseData: GenerateThemeResponse = {
        theme_type: params.theme_type,
        style,
        primary_color: params.primary_color,
        variants,
        accessibility_report: accessibilityReport,
        brand_integration: brandIntegration,
      };
  
      const executionTime = Date.now() - startTime;
  
      // Generate accessibility notes
      const accessibilityNotes: string[] = [];
      if (accessibilityReport.wcag_compliance === 'FAIL') {
        accessibilityNotes.push('Theme does not meet minimum WCAG standards');
      } else if (accessibilityReport.wcag_compliance === 'AA') {
        accessibilityNotes.push('Theme meets WCAG AA accessibility standards');
      } else {
        accessibilityNotes.push('Theme meets WCAG AAA accessibility standards');
      }
  
      const recommendations: string[] = [];
      if (accessibilityReport.contrast_issues.length > 0) {
        recommendations.push(
          `${accessibilityReport.contrast_issues.length} contrast issues found - see accessibility report`
        );
      }
      if (brandIntegration && !brandIntegration.harmony_maintained) {
        recommendations.push('Brand color harmony could be improved');
      }
  
      return createSuccessResponse(
        'generate_theme',
        responseData,
        executionTime,
        {
          colorSpaceUsed: 'sRGB',
          accessibilityNotes,
          recommendations: recommendations
            .concat(accessibilityReport.recommendations)
            .slice(0, 5),
        }
      );
    } catch (error) {
      const executionTime = Date.now() - startTime;
      return createErrorResponse(
        'generate_theme',
        'THEME_GENERATION_ERROR',
        `Failed to generate theme: ${error instanceof Error ? error.message : 'Unknown error'}`,
        executionTime,
        {
          details: {
            theme_type: params.theme_type,
            primary_color: params.primary_color,
          },
          suggestions: [
            'Check that the primary color is in a valid format',
            'Ensure theme type is supported',
            'Try with different parameters',
          ],
        }
      );
    }
  }