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 容器，提供两种功能：

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），或部署在负责处理身份验证的反向代理后面。如果将其部署到公共网络，请在代理层添加身份验证。

版本

一个模型稿（“设计”）可以包含多个版本——将同一屏幕的每次修订保存在同一处，而不是分散到多个模型稿中。

• 向现有设计添加版本： 使用 -F parent=<id>（设计 ID 或别名 ID）上传。它会作为下一个版本添加；较早的版本及其文件都会保留。
• 自动归并： 不带 parent 上传时，服务端仍会检查是否存在匹配项。如果同一项目中恰好有一个设计具有相同的基础标题——即去掉尾部标记后的标题，例如 v2、draft 3、rev 2、r5、单独的尾随数字，或 (rail fixed) 这类尾随括号内容——上传内容会自动成为该设计的新版本。变体标记（option B、variant C、单独的尾随字母）绝不会被去掉，因此 “Hero — option B” 和 “Hero — option C” 会保留为独立设计。没有匹配项或存在多个匹配项时，也会创建新设计。传入 -F fold=false 可强制创建新设计，不论标题如何。自动归并的上传响应会包含 folded: true，以及一条说明如何将其拆分回来的 note（以防匹配有误）。
• 直接链接到某个版本： /view/{id}/v/{n} 会提供指定版本。当 {id} 是设计 ID 时，/view/{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，则会复用该 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），而不是使用已配置的目录——这适用于先在数据副本上试运行归并，再正式执行。

该命令会按项目和基础标题对设计分组，并按创建时间从早到晚排列，然后将每组归并为一个设计（最早的设计会保留；其余设计会成为版本，并保留各自的旧 ID 作为别名）。此操作绝不会自动运行——必须手动执行，而且只能在检查试运行输出后执行，因为批量归并无法撤销（仍可使用 split_version 将每个设计单独拆分回去）。

MCP 工具

工具	描述
send_mockup	将 HTML/SVG（原始字符串）或 PNG/JPG（base64）发送到图库。支持 parent 和 fold（参见版本）。返回图库 URL。
list_mockups	按时间倒序列出模型稿，可选择按项目筛选。
get_mockup	根据 UUID 获取指定模型稿及其查看和图库 URL，以及版本列表。使用 curl 访问 view_url 可读取文件内容。
update_mockup	更新元数据（标题、描述、标签），或通过提供 content 添加新版本（保留早期版本）。
split_version	将设计中的一个版本拆分为独立模型稿——即撤销折叠。
delete_mockup	删除模型稿，或（提供 version 时）仅删除一个版本——同时移除数据库记录和磁盘上的文件。
tag_mockup	为现有模型稿添加或移除标签。
set_created_at	更改模型稿（或某个版本）的创建日期。适用于回填上传日期或调整时间线顺序。

服务会永久存储所有内容。AI 客户端可以在不再需要时清理本地文件，或稍后通过 get_mockup 检索内容。

API 路由

路由	用途
GET /	图库 UI
GET /view/{id}	原始模型稿：设计 ID 对应的最新版本，别名 ID 对应的固定版本（HTML 会渲染，图片会以正确的 MIME 类型提供）
GET /view/{id}/v/{n}	原始模型稿的指定版本
GET /api/mockups	JSON 列表，支持 limit、offset、project 筛选
GET /api/mockups/{id}	单个模型稿的元数据，包括其 versions 列表；?v={n} 会将 view_url 指向该版本
POST /api/mockups/{id}/versions/{n}/split	将该版本拆分为独立模型稿
DELETE /api/mockups/{id}/versions/{n}	删除一个版本（若这是最后一个剩余版本，则拒绝删除）
GET /api/projects	项目列表及计数
POST /api/upload	上传模型稿文件（multipart 表单：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（或同等文件）中添加说明，让 AI 通过 curl 上传模型稿，而不是通过模型上下文传递文件内容：

# 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。