mcp-mockuuups: Instructions file for Claude Code

CLAUDE.md

MCP server wrapping the Mockuuups Studio REST API. Part of the CDIT MCP fleet — fleet conventions live in the cdit OpenSpec store; this file covers what is specific to this repo.

The upstream API, as it actually behaves

The published reference at mockuuups.studio/api/docs/ is behind a login wall. What follows was verified against the live API on 2026-08-25 and is the reason several design choices look the way they do.

GET  /v1/account       plan, features, credit balance
GET  /v1/mockups       the catalog
GET  /v1/mockups/{id}  one mockup
POST /v1/renders       {mockup, size, mode, destination, contents[]}
GET  /v1/renders/{id}  poll an async render

Four behaviours that are load-bearing here:

1. The catalog endpoint has no search. q, search, type, family and tag are accepted and silently ignored — every call returns the same unfiltered page. limit does work, and limit=6000 returns all 5314 mockups (~3.3MB) in one response. Hence catalog.py: fetch once, cache, search locally.
2. Omitting size means hi-res, which fails the whole render with feature-not-available on any plan lacking that feature. client.py always sends size explicitly. Never make it optional upstream.
3. contents[].url is mandatory. There is no upload endpoint, no base64 field, no data-URI support. Rendering a locally-held image requires hosting it somewhere Mockuuups can fetch — that is what uploads.py is for.
4. contents must have one entry per placement, in order. All but two of the 5314 mockups have exactly one placement.

Errors come back as {"error": {"code", "message", "detail"}}; client._explain turns the ones that matter into actionable messages.

Why renders are async

A synchronous screenshot render measured 17.3s. Clients reach this server through a Cloudflare MCP portal with a hard ~60s upstream read timeout that we cannot change, so a handful of sequential sync renders gets severed mid-flight (the same trap mcp-bildsprache documents in its config).