{
  "markdown": "# Domain Search MCP\n\n[![npm](https://img.shields.io/npm/v/domain-search-mcp?label=npm)](https://www.npmjs.com/package/domain-search-mcp)\n[![downloads](https://img.shields.io/npm/dm/domain-search-mcp?label=downloads)](https://www.npmjs.com/package/domain-search-mcp)\n[![license](https://img.shields.io/npm/l/domain-search-mcp)](LICENSE)\n[![node](https://img.shields.io/node/v/domain-search-mcp?label=node)](https://www.npmjs.com/package/domain-search-mcp)\n[![MCP Registry](https://img.shields.io/badge/MCP-Registry-2b6cb0)](https://registry.modelcontextprotocol.io)\n[![Glama](https://img.shields.io/badge/Glama-Server-0ea5e9)](https://glama.ai/mcp/servers/@dorukardahan/domain-search-mcp)\n[![Context7](https://img.shields.io/badge/Context7-Indexed-16a34a)](https://context7.com/dorukardahan/domain-search-mcp)\n\n**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.\n\n**🆕 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.\n\n**🆕 v1.10.0**: GoDaddy public endpoint integration! Enhanced fallback chain (RDAP → GoDaddy → WHOIS) with premium/auction domain detection. Circuit breaker pattern ensures resilience.\n\n**🤖 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.\n\nBuilt on the [Model Context Protocol](https://modelcontextprotocol.io) for Claude, Codex, VS Code, Cursor, Cline, and other MCP-compatible clients.\n\n## Features\n\n| Feature | Description |\n|---------|-------------|\n| 🔍 **Multi-TLD Search** | Check one name across .com, .io, .dev, .ai and 500+ TLDs |\n| 📦 **Bulk Check** | Validate up to 100 domain names in a single call |\n| 💎 **Premium Detection** | Identify premium and auction domains via GoDaddy |\n| 🤖 **AI Suggestions** | Generate brandable names with fine-tuned Qwen 7B-DPO |\n| 💰 **Price Comparison** | Compare pricing across Porkbun, Namecheap |\n| 🌐 **Social Handle Check** | Verify username availability on GitHub, Twitter, etc. |\n| 🔌 **Dual Transport** | Works via stdio (Claude) or HTTP/SSE (ChatGPT Actions) |\n| ⚡ **Zero Config** | Works instantly - no API keys required for availability |\n\n## What It Does\n\n- Check a single name across multiple TLDs.\n- Bulk-check up to 100 names for one TLD.\n- Compare registrar pricing (uses backend when configured).\n- Suggest names and validate social handles.\n- Detect premium/auction signals for `search_domain`.\n\n## How It Works\n\nAvailability and pricing are intentionally separated:\n\n```\nAvailability Chain (zero-config):\n┌─────────┐     ┌─────────┐     ┌─────────┐\n│  RDAP   │ ──► │ GoDaddy │ ──► │  WHOIS  │\n│ (fast)  │     │(premium)│     │(fallback│\n└─────────┘     └─────────┘     └─────────┘\n```\n\n- **Availability** (default, no keys needed):\n  - **RDAP**: Primary source - fast, unlimited, public registry data\n  - **GoDaddy**: Secondary - adds premium/auction detection (30 req/min, circuit breaker protected)\n  - **WHOIS**: Last resort fallback for edge cases\n- **Pricing** (optional):\n  - Recommended: `PRICING_API_BASE_URL` (backend with Porkbun keys)\n  - Optional BYOK: Porkbun/Namecheap only when backend is not configured\n\nThis keeps the server zero-config while letting power users enable pricing.\n\n## Pricing Verification\n\nResponses include `price_check_url` (registrar checkout/search link) and may include\n`price_note` when a price is estimated. Always verify the final price on the registrar\ncheckout page before purchase.\n\nIf an auction/premium signal is detected, results include an `aftermarket` block with\nlinks to marketplace pages when available. Taken domains may include Sedo auction\nhints (public feed) and nameserver-based marketplace hints (Sedo/Dan/Afternic).\n\n## Quick Start\n\n### Option 1: npx (Recommended)\n\nNo installation needed - run directly:\n\n```bash\nnpx -y domain-search-mcp@latest\n```\n\n### Option 2: From Source\n\n```bash\ngit clone https://github.com/dorukardahan/domain-search-mcp.git\ncd domain-search-mcp\nnpm install\nnpm run build\nnpm start\n```\n\n## Transport Options\n\n### stdio (Default)\n\nFor MCP clients like Claude Desktop, Cursor, VS Code - uses stdin/stdout:\n\n```bash\nnpx -y domain-search-mcp@latest\n```\n\n### HTTP/SSE (ChatGPT, Web Clients, LM Studio)\n\nFor ChatGPT Actions, web apps, and REST API clients:\n\n```bash\n# Start HTTP server on port 3000\nnpx -y domain-search-mcp@latest --http\n\n# Or with custom port\nMCP_PORT=8080 npx -y domain-search-mcp@latest --http\n```\n\n**Endpoints:**\n- `/mcp` - MCP protocol (POST for messages, GET for SSE stream)\n- `/api/tools/*` - REST API for each tool (ChatGPT Actions compatible)\n- `/openapi.json` - OpenAPI 3.1 specification\n- `/health` - Health check\n- `/metrics` - Prometheus-compatible metrics (cache stats, request counts, AI inference health)\n\n### ChatGPT Custom GPT Integration\n\n1. Start the HTTP server (see above)\n2. Expose via ngrok: `ngrok http 3000`\n3. In ChatGPT, create a Custom GPT and add an Action\n4. Import the OpenAPI spec from `https://your-ngrok-url.ngrok-free.dev/openapi.json`\n5. Test the tools!\n\nFor production deployment, use a permanent domain with SSL instead of ngrok.\n\n**REST API Example:**\n```bash\ncurl -X POST https://your-domain/api/tools/search_domain \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"domain_name\":\"vibecoding\"}'\n```\n\n## MCP Client Config\n\n**Claude Code** (`.mcp.json` in project root):\n```json\n{\n  \"mcpServers\": {\n    \"domain-search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"domain-search-mcp@latest\"]\n    }\n  }\n}\n```\n\n**Claude Desktop** (`claude_desktop_config.json`):\n```json\n{\n  \"mcpServers\": {\n    \"domain-search\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"domain-search-mcp@latest\"]\n    }\n  }\n}\n```\n\n> **💡 Tip**: Always use `@latest` to ensure you're running the newest version with all features.\n\n## Tools\n\nAll 12 tools listed below are exposed to MCP clients by default. The 6-tool\nslim profile (`name_project`, `search_domain`, `bulk_search`, `check_socials`,\n`tld_info`, `ai_health`) is opt-in — set `SLIM_TOOLS=true` if you want a\nsharper tool-selection surface for simpler client integrations (see\n[Environment Variables](#environment-variables)). A future 2.0 release may\nflip the default to slim.\n\n`ADVANCED_TOOLS=true` is a deprecated alias that forces the full surface and\noverrides `SLIM_TOOLS`; it's a harmless no-op today since full is already the\ndefault.\n\n### name_project\n\n**Flagship two-phase naming engine.** Call it once to get lane-by-lane generation\ninstructions for *your* model; call it again with `candidates[]` to get anti-slop\nscoring, ranking, and live availability checks across domains, socials, and npm.\n\n- **Modes**: `brief` (describe what you're naming), `auto` (analyze the current\n  workspace), `from_name` (find domains/variants for a name you already like),\n  `from_domain` (fit a project/brand to a domain you found).\n- **Phase 1** (no `candidates`): returns generation instructions + lane prompts.\n- **Phase 2** (`candidates` present): scores + ranks candidates, then checks\n  availability for the top 12 against `targets.tlds` / `targets.platforms` —\n  omit `targets` for pure naming with no availability calls.\n\n> Scores are heuristic rankings for comparing candidates against each other —\n> not objective, universal brandability truth. Availability results reflect a\n> single source checked at one moment in time; re-verify before you register\n> or rely on anything.\n\n**Phase 1** — call with no `candidates`:\n```json\n{\"mode\": \"brief\", \"brief\": \"an MCP naming engine\"}\n```\n```\nBrief: an MCP naming engine\n\nNow generate between 30 and 50 name candidates spread across these lanes:\n- [evocative] Real words borrowed for their feeling, not their meaning (like Slack, Notion, Bolt). Single dictionary words preferred.\n- [invented] Coined words that do not exist but sound like they could (like Zapier, Klarna). Must be pronounceable on first read.\n- [compound] Two short real words fused (like Facebook, Snapchat). Both halves must stay readable; no glue letters.\n- [premium] Short, expensive-feeling names: 4-7 letters, strong single or double syllable (like Stripe, Vercel, Arc).\n\nRules: 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.\n```\n\n**Phase 2** — resubmit the same arguments plus `candidates`:\n```json\n{\"mode\": \"brief\", \"brief\": \"an MCP naming engine\", \"candidates\": [\"Nexify\", \"Corda\"]}\n```\n```\n| Name | Score | Verdict | Badges | Why |\n| --- | --- | --- | --- | --- |\n| Corda | 97 strong | - | - | no AI-slop patterns; clean pronunciation and typing |\n| Nexify | 60 middling | - | - | slop: overused prefix \"nex-\"; slop: overused suffix \"-ify\" |\n2 candidates received, 2 passed constraints, top 2 returned.\nNo availability-check targets - pure naming mode.\n```\n\nBadges: `tld✓` free to register, `tld$` for sale (aftermarket/premium - registered or priced, not free to register), `tld✗` taken, `tld?` unknown.\nccTLD checks (`.ai` / `.io` / `.sh` / `.ac`) are cross-checked against native WHOIS/DNS ground truth, not taken on RDAP's word alone.\n\nSee [docs/API.md](docs/API.md#name_project) for the full parameter/response schema.\n\n### Core Search\n- `search_domain`: Check a name across multiple TLDs, adds premium/auction signals.\n- `bulk_search`: Check up to 100 names for a single TLD.\n- `compare_registrars`: Compare pricing across registrars (backend when configured).\n\n### AI-Powered Suggestions\n- `suggest_domains`: Generate variations (prefix/suffix/hyphen).\n- `suggest_domains_smart`: **🤖 AI-powered** brandable name generation using fine-tuned Qwen 7B-DPO. Zero-config - works instantly!\n- `analyze_project`: Scan local project or GitHub repo to extract context and suggest matching domain names.\n\n### Domain Investment\n- `hunt_domains`: Find valuable domains for investment - scans Sedo auctions, generates patterns, calculates investment scores.\n- `expiring_domains`: Monitor domains approaching expiration (requires federated negative cache).\n\n### Utilities\n- `tld_info`: TLD metadata and restrictions.\n- `check_socials`: Username availability across platforms.\n- `ai_health`: Check status of AI inference services (VPS Qwen, circuit breakers, adaptive concurrency).\n\n## Configuration\n\n### Pricing Backend (Recommended)\n\nSet a backend URL that owns registrar keys (Porkbun). The MCP will call\n`/api/quote` and `/api/compare` on that backend for pricing.\n\n```bash\nPRICING_API_BASE_URL=https://your-backend.example.com\nPRICING_API_TOKEN=optional_bearer_token\n```\n\n### Optional BYOK (Local)\n\nUsed only if `PRICING_API_BASE_URL` is not set.\n\n- Porkbun keys:\n  - https://porkbun.com/account/api\n  - https://porkbun.com/api/json/v3/documentation\n- Namecheap keys (IP whitelist required):\n  - https://ap.www.namecheap.com/settings/tools/apiaccess/\n  - https://www.namecheap.com/support/api/intro/\n\n```bash\nPORKBUN_API_KEY=pk1_your_api_key\nPORKBUN_API_SECRET=sk1_your_secret\nNAMECHEAP_API_KEY=your_api_key\nNAMECHEAP_API_USER=your_username\nNAMECHEAP_CLIENT_IP=your_whitelisted_ip\n```\n\n### Redis Distributed Cache (Optional)\n\nFor horizontal scaling across multiple MCP instances, configure Redis:\n\n```bash\nREDIS_URL=redis://:password@host:6379\n```\n\nWithout Redis, the server uses in-memory caching (works fine for single instances). Redis enables:\n- Shared cache across multiple server instances\n- Persistent cache surviving restarts\n- Better cache hit rates in load-balanced deployments\n\n### AI Inference (bring your own endpoint)\n\nAI-powered suggestions (`suggest_domains_smart`) use your own inference endpoint when configured. Point `QWEN_INFERENCE_ENDPOINT` at a llama.cpp/Qwen server you control. If it is unset, suggestions fall back to the built-in offline semantic engine (no external calls, no API keys needed).\n\n```bash\n# Public hosts must use HTTPS; loopback/private hosts may use HTTP.\nQWEN_INFERENCE_ENDPOINT=http://127.0.0.1:8070\nQWEN_API_KEY=optional_if_secured\n```\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `MCP_TRANSPORT` | stdio | Transport mode: `stdio` or `http` |\n| `MCP_PORT` | 3000 | HTTP server port (when using HTTP transport) |\n| `MCP_HOST` | 0.0.0.0 | HTTP server bind address |\n| `CORS_ORIGINS` | * | Allowed CORS origins (comma-separated) |\n| `PRICING_API_BASE_URL` | - | Pricing backend base URL |\n| `PRICING_API_TOKEN` | - | Optional bearer token |\n| `PRICING_API_TIMEOUT_MS` | 2500 | Backend request timeout |\n| `PRICING_API_MAX_QUOTES_SEARCH` | 0 | Max pricing calls per search (0 = unlimited; backend rate limits apply) |\n| `PRICING_API_MAX_QUOTES_BULK` | 0 | Max pricing calls per bulk search (0 = unlimited; backend rate limits apply) |\n| `PRICING_API_CONCURRENCY` | 4 | Pricing request concurrency |\n| `PORKBUN_API_KEY` | - | Porkbun API key |\n| `PORKBUN_API_SECRET` | - | Porkbun API secret |\n| `NAMECHEAP_API_KEY` | - | Namecheap API key |\n| `NAMECHEAP_API_USER` | - | Namecheap username |\n| `NAMECHEAP_CLIENT_IP` | - | Namecheap IP whitelist |\n| `OUTPUT_FORMAT` | table | `table`, `json`, or `both` for tool output formatting |\n| `LOG_LEVEL` | info | Logging level |\n| `CACHE_TTL_AVAILABILITY` | 60 | Availability cache TTL (seconds) |\n| `CACHE_TTL_PRICING` | 3600 | Pricing cache TTL (seconds) |\n| `CACHE_TTL_SEDO` | 3600 | Sedo auctions feed cache TTL (seconds) |\n| `CACHE_TTL_AFTERMARKET_NS` | 300 | Nameserver lookup cache TTL (seconds) |\n| `SEDO_FEED_ENABLED` | true | Enable Sedo feed lookup for aftermarket hints |\n| `SEDO_FEED_URL` | https://sedo.com/txt/auctions_us.txt | Sedo public feed URL |\n| `AFTERMARKET_NS_ENABLED` | true | Enable nameserver-based aftermarket hints |\n| `AFTERMARKET_NS_TIMEOUT_MS` | 1500 | Nameserver lookup timeout (ms) |\n| `REDIS_URL` | - | Redis connection URL for distributed caching (e.g., `redis://:password@host:6379`) |\n| `QWEN_INFERENCE_ENDPOINT` | (none) | Your own AI inference endpoint for `suggest_domains_smart` (offline semantic fallback if unset) |\n| `QWEN_TIMEOUT_MS` | 15000 | AI inference request timeout |\n| `QWEN_MAX_RETRIES` | 2 | Retry count for AI inference failures |\n| `SLIM_TOOLS` | false | Set `true` to opt into the slim 6-tool surface instead of the full 12-tool default |\n| `ADVANCED_TOOLS` | false | Deprecated alias for the pre-`SLIM_TOOLS` flag. Set `true` to force the full 12-tool surface and override `SLIM_TOOLS`; no-op since full is already the default |\n\n### Output Format\n\nTool responses are returned as **Markdown tables by default**. If you need raw\nJSON for programmatic use, set:\n\n```bash\nOUTPUT_FORMAT=json\n```\n\n## Data Sources\n\n| Source | Position in Chain | Usage | API Keys |\n|--------|-------------------|-------|----------|\n| **RDAP** | 1st (Primary) | Fast availability check | Not needed |\n| **GoDaddy** | 2nd (Fallback) | Premium/auction detection | Not needed |\n| **WHOIS** | 3rd (Last resort) | Legacy availability | Not needed |\n| Pricing API | Parallel | Live pricing via backend | Backend token |\n| Porkbun API | Parallel (BYOK) | Availability + pricing | API key + secret |\n| Namecheap API | Parallel (BYOK) | Availability + pricing | API key + IP whitelist |\n| Sedo Feed | Enrichment | Aftermarket auction hints | Not needed |\n\n## Pricing Behavior\n\n- Live price is attempted first for every **available** domain.\n- If live quotes fail or are rate-limited, the result falls back to the catalog estimate and includes `price_note`.\n- Always verify pricing via `price_check_url` before purchase.\n\n## Examples\n\n### Basic Search (No API Keys)\n\n```\nsearch_domain(\"myproject\", [\"com\", \"io\", \"dev\"])\n\n┌─────────────────┬───────────┬─────────┬────────┐\n│ Domain          │ Available │ Premium │ Source │\n├─────────────────┼───────────┼─────────┼────────┤\n│ myproject.com   │ ✅        │ No      │ rdap   │\n│ myproject.io    │ ❌        │ -       │ rdap   │\n│ myproject.dev   │ ✅        │ Yes     │ godaddy│\n└─────────────────┴───────────┴─────────┴────────┘\n```\n\n### AI-Powered Suggestions\n\n```\nsuggest_domains_smart(\"coffee shop in seattle\", { style: \"brandable\" })\n\n→ seattlebrew.com, pugetperk.io, raincitycoffee.co, cascadiacafe.com\n```\n\n### Bulk Check\n\n```\nbulk_search([\"startup\", \"launch\", \"begin\", \"init\"], \"io\")\n\n→ Checks startup.io, launch.io, begin.io, init.io in parallel\n```\n\n## Development\n\n```bash\nnpm run dev       # watch mode\nnpm test          # run Jest\nnpm run build     # compile to dist/\n```\n\n## Release\n\nSee `docs/RELEASE.md` for the tag-triggered release flow. Version tags trigger\nthe GitHub Release, npm trusted publishing with provenance, and MCP Registry\npublication through GitHub Actions.\n\n## Changelog\n\nSee `CHANGELOG.md` for release history.\n\n## Security Notes\n\n- Do not commit API keys or `.mcpregistry_*` files.\n- Without `PRICING_API_BASE_URL` (or BYOK keys), pricing is not available (availability still works).\n\n## Upgrading\n\n### For npx Users\n\nIf you use `npx domain-search-mcp` (without `@latest`), npx may cache an old version.\n\n**Fix**: Update your MCP config to use `@latest`:\n```json\n\"args\": [\"-y\", \"domain-search-mcp@latest\"]\n```\n\nOr clear the npx cache manually:\n```bash\nnpx clear-npx-cache  # then restart your MCP client\n```\n\n### For Source/Git Users\n\n```bash\ncd domain-search-mcp\ngit pull origin main\nnpm install\nnpm run build\n```\n\n### Staying Updated\n\n- **Watch the repo**: Click \"Watch\" → \"Releases only\" on [GitHub](https://github.com/dorukardahan/domain-search-mcp) to get notified of new versions.\n- **Check releases**: See [GitHub Releases](https://github.com/dorukardahan/domain-search-mcp/releases) for changelog and upgrade notes.\n- **npm page**: [npmjs.com/package/domain-search-mcp](https://www.npmjs.com/package/domain-search-mcp) shows the latest version.\n\n## Architecture\n\nFor detailed system architecture diagrams, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md):\n\n- Transport layer (stdio vs HTTP/SSE)\n- Tool execution flow\n- Data source waterfall (RDAP → Pricing API → WHOIS)\n- VPS deployment architecture\n- AI suggestion flow\n- MCP session lifecycle\n\n## Why This Tool?\n\n| Problem | Solution |\n|---------|----------|\n| Domain APIs require signup/keys | RDAP + GoDaddy = zero-config availability |\n| Premium domains show as \"available\" | GoDaddy detects premium/auction status |\n| Hard to check multiple TLDs | Single call checks .com, .io, .dev, etc. |\n| No AI integration for naming | Built-in Qwen 7B for brandable suggestions |\n| Only works with Claude | HTTP transport supports ChatGPT, LM Studio |\n\n## FAQ\n\n**Q: Does this work without any API keys?**\nA: Yes! Availability checking uses public RDAP and GoDaddy endpoints. Only pricing requires API keys.\n\n**Q: Which MCP clients are supported?**\nA: Claude Desktop, Claude Code, VS Code, Cursor, Cline (stdio), and ChatGPT, LM Studio (HTTP/SSE).\n\n**Q: How accurate is premium domain detection?**\nA: GoDaddy's public endpoint detects most premium and auction domains. Always verify on registrar checkout.\n\n**Q: Can I self-host the AI suggestions?**\nA: Yes! Set `QWEN_INFERENCE_ENDPOINT` to your llama.cpp server running the fine-tuned model.\n\n## Links\n\n- **npm**: [npmjs.com/package/domain-search-mcp](https://www.npmjs.com/package/domain-search-mcp)\n- **MCP Registry**: [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io)\n- **Glama**: [glama.ai/mcp/servers/@dorukardahan/domain-search-mcp](https://glama.ai/mcp/servers/@dorukardahan/domain-search-mcp)\n- **Context7**: [context7.com/dorukardahan/domain-search-mcp](https://context7.com/dorukardahan/domain-search-mcp)\n\n### Documentation\n\n- [Architecture](docs/ARCHITECTURE.md) - System design and data flow\n- [API Reference](docs/API.md) - Tool schemas and responses\n- [Configuration](docs/CONFIGURATION.md) - Environment variables\n- [Workflows](docs/WORKFLOWS.md) - Common usage patterns\n",
  "bytes": 20276,
  "sha": "05e2e02a51e1285ec34ff57845c090abfd17f2eddec4dd454e06a18f04e1d2af",
  "repo_slug": "dorukardahan/domain-search-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_dorukardahan_domain_search_mcp_16958a53/readme"
}