@trishchuk/coolors-mcp 1.0.1 → 1.1.0

package/src/tools/contrast-checker.tool.ts

@@ -1,15 +1,22 @@
 /**
  * Contrast Checker Tool
- * Check WCAG contrast ratio between two colors
+ * Check contrast between two colors using WCAG 2.x luminance ratio,
+ * APCA (WCAG 3 draft), or both.
  */
 
 import { z } from "zod";
 
+import { apcaContrast, apcaLevel } from "../color/apca.js";
 import { getContrastRatio, parseColor } from "../color/index.js";
 
 export const contrastCheckerTool = {
-  description: "Check WCAG contrast ratio between two colors",
-  execute: async (args: { background: string; foreground: string }) => {
+  description:
+    "Check contrast between two colors. Supports WCAG 2.x luminance ratio (default), APCA Lc (WCAG 3 draft), or both algorithms side-by-side.",
+  execute: async (args: {
+    algorithm?: "apca" | "both" | "wcag";
+    background: string;
+    foreground: string;
+  }) => {
     const fg = parseColor(args.foreground);
     const bg = parseColor(args.background);
 
@@ -17,20 +24,52 @@ export const contrastCheckerTool = {
       return `Invalid color format: ${!fg ? args.foreground : args.background}`;
     }
 
-    const ratio = getContrastRatio(fg, bg);
-    const aa = ratio >= 4.5;
-    const aaLarge = ratio >= 3;
-    const aaa = ratio >= 7;
-    const aaaLarge = ratio >= 4.5;
-
-    return `Contrast Ratio: ${ratio.toFixed(2)}:1
-WCAG AA: ${aa ? "✓ Pass" : "✗ Fail"} (normal text)
-WCAG AA: ${aaLarge ? "✓ Pass" : "✗ Fail"} (large text)
-WCAG AAA: ${aaa ? "✓ Pass" : "✗ Fail"} (normal text)
-WCAG AAA: ${aaaLarge ? "✓ Pass" : "✗ Fail"} (large text)`;
+    const algorithm = args.algorithm ?? "wcag";
+
+    const wcagBlock = () => {
+      const ratio = getContrastRatio(fg, bg);
+      const aaLarge = ratio >= 3;
+      const aa = ratio >= 4.5;
+      const aaaLarge = ratio >= 4.5;
+      const aaa = ratio >= 7;
+      return `## WCAG 2.x luminance ratio
+Contrast Ratio: ${ratio.toFixed(2)}:1
+- AA (normal text):  ${aa ? "✓ Pass" : "✗ Fail"} (need 4.5:1)
+- AA (large text):   ${aaLarge ? "✓ Pass" : "✗ Fail"} (need 3:1)
+- AAA (normal text): ${aaa ? "✓ Pass" : "✗ Fail"} (need 7:1)
+- AAA (large text):  ${aaaLarge ? "✓ Pass" : "✗ Fail"} (need 4.5:1)`;
+    };
+
+    const apcaBlock = () => {
+      const lc = apcaContrast(fg, bg);
+      const level = apcaLevel(lc);
+      const polarity =
+        lc > 0
+          ? "dark text on light bg"
+          : lc < 0
+            ? "light text on dark bg"
+            : "no contrast";
+      return `## APCA (WCAG 3 draft)
+Lc: ${lc.toFixed(1)} (${polarity})
+- Body text (|Lc| ≥ 75):    ${level.body ? "✓ Pass" : "✗ Fail"}
+- Content text (|Lc| ≥ 60): ${level.content ? "✓ Pass" : "✗ Fail"}
+- Large text (|Lc| ≥ 45):   ${level.large ? "✓ Pass" : "✗ Fail"}
+- Spot / non-content (|Lc| ≥ 30): ${level.spot ? "✓ Pass" : "✗ Fail"}`;
+    };
+
+    if (algorithm === "wcag") return wcagBlock();
+    if (algorithm === "apca") return apcaBlock();
+    return `${wcagBlock()}\n\n${apcaBlock()}`;
   },
   name: "check_contrast",
   parameters: z.object({
+    algorithm: z
+      .enum(["wcag", "apca", "both"])
+      .optional()
+      .default("wcag")
+      .describe(
+        "Contrast algorithm: 'wcag' (WCAG 2.x ratio), 'apca' (Lc, WCAG 3 draft), or 'both'",
+      ),
     background: z.string().describe("Background color"),
     foreground: z.string().describe("Foreground/text color"),
   }),

package/src/tools/dislike-analyzer.tool.ts

@@ -3,9 +3,7 @@
  * Identifies and fixes universally disliked colors based on color psychology research
  */
 
-import type { Tool } from "../types.js";
-
-type McpTool = Tool<any>;
+import { z } from "zod";
 
 import { DislikeAnalyzer } from "../color/dislike/dislike-analyzer.js";
 import { Hct } from "../color/hct/hct-class.js";
@@ -14,14 +12,11 @@ import { parseColor, rgbToArgb } from "../color/index.js";
 /**
  * Analyze if a color is universally disliked
  */
-export const analyzeColorLikabilityTool: McpTool = {
+export const analyzeColorLikabilityTool = {
   description:
     "Check if a color is universally disliked (dark yellow-green associated with biological waste) and get a fixed version if needed",
-  execute: async (args: unknown, _context: any) => {
-    const { autoFix = true, color } = args as {
-      autoFix?: boolean;
-      color: string;
-    };
+  execute: async (args: { autoFix?: boolean; color: string }) => {
+    const { autoFix = true, color } = args;
 
     try {
       // Parse the input color
@@ -95,40 +90,37 @@ export const analyzeColorLikabilityTool: McpTool = {
       return `Error analyzing color: ${error instanceof Error ? error.message : String(error)}`;
     }
   },
-  inputSchema: {
-    properties: {
-      autoFix: {
-        description:
-          "Automatically return fixed version if disliked (default: true)",
-        type: "boolean",
-      },
-      color: {
-        description: "Color to analyze (hex, rgb, hsl, etc.)",
-        type: "string",
-      },
-    },
-    required: ["color"],
-    type: "object",
-  },
   name: "analyze_color_likability",
+  parameters: z.object({
+    autoFix: z
+      .boolean()
+      .optional()
+      .default(true)
+      .describe("Automatically return fixed version if disliked"),
+    color: z.string().describe("Color to analyze (hex, rgb, hsl, etc.)"),
+  }),
 };
 
 /**
  * Fix multiple disliked colors in a batch
  */
-export const fixDislikedColorsBatchTool: McpTool = {
-  description: "Analyze and fix multiple colors, returning only liked versions",
-  execute: async (args: unknown, _context: any) => {
-    const { colors, includeAnalysis = false } = args as {
-      colors: string[];
-      includeAnalysis?: boolean;
+type BatchHct =
+  | { c: number; h: number; t: number }
+  | {
+      fixed: { c: number; h: number; t: number };
+      original: { c: number; h: number; t: number };
     };
 
+export const fixDislikedColorsBatchTool = {
+  description: "Analyze and fix multiple colors, returning only liked versions",
+  execute: async (args: { colors: string[]; includeAnalysis?: boolean }) => {
+    const { colors, includeAnalysis = false } = args;
+
     try {
       const results: Array<{
         error?: string;
         fixed?: string;
-        hct?: unknown;
+        hct?: BatchHct;
         original: string;
         wasDisliked?: boolean;
       }> = [];
@@ -202,14 +194,16 @@ export const fixDislikedColorsBatchTool: McpTool = {
           output += `- **${result.original}**: ❌ ${result.error}\n`;
         } else if (result.wasDisliked) {
           output += `- **${result.original}** → **${result.fixed}** (fixed)\n`;
-          if (includeAnalysis && result.hct) {
-            output += `  - Original HCT: (${result.hct.original.h.toFixed(0)}°, ${result.hct.original.c.toFixed(0)}, ${result.hct.original.t.toFixed(0)})\n`;
-            output += `  - Fixed HCT: (${result.hct.fixed.h.toFixed(0)}°, ${result.hct.fixed.c.toFixed(0)}, ${result.hct.fixed.t.toFixed(0)})\n`;
+          if (includeAnalysis && result.hct && "original" in result.hct) {
+            const { fixed, original } = result.hct;
+            output += `  - Original HCT: (${original.h.toFixed(0)}°, ${original.c.toFixed(0)}, ${original.t.toFixed(0)})\n`;
+            output += `  - Fixed HCT: (${fixed.h.toFixed(0)}°, ${fixed.c.toFixed(0)}, ${fixed.t.toFixed(0)})\n`;
           }
         } else {
           output += `- **${result.original}** ✓ (already liked)\n`;
-          if (includeAnalysis && result.hct) {
-            output += `  - HCT: (${result.hct.h.toFixed(0)}°, ${result.hct.c.toFixed(0)}, ${result.hct.t.toFixed(0)})\n`;
+          if (includeAnalysis && result.hct && "h" in result.hct) {
+            const { c, h, t } = result.hct;
+            output += `  - HCT: (${h.toFixed(0)}°, ${c.toFixed(0)}, ${t.toFixed(0)})\n`;
           }
         }
       }
@@ -225,23 +219,16 @@ export const fixDislikedColorsBatchTool: McpTool = {
       return `Error processing colors: ${error instanceof Error ? error.message : String(error)}`;
     }
   },
-  inputSchema: {
-    properties: {
-      colors: {
-        description: "Array of colors to analyze (hex, rgb, hsl, etc.)",
-        items: {
-          type: "string",
-        },
-        type: "array",
-      },
-      includeAnalysis: {
-        description:
-          "Include detailed analysis for each color (default: false)",
-        type: "boolean",
-      },
-    },
-    required: ["colors"],
-    type: "object",
-  },
   name: "fix_disliked_colors_batch",
+  parameters: z.object({
+    colors: z
+      .array(z.string())
+      .min(1)
+      .describe("Array of colors to analyze (hex, rgb, hsl, etc.)"),
+    includeAnalysis: z
+      .boolean()
+      .optional()
+      .default(false)
+      .describe("Include detailed analysis for each color"),
+  }),
 };

package/src/tools/image-extraction.tools.ts

@@ -2,15 +2,7 @@
  * MCP tools for image color extraction
  */
 
-import type { Tool } from "../types.js";
-
-type ImageData = {
-  data: number[] | Uint8ClampedArray;
-  height: number;
-  width: number;
-};
-
-type McpTool = Tool<unknown>;
+import { z } from "zod";
 
 import {
   extractColors,
@@ -19,31 +11,37 @@ import {
 } from "../color/extract-colors.js";
 import { generateMaterialTheme } from "../color/material-theme.js";
 
+const imageDataSchema = z
+  .object({
+    data: z.array(z.number()).describe("Flat array of RGBA values (0-255)"),
+    height: z.number().int().positive().describe("Image height in pixels"),
+    width: z.number().int().positive().describe("Image width in pixels"),
+  })
+  .describe("Image data with RGBA values");
+
+type ImageDataInput = z.infer<typeof imageDataSchema>;
+
 /**
  * Extract dominant colors from image data
  */
-export const extractImageColorsTool: McpTool = {
+export const extractImageColorsTool = {
   description:
     "Extract dominant colors from an image. Input should be image data as an array of RGBA values.",
-  execute: async (args: unknown, _context: unknown) => {
+  execute: async (args: {
+    format?: "css" | "json" | "palette";
+    imageData: ImageDataInput;
+    maxColors?: number;
+    quality?: "high" | "low" | "medium";
+  }) => {
     const {
       format = "json",
       imageData,
       maxColors = 5,
       quality = "medium",
-    } = args as {
-      format?: string;
-      imageData: ImageData;
-      maxColors?: number;
-      quality?: "high" | "low" | "medium";
-    };
+    } = args;
 
     try {
-      // Convert data array to Uint8ClampedArray if needed
-      const data =
-        imageData.data instanceof Uint8ClampedArray
-          ? imageData.data
-          : new Uint8ClampedArray(imageData.data);
+      const data = new Uint8ClampedArray(imageData.data);
 
       const processedImageData = {
         data,
@@ -75,74 +73,44 @@ export const extractImageColorsTool: McpTool = {
       return `Error extracting colors: ${error instanceof Error ? error.message : String(error)}`;
     }
   },
-  inputSchema: {
-    properties: {
-      format: {
-        description: "Output format: json, css, or palette (default: json)",
-        enum: ["json", "css", "palette"],
-        type: "string",
-      },
-      imageData: {
-        description: "Image data with RGBA values",
-        properties: {
-          data: {
-            description: "Flat array of RGBA values (0-255)",
-            items: { type: "number" },
-            type: "array",
-          },
-          height: {
-            description: "Image height in pixels",
-            type: "number",
-          },
-          width: {
-            description: "Image width in pixels",
-            type: "number",
-          },
-        },
-        required: ["data", "width", "height"],
-        type: "object",
-      },
-      maxColors: {
-        description: "Maximum number of colors to extract (default: 5)",
-        maximum: 20,
-        minimum: 1,
-        type: "number",
-      },
-      quality: {
-        description:
-          "Extraction quality: low, medium, or high (default: medium)",
-        enum: ["low", "medium", "high"],
-        type: "string",
-      },
-    },
-    required: ["imageData"],
-    type: "object",
-  },
   name: "extract_image_colors",
+  parameters: z.object({
+    format: z
+      .enum(["json", "css", "palette"])
+      .optional()
+      .default("json")
+      .describe("Output format"),
+    imageData: imageDataSchema,
+    maxColors: z
+      .number()
+      .int()
+      .min(1)
+      .max(20)
+      .optional()
+      .default(5)
+      .describe("Maximum number of colors to extract"),
+    quality: z
+      .enum(["low", "medium", "high"])
+      .optional()
+      .default("medium")
+      .describe("Extraction quality"),
+  }),
 };
 
 /**
  * Generate a Material Design theme from an image
  */
-export const generateThemeFromImageTool: McpTool = {
+export const generateThemeFromImageTool = {
   description: "Generate a complete Material Design 3 theme from an image",
-  execute: async (args: unknown, _context: unknown) => {
-    const {
-      imageData,
-      includeCustomColors = true,
-      isDark = false,
-    } = args as {
-      imageData: ImageData;
-      includeCustomColors?: boolean;
-      isDark?: boolean;
-    };
+  execute: async (args: {
+    imageData: ImageDataInput;
+    includeCustomColors?: boolean;
+    isDark?: boolean;
+  }) => {
+    const { imageData, includeCustomColors = true, isDark = false } = args;
 
     try {
-      // Convert data array to Uint8ClampedArray if needed
-      const data =
-        imageData.data instanceof Uint8ClampedArray
-          ? imageData.data
-          : new Uint8ClampedArray(imageData.data);
+      const data = new Uint8ClampedArray(imageData.data);
 
       const processedImageData = {
         data,
@@ -212,41 +180,20 @@ export const generateThemeFromImageTool: McpTool = {
       return `Error generating theme: ${error instanceof Error ? error.message : String(error)}`;
     }
   },
-  inputSchema: {
-    properties: {
-      imageData: {
-        description: "Image data with RGBA values",
-        properties: {
-          data: {
-            description: "Flat array of RGBA values (0-255)",
-            items: { type: "number" },
-            type: "array",
-          },
-          height: {
-            description: "Image height in pixels",
-            type: "number",
-          },
-          width: {
-            description: "Image width in pixels",
-            type: "number",
-          },
-        },
-        required: ["data", "width", "height"],
-        type: "object",
-      },
-      includeCustomColors: {
-        description: "Include custom colors from image (default: true)",
-        type: "boolean",
-      },
-      isDark: {
-        description: "Generate dark theme (default: false for light theme)",
-        type: "boolean",
-      },
-    },
-    required: ["imageData"],
-    type: "object",
-  },
   name: "generate_theme_from_image",
+  parameters: z.object({
+    imageData: imageDataSchema,
+    includeCustomColors: z
+      .boolean()
+      .optional()
+      .default(true)
+      .describe("Include custom colors from image"),
+    isDark: z
+      .boolean()
+      .optional()
+      .default(false)
+      .describe("Generate dark theme (false for light theme)"),
+  }),
 };
 
 // Helper functions for formatting

package/src/tools/index.ts

@@ -1,10 +1,21 @@
 // Tool Registry Index - Export all tools
 
+export { adjustColorTool } from "./adjust-color.tool.js";
+// Visual cohesion: tonal scales, state colors, palette consistency
+export {
+  analyzePaletteConsistencyTool,
+  generateSemanticPaletteTool,
+  generateStateColorsTool,
+  generateTonalScaleTool,
+} from "./cohesion.tools.js";
+// Color-blindness simulation & accessibility audit
+export {
+  checkPaletteAccessibilityTool,
+  simulateColorBlindnessTool,
+} from "./color-blindness.tool.js";
 // Color tools
 export { colorConversionTool } from "./color-conversion.tool.js";
 export { colorDistanceTool } from "./color-distance.tool.js";
-// Legacy tools (if needed)
-export { convertColor } from "./colors.js";
 export { contrastCheckerTool } from "./contrast-checker.tool.js";
 
 // Dislike analyzer tools
@@ -27,6 +38,8 @@ export {
   generateTonalPaletteTool,
   harmonizeColorsTool,
 } from "./material-theme.tools.js";
+
+export { exportPaletteTool } from "./palette-export.tool.js";
 export { paletteGeneratorTool } from "./palette-generator.tool.js";
 export { paletteWithLocksTool } from "./palette-with-locks.tool.js";
 

package/src/tools/palette-export.tool.ts

@@ -0,0 +1,174 @@
+/**
+ * Palette Export Tool
+ * Convert a palette of colors into commonly used design-system formats:
+ * CSS custom properties, SCSS variables, Tailwind config, or W3C design tokens.
+ */
+
+import { z } from "zod";
+
+import { parseColor, rgbToHex, rgbToHsl } from "../color/index.js";
+
+const FORMATS = ["css", "scss", "tailwind", "tokens", "json"] as const;
+
+type ExportFormat = (typeof FORMATS)[number];
+
+interface NamedColor {
+  hex: string;
+  name: string;
+}
+
+function asCss(items: NamedColor[]): string {
+  const body = items.map(({ hex, name }) => `  --${name}: ${hex};`).join("\n");
+  return `:root {\n${body}\n}\n`;
+}
+
+function asJson(items: NamedColor[]): string {
+  const obj: Record<string, { hex: string; hsl: string; rgb: string }> = {};
+  for (const { hex, name } of items) {
+    const rgb = parseColor(hex)!;
+    const hsl = rgbToHsl(rgb);
+    obj[name] = {
+      hex,
+      hsl: `hsl(${hsl.h}, ${hsl.s}%, ${hsl.l}%)`,
+      rgb: `rgb(${rgb.r}, ${rgb.g}, ${rgb.b})`,
+    };
+  }
+  return JSON.stringify(obj, null, 2) + "\n";
+}
+
+function asScss(items: NamedColor[]): string {
+  return items.map(({ hex, name }) => `$${name}: ${hex};`).join("\n") + "\n";
+}
+
+function asTailwind(items: NamedColor[], prefix?: string): string {
+  const key = prefix ?? "palette";
+  const lines = items
+    .map(({ hex, name }) => {
+      // Drop the prefix from the entry name if it was prefixed
+      const entry =
+        prefix && name.startsWith(`${prefix}-`)
+          ? name.slice(prefix.length + 1)
+          : name;
+      return `      "${entry}": "${hex}",`;
+    })
+    .join("\n");
+  return `// tailwind.config.js
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        "${key}": {
+${lines}
+        },
+      },
+    },
+  },
+};
+`;
+}
+
+function asTokens(items: NamedColor[], prefix?: string): string {
+  // W3C Design Tokens Community Group format (draft).
+  const group = prefix ?? "color";
+  const obj: Record<string, unknown> = {
+    [group]: Object.fromEntries(
+      items.map(({ hex, name }) => {
+        const entry =
+          prefix && name.startsWith(`${prefix}-`)
+            ? name.slice(prefix.length + 1)
+            : name;
+        return [entry, { $type: "color", $value: hex }];
+      }),
+    ),
+  };
+  return JSON.stringify(obj, null, 2) + "\n";
+}
+
+function defaultName(index: number): string {
+  // Tailwind-style 50/100…900 scale up to 10 colors, then numeric.
+  const scale = [
+    "50",
+    "100",
+    "200",
+    "300",
+    "400",
+    "500",
+    "600",
+    "700",
+    "800",
+    "900",
+  ];
+  return scale[index] ?? String((index + 1) * 100);
+}
+
+function resolveNames(
+  colors: string[],
+  names?: string[],
+  prefix?: string,
+): NamedColor[] {
+  return colors.map((c, i) => {
+    const parsed = parseColor(c);
+    if (!parsed) throw new Error(`Invalid color: ${c}`);
+    const hex = rgbToHex(parsed);
+    const raw = names?.[i] ?? defaultName(i);
+    const slug = raw.toLowerCase().replace(/[^a-z0-9-]+/g, "-");
+    const name = prefix ? `${prefix}-${slug}` : slug;
+    return { hex, name };
+  });
+}
+
+export const exportPaletteTool = {
+  description:
+    "Export a list of colors as CSS custom properties, SCSS variables, a Tailwind config snippet, W3C design tokens, or JSON.",
+  execute: async (args: {
+    colors: string[];
+    format: ExportFormat;
+    names?: string[];
+    prefix?: string;
+  }) => {
+    const { colors, format, names, prefix } = args;
+
+    if (names && names.length !== colors.length) {
+      return `Error: names array length (${names.length}) must match colors length (${colors.length}).`;
+    }
+
+    let items: NamedColor[];
+    try {
+      items = resolveNames(colors, names, prefix);
+    } catch (e) {
+      return e instanceof Error ? e.message : String(e);
+    }
+
+    switch (format) {
+      case "css":
+        return asCss(items);
+      case "json":
+        return asJson(items);
+      case "scss":
+        return asScss(items);
+      case "tailwind":
+        return asTailwind(items, prefix);
+      case "tokens":
+        return asTokens(items, prefix);
+    }
+  },
+  name: "export_palette",
+  parameters: z.object({
+    colors: z.array(z.string()).min(1).describe("Palette colors"),
+    format: z
+      .enum(FORMATS)
+      .describe(
+        "Output format: css (custom properties), scss (variables), tailwind (config), tokens (W3C design tokens), json",
+      ),
+    names: z
+      .array(z.string())
+      .optional()
+      .describe(
+        "Optional names for each color. Length must match colors. Defaults to a 50/100…900 scale.",
+      ),
+    prefix: z
+      .string()
+      .optional()
+      .describe("Optional prefix for variable/token names (e.g. 'brand')"),
+  }),
+};