io.github.RNVizion/rnv-color-mcp
A complete color workflow over MCP: mix, convert, harmonize, measure, and remember palettes.
Open source Repository Open in the app JSON README (API)
About
A complete color workflow over MCP: mix, convert, harmonize, measure, and remember palettes.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- rnvizion
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 1.2.0
- Stars
- 1
- Last push
- 2026-08-25T00:04:03Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 03:02:11
- Updated
- 2026-08-29 03:02:11
- Origin id
io.github.RNVizion/rnv-color-mcp
README
--- title: RNV Color MCP emoji: 🎨 colorFrom: gray colorTo: yellow sdk: docker app_port: 7860 pinned: false short_description: Color workflow MCP server --- <!-- mcp-name: io.github.RNVizion/rnv-color-mcp --> # RNV Color MCP [](https://glama.ai/mcp/servers/RNVizion/rnv-color-mcp) [](https://github.com/punkpeye/awesome-mcp-servers) [](https://github.com/RNVizion/rnv-color-mcp/actions/workflows/tests.yml) A remote [MCP](https://modelcontextprotocol.io) server for a complete color workflow: mix, convert, harmonize, and remember palettes, called in plain language by Claude (or any MCP client), and by anything else that speaks MCP. ## Why this exists The color logic already lived in my [desktop suite](https://github.com/RNVizion): a mixer, a palette manager, a picker. Instead of rebuilding it for every new project, I lifted the engine out once and exposed it as a single server. A Claude conversation calls it today; a fashion design app will call the same backend tomorrow. Build the engine once, let both consume it. Underneath, it's a small thesis about working with LLMs: a model is great at deciding *what* you want and terrible at exact arithmetic. So the model picks the tool and the intent, and the tool owns the precise values. The server resolves or it refuses; it never guesses a color. ## What it does | Tool | What it does | |---|---| | `mix_colors` | Blend up to 12 colors. Modes: `rgb`, `hsv`, `lab` (digital) and `paint` (Kubelka-Munk pigment physics), `ryb` (artist's wheel), `cmy` (subtractive). | | `convert_color` | Convert between hex, rgb, hsv, hsl, lab. | | `generate_harmony` | complementary, analogous, triadic, split-complementary, tetradic/square, monochromatic, compound. | | `color_difference` | Perceptual difference (Delta-E, CIEDE2000 or CIE76) between two colors. | | `contrast_check` | WCAG contrast ratio plus AA/AAA pass/fail for accessible text. | | `transform_text` | 11 exact case transforms (UPPERCASE, camelCase, snake_case, …). | | `save_palette` / `list_palettes` / `get_palette` | Name a palette, recall it later. Persists across restarts. | Every color input accepts a **hex** (`#d2bc93`), a **CSS name** (`red`), an **RNV brand name** (`brand gold`, `near-black`), or a **saved-palette reference** (`Spring line`, or `Spring line:2` for its second swatch). Brand names win over CSS names on collision; `css:gold` forces the universal one. ## Connect in 30 seconds This is a hosted server, so there's nothing to install. In Claude: **Settings → Connectors → Add custom connector**, then paste: ``` https://rnvizion-rnv-color-mcp.hf.space/mcp ``` Leave auth blank, add it, then toggle it on in a chat with the **+** menu. ## Try it Once connected, just talk: > "Save a palette named *Spring line*: near-black and brand gold." > "Pull my Spring line palette and give me three complementary accents for outerwear." > "Mix paint-red and paint-blue like real pigment." The first call saves; the second composes `get_palette` → `generate_harmony`; the third runs the Kubelka-Munk paint model, so the blend darkens the way mixed pigment actually does, not the way averaged light does. ## Authentication The server implements OAuth 2.1 resource-server authentication with enforced per-tool scopes; the public endpoint runs with it disabled, so connecting by URL works with no setup. When enabled (`RNV_AUTH=1` plus a key source), the server validates bearer tokens against issuer, audience, expiry, and signature; serves [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) protected resource metadata at `/.well-known/oauth-protected-resource/mcp`; returns a spec-compliant `WWW-Authenticate` challenge on 401; and enforces two scopes: `read` covers the eight read-only tools, `write` covers `save_palette`, the only tool that mutates anything. A token without the `write` scope does not see `save_palette` in its tool list at all; out-of-scope tools are hidden rather than refused, so nothing leaks about what exists behind a scope you lack. Enforcement is covered by the test suite, run in CI on every push (status badge at the top of this file), spanning the token-validation matrix (missing, malformed, wrong issuer, wrong audience, expired, valid) and end-to-end scope enforcement over real HTTP. The suite mints its own keys and requires no credentials. The tests cover the auth layer; the color engine itself is not under automated test. Moving from the self-issued development key to a real identity provider is configuration, not code: point `RNV_AUTH_JWKS_URI` at the provider's JWKS endpoint and set the issuer and audience to match. | Variable | Purpose | |---|---| | `RNV_AUTH` | The switch. `1` / `true` / `yes` / `on` enables auth; unset means off. | | `RNV_AUTH_JWKS_URI` | A provider's JWKS endpoint. Use this or `RNV_AUTH_PUBLIC_KEY`. | | `RNV_AUTH_PUBLIC_KEY` | A static PEM public key, for development against a self-issued keypair. | | `RNV_AUTH_ISSUER` | Expected token issuer; also advertised as the authorization server. | | `RNV_AUTH_AUDIENCE` | Expected token audience. Bound to the `/mcp` path. | | `RNV_AUTH_BASE_URL` | Server base URL, without `/mcp`. | With `RNV_AUTH` on and no key source set, the server refuses to start rather than coming up unprotected. ## Run it yourself ```bash pip install -r requirements.txt python server.py # Streamable HTTP on $PORT (default 7860) pip install -r tests/requirements-dev.txt python -m pytest # auth + scope tests python tests/server_test.py # smoke: exercises all 9 tools in-process ``` Set `HF_TOKEN` to write palettes through to a private Hugging Face Dataset for durable storage. ## Running a copy? The code is MIT-licensed; you're free to rebuild, host, and modify it, and I'd rather you did than didn't. What a licence can't carry is the environment. Some capabilities depend on how a deployment is configured, not on the code alone: - **Palette persistence** needs `HF_TOKEN` and a writable Dataset. Without it, saves land in process memory and vanish with the container. - **Scoped authorization** needs `RNV_AUTH` and a configured issuer. Unset, the server runs open — which is correct for a public demo and wrong for anything else. - **Anything that fetches** needs outbound network access. A rebuild missing one of those usually doesn't fail loudly; it **returns success and drops the result.** That is worse than an outage, because an outage tells you. So: if you're running a copy and something behaves oddly, check the environment before you check the code, and check against the canonical deployment before you file anything. **Canonical endpoint:** `https://rnvizion-rnv-color-mcp.hf.space/mcp` **Canonical source:** `https://github.com/RNVizion/rnv-color-mcp` A copy served from another URL may be older, modified, or differently configured. That's fine and allowed; it just isn't this. The tools resolve or refuse; they don't guess. A copy can only keep that promise if the ground under it was checked first. ## Notes - **Brand colors are mirrored, not owned.** The vocabulary lives in [`engine/brand_vocab.py`](engine/brand_vocab.py), mirrored from `engine/brand.py` in [RNVizion/rnv-brand](https://github.com/RNVizion/rnv-brand) and corrected when drift is detected against it. It is carried locally on purpose: `resolve_color` is the hot path, and a fetch there would have to answer what happens when it fails — fail closed and the server refuses every color, fall back and the local copy is needed anyway, guess and the promise above is already broken. Identifiers are local by design; the check compares values, never names. The register and its reasoning live in `BRAND_COLORS.md`, in `rnv-brand`. - **Engine is dependency-free.** The color math, harmony, and text logic are pure standard library, lifted Qt-free from the desktop apps. Only the server layer needs `fastmcp`. - **Honest by design.** An unknown color name is refused, not guessed. An unverifiable token is refused, with a reason. Same principle at both layers. ## Stack Python · [FastMCP](https://github.com/PrefectHQ/fastmcp) (Streamable HTTP) · Hugging Face Spaces (Docker) · `huggingface_hub` for durable palette storage. --- Built by [Christian "RNVizion" Smith](https://rnvizion.dev).