Fakestore MCP

🚀 FakeStore MCP - 模型上下文协议电商演示

本项目是一个完整的电商应用程序，展示了如何将模型上下文协议（MCP）与FakeStore API集成。它基于Next.js、TypeScript和MCP TypeScript SDK构建。

🚀 在线演示：https://fakestore-mcp.vercel.app

🎥 视频讲解：https://www.youtube.com/watch?v=be9B8M1Ow88

🚀 快速开始

前提条件

• 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 → 状态协调

演示凭证

登录对话框中包含可直接使用的账户，方便测试：

额外功能

• 支持按评分、价格或评论数量对产品进行排序

• 产品推荐：

传统电商系统的推荐通常基于销售数据。在本演示中，我们展示的是不在购物车中的产品。

注意事项

• 最后时刻移除了客户端的防抖功能。每次点击对应一次服务器操作。在生产环境中，客户端操作应进行轮询，并以防抖时间作为一个操作发送。由于时间限制，此优化被撤销。