# Domain Checker MCP Server

A Model Context Protocol (MCP) server that checks domain name availability using the WhoisJSON API.

## Features

- Check if domain names are available for registration
- Get detailed registration information for registered domains
- Easy-to-use HTTP API for testing
- Built with TypeScript for type safety and readability

## API Limits

- **Rate Limit**: 20 requests per minute
- **Monthly Limit**: 1000 requests per month

## Setup

### Initial Setup

1. Install dependencies:
```bash
npm install
```

2. Create a `.env` file with your WhoisJSON API key:
```bash
WHOISJSON_API_KEY=your-api-key-here
PORT=6005
```

3. Build the project:
```bash
npm run build
```

## Usage

### Option 1: Testing with HTTP Server

The HTTP mode is for **testing only** - it runs a REST API on port 6005 so you can verify everything works.

Start the HTTP server:
```bash
npm run start:http
```

Test it:
```bash
# Health check
curl http://localhost:6005/health

# Check a domain
curl http://localhost:6005/check/example.com
```

**Stop the server when done testing** (Ctrl+C).

### Option 2: Using with Claude Desktop (MCP Mode)

This is the main use case - Claude Desktop will automatically start and manage the server.

**Important**: MCP mode uses **stdio** (not HTTP/ports), so there are no port conflicts. Claude starts the server automatically when it launches.

#### Steps to Configure:

1. **Build the project** (if not already done):
```bash
npm run build
```

2. **Add to Claude Desktop config**:
   - **Mac**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "domain-checker": {
      "command": "node",
      "args": [
        "/FULL/PATH/TO/domain-checker-mcp/dist/index.js"
      ],
      "env": {
        "WHOISJSON_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

3. **Replace the paths**:
   - Change `/FULL/PATH/TO/domain-checker-mcp` to your actual project path
   - Change `your-api-key-here` to your WhoisJSON API key

4. **Restart Claude Desktop**

5. **Test it**: Ask Claude "Is example.com available?"

#### Moving to a Different Machine

To use this MCP server on another machine:

1. **Copy the project** to the new machine
2. **Install dependencies**: `npm install`
3. **Build**: `npm run build`
4. **Update Claude Desktop config** on the new machine with the correct path and API key
5. **Restart Claude Desktop**

### How It Works: HTTP vs MCP Mode

- **HTTP Mode** (`npm run start:http`): Uses port 6005, for testing with curl/browser
- **MCP Mode** (`npm start` or run by Claude): Uses stdio (no ports), for AI integration

These are completely separate - MCP mode does NOT use HTTP or ports, so they never conflict. Claude Desktop automatically starts the server in MCP mode when it launches.

## MCP Tool: check_domain

**Input:**
- `domain` (string, required): The domain name to check (e.g., "example.com", "mysite.org")

**Output:**

If domain is **available**:
```json
{
  "available": true,
  "registered": false,
  "domain": "myawesomesite123.com"
}
```

If domain is **registered**:
```json
{
  "available": false,
  "registered": true,
  "domain": "EXAMPLE.COM",
  "created": "1995-08-14 04:00:00",
  "expires": "2026-08-13 04:00:00",
  "registrar": "RESERVED-Internet Assigned Numbers Authority",
  "nameservers": ["elliott.ns.cloudflare.com", "hera.ns.cloudflare.com"],
  "daysUntilExpiry": 125
}
```

## Code Structure

- `src/index.ts` - Main server code with clear, documented functions
- `.env` - Environment configuration (API key, port)
- `tsconfig.json` - TypeScript configuration

## Development

Watch mode (auto-restart on changes):
```bash
npm run dev
```

Build:
```bash
npm run build
```

## How It Works

1. **checkDomainAvailability()** - Queries the WhoisJSON API with the domain name
2. **createMCPServer()** - Sets up the MCP server with the `check_domain` tool
3. **createExpressServer()** - Creates an HTTP server for easy testing
4. **main()** - Entry point that starts either HTTP or MCP mode based on arguments

The code is written to be easy to read and understand, with clear function names, comments, and TypeScript types.