@rog0x/mcp-color-tools 1.0.0

package/src/index.ts

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { convertColor } from "./tools/color-converter.js";
+import { generatePalette, type PaletteType } from "./tools/palette-generator.js";
+import { checkContrast } from "./tools/contrast-checker.js";
+import { colorMix, type MixOperation } from "./tools/color-mixer.js";
+import { generateGradient, type GradientType, type ColorStop } from "./tools/css-gradient.js";
+
+const server = new Server(
+  {
+    name: "mcp-color-tools",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "color_convert",
+      description:
+        "Convert a color between formats: HEX, RGB, HSL, HSV, CMYK. Accepts any format as input and returns all formats.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          color: {
+            type: "string",
+            description:
+              "Color in any format: HEX (#ff0000), RGB (rgb(255,0,0)), HSL (hsl(0,100%,50%)), HSV (hsv(0,100%,100%)), CMYK (cmyk(0,100,100,0))",
+          },
+        },
+        required: ["color"],
+      },
+    },
+    {
+      name: "palette_generate",
+      description:
+        "Generate a color palette from a base color. Types: complementary, analogous, triadic, split-complementary, monochromatic.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          color: {
+            type: "string",
+            description: "Base color in any supported format",
+          },
+          type: {
+            type: "string",
+            description:
+              "Palette type: complementary, analogous, triadic, split-complementary, monochromatic",
+            enum: [
+              "complementary",
+              "analogous",
+              "triadic",
+              "split-complementary",
+              "monochromatic",
+            ],
+          },
+        },
+        required: ["color", "type"],
+      },
+    },
+    {
+      name: "contrast_check",
+      description:
+        "Check WCAG contrast ratio between two colors. Reports AA/AAA compliance for normal text, large text, and UI components.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          color1: {
+            type: "string",
+            description: "First color (foreground) in any supported format",
+          },
+          color2: {
+            type: "string",
+            description: "Second color (background) in any supported format",
+          },
+        },
+        required: ["color1", "color2"],
+      },
+    },
+    {
+      name: "color_mix",
+      description:
+        "Mix, blend, lighten, darken, saturate, or desaturate colors. For mix/blend provide 2+ colors; for lighten/darken/saturate/desaturate provide 1 color and an amount.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          operation: {
+            type: "string",
+            description:
+              "Operation: mix, blend, lighten, darken, saturate, desaturate",
+            enum: [
+              "mix",
+              "blend",
+              "lighten",
+              "darken",
+              "saturate",
+              "desaturate",
+            ],
+          },
+          colors: {
+            type: "array",
+            items: { type: "string" },
+            description: "Array of colors in any supported format",
+          },
+          weights: {
+            type: "array",
+            items: { type: "number" },
+            description:
+              "Optional weights for mixing (same length as colors). Default: equal weights.",
+          },
+          ratio: {
+            type: "number",
+            description:
+              "Blend ratio from 0 (first color) to 1 (second color). Default: 0.5.",
+          },
+          amount: {
+            type: "number",
+            description:
+              "Amount for lighten/darken/saturate/desaturate (0-100). Default: 10.",
+          },
+        },
+        required: ["operation", "colors"],
+      },
+    },
+    {
+      name: "css_gradient",
+      description:
+        "Generate CSS gradient code. Supports linear, radial, and conic gradients with direction, stops, and browser prefixes.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          type: {
+            type: "string",
+            description: "Gradient type: linear, radial, conic",
+            enum: ["linear", "radial", "conic"],
+          },
+          colors: {
+            type: "array",
+            items: {
+              oneOf: [
+                { type: "string" },
+                {
+                  type: "object",
+                  properties: {
+                    color: { type: "string" },
+                    position: {
+                      type: "number",
+                      description: "Stop position as percentage (0-100)",
+                    },
+                  },
+                  required: ["color"],
+                },
+              ],
+            },
+            description:
+              "Array of colors (strings) or color stops ({color, position}). Minimum 2.",
+          },
+          direction: {
+            type: "string",
+            description:
+              "Direction/shape. Linear: 'to right', '45deg'. Radial: 'circle at center', 'ellipse at top'. Conic: 'from 0deg at center'.",
+          },
+          includePrefix: {
+            type: "boolean",
+            description:
+              "Include -webkit- browser prefix. Default: true.",
+          },
+        },
+        required: ["type", "colors"],
+      },
+    },
+  ],
+}));
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case "color_convert": {
+        const result = convertColor(args?.color as string);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+      }
+
+      case "palette_generate": {
+        const result = generatePalette(
+          args?.color as string,
+          args?.type as PaletteType
+        );
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+      }
+
+      case "contrast_check": {
+        const result = checkContrast(
+          args?.color1 as string,
+          args?.color2 as string
+        );
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+      }
+
+      case "color_mix": {
+        const result = colorMix({
+          operation: args?.operation as MixOperation,
+          colors: args?.colors as string[],
+          weights: args?.weights as number[] | undefined,
+          ratio: args?.ratio as number | undefined,
+          amount: args?.amount as number | undefined,
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+      }
+
+      case "css_gradient": {
+        const result = generateGradient({
+          type: args?.type as GradientType,
+          colors: args?.colors as (string | ColorStop)[],
+          direction: args?.direction as string | undefined,
+          includePrefix: args?.includePrefix as boolean | undefined,
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+      }
+
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      content: [{ type: "text", text: `Error: ${message}` }],
+      isError: true,
+    };
+  }
+});
+
+// Start server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("MCP Color Tools server running on stdio");
+}
+
+main().catch(console.error);

package/src/tools/color-converter.ts

@@ -0,0 +1,311 @@
+// Color Converter — convert between HEX, RGB, HSL, HSV, and CMYK formats.
+// All color math is implemented manually without external libraries.
+
+export interface RGB {
+  r: number;
+  g: number;
+  b: number;
+}
+
+export interface HSL {
+  h: number;
+  s: number;
+  l: number;
+}
+
+export interface HSV {
+  h: number;
+  s: number;
+  v: number;
+}
+
+export interface CMYK {
+  c: number;
+  m: number;
+  y: number;
+  k: number;
+}
+
+// --- Parsing ---
+
+function parseHex(hex: string): RGB {
+  let h = hex.replace(/^#/, "").trim();
+  if (h.length === 3) {
+    h = h[0] + h[0] + h[1] + h[1] + h[2] + h[2];
+  }
+  if (!/^[0-9a-fA-F]{6}$/.test(h)) {
+    throw new Error(`Invalid HEX color: ${hex}`);
+  }
+  return {
+    r: parseInt(h.substring(0, 2), 16),
+    g: parseInt(h.substring(2, 4), 16),
+    b: parseInt(h.substring(4, 6), 16),
+  };
+}
+
+function parseRgbString(str: string): RGB {
+  const match = str.match(
+    /rgba?\s*\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*[\d.]+\s*)?\)/i
+  );
+  if (!match) throw new Error(`Invalid RGB string: ${str}`);
+  return {
+    r: clamp(parseInt(match[1]), 0, 255),
+    g: clamp(parseInt(match[2]), 0, 255),
+    b: clamp(parseInt(match[3]), 0, 255),
+  };
+}
+
+function parseHslString(str: string): HSL {
+  const match = str.match(
+    /hsla?\s*\(\s*([\d.]+)\s*,\s*([\d.]+)%?\s*,\s*([\d.]+)%?\s*(?:,\s*[\d.]+\s*)?\)/i
+  );
+  if (!match) throw new Error(`Invalid HSL string: ${str}`);
+  return {
+    h: parseFloat(match[1]) % 360,
+    s: clamp(parseFloat(match[2]), 0, 100),
+    l: clamp(parseFloat(match[3]), 0, 100),
+  };
+}
+
+function parseHsvString(str: string): HSV {
+  const match = str.match(
+    /hsv\s*\(\s*([\d.]+)\s*,\s*([\d.]+)%?\s*,\s*([\d.]+)%?\s*\)/i
+  );
+  if (!match) throw new Error(`Invalid HSV string: ${str}`);
+  return {
+    h: parseFloat(match[1]) % 360,
+    s: clamp(parseFloat(match[2]), 0, 100),
+    v: clamp(parseFloat(match[3]), 0, 100),
+  };
+}
+
+function parseCmykString(str: string): CMYK {
+  const match = str.match(
+    /cmyk\s*\(\s*([\d.]+)%?\s*,\s*([\d.]+)%?\s*,\s*([\d.]+)%?\s*,\s*([\d.]+)%?\s*\)/i
+  );
+  if (!match) throw new Error(`Invalid CMYK string: ${str}`);
+  return {
+    c: clamp(parseFloat(match[1]), 0, 100),
+    m: clamp(parseFloat(match[2]), 0, 100),
+    y: clamp(parseFloat(match[3]), 0, 100),
+    k: clamp(parseFloat(match[4]), 0, 100),
+  };
+}
+
+function clamp(val: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, val));
+}
+
+// --- Conversion core ---
+
+export function rgbToHex(rgb: RGB): string {
+  const toHex = (n: number) =>
+    clamp(Math.round(n), 0, 255).toString(16).padStart(2, "0");
+  return `#${toHex(rgb.r)}${toHex(rgb.g)}${toHex(rgb.b)}`;
+}
+
+export function rgbToHsl(rgb: RGB): HSL {
+  const r = rgb.r / 255;
+  const g = rgb.g / 255;
+  const b = rgb.b / 255;
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const delta = max - min;
+  let h = 0;
+  let s = 0;
+  const l = (max + min) / 2;
+
+  if (delta !== 0) {
+    s = l > 0.5 ? delta / (2 - max - min) : delta / (max + min);
+    if (max === r) {
+      h = ((g - b) / delta + (g < b ? 6 : 0)) * 60;
+    } else if (max === g) {
+      h = ((b - r) / delta + 2) * 60;
+    } else {
+      h = ((r - g) / delta + 4) * 60;
+    }
+  }
+
+  return {
+    h: round2(h),
+    s: round2(s * 100),
+    l: round2(l * 100),
+  };
+}
+
+export function hslToRgb(hsl: HSL): RGB {
+  const h = hsl.h;
+  const s = hsl.s / 100;
+  const l = hsl.l / 100;
+
+  if (s === 0) {
+    const v = Math.round(l * 255);
+    return { r: v, g: v, b: v };
+  }
+
+  const hueToRgb = (p: number, q: number, t: number): number => {
+    if (t < 0) t += 1;
+    if (t > 1) t -= 1;
+    if (t < 1 / 6) return p + (q - p) * 6 * t;
+    if (t < 1 / 2) return q;
+    if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;
+    return p;
+  };
+
+  const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+  const p = 2 * l - q;
+  const hNorm = h / 360;
+
+  return {
+    r: Math.round(hueToRgb(p, q, hNorm + 1 / 3) * 255),
+    g: Math.round(hueToRgb(p, q, hNorm) * 255),
+    b: Math.round(hueToRgb(p, q, hNorm - 1 / 3) * 255),
+  };
+}
+
+export function rgbToHsv(rgb: RGB): HSV {
+  const r = rgb.r / 255;
+  const g = rgb.g / 255;
+  const b = rgb.b / 255;
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const delta = max - min;
+  let h = 0;
+  const s = max === 0 ? 0 : delta / max;
+  const v = max;
+
+  if (delta !== 0) {
+    if (max === r) {
+      h = ((g - b) / delta + (g < b ? 6 : 0)) * 60;
+    } else if (max === g) {
+      h = ((b - r) / delta + 2) * 60;
+    } else {
+      h = ((r - g) / delta + 4) * 60;
+    }
+  }
+
+  return {
+    h: round2(h),
+    s: round2(s * 100),
+    v: round2(v * 100),
+  };
+}
+
+export function hsvToRgb(hsv: HSV): RGB {
+  const h = hsv.h;
+  const s = hsv.s / 100;
+  const v = hsv.v / 100;
+  const c = v * s;
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+  const m = v - c;
+  let r1 = 0,
+    g1 = 0,
+    b1 = 0;
+
+  if (h < 60) {
+    r1 = c; g1 = x; b1 = 0;
+  } else if (h < 120) {
+    r1 = x; g1 = c; b1 = 0;
+  } else if (h < 180) {
+    r1 = 0; g1 = c; b1 = x;
+  } else if (h < 240) {
+    r1 = 0; g1 = x; b1 = c;
+  } else if (h < 300) {
+    r1 = x; g1 = 0; b1 = c;
+  } else {
+    r1 = c; g1 = 0; b1 = x;
+  }
+
+  return {
+    r: Math.round((r1 + m) * 255),
+    g: Math.round((g1 + m) * 255),
+    b: Math.round((b1 + m) * 255),
+  };
+}
+
+export function rgbToCmyk(rgb: RGB): CMYK {
+  const r = rgb.r / 255;
+  const g = rgb.g / 255;
+  const b = rgb.b / 255;
+  const k = 1 - Math.max(r, g, b);
+
+  if (k === 1) {
+    return { c: 0, m: 0, y: 0, k: 100 };
+  }
+
+  return {
+    c: round2(((1 - r - k) / (1 - k)) * 100),
+    m: round2(((1 - g - k) / (1 - k)) * 100),
+    y: round2(((1 - b - k) / (1 - k)) * 100),
+    k: round2(k * 100),
+  };
+}
+
+export function cmykToRgb(cmyk: CMYK): RGB {
+  const c = cmyk.c / 100;
+  const m = cmyk.m / 100;
+  const y = cmyk.y / 100;
+  const k = cmyk.k / 100;
+
+  return {
+    r: Math.round(255 * (1 - c) * (1 - k)),
+    g: Math.round(255 * (1 - m) * (1 - k)),
+    b: Math.round(255 * (1 - y) * (1 - k)),
+  };
+}
+
+function round2(n: number): number {
+  return Math.round(n * 100) / 100;
+}
+
+// --- Auto-detect and parse any color format ---
+
+export function parseColor(input: string): RGB {
+  const trimmed = input.trim();
+
+  if (/^#?[0-9a-fA-F]{3}([0-9a-fA-F]{3})?$/.test(trimmed)) {
+    return parseHex(trimmed);
+  }
+  if (/^rgba?\s*\(/i.test(trimmed)) {
+    return parseRgbString(trimmed);
+  }
+  if (/^hsla?\s*\(/i.test(trimmed)) {
+    return hslToRgb(parseHslString(trimmed));
+  }
+  if (/^hsv\s*\(/i.test(trimmed)) {
+    return hsvToRgb(parseHsvString(trimmed));
+  }
+  if (/^cmyk\s*\(/i.test(trimmed)) {
+    return cmykToRgb(parseCmykString(trimmed));
+  }
+
+  throw new Error(
+    `Cannot parse color: "${input}". Supported formats: HEX (#ff0000), RGB (rgb(255,0,0)), HSL (hsl(0,100%,50%)), HSV (hsv(0,100%,100%)), CMYK (cmyk(0,100,100,0))`
+  );
+}
+
+// --- Public tool function ---
+
+export interface ConvertResult {
+  hex: string;
+  rgb: { r: number; g: number; b: number; css: string };
+  hsl: { h: number; s: number; l: number; css: string };
+  hsv: { h: number; s: number; v: number };
+  cmyk: { c: number; m: number; y: number; k: number };
+}
+
+export function convertColor(input: string): ConvertResult {
+  const rgb = parseColor(input);
+  const hsl = rgbToHsl(rgb);
+  const hsv = rgbToHsv(rgb);
+  const cmyk = rgbToCmyk(rgb);
+  const hex = rgbToHex(rgb);
+
+  return {
+    hex,
+    rgb: { ...rgb, css: `rgb(${rgb.r}, ${rgb.g}, ${rgb.b})` },
+    hsl: { ...hsl, css: `hsl(${hsl.h}, ${hsl.s}%, ${hsl.l}%)` },
+    hsv,
+    cmyk,
+  };
+}