# Domain Search MCP

Domain Search MCP is a fast domain availability aggregator built for AI assistants using the Model Context Protocol (MCP). It provides seamless domain search capabilities across multiple registrars including Porkbun, Namecheap, GoDaddy MCP, and fallback protocols like RDAP and WHOIS. The server enables AI assistants like Claude Desktop, Cursor, and Cline to check domain availability, compare pricing, generate AI-powered domain suggestions, suggest alternatives, and verify social handle availability without requiring API keys for basic functionality.

The project is designed with a "magic in 60 seconds" philosophy, offering zero-configuration startup with intelligent fallbacks. It aggregates data from premium registrar APIs when configured, but gracefully falls back to public protocols (RDAP/WHOIS) to ensure functionality without authentication. Built on TypeScript with the MCP SDK (version 1.2.5), it exposes seven powerful tools through the protocol for comprehensive domain research and brand validation, including an advanced semantic engine for intelligent domain name generation from natural language queries.

## API Reference and Code Examples

### search_domain - Check Domain Availability Across TLDs

Searches for domain availability across multiple top-level domains with pricing information, WHOIS privacy details, and actionable insights.

```typescript
import { searchDomain } from './src/services/domain-search.js';

async function checkDomain() {
  try {
    // Search default TLDs (.com, .io, .dev)
    const result = await searchDomain('vibecoding');

    // Custom TLD selection
    const customResult = await searchDomain('myapp', ['com', 'io', 'ai', 'dev']);

    // Specify preferred registrars
    const registrarResult = await searchDomain(
      'coolstartup',
      ['com', 'io'],
      ['porkbun', 'namecheap']
    );

    // Process results
    for (const domain of result.results) {
      console.log(`${domain.domain}: ${domain.available ? 'Available' : 'Taken'}`);
      if (domain.price_first_year) {
        console.log(`  Price: $${domain.price_first_year}/year`);
        console.log(`  Renewal: $${domain.price_renewal}/year`);
      }
      console.log(`  Privacy: ${domain.privacy_included ? 'Included' : 'Extra cost'}`);
      console.log(`  Source: ${domain.source}`);
    }

    // Display AI-generated insights
    console.log('\nInsights:');
    result.insights.forEach(insight => console.log(`  ${insight}`));

    // Show recommended actions
    console.log('\nNext Steps:');
    result.next_steps.forEach(step => console.log(`  • ${step}`));

  } catch (error) {
    console.error('Search failed:', error.message);
  }
}
```

### bulk_search - Search Multiple Domains Simultaneously

Efficiently checks availability for up to 100 domain names in parallel with intelligent rate limiting and batch processing.

```typescript
import { bulkSearchDomains } from './src/services/domain-search.js';

async function bulkCheck() {
  try {
    const domainList = [
      'vibecoding',
      'coolstartup',
      'myawesomeapp',
      'techhub',
      'devtools'
    ];

    // Check all domains with .io TLD
    const results = await bulkSearchDomains(domainList, 'io');

    // Use specific registrar
    const porkbunResults = await bulkSearchDomains(
      domainList,
      'com',
      'porkbun'
    );

    // Custom concurrency (default: 10)
    const fastResults = await bulkSearchDomains(
      domainList,
      'dev',
      undefined,
      10  // Check 10 domains at once
    );

    // Analyze results
    const available = results.filter(r => r.available);
    const taken = results.filter(r => !r.available);

    console.log(`Available: ${available.length}/${results.length}`);

    // Find cheapest option
    const cheapest = available
      .filter(r => r.price_first_year)
      .sort((a, b) => a.price_first_year! - b.price_first_year!)[0];

    if (cheapest) {
      console.log(`Best deal: ${cheapest.domain} at $${cheapest.price_first_year}/year`);
    }

  } catch (error) {
    console.error('Bulk search failed:', error.message);
  }
}
```

### compare_registrars - Find Best Pricing Across Registrars

Compares pricing for the same domain across multiple registrars to identify the best first-year and renewal prices.

```typescript
import { compareRegistrars } from './src/services/domain-search.js';

async function comparePricing() {
  try {
    // Compare default registrars (Porkbun, Namecheap)
    const comparison = await compareRegistrars('vibecoding', 'com');

    // Specify registrars to compare
    const customComparison = await compareRegistrars(
      'myapp',
      'io',
      ['porkbun', 'namecheap']
    );

    console.log(`Domain: ${comparison.comparisons[0]?.domain || 'N/A'}`);

    // Show all pricing
    comparison.comparisons.forEach(result => {
      console.log(`\n${result.registrar}:`);
      console.log(`  Available: ${result.available}`);
      if (result.price_first_year) {
        console.log(`  First year: $${result.price_first_year}`);
        console.log(`  Renewal: $${result.price_renewal}`);
        console.log(`  Privacy: ${result.privacy_included ? 'Free' : 'Paid'}`);
      }
      if (result.premium) {
        console.log(`  ⚠️  Premium: ${result.premium_reason}`);
      }
    });

    // Best deals
    if (comparison.best_first_year) {
      console.log(`\n✅ Best first year: ${comparison.best_first_year.registrar} at $${comparison.best_first_year.price}`);
    }

    if (comparison.best_renewal) {
      console.log(`✅ Best renewal: ${comparison.best_renewal.registrar} at $${comparison.best_renewal.price}`);
    }

    console.log(`\nRecommendation: ${comparison.recommendation}`);

  } catch (error) {
    console.error('Comparison failed:', error.message);
  }
}
```

### suggest_domains - Generate Available Domain Variations

Generates creative variations of a base domain name and checks their availability, returning ranked suggestions based on price, length, and quality.

```typescript
import { executeSuggestDomains } from './src/tools/suggest_domains.js';

async function getSuggestions() {
  try {
    // Get default suggestions (all variation types)
    const suggestions = await executeSuggestDomains({
      base_name: 'vibecoding',
      tld: 'com',
      max_suggestions: 10
    });

    // Specific variation types
    const prefixSuggestions = await executeSuggestDomains({
      base_name: 'myapp',
      tld: 'io',
      variants: ['prefixes', 'suffixes'],  // get-, try-, -app, -hq, etc.
      max_suggestions: 5
    });

    // All variation types
    const allVariations = await executeSuggestDomains({
      base_name: 'startup',
      tld: 'dev',
      variants: ['hyphen', 'numbers', 'abbreviations', 'synonyms', 'prefixes', 'suffixes'],
      max_suggestions: 20
    });

    console.log(`Base: ${suggestions.base_name}.${suggestions.tld}`);
    console.log(`Checked: ${suggestions.total_checked} variations`);
    console.log(`Found: ${suggestions.available_count} available\n`);

    // Display ranked suggestions
    suggestions.suggestions.forEach((suggestion, index) => {
      console.log(`${index + 1}. ${suggestion.domain}`);
      console.log(`   Price: $${suggestion.price_first_year || 'unknown'}/year`);
      console.log(`   Registrar: ${suggestion.registrar}`);
      console.log(`   Quality Score: ${suggestion.score}/100`);
    });

    // Show insights
    console.log('\nInsights:');
    suggestions.insights.forEach(insight => console.log(`  ${insight}`));

    // Access top suggestion
    const topPick = suggestions.suggestions[0];
    if (topPick) {
      console.log(`\n⭐ Recommended: ${topPick.domain}`);
    }

  } catch (error) {
    console.error('Suggestion failed:', error.message);
  }
}
```

### suggest_domains_smart - AI-Powered Domain Suggestions from Natural Language

Generates creative, brandable domain names from keywords or business descriptions using a dual-source approach that combines semantic analysis with GoDaddy's AI recommendations. This tool understands natural language queries, auto-detects industry context, and generates intelligent suggestions including portmanteau names.

```typescript
import { executeSuggestDomainsSmart } from './src/tools/suggest_domains_smart.js';

async function getSmartSuggestions() {
  try {
    // Natural language query
    const suggestions = await executeSuggestDomainsSmart({
      query: 'ai customer service chatbot',
      tld: 'io',
      max_suggestions: 10
    });

    // With industry context and style
    const brandableSuggestions = await executeSuggestDomainsSmart({
      query: 'organic coffee shop seattle',
      tld: 'com',
      industry: 'food',
      style: 'brandable',  // brandable, descriptive, short, creative
      max_suggestions: 15
    });

    // Include premium domains
    const withPremium = await executeSuggestDomainsSmart({
      query: 'vibecoding',
      tld: 'dev',
      style: 'short',
      include_premium: true,
      max_suggestions: 20
    });

    // Display results with dual-source info
    console.log(`Query: ${suggestions.query}`);
    console.log(`Detected Words: ${suggestions.detected_words.join(', ')}`);
    console.log(`Industry: ${suggestions.detected_industry || 'auto-detected'}`);
    console.log(`\nSources:`);
    console.log(`  Semantic Engine: ${suggestions.sources.semantic_engine} suggestions`);
    console.log(`  GoDaddy AI: ${suggestions.sources.godaddy_suggest} suggestions`);
    console.log(`  Merged (both): ${suggestions.sources.merged} verified by both`);

    // Available domains
    console.log(`\nAvailable Domains (${suggestions.results.available.length}):`);
    suggestions.results.available.forEach((domain, i) => {
      const priceInfo = domain.price_first_year
        ? `$${domain.price_first_year}/yr`
        : `via ${domain.registrar}`;
      const sourceInfo = domain.source === 'both' ? ' ✓✓ (verified)' : '';
      console.log(`${i + 1}. ${domain.domain}`);
      console.log(`   Price: ${priceInfo}`);
      console.log(`   Score: ${domain.score}/100`);
      console.log(`   Source: ${domain.source}${sourceInfo}`);
    });

    // Premium domains (if included)
    if (suggestions.results.premium.length > 0) {
      console.log(`\nPremium Domains (${suggestions.results.premium.length}):`);
      suggestions.results.premium.forEach(domain => {
        console.log(`  ${domain.domain} - ${domain.category}`);
      });
    }

    // Insights
    console.log('\nInsights:');
    suggestions.insights.forEach(insight => console.log(`  ${insight}`));

    // Related terms for further exploration
    console.log('\nRelated Terms:');
    console.log(`  ${suggestions.related_terms.join(', ')}`);

    // Access top suggestion
    const topPick = suggestions.results.available[0];
    if (topPick) {
      console.log(`\n⭐ Recommended: ${topPick.domain}`);
      if (topPick.source === 'both') {
        console.log('   This domain was validated by both our engine and GoDaddy AI!');
      }
    }

  } catch (error) {
    console.error('Smart suggestion failed:', error.message);
  }
}
```

### tld_info - Get TLD Information and Recommendations

Retrieves detailed information about top-level domains including pricing ranges, restrictions, popularity, and use case recommendations.

```typescript
import { executeTldInfo } from './src/tools/tld_info.js';

async function getTldInfo() {
  try {
    // Basic TLD info
    const comInfo = await executeTldInfo({ tld: 'com' });

    // Detailed information
    const ioInfo = await executeTldInfo({ tld: 'io', detailed: true });

    // Multiple TLDs
    const tlds = ['com', 'io', 'dev', 'ai', 'app'];
    const allInfo = await Promise.all(
      tlds.map(tld => executeTldInfo({ tld }))
    );

    // Display TLD details
    console.log(`TLD: .${comInfo.tld}`);
    console.log(`Description: ${comInfo.description}`);
    console.log(`Typical Use: ${comInfo.typical_use}`);
    console.log(`\nPricing:`);
    console.log(`  Range: $${comInfo.price_range.min} - $${comInfo.price_range.max}`);
    console.log(`  Typical Renewal: $${comInfo.renewal_price_typical}`);
    console.log(`  Currency: ${comInfo.price_range.currency}`);

    if (comInfo.restrictions.length > 0) {
      console.log(`\nRestrictions:`);
      comInfo.restrictions.forEach(r => console.log(`  • ${r}`));
    }

    console.log(`\nPopularity: ${comInfo.popularity}`);
    console.log(`Category: ${comInfo.category}`);
    console.log(`\nRecommendation: ${comInfo.recommendation}`);

    // Display insights
    console.log('\nInsights:');
    comInfo.insights.forEach(insight => console.log(`  ${insight}`));

    // Compare TLDs
    console.log('\n\nTLD Comparison:');
    allInfo.forEach(info => {
      console.log(`\n.${info.tld}: $${info.price_range.min}+ (${info.popularity} popularity)`);
      console.log(`  ${info.recommendation}`);
    });

  } catch (error) {
    console.error('TLD info failed:', error.message);
  }
}
```

### check_socials - Verify Social Handle Availability

Checks username availability across social media and developer platforms with confidence ratings based on detection reliability.

```typescript
import { executeCheckSocials } from './src/tools/check_socials.js';

async function checkHandles() {
  try {
    // Check default platforms (GitHub, Twitter, Reddit, npm)
    const results = await executeCheckSocials({ name: 'vibecoding' });

    // Custom platform selection
    const devPlatforms = await executeCheckSocials({
      name: 'myapp',
      platforms: ['github', 'npm', 'pypi']
    });

    // All platforms
    const allPlatforms = await executeCheckSocials({
      name: 'coolstartup',
      platforms: [
        'github', 'twitter', 'instagram', 'linkedin', 'tiktok',
        'reddit', 'youtube', 'npm', 'pypi', 'producthunt'
      ]
    });

    console.log(`Checking username: ${results.name}\n`);

    // Display by confidence level
    const highConfidence = results.results.filter(r => r.confidence === 'high');
    const mediumConfidence = results.results.filter(r => r.confidence === 'medium');
    const lowConfidence = results.results.filter(r => r.confidence === 'low');

    console.log('High Confidence (Public APIs):');
    highConfidence.forEach(r => {
      const status = r.available ? '✅ Available' : '❌ Taken';
      console.log(`  ${r.platform}: ${status}`);
      console.log(`    URL: ${r.url}`);
    });

    console.log('\nMedium Confidence (Status Codes):');
    mediumConfidence.forEach(r => {
      const status = r.available ? '✅ Available' : '❌ Taken';
      console.log(`  ${r.platform}: ${status}`);
    });

    console.log('\nLow Confidence (Verify Manually):');
    lowConfidence.forEach(r => {
      console.log(`  ${r.platform}: ${r.available ? 'Possibly available' : 'Possibly taken'}`);
      console.log(`    Check manually: ${r.url}`);
    });

    // Summary
    console.log(`\nSummary:`);
    console.log(`  Available: ${results.summary.available}`);
    console.log(`  Taken: ${results.summary.taken}`);
    console.log(`  Uncertain: ${results.summary.uncertain}`);

    // Insights
    console.log('\nInsights:');
    results.insights.forEach(insight => console.log(`  ${insight}`));

    // Check for consistency
    const allAvailable = results.results.every(r => r.available);
    if (allAvailable) {
      console.log('\n🎉 Username available everywhere - perfect for consistent branding!');
    }

  } catch (error) {
    console.error('Social check failed:', error.message);
  }
}
```

### MCP Server Setup and Integration

Configures the MCP server for use with Claude Desktop, Cursor, and other AI assistants with environment-based configuration.

```bash
# Install dependencies
npm install

# Build the TypeScript project
npm run build

# Create environment configuration (optional)
cat > .env << 'EOF'
# Porkbun API (optional, free at porkbun.com/account/api)
PORKBUN_API_KEY=your_api_key_here
PORKBUN_API_SECRET=your_api_secret_here

# Namecheap API (optional, requires IP whitelist)
NAMECHEAP_API_KEY=your_api_key_here
NAMECHEAP_API_USER=your_username_here

# Logging and caching
LOG_LEVEL=info
CACHE_TTL_AVAILABILITY=300
CACHE_TTL_PRICING=3600
RATE_LIMIT_PER_MINUTE=60

# TLD configuration
ALLOWED_TLDS=com,io,dev,app,co,net,org,xyz,ai,sh,me,cc
DENY_TLDS=localhost,internal,test,local
EOF

# Configure Claude Desktop (Mac)
cat > ~/Library/Application\ Support/Claude/claude_desktop_config.json << 'EOF'
{
  "mcpServers": {
    "domain-search": {
      "command": "node",
      "args": ["/absolute/path/to/domain-search-mcp/dist/server.js"]
    }
  }
}
EOF

# Configure Cursor IDE
mkdir -p .cursor
cat > .cursor/mcp.json << 'EOF'
{
  "servers": {
    "domain-search": {
      "command": "node",
      "args": ["./dist/server.js"]
    }
  }
}
EOF

# Start server in development mode
npm run dev

# Run tests
npm test

# Run with coverage
npm run coverage
```

### Error Handling and Response Types

All API functions return structured errors with user-friendly messages and retry guidance.

```typescript
import { DomainSearchError, wrapError } from './src/utils/errors.js';
import type { DomainResult, SearchResponse } from './src/types.js';

async function robustSearch() {
  try {
    const result = await searchDomain('example', ['com', 'io']);

    // Handle successful response
    const availableDomains = result.results.filter(r => r.available);

    // Check for premium domains
    const premiums = availableDomains.filter(r => r.premium);
    premiums.forEach(domain => {
      console.log(`Premium: ${domain.domain} - $${domain.price_first_year}`);
      console.log(`Reason: ${domain.premium_reason}`);
    });

    // Access metadata
    console.log(`Cache hit: ${result.from_cache}`);
    console.log(`Duration: ${result.duration_ms}ms`);

  } catch (error) {
    const wrapped = wrapError(error);

    console.error(`Error Code: ${wrapped.code}`);
    console.error(`Message: ${wrapped.userMessage}`);
    console.error(`Retryable: ${wrapped.retryable}`);

    if (wrapped.suggestedAction) {
      console.log(`Suggestion: ${wrapped.suggestedAction}`);
    }

    // Handle specific error codes
    switch (wrapped.code) {
      case 'INVALID_DOMAIN':
        console.error('Domain name format is invalid');
        break;
      case 'RATE_LIMIT':
        console.error('Too many requests - wait and retry');
        setTimeout(() => robustSearch(), 30000);
        break;
      case 'NO_SOURCE_AVAILABLE':
        console.error('All data sources failed');
        break;
      case 'AUTH_ERROR':
        console.error('Check API credentials');
        break;
    }
  }
}

// Type-safe domain result processing
function processDomainResult(result: DomainResult): void {
  // All fields are strongly typed
  const domain: string = result.domain;
  const available: boolean = result.available;
  const price: number | null = result.price_first_year;
  const source: DataSource = result.source;

  // Optional fields with type guards
  if (result.expires_at && result.days_until_expiration !== undefined) {
    const daysLeft = result.days_until_expiration;
    if (daysLeft <= 30) {
      console.log(`Domain expires soon: ${daysLeft} days`);
    }
  }

  // Quality scoring
  if (result.score !== undefined) {
    console.log(`Quality score: ${result.score}/10`);
  }
}
```

## Use Cases and Integration Patterns

Domain Search MCP serves two primary use cases: interactive domain research for startups and automated brand validation for development workflows. For interactive use, AI assistants like Claude Desktop or Cursor can leverage the seven tools to conduct comprehensive domain research conversations, helping users find available domains, compare pricing across registrars, generate AI-powered suggestions from natural language descriptions, create creative alternatives when preferred names are taken, and verify consistent branding across social platforms. The server's intelligent caching, dual-source validation (semantic engine + GoDaddy AI), and fallback mechanisms ensure fast responses even without registrar API keys configured.

For integration patterns, developers can embed the MCP server into CI/CD pipelines for brand validation, build command-line tools using the service layer directly, or create custom dashboards that aggregate domain and social handle availability data. The TypeScript service layer exports all core functions independently of the MCP protocol, enabling direct programmatic access for Node.js applications. The modular architecture with separate registrar adapters (Porkbun, Namecheap, GoDaddy MCP), fallback protocols (RDAP, WHOIS), semantic analysis engine, and caching utilities makes it straightforward to extend with additional data sources or customize behavior for specific organizational needs. All results include structured metadata like confidence levels, data sources, quality scores, and dual-source verification status to support automated decision-making.