# 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

[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](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