@rog0x/mcp-color-tools 1.0.0

package/README.md

@@ -0,0 +1,96 @@
+# mcp-color-tools
+
+MCP server providing color manipulation and design tools for AI agents.
+
+## Tools
+
+### color_convert
+
+Convert a color between HEX, RGB, HSL, HSV, and CMYK. Accepts any format as input and returns all formats.
+
+```json
+{ "color": "#ff6b35" }
+{ "color": "rgb(255, 107, 53)" }
+{ "color": "hsl(16, 100%, 60%)" }
+{ "color": "hsv(16, 79%, 100%)" }
+{ "color": "cmyk(0, 58, 79, 0)" }
+```
+
+### palette_generate
+
+Generate a color palette from a base color.
+
+**Types:** complementary, analogous, triadic, split-complementary, monochromatic
+
+```json
+{ "color": "#ff6b35", "type": "triadic" }
+```
+
+### contrast_check
+
+Check WCAG contrast ratio between two colors. Reports AA/AAA compliance for normal text, large text, and UI components.
+
+```json
+{ "color1": "#ffffff", "color2": "#333333" }
+```
+
+### color_mix
+
+Mix, blend, lighten, darken, saturate, or desaturate colors.
+
+```json
+{ "operation": "mix", "colors": ["#ff0000", "#0000ff"], "weights": [2, 1] }
+{ "operation": "blend", "colors": ["#ff0000", "#0000ff"], "ratio": 0.3 }
+{ "operation": "lighten", "colors": ["#ff6b35"], "amount": 20 }
+{ "operation": "darken", "colors": ["#ff6b35"], "amount": 15 }
+{ "operation": "saturate", "colors": ["#888888"], "amount": 30 }
+{ "operation": "desaturate", "colors": ["#ff6b35"], "amount": 25 }
+```
+
+### css_gradient
+
+Generate CSS gradient code with direction, stops, and browser prefixes.
+
+```json
+{
+  "type": "linear",
+  "colors": ["#ff6b35", "#ffd700", "#00bcd4"],
+  "direction": "135deg"
+}
+```
+
+```json
+{
+  "type": "radial",
+  "colors": [
+    { "color": "#ff6b35", "position": 0 },
+    { "color": "#ffd700", "position": 50 },
+    { "color": "#00bcd4", "position": 100 }
+  ],
+  "direction": "circle at center"
+}
+```
+
+## Setup
+
+```bash
+npm install
+npm run build
+```
+
+## Claude Desktop Configuration
+
+```json
+{
+  "mcpServers": {
+    "color-tools": {
+      "command": "node",
+      "args": ["path/to/mcp-color-tools/dist/index.js"]
+    }
+  }
+}
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const color_converter_js_1 = require("./tools/color-converter.js");
+const palette_generator_js_1 = require("./tools/palette-generator.js");
+const contrast_checker_js_1 = require("./tools/contrast-checker.js");
+const color_mixer_js_1 = require("./tools/color-mixer.js");
+const css_gradient_js_1 = require("./tools/css-gradient.js");
+const server = new index_js_1.Server({
+    name: "mcp-color-tools",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// List available tools
+server.setRequestHandler(types_js_1.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",
+                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",
+                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",
+                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",
+                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",
+                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(types_js_1.CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case "color_convert": {
+                const result = (0, color_converter_js_1.convertColor)(args?.color);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case "palette_generate": {
+                const result = (0, palette_generator_js_1.generatePalette)(args?.color, args?.type);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case "contrast_check": {
+                const result = (0, contrast_checker_js_1.checkContrast)(args?.color1, args?.color2);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case "color_mix": {
+                const result = (0, color_mixer_js_1.colorMix)({
+                    operation: args?.operation,
+                    colors: args?.colors,
+                    weights: args?.weights,
+                    ratio: args?.ratio,
+                    amount: args?.amount,
+                });
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case "css_gradient": {
+                const result = (0, css_gradient_js_1.generateGradient)({
+                    type: args?.type,
+                    colors: args?.colors,
+                    direction: args?.direction,
+                    includePrefix: args?.includePrefix,
+                });
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        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 stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error("MCP Color Tools server running on stdio");
+}
+main().catch(console.error);

package/dist/tools/color-converter.d.ts

@@ -0,0 +1,56 @@
+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;
+}
+export declare function rgbToHex(rgb: RGB): string;
+export declare function rgbToHsl(rgb: RGB): HSL;
+export declare function hslToRgb(hsl: HSL): RGB;
+export declare function rgbToHsv(rgb: RGB): HSV;
+export declare function hsvToRgb(hsv: HSV): RGB;
+export declare function rgbToCmyk(rgb: RGB): CMYK;
+export declare function cmykToRgb(cmyk: CMYK): RGB;
+export declare function parseColor(input: string): RGB;
+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 declare function convertColor(input: string): ConvertResult;

package/dist/tools/color-converter.js

@@ -0,0 +1,269 @@
+"use strict";
+// Color Converter — convert between HEX, RGB, HSL, HSV, and CMYK formats.
+// All color math is implemented manually without external libraries.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rgbToHex = rgbToHex;
+exports.rgbToHsl = rgbToHsl;
+exports.hslToRgb = hslToRgb;
+exports.rgbToHsv = rgbToHsv;
+exports.hsvToRgb = hsvToRgb;
+exports.rgbToCmyk = rgbToCmyk;
+exports.cmykToRgb = cmykToRgb;
+exports.parseColor = parseColor;
+exports.convertColor = convertColor;
+// --- Parsing ---
+function parseHex(hex) {
+    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) {
+    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) {
+    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) {
+    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) {
+    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, min, max) {
+    return Math.max(min, Math.min(max, val));
+}
+// --- Conversion core ---
+function rgbToHex(rgb) {
+    const toHex = (n) => clamp(Math.round(n), 0, 255).toString(16).padStart(2, "0");
+    return `#${toHex(rgb.r)}${toHex(rgb.g)}${toHex(rgb.b)}`;
+}
+function rgbToHsl(rgb) {
+    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),
+    };
+}
+function hslToRgb(hsl) {
+    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, q, t) => {
+        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),
+    };
+}
+function rgbToHsv(rgb) {
+    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),
+    };
+}
+function hsvToRgb(hsv) {
+    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),
+    };
+}
+function rgbToCmyk(rgb) {
+    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),
+    };
+}
+function cmykToRgb(cmyk) {
+    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) {
+    return Math.round(n * 100) / 100;
+}
+// --- Auto-detect and parse any color format ---
+function parseColor(input) {
+    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))`);
+}
+function convertColor(input) {
+    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,
+    };
+}

package/dist/tools/color-mixer.d.ts

@@ -0,0 +1,22 @@
+import { type RGB, type HSL } from "./color-converter.js";
+interface MixedColor {
+    hex: string;
+    rgb: RGB;
+    hsl: HSL;
+}
+export declare function mixColors(colors: string[], weights?: number[]): MixedColor;
+export declare function blendColors(color1: string, color2: string, ratio?: number): MixedColor;
+export declare function lightenColor(color: string, amount?: number): MixedColor;
+export declare function darkenColor(color: string, amount?: number): MixedColor;
+export declare function saturateColor(color: string, amount?: number): MixedColor;
+export declare function desaturateColor(color: string, amount?: number): MixedColor;
+export type MixOperation = "mix" | "blend" | "lighten" | "darken" | "saturate" | "desaturate";
+export interface MixRequest {
+    operation: MixOperation;
+    colors: string[];
+    weights?: number[];
+    ratio?: number;
+    amount?: number;
+}
+export declare function colorMix(req: MixRequest): MixedColor;
+export {};