
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.
概览
自托管的 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。
安装
在 SourceWeft 中
- 打开 控制台中的 Mockups Gallery,将其添加到工作区。
- 为需要使用其工具的对话启用该服务。
Web executable,通过 Streamable HTTP。 远程服务在工作区中配置后即可从网页运行时运行。
其他 MCP 客户端
参照 仓库 中的启动说明。
README
Mockups MPC
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.
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
Single Docker container running a FastAPI app that serves two roles:
- MCP Server — mounted at
/mcp/(HTTP transport) and/mcp/sse(SSE transport). AI tools connect here to send and manage mockups. - 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
parentand 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 likev2,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=falseto always create a new design regardless of title. An auto-folded upload's response carriesfolded: trueand anotesaying 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:
--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
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
Setup
1. Clone and configure
2. Deploy
Quick start (pre-built image):
Build from source:
Production (with Traefik):
3. Verify
4. Connect Claude Code
Or add to .mcp.json (project-level) or ~/.claude/.mcp.json (global):
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
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:
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
Development
The test suite covers storage, database, MCP tools, API routes, upload, and gallery.
License
MIT — see LICENSE.
来源:README.md,提交 d619d8f
工具
0版本历史
4- v1.5.1最新Sep 25, 2026
- v1.5.0Sep 24, 2026
- v1.4.3Sep 23, 2026
- v1.4.1Sep 16, 2026
评分
已满足适用检查项的 50%
该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。
- 近 30 天内可连通必需25 分
请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。
- 已声明认证方式必需10 分
请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。
- 已列出工具15 分
请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。
- 描述必需15 分
- 图标10 分
- 文档15 分
- 许可证10 分