@trishchuk/coolors-mcp 1.0.1 → 1.1.0

package/examples/theme-matching.md

@@ -1,113 +0,0 @@
-# Theme Color Matching Examples
-
-## Generate Theme CSS from Source Color
-
-Generate a complete Material Design 3 theme with CSS variables:
-
-```bash
-# Using the MCP tool
-generate_theme_css --sourceColor "#6750a4"
-```
-
-This generates:
-
-- Primary, secondary, tertiary palettes (tones 0-100)
-- Error, neutral, and neutral variant palettes
-- Semantic color mappings for light theme
-
-## Match Legacy Colors to Theme Variables
-
-Find the closest theme variable for a legacy color:
-
-```bash
-# Match a single color
-match_theme_color --color "#6850a0" --themeCSS ":root { --color-primary-40: #6750a4; }"
-
-# Result:
-# Variable: --color-primary-40
-# Confidence: 95%
-# Distance: 2.3
-```
-
-## Refactor CSS with Theme Variables
-
-Automatically replace hardcoded colors with theme variables:
-
-### Input CSS:
-
-```css
-.button {
-  background-color: #6750a4;
-  color: #fffbfe;
-  border: 1px solid #79747e;
-}
-```
-
-### Theme CSS:
-
-```css
-:root {
-  --color-primary-40: #6750a4;
-  --color-surface-99: #fffbfe;
-  --color-outline-50: #79747e;
-}
-```
-
-### Refactored Output:
-
-```css
-.button {
-  background-color: var(--color-primary-40);
-  color: var(--color-surface-99);
-  border: 1px solid var(--color-outline-50);
-}
-```
-
-## Context-Aware Matching
-
-The matcher considers usage context for better results:
-
-- **text**: Prefers high-contrast colors
-- **background**: Prefers surface colors
-- **border**: Prefers outline colors
-- **shadow**: Prefers shadow colors
-- **accent**: Prefers primary/secondary colors
-
-## Batch Color Matching
-
-Match multiple colors at once:
-
-```bash
-match_theme_colors_batch --colors ["#6750a4", "#ba1a1a", "#ffffff"] --themeCSS "..."
-
-# Result:
-# #6750a4 → --color-primary-40 (100%)
-# #ba1a1a → --color-error-40 (100%)
-# #ffffff → --color-surface-100 (100%)
-```
-
-## Key Features
-
-### HCT Color Space
-
-- Uses Google's HCT (Hue, Chroma, Tone) for perceptually uniform color matching
-- Better than LAB for UI applications
-- Tone differences guarantee specific contrast ratios
-
-### Multi-Factor Scoring
-
-- **Perceptual Distance (60%)**: How visually similar the colors are
-- **Semantic Context (20%)**: Whether the color role matches the usage
-- **Accessibility (20%)**: Contrast ratio considerations
-
-### Accessibility Validation
-
-- Automatic WCAG contrast checking
-- Warns about potential accessibility issues
-- Suggests alternatives when contrast is insufficient
-
-### Material Design Integration
-
-- Generates Material Design 3 compliant themes
-- Supports all Material color roles
-- Includes tonal palettes with standard Material tones

package/mcp-config.json

@@ -1,8 +0,0 @@
-{
-  "mcpServers": {
-    "coolors-mcp": {
-      "command": "node",
-      "args": ["/Users/taras/www/MCP/coolors-mcp/dist/bin/server.js"]
-    }
-  }
-}

package/note.md

@@ -1,34 +0,0 @@
-    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/research_results.md

@@ -1,53 +0,0 @@
-# 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/tools/colors.ts

@@ -1,31 +0,0 @@
-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/registry.ts

@@ -1,142 +0,0 @@
-import { Prompt, Tool } from "@modelcontextprotocol/sdk/types.js"; // Each tool definition includes its metadata, schema, prompt, and execution logic in one place.
-import { ZodError, ZodTypeAny } from "zod";
-import { zodToJsonSchema } from "zod-to-json-schema";
-
-export interface UnifiedTool {
-  category?: "codex" | "simple" | "utility";
-  description: string;
-  execute: (
-    args: Record<string, unknown>,
-    onProgress?: (newOutput: string) => void,
-  ) => Promise<string>;
-
-  name: string;
-
-  prompt?: {
-    arguments?: Array<{
-      description: string;
-      name: string;
-      required: boolean;
-    }>;
-    description: string;
-  };
-  zodSchema: ZodTypeAny;
-}
-
-export const toolRegistry: UnifiedTool[] = [];
-
-export async function executeTool(
-  toolName: string,
-  args: Record<string, unknown>,
-  onProgress?: (newOutput: string) => void,
-): Promise<string> {
-  const tool = toolRegistry.find((t) => t.name === toolName);
-  if (!tool) {
-    throw new Error(`Unknown tool: ${toolName}`);
-  }
-  try {
-    const validatedArgs = tool.zodSchema.parse(args);
-    return tool.execute(validatedArgs, onProgress);
-  } catch (error) {
-    if (error instanceof ZodError) {
-      const issues = error.issues
-        .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
-        .join(", ");
-      throw new Error(`Invalid arguments for ${toolName}: ${issues}`);
-    }
-    throw error;
-  }
-}
-
-export function getPromptDefinitions(): Prompt[] {
-  // Helper to get MCP Prompt definitions from registry
-  return toolRegistry
-    .filter((tool) => tool.prompt)
-    .map((tool) => ({
-      arguments:
-        tool.prompt!.arguments || extractPromptArguments(tool.zodSchema),
-      description: tool.prompt!.description,
-      name: tool.name,
-    }));
-}
-
-export function getPromptMessage(
-  toolName: string,
-  args: Record<string, unknown>,
-): string {
-  const tool = toolRegistry.find((t) => t.name === toolName);
-  if (!tool?.prompt) {
-    throw new Error(`No prompt defined for tool: ${toolName}`);
-  }
-  const paramStrings: string[] = [];
-
-  if (args.prompt) {
-    paramStrings.push(args.prompt as string);
-  }
-
-  Object.entries(args).forEach(([key, value]) => {
-    if (
-      key !== "prompt" &&
-      value !== undefined &&
-      value !== null &&
-      value !== false
-    ) {
-      if (typeof value === "boolean" && value) {
-        paramStrings.push(`[${key}]`);
-      } else if (typeof value !== "boolean") {
-        paramStrings.push(`(${key}: ${value})`);
-      }
-    }
-  });
-
-  return `Use the ${toolName} tool${paramStrings.length > 0 ? ": " + paramStrings.join(" ") : ""}`;
-}
-
-export function getToolDefinitions(): Tool[] {
-  // get Tool definitions from registry
-  return toolRegistry.map((tool) => {
-    const raw = zodToJsonSchema(tool.zodSchema, tool.name) as {
-      definitions?: Record<string, unknown>;
-      properties?: Record<string, unknown>;
-      required?: string[];
-    };
-    const def = (raw.definitions?.[tool.name] ?? raw) as {
-      properties?: Record<string, unknown>;
-      required?: string[];
-    };
-    const inputSchema: Tool["inputSchema"] = {
-      properties: def.properties || {},
-      required: def.required || [],
-      type: "object",
-    };
-
-    return {
-      description: tool.description,
-      inputSchema,
-      name: tool.name,
-    };
-  });
-}
-
-export function toolExists(toolName: string): boolean {
-  return toolRegistry.some((t) => t.name === toolName);
-}
-
-function extractPromptArguments(zodSchema: ZodTypeAny): Array<{
-  description: string;
-  name: string;
-  required: boolean;
-}> {
-  const jsonSchema = zodToJsonSchema(zodSchema) as {
-    properties?: Record<string, { description?: string }>;
-    required?: string[];
-  };
-  const properties = jsonSchema.properties || {};
-  const required = jsonSchema.required || [];
-
-  return Object.entries(properties).map(([name, prop]) => ({
-    description: prop.description || `${name} parameter`,
-    name,
-    required: required.includes(name),
-  }));
-}

package/src/tools/simple-tools.ts

@@ -1,37 +0,0 @@
-import { z } from "zod";
-
-import { UnifiedTool } from "./registry.js";
-
-const pingArgsSchema = z.object({
-  prompt: z.string().default("").describe("Message to echo "),
-});
-
-export const pingTool: UnifiedTool = {
-  category: "simple",
-  description: "Echo",
-  execute: async (args) => {
-    const message = args.prompt || args.message || "Pong!";
-    // Return message directly to avoid cross-platform issues with echo command
-    return message as string;
-  },
-  name: "ping",
-  prompt: {
-    description: "Echo test message with structured response.",
-  },
-  zodSchema: pingArgsSchema,
-};
-
-const helpArgsSchema = z.object({});
-
-export const helpTool: UnifiedTool = {
-  category: "simple",
-  description: "receive help information",
-  execute: async () => {
-    return "Help information for Coolors MCP:\n\nAvailable tools for color manipulation, theme generation, and CSS refactoring.\nSee documentation for details.";
-  },
-  name: "Help",
-  prompt: {
-    description: "receive help information",
-  },
-  zodSchema: helpArgsSchema,
-};