# minshop

Small store for Cloudflare Workers with a JSON agent API and a two-tier MCP server.

minshop is an Astro store that runs on Cloudflare Workers with D1 and R2, an admin, and Stripe, Lightning, OpenNode or demo payment rails. An agent can browse and pay through a public JSON API or a separate MCP Worker. With an operator token the MCP server also lists orders, creates and updates products, and fulfills orders.

- Capabilities: adaptable, operable
- Vertical: ecommerce
- Shape: business-app
- Form factor: web-app
- Execution model: deterministic
- Provenance: unknown (recorded, never ranked)
- Repo: https://github.com/ddyy/minshop (MIT), 190 stars, last commit 2026-08-11
- Last activity: 2026-08-11
- Page: apps/ddyy--minshop.html
- JSON: apps/ddyy--minshop.json

## Use it when

- you sell small or digital goods and want agents to shop and pay with Lightning
- you want a store on the Cloudflare free tier that your own agent can run over MCP

## Gotchas

- The MCP server is a separate Worker with its own deploy and its own MCP_TOKEN
- Operator MCP tools write live data; the bearer token is a single shared secret
- Store settings are in D1 through the admin, so theme edits do not cover them
- Node 22.12 or newer is required
- Single maintainer; repo created 2026-07-20. No commit on main since 2026-08-11, and 14 outside pull requests sit open with no reply

## Editions

- Free: Free, open source
  - source: https://github.com/ddyy/minshop
  - installable: npm create minshop@latest my-store
  - one-click: https://deploy.workers.cloudflare.com/?url=https://github.com/ddyy/minshop

## Adaptable: make it yours

Effort: light-edit (11 things to edit), surface kind admin-ui

The Worker needs two secrets, AUTH_SECRET and SECRETS_KEK. Store name, time zone, payments, shipping, email and search are set in Admin > Settings and kept in D1, with provider keys encrypted. Theme and look are source files under src/themes plus src/styles/overrides.css, built at deploy time. src/store.config.ts holds build-time overrides such as currency. So adapting the store means editing theme source.

- Env vars: AUTH_SECRET, SECRETS_KEK, MCP_TOKEN, MCP_URL, STOREFRONT_URL
- Config files: wrangler.jsonc, src/store.config.ts, theme.config.json, src/themes/<your-theme>/tokens.css, src/styles/overrides.css, .dev.vars
- Prompt files: none
- Accounts you'll need: Cloudflare; Stripe (optional); Lightning node or OpenNode (optional); Resend (optional)

## Operable: what an agent can drive

Operability: official. Interface: mcp at https://github.com/ddyy/minshop/tree/main/mcp (published by the builder, both).

### Reach (partial coverage)

- Browse and search the catalog: reachable. MCP tools browse_products, get_product_details; GET /api/products
- Check out and pay: reachable. MCP tools payment_methods, create_checkout; POST /api/checkout returns checkout_url and order_status_url
- Track an order's status and downloads: reachable. MCP tool check_order_status; GET /order/:token/status
- Create and update products: reachable. operator MCP tools create_product, update_product, list_products, get_product
- View and fulfill orders: reachable. operator MCP tools list_orders, get_order, fulfill_order
- See revenue and daily totals: reachable. operator MCP tools order_stats, daily_totals
- Edit categories, pages and media: not reachable. mcp/src/index.ts registers no tools for categories, Markdown pages or the media library
- Configure shipping, payments and email: not reachable. README: set in Admin > Settings; no MCP tool for settings
- Refunds and customers: not reachable. No refund or customer tool among the 14 MCP tools
- Edit theme templates: not reachable. CUSTOMIZING.md: themes are source files compiled at deploy time

## Code stack

- Languages: TypeScript
- Frameworks: Astro, Tailwind CSS
- Package manager: npm
- Database: Cloudflare D1
- Hosting target: Cloudflare Workers, Cloudflare R2

## Evidence and confidence

- formFactor: README: Astro SSR store on Cloudflare Workers with admin (confidence 0.95)
- executionModel: no model at runtime; optional Workers AI search (confidence 0.9)
- operability: README calls the MCP server optional beside a server-rendered store with a full admin, and settings are reached only through the admin, so the agent is not the primary interface: official. mcp/src/index.ts registers 14 tools (5 buyer, 9 operator); initialize on demo-mcp.minshop.dev/mcp returned 200 (confidence 0.85)
- effort: CUSTOMIZING.md names each store-owned file and says you edit source, build and deploy; src/store.config.ts holds currency and order numbers; the README says provider keys and store settings are in Admin (confidence 0.75)
- editions: MIT; no paid edition; hosting runs on the Adopter's own Cloudflare account (confidence 0.8)
- active: main last commit 2026-08-11 (MCP buyer tier, real development); release v0.2.0 on 2026-07-31; later pushes are Dependabot branches
- users: Outside users: one outside contributor filed issues and PRs for Royal Mail, SumUp and PayPal; three others also contributed; 65 forks, and one fork has its own branding commits
- reach:  (confidence 0.9)
- provenance:  (confidence 0.3)

## Open questions

- Is the project still maintained? The owner has not committed or replied since 2026-08-11, and npm shows 39 create-minshop downloads in the last month.

## Sources

- https://minshop.dev (sourcing:ecommerce:community)
- https://github.com/ddyy/minshop (analysis)