@trishchuk/coolors-mcp 1.0.0

package/src/tools/__tests__/palette-with-locks.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from "vitest";
+
+import { paletteWithLocksTool } from "../palette-with-locks.tool.js";
+
+describe("paletteWithLocksTool", () => {
+  it("should generate palette with locked colors in harmony mode", async () => {
+    const result = await paletteWithLocksTool.execute({
+      colorSpace: "hsl",
+      lockedColors: ["#ff0000", "#0000ff"],
+      mode: "harmony",
+      totalColors: 5,
+    });
+
+    expect(result).toContain("Generated palette with 2 locked colors:");
+    expect(result).toContain("(locked)");
+    expect(result).toContain("Mode: harmony");
+    expect(result).toContain("Total colors: 5");
+  });
+
+  it("should generate palette with contrast mode", async () => {
+    const result = await paletteWithLocksTool.execute({
+      colorSpace: "hsl",
+      lockedColors: ["#808080"],
+      mode: "contrast",
+      totalColors: 4,
+    });
+
+    expect(result).toContain("Generated palette with 1 locked colors:");
+    expect(result).toContain("Mode: contrast");
+    expect(result).toContain("Total colors: 4");
+  });
+
+  it("should generate gradient between locked colors", async () => {
+    const result = await paletteWithLocksTool.execute({
+      colorSpace: "lab",
+      lockedColors: ["#000000", "#ffffff"],
+      mode: "gradient",
+      totalColors: 5,
+    });
+
+    expect(result).toContain("Generated palette with 2 locked colors:");
+    expect(result).toContain("Mode: gradient");
+    expect(result).toContain("Color space: lab");
+  });
+
+  it("should handle gradient with HSL interpolation", async () => {
+    const result = await paletteWithLocksTool.execute({
+      colorSpace: "hsl",
+      lockedColors: ["#ff0000", "#00ff00"],
+      mode: "gradient",
+      totalColors: 7,
+    });
+
+    expect(result).toContain("Generated palette with 2 locked colors:");
+    expect(result).toContain("Mode: gradient");
+    expect(result).toContain("Color space: hsl");
+  });
+
+  it("should error when locked colors >= total colors", async () => {
+    const result = await paletteWithLocksTool.execute({
+      colorSpace: "hsl",
+      lockedColors: ["#ff0000", "#00ff00", "#0000ff"],
+      mode: "harmony",
+      totalColors: 3,
+    });
+
+    expect(result).toContain("Error: Number of locked colors");
+  });
+
+  it("should error on invalid color format", async () => {
+    const result = await paletteWithLocksTool.execute({
+      colorSpace: "hsl",
+      lockedColors: ["invalid", "#00ff00"],
+      mode: "harmony",
+      totalColors: 5,
+    });
+
+    expect(result).toContain("Invalid color format: invalid");
+  });
+
+  it("should error in gradient mode with only one locked color", async () => {
+    const result = await paletteWithLocksTool.execute({
+      colorSpace: "hsl",
+      lockedColors: ["#ff0000"],
+      mode: "gradient",
+      totalColors: 5,
+    });
+
+    expect(result).toContain("Gradient mode requires at least 2 locked colors");
+  });
+
+  it("should generate harmonious colors with multiple locked colors", async () => {
+    const result = await paletteWithLocksTool.execute({
+      colorSpace: "hsl",
+      lockedColors: ["#ff0000", "#00ff00", "#0000ff"],
+      mode: "harmony",
+      totalColors: 6,
+    });
+
+    expect(result).toContain("Generated palette with 3 locked colors:");
+    expect(result).toContain("Mode: harmony");
+    expect(result).toContain("Total colors: 6");
+
+    // Should have 6 color entries
+    const lines = result.split("\n");
+    const colorLines = lines.filter((line) => /^\d+\./.test(line));
+    expect(colorLines).toHaveLength(6);
+  });
+});

package/src/tools/color-conversion.tool.ts

@@ -0,0 +1,54 @@
+/**
+ * Color Conversion Tool
+ * Convert colors between different formats (hex, rgb, hsl, lab, hct)
+ */
+
+import { z } from "zod";
+
+import {
+  parseColor,
+  rgbToHct,
+  rgbToHex,
+  rgbToHsl,
+  rgbToLab,
+} from "../color/index.js";
+
+export const colorConversionTool = {
+  description:
+    "Convert colors between different formats (hex, rgb, hsl, lab, hct)",
+  execute: async (args: {
+    color: string;
+    to: "hct" | "hex" | "hsl" | "lab" | "rgb";
+  }) => {
+    const rgb = parseColor(args.color);
+    if (!rgb) {
+      return `Invalid color format: ${args.color}`;
+    }
+
+    switch (args.to) {
+      case "hct": {
+        const hct = rgbToHct(rgb);
+        return `hct(${hct.h.toFixed(1)}, ${hct.c.toFixed(1)}, ${hct.t.toFixed(1)})`;
+      }
+      case "hex":
+        return rgbToHex(rgb);
+      case "hsl": {
+        const hsl = rgbToHsl(rgb);
+        return `hsl(${Math.round(hsl.h)}, ${Math.round(hsl.s)}%, ${Math.round(hsl.l)}%)`;
+      }
+      case "lab": {
+        const lab = rgbToLab(rgb);
+        return `lab(${lab.l.toFixed(2)}, ${lab.a.toFixed(2)}, ${lab.b.toFixed(2)})`;
+      }
+      case "rgb":
+        return `rgb(${Math.round(rgb.r * 255)}, ${Math.round(rgb.g * 255)}, ${Math.round(rgb.b * 255)})`;
+      default:
+        return `Invalid format: ${args.to}`;
+    }
+  },
+  name: "convert_color",
+  parameters: z.object({
+    color: z.string().describe("Color to convert (hex, rgb(), or hsl())"),
+    to: z.enum(["hex", "rgb", "hsl", "lab", "hct"]).describe("Target format"),
+  }),
+};

package/src/tools/color-distance.tool.ts

@@ -0,0 +1,41 @@
+/**
+ * Color Distance Tool
+ * Calculate perceptual distance between two colors using various metrics
+ */
+
+import { z } from "zod";
+
+import { colorDistance, parseColor } from "../color/index.js";
+
+export const colorDistanceTool = {
+  description:
+    "Calculate perceptual distance between two colors using Delta E 2000",
+  execute: async (args: {
+    color1: string;
+    color2: string;
+    metric?: "deltaE2000" | "deltaE76" | "deltaE94" | "euclidean" | "weighted";
+  }) => {
+    const rgb1 = parseColor(args.color1);
+    const rgb2 = parseColor(args.color2);
+
+    if (!rgb1 || !rgb2) {
+      return `Invalid color format: ${!rgb1 ? args.color1 : args.color2}`;
+    }
+
+    const distance = colorDistance(rgb1, rgb2, {
+      metric: args.metric || "deltaE2000",
+    });
+
+    return `Distance between ${args.color1} and ${args.color2}: ${distance.toFixed(2)}`;
+  },
+  name: "color_distance",
+  parameters: z.object({
+    color1: z.string().describe("First color (hex, rgb, or hsl)"),
+    color2: z.string().describe("Second color (hex, rgb, or hsl)"),
+    metric: z
+      .enum(["euclidean", "deltaE76", "deltaE94", "deltaE2000", "weighted"])
+      .optional()
+      .default("deltaE2000")
+      .describe("Distance metric to use"),
+  }),
+};

package/src/tools/colors.ts

@@ -0,0 +1,31 @@
+import { formatHex, formatHsl, formatRgb, parse } from "culori";
+import { z } from "zod";
+
+import { ColorFormat } from "../constants.js";
+
+export const convertColor = {
+  description: "Convert a color from one format to another",
+  execute: async (args: { color: string; to?: ColorFormat }) => {
+    const { color, to = ColorFormat.HEX } = args;
+    const parsed = parse(color);
+    if (!parsed) {
+      throw new Error(`Invalid color: ${color}`);
+    }
+
+    switch (to) {
+      case ColorFormat.HEX:
+        return formatHex(parsed);
+      case ColorFormat.HSL:
+        return formatHsl(parsed);
+      case ColorFormat.RGB:
+        return formatRgb(parsed);
+      default:
+        throw new Error(`Invalid output format: ${to}`);
+    }
+  },
+  name: "convertColor",
+  parameters: z.object({
+    color: z.string().describe("The color to convert"),
+    to: z.nativeEnum(ColorFormat).optional().describe("The output format"),
+  }),
+};

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

@@ -0,0 +1,37 @@
+/**
+ * Contrast Checker Tool
+ * Check WCAG contrast ratio between two colors
+ */
+
+import { z } from "zod";
+
+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 }) => {
+    const fg = parseColor(args.foreground);
+    const bg = parseColor(args.background);
+
+    if (!fg || !bg) {
+      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)`;
+  },
+  name: "check_contrast",
+  parameters: z.object({
+    background: z.string().describe("Background color"),
+    foreground: z.string().describe("Foreground/text color"),
+  }),
+};

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

@@ -0,0 +1,247 @@
+/**
+ * MCP Tools for Dislike Color Analysis
+ * Identifies and fixes universally disliked colors based on color psychology research
+ */
+
+import type { Tool } from "../types.js";
+
+type McpTool = Tool<any>;
+
+import { DislikeAnalyzer } from "../color/dislike/dislike-analyzer.js";
+import { Hct } from "../color/hct/hct-class.js";
+import { parseColor, rgbToArgb } from "../color/index.js";
+
+/**
+ * Analyze if a color is universally disliked
+ */
+export const analyzeColorLikabilityTool: McpTool = {
+  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;
+    };
+
+    try {
+      // Parse the input color
+      const rgb = parseColor(color);
+      if (!rgb) {
+        return `Error: Invalid color format: ${color}`;
+      }
+
+      // Convert to HCT for analysis
+      const argb = rgbToArgb(rgb);
+      const hct = Hct.fromInt(argb);
+
+      // Check if disliked
+      const isDisliked = DislikeAnalyzer.isDisliked(hct);
+
+      let output = `# Color Likability Analysis\n\n`;
+      output += `## Input Color: ${color}\n\n`;
+      output += `### HCT Values\n`;
+      output += `- Hue: ${hct.hue.toFixed(1)}°\n`;
+      output += `- Chroma: ${hct.chroma.toFixed(1)}\n`;
+      output += `- Tone: ${hct.tone.toFixed(1)}\n\n`;
+
+      output += `### Analysis Result\n`;
+
+      if (isDisliked) {
+        output += `⚠️ **This color is universally disliked**\n\n`;
+        output += `This color falls in the "bile zone" - dark yellow-greens that are universally associated with biological waste and rotting food.\n\n`;
+        output += `**Reason:**\n`;
+        output += `- Hue is in yellow-green range (90-111°): ${Math.round(hct.hue)}°\n`;
+        output += `- Chroma is above threshold (>16): ${Math.round(hct.chroma)}\n`;
+        output += `- Tone is dark (<65): ${Math.round(hct.tone)}\n\n`;
+
+        if (autoFix) {
+          const fixed = DislikeAnalyzer.fixIfDisliked(hct);
+          const fixedArgb = fixed.toInt();
+          const fixedHex =
+            "#" +
+            [
+              (fixedArgb >> 16) & 0xff,
+              (fixedArgb >> 8) & 0xff,
+              fixedArgb & 0xff,
+            ]
+              .map((x) => x.toString(16).padStart(2, "0"))
+              .join("");
+
+          output += `### Recommended Fix\n`;
+          output += `**Fixed Color:** ${fixedHex}\n`;
+          output += `- Hue: ${fixed.hue.toFixed(1)}° (preserved)\n`;
+          output += `- Chroma: ${fixed.chroma.toFixed(1)} (preserved)\n`;
+          output += `- Tone: ${fixed.tone.toFixed(1)} (lightened to 70)\n\n`;
+          output += `The fix preserves the hue and saturation but lightens the color to make it more pleasant.\n`;
+        }
+      } else {
+        output += `✅ **This color is likable**\n\n`;
+        output += `This color does not fall in the universally disliked range.\n`;
+
+        // Provide context about why it's liked
+        if (Math.round(hct.hue) >= 90 && Math.round(hct.hue) <= 111) {
+          if (Math.round(hct.chroma) <= 16) {
+            output += `- Although in yellow-green hue range, the low chroma (${Math.round(hct.chroma)}) makes it neutral and acceptable.\n`;
+          } else if (Math.round(hct.tone) >= 65) {
+            output += `- Although in yellow-green hue range, the light tone (${Math.round(hct.tone)}) makes it pleasant.\n`;
+          }
+        } else {
+          output += `- Hue (${Math.round(hct.hue)}°) is outside the problematic yellow-green range.\n`;
+        }
+      }
+
+      return output;
+    } catch (error) {
+      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",
+};
+
+/**
+ * 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;
+    };
+
+    try {
+      const results: Array<{
+        error?: string;
+        fixed?: string;
+        hct?: unknown;
+        original: string;
+        wasDisliked?: boolean;
+      }> = [];
+      let dislikedCount = 0;
+
+      for (const color of colors) {
+        const rgb = parseColor(color);
+        if (!rgb) {
+          results.push({
+            error: "Invalid color format",
+            original: color,
+          });
+          continue;
+        }
+
+        const argb = rgbToArgb(rgb);
+        const hct = Hct.fromInt(argb);
+        const isDisliked = DislikeAnalyzer.isDisliked(hct);
+
+        if (isDisliked) {
+          dislikedCount++;
+          const fixed = DislikeAnalyzer.fixIfDisliked(hct);
+          const fixedArgb = fixed.toInt();
+          const fixedHex =
+            "#" +
+            [
+              (fixedArgb >> 16) & 0xff,
+              (fixedArgb >> 8) & 0xff,
+              fixedArgb & 0xff,
+            ]
+              .map((x) => x.toString(16).padStart(2, "0"))
+              .join("");
+
+          results.push({
+            fixed: fixedHex,
+            hct: includeAnalysis
+              ? {
+                  fixed: { c: fixed.chroma, h: fixed.hue, t: fixed.tone },
+                  original: { c: hct.chroma, h: hct.hue, t: hct.tone },
+                }
+              : undefined,
+            original: color,
+            wasDisliked: true,
+          });
+        } else {
+          results.push({
+            fixed: color,
+            hct: includeAnalysis
+              ? {
+                  c: hct.chroma,
+                  h: hct.hue,
+                  t: hct.tone,
+                }
+              : undefined,
+            original: color,
+            wasDisliked: false,
+          });
+        }
+      }
+
+      let output = `# Batch Color Likability Analysis\n\n`;
+      output += `## Summary\n`;
+      output += `- Total colors: ${colors.length}\n`;
+      output += `- Disliked colors found: ${dislikedCount}\n`;
+      output += `- Percentage disliked: ${((dislikedCount / colors.length) * 100).toFixed(1)}%\n\n`;
+
+      output += `## Results\n\n`;
+
+      for (const result of results) {
+        if (result.error) {
+          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`;
+          }
+        } 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 (dislikedCount > 0) {
+        output += `\n## Note\n`;
+        output += `Disliked colors have been automatically fixed by lightening their tone to 70 while preserving hue and chroma. `;
+        output += `This makes them more pleasant while maintaining their essential character.\n`;
+      }
+
+      return output;
+    } catch (error) {
+      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",
+};