# Deterministic Color Engine MCP

> Deterministic Color Engine provides precise color math for frontend development. It forces your AI client to calculate exact color codes—HEX, RGB, and HSL—eliminating guesswork when manipulating brand colors or generating palettes. You get mathematically perfect adjustments for UI hover states and design systems.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** color-palette, ui-ux, css-variables, design-automation, color-math

## Description

When building a modern interface, you can't rely on an agent guessing color values. If your prompt asks to 'darken this blue by 20%', any standard LLM will just make up a Hex code; it won't calculate the actual mathematical shift. This MCP fixes that. It forces deterministic math so you get reliable results every time. You can convert colors instantly between HEX, RGB, and HSL formats. Need a hover state? Use the engine to safely lighten or darken any base color by exact percentages. Or, generate full palettes—like complementary or analogous schemes—directly from a single seed color. The result is predictable, production-ready code that works across all platforms. When you connect this through Vinkius, your AI client gains an essential math layer for design work.

## Tools

### convert_color
Takes one CSS color code and outputs its corresponding values in HEX, RGB, and HSL formats.

### generate_color_palette
Creates a mathematically harmonious set of colors by calculating either complementary or analogous shades from a seed color.

### manipulate_luminance
Changes the brightness (lightness) of an existing color code using positive percentages to lighten or negative percentages to darken it.

## Prompt Examples

**Prompt:** 
```
Convert the brand color #4CAF50 to RGB and HSL formats.
```

**Response:** 
```
Using the convert_color tool: RGB is rgb(76, 175, 80) and HSL is hsl(122, 39%, 49%).
```

**Prompt:** 
```
I need a hover state for my button. Darken the color #3B82F6 by 15%.
```

**Response:** 
```
Using the manipulate_luminance tool (percent=-15): The darkened hover color is #1d4ed8.
```

**Prompt:** 
```
Generate a complementary color palette based on this primary brand hex: #F59E0B.
```

**Response:** 
```
Using the generate_color_palette tool (type='complementary'): The palette is ['#f59e0b', '#0b62f5'].
```

## Capabilities

### Convert Color Formats
The engine converts any CSS color input (HEX, RGB, or HSL) into all three mathematically valid formats.

### Adjust Tone/Luminance
You can safely adjust a base brand color's brightness by passing a percentage to either lighten or darken the tone.

### Generate Color Schemes
The MCP generates mathematically defined palettes, specifically complementary (180° shift) or analogous (30° shift), from one primary color.

## Use Cases

### Creating a Dark Mode Theme
A developer needs the primary brand color to appear deep and rich in dark mode, but also needs it to be slightly more visible than usual. They use `manipulate_luminance` with a negative percentage to darken the base code by exactly 15%, ensuring optimal contrast against a black background.

### Building a Brand Identity Guide
A design lead needs to prove that their new primary brand color works well with an accent color. They feed the main hex value into `generate_color_palette` and select 'complementary' to instantly get the mathematically perfect contrasting shade for the guide.

### Cross-Platform Code Conversion
A developer is working on a legacy component that uses RGB values, but the new framework requires HSL. They use `convert_color` once to transform the code and satisfy both technical requirements without manual lookups.

## Benefits

- Guaranteed Code Accuracy: Stop worrying about color codes hallucinating. The `convert_color` tool ensures that no matter which format you start with, the output is always correct across HEX, RGB, and HSL.
- Perfect Hover States: Need a button to darken on hover? Use `manipulate_luminance`. You simply pass a negative percentage and get the exact resulting Hex code for perfect contrast control.
- Systematic Palette Creation: Building a design system requires harmony. The `generate_color_palette` tool calculates mathematically sound complementary or analogous schemes, saving hours of manual color wheel work.
- Fast Color Auditing: When reviewing an existing brand palette, you can use the engine to quickly audit and convert all colors, ensuring consistency across different codebases.
- Reduced Dependency Risk: Because this MCP uses pure math, it runs instantly without needing external packages or complex setup. It’s just raw calculation.

## How It Works

The bottom line is that you get reliable, verifiable color codes every time, regardless of how complex the mathematical adjustment needs to be.

1. You provide the engine with a base color and specify what you need: perhaps converting its format, adjusting its brightness by percentage, or generating a palette type.
2. The MCP executes raw mathematical calculations against your request; it does not guess values or use approximations.
3. Your AI client receives back the precise, calculated code (e.g., `#1d4ed8` for HEX, and `rgb(29, 78, 216)` for RGB).

## Frequently Asked Questions

**How does `convert_color` work?**
It converts any provided CSS color code into all three major formats: HEX, RGB, and HSL. This is necessary when a specific framework demands one format but you only have another.

**Can I use `manipulate_luminance` to adjust colors?**
Yes. You provide the tool with an existing color code and then specify your desired adjustment percentage (positive for lighter, negative for darker). The output is a new, calculated color.

**Is `generate_color_palette` better than standard CSS?**
Yes. It’s superior because it uses mathematical principles, like the 180-degree complementary shift, guaranteeing actual harmony rather than just visually similar colors.

**Do I need to worry about input formats for `convert_color`?**
No. The tool accepts HEX, RGB, or HSL and handles the conversion process internally, so you only have to provide the color data itself.

**How fast are the calculations when I use `generate_color_palette`?**
The palette generation is instantaneous because it relies only on raw mathematical formulas. You don't worry about latency or external service calls; the calculation happens immediately.

**What happens if I pass an invalid number to `manipulate_luminance`?**
The MCP handles bad inputs gracefully by rejecting them and providing a specific error message. It won't crash your workflow, forcing you to correct the percentage value before proceeding.

**Does this Deterministic Color Engine handle color data outside of HEX, RGB, or HSL?**
No, the scope is strictly limited to those three formats. If you need to process other kinds of visual data, like CMYK or advanced gradients, you'll need a different specialized tool.

**What format does `generate_color_palette` return when I request colors?**
It returns the resulting color palette as a clean, structured list of valid hexadecimal strings. This makes it simple for your AI client to read and use directly in code.

**Why use an MCP for basic color conversion?**
While AI models can sometimes guess standard conversions, they fail consistently when computing HSL luminance shifts (like creating a 10-step Tailwind color scale). An algorithmic engine guarantees zero error margins.

**How does the palette generation work?**
It converts the base color into HSL format and shifts the Hue degree. Complementary shifts by 180 degrees, while Analogous generates a harmonic palette by shifting -30 and +30 degrees.

**Are there any external dependencies to run this tool?**
Absolutely none. The color engine is built from scratch utilizing pure Javascript bitwise operators and math algorithms, providing zero-latency execution without external bloated libraries.