Woolworths-mcp

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 12 Open GitHub ↗

No description available.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Woolworths MCP Server

A Model Context Protocol (MCP) server for interacting with Woolworths Australia's online shopping platform. This server provides tools for browsing products, searching items, viewing specials, and more.

## Features

- **Browser Automation**: Uses Puppeteer to open a browser, navigate to Woolworths, and capture session cookies
- **Session Management**: Maintains session cookies for authenticated API requests
- **Product Search**: Search for products across the Woolworths catalog with filtering and sorting
- **Product Details**: Get detailed information about specific products
- **Specials & Deals**: Browse current specials and promotional offers
- **Category Browsing**: Explore product categories
- **Shopping Cart**: Add items to cart, view cart contents, update quantities, and remove items

## Installation

1. Install dependencies:

```bash
npm install
```

2. Build the TypeScript code:

```bash
npm run build
```

## Usage

### Running the Server

The MCP server runs on stdio and is designed to be used with MCP-compatible clients (like Claude Desktop, Cline, or other AI assistants).

```bash
npm start
```

### Configuration for Claude Desktop

Add this to your Claude Desktop configuration file:

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "woolworths": {
      "command": "node",
      "args": ["C:\\Users\\eglass\\Projects\\Woolworths\\dist\\index.js"]
    }
  }
}
```

Make sure to update the path to match your installation directory.

## Available Tools

### 1. woolworths_open_browser

Opens a browser and navigates to the Woolworths website. This is typically the first step to establish a session.

**Parameters:**
- `headless` (boolean, optional): Whether to run in headless mode (default: false)

**Example:**
```json
{
  "headless": false
}
```

### 2. woolworths_navigate

Navigate to a specific URL on the Woolworths website.

**Parameters:**
- `url` (string, required): The URL to navigate to

### 3. woolworths_get_cookies

Retrieves and stores session cookies from the current browser session. Run this after logging in or when you have an active session.

**Parameters:** None

### 4. woolworths_close_browser

Closes the browser instance while preserving the captured session cookies.

**Parameters:** None

### 5. woolworths_search_products

Search for products on Woolworths.

**Parameters:**
- `searchTerm` (string, required): The product search term
- `pageSize` (number, optional): Number of results to return (default: 20)

**Example:**
```json
{
  "searchTerm": "milk",
  "pageSize": 20
}
```

### 6. woolworths_get_product_details

Get detailed information about a specific product by its stockcode.

**Parameters:**
- `stockcode` (string, required): The product stockcode/ID

### 7. woolworths_get_specials

Get current specials and deals from Woolworths.

**Parameters:**
- `category` (string, optional): Category filter (e.g., 'fruit-veg', 'meat-seafood')
- `pageSize` (number, optional): Number of results to return (default: 20)

### 8. woolworths_get_categories

Get the list of available product categories.

**Parameters:** None

### 9. woolworths_add_to_cart

Add a product to the shopping cart/trolley.

**Parameters:**
- `stockcode` (number, required): The product stockcode/ID
- `quantity` (number, optional): Quantity to add (default: 1)

**Example:**
```json
{
  "stockcode": 123456,
  "quantity": 2
}
```

### 10. woolworths_get_cart

Get the current contents of the shopping cart/trolley.

**Parameters:** None

### 11. woolworths_remove_from_cart

Remove a product from the shopping cart/trolley.

**Parameters:**
- `stockcode` (number, required): The product stockcode/ID to remove

### 12. woolworths_update_cart_quantity

Update the quantity of a product in the shopping cart/trolley.

**Parameters:**
- `stockcode` (number, required): The product stockcode/ID
- `quantity` (number, required): New quantity

## Typical Workflow

1. **Open Browser**: Use `woolworths_open_browser` to launch a browser window
2. **Log In** (if needed): The browser will open in non-headless mode by default, allowing you to manually log in to your Woolworths account if required
3. **Capture Cookies**: Use `woolworths_get_cookies` to capture session cookies
4. **Close Browser**: Use `woolworths_close_browser` to close the browser (cookies are preserved)
5. **Use API Tools**: Now you can use any of the API tools (search, get product details, etc.)

## Example Usage Scenario

```
1. User: "Open the Woolworths browser"
   → Calls: woolworths_open_browser
   
2. User manually logs in on the opened browser (if needed)

3. User: "Get the session cookies"
   → Calls: woolworths_get_cookies
   
4. User: "Close the browser"
   → Calls: woolworths_close_browser
   
5. User: "Search for bananas"
   → Calls: woolworths_search_products with searchTerm="bananas"
   
6. User: "What are the current specials?"
   → Calls: woolworths_get_specials

7. User: "Add product 123456 to my cart"
   → Calls: woolworths_add_to_cart with stockcode=123456

8. User: "Show me my cart"
   → Calls: woolworths_get_cart
```

## Technical Details

### Browser Automation

The server uses Puppeteer to:
- Launch a Chromium browser instance
- Navigate to Woolworths website
- Capture cookies from the browser session
- Maintain user agent and browser fingerprint

### API Integration

Once cookies are captured, the server makes authenticated requests to Woolworths' internal APIs:
- Search API: `/apis/ui/Search/products` (POST)
- Product Detail API: `/apis/ui/product/detail/{stockcode}`
- Browse/Category API: `/apis/ui/browse/category`
- Categories API: `/apis/ui/PiesCategoriesWithSpecials`
- Shopping Cart API: `/apis/ui/Trolley/*` (AddItem, RemoveItem, UpdateItem, Get)

### Session Management

Session cookies are stored in memory for the duration of the server process. If the server restarts, you'll need to recapture cookies by opening the browser again.

## Development

### Watch Mode

For development with auto-recompilation:

```bash
npm run dev
```

### Building

```bash
npm run build
```

## Requirements

- Node.js 18 or higher
- npm or yarn
- Chromium/Chrome (automatically installed by Puppeteer)

## Notes

- The browser opens in non-headless mode by default to allow for manual login
- Session cookies are stored in memory and persist until the server is restarted
- API endpoints are based on Woolworths' public web interface and may change
- Always respect Woolworths' Terms of Service when using this tool

## Troubleshooting

### Browser won't open
- Check that Puppeteer installed correctly
- Try running with headless: true if display issues occur

### API requests fail
- Ensure you've captured cookies with `woolworths_get_cookies`
- Check that the session hasn't expired (you may need to re-open browser and capture new cookies)
- Verify the API endpoints are still valid

### Connection issues
- Ensure you have a stable internet connection
- Check that Woolworths website is accessible from your location

## License

MIT

## Disclaimer

This is an unofficial tool and is not affiliated with or endorsed by Woolworths Group Limited. Use at your own risk and ensure compliance with Woolworths' Terms of Service.

Woolworths-mcp

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README