Fakestore MCP

🚀 FakeStore MCP - Model Context Protocol E-commerce Demo

This is a complete e-commerce application that demonstrates the integration of the Model Context Protocol (MCP) with the FakeStore API. It is built with Next.js, TypeScript, and the MCP TypeScript SDK.

• 🚀 LIVE DEMO: https://fakestore-mcp.vercel.app
• 🎥 VIDEO EXPLANATION: https://www.youtube.com/watch?v=be9B8M1Ow88

🚀 Quick Start

📦 Installation

Prerequisites

• Node.js 18+
• npm or yarn

Development

# Install dependencies
npm install

# Start development server
npm run dev

The application will be available at http://localhost:3000.

✨ Features

Core Functionality

• ✅ User authentication with session management
• ✅ Product catalog with category browsing and sorting
• ✅ Shopping cart with add/remove/quantity management
• ✅ Optimistic UI updates for instant feedback
• ✅ Desktop design tested in 1440p

🏗️ Architecture

UI-First Development

1. Phase 1: Built a working UI by directly integrating with the FakeStore API to explore UX challenges.
2. Phase 2: Added an MCP server layer to wrap the proven functionality.
3. Result: A working product was created first, followed by the addition of an abstraction layer and refactoring.

Key Design Decisions

• Component Architecture: Modular React components with clear separation.
• State Management: React Context for cart management and localStorage for data persistence.
• Error Handling: Comprehensive error boundaries and user feedback mechanisms.
• TypeScript: Strict typing throughout the codebase for reliability.
• Optimistic Updates: Instant UI feedback with background sync.
• Desktop Only: Responsive mobile design was assumed to be out of scope for the sake of brevity.

🛠️ Tech Stack

• Frontend: Next.js 15, TypeScript, Tailwind CSS, shadcn/ui, React Context + localStorage
• MCP Server: MCP TypeScript SDK
• MCP Client: A manager class to interact with the MCP Server.
• API: FakeStore API (the only external API used), Token authentication, RESTful endpoints

MCP Server

The MCP server provides all functionality through standardized tools:

Authentication

• login - User authentication
• logout - Session termination

Products

• get_products - Browse products with category filtering
• get_categories - List available categories

Cart Operations

• add_to_cart - Add products to the cart
• remove_from_cart - Remove products from the cart
• get_cart - View detailed cart contents
• clear_cart - Empty the shopping cart

Cursor IDE Integration

AI Assistant → MCP Client → /api/mcp Endpoint → FakeStore API
                                 ↓
            Tool Response ← Cart State ← Database Update

The MCP server exposes all cart operations as standardized tools, allowing AI assistants to interact with the shopping cart programmatically.

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

The MCP client should be able to display the tools and be ready to consume them:

🔄 Flow

User Journey

1. Browse Products - Navigate through categories and view product details without authentication.
2. Add to Cart - If not authenticated, a login modal will be triggered.
3. Authentication - Users can log in with the provided demo credentials when necessary.
4. Cart Management - Add or remove items from the cart with instant UI feedback.
5. Optimistic Updates - The UI updates immediately, and the changes are synced in the background.

⚠️ Important Note

Traditionally in e-commerce sites, login is postponed until checkout. Since this application has no checkout and the carts in the API are userId based, this behavior is moved to the cart CTAs.

⚠️ Important Note

Since there is no persistency at the API level, sessions are retained at the MCP level with session management. A hard-refresh (Ctrl+F5) will cause the session and cart to reset to the API values. A logout-login without refreshing the page should persist the cart session. This behavior is intended.

Technical Flow

User Action → React Component → Cart Context → Optimistic UI Update
                                     ↓
            Background Sync → FakeStore API → State Reconciliation

🪪 Demo Credentials

The login dialog contains ready-to-use accounts for easy testing:

🎁 Extras

• Product sorting by Rating, Price, or Review Count

• Recommendations:

💡 Usage Tip

Traditionally in e-commerce systems, recommendations are based on sales data. For this demonstration, a product that is not in the cart is displayed.

📝 Notes

• As a last-minute decision, the debounce on the client side was removed. Each click now corresponds to a server action. In a production environment, client actions should be polled and sent as a single action with a debounce time. Due to time constraints, this optimization was reverted.