Domain Search MCP

1# Domain Search MCP
2 
3[![npm](https://img.shields.io/npm/v/domain-search-mcp?label=npm)](https://www.npmjs.com/package/domain-search-mcp)
4[![downloads](https://img.shields.io/npm/dm/domain-search-mcp?label=downloads)](https://www.npmjs.com/package/domain-search-mcp)
5[![license](https://img.shields.io/npm/l/domain-search-mcp)](LICENSE)
6[![node](https://img.shields.io/node/v/domain-search-mcp?label=node)](https://www.npmjs.com/package/domain-search-mcp)
7[![MCP Registry](https://img.shields.io/badge/MCP-Registry-2b6cb0)](https://registry.modelcontextprotocol.io)
8[![Glama](https://img.shields.io/badge/Glama-Server-0ea5e9)](https://glama.ai/mcp/servers/@dorukardahan/domain-search-mcp)
9[![Context7](https://img.shields.io/badge/Context7-Indexed-16a34a)](https://context7.com/dorukardahan/domain-search-mcp)
10 
11Fast, local-first domain availability checks for MCP clients. Works with zero configuration using public RDAP/WHOIS, and optionally enriches results with registrar pricing via a backend you control.
12 
13**🆕 v1.10.0**: GoDaddy public endpoint integration! Enhanced fallback chain (RDAP → GoDaddy → WHOIS) with premium/auction domain detection. Circuit breaker pattern ensures resilience.
14 
15**🤖 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.
16 
17Built on the [Model Context Protocol](https://modelcontextprotocol.io) for Claude, Codex, VS Code, Cursor, Cline, and other MCP-compatible clients.
18 
19## Features
20 
21| Feature | Description |
22|---------|-------------|
23| 🔍 **Multi-TLD Search** | Check one name across .com, .io, .dev, .ai and 500+ TLDs |
24| 📦 **Bulk Check** | Validate up to 100 domain names in a single call |
25| 💎 **Premium Detection** | Identify premium and auction domains via GoDaddy |
26| 🤖 **AI Suggestions** | Generate brandable names with fine-tuned Qwen 7B-DPO |
27| 💰 **Price Comparison** | Compare pricing across Porkbun, Namecheap |
28| 🌐 **Social Handle Check** | Verify username availability on GitHub, Twitter, etc. |
29| 🔌 **Dual Transport** | Works via stdio (Claude) or HTTP/SSE (ChatGPT Actions) |
30| ⚡ **Zero Config** | Works instantly - no API keys required for availability |
31 
32## What It Does
33 
34- Check a single name across multiple TLDs.
35- Bulk-check up to 100 names for one TLD.
36- Compare registrar pricing (uses backend when configured).
37- Suggest names and validate social handles.
38- Detect premium/auction signals for `search_domain`.
39 
40## How It Works
41 
42Availability and pricing are intentionally separated:
43 
44```
45Availability Chain (zero-config):
46┌─────────┐     ┌─────────┐     ┌─────────┐
47│  RDAP   │ ──► │ GoDaddy │ ──► │  WHOIS  │
48│ (fast)  │     │(premium)│     │(fallback│
49└─────────┘     └─────────┘     └─────────┘
50```
51 
52- **Availability** (default, no keys needed):
53  - **RDAP**: Primary source - fast, unlimited, public registry data
54  - **GoDaddy**: Secondary - adds premium/auction detection (30 req/min, circuit breaker protected)
55  - **WHOIS**: Last resort fallback for edge cases
56- **Pricing** (optional):
57  - Recommended: `PRICING_API_BASE_URL` (backend with Porkbun keys)
58  - Optional BYOK: Porkbun/Namecheap only when backend is not configured
59 
60This keeps the server zero-config while letting power users enable pricing.
61 
62## Pricing Verification
63 
64Responses include `price_check_url` (registrar checkout/search link) and may include
65`price_note` when a price is estimated. Always verify the final price on the registrar
66checkout page before purchase.
67 
68If an auction/premium signal is detected, results include an `aftermarket` block with
69links to marketplace pages when available. Taken domains may include Sedo auction
70hints (public feed) and nameserver-based marketplace hints (Sedo/Dan/Afternic).
71 
72## Quick Start
73 
74### Option 1: npx (Recommended)
75 
76No installation needed - run directly:
77 
78```bash
79npx -y domain-search-mcp@latest
80```
81 
82### Option 2: From Source
83 
84```bash
85git clone https://github.com/dorukardahan/domain-search-mcp.git
86cd domain-search-mcp
87npm install
88npm run build
89npm start
90```
91 
92## Transport Options
93 
94### stdio (Default)
95 
96For MCP clients like Claude Desktop, Cursor, VS Code - uses stdin/stdout:
97 
98```bash
99npx -y domain-search-mcp@latest
100```
101 
102### HTTP/SSE (ChatGPT, Web Clients, LM Studio)
103 
104For ChatGPT Actions, web apps, and REST API clients:
105 
106```bash
107# Start HTTP server on port 3000
108npx -y domain-search-mcp@latest --http
109 
110# Or with custom port
111MCP_PORT=8080 npx -y domain-search-mcp@latest --http
112```
113 
114**Endpoints:**
115- `/mcp` - MCP protocol (POST for messages, GET for SSE stream)
116- `/api/tools/*` - REST API for each tool (ChatGPT Actions compatible)
117- `/openapi.json` - OpenAPI 3.1 specification
118- `/health` - Health check
119- `/metrics` - Prometheus-compatible metrics (cache stats, request counts, AI inference health)
120 
121### ChatGPT Custom GPT Integration
122 
1231. Start the HTTP server (see above)
1242. Expose via ngrok: `ngrok http 3000`
1253. In ChatGPT, create a Custom GPT and add an Action
1264. Import the OpenAPI spec from `https://your-ngrok-url.ngrok-free.dev/openapi.json`
1275. Test the tools!
128 
129For production deployment, use a permanent domain with SSL instead of ngrok.
130 
131**REST API Example:**
132```bash
133curl -X POST https://your-domain/api/tools/search_domain \
134  -H "Content-Type: application/json" \
135  -d '{"domain_name":"vibecoding"}'
136```
137 
138## MCP Client Config
139 
140**Claude Code** (`.mcp.json` in project root):
141```json
142{
143  "mcpServers": {
144    "domain-search": {
145      "type": "stdio",
146      "command": "npx",
147      "args": ["-y", "domain-search-mcp@latest"]
148    }
149  }
150}
151```
152 
153**Claude Desktop** (`claude_desktop_config.json`):
154```json
155{
156  "mcpServers": {
157    "domain-search": {
158      "command": "npx",
159      "args": ["-y", "domain-search-mcp@latest"]
160    }
161  }
162}
163```
164 
165> **💡 Tip**: Always use `@latest` to ensure you're running the newest version with all features.
166 
167## Tools
168 
169### Core Search
170- `search_domain`: Check a name across multiple TLDs, adds premium/auction signals.
171- `bulk_search`: Check up to 100 names for a single TLD.
172- `compare_registrars`: Compare pricing across registrars (backend when configured).
173 
174### AI-Powered Suggestions
175- `suggest_domains`: Generate variations (prefix/suffix/hyphen).
176- `suggest_domains_smart`: **🤖 AI-powered** brandable name generation using fine-tuned Qwen 7B-DPO. Zero-config - works instantly!
177- `analyze_project`: Scan local project or GitHub repo to extract context and suggest matching domain names.
178 
179### Domain Investment
180- `hunt_domains`: Find valuable domains for investment - scans Sedo auctions, generates patterns, calculates investment scores.
181- `expiring_domains`: Monitor domains approaching expiration (requires federated negative cache).
182 
183### Utilities
184- `tld_info`: TLD metadata and restrictions.
185- `check_socials`: Username availability across platforms.
186- `ai_health`: Check status of AI inference services (VPS Qwen, circuit breakers, adaptive concurrency).
187 
188## Configuration
189 
190### Pricing Backend (Recommended)
191 
192Set a backend URL that owns registrar keys (Porkbun). The MCP will call
193`/api/quote` and `/api/compare` on that backend for pricing.
194 
195```bash
196PRICING_API_BASE_URL=https://your-backend.example.com
197PRICING_API_TOKEN=optional_bearer_token
198```
199 
200### Optional BYOK (Local)
201 
202Used only if `PRICING_API_BASE_URL` is not set.
203 
204- Porkbun keys:
205  - https://porkbun.com/account/api
206  - https://porkbun.com/api/json/v3/documentation
207- Namecheap keys (IP whitelist required):
208  - https://ap.www.namecheap.com/settings/tools/apiaccess/
209  - https://www.namecheap.com/support/api/intro/
210 
211```bash
212PORKBUN_API_KEY=pk1_your_api_key
213PORKBUN_API_SECRET=sk1_your_secret
214NAMECHEAP_API_KEY=your_api_key
215NAMECHEAP_API_USER=your_username
216NAMECHEAP_CLIENT_IP=your_whitelisted_ip
217```
218 
219### Redis Distributed Cache (Optional)
220 
221For horizontal scaling across multiple MCP instances, configure Redis:
222 
223```bash
224REDIS_URL=redis://:password@host:6379
225```
226 
227Without Redis, the server uses in-memory caching (works fine for single instances). Redis enables:
228- Shared cache across multiple server instances
229- Persistent cache surviving restarts
230- Better cache hit rates in load-balanced deployments
231 
232### AI Inference (Zero-Config)
233 
234AI-powered suggestions (`suggest_domains_smart`) work out of the box using our public VPS running fine-tuned Qwen 7B-DPO. No API keys needed!
235 
236For self-hosted setups, override the endpoint:
237```bash
238QWEN_INFERENCE_ENDPOINT=http://your-server:8000
239QWEN_API_KEY=optional_if_secured
240```
241 
242### Environment Variables
243 
244| Variable | Default | Description |
245|----------|---------|-------------|
246| `MCP_TRANSPORT` | stdio | Transport mode: `stdio` or `http` |
247| `MCP_PORT` | 3000 | HTTP server port (when using HTTP transport) |
248| `MCP_HOST` | 0.0.0.0 | HTTP server bind address |
249| `CORS_ORIGINS` | * | Allowed CORS origins (comma-separated) |
250| `PRICING_API_BASE_URL` | - | Pricing backend base URL |
251| `PRICING_API_TOKEN` | - | Optional bearer token |
252| `PRICING_API_TIMEOUT_MS` | 2500 | Backend request timeout |
253| `PRICING_API_MAX_QUOTES_SEARCH` | 0 | Max pricing calls per search (0 = unlimited; backend rate limits apply) |
254| `PRICING_API_MAX_QUOTES_BULK` | 0 | Max pricing calls per bulk search (0 = unlimited; backend rate limits apply) |
255| `PRICING_API_CONCURRENCY` | 4 | Pricing request concurrency |
256| `PORKBUN_API_KEY` | - | Porkbun API key |
257| `PORKBUN_API_SECRET` | - | Porkbun API secret |
258| `NAMECHEAP_API_KEY` | - | Namecheap API key |
259| `NAMECHEAP_API_USER` | - | Namecheap username |
260| `NAMECHEAP_CLIENT_IP` | - | Namecheap IP whitelist |
261| `OUTPUT_FORMAT` | table | `table`, `json`, or `both` for tool output formatting |
262| `LOG_LEVEL` | info | Logging level |
263| `CACHE_TTL_AVAILABILITY` | 60 | Availability cache TTL (seconds) |
264| `CACHE_TTL_PRICING` | 3600 | Pricing cache TTL (seconds) |
265| `CACHE_TTL_SEDO` | 3600 | Sedo auctions feed cache TTL (seconds) |
266| `CACHE_TTL_AFTERMARKET_NS` | 300 | Nameserver lookup cache TTL (seconds) |
267| `SEDO_FEED_ENABLED` | true | Enable Sedo feed lookup for aftermarket hints |
268| `SEDO_FEED_URL` | https://sedo.com/txt/auctions_us.txt | Sedo public feed URL |
269| `AFTERMARKET_NS_ENABLED` | true | Enable nameserver-based aftermarket hints |
270| `AFTERMARKET_NS_TIMEOUT_MS` | 1500 | Nameserver lookup timeout (ms) |
271| `REDIS_URL` | - | Redis connection URL for distributed caching (e.g., `redis://:password@host:6379`) |
272| `QWEN_INFERENCE_ENDPOINT` | (public VPS) | Override AI inference endpoint for self-hosted setups |
273| `QWEN_TIMEOUT_MS` | 15000 | AI inference request timeout |
274| `QWEN_MAX_RETRIES` | 2 | Retry count for AI inference failures |
275 
276### Output Format
277 
278Tool responses are returned as **Markdown tables by default**. If you need raw
279JSON for programmatic use, set:
280 
281```bash
282OUTPUT_FORMAT=json
283```
284 
285## Data Sources
286 
287| Source | Position in Chain | Usage | API Keys |
288|--------|-------------------|-------|----------|
289| **RDAP** | 1st (Primary) | Fast availability check | Not needed |
290| **GoDaddy** | 2nd (Fallback) | Premium/auction detection | Not needed |
291| **WHOIS** | 3rd (Last resort) | Legacy availability | Not needed |
292| Pricing API | Parallel | Live pricing via backend | Backend token |
293| Porkbun API | Parallel (BYOK) | Availability + pricing | API key + secret |
294| Namecheap API | Parallel (BYOK) | Availability + pricing | API key + IP whitelist |
295| Sedo Feed | Enrichment | Aftermarket auction hints | Not needed |
296 
297## Pricing Behavior
298 
299- Live price is attempted first for every **available** domain.
300- If live quotes fail or are rate-limited, the result falls back to the catalog estimate and includes `price_note`.
301- Always verify pricing via `price_check_url` before purchase.
302 
303## Examples
304 
305### Basic Search (No API Keys)
306 
307```
308search_domain("myproject", ["com", "io", "dev"])
309 
310┌─────────────────┬───────────┬─────────┬────────┐
311│ Domain          │ Available │ Premium │ Source │
312├─────────────────┼───────────┼─────────┼────────┤
313│ myproject.com   │ ✅        │ No      │ rdap   │
314│ myproject.io    │ ❌        │ -       │ rdap   │
315│ myproject.dev   │ ✅        │ Yes     │ godaddy│
316└─────────────────┴───────────┴─────────┴────────┘
317```
318 
319### AI-Powered Suggestions
320 
321```
322suggest_domains_smart("coffee shop in seattle", { style: "brandable" })
323 
324→ seattlebrew.com, pugetperk.io, raincitycoffee.co, cascadiacafe.com
325```
326 
327### Bulk Check
328 
329```
330bulk_search(["startup", "launch", "begin", "init"], "io")
331 
332→ Checks startup.io, launch.io, begin.io, init.io in parallel
333```
334 
335## Development
336 
337```bash
338npm run dev       # watch mode
339npm test          # run Jest
340npm run build     # compile to dist/
341```
342 
343## Release
344 
345See `docs/RELEASE.md` for the canary -> latest publish flow. Tags like `v1.2.24`
346trigger GitHub Releases + npm publish via CI.
347 
348## Changelog
349 
350See `CHANGELOG.md` for release history.
351 
352## Security Notes
353 
354- Do not commit API keys or `.mcpregistry_*` files.
355- Without `PRICING_API_BASE_URL` (or BYOK keys), pricing is not available (availability still works).
356 
357## Upgrading
358 
359### For npx Users
360 
361If you use `npx domain-search-mcp` (without `@latest`), npx may cache an old version.
362 
363**Fix**: Update your MCP config to use `@latest`:
364```json
365"args": ["-y", "domain-search-mcp@latest"]
366```
367 
368Or clear the npx cache manually:
369```bash
370npx clear-npx-cache  # then restart your MCP client
371```
372 
373### For Source/Git Users
374 
375```bash
376cd domain-search-mcp
377git pull origin main
378npm install
379npm run build
380```
381 
382### Staying Updated
383 
384- **Watch the repo**: Click "Watch" → "Releases only" on [GitHub](https://github.com/dorukardahan/domain-search-mcp) to get notified of new versions.
385- **Check releases**: See [GitHub Releases](https://github.com/dorukardahan/domain-search-mcp/releases) for changelog and upgrade notes.
386- **npm page**: [npmjs.com/package/domain-search-mcp](https://www.npmjs.com/package/domain-search-mcp) shows the latest version.
387 
388## Architecture
389 
390For detailed system architecture diagrams, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md):
391 
392- Transport layer (stdio vs HTTP/SSE)
393- Tool execution flow
394- Data source waterfall (RDAP → Pricing API → WHOIS)
395- VPS deployment architecture
396- AI suggestion flow
397- MCP session lifecycle
398 
399## Why This Tool?
400 
401| Problem | Solution |
402|---------|----------|
403| Domain APIs require signup/keys | RDAP + GoDaddy = zero-config availability |
404| Premium domains show as "available" | GoDaddy detects premium/auction status |
405| Hard to check multiple TLDs | Single call checks .com, .io, .dev, etc. |
406| No AI integration for naming | Built-in Qwen 7B for brandable suggestions |
407| Only works with Claude | HTTP transport supports ChatGPT, LM Studio |
408 
409## FAQ
410 
411**Q: Does this work without any API keys?**
412A: Yes! Availability checking uses public RDAP and GoDaddy endpoints. Only pricing requires API keys.
413 
414**Q: Which MCP clients are supported?**
415A: Claude Desktop, Claude Code, VS Code, Cursor, Cline (stdio), and ChatGPT, LM Studio (HTTP/SSE).
416 
417**Q: How accurate is premium domain detection?**
418A: GoDaddy's public endpoint detects most premium and auction domains. Always verify on registrar checkout.
419 
420**Q: Can I self-host the AI suggestions?**
421A: Yes! Set `QWEN_INFERENCE_ENDPOINT` to your llama.cpp server running the fine-tuned model.
422 
423## Links
424 
425- **npm**: [npmjs.com/package/domain-search-mcp](https://www.npmjs.com/package/domain-search-mcp)
426- **MCP Registry**: [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io)
427- **Glama**: [glama.ai/mcp/servers/@dorukardahan/domain-search-mcp](https://glama.ai/mcp/servers/@dorukardahan/domain-search-mcp)
428- **Context7**: [context7.com/dorukardahan/domain-search-mcp](https://context7.com/dorukardahan/domain-search-mcp)
429 
430### Documentation
431 
432- [Architecture](docs/ARCHITECTURE.md) - System design and data flow
433- [API Reference](docs/API.md) - Tool schemas and responses
434- [Configuration](docs/CONFIGURATION.md) - Environment variables
435- [Workflows](docs/WORKFLOWS.md) - Common usage patterns
436