README.md•4.64 kB
# Superstore MCP Server
An MCP server for Real Canadian Superstore that extracts orders and product data
with authentication.
## Features
- **Order Management**: Full order history with item details, dates, prices,
images
- **DirectAuth**: Fast bearer token authentication (no browser needed)
- **Data Export**: Export orders to CSV or JSON for analysis
- **Product Discovery**: Browse categories and search products
- **Web Content**: Fetch and parse web pages
## Installation
### Quick Install to Cursor
[](cursor://anysphere.cursor-deeplink/mcp/install?name=superstore-mcp&config=eyJzdXBlcnN0b3JlLW1jcCI6eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInN1cGVyc3RvcmUtbWNwQGxhdGVzdCJdLCJlbnYiOnsiU1VQRVJTVE9SRV9CRUFSRVJfVE9LRU4iOiJ5b3VyLWJlYXJlci10b2tlbi1oZXJlIn19fQ==)
**Note**: Make sure Cursor is running before clicking the install button.
### Manual Installation
```bash
# Run directly with npx
npx -y superstore-mcp@latest
# Or clone from GitHub
git clone https://github.com/ai-protocols/superstore-mcp.git
cd superstore-mcp
npm install
npm run build
```
## Configuration
Add to your `mcp.json`:
```json
{
"superstore-mcp": {
"command": "npx",
"args": ["-y", "superstore-mcp@latest"],
"env": {
"SUPERSTORE_BEARER_TOKEN": "your-token-here"
}
}
}
```
### Getting Your Bearer Token
1. Log in to https://www.realcanadiansuperstore.ca
2. Open DevTools (F12) → Application → Cookies → www.realcanadiansuperstore.ca
3. Find `AccessToken` cookie and copy its value (starts with `eyJ`)
4. Paste into `SUPERSTORE_BEARER_TOKEN`
Tokens expire after ~1 hour. Refresh by copying a new token from your browser.
## Available Tools
### Authentication
**`login`** - Authenticate session
```json
{}
```
**`logout`** - End session
```json
{}
```
**`check_auth_status`** - Check authentication state
```json
{}
```
### Orders
**`get_orders`** - Get order history
```json
{
"limit": 10,
"offset": 0
}
```
**`get_order_details`** - Get full order with items
```json
{
"order_id": "531900014110869"
}
```
**`get_recent_orders`** - Filter orders by date
```json
{
"days": 90
}
```
**`export_orders_csv`** - Export to CSV
```json
{
"include_items": true,
"filepath": "./orders.csv"
}
```
**`export_orders_json`** - Export to JSON
```json
{
"include_items": true,
"filepath": "./orders.json"
}
```
### Products
**`get_categories`** - Get all categories
```json
{}
```
**`get_products`** - Get products from categories
```json
{
"category_ids": ["28251"],
"max_pages_per_category": 1
}
```
**`get_category`** - Get single category
```json
{
"category_id": "28251"
}
```
**`get_product`** - Search for product
```json
{
"category_id": "28251",
"product_name": "bread"
}
```
**`search_products`** - Search products (alias)
```json
{
"category_id": "28251",
"product_name": "milk"
}
```
**`get_product_details`** - Get product details from URL
```json
{
"product_url": "https://www.realcanadiansuperstore.ca/..."
}
```
**`get_product_details_by_name`** - Search and get details
```json
{
"category_id": "28251",
"product_name": "butter"
}
```
### Web Utilities
**`fetch_txt`** - Fetch web page as text
```json
{
"url": "https://www.realcanadiansuperstore.ca"
}
```
**`parse_sitemap`** - Parse sitemap
```json
{
"sitemap_url": "https://www.realcanadiansuperstore.ca/sitemap_index.xml"
}
```
## Example Usage
### Export All Orders
```javascript
// Login
await mcp.call("login", {});
// Export with full item details
await mcp.call("export_orders_csv", {
"include_items": true,
});
```
### Analyze Spending
```javascript
// Get recent orders
const orders = await mcp.call("get_recent_orders", { "days": 90 });
// Get details for each
for (const order of orders.orders) {
const details = await mcp.call("get_order_details", {
"order_id": order.id,
});
console.log(`${order.id}: ${details.items.length} items`);
}
```
## Architecture
- **DirectAuth**: Uses bearer token from browser (recommended)
- **API Integration**: Calls `api.pcexpress.ca/pcx-bff` with proper headers
- **Fallback Mode**: Puppeteer browser automation if no bearer token provided
- **HTML Parsing**: JSDOM for product pages
## Documentation
- [API Reference](docs/API.md)
- [Authentication Guide](docs/AUTHENTICATION.md)
- [Security Guide](docs/SECURITY.md)
## License
MIT
## Disclaimer
Unofficial tool. Not affiliated with Loblaw Companies or Real Canadian
Superstore. Use responsibly.
---
**Repository**: https://github.com/ai-protocols/superstore-mcp\
**Version**: 2.0.0