Palettemcp

🚀 PaletteMCP - Color Code to Name Converter

PaletteMCP is a command-line tool written in Go. It takes a hexadecimal color code as input and returns the name of the closest matching color from a predefined list of CSS colors. The output is presented in JSON format, which simplifies integration with other scripts and systems.

🚀 Quick Start

PaletteMCP can quickly convert hexadecimal color codes to the names of CSS colors. You can use it either as a command-line tool or run it as a Gemini Model Context Protocol (MCP) server.

✨ Features

• Convert any hex color code to its nearest color name.
• Outputs in a clean, machine-readable JSON format.
• Includes a comprehensive list of standard CSS colors.
• Simple and easy-to-use command-line interface.

📦 Installation

To use this tool, you need to have Go installed on your system.

Build from Source

1. Clone the repository (if you have it in a git repo) or just use the existing files.
2. Build the executable:

   go build -o palette-mcp ./cmd/palette-mcp
   

Download Pre-built Binaries

You can download pre-built binaries for various operating systems and architectures directly from the GitHub Releases page. Replace [VERSION] with the desired release version (e.g., v1.0.0).

Linux / macOS

# Download the binary (replace [OS] and [ARCH] with your system, e.g., linux_amd64, darwin_arm64)
wget https://github.com/kelvinzer0/PaletteMCP/releases/download/[VERSION]/palette-mcp_[OS]_[ARCH] -O palette-mcp

# Make it executable
chmod +x palette-mcp

# Move it to a directory in your PATH (e.g., /usr/local/bin)
sudo mv palette-mcp /usr/local/bin/

Windows

1. Download the appropriate .exe file from the GitHub Releases page (e.g., palette-mcp_windows_amd64.exe).
2. Rename the downloaded file to palette-mcp.exe.
3. Move palette-mcp.exe to a directory that is included in your system's PATH environment variable. A common practice is to create a bin folder in your user directory (e.g., C:\Users\YourUser\bin) and add it to PATH.

💻 Usage Examples

Command-Line Tool Usage

Run the tool from your terminal, passing a hex color code (with or without the # prefix) as an argument.

./palette-mcp #ff6347

Example (Command-Line Tool)

Input:

./palette-mcp #ff6347

Output:

{
  "hex": "#ff6347",
  "name": "Tomato",
  "rgb": "rgb(255, 99, 71)"
}

Gemini MCP Server Integration

palette-mcp can also run as an MCP server, exposing its functionality to the Gemini CLI. This allows the Gemini model to discover and execute palette-mcp's tools.

Running the MCP Server

To start palette-mcp in server mode, use the server argument.

Stdio Transport

This is the default transport method and is used when you run the server with the server argument.

# Start the server using stdio
./palette-mcp server

HTTP Transport

You can also run the server with an HTTP transport, which allows you to specify a custom port.

# Start on default port 8080
./palette-mcp serve-http

# Start on a custom port (e.g., 9000)
./palette-mcp serve-http 9000

SSE (Server-Sent Events) Transport

To run the server in SSE mode, use the -sse flag. This will start an HTTP server that streams events.

# Start on default port 8080 in SSE mode
./palette-mcp -sse

# Start on a custom port (e.g., 9000) in SSE mode
./palette-mcp -sse -port 9000

It's recommended to run the server in the background if you want to continue using your terminal:

./palette-mcp serve-http &
# Or for a custom port:
./palette-mcp serve-http 9000 &

# For SSE mode:
./palette-mcp -sse &
# Or for a custom port:
./palette-mcp -sse -port 9000 & 

Configuring Gemini CLI

To enable the Gemini CLI to connect to your palette-mcp server, add the following configuration to your settings.json file. This file can be found globally at ~/.gemini/settings.json or in your project's .gemini/settings.json.

{
  "theme": "ANSI Light",
  "selectedAuthType": "oauth-personal",
  "mcpServers": {
    "get-color-info": {
        "command": "/usr/local/bin/palette-mcp",
        "args":["server"]
    }
  }
}

• paletteMcpServer: This is the name you give to your MCP server within Gemini CLI. You can choose any descriptive name.
• httpUrl: The URL where your palette-mcp server is listening. Adjust the port if you started the server on a custom port (e.g., http://localhost:9000).
• timeout: The maximum time (in milliseconds) Gemini CLI will wait for a response from the server.

Available Tools

Once configured and the server is running, the Gemini CLI will discover the following tools:

• echo: Echoes back the provided message. (Example tool for demonstration)
  • Parameters: message (string)
• get_color_info: Retrieves information about a color given its hex code.
  • Parameters: hexCode (string, e.g., #FF0000)

Example Gemini CLI Usage (Conceptual)

After setting up, you can interact with the tools via the Gemini CLI. For instance, you might ask: What is the name of the color #00BFFF? The Gemini model, if it decides to use the get_color_info tool, would execute it and provide the result.

Integration with Forge MCP

PaletteMCP can be easily integrated into forge mcp workflows to provide color name lookup capabilities. You can add palette-mcp as a custom command within your forge mcp configuration.

Adding PaletteMCP to Forge MCP

You can add palette-mcp to your forge mcp configuration using the forge mcp add command or by manually editing your .mcp.json file.

Using forge mcp add (Command Line)

# Example: Add palette-mcp as a command named 'colorname'
forge mcp add --name colorname --command /path/to/palette-mcp --args "#{{hex_code}}"

• Replace /path/to/palette-mcp with the actual absolute path to your palette-mcp executable.
• #{{hex_code}} is a placeholder for the hexadecimal color code that forge mcp will pass to palette-mcp. The double curly braces {{...}} indicate a variable or expression in forge mcp.

Manual .mcp.json Configuration

You can also manually create or modify your .mcp.json file. This file can be located in your local project directory or in your user-specific configuration.

{
  "mcpServers": {
    "colorname_tool": {
      "command": "/usr/local/bin/palette-mcp",
      "args": ["server"],
      "description": "Converts a hex color code to its closest named color."
    }
  }
}

• colorname_tool: This is the name you will use to invoke palette-mcp via forge mcp (e.g., forge mcp run colorname_tool #RRGGBB).
• command: The absolute path to your palette-mcp executable.
• args: An array of arguments to pass to palette-mcp. "#{{hex_code}}" is a common pattern for passing dynamic input from forge mcp.

Example Forge MCP Usage

Once configured, you can use palette-mcp within your forge mcp workflows:

# Run the configured colorname_tool with a hex code
forge mcp run colorname_tool "#00BFFF"

# Example of using the output in a multi-agent workflow (conceptual)
# Assuming 'forge mcp run colorname_tool' outputs JSON
COLOR_INFO=$(forge mcp run colorname_tool "#FF0000")
COLOR_NAME=$(echo $COLOR_INFO | jq -r '.name')
echo "The color is: $COLOR_NAME"

• Note: The jq command is a powerful JSON processor for the command line. You might need to install it separately (brew install jq on macOS, sudo apt-get install jq on Debian/Ubuntu).

This integration allows forge mcp to leverage PaletteMCP for color code to name conversions as part of larger automation or multi-agent tasks.

📚 Documentation

How It Works

The tool calculates the "closest" color by finding the Euclidean distance between the input color's RGB values and the RGB values of each color in the predefined list. The color with the smallest distance is considered the closest match.

Color Reference

The following table lists all the named colors used for matching.

🤝 Contributing

Contributions are welcome! Please feel free to submit a pull request or open an issue if you have suggestions for improvements.

📄 License

This project is licensed under the MIT License.