kgnatx/mockups-mpc

Summary

Mockups MPC is a self-hosted FastAPI server that acts as both an MCP (Model Context Protocol) tool server and a web gallery for AI-generated UI mockups. AI clients like Claude Code connect via MCP to list, tag, and delete mockups, while actual file uploads happen via a separate HTTP multipart endpoint to avoid burning tokens on large file content. Everything is stored in SQLite + filesystem and browsable in a Jinja2/vanilla-JS gallery.

Great for

people interested in building MCP-native developer tooling that integrates directly into AI coding workflows — specifically around managing AI-generated artifacts without polluting the model context window

Easy wins

• +Add search/filter by tag in the gallery UI — the API already returns tags in every response, the JS sidebar just doesn't use them yet
• +Add pagination controls to the gallery frontend — infinite scroll is mentioned in README but the JS would need implementing against the existing ?limit&offset API
• +Add authentication middleware option (e.g., a static Bearer token via env var) — the README explicitly calls this out as missing and defers to proxy-layer auth
• +Add a MIME type guard on the /api/upload endpoint — currently relies only on file extension from the filename string, which is trivially spoofable

Red flags

• !No authentication whatsoever — the README acknowledges this but the /api/upload endpoint accepting arbitrary file writes with no auth on a misconfigured deployment is a real risk; there's no env-var token option even as a basic safeguard
• !Only one commit total — this is a brand-new repo with zero community; there is no track record of maintainer responsiveness
• !No lockfile (no poetry.lock, no uv.lock, no pip-compile output) — requirements.txt uses >= ranges, so builds are not reproducible across time
• !The 'last_commit_at' date is 2026-03-16, which is in the future relative to current date — this may indicate the system clock was wrong during commit or the data is synthetic/test data

Code quality

The internal-logic/MCP-wrapper separation in mcp_server.py is a genuinely smart testability decision — all business logic lives in _send_mockup, _delete_mockup, etc., and the FastMCP tool decorators are thin wrappers that just convert ValueError to ToolError. The db.py _UNSET sentinel pattern for distinguishing 'not provided' vs. None on description updates is correct and avoids a common NULL-clearing bug. The test suite is thorough and tests real file I/O via tmp_data_dir fixtures. One minor issue: storage.py is not included in the samples but the 25MB limit is mentioned in the README — worth verifying it's enforced on the /api/upload route too, not just the MCP path.

What makes it unique

The token-efficiency argument is the genuinely novel angle here — routing large file content through curl rather than MCP tool parameters is a real, practical insight about how MCP tool calls consume context. Most 'MCP gallery' type projects just pipe everything through tool responses. That said, this is a very early-stage solo project with 0 stars and 1 commit, so its differentiation is unproven in the wild.