tppwholesale-mcp/README.md

# tppwholesale-mcp

MCP (Model Context Protocol) server for the [TPP Wholesale](https://www.tppwholesale.com.au/) domain registrar API. Exposes domain registration, DNS management, renewals, transfers, and account queries as MCP tools that can be used by AI assistants like Claude.

## Features

- **Domain availability** — check if domains are available across 1,200+ TLDs
- **Domain registration** — register new domains with full .au eligibility support
- **Domain renewal** — renew existing registrations
- **Domain transfer** — transfer domains from other registrars
- **Nameserver management** — add/remove nameservers on any domain
- **Domain lock** — lock/unlock domains to prevent unauthorized transfers
- **Contact management** — create and manage WHOIS contacts
- **Account balance** — check prepaid account balance
- **Order tracking** — check status of pending registrations/renewals/transfers
- **Domain listing** — list and filter all domains in the account

## Quick start

### 1. Get API credentials

Log in to [The Console](https://theconsole.tppwholesale.com.au/) and go to **Account Settings > API Preferences** to find your:
- Account Number
- API Key (User ID)
- Secret Key (Password)

### 2. Configure

```bash
cp .env.example .env
# Edit .env with your credentials
```

### 3. Run with Docker

```bash
docker compose up -d
```

The MCP server will be available at `http://localhost:8089/mcp/mcp`.

### 4. Connect to Claude Code

Add to your Claude Code MCP config (`.claude.json` or project settings):

```json
{
  "mcpServers": {
    "tppwholesale": {
      "type": "streamable-http",
      "url": "http://localhost:8089/mcp/mcp"
    }
  }
}
```

## MCP Tools

| Tool | Description |
|------|-------------|
| `check_domain_availability` | Check if domains are available for registration |
| `register_domain` | Register a new domain name |
| `create_contact` | Create a WHOIS contact for use in registrations |
| `renew_domain` | Renew an existing domain |
| `get_domain_details` | Get full details (contacts, nameservers, status) |
| `list_domains` | List and filter domains in the account |
| `update_nameservers` | Add or remove nameservers on a domain |
| `set_domain_lock` | Lock or unlock a domain |
| `check_order_status` | Check status of a pending order |
| `get_account_balance` | Get prepaid account balance (AUD) |
| `get_renewal_info` | Check renewal status and expiry date |
| `check_transfer` | Check if a domain can be transferred in |
| `transfer_domain` | Request a domain transfer |

## .au domain registration

Australian domains (.com.au, .net.au, .org.au, etc.) require additional eligibility fields:

| Field | Description | Example |
|-------|-------------|---------|
| `registrant_name` | Legal entity name | "Mineracks Pty Ltd" |
| `registrant_id` | ABN or ACN | "54109565095" |
| `registrant_id_type` | ID type code | "ABN" or "ACN" |
| `eligibility_type` | Why the registrant is eligible | "Company" |
| `eligibility_reason` | Relationship to domain | "Exact match" |

### Registrant ID types
- `ABN` — Australian Business Number
- `ACN` — Australian Company Number
- `TM` — Trademark Number
- `OTHER` — Other

### Eligibility types
- `Company` — Registered company
- `Sole Trader` — Sole trader
- `Partnership` — Partnership
- `Registered Business` — Registered business name
- `Trust` — Trust
- `Government Entity` — Government body
- `Other` — Other entity type

## REST API

In addition to MCP, two REST endpoints are available:

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/health` | GET | Health check |
| `/api/balance` | GET | Account balance (requires `X-Api-Key` header if `TPP_API_KEY` is set) |

## Architecture

```
Claude Code / AI Assistant
        │
        ▼ (MCP Streamable HTTP)
┌─────────────────────┐
│  tppwholesale-mcp    │
│  (FastMCP + httpx)   │
│  Port 8089           │
└─────────┬───────────┘
          │ HTTPS
          ▼
┌─────────────────────┐
│  TPP Wholesale API   │
│  theconsole.         │
│  tppwholesale.com.au │
└─────────────────────┘
```

## Environment variables

| Variable | Required | Description |
|----------|----------|-------------|
| `TPP_ACCOUNT_NO` | Yes | TPP Wholesale account number |
| `TPP_USER_ID` | Yes | API key from The Console |
| `TPP_PASSWORD` | Yes | Secret key from The Console |
| `TPP_ALLOWED_HOSTS` | No | Comma-separated allowed Host headers (default: `localhost:8089,127.0.0.1:8089`) |
| `TPP_API_KEY` | No | Optional API key for REST endpoints |
| `TPP_PORT` | No | Port to listen on (default: `8089`) |

## Development

```bash
# Install dependencies
pip install -r requirements.txt

# Run directly
TPP_ACCOUNT_NO=xxx TPP_USER_ID=xxx TPP_PASSWORD=xxx python app/server.py

# Run tests (TODO)
pytest tests/
```

## API reference

This MCP server wraps the [TPP Wholesale HTTP API v2.7.4](https://www.tppwholesale.com.au/api/). The full API specification is available as a [PDF download](https://www.tppwholesale.com.au/wp-content/uploads/2023/10/2.7.4_TPPW_HTTP_API_Domain_Specs.pdf).

## License

MIT