A Model Context Protocol (MCP) server for integrating with Walmart products backend API. This server enables customers to shop using natural language through AI-powered conversations, providing tools for product discovery, cart management, coupon handling, and order history access.
This MCP server transforms the traditional shopping experience by allowing customers to interact with Walmart's product ecosystem using conversational AI. Customers can simply ask questions like "Show me smartphones under $500" or "What's in my cart?" and get instant, personalized responses.
- 🤖 AI-Powered Shopping: Natural language interactions for seamless shopping experiences
- 🔍 Product Search: Search products by category (smartphones, tv, shoes, healthcare, electronics, fitness)
- 💰 Price Filtering: Filter smartphones by maximum price with conversational queries
- 🛒 Cart Management: View current cart items through simple voice or text commands
- 🎟️ Coupons: Access available discount coupons via natural language requests
- 📋 Order History: Retrieve past order information through conversational interface
In today's fast-paced, digital-first world, customer experience is the ultimate competitive advantage. With limitless options at their fingertips, modern shoppers expect seamless, intuitive and highly personalized interactions—whether they're browsing online, engaging via mobile or stepping into a physical store.
This MCP server represents the convergence of several emerging technologies:
- 🧠 AI-Powered Shopping Assistants: Conversational commerce that understands customer intent and provides personalized recommendations
- 📊 Data-Driven Insights: Real-time analysis of shopping patterns to enhance customer engagement
- 🎯 Hyper-Personalized Experiences: Every interaction feels effortless, engaging and deeply relevant
- ⚡ Real-Time Commerce: Instant responses to customer queries about products, pricing, and availability
- 🔄 Predictive Shopping: Anticipating customer needs through advanced analytics
Retailers that harness AI, data-driven insights and immersive technologies are redefining customer engagement. From hyper-personalized recommendations and predictive shopping experiences to dynamic pricing models and real-time conversational commerce, emerging technologies are creating deeper, more meaningful relationships between brands and consumers.
This project embodies Walmart's vision of leveraging emerging technologies to transform the way customers shop, offering ultra-personalized experiences that make every interaction feel effortless, engaging and deeply relevant. By combining the power of AI assistants with natural language processing, we're reimagining the future of retail to enhance customer experience, boost engagement and redefine convenience in shopping.
Product Discovery:
get_products_by_category: Fetch products from a specific category using natural languageget_smartphones_by_price: Filter smartphones by maximum price through conversational queries
Cart Management:
get_cart_items: View shopping cart contents with simple voice or text commandsadd_to_cart: Add products to cart with specified quantitiesremove_from_cart: Remove products from cart (single item or all quantities)
Coupon & Discounts:
get_available_coupons: Get available discount codes via natural language requestsapply_coupon: Apply discount coupons to cart for savingsremove_coupon: Remove applied coupons from cart
Order Management:
get_order_history: Access order transaction history through conversational interfaceplace_order: Complete purchase with current cart items
Product Discovery:
- "Show me all smartphones under $300" → Uses
get_smartphones_by_price - "What electronics do you have?" → Uses
get_products_by_category
Cart Management:
- "What's in my shopping cart?" → Uses
get_cart_items - "Add iPhone 15 to my cart" → Uses
add_to_cart - "Remove the Nike shoes from my cart" → Uses
remove_from_cart
Coupons & Discounts:
- "Do I have any coupons available?" → Uses
get_available_coupons - "Apply coupon SAVE20 to my cart" → Uses
apply_coupon - "Remove the coupon from my cart" → Uses
remove_coupon
Order Management:
- "Show me my recent orders" → Uses
get_order_history - "Place my order now" → Uses
place_order
- Node.js (v18 or higher)
- pnpm package manager
- Backend API running on
http://localhost:3000
- Clone the repository:
git clone https://github.com/khushal1512/spark-mcp.git
cd spark-mcp- Install dependencies:
pnpm install- Build the project:
pnpm buildRun in development mode with hot reload:
pnpm devWatch mode for continuous development:
pnpm watchBuild and start the server:
pnpm build
pnpm startTo use this MCP server with Cursor, add the following configuration to your Cursor settings:
{
"mcpServers": {
"spark-customer-agent": {
"command": "node",
"args": ["path/to/spark-mcp/dist/index.js"]
}
}
}The server expects the following endpoints to be available:
Product Discovery:
GET /products/{category}- Get products by categoryGET /products/smartphones/{maxPrice}- Get smartphones under max price
Cart Management:
GET /cart- Get cart itemsPOST /cart/add- Add product to cartDELETE /cart/remove- Remove product from cart
Coupon Management:
GET /coupons- Get available couponsPOST /cart/apply-coupon- Apply coupon to cartDELETE /cart/remove-coupon- Remove coupon from cart
Order Management:
GET /orders- Get order historyPOST /orders/place- Place new order
spark-mcp/
├── src/
│ └── index.ts # Main MCP server implementation
├── dist/ # Compiled JavaScript output
├── package.json # Project configuration
├── tsconfig.json # TypeScript configuration
└── README.md # This file
- Backend URL: Configure
BACKEND_BASE_URLinsrc/index.ts - Categories: Modify
ALLOWED_CATEGORIESarray for different product categories
- Fork the repository
- Create a feature branch:
git checkout -b feature-name - Make your changes
- Build and test:
pnpm build - Commit your changes:
git commit -am 'Add some feature' - Push to the branch:
git push origin feature-name - Submit a pull request
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
Khushal Agrawal