# MCP Domain Availability Server

A Model Context Protocol (MCP) server for checking domain name availability using DNS, RDAP, and WHOIS lookups. This server provides AI assistants with the ability to check if domain names are available for registration.

## Features

- **Single Domain Checking**: Check availability of individual domains
- **Bulk Domain Checking**: Check up to 50 domains simultaneously
- **Multi-Protocol Lookups**: Uses DNS-over-HTTPS (DoH), RDAP, and WHOIS for accurate results
- **Robust Error Handling**: Handles timeouts, rate limits, and network errors gracefully
- **Security Limits**: Built-in protection against abuse with request limits and timeouts

## Installation

### For Cursor IDE

Add the following to your `~/.cursor/mcp.json` (or `%APPDATA%\Cursor\mcp.json` on Windows):

```json
{
  "mcpServers": {
    "domain-availability": {
      "command": "npx",
      "args": ["-y", "mcp-domain-availability"]
    }
  }
}
```

Restart Cursor to activate the server.

### For Other MCP Clients

The server can be used with any MCP-compatible client. Install globally:

```bash
npm install -g mcp-domain-availability
```

Then configure your MCP client to run:
```bash
mcp-domain-availability
```

## Usage

### Tool 1: `check_domain_availability`

Check if a single domain is available for registration.

**Input:**
```json
{
  "domain": "example.com"
}
```

**Output:**
```json
{
  "domain": "example.com",
  "available": false,
  "status": "registered",
  "registered": true,
  "details": {
    "availability": "registered",
    "registrar": "Example Registrar",
    "registrationDate": "2020-01-01",
    "expirationDate": "2025-01-01"
  }
}
```

**Possible status values:**
- `unregistered` - Domain is available for registration
- `registered` - Domain is already registered
- `unknown` - Unable to determine status

### Tool 2: `check_multiple_domains`

Check availability for multiple domains at once (up to 50 domains).

**Input:**
```json
{
  "domains": ["example.com", "test.io", "available-domain.xyz"]
}
```

**Output:**
```json
{
  "results": [
    {
      "domain": "example.com",
      "available": false,
      "status": "registered",
      "registered": true,
      "error": null
    },
    {
      "domain": "test.io",
      "available": true,
      "status": "unregistered",
      "registered": false,
      "error": null
    },
    {
      "domain": "available-domain.xyz",
      "available": false,
      "status": "error",
      "registered": false,
      "error": "Network error occurred",
      "errorType": "network"
    }
  ],
  "summary": {
    "total": 3,
    "available": 1,
    "registered": 1,
    "errors": 1,
    "unknown": 0
  }
}
```

## Error Handling

The server handles various error scenarios:

- **Timeout Errors**: Domain checks timeout after 30 seconds
- **Rate Limiting**: Detects and reports rate limit errors from WHOIS/DNS providers
- **Network Errors**: Handles connection failures gracefully
- **Invalid Input**: Validates domain format and length before checking

### Error Response Format

```json
{
  "error": "Error message",
  "domain": "example.com",
  "suggestion": "Helpful suggestion for the user"
}
```

## Requirements

- Node.js >= 18.0.0
- npm or compatible package manager

## Limitations

- **Rate Limiting**: WHOIS and DNS providers may rate limit requests. The server detects and reports these errors.
- **Timeout**: Each domain check has a 30-second timeout to prevent hanging requests.
- **Bulk Limit**: Maximum 50 domains per bulk request to prevent abuse.
- **TLD Support**: Supports all standard TLDs. Some newer or less common TLDs may have limited information available.

## Troubleshooting

### Server not starting

- Verify Node.js version: `node --version` (should be >= 18.0.0)
- Check that the package is installed: `npx -y mcp-domain-availability`
- Review Cursor logs for error messages

### Domain checks failing

- Check your internet connection
- Some domains may be rate-limited - wait a few moments and try again
- Verify domain format is correct (e.g., `example.com`, not `http://example.com`)

### Rate limit errors

If you encounter rate limit errors:
- Wait a few minutes before making more requests
- Reduce the number of domains checked in bulk operations
- Consider checking domains individually with delays between requests

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

## Acknowledgments

- Built with [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk)
- Domain checking powered by [domainstat](https://www.npmjs.com/package/domainstat)