# Trade Me MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with access to the Trade Me API, enabling interaction with New Zealand's largest online marketplace.

## Features

### Current Implementation
**Phase 1 - Foundation:**
- ✅ OAuth 1.0a authentication
- ✅ Catalogue tools (no authentication required):
  - Get category tree
  - Get category details and attributes
  - Get localities and districts
  - Get legal notices

**Phase 2 - Search & Discovery:**
- ✅ Search tools (no authentication required):
  - General marketplace search
  - Property search (residential, rental, commercial)
  - Motors search (cars, motorcycles, boats)
  - Jobs search
  - Services search

**Phase 3 - Listing Retrieval:**
- ✅ Listing details and information:
  - Get listing details, photos, and Q&A
  - View bidding history and shipping options
  - Find similar listings
- ✅ Watchlist management (requires authentication):
  - View watchlist
  - Add/remove items from watchlist

**Phase 4 - Bidding & Buying:**
- ✅ Bidding tools (requires authentication):
  - Place bids on auctions
  - Buy Now purchases
  - View won/lost auctions
  - View current bids
- ✅ Offers (requires authentication):
  - Make fixed price offers
  - Withdraw offers
  - Accept/decline offers (seller)
- ✅ Purchase management (requires authentication):
  - View purchase history

### Planned Features
- Selling and listing management
- User account management
- Saved searches and favourites

## Installation

### Prerequisites
- Python 3.11 or higher
- Trade Me API credentials ([Get them here](https://www.trademe.co.nz/MyTradeMe/Api/DeveloperOptions.aspx))

### Setup

1. Clone the repository:
```bash
git clone <repository-url>
cd trademe-mcp
```

2. Create a virtual environment:
```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

3. Install dependencies:
```bash
pip install -e .
```

4. Configure environment variables:
```bash
cp .env.example .env
# Edit .env with your Trade Me API credentials
```

### Environment Variables

```bash
# Required
TRADEME_CONSUMER_KEY=your_consumer_key
TRADEME_CONSUMER_SECRET=your_consumer_secret

# Optional (required for authenticated endpoints)
TRADEME_ACCESS_TOKEN=your_access_token
TRADEME_ACCESS_TOKEN_SECRET=your_token_secret

# Configuration
TRADEME_ENVIRONMENT=sandbox  # or 'production'
LOG_LEVEL=INFO
```

## Usage

### Running the Server

```bash
python -m trademe_mcp.server
```

### MCP Client Configuration

#### Claude Desktop

Add to your Claude Desktop configuration file:

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

```json
{
  "mcpServers": {
    "trademe": {
      "command": "python",
      "args": ["-m", "trademe_mcp.server"],
      "env": {
        "TRADEME_CONSUMER_KEY": "your_consumer_key",
        "TRADEME_CONSUMER_SECRET": "your_consumer_secret",
        "TRADEME_ENVIRONMENT": "sandbox"
      }
    }
  }
}
```

#### Other MCP Clients

The server uses standard MCP protocol over stdio. Configure your client to run:
```bash
python -m trademe_mcp.server
```

## Available Tools

### Catalogue Tools (No Authentication Required)

#### `get_categories`
Retrieve the full Trade Me category tree.

**Parameters:**
- `depth` (optional): Limit subcategory depth (1-4)
- `with_counts` (optional): Include listing counts (boolean)

**Example:**
```json
{
  "depth": 2,
  "with_counts": true
}
```

#### `get_category_details`
Get detailed information about a specific category.

**Parameters:**
- `category_number` (required): Trade Me category number (e.g., "0004-0369-6076-")
- `depth` (optional): Limit subcategory depth

**Example:**
```json
{
  "category_number": "0004-0369-6076-",
  "depth": 1
}
```

#### `get_localities`
Retrieve all Trade Me localities (regions, districts, suburbs).

**Example:**
```json
{}
```

#### `get_locality_details`
Get details about a specific locality.

**Parameters:**
- `locality_id` (required): The locality ID number

**Example:**
```json
{
  "locality_id": 100
}
```

#### `get_districts`
Retrieve all Trade Me districts.

**Example:**
```json
{}
```

#### `get_attributes`
Get available attributes for a category.

**Parameters:**
- `category_number` (required): Trade Me category number

**Example:**
```json
{
  "category_number": "0004-0369-6076-"
}
```

#### `get_legal_notice`
Get legal notice text for a category.

**Parameters:**
- `category_number` (required): Trade Me category number

**Example:**
```json
{
  "category_number": "0004-0369-6076-"
}
```

### Search Tools (No Authentication Required)

#### `search_general`
Search the Trade Me marketplace across all categories.

**Parameters:**
- `search_string` (optional): Search keywords
- `category` (optional): Category number to filter by
- `price_min` (optional): Minimum price
- `price_max` (optional): Maximum price
- `condition` (optional): Item condition (New, Used, Refurbished)
- `buy_now_only` (optional): Only show Buy Now listings
- `region` (optional): Region ID
- `district` (optional): District ID
- `suburb` (optional): Suburb ID
- `page` (optional): Page number (default: 1)
- `rows` (optional): Results per page (default: 25, max: 500)
- `sort_order` (optional): Sort order (Default, ExpiryAsc, ExpiryDesc, PriceAsc, PriceDesc, Featured)

**Example:**
```json
{
  "search_string": "laptop",
  "price_max": 1000,
  "condition": "New",
  "rows": 50
}
```

#### `search_property_residential`
Search for residential properties for sale.

**Parameters:**
- `search_string` (optional): Search keywords
- `region` (optional): Region ID
- `district` (optional): District ID
- `suburb` (optional): Suburb ID
- `price_min` (optional): Minimum price
- `price_max` (optional): Maximum price
- `bedrooms_min` (optional): Minimum bedrooms
- `bedrooms_max` (optional): Maximum bedrooms
- `bathrooms_min` (optional): Minimum bathrooms
- `property_type` (optional): Property type (House, Apartment, Townhouse, Unit, Land)
- `adjacent_suburbs` (optional): Include adjacent suburbs
- `page` (optional): Page number
- `rows` (optional): Results per page (max 500)

**Example:**
```json
{
  "region": 9,
  "bedrooms_min": 3,
  "price_max": 800000,
  "property_type": "House"
}
```

#### `search_property_rental`
Search for rental properties.

**Parameters:**
- `search_string` (optional): Search keywords
- `region` (optional): Region ID
- `district` (optional): District ID
- `suburb` (optional): Suburb ID
- `price_min` (optional): Minimum weekly rent
- `price_max` (optional): Maximum weekly rent
- `bedrooms_min` (optional): Minimum bedrooms
- `bedrooms_max` (optional): Maximum bedrooms
- `property_type` (optional): Property type
- `pets_ok` (optional): Allow pets
- `smokers_ok` (optional): Allow smokers
- `date_available` (optional): Date available from (YYYY-MM-DD)
- `adjacent_suburbs` (optional): Include adjacent suburbs
- `page` (optional): Page number
- `rows` (optional): Results per page (max 500)

**Example:**
```json
{
  "region": 9,
  "bedrooms_min": 2,
  "price_max": 500,
  "pets_ok": true
}
```

#### `search_property_commercial`
Search for commercial real estate.

**Parameters:**
- `search_string` (optional): Search keywords
- `region` (optional): Region ID
- `district` (optional): District ID
- `suburb` (optional): Suburb ID
- `price_min` (optional): Minimum price
- `price_max` (optional): Maximum price
- `property_type` (optional): Commercial property type (Office, Retail, Industrial, Land)
- `area_min` (optional): Minimum floor area (sqm)
- `area_max` (optional): Maximum floor area (sqm)
- `page` (optional): Page number
- `rows` (optional): Results per page (max 500)

**Example:**
```json
{
  "property_type": "Office",
  "region": 9,
  "area_min": 100
}
```

#### `search_motors`
Search for motor vehicles.

**Parameters:**
- `search_string` (optional): Search keywords (make/model)
- `category` (optional): Motors category
- `price_min` (optional): Minimum price
- `price_max` (optional): Maximum price
- `year_min` (optional): Minimum year
- `year_max` (optional): Maximum year
- `odometer_min` (optional): Minimum odometer reading (km)
- `odometer_max` (optional): Maximum odometer reading (km)
- `make` (optional): Vehicle make
- `model` (optional): Vehicle model
- `body_style` (optional): Body style (Sedan, SUV, Hatchback, etc.)
- `transmission` (optional): Transmission type (Automatic, Manual)
- `fuel_type` (optional): Fuel type (Petrol, Diesel, Electric, Hybrid)
- `engine_size_min` (optional): Minimum engine size (cc)
- `engine_size_max` (optional): Maximum engine size (cc)
- `region` (optional): Region ID
- `page` (optional): Page number
- `rows` (optional): Results per page (max 500)

**Example:**
```json
{
  "make": "Toyota",
  "year_min": 2015,
  "price_max": 25000,
  "transmission": "Automatic"
}
```

#### `search_jobs`
Search for job listings.

**Parameters:**
- `search_string` (optional): Search keywords (job title, company)
- `category` (optional): Jobs category number
- `region` (optional): Region ID
- `district` (optional): District ID
- `type` (optional): Job type (FullTime, PartTime, Contract, Casual, Temporary)
- `pay_min` (optional): Minimum salary/pay
- `pay_max` (optional): Maximum salary/pay
- `pay_type` (optional): Pay period (Annual, Hourly, Daily)
- `work_type` (optional): Work arrangement (Office, Remote, Hybrid)
- `page` (optional): Page number
- `rows` (optional): Results per page (max 500)

**Example:**
```json
{
  "search_string": "software developer",
  "region": 9,
  "type": "FullTime",
  "pay_min": 80000
}
```

#### `search_services`
Search for professional services and tradespeople.

**Parameters:**
- `search_string` (optional): Search keywords
- `category` (optional): Services category number
- `region` (optional): Region ID
- `district` (optional): District ID
- `suburb` (optional): Suburb ID
- `page` (optional): Page number
- `rows` (optional): Results per page (max 500)

**Example:**
```json
{
  "search_string": "plumber",
  "region": 9
}
```

### Listing Retrieval Tools

#### `get_listing_details`
Get comprehensive details about a specific listing.

**Parameters:**
- `listing_id` (required): The Trade Me listing ID
- `return_metadata` (optional): Include additional metadata

**Example:**
```json
{
  "listing_id": 4567890123
}
```

#### `get_listing_photos`
Get all photos for a listing in various sizes.

**Parameters:**
- `listing_id` (required): The Trade Me listing ID

**Example:**
```json
{
  "listing_id": 4567890123
}
```

#### `get_listing_questions`
Get questions and answers (Q&A) for a listing.

**Parameters:**
- `listing_id` (required): The Trade Me listing ID
- `page` (optional): Page number for pagination
- `rows` (optional): Number of results per page

**Example:**
```json
{
  "listing_id": 4567890123,
  "page": 1,
  "rows": 20
}
```

#### `get_bidding_history`
Get the bidding history for an auction listing.

**Parameters:**
- `listing_id` (required): The Trade Me listing ID

**Example:**
```json
{
  "listing_id": 4567890123
}
```

#### `get_shipping_options`
Get available shipping methods and costs.

**Parameters:**
- `listing_id` (required): The Trade Me listing ID

**Example:**
```json
{
  "listing_id": 4567890123
}
```

#### `get_similar_listings`
Find listings similar to a specified listing.

**Parameters:**
- `listing_id` (required): The Trade Me listing ID
- `rows` (optional): Number of results to return

**Example:**
```json
{
  "listing_id": 4567890123,
  "rows": 20
}
```

### Watchlist Tools (Require Authentication)

#### `get_watchlist`
Get the authenticated user's watchlist.

**Parameters:**
- `category` (optional): Filter by category number
- `page` (optional): Page number
- `rows` (optional): Results per page (max 500)

**Example:**
```json
{
  "page": 1,
  "rows": 50
}
```

#### `add_to_watchlist`
Add a listing to the authenticated user's watchlist.

**Parameters:**
- `listing_id` (required): The Trade Me listing ID to watch
- `email_option` (optional): Email notification preference (0=None, 1=Daily, 2=Immediate)

**Example:**
```json
{
  "listing_id": 4567890123,
  "email_option": 1
}
```

#### `remove_from_watchlist`
Remove a listing from the authenticated user's watchlist.

**Parameters:**
- `listing_id` (required): The Trade Me listing ID to unwatch

**Example:**
```json
{
  "listing_id": 4567890123
}
```

### Bidding & Buying Tools (Require Authentication)

#### `place_bid`
Place a bid on an auction listing.

**Parameters:**
- `listing_id` (required): The Trade Me listing ID to bid on
- `amount` (required): The bid amount in NZD
- `shipping_option` (optional): Shipping option ID

**Example:**
```json
{
  "listing_id": 4567890123,
  "amount": 150.00
}
```

#### `buy_now`
Purchase a listing using Buy Now.

**Parameters:**
- `listing_id` (required): The Trade Me listing ID to purchase
- `quantity` (optional): Number of items to purchase (default: 1)
- `shipping_option` (optional): Shipping option ID
- `accept_terms` (optional): Accept seller's terms and conditions

**Example:**
```json
{
  "listing_id": 4567890123,
  "quantity": 1,
  "accept_terms": true
}
```

#### `make_offer`
Make a fixed price offer on a listing.

**Parameters:**
- `listing_id` (required): The Trade Me listing ID
- `price` (required): The offer amount in NZD
- `message` (optional): Optional message to seller

**Example:**
```json
{
  "listing_id": 4567890123,
  "price": 500.00,
  "message": "Is this negotiable?"
}
```

#### `withdraw_offer`
Withdraw a previously made fixed price offer.

**Parameters:**
- `offer_id` (required): The offer ID to withdraw

**Example:**
```json
{
  "offer_id": 123456
}
```

#### `accept_offer`
Accept an offer made on your listing (seller action).

**Parameters:**
- `offer_id` (required): The offer ID to accept

**Example:**
```json
{
  "offer_id": 123456
}
```

#### `decline_offer`
Decline an offer made on your listing (seller action).

**Parameters:**
- `offer_id` (required): The offer ID to decline

**Example:**
```json
{
  "offer_id": 123456
}
```

#### `get_purchase_history`
Get the authenticated user's purchase history.

**Parameters:**
- `page` (optional): Page number for pagination
- `rows` (optional): Results per page (max 500)
- `filter` (optional): Filter by status (All, EmailSent, PaymentReceived, GoodsShipped)

**Example:**
```json
{
  "page": 1,
  "rows": 50,
  "filter": "All"
}
```

#### `get_won_items`
Get auctions the authenticated user has won.

**Parameters:**
- `page` (optional): Page number for pagination
- `rows` (optional): Results per page (max 500)

**Example:**
```json
{
  "page": 1,
  "rows": 25
}
```

#### `get_lost_items`
Get auctions the authenticated user bid on but lost.

**Parameters:**
- `page` (optional): Page number for pagination
- `rows` (optional): Results per page (max 500)

**Example:**
```json
{
  "page": 1,
  "rows": 25
}
```

#### `get_bidding_on`
Get items the authenticated user is currently bidding on.

**Parameters:**
- `page` (optional): Page number for pagination
- `rows` (optional): Results per page (max 500)

**Example:**
```json
{
  "page": 1,
  "rows": 25
}
```

## Development

### Running Tests

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=trademe_mcp
```

### Code Quality

```bash
# Format code
black src tests

# Lint
ruff check src tests

# Type checking
mypy src
```

## API Documentation

- [Trade Me API Reference](https://developer.trademe.co.nz/api-reference/)
- [Trade Me Sandbox](https://www.tmsandbox.co.nz/)
- [MCP Documentation](https://modelcontextprotocol.io/)

## Getting Trade Me API Credentials

1. Register for a Trade Me account
2. Go to [Developer Options](https://www.trademe.co.nz/MyTradeMe/Api/DeveloperOptions.aspx)
3. Create a new application
4. Note your Consumer Key and Consumer Secret
5. For authenticated endpoints, complete OAuth flow to get Access Token and Token Secret

## Troubleshooting

### Authentication Errors
- Verify your API credentials are correct
- Check you're using the right environment (sandbox vs production)
- Ensure Access Token is set for authenticated endpoints

### Connection Issues
- Confirm you have internet connectivity
- Check if Trade Me API is accessible
- Verify firewall settings

### Tool Errors
- Check the tool parameters match the schema
- Review server logs for detailed error messages
- Ensure category numbers are in correct format (e.g., "0004-0369-6076-")

## Project Structure

```
trademe-mcp/
├── src/trademe_mcp/
│   ├── __init__.py
│   ├── server.py          # Main MCP server
│   ├── auth.py            # OAuth 1.0a implementation
│   ├── client.py          # Trade Me API client
│   └── tools/
│       ├── __init__.py
│       └── catalogue.py   # Catalogue tools
├── tests/
├── .env.example
├── .gitignore
├── pyproject.toml
└── README.md
```

## License

[Your License Here]

## Contributing

Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## Support

For issues and questions:
- Trade Me API: [Developer Documentation](https://developer.trademe.co.nz/)
- MCP Protocol: [MCP Documentation](https://modelcontextprotocol.io/)
- This project: [GitHub Issues](your-repo-url/issues)