MINIPAINTER

The paint bench, indexed.

Site: arturskowronski.github.io/minipainter

minipainter is a local-first paint registry for miniature-painting workflows. It exists for one practical reason: AI paint suggestions are much more useful when they understand the paints you actually own.

The project gives you:

• a deterministic local catalog (1,607 paints across Citadel, Army Painter, Vallejo, AK) and inventory
• owned-first paint lookup and cross-brand color matching
• a colored terminal UI (TUI) that shows each paint's real RGB as a swatch
• MCP servers for both Claude Desktop and ChatGPT
• a CLI surface designed for both humans and agent workflows

The colored TUI

The ledger TUI is a real colored terminal app: a MINIPAINTER banner, gold section frames, green OWNED / red MISSING status, and a truecolor swatch of every paint's own RGB. Color turns on for a TTY and honors NO_COLOR.

Why This Exists

Most paint advice workflows break at the same point: they recommend paints you do not have on hand.

minipainter is built to solve that exact problem:

• keep a local record of what is in your paint rack
• search it quickly by name, role, family, and approximate color
• prepare a stable inventory foundation for a future AI skill that can inspect links, photos, and model images

The long-term goal is not “AI picks random colors for miniatures.” The goal is “AI reasons from your actual inventory first, then suggests stronger alternatives only when useful.”

Feature Highlights

• Owned-first matching: lookups and recommendations can prioritize paints you already have.
• Catalog in repo, inventory in your home: paint records live in data/catalog/; what you own lives in ~/.minipainting/inventory.json and follows you across projects.
• RGB-aware search: approximate RGB values help with nearest-color matching.
• Colored TUI: terminal ledger with per-paint RGB swatches and OWNED/MISSING status.
• Agent-friendly CLI: deterministic command output for AI integration (Claude + ChatGPT MCP).

Screenshots

Hero Screen

Full-screen TUI with banner, catalog, detail panel, and command strip.

See: docs/assets/hero.txt

Search View

Filtered lookup for a semantic search like bone.

See: docs/assets/search.txt

Owned View

Inventory-only presentation focused on what is already bound to your collection.

See: docs/assets/owned.txt

CLI Flow

Representative command-line usage for search, ownership updates, and color matching.

See: docs/assets/cli.txt

Run with Docker (Postgres)

The whole stack — MCP/HTTP server plus a Postgres that stores your inventory — starts with one command. Inventory persists in a named volume, so it survives container restarts and docker compose down / recreation (only down -v wipes it).

docker compose up --build        # http://localhost:3000

• GET /health — liveness
• GET /api/inventory — owned paints (from Postgres)
• POST /mcp — MCP for Claude Desktop · POST /mcp/v3 — MCP for ChatGPT (search/fetch)

Storage is selected by DATABASE_URL: set it (as docker-compose.yml does) for Postgres, leave it unset to use a local JSON inventory file (unchanged local behavior). See .env.example.

Deploy

Any Docker + Postgres host works (Fly.io, Railway, a VPS…). For a one-click remote MCP server with a managed database, the repo ships a Render Blueprint (`render.yam

... View full README on GitHub