FakeStore MCP

FakeStore MCP - Model Context Protocol E-commerce Demo

🚀 LIVE DEMO: https://fakestore-mcp.vercel.app

🎥 VIDEO EXPLANATION: https://www.youtube.com/watch?v=be9B8M1Ow88

A complete e-commerce application demonstrating Model Context Protocol (MCP) integration with the FakeStore API. Built with Next.js, TypeScript, and the MCP TypeScript SDK.

• FakeStore MCP - Model Context Protocol E-commerce Demo
  • Setup Instructions
    • Prerequisites
    • Development
  • Architecture
    • UI-First Development
    • Key Design Decisions
  • Tech Stack
    • MCP Server
      • Authentication
      • Products
      • Cart Operations
    • Cursor IDE Integration
  • Features
    • Core Functionality
  • Flow
    • User Journey
    • Technical Flow
  • Demo Credentials
  • Extras
  • Notes

Setup Instructions

Prerequisites

• Node.js 18+
• npm or yarn

Development

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

Architecture

UI-First Development

1. Phase 1: Built working UI with direct FakeStore API integration to explore UX challenges
2. Phase 2: Added MCP server layer to wrap proven functionality
3. Result: Working product first, then abstraction layer and refactoring

Key Design Decisions

• Component Architecture: Modular React components with clear separation
• State Management: React Context for cart, localStorage for persistence
• Error Handling: Comprehensive error boundaries and user feedback
• TypeScript: Strict typing throughout for reliability
• Optimistic Updates: Instant UI feedback with background sync
• Desktop Only: Assumed responsive mobile design out of scope for brevity

Tech Stack

• Frontend: Next.js 15, TypeScript, Tailwind CSS, shadcn/ui, React Context + localStorage
• MCP Server: MCP TypeScript SDK
• MCP Client: Manager class to interact with MCP Server
• API: FakeStore API (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 with category filtering
• get_categories - List available categories

Cart Operations

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

Cursor IDE Integration

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

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

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

Flow

User Journey

1. Browse Products - Navigate categories, view product details (no auth required)
2. Add to Cart - Triggers login modal if not authenticated
3. Authentication - User logs in with demo credentials when needed
4. Cart Management - Add/remove items with instant UI feedback
5. Optimistic Updates - UI updates immediately, syncs in background

Traditionally in e-commerce sites, login is postponed until checkout. Since we have no checkout and carts in API are userId based, this behaviour is moved to cart CTAs.

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

Technical Flow

Demo Credentials

Login dialog contains ready-to-use accounts for easy testing:

Extras

• Product sorting by Rating, Price or Review Count
• Recommendations:

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

Notes

• As a last minute call, debounce on client side is removed. Each click 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 is reverted.