# mcp-commerce-starter

An MCP server is how you hand an AI agent a real set of hands. This one exposes
a Shopify commerce backend — orders, inventory, logistics, fulfillment — as ~22
typed tools an agent can actually call, with the guardrails that keep it from
doing something irreversible.

It's ~1,100 lines of Node.js, and it's a *real* server, not a tutorial. It
handles pagination over large order sets, idempotent fulfillment calls,
structured errors the model can recover from, and read/write separation so an
agent can analyze freely but only mutate through explicit, narrow tools.

I'm shipping it as a starter because the gap between "MCP hello-world" and
"MCP server you'd trust against a production backend" is exactly the part
nobody publishes.

---

## Tools

### Analytics (read-only)
| Tool | What it does |
|------|--------------|
| `get_monthly_sales` | Revenue, order count, AOV, COD/prepaid split for a month |
| `get_daily_sales` | Sales for a specific date |
| `get_monthly_trend` | Month-over-month trend table |
| `compare_months` | Side-by-side comparison of two months |
| `get_product_sales_by_month` | Per-product revenue breakdown |
| `get_store_stats` | Lifetime store stats |

### Products (read + write)
| Tool | What it does |
|------|--------------|
| `get_all_products` | Full catalog with status, price, SEO fields |
| `get_product` | Single product by ID |
| `update_product_seo` | Update SEO meta title + description |
| `update_product_description` | Update product body HTML |
| `update_product_image_alt` | Update image alt text |
| `get_product_page_analytics` | Cross-references catalog with orders to flag low-converting products |
| `get_inventory_status` | Live inventory levels across all products |

### Orders (read-only)
| Tool | What it does |
|------|--------------|
| `search_order` | Find order by name, phone, or email |
| `get_order` | Single order by ID |
| `get_order_tracking` | AWB + tracking status for an order |
| `get_recent_orders` | Last N orders |
| `get_cod_orders` | COD orders for a date range |
| `get_unfulfilled_orders` | Pending fulfillment queue |

### Logistics (write — Delhivery API)
| Tool | What it does |
|------|--------------|
| `create_delhivery_shipment` | Book a forward shipment (creates AWB) |
| `create_delhivery_reverse_pickup` | Book a return pickup from customer |
| `fulfill_shopify_order` | Mark order fulfilled in Shopify with tracking |

---

## Architecture Notes

**Auth:** Uses Shopify Partner app OAuth flow (`client_credentials`) — access tokens
cached in memory, auto-refreshed before expiry. No session tokens stored to disk.

**Pagination:** Large order sets paginated transparently via Shopify's cursor-based
`page_info` system. Callers get complete data without managing cursors.

**Read/write separation:** Analytics, product reads, and order reads are all
read-only. Only `update_*`, `create_*`, and `fulfill_*` tools mutate state.
This separation is enforced at the tool description level — the model is told
explicitly which tools are safe to call freely vs. which require confirmation.

**IST date handling:** All date boundaries shifted for IST (UTC+5:30). A query
for "today's orders" returns orders placed on the Indian calendar day, not the
UTC day.

**Structured errors:** Tool errors return a JSON object with `error`, `code`,
and `detail` fields — not raw stack traces. The model can parse the error and
either retry with corrected inputs or explain the failure to the user.

---

## Setup

### 1. Clone and install

```bash
git clone https://github.com/singhjitesh889-blip/mcp-commerce-starter.git
cd mcp-commerce-starter
npm install
```

### 2. Configure environment

```bash
cp .env.example .env
# Fill in your Shopify credentials and seller details
```

### 3. Create a Shopify Partner app

You need a Shopify Partner app with the following scopes:
- `read_products`, `write_products`
- `read_orders`
- `read_inventory`

Get your `client_id` and `client_secret` from the Shopify Partner Dashboard.

### 4. Wire into Claude Code

Add to `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "commerce": {
      "command": "node",
      "args": ["/path/to/mcp-commerce-starter/index.js"],
      "env": {
        "SHOPIFY_SHOP": "https://your-store.myshopify.com",
        "SHOPIFY_CLIENT_ID": "your_client_id",
        "SHOPIFY_CLIENT_SECRET": "your_client_secret",
        "SELLER_NAME": "Your Business",
        "SELLER_CITY": "Your City",
        "SELLER_STATE": "Your State",
        "RETURN_PIN": "000000",
        "RETURN_PHONE": "9999999999",
        "RETURN_ADDRESS": "Your return address",
        "RETURN_CITY": "Your City",
        "RETURN_STATE": "Your State"
      }
    }
  }
}
```

### 5. Test

```
> what were my sales last month?
> show me unfulfilled orders
> search for order #1234
```

---

## The Logistics Tools

The Delhivery integration (`create_delhivery_shipment`, `create_delhivery_reverse_pickup`)
requires a Delhivery API account. These are India-specific — swap in your own
logistics provider's API for other markets. The tool interface stays the same;
the API call underneath is what changes.

If you don't use Delhivery, leave `DELHIVERY_API_TOKEN` unset — the tools
will return an error if called, but all other tools continue to work.

---

## Related

- **[claude-code-knowledge-architecture](https://github.com/singhjitesh889-blip/claude-code-knowledge-architecture)** — the methodology that makes this server useful in sustained AI-assisted operations.
- **[mcp-seo-starter](https://github.com/singhjitesh889-blip/mcp-seo-starter)** — companion MCP server for search performance data.