@rog0x/mcp-color-tools 1.0.0

package/src/tools/color-mixer.ts

@@ -0,0 +1,165 @@
+// Color Mixer — mix colors, blend, lighten, darken, saturate, desaturate.
+
+import {
+  parseColor,
+  rgbToHex,
+  rgbToHsl,
+  hslToRgb,
+  type RGB,
+  type HSL,
+} from "./color-converter.js";
+
+interface MixedColor {
+  hex: string;
+  rgb: RGB;
+  hsl: HSL;
+}
+
+function formatResult(rgb: RGB): MixedColor {
+  return {
+    hex: rgbToHex(rgb),
+    rgb,
+    hsl: rgbToHsl(rgb),
+  };
+}
+
+function clampRgb(rgb: RGB): RGB {
+  return {
+    r: Math.max(0, Math.min(255, Math.round(rgb.r))),
+    g: Math.max(0, Math.min(255, Math.round(rgb.g))),
+    b: Math.max(0, Math.min(255, Math.round(rgb.b))),
+  };
+}
+
+function clampHsl(hsl: HSL): HSL {
+  return {
+    h: ((hsl.h % 360) + 360) % 360,
+    s: Math.max(0, Math.min(100, hsl.s)),
+    l: Math.max(0, Math.min(100, hsl.l)),
+  };
+}
+
+// Mix two or more colors in specified ratios (weighted average in RGB space)
+export function mixColors(
+  colors: string[],
+  weights?: number[]
+): MixedColor {
+  if (colors.length < 2) {
+    throw new Error("Provide at least 2 colors to mix");
+  }
+
+  const rgbColors = colors.map((c) => parseColor(c));
+
+  // Default to equal weights
+  const w = weights && weights.length === colors.length
+    ? weights
+    : colors.map(() => 1);
+
+  const totalWeight = w.reduce((sum, v) => sum + v, 0);
+  if (totalWeight === 0) throw new Error("Total weight cannot be zero");
+
+  let r = 0, g = 0, b = 0;
+  for (let i = 0; i < rgbColors.length; i++) {
+    const ratio = w[i] / totalWeight;
+    r += rgbColors[i].r * ratio;
+    g += rgbColors[i].g * ratio;
+    b += rgbColors[i].b * ratio;
+  }
+
+  const result = clampRgb({ r, g, b });
+  return formatResult(result);
+}
+
+// Blend two colors at a given ratio (0 = color1, 1 = color2)
+export function blendColors(
+  color1: string,
+  color2: string,
+  ratio: number = 0.5
+): MixedColor {
+  const t = Math.max(0, Math.min(1, ratio));
+  const rgb1 = parseColor(color1);
+  const rgb2 = parseColor(color2);
+
+  const result = clampRgb({
+    r: rgb1.r + (rgb2.r - rgb1.r) * t,
+    g: rgb1.g + (rgb2.g - rgb1.g) * t,
+    b: rgb1.b + (rgb2.b - rgb1.b) * t,
+  });
+
+  return formatResult(result);
+}
+
+// Lighten a color by a percentage (0-100)
+export function lightenColor(color: string, amount: number = 10): MixedColor {
+  const rgb = parseColor(color);
+  const hsl = rgbToHsl(rgb);
+  const adjusted = clampHsl({ ...hsl, l: hsl.l + amount });
+  const result = hslToRgb(adjusted);
+  return formatResult(result);
+}
+
+// Darken a color by a percentage (0-100)
+export function darkenColor(color: string, amount: number = 10): MixedColor {
+  const rgb = parseColor(color);
+  const hsl = rgbToHsl(rgb);
+  const adjusted = clampHsl({ ...hsl, l: hsl.l - amount });
+  const result = hslToRgb(adjusted);
+  return formatResult(result);
+}
+
+// Saturate a color by a percentage (0-100)
+export function saturateColor(color: string, amount: number = 10): MixedColor {
+  const rgb = parseColor(color);
+  const hsl = rgbToHsl(rgb);
+  const adjusted = clampHsl({ ...hsl, s: hsl.s + amount });
+  const result = hslToRgb(adjusted);
+  return formatResult(result);
+}
+
+// Desaturate a color by a percentage (0-100)
+export function desaturateColor(color: string, amount: number = 10): MixedColor {
+  const rgb = parseColor(color);
+  const hsl = rgbToHsl(rgb);
+  const adjusted = clampHsl({ ...hsl, s: hsl.s - amount });
+  const result = hslToRgb(adjusted);
+  return formatResult(result);
+}
+
+export type MixOperation =
+  | "mix"
+  | "blend"
+  | "lighten"
+  | "darken"
+  | "saturate"
+  | "desaturate";
+
+export interface MixRequest {
+  operation: MixOperation;
+  colors: string[];
+  weights?: number[];
+  ratio?: number;
+  amount?: number;
+}
+
+export function colorMix(req: MixRequest): MixedColor {
+  switch (req.operation) {
+    case "mix":
+      return mixColors(req.colors, req.weights);
+    case "blend":
+      if (req.colors.length < 2)
+        throw new Error("Blend requires exactly 2 colors");
+      return blendColors(req.colors[0], req.colors[1], req.ratio ?? 0.5);
+    case "lighten":
+      return lightenColor(req.colors[0], req.amount ?? 10);
+    case "darken":
+      return darkenColor(req.colors[0], req.amount ?? 10);
+    case "saturate":
+      return saturateColor(req.colors[0], req.amount ?? 10);
+    case "desaturate":
+      return desaturateColor(req.colors[0], req.amount ?? 10);
+    default:
+      throw new Error(
+        `Unknown operation: "${req.operation}". Use: mix, blend, lighten, darken, saturate, desaturate`
+      );
+  }
+}

package/src/tools/contrast-checker.ts

@@ -0,0 +1,80 @@
+// Contrast Checker — check WCAG contrast ratio between two colors.
+// Reports AA/AAA compliance for normal and large text.
+
+import { parseColor, rgbToHex, type RGB } from "./color-converter.js";
+
+interface ContrastResult {
+  color1: { hex: string; rgb: RGB };
+  color2: { hex: string; rgb: RGB };
+  ratio: number;
+  ratioString: string;
+  wcag: {
+    aa: {
+      normalText: boolean;
+      largeText: boolean;
+      uiComponents: boolean;
+    };
+    aaa: {
+      normalText: boolean;
+      largeText: boolean;
+    };
+  };
+  rating: string;
+}
+
+function relativeLuminance(rgb: RGB): number {
+  const toLinear = (c: number): number => {
+    const srgb = c / 255;
+    return srgb <= 0.04045
+      ? srgb / 12.92
+      : Math.pow((srgb + 0.055) / 1.055, 2.4);
+  };
+
+  const r = toLinear(rgb.r);
+  const g = toLinear(rgb.g);
+  const b = toLinear(rgb.b);
+
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+function contrastRatio(lum1: number, lum2: number): number {
+  const lighter = Math.max(lum1, lum2);
+  const darker = Math.min(lum1, lum2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+function getRating(ratio: number): string {
+  if (ratio >= 7) return "Excellent (AAA)";
+  if (ratio >= 4.5) return "Good (AA normal text)";
+  if (ratio >= 3) return "Acceptable (AA large text only)";
+  return "Poor (fails WCAG AA)";
+}
+
+export function checkContrast(color1: string, color2: string): ContrastResult {
+  const rgb1 = parseColor(color1);
+  const rgb2 = parseColor(color2);
+
+  const lum1 = relativeLuminance(rgb1);
+  const lum2 = relativeLuminance(rgb2);
+  const ratio = contrastRatio(lum1, lum2);
+  const rounded = Math.round(ratio * 100) / 100;
+
+  return {
+    color1: { hex: rgbToHex(rgb1), rgb: rgb1 },
+    color2: { hex: rgbToHex(rgb2), rgb: rgb2 },
+    ratio: rounded,
+    ratioString: `${rounded}:1`,
+    wcag: {
+      aa: {
+        normalText: ratio >= 4.5,
+        largeText: ratio >= 3,
+        uiComponents: ratio >= 3,
+      },
+      aaa: {
+        normalText: ratio >= 7,
+        largeText: ratio >= 4.5,
+      },
+    },
+    rating: getRating(ratio),
+  };
+}

package/src/tools/css-gradient.ts

@@ -0,0 +1,143 @@
+// CSS Gradient Generator — generate CSS gradient code from colors.
+// Supports linear, radial, and conic gradients with direction, stops, and browser prefixes.
+
+import { parseColor, rgbToHex } from "./color-converter.js";
+
+export type GradientType = "linear" | "radial" | "conic";
+
+export interface ColorStop {
+  color: string;
+  position?: number; // percentage 0-100
+}
+
+export interface GradientRequest {
+  type: GradientType;
+  colors: (string | ColorStop)[];
+  direction?: string;       // e.g. "to right", "45deg", "circle", "from 0deg"
+  includePrefix?: boolean;  // include -webkit- prefix (default true)
+}
+
+interface GradientResult {
+  type: GradientType;
+  css: string;
+  cssWithPrefix: string;
+  cssProperty: string;
+  stops: { hex: string; position: string }[];
+}
+
+function normalizeStops(
+  colors: (string | ColorStop)[]
+): { hex: string; position: string }[] {
+  if (colors.length < 2) {
+    throw new Error("Gradient requires at least 2 colors");
+  }
+
+  return colors.map((entry, index) => {
+    let colorStr: string;
+    let pos: number | undefined;
+
+    if (typeof entry === "string") {
+      colorStr = entry;
+    } else {
+      colorStr = entry.color;
+      pos = entry.position;
+    }
+
+    const rgb = parseColor(colorStr);
+    const hex = rgbToHex(rgb);
+
+    // Auto-distribute if no position given
+    if (pos === undefined) {
+      pos = colors.length === 1 ? 0 : (index / (colors.length - 1)) * 100;
+    }
+
+    return {
+      hex,
+      position: `${Math.round(pos)}%`,
+    };
+  });
+}
+
+function buildStopsString(stops: { hex: string; position: string }[]): string {
+  return stops.map((s) => `${s.hex} ${s.position}`).join(", ");
+}
+
+function buildLinearGradient(
+  stops: { hex: string; position: string }[],
+  direction: string
+): { standard: string; prefixed: string } {
+  const stopsStr = buildStopsString(stops);
+  const standard = `linear-gradient(${direction}, ${stopsStr})`;
+  const prefixed = `-webkit-linear-gradient(${direction}, ${stopsStr})`;
+  return { standard, prefixed };
+}
+
+function buildRadialGradient(
+  stops: { hex: string; position: string }[],
+  shape: string
+): { standard: string; prefixed: string } {
+  const stopsStr = buildStopsString(stops);
+  const standard = `radial-gradient(${shape}, ${stopsStr})`;
+  const prefixed = `-webkit-radial-gradient(${shape}, ${stopsStr})`;
+  return { standard, prefixed };
+}
+
+function buildConicGradient(
+  stops: { hex: string; position: string }[],
+  direction: string
+): { standard: string; prefixed: string } {
+  const stopsStr = buildStopsString(stops);
+  const standard = `conic-gradient(${direction}, ${stopsStr})`;
+  // conic-gradient has limited prefix support but include for completeness
+  const prefixed = `-webkit-conic-gradient(${direction}, ${stopsStr})`;
+  return { standard, prefixed };
+}
+
+export function generateGradient(req: GradientRequest): GradientResult {
+  const stops = normalizeStops(req.colors);
+  const includePrefix = req.includePrefix !== false;
+
+  let standard: string;
+  let prefixed: string;
+
+  switch (req.type) {
+    case "linear": {
+      const direction = req.direction || "to right";
+      const result = buildLinearGradient(stops, direction);
+      standard = result.standard;
+      prefixed = result.prefixed;
+      break;
+    }
+    case "radial": {
+      const shape = req.direction || "circle at center";
+      const result = buildRadialGradient(stops, shape);
+      standard = result.standard;
+      prefixed = result.prefixed;
+      break;
+    }
+    case "conic": {
+      const direction = req.direction || "from 0deg at center";
+      const result = buildConicGradient(stops, direction);
+      standard = result.standard;
+      prefixed = result.prefixed;
+      break;
+    }
+    default:
+      throw new Error(
+        `Unknown gradient type: "${req.type}". Use: linear, radial, conic`
+      );
+  }
+
+  const cssProperty = `background: ${standard};`;
+  const cssWithPrefix = includePrefix
+    ? `background: ${prefixed};\nbackground: ${standard};`
+    : cssProperty;
+
+  return {
+    type: req.type,
+    css: standard,
+    cssWithPrefix,
+    cssProperty,
+    stops,
+  };
+}

package/src/tools/palette-generator.ts

@@ -0,0 +1,126 @@
+// Palette Generator — generate color palettes from a base color.
+// Supports: complementary, analogous, triadic, split-complementary, monochromatic.
+
+import {
+  parseColor,
+  rgbToHsl,
+  hslToRgb,
+  rgbToHex,
+  type RGB,
+  type HSL,
+} from "./color-converter.js";
+
+export type PaletteType =
+  | "complementary"
+  | "analogous"
+  | "triadic"
+  | "split-complementary"
+  | "monochromatic";
+
+interface PaletteColor {
+  hex: string;
+  rgb: { r: number; g: number; b: number };
+  hsl: { h: number; s: number; l: number };
+  role: string;
+}
+
+interface PaletteResult {
+  type: PaletteType;
+  base: string;
+  colors: PaletteColor[];
+}
+
+function hslColor(h: number, s: number, l: number, role: string): PaletteColor {
+  const hNorm = ((h % 360) + 360) % 360;
+  const sNorm = Math.max(0, Math.min(100, s));
+  const lNorm = Math.max(0, Math.min(100, l));
+  const hsl: HSL = { h: Math.round(hNorm * 100) / 100, s: Math.round(sNorm * 100) / 100, l: Math.round(lNorm * 100) / 100 };
+  const rgb = hslToRgb(hsl);
+  return {
+    hex: rgbToHex(rgb),
+    rgb,
+    hsl,
+    role,
+  };
+}
+
+function generateComplementary(hsl: HSL): PaletteColor[] {
+  return [
+    hslColor(hsl.h, hsl.s, hsl.l, "base"),
+    hslColor(hsl.h + 180, hsl.s, hsl.l, "complementary"),
+  ];
+}
+
+function generateAnalogous(hsl: HSL): PaletteColor[] {
+  return [
+    hslColor(hsl.h - 30, hsl.s, hsl.l, "analogous -30"),
+    hslColor(hsl.h - 15, hsl.s, hsl.l, "analogous -15"),
+    hslColor(hsl.h, hsl.s, hsl.l, "base"),
+    hslColor(hsl.h + 15, hsl.s, hsl.l, "analogous +15"),
+    hslColor(hsl.h + 30, hsl.s, hsl.l, "analogous +30"),
+  ];
+}
+
+function generateTriadic(hsl: HSL): PaletteColor[] {
+  return [
+    hslColor(hsl.h, hsl.s, hsl.l, "base"),
+    hslColor(hsl.h + 120, hsl.s, hsl.l, "triadic +120"),
+    hslColor(hsl.h + 240, hsl.s, hsl.l, "triadic +240"),
+  ];
+}
+
+function generateSplitComplementary(hsl: HSL): PaletteColor[] {
+  return [
+    hslColor(hsl.h, hsl.s, hsl.l, "base"),
+    hslColor(hsl.h + 150, hsl.s, hsl.l, "split-complementary +150"),
+    hslColor(hsl.h + 210, hsl.s, hsl.l, "split-complementary +210"),
+  ];
+}
+
+function generateMonochromatic(hsl: HSL): PaletteColor[] {
+  return [
+    hslColor(hsl.h, hsl.s, Math.max(hsl.l - 30, 5), "darkest"),
+    hslColor(hsl.h, hsl.s, Math.max(hsl.l - 15, 10), "darker"),
+    hslColor(hsl.h, hsl.s, hsl.l, "base"),
+    hslColor(hsl.h, hsl.s, Math.min(hsl.l + 15, 90), "lighter"),
+    hslColor(hsl.h, hsl.s, Math.min(hsl.l + 30, 95), "lightest"),
+  ];
+}
+
+export function generatePalette(
+  color: string,
+  type: PaletteType
+): PaletteResult {
+  const rgb = parseColor(color);
+  const hsl = rgbToHsl(rgb);
+
+  let colors: PaletteColor[];
+
+  switch (type) {
+    case "complementary":
+      colors = generateComplementary(hsl);
+      break;
+    case "analogous":
+      colors = generateAnalogous(hsl);
+      break;
+    case "triadic":
+      colors = generateTriadic(hsl);
+      break;
+    case "split-complementary":
+      colors = generateSplitComplementary(hsl);
+      break;
+    case "monochromatic":
+      colors = generateMonochromatic(hsl);
+      break;
+    default:
+      throw new Error(
+        `Unknown palette type: "${type}". Use: complementary, analogous, triadic, split-complementary, monochromatic`
+      );
+  }
+
+  return {
+    type,
+    base: rgbToHex(rgb),
+    colors,
+  };
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true
+  },
+  "include": ["src/**/*"]
+}