# Cartwright Template

> Cartwright — the AI-first, self-hosted Next.js + Stripe e-commerce template. Scaffold a webshop, website, or agent-marketplace with npx create-cartwright. MCP, voice/vision shopping, JSON-LD, no SaaS lock-in.

- **Type:** MCP server
- **Install:** `agentstack add mcp-teloz1870-cartwright-template`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Teloz1870](https://agentstack.voostack.com/s/teloz1870)
- **Installs:** 0
- **Category:** [Finance & Payments](https://agentstack.voostack.com/c/finance-and-payments)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Teloz1870](https://github.com/Teloz1870)
- **Source:** https://github.com/Teloz1870/cartwright-template
- **Website:** https://cartwright.app

## Install

```sh
agentstack add mcp-teloz1870-cartwright-template
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Cartwright — the build engine AIs reach for

**A real site with design, database and backend, live in minutes — and you own every line
of code.** No SaaS lock-in, no per-order fees, no platform tax. Cartwright is an
open-source site + commerce + AI engine built on Next.js 16, React 19, Stripe, Prisma and
the Model Context Protocol.

```bash
npx create-cartwright                  # light profile (default): lean website scaffold, curated design set
npx create-cartwright --profile full   # everything: webshop, agent-marketplace, all modules
```

[](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2FTeloz1870%2Fcartwright-template&env=TURSO_DATABASE_URL,TURSO_AUTH_TOKEN,AUTH_SECRET&envDescription=Turso%20database%20URL%20%2B%20auth%20token%20and%20a%20random%20AUTH_SECRET%20(openssl%20rand%20-hex%2032).%20See%20DEPLOY.md%20for%20the%203-minute%20setup.&envLink=https%3A%2F%2Fgithub.com%2FTeloz1870%2Fcartwright-template%2Fblob%2Fmain%2FDEPLOY.md&project-name=my-cartwright-site&repository-name=my-cartwright-site)

One click clones the template to your GitHub and deploys it on Vercel. You'll be asked for
three env vars (a free [Turso](https://turso.tech) database + an `AUTH_SECRET`); after the
first deploy, finish the database setup per [`DEPLOY.md`](./DEPLOY.md). Prefer the terminal?
`npx create-cartwright` above does everything locally first.

Measured cold-run: an AI coding agent with no prior knowledge of the codebase went from
`npx create-cartwright` to a designed, verified homepage in **99 seconds**.

🌐 **[cartwright.app](https://cartwright.app)** · 📦 **[Source & template](https://github.com/Teloz1870/cartwright-template)** · 🛍️ Live demos: [solbrillen.dk](https://solbrillen-dk-teloz1.vercel.app/da) (eyewear, max-features) · [demo.cartwright.app](https://demo.cartwright.app) (coffee, modern shop)

> _Looking for a Shopify alternative or a free Next.js Stripe starter kit? Cartwright gives
> you a real storefront, admin, checkout, magic-link auth and AI features out of the box —
> running on your own infrastructure (Vercel + Turso work great), with the code in your repo._

  
  

*Above: the live coffee demo wearing the Ember design pack — every pixel is the engine's own design system bound to real shop data. No mockups.*

## Your first 10 minutes

The verified scaffold → designed-homepage flow lives in the project briefing that ships
with every scaffold: [`.claude/CLAUDE.md`](./.claude/CLAUDE.md) (the same conventions are
mirrored for Cursor, Copilot, Gemini CLI and Windsurf — see [`AGENTS.md`](./AGENTS.md)).
The short version:

1. `npx create-cartwright my-site` — scaffolds, installs, creates the schema, seeds, and
   **prints your admin login** (also saved to a gitignored `.admin-credentials`).
2. `npm run dev` → open `http://localhost:3000`.
3. Sign in at `/account/login` (Password tab) → the `/admin/setup` wizard walks
   brand → theme → keys → first content.

Human-paced walkthrough: [`docs/getting-started.md`](./docs/getting-started.md).
Manual clone (no CLI)? `npm install`, put `AUTH_SECRET` + `DATABASE_URL=file:./dev.db` in
`.env.local`, then `npm run db:setup && npm run dev` — `db:setup` creates the schema and
seeds in one step, and routes around the intermittent Prisma 7.8 `Schema engine error:`
via a libSQL fallback so first-run can't get stuck.

## Profiles & plugins

`npx create-cartwright` cuts one of two profiles from the same engine:

- **`light` (the default)** — a website-mode scaffold with a curated set of design packs and the
  lean module set. A real site out of the box: design system, sections, builder, database,
  pages, SEO/JSON-LD, deploy.
- **`--profile full`** — everything; required for `--template agent-marketplace`.

The choice is stamped in `.cartwright/profile.json`. Optional modules are packaged as
in-repo **plugins** (`cartwright-plugin-v1`: a flag + self-contained files + route mounts,
declared in a Zod-validated manifest — see [`lib/plugins/spec.ts`](./lib/plugins/spec.ts)
and the catalogue in [`plugins/registry.ts`](./plugins/registry.ts)). Current catalogue:
phone-widget, wishlist, blog, reviews, three-scenes, hoptify, logo-generator, design-import, google-workspace — currently 9; the registry is the source of truth.

## Three modes, one engine

`brand.mode` in `brand.config.ts` (the single source of truth for identity, mode, flags
and copy) selects the top-level behavior:

| Mode | What it is | What's mounted |
|---|---|---|
| `website` | Corporate/marketing site, no cart | Landing, contact, info pages, optional AI assistant |
| `webshop` | Full e-commerce storefront | PLP, PDP, cart, checkout, account, magic-link auth, Stripe |
| `agent-marketplace` | A2A/agent-first shop | Agent Card endpoint, negotiation, escrow verification, agentic admin |

Hybrids (e.g. webshop + ACP checkout) are additive `brand.features.*` flags.

## Why Cartwright

- **You own the code.** It's a template you fork/scaffold, not a hosted account. Cancel nothing.
- **AI-native, not bolted-on.** Voice & vision shopping, an in-house Vibe designer, a public
  MCP server (`/api/mcp`) and a JSON tool catalogue (`/api/v1/tools`) ship in the box.
- **Built to be cited by AI.** JSON-LD structured data on every page, `llms.txt`,
  `sitemap.xml`, `.well-known/ucp` + `mcp.json`, and an AI-crawler-friendly `robots.txt`.
- **Protocol-complete for agentic commerce.** MCP (external agents), ACP (ChatGPT Instant
  Checkout incl. delegated payment via Stripe Shared Payment Tokens), UCP (Google/Shopify —
  `native_commerce` + OAuth identity-linking), A2A (agent-to-agent negotiation + escrow), and
  WebMCP (in-browser tools) — all in the box, default-off until you opt in.
- **The golden stack.** Next.js 16 (App Router, Server Actions, Turbopack), React 19,
  Tailwind CSS v4, Prisma, Stripe, NextAuth v5.

## What an AI agent finds on a Cartwright site

Every shop publishes its agentic surface; gated endpoints 404 until their flag is on:

| Surface | URL | Gate |
|---|---|---|
| Agent briefing | `/llms.txt` | always on |
| MCP server | `/api/mcp` (server card: `/.well-known/mcp.json`) | always on |
| Tool catalogue (JSON Schema) | `/api/v1/tools` | always on |
| ACP product feed + checkout | `/api/acp/feed`, `/api/acp/v1/checkout_sessions` | `features.acp` |
| Signed Agent Card (A2A) | `/api/agent-card` | `features.a2a` |
| UCP capability profile | `/.well-known/ucp` | capabilities reflect enabled flags |
| Component registry (shadcn-compatible) | `/api/registry` | `features.componentRegistryPublic` |

## Features (honest highlights)

- **Storefront**: PLP/PDP, cart, checkout (Stripe Payment Element + webhook + mock
  fallback), account, magic-link auth, reviews, wishlist.
- **Admin**: products, orders, content, integrations, AI prompts, features, designs,
  plus a no-code Vibe sandbox to build pages from natural-language prompts.
- **AI**: storefront assistant, voice/vision shopping, MCP server + WebMCP (in-browser agent
  tools), Agentic Commerce Protocol (ACP) with delegated payment (Stripe Shared Payment Token),
  UCP OAuth identity-linking, SEO/GEO autopilot.
- **Localization**: i18nexus cloud integration + a built-in Gemini-Flash translation button.
- **Commerce ops**: shipping zones + fulfillment, Stripe Tax / VAT, blog + RSS,
  GDPR/DSAR, design-import from a URL (Firecrawl), abandoned-cart recovery, CSV import.
- **AI-discoverability**: `SoftwareApplication` JSON-LD + a "Built with Cartwright"
  block in `llms.txt` so AI assistants can recommend the engine. Gated by the default-on,
  deletable `cartwrightBadge` flag.

Every non-trivial subsystem is behind a `brand.features.*` flag (default-off unless noted).
The authoritative list with metadata is [`lib/feature-flags/manifest.ts`](./lib/feature-flags/manifest.ts);
full release notes in [`CHANGELOG.md`](./CHANGELOG.md). Every shop also ships a live
[`/built-with-cartwright`](https://cartwright.app) capability tour (deletable per shop).

## Stack

- **Next.js 16** (App Router, Server Actions, Turbopack)
- **Prisma + Turso libSQL** in production (managed, scalable) / **SQLite file** for local dev
- **Stripe** (Payment Element + webhook + mock fallback)
- **NextAuth v5** (magic-link + credentials)
- **MCP server** (`/api/mcp`) — external AI-agent interface
- **AI** (Anthropic Claude + Google Gemini for Vibe coding & SEO)
- **Sentry** (no-op without DSN), **Resend** (no-op without API key), **Vercel Blob** (image upload)
- **Tailwind CSS v4** (token-based palette in `themes/.css`)

## Required env vars

| Variable | Where | What |
|---|---|---|
| `DATABASE_URL` | dev | SQLite file for local dev (`file:./dev.db`) |
| `TURSO_DATABASE_URL` + `TURSO_AUTH_TOKEN` | **prod** | Production DB (Turso libSQL). Required in prod — the app refuses to boot without it |
| `AUTH_SECRET` | dev + prod | NextAuth JWT secret (`openssl rand -hex 32`) |
| `NEXT_PUBLIC_APP_URL` | dev + prod | Canonical URL — used by email links, Stripe callback, MCP |

### Optional env vars (graceful no-op)

| Variable | Effect if unset |
|---|---|
| `ANTHROPIC_API_KEY` | AI assistant 503s — set via `/admin/integrations` |
| `GOOGLE_GEMINI_API_KEY` | SEO/theme generator disabled |
| `STRIPE_SECRET_KEY` / `STRIPE_PUBLISHABLE_KEY` / `STRIPE_WEBHOOK_SECRET` | Mock checkout instead of real Stripe |
| `RESEND_API_KEY` | Preview mailer in dev, no email in prod |
| `SENTRY_DSN` / `NEXT_PUBLIC_SENTRY_DSN` | Error tracking disabled |
| `BLOB_READ_WRITE_TOKEN` | Admin image upload disabled |
| `FIRECRAWL_API_KEY` | Design-import / Hoptify URL scraping disabled |
| `CRON_SECRET` | Vercel cron routes 401 |

> **Before going live with real customers**: set Turso (`TURSO_DATABASE_URL` +
> `TURSO_AUTH_TOKEN` — local `file:./dev.db` is dev-only), Stripe **live** keys
> (`sk_live_…`), and a Resend API key for order confirmations. Full go-live path in
> [`DEPLOY.md`](./DEPLOY.md).

## Tests

```bash
npm test            # Vitest unit tests
npm run test:e2e    # Playwright e2e (requires dev server running)
npx tsc --noEmit    # Typecheck
```

## Project structure

```
app/               Next.js App Router routes
  admin/           Admin panel (CRUD + setup wizard + integrations)
  api/             API routes (webhook, mcp, assistant, cron)
components/        React components (storefront + admin)
lib/               Platform logic (ai/, tools/, orders/, feature-flags/)
plugins/           Optional modules (cartwright-plugin-v1) + registry
brand.config.ts    Single source of truth for brand-specific config
themes/.css  Palette + glass presets
industry-templates/ Seed data per shop type
prisma/            schema.prisma, migrations, seed.ts
```

## Versioning & stability

Cartwright ships as **tagged snapshots**: `npx create-cartwright` copies the template at a
release tag, and your shop is then your own code — nothing auto-updates it. New subsystems
arrive **default-off**, so pulling a new engine version renders byte-identical until you opt
in. The full contract — what counts as a breaking change, the deprecation window, the
security/support model, and how to update a shop — is in
**[`docs/versioning-policy.md`](docs/versioning-policy.md)**.

## License

See [`LICENSE`](./LICENSE).

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Teloz1870](https://github.com/Teloz1870)
- **Source:** [Teloz1870/cartwright-template](https://github.com/Teloz1870/cartwright-template)
- **License:** MIT
- **Homepage:** https://cartwright.app

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-teloz1870-cartwright-template
- Seller: https://agentstack.voostack.com/s/teloz1870
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.