# Superstore MCP API Reference
Complete reference for all MCP tools available in the Superstore MCP server.
## Overview
The Superstore MCP server provides tools for:
- Web content fetching and parsing
- Superstore product and category data extraction
- User authentication and session management
- Order history and details retrieval
## Core Tools
### Web Fetching Tools
#### `fetch_txt`
Fetch a website and convert content to plain text.
**Input**:
- `url` (string, required): URL of the website to fetch
- `headers` (object, optional): Custom headers to include in the request
- `max_length` (number, optional): Maximum number of characters to return
- `start_index` (number, optional): Start content from this character index
**Output**: Plain text content with HTML tags removed
**Example**:
```json
{
"url": "https://www.realcanadiansuperstore.ca",
"max_length": 5000
}
```
### Sitemap and Category Tools
#### `parse_sitemap`
Parse Superstore sitemap and extract category URLs.
**Input**:
- `sitemap_url` (string, optional): URL of the sitemap to parse (default:
Superstore sitemap)
**Output**: Sitemap analysis with category information
#### `get_categories`
Get all categories from Superstore sitemap.
**Input**:
- `sitemap_url` (string, optional): URL of the sitemap to parse
**Output**: Complete list of categories with IDs and names
#### `get_category`
Get a single category by ID from Superstore sitemap.
**Input**:
- `category_id` (string, required): Category ID to get information for
- `sitemap_url` (string, optional): URL of the sitemap to parse
**Output**: Detailed category information
### Product Tools
#### `get_products`
Get all products from multiple Superstore categories.
**Input**:
- `category_ids` (array, required): Array of category IDs to get products from
- `max_pages_per_category` (number, optional): Maximum number of pages to fetch
per category (default: 2)
**Output**: Array of products from specified categories
**Example**:
```json
{
"category_ids": ["28000", "28001"],
"max_pages_per_category": 3
}
```
#### `get_product`
Get a single product by searching for it in a specific category.
**Input**:
- `category_id` (string, required): Category ID to search in
- `product_name` (string, required): Name or partial name of the product to find
- `max_pages` (number, optional): Maximum number of pages to search (default: 1)
**Output**: Matching products in the specified category
#### `get_product_details`
Get detailed product information from individual product page.
**Input**:
- `product_url` (string, required): URL of the product page to get details from
**Output**: Complete product details including nutrition info, ingredients, etc.
#### `get_product_details_by_name`
Get detailed product information by searching for a product name in a category.
**Input**:
- `category_id` (string, required): Category ID to search in
- `product_name` (string, required): Name or partial name of the product to find
**Output**: Detailed product information if found
## Authentication Tools
### `login`
Authenticate user session with Superstore account.
**Input**: None (uses environment variables)
**Output**: Success status and session information
**Example Output**:
```json
{
"success": true,
"message": "Successfully logged in",
"session_info": {
"isAuthenticated": true,
"sessionExpiry": "2023-12-01T15:30:00.000Z",
"lastActivity": "2023-12-01T14:30:00.000Z"
}
}
```
### `logout`
End session and clear cookies.
**Input**: None
**Output**: Success status
### `check_auth_status`
Verify current authentication state.
**Input**: None
**Output**: Authentication status, session info, and statistics
**Example Output**:
```json
{
"isAuthenticated": true,
"session_info": {
"isAuthenticated": true,
"sessionExpiry": "2023-12-01T15:30:00.000Z",
"lastActivity": "2023-12-01T14:30:00.000Z"
},
"session_stats": {
"isAuthenticated": true,
"lastActivity": "2023-12-01T14:30:00.000Z",
"timeSinceLastActivity": 300000,
"isNearExpiry": false
}
}
```
## Order Management Tools
### `get_orders`
Retrieve order history with pagination.
**Input**:
- `limit` (number, optional): Number of orders to fetch (default: 10)
- `offset` (number, optional): Offset for pagination (default: 0)
**Output**: Array of orders with pagination information
**Example Output**:
```json
{
"orders": [
{
"id": "12345",
"date": "2023-12-01",
"status": "Completed",
"total": 150.00,
"items": [
{
"product_id": "prod123",
"name": "Organic Bananas",
"quantity": 2,
"price": 3.99,
"image_url": "https://example.com/banana.jpg"
}
],
"delivery_info": {
"address": "123 Main St, City, Province",
"estimated_delivery": "2023-12-02",
"tracking_number": "TRK123456"
}
}
],
"total": 25,
"hasMore": true
}
```
### `get_order_details`
Get detailed information for a specific order.
**Input**:
- `order_id` (string, required): Order ID to get details for
**Output**: Complete order details including payment method, subtotal, tax, etc.
**Example Output**:
```json
{
"id": "12345",
"order_number": "ORD-12345",
"date": "2023-12-01",
"status": "Completed",
"total": 150.00,
"subtotal": 140.00,
"tax": 10.00,
"shipping": 0.00,
"discount": 0.00,
"payment_method": "Credit Card",
"items": [...],
"delivery_info": {...},
"notes": "Leave at front door"
}
```
### `get_recent_orders`
Get orders from recent period.
**Input**:
- `days` (number, optional): Number of days to look back (default: 30)
**Output**: Array of recent orders
## Data Types
### Order
```typescript
interface Order {
id: string;
date: string;
status: string;
total: number;
items: OrderItem[];
delivery_info?: DeliveryInfo;
}
```
### OrderItem
```typescript
interface OrderItem {
product_id: string;
name: string;
quantity: number;
price: number;
image_url?: string;
}
```
### DeliveryInfo
```typescript
interface DeliveryInfo {
address: string;
estimated_delivery?: string;
tracking_number?: string;
}
```
### OrderDetails
```typescript
interface OrderDetails extends Order {
order_number: string;
payment_method: string;
subtotal: number;
tax: number;
shipping: number;
discount?: number;
notes?: string;
}
```
### ProductDetails
```typescript
interface ProductDetails {
id: string;
name: string;
price: number;
brand?: string;
description?: string;
nutrition_info?: string;
availability: string;
unit?: string;
image_url?: string;
product_url: string;
category_id?: string;
ingredients?: string;
allergens?: string;
storage_instructions?: string;
origin?: string;
organic: boolean;
gluten_free: boolean;
dairy_free: boolean;
vegan: boolean;
kosher: boolean;
halal: boolean;
}
```
## Error Handling
### Common Error Responses
All tools return consistent error responses:
```json
{
"content": [
{
"type": "text",
"text": "Error message describing what went wrong"
}
],
"isError": true
}
```
### Error Types
1. **Authentication Errors**: Invalid credentials, session expired
2. **Network Errors**: Connection timeouts, network failures
3. **Parsing Errors**: Invalid HTML, missing data elements
4. **Validation Errors**: Missing required parameters, invalid input
### Retry Logic
The system automatically retries failed operations with:
- Exponential backoff
- Jitter to prevent thundering herd
- Circuit breaker pattern
- Fallback mechanisms
## Rate Limiting
The system implements built-in rate limiting to:
- Respect Superstore's servers
- Avoid detection as automated traffic
- Maintain stable performance
## Security
### Authentication Requirements
Order management tools require authentication:
- `get_orders`
- `get_order_details`
- `get_recent_orders`
### Environment Variables
Required for authentication:
- `SUPERSTORE_EMAIL`: Your Superstore account email
- `SUPERSTORE_PASSWORD`: Your Superstore account password
- `SESSION_TIMEOUT`: Session timeout in milliseconds (optional)
### Security Features
- Credentials stored in environment variables only
- Session cookies managed securely
- Stealth mode to avoid detection
- Automatic session cleanup
## Performance
### Caching
The system implements intelligent caching:
- Session state caching
- Order data caching
- Product data caching
- Automatic cache invalidation
### Optimization
- Connection pooling
- Browser instance reuse
- Intelligent retry logic
- Efficient data parsing
## Examples
### Complete Workflow
1. **Authenticate**:
```json
{
"tool": "login"
}
```
2. **Get Recent Orders**:
```json
{
"tool": "get_recent_orders",
"arguments": {
"days": 7
}
}
```
3. **Get Order Details**:
```json
{
"tool": "get_order_details",
"arguments": {
"order_id": "12345"
}
}
```
4. **Search Products**:
```json
{
"tool": "get_product",
"arguments": {
"category_id": "28000",
"product_name": "banana"
}
}
```
### Error Handling Example
```json
{
"tool": "get_orders",
"arguments": {
"limit": 10
}
}
```
**Success Response**:
```json
{
"content": [
{
"type": "text",
"text": "{\"orders\": [...], \"total\": 25, \"hasMore\": true}"
}
],
"isError": false
}
```
**Error Response**:
```json
{
"content": [
{
"type": "text",
"text": "Error getting orders: Authentication failed"
}
],
"isError": true
}
```
