Mockups Gallery

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

┌─────────────────┐     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= (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:

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

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

cd mockups-mpc

2. Deploy

Quick start (pre-built image):

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

Gallery available at http://localhost:8000

Build from source:

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

Production (with Traefik):

cp .env.example .env

Edit .env with your domain and Traefik network name

docker compose up -d --build

3. Verify

curl http://localhost:8000/health

{"status":"ok"}

4. Connect Claude Code

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):

{

"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

{

"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:

# 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= (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.

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: Tech