VibeCart

VibeCart

面向 AI 构建的应用和 AI Agent 的商务基础设施。

VibeCart 让商家在保留现有应用和 Stripe 账户的同时，添加一个精简、可检查的商务层，供 AI Agent 发现和使用。付款会直接结算到商家的 Stripe 账户；VibeCart 无需成为登记商家。

此架构以协议为先：一个可信的商务后端，外围是轻量的 MCP/UCP/客户端适配器。

在线生产服务

通用 MCP

端点：https://vibecart.vercel.app/mcp

工具：

• vibecart.list_products
• vibecart.get_product
• vibecart.get_integration_instructions
• vibecart.create_checkout

vibecart.create_checkout 同时支持旧版单商品输入和可信的多商品 items[] 输入。商品价格由服务器解析；调用方不能提供真实交易价格。

通用 MCP 客户端应使用 /mcp。

持久化购物车

VibeCart 基于 Neon 的购物车已在生产环境上线：

• POST /api/cart
• GET /api/cart/:id
• PATCH /api/cart/:id
• DELETE /api/cart/:id
• POST /api/cart/:id/checkout

购物车采用可信的服务器端重新定价、幂等创建、乐观版本检查、过期机制、多商品状态，以及从购物车转交至 Stripe Checkout 的流程。

UCP

• 发现端点：https://vibecart.vercel.app/.well-known/ucp
• 支持 UCP 的 MCP 传输端点：https://vibecart.vercel.app/ucp/mcp
• 已发布的协议目标：UCP 2026-04-08

生产环境会公布已发布的目录和购物车能力。当前购物车工具包括：

• create_cart
• get_cart
• update_cart
• cancel_cart

UCP 调用必须提供 meta.ucp-agent.profile 并进行能力协商。不要让普通 MCP 客户端连接 /ucp/mcp。

订单处理流程和符合已发布架构的 get_order 适配器也已实现，但在配置好 VibeCart Cloud 查询和真实商家永久链接依赖项之前，get_order 仍处于隐藏状态。VibeCart 不会在可选能力的运行时依赖项就绪之前公布这些能力。

Stripe 结账和订单

• 支持创建可信的多行项目 Stripe Checkout。
• 在已付款事件进入支付后处理流程之前，会验证 Stripe webhook 签名。
• 延迟付款完成情况会单独处理，以避免过早创建订单。
• 配置好 VibeCart Cloud 转发后，已付款的 Checkout 行项目会被规范化为持久化订单记录。
• 商家可信商品 ID 会通过 Stripe Product 元数据贯穿 Checkout 流程。

He Said Nothing 实体店试点

/he-said-nothing 是针对 39 美元、59 美元和 89 美元神秘礼盒的受控实体商品试点。店面可以保持公开，但下单功能会在条件不满足时默认关闭。配置好完整的上线门槛后，该试点会：

• 将关系测验、尺寸线索、包装选择、礼物留言和履约备注保存到持久化购物车
• 打开与购物车绑定的幂等 Stripe Checkout Session
• 收集电子邮箱、电话、收货地址、单独披露的运费，以及可选的 Stripe 自动税费
• 将经验证的已付款订单、行项目、配送详情、礼物线索和事件历史存储在 Neon 中
• 仅通过 /he-said-nothing/admin 上经 HMAC 签名的商家会话公开已付款订单
• 支持以下履约状态：New、Packing、Shipped、Cancelled 和 Refunded-in-Stripe

结账门槛要求 .env.example 中列出的所有依赖项都已配置；仅设置 HSN_CHECKOUT_ENABLED=true 并不足够。测试和实时 Stripe 密钥必须与 HSN_CHECKOUT_MODE 匹配；实时模式还要求提供客户支持、退货政策和处理时间相关文本。

商家目录源

内置的 lib/products.ts 目录仅用于演示和参考。真实商家可以将 SKU 和价格保存在 VibeCart 之外，并让 Core 指向由商家控制的 HTTPS JSON 源：

VIBECART_CATALOG_URL=https://merchant.example/vibecart/catalog.json
VIBECART_MERCHANT_NAME="Example Merchant"
# Optional when the feed is private:
VIBECART_CATALOG_BEARER_TOKEN=server-side-secret

接受的响应格式：

{
  "products": [
    {
      "id": "sku-123",
      "name": "Example product",
      "description": "Merchant-controlled product data",
      "priceCents": 4900,
      "image": "https://merchant.example/products/sku-123.jpg",
      "variant": "Optional variant"
    }
  ]
}

也接受文档根目录下的产品数组。必须提供 id、name 和非负整数 priceCents；如果提供图片 URL，则必须使用 HTTPS。

配置的源由通用 MCP 目录/结账、UCP 目录和持久化购物车重新定价共用。VibeCart 会验证文档、拒绝重复 ID、限制响应和产品数量、阻止重定向和私有网络目标、设置较短的超时时间，并将健康的目录数据缓存 30 秒。如果已配置 VIBECART_CATALOG_URL，但源不健康或无效，电商操作将失败关闭；VibeCart 不会静默回退到演示产品。

因此，常规 SKU 和价格变更无需编辑 VibeCart TypeScript，也无需重新部署 Core。

Agent 客户端分发

VibeCart 不会为每个模型构建不同的电商引擎。OpenAI/Codex/ChatGPT、Claude、Gemini、VS Code、Cursor 和其他 MCP 客户端都会连接到同一后端。

请参阅：

• docs/integrations/agent-clients.md
• integrations/mcp-clients.json
• https://vibecart.vercel.app/mcp-clients.json

提供商适配器经过 CI 检查，确保客户端配置中不包含 Stripe/数据库/目录机密信息和重复的电商逻辑。

VibeCart Cloud

VibeCart Core 可免费自托管。VibeCart Cloud 是可选的托管层，每月 29 美元，面向希望由 VibeCart 处理常规运营工作的商家。

Cloud 当前提供的功能包括：

• 持久化的已验证电商事件
• 持久化的标准化已付款订单记录和订单历史
• 服务器到服务器的订单查询
• 带签名的商家履约 Webhook
• 配送历史记录和有限次数的重试
• 监控/告警和支持工作流

Cloud 工作区：https://vibecart-cloud-uupzkh.v2.appdeploy.ai/

商家结账收入仍直接结算到商家的 Stripe 账户。VibeCart 不收取商家销售额的任何百分比。

快速开始

npm install
npm run dev

如果未设置 VIBECART_CATALOG_URL，Core 在开发时会使用虚构的参考目录。将产品/价格视为真实店铺目录前，请先配置商家目录 URL。

如果未设置 Stripe 密钥，结账将以明确标注的演示模式运行。如需实时付款，请在托管服务提供商的机密信息/环境设置中配置 STRIPE_SECRET_KEY。切勿提交机密值。

常用公共端点：

• /start — 商家/客户端快速入门
• /mcp — 通用 MCP 传输/发现
• /api/cart — 创建持久化购物车
• /.well-known/ucp — UCP 商业发现
• /ucp/mcp — 支持 UCP 的 MCP 传输
• /mcp-clients.json — 机器可读的客户端兼容性清单
• /llms.txt — 简明的机器可读集成说明
• /agents.md — 面向 Agent 的指南
• /api/health — 不包含机密值的布尔型就绪状态
• /cloud — 托管 Cloud 服务

安全模型

• 商家拥有 Stripe 账户，并直接接收商家款项。
• 可信价格来自已配置的服务端商家目录提供方。
• 已配置的远程商家目录源发生故障时会失败关闭，而不会回退到演示价格。
• 默认禁用客户端提供的定价；只有在服务端明确启用时，才可用于原型。
• Stripe Webhook 签名会在付款后处理之前进行验证。
• 购物车状态会持久化并进行版本控制，不会信任浏览器/Agent 提供的状态。
• 目录、Stripe、数据库和 Cloud 集成凭据均保留在服务端。
• 公共健康状态/发现端点只公开就绪状态布尔值/功能，不公开凭据值。
• 只有在运行时依赖有效时，才会公布可选的 UCP 功能。

协议一致性

CI 固定使用已发布的 UCP v2026-04-08 源代码，并通过官方 ucp-schema 验证器执行 VibeCart 的实际映射器。购物车成功／错误负载、商品目录响应、发现功能以及私有订单映射器均设有针对该版本的合规检查。

当前参考实现的限制

• 远程商品目录连接器有意采用简单的可信 JSON 提供方契约，目前还不是支持多商家的商品目录控制平面，不提供商家 UI、库存同步或由 VibeCart Cloud 存储的商家专属凭证。
• 库存、自动税费计算、运费计算、退货／退款以及完整的履约生命周期尚未作为平台服务完成。
• 在配置好 Cloud／永久链接运行时依赖项之前，公开的 UCP 订单查询仍需通过激活才能使用。
• Next.js App Router 是参考实现；其他框架应围绕相同的 Core 协议接口使用适配器，而不是分叉电商逻辑。

北极星

VibeCart：为每个 AI Agent 提供电商基础设施。构建一次。在 AI 能够采取行动的任何地方销售。

许可证

MIT — 可根据许可证条款免费使用、修改、分发、再许可和销售。