domain-search-mcp

# Domain Search MCP

[![npm](https://img.shields.io/npm/v/domain-search-mcp?label=npm)](https://www.npmjs.com/package/domain-search-mcp)
[![downloads](https://img.shields.io/npm/dm/domain-search-mcp?label=downloads)](https://www.npmjs.com/package/domain-search-mcp)
[![license](https://img.shields.io/npm/l/domain-search-mcp)](LICENSE)
[![node](https://img.shields.io/node/v/domain-search-mcp?label=node)](https://www.npmjs.com/package/domain-search-mcp)
[![MCP Registry](https://img.shields.io/badge/MCP-Registry-2b6cb0)](https://registry.modelcontextprotocol.io)
[![Glama](https://img.shields.io/badge/Glama-Server-0ea5e9)](https://glama.ai/mcp/servers/@dorukardahan/domain-search-mcp)
[![Context7](https://img.shields.io/badge/Context7-Indexed-16a34a)](https://context7.com/dorukardahan/domain-search-mcp)

**Naming engine with availability intelligence** — an MCP server that scores the names your model generates and runs availability checks against domains, socials, and package registries. Works with zero configuration using public RDAP/WHOIS, and optionally enriches results with registrar pricing via a backend you control.

**🆕 v1.12.0**: `name_project` — a two-phase naming engine. Call it once to get generation instructions for your model, call it again with `candidates[]` to get anti-slop scoring, ranking, and live availability checks across domains, socials, and npm. See [name_project](#name_project) below.

**🆕 v1.10.0**: GoDaddy public endpoint integration! Enhanced fallback chain (RDAP → GoDaddy → WHOIS) with premium/auction domain detection. Circuit breaker pattern ensures resilience.

**🤖 v1.9.0+**: AI-powered domain suggestions work out of the box! No API keys needed - `suggest_domains_smart` uses our public fine-tuned Qwen 7B-DPO model. Plus: Redis distributed caching and `/metrics` endpoint for observability.

Built on the [Model Context Protocol](https://modelcontextprotocol.io) for Claude, Codex, VS Code, Cursor, Cline, and other MCP-compatible clients.

## Features

| Feature | Description |
|---------|-------------|
| 🔍 **Multi-TLD Search** | Check one name across .com, .io, .dev, .ai and 500+ TLDs |
| 📦 **Bulk Check** | Validate up to 100 domain names in a single call |
| 💎 **Premium Detection** | Identify premium and auction domains via GoDaddy |
| 🤖 **AI Suggestions** | Generate brandable names with fine-tuned Qwen 7B-DPO |
| 💰 **Price Comparison** | Compare pricing across Porkbun, Namecheap |
| 🌐 **Social Handle Check** | Verify username availability on GitHub, Twitter, etc. |
| 🔌 **Dual Transport** | Works via stdio (Claude) or HTTP/SSE (ChatGPT Actions) |
| ⚡ **Zero Config** | Works instantly - no API keys required for availability |

## What It Does

- Check a single name across multiple TLDs.
- Bulk-check up to 100 names for one TLD.
- Compare registrar pricing (uses backend when configured).
- Suggest names and validate social handles.
- Detect premium/auction signals for `search_domain`.

## How It Works

Availability and pricing are intentionally separated:

```
Availability Chain (zero-config):
┌─────────┐     ┌─────────┐     ┌─────────┐
│  RDAP   │ ──► │ GoDaddy │ ──► │  WHOIS  │
│ (fast)  │     │(premium)│     │(fallback│
└─────────┘     └─────────┘     └─────────┘
```

- **Availability** (default, no keys needed):
  - **RDAP**: Primary source - fast, unlimited, public registry data
  - **GoDaddy**: Secondary - adds premium/auction detection (30 req/min, circuit breaker protected)
  - **WHOIS**: Last resort fallback for edge cases
- **Pricing** (optional):
  - Recommended: `PRICING_API_BASE_URL` (backend with Porkbun keys)
  - Optional BYOK: Porkbun/Namecheap only when backend is not configured

This keeps the server zero-config while letting power users enable pricing.

## Pricing Verification

Responses include `price_check_url` (registrar checkout/search link) and may include
`price_note` when a price is estimated. Always verify the final price on the registrar
checkout page before purchase.

If an auction/premium signal is detected, results include an `aftermarket` block with
links to marketplace pages when available. Taken domains may include Sedo auction
hints (public feed) and nameserver-based marketplace hints (Sedo/Dan/Afternic).

## Quick Start

### Option 1: npx (Recommended)

No installation needed - run directly:

```bash
npx -y domain-search-mcp@latest
```

### Option 2: From Source

```bash
git clone https://github.com/dorukardahan/domain-search-mcp.git
cd domain-search-mcp
npm install
npm run build
npm start
```

## Transport Options

### stdio (Default)

For MCP clients like Claude Desktop, Cursor, VS Code - uses stdin/stdout:

```bash
npx -y domain-search-mcp@latest
```

### HTTP/SSE (ChatGPT, Web Clients, LM Studio)

For ChatGPT Actions, web apps, and REST API clients:

```bash
# Start HTTP server on port 3000
npx -y domain-search-mcp@latest --http

# Or with custom port
MCP_PORT=8080 npx -y domain-search-mcp@latest --http
```

**Endpoints:**
- `/mcp` - MCP protocol (POST for messages, GET for SSE stream)
- `/api/tools/*` - REST API for each tool (ChatGPT Actions compatible)
- `/openapi.json` - OpenAPI 3.1 specification
- `/health` - Health check
- `/metrics` - Prometheus-compatible metrics (cache stats, request counts, AI inference health)

### ChatGPT Custom GPT Integration

1. Start the HTTP server (see above)
2. Expose via ngrok: `ngrok http 3000`
3. In ChatGPT, create a Custom GPT and add an Action
4. Import the OpenAPI spec from `https://your-ngrok-url.ngrok-free.dev/openapi.json`
5. Test the tools!

For production deployment, use a permanent domain with SSL instead of ngrok.

**REST API Example:**
```bash
curl -X POST https://your-domain/api/tools/search_domain \
  -H "Content-Type: application/json" \
  -d '{"domain_name":"vibecoding"}'
```

## MCP Client Config

**Claude Code** (`.mcp.json` in project root):
```json
{
  "mcpServers": {
    "domain-search": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "domain-search-mcp@latest"]
    }
  }
}
```

**Claude Desktop** (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "domain-search": {
      "command": "npx",
      "args": ["-y", "domain-search-mcp@latest"]
    }
  }
}
```

> **💡 Tip**: Always use `@latest` to ensure you're running the newest version with all features.

## Tools

All 12 tools listed below are exposed to MCP clients by default. The 6-tool
slim profile (`name_project`, `search_domain`, `bulk_search`, `check_socials`,
`tld_info`, `ai_health`) is opt-in — set `SLIM_TOOLS=true` if you want a
sharper tool-selection surface for simpler client integrations (see
[Environment Variables](#environment-variables)). A future 2.0 release may
flip the default to slim.

`ADVANCED_TOOLS=true` is a deprecated alias that forces the full surface and
overrides `SLIM_TOOLS`; it's a harmless no-op today since full is already the
default.

### name_project

**Flagship two-phase naming engine.** Call it once to get lane-by-lane generation
instructions for *your* model; call it again with `candidates[]` to get anti-slop
scoring, ranking, and live availability checks across domains, socials, and npm.

- **Modes**: `brief` (describe what you're naming), `auto` (analyze the current
  workspace), `from_name` (find domains/variants for a name you already like),
  `from_domain` (fit a project/brand to a domain you found).
- **Phase 1** (no `candidates`): returns generation instructions + lane prompts.
- **Phase 2** (`candidates` present): scores + ranks candidates, then checks
  availability for the top 12 against `targets.tlds` / `targets.platforms` —
  omit `targets` for pure naming with no availability calls.

> Scores are heuristic rankings for comparing candidates against each other —
> not objective, universal brandability truth. Availability results reflect a
> single source checked at one moment in time; re-verify before you register
> or rely on anything.

**Phase 1** — call with no `candidates`:
```json
{"mode": "brief", "brief": "an MCP naming engine"}
```
```
Brief: an MCP naming engine

Now generate between 30 and 50 name candidates spread across these lanes:
- [evocative] Real words borrowed for their feeling, not their meaning (like Slack, Notion, Bolt). Single dictionary words preferred.
- [invented] Coined words that do not exist but sound like they could (like Zapier, Klarna). Must be pronounceable on first read.
- [compound] Two short real words fused (like Facebook, Snapchat). Both halves must stay readable; no glue letters.
- [premium] Short, expensive-feeling names: 4-7 letters, strong single or double syllable (like Stripe, Vercel, Arc).

Rules: single words or tight compounds, no taglines, no explanations yet. Then call name_project again with the SAME arguments plus candidates:[...] to get scoring and availability.
```

**Phase 2** — resubmit the same arguments plus `candidates`:
```json
{"mode": "brief", "brief": "an MCP naming engine", "candidates": ["Nexify", "Corda"]}
```
```
| Name | Score | Verdict | Badges | Why |
| --- | --- | --- | --- | --- |
| Corda | 97 strong | - | - | no AI-slop patterns; clean pronunciation and typing |
| Nexify | 60 middling | - | - | slop: overused prefix "nex-"; slop: overused suffix "-ify" |
2 candidates received, 2 passed constraints, top 2 returned.
No availability-check targets - pure naming mode.
```

Badges: `tld✓` free to register, `tld$` for sale (aftermarket/premium - registered or priced, not free to register), `tld✗` taken, `tld?` unknown.
ccTLD checks (`.ai` / `.io` / `.sh` / `.ac`) are cross-checked against native WHOIS/DNS ground truth, not taken on RDAP's word alone.

See [docs/API.md](docs/API.md#name_project) for the full parameter/response schema.

### Core Search
- `search_domain`: Check a name across multiple TLDs, adds premium/auction signals.
- `bulk_search`: Check up to 100 names for a single TLD.
- `compare_registrars`: Compare pricing across registrars (backend when configured).

### AI-Powered Sug