Minipainter

MINIPAINTER

ペイント作業台を、インデックス化。

サイト：arturskowronski.github.io/minipainter

minipainter は、ミニチュア塗装のワークフロー向けのローカルファーストな塗料レジストリです。実用的な理由はひとつ。実際に所有している塗料を把握したうえで提案することで、AI による塗料の提案がずっと役立つようになります。

このプロジェクトでは、次のことができます。

• 決定論的なローカルカタログ（Citadel、Army Painter、Vallejo、AK の塗料1,607色）と在庫を管理
• 所有している塗料を優先した検索と、ブランドをまたいだ色合わせ
• 各塗料の実際の RGB を色見本で表示するカラーターミナル UI（TUI）
• Claude Desktop と ChatGPT の両方に対応する MCP サーバー
• 人間とエージェントのワークフローの両方を想定して設計された 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 ステータスを表示するターミナル台帳です。
• エージェント向け 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 を含むスタック全体が、1つのコマンドで起動します。在庫は名前付きボリュームに永続化されるため、コンテナの再起動や 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 によって選択されます。Postgres を使う場合は設定します（docker-compose.yml の設定例を参照）。設定しない場合はローカルの JSON 在庫ファイルを使用します（ローカルでの動作に変更はありません）。.env.example を参照してください。

デプロイ

Docker と Postgres を利用できるホストであれば、どこでも動作します（Fly.io、Railway、VPS など）。マネージドデータベースを備えたワンクリックのリモート MCP サーバーとして利用できるよう、リポジトリには Render Blueprint（render.yaml）が含まれています。これにより、Web サービスと Postgres がまとめてプロビジョニングされ、DATABASE_URL が自動的に設定されます。

リファレンスデプロイ warpaint-mcp.fly.dev は、Fly Managed Postgres とともに Fly.io 上で動作します。fly mpg attach とマイグレーションの手順については、 docs/deploy-fly.md を参照してください。

インストール

最も手軽な方法は、クローンやインストールをせずに、npx でそのまま実行することです。

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 互換のシェル（Linux、macOS、WSL）

ソースから

開発するには、クローンして作業ツリーに対して実行します。

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

その後、次の 4 つの利用モードを使えます。

• CLI / TUI — 下記のクイックスタートを参照
• セルフホスト型 HTTP サーバー — JSON ストレージと API エンドポイントを備えた、Docker 対応の単一ランタイム
• 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

塗料を 1 つ確認します。

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 は、次の 3 つの表示領域を中心に構成されています。

• 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 のスターター向けメーカー別カタログ
• 所有済み／未所有のインベントリ管理
• 決定論的な検索と色のマッチング
• 塗料ごとの色見本を備えたカラー表示のターミナル UI
• 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 は安定しています（プロバイダー + 名前のスラッグ）。読み込み時に、カタログにない所有済み ID は黙って破棄されず、警告として報告されます
• インベントリパスの隣に既存のプロジェクトローカル .minipainting/registry.json がある場合、初回実行時に自動移行されます
• レガシーの .warpaint/ データディレクトリは、初回実行時に自動で .minipainting/ に名前変更されます（ホームとプロジェクトローカルの両方）
• API サーフェスで { inventoryPath } または { cwd } を指定してインベントリの場所を変更できます（後者は <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. Claude Desktop に MCP サーバーを追加します
3. 公開されたツールを使って塗料を検索したり、所有状況を更新したりするよう Claude に依頼します

エージェントスキル

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 — /api/* と /mcp を Authorization: Bearer ... で保護します
• INVENTORY_SYNC_TOKEN — レガシーの /inventory 同期エンドポイントを保護します

リモート MCP（Claude Mobile）

Claude のモバイル版またはウェブ版からは、上記の stdio MCP サーバーにアクセスできません。代わりに minipainter-mcp-http を実行してください。これは、同じツールに加えて、ローカルインベントリを同期するための GET／POST /inventory を公開する Streamable HTTP MCP トランスポートです。

ローカルでのスモークテスト

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

次に、別のシェルで：

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 を保護するベアラートークンです。未設定の場合、同期は 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 はまだ認証に対応していません。ベアラートークンで保護されるのは /inventory のみです。
• ステートレスなトランスポートです。長時間実行される SSE ツールストリームには対応していません（ツールは高速なので問題ありません）。

独自の MCP をセルフホストする

MCP サーバーは汎用で、ブランド名が付いているのは CLI（mpaint）のみです。独自のインスタンスを実行するには、次の手順に従います。

1. リポジトリをフォークまたはクローンします。

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
   

これで、mpaint sync push（ローカルからリモートへアップロード）と mpaint sync pull --force（リモートの内容でローカルを上書き）を使って、ローカルのインベントリとデプロイ済みの MCP を同期できます。

ライセンス

MIT © Artur Skowronski