domain-search-mcp 1.2.9 → 1.2.10

package/README.md

@@ -2378,6 +2378,513 @@ ALLOWED_TLDS=com,io,dev,app,co,net,org,xyz,ai,sh,me,cc
 DENY_TLDS=localhost,internal,test,local
 ```
 
+### Programmatic Environment Variable Configuration
+
+For applications that need to configure API keys programmatically (without .env files), use these patterns:
+
+#### Setting Environment Variables in Application Code
+
+```typescript
+// ═══════════════════════════════════════════════════════════════════════════
+// PROGRAMMATIC CONFIGURATION MODULE
+// Use this when you need to configure Domain Search MCP in code
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { searchDomain, bulkSearch, compareRegistrars, tldInfo, checkSocials, suggestDomains } from 'domain-search-mcp';
+
+/**
+ * Configuration interface for Domain Search MCP
+ */
+interface DomainSearchConfig {
+  porkbun?: {
+    apiKey: string;
+    apiSecret: string;
+  };
+  namecheap?: {
+    apiKey: string;
+    apiUser: string;
+    clientIp?: string;  // Auto-detected if not provided
+  };
+  cache?: {
+    availabilityTtl?: number;  // seconds, default 300
+    pricingTtl?: number;       // seconds, default 3600
+  };
+  rateLimitPerMinute?: number;  // default 60
+  logLevel?: 'debug' | 'info' | 'warn' | 'error';
+}
+
+/**
+ * Configure Domain Search MCP programmatically
+ * Call this BEFORE any domain search operations
+ */
+function configureDomainSearch(config: DomainSearchConfig): void {
+  // Set Porkbun credentials
+  if (config.porkbun) {
+    process.env.PORKBUN_API_KEY = config.porkbun.apiKey;
+    process.env.PORKBUN_API_SECRET = config.porkbun.apiSecret;
+  }
+
+  // Set Namecheap credentials
+  if (config.namecheap) {
+    process.env.NAMECHEAP_API_KEY = config.namecheap.apiKey;
+    process.env.NAMECHEAP_API_USER = config.namecheap.apiUser;
+    if (config.namecheap.clientIp) {
+      process.env.NAMECHEAP_CLIENT_IP = config.namecheap.clientIp;
+    }
+  }
+
+  // Set cache configuration
+  if (config.cache) {
+    if (config.cache.availabilityTtl) {
+      process.env.CACHE_TTL_AVAILABILITY = String(config.cache.availabilityTtl);
+    }
+    if (config.cache.pricingTtl) {
+      process.env.CACHE_TTL_PRICING = String(config.cache.pricingTtl);
+    }
+  }
+
+  // Set rate limiting
+  if (config.rateLimitPerMinute) {
+    process.env.RATE_LIMIT_PER_MINUTE = String(config.rateLimitPerMinute);
+  }
+
+  // Set log level
+  if (config.logLevel) {
+    process.env.LOG_LEVEL = config.logLevel;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// USAGE EXAMPLES
+// ═══════════════════════════════════════════════════════════════════════════
+
+// Example 1: Configure with Porkbun only (recommended)
+configureDomainSearch({
+  porkbun: {
+    apiKey: 'pk1_abc123def456ghi789jkl012mno345pqr678stu901vwx234',
+    apiSecret: 'sk1_xyz789abc123def456ghi789jkl012mno345pqr678stu901'
+  },
+  logLevel: 'info'
+});
+
+// Example 2: Configure with both Porkbun and Namecheap for price comparison
+configureDomainSearch({
+  porkbun: {
+    apiKey: process.env.MY_APP_PORKBUN_KEY!,
+    apiSecret: process.env.MY_APP_PORKBUN_SECRET!
+  },
+  namecheap: {
+    apiKey: process.env.MY_APP_NAMECHEAP_KEY!,
+    apiUser: process.env.MY_APP_NAMECHEAP_USER!
+  },
+  cache: {
+    availabilityTtl: 600,   // 10 minutes
+    pricingTtl: 7200        // 2 hours
+  },
+  rateLimitPerMinute: 100,
+  logLevel: 'debug'
+});
+
+// Example 3: No API keys (uses RDAP/WHOIS fallback)
+configureDomainSearch({
+  cache: { availabilityTtl: 300 },
+  logLevel: 'warn'
+});
+
+// Now use the configured service
+const result = await searchDomain({
+  domain_name: "myproject",
+  tlds: ["com", "io", "dev"]
+});
+```
+
+#### Complete Initialization Module Pattern
+
+```typescript
+// ═══════════════════════════════════════════════════════════════════════════
+// domain-search-init.ts - Reusable initialization module
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { searchDomain, tldInfo, checkSocials, compareRegistrars } from 'domain-search-mcp';
+
+// Configuration types
+interface RegistrarCredentials {
+  type: 'porkbun' | 'namecheap';
+  apiKey: string;
+  apiSecret?: string;  // Required for Porkbun
+  apiUser?: string;    // Required for Namecheap
+  clientIp?: string;   // Optional for Namecheap
+}
+
+interface InitializationResult {
+  success: boolean;
+  activeSource: 'porkbun_api' | 'namecheap_api' | 'godaddy_mcp' | 'rdap' | 'whois';
+  pricingAvailable: boolean;
+  estimatedResponseTime: string;
+  errors: string[];
+  warnings: string[];
+}
+
+/**
+ * Initialize Domain Search MCP with full validation
+ *
+ * @param credentials - Optional registrar credentials
+ * @returns Initialization result with status and diagnostics
+ */
+async function initializeDomainSearch(
+  credentials?: RegistrarCredentials[]
+): Promise<InitializationResult> {
+  const result: InitializationResult = {
+    success: false,
+    activeSource: 'rdap',
+    pricingAvailable: false,
+    estimatedResponseTime: '2-5 seconds',
+    errors: [],
+    warnings: []
+  };
+
+  // Step 1: Set environment variables from credentials
+  if (credentials) {
+    for (const cred of credentials) {
+      if (cred.type === 'porkbun') {
+        if (!cred.apiKey || !cred.apiSecret) {
+          result.errors.push('Porkbun requires both apiKey and apiSecret');
+          continue;
+        }
+        process.env.PORKBUN_API_KEY = cred.apiKey;
+        process.env.PORKBUN_API_SECRET = cred.apiSecret;
+      } else if (cred.type === 'namecheap') {
+        if (!cred.apiKey || !cred.apiUser) {
+          result.errors.push('Namecheap requires both apiKey and apiUser');
+          continue;
+        }
+        process.env.NAMECHEAP_API_KEY = cred.apiKey;
+        process.env.NAMECHEAP_API_USER = cred.apiUser;
+        if (cred.clientIp) {
+          process.env.NAMECHEAP_CLIENT_IP = cred.clientIp;
+        }
+      }
+    }
+  }
+
+  // Step 2: Run validation search
+  try {
+    const testResult = await searchDomain({
+      domain_name: `init-test-${Date.now()}`,
+      tlds: ['com']
+    });
+
+    if (testResult.results && testResult.results.length > 0) {
+      const source = testResult.results[0].source;
+      result.activeSource = source as InitializationResult['activeSource'];
+      result.pricingAvailable = testResult.results[0].price_first_year !== null;
+
+      // Set response time estimate based on source
+      switch (source) {
+        case 'porkbun_api':
+          result.estimatedResponseTime = '100-200ms';
+          break;
+        case 'namecheap_api':
+          result.estimatedResponseTime = '150-300ms';
+          break;
+        case 'godaddy_mcp':
+          result.estimatedResponseTime = '200-400ms';
+          break;
+        default:
+          result.estimatedResponseTime = '2-5 seconds';
+      }
+
+      result.success = true;
+    }
+  } catch (error) {
+    result.errors.push(`Validation failed: ${error.message}`);
+
+    // Provide specific remediation based on error
+    if (error.message.includes('AUTH') || error.message.includes('401')) {
+      result.errors.push('API key authentication failed. Check your credentials.');
+    }
+    if (error.message.includes('IP') || error.message.includes('whitelist')) {
+      result.errors.push('IP not whitelisted for Namecheap. Add your IP at https://ap.www.namecheap.com/settings/tools/apiaccess');
+    }
+  }
+
+  // Step 3: Add warnings for suboptimal configuration
+  if (!result.pricingAvailable) {
+    result.warnings.push(
+      'Pricing data not available. Add Porkbun API keys for pricing information.'
+    );
+  }
+
+  if (result.activeSource === 'rdap' || result.activeSource === 'whois') {
+    result.warnings.push(
+      'Using fallback source. Response times will be 10-20x slower than with API keys.'
+    );
+  }
+
+  return result;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// USAGE EXAMPLE: Complete Application Bootstrap
+// ═══════════════════════════════════════════════════════════════════════════
+
+async function bootstrapApplication() {
+  console.log('Initializing Domain Search MCP...');
+  console.log('─'.repeat(60));
+
+  // Initialize with credentials (or empty array for fallback mode)
+  const initResult = await initializeDomainSearch([
+    {
+      type: 'porkbun',
+      apiKey: process.env.PORKBUN_API_KEY || '',
+      apiSecret: process.env.PORKBUN_API_SECRET || ''
+    }
+  ]);
+
+  // Report initialization status
+  console.log(`\nInitialization ${initResult.success ? '✅ SUCCESS' : '❌ FAILED'}`);
+  console.log(`Active source: ${initResult.activeSource}`);
+  console.log(`Pricing available: ${initResult.pricingAvailable ? 'Yes' : 'No'}`);
+  console.log(`Expected response time: ${initResult.estimatedResponseTime}`);
+
+  if (initResult.errors.length > 0) {
+    console.log('\n❌ Errors:');
+    initResult.errors.forEach(e => console.log(`   - ${e}`));
+  }
+
+  if (initResult.warnings.length > 0) {
+    console.log('\n⚠️ Warnings:');
+    initResult.warnings.forEach(w => console.log(`   - ${w}`));
+  }
+
+  if (!initResult.success) {
+    throw new Error('Domain Search MCP initialization failed');
+  }
+
+  console.log('\n' + '─'.repeat(60));
+  console.log('Ready to search domains!\n');
+
+  return initResult;
+}
+
+// Bootstrap the application
+bootstrapApplication()
+  .then(() => {
+    // Application is ready, proceed with domain operations
+    console.log('Application started successfully');
+  })
+  .catch((error) => {
+    console.error('Failed to start application:', error.message);
+    process.exit(1);
+  });
+```
+
+#### Invalid API Key Error Handling Patterns
+
+```typescript
+// ═══════════════════════════════════════════════════════════════════════════
+// COMPREHENSIVE API KEY ERROR HANDLING
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { searchDomain, DomainSearchError } from 'domain-search-mcp';
+
+// Error codes returned by Domain Search MCP
+type DomainSearchErrorCode =
+  | 'AUTH_ERROR'           // Invalid API key or secret
+  | 'API_KEY_EXPIRED'      // API key has expired
+  | 'IP_NOT_WHITELISTED'   // Namecheap IP whitelist issue
+  | 'RATE_LIMIT_EXCEEDED'  // Too many requests
+  | 'NETWORK_ERROR'        // Connection failed
+  | 'TIMEOUT'              // Request timed out
+  | 'INVALID_TLD'          // TLD not supported
+  | 'INVALID_DOMAIN'       // Domain name format invalid
+  | 'REGISTRAR_UNAVAILABLE'; // Registrar API down
+
+interface ErrorRecoveryAction {
+  action: 'retry' | 'fallback' | 'abort' | 'reconfigure';
+  delay?: number;            // ms to wait before retry
+  fallbackRegistrars?: string[];  // Alternative registrars to try
+  message: string;           // User-friendly message
+}
+
+/**
+ * Determine recovery action for API key errors
+ */
+function getRecoveryAction(error: DomainSearchError): ErrorRecoveryAction {
+  switch (error.code) {
+    case 'AUTH_ERROR':
+      return {
+        action: 'reconfigure',
+        message: `Authentication failed for ${error.registrar}. ` +
+          (error.registrar === 'porkbun'
+            ? 'Verify PORKBUN_API_KEY and PORKBUN_API_SECRET at https://porkbun.com/account/api'
+            : 'Verify NAMECHEAP_API_KEY and check IP whitelist at https://ap.www.namecheap.com/settings/tools/apiaccess')
+      };
+
+    case 'API_KEY_EXPIRED':
+      return {
+        action: 'reconfigure',
+        message: `API key expired for ${error.registrar}. Generate new keys from registrar dashboard.`
+      };
+
+    case 'IP_NOT_WHITELISTED':
+      return {
+        action: 'fallback',
+        fallbackRegistrars: ['porkbun', 'godaddy'],  // Exclude Namecheap
+        message: `IP ${error.detectedIp} not whitelisted for Namecheap. Falling back to other sources.`
+      };
+
+    case 'RATE_LIMIT_EXCEEDED':
+      return {
+        action: 'retry',
+        delay: error.retryAfter || 60000,  // Default 60 seconds
+        message: `Rate limit exceeded. Retrying in ${(error.retryAfter || 60000) / 1000}s.`
+      };
+
+    case 'NETWORK_ERROR':
+    case 'TIMEOUT':
+      return {
+        action: 'retry',
+        delay: 5000,
+        message: `Network issue. Retrying in 5 seconds.`
+      };
+
+    case 'REGISTRAR_UNAVAILABLE':
+      return {
+        action: 'fallback',
+        fallbackRegistrars: error.registrar === 'porkbun'
+          ? ['namecheap', 'godaddy']
+          : ['porkbun', 'godaddy'],
+        message: `${error.registrar} API unavailable. Using fallback registrars.`
+      };
+
+    default:
+      return {
+        action: 'abort',
+        message: `Unrecoverable error: ${error.message}`
+      };
+  }
+}
+
+/**
+ * Execute domain search with full error recovery
+ */
+async function searchWithErrorRecovery(
+  domainName: string,
+  tlds: string[],
+  maxRetries: number = 3
+): Promise<SearchResult> {
+  let lastError: DomainSearchError | null = null;
+  let currentRegistrars: string[] | undefined = undefined;  // Auto-select initially
+
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      const result = await searchDomain({
+        domain_name: domainName,
+        tlds,
+        registrars: currentRegistrars
+      });
+      return result;
+
+    } catch (error) {
+      lastError = error as DomainSearchError;
+      const recovery = getRecoveryAction(lastError);
+
+      console.log(`Attempt ${attempt}/${maxRetries}: ${recovery.message}`);
+
+      switch (recovery.action) {
+        case 'retry':
+          if (attempt < maxRetries && recovery.delay) {
+            await new Promise(resolve => setTimeout(resolve, recovery.delay));
+          }
+          break;
+
+        case 'fallback':
+          if (recovery.fallbackRegistrars) {
+            currentRegistrars = recovery.fallbackRegistrars;
+            console.log(`Switching to fallback registrars: ${currentRegistrars.join(', ')}`);
+          }
+          break;
+
+        case 'reconfigure':
+          // Log the issue and try without the problematic registrar
+          console.error(recovery.message);
+          if (lastError.registrar === 'porkbun') {
+            currentRegistrars = ['namecheap', 'godaddy'];
+          } else if (lastError.registrar === 'namecheap') {
+            currentRegistrars = ['porkbun', 'godaddy'];
+          }
+          break;
+
+        case 'abort':
+          throw new Error(`Search failed: ${recovery.message}`);
+      }
+    }
+  }
+
+  throw lastError || new Error('Search failed after maximum retries');
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// USAGE EXAMPLE
+// ═══════════════════════════════════════════════════════════════════════════
+
+async function main() {
+  try {
+    const result = await searchWithErrorRecovery('myproject', ['com', 'io', 'dev']);
+    console.log('Search completed successfully:', result.results.length, 'results');
+  } catch (error) {
+    console.error('Search failed:', error.message);
+    // Provide user guidance based on error
+    console.log('\nTroubleshooting steps:');
+    console.log('1. Check your .env file for correct API keys');
+    console.log('2. Verify your IP is whitelisted (for Namecheap)');
+    console.log('3. Try running without API keys to use RDAP/WHOIS fallback');
+  }
+}
+
+main();
+```
+
+### API Keys Benefits Comparison
+
+Detailed comparison of using API keys vs RDAP/WHOIS fallback:
+
+| Feature | With Porkbun API | With Namecheap API | RDAP/WHOIS Fallback |
+|---------|------------------|-------------------|---------------------|
+| **Setup Time** | 2 minutes | 10+ minutes | None |
+| **Cost** | Free | Free | Free |
+| **Response Time** | 100-200ms | 150-300ms | 2-5 seconds |
+| **Rate Limit** | 1000+ req/min | 500+ req/min | 10-50 req/min |
+| **Pricing Data** | ✅ Full | ✅ Full | ❌ Not available |
+| **Renewal Prices** | ✅ Yes | ✅ Yes | ❌ No |
+| **WHOIS Privacy Info** | ✅ Yes | ✅ Yes | ❌ No |
+| **Bulk Operations** | 100 domains | 100 domains | ~50 domains max |
+| **TLD Coverage** | All major TLDs | All major TLDs | Varies by TLD |
+| **Reliability** | 99.9% | 99.5% | 85-95% |
+| **IP Whitelist Required** | ❌ No | ✅ Yes | ❌ No |
+| **Account Required** | Free account | Account + domain/$50 | None |
+
+**Decision Matrix:**
+
+```
+Need pricing data?
+├── YES → Use Porkbun API (fastest setup)
+└── NO → RDAP/WHOIS is sufficient
+
+Need price comparison?
+├── YES → Configure BOTH Porkbun + Namecheap
+└── NO → Porkbun only
+
+High-volume usage (>50 req/min)?
+├── YES → API keys required
+└── NO → Either works
+
+Development/testing?
+├── YES → RDAP/WHOIS is fine
+└── NO → Production should use API keys
+```
+
 ### IDE Integration
 
 #### Cursor
@@ -4745,32 +5252,145 @@ report.availableDomains.slice(0, 5).forEach(d =>
 
 ### Workflow 8: Domain Research Pipeline
 
-Comprehensive domain research combining multiple tools:
+Comprehensive domain research for startups combining `search_domain`, `tld_info`, and `suggest_domains`.
+
+#### Complete Implementation with Explicit Imports
 
 ```typescript
-async function domainResearchPipeline(businessIdea: string) {
-  // Step 1: Generate smart suggestions from business description
-  const suggestions = await suggestDomainsSmart({
+// ═══════════════════════════════════════════════════════════════════════════
+// DOMAIN RESEARCH PIPELINE FOR STARTUPS
+// Combines search_domain, tld_info, and suggest_domains for comprehensive reports
+// ═══════════════════════════════════════════════════════════════════════════
+
+// Required imports from domain-search-mcp
+import {
+  searchDomain,
+  suggestDomains,
+  suggestDomainsSmart,
+  tldInfo,
+  checkSocials,
+  compareRegistrars,
+  bulkSearch
+} from 'domain-search-mcp';
+
+// Type definitions for pipeline results
+import type {
+  SearchDomainResponse,
+  TldInfoResponse,
+  SuggestDomainsResponse,
+  CheckSocialsResponse,
+  CompareRegistrarsResponse
+} from 'domain-search-mcp';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// TLD_INFO API STRUCTURE (Complete Reference)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Complete TldInfoResponse interface as returned by tld_info tool
+ * This is the exact structure you receive when calling tldInfo()
+ */
+interface TldInfoResponse {
+  // Core fields (always present)
+  tld: string;                    // e.g., "io", "com", "dev"
+  description: string;            // e.g., "Popular with tech startups"
+  typical_use: string;            // e.g., "Tech startups, SaaS products"
+  price_range: {
+    min: number;                  // Minimum price in USD (e.g., 29.88)
+    max: number;                  // Maximum price in USD (e.g., 59.99)
+    currency: "USD";              // Always USD
+  };
+  restrictions: string[];         // e.g., ["Requires HTTPS"] or []
+  popularity: "high" | "medium" | "low";
+  recommendation: string;         // Usage recommendation text
+
+  // Extended fields (only when detailed: true)
+  registry?: string;              // e.g., "Internet Computer Bureau"
+  introduced?: number;            // Year introduced, e.g., 1997
+  type?: "gTLD" | "ccTLD" | "newTLD";
+  dnssec_required?: boolean;
+  whois_server?: string;          // e.g., "whois.nic.io"
+  rdap_server?: string;           // e.g., "https://rdap.nic.io/domain/"
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// PIPELINE IMPLEMENTATION
+// ═══════════════════════════════════════════════════════════════════════════
+
+interface StartupDomainReport {
+  businessIdea: string;
+  tldAnalysis: {
+    tld: string;
+    description: string;
+    priceRange: { min: number; max: number };
+    recommendation: string;
+    restrictions: string[];
+    popularity: string;
+  };
+  topRecommendations: Array<{
+    domain: string;
+    price: number | null;
+    bestRegistrar: string;
+    socialAvailability: string;
+  }>;
+  allSuggestions: string[];
+  researchTimestamp: string;
+}
+
+/**
+ * Execute complete domain research pipeline for startups
+ *
+ * @param businessIdea - Description of the startup or business
+ * @returns Comprehensive domain research report
+ */
+async function domainResearchPipeline(businessIdea: string): Promise<StartupDomainReport> {
+  console.log(`Starting domain research for: "${businessIdea}"`);
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Step 1: Get TLD information FIRST (provides context for decisions)
+  // Using tld_info tool directly with detailed: true for full data
+  // ─────────────────────────────────────────────────────────────────────────
+
+  const tldData: TldInfoResponse = await tldInfo({
+    tld: "com",
+    detailed: true  // Get registry, whois_server, etc.
+  });
+
+  console.log(`TLD context: ${tldData.tld} - ${tldData.description}`);
+  console.log(`Price range: $${tldData.price_range.min}-$${tldData.price_range.max}`);
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Step 2: Generate smart domain suggestions using suggest_domains
+  // ─────────────────────────────────────────────────────────────────────────
+
+  const suggestions: SuggestDomainsResponse = await suggestDomainsSmart({
     query: businessIdea,
     tld: "com",
     style: "brandable",
-    max_suggestions: 15
+    industry: "tech",
+    max_suggestions: 15,
+    include_premium: false
   });
 
-  // Step 2: Get TLD information for context
-  const tldInfo = await getTldInfo({ tld: "com", detailed: true });
+  console.log(`Generated ${suggestions.results.available.length} available suggestions`);
 
+  // ─────────────────────────────────────────────────────────────────────────
   // Step 3: For top suggestions, compare registrar pricing
+  // ─────────────────────────────────────────────────────────────────────────
+
   const topDomains = suggestions.results.available.slice(0, 5);
-  const priceComparisons = await Promise.all(
+  const priceComparisons: CompareRegistrarsResponse[] = await Promise.all(
     topDomains.map(d => compareRegistrars({
       domain: d.domain.replace('.com', ''),
       tld: "com"
     }))
   );
 
-  // Step 4: Check social media for top picks
-  const socialChecks = await Promise.all(
+  // ─────────────────────────────────────────────────────────────────────────
+  // Step 4: Check social media availability for top picks
+  // ─────────────────────────────────────────────────────────────────────────
+
+  const socialChecks: CheckSocialsResponse[] = await Promise.all(
     topDomains.slice(0, 3).map(d => {
       const name = d.domain.replace('.com', '');
       return checkSocials({
@@ -4780,27 +5400,272 @@ async function domainResearchPipeline(businessIdea: string) {
     })
   );
 
-  // Compile research report
+  // ─────────────────────────────────────────────────────────────────────────
+  // Step 5: Compile final research report
+  // ─────────────────────────────────────────────────────────────────────────
+
   return {
     businessIdea,
-    tldContext: {
-      description: tldInfo.description,
-      priceRange: tldInfo.price_range,
-      recommendation: tldInfo.recommendation
+    tldAnalysis: {
+      tld: tldData.tld,
+      description: tldData.description,
+      priceRange: {
+        min: tldData.price_range.min,
+        max: tldData.price_range.max
+      },
+      recommendation: tldData.recommendation,
+      restrictions: tldData.restrictions,
+      popularity: tldData.popularity
     },
     topRecommendations: topDomains.map((d, i) => ({
       domain: d.domain,
       price: d.price_first_year,
-      bestRegistrar: priceComparisons[i]?.best_first_year?.registrar,
-      socialAvailability: socialChecks[i]?.summary
+      bestRegistrar: priceComparisons[i]?.best_first_year?.registrar || 'unknown',
+      socialAvailability: socialChecks[i]?.summary || 'not checked'
     })),
-    allSuggestions: suggestions.results.available,
-    relatedTerms: suggestions.related_terms
+    allSuggestions: suggestions.results.available.map(d => d.domain),
+    researchTimestamp: new Date().toISOString()
   };
 }
 
-// Usage
-const research = await domainResearchPipeline("ai-powered code review tool");
+// ═══════════════════════════════════════════════════════════════════════════
+// USAGE EXAMPLE WITH FULL OUTPUT
+// ═══════════════════════════════════════════════════════════════════════════
+
+async function main() {
+  const report = await domainResearchPipeline("ai-powered code review tool");
+
+  console.log("\n" + "═".repeat(60));
+  console.log("DOMAIN RESEARCH REPORT");
+  console.log("═".repeat(60));
+
+  console.log(`\nBusiness: ${report.businessIdea}`);
+
+  console.log(`\n📊 TLD Analysis (.${report.tldAnalysis.tld}):`);
+  console.log(`   ${report.tldAnalysis.description}`);
+  console.log(`   Price: $${report.tldAnalysis.priceRange.min}-$${report.tldAnalysis.priceRange.max}/yr`);
+  console.log(`   Popularity: ${report.tldAnalysis.popularity}`);
+
+  console.log(`\n🏆 Top Recommendations:`);
+  report.topRecommendations.forEach((rec, i) => {
+    console.log(`   ${i + 1}. ${rec.domain}`);
+    console.log(`      Price: $${rec.price}/yr via ${rec.bestRegistrar}`);
+    console.log(`      Social: ${rec.socialAvailability}`);
+  });
+
+  console.log(`\n📝 All Suggestions (${report.allSuggestions.length} domains):`);
+  console.log(`   ${report.allSuggestions.slice(0, 10).join(', ')}...`);
+}
+
+main().catch(console.error);
+```
+
+#### Rate Limiting and Retry Logic for Production
+
+```typescript
+// ═══════════════════════════════════════════════════════════════════════════
+// PRODUCTION-READY DOMAIN RESEARCH WITH RATE LIMITING
+// ═══════════════════════════════════════════════════════════════════════════
+
+import {
+  searchDomain,
+  tldInfo,
+  suggestDomains,
+  checkSocials,
+  compareRegistrars
+} from 'domain-search-mcp';
+
+// Rate limiter configuration
+interface RateLimiterConfig {
+  maxRequestsPerMinute: number;
+  maxConcurrent: number;
+  retryAttempts: number;
+  retryDelayMs: number;
+  backoffMultiplier: number;
+}
+
+const DEFAULT_RATE_CONFIG: RateLimiterConfig = {
+  maxRequestsPerMinute: 50,  // Conservative limit for production
+  maxConcurrent: 5,          // Max parallel requests
+  retryAttempts: 3,          // Number of retries on failure
+  retryDelayMs: 1000,        // Initial retry delay
+  backoffMultiplier: 2       // Exponential backoff multiplier
+};
+
+/**
+ * Token bucket rate limiter for API calls
+ */
+class RateLimiter {
+  private tokens: number;
+  private lastRefill: number;
+  private readonly config: RateLimiterConfig;
+
+  constructor(config: RateLimiterConfig = DEFAULT_RATE_CONFIG) {
+    this.config = config;
+    this.tokens = config.maxRequestsPerMinute;
+    this.lastRefill = Date.now();
+  }
+
+  async acquire(): Promise<void> {
+    // Refill tokens based on time elapsed
+    const now = Date.now();
+    const elapsed = now - this.lastRefill;
+    const refill = Math.floor(elapsed / 60000 * this.config.maxRequestsPerMinute);
+
+    if (refill > 0) {
+      this.tokens = Math.min(this.config.maxRequestsPerMinute, this.tokens + refill);
+      this.lastRefill = now;
+    }
+
+    // Wait if no tokens available
+    if (this.tokens <= 0) {
+      const waitTime = 60000 / this.config.maxRequestsPerMinute;
+      await new Promise(resolve => setTimeout(resolve, waitTime));
+      return this.acquire();  // Retry after waiting
+    }
+
+    this.tokens--;
+  }
+}
+
+/**
+ * Execute function with retry and exponential backoff
+ */
+async function withRetry<T>(
+  fn: () => Promise<T>,
+  config: RateLimiterConfig = DEFAULT_RATE_CONFIG,
+  attempt: number = 1
+): Promise<T> {
+  try {
+    return await fn();
+  } catch (error) {
+    if (attempt >= config.retryAttempts) {
+      throw error;
+    }
+
+    // Check if error is retryable
+    const isRetryable = error.code === 'RATE_LIMIT_EXCEEDED' ||
+                        error.code === 'NETWORK_ERROR' ||
+                        error.code === 'TIMEOUT';
+
+    if (!isRetryable) {
+      throw error;
+    }
+
+    // Calculate backoff delay
+    const delay = config.retryDelayMs * Math.pow(config.backoffMultiplier, attempt - 1);
+    console.log(`Retry ${attempt}/${config.retryAttempts} after ${delay}ms...`);
+
+    await new Promise(resolve => setTimeout(resolve, delay));
+    return withRetry(fn, config, attempt + 1);
+  }
+}
+
+/**
+ * Production-ready domain research pipeline with rate limiting
+ */
+async function productionDomainResearch(
+  businessIdea: string,
+  rateConfig: RateLimiterConfig = DEFAULT_RATE_CONFIG
+): Promise<StartupDomainReport> {
+  const rateLimiter = new RateLimiter(rateConfig);
+
+  // Step 1: Get TLD info with rate limiting
+  await rateLimiter.acquire();
+  const tldData = await withRetry(
+    () => tldInfo({ tld: "com", detailed: true }),
+    rateConfig
+  );
+
+  // Step 2: Generate suggestions with rate limiting
+  await rateLimiter.acquire();
+  const suggestions = await withRetry(
+    () => suggestDomainsSmart({
+      query: businessIdea,
+      tld: "com",
+      style: "brandable",
+      max_suggestions: 15
+    }),
+    rateConfig
+  );
+
+  // Step 3: Rate-limited parallel operations
+  const topDomains = suggestions.results.available.slice(0, 5);
+
+  // Process in batches respecting concurrency limit
+  const batchSize = rateConfig.maxConcurrent;
+  const priceResults: CompareRegistrarsResponse[] = [];
+
+  for (let i = 0; i < topDomains.length; i += batchSize) {
+    const batch = topDomains.slice(i, i + batchSize);
+
+    // Acquire tokens for batch
+    await Promise.all(batch.map(() => rateLimiter.acquire()));
+
+    // Execute batch with retry
+    const batchResults = await Promise.all(
+      batch.map(d => withRetry(
+        () => compareRegistrars({
+          domain: d.domain.replace('.com', ''),
+          tld: "com"
+        }),
+        rateConfig
+      ))
+    );
+
+    priceResults.push(...batchResults);
+  }
+
+  // Step 4: Social checks with rate limiting
+  const socialResults: CheckSocialsResponse[] = [];
+  for (const d of topDomains.slice(0, 3)) {
+    await rateLimiter.acquire();
+    const result = await withRetry(
+      () => checkSocials({
+        name: d.domain.replace('.com', ''),
+        platforms: ["github", "twitter", "npm"]
+      }),
+      rateConfig
+    );
+    socialResults.push(result);
+  }
+
+  // Compile report
+  return {
+    businessIdea,
+    tldAnalysis: {
+      tld: tldData.tld,
+      description: tldData.description,
+      priceRange: tldData.price_range,
+      recommendation: tldData.recommendation,
+      restrictions: tldData.restrictions,
+      popularity: tldData.popularity
+    },
+    topRecommendations: topDomains.map((d, i) => ({
+      domain: d.domain,
+      price: d.price_first_year,
+      bestRegistrar: priceResults[i]?.best_first_year?.registrar || 'unknown',
+      socialAvailability: socialResults[i]?.summary || 'not checked'
+    })),
+    allSuggestions: suggestions.results.available.map(d => d.domain),
+    researchTimestamp: new Date().toISOString()
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// USAGE: Production mode with custom rate limits
+// ═══════════════════════════════════════════════════════════════════════════
+
+// Conservative rate limiting for production
+const productionConfig: RateLimiterConfig = {
+  maxRequestsPerMinute: 30,   // Conservative for shared API
+  maxConcurrent: 3,           // Low concurrency
+  retryAttempts: 5,           // More retries for reliability
+  retryDelayMs: 2000,         // Longer initial delay
+  backoffMultiplier: 2        // Standard exponential backoff
+};
+
+const report = await productionDomainResearch("fintech payment platform", productionConfig);
 ```
 
 #### Tool Parameter Optimization Reference

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "domain-search-mcp",
-  "version": "1.2.9",
+  "version": "1.2.10",
   "description": "Fast domain availability aggregator MCP server. Check availability across Porkbun, Namecheap, RDAP, and WHOIS. Compare pricing. Get suggestions.",
   "main": "dist/server.js",
   "types": "dist/server.d.ts",