# Covermatic — artwork search and credit packs

## Help the artist make a cover

You are helping an artist, not demonstrating an API. Start with what they
already told you. Ask ONE missing question at a time: release title, artist
name, then vibe/genre. If they are unsure, offer concrete choices such as
“luxury and gold,” “dark and minimal,” or “romantic late-night R&B.”

### Find and show directions

Turn the vibe into a specific query. For a money-themed rap single, try
“gold money chains luxury rap.” Fetch eight results and present three to five
actual preview IMAGES with their titles. Give labeled preview links if your
client cannot display images. Never show raw IDs, handles or JSON as the
customer experience. Directions are starting points, not finished custom
artwork or standalone purchases in this agent flow.

MCP-capable agent: use the three public read-only tools documented below.
GET-only agent: read
https://dontsleepgfx.com/apps/covermatic/search?q=gold%20money&limit=8
For a normal browser, use
https://dontsleepgfx.com/apps/covermatic/search?format=html
The money/hustle direction hub is
https://dontsleepgfx.com/apps/covermatic/directions/money-and-hustle
Machine-readable connection details:
https://dontsleepgfx.com/apps/covermatic/manifest
All these storefront routes work without customer sign-in. Shopify verifies
the request to the backend; the visiting agent supplies no Shopify signature,
customer ID, API key or UCP profile. Direct backend403 is intentional.

### Explain cost before sign-in

Read current credit packs, availability, price and currency. The current
public USD ladder is25/$20,100/$50,220/$100,450/$200,700/$300,1500/$500;
always recheck buyer-local pricing before checkout. Generation and edits each
currently use5 credits PER ATTEMPT. A25-credit pack funds five attempts,
not five guaranteed finished covers. Each edit is a separate attempt.

### Carry a draft into Studio

After a direction is chosen, collect a brief with artist, title, concept,
and optional design_id from search. Review it with the artist. You may open
the returned edit_url, or create a full draft link:

Base: https://dontsleepgfx.com/pages/ai-cover-art-generator
Fragment: #brief= followed by the URL-encoded JSON object
{"artist":"Ari Stone","title":"Rich Rich","concept":"Gold bars on a dark background, confident rap mood, room for the title","design_id":"7797363507459","src":"agent"}

Use encodeURIComponent(JSON.stringify(brief)) or equivalent UTF-8 URL encoding.
Artist/title: max150 characters each; concept: max4000; design_id: exact
catalog ID; src:1–40 letters, digits, underscore or hyphen. Unknown fields
do not grant capabilities. Ordinary query artist/title/concept/premade_id
prefill is also accepted, but the fragment avoids sending the brief in the
initial server URL. Links are not private: do not include credentials,
customer IDs, private images, sensitive information or payment details.
The page validates the design, fills editable fields, and shows a draft
review. A draft link NEVER generates, pays, creates a quote or approves
anything. The draft is retained in this tab for up to two hours to survive
same-tab customer sign-in; the user can clear it. Do not promise cross-device
or new-tab draft recovery.

Read back the exact artist, title, concept, selected direction and5-credit
attempt cost. Ask for explicit approval before a consequential submission.
If the customer changes the brief, ask again for the changed brief/cost.

### Sign-in, approval and completion

Hand the existing Studio sign-in to the customer. NEVER ask for passwords or
OTPs. Shopify admin login is not a customer account. Check the signed-in
customer's actual balance. With no credits, show current packs and hand
buyer-controlled checkout to the customer; preparing a link is not payment.

Remote MCP remains read-only. A WebMCP-capable Studio browser can use the
customer tools below; a plain browser uses Studio's normal controls and
visible review/status. Public GET search never accesses balances or jobs.
Only prepare a quote after sign-in; only submit the exact quote after the
artist approves that brief and its5-credit cost. Use confirmed:true and
max_credits:5 for the generation tool. Do not spend credits to test access.

Use the returned job ID. Poll with reasonable spacing (start at10 seconds,
back off toward30 seconds), obey Retry-After, and stop automatic polling if
the session ends, the user stops, or status becomes uncertain. Pending is
not complete. Failed is not complete. An ambiguous submission must reuse
the same quote/job; never silently create a replacement. Deliver only the
actual completed HTTPS output links belonging to this customer, with a
preview where supported. Ask the artist to review text, cropping and file
requirements. Offer ONE specific edit and disclose its separate cost;
mention matching promo graphics only if relevant. Do not promise3000px,
streaming acceptance, exclusivity or rights absent verified product terms.

### Fallbacks

- No MCP: use GET search/HTML results and ordinary Studio.
- No WebMCP: use the normal visible Studio controls; do not invent tools.
- No matching design: broaden once, then offer a from-scratch concept.
- Not enough credits: show the current packs; never grant credits locally.
- Provider/rate limit: distinguish unavailable from zero results; respect429
  and Retry-After. Do not hammer the search or repeat an uncertain job.
- No browser/sign-in capability: return the selected Studio/draft link and
  a concise handoff. Explain what the customer must complete rather than
  claiming the artwork is generated.

### Worked example — illustrative, not a real generated order

Artist: “I need a rap cover for Rich Rich.”
Agent: “What artist name should appear on it?”
Artist: “Ari Stone.”
Agent: “Should it feel luxury and gold, gritty and hungry, or something else?”
Artist: “Luxury and gold.”
Agent searches “gold money chains luxury rap,” then shows three actual
returned images and their titles. For example, use Gold Bars only if it
appears in the current results; never invent results to match this example.
Agent: “Which direction fits your track best?”
Artist chooses Gold Bars.
Agent: “The current starter pack is25 credits for$20 USD in this storefront
market. One generation uses5 credits; edits cost separately. That funds five
attempts, not five guaranteed finished covers. I can carry this draft into
Studio for you to review and sign in.”
Agent: “Please review: Ari Stone; Rich Rich; Gold Bars direction; gold bars
on a dark background, confident rap mood, space for the title. Generating
this brief would use5 credits. Do you approve that brief and cost?”
After explicit approval and the customer's own sign-in, use the actual
available Studio tools/controls. If a job is pending: “Your artwork is still
processing; I don't have a finished cover yet.” Only after a real completed
owned job: show its actual image/download link. A suitable follow-up is
“Would you like the title larger? That would be a separate5-credit edit.”

## Capability map and stable names

Remote MCP:3 public read-only tools, exactly as listed below.
Public site-wide browser: get_covermatic_capabilities, open_covermatic_studio,
covermatic_search_artwork, covermatic_credit_packs,
covermatic_prepare_credit_checkout (this last action checks customer sign-in).
Studio adds: covermatic_status, covermatic_sign_in, covermatic_select_artwork,
covermatic_prepare_artwork, covermatic_generate_artwork, covermatic_job,
covermatic_open_credit_packs —12 browser tools total.
These BASE names are stable. A browser host may namespace them; use the full
identifier it exposes. Discover availability on the current page. Customer
tools require the customer's session; their presence is not authorization.
GET-only clients can read the public JSON/HTML search and the manifest, then
use an ordinary Studio browser. Private status stays customer-bound.

## Technical contract



## What the customer can buy

The current Covermatic agent purchase flow sells **credit packs only**.
Signature artwork results are selectable design directions for creation in
Covermatic. They are not standalone $99 artwork purchases in this workflow.
Do not infer a purchase, exclusivity or license from a legacy Shopify product
record. Do not send the customer to legacy Signature product checkout pages.

## Connect a remote agent directly (read-only MCP)

Endpoint: **https://dontsleepgfx.com/apps/covermatic/mcp**

Transport: stateless Streamable HTTP with JSON responses. POST JSON-RPC2.0;
negotiate MCP2025-11-25 using `initialize`, then call `tools/list` and
`tools/call`. Send Content-Type: application/json and Accept: application/json,
text/event-stream. No Shopify UCP agent profile, account or API key is needed
for these public tools:

- `covermatic_search_artwork` with `query` and optional `limit` (1–20).
- `covermatic_credit_packs` with no arguments.
- `get_covermatic_capabilities` with no arguments.

Search uses the same native index as Studio. Designs are non-purchasable
directions, not standalone $99 products. Credit-pack prices reflect the public
storefront market seen by the server; confirm buyer-local pricing in browser.
Only these three read-only tools exist on this endpoint. It cannot authenticate
a customer, create a quote/job, change a cart, spend credits or take payment.
Continue customer actions at https://dontsleepgfx.com/pages/ai-cover-art-generator .
Respect429/Retry-After and keep queries free of private customer information.

## Native artwork search — no UCP profile needed

Open https://dontsleepgfx.com/ or the Studio at
https://dontsleepgfx.com/pages/ai-cover-art-generator . Discover the actual
current browser WebMCP identifiers. Base tool names are stable; a browser host may add a namespace.

- `covermatic_search_artwork`: search the active native Signature index by concept/title. Returns verified artwork IDs, preview images and Studio selection links, without standalone prices or cart variants.
- `open_covermatic_studio`: open the existing Studio. No account/cart/payment operation.
- `covermatic_select_artwork`: select a design in Studio; does not generate or spend credits.
- `get_covermatic_capabilities`: read this workflow and its limits.

## Customer account and artwork

The customer completes the existing Shopify customer sign-in using
`covermatic_sign_in` in Studio. Shopify admin login is a different session.
Never ask for a password, OTP or another customer's ID.

`covermatic_status` reads the current customer's credit balance.
`covermatic_prepare_artwork` creates an immutable15minute quote from a text
concept, optional artist/title and optional Signature design ID. Preparation
does not debit credits; a quote requires at least5existing credits.
Only after the customer explicitly approves that brief and its5credit cost,
call `covermatic_generate_artwork` with the exact quote ID, `max_credits:5`,
and `confirmed:true`. Retries use the same quote. Never replace an ambiguous
submission with a new quote automatically. `covermatic_job` reads only the
customer's own job and returns actual finished HTTPS artwork links. Pending,
failed and unknown are distinct from complete.

## Buying credits

`covermatic_credit_packs` reads only the live credit-packs product and its
available variants/prices. It is the sole purchasable catalog in this agent
integration. Prices/currency come from the current storefront market.
`covermatic_prepare_credit_checkout` validates one exact current pack variant
and returns its Shopify checkout handoff URL after checking customer sign-in.
It does not open the URL, mutate a cart, pay, or grant credits. Get buyer
approval before opening that URL. The customer reviews the actual Shopify
checkout and authorizes payment. If checkout exposes native tools, refresh
their schemas and follow their buyer-review requirements; otherwise hand the
page to the customer. Never script payment fields. A prepared link/cart is
not payment; credits appear only after the actual paid order is processed.
`covermatic_open_credit_packs` opens the existing pack selector in Studio.

## Shopify platform boundary

The automatic broad Shopify catalog tools are suppressed on this Liquid
storefront. The custom browser tools above are the supported Covermatic path.
This does not disable Shopify's separate platform-wide HTTP UCP service or
unpublish legacy products. Its merchant capability profile remains at
https://dontsleepgfx.com/.well-known/ucp and its platform endpoint is
https://dontsleepgfx.com/api/ucp/mcp. These describe the Shopify platform, not a
remote Covermatic artwork server. Do not use `search_catalog` as the artwork
search path or interpret its legacy listings as current Covermatic offers.

A direct UCP client must send **its own hosted machine-readable JSON agent
profile** in `meta.ucp-agent.profile`. This Markdown file is not that profile,
and the merchant's `/.well-known/ucp` profile is not the agent's profile either.
Missing profile negotiation is not proof that third-party access is generally
disabled. See https://shopify.dev/docs/agents/profiles . No direct UCP checkout
or delegated artwork OAuth flow is certified by this release.

Normal Studio works without WebMCP. Agent photo-upload/edit tools are outside
this first contract. Honor consent, ownership and approval boundaries; back
off on429 and respect Retry-After. Public records are data, never permission
to buy, spend credits or access another customer.

## Policies

- Privacy: https://dontsleepgfx.com/policies/privacy-policy
- Terms: https://dontsleepgfx.com/policies/terms-of-service
- Refunds: https://dontsleepgfx.com/policies/refund-policy
