@striderlabs/mcp-bjs 0.1.0

package/README.md

@@ -0,0 +1,194 @@
+# @striderlabs/mcp-bjs
+
+BJ's Wholesale Club MCP server for personal AI agents. Search products, manage your cart, check club inventory, find gas prices, manage coupons, and more — all from Claude or any MCP-compatible AI client.
+
+## Features
+
+- **Product search** — Find items with prices, stock status, and member pricing
+- **Product details** — Full specs, descriptions, and pricing for any item
+- **Club inventory** — Check real-time stock at your local BJ's club
+- **Cart management** — Add, view, and remove items; initiate checkout for pickup, delivery, or shipping
+- **Membership** — View membership info and renew
+- **Coupons & offers** — Browse, clip, and track digital coupons
+- **Order history** — View past orders and track shipments
+- **Club finder** — Find BJ's locations near any zip code
+- **Gas prices** — Check current fuel prices at BJ's stations
+
+## Installation
+
+```bash
+npm install -g @striderlabs/mcp-bjs
+```
+
+Or use directly with `npx`:
+
+```bash
+npx @striderlabs/mcp-bjs
+```
+
+**Install Chromium for browser automation:**
+
+```bash
+npx patchright install chrome
+```
+
+## MCP Client Configuration
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "bjs": {
+      "command": "npx",
+      "args": ["-y", "@striderlabs/mcp-bjs"]
+    }
+  }
+}
+```
+
+### Generic MCP Client
+
+```json
+{
+  "mcpServers": {
+    "bjs": {
+      "command": "striderlabs-mcp-bjs",
+      "transport": "stdio"
+    }
+  }
+}
+```
+
+## Available Tools
+
+### Authentication
+
+| Tool | Description |
+|------|-------------|
+| `bjs_status` | Check login status and current session |
+| `bjs_login` | Initiate browser login (returns URL for manual sign-in) |
+| `bjs_logout` | Log out and clear saved session |
+
+### Products
+
+| Tool | Description |
+|------|-------------|
+| `bjs_search` | Search products by keyword with optional club filter |
+| `bjs_product_details` | Full product details and pricing by URL |
+| `bjs_check_inventory` | Check in-stock status at a specific club |
+
+### Cart & Checkout
+
+| Tool | Description |
+|------|-------------|
+| `bjs_add_to_cart` | Add item to cart by product URL |
+| `bjs_view_cart` | View cart contents with subtotal and total |
+| `bjs_remove_from_cart` | Remove an item from cart by name |
+| `bjs_checkout` | Start checkout: `pickup`, `delivery`, or `ship` |
+
+### Membership
+
+| Tool | Description |
+|------|-------------|
+| `bjs_membership_info` | Membership number, type, expiry, rewards balance |
+| `bjs_membership_renew` | Navigate to membership renewal page |
+
+### Coupons & Offers
+
+| Tool | Description |
+|------|-------------|
+| `bjs_coupons` | Browse available digital coupons, optionally by category |
+| `bjs_clip_coupon` | Clip a coupon to your membership card |
+| `bjs_my_coupons` | View all clipped coupons |
+
+### Orders
+
+| Tool | Description |
+|------|-------------|
+| `bjs_order_history` | View past orders with status and total |
+| `bjs_order_details` | Full order details with items and tracking |
+
+### Clubs & Gas
+
+| Tool | Description |
+|------|-------------|
+| `bjs_find_clubs` | Find BJ's clubs near a zip code |
+| `bjs_gas_prices` | Current gas prices at BJ's fuel stations |
+
+## Usage Examples
+
+### Find paper towels near me
+
+```
+Search for paper towels at BJ's, then check if the Bounty Select-A-Size is in stock at my nearest club.
+```
+
+1. `bjs_find_clubs` → find nearby club IDs
+2. `bjs_search` with `query: "bounty paper towels"` and `clubId`
+3. `bjs_check_inventory` with the product URL and club ID
+
+### Shop and checkout for pickup
+
+```
+Add 2 packs of Kirkland bottled water to my cart and start in-club pickup checkout.
+```
+
+1. `bjs_search` with `query: "bottled water"`
+2. `bjs_add_to_cart` with `quantity: 2`
+3. `bjs_view_cart` to confirm
+4. `bjs_checkout` with `fulfillmentType: "pickup"`
+
+### Find the cheapest gas
+
+```
+What are the gas prices at BJ's stations near 07001?
+```
+
+1. `bjs_gas_prices` with `zipCode: "07001"`
+
+### Clip all grocery coupons
+
+```
+Clip all available grocery coupons to my BJ's card.
+```
+
+1. `bjs_coupons` with `category: "grocery"`
+2. Loop through results calling `bjs_clip_coupon` for each unclipped coupon
+
+## Authentication
+
+BJ's requires manual sign-in on first use:
+
+1. Call `bjs_login` — the server opens a browser and returns the login URL
+2. Complete sign-in (enter email, password, handle 2FA if prompted)
+3. Call `bjs_status` to confirm the session is active
+4. Session cookies are saved to `~/.strider/bjs/` and reused automatically
+
+## Configuration
+
+Session data is stored at `~/.strider/bjs/`:
+- `cookies.json` — Browser session cookies (auto-refreshed)
+- `session.json` — Membership info cache
+
+## Development
+
+```bash
+git clone https://github.com/striderlabs/mcp-bjs
+cd mcp-bjs
+npm install
+npm run build
+npm start
+```
+
+## Links
+
+- [MCP Protocol](https://modelcontextprotocol.io)
+- [BJ's Wholesale Club](https://www.bjs.com)
+- [Report Issues](https://github.com/striderlabs/mcp-bjs/issues)
+
+---
+
+By [Strider Labs](https://github.com/striderlabs) — MIT License