@trishchuk/coolors-mcp 1.0.0

package/note.md

@@ -0,0 +1,35 @@
+    Phase 1: Core Infrastructure
+
+    - Integrate Material Color Utilities HCT system into existing codebase
+    - Build theme variable parser for CSS custom properties
+    - Implement HCT-based color distance calculations
+
+    Phase 2: Matching Engine
+
+    - Create efficient color lookup using spatial indexing (k-d tree)
+    - Implement multi-factor scoring algorithm (perceptual + semantic +
+    accessibility)
+    - Add context-aware matching for different UI elements
+
+    Phase 3: CSS Refactoring
+
+    - Build CSS parser to extract legacy colors
+    - Generate refactored CSS with theme variable replacements
+    - Include confidence scores and alternative suggestions
+
+    Phase 4: MCP Integration
+
+    - Add new MCP tools: match_theme_color, refactor_css_colors,
+    analyze_theme_quality
+    - Extend existing tools to support HCT color space
+
+    This approach leverages Material Color Utilities for sophisticated color
+    science while integrating with your existing infrastructure for maximum utility
+     in UI development.
+
+---
+
+[material-color-utilities](researcher/material-color-utilities)
+
+
+https://github.com/material-foundation/material-color-utilities#readme

package/package.json

@@ -0,0 +1,122 @@
+{
+  "name": "@trishchuk/coolors-mcp",
+  "version": "1.0.0",
+  "main": "dist/CoolorsMCP.js",
+  "scripts": {
+    "build": "tsup",
+    "lint": "prettier --check . && eslint . && tsc --noEmit",
+    "test": "vitest run",
+    "format": "prettier --write . && eslint --fix .",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  },
+  "bin": {
+    "coolors-mcp": "dist/bin/server.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "color",
+    "colors",
+    "material-design",
+    "theme",
+    "css",
+    "hct",
+    "lab",
+    "rgb",
+    "hsl",
+    "palette",
+    "gradient",
+    "wcag",
+    "accessibility",
+    "contrast",
+    "image-extraction"
+  ],
+  "type": "module",
+  "author": "Taras Trishchuk <x51xxx@gmail.com>",
+  "license": "MIT",
+  "description": "Advanced color operations MCP server with Material Design 3 support, CSS theme matching, image color extraction, and accessibility compliance. Features HCT color space for perceptually accurate operations.",
+  "module": "dist/coolors-mcp.js",
+  "types": "dist/coolors-mcp.d.ts",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.2",
+    "@standard-schema/spec": "^1.0.0",
+    "culori": "^4.0.2",
+    "execa": "^9.6.0",
+    "file-type": "^21.0.0",
+    "fuse.js": "^7.1.0",
+    "mcp-proxy": "^5.5.4",
+    "strict-event-emitter-types": "^2.0.0",
+    "undici": "^7.13.0",
+    "uri-templates": "^0.2.0",
+    "xsschema": "0.3.5",
+    "yargs": "^18.0.0",
+    "zod": "^3.25.76",
+    "zod-to-json-schema": "^3.24.6"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/x51xxx/coolors-mcp"
+  },
+  "homepage": "https://github.com/x51xxx/coolors-mcp",
+  "bugs": {
+    "url": "https://github.com/x51xxx/coolors-mcp/issues"
+  },
+  "release": {
+    "branches": [
+      "main"
+    ],
+    "plugins": [
+      "@semantic-release/commit-analyzer",
+      "@semantic-release/release-notes-generator",
+      "@semantic-release/npm",
+      "@semantic-release/github",
+      "@sebbo2002/semantic-release-jsr"
+    ]
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.33.0",
+    "@modelcontextprotocol/inspector": "^0.16.2",
+    "@sebbo2002/semantic-release-jsr": "^3.0.1",
+    "@tsconfig/node22": "^22.0.2",
+    "@types/node": "^24.2.1",
+    "@types/uri-templates": "^0.1.34",
+    "@types/yargs": "^17.0.33",
+    "@valibot/to-json-schema": "^1.3.0",
+    "@wong2/mcp-cli": "^1.13.0",
+    "arktype": "^2.1.20",
+    "eslint": "^9.33.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-perfectionist": "^4.15.0",
+    "eslint-plugin-prettier": "^5.5.4",
+    "eventsource-client": "^1.1.4",
+    "get-port-please": "^3.2.0",
+    "jiti": "^2.5.1",
+    "jsr": "^0.13.5",
+    "prettier": "^3.6.2",
+    "semantic-release": "^24.2.7",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.39.0",
+    "valibot": "^1.1.0",
+    "vitepress": "^1.6.4",
+    "vitepress-plugin-mermaid": "^2.0.17",
+    "vitest": "^3.2.4"
+  },
+  "tsup": {
+    "entry": [
+      "src/coolors-mcp.ts",
+      "src/bin/coolors-mcp.ts",
+      "src/bin/server.ts",
+      "src/color/index.ts"
+    ],
+    "format": [
+      "esm"
+    ],
+    "dts": true,
+    "splitting": true,
+    "sourcemap": true,
+    "clean": true
+  }
+}

package/research_results.md

@@ -0,0 +1,53 @@
+# Research Results
+
+## chromaticity-color-utilities
+
+Based on the search results, "chromaticity-color-utilities" seems to be a general term for libraries that provide color science calculations. There are many libraries available for different languages.
+
+For JavaScript/Node.js, some popular libraries are:
+
+- **Culori**: A comprehensive color library that supports a wide range of color spaces and difference calculations.
+- **Color.js**: A library for color conversion and manipulation.
+- **Chroma.js**: A small library for color conversions and scales.
+
+For Python, some popular libraries are:
+
+- **Colour**: A powerful color science library with a wide range of features.
+- **ColorPy**: A library for color calculations and visualization.
+- **ColorAide**: A modern color library with a focus on ease of use.
+
+The user should specify the programming language and the specific functionality they need to get a more specific recommendation.
+
+## encodable
+
+"Encodable" is a general term in software engineering that refers to the ability of data or an object to be converted into a specific format for storage, transmission, or processing.
+
+Common types of encoding include:
+
+- **Data Serialization**: Converting data structures or object states into a format that can be stored or transmitted and reconstructed later (e.g., JSON, XML, Protocol Buffers).
+- **Character Encoding**: Representing text characters in a digital format (e.g., UTF-8, ASCII).
+- **Binary-to-Text Encoding**: Converting binary data into a text-based format (e.g., Base64, Hexadecimal).
+- **URL Encoding**: Converting characters in a URL into a format that can be safely transmitted.
+
+The user should provide more context on what they mean by "encodable" to get a more specific answer.
+
+## material-color-utilities
+
+"Material Color Utilities" (MCU) is a set of color libraries developed by Material Design. It provides algorithms and utilities for generating dynamic color themes and schemes, particularly for Material You.
+
+MCU is available for various programming languages, including:
+
+- **TypeScript** (via npm): `@material/material-color-utilities`
+- **Dart** (via Pub.dev): `material_color_utilities`
+- **Rust**: `material-color-utilities`
+
+The core concepts of MCU include:
+
+- **Dynamic Color**: Generating a color palette from a single seed color, often extracted from a user's wallpaper.
+- **Tonal Palettes**: A set of 13 tones for each color in the palette, which provides a range of shades for different UI elements.
+
+MCU can be used to:
+
+- Create personalized color themes for applications.
+- Ensure color harmony and accessibility in UIs.
+- Implement Material You features in an application.

package/src/bin/coolors-mcp.ts

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+
+import { execa } from "execa";
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+
+await yargs(hideBin(process.argv))
+  .scriptName("coolors-mcp")
+  .command(
+    "dev <file>",
+    "Start a development server",
+    (yargs) => {
+      return yargs
+        .positional("file", {
+          demandOption: true,
+          describe: "The path to the server file",
+          type: "string",
+        })
+
+        .option("watch", {
+          alias: "w",
+          default: false,
+          describe: "Watch for file changes and restart server",
+          type: "boolean",
+        })
+
+        .option("verbose", {
+          alias: "v",
+          default: false,
+          describe: "Enable verbose logging",
+          type: "boolean",
+        });
+    },
+
+    async (argv) => {
+      try {
+        const command = argv.watch
+          ? `npx @wong2/mcp-cli npx tsx --watch ${argv.file}`
+          : `npx @wong2/mcp-cli npx tsx ${argv.file}`;
+
+        if (argv.verbose) {
+          console.log(`[CoolorsMCP] Starting server: ${command}`);
+          console.log(`[CoolorsMCP] File: ${argv.file}`);
+          console.log(
+            `[CoolorsMCP] Watch mode: ${argv.watch ? "enabled" : "disabled"}`,
+          );
+        }
+
+        const { stdout } = await execa({
+          shell: true,
+          stderr: "inherit",
+          stdin: "inherit",
+        })`${command}`;
+
+        console.log(stdout);
+      } catch (error) {
+        console.error(
+          "[CoolorsMCP Error] Failed to start development server:",
+          error instanceof Error ? error.message : String(error),
+        );
+
+        if (argv.verbose && error instanceof Error && error.stack) {
+          console.error("[CoolorsMCP Debug] Stack trace:", error.stack);
+        }
+
+        process.exit(1);
+      }
+    },
+  )
+
+  .command(
+    "inspect <file>",
+    "Inspect a server file",
+    (yargs) => {
+      return yargs.positional("file", {
+        demandOption: true,
+        describe: "The path to the server file",
+        type: "string",
+      });
+    },
+
+    async (argv) => {
+      try {
+        await execa({
+          stderr: "inherit",
+          stdout: "inherit",
+        })`npx @modelcontextprotocol/inspector npx tsx ${argv.file}`;
+      } catch (error) {
+        console.error(
+          "[CoolorsMCP Error] Failed to inspect server:",
+          error instanceof Error ? error.message : String(error),
+        );
+
+        process.exit(1);
+      }
+    },
+  )
+
+  .command(
+    "validate <file>",
+    "Validate a CoolorsMCP server file for syntax and basic structure",
+    (yargs) => {
+      return yargs
+        .positional("file", {
+          demandOption: true,
+          describe: "The path to the server file",
+          type: "string",
+        })
+
+        .option("strict", {
+          alias: "s",
+          default: false,
+          describe: "Enable strict validation (type checking)",
+          type: "boolean",
+        });
+    },
+
+    async (argv) => {
+      try {
+        const { existsSync } = await import("fs");
+        const { resolve } = await import("path");
+        const filePath = resolve(argv.file);
+
+        if (!existsSync(filePath)) {
+          console.error(`[CoolorsMCP Error] File not found: ${filePath}`);
+          process.exit(1);
+        }
+
+        console.log(`[CoolorsMCP] Validating server file: ${filePath}`);
+
+        const command = argv.strict
+          ? `npx tsc --noEmit --strict ${filePath}`
+          : `npx tsc --noEmit ${filePath}`;
+
+        try {
+          await execa({
+            shell: true,
+            stderr: "pipe",
+            stdout: "pipe",
+          })`${command}`;
+
+          console.log("[CoolorsMCP] ✓ TypeScript compilation successful");
+        } catch (tsError) {
+          console.error("[CoolorsMCP] ✗ TypeScript compilation failed");
+
+          if (tsError instanceof Error && "stderr" in tsError) {
+            console.error(tsError.stderr);
+          }
+
+          process.exit(1);
+        }
+
+        try {
+          await execa({
+            shell: true,
+            stderr: "pipe",
+            stdout: "pipe",
+          })`node -e "
+            (async () => {
+              try {
+                const { CoolorsMCP } = await import('coolors-mcp');
+                await import('file://${filePath}');
+                console.log('[CoolorsMCP] ✓ Server structure validation passed');
+              } catch (error) {
+                console.error('[CoolorsMCP] ✗ Server structure validation failed:', error.message);
+                process.exit(1);
+              }
+            })();
+          "`;
+        } catch {
+          console.error("[CoolorsMCP] ✗ Server structure validation failed");
+          console.error(
+            "Make sure the file properly imports and uses CoolorsMCP",
+          );
+
+          process.exit(1);
+        }
+
+        console.log(
+          "[CoolorsMCP] ✓ All validations passed! Server file looks good.",
+        );
+      } catch (error) {
+        console.error(
+          "[CoolorsMCP Error] Validation failed:",
+          error instanceof Error ? error.message : String(error),
+        );
+
+        process.exit(1);
+      }
+    },
+  )
+
+  .help()
+  .parseAsync();

package/src/bin/server.ts

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+
+/**
+ * Coolors MCP Server - Advanced Color Operations & Theme Intelligence
+ *
+ * A comprehensive Model Context Protocol server providing:
+ * - Color space conversions (RGB, HSL, HSV, LAB, XYZ, HCT)
+ * - Material Design 3 theme generation with tonal palettes
+ * - Intelligent CSS theme matching with multi-factor scoring
+ * - Image color extraction using Celebi quantization
+ * - WCAG accessibility compliance checking
+ * - Universal color preference analysis (dislike detection)
+ * - Context-aware color selection for UI components
+ *
+ * Built on Google's HCT color space for perceptually uniform operations
+ * and Material Color Utilities algorithms for professional-grade results.
+ */
+
+import { CoolorsMcp } from "../coolors-mcp.js";
+import * as tools from "../tools/index.js";
+
+// Create the MCP server
+const server = new CoolorsMcp({
+  instructions:
+    "Advanced color operations server with Material Design 3 support, CSS theme matching, image extraction, and accessibility compliance. Uses HCT color space for perceptually accurate operations.",
+  name: "coolors-mcp",
+  version: "1.0.0",
+});
+
+// Core color operations: conversion, distance metrics, accessibility
+server.addTool(tools.colorConversionTool);
+server.addTool(tools.colorDistanceTool);
+server.addTool(tools.contrastCheckerTool);
+server.addTool(tools.paletteGeneratorTool);
+server.addTool(tools.paletteWithLocksTool);
+server.addTool(tools.gradientGeneratorTool);
+
+// Material Design 3: theme generation, harmonization, tonal palettes
+server.addTool(tools.generateMaterialThemeTool);
+server.addTool(tools.harmonizeColorsTool);
+server.addTool(tools.generateTonalPaletteTool);
+
+// CSS theme intelligence: matching, refactoring, migration
+server.addTool(tools.matchThemeColorTool);
+server.addTool(tools.refactorCssWithThemeTool);
+server.addTool(tools.matchThemeColorsBatchTool);
+server.addTool(tools.generateThemeCssTool);
+
+// Image analysis: color extraction, theme generation from photos
+server.addTool(tools.extractImageColorsTool);
+server.addTool(tools.generateThemeFromImageTool);
+
+// Color psychology: detect and fix universally disliked colors
+server.addTool(tools.analyzeColorLikabilityTool);
+server.addTool(tools.fixDislikedColorsBatchTool);
+
+// Start the server
+server.start().catch((error) => {
+  console.error("Failed to start server:", error);
+  process.exit(1);
+});

package/src/color/__tests__/conversions-argb.test.ts

@@ -0,0 +1,198 @@
+/**
+ * Tests for ARGB conversion functions
+ */
+
+import { describe, expect, it } from "vitest";
+
+import { argbToRgb, rgbToArgb } from "../conversions.js";
+
+describe("ARGB Conversions", () => {
+  describe("rgbToArgb", () => {
+    it("should convert RGB to ARGB with full opacity", () => {
+      const argb = rgbToArgb({ b: 64, g: 128, r: 255 });
+
+      // Check alpha channel (should be 0xff)
+      expect((argb >> 24) & 0xff).toBe(0xff);
+
+      // Check RGB channels
+      expect((argb >> 16) & 0xff).toBe(255); // Red
+      expect((argb >> 8) & 0xff).toBe(128); // Green
+      expect(argb & 0xff).toBe(64); // Blue
+    });
+
+    it("should handle primary colors", () => {
+      const red = rgbToArgb({ b: 0, g: 0, r: 255 });
+      const green = rgbToArgb({ b: 0, g: 255, r: 0 });
+      const blue = rgbToArgb({ b: 255, g: 0, r: 0 });
+
+      // Use >>> 0 to convert expected values to unsigned
+      expect(red).toBe(0xffff0000 >>> 0);
+      expect(green).toBe(0xff00ff00 >>> 0);
+      expect(blue).toBe(0xff0000ff >>> 0);
+    });
+
+    it("should handle black and white", () => {
+      const black = rgbToArgb({ b: 0, g: 0, r: 0 });
+      const white = rgbToArgb({ b: 255, g: 255, r: 255 });
+
+      expect(black).toBe(0xff000000 >>> 0);
+      expect(white).toBe(0xffffffff >>> 0);
+    });
+
+    it("should clamp values above 255", () => {
+      const argb = rgbToArgb({ b: 1000, g: 256, r: 300 });
+
+      expect((argb >> 16) & 0xff).toBe(255); // Red clamped
+      expect((argb >> 8) & 0xff).toBe(255); // Green clamped
+      expect(argb & 0xff).toBe(255); // Blue clamped
+    });
+
+    it("should clamp negative values to 0", () => {
+      const argb = rgbToArgb({ b: -1, g: -100, r: -10 });
+
+      expect((argb >> 16) & 0xff).toBe(0); // Red clamped
+      expect((argb >> 8) & 0xff).toBe(0); // Green clamped
+      expect(argb & 0xff).toBe(0); // Blue clamped
+    });
+
+    it("should round floating point values", () => {
+      const argb = rgbToArgb({ b: 127.5, g: 127.3, r: 127.7 });
+
+      expect((argb >> 16) & 0xff).toBe(128); // Rounded up
+      expect((argb >> 8) & 0xff).toBe(127); // Rounded down
+      expect(argb & 0xff).toBe(128); // Rounded up (0.5 rounds up)
+    });
+
+    it("should produce correct 32-bit integer", () => {
+      const argb = rgbToArgb({ b: 0x56, g: 0x34, r: 0x12 });
+
+      expect(argb).toBe(0xff123456 >>> 0);
+      expect(argb.toString(16)).toBe("ff123456");
+    });
+  });
+
+  describe("argbToRgb", () => {
+    it("should convert ARGB back to RGB", () => {
+      const argb = 0xff804020; // Alpha: 255, R: 128, G: 64, B: 32
+      const rgb = argbToRgb(argb);
+
+      expect(rgb.r).toBe(128);
+      expect(rgb.g).toBe(64);
+      expect(rgb.b).toBe(32);
+    });
+
+    it("should ignore alpha channel", () => {
+      const argbFullAlpha = 0xff123456;
+      const argbNoAlpha = 0x00123456;
+
+      const rgb1 = argbToRgb(argbFullAlpha);
+      const rgb2 = argbToRgb(argbNoAlpha);
+
+      // RGB values should be the same regardless of alpha
+      expect(rgb1).toEqual(rgb2);
+      expect(rgb1.r).toBe(0x12);
+      expect(rgb1.g).toBe(0x34);
+      expect(rgb1.b).toBe(0x56);
+    });
+
+    it("should handle primary colors", () => {
+      const red = argbToRgb(0xffff0000);
+      const green = argbToRgb(0xff00ff00);
+      const blue = argbToRgb(0xff0000ff);
+
+      expect(red).toEqual({ b: 0, g: 0, r: 255 });
+      expect(green).toEqual({ b: 0, g: 255, r: 0 });
+      expect(blue).toEqual({ b: 255, g: 0, r: 0 });
+    });
+
+    it("should handle black and white", () => {
+      const black = argbToRgb(0xff000000);
+      const white = argbToRgb(0xffffffff);
+
+      expect(black).toEqual({ b: 0, g: 0, r: 0 });
+      expect(white).toEqual({ b: 255, g: 255, r: 255 });
+    });
+
+    it("should handle grayscale values", () => {
+      const gray = argbToRgb(0xff808080);
+
+      expect(gray).toEqual({ b: 128, g: 128, r: 128 });
+    });
+  });
+
+  describe("round-trip conversion", () => {
+    it("should maintain values through round-trip", () => {
+      const originalRgb = { b: 67, g: 45, r: 123 };
+      const argb = rgbToArgb(originalRgb);
+      const resultRgb = argbToRgb(argb);
+
+      expect(resultRgb).toEqual(originalRgb);
+    });
+
+    it("should handle all possible byte values", () => {
+      // Test a sampling of values
+      for (let i = 0; i < 256; i += 17) {
+        const originalRgb = { b: (i + 170) % 256, g: (i + 85) % 256, r: i };
+        const argb = rgbToArgb(originalRgb);
+        const resultRgb = argbToRgb(argb);
+
+        expect(resultRgb).toEqual(originalRgb);
+      }
+    });
+
+    it("should maintain clamped values", () => {
+      const originalRgb = { b: 127.8, g: -50, r: 300 };
+      const argb = rgbToArgb(originalRgb);
+      const resultRgb = argbToRgb(argb);
+
+      // Values should be clamped and rounded
+      expect(resultRgb).toEqual({ b: 128, g: 0, r: 255 });
+    });
+  });
+
+  describe("edge cases", () => {
+    it("should handle zero values", () => {
+      const argb = rgbToArgb({ b: 0, g: 0, r: 0 });
+      expect(argb).toBe(0xff000000 >>> 0);
+
+      const rgb = argbToRgb(0);
+      expect(rgb).toEqual({ b: 0, g: 0, r: 0 });
+    });
+
+    it("should handle maximum values", () => {
+      const argb = rgbToArgb({ b: 255, g: 255, r: 255 });
+      expect(argb).toBe(0xffffffff >>> 0);
+
+      const rgb = argbToRgb(0xffffffff);
+      expect(rgb).toEqual({ b: 255, g: 255, r: 255 });
+    });
+
+    it("should handle single channel values", () => {
+      const redOnly = rgbToArgb({ b: 0, g: 0, r: 255 });
+      const greenOnly = rgbToArgb({ b: 0, g: 255, r: 0 });
+      const blueOnly = rgbToArgb({ b: 255, g: 0, r: 0 });
+
+      expect(redOnly & 0x00ffffff).toBe(0x00ff0000);
+      expect(greenOnly & 0x00ffffff).toBe(0x0000ff00);
+      expect(blueOnly & 0x00ffffff).toBe(0x000000ff);
+    });
+
+    it("should preserve bit patterns", () => {
+      // Test specific bit patterns
+      const patterns = [
+        0xff000000 >>> 0, // Black
+        0xffffffff >>> 0, // White
+        0xff808080 >>> 0, // Gray
+        0xffaa55aa >>> 0, // Mixed pattern
+        0xff123456 >>> 0, // Sequential
+        0xfffedcba >>> 0, // Reverse sequential
+      ];
+
+      for (const pattern of patterns) {
+        const rgb = argbToRgb(pattern);
+        const result = rgbToArgb(rgb);
+        expect(result).toBe(pattern);
+      }
+    });
+  });
+});