# MCP Domain Availability Server

A Model Context Protocol (MCP) server for checking domain availability and pricing using the GoDaddy OTE (Operational Test Environment) API.

## Features

- Check domain availability and pricing via GoDaddy OTE sandbox
- Support for multiple TLD suffixes
- Fast and Full check modes
- Support for bulk domain checking
- Rate limiting (60 calls per minute)
- Normalized pricing in dollars with 2 decimal places
- Consistent field naming and data structures
- Period normalization (stored in months, displayed in years)

## Installation

### Using uv (Recommended)

```bash
# Install dependencies
uv add "mcp[cli]"

# Run with MCP Inspector for testing
DOMAIN_API_KEY="your-key:your-secret" mcp dev domain_availability/server.py
```

### Manual Installation

```bash
pip install -e .
```

## Configuration

### Environment Variables

- `DOMAIN_API_KEY`: Your GoDaddy OTE API credentials in format `"key:secret"` (required)

**Note**: The server uses GoDaddy OTE (sandbox) API by default: `https://api.ote-godaddy.com`

### GoDaddy OTE Setup

1. Sign up for GoDaddy Developer account
2. Get OTE (sandbox) API credentials
3. Set the environment variable: `DOMAIN_API_KEY="your-ote-key:your-ote-secret"`

### MCP Configuration

Add this to your MCP client configuration (e.g., Claude Desktop's `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "domain-availability": {
      "command": "uv",
      "args": ["run", "mcp-domain-availability"],
      "env": {
        "DOMAIN_API_KEY": "your-ote-key:your-ote-secret"
      }
    }
  }
}
```

## Usage

### Development & Testing

```bash
# Start MCP Inspector for testing
DOMAIN_API_KEY="your-key:your-secret" mcp dev domain_availability/server.py
```

This will start the MCP Inspector at `http://localhost:6274` for interactive testing.

### Tools Available

The server provides one tool: `check_domain_availability`

#### Parameters

**Option 1: Direct domain list**
- `domains`: Array of domain names to check (e.g., `["example.com", "example.org"]`)

**Option 2: Base name with TLD suffixes**
- `base_name`: Base domain name (e.g., `"example"`)
- `tld_suffixes`: Array of TLD suffixes (e.g., `[".com", ".org", ".net", ".io"]`)

**Optional**
- `checkType`: `"FAST"` or `"FULL"` (default: `"FAST"`)
  - `FAST`: Optimized for speed
  - `FULL`: Optimized for accuracy

### Examples

#### Check specific domains
```json
{
  "domains": ["example.com", "example.org", "example.net"],
  "checkType": "FAST"
}
```

#### Check base name with multiple TLDs
```json
{
  "base_name": "myawesomesite",
  "tld_suffixes": [".com", ".org", ".net", ".io", ".dev", ".app"],
  "checkType": "FULL"
}
```

### Response Format

**Text Response:**
```
Domain Availability Check Results:

✅ AVAILABLE DOMAINS:
  • example.com - $12.99 USD for 1 year (Definitive)
  • example.org - $8.99 USD for 2 years (Preliminary)

❌ UNAVAILABLE DOMAINS:
  • example.net - Not available - Domain already registered
```

**JSON Response (normalized fields):**
```json
{
  "domains": [
    {
      "domain_name": "example.com",
      "is_available": true,
      "price_dollars": 12.99,
      "currency_code": "USD",
      "is_definitive": true,
      "registration_period_months": 12
    },
    {
      "domain_name": "example.net",
      "is_available": false,
      "price_dollars": 0.00,
      "currency_code": "USD",
      "is_definitive": true,
      "registration_period_months": 12,
      "error_message": "Domain already registered"
    }
  ],
  "errors": []
}
```

## Data Normalization

### Price Normalization
- **Input**: GoDaddy API returns prices in micro-units (1/1,000,000 of currency)
- **Output**: Converted to dollars with 2 decimal places
- **Example**: `12000000` micro-units → `$12.00 USD`

### Period Normalization
- **Storage**: Period stored in months for consistency
- **Display**: Converted to years for user-friendly display
- **Example**: `12 months` → `"1 year"`, `24 months` → `"2 years"`

### Field Naming
Consistent, explicit field names:
- `domain_name` (instead of `domain`)
- `is_available` (instead of `available`) 
- `price_dollars` (instead of `price`)
- `currency_code` (instead of `currency`)
- `is_definitive` (instead of `definitive`)
- `registration_period_months` (instead of `period`)
- `error_message` (instead of `error`)

## API Integration

This server integrates with GoDaddy OTE API:

- **Base URL**: `https://api.ote-godaddy.com`
- **Endpoint**: `GET /v1/domains/available?domain={domain}`
- **Headers**: `Authorization: sso-key {key}:{secret}`
- **Rate Limit**: 60 requests per minute

### Authentication Format
```
Authorization: sso-key your-key:your-secret
```

## Error Handling

The server handles various error conditions:

- Missing API key
- Invalid domains
- API rate limits (429) - with retry guidance
- Partial responses (203)
- Authentication errors (401, 403)
- Server errors (500)
- Network timeouts

## Development

### Setup Development Environment

```bash
# Clone and setup
git clone <repository>
cd mcp-free-domain
uv add "mcp[cli]"

# Run tests
pytest

# Start development server
DOMAIN_API_KEY="test-key:test-secret" mcp dev domain_availability/server.py
```

### Testing with MCP Inspector

1. Set your OTE credentials: `DOMAIN_API_KEY="your-key:your-secret"`
2. Run: `mcp dev domain_availability/server.py`
3. Open browser at `http://localhost:6274`
4. Use the session token displayed in terminal if prompted
5. Test the `check_domain_availability` tool

## License

MIT License

## Support

For issues and questions, please create an issue in the repository.