MCP Color Server
by keyurgolani
README.md
# MCP Color Server
A comprehensive DeveloperTools Server and MCP that provides advanced color manipulation, palette generation, gradient creation, and visualization capabilities to AI applications.
## Features
- **Comprehensive Color Format Support**: Convert between 22+ formats including HEX, RGB, HSL, HSV, HWB, CMYK, LAB, XYZ, LCH, OKLAB, OKLCH, and named colors
- **Framework Integration**: Native support for CSS variables, SCSS, Tailwind classes, Swift UIColor, Android Color, and Flutter Color formats
- **High-Precision Conversion**: Configurable precision up to 10 decimal places for scientific and professional applications
- **Palette Generation**: Create harmonious color palettes based on color theory principles
- **Gradient Creation**: Generate linear, radial, and conic gradients with advanced interpolation
- **Accessibility Compliance**: WCAG 2.1 AA/AAA contrast checking and colorblind simulation
- **Dual Background Visualization**: Create interactive HTML and high-quality PNG visualizations with both light and dark background variants
- **Export Formats**: Generate CSS, SCSS, Tailwind CSS, and JSON exports for seamless integration
- **Theme Generation**: Generate complete design system themes with semantic color mapping
- **Performance Optimized**: Sub-100ms response times for all color operations with intelligent caching
## Installation
### Prerequisites
- Node.js 20.0.0 or higher
- npm or yarn package manager
### Install Dependencies
```bash
npm install
```
### Development Setup
```bash
# Install dependencies
npm install
# Build the project
npm run build
# Run in development mode
npm run dev
# Run tests
npm test
# Run tests with coverage
npm run test:coverage
# Lint code
npm run lint
# Format code
npm run format
```
## Usage
### As an MCP Server
The color server implements the Model Context Protocol and can be used with any MCP-compatible client.
#### Configuration
Add to your MCP client configuration:
```json
{
"mcpServers": {
"color": {
"command": "node",
"args": ["path/to/mcp-color-server/dist/index.js"]
}
}
}
```
#### Available Tools
- `convert_color`: Convert colors between different formats
- `analyze_color`: Analyze color properties (brightness, contrast, temperature)
- `generate_harmony_palette`: Create color palettes based on harmony principles
- `generate_gradient`: Create CSS gradients with advanced options
- `check_contrast`: Verify WCAG accessibility compliance
- `create_palette_html`: Generate interactive HTML visualizations
- `create_palette_png`: Generate high-quality PNG images
- `export_css`: Generate modern CSS with custom properties and utility classes
- `export_scss`: Generate SCSS variables, maps, and mixins
- `export_tailwind`: Generate Tailwind CSS configuration and utility classes
- `export_json`: Generate JSON format for programmatic use and API integration
## API
### MCP Protocol
The server implements the Model Context Protocol (MCP) specification and provides the following endpoints:
#### Tool Discovery
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list",
"params": {}
}
```
#### Tool Execution
```json
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "convert_color",
"arguments": {
"color": "#FF0000",
"output_format": "hsl"
}
}
}
```
### Response Format
All tools return responses in this standardized format:
```json
{
"success": true,
"data": {
"converted": "hsl(0, 100%, 50%)",
"original": "#FF0000"
},
"metadata": {
"execution_time": 15,
"color_space_used": "sRGB",
"accessibility_notes": [],
"recommendations": []
},
"visualizations": {
"html": "<!DOCTYPE html>...",
"png_base64": "iVBORw0KGgoAAAANSUhEUgAA..."
},
"export_formats": {
"css": ":root { --color: #FF0000; }",
"scss": "$color: #FF0000;",
"tailwind": "{ colors: { custom: '#FF0000' } }",
"json": { "hex": "#FF0000", "rgb": "rgb(255, 0, 0)" }
}
}
```
## Supported Color Formats
### Input Formats
The MCP Color Server accepts colors in any of these formats:
#### Standard Web Formats
- **HEX**: `#FF0000`, `#F00`, `FF0000`, `F00`
- **RGB**: `rgb(255, 0, 0)`, `255, 0, 0`, `255 0 0`, `[255, 0, 0]`
- **RGBA**: `rgba(255, 0, 0, 0.5)`
- **HSL**: `hsl(0, 100%, 50%)`, `0, 100%, 50%`
- **HSLA**: `hsla(0, 100%, 50%, 0.8)`
- **HSV/HSB**: `hsv(0, 100%, 100%)`, `hsb(0, 100%, 100%)`
- **HSVA**: `hsva(0, 100%, 100%, 0.7)`
#### Advanced Color Spaces
- **HWB**: `hwb(0, 0%, 0%)`
- **CMYK**: `cmyk(0%, 100%, 100%, 0%)`
- **LAB**: `lab(53.23, 80.11, 67.22)`
- **XYZ**: `xyz(41.24, 21.26, 1.93)`
- **LCH**: `lch(53.23, 104.55, 40.85)`
- **OKLAB**: `oklab(0.628, 0.225, 0.126)`
- **OKLCH**: `oklch(0.628, 0.258, 29.23)`
#### Named Colors
- **CSS Named Colors**: `red`, `blue`, `forestgreen`, `lightsteelblue`, etc.
### Output Formats
Convert to any of these formats with configurable precision:
#### Web Development
```json
{
"color": "#FF0000",
"output_format": "hex"
}
// Result: "#ff0000"
{
"color": "#FF0000",
"output_format": "rgb"
}
// Result: "rgb(255, 0, 0)"
{
"color": "#FF0000",
"output_format": "hsl",
"precision": 1
}
// Result: "hsl(0.0, 100.0%, 50.0%)"
```
#### CSS Variables
```json
{
"color": "#FF0000",
"output_format": "css-var",
"variable_name": "primary-color"
}
// Result: "--primary-color: #ff0000;"
{
"color": "#FF0000",
"output_format": "scss-var",
"variable_name": "accent_color"
}
// Result: "$accent_color: #ff0000;"
```
#### Mobile Development
```json
{
"color": "#FF0000",
"output_format": "swift",
"precision": 3
}
// Result: "UIColor(red: 1.000, green: 0.000, blue: 0.000, alpha: 1.000)"
{
"color": "#FF0000",
"output_format": "android"
}
// Result: "Color.parseColor(\"#FFFF0000\")"
{
"color": "#FF0000",
"output_format": "flutter"
}
// Result: "Color(0xFFFF0000)"
```
#### Framework Integration
```json
{
"color": "#FF0000",
"output_format": "tailwind"
}
// Result: "red-500"
```
#### Scientific/Professional
```json
{
"color": "#FF0000",
"output_format": "lab",
"precision": 6
}
// Result: "lab(53.230000, 80.110000, 67.220000)"
{
"color": "#FF0000",
"output_format": "oklab",
"precision": 8
}
// Result: "oklab(0.62800000, 0.22500000, 0.12600000)"
```
### Usage Examples
#### Basic Color Conversion
```javascript
// Convert HEX to RGB
{
"tool": "convert_color",
"parameters": {
"color": "#FF0000",
"output_format": "rgb"
}
}
// Convert RGB to HSL with high precision
{
"tool": "convert_color",
"parameters": {
"color": "rgb(255, 128, 64)",
"output_format": "hsl",
"precision": 4
}
}
```
#### Advanced Color Space Conversions
```javascript
// Convert to LAB color space for perceptual uniformity
{
"tool": "convert_color",
"parameters": {
"color": "#FF8040",
"output_format": "lab",
"precision": 3
}
}
// Convert to OKLCH for modern color workflows
{
"tool": "convert_color",
"parameters": {
"color": "hsl(25, 100%, 69%)",
"output_format": "oklch",
"precision": 5
}
}
```
#### Framework-Specific Outputs
```javascript
// Generate Swift UIColor
{
"tool": "convert_color",
"parameters": {
"color": "#2563eb",
"output_format": "swift",
"precision": 3
}
}
// Generate Tailwind CSS class
{
"tool": "convert_color",
"parameters": {
"color": "#ef4444",
"output_format": "tailwind"
}
}
// Generate CSS custom property
{
"tool": "convert_color",
"parameters": {
"color": "#10b981",
"output_format": "css-var",
"variable_name": "success-color"
}
}
```
#### Export Format Generation
Generate complete stylesheets and configuration files:
```javascript
// Generate CSS with custom properties
{
"tool": "export_css",
"parameters": {
"colors": ["#2563eb", "#ef4444", "#10b981"],
"format": "both",
"semantic_names": ["primary", "error", "success"],
"include_rgb_hsl": true
}
}
// Generate SCSS with mixins
{
"tool": "export_scss",
"parameters": {
"colors": ["#2563eb", "#ef4444"],
"format": "all",
"include_functions": true,
"namespace": "theme"
}
}
// Generate Tailwind config
{
"tool": "export_tailwind",
"parameters": {
"colors": ["#2563eb"],
"include_shades": true,
"semantic_names": ["primary"]
}
}
// Generate JSON with metadata
{
"tool": "export_json",
"parameters": {
"colors": ["#2563eb", "#ef4444"],
"format": "detailed",
"include_accessibility": true,
"group_name": "Brand Colors"
}
}
```
### Performance Characteristics
- **Single Conversions**: < 100ms response time
- **Batch Operations**: < 20ms average per conversion
- **High Precision**: Up to 10 decimal places without performance impact
- **Memory Efficient**: Optimized for concurrent operations
- **Caching**: Intelligent caching for frequently converted colors
### Direct Usage
```typescript
import { ColorServer } from './src/server.js';
const server = new ColorServer();
// Server usage examples will be added as implementation progresses
```
## Development
### Project Structure
```
mcp-color-server/
├── src/ # Source code
│ ├── server.ts # Main MCP server implementation
│ ├── tools/ # Tool implementations
│ ├── validation/ # Input validation schemas
│ ├── types/ # TypeScript type definitions
│ └── utils/ # Utility functions
├── tests/ # Test files
├── docs/ # Documentation
├── examples/ # Usage examples
└── dist/ # Compiled output
```
### Code Quality
This project maintains high code quality standards with automated Git hooks:
- **Pre-commit Hooks**: Automatic linting, formatting, and type checking on staged files
- **Pre-push Hooks**: Full test suite with 90%+ coverage requirements and build verification
- **Commit Message Validation**: Enforces conventional commit format
- **Zero-Defect Policy**: No TypeScript errors, ESLint warnings, or failing tests allowed
See [Husky Setup Documentation](docs/development/husky-setup.md) for detailed information about our Git hooks.
- **TypeScript**: Strict mode enabled with comprehensive type checking
- **ESLint**: Enforces code style and catches potential issues
- **Prettier**: Automatic code formatting
- **Jest**: Comprehensive test suite with 90%+ coverage requirement
- **Continuous Integration**: Automated testing and quality checks
### Contributing
Please read [docs/contributing.md](docs/contributing.md) for details on our code of conduct and the process for submitting pull requests.
### Testing
```bash
# Run all tests
npm test
# Run tests in watch mode
npm run test:watch
# Run tests with coverage report
npm run test:coverage
# Run specific test file
npm test -- server.test.ts
```
### Building
```bash
# Clean previous build
npm run clean
# Build for production
npm run build
# Type check without building
npm run type-check
```
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Contributing
We welcome contributions! Please see [docs/contributing.md](docs/contributing.md) for guidelines.
## Code of Conduct
This project adheres to a [Code of Conduct](docs/code-of-conduct.md). By participating, you are expected to uphold this code.
## Support
- **Issues**: [GitHub Issues](https://github.com/keyurgolani/ColorMcp/issues)
- **Discussions**: [GitHub Discussions](https://github.com/keyurgolani/ColorMcp/discussions)
- **Documentation**: [docs/](docs/)
- [Export Formats Guide](docs/guides/export-formats-guide.md)
- [Color Theory Guide](docs/guides/color-theory-guide.md)
- [Accessibility Guide](docs/guides/accessibility-guide.md)
## Production Deployment
### System Requirements
- **Node.js**: 20.0.0 or higher
- **Memory**: 512MB minimum, 2GB recommended
- **CPU**: 1 core minimum, 2+ cores recommended for high load
- **Storage**: 100MB for application, additional space for logs and cache
### Performance Characteristics
- **Response Times**: < 100ms for color conversions, < 2s for complex visualizations
- **Throughput**: 50+ concurrent requests supported
- **Memory Usage**: < 100MB per request, intelligent caching and cleanup
- **Reliability**: 99.9% uptime with proper deployment and monitoring
### Deployment Options
#### Docker Deployment
```bash
# Build Docker image
docker build -t mcp-color-server .
# Run container
docker run -d \
--name mcp-color-server \
-e NODE_ENV=production \
-e LOG_LEVEL=info \
-p 3000:3000 \
mcp-color-server
```
#### PM2 Deployment
```bash
# Install PM2 globally
npm install -g pm2
# Start with PM2
pm2 start ecosystem.config.js
# Save PM2 configuration
pm2 save
pm2 startup
```
#### Systemd Service
```bash
# Copy service file
sudo cp mcp-color-server.service /etc/systemd/system/
# Enable and start service
sudo systemctl enable mcp-color-server
sudo systemctl start mcp-color-server
```
### Monitoring and Maintenance
- **Health Checks**: Built-in health endpoint at `/health`
- **Metrics**: Performance metrics and resource usage tracking
- **Logging**: Structured JSON logging with configurable levels
- **Alerts**: Memory usage, response time, and error rate monitoring
## Security
### Security Features
- **Input Validation**: Comprehensive validation for all color formats and parameters
- **XSS Prevention**: Sanitization of generated HTML, CSS, and SVG content
- **Rate Limiting**: Built-in rate limiting for expensive operations
- **Resource Protection**: Memory limits, processing timeouts, and cleanup
- **Audit Logging**: Security-relevant events logged without exposing sensitive data
### Security Best Practices
1. **Run with minimal privileges**: Use dedicated user account
2. **Network security**: Run behind reverse proxy with HTTPS
3. **Resource limits**: Configure appropriate memory and CPU limits
4. **Regular updates**: Keep dependencies updated for security patches
5. **Monitoring**: Monitor for suspicious activity and resource usage
### Vulnerability Reporting
Report security vulnerabilities privately to: **security@mcp-color-server.org**
See [docs/security.md](docs/security.md) for detailed security policy and reporting procedures.
## Roadmap
### Current Version (0.1.0)
- ✅ Complete color format conversion system
- ✅ Palette generation with color theory algorithms
- ✅ Gradient creation and visualization
- ✅ Theme generation and semantic color mapping
- ✅ Accessibility compliance tools
- ✅ HTML and PNG visualization generation
- ✅ Export formats (CSS, SCSS, Tailwind, JSON)
- ✅ Performance optimization and caching
- ✅ Security hardening and input validation
### Planned Features (Future Releases)
- 🔄 3D color space visualizations
- 🔄 Color animation and transitions
- 🔄 Advanced image color extraction
- 🔄 Educational content and tutorials
- 🔄 Plugin architecture for custom algorithms
- 🔄 RESTful API endpoints
- 🔄 Advanced gradient types (mesh, conic)
- 🔄 Mobile framework integrations
### Community Contributions Welcome
- Color theory algorithm improvements
- New export format support
- Performance optimizations
- Documentation enhancements
- Test coverage improvements
- Accessibility features
TDQS
B3.1/5.0
Scored across 25 tools
Disambiguation3/5
The tools have clear individual purposes, but significant overlap exists in visualization and export functions. For example, create_palette_html and create_palette_png serve similar purposes with different output formats, as do the multiple gradient and export tools. Descriptions help differentiate, but agents might struggle choosing between format-specific variants.
Naming Consistency5/5
Tool names follow a highly consistent verb_noun pattern throughout, with clear action prefixes like analyze_, check_, convert_, create_, export_, generate_, mix_, optimize_, simulate_, and sort_. All names use snake_case consistently, making them predictable and readable.
Tool Count2/5
With 25 tools, this server feels overloaded for a color manipulation domain. Many tools could be consolidated (e.g., multiple create_* and export_* variants), leading to redundancy. A more focused set of 10-15 tools would better serve the core functionality without overwhelming agents.
Completeness5/5
The toolset provides comprehensive coverage for color manipulation, analysis, visualization, and integration. It includes core operations (convert, mix, generate variations), accessibility features, multiple output formats, and design system support. No obvious gaps exist; agents can perform complete color workflow tasks.
Maintenance
ActivityInactive
ResponsivenessNo issues