Fakestore MCP

🚀 FakeStore MCP - 模型上下文協議電子商務演示

本項目是一個完整的電子商務應用程序，展示瞭如何將模型上下文協議（MCP）與FakeStore API集成。它使用Next.js、TypeScript和MCP TypeScript SDK構建。

🚀 快速開始

前提條件

• Node.js 18+
• npm 或 yarn

開發步驟

# 安裝依賴
npm install

# 啟動開發服務器
npm run dev

應用程序將在 http://localhost:3000 上可用。

✨ 主要特性

核心功能

• ✅ 支持用戶認證和會話管理
• ✅ 提供帶有分類瀏覽和排序功能的產品目錄
• ✅ 具備購物車，支持添加、移除商品和管理商品數量
• ✅ 採用樂觀更新機制，為用戶提供即時的UI反饋
• ✅ 經過1440p桌面設計測試

📦 安裝指南

前提條件

• Node.js 18+
• npm 或 yarn

開發環境

# 安裝依賴
npm install

# 啟動開發服務器
npm run dev

應用程序將在 http://localhost:3000 上運行。

📚 詳細文檔

架構

UI優先開發

1. 階段1：構建與FakeStore API直接集成的可用UI，以探索用戶體驗方面的挑戰。
2. 階段2：添加MCP服務器層，封裝已驗證的功能。
3. 結果：先實現可用產品，再構建抽象層並進行重構。

關鍵設計決策

• 組件架構：採用模塊化的React組件，實現清晰的分離。
• 狀態管理：使用React Context管理購物車狀態，使用localStorage實現持久化。
• 錯誤處理：具備全面的錯誤邊界和用戶反饋機制。
• TypeScript：全程使用嚴格類型，確保可靠性。
• 樂觀更新：提供即時的UI反饋，並在後臺進行同步。
• 僅支持桌面端：為簡潔起見，假定響應式移動設計不在本次開發範圍內。

技術棧

• 前端：Next.js 15、TypeScript、Tailwind CSS、shadcn/ui、React Context + localStorage
• MCP服務器：MCP TypeScript SDK
• MCP客戶端：用於與MCP服務器交互的管理類
• API：FakeStore API（唯一使用的外部API），採用令牌認證和RESTful端點

MCP服務器

MCP服務器通過標準化工具提供所有功能：

• 認證
  • login - 用戶認證
  • logout - 終止會話
• 產品
  • get_products - 支持按類別過濾瀏覽產品
  • get_categories - 列出可用的產品類別
• 購物車操作
  • add_to_cart - 向購物車添加產品
  • remove_from_cart - 從購物車移除產品
  • get_cart - 查看購物車詳細內容
  • clear_cart - 清空購物車

Cursor IDE集成

AI助理 → MCP客戶端 → /api/mcp端點 → FakeStore API
                                 ↓
            工具響應 ← 購物車狀態 ← 數據庫更新

MCP服務器將所有購物車操作作為標準化工具公開，允許AI助理以編程方式與購物車進行交互。

{
  "mcp": {
    "servers": {
      "fakestore": {
        "endpoint": "https://fakestore-mcp.vercel.app/api/mcp",
        "protocol": "http"
      }
    }
  }
}

MCP客戶端應能夠顯示這些工具並準備好使用它們：

流程

用戶旅程

1. 瀏覽產品 - 瀏覽產品類別，查看產品詳情（無需認證）
2. 添加到購物車 - 如果未認證，將觸發登錄模態框
3. 認證 - 用戶在需要時使用演示憑證登錄
4. 購物車管理 - 添加或移除商品，同時獲得即時的UI反饋
5. 樂觀更新 - UI立即更新，並在後臺進行同步

傳統電商網站通常在結賬時才要求登錄。由於本項目沒有結賬功能，且API中的購物車基於userId，因此將登錄行為移至購物車操作的CTA處。

由於API層面沒有持久化機制，會話在MCP層面通過會話管理進行保留。硬刷新（Ctrl+F5）會使會話和購物車重置為API中的值。不刷新頁面的情況下進行註銷 - 登錄操作應保留購物車會話，這是設計意圖。

技術流程

用戶操作 → React組件 → 購物車上下文 → 樂觀UI更新
                                     ↓
            後臺同步 → FakeStore API → 狀態協調

演示憑證

登錄對話框中包含可直接使用的賬戶，方便進行測試：

額外功能

• 支持按評分、價格或評論數量對產品進行排序

• 提供推薦功能：

傳統電商系統的推薦通常基於銷售數據。在本演示中，我們展示的是不在購物車中的產品。

注意事項

• 由於時間緊迫，移除了客戶端的防抖功能。現在每次點擊都會對應一個服務器操作。在生產環境中，客戶端操作應該進行輪詢，並以防抖時間作為間隔發送為單個操作。由於時間限制，此優化被撤銷。

🚀 實時演示：https://fakestore-mcp.vercel.app

🎥 視頻講解：https://www.youtube.com/watch?v=be9B8M1Ow88