Mockups Gallery

Mockups MPC

AI が生成したモックアップを公開するセルフホスト可能なギャラリーです。MCP インターフェースを備えています。リポジトリを散らかす代わりに、モックアップを永続的に保存し、簡単に閲覧できるすっきりとしたウェブギャラリーを提供します。AI ツールは直接 curl を呼び出してアップロードし、MCP は一覧表示、メタデータ、タグ付け、取得といった軽量な連携のみを処理します。

トークン効率を考慮した設計です。 MCP ツールのパラメーターはモデルコンテキストを通過するため、大きな HTML ファイルをツール呼び出しで送信するとトークンを無駄に消費します。Mockups MPC は HTTP アップロードエンドポイント（POST /api/upload）を提供します。AI がファイルをローカルに書き込み、curl でサーバーに送信するため、ファイルの内容がモデルコンテキストに含まれることはありません。MCP ツールは、一覧表示、メタデータ、タグ付け、削除といった軽量な操作のみを処理します。

前提条件

• Docker（デプロイ用）または Python 3.12+（ローカル開発用）
• MCP 対応の AI クライアント（Claude Code、Claude Desktop など）
• オプション：Traefik リバースプロキシ（TLS を使用した本番環境向け）

導入理由

AI ツールがモックアップを生成するたびに、それを置く場所が決まっていません。そのため、リポジトリに積み重なったり、一時ディレクトリに散らばったりして、セッションから見失われ、履歴も残りません。Mockups MPC を使えば、モックアップを永続的に保存できます。AI がモックアップをギャラリーに送信し、そこから閲覧でき、ローカルファイルは削除されます。すべてを一か所にまとめ、プロジェクトを散らかしません。

アーキテクチャ

┌─────────────────┐     MCP (HTTP/SSE)     ┌──────────────────────┐
│  Claude Code /  │ ◄───────────────────── │                      │
│  Claude Desktop │  send/list/get/update  │    Mockups MPC       │
│  Any MCP Client │  delete/tag            │    (FastAPI)         │
└─────────────────┘                        │                      │
                                           │  ┌────────────────┐  │
       Browser                             │  │  MCP Server    │  │
    ┌──────────┐      GET /                │  │  (fastmcp)     │  │
    │ Gallery  │ ◄──────────────────────── │  └────────────────┘  │
    │ Viewer   │                           │  ┌────────────────┐  │
    └──────────┘                           │  │  JSON API      │  │
                                           │  │  /api/*        │  │
                                           │  └────────────────┘  │
                                           │  ┌────────────────┐  │
                                           │  │  SQLite (WAL)  │  │
                                           │  │  + Filesystem  │  │
                                           │  └────────────────┘  │
                                           └──────────────────────┘

FastAPI アプリを実行する単一の Docker コンテナで、次の 2 つの役割を担います。

1. MCP サーバー — /mcp/（HTTP トランスポート）と /mcp/sse（SSE トランスポート）で公開されます。AI ツールはここに接続して、モックアップの送信や管理を行います。
2. ウェブギャラリー — / で提供されます。サイドバーにはプロジェクト一覧と時系列フィード、メインビューアーには iframe／画像が表示されます。

データレイヤー

• SQLite（WAL モード）— メタデータカタログ（プロジェクト、タイトル、説明、タグ、コンテンツタイプ、タイムスタンプ）
• ファイルシステム — モックアップファイルを data/{project_slug}/{uuid}.{ext} に保存
• ストレージ — compose ファイルの隣にある data/ ディレクトリをバインドマウントします

技術スタック

• Python 3.12
• FastAPI + uvicorn
• fastmcp v3.x（スタンドアロン）
• aiosqlite 経由の SQLite
• Jinja2 テンプレート + バニラ JS
• Docker + Traefik

セキュリティ

組み込みの認証機能はありません。すべての API エンドポイントと MCP ツールは、サーバーに接続できるすべてのユーザーに公開されています。これは、信頼できるネットワーク（LAN、VPN、Tailscale）または認証を処理するリバースプロキシの背後での利用を想定しています。パブリックネットワークにデプロイする場合は、プロキシレイヤーで認証を追加してください。

バージョン

モックアップ（「デザイン」）には複数のバージョンを保持できます。同じ画面の各リビジョンを別々のモックアップに分散させず、1か所にまとめておけます。

• 既存のデザインにバージョンを追加する： -F parent=<id>（デザイン ID またはエイリアス ID）を指定してアップロードします。次のバージョンとして追加され、以前のバージョンとそのファイルは保持されます。
• 自動統合： parent を指定せずにアップロードしても、サーバーは一致するデザインがあるか確認します。同じプロジェクトに、同じ基本タイトル（末尾の v2、draft 3、rev 2、r5、末尾に単独で付いた数字、または (rail fixed) のような末尾の括弧書きを取り除いたタイトル）を持つデザインがちょうど1つある場合、アップロードしたものは自動的にそのデザインの新しいバージョンになります。バリエーションを示すマーカー（option B、variant C、末尾に単独で付いた文字）は取り除かれないため、「Hero — option B」と「Hero — option C」は別々のデザインとして保持されます。一致するものがない場合、または複数ある場合は、新しいデザインが作成されます。タイトルにかかわらず常に新しいデザインを作成するには、-F fold=false を指定します。自動統合されたアップロードのレスポンスには folded: true と、誤って一致した場合に元に戻す方法を示す note が含まれます。
• 特定のバージョンへの直接リンク： /view/{id}/v/{n} はそのバージョンを表示します。/view/{id} は、{id} がデザイン ID の場合は最新バージョンを、エイリアス ID の場合は固定されたバージョンを表示します（後述）。
• 統合後も以前のリンクは引き続き使えます。 モックアップが別のデザインに統合されると、その ID は統合されたバージョンに固定されたエイリアスになり、すべての読み取り（/view/…、get_mockup など）で透過的に解決されます。統合前に発行されたバージョンリンク（/view/{old id}/v/1）も引き続き使えます。
• バージョンを切り出したり削除したりすると、リンクは無効になります。 切り出されたバージョンは新しいデザインの v1 になるため、以前の /view/{design}/v/{n} リンクは 404 を返します（新しいデザインでは、バージョンにエイリアス ID がある場合はそれが再利用されるため、その ID は引き続き使えます）。バージョンを削除すると、そのバージョンと、それに固定されたエイリアスが削除されます。
• 統合を元に戻す： split_version(id, version) は、指定したバージョンを独立したデザインとして切り出し、エイリアス ID がある場合はそれを再利用します。

既存の重複を統合する（オプトイン、一度限り）

この機能が追加される前に、リビジョンを別々のモックアップとしてアップロードしていた場合は、python -m app.fold でそれらを検出して統合できます。

python -m app.fold --dry-run     # print the proposed groups, change nothing
python -m app.fold --apply       # perform them
python -m app.fold --dry-run --data-dir /path/to/copy   # run against another data directory

--data-dir を指定すると、設定済みのデータディレクトリではなく、別のデータディレクトリ（mockups.db を含むディレクトリ）をコマンドの対象にできます。実際に実行する前に、データのコピーで統合を試す場合に便利です。

同じプロジェクトと基本タイトルを持つデザインを古い順にグループ化し、各グループを1つのデザインに統合します（最も古いものが残り、それ以外はバージョンになり、以前の ID はエイリアスとして保持されます）。これは自動実行されません。一括統合は元に戻せないため、ドライランの出力を確認してから手動で実行するコマンドです（各デザインは split_version で個別に切り出して元に戻せます）。

MCP ツール

ツール	説明
send_mockup	HTML/SVG（生の文字列）またはPNG/JPG（base64）をギャラリーに送信します。parent と fold に対応しています（「バージョン」を参照）。ギャラリーのURLを返します。
list_mockups	モックアップを新しい順に一覧表示します。プロジェクトで絞り込むこともできます。
get_mockup	UUIDで指定したモックアップを、表示用URLとギャラリーURL、およびバージョン一覧とともに取得します。view_url にcurlを実行すると、ファイルの内容を読み取れます。
update_mockup	メタデータ（タイトル、説明、タグ）を更新するか、content を指定して新しいバージョンを追加します（以前のバージョンは保持されます）。
split_version	デザインの1つのバージョンを独立したモックアップに切り分けます。これはフォールドの逆操作です。
delete_mockup	モックアップを削除します。または、version を指定すると1つのバージョンのみを削除します。データベースのレコードとディスク上のファイルが削除されます。
tag_mockup	既存のモックアップにタグを追加または削除します。
set_created_at	モックアップ（または1つのバージョン）の作成日を変更します。アップロード日を過去に設定したり、タイムラインの順序を変更したりするのに便利です。

サーバーはすべてのコンテンツを永続的に保存します。AI クライアントは、不要になったローカルファイルを削除したり、後から get_mockup でコンテンツを取得したりできます。

API ルート

ルート	目的
GET /	ギャラリー UI
GET /view/{id}	生のモックアップ：デザインIDの最新バージョン、またはエイリアスIDに固定されたバージョン（HTMLはレンダリングされ、画像は適切なMIMEタイプで配信されます）
GET /view/{id}/v/{n}	生のモックアップ、特定の1つのバージョン
GET /api/mockups	limit、offset、project フィルターを指定できるJSON一覧
GET /api/mockups/{id}	versions 一覧を含む、単一のモックアップのメタデータ。?v={n} を指定すると、view_url がそのバージョンを指します
POST /api/mockups/{id}/versions/{n}/split	そのバージョンを独立したモックアップに切り分けます
DELETE /api/mockups/{id}/versions/{n}	1つのバージョンを削除します（最後に残ったバージョンの場合は拒否されます）
GET /api/projects	件数を含むプロジェクト一覧
POST /api/upload	モックアップファイルをアップロードします（マルチパートフォーム：file、project、title、description?、tags?、parent?、fold?）。「バージョン」を参照してください
GET /health	ヘルスチェック

セットアップ

1. クローンして設定する

git clone https://github.com/kgNatx/mockups-mpc.git
cd mockups-mpc

2. デプロイする

クイックスタート（ビルド済みイメージ）：

docker compose -f docker-compose.local.yml up -d
# Gallery available at http://localhost:8000

ソースからビルドする：

docker compose -f docker-compose.local.yml up -d --build

本番環境（Traefik を使用）：

cp .env.example .env
# Edit .env with your domain and Traefik network name
docker compose up -d --build

3. 確認する

curl http://localhost:8000/health
# {"status":"ok"}

4. Claude Code を接続する

claude mcp add-json mockups-gallery '{"type":"http","url":"https://your-domain.com/mcp"}'

または、.mcp.json（プロジェクト単位）または ~/.claude/.mcp.json（グローバル）に追加します：

{
  "mcpServers": {
    "mockups-gallery": {
      "type": "http",
      "url": "https://your-domain.com/mcp"
    }
  }
}

5. Claude Desktop を接続する

Claude Desktop の設定ファイルに追加します：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mockups-gallery": {
      "type": "sse",
      "url": "https://your-domain.com/mcp/sse"
    }
  }
}

6. AI に使用方法を指示する

CLAUDE.md（または同等のファイル）に指示を追加し、モデルのコンテキストを介してファイルの内容を渡すのではなく、curl 経由でモックアップをアップロードするようAIに伝えます：

# Mockups

When generating UI mockups, design concepts, or visual prototypes,
write the file locally then upload it to the Mockups MPC gallery via curl:

    curl -s -X POST https://your-domain.com/api/upload \
      -F file=@/path/to/file.html -F project=name -F title=name \
      [-F description=text] [-F "tags=a,b,c"]

To revise a mockup you already uploaded, add `-F parent=<id>` (the id
from the earlier upload response): the gallery keeps it as a new version
of the same design. Use `-F fold=false` only for a deliberate separate variant.

To read a mockup's content later, use `get_mockup` to get its
`view_url`, then curl it.

すべてのプロジェクトに適用する場合は ~/.claude/CLAUDE.md に、特定のプロジェクトに適用する場合はそのプロジェクトの CLAUDE.md に追加します。アプリ内のセットアップガイドにも同じスニペットがあります。既存のインストールでは、アップグレード後の初回起動時にセットアップガイドの新しいバージョンとして更新済みのガイドが追加されます。

ギャラリー UI

新規インストールでは、ギャラリーの最初の項目としてセットアップガイドが自動的に登録されます。このガイドには、コピー可能なコードブロックとともに、すべての設定方法が記載されています。

レイアウト： サイドバー（プロジェクト一覧＋タイトルフィルター付きの時系列フィード＋無限スクロール）＋メインビューアー（HTML用のiframe、画像/SVG用のimg）＋メタデータバー＋ポップアウトリンク。

テーマ： テクノ・シック・ミニマリスト — Space Grotesk、シアンのアクセント、亜鉛色／ニュートラルなダーク背景。

プロジェクト構成

app/
├── main.py          # FastAPI app, lifespan, MCP mount, router includes
├── config.py        # Settings (DATA_DIR, DB_PATH, BASE_URL from env)
├── db.py            # SQLite init + CRUD (WAL mode, aiosqlite)
├── models.py        # Pydantic models
├── storage.py       # Slug generation, file write/read/delete, 25MB limit
├── mcp_server.py    # FastMCP instance, tool logic, tool wrappers
├── seed.py          # Auto-seed setup guide on empty DB
├── routes/
│   ├── api.py       # JSON API endpoints
│   └── gallery.py   # Gallery page + raw mockup serving
├── templates/
│   └── gallery.html # Jinja2 gallery template
└── static/
    ├── style.css         # Gallery theme
    └── setup-guide.html  # Self-contained setup guide page

開発

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pytest tests/ -v
uvicorn app.main:app --reload

テストスイートでは、ストレージ、データベース、MCP ツール、API ルート、アップロード、ギャラリーをテストします。

ライセンス

MIT — LICENSE を参照してください。