{
  "markdown": "# VibeCart\n\n**Commerce infrastructure for AI-built apps and AI agents.**\n\nVibeCart lets a merchant keep their existing app and Stripe account while adding a small, inspectable commerce layer that AI agents can discover and use. Payments settle directly to the merchant's Stripe account; VibeCart does not need to become merchant of record.\n\nThe architecture is protocol-first: one trusted commerce backend, then thin MCP/UCP/client adapters around it.\n\n## Live production surface\n\n### Generic MCP\n\nEndpoint: `https://vibecart.vercel.app/mcp`\n\nTools:\n\n- `vibecart.list_products`\n- `vibecart.get_product`\n- `vibecart.get_integration_instructions`\n- `vibecart.create_checkout`\n\n`vibecart.create_checkout` supports both the legacy single-product input and a trusted multi-item `items[]` input. Product prices are resolved on the server; callers do not supply real transaction prices.\n\nGeneric MCP clients should use `/mcp`.\n\n### Durable cart\n\nVibeCart's Neon-backed cart is live in production:\n\n- `POST /api/cart`\n- `GET /api/cart/:id`\n- `PATCH /api/cart/:id`\n- `DELETE /api/cart/:id`\n- `POST /api/cart/:id/checkout`\n\nThe cart uses trusted server-side repricing, idempotent creation, optimistic version checks, expiration, multi-item state, and cart-to-Stripe Checkout handoff.\n\n### UCP\n\n- Discovery: `https://vibecart.vercel.app/.well-known/ucp`\n- UCP-aware MCP transport: `https://vibecart.vercel.app/ucp/mcp`\n- Released protocol target: UCP `2026-04-08`\n\nProduction advertises released catalog and cart capabilities. Current cart tools are:\n\n- `create_cart`\n- `get_cart`\n- `update_cart`\n- `cancel_cart`\n\nUCP calls require `meta.ucp-agent.profile` and capability negotiation. Do not point an ordinary MCP client at `/ucp/mcp`.\n\nThe order pipeline and released-schema `get_order` adapter also exist, but `get_order` remains hidden until its VibeCart Cloud lookup and real merchant permalink dependencies are configured. VibeCart does not advertise optional capabilities before their runtime dependencies are ready.\n\n### Stripe checkout and orders\n\n- Trusted multi-line Stripe Checkout creation is supported.\n- Stripe webhook signatures are verified before paid events enter the post-payment pipeline.\n- Delayed-payment completion is handled separately so orders are not created prematurely.\n- Paid Checkout line items are normalized into durable order records when VibeCart Cloud forwarding is configured.\n- Trusted merchant product IDs survive Checkout through Stripe Product metadata.\n\n### He Said Nothing physical-store pilot\n\n`/he-said-nothing` is the controlled physical-product pilot for the $39, $59, and $89 mystery gift boxes. The storefront can remain public while ordering fails closed. When the full launch gate is configured it:\n\n- saves the relationship quiz, sizing clues, packaging choice, gift message, and fulfillment note in a durable cart\n- opens a cart-bound, idempotent Stripe Checkout Session\n- collects email, phone, shipping address, a separately disclosed shipping charge, and optional Stripe automatic tax\n- stores the verified paid order, line items, delivery details, gift clues, and event history in Neon\n- exposes paid orders only through the HMAC-signed merchant session at `/he-said-nothing/admin`\n- supports the fulfillment states New, Packing, Shipped, Cancelled, and Refunded-in-Stripe\n\nThe checkout gate requires every dependency in `.env.example`; `HSN_CHECKOUT_ENABLED=true` alone is insufficient. Test and live Stripe keys must match `HSN_CHECKOUT_MODE`, and live mode additionally requires customer-support, return-policy, and processing-time text.\n\n## Merchant catalog source\n\nThe built-in `lib/products.ts` catalog is **demo/reference data only**. A real merchant can keep SKUs and prices outside VibeCart and point Core at a merchant-controlled HTTPS JSON feed:\n\n```bash\nVIBECART_CATALOG_URL=https://merchant.example/vibecart/catalog.json\nVIBECART_MERCHANT_NAME=\"Example Merchant\"\n# Optional when the feed is private:\nVIBECART_CATALOG_BEARER_TOKEN=server-side-secret\n```\n\nAccepted response shape:\n\n```json\n{\n  \"products\": [\n    {\n      \"id\": \"sku-123\",\n      \"name\": \"Example product\",\n      \"description\": \"Merchant-controlled product data\",\n      \"priceCents\": 4900,\n      \"image\": \"https://merchant.example/products/sku-123.jpg\",\n      \"variant\": \"Optional variant\"\n    }\n  ]\n}\n```\n\nAn array of products at the document root is also accepted. `id`, `name`, and a non-negative integer `priceCents` are required; image URLs, when present, must use HTTPS.\n\nThe configured source is shared by generic MCP catalog/checkout, UCP catalog, and durable cart repricing. VibeCart validates the document, rejects duplicate IDs, caps response/product counts, blocks redirects/private-network targets, applies a short timeout, and caches healthy catalog data for 30 seconds. If `VIBECART_CATALOG_URL` is configured and the source is unhealthy or invalid, commerce operations fail closed; VibeCart does **not** silently fall back to demo products.\n\nNormal SKU and price changes therefore do not require editing VibeCart TypeScript or redeploying Core.\n\n## Agent-client distribution\n\nVibeCart does **not** build a different commerce engine for every model. OpenAI/Codex/ChatGPT, Claude, Gemini, VS Code, Cursor, and other MCP clients connect to the same backend.\n\nSee:\n\n- [`docs/integrations/agent-clients.md`](docs/integrations/agent-clients.md)\n- [`integrations/mcp-clients.json`](integrations/mcp-clients.json)\n- `https://vibecart.vercel.app/mcp-clients.json`\n\nProvider adapters are CI-checked to keep Stripe/database/catalog secrets and duplicated commerce logic out of client configuration.\n\n## VibeCart Cloud\n\nVibeCart Core is free to self-host. **VibeCart Cloud is the optional $29/month managed layer** for merchants that want VibeCart to operate the recurring plumbing.\n\nCurrent Cloud capabilities include:\n\n- durable verified commerce events\n- durable normalized paid-order records and order history\n- server-to-server order lookup\n- signed merchant fulfillment webhooks\n- delivery history and bounded retries\n- monitoring/alerts and support workflows\n\nCloud workspace: `https://vibecart-cloud-uupzkh.v2.appdeploy.ai/`\n\nMerchant checkout revenue still settles directly to the merchant's Stripe account. VibeCart takes no percentage of merchant sales.\n\n## Quick start\n\n```bash\nnpm install\nnpm run dev\n```\n\nWithout `VIBECART_CATALOG_URL`, Core uses the fictional reference catalog for development. Configure a merchant catalog URL before treating products/prices as a real store catalog.\n\nWithout a Stripe secret, Checkout runs in clearly labeled demo mode. For live payments, configure `STRIPE_SECRET_KEY` in the hosting provider's secret/environment settings. Never commit secret values.\n\nUseful public endpoints:\n\n- `/start` — merchant/client quickstart\n- `/mcp` — generic MCP transport/discovery\n- `/api/cart` — durable cart creation\n- `/.well-known/ucp` — UCP business discovery\n- `/ucp/mcp` — UCP-aware MCP transport\n- `/mcp-clients.json` — machine-readable client compatibility manifest\n- `/llms.txt` — concise machine-readable integration notes\n- `/agents.md` — agent-facing guide\n- `/api/health` — boolean readiness state without secret values\n- `/cloud` — managed Cloud offer\n\n## Security model\n\n- Merchant owns the Stripe account and receives merchant funds directly.\n- Trusted prices come from the configured server-side merchant catalog provider.\n- A configured remote merchant catalog fails closed rather than falling back to demo prices.\n- Client-supplied pricing is disabled by default and is prototype-only when explicitly enabled server-side.\n- Stripe webhook signatures are verified before post-payment processing.\n- Cart state is durable and versioned rather than trusted from the browser/agent.\n- Catalog, Stripe, database, and Cloud integration credentials remain server-side.\n- Public health/discovery endpoints expose readiness booleans/capabilities, not credential values.\n- Optional UCP capabilities are advertised only when their runtime dependencies are valid.\n\n## Protocol conformance\n\nCI pins the released UCP `v2026-04-08` source and executes VibeCart's real mappers through the official `ucp-schema` validator. Cart success/error payloads, catalog responses, discovery, and the private order mapper have release-pinned conformance gates.\n\n## Current reference limits\n\n- The remote catalog connector is intentionally a simple trusted JSON-provider contract, not yet a multi-merchant catalog control plane with merchant UI, inventory sync, or per-merchant credentials stored by VibeCart Cloud.\n- Inventory, automated tax calculation, shipping-rate calculation, returns/refunds, and a complete fulfillment lifecycle are not finished platform services.\n- Public UCP order lookup remains activation-gated until its Cloud/permalink runtime dependencies are configured.\n- Next.js App Router is the reference implementation; other frameworks should use adapters around the same Core protocol surface rather than fork commerce logic.\n\n## North star\n\n> **VibeCart: commerce infrastructure for every AI agent. Build once. Sell everywhere AI can act.**\n\n## License\n\n[MIT](LICENSE) — free to use, modify, distribute, sublicense, and sell under the license terms.\n",
  "bytes": 9218,
  "sha": "f0559f753cff559be149e19fc5189b5c60c2ec9c552555db760a1bedee7764ee",
  "repo_slug": "runjohnray2-lgtm/vibecart",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_runjohnray2_lgtm_vibecart_b91586ac/readme"
}