@trishchuk/coolors-mcp 1.0.0

package/docs/getting-started.md

@@ -0,0 +1,366 @@
+# Getting Started
+
+Get up and running with Coolors MCP in minutes. This guide covers installation, basic usage, and your first color operations.
+
+## Quick Start
+
+### 1. Install Coolors MCP
+
+#### For Claude Code
+```bash
+claude mcp add coolors -- npx -y @trishchuk/coolors-mcp
+```
+
+#### For Claude Desktop
+Add to your configuration:
+```json
+{
+  "mcpServers": {
+    "coolors": {
+      "command": "npx",
+      "args": ["-y", "@trishchuk/coolors-mcp"]
+    }
+  }
+}
+```
+
+### 2. Verify Installation
+
+Check that Coolors MCP is available:
+```
+/mcp
+```
+
+You should see `coolors` in the list of available servers.
+
+### 3. Your First Color Operation
+
+Try a simple color conversion:
+```
+Convert #6366f1 to HSL format
+```
+
+Claude will use the `convert_color` tool and return: `hsl(239, 84%, 67%)`
+
+## Basic Color Operations
+
+### Color Conversion
+
+Convert between any supported format:
+
+```javascript
+// Hex to RGB
+"Convert #6366f1 to RGB"
+// Result: rgb(99, 102, 241)
+
+// RGB to HSL
+"Convert rgb(99, 102, 241) to HSL"
+// Result: hsl(239, 84%, 67%)
+
+// HSL to LAB
+"Convert hsl(239, 84%, 67%) to LAB"
+// Result: lab(47.9, 35.2, -65.7)
+
+// Any color to HCT
+"Convert #6366f1 to HCT"
+// Result: hct(265.8, 87.2, 47.9)
+```
+
+### Color Distance
+
+Calculate perceptual difference between colors:
+
+```javascript
+"What's the perceptual distance between #6366f1 and #5355d1?"
+// Uses Delta E 2000 algorithm
+// Result: 5.2 (very similar colors)
+
+"Compare #ff0000 and #00ff00 using Delta E"
+// Result: 86.6 (very different colors)
+```
+
+### Contrast Checking
+
+Verify accessibility compliance:
+
+```javascript
+"Check contrast between #1f2937 and #ffffff"
+// Result: 15.74:1 - Passes AAA for all text sizes
+
+"Is #6366f1 accessible on white background?"
+// Result: 3.03:1 - Passes AA for large text only
+
+"What text color works on #6366f1 background?"
+// Result: #ffffff (white) provides 4.6:1 contrast
+```
+
+## Creating Color Palettes
+
+### Basic Palettes
+
+Generate harmonious color sets:
+
+```javascript
+"Create a monochromatic palette from #6366f1"
+// Result: 5 shades of the same hue
+
+"Generate complementary colors for #6366f1"
+// Result: #6366f1 and its opposite
+
+"Create a triadic color scheme from #6366f1"
+// Result: 3 colors 120° apart
+```
+
+### Material Design Themes
+
+Generate complete Material Design 3 themes:
+
+```javascript
+"Create a Material Design theme from #6366f1"
+// Generates:
+// - Primary, secondary, tertiary palettes
+// - Surface and background colors
+// - Error colors
+// - Light and dark variants
+```
+
+### Custom Gradients
+
+Create smooth color transitions:
+
+```javascript
+"Create a gradient from #6366f1 to #ec4899 with 10 steps"
+// Result: 10 colors smoothly transitioning
+
+"Generate a gradient using LAB interpolation"
+// Result: Perceptually smooth gradient
+```
+
+## CSS Theme Matching
+
+### Finding Theme Variables
+
+Match colors to existing CSS variables:
+
+```javascript
+"Find the closest theme variable for #6365f0 in my CSS"
+// Analyzes your theme CSS and finds best match
+// Result: --color-primary-500 (99% confidence)
+```
+
+### Refactoring CSS
+
+Automatically replace hardcoded colors:
+
+```javascript
+"Refactor this CSS to use theme variables:
+.button {
+  background: #6366f1;
+  border: 1px solid #4f46e5;
+}"
+
+// Result:
+.button {
+  background: var(--color-primary-500);
+  border: 1px solid var(--color-primary-600);
+}
+```
+
+## Working with Images
+
+### Extract Colors
+
+Get dominant colors from images:
+
+```javascript
+"Extract the main colors from this image"
+// Analyzes image and returns:
+// - Top 5 dominant colors
+// - Population percentages
+// - Suitability scores
+```
+
+### Generate Theme from Image
+
+Create a complete theme from an image:
+
+```javascript
+"Create a Material Design theme from this album cover"
+// Extracts colors and generates:
+// - Source color selection
+// - Complete color scheme
+// - Light/dark variants
+```
+
+## Common Workflows
+
+### 1. Building a Color System
+
+Start with a brand color and expand:
+
+```javascript
+// Step 1: Define primary color
+"My brand color is #6366f1"
+
+// Step 2: Generate palette
+"Create a complete color system from this"
+
+// Step 3: Check accessibility
+"Verify all color combinations meet WCAG AA"
+
+// Step 4: Export as CSS
+"Generate CSS custom properties for this theme"
+```
+
+### 2. Migrating to Theme Variables
+
+Convert existing CSS to use variables:
+
+```javascript
+// Step 1: Define your theme
+"Here's my theme CSS: [paste theme]"
+
+// Step 2: Analyze existing styles
+"Find all hardcoded colors in styles.css"
+
+// Step 3: Refactor automatically
+"Replace hardcoded colors with theme variables"
+
+// Step 4: Review changes
+"Show me colors that couldn't be matched"
+```
+
+### 3. Creating Accessible Designs
+
+Ensure your colors meet standards:
+
+```javascript
+// Step 1: Test current colors
+"Check contrast for my primary colors"
+
+// Step 2: Fix issues
+"Adjust colors to meet WCAG AA"
+
+// Step 3: Generate alternatives
+"Create high contrast version of theme"
+
+// Step 4: Validate
+"Verify all combinations are accessible"
+```
+
+## Advanced Features
+
+### Color Harmonization
+
+Make multiple colors work together:
+
+```javascript
+"Harmonize these colors: #6366f1, #ec4899, #10b981"
+// Adjusts colors to be more harmonious while maintaining identity
+```
+
+### Dislike Detection
+
+Avoid universally disliked colors:
+
+```javascript
+"Is #6b7c3a a good color for UI?"
+// Detects "bile zone" colors and suggests alternatives
+```
+
+### Batch Processing
+
+Process multiple colors efficiently:
+
+```javascript
+"Match all these colors to my theme: [list of colors]"
+// Processes all colors and returns best matches
+```
+
+## Tips and Tricks
+
+### Performance
+
+- **Resize images** before extraction (300px width is usually enough)
+- **Cache theme variables** when doing multiple matches
+- **Use batch operations** when processing multiple colors
+
+### Accuracy
+
+- **Use HCT** for perceptual operations
+- **Use LAB** for color matching
+- **Use RGB/Hex** for final output
+
+### Accessibility
+
+- **Always check contrast** for text/background pairs
+- **Provide high contrast options** for users who need them
+- **Don't rely on color alone** to convey information
+
+## Next Steps
+
+### Learn More
+
+- [Color Spaces](concepts/color-spaces.md) - Understand different color models
+- [HCT System](concepts/hct.md) - Google's perceptual color space
+- [Material Design](concepts/material-design.md) - Complete theming system
+- [Accessibility](concepts/accessibility.md) - WCAG compliance
+
+### Explore Tools
+
+- [Color Operations](tools/color-operations.md) - All conversion tools
+- [Material Design Tools](tools/material-design.md) - Theme generation
+- [Theme Matching](tools/theme-matching.md) - CSS refactoring
+- [Image Extraction](tools/image-extraction.md) - Working with images
+
+### See Examples
+
+- [Basic Colors](examples/basic-colors.md) - Simple operations
+- [Creating Themes](examples/creating-themes.md) - Theme generation
+- [CSS Refactoring](examples/css-refactoring.md) - Modernizing CSS
+- [Image Extraction](examples/image-extraction.md) - Image-based themes
+
+## Getting Help
+
+### Common Issues
+
+#### "Tool not found"
+Make sure Coolors MCP is properly installed and Claude has been restarted.
+
+#### "Invalid color format"
+Check that your color is in a supported format: hex (#RRGGBB), rgb(), hsl(), etc.
+
+#### "No theme matches found"
+Lower the confidence threshold or add more theme variables.
+
+### Support
+
+- **GitHub Issues**: [Report bugs](https://github.com/x51xxx/coolors-mcp/issues)
+- **Documentation**: [Full docs](https://x51xxx.github.io/coolors-mcp/)
+- **Examples**: [Code samples](examples/basic-colors.md)
+
+## Quick Reference
+
+### Supported Color Formats
+- **Hex**: `#RRGGBB` or `#RGB`
+- **RGB**: `rgb(r, g, b)` or `{r, g, b}`
+- **HSL**: `hsl(h, s%, l%)` or `{h, s, l}`
+- **LAB**: `lab(l, a, b)` or `{l, a, b}`
+- **HCT**: `hct(h, c, t)` or `{h, c, t}`
+
+### Common Tools
+- `convert_color` - Format conversion
+- `color_distance` - Perceptual difference
+- `check_contrast` - WCAG compliance
+- `generate_palette` - Color schemes
+- `generate_material_theme` - Material Design
+- `match_theme_color` - Find CSS variables
+- `refactor_css_with_theme` - Update CSS
+- `extract_image_colors` - Image analysis
+
+### Contrast Requirements
+- **Normal text**: 4.5:1 (AA), 7:1 (AAA)
+- **Large text**: 3:1 (AA), 4.5:1 (AAA)
+- **UI elements**: 3:1 (AA)
+
+Ready to start? Try your first color operation above!

package/docs/index.md

@@ -0,0 +1,190 @@
+---
+layout: home
+
+hero:
+  name: "Coolors MCP"
+  text: "Advanced Color Operations for MCP"
+  tagline: "Professional color utilities with Material Design 3 support, CSS theme matching, image extraction, and accessibility compliance — <span style='color: #FFFFFF; background-color: #6366F1; padding: 2px 8px; border-radius: 6px; font-size: 14px; font-weight: 600; margin-left: 4px; display: inline-block; vertical-align: middle;'>built for Claude Code</span>"
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /getting-started
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/x51xxx/coolors-mcp
+
+features:
+  - icon: 🎨
+    title: Multi-Format Color Conversion
+    details: |
+      Convert between hex, RGB, HSL, LAB, and Google's HCT color spaces with perfect accuracy
+  - icon: 🎭
+    title: Material Design 3 Themes
+    details: Generate complete Material Design color systems from any source color
+  - icon: 🔍
+    title: Smart CSS Theme Matching
+    details: |
+      <span style="color: #3b82f6;">Automatically match colors to CSS variables</span><br>
+      <span style="color: #10b981;">with perceptual accuracy and semantic understanding</span>
+  - icon: 🖼️
+    title: Image Color Extraction
+    details: Extract dominant colors from images using Google's Celebi quantization algorithm
+  - icon: ♿
+    title: WCAG Accessibility
+    details: Check contrast ratios and ensure your color choices meet accessibility standards
+  - icon: 🚀
+    title: HCT Color Space
+    details: Use Google's perceptually uniform color space for superior UI color operations
+---
+
+<div class="explore-hint" style="text-align: center; margin: 32px 0 48px; position: relative;">
+  <div class="explore-dots" style="display: inline-flex; align-items: center; gap: 4px;">
+    <span class="dot" style="font-size: 11px; letter-spacing: 0.5px; color: var(--vp-c-text-3); opacity: 0.8; transition: all 0.3s ease;">•</span>
+    <span class="dot" style="font-size: 11px; letter-spacing: 0.5px; color: var(--vp-c-text-3); opacity: 0.8; transition: all 0.3s ease; transition-delay: 0.1s;">•</span>
+    <span class="dot" style="font-size: 11px; letter-spacing: 0.5px; color: var(--vp-c-text-3); opacity: 0.8; transition: all 0.3s ease; transition-delay: 0.2s;">•</span>
+  </div>
+  <p class="explore-text" style="font-size: 13px; color: var(--vp-c-text-3); margin-top: 8px; opacity: 0.7; transition: all 0.3s ease;">
+    Professional color tools for modern development
+  </p>
+</div>
+
+<div style="margin-top: 48px;">
+
+## What is Coolors MCP?
+
+</div>
+
+Coolors MCP is a Model Context Protocol (MCP) server that provides advanced color operations and utilities to AI assistants like Claude. It integrates Google's Material Color Utilities algorithms with sophisticated CSS theme matching capabilities, enabling AI-powered color workflows that were previously impossible.
+
+### Key Features
+
+- **🎨 Complete Color Toolkit**: Convert between any color format, calculate perceptual distances, and generate harmonious palettes
+- **🎭 Material Design Integration**: Generate full Material Design 3 themes with tonal palettes and semantic roles
+- **🔄 CSS Theme Refactoring**: Automatically replace hardcoded colors with theme variables in your CSS
+- **📊 HCT Color Space**: Use Google's perceptually uniform color space for accurate color operations
+- **🖼️ Image Analysis**: Extract dominant colors and generate themes from images
+- **♿ Accessibility First**: Built-in WCAG contrast checking and accessibility compliance
+- **🎯 Smart Matching**: Multi-factor algorithm considers perceptual distance, semantic context, and accessibility
+
+### Why HCT Over LAB?
+
+HCT (Hue, Chroma, Tone) is Google's color space specifically designed for UI applications:
+
+- **Tone Component**: Directly correlates with contrast ratios (40 tone = 3:1, 50 tone = 4.5:1)
+- **Perceptual Uniformity**: Better than LAB for UI color operations
+- **Material Design Native**: Used in production by Android and Material Design
+- **Semantic Understanding**: Better mapping between color relationships and UI roles
+
+<div style="margin-top: 48px;">
+
+## Quick Start
+
+</div>
+
+### For Claude Code Users
+
+```bash
+# One-command installation
+claude mcp add coolors -- npx -y @trishchuk/coolors-mcp
+
+# Verify installation
+/mcp
+```
+
+### For Claude Desktop Users
+
+Add to your configuration file:
+
+```json
+{
+  "mcpServers": {
+    "coolors": {
+      "command": "npx",
+      "args": ["-y", "@trishchuk/coolors-mcp"]
+    }
+  }
+}
+```
+
+### Example Usage
+
+Once installed, you can use natural language to work with colors:
+
+```
+// Color conversion
+"convert #6366F1 to HSL and LAB formats"
+
+// Generate Material theme
+"create a Material Design 3 theme from #6366F1"
+
+// CSS refactoring
+"match all hardcoded colors in my CSS to theme variables"
+
+// Image analysis
+"extract the dominant colors from this image and create a theme"
+
+// Accessibility checking
+"check the contrast between #6366F1 and white"
+```
+
+<div style="margin-top: 48px;">
+
+## Core Capabilities
+
+</div>
+
+### Color Operations
+- Convert between hex, RGB, HSL, LAB, and HCT formats
+- Calculate perceptual distance using Delta E 2000
+- Generate color palettes (monochromatic, analogous, complementary, etc.)
+- Create smooth gradients with multiple interpolation methods
+
+### Material Design
+- Generate complete Material Design 3 themes
+- Create tonal palettes with standard Material tones
+- Harmonize multiple colors to work together
+- Fix universally disliked colors (dark yellow-greens)
+
+### CSS Theme Matching
+- Find closest theme variables for any color
+- Automatically refactor CSS with theme variables
+- Batch process multiple colors at once
+- Confidence scoring for replacements
+
+### Image Processing
+- Extract dominant colors using Celebi quantization
+- Generate themes from image colors
+- Score colors for UI suitability
+- Detect and fix disliked colors
+
+<div style="margin-top: 48px;">
+
+## Documentation
+
+</div>
+
+- [Getting Started](/getting-started) - Installation and setup guide
+- [Tools Reference](/tools/README) - Complete tool documentation
+- [Color Spaces](/concepts/color-spaces) - Understanding different color models
+- [HCT System](/concepts/hct) - Google's perceptually uniform color space
+- [Material Design](/concepts/material-design) - Material Design 3 integration
+
+<div style="margin-top: 48px;">
+
+## Community & Support
+
+</div>
+
+- **GitHub**: [x51xxx/coolors-mcp](https://github.com/x51xxx/coolors-mcp)
+- **Issues**: [Report bugs or request features](https://github.com/x51xxx/coolors-mcp/issues)
+- **NPM**: [@trishchuk/coolors-mcp](https://www.npmjs.com/package/@trishchuk/coolors-mcp)
+
+<div style="margin-top: 48px;">
+
+## License
+
+</div>
+
+This project is licensed under the MIT License. See the [LICENSE](https://github.com/x51xxx/coolors-mcp/blob/main/LICENSE) file for details.
+
+**Built with** ❤️ **using Google's Material Color Utilities algorithms**

package/docs/installation.md

@@ -0,0 +1,157 @@
+# Installation
+
+Multiple ways to install the Coolors MCP server, depending on your needs.
+
+## Prerequisites
+
+- Node.js v18.0.0 or higher
+- Claude Desktop or Claude Code with MCP support
+
+## Method 1: NPX (Recommended)
+
+No installation needed - runs directly:
+
+### Claude Desktop Configuration
+```json
+{
+  "mcpServers": {
+    "coolors": {
+      "command": "npx",
+      "args": ["-y", "@trishchuk/coolors-mcp"]
+    }
+  }
+}
+```
+
+### Claude Code Configuration
+```bash
+claude mcp add coolors --npm-package @trishchuk/coolors-mcp
+```
+
+## Method 2: Global Installation
+
+### Install globally
+```bash
+npm install -g @trishchuk/coolors-mcp
+```
+
+### Claude Desktop Configuration
+```json
+{
+  "mcpServers": {
+    "coolors": {
+      "command": "coolors-mcp"
+    }
+  }
+}
+```
+
+### Claude Code Configuration
+```bash
+claude mcp add coolors --command coolors-mcp
+```
+
+## Method 3: Local Development
+
+For development or local testing:
+
+```bash
+# Clone the repository
+git clone https://github.com/x51xxx/coolors-mcp.git
+cd coolors-mcp
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Test locally
+node dist/bin/server.js
+```
+
+### Claude Desktop Configuration (Local)
+```json
+{
+  "mcpServers": {
+    "coolors-dev": {
+      "command": "node",
+      "args": ["/path/to/coolors-mcp/dist/bin/server.js"]
+    }
+  }
+}
+```
+
+## Verification
+
+Test your installation with a simple color conversion:
+
+```json
+{
+  "name": "convert_color",
+  "arguments": {
+    "color": "#6366F1",
+    "to": "hsl"
+  }
+}
+```
+
+Expected response: `"hsl(239, 84%, 67%)"`
+
+## Available Tools
+
+Once installed, you'll have access to these tools:
+
+### Color Operations
+- `convert_color` - Convert between color formats
+- `color_distance` - Calculate perceptual distance
+- `check_contrast` - WCAG contrast checking
+- `generate_palette` - Create color palettes
+- `generate_gradient` - Create smooth gradients
+
+### Material Design
+- `generate_material_theme` - Full Material Design 3 theme
+- `harmonize_colors` - Harmonize multiple colors
+- `generate_tonal_palette` - Material tonal palette
+- `analyze_color_likability` - Check for disliked colors
+
+### CSS Theme Matching
+- `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 Processing
+- `extract_image_colors` - Extract dominant colors
+- `generate_theme_from_image` - Create theme from image
+
+## Troubleshooting
+
+Common issues:
+- **Node.js version**: Ensure you have Node.js ≥18.0.0 (`node --version`)
+- **Permission errors**: Try running with appropriate permissions
+- **MCP connection issues**: Restart your Claude client after configuration changes
+- **Module not found**: Ensure npm packages are properly installed
+
+For more help, see the [FAQ](resources/faq) or [Troubleshooting Guide](resources/troubleshooting).
+
+## Support
+
+Need help with installation or setup? Here's how to get assistance:
+
+### 🤝 Get Help
+- **GitHub Issues**: [Report bugs or request features](https://github.com/x51xxx/coolors-mcp/issues)
+- **GitHub Discussions**: [Ask questions and share ideas](https://github.com/x51xxx/coolors-mcp/discussions)
+- **Email**: [taras@trishchuk.com](mailto:taras@trishchuk.com) for direct support
+
+### 📖 Documentation
+- **[Getting Started Guide](getting-started)** - Complete setup and configuration
+- **[Tools Reference](tools/README)** - Detailed tool documentation
+- **[Examples](examples/basic-colors)** - Practical usage patterns
+
+### 🚀 Contributing
+Interested in contributing? Check out our [Contributing Guide](https://github.com/x51xxx/coolors-mcp/blob/main/CONTRIBUTING.md) or reach out directly!
+
+---
+
+**Developed by [Taras Trishchuk](https://github.com/x51xxx)** | Licensed under MIT