npm package: @olbrain/bys-mcp
Description: Build Your Store MCP Server - Minimal 5-tool set for product discovery and order tracking (Python-based tools, optimized for MCP buffer limits)
Author: Olbrain
Latest version: 2.2.0

# Build Your Store (BYS) MCP Server

A Model Context Protocol (MCP) server for Build Your Store (BYS) e-commerce platform with **63 Storefront API tools** for customer-facing operations.

## What's New in v2.0.2

- **63 Storefront API Tools**: Complete customer-facing e-commerce operations
- **Admin API Removed**: Streamlined for sales and customer service workflows (prevents MCP buffer overflow)
- **Basic Auth Support**: Added Secret API Key support for BYS instances requiring Basic Authentication
- **Auto-generated Tools**: Tools generated from official BYS Postman collections
- **Dynamic Tool Loading**: Tools loaded from JSON files for easy updates

## Features

### Storefront API (63 tools)
- **Customer Authentication**: Login, registration, password reset
- **Product Discovery**: Browse, search, filter products with variants and pricing
- **Shopping Cart**: Create, update, manage cart items
- **Checkout**: Complete orders, manage shipping/billing addresses
- **Order Management**: Track orders, view order history
- **Customer Profile**: Manage customer information
- **Gift Cards**: Support for gift card purchases and redemption
- **Product Collections**: Browse categorized products
- **Region Support**: Multi-region pricing and currency support

> **Note**: Admin API (348 tools) has been removed to prevent MCP transport buffer overflow. For administrative operations (inventory management, order fulfillment, promotions), use the BYS Admin Dashboard or consider creating a separate Admin-focused MCP server.

## Product Pricing Information

All product tools return comprehensive pricing information to enable value-emphasized sales conversations:

### Price Structure

```json
{
  "price": {
    "current": 789,           // Current price (after discount if applicable)
    "original": 6999,         // Original price (before discount)
    "currency": "INR",        // Currency code
    "has_discount": true,     // Boolean indicating active discount
    "discount_amount": 6210,  // Absolute savings (original - current)
    "discount_percentage": 88.7  // Percentage discount
  }
}
```

### Usage in Agent Conversations

Agents should present prices in this psychologically effective sequence:

1. **Original price** (anchor high)
2. **Discount** (highlight value)
3. **Current price** (final attractive price)

Example:
> "This product was originally priced at ₹6,999. You get an amazing 88% discount - save ₹6,210! Your special price is just ₹789."

This approach:
- Creates psychological anchoring
- Emphasizes customer value
- Increases conversion rates
- Reduces price objections

See Sales Agent Template for detailed pricing presentation guidelines.

### Pricing Behavior and Region Discovery

The MCP server automatically handles regional pricing context to ensure accurate price calculations:

**How it works:**
1. **Environment Variable Check**: First checks for `BYS_DEFAULT_REGION_ID` environment variable
2. **Auto-Discovery**: If not set, automatically discovers the first available region from your store's API
3. **Caching**: Region is cached to avoid repeated API calls
4. **Multi-Level Fallback**: If region discovery fails, falls back to alternative price fields

**Price Data Priority:**
1. `calculated_price` (requires region context - most accurate, includes taxes)
2. `prices` array (fallback if no region)
3. Direct price fields on variant (last resort)
4. Returns `null` if no price data available

**Configuration Example:**
```bash
# Optional: Specify a default region for better performance
export BYS_DEFAULT_REGION_ID="reg_01ABCDEF..."

# Without this variable, the system auto-discovers region on first request
```

**Benefits:**
- ✅ Accurate regional pricing with taxes
- ✅ Zero configuration required (auto-discovery)
- ✅ Manual override available for multi-region stores
- ✅ Graceful fallbacks ensure pricing always available when possible

## Installation

1. Install via npx (recommended):
```bash
npx @olbrain/bys-mcp@latest
```

2. Or clone and install locally:
```bash
git clone https://github.com/olbrain-ai/olbrain-public-tools.git
cd olbrain-public-tools/mcp_servers/bys-mcp
npm install
```

## Configuration

### Environment Variables

Set these environment variables based on which APIs you need:

**Required:**
- `BYS_STORE_URL`: Your BYS store URL (e.g., `https://mystore.com`)

**Recommended:**
- `BYS_STORE_ID`: Your Store ID for x-store-id header (required by some BYS instances)

**Optional (at least one recommended):**
- `BYS_PUBLISHABLE_API_KEY`: Publishable API Key for Storefront API operations
- `BYS_ADMIN_API_TOKEN`: JWT Bearer token for Admin API operations

**Optional (Pricing Optimization):**
- `BYS_DEFAULT_REGION_ID`: Default region ID for price calculations (e.g., `reg_01ABCDEF...`)
  - If not set, the first available region is auto-discovered from the API
  - Improves price accuracy by providing regional context (taxes, currency)
  - Improves performance by skipping region discovery on each request
  - Format: Region ID from your store (usually starts with `reg_`)

### Getting Credentials

#### Storefront API (Publishable API Key)
1. Log in to your BYS Admin panel
2. Navigate to Settings → Publishable API Keys
3. Create a new API key
4. Copy the key (starts with `pk_`)

#### Admin API (JWT Token)
1. Authenticate via `/admin/auth/user/{provider}` endpoint
2. Use the returned JWT token
3. Token format: `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`

#### Store ID (x-store-id header)

Some BYS instances require a Store ID in the `x-store-id` header for all API requests.

**To find your Store ID:**

1. Open your BYS storefront in a browser (e.g., Chrome, Firefox)
2. Open Developer Tools (press F12 or Cmd+Option+I on Mac)
3. Go to the **Network** tab
4. Browse products or perform any action on your storefront
5. Look for API requests to `/store/products` or similar endpoints
6. Click on any request and view the **Headers** tab
7. Find the `x-store-id` header value
8. Copy this value (usually starts with `store_` followed by alphanumeric characters)

**Example:**
```
x-store-id: store_01234567890abcdef
```

If your API returns errors like "x-store-id header is required", you must configure this value.

### Example Configuration

```bash
# Storefront API only
export BYS_STORE_URL="https://mystore.com"
export BYS_STORE_ID="store_01234567890abcdef"  # Optional but recommended
export BYS_PUBLISHABLE_API_KEY="pk_01234567890abcdef"
export BYS_DEFAULT_REGION_ID="reg_01ABCDEF..."  # Optional - improves pricing accuracy

# Admin API only
export BYS_STORE_URL="https://mystore.com"
export BYS_STORE_ID="store_01234567890abcdef"  # Optional but recommended
export BYS_ADMIN_API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
export BYS_DEFAULT_REGION_ID="reg_01ABCDEF..."  # Optional - improves pricing accuracy

# Both APIs (recommended for full functionality)
export BYS_STORE_URL="https://mystore.com"
export BYS_STORE_ID="store_01234567890abcdef"  # Optional but recommended
export BYS_PUBLISHABLE_API_KEY="pk_01234567890abcdef"
export BYS_ADMIN_API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
export BYS_DEFAULT_REGION_ID="reg_01ABCDEF..."  # Optional - improves pricing accuracy
```

## Usage

### Running the Server

```bash
# Via npx
npx @olbrain/bys-mcp@latest

# Or via node
node index.js

# Or via npm
npm start
```

### Using with Claude Desktop

Add to your Claude Desktop configuration (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "build-your-store": {
      "command": "npx",
      "args": ["-y", "@olbrain/bys-mcp@latest"],
      "env": {
        "BYS_STORE_URL": "https://mystore.com",
        "BYS_PUBLISHABLE_API_KEY": "pk_your_key_here",
        "BYS_ADMIN_API_TOKEN": "your_jwt_token_here",
        "BYS_DEFAULT_REGION_ID": "reg_01ABCDEF..."
      }
    }
  }
}
```

## Available Tools

### Storefront API Tools (63)

**Authentication & Customer**
- `callback_validate_authentication_callback`
- `register_retrieve_registration_jwt_token`
- `reset_password_generate_reset_password_token`
- `update_reset_a_customers_password`
- And more...

**Products**
- `products_list_products`
- `product_get_a_product`
- `products_list_a_product_s_variants`
- And more...

**Cart & Checkout**
- `carts_create_cart`
- `cart_get_a_cart`
- `line_items_add_line_item_to_cart`
- `complete_complete_a_cart`
- And more...

**Orders**
- `order_retrieve_an_order`
- `orders_list_orders`
- And more...

### Admin API Tools (348)

**Products & Inventory**
- `products_list_products` (admin version)
- `products_create_product`
- `products_update_a_product`
- `products_delete_a_product`
- `inventory_items_list_inventory_items`
- And 100+ more...

**Orders & Fulfillment**
- `orders_list_orders` (admin version)
- `orders_get_an_order`
- `orders_update_an_order`
- `fulfillments_create_fulfillment`
- And 50+ more...

**Customers**
- `customers_list_customers`
- `customers_create_customer`
- `customers_update_a_customer`
- And 20+ more...

**Store Configuration**
- `promotions_list_promotions`
- `regions_list_regions`
- `tax_rates_list_tax_rates`
- `payment_providers_list_payment_providers`
- And 100+ more...

_For a complete list of all 411 tools, see [tools/medusa_storefront_tools.json](tools/medusa_storefront_tools.json) and [tools/medusa_admin_tools.json](tools/medusa_admin_tools.json)_

## Architecture

### Components

```
bys-mcp/
├── index.js                     # Node.js entry point
├── src/
│   ├── server.py               # MCP server implementation
│   ├── medusa_client.py        # HTTP client for BYS APIs
│   └── tools/
│       └── tool_loader.py      # Dynamic tool loader
├── tools/
│   ├── medusa_storefront_tools.json   # 63 Storefront tools
│   └── medusa_admin_tools.json        # 348 Admin tools
└── README.md
```

### How It Works

1. **Tool Loading**: On startup, the server loads tool definitions from JSON files
2. **Authentication Detection**: Based on the endpoint, the client automatically uses the correct authentication method
3. **Dynamic Execution**: Tools are executed dynamically based on their metadata (HTTP method, endpoint, parameters)
4. **MCP Protocol**: Communicates with clients using the Model Context Protocol over stdio

### Authentication Flow

```python
# Storefront API
GET /store/products
Headers: { "x-publishable-api-key": "pk_..." }

# Admin API
GET /admin/products
Headers: { "Authorization": "Bearer eyJ..." }
```

The client automatically detects the API type from the endpoint and applies the correct authentication.

## Development

### Testing Locally

```bash
# Install dependencies
npm install

# Set environment variables
export BYS_STORE_URL="https://your-store.com"
export BYS_PUBLISHABLE_API_KEY="pk_..."
export BYS_ADMIN_API_TOKEN="eyJ..."

# Run the server
npm start
```

### Adding Custom Tools

To add custom tools, edit the JSON files in `tools/`:

```json
{
  "name": "custom_tool_name",
  "description": "Tool description",
  "input_schema": {
    "type": "object",
    "properties": {
      "param1": {
        "type": "string",
        "description": "Parameter description"
      }
    },
    "required": ["param1"]
  },
  "_metadata": {
    "method": "GET",
    "endpoint": "/store/custom-endpoint",
    "path_params": []
  }
}
```

## Requirements

- **BYS Version**: 2.0+
- **API Version**: v2 (Storefront & Admin)
- **Node.js**: 14+
- **Python**: 3.7+
- **Dependencies**:
  - httpx (Python HTTP client)
  - mcp (Model Context Protocol)

## Troubleshooting

### Tools Not Loading
- Check that JSON files exist in `tools/` directory
- Verify JSON syntax is valid
- Check server logs for loading errors

### Authentication Errors
- Verify your API keys/tokens are correct
- Check that the Store URL is accessible
- Ensure API keys have the correct permissions

### Tool Execution Failures
- Check that the endpoint exists in your BYS version
- Verify required parameters are provided
- Check BYS server logs for API errors

## Changelog

### v2.0.0 (2026-01-20)
- **MAJOR**: Complete rewrite to use API tool collections
- Added support for BYS Admin API (348 tools)
- Increased Storefront API coverage (from 14 to 63 tools)
- Added dual authentication support (Publishable Key + JWT)
- Implemented dynamic tool loading from JSON files
- Auto-generated tools from official Postman collections

### v1.0.0 (2025-01-XX)
- Initial release with 14 hand-coded Storefront API tools

## License

MIT

## Support

For issues and feature requests, please visit:
https://github.com/olbrain-ai/olbrain-public-tools/issues

## Documentation

- [BYS API Documentation](https://docs.medusajs.com/api)
- [BYS Storefront API](https://docs.medusajs.com/api/store)
- [BYS Admin API](https://docs.medusajs.com/api/admin)
- [Model Context Protocol](https://modelcontextprotocol.io)