@trishchuk/coolors-mcp 1.0.0 → 1.1.0

package/.claude/settings.local.json

@@ -1,39 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(grep:*)",
-      "Bash(npm test)",
-      "Bash(npm test:*)",
-      "Bash(npm run build:*)",
-      "Bash(node:*)",
-      "Bash(npm run:*)",
-      "mcp__coolors__convert_color",
-      "mcp__coolors__generate_material_theme",
-      "mcp__coolors__generate_palette",
-      "mcp__gemini-cli__ask-gemini",
-      "Bash(open /Users/taras/www/MCP/coolors-mcp/demo/music-player.html)",
-      "Bash(open /Users/taras/www/MCP/coolors-mcp/demo/podcast-player.html)",
-      "mcp__coolors__generate_theme_css",
-      "mcp__coolors__refactor_css_with_theme",
-      "Bash(npx vitest run:*)",
-      "WebSearch",
-      "Bash(for i in {1..5})",
-      "Bash(do echo \"Run $i:\")",
-      "Bash(done)",
-      "Bash(npx prettier:*)",
-      "Bash(find:*)",
-      "Bash(npm install:*)",
-      "Bash(npx tsx:*)",
-      "Bash(git pull:*)",
-      "Bash(git config:*)",
-      "Bash(npm:*)"
-    ],
-    "deny": [],
-    "ask": []
-  },
-  "enabledMcpjsonServers": [
-    "gemini-cli",
-    "codex-cli",
-    "coolors"
-  ]
-}

package/.env

@@ -1,2 +0,0 @@
-
-GOOGLE_CLOUD_PROJECT=sincere-signal-457111-q3

package/.mcp.json

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

package/CLAUDE.md

@@ -1,201 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-This is a Coolors MCP (Model Context Protocol) server that provides advanced color utilities, Material Design 3 theme generation, and CSS theme matching capabilities. It's built on a custom TypeScript MCP framework.
-
-## Core Commands
-
-### Development & Testing
-
-```bash
-# Install dependencies
-npm install
-
-# Build the project
-npm run build
-
-# Run all tests
-npm test
-
-# Run a single test file
-npx vitest run src/color/__tests__/conversions.test.ts
-
-# Format code
-npm run format
-
-# Lint and type check
-npm run lint
-```
-
-### Running the MCP Server
-
-```bash
-# Run the built server directly
-node dist/bin/server.js
-
-# Run with TypeScript (development)
-npx tsx src/bin/server.ts
-
-# Test with MCP CLI
-npx fastmcp dev src/bin/server.ts
-
-# Inspect with MCP Inspector
-npx fastmcp inspect src/bin/server.ts
-```
-
-## Architecture & Code Organization
-
-### MCP Server Structure
-
-The project follows a clean separation pattern where tools are extracted into individual files rather than being defined inline:
-
-- **`src/bin/server.ts`** (47 lines) - Clean entry point that registers all tools
-- **`src/tools/`** - Individual tool implementations following a consistent pattern
-- **`src/CoolorsMCP.ts`** - Core MCP server class that manages tools and sessions
-- **`src/session.ts`** - Handles individual client connections and tool execution
-
-### Color System Architecture
-
-#### Multi-Layer Color Space Support
-
-1. **Basic Color Spaces** (`src/color/conversions.ts`):
-   - RGB, HSL, HSV, XYZ, LAB
-   - All conversions go through RGB as the central format
-
-2. **HCT Color Space** (`src/color/hct/`):
-   - Google's perceptually uniform color space (Hue, Chroma, Tone)
-   - Superior for UI applications vs traditional LAB
-   - Tone differences guarantee WCAG contrast ratios (40 = 3:1, 50 = 4.5:1)
-
-3. **Material Design Integration** (`src/color/hct/tonal-palette.ts`):
-   - CorePalette generates primary, secondary, tertiary, error, neutral palettes
-   - Standard Material tones: [0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 95, 99, 100]
-
-4. **Image Color Extraction** (`src/color/quantize/`, `src/color/score/`):
-   - Celebi quantizer combines Wu and WSMeans algorithms
-   - Score module ranks colors by UI suitability
-   - Dislike analyzer prevents selection of universally disliked colors
-
-### Theme Matching System
-
-The theme matching system (`src/theme/`) uses a sophisticated multi-factor approach:
-
-1. **Parser** (`src/theme/parser.ts`): Extracts CSS variables and detects semantic roles
-2. **Matcher** (`src/theme/matcher.ts`): Multi-factor scoring algorithm:
-   - Perceptual distance (60%) - HCT-based color similarity
-   - Semantic context (20%) - Role appropriateness (primary, surface, etc.)
-   - Accessibility (20%) - Contrast ratio considerations
-
-3. **Refactor** (`src/theme/refactor.ts`): Automated CSS refactoring with confidence scores
-
-### Tool Registration Pattern
-
-Tools follow a consistent structure:
-
-```typescript
-export const toolName = {
-  name: "tool_name",
-  description: "Tool description",
-  parameters: z.object({
-    /* schema */
-  }),
-  execute: async (args) => {
-    /* implementation */
-  },
-};
-```
-
-Tools are registered in `src/bin/server.ts`:
-
-```typescript
-server.addTool(tools.toolName);
-```
-
-## Key Technical Decisions
-
-### HCT vs LAB Color Space
-
-The project uses HCT instead of LAB for perceptual color operations because:
-
-- HCT is specifically designed for UI applications
-- Tone component directly correlates with contrast ratios
-- Better semantic understanding of color relationships
-- Used in production by Material Design and Android
-
-### Distance Metrics
-
-- **Delta E 2000**: Default for general color comparison
-- **HCT Distance**: Used for theme matching with weighted components (tone weighted 2x)
-- **Euclidean**: Available for simple RGB comparisons
-
-### Theme Variable Detection
-
-The parser automatically detects semantic roles from CSS variable names:
-
-- `--color-primary-*` → primary role
-- `--color-surface-*` → surface role
-- `--*-border-*` or `--*-outline-*` → outline role
-
-## Testing Approach
-
-Tests are organized by module:
-
-- `src/color/__tests__/` - Color conversion and metric tests
-- `src/theme/__tests__/` - Theme matching and refactoring tests
-
-The `researcher/` directory is excluded from tests (in `.gitignore` and `vitest.config.js`).
-
-## Material Color Utilities Integration
-
-The project incorporates algorithms from Google's Material Color Utilities:
-
-- **Quantization**: Celebi algorithm (Wu + WSMeans) for image color extraction
-- **Scoring**: Evaluating colors for UI suitability (target chroma ~48)
-- **Harmonization**: Adjusting colors to work together
-- **Dynamic Schemes**: Generating accessible color schemes
-- **Dislike Analysis**: Detecting and fixing universally disliked colors (dark yellow-greens)
-
-## MCP Tools Available
-
-### Color Tools
-
-- `convert_color` - Convert between hex, rgb, hsl, lab, hct
-- `color_distance` - Calculate perceptual distance
-- `check_contrast` - WCAG contrast checking
-- `generate_palette` - Create color palettes (monochromatic, analogous, etc.)
-
-### Material Design Tools
-
-- `generate_material_theme` - Full Material Design 3 theme
-- `harmonize_colors` - Harmonize multiple colors
-- `generate_tonal_palette` - Material tonal palette
-
-### Theme Matching Tools
-
-- `match_theme_color` - Find closest theme variable
-- `refactor_css_with_theme` - Automated CSS refactoring
-- `match_theme_colors_batch` - Batch color matching
-- `generate_theme_css` - Generate CSS custom properties
-
-### Image Extraction Tools
-
-- `extract_image_colors` - Extract dominant colors from images using Celebi quantization
-- `generate_theme_from_image` - Generate Material Design theme from image colors
-
-### Dislike Analysis Tools
-
-- `analyze_color_likability` - Check if colors are universally disliked (bile zone)
-- `fix_disliked_colors_batch` - Fix multiple disliked colors automatically
-
-## Ukrainian Language Context
-
-The user often communicates in Ukrainian. Key terms encountered:
-
-- "кольори" = colors
-- "ядро" = core
-- "утиліти" = utilities
-- "перетворення" = conversion
-- "змінні" = variables

package/DOCUMENTATION.md

@@ -1,274 +0,0 @@
-# Документація Coolors MCP
-
-## Вступ
-
-Coolors MCP — це потужний інструмент командного рядка (CLI), призначений для розробників і дизайнерів, що надає широкий
-спектр функціональних можливостей для роботи з кольорами, створення тем і рефакторингу CSS. Проект побудований на
-TypeScript і використовує Model Context Protocol (MCP) для інтеграції з іншими інструментами розробки та AI-агентами.
-
-Основні можливості включають:
-
-- **Операції з кольорами**: Конвертація, обчислення відстані, перевірка контрастності.
-- **Генерація тем**: Створення тем Material Design 3, тональних палітр і гармонізація кольорів.
-- **Тематизація на основі зображень**: Видобування кольорів із зображень для створення динамічних тем.
-- **Рефакторинг CSS**: Автоматизація процесу переходу від жорстко закодованих значень кольорів до змінних теми.
-- **Аналіз кольорів**: Інструменти для виявлення та виправлення психологічно непривабливих кольорів.
-
-Ця документація описує доступні інструменти, їхні параметри та сфери застосування.
-
-## Інструменти для роботи з кольорами
-
-Ці інструменти надають базові функції для маніпулювання та конвертації кольорів.
-
-### `convert_color`
-
-Конвертує колір між різними форматами.
-
-- **Опис**: Цей інструмент дозволяє перетворювати кольори з одного формату в інший.
-- **Параметри**:
-  - `color` (string): Колір для конвертації (може бути в форматі hex, rgb або hsl).
-  - `to` (enum): Цільовий формат. Можливі значення: `"hex"`, `"rgb"`, `"hsl"`, `"lab"`, `"hct"`.
-- **Сфери застосування**:
-  - Швидка конвертація кольорів для використання в CSS, графічних редакторах або інших інструментах.
-  - Перетворення кольорів для відповідності вимогам різних бібліотек або API.
-- **Приклад**:
-  ```bash
-  coolors-mcp convert_color --color "#ff0000" --to "rgb"
-  # Output: rgb(255, 0, 0)
-  ```
-
-### `color_distance`
-
-Обчислює перцептивну відстань між двома кольорами.
-
-- **Опис**: Використовує алгоритм Delta E 2000 для точного визначення візуальної різниці між кольорами, що корисно для
-  оцінки схожості відтінків.
-- **Параметри**:
-  - `color1` (string): Перший колір.
-  - `color2` (string): Другий колір.
-  - `metric` (enum, optional): Метрика для обчислення відстані. За замовчуванням `"deltaE2000"`.
-- **Сфери застосування**:
-  - Оцінка того, наскільки схожими є два кольори для користувача.
-  - Визначення, чи можна замінити один колір іншим без суттєвої візуальної різниці.
-  - Групування схожих кольорів у палітрі.
-- **Приклад**:
-  ```bash
-  coolors-mcp color_distance --color1 "#ff0000" --color2 "#fe0000"
-  # Output: Distance between #ff0000 and #fe0000: 0.26
-  ```
-
-### `check_contrast`
-
-Перевіряє коефіцієнт контрастності WCAG між двома кольорами.
-
-- **Опис**: Допомагає забезпечити доступність веб-контенту, перевіряючи, чи відповідає контрастність між текстом і фоном
-  стандартам WCAG AA та AAA.
-- **Параметри**:
-  - `foreground` (string): Колір тексту.
-  - `background` (string): Колір фону.
-- **Сфери застосування**:
-  - Перевірка доступності веб-сайтів та додатків.
-  - Автоматизація тестування дизайну на відповідність стандартам WCAG.
-- **Приклад**:
-  ```bash
-  coolors-mcp check_contrast --foreground "#ffffff" --background "#000000"
-  # Output:
-  # Contrast Ratio: 21.00:1
-  # WCAG AA: ✓ Pass (normal text)
-  # WCAG AA: ✓ Pass (large text)
-  # WCAG AAA: ✓ Pass (normal text)
-  # WCAG AAA: ✓ Pass (large text)
-  ```
-
-### `palette_generator`
-
-Генерує колірні палітри на основі базового кольору.
-
-- **Опис**: Створює гармонійні колірні схеми, такі як монохроматичні, аналогічні, комплементарні та інші.
-- **Параметри**:
-  - `baseColor` (string): Базовий колір для генерації палітри.
-  - `type` (enum, optional): Тип палітри. Можливі значення: `"monochromatic"`, `"analogous"`, `"complementary"`,
-    `"triadic"`, `"tetradic"`. За замовчуванням `"monochromatic"`.
-  - `count` (number, optional): Кількість кольорів у палітрі. За замовчуванням `5`.
-- **Сфери застосування**:
-  - Швидке створення колірних схем для дизайну.
-  - Пошук натхнення для нових палітр.
-  - Генерація варіацій кольорів для UI-елементів.
-- **Приклад**:
-  ```bash
-  coolors-mcp palette_generator --baseColor "#3498db" --type "analogous"
-  # Output:
-  # Generated analogous palette:
-  # 1. #34d8db
-  # 2. #34b8db
-  # 3. #3498db
-  # 4. #3478db
-  # 5. #3458db
-  ```
-
-## Інструменти для аналізу кольорів
-
-Ці інструменти допомагають аналізувати та виправляти кольори з точки зору їхнього сприйняття.
-
-### `analyze_color_likability`
-
-Аналізує, чи є колір універсально непривабливим.
-
-- **Опис**: Виявляє темно-жовто-зелені відтінки, які асоціюються з біологічними відходами, і пропонує виправлену версію.
-- **Параметри**:
-  - `color` (string): Колір для аналізу.
-  - `autoFix` (boolean, optional): Автоматично повертати виправлену версію, якщо колір непривабливий. За замовчуванням
-    `true`.
-- **Сфери застосування**:
-  - Уникнення використання кольорів, які можуть викликати негативні асоціації у користувачів.
-  - Покращення естетики дизайну шляхом автоматичної корекції "проблемних" кольорів.
-- **Приклад**:
-  ```bash
-  coolors-mcp analyze_color_likability --color "#5a6e00"
-  ```
-
-### `fix_disliked_colors_batch`
-
-Аналізує та виправляє кілька непривабливих кольорів одночасно.
-
-- **Опис**: Дозволяє пакетно обробляти список кольорів, автоматично виправляючи ті, що є універсально непривабливими.
-- **Параметри**:
-  - `colors` (array): Масив кольорів для аналізу.
-  - `includeAnalysis` (boolean, optional): Включати детальний аналіз для кожного кольору. За замовчуванням `false`.
-- **Сфери застосування**:
-  - Перевірка та виправлення всієї палітри проекту.
-  - Забезпечення того, що жоден із кольорів у дизайн-системі не є непривабливим.
-- **Приклад**:
-  ```bash
-  coolors-mcp fix_disliked_colors_batch --colors '["#5a6e00", "#00ff00"]'
-  ```
-
-## Інструменти для роботи з темами Material Design
-
-Ці інструменти призначені для створення та керування колірними темами за принципами Material Design 3.
-
-### `generate_material_theme`
-
-Генерує повну колірну тему Material Design 3 з вихідного кольору.
-
-- **Опис**: Створює світлу та темну версії теми, включаючи всі ключові кольори (primary, secondary, tertiary, error,
-  background, surface тощо).
-- **Параметри**:
-  - `sourceColor` (string): Вихідний колір для генерації теми.
-  - `includeCustomColors` (boolean, optional): Включати палітри користувацьких кольорів. За замовчуванням `false`.
-- **Сфери застосування**:
-  - Швидке створення повноцінної теми для веб-сайту або додатка.
-  - Забезпечення узгодженості кольорів у всьому інтерфейсі.
-- **Приклад**:
-  ```bash
-  coolors-mcp generate_material_theme --sourceColor "#6750a4"
-  ```
-
-### `harmonize_colors`
-
-Гармонізує кольори для кращої сумісності за допомогою алгоритмів Material Design.
-
-- **Опис**: Допомагає кольорам краще поєднуватися один з одним, що корисно при комбінуванні кольорів з різних джерел.
-- **Параметри**:
-  - `colors` (array): Масив кольорів для гармонізації.
-  - `method` (enum, optional): Метод гармонізації. Можливі значення: `"blend"`, `"harmonize"`, `"temperature"`. За
-    замовчуванням `"harmonize"`.
-  - `factor` (number, optional): Сила гармонізації (0-1). За замовчуванням `0.5`.
-- **Сфери застосування**:
-  - Покращення візуальної гармонії між різними елементами інтерфейсу.
-  - Адаптація існуючої палітри до принципів Material Design.
-
-### `generate_tonal_palette`
-
-Генерує тональну палітру Material Design з кольору.
-
-- **Опис**: Створює набір відтінків одного кольору з різною світлотою, що є основою для створення динамічних тем у
-  Material Design 3.
-- **Параметри**:
-  - `color` (string): Базовий колір для палітри.
-  - `tones` (array, optional): Масив значень тонів для генерації (за замовчуванням стандартні тони Material Design).
-- **Сфери застосування**:
-  - Створення узгоджених відтінків для станів елементів (hover, focus, disabled).
-  - Розробка гнучких колірних систем.
-
-## Інструменти для видобування кольорів із зображень
-
-Ці інструменти дозволяють створювати колірні схеми на основі вмісту зображень.
-
-### `extract_image_colors`
-
-Видобуває домінуючі кольори із зображення.
-
-- **Опис**: Аналізує зображення та повертає палітру найбільш значущих кольорів.
-- **Параметри**:
-  - `imageData` (object): Дані зображення з RGBA-значеннями.
-  - `maxColors` (number, optional): Максимальна кількість кольорів для видобування. За замовчуванням `5`.
-  - `quality` (enum, optional): Якість видобування: `"low"`, `"medium"`, `"high"`. За замовчуванням `"medium"`.
-- **Сфери застосування**:
-  - Створення динамічних тем, що адаптуються до контенту.
-  - Генерація палітр на основі фотографій або ілюстрацій.
-
-### `generate_theme_from_image`
-
-Генерує повну тему Material Design 3 із зображення.
-
-- **Опис**: Автоматично створює узгоджену колірну тему на основі домінуючих кольорів зображення.
-- **Параметри**:
-  - `imageData` (object): Дані зображення з RGBA-значеннями.
-  - `isDark` (boolean, optional): Генерувати темну тему. За замовчуванням `false`.
-- **Сфери застосування**:
-  - Створення персоналізованих інтерфейсів, що відповідають шпалерам користувача або іншим зображенням.
-  - Швидка розробка тем для мультимедійних додатків.
-
-## Інструменти для зіставлення з темою
-
-Ці інструменти допомагають інтегрувати існуючий CSS з дизайн-системою на основі змінних.
-
-### `match_theme_color`
-
-Знаходить найближчу відповідну змінну теми для заданого кольору.
-
-- **Опис**: Допомагає замінити жорстко закодовані кольори на семантичні змінні з теми.
-- **Параметри**:
-  - `color` (string): Колір для зіставлення.
-  - `themeCSS` (string): CSS, що містить змінні теми.
-  - `context` (enum, optional): Контекст використання для кращого зіставлення.
-- **Сфери застосування**:
-  - Рефакторинг CSS та міграція на дизайн-систему.
-  - Забезпечення узгодженості кольорів у великих проектах.
-
-### `refactor_css_with_theme`
-
-Рефакторить CSS для використання змінних теми замість жорстко закодованих кольорів.
-
-- **Опис**: Автоматично аналізує CSS, знаходить жорстко закодовані кольори, зіставляє їх зі змінними теми та замінює їх.
-- **Параметри**:
-  - `css` (string): Вміст CSS для рефакторингу.
-  - `themeCSS` (string): CSS, що містить змінні теми.
-  - `minConfidence` (number, optional): Мінімальна впевненість для заміни.
-- **Сфери застосування**:
-  - Масштабний рефакторинг застарілого CSS.
-  - Прискорення впровадження дизайн-системи.
-
-### `match_theme_colors_batch`
-
-Знаходить відповідності в темі для кількох кольорів одночасно.
-
-- **Опис**: Дозволяє пакетно обробляти список кольорів для зіставлення зі змінними теми.
-- **Параметри**:
-  - `colors` (array): Масив кольорів для зіставлення.
-  - `themeCSS` (string): CSS, що містить змінні теми.
-- **Сфери застосування**:
-  - Аналіз палітри існуючого проекту перед рефакторингом.
-
-### `generate_theme_css`
-
-Генерує CSS-змінні для повної теми з вихідного кольору.
-
-- **Опис**: Створює готовий до використання CSS-файл з усіма тональними палітрами та семантичними зіставленнями.
-- **Параметри**:
-  - `sourceColor` (string): Вихідний колір для генерації теми.
-  - `prefix` (string, optional): Префікс для CSS-змінних.
-- **Сфери застосування**:
-  - Швидке створення CSS-файлу теми для нового проекту.
-  - Генерація основи для кастомізації дизайн-системи.

package/GEMINI.md

@@ -1,54 +0,0 @@
-# Аналіз проекту `coolors-mcp`
-
-## Огляд
-
-Цей проект є інструментом командного рядка (CLI) або сервером, створеним за допомогою TypeScript, який надає розширений
-набір інструментів для роботи з кольорами та темами. Він значною мірою базується на принципах Material Design 3 і
-використовує `@modelcontextprotocol/sdk` для надання своїх функціональних можливостей через набір інструментів.
-
-## Основна функціональність
-
-Проект пропонує комплексний набір інструментів для керування кольорами, зокрема:
-
-- **Операції з кольорами:**
-  - Перетворення між різними колірними моделями (HEX, RGB, HSL, LAB, HCT).
-  - Обчислення перцептивної різниці кольорів (Delta E 2000).
-  - Забезпечення доступності за допомогою перевірки контрастності WCAG.
-  - Психологічна корекція кольору (виправлення "непривабливих" кольорів).
-- **Тематизація на основі зображень:**
-  - Видобування домінуючих кольорів із зображення.
-  - Автоматичне створення повної теми Material Design 3 на основі видобутих кольорів.
-- **Тематизація в стилі Material Design:**
-  - Генерація колірних тем Material Design 3.
-  - Створення тональних палітр.
-  - Гармонізація кольорів на основі принципів Material Design.
-- **Рефакторинг CSS:**
-  - Аналіз існуючого CSS.
-  - Зіставлення жорстко закодованих кольорів із темою.
-  - Рефакторинг CSS для використання змінних теми.
-- **Генерація палітри:**
-  - Створення різних типів колірних палітр (монохроматичних, аналогічних, комплементарних тощо) з базового кольору.
-
-## Структура проекту
-
-- `CoolorsMCP.ts`: Основна точка входу, що налаштовує сервер за допомогою `@modelcontextprotocol/sdk`.
-- `session.ts`: Керує сеансами клієнтів і викликами інструментів.
-- `tools/`: Містить усі визначення інструментів, які є основними функціями, що надаються сервером.
-- `color/`: Ймовірно, містить базову логіку маніпулювання кольорами, що використовується інструментами.
-- `theme/`: Ймовірно, містить логіку для розбору, зіставлення та рефакторингу тем.
-- `bin/`: Містить виконувані сценарії для запуску сервера або CLI.
-- `examples/`: Містить приклади використання інструментів.
-
-## Ключові залежності
-
-- `@modelcontextprotocol/sdk`: Використовується для створення сервера та обробки протоколу інструментів.
-- `zod`: Використовується для перевірки вхідних даних в інструментах.
-- `@standard-schema/spec`: Використовується для визначення параметрів інструментів.
-- `xsschema`: Використовується для перетворення схем Zod на схеми JSON.
-
-## Загальне враження
-
-Цей проект є складним інструментом для розробників і дизайнерів, які працюють із кольорами та системами дизайну. Він
-автоматизує багато виснажливих завдань, пов'язаних із керуванням кольорами та створенням тем, а функція рефакторингу CSS
-є особливо вражаючою. Використання Model Context Protocol свідчить про те, що він призначений для інтеграції з іншими
-інструментами розробки або агентами ШІ.