Web MCP Ecomm

WebMCP示例——演示商店

小的 React+TypeScript+Vite 演示的应用程序 WebMCP：在上注册工具 navigator.modelContext 因此，AI代理可以驱动商店UI（购物车、愿望清单、结账和声明性HTML表单）。

回购协议是在 阶段 （参见 docs/PHASES.md): 第一阶段 --客户端持久性； 第2阶段 — Postgres+细雨 和 GET /api/products; 第三期 — POST /api/orders; 阶段4 — 更好的认证; 阶段5 — Razorpay; 第6阶段 — 缓存、对CDN友好的映像、目录管理API、CI合约 (docs/scale-ops.md).

______________________________________________________________________

先决条件

• Node.js 建议20+（用于工具；Vite/React根据 package.json).
• Chrome 146+ 带着实验旗帜 “用于测试的WebMCP”: chrome://flags/#enable-webmcp-testing\

如果 navigator.modelContext 缺失，应用程序仍在运行； useWebMCP 记录警告并跳过工具注册。

• 可选： 码头工人 对于本地Postgres().
• 可选： Vercel 命令行工具 对于本地API路线： npx vercel dev.

______________________________________________________________________

快速入门（仅前端）

无需数据库：应用程序会尝试 GET /api/products，如果不可用（例如纯 npm run dev它 退而求其次 到中的静态目录 src/data/products.ts.

npm install
npm run dev

打开Vite打印的URL（通常 http://localhost:5173).

______________________________________________________________________

本地全栈（Postgres+ /api/*)

1. 启动Postgres （Docker示例）：

   npm run docker:db:up

1. 环境 --复制和编辑：

   cp .env.example .env

集 DATABASE_URL （或 DATABASE_POSTGRES_URL 来自Neon）。用于身份验证 vercel dev，set BETTER_AUTH_SECRET （例如。 openssl rand -base64 32)以及 BETTER_AUTH_URL=http://localhost:3000 （与Vercel打印的URL匹配）。

1. 模式+种子:

   npm run db:migrate
   npm run db:seed

1. 运行应用程序+API （Vite+无服务器路由在一个源上）：

   npx vercel dev

打开Vercel打印的URL（通常 http://localhost:3000). GET /api/products 和 POST /api/orders 在以下情况下使用数据库 DATABASE_URL 已设置。平原 npm run dev 有 不 /api 路由：目录回退到静态数据和签出返回 503 如果你只运行Vite。

架构更新后： 如果你改变了 db/schema.ts，跑 npm run db:generate，在下提交新文件 drizzle/那么 npm run db:migrate 在每个数据库上。在拉动其他人的迁移后，运行 npm run db:migrate 之前 db:seed 或订购。

有用的脚本

逐步检查（缓存、管理API、图像）： docs/manual-testing.md.

______________________________________________________________________

部署（Vercel）

• 将仓库连接到Vercel； vercel.json 套 维特 生成输出 dist.
• 集 DATABASE_URL 或 DATABASE_POSTGRES_URL 在项目环境中（例如Neon）。
• 认证（第4阶段）： 集 BETTER_AUTH_SECRET （≥32个字符）和 BETTER_AUTH_URL 到您的生产现场来源（例如。 https://your-project.vercel.app).可选的 BETTER_AUTH_TRUSTED_ORIGINS 对于额外允许的来源（逗号分隔）。
• 生产迁移： 推动 main 这触动了 db/, drizzle/, drizzle.config.ts，根 package.json / package-lock.json，或 运行该工作流，该工作流将执行 npm run db:migrate 使用 DATABASE_URL 存储库机密 （使用与Vercel生产相同的霓虹灯连接串）。对于其他任何操作（或者如果推送与这些路径不匹配），请从“操作”选项卡手动运行它(数据库迁移 → 运行工作流).在以下位置传送新文件 drizzle/ 在模式更改的同一提交中。
• 播种： 跑 npm run db:seed 仅当您需要目录数据时才反对生产（一次性来自安全的机器 DATABASE_URL=… 为该命令设置，或者如果添加了专用工作流，则设置专用工作流）。不要泄露秘密。
• 第6阶段（运营）： vercel.json 添加 缓存标头 对于资产， /api/products，以及HTML shell。可选的 ADMIN_API_SECRET 使能够 PUT /api/admin/product （参见 docs/scale-ops.md).
• CI： 跑 check:contracts, 棉绒，以及 构建 关于推送/PR main.
• api/products.ts → GET /api/products; api/orders.ts → POST /api/orders; api/auth/[...all].ts → **/api/auth/*** （更好的认证）。

VITE_API_BASE 仅当API托管在 不同起源 比SPA。

______________________________________________________________________

应用程序中有什么

• 状态 — src/store/StoreContext.tsx：购物车、愿望清单、视图、目录加载状态、WebMCP相关UI状态。
• 坚持（第一阶段） — src/lib/persist.ts：购物车/愿望清单在 localStorage；在阶段2之后，持久性同步一次 API目录 已加载。
• 目录（第2阶段） --加载自 GET /api/products 回退到 src/data/products.ts.
• 订单（第3阶段） — POST /api/orders 创造 orders + order_lines；结账需求 vercel dev 或部署API+数据库URL。
• 认证（第4阶段） — auth.ts, [api/auth/[...all].ts](api/auth/%5B...all%5D.ts), src/lib/authClient.ts头球 登录 打开帐户UI；订单包括 user_id 当会话cookie存在时(credentials: "include" 结账时）。
• 付款（第5阶段） --Razorpay标准结账；看见 docs/razorpy-flow.md.
• 规模和运营（第6阶段） --缓存标头(vercel.json, api/products.ts), ProductImage，可选 api/admin/product.ts; docs/scale-ops.md.
• 强制性WebMCP — src/hooks/useWebMCP.ts：工具登记簿 之后 目录可用； product_id 是一个 字符串 （使用 get_products / list_products ID）。
• 声明性WebMCP — src/components/DeclarativeView.tsx, src/components/QuickBuyModal.tsx：表单使用 toolname, tooldescription, toolparamdescription，可选 toolautosubmit.

静态参考物质： architecture.html, public/webmcp-guide.html.

______________________________________________________________________

工具参考（必须）

目录非空时注册(navigator.modelContext +Chrome标志）。

声明性（HTML属性）

TypeScript扩展了WebMCP属性： src/types/webmcp.d.ts.

______________________________________________________________________

项目布局（高层）

auth.ts                  # Better Auth server config (Drizzle adapter)
api/products.ts          # GET /api/products
api/orders.ts            # POST /api/orders
api/auth/[...all].ts     # /api/auth/* (sessions, sign-in, etc.)
db/                      # Drizzle schema + DB client
drizzle.config.ts        # Drizzle Kit (+ dotenv for local .env)
docker-compose.yml       # Optional local Postgres
scripts/seed.ts          # Seed DB from src/data/products.ts
src/
  hooks/useWebMCP.ts
  store/StoreContext.tsx
  lib/persist.ts
  components/
  data/products.ts       # Fallback catalog + seed source
docs/PHASES.md           # Phase 1–2 summary & roadmap

______________________________________________________________________

技术栈

• React 19、TypeScript、Vite 8
• 可选： 淋上ORM， postgresPostgres（本地Docker或托管）
• 可选： Vercel无服务器 api/
• 购物车/愿望清单： 客户端 持续到未来的“服务器购物车”阶段（参见 docs/PHASES.md).

______________________________________________________________________

路线图

看 docs/PHASES.md 对于已完成的阶段（1-2）和计划的下一步（订单、授权、条纹、规模）。