Mockups Gallery

io.github.kgNatx由 GitHub 帳號 kgNatx 發布v1.5.1更新於 Oct 25, 2026

Self-hosted gallery for AI-generated mockups. MCP interface; token-efficient curl uploads.

已驗證Streamable HTTP可網頁執行檔案與儲存媒體與設計

概覽

AI 產生的概覽

自架的 AI 生成 mockup 圖庫,提供 MCP 工具來上傳、列出、標記、管理版本與刪除 mockup,並附網頁瀏覽介面。

可以做什麼
以 HTML/SVG 字串或 base64 PNG/JPG 形式把 mockup 送到圖庫,可作為既有設計的新版本,並回傳圖庫連結。依時間倒序列出 mockup,可依專案篩選,並依 UUID 取得單一 mockup 的檢視連結、圖庫連結與版本清單。更新標題、描述、標籤等中繼資料,或新增版本並保留舊版本。新增或移除標籤,把某個版本拆回獨立設計,修改建立日期,刪除整個 mockup 或單一版本。在含專案側欄與時間軸的網頁圖庫中瀏覽全部內容。
適用情境
適合 AI 助理產生 UI mockup、設計概念或視覺原型後,希望集中保存在一個可瀏覽的地方,而不是散落在程式碼倉庫或暫存目錄中。適用於你自行掌控主機的可信本機或私有網路環境。
執行需求
需要自架實例:部署用 Docker,本機開發用 Python 3.12+,並掛載資料目錄以存放 SQLite 中繼資料與檔案。MCP 用戶端透過 HTTP 或 SSE 端點連線;README 也建議正式環境用 Traefik 等反向代理提供 TLS。
安裝前請注意
沒有內建身分驗證:所有 API 端點與 MCP 工具對任何能連上伺服器的人開放,因此只應部署在可信網路或負責驗證的反向代理之後。工具可更新、標記、拆分並永久刪除 mockup 及其磁碟檔案,儲存內容會永久保留。上傳也可透過無驗證的 HTTP 端點進行。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Mockups Gallery,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Web executable,透過 Streamable HTTP。 遠端服務在工作區中設定後即可從網頁執行環境執行。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

Mockups MPC

[CI] [License: MIT]

A self-hosted gallery for AI-generated mockups — with an MCP interface. Instead of cluttering your repo, mockups get a permanent home and a clean web gallery you can browse. AI tools upload them over a direct curl call; MCP handles only the lightweight coordination — listing, metadata, tagging, and retrieval.

Token-efficient by design. MCP tool parameters flow through the model context, so sending a large HTML file via a tool call wastes tokens. Mockups MPC provides an HTTP upload endpoint (POST /api/upload) — the AI writes the file locally and curls it to the server, keeping file content entirely out of the model context. MCP tools handle lightweight operations only: listing, metadata, tagging, and deletion.

[Mockups MPC — gallery demo]

Prerequisites

  • Docker (for deployment) or Python 3.12+ (for local development)
  • An MCP-compatible AI client (Claude Code, Claude Desktop, etc.)
  • Optional: Traefik reverse proxy (for production with TLS)

Why

Every time an AI tool generates a mockup, there's no consistent place for it to go — so they pile up in your repo or get scattered across temp dirs, sessions lose track of them, and there's no history. Mockups MPC gives them a permanent home instead: the AI pushes the mockup to the gallery, you browse it there, and the local file gets cleaned up. One place for everything, nothing cluttering your project.

Architecture

┌─────────────────┐     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  │  │                                           │  └────────────────┘  │                                           └──────────────────────┘

Single Docker container running a FastAPI app that serves two roles:

  1. MCP Server — mounted at /mcp/ (HTTP transport) and /mcp/sse (SSE transport). AI tools connect here to send and manage mockups.
  2. Web Gallery — served at /. Sidebar with project list and chronological feed, main viewer with iframe/image display.

Data Layer

  • SQLite in WAL mode — metadata catalog (project, title, description, tags, content type, timestamps)
  • Filesystem — mockup files stored in data/{project_slug}/{uuid}.{ext}
  • Storage is a bind-mounted data/ directory next to the compose file

Tech Stack

  • Python 3.12
  • FastAPI + uvicorn
  • fastmcp v3.x (standalone)
  • SQLite via aiosqlite
  • Jinja2 templates + vanilla JS
  • Docker + Traefik

Security

There is no built-in authentication. All API endpoints and MCP tools are open to anyone who can reach the server. This is designed for trusted networks (LAN, VPN, Tailscale) or behind a reverse proxy that handles auth. If you deploy this on a public network, add authentication at the proxy layer.

Versions

A mockup ("design") can hold more than one version — every revision of the same screen, kept in one place instead of scattering separate mockups.

  • Add a version to an existing design: upload with -F parent=<id> (a design or alias id). It's added as the next version; earlier versions and their files are kept.
  • Auto-fold: upload without parent and the server still checks for a match. If exactly one design in the same project has the same base title — the title with trailing markers like v2, draft 3, rev 2, r5, a bare trailing number, or trailing parentheticals such as (rail fixed) stripped — the upload becomes a new version of it automatically. Variant markers (option B, variant C, a standalone trailing letter) are never stripped, so "Hero — option B" and "Hero — option C" stay separate designs. Zero or several matches also create a new design. Pass -F fold=false to always create a new design regardless of title. An auto-folded upload's response carries folded: true and a note saying how to split it back out if the match was wrong.
  • Direct link to one version: /view/{id}/v/{n} serves that exact version. /view/{id} serves the latest version when {id} is a design id, and the pinned version when {id} is an alias id (see below).
  • Folding keeps old links working. When a mockup is folded into another design, its id becomes an alias pinned to the version it turned into, and every read (/view/…, get_mockup, etc.) resolves it transparently. A version link minted before the fold (/view/{old id}/v/1) keeps working too.
  • Splitting and deleting a version do remove links. A split-out version moves to its new design as v1, so its old /view/{design}/v/{n} link returns 404 (the new design reuses the version's alias id when it has one, so that id keeps working). Deleting a version removes it and any alias pinned to it.
  • Undo a fold: split_version(id, version) pulls one version back out into its own standalone design, reusing its old alias id if it has one.

Merging existing duplicates (opt-in, one-time)

If you were already uploading revisions as separate mockups before this feature existed, python -m app.fold finds and merges them:

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

--data-dir points the command at a different data directory (the one holding mockups.db) instead of the configured one — useful for trying the fold on a scratch copy of your data before running it for real.

It groups designs that share a project and a base title, oldest first, and folds each group into one design (the oldest survives; the rest become versions, with their old ids kept as aliases). This never runs automatically — it's a command you run by hand, and only after reviewing the dry-run output, since merging is not reversible in bulk (each design can still be split back out individually with split_version).

MCP Tools

ToolDescription
send_mockupSend HTML/SVG (raw string) or PNG/JPG (base64) to the gallery. Supports parent and fold (see Versions). Returns a gallery URL.
list_mockupsList mockups reverse-chronologically, optionally filtered by project.
get_mockupGet a specific mockup by UUID with view and gallery URLs, plus its version list. Curl the view_url to read the file content.
update_mockupUpdate metadata (title, description, tags), or add a new version by supplying content (earlier versions are kept).
split_versionSplit one version out of its design into its own standalone mockup — reverses a fold.
delete_mockupDelete a mockup, or (with version) just one version — removes the DB record(s) and file(s) on disk.
tag_mockupAdd or remove tags on an existing mockup.
set_created_atChange the created date of a mockup (or one version). Useful for backdating uploads or reordering the timeline.

The server stores all content permanently. AI clients can clean up local files when they're no longer needed, or retrieve content later via get_mockup.

API Routes

RoutePurpose
GET /Gallery UI
GET /view/{id}Raw mockup: the latest version for a design id, the pinned version for an alias id (HTML rendered, images served with correct MIME type)
GET /view/{id}/v/{n}Raw mockup, one specific version
GET /api/mockupsJSON listing with limit, offset, project filter
GET /api/mockups/{id}Single mockup metadata, including its versions list; ?v={n} points view_url at that version
POST /api/mockups/{id}/versions/{n}/splitSplit that version out into its own standalone mockup
DELETE /api/mockups/{id}/versions/{n}Delete one version (refused on the last remaining one)
GET /api/projectsProject list with counts
POST /api/uploadUpload a mockup file (multipart form: file, project, title, description?, tags?, parent?, fold?) — see Versions
GET /healthHealth check

Setup

1. Clone and configure

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

2. Deploy

Quick start (pre-built image):

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

Build from source:

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

Production (with Traefik):

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

3. Verify

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

4. Connect Claude Code

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

Or add to .mcp.json (project-level) or ~/.claude/.mcp.json (global):

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

5. Connect Claude Desktop

Add to your Claude Desktop config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json
json
{  "mcpServers": {    "mockups-gallery": {      "type": "sse",      "url": "https://your-domain.com/mcp/sse"    }  }}

6. Tell your AI to use it

Add instructions to your CLAUDE.md (or equivalent) so your AI uploads mockups via curl instead of passing file content through the model context:

markdown
# 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 idfrom the earlier upload response): the gallery keeps it as a new versionof 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.

Add to ~/.claude/CLAUDE.md for all projects, or a project's CLAUDE.md for specific ones. The in-app Setup Guide carries the same snippet; an existing install gets the updated guide as a new version of its Setup Guide on the first start after upgrading.

Gallery UI

The gallery auto-seeds a Setup Guide as the first entry on fresh installs. The guide covers all configuration methods with copy-able code blocks.

Layout: Sidebar (project list + chronological feed with title filter + infinite scroll) + main viewer (iframe for HTML, img for images/SVG) + metadata bar + pop-out link.

Theme: Techno Chic Minimalist — Space Grotesk, cyan accents, zinc/neutral dark backgrounds.

Project Structure

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

Development

bash
python -m venv .venvsource .venv/bin/activatepip install -r requirements.txtpytest tests/ -vuvicorn app.main:app --reload

The test suite covers storage, database, MCP tools, API routes, upload, and gallery.

License

MIT — see LICENSE.

來源:README.md,提交 d619d8f

工具

0
SourceWeft 尚未讀取此伺服器的工具。

版本歷史

4
  1. v1.5.1最新Sep 25, 2026
  2. v1.5.0Sep 24, 2026
  3. v1.4.3Sep 23, 2026
  4. v1.4.1Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通必需25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式必需10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分