@snowcone-app/mcp

Prefer raw docs? The complete agent-facing text is one fetch away — https://developers.snowcone.app/llms-full.txt. Grep it before assuming a field or behavior is undocumented.

The agent-native quickstart for Snowcone. An MCP server that exposes the "a mockup is a URL" model as callable tools, so an agent (Claude, Cursor, Codex, …) goes from zero to a buyable printed-merch mockup in a few tool calls — no SDK install, no docs crawl.

Install

No global install needed — npx runs the server.

Claude Code (CLI):

claude mcp add snowcone -- npx -y @snowcone-app/mcp

Claude Desktop / Cursor / Codex (config block):

{
  "mcpServers": {
    "snowcone": {
      "command": "npx",
      "args": ["-y", "@snowcone-app/mcp"]
    }
  }
}

Then restart / reconnect the client and confirm it's live — the tools should appear (e.g. claude mcp list shows snowcone ✔, and snowcone_* tools are callable). If no snowcone_* tools show up, the server isn't actually connected: re-run the add command and restart, rather than proceeding (a registered-but-empty MCP connection fails silently). Once connected, call snowcone_quickstart first.

The server is self-contained (zero @snowcone-app/* runtime deps — the canonical URL builder is bundled in).

Tools

| Tool | What it does | |---|---| | snowcone_quickstart | The whole model + recommended tool order in one screen. Call this first. | | snowcone_mint_shop | Mint your own sandbox Shop ID — no account or human needed. | | snowcone_claim_status | Poll whether your human has claimed the shop (to get paid). | | snowcone_release_shop | Delete an unclaimed sandbox shop you minted. | | snowcone_search_catalog | Full-text search the public product catalog. | | snowcone_get_product | Placements / mockups / options for one product. | | snowcone_render_mockup | Build an <img>-ready mockup URL from a product + artwork + shop. | | snowcone_buy_url | Build the matching checkout URL. |

The happy path

1. snowcone_mint_shop once → get a shop_id (reuse it everywhere).
2. snowcone_get_product to pick a product code (BEEB77 is a good demo).
3. snowcone_render_mockup with the code, your shop_id, and a publicly fetchable image URL → an image URL you can drop anywhere.
4. snowcone_buy_url to sell it; hand claim.verification_uri_complete to your human to route the money to them.

Configuration

All hosts default to production and are overridable by env var, so the same server can drive local/staging stacks:

SNOWCONE_API_BASE, SNOWCONE_IMG_BASE, SNOWCONE_BUY_BASE, SNOWCONE_MEILI_HOST, SNOWCONE_MEILI_KEY, SNOWCONE_MEILI_INDEX.

Development

pnpm build       # bundle to dist/ (self-contained)
pnpm test        # hermetic CI gate: drives the server in-memory, locks the URL grammar
pnpm typecheck

The test suite (src/server.test.ts) connects a real MCP client to the server over an in-memory transport and asserts the exact public URL grammar — if the shared URL builder drifts, the gate fails. Network tools are dogfooded out-of-band so the gate stays fast and hermetic.