Minipainter

MINIPAINTER

颜料工作台，尽在索引之中。

网站：arturskowronski.github.io/minipainter

minipainter 是一个本地优先的微缩模型涂装工作流颜料登记工具。它的存在只有一个实际原因：只有当 AI 了解你实际拥有的颜料时，AI 的涂装建议才会更有用。

该项目为你提供：

• 确定性的本地目录（涵盖 Citadel、Army Painter、Vallejo、AK，共 1,607 种颜料）和库存
• 优先查找已拥有颜料，以及跨品牌颜色匹配
• 彩色终端 UI（TUI），以色块显示每种颜料的实际 RGB 值
• 面向 Claude Desktop 和 ChatGPT 的 MCP 服务
• 同时为用户和 Agent 工作流设计的 CLI

彩色 TUI

库存 TUI 是一款真正的彩色终端应用：包含 MINIPAINTER 横幅、金色分区边框、绿色 OWNED / 红色 MISSING 状态，以及显示每种颜料自身 RGB 值的真彩色色块。TTY 终端会启用颜色，并遵循 NO_COLOR 设置。

为什么要做这个项目

大多数颜料建议工作流都会卡在同一个地方：它们推荐了你手头没有的颜料。

minipainter 正是为了解决这个问题而构建的：

• 在本地记录你的颜料架上有哪些颜料
• 按名称、用途、色系和近似颜色快速搜索
• 为未来可检查链接、照片和模型图像的 AI 技能准备稳定的库存基础

长远目标不是“AI 为微缩模型随意挑选颜色”，而是“AI 首先根据你的实际库存进行推理，只在有用时才推荐更合适的替代品”。

功能亮点

• 优先匹配已拥有颜料：查找和推荐时可以优先考虑你已经拥有的颜料。
• 目录存于仓库，库存存于主目录：颜料记录存放在 data/catalog/；你拥有的颜料存放在 ~/.minipainting/inventory.json，并可在不同项目间使用。
• 支持 RGB 的搜索：近似 RGB 值有助于查找最接近的颜色。
• 彩色 TUI：终端库存界面，带有每种颜料的 RGB 色块和 OWNED/MISSING 状态。
• 适合 Agent 的 CLI：为 AI 集成（Claude + ChatGPT MCP）提供确定性的命令输出。

截图

主界面

全屏 TUI，包含横幅、目录、详情面板和命令栏。

See: docs/assets/hero.txt

搜索视图

针对 bone 这类语义搜索的筛选结果。

See: docs/assets/search.txt

已拥有视图

仅展示库存，聚焦于已纳入你收藏的颜料。

See: docs/assets/owned.txt

CLI 工作流

展示搜索、更新所有权和颜色匹配的典型命令行用法。

See: docs/assets/cli.txt

使用 Docker 运行（Postgres）

整个技术栈——MCP/HTTP 服务和用于存储库存的 Postgres——只需一条命令即可启动。库存会持久保存在命名卷中，因此容器重启以及执行 docker compose down 后重新创建时，库存都会保留（只有执行 down -v 才会清除库存）。

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

• GET /health — 存活状态
• GET /api/inventory — 已拥有的颜料（来自 Postgres）
• POST /mcp — 面向 Claude Desktop 的 MCP · POST /mcp/v3 — 面向 ChatGPT 的 MCP（search/fetch）

存储方式由 DATABASE_URL 决定：设置该变量（如 docker-compose.yml 中所示）即可使用 Postgres；不设置则使用本地 JSON 库存文件（本地行为保持不变）。参见 .env.example。

部署

任何支持 Docker 和 Postgres 的主机都可以（Fly.io、Railway、VPS……）。如果要一键部署带托管数据库的远程 MCP 服务，仓库提供了 Render Blueprint（render.yaml），可一并创建 Web 服务和 Postgres，并自动配置 DATABASE_URL：

参考部署 warpaint-mcp.fly.dev 在 Fly.io 上运行，并使用 Fly Managed Postgres — 请参阅 docs/deploy-fly.md，了解 fly mpg attach 和迁移步骤。

安装

最快的方法是通过 npx 直接从 npm 运行，无需克隆或安装：

npx minipainter paint search bone
npx minipainter match color "#d2c29b"
npx minipainter tui

也可以全局安装，以便随时使用简短的 mpaint 命令：

npm install -g minipainter
mpaint paint search bone
mpaint match color "#d2c29b"

目录已打包，因此首次运行即可搜索和匹配，无需任何配置。你的库存位于 ~/.minipainting/inventory.json；首次将某种颜料标记为已拥有时会自动创建该文件（旧版 ~/.warpaint/ 会自动迁移）。

要求：

• Node.js 18 或更高版本
• POSIX 类 shell（Linux、macOS、WSL）

从源代码构建

如需修改项目，可克隆仓库并在工作树中运行：

git clone https://github.com/ArturSkowronski/minipainter.git
cd minipainter
npm install
node src/cli.mjs paint search bone

之后，你可以通过以下四种方式使用：

• CLI / TUI — 请参阅下方的快速入门
• 自托管 HTTP 服务 — 支持 Docker 的单一运行时，提供 JSON 存储和 API 端点
• Claude Desktop 本地 MCP — 请参阅 Claude Desktop MCP 设置
• Claude 移动端/Web 远程 MCP — 请参阅 远程 MCP

快速入门

初始化本地库存文件 ~/.minipainting/inventory.json：

node src/cli.mjs catalog sync

搜索颜料：

node src/cli.mjs paint search black
node src/cli.mjs paint search bone --json

查看一种颜料的详情：

node src/cli.mjs paint show "Abaddon Black" --json

将颜料标记为已拥有或缺失：

node src/cli.mjs inventory own "Abaddon Black"
node src/cli.mjs inventory unown "Abaddon Black"
node src/cli.mjs inventory list

运行语义或颜色匹配：

node src/cli.mjs match describe bone
node src/cli.mjs match color "#d2c29b"

启动 TUI：

node src/cli.mjs tui

在本地运行 MCP 服务：

node src/mcp-server.mjs

在本地运行自托管 HTTP 服务：

DATA_DIR=.minipainting-data node src/mcp-http-server.mjs

TUI 工作流

TUI 以三个展示区域为核心：

• FORGE CATALOG：当前范围内可见的颜料
• SELECTED PIGMENT：当前高亮显示的颜料及其供应商、系列、用途和 RGB 值
• RITUAL COMMANDS：当前会话的命令说明

当前 TUI 命令：

• search <text>
• owned
• catalog
• toggle
• quit

推荐用法：

1. 从 catalog 开始
2. 使用 search bone、search black 或类似查询缩小范围
3. 查看所选颜料面板
4. 随着收藏变化，切换颜料的拥有状态

项目方向

目前已实现：

• 本地 JSON 注册表
• Citadel 和 Army Painter 的入门供应商目录
• 已拥有 / 缺失库存追踪
• 确定性搜索和颜色匹配
• 带有逐种颜料色样的彩色终端展示
• 用于 Claude Desktop 的本地 MCP 服务

后续计划：

• 用于解析颜料套装链接的独立技能
• 根据颜料瓶照片填充库存
• 分析模型照片，优先推荐已拥有的颜料
• 更强的跨供应商等效颜料匹配及提示

技术说明

• 内置目录数据位于 data/catalog/（Citadel 和 Army Painter，纳入版本控制）
• 库存文件：~/.minipainting/inventory.json — 仅存储已拥有的颜料 ID，格式为 { "version": 1, "owned": ["citadel/abaddon-black", ...] }
• 可自托管服务的数据目录：DATA_DIR（在 Docker 中默认为 /data）；库存位于 <DATA_DIR>/inventory.json
• 目录和库存会在运行时合并；保存时不会重写目录
• 按照约定，ID 是稳定的（提供方 + 名称 slug）；加载时，目录中不存在的已拥有 ID 会作为警告报告，而不会被静默丢弃
• 如果库存路径旁边已有项目本地 .minipainting/registry.json，首次运行时会自动迁移
• 首次运行时，旧版 .warpaint/ 数据目录会自动重命名为 .minipainting/（包括主目录和项目本地目录）
• 可通过 { inventoryPath } 或 { cwd } 在 API 层指定库存位置（后者会解析为 <cwd>/.minipainting/inventory.json，测试套件会使用此路径进行隔离）
• RGB 值是用于匹配的近似参考颜色，并不保证最终涂装效果
• MCP 入口：node src/mcp-server.mjs
• MCP 辅助脚本：npm run mcp
• HTTP 服务辅助脚本：npm run server
• README 演示截图可通过以下方式复现：

npm run generate:demo

Claude Desktop MCP 设置

minipainter 现在包含本地 MCP 服务，因此 Claude Desktop 可以直接使用你的颜料注册表。

本地 MCP 配置示例：

{
  "mcpServers": {
    "minipainter": {
      "command": "node",
      "args": ["/absolute/path/to/minipainter/src/mcp-server.mjs"]
    }
  }
}

添加服务后，Claude Desktop 可以调用以下工具：

• paint_search
• paint_show
• inventory_list
• inventory_mark_owned
• inventory_mark_unowned
• match_color
• match_describe

建议的本地流程：

1. 使用 node src/cli.mjs catalog sync 初始化注册表
2. 将 MCP 服务添加到 Claude Desktop
3. 让 Claude 通过已开放的工具搜索颜料或更新所属状态

Agent 技能

对于 Claude Code，可直接从网站获取技能，无需克隆。它内置了合适的防护措施：仅以 JSON 格式读取、遵循 product_format 规则、处理失败情况。

# project-scoped
mkdir -p .claude/skills/minipainter
curl -fsSL https://arturskowronski.github.io/minipainter/SKILL.md \
  -o .claude/skills/minipainter/SKILL.md

或者将其保存到 ~/.claude/skills/minipainter/SKILL.md，即可在所有地方使用。

可自托管 Docker

Docker 镜像运行一个专为可自托管场景设计的单一 HTTP 服务运行时。可从仓库构建（目前尚未将镜像发布到注册表）：

docker build -t minipainter .
docker run -p 3000:3000 -v minipainting-data:/data minipainter

或者通过 docker compose up -d 一步启动服务和 Postgres。

服务提供以下接口：

• GET /health
• GET /api/paints
• GET /api/paints/:paint
• GET /api/inventory
• PUT /api/inventory/:paint
• DELETE /api/inventory/:paint
• POST /api/match/color
• POST /api/match/describe
• POST /mcp

可选运行时配置：

• PORT — 监听端口，默认为 3000
• DATA_DIR — 持久化状态目录，在 Docker 中默认为 /data
• AUTH_TOKEN — 使用 Authorization: Bearer ... 保护 /api/* 和 /mcp
• INVENTORY_SYNC_TOKEN — 保护旧版 /inventory 同步接口

远程 MCP（Claude Mobile）

Claude 移动端或网页端无法访问上文的 stdio MCP 服务。请改为运行 minipainter-mcp-http — 一种 Streamable HTTP MCP 传输方式，提供相同的工具， 并额外提供用于同步本地库存的 GET/POST /inventory。

本地冒烟测试

export INVENTORY_SYNC_TOKEN=$(openssl rand -hex 32)
export PORT=3000
export INVENTORY_PATH=$HOME/.minipainting/inventory.json
npm run mcp:http

然后在另一个 shell 中：

curl -s http://localhost:3000/health
curl -s -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Sync endpoint (bearer-token protected)
curl -s -H "Authorization: Bearer $INVENTORY_SYNC_TOKEN" \
     http://localhost:3000/inventory

部署到 Fly.io

仓库附带 Dockerfile 和 fly.toml。完整步骤见 docs/deploy-fly.md。简要步骤：

fly launch --no-deploy --copy-config --name <your-app-name>
fly volumes create inventory_data --region <your-region> --size 1
fly secrets set INVENTORY_SYNC_TOKEN="$(openssl rand -hex 32)"
fly deploy

连接 Claude

在 Claude（移动端或网页端）中，添加自定义连接器：

• URL：https://<your-app-name>.fly.dev/mcp

/mcp 端点目前没有身份验证 — 任何知道 URL 的人都可以 调用工具。目前请依靠 URL 的隐蔽性和 Fly 的网络控制； 在分享 URL 前添加按用户身份验证。

环境变量

变量	必需	用途
INVENTORY_SYNC_TOKEN	用于 /inventory	用于保护 GET/POST /inventory 的 Bearer 令牌；未设置时，同步会返回 503
INVENTORY_PATH	否	inventory.json 的路径；本地默认为 ~/.minipainting/inventory.json，Docker 镜像中默认为 /data/inventory.json
INVENTORY_JSON	否	一次性初始 JSON；仅在首次启动时 INVENTORY_PATH 不存在的情况下使用
WARPAINT_INVENTORY_JSON	否	INVENTORY_JSON 的旧版别名
MCP_SERVER_NAME	否	MCP 握手和启动日志中显示的服务名称；默认为 paint-inventory
PORT	否（默认 3000）	要监听的 TCP 端口

已知限制

• /mcp 尚无身份验证。Bearer 令牌仅用于保护 /inventory。
• 无状态传输：不支持长时间运行的 SSE 工具流（工具执行很快，因此没有问题）。

自托管你自己的 MCP

MCP 服务是通用的，只有 CLI（mpaint）带有品牌标识。要运行你自己的实例：

1. Fork 或克隆此仓库。

2. （可选）在 fly.toml 中重命名你的 Fly 应用。

3. 创建 Fly 卷并设置机密：

   fly volumes create inventory_data --size 1 --region <your-region>
   fly secrets set INVENTORY_SYNC_TOKEN=$(openssl rand -hex 24)
   # Optional one-time seed:
   fly secrets set INVENTORY_JSON="$(cat ~/.minipainting/inventory.json)"
   

4. （可选）为你的 MCP 服务命名（名称会显示在 MCP 握手和启动日志中）：

   fly secrets set MCP_SERVER_NAME=my-paints
   

5. 部署：

   fly deploy
   

6. 在本地 CLI 中注册远程服务并同步：

   mpaint sync add default \
     --url https://my-app.fly.dev \
     --token <token-from-step-3>
   mpaint sync push
   

之后，你的本地库存与已部署的 MCP 会通过 mpaint sync push（将本地内容上传到远程服务）和 mpaint sync pull --force （用远程内容覆盖本地内容）保持同步。

许可证

MIT © Artur Skowronski