spark

Spark is an MCP server that enables conversational shopping against Walmart's product backend. It exposes tools for product discovery, cart management, coupons, and order history, all accessible through natural language prompts. Use it to answer questions like 'Show me smartphones under $500' or 'What items are in my cart?' and to perform actions such as adding items to a cart, applying coupons, or placing orders. The server is designed to work with Cursor-integrated flows, chatbots, or any client that can send MCP-formatted requests to the backend endpoints defined in the README. The available toolset includes product discovery by category, price-filtered smartphone queries, cart inspection and modification, coupon handling, and order history retrieval, enabling end-to-end shopping conversations.

To use Spark in a Cursor-enabled workflow, point the MCP server entry to the compiled index and ensure the BACKEND_BASE_URL is correctly set. Tools like get_products_by_category, get_smartphones_by_price, get_cart_items, add_to_cart, remove_from_cart, get_available_coupons, apply_coupon, remove_coupon, get_order_history, and place_order can then be invoked via natural-language intents in your conversational UI. When using the provided endpoints, Spark translates natural language into the corresponding tool calls under the hood, returning structured results suitable for chat-based presentations.

Prerequisites:

• Node.js v18 or higher
• pnpm package manager
• A running backend API compatible with Spark (listed endpoints in the README), accessible at BACKEND_BASE_URL (default http://localhost:3000)

Installation steps:

1. Clone the repository:

git clone https://github.com/khushal1512/spark-mcp.git
cd spark-mcp

2. Install dependencies:

pnpm install

3. Build the project:

pnpm build

4. Run in development mode (hot-reload):

pnpm dev

5. Build for production and start the server:

pnpm build
pnpm start

6. If you’re integrating with Cursor, ensure the MCP config (as shown in mcp_config) is applied to Cursor’s settings so the server is reachable by your workflow.

Environment variables and configuration:

• BACKEND_BASE_URL: Base URL for the backend API (default http://localhost:3000). Update to your deployed backend if needed.
• ALLOWED_CATEGORIES: Comma-separated list of categories Spark can search, e.g., smartphones,tv,shoes,healthcare,electronics,fitness. Adjust as needed.

Common issues:

• If the backend API is not reachable, verify BACKEND_BASE_URL and ensure the backend is running.
• Ensure Node.js v18+ is installed and that pnpm is available during development.
• When integrating with Cursor, confirm the JSON in Cursor settings matches the provided mcpServers entry and that the path to dist/index.js is correct after building.

Configuration tips:

• For production deployments, consider pinning specific package versions and using environment-based overrides for BACKEND_BASE_URL and allowed categories.
• Monitor logs for any tool invocation errors and verify that endpoints return data in the expected shape for the MCP layer.